@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/skills/doc-smith/references/document-structure-schema.md

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

package/skills/doc-smith/references/patch-guide.md

@@ -0,0 +1,96 @@
+# PATCH 标记处理指南
+
+## 核心定位
+
+PATCH 是**文档内的确定性文本改动标记**，只执行准确的变更。
+
+**关键特点**：
+- 精确指定修改内容
+- 执行后必须删除标记
+- 优先级高于结构重写
+
+## PATCH 标记格式
+
+### 格式 1：替换内容（Original + Revised）
+
+```markdown
+::: PATCH
+# Original
+旧内容
+
+# Revised
+新内容
+:::
+```
+
+### 格式 2：插入内容
+
+```markdown
+::: PATCH
+# Insert After: "## 章节标题"
+
+新增的内容
+:::
+```
+
+支持的插入指令：
+- `# Insert After: "锚点"` - 在锚点后插入
+- `# Insert Before: "锚点"` - 在锚点前插入
+
+### 格式 3：删除内容
+
+```markdown
+::: PATCH
+# Delete
+
+要删除的内容
+:::
+```
+
+## 执行流程
+
+### 1. 扫描 PATCH
+
+使用 Grep 查找所有 PATCH 标记：
+
+```bash
+pattern: ":::\s*PATCH"
+path: docs/
+output_mode: files_with_matches
+```
+
+### 2. 执行 PATCH
+
+对每个 PATCH 块：
+1. 解析 PATCH 类型（替换/插入/删除）
+2. 定位目标位置
+3. 执行变更
+4. **删除整个 `::: PATCH ... :::` 块**
+
+### 3. 处理错误
+
+| 错误类型 | 处理方式 |
+|---------|---------|
+| **Original 不存在** | 展示最接近内容，询问用户 |
+| **多个匹配** | 列出所有匹配位置，询问用户 |
+| **锚点不存在** | 展示文档结构，询问用户 |
+
+## 执行要点
+
+- **优先级**：PATCH 先于结构重写执行
+- **批量处理**：一次性扫描所有文档
+- **必须删除标记**：执行后删除 `::: PATCH ... :::` 块，避免重复执行
+
+## 与 Changeset 的关系
+
+- PATCH 直接标记在文档正文中，不要求写在 Changeset 文件中
+- 执行顺序：`读取 Changeset → 扫描 PATCH → 执行 PATCH → 应用 Changeset 修改`
+
+## 输出摘要
+
+```markdown
+✓ PATCH 应用：N 处精确修改
+  - overview.md: 修正定位说明
+  - quick-start.md: 新增环境要求章节
+  - api.md: 删除过时说明
+```

package/skills/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. **理解用户意图** - 反馈可能不够精确，需要确认理解是否正确

package/skills/doc-smith/references/structure-planning-guide.md

@@ -0,0 +1,149 @@
+# 文档结构规划指南
+
+**文件位置**: `planning/document-structure.yaml`
+**权限**: AI 可重写/更新，可重算
+
+本文档提供如何规划文档结构和决定是否拆分的详细指南。
+
+## 核心原则
+
+**规划必须依据用户意图**
+
+在规划文档结构时，持续参考 `intent/user-intent.md` 中的内容：
+- **目标用户决定文档类型**：技术开发者需要 API 参考，最终用户需要使用指南
+- **使用场景决定文档范围**：快速上手只需核心功能，深入学习才需要完整架构
+- **侧重点决定详细程度**：使用指南型文档重实践轻原理，参考手册型文档要全面覆盖
+
+## 常见问题及避免方法
+
+### ❌ 不看用户意图，直接按代码结构规划
+
+导致文档大而全，不聚焦用户需求。应该先参考 intent/user-intent.md，只为用户需要的模块创建文档。
+
+### ❌ 规划了用户不需要的文档
+
+浪费资源生成无用文档。应该严格按照 intent/user-intent.md 中的"文档侧重点"规划。
+
+### ❌ 文档粒度与用户需求不匹配
+
+顺序任务应合并成单一文档，独立模块才考虑拆分。
+
+## 规划策略
+
+### 1. 最小必要原则
+
+只规划用户意图中明确需要的文档。
+
+**检查清单**：
+- [ ] 这个文档是否在 intent/user-intent.md 的使用场景中？
+- [ ] 这个文档是否符合文档侧重点？
+- [ ] 如果去掉这个文档，用户会缺失重要信息吗？
+
+### 2. 聚焦核心场景
+
+优先覆盖用户的主要使用场景。
+
+**优先级排序**：
+1. intent/user-intent.md 中明确提到的场景
+2. 对目标用户最重要的功能
+3. 可选的高级特性
+
+### 3. 适度深度
+
+根据用户需求决定嵌套层级。
+
+**深度指南**：
+- 最终用户：扁平结构（1 层）
+- 开发者：适度嵌套（1-2 层）
+- 复杂系统：合理嵌套（2-3 层）
+
+## 拆分判断标准
+
+### 应该拆分为子文档
+
+**必须满足以下 3-4 个条件**：
+
+1. **内容量大**
+   - 父主题包含 4 个以上主要章节
+   - 单页阅读体验差（预计超过 500 行）
+
+2. **独立性强**
+   - 每个子主题都有丰富的独立内容
+   - 至少 3 个段落或 3+ 小节
+   - 可以独立理解，不强依赖其他子主题
+
+3. **无重复**
+   - 子文档之间没有明显内容重复
+   - 子文档与父文档之间没有明显内容重复
+
+4. **独立查阅**
+   - 用户经常需要单独查阅某个子主题
+   - 而非顺序通读全部内容
+
+**示例：应该拆分**
+
+API 参考拆分为用户、订单、支付三个子文档，因为每个类别内容丰富、相对独立、开发者会单独查阅。
+
+### 不应该拆分
+
+**有以下任一情况**：
+
+1. **子文档内容单薄**
+   - 预计少于 3 段内容
+   - 没有足够的源文件支持
+
+2. **存在内容重复或相互依赖**
+   - 子文档之间有明显的内容重复
+   - 必须同时阅读多个子文档才能理解
+
+3. **顺序完成的步骤**
+   - 用户需要按顺序完成所有步骤
+   - 如：安装 → 配置 → 首次运行
+
+4. **拆分后父文档变空壳**
+   - 父文档只剩导航链接
+   - 没有实质内容
+
+**示例：不应该拆分**
+
+快速开始不应拆分为安装、配置、首次运行三个子文档，因为这是顺序步骤，用户需要连续完成，拆分反而增加导航负担。应该合并为单一文档。
+
+## 结构评估清单
+
+在创建 document-structure.yaml 之前，对每个可能的嵌套结构使用此清单：
+
+### 支持拆分的信号
+
+满足 3+ 个时考虑拆分：
+
+- [ ] 父主题源文件内容丰富，预计生成 4+ 个主要章节
+- [ ] 每个子主题都有足够的源文件和独立内容（预计 3 段或 3+ 小节）
+- [ ] 子主题之间相对独立，用户可能单独查阅（如不同的 API 类别）
+- [ ] 工作区中已有按模块组织的源文件结构
+
+### 反对拆分的信号
+
+有 2+ 个时保持扁平：
+
+- [ ] 子主题源文件内容单薄，预计每个少于 3 段
+- [ ] 子主题之间有明显的顺序依赖或内容重复
+- [ ] 用户需要按顺序完成（如安装 → 配置 → 首次运行）
+- [ ] 源文件没有明确的模块划分
+
+### 决策
+
+综合评估后选择最适合用户的结构。
+
+## 平衡原则
+
+**优先考虑用户体验，根据实际内容量和用户需求决定结构。**
+
+当难以决定时，问自己：
+1. 这个结构对用户友好吗？
+2. 用户能快速找到需要的信息吗？
+3. 是否有不必要的导航层级？
+
+**经验法则**：
+- 有疑虑时，选择更简单的结构
+- 扁平优于嵌套
+- 少即是多

package/skills/doc-smith/references/update-workflow.md

@@ -0,0 +1,108 @@
+# 文档更新执行流程
+
+## 流程概览
+
+```
+检测文档状态 → 识别输入类型 → 解析修改请求 → 执行修改 → 展示摘要
+```
+
+## 步骤 1：检测文档状态
+
+检查 `docs/` 目录：
+- **不存在** → 告知用户先执行文档生成流程
+- **存在** → 继续更新流程
+
+## 步骤 2：识别输入类型
+
+根据用户消息判断输入类型：
+
+| 输入类型 | 识别特征 | 下一步 |
+|---------|---------|--------|
+| **Changeset 文件** | 用户提供 `.md` 文件路径 | 读取文件，参见 [changeset-guide.md](changeset-guide.md) |
+| **PATCH 标记** | 用户提到"PATCH 标记"或"应用 PATCH" | 扫描文档，参见 [patch-guide.md](patch-guide.md) |
+| **自然语言** | 直接描述修改需求 | 分析并分类为下列类型之一 |
+
+### 自然语言修改的分类
+
+分析用户请求，识别修改类型：
+
+**全局语义修改** - 跨多个文档的规则
+- 关键词：`所有`、`统一`、`全部`、`删除`
+- 示例：`"所有 API 改为 API 接口"`、`"删除所有第一人称"`
+
+**局部结构重写** - 特定章节的补充或重组
+- 关键词：`补充`、`添加`、`重写`、`重组`
+- 示例：`"overview.md 补充项目背景"`、`"快速开始添加环境要求章节"`
+
+**PATCH 级修改** - 用户提供精确的替换内容
+- 特征：给出原文和修订文本
+- 建议：引导用户使用 PATCH 标记格式
+
+## 步骤 3：执行修改
+
+### 执行优先级
+
+严格按以下顺序执行，避免冲突：
+
+```
+1. 读取 Changeset（如果有）→ 建立全局约束
+2. 扫描并执行所有 PATCH → 确定性变更
+3. 应用全局语义修改 → 跨文档规则
+4. 执行局部结构重写 → 章节级改写
+5. 一致性检查 → 术语、链接、格式
+```
+
+### 冲突处理原则
+
+当多个修改类型发生冲突时：
+
+| 冲突场景 | 处理原则 |
+|---------|---------|
+| **PATCH vs 重写** | PATCH 先执行，重写在 PATCH 结果基础上进行 |
+| **全局 vs 局部** | 局部（更具体）优先，在摘要中说明覆盖 |
+| **澄清 vs 其他** | 澄清（需求理解）优先级最高 |
+
+## 步骤 4：展示变更摘要
+
+执行完成后，使用以下格式展示摘要：
+
+```markdown
+已完成文档更新：
+
+✓ 全局语义修改：N 条规则应用到 M 个文档
+  - [规则描述]（X 处修改）
+
+✓ 局部结构重写：N 个章节
+  - [文档名]: [章节名]
+
+✓ PATCH 应用：N 处精确修改
+  - [文档名]: [修改描述]
+
+修改的文件：
+  - [文件路径 1]
+  - [文件路径 2]
+  ...
+
+[如有验收标准] 验收对齐：
+  ☑ [标准 1]
+  ☑ [标准 2]
+  ☐ [未满足项] - [原因和建议]
+```
+
+## 执行要点
+
+- **理解意图**：仔细分析修改请求，确定类型和范围
+- **完整读取**：编辑时文档时，为了避免修改遗漏，确保读取文档的全部内容
+- **批量执行**：同类修改一次性处理，减少读写
+- **保持一致**：全局修改必须应用到所有匹配位置
+- **验证完整**：修改后检查语法、链接、术语一致性
+- **清晰反馈**：详细列出所有修改，说明冲突取舍
+
+## 错误处理
+
+| 错误类型 | 处理方式 |
+|---------|---------|
+| **位置不存在** | 展示最接近匹配，询问确认 |
+| **修改冲突** | 说明冲突原因，询问优先级 |
+| **结构不匹配** | 展示当前结构，询问如何处理 |
+| **信息不足** | 标注需澄清的问题，不要编造 |