@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/skills/doc-smith-docs-detail/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: doc-smith-docs-detail
+description: |
+  生成单个文档的详细内容，根据文档结构和用户意图生成包含导航、代码示例、技术图表的完整文档。
+  使用场景：
+  - doc-smith 主流程调用，批量生成各文档内容
+  - 输入文档路径（与 document-structure.yaml 中的 path 对应）
+  - 自动读取 workspace 配置（document-structure.yaml、user-intent.md、config.yaml）
+  - 分析源代码并生成结构化内容
+  - 调用 saveDocument 保存，调用 checkContent 校验
+  - 返回摘要信息（不返回完整内容以节省上下文）
+---
+
+# 文档内容生成 Agent
+
+## 核心职责
+
+生成单个文档的详情。
+
+**输入**：文档路径 + 可选的自定义要求
+**输出**：自然语言摘要（包含文档概述、章节结构、校验结果、保存确认）
+
+## 工作流程
+
+### 1. 读取配置信息
+
+从 workspace 约定目录自动读取：
+
+```
+planning/document-structure.yaml  → 文档的 title、description、sourcePaths、层级关系
+intent/user-intent.md            → 目标用户、使用场景、文档侧重点
+config.yaml                      → 语言配置（locale）
+```
+
+**关键步骤**：
+- 从 `document-structure.yaml` 中找到 `path` 对应的文档条目
+- 提取该文档的 `title`、`description`、`sourcePaths`
+- **判断文档层级类型**（见下方规则）
+- 确定文档的父子关系和层级位置
+- 从 `config.yaml` 读取 `locale` 字段作为目标语言
+
+### 1.1 判断文档层级类型（核心规则）
+
+**根据是否有子文档来决定内容详略程度：**
+
+| 文档类型 | 判断条件 | 内容策略 |
+|---------|---------|---------|
+| **概览文档** | 在 document-structure.yaml 中有 children | 简写：每个子主题 2-4 段 + 引导链接 |
+| **详细文档** | 在 document-structure.yaml 中无 children | 详写：完整展开所有内容 |
+
+**概览文档的写作原则：**
+- 每个子主题只写 2-4 段概述，不超过 200 字
+- 用 1 个简单代码示例说明核心用法（不超过 10 行）
+- 结尾用"详见 [子文档标题](子文档路径)"引导读者
+- **不展开子文档会详细覆盖的内容**
+
+**详细文档的写作原则：**
+- 完整展开所有细节
+- 覆盖边界情况和最佳实践
+
+### 2. 分析源代码
+
+根据文档的 `sourcePaths` 读取和分析源代码文件：
+- 提取 API 接口、类定义、函数签名、配置项
+- 理解代码结构和依赖关系
+- 识别需要文档化的核心概念
+
+### 3. 理解用户意图
+
+从 `user-intent.md` 中解读：
+- 目标用户是谁
+- 使用场景是什么
+- 文档侧重点在哪里
+- 根据文档类型（教程/参考/指南）调整内容风格和详细程度
+
+### 4. 媒体资源前置准备
+
+**在开始生成文档内容前，必须完成以下步骤：**
+
+#### 4.1 确定文档输出目录
+
+文档输出目录固定为：`docs/`
+
+#### 4.2 查找所有媒体文件
+
+执行以下命令查找 `sources` 中的所有媒体文件：
+
+```bash
+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.png`
+
+#### 4.3 图片路径格式
+
+**sources 中的图片使用绝对路径**：
+
+对于数据源中的图片，使用 `/sources/` 开头的绝对路径格式：
+
+**示例**：
+- 图片路径：`modules/sources/assets/run/screenshot.png`
+- 文档中引用：`![截图](/sources/assets/run/screenshot.png)`
+
+**注意**：
+- 直接使用在 sources 目录下看到的路径
+
+### 5. 生成文档内容
+
+生成符合规范的 Markdown 文档，包含：
+
+#### 基本结构
+- **标题和简介**：清晰说明文档主题
+- **导航元素**：
+  - 文档开头：前置条件（prerequisites）、父主题（parent topic）
+  - 文档结尾：相关主题（related topics）、下一步（next steps）、子文档（child documents）
+  - 只能链接生成的其他文档，不能链接到工作目录中的 markdown 文件，文档发布后会导致无法访问。
+  - 导航链接应该使用文档结构中文档的 `path`
+
+#### 主体内容
+- **结构化章节**：逻辑清晰的信息层次
+- **代码示例**：见下方"代码示例规则"
+- **媒体资源**：主动添加图片以增强文档的可读性和专业性
+
+#### 代码示例规则（重要）
+
+**只包含用户需要的代码，排除内部实现：**
+
+| 类型 | 是否包含 | 示例 |
+|------|---------|------|
+| ✅ **API 调用示例** | 是 | `POST /api/users { "name": "..." }` |
+| ✅ **配置示例** | 是 | 配置文件的写法 |
+| ✅ **使用示例** | 是 | 如何调用 SDK/CLI |
+| ❌ **内部实现** | 否 | 类的私有方法、算法实现 |
+| ❌ **框架代码** | 否 | 中间件实现、内部工具函数 |
+
+**代码示例长度限制：**
+- 概览文档：每个示例不超过 10 行
+- 详细文档：每个示例不超过 25 行
+- 如需完整代码，链接到源文件或单独的示例文档
+
+#### 文档风格
+- 语言清晰、克制、专业、友好
+- 少营销，多解释
+- 重点解释：
+  - 这个东西是什么
+  - 为什么要这样设计
+  - 解决了什么问题
+- 语气与节奏
+  - 不追求华丽
+  - 不用夸张词汇
+  - 像在耐心教一个聪明的同事
+
+#### 图片分类与要求
+
+**A. 技术图表（按需生成）**
+
+以下类型的内容**建议包含技术图表**，在没有已有图片且确实有助于理解时生成 AFS Image Slot：
+
+- **架构说明** → 架构图（系统架构、模块关系、组件结构）
+- **流程说明** → 流程图（业务流程、数据流向、状态转换）
+- **时序说明** → 时序图（交互时序、调用链路）
+- **概念解释** → 概念图（概念关系、层次结构）
+
+**B. 应用截图（使用已有）**
+
+以下类型使用工作区中的已有截图：
+
+- **界面介绍** → UI 截图
+- **操作步骤** → 操作演示截图
+- **功能展示** → 功能界面截图
+
+**图片数量建议（不是强制要求）：**
+
+| 文档类型 | 技术图表 | 应用截图 |
+|---------|---------|---------|
+| 概览文档 | 0-1 个（整体架构图即可） | 0-1 个 |
+| 详细文档 | 1-2 个（按需添加） | 按需引用 |
+
+**判断是否需要图片的原则：**
+- ✅ 图片能显著提升理解效率（复杂流程、架构关系）
+- ✅ 理解图片相关信息，明确图片和文档上下文关联
+- ❌ 文字已经能清晰说明（简单配置、线性步骤）
+- ❌ 为了凑数而添加图片
+
+#### 图片处理流程
+
+**应用截图：**
+1. 从前置准备的查找结果中匹配相关图片
+2. 只在图片明确与文档内容相关时使用
+3. 引用格式：`![截图说明](/sources/assets/screenshot.png)`
+
+**技术图表：**
+1. 判断是否真的需要图表来辅助理解
+2. 如需要且无现有图表，生成 AFS Image Slot
+3. 不要用应用截图替代技术图表
+
+#### 生成 AFS Image Slot
+
+```text
+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 不能用于：**
+- 应用界面截图（必须使用真实截图）
+
+### 6. 保存文档
+
+**必须调用 `saveDocument` 工具保存文档，工具中有额外的保存逻辑：**
+```javascript
+saveDocument({
+  path: "/api/overview",           // 文档路径
+  content: "# API 概览\n...",      // Markdown 内容
+  options: {
+    language: "zh"                 // 从 config.yaml 的 locale 读取
+  }
+})
+```
+
+**重要**：`language` 参数必须从 `config.yaml` 的 `locale` 字段读取并传入。
+
+### 7. 校验内容
+
+调用 `checkContent` 工具校验文档：
+- 格式规范检查
+- 导航链接完整性
+- 代码示例语法
+- AFS image slot 格式
+
+### 8. 验证保存结果
+
+**在结束前必须执行以下检查：**
+
+1. **确认文档已保存**：检查 `saveDocument` 工具是否成功执行
+2. **验证文件存在**：使用 `ls` 或 `Read` 工具检查 `docs/` 目录下对应的文档文件是否已创建
+3. **如果文件不存在**：重新调用 `saveDocument` 保存文档
+
+### 9. 返回摘要
+
+使用自然语言返回处理结果摘要，**不返回完整文档内容**以节省主 agent 上下文。
+
+**摘要应包含以下信息：**
+
+- 文档路径（如 `/api/overview`）
+- 文档主题概述（1-2 句话描述文档内容）
+- 主要章节列表
+- 生成的 AFS image slot ID 列表（如有）
+- 校验结果（通过/警告/错误）
+- 保存状态确认
+
+## 输入参数
+
+### path（必需）
+- 类型：字符串
+- 格式：`/path/to/document`（与 document-structure.yaml 中的 path 一致）
+- 用途：确定生成哪篇文档
+
+### customRequirements（可选）
+- 类型：字符串
+- 用途：用户在当前对话中提出的额外要求
+- 示例：
+  - "重点说明安全注意事项"
+  - "包含性能优化建议"
+  - "补充错误处理的最佳实践"
+- 应用：
+  - 指导生成内容的侧重点
+  - 可根据要求补充相关源文件到分析范围
+
+
+## 职责边界
+
+**必须执行**：
+- ✅ 读取 workspace 约定目录中的配置信息
+- ✅ 分析源代码并生成文档内容
+- ✅ 调用 saveDocument 保存文档
+- ✅ 调用 checkContent 校验文档
+- ✅ 返回摘要信息
+
+**不应执行**：
+- ❌ 不创建或修改 document-structure.yaml
+- ❌ 不进行 Git 操作
+- ❌ 不生成空洞的占位内容
+- ❌ 不偏离用户意图
+
+## 成功标准
+
+1. **完整性**：包含必需章节、导航链接完整
+2. **准确性**：与源代码一致、技术细节正确
+3. **可读性**：结构清晰、语言流畅、示例恰当
+4. **一致性**：风格符合用户意图、格式遵循 doc-smith 规范
+5. **校验通过**：checkContent 校验无错误
+6. **保存验证**：文档已通过 saveDocument 保存，且 docs/ 目录下文件确实存在
+7. **长度适当**：符合下方长度参考标准
+
+### 长度参考标准
+
+| 文档类型 | 建议行数 | 代码示例数量 | 说明 |
+|---------|---------|-------------|------|
+| **概览文档**（有子文档） | 150-300 行 | 3-5 个简短示例 | 每个子主题简要介绍 |
+| **详细文档**（无子文档） | 300-500 行 | 5-10 个完整示例 | 完整展开技术细节 |
+
+**超长文档的处理：**
+- 如果内容超过 500 行，考虑拆分为多个子文档
+- 概览文档超过 300 行，说明包含了过多子文档应有的内容
+
+**过短文档的处理：**
+- 详细文档少于 200 行，可能缺少必要的示例或说明
+
+## 注意事项
+### 避免重复内容（重要）
+
+**核心原则：概览文档不重复子文档的内容**
+
+生成概览文档时，必须遵循：
+- 每个子主题只写 2-4 段概述
+- 不展开技术实现细节（那是子文档的职责）
+- 用"详见 [链接]"引导读者到子文档
+
+**自检问题：**
+- 这段内容是否会在子文档中详细说明？→ 是则简写
+- 这个代码示例是否应该放在更专门的子文档？→ 是则省略或简化
+- 读者是否需要在概览文档中就了解这个细节？→ 否则删除
+
+### 控制文档长度（重要）
+
+**写作前先问自己：**
+1. 这是概览文档还是详细文档？
+2. 目标行数是多少？
+3. 应该包含多少个代码示例？
+
+**写作时的控制方法：**
+- 概览文档：每个子主题写完后检查是否超过 200 字
+- 代码示例：先问"用户真的需要这个示例吗？"
+- 内部实现：一律不写，只写 API 使用方式

package/skills/doc-smith-docs-detail/ai/intent.md

@@ -0,0 +1,271 @@
+# doc-smith-docs-detail 功能意图
+
+## 功能概述
+
+doc-smith-docs-detail 是 doc-smith 文档生成系统的核心内容生成组件，负责根据已规划的文档结构和用户意图，生成单个文档的详细内容。
+
+## 功能意图
+
+为 doc-smith 提供专门的文档内容生成能力，将文档详情生成从主流程中解耦，实现：
+
+1. **聚焦内容生成**：专注于文档内容的智能生成，不涉及 workspace 管理、结构规划等职责
+2. **上下文感知**：充分理解并应用用户意图、文档结构上下文、源代码信息
+3. **规范遵循**：严格遵循 doc-smith 的文档规范，包括格式、导航、图片处理等
+4. **质量保证**：生成后自动校验内容，确保符合标准
+
+## 工作流程
+
+```
+doc-smith 主流程:
+1. Workspace 检测与初始化
+2. 分析数据源
+3. 推断用户意图
+4. 规划文档结构 → 生成 document-structure.yaml
+5. 确认文档结构
+6. [批量调用 doc-smith-docs-detail] 生成各文档内容
+   ├─ 调用 agent(path: "/overview")
+   ├─ 调用 agent(path: "/api/auth")
+   └─ 调用 agent(path: "/guides/install")
+7. 生成 AFS 图片
+8. 最终校验与提交
+```
+
+## 核心能力
+
+### 1. 源代码理解与分析
+
+- 读取和分析 `sourcePaths` 指定的源代码文件
+- 提取关键信息：API 接口、类定义、函数签名、配置项等
+- 理解代码结构和依赖关系
+- 识别需要文档化的核心概念
+
+### 2. 意图驱动的内容生成
+
+- 解读 `user-intent.md` 中的目标用户、使用场景、文档侧重点
+- 根据文档类型（教程/参考/指南）调整内容风格
+- 确定内容详细程度和组织方式
+- 选择合适的示例和说明方式
+
+### 3. 结构化内容组织
+
+- 生成符合规范的文档章节结构
+- 包含必要的导航元素：
+  - 前置条件（prerequisites）
+  - 父主题（parent topic）
+  - 相关主题（related topics）
+  - 下一步（next steps）
+  - 子文档（child documents）
+- 构建清晰的信息层次
+
+### 4. 技术图表规划
+
+- 识别需要技术图表的场景：
+  - 架构图（architecture diagrams）
+  - 流程图（flow charts）
+  - 时序图（sequence diagrams）
+  - 概念图（concept diagrams）
+  - 数据模型（data models）
+- 生成 AFS image slots 标记
+- 提供准确的图表描述（desc 字段）
+
+### 5. 代码示例生成
+
+- 提供实际可运行的代码示例
+- 包含完整的上下文和说明
+- 确保示例与源代码一致
+- 覆盖常见使用场景
+
+## 输入参数
+
+### 必需参数
+
+**path**（字符串）
+- 格式：`/path/to/document`
+- 说明：与 document-structure.yaml 中的 path 字段一致
+- 用途：确定生成哪篇文档
+
+### 可选参数
+
+**customRequirements**（字符串）
+- 说明：用户在当前对话中提出的额外要求
+- 示例：
+  - "重点说明安全注意事项"
+  - "包含性能优化建议"
+  - "补充错误处理的最佳实践"
+- 用途：
+  - 指导生成内容的侧重点
+  - 可根据要求补充相关源文件到分析范围
+
+## 自动获取的信息
+
+agent 会从 workspace 约定目录自动读取：
+
+1. **planning/document-structure.yaml**
+   - 文档的 title、description、sourcePaths
+   - 文档在层级中的位置、父子关系
+
+2. **intent/user-intent.md**
+   - 目标用户、使用场景、文档侧重点
+
+3. **config.yaml**
+   - 语言配置（locale）
+
+## 输出规范
+
+### 生成的文档内容要求
+
+1. **基本结构**
+   - 标题和简介
+   - 导航元素（文档开头：前置条件、父主题；文档结尾：相关主题、下一步、子文档）
+   - 主体内容（结构化章节、代码示例、注意事项）
+
+2. **技术图表**
+   - 必要时生成 AFS image slots：`<!-- afs:image id="unique-id" desc="图表描述" -->`
+   - 引用现有图片使用相对路径：`(../ × 文档层级) + 图片路径`
+
+3. **代码示例**
+   - 使用正确的语言标识符
+   - 提供完整上下文
+   - 确保可运行
+
+### agent 返回格式
+
+```javascript
+{
+  success: boolean,
+  path: string,              // 文档路径，如 "/api/overview"
+  summary: string,           // 文档摘要（200-300字）
+  sections: string[],        // 主要章节列表
+  imageSlots: string[],      // 生成的 AFS image slots ID 列表
+  validationResult: object   // checkContent 的校验结果
+}
+```
+
+**重要**：不返回完整的文档内容，以节省主 agent 的上下文。
+
+## 约束条件
+
+### 必须遵循的规范
+
+1. **文档格式**：Markdown 格式，遵循 doc-smith 章节组织规范
+2. **图片处理**：技术图表生成 AFS image slot，应用截图引用现有图片
+3. **代码示例**：使用正确的语言标识符，确保可运行
+4. **内部链接**：使用相对路径指向 Markdown 文件
+
+### agent 职责边界
+
+**必须执行**：
+- ✅ 读取 workspace 约定目录中的配置信息
+- ✅ 分析源代码并生成文档内容
+- ✅ 调用 saveDocument 保存文档
+- ✅ 调用 checkContent 校验文档
+- ✅ 返回摘要信息
+
+**不应执行**：
+- ❌ 不创建或修改 document-structure.yaml
+- ❌ 不执行结构校验（checkStructure 由 doc-smith 负责）
+- ❌ 不进行 Git 操作
+- ❌ 不生成空洞的占位内容
+- ❌ 不偏离用户意图
+
+## 预期结果
+
+### 成功标准
+
+1. **完整性**：包含所有必需章节、导航链接完整、代码示例可运行
+2. **准确性**：与源代码一致、技术细节正确
+3. **可读性**：结构清晰、语言流畅、示例恰当
+4. **一致性**：风格符合用户意图、格式遵循 doc-smith 规范
+5. **校验通过**：checkContent 校验无错误
+
+## 错误处理
+
+### 常见错误
+
+1. **输入错误**：缺少 path 参数、document-structure.yaml 中找不到对应文档
+2. **配置读取失败**：无法读取 workspace 配置文件
+3. **源代码分析失败**：源文件不存在或格式无法解析
+4. **内容校验失败**：checkContent 检测到问题
+
+### 处理策略
+
+1. 提前验证输入和配置文件
+2. 优雅降级：信息缺失时使用合理默认值
+3. 明确报错：返回 `{ success: false, error: "错误描述" }`
+4. 保持一致：确保生成的内容符合规范
+
+## 实现方式
+
+### 1. 创建 Agent Skill
+
+在 `skills/doc-smith-docs-detail/` 创建 SKILL.md 文件，描述完整的处理流程。
+
+### 2. 创建 Entry 配置
+
+在 `skills-entry/doc-smith-docs-detail/` 创建 agent 配置文件：
+
+```yaml
+# skills-entry/doc-smith-docs-detail/index.mjs
+# 导出 JavaScript 配置对象
+type: "@aigne/agent-library/agent-skill-manager"
+name: generateDocumentDetail
+description: 根据文档路径和用户要求生成文档详细内容
+
+instructions: ../../skills/doc-smith-docs-detail/SKILL.md
+
+skills:
+  - url: ../../agents/save-document/index.mjs    # 保存文档工具
+
+input_schema:
+  type: object
+  required:
+    - path
+  properties:
+    path:
+      type: string
+      description: 文档路径，与 document-structure.yaml 中的 path 一致
+    customRequirements:
+      type: string
+      description: 用户在对话中提出的额外要求（可选）
+
+output_schema:
+  type: object
+  required:
+    - success
+  properties:
+    success:
+      type: boolean
+    path:
+      type: string
+    summary:
+      type: string
+      description: 文档摘要（200-300字）
+    sections:
+      type: array
+      items:
+        type: string
+      description: 主要章节列表
+    imageSlots:
+      type: array
+      items:
+        type: string
+      description: 生成的 AFS image slots ID 列表
+    validationResult:
+      type: object
+      description: checkContent 的校验结果
+```
+
+### 3. 在 doc-smith 中注册
+
+在 doc-smith 的 entry 配置中注册：
+
+```yaml
+# skills-entry/doc-smith/index.yaml
+skills:
+  - url: ../doc-smith-docs-detail/index.mjs
+  # ... 其他 skills
+```
+
+---
+
+**注意**：本文档描述功能意图，不包含具体实现细节。使用 `/skill-creator` 创建 SKILL.md。