Project Cartographer Agent 是 Quality Agent 体系的共享项目制图 Agent。它先为本地路径或 GitHub 仓库建立结构化、可审计、可回补的项目地图，再把白盒、灰盒、黑盒各自需要的上下文视图交给专业 Agent 下钻。
根规范见：
当前实现提供一个无外部 npm 依赖的 Node.js review-grade 实现：
- 本地仓库
project_bootstrap - 指定路径
path_bootstrap - 只读 GitHub-style checkout
github_bootstrap - 核心项目地图 artifacts
- command/source/search trace
- completeness gate 和 Human Gate work order
- final-answer manifest、渲染器和校验器
- deterministic audit
- downstream refill response、changed-artifact diff 和 item-level semantic diff
- heuristic parser seeds，用于 JS/TS/Go/Python 路由和符号发现
- deep index enrichment，用于 dependency graph hints、route/controller hints、test runner hints、targeted unknown reads 和 consumer-specific refs
- large-project gate，触发时阻止下游 focused dispatch 并生成 Human Gate work order
- requested-consumer handoff，只为请求的下游 Agent 生成 context package 和 context admission
- failure-code registry，用于集中维护和校验错误码
- network-dependent GitHub remote profile，用于验证真实只读 checkout、resolved SHA、cache manifest 和 mutation audit
- prompt-to-input adapter，用于把短提示归一化为 canonical input
- Human Gate v2 work order，包含推荐决策、decision matrix、推荐 scope paths 和 next action
- Gate decision resume，用于从人工决策生成下一轮 canonical input 或 inventory closeout
- validation summary artifact，用于让最终回答从 artifact 而不是 stdout 复述质量指标
- downstream readiness reasons，用于解释每个下游 Agent 为什么 allowed、blocked 或 inventory_only
- 生成目录、缓存目录和 checkout 目录默认排除，避免运行产物污染项目地图
- 机器可读 policy，用于集中维护排除规则、完整性阈值、大项目判定和最终回答禁用声明
- 正向和负向 fixtures
实现状态见：
安装依赖不是必须的；项目只使用 Node.js 标准库。
运行内置验证：
npm run verify:cartographer
npm run verify:cartographer:v2
npm run audit:spec-coverage运行真实 GitHub 远端只读 profile。该命令依赖网络和本机 git，因此不放进默认离线验证链：
npm run test:github-remote对本地仓库运行项目制图：
node scripts/run-project-cartographer.mjs fixtures/local-project/input.json runs/local-project
node scripts/validate-run.mjs runs/local-project --print-metrics
node scripts/render-final-answer-summary.mjs runs/local-project > runs/local-project/final-answer-summary.md
node scripts/validate-final-answer-summary.mjs runs/local-project runs/local-project/final-answer-summary.md从短提示生成 canonical input，再运行项目制图：
printf '请用 Project Cartographer Agent 分析 fixtures/sample-repo。' \
| node scripts/create-input-from-request.mjs \
--run-id prompt-local \
--output-run-dir runs/prompt-local \
--output fixtures/prompt-to-input/local-input.json
node scripts/run-project-cartographer.mjs fixtures/prompt-to-input/local-input.json runs/prompt-local
node scripts/validate-run.mjs runs/prompt-local --print-metrics短提示也可以保留路径范围：
printf '目标项目: fixtures/sample-repo\n指定路径: app' \
| node scripts/create-input-from-request.mjs \
--run-id prompt-path-scope \
--output-run-dir runs/prompt-path-scope \
--output fixtures/prompt-to-input/path-scope-input.json
node scripts/run-project-cartographer.mjs fixtures/prompt-to-input/path-scope-input.json runs/prompt-path-scope
node scripts/validate-run.mjs runs/prompt-path-scopeGitHub URL 短提示会生成只读 GitHub canonical input。默认验证链只校验解析，不自动依赖网络 clone：
printf '请分析 https://github.com/acme/cartographer/tree/main/packages/api' \
| node scripts/create-input-from-request.mjs \
--run-id prompt-github \
--output-run-dir runs/prompt-github \
--output fixtures/prompt-to-input/github-input.json无有效目标的短提示必须失败：
printf '请分析这个项目' | node scripts/create-input-from-request.mjs处理 Human Gate：
node scripts/run-project-cartographer.mjs fixtures/human-gate/input.json runs/human-gate
node scripts/validate-run.mjs runs/human-gate --print-metrics
node scripts/render-final-answer-summary.mjs runs/human-gate > runs/human-gate/final-answer-summary.md
node scripts/validate-final-answer-summary.mjs runs/human-gate runs/human-gate/final-answer-summary.md
cat runs/human-gate/human-gate-work-order.project-cartographer.jsonHuman Gate 批准后生成下一轮 input：
cat > runs/human-gate/human-gate-decision.project-cartographer.json <<'JSON'
{
"artifact_type": "human-gate-decision-project-cartographer",
"schema_version": "project-cartographer-v1",
"run_id": "fixture-human-gate",
"work_order_ref": "runs/human-gate/human-gate-work-order.project-cartographer.json#/",
"decision": "approve_with_scope",
"approved_scope_paths": ["app"],
"approved_index_depth": "deep",
"operator_label": "human",
"decision_source": "chat",
"decision_reason": "先聚焦 app 路径继续 deep index。",
"operator_note": "批准 scope narrowing",
"approved_at": "2026-05-28T00:00:00.000Z",
"created_at": "2026-05-28T00:00:00.000Z"
}
JSON
node scripts/create-input-from-gate-decision.mjs \
runs/human-gate \
runs/human-gate/human-gate-decision.project-cartographer.json \
--output fixtures/prompt-to-input/human-gate-next-input.json处理下游 refill request：
node scripts/run-refill-scope.mjs runs/local-project fixtures/refill/request.json runs/refill执行 AI-free deterministic audit：
node scripts/deterministic-audit.mjs runs/local-project runs/local-project-audit本项目的 orchestrator 应把短提示归一化为 project-cartographer-input.json：
请用 Project Cartographer Agent 分析 /abs/path/to/repo。
当前确定性 runner 仍只消费 canonical input；scripts/create-input-from-request.mjs 只是输入生成器，不生成项目地图事实、不读取目标代码、不运行 runner。项目事实仍由 run-project-cartographer.mjs 和后续 validate-run.mjs 负责。
Project Cartographer 输出上下文地图，不输出白盒、灰盒、黑盒 validated risk，不声明 release ready，也不声明 all code understood。