wpsnote/wpsnote-skills/tag-organize-cli

笔记标签整理核心原则与流程（CLI 版）

CLI 工具适配

启动本 Skill 的第一步，先检查连接状态：

wpsnote-cli status --json

如果命令不存在或返回连接失败，停止执行并告知用户需要先安装并打开 WPS 笔记、在「设置」→「AI 实验室」中开通能力，然后重新运行 wpsnote-cli status --json 确认。

所有 WPS 笔记操作直接在系统命令行中执行 wpsnote-cli；复杂参数一律通过 --json-args 传入，所有需要结构化结果的命令加 --json。

wpsnote-cli manage-tags --note_id "<id>" --json-args '{"add":["工作/项目"],"remove":["旧标签"]}' --json

标签整理写入只使用 wpsnote-cli manage-tags。read、outline、read-blocks 只用于理解内容，不用于改标签。

核心原则

整理标签不是在执行一套标准方法论，而是在服务一个具体的人。没有统一的「正确」分类方式，一切决策以用户的实际需求为准。

整理的价值只来自三个方向，不能带来其中任何一项的改动都不值得做：

• 提升使用效率：减少维护负担，降低分类焦虑
• 提升检索效率：让用户更快找到目标内容
• 带来新的知识连接视角：发现原来看不到的关联

不要在任务开始时反问用户「你想整理什么范围、怎么整理」。用户找 AI 来整理，本身就意味着他不想自己做这些判断。AI 的职责是主动给出具体方案，让用户做选择题，而不是问答题。

操作安全约束

当前阶段只做打标。 笔记标签是文件级独立对象，通过专用命令 wpsnote-cli manage-tags 增删改。

硬性规则，每次操作都必须遵守：

1. 修改标签只用 `wpsnote-cli manage-tags`：

• 查询某笔记当前标签：wpsnote-cli manage-tags --note_id <id> --json
• 添加：wpsnote-cli manage-tags --note_id <id> --json-args '{"add":["工作/项目"]}' --json
• 删除：wpsnote-cli manage-tags --note_id <id> --json-args '{"remove":["旧标签"]}' --json
• 重命名 / 合并：在同一次调用中组合 remove + add

1. 跨笔记的全局操作必须先 `ask_user` 确认：标签的全局重命名、合并、批量删除（影响 2 篇以上笔记）属于跨笔记批量操作，执行前必须调用 ask_user。

1. 意图不明的笔记直接跳过：无法确定内容主题或用途时，不猜测、不修改，在方案中列为「未处理」告知用户。

1. 不删除任何笔记：无论笔记看起来多空，都不在此阶段做任何笔记删除。

1. 确认必须用 `ask_user` 工具：禁止用文本提问代替 ask_user 调用——文本提问不会暂停执行，用户无法介入。调用 ask_user 的同一轮中禁止执行写入命令。

WPS 笔记系统行为说明

在 WPS 笔记中操作时，以下系统行为会影响结果，必须了解：

任务流程

第一步：全局概览，判断健康度
    ↓
第二步：分析与诊断
    ↓
第三步：给出具体方案  ──→  [结论：不需要整理] → 说明理由，结束
    ↓
第四步：用户确认  ──→  [有异议] → 修改方案，回到第四步
    ↓
第五步：执行
    ↓
第六步：回顾检查  ──→  [有偏差] → 修正，重新检查

第一步：全局概览，判断健康度

选择合适的命令查看当前笔记文件和标签列表，了解当前笔记系统的整体状况，再决定深入哪些地方。

第一层：必做（全局概览）

1. `wpsnote-cli stats --detailed true --json` — 一次调用获得：

• 文件总数、标签总数、无标签文件数
• 每个标签下的文件数量分布（按笔记数降序，最多返回 30 个；标签较多时结合 wpsnote-cli tags --json 看全量）
• 近期更新的文件列表

1. `wpsnote-cli tags --json` — 获得：

• 完整的标签层级结构（父子关系、命名）
• 识别命名风格、层级逻辑、可疑标签名

完成这两步后，通常已能发现大多数问题（颗粒度失衡、命名不一致、无标签文件过多等），并形成整理方向的初步判断。

第二层：按需调查（针对发现的问题）

根据第一层发现的线索，针对性使用以下命令按需调查：

原则：用最轻量的命令满足当前需求：outline 能定位时优先用它；find --tags 能筛选时优先用它；仅在需要完整内容理解时才用 read。

第二步：分析与诊断

在完整信息的基础上，识别用户的分类习惯，并逐项对照下方问题诊断表检查。

已有习惯是有价值的资产，不是需要纠正的问题。如果用户已有固定习惯且分类逻辑合理，不要轻易打破。

分析时同时结合笔记内容思考：每篇笔记用户为什么存了它？服务于什么场景？未来会用什么关键词检索？这决定了标签是否有真实的检索价值。

前置判断：标签数量过少，无法诊断

当已有标签极少时，不足以判断用户的分类偏好，此时跳过以下诊断，改为根据笔记内容为用户从头设计标签体系。

→ 查阅 references/classification-methods.md，根据用户场景从中选择合适的分类方法（层级分类法 / P.A.R.A. / 实体场景法），并在第三步明确说明选择理由，让用户确认。不确定时默认推荐层级分类法（适应性最广，最易上手）。

问题诊断表

1. 重复 / 语义相同

2. 层级结构不合理

3. 标签颗粒度失衡

4. 命名风格不一致

5. 笔记覆盖不均衡

如果以上问题均不存在： → 进入第三步，直接告知用户「建议保持现状」并说明理由。

第三步：给出具体方案

直接呈现改动后的目标标签体系结构，附上每条改动的理由——完整呈现目标状态，便于用户对比判断。

方案格式示例：

建议改动后的标签体系：
 
工作
├── 项目            ← 原 项目A、项目B 统一归入此处
└── 日常            ← 原 工作记录 改为此，更简洁
 
学习               ← 原 读书 和 网课 合并入此
├── 读书
└── 网课
 
生活               ← 保持不变
 
待办               ← 原 TODO、to-do 合并为此（用户最常用的写法）
 
未处理：「未命名笔记」「未命名笔记(1)」（内容为空或无法判断意图，请用户自行决定）

情况一：只需要少量改动

→ 直接列出具体的几条改动，说明理由，进入第四步确认。

情况二：需要较大范围重建

→ 先呈现整体目标结构，再列出主要改动点，让用户对全貌有判断后再确认。

第四步：用户确认

通过 ask_user 工具获取用户确认。

情况一：用户同意

→ 进入第五步执行。

情况二：用户提出异议或质疑

→ 重新思考方案。用户的质疑通常指向方案中逻辑不自洽的地方，据此修改后重新呈现，回到第四步。

情况三：用户部分同意

→ 只执行用户确认的部分，存疑的部分暂缓，等用户进一步确认。

第五步：执行

按确认后的方案执行改动。

执行规模判断：

• 改动少（个位数）→ 一次完成
• 改动多 → 分批执行，每批按逻辑单元划分（如：先处理全局合并操作，再处理单篇笔记调整）

第六步：回顾检查

执行完成后，主动验证结果。

必须验证两个层面：

1. 目标笔记的标签：从 wpsnote-cli manage-tags 写入返回值检查——tags 是更新后的完整标签列表，added / removed 是实际生效的项；确认目标标签在 tags 中、层级以 / 正确体现
2. 系统标签列表（wpsnote-cli tags --json）：确认新标签已创建、合并/删除的旧标签已消失，整体结构符合方案

情况一：结果与预期一致

→ 向用户呈现改动摘要，说明有无遗留问题（例如某些笔记被跳过的原因）。

情况二：发现偏差

→ 找到原因，修正，重新检查，直到结果与预期一致后再向用户汇报。