skillhub/openspec/changes/add-dsh-native-plugin/acceptance.md
XiaoSeS f3078afae4 feat(dsh): manage installed skills through conversation
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
2026-10-26 10:54:11 +08:00

22 KiB
Raw Permalink Blame History

验收追踪与实现就绪条件

本文定义功能验收追踪、阶段出口条件和兼容性验证要求。执行结果记录在 verification.md。

1. 功能到证据映射

验收组 产品 ID / 任务 必须看到的结果 证据
A01 原生分发 F01;0.1–0.3、1.1 仓库外 tarball 加载 Host/Client/Remote,单一入口,无额外 CLI/Bun 包清单、hash、固定发行版与平台、实机截图
A02 匿名与来源 F02/F12;0.4、1.3 不发认证信息;地址切换不串结果;拒绝不是空列表 HTTP 契约测试和真实实例状态记录
A03 浏览详情 F03–F06/F11;2.1–2.2 分页来源每批 12 项、点击加载更多;旧来源单次最多 20 项并说明真实范围;新关键词提交后旧响应不覆盖新结果;精确版本、返回保留筛选/滚动/焦点 UI 自动化、延迟响应场景和实机操作
A04 安装目标 F07;0.5、3.1 用户/可信项目,远程 Host 落盘;无项目不猜路径 目标解析测试、路径与主机核对
A05 完整安装 F08–F10;3.1–3.4 确认框列明技能、精确版本、来源和目标,取消时零写请求;资源完整、不执行脚本、无覆盖;文件提交、DSH 发现与会话实际使用分别记录,不由发现推断使用 确认/取消操作、带资源包、hash/metadata/inventory、并发/故障测试及真实会话使用记录
A06 本地管理 F13;2.4 两目标分行、部分失败、离线本地详情、明确来源 本地投影测试与 UI 状态截图
A07 可选模块 F14–F15;2.3 hide 无请求,auto 正确降级,show 不绕过匿名拒绝 网络断言、空/拒绝/错误实例用例
A08 升级 F16–F17;4.1–4.2、4.7 用户确认完整目标集合;漂移/外部目标/同版本变内容阻断 计划快照、变更前后 hash 和共享记录
A09 卸载 F18;4.4–4.7 仅移除单目标;离线可用;ENOENT 与 EACCES 不混淆 多目标测试、隔离/恢复及确认 UI
A10 恢复 F19;3.4、5.2 CAS 后不回滚;未知先核验;同 key 不重放 移动/CAS/日志/清理各边界故障注入
A11 对话发现 F20–F21;6.1–6.3 找技能不写文件;卡片打开共享详情抽屉,关闭保留会话 工具 schema 测试、真实 ToolView 和键盘操作
A12 对话安装 F22–F23;6.2、6.4、6.6 显式请求及安装前确认;取消不提交且保留详情抽屉;accepted 与安装完成分别展示;历史选择失效阻断;双入口幂等 确认框、工具结果、操作日志、重开会话和并发用例

| A13 公共 API | 9.3–9.4 | 开源/SaaS 同契约;必需能力和可选能力分别判定;服务端先兼容部署 | OpenAPI、公共契约测试及实例兼容矩阵 | | A14 独立发布 | 9.1–9.2、9.5 | 插件版本独立;不误触发其他组件;已发布包与候选包一致 | CI 触发测试、包内容比对、干净安装 | | A15 回退 | 9.2、9.5 | 已装技能和日志保留;不兼容日志阻止降级;数据库回退条件明确 | 回退演练与恢复结果 |

| A16 DSH 兼容 | 10.1–10.5 | 单一 DSH 基线、发行依赖固定、未验证版本禁止新写、双入口回归 | 单基线平台矩阵、依赖锁文件、CI 及降级用例 |

详细边界以 specs 中每个 Scenario 为准,上表不缩减它们。

评审边界回归还须覆盖:单范围不可用而另一范围健康、共享清单损坏、大于400条的已安装列表与跨会话重复刷新、accepted/staging无事务时的中断恢复、活跃执行租约拒绝恢复、幂等安装的发现确认及内容变化后撤回确认。恢复和发现核验均不得通过删除日志、伪造提交或绕过完整性检查实现。

2. 实施阶段依赖

flowchart LR
  M0[M0 发行兼容与最小贯通] --> M1[M1 两入口只读体验]
  M1 --> M2[M2 日志恢复与双入口安装]
  M2 --> M3[M3 受保护升级卸载]
  M3 --> M4[M4 实机打包和平台验收]
  M4 --> R[交付可审查产物与限制清单]
阶段 出口条件 未通过时
M0 包加载、Remote、工具身份/结果持久化、ToolView、匿名下载、可信目标及发现观察有实机证据 标明具体阻塞,不直接开展依赖该假设的写操作实现
M1 广场与对话共用读取/详情;可选模块、空/错误、导航焦点符合规范 修复交互/协议,使用接口定义的有效数据
M2 日志与恢复在写入口开放前就绪;页面/工具同目标并发和响应丢失通过 补齐失败、并发和恢复场景后交付
M3 完整计划、共享版本、精确目标、CAS 与恢复矩阵通过 不提供 force 或省略确认绕开失败
M4 干净包、至少一个真实资源技能使用、平台矩阵、命令结果与已知限制完整 只声明已验证平台,不声称全部兼容

3. 兼容性验证要求

编号 验证对象 验证方法 设计约束
B01 DSH 实际兼容发行版、Node/peer/build 条件 记录版本与 tarball 贯通证据 同仓库独立原生包
B02 外部 Remote manifest 挂载及工具结果 UI 协议 最小真实插件验证成功/拒绝/重载 单一 Host 服务,页面/工具共用
B03 每个目标 Registry 的匿名详情/评论/下载能力 对实际实例契约测试,记录状态码 不登录、不绕过审核拒绝
B04 会话身份与项目根在工具/Remote 的传递方式 官方对应发行源码及实机测试 可信目标、selectionRef、旧上下文不得自动迁移
B05 DSH 发现观察证据 实际安装后记录宿主发现输出 不可确认时显示 unconfirmed,保留未确认状态

以上项目应在 M0 完成兼容性验证。

4. 文档验证与交付判定

文档完成:本地链接有效、围栏闭合、Mermaid 可解析、OpenSpec strict 通过、范围和追踪一致。功能完成:相关任务已执行、检查通过、对应证据记录。两者分开判定。

5. 正式需求覆盖

需求分组 正式规范 验收组
单一匿名来源、上下文失效、公共 API 与兼容演进 连接规范 A02、A07、A13
浏览、可信目标、完整包、冲突保护、发现反馈 消费规范 A03–A05
已安装、精确计划、升级、卸载、日志与恢复 消费规范 A06、A08–A10
原生页面、独立包、可选模块、生命周期 原生体验规范 A01、A03、A07
对话搜索、详情引用、显式安装、历史结果保留边界 原生体验规范 A11–A12
独立发布、兼容矩阵与安全回退 原生体验规范 A14–A16

版本支持及能力降级遵循 兼容性设计。

6. 交付状态

本轮产品交互已获人工确认,当前候选完成本地自动化检查与真实 DSH 预览验证。各环境和历史证据不能互相替代,当前状态统一见验证摘要。发布前仍需最终提交 CI、目标部署契约验收及候选版本确认;macOS 实机按既定安排后续验证。

7. 真实模型与宿主交互执行单

本节落实 5.3、6.6 的剩余验证,不用直接调用工具或合成历史消息代替模型行为。使用隔离 Web Profile、测试会话与工作目录,连接已批准的测试模型;模型凭证仅在本机 DSH 配置中提供,不进入截图、报告或仓库。先执行只读搜索用例,通过后再按序执行写入和异常用例。每例独立记录实际工具调用、操作 ID、文件变化与截图,不以自然语言“成功”作为通过依据。

用例 用户操作或输入 必须观察到的结果
只读搜索 “在 SkillHub 搜索 document 相关技能,只展示结果,先不要安装。” 模型调用原生搜索工具并显示卡片;没有安装工具调用、安装操作日志或技能文件新增
歧义选择 提供至少两个实际候选后输入“装那个文档技能”,不指定目标 模型要求明确选择或引导打开详情;不能任意挑选候选写入
明确安装 从结果打开固定版本详情,选择当前项目并明确确认安装 参数来自已查看的候选和可信目标;先显示受理状态,后通过同一 operationId 展示终态;文件、资源与清单一致
无详情直接安装 搜索至少三个候选后直接输入“安装第二个到当前项目”,不打开详情 使用第二项原 selectionRef,Host 固定搜索时版本;openConversationDetail 与 acknowledgeConversationDetail 调用数均为0;实际 completed、文件哈希、库存、DSH发现分别核验。直接官方工具验收与真实模型验收分开记录
核验期间变化 未展示候选核验时改变来源/项目、发布新latest、使原版本不可用或产生展示歧义 上下文变化和版本不可用拒绝;新latest不改变所选版本;不绕过已展示快照歧义
模型使用资源 对已安装 document-helper 输入“使用刚安装的技能,按说明读取 references/note.md,并告诉我文件内容。” 模型实际加载该技能并读取安装目录内的资源,回答与文件内容一致;仅识别技能名称或复述历史卡片不算通过
真实 Registry 技能使用 从已验证开源测试实例安装一个带资源、无外部执行副作用的真实技能,要求按其说明完成一个只读任务 记录真实技能坐标/固定版本、资源完整性、DSH 加载和模型使用证据;本地 document-helper 夹具不能替代此项
关闭详情 在搜索结果打开详情后直接关闭,不确认安装 没有隐式安装;焦点回到触发入口,搜索结果仍可用
停止等待 分别在工具受理前、安装已受理后点击 DSH 的停止按钮 受理前没有新增文件;受理后不谎报取消文件事务,能通过原操作查询实际结果;区分宿主停止、工具 signal 和事务生命周期
断线重开 安装受理后断开浏览器连接,再打开原会话 原回执与当前操作状态可关联,无第二次安装提交;历史记录不伪装为新操作
失效记录 显式移除测试技能目录后重开原卡片,再尝试安装或清理 显示实际缺失状态;不能直接用历史引用覆盖或删除未知路径;按现行确认流程处理

前四项使用现有 catalog-fixture 的 document-helper,资源路径为 references/note.md,基础版本内容为 Native installation resource。停止/断线用例需受控延迟夹具以准确区分受理边界,不靠点击时机猜测。真实 Registry 用例另选已审阅的只读技能。对话升级和卸载不是首期模型工具范围,不在这些用例中添加新能力。

模型调用前需要确认可使用的本机测试配置与调用额度;未获得授权时保持未验证。该依赖不阻止继续整理本地证据、文档和不调用模型的检查。macOS 按用户决定延后验证,不作为本轮验收阻塞项,状态保持“未验证”,不得列为已支持平台。远程 Host 仍需要对应测试环境,不以本机 WSL 或浏览器夹具替代。

7.1 模型验收记录原则

模型回合、直接官方工具调用及浏览器状态投影分别记录。真实模型搜索和明确安装已有历史验证;当前展示样式调整不重复消耗模型调用。无详情直接安装的官方工具核验,不能单独替代模型完整回合;具体已验证范围见验证摘要。

8. 发布前检查

项目 完成条件
最终提交 CI 对整理后的实际提交执行检查;历史提交矩阵不替代当前提交
目标 Registry 当前服务端版本的公开契约、下载与资源完整性验收;SaaS 独立同步和验收
平台兼容 明确发布声明覆盖的平台及精确DSH/Node组合;macOS实机未验收不得声称支持
候选与发布 确定正式版本与权限,检查独立tarball;获准发布后验证实际下载包
升级与回退 保留技能、清单和事务日志;存在正式前版后补跨正式版本回退验证
Host重启 使用有效入口重新进入;旧页面异常时强制刷新,不以空白页推断数据丢失

本轮未发布、创建tag或执行生产部署。已获人工确认的产品功能与发布门禁分别跟踪,未验证项不改写为通过。

Issue #981:双 RC 兼容候选验收

验收项 结果与边界
精确版本和拒绝策略 支持 0.2.0-rc.2、0.2.1-rc.2 的一致依赖图;未知版本、跨 RC 混装、清单失效及 Host 解析不一致的定向测试通过。
构建与源码检查 build、typecheck、lint、完整 365 项插件测试通过;冻结后的 63 项定向回归及 OpenSpec 严格校验通过。
严格依赖安装 Linux 两版官方 Host 均完成原生 Profile 安装和独立 npm 严格安装;实际配置与故意冲突负控确认严格检查生效,候选的全部 81 个文件与安装内容一致。未使用 peer 豁免或 fresh graph overrides。
原生运行 两版均通过 runtime-baseline、plugin-lifecycle、plan-context、plan-source、upgrade-drift,覆盖加载、启停、真实 Gateway 作用域、上下文/来源漂移及本地修改保护。
真实浏览器 两版均在本地受控 Registry 上通过设置保存与读回、搜索、详情,以及项目/用户两个范围的 1.2.0 安装、1.3.0 升级和卸载。每版六次写入 RPC;三类取消均不改变文件、库存和操作日志。实际 Client 交付内容核验通过,未认证 RPC 返回 401,无未解释页面异常。
CI 与保留组合 兼容修复 CI 的八组运行检查通过:旧 RC 三系统各两个 Node 档,新 RC Linux 两个 Node 档;旧 Cordis 完整保留组合的原生回归通过。CI 与本地构建产物分别留证,不混用摘要。
尚未验收 新 RC 的 macOS/Windows 原生文件操作、真实桌面及真实模型调用不在本轮通过范围内;既有单元或 Linux 结果不替代这些验证。

两版 Linux 的严格安装与浏览器验收使用同一冻结候选包。

pnpm add 不能单独证明严格 peer 校验有效。本轮追加 dsh plugin --profile <profile> install --strict-peer-dependencies --ignore-scripts 与独立 npm --strict-peer-deps 安装,并验证冲突时正常失败。

交付跟踪见 PR #988。本轮未发布 npm、创建 tag、调用模型或修改生产环境;公开插件 0.3.0 不包含此候选兼容修复。

使用此技能:候选验收门禁

编号 输入与动作 应观察结果 当前状态
USE-01 已安装卡片、详情、安装成功分别点击使用 三处共用本地核验与原生草稿衔接;不自动发送 通过:五处原生入口及统一服务
USE-02 市场 slug 与 SKILL.md name 不同 调用真实 name;不取标题或 slug 猜测 通过:双 RC 原生技能真名
USE-03 草稿已有文字、引用与附件;包含非折叠选区 既有内容保留,在原生捕获位置末端插入;仍可编辑和手动发送 通过:选区行为测试;原生引用和图片保留
USE-04 核验期间编辑草稿、切会话/来源/工作区、卸载组件 比较或上下文检查失败,无跨会话污染、无自动重试覆盖 通过:行为测试及原生会话/草稿竞态
USE-05 本地资源改变、同名 Provider 覆盖、禁止用户调用、记录删除 明确阻止,草稿和技能文件不变 通过:行为测试;原生资源改动及同名覆盖
USE-06 从已升级或已卸载的历史安装回执使用 不静默替换版本;要求选择当前安装 通过:精确版本/范围行为测试;当前回执实机
USE-07 两个支持 RC 独立 Profile 加载同一冻结候选 实际 Host RPC/原生编辑器交互通过,无脚本异常、模型请求或消息提交 通过:双 RC 各 12 项原生浏览器检查

设计见 use-skill-design.md。详细结果见 verification.md。“通过”指各项规定层级的组合验收,不表示所有异常分支都已逐一人工浏览器操作;本功能尚未发布到 npm。此处不扩大到真实模型技能执行、SaaS、桌面或原生 Windows/macOS 验收。

固定技能案例文件:开源验收

已确认 .skillhub/examples.json 为上传、下载和安装后保持一致的唯一案例文件,随技能版本更新。协议合法则自动识别,不合法则在通过通用安全检查后按普通文件保留;不新增 Web 编辑器或独立缓存。详细行为与验收由 使用设计 和 正式场景 定义。

协议 schema、接口投影、内部 metadata 上传策略和旧消费者发布策略已在 skill-examples-design.md 定义;开源跨端功能、真实新旧消费者与双RC案例选择已通过本地验收,具体范围和平台缺口见 verification.md 的固定案例开源实现记录。SaaS 后续独立执行,见 tasks.md §40.9。

输入框内联案例交互:本轮门禁

编号 动作 预期
USE-N01 技能中心的卡片、详情及安装成功点击使用 同一工作区仅创建一个新对话,展开内联案例;旧会话内容、引用、附件不变
USE-N02 对话工具回执点击使用 留在原会话,展开同一内联案例区,无新对话
USE-N03 取消、选择后确认、自定义与无案例 展开不写草稿;取消不写不删;确认后可编辑,无案例不显示空选项
USE-N04 快速重复、创建失败、切会话/工作区/来源/语言、确认期间编辑 明确失败或撤销,旧结果不抢回导航或污染其他草稿
USE-N06 满8份非空草稿、回访、清空、会话移除、创建失败、插件卸载 新建前限额拒绝,不驱逐;官方retain按生命周期准确释放;不承诺跨刷新持久化
USE-N05 双支持RC安装同一候选并实际浏览器操作 官方API与slot可用,核验精确原安装范围/版本、草稿附件保留,零消息发送和模型调用

本轮组合门禁已通过,结果见 verification.md 的“原生新对话与输入框案例交互”。USE-N01–N03、N05 的正常交互与 USE-N04 的重复点击、切会话、确认期间编辑,均在两版真实浏览器验证;创建失败、工作区/来源/语言失效、无案例和 USE-N06 的容量/清理分支由行为测试与独立评审覆盖。不是所有边界都逐一执行了浏览器操作,历史弹窗结果不替代本轮。

对话管理与按位置版本验收(任务 42)

场景 必须观察的结果
新安装不指定范围 默认用户级;项目级在高级入口;明确项目请求不误装用户级
两位置 v1,项目升级 v2 用户级文件/版本/指纹/时间/归属不变;项目显示 v2
多份安装目标不明确 先选择,再确认;默认安装范围不用于猜测修改目标
已有项目级安装 查询和管理保留,不迁移或隐藏
取消与伪造确认 不下载/更新/卸载;模型 confirmed 标志不能授权
本地修改、共享目标、来源不符 操作阻断,保留原文件
切换来源/会话或旧引用 旧计划失效,不回退为最新版本或另一安装
并发更新与响应丢失 无库存丢失;重复请求对应同一操作;不覆盖其他位置
库存迁移与崩溃恢复 原始备份可验证;明确唯一权威;文件与目标记录一致
CLI/sync/suite回归 正确读取各位置版本,不改变未选目标;归属保护不减弱
真实宿主与模型 双RC浏览器、原生确认与回退;真实模型证据独立记录

Desktop 旧版、SaaS、npm 发布不计为本轮已验收;需要单独任务或授权。

任务 42 的代码、行为测试及双 RC 浏览器门禁已通过;最终候选真实模型完成项目单位置更新与原操作查询。完整结果、历史候选取消场景和执行前冗余追问的体验限制见 verification.md“对话管理与按安装位置版本”。未授权的来源、未选位置、共享目标和模型伪造确认仍由 Host/核心硬校验保护;模型措辞不作为写入授权。

42.8 分组与场景操作增量验收

以下是本轮需验证的准则,不沿用早期逐行 UI 的通过结果:

  • 同一来源与技能身份只展示一次;同名不同 namespace 不合并。同 scope 多目标保留且选中标签与确认一致。
  • 用户/项目版本随选择显示,按钮使用对应引用;在检查未完成时切位置,迟到结果不能更新另一目标。
  • 单份无 Tab,正常无刷新;低频操作在更多中,更新检查/确认/终态仅出现相关按钮。
  • 确认目标锁定,取消不写;变更仅影响选定位置,另一份文件与库存不变。
  • 旧引用仍拒绝;重新查询只读替换内容,不能自动执行旧意图。
  • 部分读取失败不视为未安装;本地修改、共享归属、同名覆盖及禁止用户调用保持原边界。
  • 双支持 RC 验证实际组件,深浅主题和窄屏无目标截断,菜单键盘操作和关闭后焦点可用。
  • 原型场景截图与正式宿主结果分开保存;本轮未调用模型时明确说明,不重写既有真实历史。