CodeDebrief

align="center"> <img src/assets/codedief-wordmark.svg"CodeDebrief" width="420"> </p> <p align="center"> >基于源码的工作流图表，适用于编码代理和代码。</strong> </p> <p align="center"> <a href="https://pypi.org/project/codedebrief/"><img alt="PyPI" src="https://img.shields.io/pypi/v/codedebrief"></a> <a href="https://pypi.org/project/codedebrief/"><img alt="" src="https://.io/pypi/pyversionsebrief"></a> <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/ferdinandobons/CodeDebrief"></a> <img altCP first" src://img.shields.io/badge/MCP--first-local--6b8cff"> > <p align=" <a href="ferdinandobons/CodeDebrief</a> a href="#quick-start开始</a> · <a href="#codingflow">代理工作流</a> · <a href="#manual-viewer">手动查看器</a> <a href="CHANGELOG.md">更新日志</</p> CodeDebrief 将本地代码库工作流图表，供编码代理检查、渲染、翻译和解释。它静态地映射入口点、决策、内部调用、返回、异常和结果，然后由，这样视觉解释就基于可重用的工件，而不是努力重建。 分析器、工件、查看器和 MCP 服务器都是本地优先的，不需要 LLM 提供商密钥。CodeDebrief 不是文档生成器、错误查找器、通用图数据库或 LLM 丰富服务；它是用于理解代码路径如何实际连接的工作流导航层。  示例输出：从本地 CodeDebrief 工件生成的紧凑表示层。规范的工作流可视化默认情况下是垂直的；当用户明确要求紧凑的概览时，会使用水平图表。 > 状态：预 1.0 alpha。模型已版本化，但模式和 MCP 有效载荷可能在 1.0 之前演变。 > 最新版本：[v0.17.0](https://github.com/ferdinandobons/CodeDebrief/releases/tag/v0.17.0). ## 快速开始 CodeDebrief 需要 Python 3.10 或更高版本。使用 `uv` 从 PyPI 安装： ```bash uv tool install codedebrief codedebrief setup claude ``` 将 `claude` 替换为 `codex`、`gemini` 或 `cursor` 以支持另一个代理界面。 要分析选定的文件夹，同时在当前项目根目录中保留 `codedebrief-out`，请在设置期间传递它们： ```bash codedebrief setup claude --source backend/ frontend/ ``` 对于多仓库工作区，创建一个文件夹来保存 CodeDebrief 配置和工件，然后将 `--source` 指向仓库： ```bash mkdir pipeline-map cd pipeline-map codedebrief setup claude --source ../ingest-service ../transform-service ../warehouse-ui ``` 作用域大小很重要。 将 CodeDebrief 指向整个仓库或许多大文件夹可能会显著增加 `setup`、`update` 和 MCP 响应时间，因为有更多文件需要哈希、解析、链接和搜索。 请选择仍然包含您要代理解释的工作流的最小源根。 MCP 响应受 `token_budget` 限制。 如果代理传递显式预算，CodeDebrief 会遵守它。 对于使用默认预算的广泛 `agent_context` 请求，CodeDebrief 会在大型项目上自动增加有效预算，以便第一个切片有足够的空间，而无需强制代理重试并使用更大的请求。 设置后，提出普通问题： ```text 显示我checkout工作流。 哪些分支处理了支付失败？ 哪些工作流受此文件影响？ 此状态在哪里处理？ 将此工作流扩展一个级别更深。 ``` 用于手动探索： ```bash codedebrief view ``` `setup` 默认情况下将 CodeDebrief 所需的配置和工件保存在 `codedebrief-out/` 中： ```text codedebrief-out/ ├── codedebrief.toml 可选的项目配置，由 setup 创建 ├── codedebrief.html 本地交互式全项目查看器 ├── codedebrief.md 可审查的 Mermaid 流程图 ├── codedebrief.json MCP、CI、脚本和查看器的规范模型 ├── codedebrief.hash.json 模型哈希边车，用于更快的 MCP 冷启动 └── codedebrief.errors.jsonl 保存的 CLI/MCP 诊断信息，当出现错误时 ``` 提供者所需的文件仍保留在客户端期望的位置，例如 `.mcp.json`、`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`.cursor/rules/codedebrief.mdc` 和代理技能目录。 用于开发期间的显式刷新： ```bash codedebrief update codedebrief validate --check-sync ``` 默认 CLI 输出故意紧凑。 在需要详细进度和文件路径时，将 `--verbose` 添加到 `setup`、`update`、`validate` 或 `doctor` 中。 要检查失败的 CLI/MCP 操作的保存的本地错误： ```bash codedebrief doctor --errors codedebrief doctor --errors --clear ``` 要从当前项目文件夹中删除 CodeDebrief： ```bash codedebrief clear ``` `clear` 删除 `codedebrief-out/`、遗留根目录 `codedebrief.toml`、`.codedebriefignore`、已安装的 CodeDebrief 技能、MCP 服务器条目和托管指令块。 它默认请求确认； 在脚本中使用 `codedebrief clear --yes`。 要安装固定的 GitHub 版本： ```bash uv tool install "git+https://github.com/ferdinandobons/CodeDebrief.git@v0.17.0" ``` 或者从源代码检出安装： ```bash git clone https://github.com/ferdinandobons/CodeDebrief.git codedebrief cd codedebruv tool install . ``` ## 为什么存在 编码代理可以从原始源代码重建工作流，但通常这种重建依赖于它执行的搜索、选择的 文件和具有的上下文。 重复此过程很慢，并且不太明显的分支或跨文件路径可能会被遗漏。 CodeDebrief 在代理解释任何内容之前创建了一个可重用的导航层： - 入口点、决策、分支、调用、结果和源范围； - 领域概念，例如状态、角色、权限、枚举和功能标志； - 更改的文件、符号、流程和依赖路径的影响上下文； -稳定图表哈希的规范视觉切片； - 可选的语言友好标签，作为分析器事实的表示层导出。 ## 适用场景Debrief 不维护的项目文档。 文档应捕获架构、变性、约定知识以及做出重要CodeDebr一个更快、：在集思、调试、计划审查影响时，检查代码中编码。 使用它来- 按需可视化工作流的某个聚焦- 跟随决策调用跨文件； - 检查受文件、符号更改影响的工作流 为编码代理提供一个共享的结构切片，以便其立即推理。 文档随时间推移解释系统。 CodeDebrief 在您需要推理当前源代码时提供按需的视觉切片。 编写的解释或都是分析器生成的流程图的表示层，而不是本身的源代码。 生成的代理指令将 CodeDebrief 工件视为已完成的工作流相关更改最终确定或提交 `codedebrief update` 和 `codedief validate --以便、Markdown 摘要codedebrief view` 使用当前图表。 ## 可以验证的内容 返回的_slice` 可以 - 模型的源范围； -式决策、分支和结果； -、被调用者和的调用上下文； token 预算、模糊性、过时工不支持的功能引起的不完整性； - 用于扩展切片、跟踪路径或打开相关可视化的稳定句柄。 这些信号使源级模型可检查。 它们不能证明业务正确性或运行时行为。 ## 映射优先，然后解释 一旦 `setup` 配置了项目 MCP 服务器和代理指令的代理应该使用 MCP_context` 启动问题。 代理在决定更多源更深的切片跟踪之前接收到的 `workflow_slicetext 显示可视化工作用源代码基础图解释此代码路径。 哪些工作流受此更改影响？ 此处理？ 在该 中扩展省略的分支。 重写为纯英语。 ``` 解释流程图，但器创建底层地图 设置 支持的目标： ```bash codedief setup codecodedebrief setup claude codedebrief setup claude --/ frontend/ codedief setup claude ../ --source backend-api codedeb setup claude-map --source ../ ../repo-b rief setup cursor --full ``` 所选写入哪些文件： | 目标 | 文件 | --- `codex`AGENTS.md`、` .agents/skills/cief/SK`、项目 MCP 配置 `claude `CLAUDE、`.claude/skills/codedebrief/SKILL.md` MCP 配置 | |` | `.md`、/skills/crief/SK`、`.gem.json` MCP 配置 `cursor` |/rules/codedief.mdc` MCP 配置 | `target>` 仅的文件。 为配置的代理界面分别运行它。 ` 在需要时创建ebrief-outebrief.toml安装所选的代理指令文件，安装支持的提供程序本地 CodeDebrief 技能，注册项目范围的 MCP（如果支持），生成初始工件，运行 `doctor`，并验证结果。 使用 `--source` 在初始工件生成开始之前设置 `source_roots`。 在 Windows可能，请运行编码代理运行 `setup`您从 WSLsetup` 进入/c/...` 项目Debrief 编 MCP 配置文件，通过.exe`，并使用 `--cd < `bash "codedebr ."` Windows 原生代理收到原始 WSL命令目标。 ini` 目标 CLI / Ant 约定：`.md` 提供项目上下文，`.gemini/skodedebrKILL.md`程序本地工作流`.gemini` 注册项目范围的 CodeDebrief MCP## 代理工作对于自然语言代理应该从 MCP_context` 开始。 _context` 返回一个`， - 规范和任务类型； 和支持流程； 序的源代码基础步骤； - 决策分支、值； - 调用者、被调用解析的调用上下文 相关状态类概念逻辑； -可以引用的源- `snapshot_slice` 和 `codedeb view` 的视觉句柄； - 由 token 预算、模糊性时工件或引起的不完整性 用于扩展、路径解释和的后续工具。 当用户请求可视化时，代理应该首先渲染 CodeDebr的确定性 M视化：. 仅当联渲染 Mermaid精确渲染 `.presentation.canonical_visual.diagram`。 2. 如果客户端无法内联渲染 Mermaid，请使用 `snapshot_slice` 并设置 `include_svg=false`，并在文本之前提供返回的 `.mmd` 或 Mermaid Markdown 工件。 除非用户请求原始或可复制的 Mermaid，否则不要粘贴ermaid 代码块作为主要可。 这些生成的文件旨在使用最佳的打开，例如在打开 Markdown 工 Markdown 或览支持。 仅当用户明确要求 SVG 或本地检查时，才使用 SVG 快照工件。 它们不是规范的聊天可。 模型可以选择，但显示块必须来自 CodeDeb 有效载荷可视化之后包括用编写的简短高级流程，源自有序选定的流程、领域逻辑和 该书面流程快乐路径，并仅包含请求所需的分支。 答案还应说明边界摘要，可以 如果用户想要更性的视图可以用用户的语言重写标签和书面流程，作为表示层，保留源锚点，而不添加事实。 接口 主要 MCP 工具： 工具 | 目的 | | --- | --- | | `agent_context` | 自然语言问题和更改代码上下文的默认。 | | `` | 从稳定的柄加宽或工作流切片| `workflow | 在流程、符号或概念之间跟踪路径。 | | `` | 为性视觉。 | | ` | 用、决策、调用锚点。 | |_node` |边缘和源上下文流程图节点。 `explain_edge 用源上下文解释模的边缘| `validate_artifacts` | 检查生成的性和可选的 JSON/Markdown 同步。 | | `update_codedebrief` | 从本地源代码刷新 JSON、Markdown 和 HTML 工件。 | 使用 `codedebrief view` 进行手动 UI。 CLI 故意保持小：`setup`、`、`view`、`doctor`、`clear` 和 `mcp` 生成的工| 文件 | 提交 目的 | | --- | --- | | `codedebrief.json` | 是 | MCP、CI、查看器使用的规范 | | `rief.md` | 生成的检查包含 M图。 它项目文档品。 | |ebriefl` | 通常失败的 CLI/MCP 操作的追加信息。 使用rief doctor 检查它| `codedeb.html` | | 从模型生成的式查看器当 CodeDebrief 是项目工作流提交 `codedebrief.json`codedebr。 `codedief validate --` 验证 JSON 与当前源代码匹配，以及 `codedeb.md` 是否渲染。 当器时，请在本地重新生成 HTMLcodedebrief doctor` 还会报告的 `logicchart` MCP 服务器配置，这些旧安装。影响的代理重新运行 `codedebrtarget>`使用项目范围的 `codedebrief`替换它们。 rieferrors` 显示 `codedebrief-outrief.errors.jsonl` 中最近诊断信息； 在后，使用 `rief doctor --errors --clear`。 rief` 报告状况。 其调用解析率基于仅项目调用：确定性运行时、标准库、DOM/浏览器和动态接收器调用分别计为 `runtime_or_dynamic`，因此它们不会像未解析的工作流边缘一样显示。 ## 团队工作流 一个简单的共享工作流1. 在运行 `ief setup <2.codedebr 和 `codedebrief.md`。 队友拉取相同的源代码。 4. 在流的源路由、配置指令更改后，在或提交之前ebrief 和 `coded validate --。 通常，器在本地，而不是提交。 ## 手动查看器 ebrief 为人类打开完整的交互式流程图。 这是广泛探索的官方手动体验： ```ebr codedebr --render-only ``` rief 手器显示交互图](odedebr-preview.png) 视图：用于探索文件、和连接的工作流流程的交互式浏览器。 当您需要检查整个项目图作用域、比较或视觉调用者和时，请使用。 当代理的 `workflow 回答有界问题使用 MCP 领域逻辑rief 聚合领域概念- 枚举- 状态和生命周期状态； - 权限； - 功能标志； - 处理的值和对它们的决策分支agent_context` 包括返回的 `workflow_slice` 中的相关领域逻辑，链接到流程、节点范围、快照和查看器目标。 值匹配使用建模的代码事实，包括 `PAID` 的 `Status.PAID` 等基于后缀的匹配。 ## 支持的代码 CodeDebrief 目前支持提取 11 种语言的代码控制流： | 语言 | 当前覆盖范围 | | --- | --- | | Python (`.py`) | AST 分析器，包含函数、方法、决策、循环、调用、返回、异常、测试、枚举提取和导入依赖。 | | TypeScript / TSX (`.ts`, `.tsx`) | Tree-sitter 分析器，支持 Next.js 和 React 入口检测、决策、循环、调用、返回、表达式箭头函数、测试、枚举提取和导入依赖。 | | JavaScript / JSX (`.js`, `.jsx`, `.mjs`, `.cjs`) | Tree-sitter 分析器，支持 JavaScript 标签、决策、循环、调用、返回、表达式箭头函数、测试和导入依赖。 | | Go (`.go`) | 基于性能的 Tree-sitter 分析器，包含函数、方法、决策、循环、调用、返回、测试和导入依赖。 | | Java (`.java`) | 基于性能的 Tree-sitter 分析器，包含方法、决策、循环、调用、返回、异常、测试、导入和 Spring 路由注解。 | | C# (`.cs`) | 基于性能的 Tree-sitter 分析器，包含方法、决策、循环、调用、返回、异常和测试。 | | PHP (`.php`) | 基于性能的 Tree-sitter 分析器，包含函数、方法、决策、循环、调用、返回、异常和测试。 | | C (`.c`, `.h`) | 基于性能的 Tree-sitter 分析器，包含函数、决策、循环、调用、返回和测试。 | | C++ (`.cc`, `.cpp`, `.cxx`, `.hh`, `.hpp`, `.hxx`, `.ipp`, `.tpp`) | 基于性能的 Tree-sitter 分析器，包含函数、方法、决策、循环、调用、返回、异常和测试。 | | Rust (`.rs`) | 基于性能的 Tree-sitter 分析器，包含函数、决策、循环、调用、匹配处理、返回和测试。 | | Ruby (`.rb`) | 基于性能的 Tree-sitter 分析器，包含方法、决策、循环、调用、返回和测试。 | 生成的模型包括 `metadata.language_capabilities`，提供了每种语言的功能标志和限制说明。代理应该在解释分析器深度时使用此约定。 ## 隐私 分析器、规范工件、Mermaid 生成、本地查看器和 MCP 服务器不需要 LLM API 密钥。CodeDebrief 本身在本地构建工作流模型。 当 CodeDebrief 连接到托管的代码代理时，代理可能会通过 MCP 接收工作流片段和源范围。数据传输由您使用的代码代理和提供商管理。 ## 配置 CodeDebrief 无需配置即可运行。新的 `setup` 运行仅在默认设置不足时创建 `codedebrief-out/codedebrief.toml`；旧的根目录 `codedebrief.toml` 文件仍会被读取和保留。 ```toml [codedebrief] # 只分析这些文件夹或文件。路径相对于项目根目录，除非是绝对路径；支持兄弟仓库，例如 "../api"。 # 工件仍会写入相对于项目根目录的 output_dir。 source_roots = ["."] exclude = [] exclude_dirs = [] include_public_functions = true max_call_depth = 4 output_dir = "codedebrief-out" self_exclude = true [codedebrief.entrypoints] include = [] exclude = [] [codedebrief.scopes] backend = ["backend/**", "services/**"] frontend = ["frontend/**", "web/**"] edge = ["edge/**", "workers/**"] ``` 默认设置会修剪常见的 VCS、依赖、缓存、临时、生成和输出目录，包括 `.git`、`node_modules`、虚拟环境文件夹、`.next`、`.turbo`、`.svelte-kit`、`.nx`、`.pytest_cache`、`.mypy_cache`、`.ruff_cache`、`.pyre`、`.dart_tool`、`dist`、`build`、`out`、`target`、`obj`、`coverage`、`vendor`、`Pods` 和 `codedebrief-out`。 ### 分析选定文件夹或仓库 支持此功能。从您希望工作区配置和 `codedebrief-out` 文件夹位于的目录运行 CodeDebrief，然后将选定的文件夹或仓库传递给 `--source`。 例如，从仓库根目录： ```bash cd path/to/my-project codedebrief setup claude --source backend-api frontend/src ``` 在此配置下： - CodeDebrief 仅分析 `backend-api/` 和 `frontend/src/`； - `codedebrief-out/codedebrief.json`、`codedebrief-out/codedebrief.md`、哈希侧车和本地查看器 HTML 仍在当前项目根目录中创建； - MCP 和手动查看器继续使用根项目上下文，但建模的工作流仅来自选定的文件夹。 对于兄弟仓库，请使用专用工作区文件夹： ```bash mkdir pipeline-map cd pipeline-map codedebrief setup claude --source ../repo-ingest ../repo-transform ../repo-app ``` 在此配置下，CodeDebrief 将其配置和工件写入 `pipeline-map/codedebrief-out/`，而模型路径相对于工作区，例如 `../repo-ingest/src/pipeline.py`。推断的范围使用仓库文件夹名称（`repo-ingest`、`repo-transform`、`repo-app`），除非您手动定义 `[codedebrief.scopes]`。 `--source` 值可以指向文件夹或单个源文件。CodeDebrief 在初始分析开始前将它们写入活动配置中作为 `source_roots`。如果您希望为 monorepo 或多仓库工作区的不同部分创建单独的模型，请使用不同的工作区根目录或具有不同 `output_dir` 值的配置文件。 ## 限制 CodeDebrief 不运行代码、不观察运行时状态、不执行完整的符号执行、不证明业务正确性或重建深层框架状态。它静态地建模源文件、控制流、选定的框架约定和可解析的内部调用。 重要的实际限制： - 动态调度可能仍未解决； - 语言能力因分析器前端而异； - 生成或不支持的文件可能会被跳过； - 大型切片按 token 预算，并报告遗漏； - 显示的第一个切片是有限的摘要，可以使用 MCP 工具扩展。 ## 常见问题 ### CodeDebrief 是否取代项目文档？ 不。维护的文档应解释架构、意图、设计原理、约定和操作知识。CodeDebrief 用于在集思广益、调试、规划和影响分析期间进行快速、以源代码为基础的工作流检查。 ### LLM 是否生成流程图？ 不。分析器从源代码构建规范的工作流模型和 Mermaid 图。代码代理可以选择有限的切片、渲染它、翻译标签或解释它，但这些操作仍是确定性图的表示层。 ### 这与生成的仓库摘要有何不同？ 生成的摘要是为一个请求和一个上下文窗口生成的文本。CodeDebrief 维护一个可重用的结构模型，可以返回有限的流程图、源锚、遗漏和扩展手柄，以供后续问题使用。 ### CodeDebrief 是 AI 代码审查工具吗？ 不。CodeDebrief 用于代码理解和工作流导航。它帮助人类和代码代理理解建模的逻辑；它不将可能的缺陷作为产品输出呈现。 ### CodeDebrief 需要 LLM API 密钥吗？ 不。分析器、工件、Mermaid 图、手动查看器和 MCP 服务器是本地优先和确定性的。代码代理可以使用 MCP 工具而无需任何所需的提供商密钥。 ### CodeDebrief 与调用图有何不同？ 调用图显示符号之间的关系。CodeDebrief 建模工作流片段，包括入口点、决策、分支、顺序步骤、源范围、领域概念、视觉目标和代码代理的扩展工具。 ### CodeDebrief 能否从代码生成 Mermaid 工作流图？ 是的。`agent_context` 为选定的 `workflow_slice` 返回规范的自上而下的 Mermaid 视觉图，`snapshot_slice` 可以为无法内联渲染 Mermaid 的客户端保存 Mermaid 文件。 ### 我可以仅将 CodeDebrief 用作手动视觉浏览器吗？ 是的。运行 `codedebrief view` 以打开交互式本地查看器。MCP 是主要的代理界面，但查看器仍然是官方的手动探索界面。 ## 开发 在该仓库中进行本地开发： ```bash uv sync --extra dev uv run codedebrief --help ``` 标准网关： ```bash UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run ruff check . UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run ruff format --check . UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run mypy UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run pytest --cov UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run codedebrief validate . --check-sync --json ``` 查看器网关： ```bash npm run viewer:typecheck npm run viewer:test npm run viewer:build UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run codedebrief update UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run codedebrief view --render-only --no-open ``` 架构： - [schema/codedebrief.schema.json](schema/codedebrief.schema.json) 文档化了规范的工件模型。 ## 许可证 Apache License 2.0。参见 [LICENSE](LICENSE)。