wonder/my-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- todo: 明确 mysql_query MCP 工具调用方式，补充触发词和字段说明
- todo/setup: 补充 QwenPaw 和 Claude Code 两种配置方式，修正环境变量名
- wiki: 用 glob_search 替换 <skill-path> 占位符，流程更清晰
This commit is contained in:
wonder
2026-09-01 20:58:53 +08:00
parent be7720e732
commit 14e93d2001
3 changed files with 157 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
todo/SKILL.md
+74 -53
View File
@@ -11,43 +11,56 @@ description: |
通过自然语言管理 MySQL 数据库中的待办事项，支持 LRU 自动淘汰。 通过自然语言管理 MySQL 数据库中的待办事项，支持 LRU 自动淘汰。
## 前置条件 ## 工具说明
此 skill 依赖 MySQL MCP 工具。使用前需确认： 本 skill 依赖 **MySQL MCP 工具** `mysql_query`。所有数据库操作都通过该工具执行。
1. MySQL MCP 已配置（参考 `references/setup.md`） 调用方式：使用 `execute_shell_command` 执行 MySQL MCP 查询，或直接使用 MCP 工具（如可用）。
2. todos 表已创建（参考 `references/setup.md` 中的建表 SQL）
如果 MCP 工具不可用，引导用户参考 `references/setup.md` 完成配置。 如果 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 ```sql
INSERT INTO todos (title, description, priority) VALUES ('<标题>', '<描述>', '<优先级>'); INSERT INTO todos (title, description, priority) VALUES ('<标题>', '<描述>', '<优先级>');
``` ```
- 优先级默认 `medium`，如果用户提到"紧急/urgent"则为 `urgent`，"重要"为 `high` - 优先级默认 `medium`
- 添加后自动执行 LRU 检查（见淘汰策略） - 用户说"紧急/urgent/马上/ASAP" → `urgent`
- 用户说"重要" → `high`
- 用户说"不急/有空/low" → `low`
- 添加后执行 LRU 检查（见下方淘汰策略）
### 查看待办 ### 查看待办
用户说："我的待办" / "有什么任务" / "看看今天的任务" 触发词：我的待办 / 有什么任务 / 今天要做什么 / 列出任务
```sql ```sql
SELECT id, title, status, priority, last_accessed_at SELECT id, title, status, priority, DATE_FORMAT(updated_at, '%m-%d') AS updated
FROM todos FROM todos
WHERE status IN ('pending', 'in_progress') WHERE status IN ('pending', 'in_progress')
ORDER BY ORDER BY
CASE priority FIELD(priority, 'urgent', 'high', 'medium', 'low'),
WHEN 'urgent' THEN 0
WHEN 'high' THEN 1
WHEN 'medium' THEN 2
WHEN 'low' THEN 3
END,
last_accessed_at DESC; last_accessed_at DESC;
``` ```
@@ -55,33 +68,41 @@ ORDER BY
```sql ```sql
UPDATE todos SET last_accessed_at = NOW(), access_count = access_count + 1 UPDATE todos SET last_accessed_at = NOW(), access_count = access_count + 1
WHERE id IN (<查看到的 id 列表>); WHERE id IN (<id 列表>);
``` ```
### 查看已完成 ### 查看已完成
用户说："已完成的任务" / "看看做完了哪些" 触发词：已完成的任务 / 做完了哪些
```sql ```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' FROM todos WHERE status = 'done'
ORDER BY updated_at DESC; ORDER BY updated_at DESC;
``` ```
### 标记完成 ### 标记完成
用户说："完成 XXX" / "把这个标记为完成" / "做完了" 触发词：完成 XXX / 标记为完成 / 做完了
```sql ```sql
UPDATE todos SET status = 'done', last_accessed_at = NOW(), access_count = access_count + 1 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 ```sql
UPDATE todos SET status = 'in_progress', last_accessed_at = NOW(), access_count = access_count + 1 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 ```sql
UPDATE todos SET <字段> = '<新值>', last_accessed_at = NOW(), access_count = access_count + 1 UPDATE todos SET <字段> = '<新值>', last_accessed_at = NOW(), access_count = access_count + 1
WHERE id = <id>; WHERE id = <id>;
``` ```
可更新字段：`title`、`description`、`priority`、`status`
### 删除任务 ### 删除任务
用户说："删除任务 XXX" / "去掉这个待办" 触发词：删除任务 / 去掉这个待办
**软删除（推荐）**： **软删除（推荐）**：
@@ -107,62 +130,60 @@ WHERE id = <id>;
UPDATE todos SET status = 'archived' WHERE id = <id>; UPDATE todos SET status = 'archived' WHERE id = <id>;
``` ```
**硬删除**（用户明确要求彻底删除时）： **硬删除**（用户明确要求时）：
```sql ```sql
DELETE FROM todos WHERE id = <id>; DELETE FROM todos WHERE id = <id>;
``` ```
- 硬删除前必须确认，列出将被删除的事项 - 硬删除前必须列出将被删除的事项并确认
- 默认使用软删除（归档），保护数据 - 默认用软删除
### 搜索任务 ### 搜索任务
用户说："找一下关于 XXX 的任务" 触发词：找一下关于 XXX 的任务 / 有没有 XXX
```sql ```sql
SELECT id, title, description, status, priority SELECT id, title, status, priority
FROM todos FROM todos
WHERE title LIKE '%<关键词>%' OR description LIKE '%<关键词>%' WHERE title LIKE '%<关键词>%' OR description LIKE '%<关键词>%'
ORDER BY status, priority; ORDER BY FIELD(status, 'in_progress', 'pending', 'done', 'archived'), priority;
``` ```
## LRU 淘汰策略 ## LRU 淘汰策略
### 自动触发 每次 INSERT 后检查总数：
每次 INSERT 后检查：
```sql ```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. 仍超标则归档最久未访问的待办事项
2. **其次归档待办**：如果仍超标，归档最久未访问的 `pending` 事项 UPDATE todos SET status = 'archived'
3. **保护进行中**：不归档 `in_progress` 状态的事项 WHERE status = 'pending'
4. **告知用户**：归档时列出被归档的事项标题 ORDER BY last_accessed_at ASC LIMIT 10;
```
### 手动触发 **保护规则**：不归档 `in_progress` 状态的事项。
用户说："清理旧任务" / "归档一些任务" / "整理一下待办"
执行同样的归档逻辑，但需要先告知用户当前待办数量，并询问是否确认清理。
## 交互原则 ## 交互原则
- **模糊匹配时确认**：如果用户说的关键词匹配多条任务，列出选项让用户确认 - **模糊匹配时确认**：关键词匹配多条任务，列出选项让用户选
- **操作前预览**：删除/归档操作前，显示受影响的事项列表 - **操作前预览**：删除/归档前，先 `SELECT` 显示受影响的事项
- **优先级合理推断**：用户说"紧急""马上""ASAP" → urgent；"重要" → high；默认 → medium - **自然语言理解**：用户说"帮我记一下明天要买菜" → 添加任务"买菜"
- **自然语言理解**：用户可能说"帮我记一下明天要买菜"，理解为添加任务"买菜" - **状态转换合理**：不允许 archived → in_progress 等不合理跳转
- **状态转换合理**：不要让用户手动做不合理的状态跳转（如 archived → in_progress）
## 输出格式 ## 输出格式
查询结果以表格形式展示： 查询结果用表格展示：
``` ```
| ID | 标题 | 状态 | 优先级 | 更新时间 | | ID | 标题 | 状态 | 优先级 | 更新时间 |
@@ -170,7 +191,7 @@ SELECT COUNT(*) FROM todos WHERE status != 'archived';
| 1 | xxx | 待办 | 高 | 08-31 | | 1 | xxx | 待办 | 高 | 08-31 |
``` ```
操作结果用简洁的确认语句： 操作结果用简洁确认：
- ✓ 已添加任务：XXX - ✓ 已添加任务：XXX
- ✓ 已完成任务：XXX - ✓ 已完成任务：XXX
- ✓ 已归档 5 条旧任务 - ✓ 已归档 5 条旧任务
todo/references/setup.md
+47 -53
View File
@@ -4,35 +4,57 @@
推荐使用 `@benborla29/mcp-server-mysql`（支持读写操作）。 推荐使用 `@benborla29/mcp-server-mysql`（支持读写操作）。
### 配置方式 ### QwenPaw 配置方式
在项目的 `.mcp.json` 文件中添加（或在 `~/.claude.json` 中配置）： 在 `~/.qwenpaw/config.json` 的 `mcp.clients` 中添加：
```json ```json
{ "mysql": {
"mcpServers": { "name": "mysql",
"mysql": { "description": "MySQL MCP for todo skill",
"command": "npx", "enabled": true,
"args": ["-y", "@benborla29/mcp-server-mysql"], "transport": "stdio",
"env": { "command": "npx",
"MYSQL_HOST": "<替换为你的主机地址>", "args": ["-y", "@benborla29/mcp-server-mysql"],
"MYSQL_PORT": "<替换为你的端口，默认 3306>", "env": {
"MYSQL_USER": "<替换为你的用户名>", "MYSQL_HOST": "<主机地址>",
"MYSQL_PASSWORD": "<替换为你的密码>", "MYSQL_PORT": "<端口，默认 3306>",
"MYSQL_DATABASE": "<替换为你的数据库名>" "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 可用 ### 验证 MCP 可用
配置完成后重启 Claude Code，然后尝试： 配置完成后重启客户端，然后尝试：
- 列出数据库中的表 - 列出数据库中的表
- 执行一条简单查询 - 执行一条简单查询
如果 MCP 工具可用，会看到 `mysql` 相关的工具。 如果 MCP 工具可用，会看到 `mysql_query` 工具。
--- ---
@@ -65,48 +87,20 @@ CREATE TABLE IF NOT EXISTS todos (
| id | BIGINT UNSIGNED | 自增主键 | | id | BIGINT UNSIGNED | 自增主键 |
| title | VARCHAR(500) | 任务标题，必填 | | title | VARCHAR(500) | 任务标题，必填 |
| description | TEXT | 任务描述，可选 | | description | TEXT | 任务描述，可选 |
| status | ENUM | 状态：pending / in_progress / done / archived | | status | ENUM | pending / in_progress / done / archived |
| priority | ENUM | 优先级：low / medium / high / urgent | | priority | ENUM | low / medium / high / urgent |
| created_at | DATETIME | 创建时间，自动填充 | | created_at | DATETIME | 创建时间，自动填充 |
| updated_at | DATETIME | 更新时间，自动刷新 | | updated_at | DATETIME | 更新时间，自动刷新 |
| last_accessed_at | DATETIME | 最后访问时间，每次查看/更新时刷新 | | last_accessed_at | DATETIME | 最后访问时间，LRU 依据 |
| access_count | INT UNSIGNED | 访问计数，每次访问 +1 | | access_count | INT UNSIGNED | 访问计数，每次 +1 |
--- ---
## 3. LRU 淘汰策略 ## 3. LRU 淘汰策略
### 原理
基于 `last_accessed_at` 字段实现 LRU（Least Recently Used）淘汰： 基于 `last_accessed_at` 字段实现 LRU（Least Recently Used）淘汰：
- 每次查看、更新 todo 时，刷新 `last_accessed_at` 为当前时间，`access_count` +1 - 每次查看、更新 todo 时刷新 `last_accessed_at` 和 `access_count`
- 当待办事项总数超过阈值（默认 100 条非 archived 记录）时，自动触发归档 - 待办总数超过 100 条时自动归档
- 归档优先级：先归档最久未访问的 `done` 事项，再归档最久未访问的 `pending` 事项 - 先归档最久未访问的 `done` 事项，再归档 `pending` 事项
- 不归档 `in_progress` 状态的事项
### 归档 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` 状态的事项（保护正在做的任务）
wiki/SKILL.md
+36 -33
View File
@@ -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
bash <skill-path>/scripts/check_ssh.sh bash <skill-dir>/scripts/check_ssh.sh
``` ```
如果检查失败，告知用户需要配置 SSH 密钥，不要继续操作。 如果检查失败，告知用户需要配置 SSH 密钥，不要继续操作。
### 2. 克隆仓库 ### 3. 克隆仓库
```bash ```bash
TMP_DIR=$(mktemp -d) TMP_DIR=$(mktemp -d)
@@ -32,31 +43,30 @@ git clone ssh://git@47.121.181.112:222/wonder/docs.git "$TMP_DIR"
后续所有文件操作在 `$TMP_DIR` 中进行。 后续所有文件操作在 `$TMP_DIR` 中进行。
### 3. 理解用户意图 ### 4. 理解用户意图
用户可能以不同方式使用此 skill：
**场景 A — 提供主题**：用户说"写一篇关于 XXX 的文章" **场景 A — 提供主题**：用户说"写一篇关于 XXX 的文章"
- 根据主题判断应该放在哪个章节（algorithm/architecture/project/qiniu-cloud） - 根据主题判断章节（algorithm / architecture / project / qiniu-cloud）
- 如果章节不明确，询问用户 - 不确定时询问用户
- 按模板生成完整文档 - 按模板生成完整文档
**场景 B — 提供内容**：用户粘贴了一段文档或笔记 **场景 B — 提供内容**：用户粘贴了一段文档或笔记
- 分析内容主题，判断合适的章节 - 分析内容主题，判断合适章节
- 整理成标准格式（参考 `references/article-template.md`） - 整理成标准格式（参考 `<skill-dir>/references/article-template.md`）
- 如果内容不完整，询问用户补充 - 内容不完整时询问用户补充
**场景 C — 更新现有文档**：用户说"更新 XXX 文章" **场景 C — 更新现有文档**：用户说"更新 XXX 文章"
- 在仓库中找到对应文件 - 在仓库中找到对应文件
- 根据用户要求更新内容 - 根据用户要求更新内容
**场景 D — 章节不明确**：无法确定放在哪里 **场景 D — 章节不明确**：
- 列出当前仓库的章节结构供用户选择 - 先查看仓库目录结构：`ls $TMP_DIR/`
- 询问用户该内容属于哪个章节，或是否需要新建章节 - 列出当前章节供用户选择
- 询问是否需要新建章节
### 4. 生成/更新文档 ### 5. 生成/更新文档
遵循 `references/article-template.md` 中的标准格式。关键要点： 遵循 `<skill-dir>/references/article-template.md` 中的标准格式：
- 使用中文撰写 - 使用中文撰写
- 代码示例以 Go 为主 - 代码示例以 Go 为主
@@ -64,13 +74,13 @@ git clone ssh://git@47.121.181.112:222/wonder/docs.git "$TMP_DIR"
- 包含常见陷阱和练习题 - 包含常见陷阱和练习题
- 文件名使用 kebab-case - 文件名使用 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 ```bash
cd "$TMP_DIR" cd "$TMP_DIR"
@@ -79,25 +89,18 @@ git commit -m "docs: 添加/更新 <文档标题>"
git push origin main git push origin main
``` ```
提交信息遵循 Conventional Commits 格式（参考全局 CLAUDE.md 规范）。 ### 8. 清理
### 7. 清理
```bash ```bash
rm -rf "$TMP_DIR" rm -rf "$TMP_DIR"
``` ```
告知用户文档已推送，CI/CD 会自动部署。 告知用户文档已推送，CI/CD 通常 1-2 分钟自动部署。
## 交互原则 ## 交互原则
- **章节不确定时必须询问**：不要擅自决定文档位置 - **章节不确定时必须询问**：不要擅自决定文档位置
- **内容不明确时必须询问**：不要编造技术内容 - **内容不明确时必须询问**：不要编造技术内容
- **确认用户意图**：在生成大量内容前，先确认主题和范围 - **确认用户意图**：生成大量内容前，先确认主题和范围
- **保持一致性**：新文档的风格应与现有文档一致 - **保持一致性**：新文档风格与现有文档一致
- **新建目录时**：同时创建该目录的 `index.md`
## 注意事项
- 根据用户指示可以修改已有的 nav 条目（重命名、移动位置、删除等）
- 如果需要新建目录，同时创建该目录的 `index.md`
- 推送后告知用户 CI/CD 部署通常需要 1-2 分钟