/tag-organize-cli

name: tag-organize-cli
description: 笔记文件级标签整理的核心原则与完整工作流程（CLI 版）。通过系统命令行调用 wpsnote-cli 操作 WPS 笔记，无需 MCP 服务连接。当用户提到"整理笔记标签"、"清理标签"、"标签太乱"、"标签太多"、"帮我打标签"、"重构标签"、"重新分类"、"笔记分类混乱"、"标签体系需要优化"等需求时使用；标签管理必须使用 wpsnote-cli manage-tags，不通过编辑 block 或 <tag> XML 修改标签。
metadata:
  author: wps
  version: 1.1.1
  category: note-organization
  tags: [wps-note, cli, file-level-tags, note-organization]

笔记标签整理核心原则与流程（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

| MCP 语义 | CLI 命令 | |---|---| | `get_note_stats({ detailed: true })` | `wpsnote-cli stats --detailed true --json` | | `find_tags()` | `wpsnote-cli tags --json` | | `search_notes({ tags })` | `wpsnote-cli find --json-args '{"tags":["标签名"]}' --json` | | `get_note_info({ limit, page })` | `wpsnote-cli info --json-args '{"page":1,"page_size":50}' --json` | | `manage_note_tags({ note_id })` | `wpsnote-cli manage-tags --note_id <id> --json` | | `manage_note_tags({ note_id, add/remove })` | `wpsnote-cli manage-tags --note_id <id> --json-args '{"add":["新标签"],"remove":["旧标签"]}' --json` | | `get_note_outline({ note_id })` | `wpsnote-cli outline --note_id <id> --json` | | `read_note({ note_id })` | `wpsnote-cli read --note_id <id> --json` | | `read_blocks({ note_id, block_ids })` | `wpsnote-cli read-blocks --json-args '{"note_id":"...","block_ids":["..."]}' --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`

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

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

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

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

---

WPS 笔记系统行为说明

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

| 行为 | 说明 | 应对方式 | |------|------|---------| | `/` 表示层级分隔 | 标签名中的 `/` 是层级分隔符，WPS 自动将其解析为父子关系 | 写完整路径调用 `wpsnote-cli manage-tags --json-args '{"add":["工作/项目"]}' --json` | | 区分大小写 | 标签按用户输入原样存储，`TODO`、`Todo`、`todo` 是三个不同的标签 | 比对标签时按字面比对，不做大小写归一 | | 标签输入限制 | 最多 10 级层级，每级最多 20 字符；禁用 `\ : * ? " < > \|` 与 emoji；同一文档内不允许重复标签 | 生成新标签时主动遵守这些限制；命中系统报错时根据返回信息调整后重试 |

---

任务流程

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

---

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

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

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

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

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

2. **`wpsnote-cli tags --json`** — 获得：

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

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

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

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

| 想了解的内容 | 用哪个命令 | |---|---| | 某个可疑标签下都有哪些文件 | `wpsnote-cli find --json-args '{"tags":["标签名"]}' --json` | | 无标签的文件有哪些 | `wpsnote-cli info --json-args '{"page":1,"page_size":50}' --json` 分页查询，过滤 `tags` 为空的笔记 | | 某篇笔记当前挂着哪些标签 | `wpsnote-cli manage-tags --note_id <id> --json` | | 某篇文件大概讲什么 | `wpsnote-cli outline --note_id <id> --json` | | 某篇文件的某几个 block 的精确内容 | `wpsnote-cli read-blocks --json-args '{"note_id":"...","block_ids":["..."]}' --json` | | 某篇文件的完整内容（需要深度理解内容时） | `wpsnote-cli read --note_id <id> --json` |

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

---

第二步：分析与诊断

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

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

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

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

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

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

---

问题诊断表

**1. 重复 / 语义相同**

| | 说明 | |---|---| | 正常状态 | 同一概念只有一个标签 | | 问题表现 | `待办`、`TODO`、`to-do` 并存；`AI` 和 `人工智能` 并存；`会议` 和 `meeting` 并存 | | 处理建议 | 合并为用户更常用的那个；原标签失去所有引用后由系统自动清理 |

**2. 层级结构不合理**

| | 说明 | |---|---| | 正常状态 | 父子关系在语义上成立（子标签是父标签的具体化）；同级标签是真正的并列概念；每层标签数量适中，层级深度有实际意义 | | 问题表现（层级错位）| 同级概念被误放成父子关系：`学习/数学/语文`，`数学` 和 `语文` 是并列学科，`语文` 不应挂在 `数学` 下面 | | 问题表现（同级过多）| 一个层级中有几十个标签全部平铺，没有任何分组，标签列表冗长——此时应将同类标签归入共同的父标签 | | 问题表现（层级冗余）| 一个层级中只有一个标签，中间层没有其他并列项，也不带来额外的过滤价值——此时应合并或移除中间层 | | 判断方法 | 每个层级都问：「这一层的意义是什么？未来可能会有哪些概念与它并列？」答不上来的层级不应存在；同级标签较多时，考虑是否有可以归类的共同上级 | | 处理建议 | 层级错位 → 修正父子关系；同级过多 → 找出共同属性，建立父标签做归类；层级冗余 → 合并或移除中间层 |

**3. 标签颗粒度失衡**

| | 说明 | |---|---| | 正常状态 | 每个标签关联的文件数量适中，能有效过滤（既不过宽也不过细） | | 问题表现（过细）| 某标签只关联 1-2 篇文件，且这些文件已被更合适的父标签覆盖——此标签是冗余的 | | 问题表现（过粗）| 某标签关联了大量文件，点开后几乎等于「全部笔记」，检索时没有过滤价值 | | 处理建议 | 过细 → 合并到父标签或相近标签；过粗 → 拆分子标签，引导用户使用更精确的分类 |

**4. 命名风格不一致**

| | 说明 | |---|---| | 正常状态 | 同一层级的标签命名风格统一（词性、语言、大小写一致） | | 问题表现 | 同级标签中部分用名词、部分用动词；中英文混用；全角半角符号混用；英文大小写不统一 | | 处理建议 | 以用户现有的多数标签风格为基准统一；命名风格本身没有对错，统一即可 |

**5. 笔记覆盖不均衡**

| | 说明 | |---|---| | 正常状态 | 大多数笔记有标签，标签体系能覆盖用户的主要内容类型 | | 问题表现 | 大量笔记没有任何标签，或某一类内容（如近期新增笔记）系统性地缺少标签 | | 处理建议 | 为无标签笔记补充标签；缺口过大