# 技能详情、安装与使用链路修正（2026-10-20）

## 本轮实现

### 头像与详情

- 核对 GitHub 官方仓库 owner 为 `tt-a1i`（ID `53142663`），下载官方头像并随 renderer 打包，不在运行时请求 GitHub。来源、URL 和文件哈希见[头像来源](推荐技能头像来源-2026-10-20.md)。
- 推荐卡片、详情和带推荐来源的已安装卡片／详情统一显示头像，普通同名本地导入不套用。图片损坏降级首字母；未修改技能包、原 ZIP 哈希或内容 digest。
- `SkillDetailShell` 统一推荐与已安装详情：头像／标题／主操作、可展开简介、真实元信息及按内容收缩的正文。移除仅展示来源却沿用正文最小高度导致的大块空白；完整 commit、包路径和哈希折叠展示，不编造安装数、使用数或市场 ID。
- 已安装技能说明仍读取真实本地 SKILL.md。未安装时只展示内置精选简介，不提前下载整个包。

### 全局弹层与安装

- 根因：能力中心 `isolation:isolate` 限制了内部 fixed 遮罩的层叠范围，而侧栏 sticky 标题拥有独立层级。
- 详情、导入及卸载确认使用 body 级 `SkillModalPortal`，保留源主题变量和 CSS 作用域；背景设为 inert / aria-hidden 并在退出后按原值恢复。没有降低全部侧栏层级。
- 共用焦点栈，Esc 只关闭顶层，Tab／ShiftTab 包含折叠区 summary 并跳过闭合 details 内的不可见按钮，关闭后恢复焦点。技能弹层存在时不响应背景的应用导航快捷键。
- 推荐卡片和详情共用操作状态。首次安全确认在原详情内展示；下载、校验、提交、失败、取消和成功均原位呈现，提交阶段不可取消。关闭详情不取消已确认安装，重新打开继续显示同一操作。
- 成功按钮切换为“去使用”，成功提示也提供相同入口；移除列表底部重复的永久完成面板。失败可明确重试，覆盖确认仍展示当前来源、本地修改及启停保留。
- 沿用操作 ID / 单调时间戳、防重复与跨窗口互斥。GitHub 官方 API、固定提交及 ZIP 安全／事务校验保持不变。

### 新草稿与斜杠

- 管理页各“去使用”入口统一调用 App 的新任务 intent：继承工作空间和模型，清除原任务专家绑定；带目标 owner 的 intent 将技能加入新草稿并聚焦，不发送、不创建持久会话。已有会话草稿不被覆盖。
- 无效或仅模型调用技能不提供可执行的使用动作；禁用技能显示“启用后使用”，等待启用和状态确认成功后再跳转。
- 斜杠问题根因：只修改 `text`，旧 `userContent` 在切换至 Slate 时重建了斜杠；菜单因检测到旧文本重新出现。
- `withCapabilitySelection` 将技能选择、纯文本和结构化草稿合并为同一次草稿更新。斜杠采用 add-once 语义，加号菜单仍为多选 toggle。
- 已有 Slate 编辑器通过文本叶事务删除触发区间，PointRef 保留光标与引用的相对位置，不删除附件或技能标签；恢复原生焦点以处理移除 picker 后 Slate 焦点缓存仍为 true 的情况。选择后可以直接继续输入。
- Esc 记录当前触发文本的关闭状态，只有用户编辑后才重新检测；中文输入法组合期间不弹菜单。

## 接口与文件边界

- SkillsApi 不变；`RecommendedSkill.avatarResource` 新增可选受限标识 `archify-owner`，不是任意本地路径或 URL。
- 输入区内部回调增加可选 `CapabilitySelectionIntent`（slash/menu 来源及已消费的 text/userContent）；ReferenceContentEditor 增加删除文本区间的宿主方法。
- 新增公共详情／portal／头像及源文件选择 helper。未修改 WorkBuddy 安装文件，也未改变技能下载的主进程信任边界。

## 原版依据与限制

- 本轮按用户选择仅做原版只读源码调查，没有启动额外 WorkBuddy 实例或安装原版技能。
- WorkBuddy 5.8.2 已保存 REA 证据 `ev_717fa5e846e64d67ac19c8925d121bff632c0d3aefb3603b10858559cabb2dcb` 的恢复源码中，`ActionRow` 随安装状态切换安装／使用；`toastSkillInstallSuccess` 带使用动作；`useTrySkill` 普通分支进入新任务草稿。
- 本次 REA 请求 `127.0.0.1:9223` 返回 endpoint_unreachable。当前安装包 SHA-256 为 `3e50fcb5b060deba4f1ea9a8c293cf955bf12d7e52d971985de914350afd9077`，与历史技能证据不同；REA inventory 记录 45 项完整性矛盾，历史文件路径不能直接选中。此次 inventory 仅作身份／限制记录，不据此宣称分析了当前版本的详情实现。父 Evidence：`ev_1908879a0d710764cd53bd08c36bd9d70d07a004c08ee8f711ca6f849a3b6244`。
- 因此是“历史 REA 源码行为依据 + YCode 实现及动态验收”，不是当前原版同场景动态或完整 1:1 验收。安装完成也不意味着 Archify 的执行依赖和全部绘图能力已验证。

## 验证

- `npm run test:capability-slash:ui`：真实 ComposerControls / Slate / 生产选择 helper 的隔离 Electron 测试 **21 项通过**，`.tmp/capability-slash-3UD46Z/report.json`。覆盖鼠标、Enter、裸斜杠、句中光标及后文、已有与重复技能、继续输入、多行、附件、Esc、IME；零 renderer 错误。
- `npm run test:recommended-skills:ui`：**48 项通过**，`.tmp/recommended-skills-ui-LGtBA4/report.json`。受控宿主覆盖确认与同一详情 DOM、成功入口、取消、关闭再打开保留操作、提交不能取消、禁用后启用使用、冲突替换、错误重试、外部操作、过期事件、Tab 焦点和深／浅色窄窗。不是实际网络安装。
- `node scripts/test-skills-ui.mjs`：既有管理／真实隔离文件系统与受控 picker **37 项通过**，最终单独复跑 `.tmp/skills-ui-10SOjj/report.json`；并发运行曾发生一次坐标点击未切换批量态的测试失败，独立复跑通过，不将其隐藏为从未失败。
- `npm run test:recommended-skills`：后端 **66 项通过**，包括离线缓存的 Archify 实包组；没有更改下载与导入校验策略。
- `npm run test:composer-capabilities`、`npm run test:conversation`、`npm run test:persistence`、`npm run test:sessions` 均通过。输入区回归日志 `.tmp/skills-flow-composer-regression.log`。
- 类型检查及完整构建通过，日志 `.tmp/skills-flow-build.log`。
- 正式 main/preload/renderer 真实 GitHub 下载隔离验收 **20 项通过**，最终报告 `.tmp/recommended-app-RFA1cK/report.json`；包含 body 级遮罩、背景 inert、侧栏命中测试、全窗深色／720px 截图、离线头像、原位安装、新草稿引用、原会话草稿恢复及无持久会话新增。主线程查看同批实现的全窗／窄窗、安装成功和输入区截图。

所有技能安装、启停和草稿测试均使用 `.tmp` 隔离数据，未操作用户技能库、执行技能脚本或请求模型。保留既有修改，未提交、发布或重启用户安装版。