Files

T

玉澜andCursor b6851e641e fix(skill): back up skill dirs before removal and satisfy coverage gate

Address the two P1 review findings and the coverage-gate CI failures:
- Every install/upgrade path that removes a skill dir (opposite-mode
  leftovers, stale dingtalk-* / dws-shared, and same-name refreshes) now
  moves the directory to ~/.dws/skill-backups/<stamp>/ first across
  install.sh, install-skills.sh, install.ps1, install.js, `dws skill
  setup`, and `dws upgrade`. A backup failure preserves the original
  directory and never removes it.
- Remove --yes from every copyable `dws skill setup` example and document
  what the command may remove; add regression tests that declining the
  confirmation performs no removal and that the confirmation previews
  every directory slated for backup+removal.
- Rename the skill-mode tests to the TestCrossPlatformCoverage* prefix so
  the platform coverage gate selects them, and add edge tests for the
  backup/prune/cleanup fallback branches, restoring changed-code coverage
  to 100%.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-10 20:23:35 +08:00

8.3 KiB

Raw Blame History

Skill multi 迁移：技术方案（as-implemented）与 Roadmap

本文是 multi 迁移的当前事实源：第一部分记录已落地实现（代码级锚点，均可跳转验证），第二部分是带实时状态的 roadmap。原始方案 skill-multi-migration-plan.md 的若干"待做"描述已被后续决策取代（见决策记录 D1/D5）；分发机制调研结论见 skill-distribution-mechanism.md。代码快照：feat/skill-mode-migration @ 402429ac + 工作区 upgrade-force-multi 调整（2026-08-05）。

状态速览

项	内容
当前阶段	阶段 1 / 1.5 ✅（安装/升级默认 multi 已落地）；阶段 2 运行时切换产品线 ❌ CANCELLED（2026-08-05 owner 决策）
硬 deadline	2026-08-30：安装/升级默认 multi（✅）+ upgrade 有 multi 包时一次性刷成 multi（不做磁盘粘性）+ mono 仅安装时 opt-in；mono 物理下线仍可在独立 retirement 版本推进，但不再依赖 `dws skill mode` / 备份回滚产品
已完成	五面默认 multi、`dws skill setup` 默认 multi、互斥清理对称、文案翻转；upgrade 有 `multi/` 时一律刷新 multi（存量 mono 一次性迁移）
下一步	beta/L1 版本门控与观察（靠 issue/回访，无 `x-dws-skill-mode` 埋点）；可选 agent-home 清单门禁；内容 C 线并行
终态	mono 仅安装时 opt-in；日常 upgrade（含 multi 的包）刷 multi；mono 物理删除仍可在 dedicated retirement 版本收尾（非用户切换命令）

简化设计（2026-08-05 起生效）

安装时一次决定：默认 multi；DWS_SKILL_MODE=mono / --mode mono / 安装器 TTY 选 mono 为唯一 opt-in。
装完无运行时切换产品：不做 dws skill mode set/rollback，不做备份式安装 / state.json 记账产品面。
升级不做粘性：release zip 含 multi/ 时一律刷新 multi（清 dws/、刷产品 skill + 缓存）；仅 legacy 无 multi 树的包回退 mono 路径。存量 mono 在日常 upgrade 上一次性迁到 multi。
mono 下线：安装侧仍可 opt-in；upgrade 已承担「有 multi 包即迁走」；物理删 mono 树可另议 retirement。
可观测：x-dws-skill-mode 请求头已按 owner 决策移除；灰度靠 issue + 回访。

第一部分：技术方案（as-implemented）

1. 升级：包驱动 multi 刷新（`dws upgrade`）

核心语义：升级不做磁盘粘性；产物有 multi/ 时一次性刷成 multi。无需 state.json，也无运行时切换命令。

LocateSkillsRoot 优先返回 zip 内 multi/（internal/upgrade/paths.go）。
UpgradeSkillLocations：包内有 multi 技能树 → 始终 upgradeMultiSkillLocations （平铺 dingtalk-* + dingtalk-shared，删 mono 残留 dws/，清过期 multi skill，刷 ~/.dws/skills/multi）；无 multi 树的 legacy 包才走 mono 刷新。删除前先把目录移入 ~/.dws/skill-backups/，备份失败则保留原目录并上报。
这是 upgrade 上的一次性迁移，不是 dws skill mode 产品。

测试：internal/upgrade/paths_multi_test.go（含 TestCrossPlatformCoverageUpgradeSkillLocationsMonoDiskMigratesToMulti）+ internal/app/upgrade_skill_multi_e2e_test.go。

2. 安装默认 multi（四个脚本面）

四个脚本安装面默认值全部为 multi，DWS_SKILL_MODE=mono 为统一 opt-in，互斥清理双向对称。详见阶段 1 落地说明（scripts/install.sh / install.ps1 / build/npm/install.js / scripts/install-skills.sh）。

3. `dws skill setup` 默认 multi

非交互未指定 --mode 时默认 multi。
交互选项 multi 在前（默认）、mono 标 legacy。
仍可用 dws skill setup --mode mono 重装到 mono（这是安装入口，不是 lifecycle 切换产品；无备份/state/rollback 命令）。

4. 文案翻转

README.md / README_zh.md：multi 默认、mono legacy。
skills/multi/dingtalk-skill/SKILL.md：去掉 EXPERIMENTAL。

5. 已验证

go test ./internal/upgrade ./internal/app ./test/scripts（阶段 1 基线）+ upgrade-force-multi 单测 / fake-HOME E2E。
脚本面契约测试暴露 DWS_SKILL_MODE 与 mono/multi 选项。

6. 决策记录

D1 升级不依赖 state.json（仍成立）。不读状态文件；布局由包内容驱动。
D2 无服务端灰度。L1 beta 轨 + issue/回访；L2 rollout.json 已砍； kill switch = beta 撤回 / 重装 --mode mono（无 skill mode 命令）。
D3 生态分发通道已否决（npx skills add 等）。见 skill-distribution-mechanism.md。
D4 互斥前缀约定。dingtalk-* / dws-shared 属 DWS 产品 skill。
D5 无运行时模式切换（2026-08-05）。取消阶段 2 的备份式安装、 state.json、dws skill mode（status/set/rollback）、x-dws-skill-mode 请求头。Mode 只在安装时决定。
D6 升级不做粘性（2026-08-05）。有 multi 包时 upgrade 一次性刷成 multi （含存量 mono）；legacy 无 multi 树才回退 mono 路径。

第二部分：Roadmap

✅ 阶段 1 / 1.5（已完成，2026-08-05）

安装/升级默认 multi、五面互斥清理、文案翻转、1.5 review 修复与实机 9/9。 HEAD：402429ac。

❌ 阶段 2（原切换/状态/备份产品线）— CANCELLED（2026-08-05）

原任务	状态	说明
备份式安装（`~/.dws/skills/backup/...`）	❌ CANCELLED	不做运行时切换，无需备份回滚产品
`~/.dws/skills/state.json`	❌ CANCELLED	无切换产品；upgrade 按包刷 multi，不需要状态文件
`dws skill mode` status/set/rollback/--dry-run	❌ CANCELLED	无运行时切换 UX
`x-dws-skill-mode` 请求头	❌ CANCELLED	owner 决策移除；观测改 issue/回访
agent home 清单门禁	⬜ 可选	与切换产品无关，仍可作工程质量项
`upgrade --dry-run` multi 文案	⬜ 可选	可随 force-multi 语义轻量对齐

重构后的 8/30 目标

底线：新装默认 multi；含 multi/ 的 release 上 dws upgrade 一次性刷成 multi（含存量 mono）；仅需保持 mono 的用户用安装入口 opt-in 后勿升级到含 multi 的包，或 retirement 前用 setup 重装；mono 物理删除可另议。

建议关键路径（简化）

阶段1默认multi ✅ → upgrade force-multi ✅ → beta/L1（可选）→ 观察(issue/回访)
→ stable 默认已是 multi → 可选 mono retirement（删 mono 树 / 安装入口报错）

mono retirement（原阶段 4，重框）

不再提供 dws skill mode rollback 作为用户出口。
日常 upgrade 已在有 multi 包时迁走存量 mono；retirement 版本可进一步移除 install/setup 的 mono 分支与 zip 内 mono 树。
下线判据改为：issue/回访无系统性 multi P1、mono opt-in 可接受、政策门不再依赖 skills/mono/SKILL.md。（原请求头占比判据作废。）

悟空线下线的影响（2026-08-05）

悟空 bundled-skill 分发线已下线：mono 下线无仓外节奏闸门；skills/multi/ 为唯一 multi 事实源。设计资产留档 skill-wukong-comparison.md。

明确不做

❌ 运行时模式切换（dws skill mode set/rollback）。
❌ state.json / 备份式安装产品面（随 D5 取消）。
❌ x-dws-skill-mode 请求头。
❌ 服务端远程配置 / L2 rollout.json。
❌ 运行时「模式切换」产品（含 sticky 伪切换）；upgrade 有 multi 时刷 multi 是包驱动的一次性迁移，不是 switch UX。
不动 dws-skills.zip 双树布局（仍可含 mono 副本供安装 opt-in）；不动市场 skill（dws skill install）。

风险表

风险	现状	缓解
半装无备份	安装/清理仍 `RemoveAll`	接受为非切换产品下的已知限制；重装可收敛
mono/multi 漂移	无 state；upgrade 有 multi 即刷 multi	升级后收敛为 multi；安装互斥清理
用户想换模式	无 switch 命令	文档引导：`dws skill setup --mode <mono\|multi>` 重装
8/30 滑期	切换产品线已砍，关键路径缩短	聚焦 force-multi upgrade + 默认 multi 稳定

8.3 KiB Raw Blame History Unescape Escape