// 生成单个文档的详细内容，根据文档结构和用户意图生成包含导航、代码示例、技术图表的完整文档。 使用场景： - doc-smith 主流程调用，批量生成各文档内容 - 输入文档路径（与 document-structure.yaml 中的 path 对应） - 自动读取 workspace 配置（document-structure.yaml、user-intent.md、config.yaml） - 分析源代码并生成结构化内容 - 调用 saveDocument 保存，调用 checkContent 校验 - 返回摘要信息（不返回完整内容以节省上下文）
| name | doc-smith-docs-detail |
| description | 生成单个文档的详细内容，根据文档结构和用户意图生成包含导航、代码示例、技术图表的完整文档。 使用场景： - doc-smith 主流程调用，批量生成各文档内容 - 输入文档路径（与 document-structure.yaml 中的 path 对应） - 自动读取 workspace 配置（document-structure.yaml、user-intent.md、config.yaml） - 分析源代码并生成结构化内容 - 调用 saveDocument 保存，调用 checkContent 校验 - 返回摘要信息（不返回完整内容以节省上下文） |
生成单个文档的详情。
输入：文档路径 + 可选的自定义要求 输出：自然语言摘要（包含文档概述、章节结构、校验结果、保存确认）
从 workspace 约定目录自动读取：
planning/document-structure.yaml → 文档的 title、description、sourcePaths、层级关系
intent/user-intent.md → 目标用户、使用场景、文档侧重点
config.yaml → 语言配置（locale）
关键步骤：
document-structure.yaml 中找到 path 对应的文档条目title、description、sourcePathsconfig.yaml 读取 locale 字段作为目标语言根据是否有子文档来决定内容详略程度：
| 文档类型 | 判断条件 | 内容策略 |
|---|---|---|
| 概览文档 | 在 document-structure.yaml 中有 children | 简写：每个子主题 2-4 段 + 引导链接 |
| 详细文档 | 在 document-structure.yaml 中无 children | 详写：完整展开所有内容 |
概览文档的写作原则：
详细文档的写作原则：
根据文档的 sourcePaths 读取和分析源代码文件：
从 user-intent.md 中解读：
在开始生成文档内容前，必须完成以下步骤：
文档输出目录固定为：docs/
执行以下命令查找 sources 中的所有媒体文件：
find . -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.svg" -o -name "*.mp4" -o -name "*.webp" \)
记录所有结果，例如：
./assets/create/screenshot1.png./assets/run/screenshot2.png./images/architecture.pngsources 中的图片使用绝对路径：
对于数据源中的图片，使用 /sources/ 开头的绝对路径格式：
示例：
modules/sources/assets/run/screenshot.png注意：
生成符合规范的 Markdown 文档，包含：
path只包含用户需要的代码，排除内部实现：
| 类型 | 是否包含 | 示例 |
|---|---|---|
| ✅ API 调用示例 | 是 | POST /api/users { "name": "..." } |
| ✅ 配置示例 | 是 | 配置文件的写法 |
| ✅ 使用示例 | 是 | 如何调用 SDK/CLI |
| ❌ 内部实现 | 否 | 类的私有方法、算法实现 |
| ❌ 框架代码 | 否 | 中间件实现、内部工具函数 |
代码示例长度限制：
A. 技术图表（按需生成）
以下类型的内容建议包含技术图表，在没有已有图片且确实有助于理解时生成 AFS Image Slot：
B. 应用截图（使用已有）
以下类型使用工作区中的已有截图：
图片数量建议（不是强制要求）：
| 文档类型 | 技术图表 | 应用截图 |
|---|---|---|
| 概览文档 | 0-1 个（整体架构图即可） | 0-1 个 |
| 详细文档 | 1-2 个（按需添加） | 按需引用 |
判断是否需要图片的原则：
应用截图：
技术图表：
Use an AFS image slot only when you want the framework to generate a new image.
Slot format (single line):
<!-- afs:image id="architecture-overview" desc="..." -->
Optional stable intent key (for reuse across edits or documents):
<!-- afs:image id="architecture-overview" key="aigne-cli-architecture" desc="..." -->
Rules:
- Insert a slot only for new image generation.
If the source already provides an image (existing URL/path/asset), reference it directly; do not create a slot.
- id is required and must be a semantic identifier describing the image's role or position
(e.g. architecture-overview, core-flow, deployment-banner).
It must be unique in the same document and match: [a-z0-9._-]+.
- desc is required, concise, double-quoted, and must not contain ".
It describes what the image should depict.
- key is optional. Use a short, stable token ([a-z0-9._-]+) when you want the same image intent to be reused across sections or documents.
何时生成 Slot：
Slot 不能用于：
必须调用 saveDocument 工具保存文档，工具中有额外的保存逻辑：
saveDocument({
path: "/api/overview", // 文档路径
content: "# API 概览\n...", // Markdown 内容
options: {
language: "zh" // 从 config.yaml 的 locale 读取
}
})
重要：language 参数必须从 config.yaml 的 locale 字段读取并传入。
调用 checkContent 工具校验文档：
在结束前必须执行以下检查：
saveDocument 工具是否成功执行ls 或 Read 工具检查 docs/ 目录下对应的文档文件是否已创建saveDocument 保存文档使用自然语言返回处理结果摘要，不返回完整文档内容以节省主 agent 上下文。
摘要应包含以下信息：
/api/overview）/path/to/document（与 document-structure.yaml 中的 path 一致）必须执行：
不应执行：
| 文档类型 | 建议行数 | 代码示例数量 | 说明 |
|---|---|---|---|
| 概览文档（有子文档） | 150-300 行 | 3-5 个简短示例 | 每个子主题简要介绍 |
| 详细文档（无子文档） | 300-500 行 | 5-10 个完整示例 | 完整展开技术细节 |
超长文档的处理：
过短文档的处理：
核心原则：概览文档不重复子文档的内容
生成概览文档时，必须遵循：
自检问题：
写作前先问自己：
写作时的控制方法：