@aigne/doc-smith 0.9.8-alpha.2 → 0.9.8-alpha.4

package/doc-smith/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: doc-smith
+description: "从工作区数据源生成和更新全面的文档，包括代码仓库、文本文件和媒体资源。当用户请求以下操作时使用此技能：(1) 从代码或文件创建或生成文档，(2) 构建文档结构或文档详情，(3) 分析工作区内容以生成有组织的文档，(4) 将代码/项目内容转换为可读文档，(5) 更新、修改或改进已有文档，(6) 应用术语统一、风格调整等全局修改，(7) 重写文档的特定章节或段落，(8) 处理 changeset 文件或 PATCH 标记的修改请求。支持技术文档、用户指南、API 参考和一般文档需求的生成与维护。"
+---
+
+# DocSmith
+
+从工作区数据源生成和更新结构化文档。
+
+## 概述
+
+DocSmith 分析工作区内容（代码、文件、媒体）并生成：
+1. 用户意图描述（`user_intent.md`）
+2. 文档结构计划（`document_structure.yaml`）
+3. 按层次组织的 Markdown 文档文件
+
+所有输出都创建在 `.aigne/doc-smith/` 目录中。
+
+## 使用场景
+
+### 场景 A：生成新文档
+
+当 `.aigne/doc-smith/docs/` 目录不存在或用户明确要求重新生成时，使用 **文档生成流程**（步骤 1-6）。
+
+**适用情况：**
+- 首次为项目生成文档
+- 完全重建文档结构
+- 用户说"重新生成所有文档"
+
+### 场景 B：更新已有文档
+
+当 `.aigne/doc-smith/docs/` 目录已存在且用户要求修改时，使用 **文档更新流程**（步骤 7）。
+
+**适用情况：**
+- 用户提出自然语言修改请求（如"统一术语"、"补充章节"、"修正错误"）
+- 用户提供 changeset 文件路径
+- 文档中存在 `:::PATCH` 标记
+- 用户说"更新文档"、"修改文档"、"应用修改"
+
+## 工作流程
+
+按以下步骤依次执行：
+
+### 1. 分析工作区
+
+使用 Glob/Grep/Read 工具探索工作区，了解项目目的、结构、主要模块、现有文档和媒体资源。
+
+### 2. 推断用户意图
+
+首先检查用户意图文件是否已存在，如果存在向用户问询是否需要修改。
+用户意图格式参考： `references\user_intent_guide.md`
+
+### 3. 规划文档结构
+
+首先检查文档结构文件是否已存在，如果存在执行第 5 步骤 ，向用户问询是否需要修改。
+文档结构规划要求参考： `references\structure_planning_guide.md`
+
+### 4. 生成 document_structure.yaml
+
+文档结构数据结构参考： `references\document_structure_schema.md`
+
+### 5. 确认文档结构
+
+向用户展示的结构请参考： `references\structure_confirmation_guide.md`
+
+### 6. 生成文档内容
+
+为结构中的每个文档在 `.aigne/doc-smith/docs/` 中创建 markdown 文件。使用 YAML 中的 `path` 作为文件路径，从 `sourcePaths` 提取信息，编写清晰、结构化的内容。
+
+在文档开头和结尾添加导航链接，引导用户阅读相关文档（开头：前置条件、父主题；结尾：相关主题、下一步、子文档）。
+
+### 7. 更新已有文档
+
+仅当 `.aigne/doc-smith/docs/` 已存在时处理文档更新。
+处理流程请参考 `references\document_update_guide.md` 和 `references\changeset_schema.md`
+
+## 输出结构
+
+完成后：
+
+```
+.aigne/doc-smith/
+├── output/
+│   ├── user_intent.md             # 用户意图描述
+│   └── document_structure.yaml    # 文档计划
+└── docs/
+    ├── overview.md                # 生成的文档
+    ├── getting-started.md
+    └── api/
+        └── authentication.md
+```
+
+## 媒体资源
+
+当工作区中存在媒体文件（图片、视频）时：
+
+**发现：**
+```bash
+find . -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.gif" -o -name "*.mp4" \)
+```
+
+**在 markdown 中引用：**
+```markdown
+![架构图](../path/to/diagram.png)
+
+<!-- 或相对于文档位置 -->
+![截图](../../screenshots/ui.png)
+```
+
+**不要复制**媒体文件。直接从它们的工作区位置引用。
+
+## 关键原则
+
+- **参考引用文件**：执行到每个步骤时，如果提供了参考文件，必须先阅读参考文件中的要求
+- **基于用户意图**：所有规划和生成都应参考 `user_intent.md`
+- **最小必要原则**：只生成用户意图中明确需要的文档
+- **批量执行**：生成文档内容时优先批量执行，缩短执行时间

package/doc-smith/references/changeset_schema.md

@@ -0,0 +1,118 @@
+# Changeset 文件理解指南
+
+## 核心原则
+
+Changeset 只包含两类修改：
+1. **全局语义修改** - 跨文档的规则、术语、风格
+2. **结构重写** - 补充、重写、重组特定章节
+
+**注意：** PATCH 类修改通过文档内 `:::PATCH` 标记实现，不会出现在 changeset 中。
+
+## 读取和理解
+
+Changeset 是自然语言文本，格式自由。你需要：
+1. 读取文件全部内容
+2. 识别所有修改请求
+3. 分类为"全局修改"或"结构重写"
+4. 按优先级执行：全局修改 → 结构重写
+
+## 识别规则
+
+### 全局修改特征
+- 关键词："所有"、"统一"、"全部"、"删除"
+- 跨多个文档的规则
+- 术语、风格、格式的一致性
+
+**示例：**
+```
+"所有 API 改为 API 接口"         → 全局修改
+"删除所有第一人称"               → 全局修改
+"代码块统一添加语言标识符"       → 全局修改
+```
+
+### 结构重写特征
+- 关键词："补充"、"添加"、"重写"、"重组"
+- 指定文档或章节
+- 需要生成新内容
+
+**示例：**
+```
+"overview.md 补充项目背景"       → 结构重写
+"快速开始添加环境要求章节"       → 结构重写
+"API 文档补充错误码说明"         → 结构重写
+```
+
+## 常见模式参考
+
+### 模式 1：简单列表
+```markdown
+1. 统一术语："API" → "API 接口"
+2. 补充 overview.md 的项目背景
+3. 删除所有形容词
+```
+
+理解：1, 3 是全局修改；2 是结构重写
+
+### 模式 2：分类组织
+```markdown
+## 全局修改
+- 代码示例添加语言标识符
+- 禁止使用第一人称
+
+## 补充内容
+- getting-started.md 添加环境要求
+- api/errors.md 补充错误原因
+```
+
+理解：按章节分类，直接识别
+
+### 模式 3：自由描述
+```markdown
+发现文档问题：
+- "API" 和 "接口" 混用，统一为 "API 接口"
+- 快速开始缺环境要求说明
+```
+
+理解：第一条是全局修改，第二条是结构重写
+
+## 执行流程
+
+### 1. 读取文件
+```bash
+cat <changeset-file-path>
+```
+
+### 2. 分类汇总
+
+**全局修改：**
+- 规则 1: ...
+- 规则 2: ...
+
+**结构重写：**
+- 文档 A, 章节 X: ...
+- 文档 B, 章节 Y: ...
+
+### 3. 执行修改
+
+**优先级：** 全局修改 → 结构重写
+
+**全局修改：**
+```bash
+find .aigne/doc-smith/docs/ -name "*.md"
+```
+遍历所有文档，应用规则
+
+**结构重写：**
+定位章节，读取上下文，重新生成内容
+
+### 4. 展示摘要
+
+列出所有执行的修改和受影响的文件
+
+## 处理歧义
+
+**模糊描述：** 询问用户具体要求
+
+**范围不明：** 先搜索确定影响范围，再执行
+
+**冲突规则：** 说明冲突，询问优先级

package/doc-smith/references/document_structure_schema.md

@@ -0,0 +1,139 @@
+# 文档结构 Schema
+
+本参考定义了 `document_structure.yaml` 的完整 schema。
+
+## 完整的 YAML 结构
+
+```yaml
+project:
+  title: "项目名称"           # 必需：项目名称
+  description: "项目概述"     # 必需：项目简要描述
+
+documents:                    # 必需：文档对象数组
+  - title: "文档标题"         # 必需：文档标题
+    description: "简要摘要"   # 必需：此文档涵盖的内容
+    path: "/filename.md"      # 必需：相对于 .aigne/doc-smith/docs/ 的路径
+                              # 示例：/overview.md, /getting-started.md, /api/authentication.md
+    sourcePaths:              # 必需：源文件路径数组（相对路径，不使用 'workspace:' 前缀）
+      - "src/main.py"         # 为此文档内容提供信息的文件
+      - "README.md"           # 如果没有特定源文件则使用空数组 []
+    icon: "lucide:book-open"  # 仅顶层文档必需
+                              # 必须是有效的 Lucide 图标名称："lucide:icon-name"
+                              # 示例：lucide:book-open, lucide:settings, lucide:code
+                              # 嵌套文档省略此字段
+    children:                 # 可选：嵌套文档（相同结构）
+      - title: "嵌套文档"
+        description: "详细信息"
+        path: "/section/nested.md"
+        sourcePaths:
+          - "src/utils.py"
+        # 嵌套文档不需要 icon
+```
+
+## 字段详解
+
+### project
+- **title**：项目名称（字符串）
+- **description**：项目简要概述（字符串）
+
+### documents（数组）
+每个文档对象包含：
+
+- **title**（必需）：文档的显示标题
+- **description**（必需）：内容简要摘要
+- **path**（必需）：相对于 `.aigne/doc-smith/docs/` 的文件路径
+  - 必须以 `/` 开头
+  - 必须以 `.md` 结尾
+  - 可以包含子目录：`/api/endpoints.md`
+- **sourcePaths**（必需）：源文件路径数组
+  - 相对于工作区根目录的路径
+  - 不要包含 `workspace:` 前缀
+  - 如果没有特定源文件则使用 `[]`
+- **icon**（仅顶层文档必需）：Lucide 图标标识符
+  - 格式：`lucide:icon-name`
+  - 仅用于根级别的文档（不是子文档）
+  - 示例：`lucide:home`, `lucide:file-text`, `lucide:settings`
+  - 可用图标请参见 https://lucide.dev/icons
+- **children**（可选）：具有相同结构的嵌套文档数组
+  - 可以嵌套多层
+  - 子文档不需要 icons
+
+## 示例
+
+基本的 YAML 结构示例：
+
+### 扁平结构示例
+```yaml
+project:
+  title: "项目名称"
+  description: "项目简要描述"
+
+documents:
+  - title: "概述"
+    description: "项目介绍和核心概念"
+    path: "/overview.md"
+    sourcePaths:
+      - "README.md"
+    icon: "lucide:home"
+
+  - title: "快速开始"
+    description: "安装、配置和第一个示例"
+    path: "/getting-started.md"
+    sourcePaths:
+      - "docs/installation.md"
+    icon: "lucide:rocket"
+
+  - title: "API 参考"
+    description: "API 使用说明"
+    path: "/api.md"
+    sourcePaths:
+      - "src/api/"
+    icon: "lucide:code"
+```
+
+### 嵌套结构示例
+```yaml
+project:
+  title: "项目名称"
+  description: "项目简要描述"
+
+documents:
+  - title: "概述"
+    description: "项目介绍"
+    path: "/overview.md"
+    sourcePaths:
+      - "README.md"
+    icon: "lucide:home"
+
+  - title: "核心功能"
+    description: "主要功能模块说明"
+    path: "/features.md"
+    sourcePaths:
+      - "src/core/"
+    icon: "lucide:box"
+    children:
+      - title: "子功能 A"
+        description: "子功能详细说明"
+        path: "/features/feature-a.md"
+        sourcePaths:
+          - "src/feature-a/"
+
+      - title: "子功能 B"
+        description: "子功能详细说明"
+        path: "/features/feature-b.md"
+        sourcePaths:
+          - "src/feature-b/"
+```
+
+**注意**：选择扁平还是嵌套结构应基于 SKILL.md 中的判断标准，而非模仿示例。
+
+## 最佳实践
+
+1. **基于实际内容决策**：根据实际的源文件内容量和独立性选择结构，参考 SKILL.md 中的判断标准
+2. **避免内容重复**：如果子文档之间有重复内容，应该合并
+3. **逻辑层次**：在父主题下组织相关文档
+4. **清晰路径**：使用与文档标题匹配的描述性路径名称
+5. **相关源文件**：包含所有为文档内容提供信息的文件
+6. **合适的图标**：选择代表文档用途的图标（仅顶层文档需要）
+7. **控制深度**：避免嵌套过深（建议最多 2 层）
+8. **一致的描述**：保持描述简洁但信息丰富

package/doc-smith/references/document_update_guide.md

@@ -0,0 +1,193 @@
+# 文档更新执行指南
+
+## 三种反馈类型识别
+
+### 1. 全局语义修改（Global Semantic Changes）
+
+**识别特征：** 跨多个文档的规则、术语、风格变更。
+
+**处理方式：**
+1. 提取所有全局修改
+2. 遍历 `.aigne/doc-smith/docs/` 下所有文档
+3. 对每个文档应用修改
+4. 保持修改的一致性
+
+**典型模式：**
+- 术语替换："blocklet" → "Blocklet"
+- 风格调整：删除第一人称
+- 格式统一：代码块添加语言标识
+
+**来源：** 自然语言请求、Changeset 文件
+
+### 2. 局部结构性重写（Structural Rewrite Requests）
+
+**识别特征：** 需要补充、重写、重组特定章节。
+
+**处理方式：**
+1. 定位目标文档和章节
+2. 读取相关源文件和上下文
+3. 基于重写目标重新生成内容
+4. 替换原有章节，确保前后衔接
+
+**典型模式：**
+- 补充内容："添加环境要求章节"
+- 重组结构："合并分散的安装步骤"
+- 增强说明："补充错误码说明"
+
+**来源：** 自然语言请求、Changeset 文件
+
+### 3. 直接内容改写（PATCH）
+
+**识别特征：** 文档内的 `:::PATCH` 标记。
+
+**处理方式：**
+1. 扫描所有文档查找 `:::PATCH` 标记
+2. 读取 PATCH 内的修改指令
+3. 执行精确替换
+4. 删除整个 PATCH 标记
+
+**PATCH 标记格式：**
+```markdown
+::: PATCH
+修改说明或新内容
+:::
+```
+
+**来源：** 仅通过文档内标记（不会出现在 Changeset 文件中）
+
+## 三种输入方式处理
+
+### 方式 1：自然语言修改请求
+
+**检测：** 用户直接描述修改需求，无文件路径，无 PATCH 标记提及。
+
+**执行步骤：**
+1. 分析请求，识别反馈类型
+2. 确定影响范围（单文档 vs 多文档）
+3. 按识别的类型执行修改
+4. 记录所有修改的文件
+
+### 方式 2：Changeset 文件
+
+**检测：** 用户提供文件路径（通常是 `.md` 文件）。
+
+**执行步骤：**
+1. 读取 changeset 文件
+2. 理解所有修改请求
+3. 分类为全局修改、结构重写
+4. 按优先级执行：全局修改 → 结构重写
+5. 记录所有修改
+
+**重要：**
+- 格式自由，自然语言描述
+- 参见 `references\changeset_schema.md` 了解识别规则
+
+### 方式 3：文档内 PATCH 标记
+
+**检测：** 用户提到"PATCH 标记"或要求"应用 PATCH"。
+
+**执行步骤：**
+1. 扫描所有文档
+
+2. 对每个标记：
+  - 读取 PATCH 内的修改指令
+  - 理解并执行修改
+  - 删除整个 `:::PATCH ... :::` 标记
+  - 保存文档
+
+**PATCH 标记格式：**
+```markdown
+::: PATCH
+修改说明或新内容
+:::
+```
+
+## 更新执行流程
+
+### 步骤 1：检测文档状态
+
+```bash
+ls -la .aigne/doc-smith/docs/
+```
+
+- 不存在 → 告知用户使用生成流程（步骤 1-6）
+- 存在 → 继续更新流程
+
+### 步骤 2：识别输入类型
+
+根据用户消息判断：
+- 包含文件路径 → Changeset
+- 提到"PATCH 标记"或"应用 PATCH" → PATCH 方式
+- 其他 → 自然语言
+
+如果不确定，询问用户。
+
+### 步骤 3：解析更新请求
+
+- **自然语言：** 分析并分类为全局修改、结构重写或 PATCH
+- **Changeset：** 读取文件，提取全局修改和结构重写
+- **PATCH 标记：** 扫描文档，查找所有 `:::PATCH`
+
+### 步骤 4：应用修改
+
+**执行优先级：** 全局修改 → 结构重写 → PATCH
+
+**全局修改：**
+```bash
+# 获取所有文档
+find .aigne/doc-smith/docs/ -name "*.md"
+```
+对每个文档：
+- 读取内容
+- 应用规则（替换、删除、添加）
+- 保存修改
+
+**结构重写：**
+- 定位目标章节（使用标题或位置描述）
+- 读取相关源文件（如果需要）
+- 重新生成内容
+- 替换章节
+
+**PATCH：**
+- 精确定位
+- 直接替换
+- 删除标记
+
+### 步骤 5：展示变更摘要
+
+格式：
+```
+已完成文档更新：
+
+✓ 全局语义修改：N条规则应用到 M 个文档
+  - 规则描述（N处修改）
+
+✓ 结构重写：N个章节
+  - 文档名: 章节名
+
+✓ PATCH 应用：N处精确修改
+  - 文档名: 修改描述
+
+修改的文件：
+  - 文件路径
+  - ...
+```
+
+## 执行要点
+
+1. **理解意图：** 仔细分析修改请求，确定类型和范围
+2. **正确分类：** 准确识别是全局、重写还是 PATCH
+3. **优先级：** 严格按"全局 → 重写 → PATCH"顺序，避免冲突
+4. **一致性：** 全局修改必须应用到所有匹配位置
+5. **批量执行：** 一次性处理，减少读写次数
+6. **验证：** 修改后检查语法和链接
+7. **清晰反馈：** 详细列出所有修改
+8. **删除标记：** PATCH 应用后必须删除标记
+
+## 错误处理
+
+**位置不存在：** 展示最接近匹配，询问确认。
+
+**修改冲突：** 说明冲突原因，询问优先级。
+
+**结构不匹配：** 展示当前结构，询问如何处理。

package/doc-smith/references/structure_confirmation_guide.md

@@ -0,0 +1,133 @@
+# 文档结构确认指南
+
+本文档提供如何向用户展示文档结构并处理反馈的详细指南。
+
+## 目的
+
+这是避免浪费资源的关键检查点。在生成文档内容前，必须确保规划的结构符合用户需求。
+
+## 展示方式
+
+以清晰、易读的方式向用户展示规划的文档结构。
+
+### 必须包含的信息
+
+1. **文档总数**：让用户快速了解规模
+2. **文档层次结构**：顶层文档及其子文档
+3. **每个文档的标题、描述**：让用户理解每个文档的内容
+
+### 标准展示格式
+
+使用 emoji、编号和缩进来增强可读性：
+
+```
+📋 文档结构规划完成
+
+根据用户意图，我规划了以下 5 个文档：
+
+1. 📘 概述 (/overview.md)
+   - 项目介绍和核心概念
+
+2. 🚀 快速开始 (/getting-started.md)
+   - 安装、配置和第一个示例
+
+3. 💻 API 参考 (/api.md)
+   - API 使用说明
+   - 源文件：src/api/
+   └── 3.1 认证 (/api/authentication.md)
+       - 认证方式和示例
+   └── 3.2 端点 (/api/endpoints.md)
+       - 所有 API 端点详情
+
+4. ❓ FAQ (/faq.md)
+   - 常见问题解答
+
+5. 🔧 故障排查 (/troubleshooting.md)
+   - 常见问题和解决方案
+
+---
+
+[使用 AskUserQuestion 工具]
+问题：文档结构是否符合您的需求？
+选项：✅ 确认，开始生成文档
+```
+
+### 推荐的 Emoji 使用
+
+- 📘 概述/介绍
+- 🚀 快速开始
+- 💻 API/代码
+- 🔧 配置/工具
+- 📖 指南/教程
+- ❓ FAQ/帮助
+- 🏗️ 架构/设计
+- 🔍 故障排查
+- 📊 示例/演示
+- ⚙️ 配置/设置
+
+## 处理用户反馈
+
+识别用户意图并执行相应操作：
+
+### 反馈类型
+
+1. **删除文档**：从 document_structure.yaml 删除条目，如果是父文档则连同子文档一起删除
+2. **添加文档**：确定位置、title、description、path、sourcePaths 和 icon（如果是顶层文档）
+3. **调整层次**：合并/拆分子文档，或调整父子关系
+4. **修改内容范围**：更新 description 和 sourcePaths
+5. **确认无误**：进入步骤 6 生成文档内容
+
+### 操作要点
+
+- 每次修改后更新文档总数
+- 重新展示完整结构
+- 简要说明做了什么改动
+- 询问用户是否确认
+
+## 交互示例
+
+```
+Agent: 📋 文档结构规划完成
+[展示 5 个文档的结构]
+
+---
+
+[Agent 使用 AskUserQuestion 工具]
+问题：文档结构是否符合您的需求？
+选项：✅ 确认，开始生成文档
+
+---
+
+User: [选择 ✏️ Other] FAQ 和故障排查合并，API 参考不要拆分
+
+---
+
+Agent: 好的，我将进行以下调整：
+1. 合并 FAQ 和故障排查
+2. 合并 API 参考的子文档
+
+📋 更新后的文档结构
+[展示 3 个文档的结构]
+
+---
+
+[Agent 使用 AskUserQuestion 工具]
+问题：文档结构是否符合您的需求？
+选项：✅ 确认，开始生成文档
+
+---
+
+User: ✅ 确认，开始生成文档
+
+---
+
+Agent: 收到确认，开始生成文档内容...
+```
+
+## 关键原则
+
+1. **每次修改后都要重新展示完整结构** - 不要只说"已修改"
+2. **支持多轮调整** - 耐心处理用户的每一次反馈
+3. **用户确认后才进入步骤 6** - 绝对不要在确认前开始生成内容
+4. **清晰传达变化** - 简要说明改动内容
+5. **理解用户意图** - 反馈可能不够精确，需要确认理解是否正确