atharvm416/codedoc-ai
GitHub: atharvm416/codedoc-ai
一款支持增量和确定性输出的 AI 文档生成 CLI 工具，为代码仓库构建可持久复用的结构化文档记忆层。
Stars: 1 | Forks: 0
# codedoc-ai
`codedoc-ai` 为源代码仓库生成结构化且可增量复用的文档。它在本地扫描源代码，构建确定性的依赖关系图，
仅将需要分析的文件发送到配置的 LLM，并输出 JSON、
Markdown 或两者兼有。
## 为什么选择 codedoc-ai
大多数文档生成器只运行一次，并从零开始重新生成所有内容。
codedoc-ai 被构建为 AI 辅助开发的文档*记忆层*：它将文档视为持久的、
可复用的状态，而不是一次性的输出。
- 它进行**增量**文档化 —— 仅将源代码或分析标识发生变化的文件
发送给 LLM；其他所有内容都会被复用。
- 其完成后的输出是**确定性的** —— 相同的输入会产生
字节完全相同的文档，没有时间戳会产生虚假的 diff。
- 它是**崩溃安全**的 —— 中断的运行会从恢复文件中恢复，而不会
重复付费工作。
- 在写入之前，它会**验证所有权**，因此它绝不会覆盖
它不认可为自己产出的文件。
- 它生成**结构化的 JSON 和 Markdown**，旨在供人类
和工具重读。
这样的文档可以低成本重新生成，并且在一次次的运行中始终与代码保持同步。
## 架构概览
```
flowchart TD
A["Repository"] --> B["Scan - local, deterministic"]
B --> C["Dependency graph, entry-based selection"]
C --> D["Plan"]
D -->|"unchanged (content hash + analysis identity)"| E["Reuse"]
D -->|"compatible crash-recovery work"| F["Resume"]
D -->|"changed files only"| G["LLM"]
E --> H["Write JSON / Markdown - atomic, ownership-guarded"]
F --> H
G --> H
```
纯文本版本（适用于不渲染 Mermaid 的查看器）
```
repository
│
▼
scan (local, deterministic)
│
▼
dependency graph → entry-based selection
│
▼
plan ─── reuse unchanged (content hash + analysis identity)
│ ── resume compatible crash-recovery work
│ ── send only changed files to the LLM
▼
write JSON / Markdown (atomic, ownership-guarded)
```
有关完整的逐阶段运行生命周期 —— 包括缓存和恢复标识
以及失败不变量 —— 请参见
[RUN_FLOW.md](https://github.com/atharvm416/codedoc-ai/blob/main/RUN_FLOW.md)。
## 核心设计原则
这些原则由代码强制执行，而非仅是愿景：
- **确定性输出** —— 相同的输入产生字节完全相同的文档；
完成后的输出不包含时间戳。
- **默认增量** —— 未更改的文件将被复用，永远不会重新发送给
provider。
- **Fail-closed（失败即停止）验证** —— 未知的配置、格式错误的指令
profile 以及外部的输出文件会停止运行，而不是被静默
忽略。
- **最小的缓存失效** —— 更改仅重新处理它
实际影响的文件。
- **明确的所有权** —— codedoc-ai 仅覆盖它认可为自己
产出的文件。
- **可读的输出契约** —— 完成后的 JSON 和 Markdown 结构化设计，适合
人类、脚本和 AI 助手阅读。
- **基于验证的兼容性** —— CodeDoc 会读取已识别的 CodeDoc 文档
和恢复文件，并拒绝外部或格式错误的 artifact。
- **配置优于 CLI 膨胀** —— 深度定制存在于 `codedoc.config.json`
（`codedoc --init-config`）中；命令行接口保持精简。
## 核心亮点
- 显式或自动检测的入口文件，支持 `entry` 或 `all` 文档范围。
- 默认每个文件一次组合的 provider 调用；可选的 triple-agent 分析。
- 基于源哈希和分析标识，在 JSON 和 Markdown 之间进行增量复用。
- 一个固定的崩溃恢复文件，可在中断后保留已完成的工作。
- 仅限配置的、经过验证的指令定制，并带有强制性的语义审查。
- 支持 OpenAI、Anthropic、Gemini 和 OpenAI 兼容的 endpoint。
- 只读的 dry run、付费文件上限、确定性的所有权防护，以及稳定的
面向 CI 的退出代码。
## 安装
```
pip install codedoc-ai
```
## 快速开始
在进程环境中设置 provider 凭证，然后运行 CodeDoc：
```
export OPENAI_API_KEY="your-key"
codedoc --entry src/main.py
```
PowerShell：
```
$env:OPENAI_API_KEY="your-key"
codedoc --entry src/main.py
```
默认输出为 `codedoc/codedoc.json`。常见的替代方案：
```
codedoc --format md
codedoc --format both
codedoc --output docs/report.json
codedoc --documentation-scope all
codedoc --dry-run --max-files 25
```
入口是可选的：CodeDoc 可以从所选输出中恢复它，
自动检测配置的候选对象，或者在不存在
候选对象时记录所有扫描的文件。
在后续运行中，CodeDoc 会复用未更改的自身记录，并重新处理已更改的
文件。如果你在 JSON 和 Markdown 之间切换，并且请求的目标
尚不存在，则会验证并使用格式完全相反的同级文件作为
转换源；未更改的文件不需要调用 provider。
空和仅包含空格的源文件会在解析之前和
其每文件文档化调用之前被跳过。它们不算作失败，也不会产生每文件
provider 费用。运行会通过
`files_skipped_insufficient_source` 报告它们；如果被跳过的路径在
旧的输出中有文档，该过期的记录将从新完成的输出中
省略。
## 将输出与 AI 助手结合使用
CodeDoc 的输出设计为可以粘贴、被索引或附加到 AI
编码助手中。为了获得最佳效果：
- 当人类和工具需要读取同一次运行的结果时，使用 `--format both`：Markdown
更容易浏览，而 JSON 更便于 agent 和脚本查询。
- 对于具有明确起点的应用程序流程、CLI、服务
和库，使用 `--entry` 加上默认的 `documentation_scope: entry`。
- 对于包索引、SDK 风格的参考，或者
没有有意义入口文件的仓库，使用 `--documentation-scope all`。
- 在大型或首次运行之前，运行 `codedoc --dry-run --max-files N` 以查看
有多少文件将到达 provider。
- 将 `codedoc/codedoc.json` 或 `codedoc/codedoc.md` 保持在稳定的位置，以便
将来的运行和 AI 助手可以与相同的文档
记忆进行比较。
- 更倾向于使用 `analysis_mode: single` 以获得快速、经济的文档。当依赖推理和角色分离比
provider 调用次数更重要时，请使用 `analysis_mode: triple`。
## 文件契约
CodeDoc 会自动管理一小组刻意设计的持久化文件：
| 阶段 | 确切文件 | 用途 |
| --- | --- | --- |
| 配置 | `
/codedoc.config.json` | 可选的运行时配置和内联指令。 |
| 活动运行 | `标签：AI辅助编程, LLM集成, Petitpotam, SOC Prime, 代码分析, 凭证管理, 开发工具, 文档生成, 文档结构分析, 逆向工具