内容
<div align="center">
# 🛰️ 信标
### 用于并行 AI 编码代理的实时存在和防碰撞
在同一仓库上同时运行两个、五个、十个 Claude Code 会话 - 并 **再也不会让它们相互冲突**。
<p align="center"><b>English</b> · <a href="README.zh-CN.md">简体中文</a></p>
[](LICENSE)
[](https://nodejs.org)
[](package.json)
[](https://docs.claude.com/en/docs/claude-code)
[](CONTRIBUTING.md)
<img src="docs/hero.svg" alt="Beacon live dashboard showing two agents editing the same file with an overlap warning" width="720" />
</div>
---
## 问题
并行运行多个 AI 编码代理是常态 - 一个会话重构 API，另一个编写测试，第三个更新配置。在两个代理编辑同一个文件时，或者一个运行 `git checkout` / `git stash` 并悄悄地从另一个代理下删除文件时，速度会大大加快。您只在工作丢失后才发现冲突。
代理处于盲状态。**它们看不到对方。**
## 信标的作用
信标是一个小型本地服务，为每个代理提供共享的实时 **谁正在操作什么** 的视图 - 并在两个代理重叠时向它们发出警告。
- 👀 **相互感知** - 每个会话报告它正在编辑的内容；其他会话可以实时看到它。
- ⚡ **上下文中的冲突警告** - 当一个代理即将编辑另一个代理已经在编辑的文件时，信标会在该代理的上下文中注入一行提示信息。
- 🔪 **保护破坏性 git 操作** - `checkout`、`reset --hard`、`stash`、`rebase`、`clean`，而另一个会话在树中有未保存的编辑 → 代理收到警告（或被要求确认）。
- 📊 **实时仪表盘** - 一个单独的本地网页，显示所有活动的代理，实时更新。
- 🪶 **轻量级和无形** - 零依赖，100% 本地，并且 **从不阻塞您的工作**。没有冲突？您永远不会注意到它的存在。
> **设计安全：** 信标是 advisory 的。它 **打开失败** - 如果守护进程宕机或发生错误，您的会话行为与信标不存在时完全相同。它默认从不拒绝编辑，并且在常见（无冲突）情况下，它为代理的上下文添加 **零 token**。
---
## 快速开始
```bash
# 1. 获取它（Node ≥ 18）
git clone https://github.com/a1473838623/agent-beacon.git && cd agent-beacon
npm link # 将 `beacon` 命令添加到您的 PATH 中（或：npm i -g agent-beacon）
# 2. 连接 Claude Code + 启动守护进程
beacon init # 默认全局 - 覆盖此机器上的所有项目
beacon start -d # 启动本地守护进程（后台）
# 3. 实时查看
open http://127.0.0.1:4517
```
这就是整个设置。**此机器上的每个新的 Claude Code 会话现在都自动报告活动** - 无需每个项目步骤，无需每个会话步骤，无需记住提示。
打开第二个会话，让两个会话编辑同一个文件，并在仪表盘上查看重叠情况，同时第二个代理在上下文中收到警告。
### 全局 vs 项目范围
`beacon init` 默认 **全局安装** (`~/.claude/settings.json`)，因此只需一个命令即可覆盖所有项目。更喜欢限定在单个仓库？使用 `--project`：
```bash
beacon init # 全局 - 所有项目（推荐默认）
beacon init --project # 仅限此仓库（.claude/settings.json）
```
**两个级别是相互排斥的 - 切换会自动禁用另一个。** 运行 `beacon init --project` 会删除全局钩子；再次运行 `beacon init` 会删除项目钩子。这保证钩子永远不会为一次编辑触发两次。（它会清理全局级别和**当前**项目；如果您已为多个项目启用了个别项目，请在每个项目中重新运行 `--project` 以关闭它们。）全局监控是安全的：冲突检测按文件路径和工作树限定，因此无关项目永远不会引发错误重叠 - 全局只是意味着“始终开启，在任何地方”。
守护进程和仪表盘已经是机器范围的，因此使用全局范围，仪表盘成为您在所有仓库中正在执行的所有操作的单个实时视图。
---
## 工作原理
```
Claude Code 会话 ──PreToolUse hook──┐
Codex / MCP 代理 ──MCP 工具────────┤
git / docker / CI ──with_report──────┼──▶ 信标守护进程 ──▶ 实时仪表盘
任意编辑器 / 人类 ──文件监视器─────┘ (本地 HTTP，JSONL) + 上下文警告
```
一个想法，贯穿始终：**活动是 `{ actor, action, target }`** - “会话 A 正在编辑 `orders.ts`”。所有内容都是客户端，报告活动；守护进程检测重叠并回答“是否有人也在使用？” - 就是这样。
- **报告** 和 **查询** 是仅有的两个操作。`report` 甚至在其响应中返回冲突，因此代理在其公告的同一个调用中得知重叠。
- **报告是带外** 的（钩子 / shell 包装器），因此您的代理在宣布自己时不会花费 token。
- **仅在真正冲突时才会显示感知** - 一条简短的相关行，恰好在需要时。
---
## 集成
信标 **不限于 Claude Code**。核心是一个与语言无关的本地 HTTP 总线；每个集成只是向其馈送活动的一种方式。
| 演员 | 如何报告 | 是否获得上下文警告？ |
|---|---|---|
| **Claude Code** | `beacon init`（PreToolUse 钩子）- 自动，无需配置 | ✅ 是，在编辑前注入警告 |
| **Codex** | `beacon init --codex`（MCP 服务器）+ `AGENTS.md` 中的一行 | ➖ 可以查询和报告；模型决定如何操作 |
| **任意 MCP 代理** *(Cursor, Cline, Windsurf, Zed, Claude Agent SDK)* | 将其 MCP 配置指向 `beacon mcp` - `report_activity` / `get_activity` 工具 | ➖ 可以查询和报告 |
| **git / docker / CI 脚本** | `with_report <action> <target> -- <cmd>` | - |
| **任意编辑器或人类** | `beacon watch <dir>`（文件系统监视器） | - |
| **任何支持 HTTP 的东西** | `POST /report` | - |
Claude Code 获得最丰富的体验，因为其钩子允许信标自动报告 *和* 在任务中途将警告注入代理。所有其他工具仍在仪表盘上显示，并在其他代理的警告中显示。
### Codex 和其他 MCP 客户端
信标附带一个零依赖的 **MCP 服务器**，因此任何具有 MCP 功能的代理都可以报告和查询与您的 Claude Code 会话相同的总线。
**Codex:**
```bash
beacon init --codex # 将 [mcp_servers.beacon] 添加到 ~/.codex/config.toml（全局）
beacon start -d
```
（默认全局；`beacon init --codex --project` 限定为 `.codex/config.toml`，并且切换级别会禁用另一个 - 与 Claude 钩子相同。）
可选地，在您的 `AGENTS.md` 中添加一行，以便 Codex 主动使用它：
> 在编辑文件或运行风险命令之前，调用 `beacon` 的 `get_activity` / `report_activity` 工具，以避免与其他代理发生冲突。
**Cursor / Cline / Windsurf / Zed / Claude Agent SDK:** 将客户端的 MCP 配置指向服务器（`command: node`，`args: ["<install>/mcp/server.js"`，或仅 `beacon mcp` 如果 `beacon` 在 PATH 中）。
**Codex 今日现状 - 请清晰：**
- ✅ **对其他所有代理可见。** Codex 的活动显示在仪表盘和警告中 - 通过 MCP 工具，或通过 `beacon watch` 零配置。
- ✅ **可以自行检查冲突。** Codex 可以调用 `get_activity` / `report_activity` - 主动仅当您添加上述 `AGENTS.md` 行（否则可用但模型不会自行调用）。
- ❌ **Codex 内无自动编辑前警告。** 与 Claude Code 不同，Codex 无法在编辑前在内部注入警告：其钩子仅在 Bash（非文件写入）时触发，无法添加上下文。 这是 Codex 平台限制，而不是信标限制。
- 🔜 **在冲突时硬阻止破坏性 git 操作** - 计划中，通过 Codex Bash 钩子（Codex 钩子 *可以* 拒绝）。参见 [路线图](#roadmap)。
简而言之：**Claude Code = 全自动，在每次编辑前发出警告。 Codex = 对所有人可见 + 可按需查询，但不自动警告。**
---
## 配置
所有配置均为可选 - 默认情况下配置合理。设置为环境变量。
| 变量 | 默认值 | 含义 |
|---|---|---|
| `BEACON_PORT` | `4517` | 守护进程端口（仅限 localhost） |
| `BEACON_GUARD` | `warn` | `warn` = advisory 上下文 · `ask` = 需要确认的破坏性 git 操作 · `off` = 仅报告，从不警告 |
| `BEACON_TTL_MS` | `900000` | 活动在没有心跳的情况下生存多长时间（15 分钟）- 崩溃的会话自我清除 |
| `BEACON_LOG_LEVEL` | `info` | `error` · `warn` · `info` · `debug`。 错误/警告始终记录；`debug` 跟踪每个报告。 |
| `BEACON_HOME` | `~/.beacon` | 守护进程存储其 pidfile、活动日志和 `beacon.log` 的位置 |
---
## 故障排除和报告错误
信标设计为打开失败 - 因此如果有问题，线索在 **本地日志** 中，而不是您的终端中。
```bash
beacon logs # 最后 200 行 + 日志路径
beacon logs --tail 50 # 更少的行
beacon logs --path # 仅打印文件路径 (~/.beacon/beacon.log)
beacon logs --clear # 清除它
```
错误和警告（包括每次钩子 **打开失败** 因为守护进程无法访问）始终记录。要在重现问题时获取完整跟踪信息，请以更多详细信息重启：
```bash
BEACON_LOG_LEVEL=debug beacon start # 记录每个报告和工具调用
```
发现错误？请 [打开问题](https://github.com/a1473838623/agent-beacon/issues/new?template=bug_report.yml) 并粘贴 `beacon logs` 输出（**先查看它** - 它可能包含您项目的文件路径）。日志是 100% 本地的；除非您自己附加，否则永远不会发送任何内容。
---
## 常见问题
**这会减慢我的代理速度或增加我的 token 使用量吗？**
否。报告发生在带外（在钩子中，而不是模型中），因此它消耗零模型 token。仅当存在真正重叠时，才会向代理的上下文中添加一个警告行。无冲突 → 无影响。
**它会破坏我的工作流 / 阻止编辑吗？**
默认情况下不会。它是 advisory 的，并且打开失败 - 守护进程宕机，超时，错误输入，都导致“不执行，允许”。仅当您 **希望** 破坏性 git 操作在真正冲突时暂停确认时，请设置 `BEACON_GUARD=ask`。
**它会发送我的代码到任何地方吗？**
否。所有内容都是本地的 - `127.0.0.1` 上的守护进程，`~/.beacon` 下的追加日志。无网络，无遥测，无帐户。
**它会取代 git / 锁 / 工作树吗？**
否 - 它是位于它们之下的 **感知层**。它不会占用锁或移动文件；它使代理 **看到** 彼此，因此您可以（或它们可以）协调。 与 git 工作树完美搭配使用。
---
## 路线图
- [x] 原生 **MCP 服务器** (`report_activity` / `get_activity`) - 与 Codex、Cursor、Cline、Windsurf、Zed 和 Claude Agent SDK 配合使用
- [ ] `beacon init --codex` 还安装一个 Codex Bash 钩子，以在冲突时阻止破坏性 git 操作
- [ ] `SessionStart` 钩子：用对等方正在执行的操作的摘要问候每个新会话
- [ ] 资源的 **可选硬租赁** （例如，一次一个构建）
- [ ] 冲突时的 Slack / 桌面通知
- [ ] `npx agent-beacon` 零安装运行器
想法和 PR 欢迎 - 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
---
## 贡献
信标故意设计得很小（几百行，无依赖）。这使得它易于阅读，易于修改和易于信任。使用 `npm test` 运行测试。问题和拉取请求非常受欢迎。
## 许可证
[MIT](LICENSE) © 信标贡献者
