内容
# 章鱼黑板
**AI 编码代理的共享内存和协调层。**
> 代理不需要另一个老板。他们需要一个共享的黑板。
[简体中文](./README.zh-CN.md)
---
Claude Code、Codex、Gemini CLI、Cursor 和您的本地代理都在同一个仓库上工作，但它们彼此是盲的。一个重构身份验证，而另一个重写同一个文件。上下文分散在各个 CLI 中。没有人可以回放发生了什么。
章鱼黑板 **不是一个协调器。** 它不调度代理，不触发它们，也不代表它们做出决定。它是一个被动的、本地优先的共享内存，回答六个问题：
```text
谁正在处理什么 → 代理，任务，声明
发生了什么变化 → 文件更改
做出了什么决定 → 决定
存在什么证据 → 证据
有哪些风险 → 风险
为谁留下了什么 → 消息，交接
```
每个代理只需要能够 **读取黑板，写入黑板，留下消息，并附加证据。** 就是这样。
## 为什么
企业主要担心的是：
- 多个 AI 工具同时编辑相同的代码
- 上下文分散在不同的 CLI 中
- 没有共享内存，没有审计，没有交接
- 没有冲突感知和回放方式
黑板直接解决了这些问题。每次写入都会追加一个 **防篡改，哈希链条** 条目到一个只追加的 `时间线` 中，这样整个历史记录是可审计和可回放的 - 并且任何事后修改早期条目都会破坏验证。
## 安装
```bash
npm install
npm run build # 编译到 dist/
```
需要 Node ≥ 22。黑板是一个位于 `.octoboard/` 下的单个 SQLite 文件，通过从工作目录向上查找来发现。
## 看看它是如何工作的
[`examples/two-agents.sh`](./examples/two-agents.sh) 演绎了旗舰场景 - Claude Code 和 Codex 在同一个仓库上共享一个黑板：冲突声明，实时同文件冲突，决策，属性，交接进入另一个代理的收件箱，AI 审查，人类批准 CI 门（阻止 → 通过），责任记分卡，责备→叙述，以及带有会话签名的验证哈希链。 在空目录中运行：
```bash
bash examples/two-agents.sh # 需要 `octoboard` 在 PATH 上
```
## CLI
```bash
octoboard init # 在此处创建 .octoboard/
octoboard status # 当前谁在黑板上
octoboard note "Codex 正在重构身份验证中间件"
octoboard claim trust-layer-policy-schema # 声明工作；冲突时发出警告
octoboard message claude "在合并前审查策略边缘情况"
octoboard decision "使用哈希链审计日志" --why "防篡改证据"
octoboard risk "迁移可能会破坏审计回放" --severity high
octoboard file src/auth.ts --change modified --task trust-layer-policy-schema
octoboard handoff claude "测试通过，除策略回放外" --task trust-layer-policy-schema
octoboard timeline # 完整的哈希链历史记录
octoboard verify # 确认链是完整的
```
身份通过 `--as <agent>` 或 `OCTOBOARD_AGENT` 环境变量设置。指向特定黑板使用 `--board <dir>` 或 `OCTOBOARD_DIR`。
### 冲突感知
黑板永远不会阻塞 - 它会 **显示**。如果两个代理声明相同的键或触摸同一个任务的文件，则两个写入都会被记录，第二个代理会收到警告：
```text
⚠ 冲突："trust-layer-policy-schema" 也被 codex 占用。两个声明都被记录。
```
## AI 属性和共享开发内存
Git 记录谁 **推送** 了提交。它不记录哪个 AI 代理生成了代码，在哪个会话中，在哪台机器上，另一个 AI 是否审查了它，或者人类是否批准了它。随着 AI 原生开发变得普遍，责任必须超越 Git 作者身份。
黑板在 Git 之上添加了一个属性层 - 它永远不会重写历史。Git 仍然是代码的源头；黑板成为属性的源头。
### 会话
一个会话是一个代理的连续执行，属性单位由此而定。启动一个会话会使后续的所有写入都归属于它（活动会话在 CLI 调用之间被记住，每个代理）：
```bash
export OCTOBOARD_AGENT=claude OCTOBOARD_PROVIDER=anthropic \
OCTOBOARD_MODEL=claude-opus-4-8 OCTOBOARD_CLI=claude-code
blackboard session start --label "auth work" # 捕获机器，分支，仓库
blackboard claim policy-engine
blackboard file src/policy.ts --change modified
# ... 进行 git 提交 ...
blackboard link HEAD # 归因于提交的文件
blackboard session stop
```
身份完全与提供者无关 - `--provider`， `--model`， `--cli`，或匹配的 `OCTOBOARD_*` 环境变量。任何 AI CLI（本地或云）都可以注册它，而无需对特定供应商做出任何假设。
### 链接提交
`blackboard link <rev>` 读取提交所触摸的文件（通过 Git），并为活动会话记录每个文件的属性：
```bash
blackboard link HEAD --note
blackboard attribute <sha> --file src/x.ts --actor human --name Ran # 手动
```
### 审查
```bash
blackboard review HEAD --by ai --name codex --outcome approved --note "测试通过"
blackboard review HEAD --by human --name Ran --outcome approved
```
### 查询共享内存
```bash
blackboard who src/auth.ts # git 作者 + 触摸它的 AI 会话
blackboard who src/auth.ts --line 42 # 哪个会话引入了这一行
blackboard explain HEAD # 属性 + 审查 + 相关决策
blackboard commits claude-code # 哪些提交来自 AI / CLI
blackboard unreviewed # AI 提交未被人类审查
blackboard joint claude codex # 两个代理修改的文件
blackboard timeline --session <id> # 会话的 HH:MM 时间线
```
示例 `explain`：
```text
commit 5fa3095… Human Dev <a@b.c> add auth
生成者：
ai claude [claude-opus-4-8] — src/auth.ts
审查：
human Ran: approved
git 注释：blackboard：由 claude-code（claude-opus-4-8）生成，会话 75b2b7e7…
```
每个属性，审查，会话和决策也记录在哈希链的 `时间线` 中，因此完整的责任历史是防篡改和可回放的。`blackboard` 和 `octoboard` 是同一个命令。
## 治理和责任链
属性的目的是 **强制执行** 某些东西。从工作到合并门的链条：
```text
代理工作 → 提交属性 → 导出/导入 → CI 检查 → 人类审查门
```
### CI 门（`check`）
将查询转换为强制门。只读 - 它报告通过/失败并退出非零；CI 系统决定接下来怎么做。黑板永远不会阻塞。
```bash
# 在 CI 上，在 PR 分支 - 如果任何 AI 提交未经人类批准，则失败构建：
# （拒绝/请求更改的审查不会清除门）：）
blackboard check --range origin/main..HEAD --require-human-review
echo $? # 0 = 通过，1 = 违规
blackboard check --verify-chain --require-attribution --range origin/main..HEAD
blackboard check # 默认门：验证链 + 需要人类审查
```
### 可移植性（`export` / `import` / `trailers`）
属性是本地优先的；这些使其在 `git push` 到团队黑板或 CI 时存活：
```bash
blackboard export --range origin/main..HEAD --out attribution.json # 在开发机器上
blackboard import attribution.json # 在团队黑板 / CI 上
blackboard trailers HEAD # 提交消息的尾行
```
`import` 是幂等的（按行 ID 键入）。包携带属性，审查，会话和相关决策。
### 订阅（`watch`）
完成读写 **订阅** 消息的合同。被动：它轮询并报告；它从不推送工作。
```bash
blackboard watch --for claude # 仅限我地址的消息/交接/冲突
blackboard watch # 完整的流
blackboard watch --once # 一次性轮询（用于脚本）
```
### 签名会话（`sign` / `verify`）
最小身份（v0）：每个会话都会获得一个 Ed25519 密钥对（私钥保留在 `.octoboard/keys/` 下，被 gitignore）。签署时间线头部让 `verify` 区分 **受信任** 状态和仅断言：
```bash
blackboard sign # 用活动会话密钥签署当前头部
blackboard verify # 链完整性 + 哪些会话已签名，信任/过时
```
会话在 `session stop` 时自动签署其头部。头部上的签名在任何早期历史被更改时变为 **过时** - 因此即使签名本身在密码学上仍然有效，也可以看到篡改。
## 消化 CLI 转录
从 CLI 会话转录中填充黑板，而不是手动调用 API - 文件编辑，决策和笔记流入活动会话：
```bash
blackboard ingest ~/.claude/transcript.jsonl --format claude-code
blackboard ingest session.jsonl --format codex # 还有：gemini，grok
blackboard ingest events.json --format generic --dry-run
```
`claude-code`/`codex`/`gemini`/`grok` 使用保守的工具使用 JSONL 启发式（它从 `file_path`/`notebook_path` 和补丁/写入工具调用中找到文件编辑）。`generic` 读取规范化的模式 - **任何** CLI 的稳定集成路径：
```json
{ "events": [
{ "type": "file", "path": "src/auth.ts", "change": "modified" },
{ "type": "decision", "title": "use ed25519", "rationale": "small keys" },
{ "type": "note", "text": "left policy edge cases for review" }
] }
```
## 团队后端
黑板保持本地优先；同步将可移植的属性记录（而非黑板的私有哈希链）共享到团队存储 - 共享文件或 Postgres。
```bash
blackboard sync push --target /shared/team.json # 文件（共享驱动）
blackboard sync pull --target postgres://host/blackboard # 团队数据库（需要 `pg`）
```
`export` 使用活动会话密钥签名包；`import` 验证它，而 `import --require-signed` 拒绝未签名或篡改的包 - 因此导入的属性具有源真实性，而不仅仅是 ID 消除重复。
防篡改措施进一步扩展了基于 DB 的链条，如果你将头部哈希锚定到外部：
```bash
blackboard anchor --git-note # 记录 seq:hash 在提交上（或 --out 文件）
blackboard verify --against git-note # 证明历史记录未被截断/更改
```
活跃度和合规性：
```bash
blackboard session heartbeat # 标记会话活跃（活跃 vs 过时）
# `blackboard file ...` 现在警告如果另一个活跃会话正在编辑相同的文件
blackboard prune --before 2026-01-01T00:00:00Z # 保留：删除旧消息/
# 证据/文件更改（时间线保留）
blackboard redact 42 --reason PII # 隐藏时间线条目的内容
```
`prune` 永远不会触摸只追加的时间线（审计轨迹）。`redact` 在每个读取路径上清空内容 - 时间线叠加层 *和* 底层源行（消息正文，证据注释等），因此 `inbox`/`status`/仪表板无法泄露它 - 同时保持哈希链有效。它不是加密擦除：原始摘要仍保留在时间线行中，因此链仍然验证，因此不要存储您必须能够销毁的秘密。为了防止攻击者具有数据库写入访问权限的篡改证据，请将头部哈希锚定到外部（提交，日志，第二台机器）- `verify` 显示一个 `unanchored` 警告，当它无法确认尾部。
## 任务和看板
任务是看板卡 - 数字，内容，所有者（哪个代理/CLI），项目，影响半径，风险和实时进度。**“通知代理”是被动的**：分配任务会在该代理的收件箱中发送“请查看任务 #N”消息；代理读取它并决定采取行动 - 黑板永远不会启动任何人。
*实时 `blackboard serve` 仪表板 - 只读，自动刷新。每个卡片显示任务编号，进度条，分配者，活跃代理计数（⚡），项目，和风险颜色边框。*
```bash
blackboard task add auth-mw --title "Refactor auth middleware" \
--project octopus-api --impact "src/auth.ts, src/db.ts" --risk high
blackboard assign 1 claude → 在 claude 的收件箱中发送“请查看任务 #1 ...”消息
blackboard progress 1 40 → 将 #1 移到进行中，40%
blackboard tasks # 看板视图，按状态分组
blackboard task show 1 # 完整的卡片：所有者，项目，影响，风险，文件
```
只读 `serve` 仪表板实时渲染这些作为实时看板（按状态列；每个卡片显示编号，标题，进度条，分配者，活跃代理计数，项目和风险颜色左侧边框）。代理通过 MCP 工具 `board_task_define`，`board_assign`，`board_progress`，`board_tasks` - 代理调用 `board_progress` 时，它会实时移动进度条。
## 可见性
```bash
blackboard report # 记分卡：审查覆盖率，AI/人类比例，按代理
blackboard blame src/auth.ts 42 # 跟踪一行 → 编写它的会话及其
# 其他工作，决策和交接（责备 → 叙述）
blackboard serve # 只读本地 Web 仪表板（http://localhost:4319）
```
仪表板依赖项为空（`node:http`），严格只读（非 GET 被拒绝），并自动刷新：实时时间线，会话，冲突/属性状态和记分卡。
## MCP 服务器 - 连接任何 CLI
黑板通过标准 MCP 在stdio上公开，因此 **任何** 支持 MCP 的客户端（Claude Code，Cursor，Codex，Gemini CLI，VS Code，Windsurf，...）都可以读写黑板。 为您的客户端生成确切的配置：
```bash
blackboard mcp-config cursor # → ~/.cursor/mcp.json 块
blackboard mcp-config claude-code → 项目 `.mcp.json` 块
blackboard mcp-config codex → ~/.codex/config.toml（TOML）
blackboard mcp-config gemini → ~/.gemini/settings.json 块
blackboard mcp-config vscode → .vscode/mcp.json（服务器块）
blackboard mcp-config → 通用 mcpServers JSON（任何客户端）
```
每个打印它们粘贴的位置和使用示例，例如：
```json
{
"mcpServers": {
"blackboard": {
"command": "npx",
"args": ["-y", "octopus-blackboard-mcp"],
"env": { "OCTOBOARD_AGENT": "cursor" }
}
}
}
```
代理身份默认为客户端名称（所以 Cursor 编写为 `cursor`，Codex`）
```
该代理默认设置为客户端名称（因此Cursor编写为`cursor`，Codex编写为`codex`）；使用 `--agent` 覆盖。黑板从工作目录中的`.octoboard/`自动发现，或者使用 `--dir`固定。
### 数据模型
| 层级 | 表格 | 目的 |
|---|---|---|
| **谁在场** | `agents`, `sessions` | 提供者独立的身份，会话上下文 |
| **发生了什么** | `tasks`, `messages`, `handoffs` | 协调 - 声明，消息，交接 |
| **谁生成了什么** | `attributions`, `reviews` | AI/人类属性和审查，按提交键入 |
| **已确定的事实** | `decisions`, `evidence`, `files_changed`, `risks`, `timeline` | 可审计的共享内存 |
`timeline` 是一个只追加的哈希链条，每个其他写入也记录到其中，因此黑板及其审计日志永远不会分离。
## 架构
```text
better-sqlite3（本地优先，默认）
+ MCP 服务器（读取/写入黑板）
+ CLI（octoboard ...）
+ 哈希链审计日志（时间线）
+ 可选 Postgres 同步（计划中）
+ 可选 git / 文件监视器（计划中）
```
## 状态
早期MVP（v0.1）。今天有效：本地SQLite黑板，CLI（`octoboard` / `blackboard`），MCP服务器，可验证的哈希链时间线，第一类会话，提供者独立的AI/人类属性按Git提交键入，审查，以及查询层（`who`，`explain`，`commits`，`unreviewed`，`joint`）。Git集成是只读的加上添加`git notes` - 历史记录从未重写。Postgres同步和更改订阅正在路线图中。
## 许可
AGPL-3.0-or-later Octoryn 版权所有。参见 [LICENSE](./LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器