Codex Commit Review

PyPI package: codex-commit-review-mcp · Release: v0.3.0

这是一个零运行时第三方依赖的本地 MCP server。成功提交代码或运行时配置后， Codex 会收到强制的 $commit-review 提醒；显式调用后，它生成一份计划关联、 可阅读、可追溯的代码审阅站点。一次 history 调用可以在同一页面内切换多个 commit tab。

它把普通 git diff 缺少的审阅上下文集中到一个界面：

• 左侧是真正递归、可折叠的 GitLab 风格 changed-file tree，显示状态、重要性和增删行数。
• 中间支持 unified 与严格对齐的 before/after split diff，保留新旧行号、hunk 和函数位置。
• 右侧展示重要功能改动，以及逐文件、逐函数、逐块、逐行解释；点击解释可跳到对应代码。
• 顶部把 build plan 的稳定步骤 ID 映射到文件和函数，并显示 covered/unmapped。
• review.json、comments.json 与 manifest.json 提供 SHA-256 审计证据。

站点只绑定 127.0.0.1，不会上传代码。自动定位提示始终标记为 heuristic；它们能帮助 Codex 找位置，但不能满足最终语义审阅门槛。

交互演示

仓库内包含一份继承 MCP light theme 的双语交互展示页。它用脱敏伪数据模拟 Codex Mac 中的完整工作流：输入任务、生成 Plan、确认执行、逐项 Build、交付并调用 MCP 打开 本地 Review。完成后，plan/sub-feature/commit 保持一一映射；点击任一计划条目会打开对应 commit，并提供 changed-file tree、before/after diff、文件/函数/行定位、semantic gate 与 receipt。演示不会读取当前仓库或上传数据。

python3 -m http.server 4173 --directory site

然后打开 http://127.0.0.1:4173/。

公开产品页：GitHub Pages

一键安装

安装 PyPI 包并注册 Codex stdio MCP：

python3 -m pip install --user codex-commit-review-mcp==0.3.0 && codex mcp add codex_commit_review -- python3 -m commit_review_mcp

在 Codex 中使用内置 $skill-installer 安装对应 workflow skill：

$skill-installer https://github.com/chi-qhsun/Codex-Semantic-Review/tree/v0.3.0/skills/commit-review

新 skill 会在下一轮可用。用 codex mcp list 检查 MCP，再显式调用 $commit-review 完成一次提交审阅。

Codex 接入

官方 Codex 接入分为三层：

1. .codex/config.toml 注册 stdio MCP，并用 required = true 保证按需调用时可用。
2. AGENTS.md 要求在行为变更 commit 后显示提醒，但不自动启动 MCP。
3. .codex/hooks.json 在 PostToolUse 捕获成功的 git commit，并在 Stop 重复提醒；纯文档和图片提交不会登记 pending，也不会阻止当前 turn。

本仓库已经包含可直接运行的项目级配置。Codex 只会在项目被信任后加载项目级 MCP 与 hooks；首次使用或 hook 内容变化后，在 Codex 中用 /hooks 检查并信任 具体 hook 定义。

官方依据：

• Codex MCP 配置
• Codex lifecycle hooks
• AGENTS.md 项目指令

供其他仓库或用户级配置使用的 TOML 模板见 examples/config.toml。可复用 skill 位于 skills/commit-review。

运行

Python 3.9+ 即可：

PYTHONPATH=src python3 -m commit_review_mcp

也可以安装命令入口：

python3 -m pip install .
codex-commit-review-mcp

项目 checkout 形式的 TOML 配置如下；Codex 会把 MCP 的相对 cwd 解析到当前 项目根目录，因此 . 让 PYTHONPATH = "src" 指向仓库内的源码目录：

[mcp_servers.codex_commit_review]
command = "python3"
args = ["-m", "commit_review_mcp"]
cwd = "."
env = { PYTHONPATH = "src" }
enabled = true
required = true
enabled_tools = ["prepare_commit_review", "create_commit_review", "prepare_commit_history_review", "create_commit_history_review", "read_commit_review"]
default_tools_approval_mode = "auto"
startup_timeout_sec = 10
tool_timeout_sec = 120

两阶段审阅

单个 commit 使用 prepare_commit_review / create_commit_review。同一 task 有多个 pending commit 时，优先使用 prepare_commit_history_review / create_commit_history_review；结果是一个可按 oldest-to-newest 切换的 tabbed 页面， 但每个 SHA 仍有独立的 semantic result、digest 和 receipt。

第一阶段调用 prepare_commit_review 或 prepare_commit_history_review。有完成的 plan 时每个 item 应有稳定 id；没有 plan 时 MCP 会生成显式的 auto-generated / unplanned item：

{
  "repo_path": "/absolute/path/to/repo",
  "commit": "a1b2c3d",
  "plan": {
    "title": "Bound retry behavior",
    "items": [
      {"id": "retry", "title": "Bound transient retries", "description": "Retry transient failures at most three times"},
      {"id": "tests", "title": "Prove failure behavior", "acceptance": "Focused success and permanent-failure tests pass"}
    ],
    "decisions": ["Keep the public API compatible"],
    "risks": ["Retries must not hide permanent errors"]
  }
}

工具会返回：

• important_files：由函数/控制流、变更规模和 plan 映射共同决定；
• annotation_contract.targets：必须覆盖的 file/function/block/line 精确锚点；
• review_template：可直接填写的最终 payload 骨架，包含行号、hunk index、函数名和 plan_item_ids。

第二阶段填写所有目标后调用 create_commit_review：

{
  "repo_path": "/absolute/path/to/repo",
  "commit": "a1b2c3d",
  "plan": {"title": "Bound retry behavior", "items": [{"id": "retry", "title": "Bound transient retries"}]},
  "review": {
    "summary": "This commit bounds transient retries while preserving permanent error propagation and the public call contract.",
    "important_changes": [
      {
        "path": "src/retry.py",
        "title": "Bounded retry state machine",
        "body": "Before, every failure escaped immediately; after, only transient failures enter a three-attempt loop and permanent failures still propagate.",
        "plan_item_ids": ["retry"]
      }
    ],
    "comments": [
      {"level": "file", "path": "src/retry.py", "body": "This file now owns retry classification, the bounded loop, and unchanged outward error propagation.", "plan_item_ids": ["retry"]},
      {"level": "function", "path": "src/retry.py", "function": "run", "line": 18, "body": "The function keeps its return contract but adds bounded state around transient calls; permanent exceptions are not caught.", "plan_item_ids": ["retry"]},
      {"level": "block", "path": "src/retry.py", "hunk_index": 0, "line": 19, "body": "This hunk introduces the three-attempt loop and separates retryable failures from the terminal path.", "plan_item_ids": ["retry"]},
      {"level": "line", "path": "src/retry.py", "hunk_index": 0, "line": 22, "body": "The explicit attempt bound prevents an unbounded retry loop while leaving the final exception visible.", "plan_item_ids": ["retry"]}
    ]
  },
  "open_browser": true
}

create_commit_review 会拒绝缺少重要文件解释、任一目标注释、plan link 或具体 summary 的 payload。成功结果必须包含 semantic_review.passed = true、 url、review_dir、review_sha256、important_files、plan_coverage、 comment_counts 和 receipt。

提醒与审计闭环

成功审阅会在 Git metadata 下写入 codex-commit-review/receipts/<commit>.json，不会污染工作树。history 页面为每个 commit 写一份 receipt，全部指向同一个 localhost artifact，同时绑定各自的 commit、 digest 和 semantic coverage。提醒是强制的，但本项目的按需策略不会因用户未调用 MCP 而阻止 turn；一旦调用，MCP 仍严格拒绝 heuristic-only 或不完整 payload。

Hook 是本地工作流提醒，不是权限扩张：它不会 push、merge、上传、删除代码或停止 其他进程。amend/rebase 后的新 SHA 重新进入 history；已经不可达的 superseded SHA 不再要求审阅。工作树未提交修改与 committed diff 分开显示。

审计文件

默认 artifact 位于 ~/.codex/commit-reviews/<repo>/<commit12>/。若不可写，会在 结果中说明并回退到系统临时目录。目录包含：

• review.json：commit、base、plan 映射、重要改动、diff 模型与语义覆盖；
• comments.json：Codex、heuristic 和网页本地审阅评论；
• manifest.json：静态资源、review 与 comments 的 SHA-256；
• index.html、app.js、styles.css：不依赖 CDN 的本地站点。

大 diff 受 max_diff_bytes 约束；二进制文件降级为文件级审阅。函数检测是跨语言的 轻量签名识别，不冒充完整 AST 分析。

验证

python3 -m unittest discover -s tests -v
PYTHONPYCACHEPREFIX=/tmp/codex-commit-review-pyc python3 -m py_compile src/commit_review_mcp/*.py .codex/hooks/*.py
node --check src/commit_review_mcp/web/app.js
python3 -m build --wheel --no-isolation

可视化方案调研和取舍见 docs/research.md。