Git Review

resolve → collect_commits → agent_review(TO_AGENT) → aggregate → export_html

依赖

pip install esflow

快速使用

python3 scripts/run.py --repo /path/to/repo --scope 2026-05-01..2026-05-07
python3 scripts/run.py --repo /path/to/repo --scope main..dev
python3 scripts/run.py --repo /path/to/repo --scope main

产物路径见 stdout envelope 的 data.report 字段（绝对路径）；默认落 <output_root>/git-review/<job_id>/，按节点分目录：

review.json 由 Agent 读 assets/vigil.md + commits.json 生成，写到 agent_review/ 目录。

默认 output_root = /tmp/esflow/outputs，享受系统自动清理。需长期保留用 --out <dir> 指定持久目录。--resume 依赖 job_dir 存活，目录被清理后 resume 会丢。

scope 日期边界

--scope since..until 日期模式：since 含当天零点，until 含当天 23:59:59。如 2026-07-03..2026-07-05 抓 7-03 00:00 到 7-05 23:59 的 commit。

Flow 结构

esflow DAG 编排（scripts/flow.py 声明，scripts/nodes/ 各节点）：

job_dir

• job_dir = <output_root>/git-review/<job_id>/，<job_id> = <YYYYMMDD-HHMMSS>-<4hash>
• 各节点 output_dir = job_dir/<rid>/，产物落各自目录，互不覆盖
• 框架元数据在 job_dir/.esflow/：break_to_agent.json（待 resume 节点列表）、<rid>/artifact.json（每节点一个）
• TO_AGENT 退出时 stdout envelope 携带 review_path / commits / vigil_md / commits_count，Agent 解析 stdout 拿接管路径
• --resume <job_dir> 传 job_dir 续跑

Agent 介入

# 1. 首跑到 agent_review 退出(exit 2)
python3 scripts/run.py --repo /path/to/repo --scope 2026-05-01..2026-05-07
# stdout envelope.data: {review_path, commits, vigil_md, commits_count}
# stderr: [to_agent] 完成后续跑:python3 scripts/run.py --resume <job_dir>

# 2. Agent 读 data.vigil_md + data.commits,按 vigil 规则逐 commit 评估
#    写 data.review_path (agent_review/review.json)

# 3. 续跑聚合 + HTML
python3 scripts/run.py --resume <job_dir>

TO_AGENT 退出时 envelope.data 含 review_path/commits/vigil_md/commits_count（产物未生成）；续跑聚合后最终 envelope.data 含 commits/aggregate/process_md/report（见 --schema）。

review.json Schema

写到 agent_review/review.json（即 envelope.data.review_path），框架 deliver 严格校验值类型：

{
  "reviews": [
    {
      "hash": "commit sha",
      "author": "提交者",
      "risk_level": "P0|P1|P2|P3|P4|P5",
      "risk_summary": "会造成什么后果",
      "files": ["path/to/file:起始行-结束行"],
      "fix_suggestion": "可执行的修改建议",
      "time": "提交时间 ISO",
      "subject": "提交标题",
      "cause": "造成风险原因"
    }
  ]
}

必填 6 字段：hash / author / risk_level / risk_summary / files / fix_suggestion 可选 3 字段：time / subject / cause（建议都填，process.md 才不空列）

约束：risk_level 只能 P0-P5；files 是字符串数组，元素格式 path:起-止；deliver 失败 stderr 会提示缺哪个字段，修复后 --resume 续跑。完整规则见 assets/vigil.md。

参数

退出码：0 ok / 1 runtime / 2 to_agent / 3 validation / 4 auth

硬性规则

• security_report.html 由 nodes/export_html.py 生成，避免样式漂移
• 审查代码只读，不修改被审查业务代码
• 每次跑用独立 job_id，不覆盖历史报告
• assets/vigil.md 是 Agent 角色设定与 schema 完整说明，agent_review 节点执行前必须读