skillhub/openspec/changes/add-dsh-native-plugin/skill-examples-execution-plan.md
XiaoSeS 3402c07dbb feat(dsh): add versioned skill examples and native task handoff
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
2026-10-22 17:50:03 +08:00

12 KiB
Raw Permalink Blame History

技能使用案例:执行范围、实施顺序与 SaaS 同步

1. 目标与当前状态

在 DSH 点击“使用此技能”后,用户可以选择该技能的本地版本案例,或自定义任务,再将包含真实技能调用的内容填入原生输入框。案例固定为技能包中的 .skillhub/examples.json,采用多语言 id/title/prompt 对象与 {{skill}} 占位符,随技能版本更新。

协议唯一来源是 案例实现设计 与 JSON Schema,本文只确定执行范围、依赖和验收,不定义第二套协议。

开源实现与本地验收已完成:共享核心和 CLI 保留随包案例并纳入指纹,开源后端/Web 提供非阻断预检反馈,DSH 支持多语言案例选择、末次核验与草稿衔接。完整检查、真实后端和双 DSH 浏览器结果见 验证记录。改动尚未提交或发布;SaaS 实施与联验后续另做,不作为本轮完成前置。

2. 范围与责任

模块 本轮开源研发范围 不在本轮范围
作者协议 固定文件、字段/语种/占位符校验、可复制说明及样例 作者填写额外Web表单、修改SKILL.md、生成案例内容
共享CLI核心 包路径策略、解析器、完整性指纹、内部记录保护;安装/升级/同步/恢复接缝 独立案例缓存、自动修复作者JSON、案例独立刷新
CLI 目录发布与sync push保留作者文件,非阻断协议提示,正常管理带案例技能 新增案例管理命令、改变既有remove/force产品语义
开源服务端 上传路径与内部metadata边界、发布预检识别摘要;核验版本文件/ZIP/指纹链路 新案例数据库表、案例编辑API、独立案例版本或CRUD系统
开源Web 文件夹打包精确过滤内部记录;现有发布页显示识别结果/非阻断提示 案例编辑器、语言配置页、市场案例展示新页面
DSH Host 可信安装目录读取、解析状态与摘要投影、复用现有prepareSkillUse 任意路径读取RPC、模型执行或新增服务端安装任务
DSH Client 多案例面板、语言选择规则、标题/正文预览、自定义、占位符与原生草稿衔接 语言切换设置、自动翻译、自动发送、输入材料变量系统
SaaS 本轮提供独立交接文档和一致性测试清单 本轮直接修改SaaS仓库、数据库、部署或生产内容
发布 本轮确定依赖和门禁,研发后准备可审阅候选 自动提交/合并、tag、npm发布或上线

共享核心改变后套件等现有消费者需要回归,但本轮不增加DSH套件产品能力。不将不同源手工技能纳入SkillHub案例管理。

3. 实施顺序与交付切片

flowchart TD
  A[P0 协议与历史内容基线] --> B[P1 共享核心与CLI内容规则]
  A --> C[P2 开源服务端与Web发布链路]
  B --> D[P3 DSH多案例与原生草稿]
  B --> E[P4 跨端生命周期与旧消费者验收]
  C --> E
  D --> E
  C --> S[SaaS Agent按同一协议适配测试环境]
  E --> R[审阅候选与发布准备]
  S --> T[SaaS测试环境与真实DSH联验]
  R --> T
  T --> P[授权后分阶段发布]
阶段 具体动作与产物 退出条件
P0 基线 固定schema/样例,记录实际检出基线;本地夹具建立旧包/新包/非法案例/内部记录冲突;确认宿主语言来源;盘点可访问历史包是否存在已被旧规则忽略的.skillhub作者文件 设计冲突解决;未知历史子集明确标注;不访问未授权生产数据
P1 共享核心与CLI 统一根相对路径策略;指纹纳入作者文件、仅排除内部记录;解析对象/语言/占位符;修正目录发布和sync;审计恢复/回滚所有调用点 有效/无效案例字节均保留,未知新增/修改仍被保护;内部metadata不可伪造;CLI范围检查通过
P2 开源服务端与Web 校验预览和发布共用内部记录拒绝规则;保留examples;现有预检响应增加可选识别摘要;Web目录打包精确过滤,显示非阻断提示;生成API类型 手工ZIP、文件夹、直接API一致;无案例旧包正常;存储清单/下载/resolve指纹一致
P3 DSH消费与交互 prepareSkillUse扩展有界对象投影;使用界面语言→父语言→作者默认;面板标题/正文、按id选择、自定义;确认时复验摘要/语言/安装/草稿并替换真实调用 多入口共用,取消不写草稿;保留文字/引用/附件,不发送;语言与安装范围不串用
P4 端到端与兼容 使用实际打包候选和旧公开包完成兼容矩阵;真实本地Registry与双RC官方Host跑生命周期、浏览器及原生输入框 记录通过/失败/不支持,独立review无阻断问题;不以mock或schema检查代替产品验收
P5 交付准备 清理临时证据、回写OpenSpec与双语使用说明;提交/PR及包发布按后续授权执行 候选、检查记录和未验范围可审阅;不擅自发布

P1和P2可在协议固定后分别实施,但必须使用同一组路径/字节夹具;P3可以先用受控解析夹具开发,P4必须依赖完整真实链路。先运行最小测试,再运行受影响模块完整检查。

4. 开源代码接缝

下表为已核对的当前文件,不要求为匹配规划而重命名或复制现有模块;新增helper位置由实现时的最小复用决定。

责任 现有接缝
指纹与发布打包 cli/src/services/skill-fingerprint.ts、cli/src/commands/publish.ts、cli/src/services/sync-service.ts、cli/src/platform/archive.ts
安装记录与安全恢复 cli/src/services/install-service.ts、cli/src/integrations/recovery-files.ts、upgrade-baseline.ts、native-installed.ts及所有恢复调用点
服务端路径/包检查 server/skillhub-domain/.../skill/validation/SkillPackagePolicy.java、SkillPackageValidator.java,以及上传提取的包根归一化
预检识别摘要 server/skillhub-app/.../service/SkillPackagePreviewService.java、dto/SkillPackagePreviewResponse.java
版本内容核对 SkillPublishService文件manifest/存储与SkillQueryService.computeFingerprint;现有服务端按全部SkillFile聚合,若已符合则只补测试,不重写算法
Web发布 web/src/features/publish/folder-zip.ts、web/src/pages/dashboard/publish.tsx、现有查询hook/翻译资源、生成的API类型
DSH使用 plugins/dsh/src/host/index.ts的prepareSkillUse、host/types.ts、src/client/use-skill.tsx及既有使用入口

公开API新增字段仅限已有预检响应的可选识别摘要,旧响应缺字段保持兼容;精确返回字段见案例实现设计。已有版本文件接口已经返回原始内容流,安装后Use无需额外网络请求。实现如发现还需新端点、表或安装状态字段,先回到设计评审,不能扩大范围后再补文档。

5. SaaS 后续同步:必须、条件项与无需调整项

SaaS实际模块名称、数据结构和已部署行为需由SaaS Agent核实;下面是目标契约,不是已完成状态。

SaaS项目 必须达到的行为 是否必改代码
文件接收和存储 不丢弃/改写.skillhub/examples.json;合法、非法协议均按普通安全文件保留 先对照,已符合则补验证
预检和正式发布 同一规范化路径下,拒绝上传内部metadata;合法协议识别多语对象,非法仅非阻断提示;不能绕过扫描/审核 对照后补缺口
Web文件夹上传 只过滤根目录内部metadata,保留examples和其他允许作者文件;无案例编辑表单 若有目录上传或既有过滤则同步
清单、ZIP、resolve指纹 作者文件全部覆盖且算法与新消费者一致,原始字节/版本/坐标对应 核验为必需,算法已一致不改
精确版本文件读取 如已有通用file接口则复用,返回原始字节;权限/租户/可见性不变 现有能力充足不新增接口
发布提示摘要 若复用开源Web预检体验,同步可选examplesStatus/examplesCount及OpenAPI类型;不得影响旧客户端 SaaS有相同预检入口时实施
本地技能管理/案例选择/占位替换 由CLI与DSH负责,SaaS不读取用户项目或主机目录 不新增服务端能力
案例持久化 复用版本包文件、现有对象存储与文件清单 本期不新增案例表或数据迁移

SaaS的发布、审核、删除和版本复制流程都应自然保留该文件;若存在技能包重建/过滤中间层,必须补齐该层,而非只在上传Controller加字段。原始文件API及对象存储URL不能变成绕过私有技能或跨租户隔离的通道。

可直接交接的增量任务见 SaaS案例适配Prompt。旧的总体DSH交接见 saas-agent-prompt.md,不要重复实施已经上线的通用Registry能力。

6. 验收矩阵与完成定义

层级 核心场景 可观察结果
协议 多语对象、空集合、非法JSON/结构/语种/id、上限和未知版本 解析状态准确;非法内容不变成案例,也不因此丢失文件
发布 CLI目录、sync push、Web目录、手工ZIP、直接API examples路径/字节保留;内部metadata精确过滤或明确拒绝
本地生命周期 install/retry/upgrade/remove/sync/rollback/recovery/suite manifest/库存/目录一致;本地案例改动受保护,恢复不误删未知文件
UI 多案例和自定义、语言回退/变化、占位符/无占位符、重复点击/取消 选择按id,真实name而非slug;保留草稿附件且无自动发送
上下文 用户/项目、同名覆盖、不同Registry/版本、读取期间切会话 不串用、不插入陈旧任务,不因模板存在跳过可调用性核验
消费者兼容 新消费者→旧无案例包、新→新案例包、旧→新包、旧访问新安装目录 用实际产物观察成功或拒绝/原行为,明确不支持混用,不假称全兼容
SaaS测试环境 发布→精确版本读取/下载→新DSH安装→选择案例→升级/卸载 真实目标环境全链路成立;不能仅以HTTP200或单测代替

兼容发布顺序为:开源候选完成联验→授权发布支持新规则的CLI/DSH→SaaS适配测试环境联验→授权部署SaaS→推广带案例的新技能版本。SaaS研发可提前并行,不必等npm发布,但生产推广必须等兼容消费者可用。

新旧包与旧二进制不能全量透明兼容。旧CLI的remove/force行为沿原语义,新设计不能改变已经发布的二进制;旧DSH拒绝的具体动作需实际验证。历史包字节、版本号和指纹不得回算。出现历史被忽略作者文件时保持独立迁移门禁,不自动修改旧安装记录。

回退软件版本前先确认是否仍需管理新格式安装;优先停止推广新案例技能并保留已安装目录及可管理它的新消费者,不通过删除examples或伪造metadata来迁就旧客户端。SaaS应用回退不修改历史对象/文件清单。

本功能的确定性验收以原生草稿与文件生命周期为主,不要求真实模型调用来证明模板填入正确;若增加模型执行体验验收,单独记录模型配置、额度和真实对话证据,不把模型输出当作文件兼容证明。

完成定义:P1–P4实现与验证通过、文档/任务状态与证据一致、SaaS增量交接可执行。SaaS部署、npm发布及生产可用性为后续独立交付状态,不能被本地完成所代替。