codecartographer

CodeCartographer 是一个框架，用于借助 AI 编码智能体理解陌生的代码库，并产出一份经过验证、与语言无关的重实现规范。它以 Pi 扩展、MCP 服务器或即插即用的 `.codecarto/` Markdown 与 YAML 模板文件形式分发。 工作原理：这里的“代码”是 `.codecarto/` 内结构化的 Markdown 加 YAML。`GUIDE.md` 是 LLM 的入口点，`workflow/pipeline.yaml` 定义各阶段及其依赖关系，`workflow/status.yaml` 保存每个项目的可变状态，`workflow/VALIDATE.md` 描述验证协议。各阶段构成一个有向无环图（DAG）——契约与协议可在架构阶段之后并行运行，移植阶段等待两者完成，重实现规范排在最后。宿主读取当前激活的流水线，找到依赖已全部完成的下一阶段，将该阶段的指令交给 LLM，验证输出，并推进状态。 证据与验证：每个阶段都会在 `.codecarto/findings/` 下写入一个更小、基于模板、带证据标签的产物，后续阶段会重新读取它们所需的特定上游文件。发现结果被标记为观察事实、强推断、可移植性风险、外部行为主张或开放问题。每个阶段的输出都以一个 `## Validation` 表格结尾，将每项完成标准标记为 PASS、PARTIAL 或 FAIL 并附上证据；验证过程会解析该表格，交叉核对证据与行动的配对以及声明的次级输出，若出现 FAIL、缺失输出或无法读取的判定，则拒绝推进。 产出的产物包括架构图、缺陷报告、缺陷修复跟踪表、行为契约、协议与状态、移植包，以及最终的重实现规范，其中包含模块、验收场景和已知未知项。 流水线变体：默认是 7 阶段深度审计运行，将缺陷扫描拆分为机械扫描与语义扫描两遍。其他变体包括 scout-first（8 阶段）、full-with-audit（6 阶段）、full（5 阶段）、defect scan（2 阶段）、lite（3 阶段）、architecture-only（1 阶段）和 synthesis（4 阶段）。变体可以就地切换，而不会删除发现结果或进度。 上下文韧性：持久记忆是文件系统，而不是对话。每个阶段都获得全新的上下文窗口；已完成的发现结果保存在磁盘上；`status.yaml` 记录进度、开放问题、结转事项以及流水线后的待办清单。Pi 的阶段记录由文件支撑，并可通过 `/resume`、`/tree` 和 `/export` 继续使用。阶段感知的压缩摘要会作为检查点保存在 `.codecarto/scratch/checkpoints/` 下。README 指出，阶段内的上下文压力是被限制的，而非被消除的。 界面与功能：Pi 扩展添加了斜杠命令、实时智能体小组件、由文件支撑的阶段会话、阶段完成摘要、可选的由 LLM 引导的种子提示、按阶段的使用量跟踪，以及工具拦截（bash 被阻止；edit/write 被限制在 `.codecarto/` 内）。MCP 服务器向其他支持 MCP 的智能体暴露阶段提示、验证以及实验性的库发布/列出/重建索引操作。一个单文件 HTML 仪表盘汇总进度、链接、使用量以及可选的叙述性摘要。前向综合将产品愿景与经人工确认的库规范结合为一份有来源依据的项目计划，并在合并或最终确定之前通过运行时预检要求明确的人工确认。