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

package/doc-smith/references/structure_planning_guide.md

@@ -0,0 +1,146 @@
+# 文档结构规划指南
+
+本文档提供如何规划文档结构和决定是否拆分的详细指南。
+
+## 核心原则
+
+**规划必须依据用户意图**
+
+在规划文档结构时，持续参考 `user_intent.md` 中的内容：
+- **目标用户决定文档类型**：技术开发者需要 API 参考，最终用户需要使用指南
+- **使用场景决定文档范围**：快速上手只需核心功能，深入学习才需要完整架构
+- **侧重点决定详细程度**：使用指南型文档重实践轻原理，参考手册型文档要全面覆盖
+
+## 常见问题及避免方法
+
+### ❌ 不看用户意图，直接按代码结构规划
+
+导致文档大而全，不聚焦用户需求。应该先参考 user_intent.md，只为用户需要的模块创建文档。
+
+### ❌ 规划了用户不需要的文档
+
+浪费资源生成无用文档。应该严格按照 user_intent.md 中的"文档侧重点"规划。
+
+### ❌ 文档粒度与用户需求不匹配
+
+顺序任务应合并成单一文档，独立模块才考虑拆分。
+
+## 规划策略
+
+### 1. 最小必要原则
+
+只规划用户意图中明确需要的文档。
+
+**检查清单**：
+- [ ] 这个文档是否在 user_intent.md 的使用场景中？
+- [ ] 这个文档是否符合文档侧重点？
+- [ ] 如果去掉这个文档，用户会缺失重要信息吗？
+
+### 2. 聚焦核心场景
+
+优先覆盖用户的主要使用场景。
+
+**优先级排序**：
+1. 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/doc-smith/references/user_intent_guide.md

@@ -0,0 +1,172 @@
+# 用户意图推断指南
+
+本文档提供如何推断和生成用户意图的详细指南。
+
+## 推断内容
+
+基于工作区内容推断以下三个方面：
+
+### 1. 目标用户
+
+判断文档的主要受众（技术开发者、最终用户、运维人员、产品经理等）。
+
+### 2. 主要使用场景
+
+推断用户查阅文档的场景（首次接触、开发集成、问题排查、深入学习等）。
+
+### 3. 文档侧重点
+
+确定文档类型（使用指南型、参考手册型、快速上手型、架构说明型）。
+
+## user_intent.md 模板
+
+```markdown
+# 用户意图
+
+## 目标用户
+[描述主要受众是谁，需要什么类型的信息]
+
+## 使用场景
+- [场景 1：用户在什么情况下查阅文档]
+- [场景 2：...]
+- [场景 3：...]
+
+## 文档侧重点
+本文档采用**[文档类型]**的形式：
+- [侧重点 1]
+- [侧重点 2]
+- [侧重点 3]
+
+[可选：说明不需要的内容，帮助聚焦]
+```
+
+## 示例
+
+```markdown
+# 用户意图
+
+## 目标用户
+本文档主要面向希望集成本项目 API 的开发者。
+
+## 使用场景
+- 开发者首次接触项目时，需要快速了解核心功能和如何开始
+- 开发过程中查阅具体 API 的使用方法和参数说明
+
+## 文档侧重点
+本文档采用**使用指南 + API 参考**的组合形式：
+- 提供清晰的快速开始指南
+- 提供完整的 API 参考文档
+
+不需要过多的架构设计说明。
+```
+
+## 交互策略
+
+### 默认流程
+
+1. **自动生成**：基于工作区分析，自动推断用户意图并生成 user_intent.md
+2. **展示意图**：向用户展示推断的完整意图
+3. **使用 AskUserQuestion 工具确认**：
+   - 问题："用户意图是否符合您的需求？"
+   - 选项："✅ 确认，开始规划文档结构"
+4. **接收反馈**：如果用户选择调整或通过 Other 提供具体需求，更新 user_intent.md
+5. **重新展示**：展示更新后的完整意图
+6. **循环确认**：重复步骤 3-5，直到用户确认
+7. **进入下一步**：用户确认后，才开始规划文档结构
+
+### 展示格式
+
+向用户展示推断的意图时，应清晰展示三个部分：
+
+```
+📝 用户意图推断
+
+## 目标用户
+[具体描述]
+
+## 使用场景
+- [场景 1]
+- [场景 2]
+- [场景 3]
+
+## 文档侧重点
+本文档采用**[文档类型]**的形式：
+- [侧重点 1]
+- [侧重点 2]
+
+[可选：不需要的内容]
+
+这个意图是否符合您的需求？您可以提出调整建议。
+```
+
+### 示例交互
+
+```
+Agent: 📝 用户意图推断
+
+## 目标用户
+本文档主要面向希望集成本项目 API 的开发者。
+
+## 使用场景
+- 开发者首次接触项目时，需要快速了解核心功能
+- 开发过程中查阅具体 API 的使用方法
+
+## 文档侧重点
+本文档采用**使用指南 + API 参考**的组合形式：
+- 提供清晰的快速开始指南
+- 提供完整的 API 参考文档
+
+---
+
+[Agent 使用 AskUserQuestion 工具]
+问题：用户意图是否符合您的需求？
+选项：✅ 确认，开始规划文档结构
+
+---
+
+User: [选择 ✏️ Other] 其实主要是给运维人员看的，重点是部署和配置说明
+
+---
+
+Agent: 已更新目标用户和文档侧重点。
+
+📝 更新后的用户意图
+
+## 目标用户
+本文档主要面向需要部署和维护系统的运维人员。
+
+## 使用场景
+- 运维人员首次部署时，需要了解系统要求和部署步骤
+- 日常维护中查阅配置选项和最佳实践
+
+## 文档侧重点
+本文档采用**运维指南**的形式：
+- 提供详细的部署和配置说明
+- 提供系统要求和环境配置指南
+
+---
+
+[Agent 使用 AskUserQuestion 工具]
+问题：用户意图是否符合您的需求？
+选项：✅ 确认，开始规划文档结构
+
+---
+
+User: ✅ 确认，开始规划文档结构
+
+---
+
+Agent: 收到确认，开始规划文档结构...
+```
+
+### 处理反馈
+
+根据用户反馈更新 user_intent.md 的对应部分（目标用户、使用场景、文档侧重点），必要时完全重写。每次修改后必须重新展示完整意图并询问确认。
+
+## 关键原则
+
+1. **基于证据推断**：从工作区内容（代码结构、README、配置文件）中寻找线索
+2. **保持简洁**：user_intent.md 应该简洁明了，避免冗长
+3. **可修改性**：用自然语言编写，用户易于理解和调整
+4. **多轮确认**：支持用户多轮调整，每次修改后重新展示完整意图并确认
+5. **用户确认后才继续**：绝对不要在用户确认前开始规划文档结构

package/doc-smith.yaml

@@ -0,0 +1,114 @@
+type: ai
+name: docsmith
+keep_text_in_tool_uses: true
+task_render_mode: collapse
+instructions:
+  - role: system
+    url: ./main-system-prompt.md
+
+input_key: message
+skills:
+  - type: function
+    name: askUserQuestion
+    description: |
+      Use this tool when you need to ask the user questions during execution. This allows you to:
+      1. Gather user preferences or requirements
+      2. Clarify ambiguous instructions
+      3. Get decisions on implementation choices as you work
+      4. Offer choices to the user about what direction to take.
+
+      Usage notes:
+      - The system automatically adds an "✏️ Other" option to all questions, allowing users to provide custom text input. DO NOT add your own "Other", "需要调整", or similar options - they will cause duplication.
+      - Only provide the specific action options (e.g., "✅ Confirm"). The "Other" option is handled by the system.
+      - Use multiSelect: true to allow multiple answers to be selected for a question
+      - If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
+    input_schema:
+      type: object
+      properties:
+        questions:
+          type: array
+          items:
+            type: object  
+            properties:
+              question:
+                type: string
+                description: The complete question to ask
+              header:
+                type: string
+                description: Short label(max 12 chars)
+              options:
+                type: array
+                items:
+                  type: string
+                description:
+                  Available choices (2 ~ 4 options)
+              # multiSelect:
+              #   type: boolean
+              #   description: Allow multiple selections
+            required:
+              - question
+              - header
+      required:
+        - questions
+    process: |
+      const {questions} = input
+
+      const answers = []
+      const OTHER_OPTION = '✏️ Other'
+
+      for (const item of questions) {
+        let answer
+
+        if (item?.options?.length) {
+          answer = await options.prompts.select({
+            message: item.question,
+            choices: [
+              ...item.options.map(option => ({
+                name: option,
+                description: option,
+                value: option
+              })),
+              {
+                name: OTHER_OPTION,
+                description: 'Enter your own response',
+                value: OTHER_OPTION
+              }
+            ]
+          })
+
+          if (answer === OTHER_OPTION) {
+            answer = await options.prompts.input({
+              message: 'Please enter your response:'
+            })
+          }
+        } else {
+          answer = await options.prompts.input({
+            message: item.question
+          })
+        }
+
+        answers.push({question: item.question, answer})
+      }
+
+      return {answers}
+
+
+afs:
+  modules:
+    - module: local-fs
+      options:
+        name: workspace
+        localPath: ${CWD}
+        description: |
+          Current working directory for the agent
+          - Read-write access to project files
+          - Use absolute path for file operations
+    - module: local-fs
+      options:
+        agentSkills: true
+        name: doc-smith
+        localPath: ./doc-smith
+        description: |
+          Agent skill for document operations
+          - Read-only access to skill definition files
+          - Do NOT modify files in this directory

package/main-system-prompt.md

@@ -0,0 +1,56 @@
+You are an interactive CLI tool that helps users according to your "Output Style" below, which describes how you should respond to user queries. Use the instructions below and the tools available to you to assist the user.
+
+IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.
+
+# Looking up your own documentation:
+
+When the user directly asks about any of the following:
+- how to use Claude Code (eg. "can Claude Code do...", "does Claude Code have...")
+- what you're able to do as Claude Code in second person (eg. "are you able...", "can you do...")
+- about how they might do something with Claude Code (eg. "how do I...", "how can I...")
+- how to use a specific Claude Code feature (eg. implement a hook, write a slash command, or install an MCP server)
+- how to use the Claude Agent SDK, or asks you to write code that uses the Claude Agent SDK
+
+# Tone and style
+- Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
+- Your output will be displayed on a command line interface. Your responses should be short and concise. You can use Github-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
+- Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like Bash or code comments as means to communicate with the user during the session.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. This includes markdown files.
+- Do not use a colon before tool calls. Your tool calls may not be shown directly in the output, so text like "Let me read the file:" followed by a read tool call should just be "Let me read the file." with a period.
+
+# AFS Context
+
+{{ $afs.description }}
+
+```yaml alt="AFS Modules"
+{{ $afs.modules | yaml.stringify }}
+```
+
+# Asking questions as you work
+
+You have access to the askUserQuestion tool to ask the user questions when you need clarification, want to validate assumptions, or need to make a decision you're unsure about. When presenting options or plans, never include time estimates - focus on what each option involves, not how long it takes.
+
+# Skill usage
+
+When the user requests you to perform tasks, check if any of the available skills can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
+
+## Loading skill resources on demand
+
+Skills may include reference documents (guides, schemas, examples) in a `references/` directory. To optimize performance and context usage:
+
+1. **Start with the main skill file** (e.g., `SKILL.md`) - it contains the workflow overview and references to detailed guides
+2. **Load reference documents only when needed** - read specific guides only when you reach the step that requires them
+3. **Don't preload all resources** - avoid reading all reference files at the start of a task
+
+# Doing tasks
+The user will primarily request you perform software engineering tasks. This includes solving bugs, adding new functionality, refactoring code, explaining code, and more. For these tasks the following steps are recommended:
+- NEVER propose changes to code you haven't read. If a user asks about or wants you to modify a file, read it first. Understand existing code before suggesting modifications.
+- Use the askUserQuestion tool to ask questions, clarify and gather information as needed.
+- Be careful not to introduce security vulnerabilities such as command injection, XSS, SQL injection, and other OWASP top 10 vulnerabilities. If you notice that you wrote insecure code, immediately fix it.
+- Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.
+  - Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability. Don't add docstrings, comments, or type annotations to code you didn't change. Only add comments where the logic isn't self-evident.
+  - Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use feature flags or backwards-compatibility shims when you can just change the code.
+  - Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task—three similar lines of code is better than a premature abstraction.
+- Avoid backwards-compatibility hacks like renaming unused \`_vars\`, re-exporting types, adding \`// removed\` comments for removed code, etc. If something is unused, delete it completely.
+
+IMPORTANT: Complete tasks fully. Do not stop mid-task or leave work incomplete. Do not claim a task is too large, that you lack time, or that context limits prevent completion. You have unlimited context through summarization. Continue working until the task is done or the user stops you.

package/package.json

@@ -1,83 +1,17 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.8-alpha.2",
+  "version": "0.9.8-alpha.4",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "agents",
-    "agentic-agents",
-    "assets/report-template",
-    "docs-mcp",
-    "prompts",
-    "types",
-    "utils",
-    "aigne.yaml",
-    "LICENSE",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "main": "index.js",
+  "main": "aigne.yaml",
   "type": "module",
   "bin": "aigne.yaml",
   "keywords": [],
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "Elastic-2.0",
   "dependencies": {
-    "@aigne/cli": "^1.57.3",
-    "@aigne/core": "^1.70.1",
-    "@aigne/publish-docs": "^0.14.2",
-    "@aigne/secrets": "^0.1.4",
-    "@blocklet/payment-broker-client": "^1.22.30",
-    "chalk": "^5.5.0",
-    "debug": "^4.4.1",
-    "diff": "^8.0.2",
-    "dompurify": "^3.2.6",
-    "fast-deep-equal": "^3.1.3",
-    "fastq": "^1.19.1",
-    "file-type": "^21.0.0",
-    "fs-extra": "^11.3.1",
-    "glob": "^11.0.3",
-    "gpt-tokenizer": "^3.2.0",
-    "image-size": "^2.0.2",
-    "is-in-ci": "^2.0.0",
-    "isbinaryfile": "^5.0.6",
-    "jsdom": "^26.1.0",
-    "marked": "^15.0.12",
-    "marked-terminal": "^7.3.0",
-    "mermaid": "^11.9.0",
-    "minimatch": "^10.1.1",
-    "open": "^10.2.0",
-    "p-limit": "^7.1.1",
-    "p-map": "^7.0.3",
-    "p-retry": "^7.0.0",
-    "remark-gfm": "^4.0.1",
-    "remark-lint": "^10.0.1",
-    "remark-parse": "^11.0.0",
-    "sharp": "^0.33.0",
-    "typescript": "^5.9.3",
-    "ufo": "^1.6.1",
-    "unified": "^11.0.5",
-    "unist-util-visit": "^5.0.0",
-    "vfile": "^6.0.3",
-    "yaml": "^2.8.0",
-    "zod": "^3.25.76",
-    "zod-to-json-schema": "^3.24.6"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.2.4"
-  },
-  "scripts": {
-    "test": "bun test --preload ./tests/setup/mock-process-exit.mjs",
-    "test:coverage2": "bun test --preload ./tests/setup/mock-process-exit.mjs --coverage",
-    "test:coverage": "bun test --preload ./tests/setup/mock-process-exit.mjs --coverage --coverage-reporter=lcov --coverage-reporter=text",
-    "test:deploy": "bun test --preload ./tests/setup/mock-process-exit.mjs tests/utils/deploy.test.mjs --coverage --coverage-reporter=text",
-    "test:user-review": "bun test --preload ./tests/setup/mock-process-exit.mjs tests/agents/update/user-review-document.test.mjs --coverage --coverage-reporter=lcov --coverage-reporter=text",
-    "test:watch": "bun test --preload ./tests/setup/mock-process-exit.mjs --watch",
-    "lint": "biome lint && biome format",
-    "update:deps": "npx -y taze major -r -w -f -n '/@abtnode|@aigne|@arcblock|@blocklet|@did-connect|@did-pay|@did-space|@nft-store|@nft-studio|@ocap/' && pnpm install && pnpm run deduplicate",
-    "deduplicate": "pnpm dedupe",
-    "lint:fix": "biome lint --write && biome format --write"
+    "@aigne/cli": "^1.59.0-beta.4"
   }
 }

package/scripts/README.md

@@ -0,0 +1,90 @@
+# DocSmith Skill 安装脚本
+
+这个目录包含用于安装和卸载 doc-smith skill 的脚本。
+
+## 脚本说明
+
+### install.sh
+将 doc-smith skill 安装到 Claude 的全局 skills 目录（`~/.claude/skills`），使其可以在任何项目中使用。
+
+**功能：**
+- 自动创建 `~/.claude/skills` 目录（如果不存在）
+- 复制 doc-smith 文件夹到全局 skills 目录
+- 检测并提示是否覆盖已存在的安装
+- 验证安装是否成功
+
+### uninstall.sh
+从 Claude 的全局 skills 目录移除 doc-smith skill。
+
+**功能：**
+- 检查 skill 是否已安装
+- 确认后删除 doc-smith skill
+- 验证卸载是否成功
+
+## 使用方法
+
+### 安装
+
+在项目根目录执行：
+
+```bash
+./scripts/install.sh
+```
+
+或者从 scripts 目录执行：
+
+```bash
+cd scripts
+./install.sh
+```
+
+**自动确认安装（跳过提示）：**
+
+```bash
+./scripts/install.sh -y
+# 或
+./scripts/install.sh --yes
+```
+
+安装成功后，你可以在任何地方的 Claude Code 中使用：
+
+```
+/doc-smith
+```
+
+### 卸载
+
+```bash
+./scripts/uninstall.sh
+```
+
+## 安装位置
+
+- **源文件：** `doc-smith-skill/doc-smith/`
+- **安装位置：** `~/.claude/skills/doc-smith/`
+
+## 注意事项
+
+1. 脚本会提示是否覆盖已存在的安装
+2. 卸载前会要求确认
+3. 所有操作都有彩色输出提示，便于识别状态
+4. 脚本执行失败时会返回非零退出码
+
+## 故障排查
+
+**权限问题：**
+```bash
+chmod +x scripts/install.sh
+chmod +x scripts/uninstall.sh
+```
+
+**手动安装：**
+```bash
+mkdir -p ~/.claude/skills
+cp -r doc-smith ~/.claude/skills/
+```
+
+**手动卸载：**
+```bash
+rm -rf ~/.claude/skills/doc-smith
+```