feat(skills): 专项包、整仓导入与 Dashboard 三表联动

[swtxbling]

feat(skills): 专项包、整仓导入与 Dashboard 三表联动

背景

现有 Skill 管理在“安装、组合、分配、诊断”四段链路上彼此割裂：多个 Skill 需要逐个分配给 Bot；GitHub 整仓地址遇到分类目录时扫不到 Skill；文档承诺的 agentbuddy: 标识符从未实现；部分标准 frontmatter 安装后丢失描述；Dashboard 安装向导还有空步骤，并可能在“下一步”阶段触发安装。

本 PR 以 Skill Pack（专项包）为组合单元，把核心模型、解析安装、Dashboard 管理和回归测试一次贯通。虽然改动横跨 core / dashboard / CLI / IM，但都服务于同一条 Skill 管理工作流，因此保持为一个 PR，并按以下逻辑层次组织 review。

改了什么

1. Skill Pack 核心模型与管理入口

• 新增独立的专项包 registry（~/.botmux/skills/packs.json）及 CRUD：校验 id/name/include/tags，成员只允许 skill:*，禁止 pack 嵌套；写入串行化，并用 revision 防止编辑器覆盖并发更新。
• Bot 的 skills.include 新增 pack:<id> selector。会话解析时先解析显式 skill:*，再按策略顺序展开 pack:* 并按 Skill 名去重；同一 Skill 同时被直接引用和专项包引用时，直接引用优先。
• CLI 新增 botmux skills pack list/show/create/update/delete；现有 /skills attach|detach 只修改直接 Skill，并原样保留 pack selector，避免 IM 操作误清空专项包分配。
• Dashboard 新增 /api/skill-packs CRUD，并把 Skill 管理拆成 Skill 库、专项包、Bot 分配、投递设置四个标签：支持专项包搜索/全选、Bot 搜索与 tag 过滤、双向拖拽分配（拖入 Bot 添加、将行内已展示芯片拖回明确移除区取消），以及全局工作区 Skill / delivery 配置。重复投放会显示“已在配置中”而非静默失败，跨单元格移动也不会让投放高亮闪烁。紧凑表格折叠的第 4 个及以后直接 Skill、以及键盘操作，继续通过“选择”编辑器完整管理。
• 补充 pack store、selector fidelity、策略展开、引用保留、安装转专项包与 UI 工作流测试。

2. 来源解析与元数据兼容

• 实现文档已承诺的 agentbuddy:collection/<uid> 与 agentbuddy:<group>/<skill>[@version]；抽出 formatAgentbuddyIdentifier，保证 registry 保存格式可以反解回同一目标。
• 兼容 marketplace 复制命令的 skill add <group>/<skill> 合并路径写法，并保留 --skill / --version 显式形式与 npm_config_registry=... npx -y agentbuddy@latest ... 前缀。
• 用户粘贴的命令只用于提取结构化安装目标；真正执行使用部署机配置的 Agentbuddy CLI，并通过 execFile 传参，不执行用户粘贴的 shell 前缀。
• 裸 owner/repo[/path] GitHub 简写改由后端归一化，同名本机目录优先；其它 http(s) 按 Git remote 处理；未知 scheme 明确报错。Dashboard、CLI、IM 因此使用同一套服务端分类。
• 移除“字符串包含 agentbuddy”启发式，避免误判 URL 或本机路径。marketplace URL 在没有正式格式前明确不支持。
• frontmatter 支持 YAML 块标量（>、>-、|、|-）并容忍 BOM 与前导空行，修复描述被存成字面量 ">-" 或整块元数据静默丢失。

3. 整仓发现与安装一致性

• 默认浅扫只检查源根目录及 skills/*、.agents/skills/*、.botmux/skills/* 的直接子目录；真实集合常见的 skills/<category>/<skill>/SKILL.md 因此会漏检。
• 改为浅扫命中走快路径，无结果时自动回退递归扫描；Git/GitHub 在同一次 clone 内完成回退，不重复拉取。
• discovery 回传 deepScanned，安装阶段沿用相同 fullDepth，避免“预览扫得到、提交时装不上”。显式深度扫描仍可跳过浅扫。

4. Dashboard 安装体验、三表联动与健康状态

• 三步向导改为单页表单：导入地址作为主输入；仓库内路径、Ref、深度扫描放入“高级选项”；支持格式收进可点击、可键盘操作的来源帮助浮层，安装按钮只在用户明确提交时触发。
• 输入框展示与服务端分类保持一致的前端识别提示及部署机运行条件；最终来源类型仍由后端权威判定。失败时按 Git / Agentbuddy / 本机路径展示可执行的诊断建议。
• 新增共用数据层 useSkillsData，四个标签共用 skills / packs / bots，避免各标签独立取数和状态漂移。
• 新增 buildSkillGraph 作为 Skill ↔ 专项包 ↔ Bot 的关系模型，保留“被引用但未安装”的节点；最终能力数、引用数和健康度统一由 graph 派生。
• Skill、专项包、Bot 三表支持互相跳转和预筛选；缺失 Skill 只定位并预填安装入口，绝不因导航自动安装。
• 新增配置健康总览：被引用但未安装的 Skill、未分配 Bot 的专项包、缺失能力的 Bot，均可点击进入对应视图。
• 专项包 API 非 404 失败时保留上次成功数据；首次加载失败保持 packsKnown=false，相关结论显示为“未知”，不会误报 pack_missing 或“配置健康”，也不会泄漏虚假的 0。
• 修复不存在的 CSS 变量导致浅色主题卡片/芯片渲染成深色的问题，并补齐安装面板、对话框、按钮、空状态和未知态样式。

5. 测试稳定性

expect(a).toBe(b) 直接比较两个 React TestInstance 时，失败会让 Vitest 为 diff 序列化两棵带循环引用的内部树，最终耗尽 fork worker 的堆并表现为 Worker exited unexpectedly。测试改为先判断归属关系，再断言布尔值，避免生成巨型对象 diff。

此外，本分支已 rebase 到最新 upstream/master。上游新增 /fork 命令后，命令实现与注册表已经落地，但中英文 Slash Command 文档尚未同步，导致仓库既有的文档同步测试失败；本 PR 仅补齐对应两行说明，不改动 /fork 行为。

影响面评估

• src/core/skills/sources.ts、policy.ts、references.ts、frontmatter.ts 和 Skill Pack store 是共享核心路径，会影响 Dashboard、Skill 管理 CLI、IM 快捷命令及新会话的 priority Skill 解析；对应行为均有专项测试。
• 来源归一化收敛到服务端；test/skill-source-parity.test.ts 锁定 Dashboard 提示与后端分类不发散，但最终判定仍以后端为准。
• frontmatter 改动会影响 registry、本机 CLI 发现和专项包解析等所有 Skill 加载路径；变更只放宽可接受格式，原有单行格式有回归覆盖。
• 深度扫描使用 Node 文件系统递归和现有 Git checkout，未引入 shell/PTY/编码差异；macOS 与 Linux 行为一致。
• 不涉及模型会话运行时的 Claude/Codex CLI 适配器、PTY/Tmux 后端，以及 adopt/restore/话题或群会话生命周期；但 Skill 管理 CLI/IM 命令及会话 priority Skill 解析有上述调整。
• UI 代码改动限定在 src/dashboard/web/**；后端和共享核心改动已在前述条目单列。

测试验证

pnpm build        通过
pnpm test         794 passed | 3 skipped (797 files)
                  12494 passed | 35 skipped (12529 tests)
                  exit code 0；无失败用例、无 worker crash
tsc --noEmit      通过
git diff --check  通过

重点新增/扩展测试：

• test/skill-pack-store.test.ts / skill-pack-policy.test.ts / skill-pack-references.test.ts — 专项包持久化、策略展开、selector 保真与引用行为
• test/skill-frontmatter.test.ts — 块标量、BOM、前导空行及原有格式回归
• test/skill-discovery-deep-scan.test.ts — 浅扫漏检、自动回退、显式 fullDepth 与 shallow fast path
• test/skill-source-parity.test.ts / skill-sources.test.ts — 三入口来源分类、Agentbuddy round-trip、Git 安全边界
• test/skill-graph.test.ts / skills-cross-link-ui.test.ts — 关系图、三表跳转、导航不触发安装、Pack API 错误及未知态
• test/dashboard-skills-ui.test.ts — 单页安装表单、高级项折叠、可访问来源帮助、诊断与选择流程
• test/bot-assignments-ui.test.ts — 左侧拖入分配、重复投放反馈、行内高亮边界、已分配 Skill / 专项包拖回取消、跨 Bot 拖放严格 no-op、Firefox 原生拖拽数据，以及移除时其它 selector 保真

手工预览未执行 switch:here，也未重启 daemon 和现有 Bot。功能主体此前已使用真实数据检查单页安装表单、高级选项、Skill / 专项包 / Bot 三表跳转、健康总览，以及 grill-me 描述展示；本轮来源帮助浮层则在独立临时 HOME、空数据目录和隔离端口的 Dashboard 中验收。全程未提交安装请求，也未在真实 registry 执行 Agentbuddy 写入。Agentbuddy 解析、GitHub 整仓深扫与 frontmatter 兼容由自动化测试覆盖。

截图

Skill 库：单页安装、健康总览与解析后的描述

导入来源帮助：默认收起，按需查看完整格式与 Agentbuddy 命令

专项包：组合能力与 Bot 引用

Bot 分配：专项包、直接 Skill、最终能力与健康状态

部署说明

• Agentbuddy 安装需要部署机具备该 CLI并已登录。未全局安装时可在 ~/.botmux/.env 配置 BOTMUX_AGENTBUDDY_CMD="npx -y agentbuddy@latest"；私有 npm registry 由部署机 npmrc/env 提供。
• 用户粘贴命令中的 npm_config_registry=... npx... 前缀只用于识别来源，不会覆盖部署机执行环境，也不会作为 shell 命令执行。
• frontmatter 修复不追溯已有 registry 条目：受影响的 Skill 需要重新安装或更新一次，才会刷新 description 等元数据。

[deepcoldy]

复审进度（Codex，head 2494788ed）：已完成 pack 解析/来源安全/深扫主链路静态审查，并做了两组定向复现。当前先记录重点，最终 review 结论待构建与针对性测试完成后补充。

目前确认的边角：

1. 默认深扫回退会在“浅扫已有部分结果”时静默漏掉深层 Skill。 构造同一仓库同时包含 skills/flat/SKILL.md 与 skills/category/nested/SKILL.md，默认 Dashboard discovery 只返回 flat；显式 fullDepth: true 才返回两者。原因是 fallback 仅在 first.skills.length === 0 时触发。对“整仓导入”语义而言，混合目录布局会产生无提示的不完整候选集。
2. 合法 JSON、非法 pack member 可打崩解析。 packs.json 若含 include: [123]，resolveSkillPolicy() 在 member.startsWith(...) 抛 TypeError，与 readSkillPackRegistry() 注释中的“corrupt packs.json 不影响 skill pipeline”不符。存储 API 会阻止该值，但磁盘损坏/手工编辑/兼容性输入仍会让新会话解析失败，建议 read 时做完整 schema 归一化或 resolver 对 member 做 typeof 守卫。
3. git 整仓批量安装存在 O(N) fetch/checkout。 installGitSkillsFromSourceAsync() 先 checkout+discover，随后每个 candidate 再进 installGitSkillAsyncLocked() → checkoutGitSourceAsync()。本地 2-Skill 仓库 trace 已出现初次 clone/fetch/checkout 后又对每个 Skill 各跑一轮 fetch/checkout；大仓批量安装会放大网络往返。此循环是既有实现，但本 PR 新打通的深层整仓导入会直接踩到，建议本次至少确认是否接受，理想是一次 checkout 内复制全部 selected candidates、最后一次 registry write。

已核对：direct skill:* 分区先于 pack:*，跨 pack 按名称首个胜出；agentbuddy 用户输入只被解析成结构化 argv，未执行粘贴命令前缀，token/group/path/ref 现有校验未见明显 RCE 逃逸。来源/UI 还有小一致性项在继续确认。

[deepcoldy]

复审结论：请求修改。head 2494788ed；pack 的 direct 优先/跨 pack 去重主逻辑与 agentbuddy 结构化 argv 安全边界核对通过，但发现 2 个会影响核心承诺的正确性问题，以及 1 个大仓性能问题。

Blocking

P2：混合目录布局下，“整仓导入”会静默漏 Skill

src/dashboard/skill-install-request.ts:120-123 只在浅扫结果为 0 时回退深扫。若仓库同时包含：

• skills/flat/SKILL.md
• skills/category/nested/SKILL.md

默认 discovery 只返回 flat，不会设置 deepScanned；显式 fullDepth: true 才返回 flat + nested。这不是“空仓误报”，而是无提示的不完整候选集，用户也没有线索去打开隐藏在高级选项里的深扫。

建议：至少在已知浅扫根下还存在非 Skill 子目录时继续深扫，或用其它方式保证整仓候选完整；补“浅层 + 深层混合布局”回归测试。

P2：语义损坏的 packs.json 可打崩新会话解析

src/services/skill-pack-store.ts:53-65 对合法 JSON 直接按 Record<string, SkillPack> 信任；src/core/skills/policy.ts:111-113 随后无类型守卫调用 member.startsWith()。例如 include: [123] 会抛：

TypeError: member.startsWith is not a function

这与 store 注释的“corrupt packs.json 不影响 skill pipeline”不符。API 正常写入会校验，但手工编辑、磁盘/兼容性输入仍可阻断 session skill resolution。

建议：read 时做完整 schema 归一化/丢弃非法 pack，且 resolver 保留 typeof member === 'string' 的防御；补合法 JSON 但非法字段类型的测试。

需要本次确认的性能问题

P2：git 批量安装对每个 Skill 重复 fetch/checkout

installGitSkillsFromSourceAsync() 在 src/services/skill-registry-store.ts:894-904 先 checkout+discover，随后每个 candidate 又进入 installGitSkillAsyncLocked() → checkoutGitSourceAsync()。我用本地 2-Skill git repo 跑 trace，已看到初次 clone/fetch/checkout 后，对 a、b 各重复一轮 fetch/checkout；含 Git plumbing 共启动 31 个 git process。大仓整仓导入会按 Skill 数量线性放大远端往返。

这段循环是既有实现，但本 PR 新打通的深层整仓导入正是会把它推到真实大集合上的入口。建议本次收敛为一次 checkout 内复制全部 selected candidates、一次 registry write；如果决定拆后续，至少请在 PR 说明里明确评估和上限。

非阻塞一致性项

• detectSourceType() 把文档支持的 skills add owner/repo / npx skills@latest add ... / add-skill ... 显示为“本地”，后端实际判为 GitHub；建议补 parity 用例并修 visual hint。
• docs/setup/skills.md:142 仍写 skills.include “只支持 skill:”，与新增 pack:<id> 冲突。

验证

• pnpm build ✅
• PR 新增/相关 14 个测试文件：169 tests passed ✅
• git diff --check ✅
• git merge-tree --write-tree origin/master HEAD ✅（当前 master 合并无文本冲突）
• 额外定向复现：混合布局默认漏深层 Skill；非法 pack member 触发 TypeError；2-Skill git 批装 trace 证实逐项重复 fetch/checkout。

未执行 merge；仍遵守“申晗确认前不合码”。