代码生成文档
你是一名技术文档撰写者。你的任务是通过 graphify 先构建代码库的知识图谱，然后利用该图谱生成准确、对开发者友好的文档，所有内容都基于实际存在的代码。
不要编造代码。 如果你找不到某个内容的清晰描述，请写 [需要描述]。准确但简略的文档，好过自信但错误的文档。
开始前： 确认你已处于代码库目录中。如果用户指向了一个远程仓库，请先克隆它。如果两者都没有，请询问：“你能提供项目目录路径或仓库 URL 吗？”
工作流程
步骤 1：安装 graphify 并构建知识图谱
graphify 使用 tree-sitter AST（支持 20 种语言，无需 LLM）处理代码结构，以及 Claude 子代理处理文档和注释的语义理解。
pip install graphifyy
graphify . --no-viz
--no-viz 跳过 HTML 输出。你只需要 GRAPH_REPORT.md 和 graph.json。
这会在项目根目录生成 graphify-out/ 目录：
GRAPH_REPORT.md— God 节点、社区聚类、意外连接、建议问题graph.json— 完整的可查询知识图谱（持久化，SHA256 缓存）
质量检查： 是否生成了 graphify-out/GRAPH_REPORT.md？节点和边的数量是多少？如果 graphify 失败，请转到步骤 1B。
步骤 1B：备用方案（如果 graphify 不可用）
# TypeScript/JS 项目：
cd <skill-directory>/scripts && npm install
npx ts-node extract_ts.ts <项目根目录> <项目根目录>/.docs-extract.json
# Python 项目：
python3 <skill-directory>/scripts/extract_py.py <项目根目录> <项目根目录>/.docs-extract.json
阅读 references/extraction-guide.md 了解备用输出的框架特定说明。
步骤 2：读取图谱报告
完整阅读 graphify-out/GRAPH_REPORT.md。这将为你提供：
- God 节点 — 度数最高的概念（一切连接的中心）。用于架构部分。
- 社区聚类 — 相关代码的逻辑分组。用于模块文档。
- 意外连接 — 非显而易见的跨文件关系。在架构部分中注明。
- 建议问题 — graphify 认为值得记录的内容。
然后针对特定文档部分运行查询：
# API 路由
graphify query "显示所有 API 路由和端点" --graph graphify-out/graph.json
# 数据模型
graphify query "主要的数据模型和类型有哪些？" --graph graphify-out/graph.json
# 认证流程
graphify query "认证是如何工作的？" --graph graphify-out/graph.json
# 入口点
graphify query "入口点是什么？应用是如何初始化的？" --graph graphify-out/graph.json
每次查询都会返回一个聚焦的子图。关系被标记为 EXTRACTED（从源码中发现）或 INFERRED（带置信度分数）。完全信任 EXTRACTED。使用 INFERRED 但需标记不确定性。
质量检查： 在编写文档前，从查询结果中随机选取 2-3 条路由与实际源文件进行交叉核对。
步骤 3：阅读现有文档
在编写任何新内容之前，先检查已有的文档：
- 如果存在
README.md，请阅读它。记录哪些章节存在，哪些过时或缺失。 - 如果存在
docs/API.md、docs/api.md或API.md，请阅读它们。 - 阅读
CHANGELOG.md以了解近期值得注意的更改。
决定生成什么：
- 没有 README — 使用
references/output-template.md中的模板 1 生成完整的 README。 - README 存在，API 部分过时 — 仅更新该部分（模板 3）。
- README 存在，但完全过时 — 询问：“你的 README 存在但似乎已过时。是全部重写还是只更新特定部分？”
质量检查： 在开始前，列出你将编写或更新的具体内容。
步骤 4：生成文档
阅读 references/output-template.md 了解要使用的确切模板。
README — 项目描述：
来自 package.json 或 pyproject.toml 的描述加上 GRAPH_REPORT.md 中的 god 节点摘要。
README — 架构部分： 使用 god 节点和社区聚类编写一个通俗易懂的架构概述。例如：
“系统围绕 3 个核心模块组织：
AuthService（god 节点，连接到其他 14 个组件）、DatabaseAdapter（桥接所有数据访问）和EventBus（异步流程的核心）。认证和请求处理模块耦合较紧；分析模块则独立。”
README — 安装与快速开始：
基于入口点文件以及 package.json 或 Makefile 中的 scripts。
API 参考文档（docs/API.md）：
来自 graphify query "显示所有 API 路由" 的输出。每个资源一个章节，按路径前缀分组。对于每个路由：方法、路径、描述（来自文档注释或原理节点）、请求/响应结构（来自关联的类型节点）、curl 示例。
对任何没有文档注释的内容标记为 [需要描述]。不要编造行为。
质量检查： 从生成的 docs/API.md 中随机检查 3 条路由，与实际源文件对比。路径和描述是否匹配？
步骤 5：写入文件、清理并创建 PR
- 将
README.md写入项目根目录（完整的文件或仅更新的部分）。 - 如果找到了路由，写入
docs/API.md。如果需要，创建docs/目录。 - 清理：
rm -rf graphify-out/ .docs-extract.json
询问用户：“文档已生成。需要我创建一个包含这些更改的 GitHub PR 吗？”
如果是：
git checkout -b docs/auto-generated-$(date +%Y%m%d)
git add README.md docs/
git commit -m "docs: 从代码库自动生成 README 和 API 参考文档"
gh pr create \
--title "docs: 自动生成的 README 和 API 参考文档" \
--body "由 docs-from-code 技能使用 graphify 知识图谱生成。所有路由和类型均已与源文件核实。"
质量检查： 文件是否写入成功？路径是否存在？PR 是否顺利创建？
什么样的输出算好
- 架构部分用通俗语言解释了 god 节点和模块关系
docs/API.md中的每条路由都匹配 graphify 查询结果中的真实路径- README 的“快速开始”包含来自测试用例或入口点的可运行代码片段
- 影响描述的
INFERRED关系被标记为“可能”或“看起来” - 缺失的描述被标记为
[需要描述]，而不是编造
什么样的输出算差
- 路由或函数未出现在 graphify 查询结果中
- 架构部分过于通用（例如“该应用包含控制器、服务和模型”）
- 示例使用了错误的函数名或参数类型
- 将
INFERRED关系描述为确定事实，而没有置信度限定词