engineering-board

产品描述

Engineering Board 是一个由仓库维护、面向工程 Agent 的模式智能系统。

该系统将错误、功能、问题和观察记录为 Markdown 证据，并以确定性图谱连接反复出现的发现。

该图谱可帮助 Agent 调查不同领域中的共同原因。这种方法可以减少对单个症状的重复修正。

Markdown 是规范记录。拉取请求可以展示对此记录的每项更改。

BOARD.md、GRAPH.yml、JSON 分析和 HTML 都是派生视图。系统可以根据规范记录重新构建这些视图。

假设与确定性的图谱事实相互独立。只有调查证据或修复证据才能确认假设。

可选的 tdd → review → validate 循环可以测试修复。此循环支持模式记忆，但不定义产品。

Milestone C 新增：

• 透明的调查评分，范围为 0 至 100
• 持久的 H### 假设生命周期
• 针对已驳回主张的负面记忆

每个评分组成部分都清晰可见。评分不能证明某个原因属实。

里程碑 D 将此记忆纳入 Agent 的决策路径：

• board_context 会检索相关集群、假设、负面记忆和学习成果，供 Agent 在选择修复方案前参考。
• 每条结果都会显示稳定标题、最多 2,000 个字符的类型化摘要、认知状态、结构信号、评分组成部分、匹配原因和规范来源。
• board_get_entry 会完整打开检索到的 H### 记录，包括其替代解释和证伪条件。读取不会改变其状态；也不会确认某个拟议原因或记录结果。
• 仅按任务内容检索但未命中时，会提示调用方添加文件、条目标识符或当前目录。任务词语不会绕过结构资格条件。
• board_outcomes 会针对 H### 假设记录明确的修复结果。
• 结构化结果会通过单独的预览和应用操作更新学习状态与置信度。
• 派生价值报告会统计经验证的复用情况和系统性修复证据，不统计提示词、会话或其他活动。

里程碑 D.1 增加了一个仅针对代码库的评估测试框架和八个经过脱敏的案例。默认契约会为 Codex 参考运行准备 24 组隔离的基线/上下文配对。其他客户端可以选择运行复测，而不改变产品门槛。协议和软件包测试用于确认受支持的客户端接口，无需提供商账号。首次 Codex 运行在正向基线组和上下文组中的得分均为 100%，因此该语料被保留为非评分校准集。另一个独立的锁定证据语料排除了已声明的评分预言，并要求其词汇干扰上下文中包含已驳回记忆。其参考运行的上下文组得分为 100%，基线组为 83.33%。两者相差 16.67 个百分点，未达到要求的 25 个百分点提升。项目不声称该上下文能够改善 Agent 的诊断结果。

解锁版本 4 提案现在将每个正向案例限制为一个可见的当前事件。它还要求正向分类将该事件与代码库中的既往证据关联起来。非评分提案预检发现，v1.11.0 会将预期记忆排在前列，但返回结果中不包含该记忆的标题、原因或摘要。上下文契约版本 2 增加了有界的规范内容，以及单独的认知状态、匹配原因和来源。当前契约版本 3 保留了这些限制，并增加了置信度，以便在需要时传递学习成果。随后进行的当前来源、单次重复预检中，四个基线组和四个上下文组均未出现符合条件的跨事件首要原因。预期记忆排在第一或第二位，但响应没有将当前事件与先前事件关联起来。这不是经过评分的产品效果结果。之后，一项来源锁定的 C04 诊断测试了原始 JSON 与已发布的提示词防护说明，并分别在案例证据之前和之后进行测试。在当前客户端的这一有界测试中，四种处理方式都再次只给出了针对当前事件的首要原因，因此，仅改变呈现格式和位置并不足以解决 C04。该提案仍处于未解锁状态，最终基线决策由产品负责人决定。有关证据边界和操作员命令，请参见 evaluation/README.md。

产品差异

一些 Git 看板能显示状态，但分析能力有限。一些记忆系统具备实用的分析能力，却将源文件保存在仓库之外。

Engineering Board 结合了这些特性：

• 可供拉取请求审查的仓库证据
• 带有证据链接的跨领域模式图
• 包含替代解释和证伪条件的 H### 记录
• 用于记录已驳回主张的负面记忆
• 适用于并行 Agent 的原子化主张
• 被动捕获
• Codex 和 Claude Code 插件
• MCP 服务。

原生 Claude Code Tasks 和 Engineering Board 用途不同。

原生 Tasks 将个人任务状态存储在 ~/.claude/tasks/ 中。此状态不属于项目拉取请求。

Engineering Board 将共享的项目记忆存储在仓库中。临时个人工作请使用原生 Tasks。持久的项目知识请使用 Engineering Board。

安装 Codex 插件

添加仓库市场：

codex plugin marketplace add GhostlyGawd/engineering-board

安装插件：

codex plugin add engineering-board@engineering-board

Codex 市场会从与所公布插件版本对应的不可变 Git 标签安装仓库根目录。安装更新的已发布版本之前，请刷新市场。

启动新的 Codex 会话。该插件提供五项看板技能，并启动包含 19 个工具的 Engineering Board MCP 服务。它不需要模型提供商账户。Codex 清单明确选择 hooks/codex-hooks.json，其中不包含自动钩子。因此，Codex 会使用这些技能和 MCP 服务，而不会加载 hooks/hooks.json 中的 Claude Code 钩子工作流。

请 Codex 在当前仓库中初始化 Engineering Board。Agent 会将仓库的绝对路径传递给 board_init，并使用 MCP 工具进行捕获、晋升、上下文、图谱、假设、结果、主张和生命周期操作。

安装 Claude Code 插件

添加仓库市场：

/plugin marketplace add GhostlyGawd/engineering-board

安装插件：

/plugin install engineering-board

设置看板：

/board-setup

/board-setup 会创建看板结构，并检查所需权限。

运行内置演示：

/board-demo

该命令会在 .engineering-board/demo/pattern-intelligence/ 中创建一次合成运行。

该命令会连接来自不同领域的三项发现，然后请求提出一个引用这些证据的假设。

该假设的 status: proposed。它包含一种替代解释和一个证伪条件。

报告会给出准确的清理命令。清理操作会保留已更改的运行。

如需使用明确的设置值，请使用：

/board-init <project> [affects-prefix]
/board-install-permissions

使用 pattern-memory 工作流

使用 Codex 或其他 MCP 客户端：

1. 使用 board_init 初始化一个项目。
2. 在选择修复方案前，使用 board_context 检索相关记忆。
3. 使用 board_capture_finding 记录发现。
4. 使用 board_promote_findings 预览并应用提升操作。
5. 使用 board_insights 和 board_hypotheses 进行与证据关联的共同原因分析。
6. 使用 board_outcomes 记录观察到的结果。

在每次捆绑插件工具调用中传入仓库的绝对路径。插件不会猜测原始 MCP 调用的目标是哪个已打开的工作区。

使用 Claude Code hooks 和 commands：

1. 在 Claude Code 中工作。
2. 让 SessionStart 和 UserPromptSubmit 检索相关的系统性记忆。
3. 需要显式获取同一份有界简报时，运行 /board-context <project>。
4. 阅读记忆标题、类型化摘要、认知状态、匹配原因和来源。依赖提议的原因前，先检查所引用的规范记录。
5. 在 PM 模式下，新发现提升后，阅读追加到本轮摘要中的匹配中/高置信度经验。
6. 让 Stop hook 将发现捕获到 engineering-board/<project>/_sessions/。
7. 运行 /board-promote 预览规范变更。
8. 审阅后，应用未更改的提升计划。
9. 需要完整的排序调查视图时，运行 /board-insights <project>。
10. 运行 /board-hypothesis <project> propose 预览 H### 记录。
11. 审阅证据、替代解释、反证、置信度依据和证伪条件。
12. 应用未更改的假设计划。
13. 验证后，运行 /board-outcome <project> preview ...。
14. 应用未更改的结果计划。分别审阅并应用返回的每个经验计划。

结果会记录为 held、failed、partial 或 inconclusive。只有通过兼容的显式处置，结果才能确认、削弱、否定假设，或保持假设不变。

仅在进行高级批量提升时使用 /pm-start。仅在想测试已选定的修复方案时使用可选的 Worker 循环。

使用一种会话模式

/pm-start 和 /worker-start 会设置 .engineering-board/session-mode.json。

一个会话只能有一种模式。启动新会话即可更改模式。

在 Claude Code web 上，每个会话都会使用新的克隆。在本地安装中，模式文件会保留在磁盘上。

要返回被动捕获模式：

1. 启动新会话。
2. 阅读 SessionStart 消息。
3. 如果仍有模式，删除 .engineering-board/session-mode.json。

在不使用插件的情况下注册 MCP 服务

使用 Claude Code 命令行界面（CLI）注册 PyPI 包：

claude mcp add engineering-board -- uvx engineering-board-mcp

要从克隆运行服务：

git clone https://github.com/GhostlyGawd/engineering-board
claude mcp add engineering-board -- python3 "$(pwd)/engineering-board/mcp-server/engineering_board_mcp.py"

对于 Claude Desktop，将此对象添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "engineering-board": {
      "command": "uvx",
      "args": ["engineering-board-mcp"]
    }
  }
}

mcp-server/README.md 还包含 Codex CLI、Gemini CLI 和 Cursor 的设置步骤。

Claude Code 插件通过 .mcp.json 注册服务。Codex 清单选择 codex-mcp.json。这两个文件都通过同一个跨平台启动器仅启动 Engineering Board。Codex 专用文件使用 writes 审批策略：只读记忆工具无需逐次调用提示即可运行，而所有具备写入能力的工具都会受到审批限制。

产品界面

该插件有四种会话模式：

模式	启动方式	停止操作
被动	默认	运行 finding-extractor
已暂停	/board-pause	不捕获发现
PM	/pm-start	运行四个 PM Agent
Worker	/worker-start --discipline <tdd|review|validate>	认领并处理一条记录

规范的 Stop 流程见 hooks/stop-hook-procedure.md。

命令（21 个）： /board-setup、/board-demo、/board-context、 /board-outcome、/board-promote、/board-pattern、/board-insights、 /board-hypothesis、/board-run、/board-init、/board-rebuild、 /board-graph、/board-view、/board-remember、/board-pause、 /board-resume、/pm-start、/worker-start、 /board-install-permissions、/board-claim-release 和 /board-migrate。

Agent（8 个）： board-manager、finding-extractor、consolidator、tidier、 learnings-curator、tdd-builder、code-reviewer 和 validator。

技能（5 个）： board-intake、board-triage、board-resolve、 board-consolidate 和 board-insights。

Claude Code 钩子（4 个事件）： SessionStart、PostToolUse(Write)、 UserPromptSubmit 和 Stop。Codex 插件会选择单独的空钩子清单，并使用 MCP 优先工作流。

MCP 服务有 19 个工具。所有工具都使用相同的规范 Markdown 和相同的确定性核心。

工具	功能
board_init	创建项目看板
board_list_projects	列出路由器项目
board_create_entry	创建有效记录
board_list_entries	列出并筛选记录
board_get_entry	获取一条记录，包括完整的规范 H### 详情
board_update_entry	更改一条记录并归档新的解决方案
board_graph	构建确定性图谱
board_context	检索有界且可解释的系统记忆
board_insights	对集群排序并返回关联证据
board_hypotheses	列出、预览或应用 H### 操作
board_outcomes	预览或应用修复结果和 Learning 反馈
board_patterns	列出、预览或应用 P### 操作
board_promote_findings	预览或应用临时记录升级，不复用已解决的 ID；未更改的计划 ID 会恢复预览时省略的会话选择器
board_rebuild	重新构建 BOARD.md
board_capture_finding	将发现添加到临时收件箱
board_claim	获取记录认领权
board_release	释放记录认领权
board_remember	保存一条学习
board_status	显示看板状态和待处理工作

六个纯读取工具是 board_list_projects、board_list_entries、 board_get_entry、board_insights、board_context 和 board_status。它们的 MCP 架构将 readOnlyHint: true 设为真。其他每个工具都按其最大能力分类。因此，可预览并应用更改的工具在审批方面属于具备写入能力的工具。Codex 插件的 writes 审批策略允许六个纯读取工具无需提示即可运行，并要求所有具备写入能力的工具通过审批。这些注释属于建议性元数据。它们不能替代宿主策略、根目录限制、与内容绑定的计划或认领所有权。

架构边界

规范卡片、假设、Learnings 和 BOARD-ROUTER.md 使用 Markdown。 派生视图包括 BOARD.md、GRAPH.yml、上下文简报、价值报告、 JSON 和 HTML。

该产品不要求使用 SQLite。未来的 SQLite 索引必须可丢弃且可重建。必须有经过测量的查询需求才能证明其合理性。

共享 MCP 运行时使用 Python 3，且不依赖任何第三方软件包。 Codex 插件仅使用 Node.js 在 Windows 或 Linux 上选择 Python 解释器。Claude Code 命令和钩子使用 Bash 和 Python 3。

阅读 ARCHITECTURE.md 了解完整的系统概览。

路线图边界

Milestone D 将随 v1.11.0 发布。

跨会话 Conductor 仍是 RFC 草案。/board-run <entry-id> 仅发布单会话内部循环。

跨仓库智能、托管服务和必需的数据库仍在当前产品边界之外。

docs/PRODUCT_EVOLUTION_SPEC.md 是产品方向的权威来源。

贡献

运行完整测试套件：

bash tests/run-all.sh

运行全部测试的命令使用维护中的测试套件列表。修改仓库前，请阅读 CONTRIBUTING.md。

支持

• 有问题请使用 GitHub Discussions。
• 报告错误或提出功能建议请使用 GitHub Issues。
• 报告漏洞请使用 GitHub Security Advisories。
• 查看当前项目工作请使用实时看板。
• 如需支持项目，请使用 GitHub Sponsors。

GhostlyGawd 维护这个开源项目。

许可证

本项目采用 MIT License。

语言状态

所有者已批准当前的受控英语文本。项目不声称符合正式的 ASD-STE100 标准，也不声称获得认证或经过独立审查。