AI Workbench MCP

AI Workbench

AI Workbench 负责监督 AI 编码 Agent、采集证据、验证工作、执行验收策略，并生成可审计、适合提交 PR 的报告。

由于 ai-workbench 这个包名已被占用，此公开 Alpha 版仍使用 PyPI 包名 ai-workbench-mcp。产品和 CLI 的名称是 AI Workbench：

pip install ai-workbench-mcp
ai-workbench --help

当前源代码元数据指向尚未发布的 ai-workbench-mcp==0.8.0a0。 此公开 Alpha 版将本地监督、证据采集、验证、验收策略和 PR 报告整合为统一的产品界面。

公开 Alpha 版警告

监督器是首选的自动化证据途径，但守护进程、Codex 钩子和 OpenCode 适配器的支持仍处于 Alpha 阶段。AI Workbench 会检查证据质量和验收就绪情况，但不能证明工作绝对正确。高风险工作仍需人工审核。

架构

• AI Workbench 监督器采集本地证据。
• AI Workbench 验证会写入 validation_report.json。
• AI Workbench 质量门会写入 revision_decision.json。
• AI Workbench PR/报告界面会呈现 accept、needs_review 或 block。

Agent 的输出是一项提议。Workbench 接受证据。

MCP 是连接协议。AI Workbench MCP 是工具服务。 验收由选定的验证配置文件和质量门决定。 Agent 执行工作。Workbench 验收工作。MCP 将两者连接起来。

快速开始

注册一次项目，然后启动本地监督器：

pip install ai-workbench-mcp
ai-workbench supervisor setup --project-dir . --task-type code_change
ai-workbench supervisor start

在项目中运行 Codex、OpenCode、Goose 或其他受支持的本地工作流。 然后检查最新报告：

ai-workbench supervisor status
ai-workbench reports show latest --project-dir .

从已完成的运行中生成适合提交 PR 的产物：

ai-workbench pr-gate --run-dir runs/<run_id>

规范的本地运行记录为：

runs/<run_id>/
  task_metadata.json
  final_prompt.md
  model_selection.json
  model_output.md
  validation_report.json
  revision_decision.json
  run_log.jsonl
  metadata.json
  transcript.jsonl
  commands.jsonl
  workspace/
  validation/
  artifacts/

validation_report.json 和 revision_decision.json 是最终验收依据。监督器的配套报告是本地证据，不能替代这些 Workbench 产物。

Codex 钩子

安装项目级 Codex 钩子：

ai-workbench setup codex --project-dir . --task-type code_change

重启 Codex 或启动新会话，打开 /hooks，检查项目钩子，并信任该钩子一次。在观察到钩子事件之前，监督器状态报告会将 Codex 覆盖状态标记为已配置但未验证。

Goose MCP

AI Workbench 仍提供相同的 MCP 工具生命周期。使用以下命令向 Goose 或其他 MCP 主机注册服务：

ai-workbench mcp serve

七个 MCP 工具仍为：

workbench_open_run
workbench_select_policy_pack
workbench_select_model
workbench_record_execution
workbench_validate_run
workbench_quality_gate
workbench_analyze_runs

PR 门禁

Workbench 的 PR 验收会使用真实的 Workbench 运行证据：

ai-workbench pr-gate \
  --run-dir runs/<run_id> \
  --out runs/pr_gate/pr_comment.md \
  --json-out runs/pr_gate/pr_decision.json

结果仅有以下几种：

• accept
• needs_review
• block

缺失、无法读取或仅含脚手架内容的证据都会导致阻止。CI 运行成功、上传的产物、置顶的 PR 评论或模型自述均不构成验收证据。

引导资源

如需将入门配置、提示词、配方、文档和 GitHub PR 门禁工作流添加到仓库：

ai-workbench bootstrap --target .

引导过程会将 runs/ 保持为忽略状态。

包演示

如需仅使用软件包运行合成演示：

ai-workbench demo --target ./workbench-first-run

此演示使用固定证据展示 PR 门禁的 accept、needs_review 和 block 结果。这并非针对真实目标仓库的验收运行。

开发

python -m pip install -e ".[dev,publish]"
python -m pytest -q -p no:cacheprovider
python -m ruff check . --no-cache
python -m mypy --no-sqlite-cache --no-incremental
ai-workbench demo --target runs/package_demo_smoke
ai-workbench validate --project ai_workbench_mcp --profile scaffold --run-dir runs/scaffold-smoke

不要提交 runs/。已提交的示例证据必须经过脱敏，并存放在 examples/ 下。

文档

• Supervisor 文档
• 证据文件夹约定
• 转录记录架构
• 工作区规范
• 置信度规则
• 验收机制
• 契约基线
• 软件包演示指南
• Codex 设置
• Codex 实测交接
• Codex 验收演示指南
• 验收分析
• 证据仪表板
• 事件台账
• 黄金案例测试框架
• 模型注册表
• 内部试用指南
• Goose 演示指南 - 可用于录制的 3-5 分钟公开演示操作手册
• 策略包
• PR 门禁
• 发布问题
• 仓库主题
• 创建发布问题
• 发布指南
• Gemini 固定样例证明
• Codex 固定样例证明

配方：

• 工程验收
• MCP 工具冒烟测试
• 仅文档验收
• Python 软件包维护
• 测试修复验收

样例证据：

• 已验收的微型 Python 修复
• 已验收的 Codex 微型 Python 修复
• 已验收的仅文档冒烟测试
• 需要审核的测试修复

许可证

Apache-2.0。参见 LICENSE。整合后的 Prove It 代码保留了源自 MIT 的署名信息，详见 NOTICE。