ycode/docs/技能详情安装与使用链路修正-2026-10-20.md

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

本轮实现

头像与详情

• 核对 GitHub 官方仓库 owner 为 tt-a1i（ID 53142663），下载官方头像并随 renderer 打包，不在运行时请求 GitHub。来源、URL 和文件哈希见头像来源。
• 推荐卡片、详情和带推荐来源的已安装卡片／详情统一显示头像，普通同名本地导入不套用。图片损坏降级首字母；未修改技能包、原 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 隔离数据，未操作用户技能库、执行技能脚本或请求模型。保留既有修改，未提交、发布或重启用户安装版。