# Codex Semantic 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。演示不会读取当前仓库或上传数据。

```bash
python3 -m http.server 4173 --directory site
```

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

公开产品页：[GitHub Pages](https://chi-qhsun.github.io/Codex-Semantic-Review/)

## 一键安装

安装 PyPI 包并注册 Codex stdio MCP：

```bash
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：

```text
$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 配置](https://learn.chatgpt.com/docs/extend/mcp)
- [Codex lifecycle hooks](https://learn.chatgpt.com/docs/hooks)
- [AGENTS.md 项目指令](https://learn.chatgpt.com/docs/agent-configuration/agents-md)

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

## 运行

Python 3.9+ 即可：

```bash
PYTHONPATH=src python3 -m commit_review_mcp
```

也可以安装命令入口：

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

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

```toml
[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：

```json
{
  "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`：

```json
{
  "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 分析。

## 验证

```bash
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](docs/research.md)。