# 100 · 实例内「我的技能」—— 并入「功能管理」的分组方案与实现

- 日期：2026-09-15
- 触发：用户「规划一个产品方案（界面布局美观 方便操作）然后实现这个功能」＝落地 `交接单/T01`（档案 16 阶段 3/4）
- 对象：`poc/business-plugins`（`@dsh-local/business-plugins`）client bundle 的「功能管理」section
- 状态：✅ **已实施并投放**（`business-plugins` **0.3.21**，两实例；方案见 §二，验收见 §8.2/§8.4）
  - ⚠️ 后续：该分区已改名「**能力管理**」并改为**页内 tab 分页**（档案 **101**）；本档案正文保留当时的形态描述（档案只增不改）

> **TL;DR**｜**结论**：在**既有「功能管理」section 内新增「我的技能」分组**（**不新开 section**），用户在同一页看完并管理「功能插件 + 我的技能」两类功能；技能行支持 上传 / 启用 / 停用 / 删除，平台共享技能显示为**锁定只读**。
> **关键**：入口层合并、**机制层分离**（技能 watch 即时生效 vs 插件需重启；API / 落盘各自独立）—— 依据见 `交接单/T01 §九`。
> **不做**：不改服务端（6 个 `/api/skills/mine*` 路由早已就绪，档案 41）；不新造包；不碰官方包。

---

## 一、目标与完成判定

**目标**：普通用户在实例内**自助管理个人技能**，且平台投放/用户自传两类"功能"在**同一页、同一套交互语汇**下呈现。

**完成判定（可被第三方复现）**：
1. guest 实例 → 设置 →「功能管理」页内出现「**我的技能**」分组，且与「功能插件」同页可见；
2. 上传一个合法 `.zip` 技能 → 行内新增且状态「已启用」；`$DSH_HOME/skills/<name>` 存在；
3. 停用 → 文件移到 `home/skills-library/<name>`；启用 → 回到 `skills/`；删除 → 两处均无；
4. 与共享技能同名上传 / 对锁定行操作 → 后端 409，界面以**行内错误**如实呈现；
5. 全程**无需重启实例**（技能是 watch 驱动）。

---

## 二、产品方案（界面布局）

### 2.1 页内结构（自上而下，同页滚动）

```
┌─ 功能管理 ───────────────────────────────────────────────────────┐
│                                                                  │
│  ▍功能插件                              ← 既有分组（不动）        │
│  ├─ 内存配额状态条（既有）                                        │
│  ├─ 工具行：搜索 / 全选 / 清空 / 已选 N 项（既有）                 │
│  └─ 插件卡片网格（既有，勾选式）                                   │
│                                                                  │
│  ─────────────── 1px 分隔线 ───────────────                       │
│                                                                  │
│  ▍我的技能   [3]            [+ 上传技能]   ← 新增分组（本单）       │
│  ├─ 说明行：上传 .zip 技能包；启用/停用**立即生效，无需重启**       │
│  ├─ 上传面板（默认收起，点「上传技能」展开 / 支持拖入）             │
│  └─ 技能行列表                                                    │
│      ┌──────────────────────────────────────────────────┐        │
│      │ 账号诊断        [共享]🔒只读   12 文件 · 136 KB     │        │
│      │ 我的图表工具     [我的]●已启用  8 文件 · 24 KB   [停用][删除]│
│      │ 旧版脚本         [我的]○已停用  5 文件 · 12 KB   [启用][删除]│
│      └──────────────────────────────────────────────────┘        │
└──────────────────────────────────────────────────────────────────┘
```

**为什么是这个结构**：用户在「功能管理」里的心智是"**我有哪些功能、开没开**"。两类功能放同一页、同一行卡片语汇，一次滚动看完；差异（要不要重启）由**行内事实文案**承担，而不是靠分成两页去解释。

### 2.2 分组头（`.bp-group-h`）

| 元素 | 规格 |
|---|---|
| 标题 | 15px / 600 / `T.text`，前缀 3px 竖条（`T.primary`，圆角 2px）—— 与「功能插件」分组头**同一形态** |
| 计数徽章 | 13px，`T.field` 底 + `T.sub` 字，`2px 8px` r10（规范 §4.6 `.badge` 量级） |
| 右侧主按钮 | 「+ 上传技能」，白底 + `T.border` 边 + `T.primary` 字（规范 §4.1 `.btn-view` 量级），点击展开/收起上传面板（`aria-expanded`） |
| 与上方分组的分隔 | `1px solid T.border` + `margin-top: 22px; padding-top: 18px`（规范 §2.4 间距序列） |

### 2.3 技能行（`.bp-skill-row`）—— 单行不换行

| 区 | 内容 | 规格 |
|---|---|---|
| 左 | **技能名**（`name`） | 14px / 500 / `nowrap` + ellipsis + `title`（规范 §5 长文本截断三件套）；`min-width:0` 允许收缩 |
| 中 | **来源徽章** | `共享` = `T.primary` 12% 底 + `T.primary` 字；`我的` = `T.field` 底 + `T.sub` 字。13px / r10 |
| 中 | **状态** | ● 点（6px 圆点）+ 文字：已启用 = `T.success`；已停用 = `T.dim`。13px |
| 中 | **事实**（右对齐） | `12 文件 · 136 KB`，13px + `font-variant-numeric: tabular-nums`（规范 §5「数值一律右对齐 + 等宽数字」） |
| 右 | **动作区** | `margin-left:auto` + `nowrap`；启用/停用 = 白底 border 按钮（`.btn-sm` 量级）；删除 = `T.danger` 文字按钮。**busy 时该行按钮统一 disabled + opacity .5** |
| 整行 | 容器 | `padding: 12px 14px`，`border: 1px solid T.border`，r12，白底（`--dsw-alias-bg-layer-1`），hover 变 `T.field` 底 |

**锁定行（`locked: true`，平台共享技能）**：来源徽章后追加 🔒 + 「只读」，**不渲染任何动作按钮**；`title` 说明「平台共享技能，全员只读，不可停用/删除/覆盖」。→ 与后端 `assertNotShared()` 的 409 双向一致（前端不给出会失败的按钮，后端仍然兜底）。

### 2.4 上传面板（`.bp-upload`）

| 元素 | 交互 |
|---|---|
| 虚线投放区 | `border: 1px dashed T.border`，r10，`padding: 18px`，居中；文案「把 .zip 拖到这里」+ 次行「技能包需含 `SKILL.md`（name / description）」 |
| 「选择文件」 | `input[type=file][accept=".zip"]` 隐藏 + `<label>` 触发（点击即开系统文件框）；`aria-label` 齐备 |
| 选中态 | 显示文件名 + 体积；主按钮「上传」+ 次按钮「取消」；**客户端先校**：后缀非 `.zip` → 行内报错；`> 150MB` → 行内报错（与门户一致） |
| 拖拽 | `onDragOver` 阻止默认 + 高亮边框；`onDrop` 取 `dataTransfer.files[0]`；**非文件拖入**静默忽略 |
| 上传中 | 区禁用 + 按钮文案「上传中…」；完成后 `load()` 重拉列表 |
| 错误 | **行内**（`.bp-upload-err`，`T.danger`，13px）显示后端返回的中文错误原文（如「「x」是平台共享技能…请改用其他技能名」），不弹窗 |

### 2.5 两个页内确认弹窗（沿用 v0.2.8/v0.3.15 的既有弹窗语汇）

| 弹窗 | 触发 | 内容 | 按钮 |
|---|---|---|---|
| **同名替换** | 上传返回 `conflict: true` | 标题「检测到同名技能「X」」；正文：⚠️**替换将删除旧技能的全部文件 —— 新包中已移除的文件也会一并删除，不可恢复**；事实行：`旧 12 文件 · 136 KB → 新 8 文件`（`tabular-nums`） | 取消（白底）/ **确认替换**（`T.danger` 实心） |
| **删除技能** | 行内「删除」 | 标题「删除技能「X」？」；正文：该技能将从你的实例移除，**不可恢复**（若是停用状态，库中的文件也一并删除） | 取消 / **删除**（`T.danger` 实心） |

两者均：遮罩 `rgba(0,0,0,.35)` + 面板 r12 + 标题行 ✕ + 点遮罩关闭 + `stopPropagation`（与既有 `__confirm` 同款，规范 §4.7 提到 `.modal-mask[hidden]` 的坑 → 这里用条件渲染，不存在该问题）。

### 2.6 文案（zh / en 双语，键前缀 `msk.`）

新增词典键全部落在客户端既有 `zh` / `en` 两个对象里，**同批加、键数一致**（由 `scripts/verify-models-dict.mjs` 全词典断言守住：键数一致 + 被引用必已声明）。

**措辞三原则**：
1. **如实说生效方式**：技能「启用 / 停用**立即生效，无需重启**」；插件侧文案仍保留「需重启」——两者并存，用户看得到区别。
2. **如实说后果**：替换/删除弹窗写明"不可恢复""旧文件一并删除"。
3. **不暴露内部标识**：只说"技能 / 技能包 / .zip"，不出现路径、`skills-library`、rank、"共享层"等内部词。

### 2.7 视觉同源（为什么"看起来是一家"）

复用 v0.3.14 起确立的**官方卡片行语汇**：`min-width:0` + `overflow/ellipsis/nowrap` 三件套、动作区 `margin-left:auto` + `nowrap`、颜色全走 `--dsw-*` token（跟随 dsh 主题，亮/暗自动适配）。**结构上不可能换行**，也就不会再犯 v0.3.14 那次"按钮被挤换行"的缺陷。

---

## 三、为什么是「分组」而不是「新 section」

见 `交接单/T01 §九`（本次追加）。一句话：用户口径「不要分开管理」+ 该 section 已由档案 60 命名为「**功能管理**」⇒ 另立「我的技能」等于在"功能"之外再造平行概念。

⛔ **仅入口层合并**：两条后端 API、两套落盘位置、两种生效方式**都不合并**（档案 16 §2.1 决策 2「技能与插件启用语义不同」）。

---

## 四、接口契约（后端**已就绪**，本单不改服务端）

`src/web/routes/skills.ts`（档案 11 v2 + 档案 41，均 `requireAuth`）：

| 方法 | 路径 | 请求 | 响应 |
|---|---|---|---|
| GET | `/api/skills/mine` | — | `{ skills: [{ dir,name,description,size,files,mtimeMs, source:'shared'\|'user', enabled, locked }] }`（**三类合并**：共享 → user 已启用 → user 已停用） |
| POST | `/api/skills/mine` | `{ file: base64, filename }` | 无同名 → `{ ok, skill }`；有同名 → `{ ok, conflict:true, stagedId, skill:{name,description,files}, existing:{name,size,files,mtimeMs} }`；错误 → 4xx `{ error }` |
| POST | `/api/skills/mine/apply` | `{ stagedId }` | `{ ok, skill }`（**全量替换**：旧目录整删，新包缺失的文件随之消失） |
| POST | `/api/skills/mine/:name/enable` | — | `{ ok, skill }`；404 `not_found`；409 `already_enabled` |
| POST | `/api/skills/mine/:name/disable` | — | `{ ok }`；404 `not_found` |
| DELETE | `/api/skills/mine/:name` | — | `{ ok }`；404 `not_found`；409（与共享技能同名） |

- 与共享技能同名 → 上传/启用/停用/删除**一律 409**，错误文案为中文原文（前端直接展示）。
- 跨子域调用：沿用 `fetch(portalHost() + …)` + `credentials: 'include'`（门户 CORS 白名单含 GET/POST/DELETE，与 `/api/plugins/mine` 同机制）。

---

## 五、实现落点

| 文件 | 改动 |
|---|---|
| `poc/business-plugins/lib/client.js` | ① zh/en 各加 `msk.*` 词条；② `BusinessPluginsSection` 内新增 `skills` 状态 + `loadSkills/upload/applyReplace/toggle/remove` 动作；③ 渲染「我的技能」分组（分组头 + 上传面板 + 技能行 + 空态）；④ 两个页内弹窗；⑤ 注入 CSS（`.bp-skill-row` 等） |
| `poc/business-plugins/package.json` | 版本 `0.3.20 → 0.3.21`；`description` 头部追加本轮条目 |
| `scripts/verify-my-skills.mjs` | 新增：**词典键 / 版式不换行 / 危险操作二次确认 / 锁定行无动作按钮** 的机械断言（防回退） |
| `package.json`（仓根） | `npm run verify` 串联新脚本 |

**明确不动**：服务端 `src/**`（无改动）· 官方包（R2）· 现有「功能插件」分组的行为与文案 · `web/**` 静态页。

---

## 六、验收

| # | 口径 | 命令 / 动作 | 期望 |
|---|---|---|---|
| A | 本地 | `npm run verify` | 退出码 0（build + 单测 + 全部 verify 脚本） |
| B | 磁盘（06 §7.3 ①） | 在实例 profile 的插件里 grep 新特征串 | ≥ 1 |
| C | 实例已加载（06 §7.3 ②） | 抓实例页 HTML，比 URL 里的 `rev` | **与改前不同** |
| D | 服务端返回（06 §7.3 ③） | 用 HTML 里**完整** bundle URL 请求 | 200 + 含新特征串 |
| E | 端到端（R4 模板：临时用户，用完即删） | 上传 → 停用 → 启用 → 删除 | 四步皆 200；列表状态随之变化 |
| F | 守卫 | 与共享技能同名上传；对锁定行调 enable/disable/delete | 全部 **409** |
| G | 界面 | 浏览器（`agent-browser`，唯一许可）打开 guest 实例「功能管理」 | 「我的技能」分组与「功能插件」同页；锁定行无可点动作 |

**生效链路提醒**（06 §7.1）：改 client bundle **必须**走 `npm pack` → 铺 profile → **重启实例** → 浏览器侧由 `rev` 自动更新（平台已加 `no-cache`）。

---

## 七、回滚

- **插件回退**：把 `/opt/dsh/artifacts/business-plugins-0.3.20.tgz` 放回并按 `ensure-biz-plugins.cjs --all --restart` 重铺（版本号不同即可，pnpm 不会命中缓存）。
- **服务端**：本单**零改动**，无需回滚。
- **残留检查**：实例 profile 的 `@dsh-local/business-plugins` 版本号回落到 0.3.20 即成功。

---

## 八、实现与验证记录

### 8.1 改动清单

| 文件 | 改动 |
|---|---|
| `poc/business-plugins/lib/client.js` | ① zh/en 各 +46 条 `msk.*` 词条；② `BusinessPluginsSection` 内新增「我的技能」状态机 + `loadSkills/submitUpload/applyReplace/toggleSkill/removeSkill` + 参数化弹窗 `skillDialog()`；③ 渲染分组（分组头 + 说明行 + 拖拽上传面板 + 行内结果 + 技能行列表）；④ 两个页内确认弹窗；⑤ 注入 `.bp-*` CSS（含 hover / 拖拽高亮 / `prefers-reduced-motion`） |
| `poc/business-plugins/package.json` | 版本 **0.3.20 → 0.3.21**；`description` 头部追加本轮条目 |
| `scripts/verify-my-skills.mjs` | **新增**：34 条机械断言（结构 / 危险操作 / 锁定行 / 版式不换行 / 措辞 / R3） |
| `package.json`（仓根） | `npm run verify` 串联新脚本（末位） |

**零服务端改动**（后端 6 路由早已就绪）；未动官方包（R2）；未动现有「功能插件」分组行为。

### 8.2 验收结果（全绿）

| # | 口径 | 结果 |
|---|---|---|
| A | 本地 `npm run verify`（build + 3 组单测 + 全部 verify 脚本） | ✅ **通过**；词典 zh/en 各 **366** 键、引用键 343 个全部已声明 |
| B | 磁盘（06 §7.3 ①） | ✅ 两实例 profile 均 **0.3.21**，`msk.group` 命中 3 / `bp-skillRow` 命中 4 |
| C | 实例已加载（06 §7.3 ②） | ✅ 壳页 combo 出现 `@dsh-local/business-plugins`；壳页 58,126 B → **58,724 B**；`rev=533537bbc02b` |
| D | 服务端返回（06 §7.3 ③） | ✅ bundle **HTTP 200**，**11,363,655 B**，含 `msk.group` / `msk.replaceWarn` / `bp-skillRow` / 「我的技能」 |
| E | 端到端（R4 一次性用户） | ✅ **19/19**：上传 → 列表 enabled → 同名 conflict+stagedId → apply 全量替换 → 停用（文件落 `skills-library` 且不在 `skills`）→ 启用（回到 `skills`）→ 删除（两处皆无、列表消失） |
| F | 守卫 | ✅ 对共享技能 `platform-capabilities` 的 disable / delete **均 409**；非 `.zip` **400**「仅支持 .zip 文件」 |
| G | 浏览器视觉 | 见 §8.4 |

### 8.3 部署记录

```
# 打包（先删 lib/*.bak；npm pack 前核断言锚点）
dsh-local-business-plugins-0.3.21.tgz  70,758 B  4 files  sha256 77429d2c…
# 投放
scp → /opt/dsh/artifacts/business-plugins-0.3.21.tgz   （哈希与本地一致）
ssh bt-server 'cd /opt/dshs && node scripts/ensure-biz-plugins.cjs --all --restart'
  admin: 版本落后（0.3.20 → 0.3.21），升级中… ✓ bundles=7（含 @dsh-local/business-plugins: true）
  guest: 版本落后（0.3.20 → 0.3.21），升级中… ✓ bundles=6（含 @dsh-local/business-plugins: true）
  已停 0 个实例 scope（下次访问自动拉起，新 bundle 才生效）
```
✅ **`bundles` 未被 `pruneBrokenFileDeps()` 摘掉依赖**（这是换产物时最需要核对的一项）。

### 8.4 浏览器视觉验收（✅ 全绿，`agent-browser` + 一次性用户）

R4 一次性用户 `pocui*` → 门户登录 → 进实例 → 设置 →「功能管理」。**全程零缺陷**：

| 步骤 | 观察到的结果 |
|---|---|
| 实例页壳 | 浏览器**实际请求**的 combo URL 含 `@dsh-local/business-plugins/client.js`、`rev=533537bbc02b`（= 06 §7.3 ② 的浏览器侧复核） |
| 设置 → 功能管理 | 分区列表 = 通用设置 / 模型 / 插件 / Agent 预设 / 偏好设置 / 模型设置 / **功能管理** / 用户设置；「功能管理」页 = 内存条 + 工具行 + 插件卡片 + **「我的技能」分组**（同页，分隔线之上是「功能插件」） |
| 分组头 | `❙ 我的技能` + 计数徽章「1 个技能」+ 右侧「+ 上传技能」；下方说明行「上传你自己的技能包（.zip）。启用 / 停用立即生效，无需重启实例。」 |
| 共享技能行 | `platform-capabilities｜共享｜🔒 只读｜已启用｜1 个文件 · 2.9 KB` —— **没有任何动作按钮** ✓ |
| 上传面板 | 点「+ 上传技能」展开 → 按钮变「收起」；面板 = 虚线框 +「把 .zip 拖到这里，或 [选择文件]」+ SKILL.md 要求说明 |
| 选文件 | 选 `poc-skill-demo.zip` → 行内出现 `poc-skill-demo.zip｜843 B｜[上传][取消]`（客户端校验通过） |
| **点「上传」** | `POST /api/skills/mine` → **200**；页面出现「✓ 已上传技能「poc-skill-demo」」；列表新增 `poc-skill-demo｜我的｜已启用｜3 个文件 · 575 B｜[停用][删除]` |
| **点「删除」** | 弹窗 = 标题「删除技能「poc-skill-demo」？」+ ✕ + 「该技能将从你的实例移除，不可恢复；若它当前处于停用状态，保留的文件也会一并删除。」+ [取消][删除] |
| **弹窗确认「删除」** | `DELETE /api/skills/mine/poc-skill-demo` → **200**；页面出现「✓ 已删除「poc-skill-demo」」；列表回到只剩共享技能行 |

截图：`_tmp_t01/ui-myskills2.png`（分组 + 展开的上传面板）、`ui-uploaded.png`、`ui-del-dialog.png`。

⚠️ **一处值得记的机制**：用 `agent-browser` 的 `click @ref` 时，ref 会随每次 `snapshot` 重排；连续操作间**必须重新 snapshot 取 ref**，或用 `eval` 按**按钮文本**定位后再 click（本轮最终用后者才稳定跑通，前者出现过"点了没反应 / 弹窗消失"的假象 —— 不是产品缺陷）。

### 8.5 踩坑记录（**全部是可复用判据，后续同类验收直接照用**）

| # | 现象 | 根因 / 正确做法 |
|---|---|---|
| 1 | 抓实例页 HTML 只拿到 10.7 KB 的**登录页** | 实例子域代理按**会话**判归属 ⇒ curl 必须**带上门户 `sid` cookie**（只有 launch token 不够）。正确姿势：303 → `set-cookie: dsh-auth-*` → 200，壳页 ≈58 KB |
| 2 | `/plugins/??…` 请求 **404（2702 B）** | 两点都要对：① 站点必须是**实例子域**（`/plugins/` 是 dsh 自己的路由，打门户域只会得到门户 404）；② 同样要带 `sid`（否则被当成"无租户"请求 → **假 404**，与"fetch 不能设 Host"同族） |
| 3 | 新用户壳页 combo 里**没有** `@dsh-local/business-plugins` | **新用户 profile 是首次进实例时才创建的** ⇒ `ensure-biz-plugins` 对它直接"无 profile → 跳过"（实测输出）。正确顺序：**先 enter 起一次实例**（生成 profile）→ 再铺 bundle → **`POST /api/dsh/restart`**（client bundle 只在实例启动时加载）→ 再 enter |
| 4 | 直改 DB 审批后登录失败 / CHECK 报错 | 角色取值是 **`active`**（约束 `admin|pending|active|disabled`），**不是 `approved`**；且直改 DB 会**绕过"审批时自动铺 bundle"的钩子**（档案 36）—— 这正是坑 3 的另一个成因 |
| 5 | `POST /api/dsh/restart` 返回 **400** | `restartSchema` 要求 `command` 是**必填 string**（handoff 停写后恒传空串），必须发 `{"command":""}` + JSON 头 |
| 6 | `verify-my-skills.mjs` 首跑"R3 断言"假红 | 断言 `exports.default` 别用 `includes()` —— 本文件**头部注释里就有这句话**（"绝不 exports.default"）⇒ 只断言**赋值形态** `exports.default =` |

### 8.6 回滚演练要点

装回 `/opt/dsh/artifacts/business-plugins-0.3.20.tgz`（版本号不同即可，pnpm 不会命中缓存）→
`ensure-biz-plugins.cjs --all --restart` → 磁盘层版本回落 0.3.20 即成功。**服务端零改动、无需回滚。**