给 AI coding 的项目小地图。
cmap 在你的项目里维护一组 .context/ 文件,记录项目目标、模块关系、当前主线、历史决策、验证方式、工作日志和灵感池。人能看,AI 也能看。
当你从 0 到 1 做项目、上下文被压缩、新会话重新接手、或者项目模块越来越多时,AI 可以先读这张地图,快速知道:
- 现在在做什么
- 该改哪个模块
- 会影响哪些地方
- 哪些决策不能忘
- 改完怎么验证
cmap 不是 AI coding 全家桶。它只做一件事:让项目持续可理解。
Current v0.2 direction is Trust Boundary + Human Review Layer:
- Graph means a deterministic projection of reviewed canonical module relations, not an import graph.
- Route uses canonical module docs and reviewed relations only; unpromoted candidates can be surfaced for review but must not affect
route.modules,route.contextModules, or benchmark scoring. - HTML view is the human review layer for maps, evidence, freshness, and candidates; UI labels default to English and can be exported in Chinese with
--ui-lang zh-CN. - i18n / zh-CN / locale mirrors remain paused; UI label localization must not become a second maintained fact store.
- Old import graph, route v2, and pack v2 plans are paused historical ideas, not the active roadmap.
pnpm install pnpm build node dist/cli.js version
During local development:
pnpm dev --help
New project:
cmap bootstrap --init --host both --skill cmap verify
Existing project:
cmap adopt
cmap install --host both
cmap skill export --host generic
cmap verifyDaily task:
cmap route "多人对话页面消息发不出去" --max-context 4 cmap checkpoint write --task "多人对话页面消息发不出去" --next "Read routed module docs" cmap brief "多人对话页面消息发不出去" --max-context 4 --out .context/out/brief.md cmap pack "多人对话页面消息发不出去" --budget 1200 --format markdown --out .context/out/pack.md cmap finish cmap finish --agent --task "多人对话页面消息发不出去" cmap update --agent --from .context/out/update-request-xxxx.md --apply-routine cmap evidence append --module route --file src/commands/route.ts --summary "Route behavior verified" cmap evidence list --module route cmap evidence migrate --from-module-docs --dry-run cmap policy validate cmap freshness snapshot cmap freshness mark-reviewed --module route --evidence "Reviewed route semantics" cmap hooks stop --profile assist --changed src/commands/route.ts --summary "Observed route work" cmap hooks render --host codex --mode assist cmap hooks ingest --host codex --event UserPromptSubmit --mode assist < codex-hook-payload.json cmap hooks test --event UserPromptSubmit --mode assist --prompt "多人对话页面消息发不出去" cmap hooks test --event PostToolUse --mode observe --tool Read --file src/commands/route.ts cmap graph build cmap graph explain route cmap inbox status cmap inbox triage cmap inbox promote update-xxxx --dry-run cmap inbox archive update-xxxx cmap verify --stale cmap verify --freshness cmap verify --coverage --changed cmap verify --ci --format markdown cmap obsidian export cmap obsidian export --check cmap view export --out _cmap-view cmap view export --ui-lang zh-CN --out _cmap-view cmap view export --include-support --out _cmap-view cmap view export --check --out _cmap-view cmap skill export --host codex cmap skill export --check cmap bootstrap --host both --skill cmap relate request --task "多人对话页面消息发不出去" --changed src/commands/route.ts --out .context/out/relation-request.md cmap relate ingest --from .context/out/relation-patch.json --dry-run cmap benchmark route --file bench/tasks.jsonl --min-top1 80 --min-top3 80 --min-context 80 --max-bad 0 cmap reconcile --adapter gsd-v1 --from .planning
| Command | Purpose |
|---|---|
cmap version |
Print version. |
cmap init --auto |
Create .context skeleton for a new project. |
cmap bootstrap --init --host both --skill |
Recommended new-project entrypoint: create .context, merge host entrypoints, export skill instructions, and write .context/out/start-here.md. |
cmap bootstrap --host claude|codex|both --skill |
In an initialized project, merge host entrypoints, optionally export skill instructions, and write .context/out/start-here.md. |
cmap adopt |
Create adoption workspace and candidate signals for an existing project. |
cmap install --host claude|codex|both |
Merge short cmap marker blocks into host entrypoints without overwriting existing rules. |
cmap install --host both --mode print |
Print the cmap marker block without writing files. |
cmap install --host both --force |
Explicitly overwrite host entrypoints with standalone cmap entrypoints. |
cmap install --host both --backup |
Back up existing entrypoints under .context/backups/install-* before writing. |
cmap skill export --host generic|codex|claude |
Export a project-local skill/reference pack under .cmap/skills/cmap/. |
cmap skill export --check |
Fail when the exported skill pack is missing or stale. |
cmap install --host both --hooks reminder |
Write project-local hook templates under .context/hooks/. |
cmap install --host both --hooks assist |
Write hook templates that can record generated evidence from changed files. |
cmap hooks render --host codex --mode observe|assist|strict |
Render Codex lifecycle settings to .codex/hooks.json without editing global host config. |
cmap hooks render --host claude --mode observe|assist|strict |
Render Claude lifecycle hook settings without editing global host config. |
cmap hooks ingest --host codex --event <event> --mode observe|assist|strict |
Read a real host hook JSON payload from stdin, write session logs/briefs, and return Codex-compatible JSON. |
cmap hooks test --event <event> --mode observe|assist|strict |
Simulate hook lifecycle events and strict guard decisions locally. |
cmap codex start "<task>" |
Run the supported explicit Codex startup workflow without relying on hook parity. |
cmap codex finish --task ... --verified ... |
Close a Codex task through finish/update/verify reminders. |
cmap codex guard --changed |
Run changed/stale/freshness/inbox guard checks for Codex handoff. |
cmap route "<task>" --max-context 4 |
Recommend direct modules, bounded related context files, and suggested verification commands. |
cmap route "<task>" --graph |
Enable explicit graph-aware route explanation while keeping direct matches separate from related context. |
cmap brief "<task>" --max-context 4 |
Render an AI coding brief from route, checkpoint/status, bounded context pack, and module docs. |
cmap pack "<task>" --budget 1200 --format markdown |
Render a redacted, budgeted context pack from the routed graph neighborhood. |
cmap status |
Print .context/STATUS.md. |
cmap checkpoint read |
Print .context/CHECKPOINT.md, falling back to .context/STATUS.md. |
cmap checkpoint write --task ... --next ... |
Update .context/CHECKPOINT.md from explicit handoff fields. |
cmap checkpoint close|clear |
Close or clear the current .context/CHECKPOINT.md. |
cmap checkpoint --goal ... --next ... |
Legacy-compatible update of .context/STATUS.md. |
cmap verify [--changed] |
Check context structure, heading anchors, and changed-file coverage. |
cmap verify --ci --format markdown |
Print a stable CI-friendly Markdown report for GitHub Actions or PR logs. |
cmap finish [--changed files] |
Print a QA-lite context closeout report. |
cmap finish --agent --task ... |
Write a local MapPatch request artifact under .context/out/. |
cmap update --agent --from <json> |
Classify an AI-authored MapPatch without changing canonical facts. |
cmap update --agent --from <json> --apply-routine |
Apply routine/generated MapPatch v2 operations; route semantic candidates to .context/inbox/. |
cmap update rollback <backupId> |
Restore files from a backup printed by update --apply-routine. |
cmap policy show |
Print the merged deterministic policy v2 JSON. |
cmap policy validate |
Warn about unknown policy keys without mutating files. |
cmap evidence append --module <id> --file <path> --summary ... |
Append bounded generated evidence to .context/generated/evidence/modules/<id>.jsonl. |
cmap evidence list --module <id> |
List generated module evidence entries. |
cmap evidence migrate --from-module-docs --dry-run|--apply |
Move legacy generated evidence blocks out of module docs. |
cmap freshness snapshot |
Write .context/generated/freshness.json. |
cmap freshness diff |
Compare current files to the generated freshness snapshot. |
cmap freshness mark-reviewed --module <id> |
Mark module semantic facts as reviewed. |
cmap hooks stop --profile observe|assist --changed <files> |
Record hook events; assist can append generated evidence for mapped changed files. |
cmap inbox status |
Count candidate context updates and high-risk backlog under .context/inbox/. |
cmap inbox triage |
Group candidate context updates by risk/type and suggest the next review action. |
cmap inbox promote <id> --dry-run |
Preview promotion guidance without editing canonical context. |
cmap inbox promote <id> --apply |
Apply allowed low-risk alias/path/evidence candidates with backup, audit, verify, and archive. |
cmap inbox reject <id> --reason ... |
Archive a reviewed false candidate with an explicit rejection reason. |
cmap inbox archive <id> |
Move reviewed candidates to .context/inbox/archive/ without deleting them. |
cmap verify --stale |
Warn when module docs are older than owned files or inbox candidates need review. |
cmap verify --freshness |
Warn when reviewed facts are older than owned files, generated evidence, or pending candidates. |
cmap obsidian export |
Export Obsidian-friendly module notes under _cmap/<project>/. |
cmap obsidian export --check |
Fail when the generated Obsidian view layer is missing or stale. |
cmap obsidian open <module> |
Print an obsidian:// URI for a module note. |
cmap obsidian pull --dry-run |
Detect candidate edits from exported Obsidian notes without changing .context. |
cmap view export --out _cmap-view |
Export a read-only single-file HTML project-map review dashboard. |
cmap view export --ui-lang zh-CN --out _cmap-view |
Export the same reviewed .context facts with Chinese UI labels. |
cmap view export --include-support --out _cmap-view |
Include generated evidence, inbox candidates, and freshness support layers. |
cmap view export --check --out _cmap-view |
Fail when the HTML review dashboard is missing or stale. |
cmap relate request --task ... --changed ... |
Generate an AI RelationPatch request prompt/template. |
cmap relate ingest --from <json> --dry-run |
Validate AI relation candidates without writing inbox files. |
cmap relate ingest --from <json> --write-inbox |
Write accepted relation candidates to `.context/inbox/relations/*.json |
cmap relate promote <id> --dry-run |
Preview relation promotion only; v0.2 does not auto-apply canonical relation edits. |
cmap graph build |
Write deterministic .context/graph/*.json projections from reviewed module docs. |
cmap graph explain <module> |
Explain one module's files and typed graph relations. |
cmap benchmark route --file bench/tasks.jsonl |
Measure route top-k and context-pack accuracy against JSONL task fixtures. |
cmap benchmark route --file bench/tasks.jsonl --min-top1 80 --min-top3 80 --min-context 80 --max-bad 0 |
Fail CI when route quality falls below explicit thresholds. |
cmap reconcile --adapter gsd-v1|gsd-v2 --from <dir> |
Dry-run candidate facts from external workflow artifacts. |
cmap add-module <name> |
Create a candidate module doc. |
cmap cp copy/move/delete/restore |
Move existing line blocks with backups for destructive edits. |
cmap log add "..." |
Append a work log entry. |
cmap idea add "..." |
Append a non-canonical idea. |
cmap doctor |
Diagnose context, entrypoints, and hook templates. |
cmap CLI does not generate trusted project semantics.
- CLI creates skeletons, scans deterministic signals, routes by aliases, and checks structure.
- Route graph expansion is a context-pack hint only. Related modules are not treated as direct task matches.
graph buildprojects canonical module relations reviewed in.context/modules/*.md; it does not infer imports, symbols, tests, or ownership from source code.- Source-level facts such as imports, callers/callees, symbol lookup, and impact analysis belong to the configured code intelligence tool, such as CodeGraph.
- CMAP records durable project memory: module explanations, handoff, decisions, status, candidates, and verification notes.
- Unpromoted inbox/relation candidates are non-canonical. They may appear as warnings or review material, but route and benchmark must not score from them.
--max-contextonly limits selected context modules and derived verify suggestions; it does not change module scoring.packonly includes routed graph-neighborhood context; it does not scan or embed the whole repository.pack --budgetuses a deterministic approximate token budget and redacts obvious secret-looking values before output.- AI or users write project purpose, module responsibilities, decisions, and current state.
update --agentcan process AI-authored MapPatch JSON; routine checkpoint/generated evidence/stats operations can auto-apply with policy gates, while module semantics and decisions go to.context/inbox/.evidence appendwrites generated support evidence only. It does not make module responsibilities, dependencies, or decisions canonical..context/policy.ymlcontrols bounded routine/generated maintenance defaults such as stats updates and inbox thresholds; semantic and decision auto-writes remain disabled.- Route commands and assist hook prompt events may update generated
.context/generated/stats/route-usage.jsonwhen policy allowsstats.update; these counters are not canonical semantics. inbox status,inbox triage,inbox promote --dry-run,inbox promote --apply,inbox reject,verify --stale, andverify --freshnesskeep candidate backlog and map drift visible. Only low-risk alias/path/evidence candidates can be promoted automatically.- Reminder/maintain hooks only remind. Observe hooks write non-canonical hook logs/session events. Assist hooks may write generated evidence under
.context/generated/or generated session briefs, and strict Codex ingest / local hook tests can block direct semantic canonical writes, but hooks do not updateMAP.md,CHECKPOINT.md,STATUS.md,DECISIONS.md, module responsibilities, or decisions. hooks ingest --host codex --event UserPromptSubmit --mode assistandhooks test --event UserPromptSubmit --mode assist --prompt ...write.context/out/session-brief.mdas a generated startup artifact, not trusted project memory.logs/,ideas/,inbox/, and.context/generated/are not canonical project facts.
bench/tasks.jsonl supports:
expected_modules: direct route modules that should appear in top results.bad_modules: direct route modules that should not appear in top results.expected_context_modules: context-pack modules that should be selected through direct matches or graph relations.
CI can enforce benchmark thresholds with:
cmap benchmark route --file bench/tasks.jsonl --min-top1 80 --min-top3 80 --min-context 80 --max-bad 0
pnpm test pnpm typecheck pnpm build pnpm dev verify --ci --format markdown pnpm dev verify --stale pnpm dev verify --freshness pnpm dev obsidian export --check pnpm smoke pnpm dev benchmark route --file bench/tasks.jsonl --min-top1 80 --min-top3 80 --min-context 80 --max-bad 0