技能全生命周期管家

0. 一句话定位

本技能是「技能从生到发」的全链路管家：收集创建/更新意图 → 落地技能文件 → 打包过滤二进制 → 桌面产 ZIP → 归档索引登记（默认乐享知识库《7.workbuddy.skill》，用户特别说明时 WPS 云文档《7.workbuddy.skill》）→ 问题清单持续累积。替代旧版「技能归档发布助手」，覆盖发版全部动作，大幅减少每发一版的手工步骤。

> 归档后端选择（v1.0.3 起，硬执行）
> - 默认后端 = 乐享知识库（lexiang 连接器，已连接）。除非用户明确说"归档到 WPS 云文档 / 用 WPS 归档"，否则一律走乐享分支（第 5.5B 节）。
> - 用户特别说明时，按用户意图执行对应分支（说 WPS 则走第 5.5A 节，说乐享或什么都不说则走第 5.5B 节）。
> - 命名规范、四区结构、版本号、问题清单机制两套后端完全一致，仅落地位置与工具链不同。
> - 乐享写入前先 whoami() 确认连接与产品版本（v2 继续；v1/v1v2 按 lexiang 连接器提示处理）；遇 401 立即停止重试并引导用户在连接器管理续期。
> - WPS 云文档分支为兼容保留（逐步弃用），仅当用户特别要求时使用。

1. 触发机制（100% 命中，硬执行）

用户出现以下任一词/意，必须直接调用本技能，不得另判或漏判：
- 「归档技能」「归档」「归档skill」「归档一下」
- 「更新技能」「改技能」「迭代技能」「给某技能加功能/删功能」
- 「新建技能」「创建一个技能」「做个技能」
- 「发布技能」「上传技能到 SkillHub」「发一版」

命中即全流程执行；若用户仅问「这个技能能做什么」类咨询，读 SKILL.md 回答即可，不触发归档动作。

2. 两类核心动作

2.1 创建新技能

• 意图来源：① 从用户对话中提取意图；② 从其他文字源（文档、截图 OCR 文本、网页等）获取信息。
• 落地：按 WorkBuddy 技能结构建目录（SKILL.md + scripts/ + references/ 等），SKILL.md frontmatter 含 name（hyphen-case）、display、description、version（初版固定 1.0.0）、author、license、platforms、agent_created: true。
• 通用化铁律：新用户视角，主语「助手」、对象「应用本技能的用户」，不出现个人昵称/个人本机路径等专属信息。

2.2 更新已有技能

• 含义：对既有技能调整、增删功能、修 bug、补资料。
• 落地：读取目标技能目录，按意图改 SKILL.md 与附属文件；版本号按第 4 节自增。
• 用户已修改内容默认保留、不回退不改写（除非用户明确要求）。

3. 内置命名规范（权威，来源《7.workbuddy.skill/0.命名规范.md》）

> 所有文件夹/文件命名以此为准，不必再问位置。
> 根：WPS 云文档 / 1.四项基本原则 / 2.学习和美食 / 7.workbuddy.skill（folder 4D8WvsdCurMhE8A2H3zErxH8BcdYyYTzB，drive 165846236）。

3.1 三层目录结构

7.workbuddy.skill/
├─ 0.命名规范.md                      ← 规范本身（本技能内置副本）
├─ 技能台账.xlsx / 技能规划总表.xlsx   ← 固定名台账，不动
├─ <序号>.<技能名>（状态）/            ← 【顶层】序号.技能名（状态），本层不带版本号
│  └─ <序号>.【<技能名>】【vX.Y.Z】【上传日期YYYY年M月D日】/   ← 【版本】每次新建一个
│     ├─ 1.技能ZIP/
│     ├─ 2.变更说明/
│     ├─ 3.其他资料/
│     └─ 4.文章（空）/               ← 专指腾讯社区发布文章；无则标（空）

> 上述结构在乐享知识库与 WPS 云文档两套《7.workbuddy.skill》中完全一致。默认落地乐享（space 名 7.workbuddy.skill）；用户特别说明时落 WPS 云文档（folder 4D8WvsdCurMhE8A2H3zErxH8BcdYyYTzB，drive 165846236）。

3.2 命名格式（权威）

• 顶层技能文件夹：序号.技能名（状态）。序号从 1 递增不跳号；状态括号可省略（未完成时不写）；本层不带版本号，保持原样。
• 版本子文件夹：序号.【技能名称】【vX.Y.Z】【上传日期YYYY年M月D日】。
• 序号：每个技能内独立从 1 开始，每次发新版本 +1。
• 技能名称：以该技能 SKILL.md 的 name 字段为准，全文统一。
• vX.Y.Z：真实版本号。
• 上传日期：YYYY年M月D日。
• 示例：10.【记忆同步助手】【v2.0.2】【上传日期2026年8月22日】
• 版本内四分类子文件夹（固定 4 个带序号）：1.技能ZIP / 2.变更说明 / 3.其他资料 / 4.文章。
• 1.技能ZIP：放技能 ZIP 包（桌面打包好直接上传；若 SKILL.md 与 ZIP 同在，以后只传 ZIP，已有 SKILL.md 不删）。
• 2.变更说明：放变更说明。优先用 mcp__kdocs__create_file_with_content 直接写 otl（UTF-8 明文 content，文件名 技能名称-变更说明-vX.Y.Z.otl），不走 base64 内联上传（长字符串易在会话内联传输中损坏）；无变更说明则标「（空）」。
• 3.其他资料：放除 1/2/4 之外的全部资料——说明文档、技术文档、速查表、规范原文、脚本、SKILL.md、特殊用途 zip 等。无则标「（空）」。
• 4.文章：专指发布在腾讯社区/微信公众号/CSDN 等的文章本地存档。不是每次都有，没有则标「（空）」；补了内容去掉「（空）」。
• 空子文件夹必须带「（空）」后缀（如 4.文章（空）），一旦补入内容立即去掉。同级其他文件夹同理。例外：1.技能ZIP 因预建占位用途（待用户手动上传桌面 ZIP）豁免「（空）」标注——按总纲规则它本就是预留空文件夹，名字不带（空）。
• 编号与顺序固定：技能ZIP=1、变更说明=2、其他资料=3、文章=4。文章恒为最后一位。

3.3 文件命名

3.4 操作约定

• 全量覆盖：7.workbuddy.skill 下所有文件/文件夹均按本规范统一。
• 不删除原则：kdocs 无删除能力；整理只做「改名 + 建子文件夹 + 移文件」。
• ZIP 优先：新归档默认只上传 ZIP；已有 SKILL.md 保留不删。
• 腾讯社区文章联动：发文时本地那份直接按「文章」子文件夹 + 技能名称vX.Y.Z-文章.md 命名归档。
• 云端文件夹归属（双后端，v1.0.3 起）：
• 乐享（默认）：space 名 7.workbuddy.skill，真实 space_id / root_entry_id 用 space_describe_space 实时取得，不写死；若 space 不存在提示用户先建好该知识库；若已有同名顶层 folder 则直接放置在同名 folder 中（用 entry_list_children 实时核验）。
• WPS 云文档（仅用户特别要求时）：folder 4D8WvsdCurMhE8A2H3zErxH8BcdYyYTzB，drive 165846236；若用户云文档内没有该文件夹则自行创建；若用户指定其他文件夹则按用户意图执行。
• 用户指定其他空间/文件夹时按用户意图执行；已有同名顶层 folder 直接复用，不重名新建。

3.5 技能更名与编号衔接（v1.0.2 补强，2026-08-23）

• 顶层更名：技能更名后，原顶层 序号.旧技能名 应直接 rename 为 序号.新技能名，序号沿用不重起。例如 10.技能归档发布助手 → 10.技能全生命周期管家，序号 10 不变。
• 版本子目录更名（关键）：技能更名后，已存在的旧版本子目录保留旧名不动（如 1.【技能归档发布助手】【v1.0.1】... 保留为历史快照），从当前最新版本起的子目录用新名（如 2.【技能全生命周期管家】【v1.0.2】...）。版本子目录序号沿用递增、不重起——本次更名后下一个版本子目录是 2、再下一个是 3，绝不因更名跳回 1。
• 避免历史快照改名：旧版本子目录保留旧名是刻意为之，便于一眼看出「这条技能历史上叫什么、什么时间点改名」。如确需统一改名，需用户明确指示，避免擅自破坏历史快照。
• 示例：本次 10.技能归档发布助手（含 1.【技能归档发布助手】【v1.0.1】...）→ rename 顶层为 10.技能全生命周期管家，新增 2.【技能全生命周期管家】【v1.0.2】...；旧子目录序号 1 + 旧名保留。

3.6 空文件夹标记硬规则（v1.0.2 补强，2026-08-23）

• 四区所有空文件夹一律加「（空）」后缀，无差别处理——1.技能ZIP 非空（必有 ZIP）不加；2.变更说明 非空（必有 otl）不加；3.其他资料 空时为 3.其他资料（空）；4.文章 空时为 4.文章（空）。
• 典型 bug 复盘：v1.0.2 首次建四区时只给 4.文章 拼了「（空）」、3.其他资料 漏拼，导致两个空文件夹口径不一。已修复：rename 3.其他资料 → 3.其他资料（空）。规则写入本节防再犯。
• 自动检查：建四区后必须 list_files 回读核对每个空文件夹名都带「（空）」后缀，缺则立即 rename，不放过发前。

4. 版本号自增规则（0.01 步长，十进制进位）

• 初版 1.0.0；每更新一次 +0.01（1.0.0 → 1.0.1 → 1.0.2 …）。
• 末位逢 9 进位：1.0.9 更新后为 1.1.0，1.9.9 → 2.0.0，其余同理。
• 版本号与 SkillHub 表单《x.y.z》一致自增，保留真实版本历史。

5. 标准流程（六步）

5.1 意图收集与确认

• 创建：从对话或文字源提炼技能用途、触发词、必备能力；确认 name/display/初版版本。
• 更新：定位既有技能目录，确认要增删改的内容与版本号。

5.2 落地技能文件

• 创建：建 SKILL.md + 必要 scripts/、references/，写 frontmatter 与正文。
• 更新：改既有文件，保留用户已改内容。

5.3 打包（本地 Python zipfile）

• 用 scripts/archive_zip.py <技能目录> <版本号> 打包，必须 Python zipfile（规避 PowerShell Compress-Archive 清零文件属性）。
• 输出默认：桌面/<技能名>v<版本号>归档.zip。
• 脚本自动过滤二进制图片（.png/.jpg/.jpeg/.gif/.ico/.svg）与 .zip 产物、.git/__pycache__ 缓存；包体解压后 ≤10MB（SkillHub 限制），超限给警告。

5.4 桌面落盘

• ZIP 直接放桌面，用户自行去 https://skillhub.cn/dashboard 上传（助手无法代为登录）。

5.5 归档索引（按后端分支，默认乐享）

> 执行第 5.5 节前先确定后端：用户说"归档到 WPS 云文档 / 用 WPS 归档"→ 走 5.5A；否则（说乐享或什么都不说）→ 走 5.5B。命名规范、四区结构两套一致。

5.5A WPS 云文档分支（仅用户特别要求时，逐步弃用）

• 目标：WPS 云文档《7.workbuddy.skill》（folder 4D8WvsdCurMhE8A2H3zErxH8BcdYyYTzB，drive 165846236）。
  1. 顶层：若无则自建；按 序号.技能名（状态） 建/复用顶层文件夹（同名直接放入，用 mcp__kdocs__search_files 实时取真 id）。
  2. 版本子文件夹：序号.【技能名称】【vX.Y.Z】【上传日期YYYY年M月D日】。
  3. 四区：1.技能ZIP（放桌面 ZIP，直接上传）/ 2.变更说明（用 mcp__kdocs__create_file_with_content 写 otl，UTF-8 明文，不走 base64）/ 3.其他资料/4.文章（无则标「（空）」）。
  4. 空文件夹一律加「（空）」后缀；有内容即去掉。1.技能ZIP 因预建占位用途豁免（不标空）。
• 写前用 mcp__kdocs__search_files 实时取真 file_id / folder_id，绝不把父 folder id 当 file id。

5.5B 乐享知识库分支（默认）

• 目标：乐享知识库《7.workbuddy.skill》space（space_id 用 space_describe_space 实时取；root_entry_id 作为顶层父节点）。
  1. 定位根：space_describe_space 取 root_entry_id；若需找已有顶层 folder，用 entry_list_children（parent 为 root_entry_id）或 search_kb_search（keyword=7.workbuddy.skill）核验真实 entry_id，不写死 id。
  2. 顶层 folder：若无对应顶层 folder 则 entry_create_entry（entry_type=folder，parent_id=root_entry_id，name=序号.技能名（状态））；同名直接复用。
  3. 版本子 folder：entry_create_entry（folder，parent_id=顶层 folder entry_id，name=序号.【技能名称】【vX.Y.Z】【上传日期YYYY年M月D日】）。
  4. 四区：
  • 1.技能ZIP（folder）：用 files 三步上传桌面打好的 ZIP —— file_apply_upload（parent_entry_id=该 folder entry_id，name=ZIP 名，size=字节数，mime_type=application/zip，upload_type=PRE_SIGNED_URL）→ curl PUT 上传 → file_commit_upload。
  • 2.变更说明（folder 或文档）：变更说明 md 用 entry_import_content（content_type=markdown，space_id + parent_id=该 folder entry_id）导入为文档；空则建 folder 标「（空）」。
  • 3.其他资料（folder）：其余资料文档同样 entry_import_content 导入；空则标「（空）」。
  • 4.文章（folder）：腾讯社区等文章 md 导入归档；无则建 folder 标 4.文章（空）。
    5. 空文件夹一律加「（空）」后缀；有内容即去掉。1.技能ZIP 因预建占位用途豁免（不标空）。

• 乐享写入前先 whoami() 确认连接；遇 401 立即停止重试引导用户续期。

• 两分支共用「恢复 1.技能ZIP 分区强制创建并上传 ZIP」规定（撤销旧版「不再单列 1.技能ZIP 分区」）。

5.6 问题清单更新与备份同步

• 先读《7.workbuddy.skill》根下「问题清单」条目（不存在则建）；将本次遇到的问题、日期、后续成功解决方案追加记录。
• 乐享分支（默认）：用 entry_describe_ai_parse_content 取正文；新建/追加用 entry_import_content / entry_import_content_to_entry（mode=append）。
• WPS 分支（仅用户特别要求时）：用 mcp__kdocs__read_file_content 取正文；新建用 mcp__kdocs__create_file_with_content，追加用 otl.insert_content。
• 若本次改了云《工作习惯总纲》或《7.workbuddy.skill》索引，按记忆同步助手规则刷备份。

6. 问题清单机制（每次调用先读）

• 位置：归档后端《7.workbuddy.skill》根下「问题清单」条目（乐享分支默认用 entry 文档；WPS 分支用 问题清单.md）。
• 内容格式（追加式）：
  ```
  ## [日期] 问题简述
• 现象：……
• 根因：……
• 解决方案：……（成功解决后补）
  ```
• 每次本技能被调用，第一步先读该清单，避免重复踩坑；新问题解决后回写方案。

7. 命名与禁忌

• 技能 ZIP 命名：技能名vX.Y.Z归档.zip（书名号仅用于版本号标注，文件名用普通字符规避服务端拒收）。
• 云子文件夹序号从 1 递增不跳号；状态括号（已上传/已完成/进行中）。
• 不建「修改版/旧」副本；公司专属资料不嵌入技能（只放通用规范方法）。
• SkillHub name 必须 hyphen-case，目录名/description 可中文。

8. 铁律（v1.0.2 修订）

• 桌面 ZIP 是默认产出，不可省。
• 恢复 1.技能ZIP 分区：版本子目录下必须建 1.技能ZIP 并放入打包好的 ZIP（撤销旧版「不再单列 1.技能ZIP 分区、不再写技能ZIP说明 otl」规定）。
• 空文件夹标「（空）」：3.其他资料 与 4.文章 两种空场景统一加「（空）」后缀（3.其他资料（空）/4.文章（空））；1.技能ZIP/2.变更说明 必有内容不标空。详见 3.6 节。
• 版本号按第 4 节 0.01 自增、十进制进位。
• 触发词 100% 命中（见第 1 节）。
• 失败必须显式告知（结果导向，硬执行）：本技能任一步未成功执行（创建技能失败、打包失败、桌面落盘失败、云端建文件夹失败、写变更说明失败、上传/放回 ZIP 失败、问题清单读取/写入失败等），必须直接用大白话告诉用户"结果没成"，并给出可手动补救的具体路径建议，过程原因只一句话带过（如"因为没能成功调用 XXX 工具 / 因为云文档写入返回 400100"）。严禁只写一堆过程、把失败藏起来或谎称成功。统一套用下方「失败告知模板」。

8.1 通用失败告知模板（本技能内任意环节失败均可调用）

⚠️ 这一步没成：<用大白话说结果，比如"我没能把技能 ZIP 传到<后端名>《7.workbuddy.skill》的 1.技能ZIP 文件夹">
建议你可以手动这样补：
  把桌面 <技能名>v<版本号>归档.zip
  上传到 <后端名> 《7.workbuddy.skill》→ <序号>.<技能名>（状态） → <序号>.【<技能名>】【vX.Y.Z】【上传日期】 → 1.技能ZIP 文件夹下，方便归档。
（路径里的 <序号>/<版本子目录> 用实时 search 取到的真 id 动态拼接，不写死）
原因一句话：因为 <没能成功调用 XXX 工具 / <后端名>写入返回 XXX 错误码 / 其他>，已记录进问题清单。

> <后端名> 占位：默认乐享分支填"乐享知识库"；用户特别要求走 WPS 时填"WPS 云文档"。

• 模板适用所有环节，只替换「没成的那步」与「对应的补救动作」：
• 没传 ZIP → 建议手动传桌面 ZIP 到 1.技能ZIP；
• 没建顶层/版本子目录 → 建议手动在《7.workbuddy.skill》建 序号.技能名（状态） / 序号.【技能名】【vX.Y.Z】【上传日期】；
• 没写变更说明 → 建议手动在 2.变更说明 建 变更说明.md；
• 没读/写问题清单 → 建议手动在《7.workbuddy.skill》根下建/补「问题清单」；
• 其余同理。
• 过程原因严禁展开成排查长文，一句话即可。
• 跨技能复用口径（做法A，零维护）：其他涉及云文档写操作的技能（如记忆同步助手、标准归档合规管家等）失败时，直接引用本模板——在其 SKILL.md 写明「失败反馈口径见《技能全生命周期管家》SKILL.md 8.1 节，本技能任一步未成时按同模板大白话告知用户 + 给手动补救路径 + 原因一句话」，不必各抄一份，避免日后两处漂移。若需离线不依赖管家，可整段复制为本地片段（做法B），但改模板时要同步多处。

8.2 云文档增删改查稳定性记录（目标：提高云文档读写稳定性）

• 本技能涉及的所有云文档操作（读总纲、读复盘库、建/改《7.workbuddy.skill》索引、写问题清单等），稳定可用的方法要记录，错误的方法也要记录，便于避坑。
• 已验证稳定方法（记正）：
• 读云文档正文用 MCP 文档工具 mcp__kdocs__read_file_content（file_id + format=markdown；otl 首选）；read_file 对 .memory 类型不支持，勿用。
• 写 otl 局部内容用 mcp__kdocs__otl.insert_content（mode=append 追加 / prepend 头插 / replace 整文替换），小修走 append 避免整文覆盖触发 400100。
• 写说明类小文档（如变更说明 otl）：用 mcp__kdocs__create_file_with_content（content=UTF-8 明文，非 base64），明文不受长字符串内联损坏；ZIP 等二进制大文件仍走本地桌面产出 + 用户手动上传。
• 写前用 mcp__kdocs__search_files 实时取真 file_id / folder_id，绝不把总纲里记的 id 当常量直接套（那是父目录 id，非文件 id）。
• 已验证错误方法（记反，避坑）：
• 误用 Skill 工具当"读云文档"手段——它只返回技能使用说明，不是文档内容，会导致数轮谎称"已读"却未拿到正文（详见云《犯错复盘库》第 19 条）。
• 把父文件夹 folder id 当文件 file id 去 read/write，返回 400100/400001。
• 对大 otl 整文 otl.replace 覆盖，易触发服务端写锁/限流 400100。
• 用 upload_file 的 content_base64 内联上传长文档（如数 KB 的变更说明 md、或 28KB 级 ZIP 的 base64）：长字符串在本会话上下文内联易损坏，服务端报 base64 解码失败，且大 base64 完全无法承载——说明类文档改用 create_file_with_content 明文写入，ZIP 走桌面产出 + 用户手动传。
• 上述正反方法同步沉淀进云《犯错复盘库.otl》与本地 kdocs_drafts/ 双写草稿，目标只有一个：提高云文档增删改查稳定性。

9. 版本变更记录

• v1.0.3（2026-08-23）：① 合并乐享版思路，默认归档后端 = 乐享知识库（lexiang），用户特别说明"归档到 WPS 云文档"时按意图走 WPS 分支，否则默认乐享（逐步弃用 WPS 云文档）；② 第 0 节新增「归档后端选择」硬执行声明；③ 第 3 节根位置说明扩展为双后端一致结构；④ 第 5.5 节拆为 5.5A（WPS 云文档分支，仅特别要求时）/ 5.5B（乐享知识库分支，默认），共用命名规范与四区；⑤ 第 5.6、第 6 节问题清单位置按后端分支取工具（乐享 entry_import_content / WPS create_file_with_content）；⑥ 第 8.1 失败模板 <后端名> 占位按分支动态替换（乐享/ WPS 云文档）；⑦ 乐享写入前 whoami 探连接、遇 401 即停。以 WPS 版 v1.0.2 为写作模板（保留 3.5/3.6 等补强），落点改为默认乐享。
• v1.0.2（2026-08-23）：① 更名「技能归档发布助手」→「技能全生命周期管家」，定位升级为「意图收集→建/改→打包→云端四区登记→问题累积」全链路；② 内置《0.命名规范.md》为权威命名依据；③ 恢复 1.技能ZIP 分区并上传 ZIP（撤销 v1.0.1 铁律「不再单列 1.技能ZIP 分区」）；④ 明确空文件夹加「（空）」后缀；⑤ 新增问题清单机制（每次先读、累积问题与方案）；⑥ 写死触发词保证「归档技能/归档/归档skill」等 100% 命中；⑦ 版本号 0.01 自增、十进制进位固化。（同日补强）⑧ 新增「失败必须显式告知」铁律 + 通用失败告知模板（8.1），任一步未成须大白话讲结果 + 给手动补救路径 + 过程原因一句话；⑨ 新增「云文档增删改查稳定性记录」（8.2）：稳定方法（read_file_content / otl.insert_content append / search_files 实时取 id）与错误方法（误用 Skill 工具当读取、父 folder id 当 file id、大 otl 整文 replace）均记录避坑，目标提高云文档读写稳定性。（同日续补）⑩ 新增 3.5「技能更名与编号衔接」：顶层 rename 用真 id 序号沿用不重起；版本子目录已存在旧版本保留旧名作为历史快照，从当前最新版本起用新名，序号沿用递增（本次 v1.0.1 子目录保留旧名「技能归档发布助手」不动，v1.0.2 子目录用新名「技能全生命周期管家」+ 序号 2）。（同日续补 ⑪） 固化归档写入改进：① 2.变更说明 明确用 create_file_with_content 直接写 otl（UTF-8 明文，不走 base64 内联），从根规避长字符串内联损坏；② 8.2 稳定方法补 create_file_with_content、错误方法补 upload_file 的 base64 内联长文档损坏案例；③ 修复空文件夹漏标 bug：v1.0.2 首次建四区时只给 4.文章 拼「（空）」、3.其他资料 漏拼，用户截图指出后已 rename 修复（id pZeMjAMKQ9MsLXPQFm74rxiC1Sf5RRW5b → 3.其他资料（空））；新增 3.6「空文件夹标记硬规则」——四区所有空文件夹一律加「（空）」后缀无差别，1.技能ZIP/2.变更说明 必有内容不标空，建四区后必须 list_files 回读核对，缺则立即 rename。
• v1.0.1（2026-08-22）：打包脚本增加二进制图片过滤，解决 SkillHub 拒收 zip 内含 _icon.png 问题。
• v1.0.0（2026-08-22）：初版，固化四步归档流程。