三层文档结构设计

API 文档被组织为三层，从粗到细：项目级汇总 → 模块级列表 → 函数级详情。这个层次对应两种使用场景：人类浏览和 LLM embedding 的输入粒度。所有文档存储在 artifact_dir/api_docs/ 目录下。

📋

L1 — index.md

项目级汇总表。列出所有模块路径、每个模块的函数/类数量。是进入文档系统的入口，也是 MCP list_api_docs 工具的数据来源。

📁

L2 — modules/{qn}.md

单模块文档。列出该模块所有公开函数和类，含一句话摘要和签名。文件名用模块 FQN 的点替换成下划线，避免路径冲突。

📄

L3 — funcs/{qn}.md

单函数详情页。为 embedding 优化的密集格式：签名、描述、ASCII 调用树、调用方列表（带文件+行号）、源码片段。是语义搜索的基础单元。

文档生成流水线

文档生成从图数据库出发，通过 Cypher 查询提取数据，渲染为 Markdown 后写入文件系统。

🗄️

Cypher 查询

→

📁

L2 模块文档

→

🌿

调用树渲染

→

📄

L3 函数文档

→

📋

L1 index.md

点击"下一步"开始 Step 0 / 5

_build_call_tree：防环递归调用树

调用树渲染面临两个挑战：递归/循环调用导致的死循环、以及树深度爆炸。 _build_call_tree() 使用 visited set + 深度限制双重防护。

LLM 增强模式：为无 docstring 函数生成描述

当 mode='enhance' 时，文档生成器会检测没有 docstring 的函数，将其签名 + 源码片段 + 调用上下文发送给 LLM，生成一句话描述，填入  位置。

enhance 模式 — LLM 增强流程

0 / 4 messages

_infer_ownership：C++ 指针所有权分析

_infer_ownership() 是专门为 C++ 代码设计的静态分析功能。它通过分析参数类型标注和函数体内的内存操作，推断每个指针参数是owned 还是 borrowed，写入 L3 文档的参数表格。

💡 关键洞察

三层文档结构的本质是粒度分层的语义索引。L1/L2 面向人类导航；L3 面向向量化——每个函数一个文件，embedding 时天然按语义单元切分，避免了文档块切割的粒度问题。LLM enhance 模式进一步把"静态代码结构"升维为"可读语义描述"，让语义搜索从"字符串相似"进化为"意图匹配"。