From 14e93d2001e7809e8298121bc3b46deab57bbf2a Mon Sep 17 00:00:00 2001 From: wonder Date: Tue, 1 Sep 2026 20:58:53 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E5=AE=8C=E5=96=84=20todo=20?= =?UTF-8?q?=E5=92=8C=20wiki=20skill=20=E7=9A=84=E8=87=AA=E5=8C=85=E5=90=AB?= =?UTF-8?q?=E6=93=8D=E4=BD=9C=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - todo: 明确 mysql_query MCP 工具调用方式，补充触发词和字段说明 - todo/setup: 补充 QwenPaw 和 Claude Code 两种配置方式，修正环境变量名 - wiki: 用 glob_search 替换 占位符，流程更清晰 --- todo/SKILL.md | 127 +++++++++++++++++++++++---------------- todo/references/setup.md | 100 +++++++++++++++--------------- wiki/SKILL.md | 69 +++++++++++---------- 3 files changed, 157 insertions(+), 139 deletions(-) diff --git a/todo/SKILL.md b/todo/SKILL.md index e82515f..226bcd2 100644 --- a/todo/SKILL.md +++ b/todo/SKILL.md @@ -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 (); ``` ### 查看已完成 -用户说："已完成的任务" / "看看做完了哪些" +触发词：已完成的任务 / 做完了哪些 ```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 = OR title LIKE '%<关键词>%'; +WHERE 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 = ; ### 更新任务 -用户说："修改 XXX 的描述为 YYY" / "把 XXX 的优先级改为 high" +触发词：修改 XXX 的描述/优先级/标题 ```sql UPDATE todos SET <字段> = '<新值>', last_accessed_at = NOW(), access_count = access_count + 1 WHERE id = ; ``` +可更新字段：`title`、`description`、`priority`、`status` + ### 删除任务 -用户说："删除任务 XXX" / "去掉这个待办" +触发词：删除任务 / 去掉这个待办 **软删除（推荐）**： @@ -107,62 +130,60 @@ WHERE id = ; UPDATE todos SET status = 'archived' WHERE id = ; ``` -**硬删除**（用户明确要求彻底删除时）： +**硬删除**（用户明确要求时）： ```sql DELETE FROM todos WHERE 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 条旧任务 diff --git a/todo/references/setup.md b/todo/references/setup.md index a83880f..9cd9184 100644 --- a/todo/references/setup.md +++ b/todo/references/setup.md @@ -4,35 +4,57 @@ 推荐使用 `@benborla29/mcp-server-mysql`（支持读写操作）。 -### 配置方式 +### QwenPaw 配置方式 -在项目的 `.mcp.json` 文件中添加（或在 `~/.claude.json` 中配置）： +在 `~/.qwenpaw/config.json` 的 `mcp.clients` 中添加： ```json -{ - "mcpServers": { - "mysql": { - "command": "npx", - "args": ["-y", "@benborla29/mcp-server-mysql"], - "env": { - "MYSQL_HOST": "<替换为你的主机地址>", - "MYSQL_PORT": "<替换为你的端口，默认 3306>", - "MYSQL_USER": "<替换为你的用户名>", - "MYSQL_PASSWORD": "<替换为你的密码>", - "MYSQL_DATABASE": "<替换为你的数据库名>" - } - } +"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_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` 状态的事项 diff --git a/wiki/SKILL.md b/wiki/SKILL.md index 92829d2..81b9987 100644 --- a/wiki/SKILL.md +++ b/wiki/SKILL.md @@ -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` 后缀）。 + +后续步骤中用 `` 代指该路径。 + +### 2. SSH 连通性检查 ```bash -bash /scripts/check_ssh.sh +bash /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`） -- 如果内容不完整，询问用户补充 +- 分析内容主题，判断合适章节 +- 整理成标准格式（参考 `/references/article-template.md`） +- 内容不完整时询问用户补充 **场景 C — 更新现有文档**：用户说"更新 XXX 文章" - 在仓库中找到对应文件 - 根据用户要求更新内容 -**场景 D — 章节不明确**：无法确定放在哪里 -- 列出当前仓库的章节结构供用户选择 -- 询问用户该内容属于哪个章节，或是否需要新建章节 +**场景 D — 章节不明确**： +- 先查看仓库目录结构：`ls $TMP_DIR/` +- 列出当前章节供用户选择 +- 询问是否需要新建章节 -### 4. 生成/更新文档 +### 5. 生成/更新文档 -遵循 `references/article-template.md` 中的标准格式。关键要点： +遵循 `/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` 了解当前导航结构和规范。 +参考 `/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`