From learning-skills
Organizes tags in WPS Notes using wpsnote-cli CLI commands without MCP service. Follows workflow to assess, diagnose, propose schemes, and execute tag cleanup or refactoring on user requests like messy tags or reclassification.
npx claudepluginhub wpsnote/wpsnote-skills --plugin learning-skillsThis skill uses the workspace's default tool permissions.
启动本 Skill 的第一步，必须先检查 `wpsnote-cli` 是否可用：
Provides core principles and workflow for organizing, cleaning, and optimizing note tags in WPS Notes via MCP service. Activates on requests like 'sort note tags' or 'refactor labels'.
Analyzes vault tags to identify unused, orphan, near-duplicate, over-used, and under-used ones. Suggests merges and cleanup actions.
Orchestrates Joplin MCP tools for note, notebook, and tag management. Guides setup via API token, editing vs updating notes, reading long content, ID handling, bulk tagging, and workflows.
Share bugs, ideas, or general feedback.
启动本 Skill 的第一步，必须先检查 wpsnote-cli 是否可用：
wpsnote-cli status --json
如果命令不存在或返回连接失败，立即停止，告知用户：
这个功能需要配合 WPS 笔记使用。请按以下步骤开通：
- 下载并安装 WPS 笔记应用（如已安装请跳过）
- 打开应用后，点击左下角的「设置」
- 进入 「AI 实验室」
- 开通后重新发送你的需求，即可开始整理
开通后再次调用 wpsnote-cli status --json 确认连接正常，再继续后续流程。
所有 WPS 笔记操作直接在系统命令行中执行 wpsnote-cli 命令：
wpsnote-cli <子命令> [参数]
复杂参数（含 JSON、XML 内容）一律通过 --json-args 传入，避免 shell 转义问题：
wpsnote-cli <子命令> --json-args '{"key": "value", "content": "<p>XML内容</p>"}'
所有写操作加 --json 获取结构化返回值，方便提取 note_id / block_id。
| 操作 | CLI 命令 |
|---|---|
| 获取笔记统计（含标签分布） | wpsnote-cli stats --detailed true --json |
| 查找所有标签 | wpsnote-cli tags --json |
| 按关键词搜索标签 | wpsnote-cli tags --keyword "标签名" --json |
| 按标签筛选笔记 | wpsnote-cli find --json-args '{"tags":["标签名"]}' |
| 列出所有笔记 | wpsnote-cli list --json |
| 获取笔记大纲 | wpsnote-cli outline --note_id <id> --json |
| 读取笔记全文 | wpsnote-cli read --note_id <id> --json |
| 读取指定 block | wpsnote-cli read-blocks --json-args '{"note_id":"...","block_ids":["..."]}' |
| 搜索笔记内容 | wpsnote-cli search --note_id <id> --query "#标签名" --json |
| 编辑单个 block | wpsnote-cli edit --json-args '{"note_id":"...","op":"replace","block_id":"...","content":"<p>...</p>"}' |
| 批量编辑 | wpsnote-cli batch-edit --json-args '{"note_id":"...","operations":[...]}' |
整理标签不是在执行一套标准方法论，而是在服务一个具体的人。没有统一的「正确」分类方式，一切决策以用户的实际需求为准。
整理的价值只来自三个方向，不能带来其中任何一项的改动都不值得做：
不要在任务开始时反问用户「你想整理什么范围、怎么整理」。用户找 AI 来整理，本身就意味着他不想自己做这些判断。AI 的职责是主动给出具体方案，让用户做选择题，而不是问答题。
当前阶段只做打标。 标签没有专属位置，可能出现在任意 block 中——修改标签必须通过修改 block 内容来实现。
三条硬性规则，每次操作都必须遵守：
操作前必须读完整 block：先用 wpsnote-cli read-blocks 获取目标 block 的完整内容，在新内容中只改标签部分（<tag> 元素或 #标签 文本），其余内容原样保留后再用 wpsnote-cli edit 写回。未读完整就直接写回会导致 block 内正文文字丢失，不可恢复。
意图不明的笔记直接跳过：无法确定内容主题或用途时，不猜测、不修改，在方案中列为「未处理」告知用户。判断标准：内容极少看不出主题、无法确定用户是否仍关注、打什么标签都不确定。
不删除任何笔记：无论笔记看起来多空，都不在此阶段做任何笔记删除。
在 WPS 笔记中操作时，以下系统行为会影响结果，必须了解：
| 行为 | 说明 | 应对方式 |
|---|---|---|
/ 表示层级分隔 | 标签名中的 / 是层级分隔符，写入 #父级/子级 时 WPS 自动将其解析为父子关系 | 写完整路径，如 <tag>#工作/项目</tag>，不要把父级名和子级名分段拼接后再合并 |
| 标签名小写存储 | WPS 笔记中所有英文字母均以小写存储，这是系统级规则，与写入方式无关（GTD笔记 → gtd笔记） | 已知限制，无法通过 CLI 修复，请勿尝试将小写转大写 |
| 标签自动清理 | 标签失去所有笔记引用后，WPS 笔记会异步自动删除，不会立即消失 | 验证时不以标签立即消失为判断标准 |
第一步：全局概览，判断健康度
↓
第二步：分析与诊断
↓
第三步：给出具体方案 ──→ [结论：不需要整理] → 说明理由，结束
↓
第四步：用户确认 ──→ [有异议] → 修改方案，回到第四步
↓
第五步：执行
↓
第六步：回顾检查 ──→ [有偏差] → 修正，重新检查
选择合适的命令查看当前笔记和标签列表，了解整体状况，再决定深入哪些地方。
wpsnote-cli stats --detailed true --json
wpsnote-cli tags --json
完成这两步后，通常已能发现大多数问题（颗粒度失衡、命名不一致、无标签文件过多等），并形成整理方向的初步判断。
根据第一层发现的线索，有针对性地使用以下命令，不要全量展开：
| 想了解的内容 | 用哪个命令 |
|---|---|
| 某个可疑标签下都有哪些文件 | wpsnote-cli find --json-args '{"tags":["标签名"]}' |
| 某篇文件大概讲什么、标签在哪 | wpsnote-cli outline --note_id <id> --json |
| 某篇文件的某几个 block 的精确内容 | wpsnote-cli read-blocks --json-args '{"note_id":"...","block_ids":["..."]}' |
| 某篇文件的完整内容（需要深度理解或精确改标签时） | wpsnote-cli read --note_id <id> --json |
| 在某篇长文件里快速找到标签所在 block | wpsnote-cli search --note_id <id> --query "#标签名" --json |
原则：用最轻量的命令满足当前需求，只在必要时才读全文。
在完整信息的基础上，识别用户的分类习惯，并逐项对照下方问题诊断表检查。
已有习惯是有价值的资产，不是需要纠正的问题。如果用户已有固定习惯且分类逻辑合理，不要轻易打破。
分析时同时结合笔记内容思考：每篇笔记用户为什么存了它？服务于什么场景？未来会用什么关键词检索？这决定了标签是否有真实的检索价值。
当已有标签极少（例如有意义的标签少于 3 个）时，不足以判断用户的分类偏好，此时跳过以下诊断，改为根据笔记内容为用户从头设计标签体系。
→ 查阅 references/classification-methods.md，根据用户场景选择合适的分类方法，并在第三步明确说明选择理由，让用户确认。不确定时默认推荐层级分类法（适应性最广，最易上手）。
1. 重复 / 语义相同
| 说明 | |
|---|---|
| 正常状态 | 同一概念只有一个标签，命名风格统一（中英文、缩写、全称选其一） |
| 问题表现 | 待办 / TODO / to-do 并存；AI 和 人工智能 并存；会议 和 meeting 并存 |
| 处理建议 | 合并为用户更常用的那个；原标签失去所有引用后会由系统自动清理 |
2. 层级结构不合理
| 说明 | |
|---|---|
| 正常状态 | 父子关系在语义上成立（子标签是父标签的具体化）；同级标签是真正的并列概念；每层标签数量适中，层级深度有实际意义 |
| 问题表现（层级错位） | 同级概念被误放成父子关系：学习/数学/语文，数学 和 语文 是并列学科，语文 不应挂在 数学 下面 |
| 问题表现（同级过多） | 一个层级中有几十个标签全部平铺，没有任何分组，标签列表冗长——此时应将同类标签归入共同的父标签 |
| 问题表现（层级冗余） | 一个层级中只有一个标签，中间层没有其他并列项，也不带来额外的过滤价值——此时应合并或移除中间层 |
| 判断方法 | 每个层级都问：「这一层的意义是什么？未来可能会有哪些概念与它并列？」答不上来的层级不应存在；同级标签较多时，考虑是否有可以归类的共同上级 |
| 处理建议 | 层级错位 → 修正父子关系；同级过多 → 找出共同属性，建立父标签做归类；层级冗余 → 合并或移除中间层 |
3. 标签颗粒度失衡
| 说明 | |
|---|---|
| 正常状态 | 每个标签关联的文件数量适中，能有效过滤（既不过宽也不过细） |
| 问题表现（过细） | 某标签只关联 1-2 篇文件，且这些文件已被更合适的父标签覆盖——此标签是冗余的 |
| 问题表现（过粗） | 某标签关联了大量文件，点开后几乎等于「全部笔记」，检索时没有过滤价值 |
| 处理建议 | 过细 → 合并到父标签或相近标签；过粗 → 拆分子标签，引导用户使用更精确的分类 |
4. 命名风格不一致
| 说明 | |
|---|---|
| 正常状态 | 同一层级的标签命名风格统一（词性、语言一致） |
| 问题表现 | 同级标签中部分用名词、部分用动词；中英文混用；全角半角符号混用 |
| 处理建议 | 以用户现有的多数标签风格为基准统一；命名风格本身没有对错，统一即可 |
| 排除项 | 英文字母大小写差异不属于命名风格问题。WPS 笔记中所有英文字母均以小写存储，这是系统级规则，无法通过 CLI 修复，无需处理。 |
5. 笔记覆盖不均衡
| 说明 | |
|---|---|
| 正常状态 | 大多数笔记有标签，标签体系能覆盖用户的主要内容类型 |
| 问题表现 | 大量笔记没有任何标签，或某一类内容（如近期新增笔记）系统性地缺少标签 |
| 处理建议 | 为无标签笔记补充标签；缺口过大时优先处理最常用、最重要的内容 |
如果以上问题均不存在： → 进入第三步，直接告知用户「建议保持现状」并说明理由。
直接呈现改动后的目标标签体系结构，附上每条改动的理由。不要只列问题，要给出完整的目标状态。
方案格式示例：
建议改动后的标签体系：
工作
├── 项目 ← 原 #项目A、#项目B 统一归入此处
└── 日常 ← 原 #工作记录 改为此，更简洁
学习 ← 原 #读书 和 #网课 合并入此
├── 读书
└── 网课
生活 ← 保持不变
待办 ← 原 #TODO、#to-do 合并为此（用户最常用的写法）
未处理：「未命名笔记」「未命名笔记(1)」（内容为空或无法判断意图，请用户自行决定）
情况一：只需要少量改动
→ 直接列出具体的几条改动，说明理由，进入第四步确认。
情况二：需要较大范围重建
→ 先呈现整体目标结构，再列出主要改动点，让用户对全貌有判断后再确认。
等待用户基于方案给出判断。
情况一：用户同意
→ 进入第五步执行。
情况二：用户提出异议或质疑
→ 重新思考方案，不要辩解。用户的质疑通常指向方案中逻辑不自洽的地方。修改后重新呈现，回到第四步。
情况三：用户部分同意
→ 只执行用户确认的部分，存疑的部分暂缓，等用户进一步确认。
按确认后的方案执行改动。执行每个操作前，先说一句话告知用户正在做什么，不允许沉默直接调用：
执行规模判断：
每次写操作的标准流程：
# 1. 找到标签所在 block
wpsnote-cli search --note_id <id> --query "#旧标签名" --json
# 2. 读取该 block 完整内容
wpsnote-cli read-blocks --json-args '{"note_id":"<id>","block_ids":["<block_id>"]}'
# 3. 只修改 <tag> 元素，其余内容原样保留，写回
wpsnote-cli edit --json-args '{"note_id":"<id>","op":"replace","block_id":"<block_id>","content":"<p><tag>#新标签</tag></p>"}'
执行完成后，主动验证结果，不能依赖用户来发现问题。
必须验证两个层面：
<tag> 元素，block 内其他内容是否完整；层级标签格式为 #父级/子级wpsnote-cli read-blocks --json-args '{"note_id":"<id>","block_ids":["<block_id>"]}'
wpsnote-cli tags --json
情况一：结果与预期一致
→ 向用户呈现改动摘要，说明有无已知遗留问题（如系统限制导致的标签小写存储）。
情况二：发现偏差
→ 找到原因，修正，重新检查，直到结果与预期一致再向用户汇报。不要在偏差未修正前向用户声称完成。
| 错误 | 后果 | 正确做法 |
|---|---|---|
| 层级标签写法错误 | 父子关系解析、筛选出现异常 | 多级路径用 / 分隔：<tag>#工作/项目</tag> |
| 一开始就逐篇读所有文件 | 效率极低，文件多时完全不可行 | 先用 stats + tags 建立全局视图，再按需深入 |
| 需要读全文时截断内容 | 漏掉标签，误判内容性质 | wpsnote-cli read 不加截断参数 |
| 只看笔记块预览，不读系统标签列表 | 遗漏未发现的残留标签 | 两个视角都验证 |
| 任务开始时先问用户想整理什么 | 把负担推回给用户 | 先读后分析，主动给出具体方案 |
| 结论是不需要整理时强行提改动 | 引入不必要风险 | 明确说「建议保持现状」并说明理由 |
| 用户有异议时辩解而不是修改方案 | 方案逻辑缺陷被掩盖 | 重新思考，修改后再呈现 |
| 执行后不主动回顾检查 | 偏差未被发现 | 执行后必须验证块内容和标签列表 |
| 未读完整 block 就直接写回 | block 内的非标签文字丢失，不可恢复 | 先用 read-blocks 读取完整内容，只改标签部分，其余原样保留后再写回 |
| 对意图不明的笔记强行打标 | 标签不准确，干扰检索 | 跳过，列为「未处理」告知用户 |
| 删除看起来为空的笔记 | 可能丢失用户数据 | 不在此阶段做任何笔记删除 |
| 为了「整洁」而整洁 | 用户体验未改善，还引入风险 | 每次改动都对应具体的效率提升或检索价值 |
| 执行前不通知用户 | 用户不知道 AI 在做什么 | 每个操作前先说一句话告知 |