内容
# 克劳德备份
**在您的页面上评论。克劳德会读取它。**
克劳德备份是一款Chrome扩展程序，用于在任何网页上为元素固定视觉反馈评论，同时附带一个本地MCP服务器（`claudback-mcp`），让克劳德读取这些评论并进行更改。主要使用场景：在本地构建或原型设计时，与克劳德代码（Claude Code）配合使用，无需截图或“侧边栏第三个按钮”的描述 — 点击所需元素，说明您的意图，询问克劳德检查您的评论。在React和Vue应用程序中，评论还会命名渲染元素的组件，以便克劳德可以直接跳转到源代码。
所有内容都保留在您的机器上：评论同步到仅限回环的收集器，并存储在`~/.claudback/`中。
**文档和入门指南：** https://andybiggs.github.io/claudback/ · **状态：** 预发布v1。参见 [PLAN.md](./PLAN.md) 了解架构和安全模型， [RELEASING.md](./RELEASING.md) 了解发布流程。
由 [Andy Biggs](https://www.andybiggs.net) (新西兰) 创建。
## 快速入门
1. **安装扩展程序** — 从Chrome网上应用商店安装（链接即将开放 — 在此之前，请参见下面的“从源代码加载扩展程序”）。安装时将打开设置指南。
2. **注册MCP服务器** — 为克劳德代码（CLI）运行此命令：
```sh
claude mcp add --scope user claudback -- npx -y claudback-mcp
```
`--scope user` 将克劳德备份注册到您机器上的所有项目中，因此您只需执行一次。如果使用 **克劳德代码桌面应用程序**？直接在克劳德代码聊天中粘贴相同的命令作为提示，而不是在终端中运行 — 克劳德代码为您运行安装程序。
3. **配对** — 向克劳德请求配对代码（“给我一个克劳德备份配对代码”），并在扩展程序的设置页面中输入。配对代码10分钟后过期，并且仅可使用一次。备用方法：粘贴`~/.claudback/token`中的长寿命令牌（在服务器首次运行时保存，也会打印到stderr）。
4. **注释** — 点击任意标签页上的克劳德备份图标 → **启用**，授予站点权限，并使用浮动按钮固定评论。
5. **询问克劳德** — “获取我的克劳德备份评论。” 克劳德通过`get_comments`工具读取它们；`list_origins`、`resolve_comment`和`clear_comments`也可用。
## 开发
```sh
npm install
npm run typecheck # 跨所有软件包的tsc -b
npm test # 跨所有软件包的vitest
```
仓库布局（npm工作区）：
```
packages/
shared/ zod注释模式，常量，选择器捕获
extension/ MV3扩展程序
mcp-server/ stdio MCP服务器 + 嵌入式收集器
```
每个软件包都通过`npm run build --workspace=<name>`进行构建。`npm run zip --workspace=@claudback/extension` 生成Web Store压缩包。
### 从源代码加载扩展程序
```sh
npm run build --workspace=@claudback/extension
```
打开 `chrome://extensions`，启用开发者模式，点击 **加载解压**，选择 `packages/extension/dist/`。设置指南在首次安装时自动打开（或通过 **配对和选项 → 打开设置指南**）。
在测试解压版本时，请禁用Web Store复制的克劳德备份 — 它们是独立的扩展程序，都会注入叠加层。请注意解压副本的ID来自 `chrome://extensions`（只要您从同一目录加载，它就保持稳定）；您需要它来允许服务器的扩展程序白名单。
### 扩展程序白名单（`CLAUDBACK_DEV_EXTENSION_ID`）
收集器的CORS白名单固定为已发布的扩展程序ID，因此解压版本的请求被403/CORS预检错误拒绝（`无'Access-Control-Allow-Origin'头部`）— 包括配对。通过设置`CLAUDBACK_DEV_EXTENSION_ID`环境变量，将开发扩展程序ID注册到服务器：
```sh
claude mcp remove --scope user claudback
claude mcp add --scope user claudback \
--env CLAUDBACK_DEV_EXTENSION_ID=<your-unpacked-extension-id> \
-- node /absolute/path/to/Claudback/packages/mcp-server/dist/bin.js
```
之后重启克劳德代码会话，以便它启动重新注册的服务器，然后像正常一样配对解压扩展程序。要返回生产环境，请在没有变量的情况下重新注册：`claude mcp add --scope user claudback -- npx -y claudback-mcp`.
仍然遇到问题？另一个克劳德会话的服务器可能正在占用收集器端口 — 只有一个服务器可以绑定57463，扩展程序会与先到的服务器通信，而不管您刚刚注册了哪个服务器。使用 `lsof -nP -i :57463` 查找它，杀死僵尸进程，正确的服务器会在几秒钟内接管端口。
### 从源代码运行服务器
```sh
npm run build --workspace=claudback-mcp
claude mcp add --scope user claudback -- node /absolute/path/to/Claudback/packages/mcp-server/dist/bin.js
```
配对通常通过向克劳德请求代码来完成，但要手动获取长期令牌而不使用MCP客户端，请直接运行服务器一次然后停止：
```sh
node packages/mcp-server/dist/bin.js
# ^C once you see "collector listening on http://127.0.0.1:57463"
cat ~/.claudback/token
```
<details>
<summary><strong>高级：注释时克劳德未运行</strong></summary>
您不需要服务器运行即可进行注释：扩展程序会将注释缓存在`chrome.storage.local`中，并在收集器可访问时自动刷新，因此在克劳德会话之间不会丢失任何内容。
如果您希望在克劳德关闭时与 `~/.claudback/` 进行**实时**同步，您可以单独运行服务器 — 收集器是同一进程中的普通HTTP服务器：
```sh
node packages/mcp-server/dist/bin.js
```
收集器独占绑定端口57463，因此当独立实例运行时，克劳德会话的自身进程改为共享存储模式 — 其MCP工具（包括`get_pairing_code`）继续与`~/.claudback/`合作，但它不提供扩展程序本身。当独立实例停止时，正在运行的会话在几秒钟内自动接管端口。
</details>
## License
[PolyForm Noncommercial 1.0.0](./LICENSE) — 免费用于个人、内部和非商业用途。不允许用于转售或作为付费产品/服务。
