CodeCartographer

CodeCartographer

借助 AI Agent 理解陌生代码库，并获得可供重建的经过验证的规范。 CodeCartographer 会将代码库转化为分层架构、行为契约、缺陷发现结果，以及与语言无关的重实现规范；每个阶段都会经过验证后才会运行下一阶段。可与 Pi、Claude Code、Cursor、Codex 或任何兼容 MCP 的 Agent 搭配使用。

●  CodeCartographer
├─ ✓  architecture phase    ⟳ 25 · 76 tool uses · 1.0M tokens · 4m28s
├─ ✓  defect-scan-mech.     ⟳ 39 · 91 tool uses · 2.4M tokens · 7m05s
└─ ⠹  contracts phase       ⟳ 11 · 37 tool uses · 335.1k tokens · 40.1s
       ⎿ extracting behavioral contracts from server/index.ts…

---

为什么选择 CodeCartographer

让大模型“分析这个代码库”，往往会在分析到一半时丢失上下文、臆造发现结果，而且不会留下可供下一次会话接续使用的产物。CodeCartographer 解决了三个问题：

1. 文件系统才是记忆，而不是对话。 每个阶段都会将更精简、采用模板且带有证据标签的产物写入 .codecarto/findings/。后续阶段会重新读取所需的特定上游文件。新会话——或上下文压缩后——都能根据 status.yaml 接续进度，不会丢失已有成果。

2. 每个阶段都会证明自己已完成，而门禁会据此进行核验。 每项输出末尾都有一个 ## Validation 表格，阶段会在其中根据证据，将每项完成标准标记为 PASS、PARTIAL 或 FAIL。验证过程会解析该表格，交叉核对发现结果中的证据与行动是否匹配，以及声明的次要输出；如果出现 FAIL、缺少输出或无法读取的判定，就会拒绝继续推进。验证不会自行重新判定这些标准——判定依据是模型诚实的自我评估，再加上两项机械检查；后续阶段正是通过这些内容来核验前序阶段。

3. 输出是规范，而不是聊天记录。 最终的 reimplementation-spec.md 与语言无关，列出了模块清单，并附带验收场景和已知未知项。可将它交给另一个 Agent 来重建。

每项发现都会标注一个证据等级：observed fact、strong inference、portability hazard、external-behavior claim 或 open question。

---

概览

你将获得	所在位置
分层分析流水线 — 架构 → 缺陷扫描 → 行为契约 → 协议 → 移植 → 重新实现规范	.codecarto/ 模板
阶段之间的验证关卡 — 阶段自身的 ## Validation 表格加两项交叉检查；未通过 FAIL 时不得进入下一阶段	core/ 状态机
三个入口，共用一个框架 — Pi 扩展（推荐）、MCP 服务（供其他编码 Agent 使用）或即用型模板（一次性评估）	三者共用 core/
实时进度小组件，在阶段子 Agent 工作时显示	Pi 扩展
HTML 仪表板 — 单文件汇总进度、链接、用法和说明	.codecarto/dashboard.html
按阶段跟踪 token 用量	/codecarto-usage
选择启用 LLM 引导下一阶段的种子提示词	/codecarto-next --llm-steer
前向综合 — 愿景 + 已确认的库规范 → 有来源依据的项目计划	pipeline-synthesis.yaml

从 Pi 或 MCP 发布已完成的重新实现规范，然后运行 synthesis 流水线，将产品愿景和明确确认的库条目转化为能够识别冲突的 project-plan.md，并附带决策级来源记录。

如果 CodeCartographer 为你节省了一天的代码库考古时间，请给仓库点个星标 — 这有助于更多人找到它。

OpenAI Build Week 评审者：请参阅新旧范围说明和一键演示。

---

安装

三个入口，按推荐顺序排列。三者共用同一 core/，并生成字节级完全相同的阶段提示词。Pi 提供最丰富的编排体验；Pi 和 MCP 均支持可执行的库和综合工作流；即用型模式提供分析框架，但不包含这些运行时操作。

1. Pi 扩展 — 推荐用于交互式使用。提供一流的用户体验。
2. MCP 服务 — 适用于 Claude Code、Codex、opencode、Cursor、Claude Desktop，以及任何其他支持 MCP 的 Agent。
3. 即用型模板 — 纯 .codecarto/ Markdown + YAML，适用于一次性评估或任何能够读写文件的大模型。纯即用型模式不支持库和综合工作流；分析功能则完整可用。

Pi 扩展（推荐）

Pi 是一款 TUI 编码 Agent。CodeCartographer 扩展提供斜杠命令、实时 Agent 小组件和仪表板。

pi install npm:codecartographer-pi          # from the npm registry
pi install /absolute/path/to/CodeCartographer  # from a local checkout
pi install git:github.com/HuginnIndustries/CodeCartographer  # from a git URL

请勿为 Pi 使用场景运行 npm install codecartographer-pi。普通的 npm install 只会将软件包安装到磁盘上，不会将其注册到 Pi。请使用 pi install npm:...，这样 Pi 才会将软件包写入自己的 ~/.pi/agent/settings.json。

开发扩展时，可让 Pi 直接指向入口文件：

pi -e /absolute/path/to/CodeCartographer/extensions/codecarto/index.ts

MCP 服务（供其他编码 Agent 使用）

当你的编码 Agent 不是 Pi 时使用此方式 — 适用于 Claude Code、Codex、opencode、Cursor、Claude Desktop，或任何支持 MCP 的工具。宿主负责驱动对话并运行大模型；CodeCartographer 提供阶段提示词、验证以及实验性的库发布／列出／重新索引操作。

Claude Code、Cursor、Codex 和 Claude Desktop 的 30 秒快速设置：请参阅 MCP 快速入门。

**教 Agent 如何驱动它：**调用 codecarto_guide 工具 — 服务会返回完整的驱动流程、阶段交接契约、执行器选择和恢复模式，无需安装任何内容。相同内容也以可安装技能的形式提供，位于 agent-skill/codecartographer/，适用于从磁盘加载技能的 Agent；在 Pi 会话中运行 /codecarto-guide [topic] 即可读取这些内容。

npm install --global codecartographer-pi

添加到宿主配置中（~/.config/claude-code/config.json、claude_desktop_config.json 等）：

{
  "mcpServers": {
    "codecartographer": {
      "command": "codecarto-mcp"
    }
  }
}

官方 MCP Registry 条目：io.github.HuginnIndustries/codecartographer。

即插即用模板（一次性使用／评估）

使用此模板，无需安装任何内容即可在任意仓库中试用 CodeCartographer；也适用于无法使用 Pi 或支持 MCP 的 Agent 的环境。适用于任何能够读取和写入文件的大模型。

cp -r /path/to/CodeCartographer/.codecarto /path/to/your-repo/

然后在大模型会话中运行：Read .codecarto/GUIDE.md and begin the analysis.

限制。 即插即用模式会完整运行分析流程，但库和综合工作流需要通过 Pi 或 MCP 执行代码。

---

前向综合快速入门

分析会将仓库转化为可复用的规格。综合则反向进行：将原始产品愿景与经过人工确认的规格结合起来，生成可直接用于实施的计划，同时保留溯源信息。

1. 配置包含通过 /codecarto-publish 或 MCP codecarto_publish 工具发布的规格的库：

   # ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml
   library:
     path: /absolute/path/to/codecarto-library
     namespace: your-namespace # omit for a single-tenant library
     publish_confirm: true # Pi asks before writing; MCP refuses a publish that lacks confirm: true
   

2. 初始化一个干净的规划工作区，并填写其中的项目简介：

   /codecarto-init synthesis
   

   编辑 .codecarto/inputs/vision.md，填写受众、问题、期望结果、约束和非目标。

3. 运行，直到 CodeCartographer 创建候选方案：

   /codecarto-next --auto
   

   此次运行会刻意在合并前停止。检查 .codecarto/findings/goal-synthesis/proposal.md，并将一个或多个候选框从 [ ] 改为 [x]。

4. 恢复运行：

   /codecarto-next --auto
   

最终的 .codecarto/findings/goal-synthesis/project-plan.md 包含产品范围、架构、工作包、验收关卡、未解决冲突登记表，以及一份溯源台账，将每项关键决策映射回愿景或已确认的规格。运行时预检会阻止在获得明确的人工确认前进行合并或最终定稿。

---

工作原理

“代码”是 .codecarto/ 中结构化的 Markdown + YAML：

• GUIDE.md — 大模型入口。每次会话都会先读取此文件。
• workflow/pipeline.yaml — 阶段定义、依赖关系和输出路径。
• workflow/status.yaml — 每个项目可变的状态。进度的唯一事实来源。
• workflow/VALIDATE.md — 每个阶段结束后运行的验证协议。
• findings/<phase>/SKILL.md — 各阶段的详细分析说明。
• templates/ — 用于确保结构一致的输出模板。

各阶段组成一个有向无环图（DAG）：contracts 和 protocols 可在 architecture 之后并行运行；porting 需等待两者完成；reimplementation-spec 为最后一个阶段。宿主环境（Pi、MCP 或你的 shell）会读取当前启用的流水线，找到依赖项均为 complete 的下一个阶段，将该阶段的说明交给大模型，验证输出，并更新 status.yaml。

对于跨多个会话的工作，每个新会话都会读取 .codecarto/GUIDE.md（或更精简的 NEW_THREAD_BLURB.md），检查 workflow/status.yaml，然后从上次会话结束处继续。你无需解释之前会话中发生了什么。

---

渐进式提炼与上下文韧性

CodeCartographer 会逐步提炼代码库，并为证据标注标签。它不会要求一个上下文窗口记住整个调查过程，而是让每个阶段将大量源证据转化为更精简、针对性更强的产物，供下一阶段读取：

source code
  → architecture map
  → behavioral contracts + protocols + defect findings
  → porting bundle
  → reimplementation spec

这是有意进行的提炼，而非偶然的聊天摘要。每个产物都遵循模板，保留证据等级和已知的未知项，并且必须通过验证后才能作为下游阶段的输入。

对话上下文被压缩时会发生什么？

运行过程的持久记忆来自文件系统，而非对话：

• 每个阶段都会获得全新的上下文窗口。在 Pi 扩展中，阶段作为隔离的阶段子 Agent 运行；MCP 和即插即用宿主应采用相同的每阶段一个会话模式。
• 已完成的发现保存在 .codecarto/findings/ 下。后续阶段会重新读取当前流水线声明的特定上游产物，而不是依赖对话记忆。
• workflow/status.yaml 会记录进度、终结状态的 open_questions、流水线内的 carry_forward，以及单独的 post_pipeline 待办列表，用于记录完成后的可选探索、修订、差异、决策和重新运行。阶段 Agent 会在 .codecarto/scratch/handoffs/<phase>.yaml 中提出更改；完成时会在锁定状态下验证并应用这些更改，同时写入宿主时间戳、唯一规范的收尾记录，以及幂等的 THREAD_LOG.md 条目。
• Pi 阶段记录以文件形式保存，即使活动模型上下文已被压缩，仍可通过 /resume、/tree 和 /export 查阅。
• 对于隔离的 Pi 阶段会话，压缩时会使用感知阶段的续接摘要，明确保留证据、检查过的文件、输出进度、待解问题和验证缺口。生成的摘要也会以原子方式保存为检查点，位于 .codecarto/scratch/checkpoints/<phase>.md。
• Pi 会在本地使用数据中记录成功、失败和中止的压缩操作及其触发原因（threshold、overflow 或 manual），并在小组件、/codecarto-usage、完成摘要和仪表板中显示总数。

因此，压缩甚至替换编排器会话都不会抹去流水线进度。新会话可以从磁盘还原相关状态并继续执行。

剩下的限制是单个超大阶段内部。即便是 Pi 的阶段感知摘要，也仍是有损提炼；MCP 和即插即用环境中的压缩则完全由宿主控制。因此，阶段说明会优先要求定向读取、持久检查点和明确的覆盖范围记录；如果无法完整覆盖，阶段会记录 PARTIAL 验证状态，并将未解决的工作列入 open_questions 或 carry_forward。跨阶段的上下文丢失在很大程度上已通过设计消除；阶段内的上下文压力则会被观察并限制，而非隐藏。

移植包是最后一个有意设置的压缩边界。它包含来源索引、关键不变量、缺陷处置情况和深度阅读触发条件。reimplementation-spec 默认读取该包，仅在存在明确缺口、冲突、验收细节缺失或缺陷理由时才打开较低层级的报告。

---

各阶段会生成以下产物

产物	说明
架构图	分层、依赖方向、公共接口、运行时生命周期、并发模型
缺陷报告	多轮扫描逻辑错误、安全问题、并发错误和 API 违规
缺陷修复跟踪表	修复、延期或接受的每项缺陷处置与缺陷报告之间的对应记录
行为契约	按功能说明行为、默认值、错误处理和验收测试
协议与状态	事件流、状态机、持久化格式、兼容性隐患
移植包	汇总为面向移植的视图，并按优先级排序
重新实现规范	与语言无关的构建计划，包含模块、验收场景和已知未知事项

每项发现都会标注证据等级：observed fact、strong inference、portability hazard、external-behavior claim 或 open question。每个阶段的输出末尾都会附上该阶段针对流水线完成标准的验证表；在流水线推进前，关卡会先检查该表。

---

流水线变体

默认配置为 7 阶段运行，将缺陷扫描拆分为前期的机械扫描和后期的语义扫描；随后，重新实现阶段会结合完整的契约和协议上下文，围绕缺陷进行设计。如果想缩减流程，可以选择以下变体：

变体	阶段数	适用场景
完整（深度审计）（默认）	7	完整分析，包含拆分的缺陷扫描；重新实现基于结合契约和协议的缺陷发现结果
先侦察	8	在深度审计流程前增加 broadside-scout 阶段，将已有的 Broad-Side 运行结果提炼为路由简报，供后续每个阶段读取
完整（含审计）	6	仅进行一次前期缺陷扫描；当缺陷大多是机械性问题时，比深度变体成本更低
完整	5	移植或重新实现，不进行任何缺陷扫描
缺陷扫描	2	维护审计，用于发现潜在问题
精简	3	需要了解行为，但不需要移植计划
仅架构	1	快速了解整体结构
综合规划	4	将产品愿景和已确认的库规格转化为有溯源依据的实施计划

使用 /codecarto-switch-pipeline <variant>（Pi）或 codecarto_switch_pipeline（MCP）切换当前流水线。这会就地改写 status.yaml，但不会删除发现结果、交接内容、使用数据或收尾记录。新旧流水线共有的阶段会保留其完成状态，游标则会移至新流水线中下一个尚未完成的阶段。如果某项后续处理的目标阶段不在新流水线中，该项会移至 post_pipeline（切换时会逐项列出），届时可通过修订将其关闭。

磁盘上的文件：

变体	流水线文件
完整（深度审计）（默认）	workflow/pipeline-full-with-deep-audit.yaml
先侦察	workflow/pipeline-scout-first.yaml
完整（含审计）	workflow/pipeline-full-with-audit.yaml
完整	workflow/pipeline.yaml
缺陷扫描	workflow/pipeline-defect-scan.yaml
精简	workflow/pipeline-lite.yaml
仅架构	workflow/pipeline-architecture-only.yaml
综合规划	workflow/pipeline-synthesis.yaml

---

仪表板

每次状态变更都会重新渲染 .codecarto/dashboard.html——这是一个自包含的单文件产物，可在任意浏览器中打开。它汇总了人们希望一目了然看到的所有信息：

• 流水线进度条及各阶段状态徽章
• 各阶段卡片，包含输出链接、未解决问题、后续处理路由、负责人备注和最近一次运行用量
• 汇总 Token 和上下文压缩遥测数据，以及各阶段明细
• 阶段运行活动时间线（Token、时长、上下文压缩）
• 按来源阶段分组汇总的未解决问题
• 收尾记录列表（按时间倒序），包含相对路径链接

不使用任何外部资源——没有外部链接，也不会获取任何内容。文件内嵌了两个自带的 <script> 块（一个 JSON 数据岛和搜索／筛选代码），因此可直接通过 file:// 打开。浅色／深色模式由 prefers-color-scheme 控制。

可选的叙述式摘要。 /codecarto-dashboard --narrate 会将编排器模型作为一次性会话运行，撰写一份 200–400 词的执行摘要，并引用近期收尾记录中的具体发现。摘要会缓存至 .codecarto/.dashboard-narration.local.md，并在确定性重新渲染时保留，同时附带“（距上次已运行 N 次）”的过期提示。

Pi 扩展功能

除了斜杠命令外，Pi 扩展还提供：

阶段子 Agent。 /codecarto-next 会将每个阶段作为独立的 AgentSession 启动。工具调用、文件读取和推理都在子级自己的上下文窗口中进行，不会累积到协调器中。阶段在后台运行时，你的 TUI 会停留在协调器会话中，并保持响应。

编辑器上方的实时 Agent 小组件，显示工具调用次数、令牌用量、耗时和当前活动。

●  CodeCartographer
└─ ⠹  architecture phase  ⟳ 3 · 5 tool uses · 12.3k tokens · 1m32s
       ⎿ reading…

基于文件的阶段会话。 阶段记录会持久化到协调器使用的同一个 Pi 会话目录中，因此可以通过 /resume、/tree 和 /export 将它们作为一等会话浏览。每个会话都会显示为 CodeCartographer phase: <id>，并保留其与协调器会话的沿袭关系。

阶段感知的压缩与检查点。 只有名为 CodeCartographer phase: <id> 的隔离会话才会收到专用压缩提示词。它会保留阶段目标、证据、已检查文件、输出进度、待解决问题和验证缺口，然后将生成的摘要写入 .codecarto/scratch/checkpoints/<phase>.md。协调器和无关的 Pi 会话仍使用主机的常规压缩方式。

协调器记录中的阶段完成摘要。 阶段结束时，会通过 pi.sendMessage(...) 将 Markdown 收尾块追加到协调器会话中。该内容会显示在 TUI 的滚动记录中，并在你发送下一条消息时作为上下文提供给协调器的大模型。不自动触发——由你掌控。

可选的 LLM 引导种子提示词。 在 .codecarto/workflow/config.yaml 中设置 orchestrator.llm_steer_next_phase: true（或在每次调用时传入 --llm-steer），协调器的大模型便会改写下一阶段的种子提示词，突出相关的既有发现。默认关闭——这会额外消耗协调器侧的令牌，且必须选择启用。改写后的提示词会注入协调器记录，方便你审查改写器选择强调的内容。

按阶段跟踪用量。 每次阶段运行都会追加到 .codecarto/workflow/.usage.local.yaml。/codecarto-usage 会报告累计用量和各阶段的令牌、运行时间、工具使用及压缩总量，包括阈值／溢出／手动触发，以及成功／失败／中止的结果。

工具拦截。 bash 会被直接屏蔽；edit 和 write 只能操作 .codecarto/，以及配置并通过标记验证的 CodeCartographer 库（如有配置）。阶段子 Agent 也会受到相同的钩子限制，但根目录范围更窄——仅限 .codecarto/，因为阶段只写入发现和交接内容，不会发布成果。

斜杠命令

命令	用途
/codecarto-init [variant]	将 .codecarto/ 复制到当前仓库，并选择流水线变体
/codecarto-open	在新的 Pi 会话中激活现有 .codecarto/ 工作区，不重置持久状态
/codecarto-vision	通过引导式产品探索访谈，生成供综合流水线使用的 inputs/vision.md
/codecarto-switch-pipeline <variant>	原地切换活动流水线，不丢失发现结果或进度
/codecarto-status	查看当前阶段、进度和未解决的问题
/codecarto-next [--auto [--strict]] [--llm-steer | --no-llm-steer]	将下一个符合条件的阶段作为子 Agent 启动。子 Agent 完成后，会自动验证并完成该阶段，让 status.yaml 无需手动操作即可推进。--auto 会端到端遍历整个流水线（重复执行相同的验证、完成和推进循环）；--strict 会将 PASS WITH GAPS 规则从“推进”切换为“暂停”。
/codecarto-phase <id>	强制执行指定阶段，即使它不符合流水线顺序
/codecarto-validate [phase]	根据完成标准验证阶段输出
/codecarto-complete [phase]	验证并原子化应用阶段交接、规范状态、收尾记录和日志条目
/codecarto-skill <name>	所有阶段完成后运行一次后续流水线技能（或随时运行 broadside，用于侦察阅读指南）
/codecarto-list-skills	列出已安装的后续流水线技能和不受限制的 broadside 阅读指南，并说明受限技能何时解锁
/codecarto-guide [topic]	将打包的 Agent 指南——驱动循环、交接约定、执行器、恢复和 Broad-Side——载入会话；主题支持 Tab 补全；无需工作区
/codecarto-broadside [action] [lenses…]	批量侦察（Broad-Side）。操作：submit、collect、status、models。运行前会估算费用并征求同意；有无工作区均可使用
/codecarto-publish	在查看明确的确认预览后，将重新实现规范发布到已配置的库
/codecarto-library-init <path> [--namespace <name>]	创建包含标记文件的库目录并写入配置——解决首次发布时无法继续的问题
/codecarto-config	显示合并后的有效配置（全局配置 + 工作区配置）以及库标记状态
/codecarto-usage	查看累计用量和各阶段的令牌用量
/codecarto-dashboard [--narrate]	重新生成 .codecarto/dashboard.html；使用 --narrate 生成大模型执行摘要
/codecarto-refresh-scaffold	在确认提示列出确切文件集后，从打包模板刷新框架管理的 .codecarto/ 文件（GUIDE.md、templates/、workflow/ 流水线和 VALIDATE.md）；绝不会触碰项目状态、配置、发现结果输出、临时文件、收尾记录和 broadside/
/codecarto-amend <name>	在确认预览将关闭哪些未解决问题和后续流水线项目后，应用来自 scratch/amendments/<name>.yaml 的后续流水线修订；流水线未完成时会拒绝执行

端到端自动模式（0.8.0+）

/codecarto-next --auto 会在无需人工干预的情况下遍历整个流水线。循环会启动下一个符合条件的阶段，自动验证输出，自动将其标记为完成，然后继续推进，直到流水线完成，或遇到阻止流程继续的情况（验证结果为 FAIL / MISSING、子 Agent 出错或 ctx.signal 中止）。编排器的 TUI 始终保持响应；各阶段摘要照常写入记录，最后的 codecarto-auto-summary 块会报告执行结果、累计 token 数、耗时，以及运行提前停止时的恢复提示。

• 可恢复性是隐式的：重新运行 --auto 时会读取 status.yaml，并从 getNextEligiblePhase 继续。
• --strict（需要 --auto）会将 PASS WITH GAPS 视为停止条件，适用于你想先处理差距再继续推进的情况。
• --auto --llm-steer 会在每次阶段转换时运行改写器；各阶段的引导块会写入编排器记录，便于审计运行过程。

版本历史（Pi 编排）

当前的并行子 Agent 设计在 0.2.0 中推出，之后逐步扩展：基于文件的会话（0.3.0）、摘要注入（0.4.0）、可选的 LLM 引导（0.5.0）、用量跟踪（0.6.0）、HTML 仪表板（0.7.0）、端到端自动模式（0.8.0）、实验性的库基础设施及 MCP 库工具（0.9.0），以及 Pi 覆盖层激活门控（0.9.1）。0.1.x 工作区无需迁移，现有 .codecarto/ 目录可保持不变。详情请参阅 CHANGELOG.md。

---

MCP 服务

同一框架也打包为 Model Context Protocol 服务。MCP 路径会返回提示词文本，供宿主分发，不会自行运行子 Agent，因此 Pi 专属的编排功能（子 Agent、实时小部件、仪表板、用量跟踪）不适用。不过，由于两种路径都会导入同一个 core/，因此阶段提示词和验证结果与 Pi 路径逐字节一致。v0.9.0 还提供了实验性库工具，支持具备 MCP 能力的宿主发布、列出和重新索引可复用的 reimplementation-spec.md 工件。

通过 @modelcontextprotocol/server ≥ 2.0.0 实现 MCP 规范修订版 2026-07-28 和 2025-11-25。初始消息决定采用哪个时期：发送 initialize 的客户端会使用 2025 时期的握手，协商后的 protocolVersion 会反映客户端请求的版本（服务端接受 SDK 支持的所有旧版修订：2025-11-25、2025-06-18、2025-03-26、2024-11-05、2024-10-07）；通过 server/discover 探测的客户端会使用 2026-07-28 时期的协议（每个请求都包含 _meta 信封、每个结果都带有 resultType、tools/list 缓存提示包含 ttlMs/cacheScope、每个响应都会标注 serverInfo）。两个时期共用同一进程和同一组工具处理程序。

工具	Pi 对应项
codecarto_init	/codecarto-init
codecarto_open	/codecarto-open
codecarto_vision	/codecarto-vision
codecarto_status	/codecarto-status
codecarto_switch_pipeline	/codecarto-switch-pipeline
codecarto_next	/codecarto-next
codecarto_phase	/codecarto-phase
codecarto_validate	/codecarto-validate
codecarto_complete	/codecarto-complete
codecarto_skill	/codecarto-skill
codecarto_list_skills	/codecarto-list-skills
codecarto_publish	/codecarto-publish
codecarto_library_init	/codecarto-library-init
codecarto_library_list	仅限 MCP 的库列表
codecarto_library_reindex	仅限 MCP 的库重新索引
codecarto_config	/codecarto-config
codecarto_usage	/codecarto-usage
codecarto_dashboard	/codecarto-dashboard
codecarto_guide	/codecarto-guide
codecarto_amend	/codecarto-amend（Pi 会预览要关闭的内容并先征求确认）
codecarto_refresh_scaffold	/codecarto-refresh-scaffold（Pi 会列出文件集并先征求确认）
codecarto_broadside	/codecarto-broadside
codecarto_change	仅限 MCP，实验性：记录工程变更、尝试、证明、评审和验收门禁；绝不会执行任何操作（详情）

每个工作流工具都接受目标代码库的绝对路径 cwd。codecarto_init 需要 force: true 才会覆盖已有的 .codecarto/（而 Pi 会通过交互式确认来处理）。库工具接受显式的绝对路径 library_path，或从 .codecarto/workflow/config.yaml / ~/.codecarto/config.yaml 解析 library.path。codecarto_library_reindex 和 codecarto_library_list 还会报告版本之间 source_repo 不一致的条目——这是 v0.17.0 的发布守卫推出前，slug 冲突留下的结构；修复仍需手动进行，因为拆分条目会更改库格式视为 ABI 的路径。库架构为实验性，在 v2 之前可能发生破坏性变更。

---

Broad-Side（批量侦察）

Broad-Side 是在成本高昂的交互式运行之前执行的低成本全面扫描。它通过 OpenRouter Batch API，针对代码仓库以单轮提示词运行六个分析视角——架构、API 表面、安全、机械缺陷扫描、惯例提取和移植；随后交叉比对结果，生成一份执行摘要报告（synthesis.md）和一份按优先级排列的 P0–P3 工作单（triage.md）。安全和 API 分析视角会检查信任边界通常所在的路径（server/、auth*、middleware/、路由器和处理程序）；如果代码仓库在这些路径下没有代码，则回退为检查所有源文件——估价会按此计费并明确说明。因此，即使某个服务的服务器文件是 src/server.js，或者唯一匹配项是其 SECURITY.md，也仍会接受安全审查。

Broad-Side 的发现是未经验证的初步线索，而非证据。 每个分析视角都只运行一次：不会跨文件追踪，不会进行运行时验证，也不会构建或测试。每条发现都包含一个 file:line 指针，必须由交互式流水线或你本人确认后，才能视为事实。这种分工正是其价值所在：以低于 1 美元的成本进行无人值守扫描，告诉成本高昂的运行该从哪里入手。后续任何环节都不得将 Broad-Side 报告作为来源引用。

它适用于任何 Go、Python、Rust、TypeScript 或 JavaScript 代码仓库——无需初始化工作区；但需要 OpenRouter API 密钥（api_key 参数、OPENROUTER_API_KEY 环境变量，或 .codecarto/broadside/config.yaml 中的 api_key）。系统会根据现有清单文件以及各语言的源文件数量检测语言；如果代码仓库使用其他语言，或清单文件对应的语言没有源文件，则会在估价或发送任何内容之前拒绝运行。文件从工作树读取——包括已跟踪和未跟踪的文件，并应用忽略规则——每次运行都会记录该快照的来源、HEAD，以及工作树是否有未提交更改。由于会上传代码仓库内容，因此会先执行脱敏：名称类似凭据存储的文件（.env*、*.pem、id_rsa*、credentials.json 等）不会提供给任何分析视角；其他文件中符合常见特征的机密信息（私钥块、云服务和 API 密钥、JWT、带引号的密码或令牌赋值、URL 中的密码）会替换为 [REDACTED:<kind>] 标记——安全分析视角仍能看到此处硬编码了凭据，但看不到其值。提交报告会说明脱敏了哪些内容。这是一项采用低误报模式的安全措施，并非机密信息扫描器；在配置中设置 redact_secrets: false 可关闭内容脱敏。

codecarto_broadside {cwd, action: "models"}                   # compare batch models and pricing
codecarto_broadside {cwd, action: "submit", lenses: [...]}    # fire the batches, priced first
codecarto_broadside {cwd, action: "status"}                   # what is in flight
codecarto_broadside {cwd, action: "collect"}                  # poll, save, synthesize, triage
codecarto_broadside {cwd, action: "verify", top: 10}          # read the top findings against the source
codecarto_broadside {cwd, action: "collect", regenerate_post_passes: true}   # rebuild the report and work order from the verdicts

第三个操作 verify 会针对真实源代码检查已收集运行中的顶级缺陷和安全发现——每项发现分别进行一次按同步调用计费的调用，并使用受限于代码仓库的只读工具（read_file、grep、list_dir）；随后写入 verified.md，为每项发现给出判定：已确认（存在可触发的故障，并说明触发条件）、并非缺陷、已丢弃或不明确。在此代码仓库上进行的测量显示，按严重性排列的前十二项发现中，两项是真实缺陷，其余十项则经查看防护逻辑或调用方后被排除；该检查每项仅花费 1 美分，且十二项均与审查者意见一致。请先阅读 verified.md，再阅读 triage.md——并根据 verified.md 生成 triage.md：如果存在判定，综合分析和分诊环节会根据判定进行排序（已确认的优先，已丢弃的移除，并非缺陷的单独列出）；对于已收集但尚未验证的运行，collect 配合 regenerate_post_passes: true（在 Pi 上使用 --regenerate）会重新生成这两份文件。 提交和收集是分开的，因为批处理作业通常需要数十分钟；收集可以恢复，并会接着处理仍在运行的任务（wait_seconds: 0 是默认值，只轮询一次后返回）。同一运行的两次收集——例如重试工具调用、开启第二个会话——不会为综合、分类或截断重试重复付费：每项操作都会在提交前记录到运行状态中；如果客户端已断开，收集就会停止轮询，且不再提交任何内容。提交会根据收集到的文件大小和模型当前的每 Token 定价（缓存 24 小时）计算本次运行的费用，并在估算费用超过 max_cost 时拒绝执行——除非配置或调用另行设置，否则该值为 $1.00；设为 0 则表示不设限——但传入 force: true 可强制执行。这是执行前的估算，并非运行时的停止条件。实际支出会记录在每次运行的 run-meta.json 中。

仓库默认值位于 .codecarto/broadside/config.yaml（model、api_key、default_lenses、max_cost、pricing 覆盖项、lens_models、incremental、retry_truncated、include_synthesis、include_triage、wait_seconds）；显式工具参数始终优先。lens_models 可将各个透镜路由到各自的批处理模型——比起架构图，更强的模型对安全和缺陷发现的影响大得多——每个覆盖项都会像默认模型一样进行定价、能力检查和费用上限限制，并按透镜列出估算费用，避免混合模型的运行在未明确各透镜费用的情况下获批。CodeCartographer 不提供更强模型作为默认值：哪种模型物有所值取决于你的仓库和预算，因此请使用 models 操作比较候选模型并自行选择——单次运行可通过 model 和 lens_models 参数指定（Pi：--model=ID、--lens-model=LENS:ID），也可在 config.yaml 中为整个仓库设置。models 列表仅供参考：OpenRouter 的目录会为某些模型返回 :batch ID，但其 Batch API 随后会拒绝这些 ID（does not have a :batch endpoint），且不会产生费用；目录中没有信息能区分它们，因此该列表会标记本仓库自身提交曾获接受或遭拒的 ID，而被拒绝的透镜会在提交报告中说明原因。codecarto_skill {cwd, name: "broadside"} 会返回已完成运行的阅读指南；与流水线后的技能不同，它不要求流水线已完成。

在 Pi 扩展中，同一运行的命令为 /codecarto-broadside [submit|collect|status|models|verify] [lenses…] [--model=ID] [--lens-model=LENS:ID] [--top=N] [--regenerate]，支持对操作、透镜名称和标志进行 Tab 补全，并会在批处理轮询期间实时显示各透镜的进度。两个使用界面有一处刻意的差异：MCP 无法询问用户，因此在费用超过 max_cost 时会拒绝运行，直到你传入 force；Pi 会显示各透镜的费用明细并征求同意，而你的批准本身就是 force 标志。两个界面都不允许将 API 密钥作为命令参数传入——在斜杠命令中输入的密钥会进入会话记录。

Broad-Side 需要运行时代码，因此触发运行属于可执行界面功能：Pi 和 MCP 支持此功能，纯即插即用模板不支持（模板仅包含阅读指南）。

将运行结果送入流水线的变体是 scout-first。其第一阶段 broadside-scout 会将已完成的运行提炼为 findings/broadside-scout/scout-brief.md——一份简短的线索列表，每条线索都会路由到特定的后续阶段，并附上该阶段应开始查看的源代码位置。六个后续阶段会读取这份简报，并且在验证时必须逐条处理分配给自己的线索：根据源代码确认、说明理由后排除，或继续传递。不得仅凭简报就将任何内容报告为发现。侦察阶段本身从不提交批处理任务，也不产生费用；如果磁盘上没有运行结果，它会写入一份明确标为空的简报，流水线则照常继续。 这种间接处理是有意为之。运行目录带有时间戳，且已加入 Git 忽略列表，因此任何流水线 YAML 都无法将其指定为 required_reads 路径；简报是稳定、可供审阅的产物，阶段契约可以指向它，而将内容提炼成简报的过程，正是判断“哪些内容值得任何人关注”的关键所在。

---

兼容环境

环境	推荐方式
Pi	原生 Pi 扩展——斜杠命令 + 小组件 + 仪表板。
Claude Code / Codex / opencode	MCP 服务。这三者都能顺畅使用 MCP。
Cursor / Windsurf / IDE copilots	支持时使用 MCP 服务；否则使用即插即用模板（.codecarto/GUIDE.md）。
Claude Desktop	MCP 服务。
Aider	即插即用模板——指向 .codecarto/GUIDE.md。
Claude.ai / ChatGPT（网页聊天）	即插即用，手动粘贴文件内容。用于多阶段运行会很繁琐。
基于 API 的 Agent	以编程方式加载文件，传递给模型，再将输出写回。采用即插即用语义。

---

Token 用量和成本

CodeCartographer 的 Token 用量较高——它会在多个阶段反复读取源代码，并生成数千字的结构化输出。请做好相应规划。

模板开销（固定成本）

每次会话都会读取指南、流水线定义、状态和验证协议。每个阶段还会额外读取自身的 SKILL.md 和输出模板。无论代码库大小如何，这部分开销都固定不变：

组件	Token（输入）
每次会话基础开销（GUIDE + pipeline + status + VALIDATE）	~2,600
架构阶段说明	~1,500
缺陷扫描阶段说明（包含 6 个 pass 文件）	~5,000
契约阶段说明	~1,500
协议阶段说明	~1,200
移植阶段说明	~1,200
重新实现规范阶段说明	~1,100
6 阶段运行的模板总开销	~27,000
7 阶段深度审计的模板总开销	~32,000（拆分后的缺陷扫描会额外加载一个 SKILL）

源代码读取（可变成本）

这是主要成本。每个阶段都会读取部分或全部源代码；架构阶段读取最多。粗略估算：每个阶段的 Token 用量约为代码库大小的 1–3 倍。一个含 50k Token 的代码库，在完整流水线运行中可能消耗 100–200k 输入 Token。

输出生成

以下数据来自一次真实的 6 阶段运行（CodeCartographer 分析自身——一个约 14k 词的小型模板）：

阶段	输出大小
架构图	~3,100 Token
缺陷报告	~2,400 Token
行为契约	~4,500 Token
协议与状态	~3,900 Token
移植包	~3,400 Token
重新实现规范	~4,400 Token
输出总量	~21,800 Token

代码库越大，输出也会按比例增加。

成本估算

对于中型代码库（约 100k Token 源代码）：

流水线	预计输入	预计输出	总计
仅架构	~130k	~5k	~135k Token
缺陷扫描（2 阶段）	~260k	~10k	~270k Token
Lite（3 阶段）	~370k	~15k	~385k Token
完整（5 阶段）	~570k	~22k	~592k Token
完整并含审计（6 阶段）	~700k	~27k	~727k Token
完整并含深度审计（7 阶段，默认）	~830k	~32k	~862k Token

按当前 API 定价（Claude Sonnet 的输入约为 $3/M，输出约为 $15/M），对一个含 100k Token 的代码库运行完整的 5 阶段流水线，成本约为 $2–4。更大的代码库成本会线性增长。

减少令牌用量的技巧

• 从 architecture-only 开始，先看看输出质量是否有用，再决定是否执行完整流程。
• 每个阶段使用一个 LLM 会话——每个阶段都会开启一个全新的上下文窗口，因此无需为保留过时上下文付费。
• 对于非常庞大的代码库（源代码超过 500k 个令牌），LLM 无法读取所有内容。它会使用架构图确定优先级，并生成部分结果。status.yaml 中的 open_questions 会显示哪些内容被跳过。
• **lite 流程（3 个阶段）**在理解代码库方面能提供 80% 的价值，且不包含移植专用阶段。
• 除非遇到跨阶段一致性问题，否则不要使用 --llm-steer——重写器每个阶段都会消耗编排器端的令牌。

---

模型兼容性

该工具在设计上与 LLM 无关，但模型选择会同时影响可分析的内容和结果质量。需要考虑两个独立的限制：上下文窗口大小和模型能力。

上下文窗口

每个阶段都在独立会话中运行，因此上下文窗口限制的是每个阶段可读取的源代码量，而非整个流程的总量。扣除模板开销、前序阶段的发现结果和输出生成所需空间后：

阶段	可用于源代码的空间（128k 模型）	可用空间（200k 模型）
架构	~121k	~193k
缺陷扫描	~115k	~187k
契约	~114k	~186k
协议	~115k	~187k
移植	~104k	~176k
重新实现规范	~103k	~175k

按代码库规模划分的实际限制：

代码库	128k 上下文	200k 上下文
<30k 个令牌	所有阶段都能轻松运行	所有阶段都能轻松运行
30–60k 个令牌	可行，但会有一些 PARTIAL 结果	运行轻松
60–100k 个令牌	勉强可行——大量使用 PARTIAL	经优先级排序后可行
>100k 个令牌	不可行	可行，后续阶段可能为 PARTIAL

流程能妥善处理上下文耗尽的情况：各阶段会写入 PARTIAL 验证状态，并在 open_questions 中记录剩余工作。

模型能力

这是更严格的限制。较弱模型在以下任务中的表现下降最快：

1. 证据分类（高风险）——区分 observed fact、strong inference 和 open question，需要准确判断自身结论的确定性。较弱模型会将推断过度归类为事实，并跳过 open question 标记。
2. 缺陷扫描（高风险）——多轮扫描需要特定领域的推理能力（并发、安全性、API 契约）。较弱模型会产生更多误报、漏掉细微错误，并将风格问题过度报告为缺陷。
3. 架构综合（中高风险）——从众多文件中抽象出连贯的分层图，需要高阶推理能力。
4. 遵循结构化输出要求（中等风险）——正确填写模板，包含所有必需部分并保持格式一致。
5. 跨阶段一致性（中等风险）——后续阶段会基于前序发现结果开展工作。架构分析薄弱会导致下游错误累积。

推荐的模型梯队

梯队	示例	推荐流程	备注
前沿模型	Claude Opus 4.6、Claude Sonnet 4.6	Full-with-deep-audit（默认）	对于不超过 ~100k 个令牌的代码库，能提供完整质量；深度审计中的语义分析最能受益于前沿模型的推理能力。
强大的中端模型	Claude Haiku 4.5、GPT-4o	Lite（3 个阶段）	架构和契约分析表现稳健。跳过缺陷扫描——误报率过高。
更小／更快的模型	GPT-4o-mini、Gemini Flash、小型开放权重模型	仅架构分析	可提供尚可的结构概览。多阶段运行会造成明显的质量损失。

如果要测试新模型，请先对一个你已了解的代码库运行 pipeline-architecture-only.yaml，并将输出与你自己的知识进行比较。这样可以快速判断是否能信任该模型执行更深入的阶段。

---

仓库结构

.codecarto/                  # The drop-in template (Markdown + YAML).
  GUIDE.md                   # LLM entry point.
  findings/
    architecture/            # System structure, layers, dependency direction.
    defect-scan/             # Multi-pass defect report with severity and actions.
    contracts/               # User-visible behavior, defaults, acceptance checks.
    protocols/               # Event streams, state machines, persistence formats.
    porting/                 # Reverse-engineering synthesis bundle.
    reimplementation-spec/   # Language-agnostic build spec.
  scratch/                   # Disposable notes plus checkpoints and structured phase handoffs.
  templates/                 # Output structure templates.
  workflow/                  # Pipeline definitions, status, validation, config.
  broadside/                 # Broad-Side batch reconnaissance: config, state, run results.
  closeouts/                 # Per-session closeout files.
  THREAD_LOG.md              # Cross-session summary log.
  dashboard.html             # Generated; gitignored.
core/                        # Pipeline state machine, validators, prompt assembly,
                             # dashboard renderer, usage log, orchestrator config.
extensions/codecarto/        # Pi extension surface (slash commands, widget,
                             # tool gating, dashboard writer + narrator).
mcp-server/                  # MCP server surface (workflow tools + experimental library tools).
tests/                       # Invariant tests catching cross-wrapper drift.
docs/                        # Roadmap, design notes.

应提交的内容

init 写入的 .codecarto/.gitignore 会在所有安装路径中排除生成的发现结果、临时文件、仪表板以及本地用量／叙述缓存。模板文件（工作流定义、技能、输出模板）可以安全提交，方便队友运行自己的分析。

需要了解一个影响：workflow/status.yaml 会被提交，并记录哪些阶段已完成，而这些阶段生成的报告不会提交。因此，队友刚克隆仓库时，可能会看到「已完成 6/7 个阶段」，但却没有相关发现结果。codecarto_status 和 /codecarto-status 会指出此类阶段（「有 N 个已完成阶段的输出文件在磁盘上缺失……」），因此不会让这个缺口悄无声息地存在；仪表板也会标明每个输出文件是否存在。若要分享分析本身，请从工作区的 .codecarto/.gitignore 中删除 findings/… 条目并提交报告——这是每个工作区自行决定的；框架默认仍会忽略这些文件。

---

面向自动化 Agent

1. 加载当前使用的管道 YAML 和 workflow/status.yaml。
2. 选择第一个状态不是 complete 且所有依赖项均为 complete 的阶段。
3. 将该阶段的 skill_path 和 required_reads 提供给 Agent。
4. 将输出写入声明的路径。运行验证。更新状态。
5. 重复以上步骤，直到所有阶段都完成。完成后，将 current_phase 设为 complete。

MCP 服务会直接执行步骤 1–3；Pi 扩展则将其封装为斜杠命令，并提供上述并行子 Agent 运行器。

---

设计原则

• 与大模型无关 — 可与任何能够读取和写入文件的模型配合使用。
• 阶段门控 — 每个会话只处理一个阶段，通过验证后再进入下一阶段。
• 单一事实来源 — status.yaml 跟踪进度，不重复保存状态。
• 证据分类 — 每项发现都标记为观察到的事实、强推断、可移植性隐患、外部行为声明或待解决问题。
• 模板驱动 — 确保不同项目和会话的输出结构一致。
• 即插即用 — 位于仓库内的 .codecarto/ 中。无需符号链接、复制源代码或运行时守护进程。

---

贡献

未来的工程生命周期相关工作，请从产品路线图和面向 Agent 的工程交接文档开始。这些文档介绍的是计划中的功能，而非已发布的功能。

欢迎提交错误报告、功能请求和拉取请求。开发环境设置、分支模型和维护者发布流程请参阅 CONTRIBUTING.md。所有参与者都应遵守行为准则。如有安全问题，请按照 SECURITY.md 中的说明处理，而不要公开提交问题。

许可证

MIT — 详见 LICENSE。