docs: 添加 AI 章节 - Skill 编写最佳实践

ai/index.md

@@ -0,0 +1,9 @@
+# AI
+
+本章记录 AI 辅助开发相关的实践经验与工具使用指南。
+
+## 文章列表
+
+| 文章 | 说明 |
+|------|------|
+| [Skill 编写最佳实践](skill-best-practices.md) | 基于真实 skill 提炼的 SKILL.md 编写规范 |

ai/skill-best-practices.md

@@ -0,0 +1,351 @@
+# QwenPaw Skill 编写最佳实践
+
+!!! note "本文总结了基于 todo 和 wiki 两个真实 skill 提炼出的 SKILL.md 编写规范，帮助开发者写出仅靠一份文件就能让 agent 独立运行的 skill。"
+
+---
+
+## 核心概念
+
+1. **SKILL.md 是 agent 的唯一指令源** — agent 只读这一份文件就能完成所有操作，不依赖外部搜索
+2. **Frontmatter 是触发入口** — `name` 和 `description` 决定了 agent 何时加载这个 skill
+3. **References 是按需展开的辅助材料** — setup、模板、参考数据等不放进正文，避免上下文膨胀
+4. **可执行性优先** — 每条操作指南必须是可直接复制执行的 SQL/命令，不留占位符
+
+## 详解
+
+### Frontmatter 写法
+
+Frontmatter 是 SKILL.md 最关键的部分。agent 通过它判断"这个 skill 是否和当前用户请求相关"。
+
+```yaml
+---
+name: todo
+description: |
+  任务待办管理 skill。通过自然语言操作 MySQL 数据库中的待办事项。
+  当用户提到待办、任务管理、todo list、添加任务、查看任务、标记完成、
+  清理任务、归档旧任务时，使用此 skill。
+  支持增删改查和基于 LRU 策略的自动归档。
+---
+```
+
+#### `name` 字段
+
+- 使用小写 kebab-case 或纯小写：`todo`、`wiki`、`file-reader`
+- 与 skill 目录名保持一致
+- 简短，不超过 2 个单词
+
+#### `description` 触发词设计
+
+`description` 是 agent 路由决策的核心依据。写好它需要遵循以下原则：
+
+| 原则 | 说明 | 反例 |
+|------|------|------|
+| 枚举用户可能的原话 | 把触发词直接写进去，而不是描述功能 | ~~"管理任务的工具"~~ |
+| 覆盖中英文 | 中文用户和英文用户都可能触发 | 只写中文触发词 |
+| 包含近义词和口语化表达 | "记一下"、"提醒我"、"todo list" | 只写正式术语 |
+| 一句话说明核心能力 | 让 agent 知道这个 skill 能做什么 | 只列触发词不说明功能 |
+| 末尾写一句话总结支撑能力 | 便于 agent 快速理解 scope | — |
+
+好的 description 示例：
+
+```
+任务待办管理 skill。通过自然语言操作 MySQL 数据库中的待办事项。
+当用户提到待办、任务管理、todo list、添加任务、查看任务、标记完成、
+清理任务、归档旧任务时，使用此 skill。
+支持增删改查和基于 LRU 策略的自动归档。
+```
+
+差的 description 示例：
+
+```
+管理任务。  ← 太模糊，agent 不知道何时触发
+```
+
+### 正文结构
+
+正文遵循固定结构，让 agent 能按顺序读取并理解整个 skill 的能力边界。
+
+```
+# Skill 名称
+
+一句话概述
+
+## 工具说明        ← 依赖什么外部工具，不可用时怎么办
+## 表/数据结构     ← 数据库 schema、文件格式等
+## 操作指南        ← 核心：触发词 + 可执行命令
+## LRU/策略        ← 业务逻辑（如有）
+## 交互原则        ← agent 的行为边界
+## 输出格式        ← 展示规范
+```
+
+#### 工具说明
+
+必须明确告诉 agent：
+
+1. **依赖什么工具**：如 `mysql_query` MCP 工具
+2. **调用方式**：通过 `execute_shell_command` 执行，还是直接使用 MCP
+3. **不可用时的降级方案**：引导用户参考 `references/setup.md` 完成配置
+
+```markdown
+## 工具说明
+
+本 skill 依赖 **MySQL MCP 工具** `mysql_query`。所有数据库操作都通过该工具执行。
+
+调用方式：使用 `execute_shell_command` 执行 MySQL MCP 查询，或直接使用 MCP 工具（如可用）。
+
+如果 MCP 工具不可用，引导用户参考 `references/setup.md` 完成配置。
+```
+
+#### 表/数据结构
+
+完整展示 schema，不要省略字段。agent 需要知道所有字段才能写出正确的 SQL。
+
+```markdown
+## 表结构
+
+\```sql
+CREATE TABLE IF NOT EXISTS todos (
+    id               BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+    title            VARCHAR(500) NOT NULL,
+    ...
+);
+\```
+```
+
+#### 操作指南（核心）
+
+每个操作包含三个要素：**触发词**、**SQL/命令**、**边界条件**。
+
+```markdown
+### 添加任务
+
+触发词：添加任务 / 新建待办 / 提醒我做 / 记一下
+
+\```sql
+INSERT INTO todos (title, description, priority)
+VALUES ('<标题>', '<描述>', '<优先级>');
+\```
+
+- 优先级默认 `medium`
+- 用户说"紧急/urgent/马上/ASAP" → `urgent`
+- 用户说"重要" → `high`
+- 添加后执行 LRU 检查（见下方淘汰策略）
+```
+
+关键设计点：
+
+| 设计点 | 说明 | 为什么重要 |
+|--------|------|------------|
+| 列出触发词 | `触发词：添加任务 / 新建待办 / 提醒我做 / 记一下` | agent 直接匹配用户意图 |
+| 可复制的 SQL | 不用 `<placeholder>` 填参数，而是写清参数含义 | agent 知道该填什么 |
+| 参数映射规则 | 明确自然语言到字段值的映射 | agent 说"紧急"时知道映射为 `urgent` |
+| 边界条件 | 列出每种操作的限制和特殊情况 | 避免 agent 做出不合理操作 |
+| 关联操作 | 指向其他操作（如"见下方淘汰策略"） | agent 能自动串联操作流 |
+
+### References 目录组织
+
+References 用于存放按需展开的辅助材料，避免 SKILL.md 正文过长。
+
+```
+skills/todo/
+├── SKILL.md              ← agent 始终加载
+└── references/
+    └── setup.md          ← 仅在需要配置时读取
+
+skills/wiki/
+├── SKILL.md
+└── references/
+    ├── article-template.md   ← 写文档时参考
+    └── mkdocs-nav.md         ← 更新导航时参考
+```
+
+#### 什么内容放 references
+
+| 放 references | 放 SKILL.md 正文 |
+|---------------|-------------------|
+| 安装配置指南（setup） | 核心操作指南 |
+| 模板和格式规范 | 数据结构定义 |
+| 参考数据（如现有目录结构） | 交互原则 |
+| 第三方文档摘要 | 工具依赖说明 |
+
+#### references 文件的命名
+
+- 使用 kebab-case：`setup.md`、`article-template.md`、`mkdocs-nav.md`
+- 文件名应直观表达内容
+- 一个文件聚焦一个主题
+
+### 让 Agent 仅看 SKILL.md 就能运行
+
+以下是确保 agent 不需要额外搜索就能独立运行的关键设计：
+
+#### 1. 自包含的命令模板
+
+每个操作指南必须包含完整的、可直接执行的 SQL/命令。不要写"根据需要构造 SQL"，而是写出来：
+
+```markdown
+\```sql
+INSERT INTO todos (title, description, priority)
+VALUES ('<标题>', '<描述>', '<优先级>');
+\```
+```
+
+#### 2. 自然语言到结构化数据的映射
+
+明确告诉 agent 如何理解用户的口语化表达：
+
+```markdown
+- 用户说"紧急/urgent/马上/ASAP" → `urgent`
+- 用户说"重要" → `high`
+- 用户说"不急/有空/low" → `low`
+```
+
+#### 3. 工作流串联
+
+在操作指南中明确标注操作之间的依赖关系：
+
+```markdown
+- 添加后执行 LRU 检查（见下方淘汰策略）
+- 匹配多条时列出匹配项让用户确认
+- 用 `SELECT` 先查再改，避免误操作
+```
+
+#### 4. 工具查找方式
+
+如果 skill 有自己的脚本或模板，告诉 agent 如何定位它们：
+
+```markdown
+## 工作流程
+
+### 1. 查找 skill 路径
+
+\```
+# 用 glob_search 找到本 skill 的位置
+glob_search(pattern="**/wiki/SKILL.md")
+\```
+
+找到后，skill 目录路径为结果中 `SKILL.md` 所在的目录（去掉 `/SKILL.md` 后缀）。
+```
+
+#### 5. 降级方案
+
+当依赖的外部工具不可用时，告诉 agent 该怎么做：
+
+```markdown
+如果 MCP 工具不可用，引导用户参考 `references/setup.md` 完成配置。
+```
+
+### 交互原则
+
+SKILL.md 末尾必须定义 agent 的行为边界，防止 agent 做出用户不期望的操作：
+
+```markdown
+## 交互原则
+
+- **模糊匹配时确认**：关键词匹配多条任务，列出选项让用户选
+- **操作前预览**：删除/归档前，先 `SELECT` 显示受影响的事项
+- **自然语言理解**：用户说"帮我记一下明天要买菜" → 添加任务"买菜"
+- **状态转换合理**：不允许 archived → in_progress 等不合理跳转
+```
+
+交互原则的核心模式：
+
+| 模式 | 说明 | 示例 |
+|------|------|------|
+| 确认机制 | 破坏性操作前必须确认 | 删除前先列出受影响条目 |
+| 预览机制 | 执行前展示将要发生的事 | SQL 执行前先 SELECT |
+| 合理性检查 | 拒绝不合理的状态跳转 | archived 不能直接变 in_progress |
+| 意图理解 | 从口语中提取结构化信息 | "明天要买菜" → title="买菜" |
+
+### 输出格式
+
+定义 agent 的展示规范，让输出风格一致：
+
+```markdown
+## 输出格式
+
+查询结果用表格展示：
+
+| ID | 标题 | 状态 | 优先级 | 更新时间 |
+|----|------|------|--------|----------|
+| 1  | xxx  | 待办 | 高     | 08-31    |
+
+操作结果用简洁确认：
+- ✓ 已添加任务：XXX
+- ✓ 已完成任务：XXX
+```
+
+## 常见陷阱
+
+!!! warning "陷阱一：使用占位符而非完整命令"
+    不要写 `INSERT INTO table (col) VALUES (?)`，agent 不知道 `?` 该填什么。写完整模板并说明参数来源。
+
+!!! warning "陷阱二：依赖 agent 自己搜索"
+    不要写"参考官方文档"或"搜索相关 API"。agent 的 SKILL.md 必须自包含所有必要信息。
+
+!!! warning "陷阱三：description 太简略"
+    只写"任务管理工具"会导致 agent 无法准确判断何时触发。必须枚举具体触发词。
+
+!!! warning "陷阱四：references 目录缺失"
+    安装配置、模板等辅助材料不放正文，但必须放在 references 中。否则 agent 在需要时无处可查。
+
+!!! warning "陷阱五：缺少交互原则"
+    不定义行为边界，agent 可能直接删除数据而不确认，或在模糊匹配时随机选择。交互原则是安全网。
+
+## 两个 Skill 的设计模式对比
+
+| 维度 | todo skill | wiki skill |
+|------|------------|------------|
+| 核心操作 | CRUD（SQL） | 文件操作（shell） |
+| 数据结构 | MySQL 表结构 | MkDocs 目录结构 |
+| 外部依赖 | MySQL MCP | SSH + Git |
+| references | setup.md（配置指南） | article-template.md + mkdocs-nav.md |
+| 工作流特点 | 每次操作独立 | 多步骤流水线（检查→克隆→编辑→推送） |
+| 交互原则重点 | 模糊匹配确认、操作前预览 | 章节不确定时必须询问 |
+
+## 练习题
+
+??? question "题目一：为一个「笔记管理」skill 设计 frontmatter"
+    ??? success "答案"
+        ```yaml
+        ---
+        name: notes
+        description: |
+          笔记管理 skill。支持添加、搜索、编辑和删除 Markdown 笔记。
+          当用户提到记笔记、写笔记、查找笔记、搜索笔记、
+          编辑笔记、删除笔记、笔记管理时，使用此 skill。
+          支持标签分类和全文搜索。
+        ---
+        ```
+
+??? question "题目二：以下 SKILL.md 有哪些问题？"
+    ```markdown
+    ---
+    name: mytool
+    description: 一个好用的工具
+    ---
+    # MyTool
+    这个工具可以帮你做很多事情。
+    需要用什么命令请参考官方文档。
+    ```
+    ??? success "答案"
+        1. **name 不规范**：应使用小写 kebab-case
+        2. **description 太模糊**：没有触发词，agent 不知道何时加载
+        3. **正文缺乏结构**：没有工具说明、操作指南、交互原则
+        4. **依赖外部搜索**：写了"参考官方文档"，agent 无法独立运行
+        5. **没有 references**：没有提供任何辅助材料
+
+??? question "题目三：什么时候应该把内容放 references 而不是正文？"
+    ??? success "答案"
+        当内容满足以下任一条件时，应放 references：
+        1. **按需使用**：不是每次调用都需要（如安装配置指南）
+        2. **内容较长**：放正文会膨胀上下文（如模板、参考数据）
+        3. **独立性强**：本身是一份完整的参考文档（如 API 文档摘要）
+
+        正文应该只放：核心操作指南、数据结构定义、交互原则、工具依赖说明。
+
+## 相关链接
+
+- [QwenPaw 官方文档](https://qwenpaw.agentscope.io/) — 框架使用指南
+- [QwenPaw GitHub](https://github.com/agentscope-ai/QwenPaw) — 源码与示例
+- [todo skill](https://github.com/agentscope-ai/QwenPaw) — 本文分析的 todo skill 示例
+- [wiki skill](https://github.com/agentscope-ai/QwenPaw) — 本文分析的 wiki skill 示例

mkdocs.yml

@@ -127,3 +127,6 @@ nav:
     - 部署与 CI/CD: qiniu-cloud/deployment-cicd.md
     - 安全·认证·数据: qiniu-cloud/security-auth-data.md
     - 简历技术要点: qiniu-cloud/resume-tech-points.md
+  - AI:
+    - ai/index.md
+    - Skill 编写最佳实践: ai/skill-best-practices.md