octopus-blackboard

Octopus Blackboard

面向 AI 编码 Agent 的共享记忆与协作层。

Agent 不需要另一个老板，它们需要一块共享黑板。

简体中文

属于 Octopus Core —— 面向受治理 AI 的开放基础设施堆栈。 每个仓库各司其职，覆盖 Agent 生命周期：Scout · Observe · Experience · Blackboard · Workstate · Runtime · Replay ——由 Inspect 对每个阶段实施治理。整个堆栈基于一个根基元——Evidence，它是规范、可防篡改的原子，也是构建一切的根类别。

**本仓库——Blackboard · 协调：**为编码 Agent 提供共享认知。

---

Claude Code、Codex、Gemini CLI、Cursor 以及你的本地 Agent 都在同一个仓库上工作，却彼此不可见。一个 Agent 在重构身份验证，另一个却在重写同一个文件。上下文散落在各个 CLI 中。没有人能重放发生过的事情。

Octopus Blackboard **不是编排器。**它不会安排 Agent、触发 Agent，也不会替它们做任何决定。它是一种被动、本地优先的共享记忆，可以回答六个问题：

Who is working on what      →  agents, tasks, claims
What changed                →  files_changed
What was decided            →  decisions
What evidence exists        →  evidence
What risks are open         →  risks
What was left for whom       →  messages, handoffs

每个 Agent 只需能够读取黑板、写入黑板、留言并附加证据。这就是全部约定。

为什么需要它

企业最担心的并不是 Agent 不够聪明，而是：

• 多个 AI 工具同时编辑同一份代码
• 上下文散落在不同的 CLI 中
• 没有共享记忆、没有审计、没有交接
• 无法感知冲突，也无法重放

黑板能直接解决这些问题。每次写入都会向只追加的 timeline 添加一条可防篡改、由哈希链保护的记录，因此完整历史都可审计、可重放；任何事后对先前记录的修改都会导致验证失败。

2 分钟快速开始

Blackboard 是接入 Octopus 堆栈最简单的方式——它是纯粹的协作记忆，只需 Claude Code 和 Cursor 即可立即使用，无需编排器。 一条命令即可完成所有设置：

npx octopus-blackboard quickstart

这条命令会：在本地看板（.octoboard/）不存在时创建它，自动检测你的 MCP 客户端（.claude/ → Claude Code，.cursor/ → Cursor，……否则提供通用代码片段），打印可直接复制粘贴的配置，并通过一次写入和一次读取验证看板可用。

然后只需：

1. 粘贴打印出的配置块到指定文件中。
2. 重新加载你的 MCP 客户端（重启客户端或重新打开项目）。
3. **完成。**让你的 Agent 调用 board_status，然后调用 board_note "hello"——这就是你在共享、可防篡改时间线上执行的第一个看板操作。

再次运行 quickstart 始终安全：它绝不会覆盖现有看板或其历史记录。想先了解为什么应该优先采用协作层？请参阅为什么先采用 Blackboard。

安装

npm install
npm run build      # compiles to dist/

需要 Node ≥ 22。看板是 .octoboard/ 下的一个 SQLite 文件，会从当前工作目录向上查找（类似 .git）。

实际效果

examples/two-agents.sh 展示了核心场景——Claude Code 和 Codex 在同一个仓库中共用一个看板：认领冲突、实时的同文件冲突、决策、归属记录、发送到另一个 Agent 收件箱的交接、AI 审查、人类审批 CI 门禁（阻止 → 通过）、问责评分卡、从 blame 到叙述，以及带有会话签名的已验证哈希链。在一个空目录中运行：

bash examples/two-agents.sh          # needs `octoboard` on PATH

CLI

octoboard init                                   # create .octoboard/ here
octoboard status                                 # who's on the board, right now

octoboard note "Codex is refactoring auth middleware"
octoboard claim trust-layer-policy-schema        # claim work; warns on conflict
octoboard message claude "Review policy edge cases before merge"
octoboard decision "Use hash-chain audit log" --why "tamper-evidence"
octoboard risk "Migration may break audit replay" --severity high
octoboard file src/auth.ts --change modified --task trust-layer-policy-schema
octoboard handoff claude "Tests pass except policy replay" --task trust-layer-policy-schema

octoboard timeline                               # the full hash-chained history
octoboard verify                                 # confirm the chain is intact

使用 --as <agent> 或环境变量 OCTOBOARD_AGENT 设置身份。使用 --board <dir> 或 OCTOBOARD_DIR 指定看板。

冲突感知

看板不会阻止操作——它会揭示冲突。如果两个 Agent 认领同一个键，或修改同一任务的文件，两个写入都会被记录，并向第二个 Agent 发出警告：

⚠ CONFLICT: "trust-layer-policy-schema" is also held by codex. Both claims recorded.

AI 归属与共享开发记忆

Git 会记录谁推送了提交，但不会记录代码由哪个 AI Agent 在哪个会话、哪台机器上生成，也不会记录是否有另一个 AI 审查过代码，或是否经过人工批准。随着 AI 原生开发日益普及，问责机制必须超越 Git 作者身份。

黑板在 Git 之上添加归属层——绝不改写历史。Git 仍然是代码的来源；黑板则成为归属信息的来源。

会话

会话是 Agent 一次连续执行，也是归属信息所依附的单位。启动会话后，后续所有写入都会归属于该会话（每个 Agent 的活动会话会在不同 CLI 调用之间保留）：

export OCTOBOARD_AGENT=claude OCTOBOARD_PROVIDER=anthropic \
       OCTOBOARD_MODEL=claude-opus-4-8 OCTOBOARD_CLI=claude-code

blackboard session start --label "auth work"   # captures machine, branch, repo
blackboard claim policy-engine
blackboard file src/policy.ts --change modified
# ... make a git commit ...
blackboard link HEAD                            # attribute the commit's files
blackboard session stop

身份设置完全独立于提供商——可使用 --provider、--model、--cli，或对应的 OCTOBOARD_* 环境变量。任何 AI CLI（本地或云端）都可以注册，无需假设使用了特定供应商的产品。

关联提交

blackboard link <rev> 会读取提交修改过的文件（通过 Git），并为活动会话中的每个文件记录一条归属信息。也可以在 refs/notes/blackboard 下写入一条附加的 git notes 记录：

blackboard link HEAD --note
blackboard attribute <sha> --file src/x.ts --actor human --name Ran  # manual

审查

blackboard review HEAD --by ai   --name codex --outcome approved --note "tests pass"
blackboard review HEAD --by human --name Ran   --outcome approved

查询共享记忆

blackboard who src/auth.ts             # git authors + AI sessions that touched it
blackboard who src/auth.ts --line 42   # which session introduced this line
blackboard explain HEAD                # attribution + reviews + related decisions
blackboard commits claude-code         # which commits came from an AI / CLI
blackboard unreviewed                  # AI commits never reviewed by a human
blackboard joint claude codex          # files modified by BOTH agents
blackboard timeline --session <id>     # per-session HH:MM timeline

explain 示例：

commit 5fa3095…  Human Dev <[email protected]>  add auth
  produced by:
    ai claude [claude-opus-4-8] — src/auth.ts
  reviews:
    human Ran: approved
  git note: blackboard: produced by claude-code (claude-opus-4-8), session 75b2b7e7…

每条归属信息、审查、会话和决策也会记录在哈希链式的 timeline 中，因此完整的问责历史可验证是否被篡改，并可重放。blackboard 和 octoboard 是同一个命令。

治理与问责链

归属记录的意义在于落实问责。工作到合并门禁之间的链路：

agent work → commit attribution → export/import → CI check → human-review gate

CI 门禁（check）

将查询变成可执行的门禁。此操作只读——报告通过或失败，并以非零状态码退出；后续处理由 CI 系统决定。黑板不会阻止操作。

# In CI, on a PR branch — fail the build if any AI commit isn't human-APPROVED
# (a rejected / changes-requested review does not clear the gate):
blackboard check --range origin/main..HEAD --require-human-review
echo $?   # 0 = pass, 1 = violations

blackboard check --verify-chain --require-attribution --range origin/main..HEAD
blackboard check            # default gate: verify chain + require human review

可移植性（export / import / trailers）

归属信息优先存储在本地；这些命令可让它通过 git push 进入团队看板或 CI，并在其中保留：

blackboard export --range origin/main..HEAD --out attribution.json  # on the dev machine
blackboard import attribution.json                                   # on the team board / CI
blackboard trailers HEAD                                             # trailer lines for a commit message

import 具有幂等性（以行 ID 为键）。此捆绑包包含归属信息、审查、会话及相关决策。

订阅（watch）

完善读取/写入/订阅/消息契约。此功能是被动的：它会轮询并报告，但不会推送工作。

blackboard watch --for claude     # only messages/handoffs/conflicts addressed to me
blackboard watch                  # the full stream
blackboard watch --once           # one-shot poll (for scripts)

已签名会话（sign / verify）

最精简的身份机制（v0）：每个会话都会获得一个 Ed25519 密钥对（私钥保存在本地的 .octoboard/keys/ 下，并由 gitignore 忽略）。对时间线头部签名后，verify 就能区分可信状态与仅仅声称可信的状态：

blackboard sign        # sign the current head with the active session key
blackboard verify      # chain integrity + which sessions have signed, trusted/stale

会话在 session stop 时会自动为其头部签名。一旦更早的历史记录被修改，针对头部的签名就会变成过时状态——因此，即使签名本身在密码学上仍然有效，篡改也会显现。目前这还不是完整的 PKI（没有密钥分发或撤销机制）。

导入 CLI 转录记录

无需手动调用 API，即可从 CLI 的会话转录记录填充看板——文件编辑、决策和备注都会流入当前会话：

blackboard ingest ~/.claude/transcript.jsonl --format claude-code
blackboard ingest session.jsonl --format codex        # also: gemini, grok
blackboard ingest events.json    --format generic --dry-run

claude-code/codex/gemini/grok 使用保守的工具调用 JSONL 启发式规则（通过 file_path/notebook_path 以及补丁/写入工具调用来查找文件编辑）。generic 则读取规范化架构——这是适用于任何 CLI 的稳定集成路径：

{ "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。

blackboard sync push --target /shared/team.json          # file (shared drive)
blackboard sync pull --target postgres://host/blackboard # team database (needs `pg`)

export 使用当前会话密钥为数据包签名；import 会验证签名，而 import --require-signed 会拒绝未签名或遭篡改的数据包——因此，导入的归属记录具有来源真实性，而不只是通过 ID 去重。

如果将头部锚定到外部，防篡改能力会超越数据库内部哈希链：

blackboard anchor --git-note              # record seq:hash on the commit (or --out file)
blackboard verify --against git-note      # prove history wasn't truncated/altered

活跃状态与合规性：

blackboard session heartbeat        # mark your session alive (active vs stale)
# `blackboard file ...` now warns if another LIVE session is editing the same file

blackboard prune --before 2026-01-01T00:00:00Z   # retention: drop old messages/
                                                 # evidence/file-changes (timeline kept)
blackboard redact 42 --reason PII                # hide a timeline entry's content

prune 不会触及只能追加的时间线（审计跟踪）。redact 会在所有读取路径中清空内容——包括时间线叠加层和底层源记录（如消息正文、证据备注等），确保 inbox/status/仪表板不会泄露这些内容，同时保持哈希链有效。这并非密码学擦除：原始摘要仍会保留在时间线记录中，以确保哈希链仍可验证，因此不要存储必须能够销毁的秘密。若要防范拥有数据库写入权限的攻击者篡改数据，请将头部哈希锚定到外部位置（一次提交、一份日志或另一台机器）——如果无法确认尾部，verify 会显示 unanchored 警告。

任务与看板

任务采用看板卡片形式——包含编号、内容、负责人（哪个 Agent / CLI）、项目、影响范围、风险和实时进度。**“通知 Agent”是被动操作：**分配任务只会在该 Agent 的收件箱中放入一条“请查看任务 #N”的消息；Agent 会读取消息并决定是否采取行动——看板绝不会启动任何人。

实时的 blackboard serve 仪表板——只读、自动刷新。每张卡片都会显示任务编号、进度条、受派人、活跃 Agent 数量（⚡）、项目和按风险着色的边框。

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       # → drops "please look at task #1 …" in claude's inbox
blackboard progress 1 40         # → moves #1 to in-progress, 40%
blackboard tasks                 # kanban view, grouped by status
blackboard task show 1           # full card: owner, project, impact, risk, files

只读的 serve 仪表板会将这些内容呈现为实时任务看板（按状态分列；每张卡片都会显示编号、标题、进度条、受派人、活跃 Agent 数量、项目和按风险着色的左侧边框）。Agent 通过 MCP 工具 board_task_define、board_assign、board_progress、board_tasks 来操作——Agent 在工作过程中调用 board_progress，进度条就会实时更新。

可见性

blackboard report          # scorecard: review coverage %, AI/human ratio, per-agent
blackboard blame src/auth.ts 42   # trace a line → the session that wrote it, and its
                                  # other work, decisions, and handoffs (blame → narrative)
blackboard serve           # read-only local web dashboard (http://localhost:4319)

仪表板无需依赖项（node:http），严格只读（拒绝非 GET 请求），并会自动刷新：实时时间线、会话、冲突/归属状态和问责评分卡。

MCP 服务 — 连接任意 CLI

黑板通过标准 MCP over stdio 通信，因此任何兼容 MCP 的客户端 （Claude Code、Cursor、Codex、Gemini CLI、VS Code、Windsurf，……）都可以读取和 写入黑板。只需一步，即可为你的客户端生成准确的配置：

blackboard mcp-config cursor        # → ~/.cursor/mcp.json block
blackboard mcp-config claude-code   # → project .mcp.json block
blackboard mcp-config codex         # → ~/.codex/config.toml (TOML)
blackboard mcp-config gemini        # → ~/.gemini/settings.json block
blackboard mcp-config vscode        # → .vscode/mcp.json (servers block)
blackboard mcp-config               # → generic mcpServers JSON (any client)

每条命令都会显示粘贴位置和可直接使用的代码片段，例如：

{
  "mcpServers": {
    "blackboard": {
      "command": "npx",
      "args": ["-y", "octopus-blackboard-mcp"],
      "env": { "OCTOBOARD_AGENT": "cursor" }
    }
  }
}

Agent 身份默认使用客户端名称（因此 Cursor 会以 cursor 身份写入， Codex 会以 codex 身份写入）；使用 --agent 可覆盖此设置。系统会自动从 工作目录中的 .octoboard/ 发现黑板，也可以使用 --dir 指定目录。现在，指向同一个 .octoboard/ 的两个 CLI 会共享同一块黑板——这正是设计目的。

公开的工具——协作：board_status、board_timeline、board_note、board_claim、board_task_define、board_task、board_tasks、board_assign、board_progress、board_message、board_inbox、board_handoffs、board_decision、board_evidence、board_file_changed、board_risk、board_handoff、board_heartbeat、board_since；归属信息：session_start、session_stop、board_link、board_attribute、board_review、board_who、board_explain、board_blame、board_unreviewed、board_report；治理与可移植性：board_check、board_export、board_import、board_trailers、board_sign、board_trust、board_prune、board_redact、board_ingest。每个工具 都接受可选的 agent 参数，可按调用覆盖当前操作的身份。

推荐的模式：Agent 在开始工作之前调用 board_status， 查看其他人的工作进展，并在工作过程中持续记录。

数据模型

层级	表	用途
当前参与者	agents、sessions	与提供商无关的身份、会话上下文
当前事务	tasks、messages、handoffs	协作——认领、发送消息、交接
产出归属	attributions、reviews	AI/人工归属与审查，以提交为键
已确认事实	decisions、evidence、files_changed、risks、timeline	可审计的共享记忆

timeline 是仅追加的哈希链，其他所有写入也会记录在其中，因此 黑板与其审计日志永远不会出现不一致。

架构

better-sqlite3 (local-first, default)
  + MCP server   (read / write board)
  + CLI          (octoboard ...)
  + hash-chain audit log (the timeline)
  + optional Postgres sync   (portable attribution records)
  + optional git / file watcher (planned)

状态

公开测试版（v0.3）。目前已可使用：本地 SQLite 黑板、CLI（octoboard / blackboard）、MCP 服务、可验证的哈希链时间线、一等会话、与提供商无关且以 Git 提交为键的 AI/人工归属、审查、查询层（who、explain、commits、unreviewed、joint）、 只读 serve 仪表板、签名导入/导出包、保留策略、 脱敏、快速入门，以及 MCP 注册表元数据/发布工作流。Git 集成仅支持只读操作和增量添加 git notes——绝不重写历史记录。 团队同步支持共享 JSON 文件和 Postgres 目标，以存储可移植的 归属记录；黑板的私有哈希链则按设计保留在本地。 变更订阅和更深入的 Octopus 跨仓库桥接仍在路线图中。

许可证

Apache-2.0 © Octoryn。请参阅 LICENSE。