HuginnIndustries/CodeCartographer
GitHub: HuginnIndustries/CodeCartographer
CodeCartographer 是一款基于渐进式蒸馏的代码库逆向分析与重新实现规划工具，为 AI 编程代理提供分阶段、带证据验证的代码理解与移植流水线。
Stars: 1 | Forks: 0
# CodeCartographer
[](https://github.com/HuginnIndustries/CodeCartographer/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.npmjs.com/package/codecartographer-pi)
[](package.json)
```
● 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…
```
## 概览
| 获得的功能 | 所在位置 |
|---|---|
| **分层分析流水线** — 架构 → 缺陷扫描 → 行为契约 → 协议 → 移植 → 重新实现规范 | `.codecarto/` 模板 |
| **阶段之间的验证门** — 输出为 `FAIL` 时无法进入下一阶段 | `core/` 状态机 |
| **三种界面，统一框架** — Pi 扩展（推荐）、MCP 服务器（用于其他编程代理）或直接套用模板（一次性 / 评估） | 这三者共享 `core/` |
| **实时进度组件**，在阶段子代理工作时显示 | Pi 扩展 |
| **HTML 仪表盘** — 将进度、链接、使用情况、叙述汇总在单一文件中 | `.codecarto/dashboard.html` |
| **各阶段 token 追踪** | `/codecarto-usage` |
| **可选的 LLM 引导**，用于引导下一阶段的种子提示词 | `/codecarto-next --llm-steer` |
| **前向综合** — 愿景 + 确认的库规范 → 具备溯源支持的项目计划 | `pipeline-synthesis.yaml` |
从 Pi 或 MCP 发布已完成的重新实现规范，然后运行 `synthesis` 流水线，将产品愿景和明确确认的库条目转化为具备冲突感知能力的 `project-plan.md`，并附带决策级别的溯源记录。
OpenAI Build Week 评审人员：请参阅[新旧范围对比及单命令演示](docs/build-week-2026.md)。
## 安装
1. **Pi 扩展** — 推荐用于交互式操作。提供一流的用户体验。
2. **MCP 服务器** — 适用于 Claude Code、Codex、opencode、Cursor、Claude Desktop 以及任何其他支持 MCP 的代理。
3. **直接套用模板** — 纯 `.codecarto/` Markdown + YAML，适用于一次性评估或任何能够读写文件的 LLM。库和综合工作流在纯直接套用模式下**不可用**；但分析端功能可完全正常使用。
### Pi 扩展（推荐）
[Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) 是一个 TUI 编程代理。CodeCartographer 扩展添加了斜杠命令、实时代理组件以及仪表盘。
```
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 直接指向入口点：
```
pi -e /absolute/path/to/CodeCartographer/extensions/codecarto/index.ts
```
### MCP 服务器（用于其他编程代理）
当你的编程代理不是 Pi 时（例如 Claude Code、Codex、opencode、Cursor、Claude Desktop 或任何其他支持 MCP 的代理），请使用此项。宿主程序驱动对话并运行 LLM；CodeCartographer 提供阶段提示、验证以及实验性的库发布/列表/重建索引操作。
```
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 的代理均不可用的环境中使用。适用于任何能够读写文件的 LLM。
```
cp -r /path/to/CodeCartographer/.codecarto /path/to/your-repo/
```
然后在 LLM 会话中输入：`Read .codecarto/GUIDE.md and begin the analysis.`（阅读 .codecarto/GUIDE.md 并开始分析。）
## 前向综合快速入门
分析过程将代码库转化为可复用的规范。而综合过程则反其道而行之：它将原始的产品愿景与经人工确认的规范结合，生成一份实现就绪的计划，且不丢失溯源信息。
1. 配置包含通过 `/codecarto-publish` 或 MCP `codecarto_publish` 工具发布的规范的库：
# ~/.codecarto/config.yaml 或 .codecarto/workflow/config.yaml
library:
path: /absolute/path/to/codecarto-library
namespace: your-namespace # 单租户库可省略此项
publish_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 文件：
## 渐进式蒸馏与上下文韧性
CodeCartographer 是对代码库进行的一种渐进式、带有证据标记的蒸馏过程。它不需要单一上下文窗口来记住整个调查过程。相反，每个阶段都会将大量源码证据转化为更小、更针对特定任务的产出物，供下一阶段读取：
```
source code
→ architecture map
→ behavioral contracts + protocols + defect findings
→ porting bundle
→ reimplementation spec
```
这是刻意的蒸馏，而非偶然的聊天摘要。每个产出物都遵循特定模板，保留证据等级和已知的未知信息，并且必须通过验证，然后才能成为下游阶段的输入。
### 当对话上下文被压缩时会发生什么？
文件系统，而非对话本身，才是运行过程的持久记忆：
- 每个阶段都会获得一个全新的上下文窗口。在 Pi 扩展中，它作为独立的阶段子代理运行；MCP 和直接套用的宿主程序也应采用每个阶段一个会话的模式。
- 已完成的发现存放在 `.codecarto/findings/` 下。后续阶段会重新读取当前流水线声明的特定上游产出物，而不是依赖对话回忆。
- `workflow/status.yaml` 记录进度、最终态的 `open_questions`、流水线内的 `carry_forward`，以及用于存放可选测试、修订、增量、决策和完成后重跑的独立 `post_pipeline` 积压任务。阶段代理在 `.codecarto/scratch/handoffs/
.yaml` 中提出更改建议；完成时会在锁定状态下验证并应用它们，带有宿主时间戳、单一的规范收尾以及幂等的 `THREAD_LOG.md` 记录。
- Pi 阶段记录由文件支持，并可通过 `/resume`、`/tree` 和 `/export` 访问，即使当前活动的模型上下文已被压缩。
- 对于独立的 Pi 阶段会话，压缩使用具备阶段感知能力的连续摘要，明确保留证据、检查过的文件、输出进度、悬而未决的问题以及验证缺失。生成的摘要也会被原子化地检查点保存到 `.codecarto/scratch/checkpoints/.md`。
- Pi 会在本地使用数据中记录成功、失败和中断的压缩，及其触发器（`threshold`、`overflow` 或 `manual`），并在组件、`/codecarto-usage`、完成摘要和仪表盘中显示总计数据。
因此，压缩——甚至替换——编排器会话都不会抹除流水线的进度。新的会话可以从磁盘重构相关状态并继续执行。
## 各阶段生成的产出物
| 产出物 | 描述 |
|---|---|
| **架构图** | 层级、依赖方向、公共接口、运行时生命周期、并发模型 |
| **缺陷报告** | 多轮扫描，查找逻辑错误、安全问题、并发缺陷、API 违规 |
| **缺陷修复追踪器** | 将每次修复、延后或接受映射回缺陷报告的修复日志 |
| **行为契约** | 逐项特性的行为，包含默认值、错误处理和验收测试 |
| **协议与状态** | 事件流、状态机、持久化格式、兼容性隐患 |
| **移植包** | 将所有内容综合为面向移植的视图，并带有优先级排名 |
| **重新实现规范** | 语言无关的构建计划，包含模块、验收场景和已知的未知信息 |
每项发现都标记了证据等级：`observed fact`（观察到的事实）、`strong inference`（强推断）、`portability hazard`（可移植性隐患）或 `open question`（开放问题）。每个阶段的输出都会在流水线推进之前，根据明确的完成标准进行验证。
## 流水线变体
默认设置为 7 阶段运行，它将缺陷扫描拆分为前期的机械性检查和后期的语义分析——随后重新实现阶段会基于完整的契约和协议上下文，围绕这些缺陷进行设计。如果你想要更轻量的流程，可以缩减规模：
| 变体 | 阶段数 | 适用场景 |
|---|---|---|
| **带深度审计的完整流程**（默认） | 7 | 包含拆分缺陷扫描的完整分析；重新实现基于具备契约/协议感知的缺陷发现 |
| **带审计的完整流程** | 6 | 单次前期缺陷扫描；当缺陷主要是机械性问题时，比深度变体成本更低 |
| **完整流程** | 5 | 不进行任何缺陷扫描的移植或重新实现 |
| **缺陷扫描** | 2 | 用于暴露潜在问题的维护审计 |
| **精简版** | 3 | 你只需要了解行为，而不需要移植计划 |
| **仅架构** | 1 | 快速进行结构概述 |
| **综合** | 4 | 将产品愿景和确认过的库规范转化为具备溯源支持的实现计划 |
通过编辑 `workflow/status.yaml` 的 `pipeline:` 字段设置当前流水线，或将其作为 `/codecarto-init` 的参数传入。
**在磁盘上：**
| 变体 | 流水线文件 |
|---|---|
| 带深度审计的完整流程（**默认**） | `workflow/pipeline-full-with-deep-audit.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 与压缩遥测数据 + 各阶段细分
- 带有会话文件链接的活动时间轴
- 按来源阶段分组的悬而未决的问题汇总
- 结项列表（按时间倒序），带有相对路径链接
无需 JavaScript。无外部资产。通过 `prefers-color-scheme` 支持浅色/深色模式。支持直接从 `file://` 打开。
**可选的叙述性摘要。** `/codecarto-dashboard --narrate` 会以单次会话的形式运行编排器的模型，撰写一份 200-400 字的执行摘要，并引用近期结项中的具体发现。缓存在 `.codecarto/.dashboard-narration.local.md` 中，并在确定性重渲染中保留，同时附有“(N runs since)”（距上次运行 N 次）的陈旧度提示。
## Pi 扩展功能
除了斜杠命令外，Pi 扩展还提供了以下附加功能：
编辑器上方的**实时代理组件**，显示工具调用次数、token 使用量、已用时间以及当前活动。
```
● CodeCartographer
└─ ⠹ architecture phase ⟳ 3 · 5 tool uses · 12.3k tokens · 1m32s
⎿ reading…
```
**基于文件的阶段会话。** 阶段记录会持久化到编排器使用的同一 Pi 会话目录中，因此 `/resume`、`/tree` 和 `/export` 可以将它们作为一等公民会话进行浏览。每个会话显示为 `CodeCartographer phase: `，并可追溯到编排器会话的沿袭。
**具备阶段感知的压缩与检查点。** 只有名为 `CodeCartographer phase: ` 的独立会话才会使用专门的压缩提示词。它会保留阶段目标、证据、检查过的文件、输出进度、悬而未决的问题和验证缺失，然后将生成的摘要写入 `.codecarto/scratch/checkpoints/.md`。编排器和无关的 Pi 会话则保留正常的宿主压缩机制。
**编排器记录阶段完成摘要。** 当一个阶段结束时，一个 Markdown 结项块会通过 `pi.sendMessage(...)` 追加到编排器的会话中。在 TUI 回看记录中可见；在你发送下一条消息时，可作为上下文供编排器的 LLM 使用。不会自动触发 —— 控制权完全在你手中。
**可选的 LLM 引导的种子提示词。** 在 `.codecarto/workflow/config.yaml` 中设置 `orchestrator.llm_steer_next_phase: true`（或者在每次调用时传入 `--llm-steer`），编排器的 LLM 就会重写下一阶段的种子提示词，以突出相关的先前发现。默认关闭 —— 会额外消耗编排器端的 token，需主动启用。重写后的提示词会注入到编排器记录中，以便你审查重写器选择强调的内容。
**各阶段使用量追踪。** 每次阶段运行都会追加到 `.codecarto/workflow/.usage.local.yaml` 中。`/codecarto-usage` 会报告累积和各阶段的 token、运行时、工具调用以及压缩总计，包括触发条件（阈值/溢出/手动）以及成功/失败/中断的结果。
**工具拦截。** `bash` 被完全阻止；`edit` 和 `write` 被限制在 `.codecarto/` 目录内，并在配置后允许访问经过标记验证的 CodeCartographer 库。同样的规则也适用于阶段子代理。
### 斜杠命令
| 命令 | 用途 |
|---|---|
| `/codecarto-init [variant]` | 将 `.codecarto/` 复制到当前仓库中，选择流水线变体 |
| `/codecarto-open` | 在新的 Pi 会话中激活现有的 `.codecarto/` 工作区，而不重置持久状态 |
| `/codecarto-status` | 当前阶段、进度、悬而未决的问题 |
| `/codecarto-next [--auto [--strict]] [--llm-steer \| --no-llm-steer]` | 将下一个符合条件的阶段作为子代理启动。`--auto` 会端到端遍历整个流水线（自动验证 + 自动完成 + 推进）；`--strict` 会将 `PASS WITH GAPS`（带缺陷通过）规则的行为从“推进”改为“暂停”。 |
| `/codecarto-phase ` | 强制执行特定阶段，甚至可以乱序执行 |
| `/codecarto-validate [phase]` | 根据完成标准验证阶段输出 |
| `/codecarto-complete [phase]` | 验证并原子化地应用阶段移交、规范状态、结项和日志记录 |
| `/codecarto-skill ` | 在所有阶段完成后运行流水线后置技能 |
| `/codecarto-publish` | 在审查明确的确认预览后，将重新实现规范发布到配置的库中 |
| `/codecarto-usage` | 累积和各阶段的 token 使用量 |
| `/codecarto-dashboard [--narrate]` | 重新生成 `.codecarto/dashboard.html`；`--narrate` 用于生成 LLM 执行摘要 |
### 端到端自动模式 (0.8.0+)
`/codecarto-next --auto` 无需人工干预即可遍历整个流水线。该循环会启动下一个符合条件的阶段，自动验证输出，自动标记为完成，并不断推进，直到流水线结束——或者直到有事物停止它（`FAIL` / `MISSING` 验证、子代理错误或 `ctx.signal` 中止）。在此过程中，编排器的 TUI 保持响应；各阶段的摘要会像往常一样出现在记录中，最后的 `codecarto-auto-summary` 块会报告结果，包含累积的 token 数、墙上时间，以及如果运行提前停止时的恢复提示。
### 版本历史（Pi 编排）
当前的并行子代理设计在 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](https://modelcontextprotocol.io) 服务器。MCP 路径返回供宿主程序分发的提示文本，且本身从不运行子代理，因此 Pi 独有的编排功能（子代理、实时组件、仪表盘、使用量追踪）不适用——但阶段提示和验证与 Pi 路径在字节上是完全一致的，因为两者都引入了相同的 `core/`。v0.9.0 还公开了实验性的库工具，以便支持 MCP 的宿主程序可以发布、列出并重建可重用的 `reimplementation-spec.md` 产出物的索引。
通过 `@modelcontextprotocol/sdk` ≥ 1.29.0 实现了 MCP 规范修订版 [`2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25)。协商后的 `protocolVersion` 反映了连接客户端请求的任何版本；服务器接受 SDK 支持的每一个修订版（目前为 `2025-11-25`、`2025-06-18`、`2025-03-26`、`2024-11-05`、`2024-10-07`）。
| 工具 | Pi 等效项 |
|---|---|
| `codecarto_init` | `/codecarto-init` |
| `codecarto_status` | `/codecarto-status` |
| `codecarto_next` | `/codecarto-next` |
| `codecarto_phase` | `/codecarto-phase` |
| `codecarto_validate` | `/codecarto-validate` |
| `codecarto_complete` | `/codecarto-complete` |
| `codecarto_skill` | `/codecarto-skill` |
| `codecarto_publish` | 仅限 MCP 的库发布 |
| `codecarto_library_list` | 仅限 MCP 的库列表 |
| `codecarto_library_reindex` | 仅限 MCP 的库索引重建 |
每个工作流工具都接受目标仓库的绝对路径 `cwd`。`codecarto_init` 需要 `force: true` 才能覆盖现有的 `.codecarto/`（取代了 Pi 的交互式确认）。库工具接受显式的绝对路径 `library_path`，或者从 `.codecarto/workflow/config.yaml` / `~/.codecarto/config.yaml` 解析 `library.path`。库 schema 是实验性的，在 v2 之前可能会发生重大变更。
## 兼容的环境
| 环境 | 推荐界面 |
|---|---|
| **Pi** | 原生 Pi 扩展 —— 斜杠命令 + 组件 + 仪表盘。 |
| **Claude Code / Codex / opencode** | MCP 服务器。这三者都能完美兼容 MCP。 |
| **Cursor / Windsurf / IDE 副驾驶** | 如果支持，则使用 MCP 服务器；否则使用直接套用模板（`.codecarto/GUIDE.md`）。 |
| **Claude Desktop** | MCP 服务器。 |
| **Aider** | 直接套用模板 —— 指向 `.codecarto/GUIDE.md`。 |
| **Claude.ai / ChatGPT（网页聊天）** | 直接套用模板，需手动粘贴文件内容。对于多阶段运行来说很繁琐。 |
| **基于 API 的代理** | 以编程方式加载文件，传递给模型，并将输出写回。采用直接套用的运行机制。 |
## Token 使用量与成本
### 模板开销（固定成本）
| 组件 | Tokens（输入） |
|---|---|
| 每个会话的基准（GUIDE + pipeline + status + VALIDATE） | ~2,600 |
| 架构阶段说明 | ~1,500 |
| 缺陷扫描阶段说明（包含 6 个检查点文件） | ~5,000 |
| 契约阶段说明 | ~1,500 |
| 协议阶段说明 | ~1,200 |
| 移植阶段说明 | ~1,200 |
| 重新实现规范阶段说明 | ~1,100 |
| **6 阶段运行的模板总开销** | **~27,000** |
| **7 阶段深度审计的模板总开销** | **~32,000**（拆分的缺陷扫描会额外增加一次 SKILL 加载） |
### 源代码阅读（可变成本）
### 输出生成
来自一次真实的 6 阶段运行（CodeCartographer 对自身进行分析 —— 一个约 1.4 万字的小型模板）：
| 阶段 | 输出大小 |
|---|---|
| 架构图 | ~3,100 tokens |
| 缺陷报告 | ~2,400 tokens |
| 行为契约 | ~4,500 tokens |
| 协议与状态 | ~3,900 tokens |
| 移植包 | ~3,400 tokens |
| 重新实现规范 | ~4,400 tokens |
| **总输出** | **~21,800 tokens** |
代码库越大，生成的输出也会按比例增大。
### 成本估算
对于中型代码库（约 10 万 token 的源码）：
| 流水线 | 预计输入 | 预计输出 | 总计 |
|---|---|---|---|
| 仅架构 | ~130k | ~5k | ~135k tokens |
| 缺陷扫描（2 阶段） | ~260k | ~10k | ~270k tokens |
| 精简版（3 阶段） | ~370k | ~15k | ~385k tokens |
| 完整流程（5 阶段） | ~570k | ~22k | ~592k tokens |
| 带审计的完整流程（6 阶段） | ~700k | ~27k | ~727k tokens |
| 带深度审计的完整流程（7 阶段，默认） | ~830k | ~32k | ~862k tokens |
按照当前的 API 定价（对于 Claude Sonnet，输入约为 $3/M，输出约为 $15/M），在 10 万 token 的代码库上运行一次完整的 5 阶段分析大约花费 **$2–4**。更大的代码库会呈线性增加成本。
### 减少 Token 使用量的技巧
- **从 `architecture-only` 开始**，在进行完整运行之前，先看看输出质量是否有用。
- **每个阶段一个 LLM 会话** —— 每个阶段都会获得一个全新的上下文窗口，因此你无需为携带陈旧上下文付费。
- **对于非常大的代码库**（超过 50 万 token 的源码），无论如何 LLM 都无法阅读所有内容。它会利用架构图进行优先级排序，并生成部分结果。`status.yaml` 中的 `open_questions` 会显示被跳过的部分。
- **`lite` 流水线（3 个阶段）能带来 80% 的价值**，非常适合无需特定移植阶段即可了解代码库的情况。
- **跳过 `--llm-steer`**，除非你遇到了跨阶段连贯性问题 —— 因为重写器会在每个阶段消耗编排器端的 token。
## 模型兼容性
在设计上不绑定特定的 LLM，但模型的选择既会影响你能分析的内容，也会影响结果的好坏。这受制于两个独立的因素：**上下文窗口大小** 和 **模型能力**。
### 上下文窗口
每个阶段都在其独立的会话中运行，因此上下文窗口限制的是每个阶段可读取的源代码数量——而不是整个流水线的总量。在扣除模板开销、前置阶段发现和输出生成之后：
| 阶段 | 可用于源码（128k 模型） | 可用空间（200k 模型） |
|---|---|---|
| 架构 | ~121k | ~193k |
| 缺陷扫描 | ~115k | ~187k |
| 契约 | ~114k | ~186k |
| 协议 | ~115k | ~187k |
| 移植 | ~104k | ~176k |
| 重新实现规范 | ~103k | ~175k |
根据代码库大小的实际限制：
| 代码库 | 128k 上下文 | 200k 上下文 |
|---|---|---|
| <30k tokens | 所有阶段都很轻松 | 所有阶段都很轻松 |
| 30–60k tokens | 可行，部分出现 `PARTIAL` 结果 | 轻松 |
| 60–100k tokens | 处于边缘 —— 大量使用 `PARTIAL` | 通过优先级排序即可行 |
| >100k tokens | 不可行 | 可行，后期阶段可能为 `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 | 带深度审计的完整流程（默认） | 对于最高可达 ~100k token 的代码库提供全面质量保障；深度审计的语义检查阶段最能受益于前沿推理能力。 |
| **强大中端** | Claude Haiku 4.5, GPT-4o | 精简版（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.
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.
```
`.codecarto/.gitignore` 排除了生成的发现结果、草稿文件、仪表盘以及本地使用量/叙述缓存。模板文件（工作流定义、技能、输出模板）可以安全地提交到版本库，以便团队成员可以运行他们自己的分析。
## 面向自动化代理
1. 加载当前活动的流水线 YAML 和 `workflow/status.yaml`。
2. 选择第一个状态不为 `complete` 且其所有依赖项状态均为 `complete` 的阶段。
3. 将该阶段的 `skill_path` 和 `required_reads` 提供给代理。
4. 将输出写入声明的路径中。运行验证。更新状态。
5. 重复上述步骤，直到所有阶段完成。完成后将 `current_phase` 设置为 `complete`。
MCP 服务器会直接执行第 1-3 步；而 Pi 扩展会将它们包装为斜杠命令，并加上前文所述的并行子代理运行器。
## 设计原则
- **不绑定特定 LLM** —— 可与任何能读写文件的模型配合使用。
- **阶段门控** —— 每个会话一个阶段，通过验证后才能推进。
- **单一事实来源** —— `status.yaml` 追踪进度；没有重复的状态。
- **证据分类** —— 每一项发现都标记为观察到的事实、强推断、可移植性隐患或开放问题。
- **模板驱动** —— 在不同项目和会话中保持一致的输出结构。
- **直接套用** —— 作为 `.codecarto/` 存在于你的代码库中。无需符号链接，无需复制源代码，也无需运行时守护进程。
## 许可证
MIT —— 详见 [LICENSE](LICENSE)。标签：MITM代理, 暗色界面, 自动化攻击, 防御加固