skillhub/openspec/changes/add-dsh-native-plugin/lifecycle-design.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

安装、升级、卸载:产品规则与执行契约

本文统一定义安装、升级、卸载的产品规则、执行协议、并发控制和恢复机制。

1. 精确定义与范围

操作 改变什么 不改变什么
安装 一个明确目标新增技能包与记录 不覆盖已有目录,不执行包内脚本
检查更新 读取源最新可用版本并比较本地版本 不写目录、不自动下载完整包
升级 将确认计划中的已有安装替换为解析时的精确新版本 不随执行时 latest 漂移;不降级,不绕过本地修改
卸载 移除一个确认目标的技能目录及对应 inventory target 不删远端技能,不删除其他目标,不卸载连接插件

本期均是用户主动操作,没有自动更新、批量跨技能管理、版本回退、清理未知目录或 Suite 管理。无登录、Token 或权限管理;升级使用匿名 Registry,卸载可以离线完成。保留宿主已有调用边界与策略。

2. 已安装页交互

已安装行显示坐标、已装版本、范围、本地状态、更新状态和操作。基础列表只读本地数据,打开页面不对全部条目发起远端更新检查。

行状态 详情 检查更新 升级 卸载
身份/版本/基线可信,尚未检查 可用 可用 先检查,不能直接提交 可进入卸载预检
已确认新版本可升级 可用 可重新检查 可进入计划 可进入卸载预检
最新且指纹一致 可用 可重新检查 禁用,显示已是最新 可进入卸载预检
远端离线或匿名拒绝 本地可用 显示失败/重试 禁用 本地预检通过仍可卸载
本地文件修改、缺基线或记录失配 可用 可只读获知版本 阻断并给原因 阻断,避免删除无法确认的文件
Suite/shared ownership 可用 可只读获知版本 本期阻断 本期阻断,不能破坏共享来源
目录已经缺失且记录精确可信 本地可用 不作为完整安装检查 阻断,不能冒充升级 变为“清理失效记录”,需明确确认
操作中/恢复待处理 可用 不开始同目标检查计划 禁用 禁用

检查更新产生 unchecked/checking/upgradable/current/blocked/unavailable 状态及 checkedAt。状态绑定当前来源、安装版本和目标指纹,安装记录变化就失效。用户点击升级时重新生成计划,不能直接执行旧徽标。

已安装详情展示当前本地版本,升级目标版本在计划区单独展示。版本 Tab 仍可只读查看历史,不增加“安装旧版/降级”入口。

3. 升级流程与多目标规则

flowchart TD
  A[点击检查更新] --> B[读取精确本地记录和匿名 resolve]
  B --> C{版本顺序与指纹}
  C -->|相同版本且相同内容| D[已是最新]
  C -->|远端更旧或顺序未知| E[阻断并保留本地]
  C -->|同版本不同内容| E
  C -->|远端更新| F[显示可升级版本]
  F --> G[用户点击升级并生成计划]
  G --> H{选定目标可信且独立可管理}
  H -->|否| I[阻断,不扩大到其他项目或 Agent]
  H -->|是| J[显示所选位置与旧新版本]
  J --> K{基线完整且无本地修改}
  K -->|否| E
  K -->|是| L[用户确认升级]
  L --> M[下载暂存与校验]
  M --> N[锁内重校验和提交]
  N --> O[报告结果并刷新已安装]

3.1 候选版本与比较

使用 Registry resolve 返回的最新可用版本,不自行从所有历史版本挑最大值。沿用 CLI compareSkillVersions:相同字符串为 same;合法 SemVer 才比较;无法比较返回 unknown,不按字符串排序。远端更旧、不可比较、同版本不同 fingerprint 都阻断。

已发现预发布版本是否可用由现有 Registry resolve 决定;插件不另造“稳定/测试通道”。计划绑定精确版本和 fingerprint;确认后该版本不可下载就失败,不换成另一个版本。

3.2 按安装位置独立版本

对话管理扩展将库存迁移为显式 v2,各 target 独立持有 version/fingerprint;来源坐标组不再有可用于执行判断的单一版本。迁移与兼容约束见 conversation-management-design.md,正式实现计划须覆盖 CLI、套件、同步和恢复。

  • 一次 DSH 更新只操作用户选定的目标。唯一匹配直接定位;多份且未指定目标时先选择。
  • 其他项目、Agent 或用户级副本保留原版本、文件、时间及归属,不因属于同一来源组而被连带更新。
  • 选定目标必须为可信路径、直接归属且通过内容基线校验;物理目录别名或共享所有权仍阻断。
  • 提交使用当前库存的比较与交换检查,不能用旧快照覆盖其他目标。并发冲突可要求重试,不得丢失其他目标修改。
  • 用户取消不下载、不写文件;模型不能代替用户确认。

3.3 升级确认内容

就地确认展示技能、所选范围和旧新版本,详情按需展开;不默认展示原始路径、来源 URL 或内部过期时间。对话优先原生输入框附近确认,缺少该能力时回退为不执行的确认卡。

4. 卸载流程与影响确认

卸载入口在已安装行和对应详情的次级操作区,点击先预检,再展示确认弹窗。焦点默认落在取消,确认按钮使用破坏性操作样式,弹窗展示来源、坐标、版本、主机、范围和只读目标路径。

文案:“仅删除此安装位置的技能文件及对应记录。不删除 SkillHub 远端技能,不影响其他安装位置。当前正在运行的任务不会被强制终止。”

flowchart TD
  A[点击某一行卸载] --> B[Host 按 itemKey 解析唯一目标]
  B --> C{记录和目录是否可信}
  C -->|未知来源或基线缺失或本地修改| D[阻断并给出原因]
  C -->|有共享 Suite 来源| D
  C -->|目录缺失且记录可信| E[确认清理这一条失效记录]
  C -->|正常| F[确认删除指定范围的技能]
  E --> G[锁内重新核验]
  F --> G
  G --> H{计划仍有效}
  H -->|否| I[返回需重新检查]
  H -->|是| J[隔离目录并提交清单变更]
  J --> K[清理隔离文件]
  K --> L[报告已卸载或残留与恢复信息]

不调用远端 DELETE。不同于升级,卸载可以只移除一个 target,其余 target 仍沿用原版本,不违反共享版本模型。无 baseline 或检测到本地修改时本期不提供“强制删除”,用户需在外部妥善处理后重新检查。

目录缺失只认明确 ENOENT;权限错误、I/O 错误、符号链接异常不能算“已经不存在”。 判断前须核验安装根仍是原真实目录;Windows 对普通文件下的子路径也可能返回 ENOENT,不能据此清理安装记录。执行提交及恢复时再次检查安装根和隔离根的目录类型。清理失效记录也是独立确认计划,不伪装成删除文件成功。

安装执行已失败且共享核心已退出清理流程时,若日志尚无事务记录,或仅有暂存 intent、无 preparation/移动/清单提交或恢复动作,Host 可在目标锁内验证暂存路径绑定及目录确实不存在,然后记录 failed/not-needed。此核验只更新操作状态,不删除文件、不回滚其他请求;暂存仍在、路径不可信、锁竞争或核验失败仍保留恢复要求。

5. 计划协议和并发约束

升级/卸载使用“prepare → 展示影响 → execute”,安装仍保持详情按钮直接开始。三个操作共用一个 MutationOperation 生命周期。

共享安装清单在获取文件锁前,复用目标锁的 acquisition gate 串行化过期锁回收;取得清单锁后释放 gate,清单读改写继续由文件锁保护。两个进程不能同时根据同一份过期状态删除锁,从而覆盖新持有者。清单锁获取使用 10 秒重试预算,既有轮询可能增加一次最多约 1 秒的等待,并叠加文件系统及事件循环耗时;该预算不是严格的时间截止,最后一次尝试若成功仍可返回。超时返回锁忙,仅清理自身排队记录,不删除仍存活的其他竞争者。此保证要求参与进程均采用该 gate;与未包含修复的旧 CLI 并发恢复过期锁时,不声明相同保证。清单格式、原锁路径及事务提交边界保持不变。

字段 定义
planId Host 生成的不可猜测引用;Client 不提交原始路径
kind upgrade / uninstall / remove-stale-record
sourceRevision 生成计划时的实例修订,地址切换导致未执行计划失效
identity Registry 规范化身份、namespace、slug
targets 精确规范化目标集合与范围,来自 Host,不接受客户端自由扩展
before 本地版本、fingerprint、metadata 快照、当前文件快照、target 所有权与完整 target set
after 升级精确版本/fingerprint;卸载为目标不再存在
expiresAt 拟定生成后 5 分钟到期;重新生成才可继续,不延长旧计划
status ready / unchanged / blocked,只有 ready 可执行
blockers 机器可判定的原因码及可展示说明

execute 只接 planId 和 requestKey。Host 对计划、调用上下文、expiry 和参数重放校验,锁内还要比较 before。确认弹窗显示路径用于告知影响;客户端仍不能把路径作为写操作参数。

requestKey 在页面入口由 Client 为一次明确提交生成并保留;在对话入口由可信工具适配层按 Host/会话/toolCallId 生成稳定映射(不由模型输入);同 key、同操作参数重复请求返回原 operationId,同 key 不同参数拒绝。不能因请求超时换 key 自动再执行。计划提交后不能重复用于另一操作。

stateDiagram-v2
  [*] --> Prepared
  Prepared --> Expired: 到期或来源项目变化
  Prepared --> Blocked: 不满足执行条件
  Prepared --> Accepted: 用户确认
  Accepted --> Staging
  Staging --> Revalidating
  Revalidating --> Failed: 目标变化
  Revalidating --> Committing
  Committing --> Completed
  Committing --> Recovering: 提交失败
  Recovering --> Failed: 已恢复
  Recovering --> RecoveryRequired: 恢复不完整
  Completed --> [*]
  Failed --> [*]

UI 离开页面不等于取消已接收操作;不提供提交阶段的取消按钮。插件正常禁用时停止接收新写操作,让已进入提交阶段的操作完成或按日志恢复;进程崩溃按第 7 节处理。

6. 升级的文件提交

sequenceDiagram
  participant C as Client
  participant H as Host
  participant R as Registry
  participant K as 安装核心
  participant I as Inventory
  C->>H: prepareUpgrade(itemKey)
  H->>I: 读取所选目标版本、基线与归属
  H->>R: 匿名 resolve 最新版本
  H-->>C: planId 与旧新版本、所选目标
  C->>H: executePlan(planId,requestKey)
  H->>H: 保存 accepted operation
  H->>K: 固定版本下载与 staging 校验
  K->>K: 按规范化目标排序获取目标锁
  K->>I: 重读并比较目标集合与基线
  K->>K: 原目录移备份,再提交新目录
  K->>I: 锁内 CAS 更新所选目标版本并保留其他目标
  alt 提交成功
    I-->>H: 已提交
    K->>K: 清理备份,失败则保留 warning
    H-->>C: upgraded 与独立发现状态
  else 提交前失败且确认清单未提交
    K->>K: 恢复原目录及可恢复记录
    H-->>C: failed / recoveryRequired 与实际恢复信息
  end

CLI upgrade 内部会调用 installSkill(force:true),这里 force 表示受保护的同来源替换,不代表用户可强制覆盖本地变化。本插件生成计划固定 allowTargetDrift:false、requireExistingTargets:true,并执行所有权和旧版本 CAS。不能仅把 force 改为 true 就认为实现了升级。

7. 卸载、日志与恢复

现有 removeLocalSkill 直接 rm 再 removeTarget,不能满足可恢复精确卸载。拟新增内部目标级卸载适配,或收敛现有核心后保留 CLI 旧入口;禁止调用其 Agent 级筛选后误删多个 DSH 目标。

sequenceDiagram
  participant H as Host
  participant J as 操作日志
  participant F as 技能目录
  participant Q as 同文件系统隔离目录
  participant I as Inventory
  H->>J: 写 accepted 与原记录摘要
  H->>F: 获取目标锁并核验来源、基线
  H->>J: 写即将移动的精确路径与阶段
  H->>Q: rename 原目录到隔离位置
  H->>I: CAS 删除这一个 target
  alt 清单提交成功或重读证明已提交
    H->>J: 写 committed
    H->>Q: 删除隔离内容
    H->>J: 写 completed 或 cleanupWarning
  else 重读证明清单未提交且原基线仍匹配
    H->>F: rename 隔离目录回原位置
    H->>J: 写 failed 或 recoveryRequired
  end

隔离目录须位于目标同文件系统且在 DSH 扫描范围外。拟议例子为 DSH 根下 .skillhub-trash/<operationId>,实际位置由可信目标适配器推导;不能放到其他盘或可被技能发现的子目录,EXDEV 不退化为无恢复保证的直接 rm。

操作日志保存在官方解析后的 DSH home 下:<DSH_HOME>/skillhub/operations/<operationId>.json,同目录 host.json 保存稳定主机身份。该位置与技能发现目录分离;Host 使用官方 home 解析及路径规范化函数,不接收 Client 路径。只记录操作阶段、绑定身份/目标、原 target 记录、版本/指纹摘要、备份/隔离路径;不存凭证、签名下载 URL 或技能正文。原子写入,文件权限沿用宿主受保护状态目录。不新增服务端数据库。

恢复按真实文件与 inventory 状态判断,不只看最后一条日志:

恢复观察 处理
未开始移动 标记失败,可重新预检
隔离目录存在、原目录不存在、清单仍有原 target 尝试恢复;若原路径已被别人占用则停止,标 recoveryRequired
隔离目录存在、清单已删除 target 逻辑卸载完成,报告清理残留,不把记录加回
原目录和隔离目录都存在,或版本/所有权不符 不覆盖、不猜测,报告人工恢复所需的精确位置
升级日志显示中间状态 按原版本、备份、新目录与 inventory 比对;只有确定可逆才恢复

Host 启动扫描到的未完成操作,在查询时将 accepted/staging/revalidating/committing/recovering 投影为 unknown,供用户核验并恢复;不据此修改持久日志或断言旧任务仍在运行。当前实例启动后创建的操作维持真实执行阶段,已完成或已恢复的原操作维持终态。其他进程仍持有执行锁时,恢复不得抢占;阶段投影不替代执行锁、目标归属与权限校验。进程强制退出后,尚未过期的锁租约也可能暂时拒绝恢复;此时保留原操作和未确认提示,不显示恢复成功、不自动重放写操作。租约过期后由用户再次明确发起核验恢复。

对当前合法日志中 accepted/staging 且完全没有 transaction 的安装请求,执行顺序保证技能内容变更尚未开始。显式恢复须持有执行租约和目标锁、重新验证原目标及可信祖先,然后将请求安全收尾为失败;目标根尚未创建也无需为收尾创建目录。已有事务意图、未知格式、异常阶段或正在执行的请求不能套用此规则。日志保留,用户需要重新明确提交才能开始新安装。

重启不自动重新下载/升级,也不重放删除。恢复检查在重新取得相同锁后进行;受影响目标处于 recoveryRequired 时拒绝新的写操作。成功且无残留的日志可按拟议 7 天保留期清理;恢复未完成/有残留的日志不自动过期。

7.1 不可混淆的提交边界

inventory CAS 成功是逻辑提交点,后续 committed 日志或清理失败不得恢复旧目录。 journal 是恢复证据,不比真实 inventory 和目标内容更权威。

失败窗口 文件动作 对外状态
移动前的计划/日志写失败 停止尚未开始的移动,清理安全暂存 failed,目标未变
目录已切换,但确定 CAS 尚未提交 在锁内恢复原文件;确认未破坏他人更新 failed/restored 或 recovery-required
CAS 抛异常但结果未知 保持现场,锁内重读 inventory 对比 before/after;不能立即恢复 unknown/recovering
CAS 已提交,写 committed 日志失败 保留已提交文件和清单,尽力保存告警;不回滚旧目录 completed+journalWarning;无法确认则待核验
CAS 已提交,清理备份/隔离失败 保留残留并告知精确位置 completed+cleanupWarning
重读既不匹配 before 也不匹配 after 停止自动恢复,不覆盖任何一方 recovery-required

恢复必须比较本次确认目标的版本、metadata、文件与清单,并保持其他位置不变。恢复日志在变更前已持久保存确定的 backup/staging 路径,因此 committed 日志失败仍可由 precommit 日志和真实状态核验;无可信日志时不猜测删除遗留目录。

flowchart TD
  E[事务异常] --> C{inventory 提交状态}
  C -->|确定未提交| R[锁内按原基线尝试恢复]
  C -->|确定已提交| W[保留新状态并报告告警]
  C -->|未知| Q[锁内重读清单与文件]
  Q -->|匹配 after| W
  Q -->|匹配 before 且可逆| R
  Q -->|均不匹配| M[保留现场并要求恢复处理]

8. 锁与共享来源

统一顺序为按 canonical lock key 排序的 target locks → inventory lock;CLI 和插件共用 orderSkillTargetLocks,不能各自实现不同排序。锁身份由规范化目标路径生成,路径别名及输入顺序不同也必须得到同一取锁顺序。禁止另一路先持 inventory lock 再等 target lock,避免死锁。取锁前 canonical 去重与冲突检查;由事务核心唯一负责取锁,插件外围不得再持同批锁调用旧 installSkill。网络下载在持目标锁之前进行,提交前重新验证;安装幂等的早期锁检查完成后释放,再下载。

Inventory 变更必须在 mutateAtomic 的最新快照里比较所选位置的旧身份、版本、指纹、时间、installedBy 及重叠路径认领,不能用预检读到的旧 inventory 覆盖他人更新。显式 v2 中每个 target 持有自己的版本、指纹和归属;旧格式仅经验证适配和受控迁移读取。

targetInstalledBy 非单一 direct 的目标视为共享来源,本期升级与卸载均阻断。缺失 installedBy 按现有 CLI 的 legacy direct 语义读取,但 metadata/文件基线缺失仍阻断。任何 canonical path 不同来源记录共享、符号链接逃逸或目录重定向均需停止变更。

9. 结果反馈与验收

结果包含 operationId、kind、受影响目标、旧新版本、files 状态、recovery 状态、warnings 与 discovery。卸载后只能承诺该目标移除;同名技能可能由项目/用户/其他 provider 继续提供,不能显示“DSH 中已彻底删除”。运行中的任务不强制终止,不能承诺撤销已加载内容。

验收至少覆盖:单目标升级;两个允许目标一起升级且确认完整;外部目标阻断;无新版本;版本不可比较;同版本变内容;本地修改;Suite 共享;下载/指纹失败;确认后变化;双击;响应丢失;目录移走后清单失败;清理隔离失败;重启恢复;精确单目标卸载;离线卸载;ENOENT 与 EACCES 区别。

10. 两入口的持久操作归属

操作日志同时持久化 OperationContext、requestKey 的调用归属和原始参数摘要,字段以接口分册第 10 节为准。Host 重启后先查已接受记录再验证新写 token;恢复原操作引用不受旧 token 内存记录消失影响,也不得开始第二次文件变更。缺日志、不同 Host 或参数冲突按 unknown/拒绝处理,不把自动重试当成新授权。

11. 幂等安装的发现核验

同版本已安装时不创建写事务,也不生成虚假的 inventory 提交。核心在目标和清单锁内验证现有安装,并随原操作原子保存只读基线 existingInstallation:versionId、fingerprint 与 inventoryDigest(相关清单内容的 SHA-256 摘要);操作本身保留原坐标、版本和目标。后续发现观察须在调用 DSH 前后重新核验原基线、归属、可信根与操作修订;内容或记录变化即保持未确认。旧操作没有该基线时不使用当前库存补写历史成功证据。此基线属于 Host 内部日志,不增加 Client Remote 字段,也不向 Client 暴露路径或内部清单。

定向升级补充

用户在详情选中精确版本时,先通过 checkVersionUpdate 核验升级方向,再通过 prepareVersionUpgrade 固定候选;最新版检查与计划仍使用原接口。固定候选不可用或版本不符时阻断,不回退 latest。用户确认的计划仅列出本次选定安装位置,执行使用该位置锁定基线与候选快照;合并库存时保留其他位置的最新状态。较旧与不可排序版本不允许覆盖安装;取消计划不写文件。

固定技能案例文件(待实施补充)

.skillhub/examples.json 为版本化作者内容;无论协议是否可识别,都保留原始字节并参与 manifest、指纹、升级/删除保护与恢复。只排除安装器内部 .skillhub/metadata.json,不能继续跳过整个目录。上传、安装器内部记录保护与普通作者文件处理统一见 案例实现设计,旧版消费者不透明兼容的事实和分阶段发布约束见该文 §6。当前共享核心仍待修改;此前通过的生命周期测试不代表新案例文件已受支持。