玉澜andCursor
b6851e641e
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>
155 lines
8.3 KiB
Markdown
155 lines
8.3 KiB
Markdown
# Skill multi 迁移：技术方案（as-implemented）与 Roadmap
|
||
|
||
> 本文是 multi 迁移的当前事实源：第一部分记录**已落地实现**（代码级锚点，
|
||
> 均可跳转验证），第二部分是带实时状态的 roadmap。
|
||
> 原始方案 [skill-multi-migration-plan.md](skill-multi-migration-plan.md) 的
|
||
> 若干"待做"描述已被后续决策取代（见决策记录 D1/D5）；分发机制调研结论见
|
||
> [skill-distribution-mechanism.md](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 起生效）
|
||
|
||
1. **安装时一次决定**：默认 multi；`DWS_SKILL_MODE=mono` / `--mode mono` / 安装器 TTY 选 mono 为唯一 opt-in。
|
||
2. **装完无运行时切换产品**：不做 `dws skill mode set/rollback`，不做备份式安装 / `state.json` 记账产品面。
|
||
3. **升级不做粘性**：release zip 含 `multi/` 时 **一律** 刷新 multi（清 `dws/`、刷产品 skill + 缓存）；仅 legacy 无 multi 树的包回退 mono 路径。存量 mono 在日常 upgrade 上一次性迁到 multi。
|
||
4. **mono 下线**：安装侧仍可 opt-in；upgrade 已承担「有 multi 包即迁走」；物理删 mono 树可另议 retirement。
|
||
5. **可观测**：`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](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 物理删除可另议。
|
||
|
||
### 建议关键路径（简化）
|
||
|
||
```text
|
||
阶段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](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 稳定 |
|