refactor: 完善 todo 和 wiki skill 的自包含操作指南

- todo: 明确 mysql_query MCP 工具调用方式，补充触发词和字段说明 - todo/setup: 补充 QwenPaw 和 Claude Code 两种配置方式，修正环境变量名 - wiki: 用 glob_search 替换 <skill-path> 占位符，流程更清晰
2026-09-01 20:58:53 +08:00
parent be7720e732
commit 14e93d2001
3 changed files with 157 additions and 139 deletions
@@ -11,43 +11,56 @@ description: |

 通过自然语言管理 MySQL 数据库中的待办事项，支持 LRU 自动淘汰。

-## 前置条件
+## 工具说明

-此 skill 依赖 MySQL MCP 工具。使用前需确认：
+本 skill 依赖 **MySQL MCP 工具** `mysql_query`。所有数据库操作都通过该工具执行。

-1. MySQL MCP 已配置（参考 `references/setup.md`）
-2. todos 表已创建（参考 `references/setup.md` 中的建表 SQL）
+调用方式：使用 `execute_shell_command` 执行 MySQL MCP 查询，或直接使用 MCP 工具（如可用）。

 如果 MCP 工具不可用，引导用户参考 `references/setup.md` 完成配置。

-## 自然语言操作映射
+## 表结构
+
+```sql
+CREATE TABLE IF NOT EXISTS todos (
+    id               BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+    title            VARCHAR(500) NOT NULL,
+    description      TEXT,
+    status           ENUM('pending', 'in_progress', 'done', 'archived') NOT NULL DEFAULT 'pending',
+    priority         ENUM('low', 'medium', 'high', 'urgent') NOT NULL DEFAULT 'medium',
+    created_at       DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at       DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    last_accessed_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    access_count     INT UNSIGNED NOT NULL DEFAULT 1
+);
+```
+
+## 操作指南

 ### 添加任务

-用户说："添加任务：XXX" / "新建一个待办：XXX" / "提醒我做 XXX"
+触发词：添加任务 / 新建待办 / 提醒我做 / 记一下

 ```sql
 INSERT INTO todos (title, description, priority) VALUES ('<标题>', '<描述>', '<优先级>');
 ```

- 优先级默认 `medium`，如果用户提到"紧急/urgent"则为 `urgent`，"重要"为 `high`
- 添加后自动执行 LRU 检查（见淘汰策略）
+- 优先级默认 `medium`
+- 用户说"紧急/urgent/马上/ASAP" → `urgent`
+- 用户说"重要" → `high`
+- 用户说"不急/有空/low" → `low`
+- 添加后执行 LRU 检查（见下方淘汰策略）

 ### 查看待办

-用户说："我的待办" / "有什么任务" / "看看今天的任务"
+触发词：我的待办 / 有什么任务 / 今天要做什么 / 列出任务

 ```sql
-SELECT id, title, status, priority, last_accessed_at
+SELECT id, title, status, priority, DATE_FORMAT(updated_at, '%m-%d') AS updated
 FROM todos
 WHERE status IN ('pending', 'in_progress')
 ORDER BY
-  CASE priority
-    WHEN 'urgent' THEN 0
-    WHEN 'high' THEN 1
-    WHEN 'medium' THEN 2
-    WHEN 'low' THEN 3
-  END,
+  FIELD(priority, 'urgent', 'high', 'medium', 'low'),
  last_accessed_at DESC;
 ```

@@ -55,33 +68,41 @@ ORDER BY

 ```sql
 UPDATE todos SET last_accessed_at = NOW(), access_count = access_count + 1
-WHERE id IN (<查看到的 id 列表>);
+WHERE id IN (<id 列表>);
 ```

 ### 查看已完成

-用户说："已完成的任务" / "看看做完了哪些"
+触发词：已完成的任务 / 做完了哪些

 ```sql
-SELECT id, title, priority, updated_at
+SELECT id, title, priority, DATE_FORMAT(updated_at, '%m-%d %H:%i') AS completed
 FROM todos WHERE status = 'done'
 ORDER BY updated_at DESC;
 ```

 ### 标记完成

-用户说："完成 XXX" / "把这个标记为完成" / "做完了"
+触发词：完成 XXX / 标记为完成 / 做完了

 ```sql
 UPDATE todos SET status = 'done', last_accessed_at = NOW(), access_count = access_count + 1
-WHERE id = <id> OR title LIKE '%<关键词>%';
+WHERE id = <id>;
 ```

-如果匹配多条，列出匹配项让用户确认。
+按标题匹配：
+
+```sql
+UPDATE todos SET status = 'done', last_accessed_at = NOW(), access_count = access_count + 1
+WHERE title LIKE '%<关键词>%' AND status != 'done';
+```
+
+- 匹配多条时列出匹配项让用户确认
+- 用 `SELECT` 先查再改，避免误操作

 ### 标记进行中

-用户说："开始做 XXX" / "进行中"
+触发词：开始做 XXX / 进行中

 ```sql
 UPDATE todos SET status = 'in_progress', last_accessed_at = NOW(), access_count = access_count + 1
@@ -90,16 +111,18 @@ WHERE id = <id>;

 ### 更新任务

-用户说："修改 XXX 的描述为 YYY" / "把 XXX 的优先级改为 high"
+触发词：修改 XXX 的描述/优先级/标题

 ```sql
 UPDATE todos SET <字段> = '<新值>', last_accessed_at = NOW(), access_count = access_count + 1
 WHERE id = <id>;
 ```

+可更新字段：`title`、`description`、`priority`、`status`
+
 ### 删除任务

-用户说："删除任务 XXX" / "去掉这个待办"
+触发词：删除任务 / 去掉这个待办

 **软删除（推荐）**：

@@ -107,62 +130,60 @@ WHERE id = <id>;
 UPDATE todos SET status = 'archived' WHERE id = <id>;
 ```

-**硬删除**（用户明确要求彻底删除时）：
+**硬删除**（用户明确要求时）：

 ```sql
 DELETE FROM todos WHERE id = <id>;
 ```

- 硬删除前必须确认，列出将被删除的事项
- 默认使用软删除（归档），保护数据
+- 硬删除前必须列出将被删除的事项并确认
+- 默认用软删除

 ### 搜索任务

-用户说："找一下关于 XXX 的任务"
+触发词：找一下关于 XXX 的任务 / 有没有 XXX

 ```sql
-SELECT id, title, description, status, priority
+SELECT id, title, status, priority
 FROM todos
 WHERE title LIKE '%<关键词>%' OR description LIKE '%<关键词>%'
-ORDER BY status, priority;
+ORDER BY FIELD(status, 'in_progress', 'pending', 'done', 'archived'), priority;
 ```

 ## LRU 淘汰策略

-### 自动触发
-
-每次 INSERT 后检查：
+每次 INSERT 后检查总数：

 ```sql
-SELECT COUNT(*) FROM todos WHERE status != 'archived';
+SELECT COUNT(*) AS total FROM todos WHERE status != 'archived';
 ```

-如果总数超过 100，执行归档。
+如果超过 100 条，执行归档：

-### 归档逻辑
+```sql
+-- 1. 归档最久未访问的已完成事项（最旧 10 条）
+UPDATE todos SET status = 'archived'
+WHERE status = 'done'
+ORDER BY last_accessed_at ASC LIMIT 10;

-1. **优先归档已完成**：归档最久未访问的 `done` 事项（取最旧的 10 条）
-2. **其次归档待办**：如果仍超标，归档最久未访问的 `pending` 事项
-3. **保护进行中**：不归档 `in_progress` 状态的事项
-4. **告知用户**：归档时列出被归档的事项标题
+-- 2. 仍超标则归档最久未访问的待办事项
+UPDATE todos SET status = 'archived'
+WHERE status = 'pending'
+ORDER BY last_accessed_at ASC LIMIT 10;
+```

-### 手动触发
-
-用户说："清理旧任务" / "归档一些任务" / "整理一下待办"
-
-执行同样的归档逻辑，但需要先告知用户当前待办数量，并询问是否确认清理。
+**保护规则**：不归档 `in_progress` 状态的事项。

 ## 交互原则

- **模糊匹配时确认**：如果用户说的关键词匹配多条任务，列出选项让用户确认
- **操作前预览**：删除/归档操作前，显示受影响的事项列表
- **优先级合理推断**：用户说"紧急""马上""ASAP" → urgent；"重要" → high；默认 → medium
- **自然语言理解**：用户可能说"帮我记一下明天要买菜"，理解为添加任务"买菜"
- **状态转换合理**：不要让用户手动做不合理的状态跳转（如 archived → in_progress）
+- **模糊匹配时确认**：关键词匹配多条任务，列出选项让用户选
+- **操作前预览**：删除/归档前，先 `SELECT` 显示受影响的事项
+- **自然语言理解**：用户说"帮我记一下明天要买菜" → 添加任务"买菜"
+- **状态转换合理**：不允许 archived → in_progress 等不合理跳转

 ## 输出格式

-查询结果以表格形式展示：
+查询结果用表格展示：

 ```
 | ID | 标题 | 状态 | 优先级 | 更新时间 |
@@ -170,7 +191,7 @@ SELECT COUNT(*) FROM todos WHERE status != 'archived';
 | 1  | xxx  | 待办 | 高     | 08-31    |
 ```

-操作结果用简洁的确认语句：
+操作结果用简洁确认：
 - ✓ 已添加任务：XXX
 - ✓ 已完成任务：XXX
 - ✓ 已归档 5 条旧任务
@@ -4,35 +4,57 @@

 推荐使用 `@benborla29/mcp-server-mysql`（支持读写操作）。

-### 配置方式
+### QwenPaw 配置方式

-在项目的 `.mcp.json` 文件中添加（或在 `~/.claude.json` 中配置）：
+在 `~/.qwenpaw/config.json` 的 `mcp.clients` 中添加：

 ```json
-{
-  "mcpServers": {
 "mysql": {
+  "name": "mysql",
+  "description": "MySQL MCP for todo skill",
+  "enabled": true,
+  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@benborla29/mcp-server-mysql"],
  "env": {
-        "MYSQL_HOST": "<替换为你的主机地址>",
-        "MYSQL_PORT": "<替换为你的端口，默认 3306>",
-        "MYSQL_USER": "<替换为你的用户名>",
-        "MYSQL_PASSWORD": "<替换为你的密码>",
-        "MYSQL_DATABASE": "<替换为你的数据库名>"
-      }
-    }
+    "MYSQL_HOST": "<主机地址>",
+    "MYSQL_PORT": "<端口，默认 3306>",
+    "MYSQL_USER": "<用户名>",
+    "MYSQL_PASS": "<密码>",
+    "MYSQL_DB": "<数据库名>",
+    "ALLOW_INSERT_OPERATION": "true",
+    "ALLOW_UPDATE_OPERATION": "true",
+    "ALLOW_DELETE_OPERATION": "true",
+    "SCHEMA_DDL_PERMISSIONS": "<数据库名>:true"
  }
 }
 ```

+> **注意**：环境变量名是 `MYSQL_PASS`（不是 `MYSQL_PASSWORD`）和 `MYSQL_DB`（不是 `MYSQL_DATABASE`）。
+
+### Claude Code 配置方式
+
+```bash
+claude mcp add mysql \
+  -e MYSQL_HOST="<主机地址>" \
+  -e MYSQL_PORT="<端口>" \
+  -e MYSQL_USER="<用户名>" \
+  -e MYSQL_PASS="<密码>" \
+  -e MYSQL_DB="<数据库名>" \
+  -e ALLOW_INSERT_OPERATION="true" \
+  -e ALLOW_UPDATE_OPERATION="true" \
+  -e ALLOW_DELETE_OPERATION="true" \
+  -e SCHEMA_DDL_PERMISSIONS="<数据库名>:true" \
+  -- npx -y @benborla29/mcp-server-mysql
+```
+
 ### 验证 MCP 可用

-配置完成后重启 Claude Code，然后尝试：
+配置完成后重启客户端，然后尝试：
 - 列出数据库中的表
 - 执行一条简单查询

-如果 MCP 工具可用，会看到 `mysql` 相关的工具。
+如果 MCP 工具可用，会看到 `mysql_query` 工具。

 ---

@@ -65,48 +87,20 @@ CREATE TABLE IF NOT EXISTS todos (
 | id | BIGINT UNSIGNED | 自增主键 |
 | title | VARCHAR(500) | 任务标题，必填 |
 | description | TEXT | 任务描述，可选 |
-| status | ENUM | 状态：pending / in_progress / done / archived |
-| priority | ENUM | 优先级：low / medium / high / urgent |
+| status | ENUM | pending / in_progress / done / archived |
+| priority | ENUM | low / medium / high / urgent |
 | created_at | DATETIME | 创建时间，自动填充 |
 | updated_at | DATETIME | 更新时间，自动刷新 |
-| last_accessed_at | DATETIME | 最后访问时间，每次查看/更新时刷新 |
-| access_count | INT UNSIGNED | 访问计数，每次访问 +1 |
+| last_accessed_at | DATETIME | 最后访问时间，LRU 依据 |
+| access_count | INT UNSIGNED | 访问计数，每次 +1 |

 ---

 ## 3. LRU 淘汰策略

-### 原理
-
 基于 `last_accessed_at` 字段实现 LRU（Least Recently Used）淘汰：

- 每次查看、更新 todo 时，刷新 `last_accessed_at` 为当前时间，`access_count` +1
- 当待办事项总数超过阈值（默认 100 条非 archived 记录）时，自动触发归档
- 归档优先级：先归档最久未访问的 `done` 事项，再归档最久未访问的 `pending` 事项
-
-### 归档 SQL
-
-```sql
-- 查询非 archived 的事项总数
-SELECT COUNT(*) FROM todos WHERE status != 'archived';
-
-- 归档最久未访问的已完成事项（取最旧的 10 条）
-UPDATE todos
-SET status = 'archived'
-WHERE status = 'done'
-ORDER BY last_accessed_at ASC
-LIMIT 10;
-
-- 如果仍然超标，归档最久未访问的待办事项
-UPDATE todos
-SET status = 'archived'
-WHERE status = 'pending'
-ORDER BY last_accessed_at ASC
-LIMIT 10;
-```
-
-### 触发时机
-
- 每次 INSERT 新事项后，检查总数是否超标
- 用户主动要求"清理"或"归档旧任务"时
- 不会自动归档 `in_progress` 状态的事项（保护正在做的任务）
+- 每次查看、更新 todo 时刷新 `last_accessed_at` 和 `access_count`
+- 待办总数超过 100 条时自动归档
+- 先归档最久未访问的 `done` 事项，再归档 `pending` 事项
+- 不归档 `in_progress` 状态的事项
@@ -13,17 +13,28 @@ description: |

 ## 工作流程

-### 1. SSH 连通性检查
+### 1. 查找 skill 路径

-在操作仓库之前，先运行 SSH 检查脚本：
+本 skill 的脚本和模板位于 skill 目录下。查找方法：
+
+```
+# 用 glob_search 找到本 skill 的位置
+glob_search(pattern="**/wiki/SKILL.md")
+```
+
+找到后，skill 目录路径为结果中 `SKILL.md` 所在的目录（去掉 `/SKILL.md` 后缀）。
+
+后续步骤中用 `<skill-dir>` 代指该路径。
+
+### 2. SSH 连通性检查

 ```bash
-bash <skill-path>/scripts/check_ssh.sh
+bash <skill-dir>/scripts/check_ssh.sh
 ```

 如果检查失败，告知用户需要配置 SSH 密钥，不要继续操作。

-### 2. 克隆仓库
+### 3. 克隆仓库

 ```bash
 TMP_DIR=$(mktemp -d)
@@ -32,31 +43,30 @@ git clone ssh://git@47.121.181.112:222/wonder/docs.git "$TMP_DIR"

 后续所有文件操作在 `$TMP_DIR` 中进行。

-### 3. 理解用户意图
-
-用户可能以不同方式使用此 skill：
+### 4. 理解用户意图

 **场景 A — 提供主题**：用户说"写一篇关于 XXX 的文章"
- 根据主题判断应该放在哪个章节（algorithm/architecture/project/qiniu-cloud）
- 如果章节不明确，询问用户
+- 根据主题判断章节（algorithm / architecture / project / qiniu-cloud）
+- 不确定时询问用户
 - 按模板生成完整文档

 **场景 B — 提供内容**：用户粘贴了一段文档或笔记
- 分析内容主题，判断合适的章节
- 整理成标准格式（参考 `references/article-template.md`）
- 如果内容不完整，询问用户补充
+- 分析内容主题，判断合适章节
+- 整理成标准格式（参考 `<skill-dir>/references/article-template.md`）
+- 内容不完整时询问用户补充

 **场景 C — 更新现有文档**：用户说"更新 XXX 文章"
 - 在仓库中找到对应文件
 - 根据用户要求更新内容

-**场景 D — 章节不明确**：无法确定放在哪里
- 列出当前仓库的章节结构供用户选择
- 询问用户该内容属于哪个章节，或是否需要新建章节
+**场景 D — 章节不明确**：
+- 先查看仓库目录结构：`ls $TMP_DIR/`
+- 列出当前章节供用户选择
+- 询问是否需要新建章节

-### 4. 生成/更新文档
+### 5. 生成/更新文档

-遵循 `references/article-template.md` 中的标准格式。关键要点：
+遵循 `<skill-dir>/references/article-template.md` 中的标准格式：

 - 使用中文撰写
 - 代码示例以 Go 为主
@@ -64,13 +74,13 @@ git clone ssh://git@47.121.181.112:222/wonder/docs.git "$TMP_DIR"
 - 包含常见陷阱和练习题
 - 文件名使用 kebab-case

-### 5. 更新导航
+### 6. 更新导航

-修改 `mkdocs.yml` 的 `nav` 字段，将新文档添加到正确位置，或根据用户指示修改已有条目。
+修改 `$TMP_DIR/mkdocs.yml` 的 `nav` 字段，将新文档添加到正确位置。

-参考 `references/mkdocs-nav.md` 了解当前导航结构和规范。
+参考 `<skill-dir>/references/mkdocs-nav.md` 了解当前导航结构。

-### 6. 提交并推送
+### 7. 提交并推送

 ```bash
 cd "$TMP_DIR"
@@ -79,25 +89,18 @@ git commit -m "docs: 添加/更新 <文档标题>"
 git push origin main
 ```

-提交信息遵循 Conventional Commits 格式（参考全局 CLAUDE.md 规范）。
-
-### 7. 清理
+### 8. 清理

 ```bash
 rm -rf "$TMP_DIR"
 ```

-告知用户文档已推送，CI/CD 会自动部署。
+告知用户文档已推送，CI/CD 通常 1-2 分钟自动部署。

 ## 交互原则

 - **章节不确定时必须询问**：不要擅自决定文档位置
 - **内容不明确时必须询问**：不要编造技术内容
- **确认用户意图**：在生成大量内容前，先确认主题和范围
- **保持一致性**：新文档的风格应与现有文档一致
-
-## 注意事项
-
- 根据用户指示可以修改已有的 nav 条目（重命名、移动位置、删除等）
- 如果需要新建目录，同时创建该目录的 `index.md`
- 推送后告知用户 CI/CD 部署通常需要 1-2 分钟
+- **确认用户意图**：生成大量内容前，先确认主题和范围
+- **保持一致性**：新文档风格与现有文档一致
+- **新建目录时**：同时创建该目录的 `index.md`