git-review

Git Review

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

Dependencies

pip install esflow

Quick start

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

For artifact paths, see the data.report field in the stdout envelope (absolute path); by default they land in <output_root>/git-review/<job_id>/, organized into per-node directories:

File	Node directory	Description
commits.json	collect_commits/	Structured git log manifest
review.json	agent_review/	Agent commit-by-commit risk assessment
aggregate.json	aggregate/	Dual-index aggregation result
process.md	aggregate/	Human-readable process log
security_report.html	export_html/	Visualized report (auto-opens browser)

review.json is read by the Agent from assets/vigil.md + commits.json and generated, written to the agent_review/ directory.

Default is output_root = /tmp/esflow/outputs, which benefits from automatic system cleanup. For long-term retention, use --out <dir> to specify a persistent directory.--resume depends on the job_dir being alive; after the directory is cleaned up, resume will lose it.

scope date boundaries

--scope since..until Date mode:since includes midnight of that day,until includes 23:59:59 of that day. For example, 2026-07-03..2026-07-05 captures commits from 7-03 00:00 to 7-05 23:59.

Flow structure

esflow DAG orchestration (scripts/flow.py declaration,scripts/nodes/ each node):

Node	Responsibility
resolve	Parse repo/scope, produce plan (including scope_id)
collect_commits	Run git log, structure commits.json into the node output_dir
agent_review	TO_AGENT node; run until it exits the process (exit 2), the Agent writes review.json then continues running
aggregate	Pure-Python dual-index aggregation (author risk ranking + commit risk details), producing aggregate.json + process.md
export_html	Render security_report.html from aggregate.json, auto-open browser

job_dir

• job_dir = <output_root>/git-review/<job_id>/，<job_id> = <YYYYMMDD-HHMMSS>-<4hash>
• Each node output_dir = job_dir/<rid>/, artifacts land in their respective directories without overwriting each other
• Framework metadata is in job_dir/.esflow/：break_to_agent.json(list of nodes pending resume),<rid>/artifact.json(one per node)
• When TO_AGENT exits, the stdout envelope carries review_path / commits / vigil_md / commits_count, the Agent parses stdout to get the takeover path
• --resume <job_dir> pass job_dir to resume

Agent intervention

# 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>

When TO_AGENT exits, envelope.data contains review_path/commits/vigil_md/commits_count(artifact not yet generated); after resume aggregation, the final envelope.data contains commits/aggregate/process_md/report(see --schema）。

review.json Schema

written to agent_review/review.json(i.e. envelope.data.review_path), the framework deliver strictly validates value types:

{
  "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 required fields：hash / author / risk_level / risk_summary / files / fix_suggestion 3 optional fields：time / subject / cause(it is recommended to fill all, otherwise process.md will have empty columns)

Constraints:risk_level can only be P0-P5;files is a string array, element format path:起-止; if deliver fails, stderr will indicate which field is missing; after fixing, --resume resume. See full rules at assets/vigil.md。

Parameters

Parameter	Default	Description
--repo <path>	.	The git repository under review
--scope <range>	-	Date since..until / branch b1..b2 / single branch
--out <dir>	/tmp/esflow/outputs	esflow output_root, job_dir lands under it
--resume <job_dir>	-	resume the TO_AGENT node
--max-count <n>	0	Maximum number of commits to capture in single-branch mode, 0 means unlimited
--no-open	false	Do not open a browser; for CI/headless environments
--dry-run	false	Only run resolve to produce a plan
--schema	false	Output the JSON contract

Exit codes:0 ok / 1 runtime / 2 to_agent / 3 validation / 4 auth

Hard rules

• security_report.html generated by nodes/export_html.py to avoid style drift
• The review code is read-only; do not modify the business code under review
• Each run uses an independent job_id and does not overwrite historical reports
• assets/vigil.md is the complete specification of the Agent role settings and schema; it must be read before the agent_review node executes