@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/skills/doc-smith/ai/intent/sources-improve.md

@@ -0,0 +1,290 @@
+# Source 类型重构功能意图
+
+## 功能概述
+
+重构 DocSmith workspace 的数据源接入方式，支持两种启动路径和统一的多数据源配置，以满足不同的文档管理场景。
+
+## 功能意图
+
+当前 DocSmith 将源代码仓库作为 git submodule 添加到 workspace，这种方式导致一个架构限制：**无法让产品仓库管理自己的文档**。
+
+具体问题：
+- 如果 docs workspace 放在产品仓库内，又把产品仓库作为自己的 submodule，会形成循环嵌套
+- 这与"项目自己管理自己的文档"的长期目标冲突
+- DocSmith 应该是项目自动构建的一部分，而非独立存在
+
+解决思路：
+- **两种启动路径**：根据用户启动位置自动选择合适的初始化流程
+- **统一的 schema**：无论哪种方式启动，config.yaml 格式一致
+- **多数据源支持**：可以添加多个 local-path 或 git-clone 类型的数据源
+
+## 两种启动路径
+
+### 路径 A：项目内启动（推荐）
+
+**触发条件**：在已有的 git 仓库中执行 `docsmith init`
+
+**初始化行为**：
+1. 创建 `.docsmith/` 子目录
+2. 在 `.docsmith/` 中执行 `git init`（独立仓库）
+3. 将 `.docsmith/` 添加为外层仓库的 submodule
+4. 自动配置主数据源为 `local-path: "../"`
+
+**目录结构**：
+```
+product-repo/                    # 产品仓库（外层）
+├── .gitmodules                 # .docsmith 作为 submodule
+├── src/                        # 产品源代码
+└── .docsmith/                  # DocSmith workspace（独立 git 仓库）
+    ├── .git/                   # 独立的 git 历史
+    ├── config.yaml             # sources 包含 local-path: "../"
+    ├── intent/
+    ├── planning/
+    └── docs/
+```
+
+**Git 关系**：
+```
+product-repo  ──submodule──>  .docsmith
+
+文件引用（非 git 关系）：
+.docsmith  ──local-path "../"──>  product-repo 的文件
+```
+
+**适用场景**：
+- 项目团队自己维护文档
+- DocSmith 作为项目构建的一部分
+- 希望文档版本与代码版本同步
+
+### 路径 B：独立启动
+
+**触发条件**：在空目录或非 git 目录中执行 `docsmith init`
+
+**初始化行为**：
+1. 在当前目录初始化 workspace
+2. 执行 `git init`
+3. 询问用户添加数据源（git-clone URL）
+4. 克隆数据源到 `.cache/` 目录
+
+**目录结构**：
+```
+docs-workspace/                  # DocSmith workspace
+├── .git/
+├── config.yaml                 # sources 包含 git-clone 配置
+├── .cache/
+│   └── main-project/           # 克隆的数据源（gitignore）
+├── intent/
+├── planning/
+└── docs/
+```
+
+**适用场景**：
+- 快速试用 DocSmith
+- 纯文档项目
+- CI/CD 临时构建环境
+
+## 统一的 Config Schema
+
+**两种启动路径生成相同格式的 config.yaml**：
+
+```yaml
+# config.yaml
+
+# 数据源列表（支持多个）
+sources:
+  # 主数据源
+  - name: "main-project"
+    type: local-path              # 或 git-clone
+    path: "../"                   # local-path 专用
+
+  # 参考数据源（可选）
+  - name: "aigne-framework"
+    type: git-clone
+    url: "https://github.com/ArcBlock/aigne-framework.git"
+    ref: "main"                   # branch/tag/commit，默认 "main"
+    cachePath: ".cache/aigne-framework"
+
+  - name: "blocklet-sdk"
+    type: git-clone
+    url: "https://github.com/ArcBlock/blocklet-sdk.git"
+    ref: "v1.2.0"
+```
+
+## 核心能力
+
+### 1. 两种数据源类型
+
+| 类型 | 用途 | 配置字段 |
+|------|------|---------|
+| `local-path` | 引用本地目录 | `path`（相对路径） |
+| `git-clone` | 克隆远程仓库 | `url`, `ref`, `cachePath` |
+
+### 2. 启动路径自动检测
+
+```
+docsmith init
+  ↓
+检测当前目录
+  ↓
+├─ 是 git 仓库 → 项目内启动
+│   ├─ 创建 .docsmith/ 子目录
+│   ├─ git init（独立仓库）
+│   ├─ 添加为 submodule
+│   └─ 配置 local-path: "../"
+│
+└─ 非 git 仓库 → 独立启动
+    ├─ 在当前目录初始化
+    ├─ git init
+    ├─ 询问数据源 URL
+    └─ 配置 git-clone
+```
+
+### 3. 多数据源支持
+
+无论哪种启动路径，都可以后续添加更多数据源：
+```bash
+docsmith add-source https://github.com/ArcBlock/aigne-framework.git
+docsmith add-source ../another-local-project --type local-path
+```
+
+### 4. Workspace 目录名称
+
+项目内启动时，固定使用 `.docsmith/`：
+- 隐藏目录，对项目侵入最小
+- 固定名称，无需配置
+- 检测简单：`.docsmith/config.yaml` 存在即为已初始化
+
+### 5. 历史独立
+
+项目内启动时，`.docsmith/` 是独立的 git 仓库：
+- 文档提交不污染产品仓库历史
+- 通过 submodule 关联，产品仓库只记录指向的 commit
+- DocSmith 封装 submodule 操作，降低用户门槛
+
+## 输入输出
+
+### 输入
+
+- 自动检测：
+  - 当前目录是否为 git 仓库（决定启动路径）
+
+- 项目内启动：
+  - 无需额外输入（自动配置）
+
+- 独立启动：
+  - 数据源 URL（必需）
+  - 分支/tag/commit（可选，默认 main）
+
+- 添加数据源：
+  - URL 或本地路径
+  - 数据源名称（可选，自动从 URL 推断）
+
+### 输出
+
+- config.yaml 中的 sources 配置
+- 根据启动路径执行相应的 git 操作
+- 初始化完成后的 workspace 结构
+
+## 约束条件
+
+### 必须遵循的规范
+
+1. **config.yaml schema**：
+   ```yaml
+   sources:
+     - name: string              # 数据源名称
+       type: "local-path" | "git-clone"
+
+       # local-path 专用
+       path: string              # 相对路径
+
+       # git-clone 专用
+       url: string               # 仓库 URL
+       ref: string               # branch/tag/commit，默认 "main"
+       cachePath: string         # 克隆位置，默认 ".cache/{name}"
+   ```
+
+2. **项目内启动要求**：
+   - workspace 目录固定为 `.docsmith/`
+   - 必须初始化为独立 git 仓库
+   - 必须添加为外层仓库的 submodule
+
+3. **git-clone 要求**：
+   - cachePath 目录必须加入 .gitignore
+   - 支持通过 ref 字段锁定版本
+
+### 职责边界
+
+- **必须执行**：
+  - 自动检测启动路径
+  - 项目内启动时自动添加 submodule
+  - git-clone 时自动克隆到 cache 目录
+  - 验证路径/URL 有效性
+
+- **不应执行**：
+  - 不创建远程仓库（用户自行创建）
+  - 不推送到远程（用户自行推送）
+  - 不修改外层仓库的其他文件（除 .gitmodules）
+
+- **协作方式**：
+  - 与现有 workspace 初始化流程集成
+  - 封装 submodule 操作，降低用户门槛
+
+## 预期结果
+
+### 成功标准
+
+1. **路径自动选择**：根据启动位置自动决定初始化流程
+2. **schema 统一**：两种路径生成相同格式的 config.yaml
+3. **多数据源**：支持添加多个 local-path 或 git-clone 数据源
+4. **历史独立**：项目内启动时文档有独立的 git 历史
+5. **操作简单**：用户无需直接操作 submodule
+
+## 错误处理
+
+### 常见错误
+
+1. **submodule 添加失败**：外层仓库不是 git 仓库或权限问题
+2. **目录已存在**：`.docsmith/` 目录已存在
+3. **网络问题**：git-clone 无法访问远程仓库
+4. **URL 无效**：git-clone 的 URL 格式错误或仓库不存在
+5. **路径无效**：local-path 指向的路径不存在
+
+### 处理策略
+
+1. **submodule 失败**：提供手动添加的命令指引
+2. **目录存在**：检测是否为有效 workspace，是则提示已初始化，否则报错
+3. **网络问题**：提示检查 URL 和网络连接，支持重试
+4. **路径无效**：提示检查路径，建议正确的相对路径格式
+
+## 实现方式
+
+### 1. 修改 workspace-initialization.md
+
+- 新增启动路径检测逻辑
+- 分支处理两种启动路径的初始化流程
+- 统一 config.yaml 生成逻辑
+
+### 2. config.yaml schema 更新
+
+- `source` 改为 `sources`（数组）
+- 每个数据源包含 `name`, `type` 及类型专属字段
+- 支持 local-path 和 git-clone 两种类型
+
+### 3. 封装 submodule 操作
+
+提供高级命令，用户无需直接操作 submodule：
+- `docsmith init`：自动处理 submodule 创建和添加
+- `docsmith commit`：在 workspace 中提交
+- `docsmith push`：推送 workspace
+- `docsmith add-source`：添加新数据源
+
+### 4. 迁移策略
+
+对于现有 workspace：
+- 旧的 `source` 单数据源配置自动转换为 `sources` 数组
+- 保持向后兼容
+
+---
+
+**注意**：本文档描述功能意图，不包含具体实现细节。

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

@@ -0,0 +1,171 @@
+# Changeset 文件理解与执行指南
+
+## 核心定位
+
+Changeset 是**批量反馈的结构化载体**，格式自由，自然语言描述。
+用户通过 Changeset 提出的修改请求都直接执行， 不需要向用户二次确认。
+ChangeSet 文件应该在仓库中保留，记录历史修改要求。
+
+**包含内容**：
+- Summary（摘要）
+- Global Semantic Changes（全局语义修改）
+- Structural Rewrite Requests（局部结构性重写）
+- Additional Data/References（补充资料）
+- Clarifications/Corrections（需求澄清）
+- Acceptance Criteria（验收标准）
+
+**注意**：PATCH 推荐直接标记在文档正文中，不要求写在 changeset 中。
+
+## 六大类型
+
+### 0. Summary（摘要）
+
+用 1–3 句说明变更范围与重点。
+
+**要点**：
+- 用于规划步骤与排序
+- 不提供位置锚点时，不要扩大修改范围
+- 优先依赖下面更具体的条目
+
+**示例**：`本次为全局语义调整 + 局部重写：统一术语，补充快速开始章节`
+
+---
+
+### 1. Global Semantic Changes（全局语义修改）
+
+跨文档的术语、风格、命名一致性修改。
+
+**典型场景**：术语统一、风格调整、叙述视角统一、格式规范。
+
+**要点**：
+- 优先级高：先于局部改写执行
+- 避免过度改写：只做最小必要修改
+- 冲突时以更具体的局部要求为准
+
+**示例**：
+```
+1. 术语统一："API" → "API 接口"、"blocklet" → "Blocklet"
+2. 风格调整：删除第一人称，保持中立第三人称
+3. 格式规范：代码块统一添加语言标识符
+```
+
+---
+
+### 2. Structural Rewrite Requests（局部结构性重写）
+
+对特定章节/段落提出重写或重构请求，对文档结构提出调整请求，描述目标但不给出确定文本。
+
+如果涉及文档结构的修改，需要参考以下信息：
+- 文档结构数据结构参考： `document-structure-schema.md`
+- 向用户展示确认文档结构请参考： `structure-confirmation-guide.md`
+
+阅读参考文件需在 task 中记录，在执行到相应 task 时阅读这些参考文件。
+
+**位置锚点**：章节标题、段落关键词、文件路径。
+
+**推荐字段**（自然语言）：
+- Target（目标位置）
+- Issue（问题描述）
+- Rewrite Goal（改写目标）
+- Suggested Outline（可选）
+- Materials（可选）
+
+**要点**：
+- 只修改目标范围，不扩散到无关章节
+- 锚点不精确时，先检索定位最匹配段落
+- PATCH 优先：先执行 PATCH，再在结果基础上重写
+- 保持链接、术语、结构一致性
+
+**示例**：
+```
+Target: overview.md, Introduction 章节
+Issue: 缺少项目背景
+Rewrite Goal: 补充项目定位、核心价值、适用场景
+```
+
+---
+
+### 3. Additional Data / References（补充资料）
+
+新增或修正的参考信息，提供更准确的上下文。
+
+**典型场景**：附加文档、术语表更新、产品说明、纠正错误。
+
+**要点**：
+- 作为参考上下文，用于修正事实与补齐遗漏
+- 只在与现有内容矛盾或能显著提升准确性时才改
+- 信息不足时标注问题，不要编造
+
+**示例**：
+```
+1. 术语表更新：`Workspace` → 独立的文档工作空间
+2. 参考文档：/path/to/api-v2.md
+```
+
+---
+
+### 4. Clarifications / Corrections（需求澄清）
+
+对最初目标、范围、约束、受众等的理解修正，改变判断标准。
+
+**典型场景**：受众变更、输出形态澄清、语气调整、范围修正。
+
+**要点**：
+- **最高优先级**：覆盖旧的隐含前提
+- 大范围重构时，优先调整入口段和目录结构
+- 与其他类型冲突时，以澄清为准
+- 一旦存在，必须重新审视全文是否存在与之冲突的内容，但只允许进行最小必要修改，不得引入无关变更。
+
+**示例**：
+```
+1. 受众修正：从技术开发者改为产品经理
+2. 输出澄清："全自动"指 patch 自动合并，非跳过人工审核
+3. 语气调整：从营销宣传改为朴实技术说明
+```
+
+---
+
+### 5. Acceptance Criteria（验收标准）
+
+判断"是否改对了"的检查清单，逐条勾选。
+
+**要点**：
+- 生成完成后必须自检，并在摘要中逐条对齐
+- 未满足项需说明原因和下一步建议
+
+**示例**：
+```
+- [ ] 全局术语统一：API、Blocklet、Workspace 一致
+- [ ] 快速开始章节已补充环境要求
+- [ ] 文档无重复段落、无矛盾
+- [ ] 所有链接有效
+- [ ] 代码块都有语言标识符
+```
+
+---
+
+## 执行顺序
+
+```
+1. 找到 changeset 文件 → 提取用户信息中的文件信息，使用 pattern 搜索 changeset 文件
+1. 读取 changeset 文件 → 建立全局约束
+2. 扫描文档 → 定位所有 PATCH
+3. 执行 PATCH → 确定性变更
+4. 应用全局语义修改 → 遍历所有文档
+5. 执行局部结构重写 → 利用 Additional Data
+6. 一致性检查 → 术语、风格、结构
+7. 输出摘要 → 对齐 Acceptance Criteria
+```
+
+## 冲突处理
+
+| 冲突类型 | 处理原则 |
+|---------|---------|
+| **澄清 vs 其他** | 澄清优先（最高优先级） |
+| **全局 vs 局部** | 局部优先（更具体） |
+| **PATCH vs 重写** | PATCH 先执行 |
+| **规则冲突** | 询问用户 |
+
+## 处理歧义
+
+遇到模糊描述、范围不明、规则冲突时：先搜索定位，说明问题，询问用户，不要编造。

package/skills/doc-smith/references/document-content-guide.md

@@ -0,0 +1,214 @@
+# 文档内容生成指南
+
+本指南定义了生成 markdown 文档时的内容要求和格式规范。
+
+## 基本要求
+
+为结构中的每个文档在 `docs/` 目录中创建文档文件夹和文件：
+- 使用 YAML 中的 `path` 创建文件夹
+- 生成 `.meta.yaml` 元信息文件
+- 生成语言版本的 markdown 文件
+- 从 `sourcePaths` 提取信息
+- 编写清晰、结构化的内容
+- **在生成文档内容时主动添加图片**（参见"媒体资源"章节）
+
+## 文档生成步骤
+
+### 6.1 读取配置
+
+读取 `config.yaml` 获取输出语言(locale)：
+
+### 6.2 使用 saveDocument 工具
+
+**重要**：新增文档时，必须使用 `saveDocument` 工具，不要手动创建文件和文件夹。
+**工具功能**：
+- 自动创建文档文件夹（`docs/overview/`）
+- 自动生成 `.meta.yaml`：
+- 自动保存语言文件（`docs/overview/zh.md`）
+
+### 6.3 编辑已有文档
+
+直接使用 Edit 工具修改对应的语言文件：
+### 6.4 批量生成
+
+为提高效率，批量生成多个文档内容，然后批量调用 saveDocument。
+
+## 导航链接
+
+在每个文档中添加导航链接，引导用户在文档之间流畅跳转。
+只能链接生成的其他文档，不能链接到工作目录中的 markdown 文件，文档发布后会导致无法访问。
+导航链接应该使用文档结构中文档的 `path`
+
+### 文档开头导航
+
+在文档正文开始前添加：
+- **前置条件**：阅读本文档前建议先了解的内容
+- **父主题**：当前文档所属的上级主题
+
+### 文档结尾导航
+
+在文档末尾添加：
+- **相关主题**：与当前文档相关的其他文档
+- **下一步**：建议阅读的后续内容
+- **子文档**：当前文档包含的子主题列表
+
+## 媒体资源
+
+### 前置准备：确定文档和媒体的位置关系
+
+**在开始生成文档前，必须完成以下步骤：**
+
+#### 1. 确定文档输出目录
+
+从 `planning/document-structure.yaml` 的文档配置中读取，文档输出目录固定为：`docs/`
+
+#### 2. 查找所有媒体文件
+
+执行以下命令查找工作区中的所有媒体文件：
+
+```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`
+
+#### 3. 图片路径格式
+
+**sources 中的图片使用绝对路径**：
+
+对于数据源中的图片，使用 `/sources/` 开头的绝对路径格式：
+
+```
+/sources/<path-to-image>
+```
+
+**示例**：
+- 图片路径：`modules/sources/assets/run/screenshot.png`
+- 文档中引用：`![截图](/sources/assets/run/screenshot.png)`
+
+**注意**：
+- 直接使用在 sources 目录下看到的路径
+- 不需要计算相对路径层级，统一使用绝对路径
+- 路径区分大小写
+- 检查和发布阶段会自动解析并处理图片路径
+
+### 生成文档时的图片处理
+
+在编写每个文档的内容时，必须主动添加图片以增强文档的可读性和专业性。
+
+#### 1. 图片分类与要求
+
+**A. 技术图表（必须生成）**
+
+以下类型的内容**必须包含相应的技术图表**，没有已有图片时必须生成 AFS Image Slot：
+
+- **架构说明** → 架构图（系统架构、模块关系、组件结构）
+- **流程说明** → 流程图（业务流程、数据流向、状态转换）
+- **时序说明** → 时序图（交互时序、调用链路）
+- **概念解释** → 概念图（概念关系、层次结构）
+- **数据结构** → 数据模型图（类图、ER 图）
+
+**B. 应用截图（必须使用已有）**
+
+以下类型必须使用工作区中的已有截图，因为必须使用真实的应用截图：
+
+- **界面介绍** → UI 截图
+- **操作步骤** → 操作演示截图
+- **功能展示** → 功能界面截图
+
+**强制性要求：**
+
+1. **技术文档必须包含技术图表**：
+   - 架构文档：至少 1 个架构图
+   - API 文档：至少 1 个时序图或流程图
+   - 概念说明：至少 1 个概念图
+   - 数据模型：至少 1 个数据结构图
+
+2. **用户指南需要包含应用截图**：
+   - 操作指南：每个主要操作步骤至少 1 张截图
+   - 功能介绍：每个功能至少 1 张界面截图
+
+3. **综合文档建议配比**：
+   - 技术图表：1-3 个
+   - 应用截图：1-2 个
+
+#### 2. 图片处理流程
+
+**对于应用截图（B 类）：**
+
+1. 只能从前置准备的查找结果中匹配图片
+2. 根据文件名判断用途（如 login.png、dashboard.png、settings.png）
+3. 使用绝对路径格式引用：`![截图说明](/sources/assets/screenshot.png)`
+4. 如果仓库未提供相关截图，可以不展示
+
+**对于技术图表（A 类）：**
+
+1. 检查是否有对应的技术图表（架构图、流程图等）
+2. 如果没有，**必须生成 AFS Image Slot**（不是可选）
+3. 即使有应用截图，也不能用应用截图替代技术图表
+
+**关键区别：**
+- ❌ 错误：架构说明章节使用应用截图代替架构图
+- ✅ 正确：架构说明章节生成架构图 slot，另外可以添加应用截图作为补充
+
+#### 3. 生成 AFS Image Slot
+
+``` text AFS Image Slot Instructions
+
+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：**
+
+1. 文档内容需要技术图表（架构图、流程图、时序图等）
+2. 工作区中没有对应的技术图表
+
+**AFS Image Slot 不能用于**
+
+1. 应用界面必须使用真实截图，不能用 Slot 生成虚构的界面
+
+
+### 图片使用检查清单
+
+生成每个文档时，确认以下项目：
+
+**技术图表检查：**
+- [ ] 架构说明章节是否包含架构图？（没有则生成 slot）
+- [ ] 流程说明章节是否包含流程图？（没有则生成 slot）
+- [ ] 时序说明章节是否包含时序图？（没有则生成 slot）
+- [ ] 概念解释章节是否包含概念图？（没有则生成 slot）
+
+**应用截图检查：**
+- [ ] 是否有可用的应用截图可以引用？
+- [ ] 引用路径是否使用正确的绝对路径格式？
+
+**数量检查：**
+- [ ] 技术文档是否至少包含 1 个技术图表？
+- [ ] 用户指南是否包含足够的应用截图？
+
+## 内容组织原则
+
+1. **层次清晰**：使用恰当的标题层级（H1-H6）
+2. **段落简洁**：每个段落专注于单一主题
+3. **描述丰富**：每个段落有详细描述，帮助用户理解主题
+4. **列表使用**：用列表组织并列信息
+5. **强调重点**：使用粗体、引用等方式突出重要信息