refactor: 完善 todo 和 wiki skill 的自包含操作指南
- todo: 明确 mysql_query MCP 工具调用方式，补充触发词和字段说明 - todo/setup: 补充 QwenPaw 和 Claude Code 两种配置方式，修正环境变量名 - wiki: 用 glob_search 替换 <skill-path> 占位符，流程更清晰
This commit is contained in:
+74
-53
@@ -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 条旧任务
|
||||
|
||||
+47
-53
@@ -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` 状态的事项
|
||||
|
||||
Reference in New Issue
Block a user