skillhub/openspec/changes/add-dsh-native-plugin/design.md
XiaoSeS c4c3d5b63c
feat(dsh): refine skill lifecycle and release 0.3.0 (#986)
Refine marketplace actions, scoped installation, native questions, progress, removal and exact-version upgrades; align downloadable version pagination and OpenSpec.\n\nSigned-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
2026-10-20 15:18:23 +08:00

16 KiB
Raw Permalink Blame History

SkillHub DSH 插件:详细方案与架构设计

本文定义广场管理与对话搜索安装的总体架构。 产品与需求见 product-design.md,精确契约见 interface-design.md,开发拆分见 implementation-design.md,验收以 specs 为准,任务见 tasks.md。

Context

本期提供匿名浏览、详情、安装、已安装管理、升级卸载,以及对话搜索和安装。

SkillHub 仍负责技能发布、版本和服务端规则;本插件只提供 DSH 内的匿名消费入口。DSH 负责工作区、会话、模型和运行策略,插件不复制这些产品能力。

Goals / Non-Goals

目标:从技能广场或原 DSH 对话发现技能 → 看详情或明确提出安装请求 → 安装到 DSH Host → 查看真实结果;广场继续提供已安装、升级与卸载。 不建设登录、账号、权限管理、私有技能访问或 DSH 插件市场。已安装 Tab 支持检查更新、受保护升级与精确卸载;详情支持可配置的版本、安全审核、评论模块。 不主动修改 SkillHub 服务端访问规则,不建立额外审批;现有拒绝按错误处理。

Decisions

1. 一个宿主入口、目录与详情子页面

保留 DSH 品牌、工作区/会话树及设置。SkillHub 通过已核对的 sidebar.panellist 和同 id 的 main 进入主内容区。广场提供“浏览技能 / 已安装”Tab;卡片打开独立详情子页面,左上角返回原列表。详情有详情/版本/安全审核/评论 Tab,后面三项按实例配置与匿名能力决定。无插件双市场,无账号/权限页面。 需要修改来源地址或可选 Tab 时提供最小配置表单,可挂载于宿主 plugins.bundle.config;不建设连接测试中心与登录页。 上述扩展点来自已核对的官方源码基线,运行版兼容仍须 M0 实测。

2. 匿名访问单一实例

从 0.2.1 起,Host 配置 Schema 在缺少 registryUrl 时使用 https://skill.xfyun.cn;显式空串或仅空白仍断开,已有自定义来源保留。初始化和读取配置本身不访问网络;Client 不另设回退来源。

Host 对指定 SkillHub 发起无 Token、无 Cookie 的请求;不读取或复用 CLI 凭证。不做 Device Flow、API Token、账号状态或凭证持久化。 地址变化取消旧查询、使旧安装计划失效,旧响应不得进入新实例的列表。网络失败保留查询并提供重试。 匿名可见不等于匿名可下载;安装前重新 resolve。需要身份或被拒绝时提示“此来源或技能暂不支持匿名访问”,当前版本不提供登录补救入口。

3. 现有代码依据与接口缺口

已核对来源 已存在的能力 实施注意
cli/src/clients/skillhub-client.ts search 的 q/limit、坐标/版本/摘要;resolve、下载 无完整分页、标签与浏览卡片所需的全部字段
server/.../controller/cli/CliSkillController.java q 可省略、搜索/解析/下载端点 空 q 返回及匿名下载仍须实测
server/.../controller/portal/SkillSearchController.java Web 搜索支持命名空间、标签、分页、排序 已核对 /api/web/skills 的匿名读取策略;使用发布版本和公开统计,SaaS 部署仍须单独验证
web/src/shared/hooks/use-skill-queries.ts 详情、版本、资源读取 网站会话请求不直接复制到插件
web/src/features/skill/skill-card.tsx 命名空间、说明、版本、统计展示 插件只显示实际接口提供且有含义的字段

首版必需字段为完整坐标、说明、可安装版本;名称缺失时以 slug 呈现。详情只展示可匿名读取的信息;卡片可展示服务端提供的下载量、收藏数、评分,并按服务端支持的维度排序。不提供评分写操作、独立榜单或无真实契约的分类。 广场使用匿名目录接口每页 12 项,点击“加载更多”读取下一页,保留查询、排序与详情返回位置。若首批目录路由返回 404/405,回退旧 CLI 首批搜索并明确范围限制;其余错误正常呈现,不伪造全量目录或无限滚动。

展示层使用 shadcn/ui Radix 组件源码与插件独有 CSS 前缀,映射 DSH 主题变量;React/React DOM 保留宿主 external,不向宿主注入全局 reset。界面改造复用既有 Host 生命周期协议。

4. 同仓库独立包与内部复用

plugins/dsh/
  package.json
  cordis.patch.yml
  src/host/     # 来源、查询、可信目标、安装适配
  src/client/   # 广场、详情、安装结果
  src/shared/   # 非敏感交互契约
  test/
  README.md

增加 cli/src/integrations/ 的最小内部消费入口,构建进插件,不导入 CLI main、不调用 PATH CLI、不新发 SDK 包。Host 与 Client 产物及 bundle patch 一起发布;独立构建不依赖用户仓库。 复用 install-service.ts、archive/download、installed-skill-metadata、inventory-store、skill-target-lock。不需要 AuthService;升级可复用 upgrade-service 的计划/执行分层,卸载需补精确 target 的受保护入口,不直接沿用 removeLocalSkill 的 Agent 级选择。

5. 安装目标与边界

默认用户级,使用 Host 解析的 DSH 用户根;可选项目级只接受宿主真实项目根。无项目时不能猜测路径。远程场景文件落在远程 Host。 操作绑定 Registry、坐标、精确版本、可信目标及相关会话上下文;需要宿主策略时沿用其真实机制,不绕过、不新增权限管理 UI。 下载完整包,暂存检查路径/数量/大小/指纹,以及目标版本 DSH 的名称和 invocation 格式;不兼容时拒绝提交,不改写原包。安装不执行包内脚本。 同一目标/来源/版本已安装则返回已安装;首次安装遇到不同来源、本地修改或其他版本占用时阻断;可信已有安装使用独立升级计划。多目标共享版本保留,只有全部目标都在管理范围且用户确认完整集合时一起升级;其他情况阻断。

6. 提交与发现分别报告

复用 CLI 同一目标锁,提交前重新校验。文件与 inventory 写入失败时尝试既有恢复,报告实际结果,不能把未确认状态伪装成回滚成功。 安装后按真实宿主接口观察发现结果。显示“已安装”和“当前会话已发现/待确认/发现失败”两个独立事实,不自动重启或执行技能。 本期观察所安装技能,并以本地 metadata/inventory 提供当前来源、用户与当前项目范围的列表及明确升级/卸载;不实现全量多来源管理或自动目录修复。禁用连接插件不删除已安装技能。

Architecture

flowchart LR
    W[SkillHub 网站:发布与治理] --> R[SkillHub Registry]
    U[用户] --> P[DSH 内技能广场]
    U --> C[DSH 原对话:工具与卡片]
    C --> H[插件 Host]
    P --> H
    H -->|匿名查询/解析/下载| R
    H --> I[复用 CLI 安装核心]
    I --> F[Host 技能目录与安装记录]
    F --> D[DSH 发现与后续任务使用]

Risks / Trade-offs

  • 实例如果完全禁止匿名访问,本版无法使用;该限制明确展示,不能私自放开后端。
  • 目录格式合法不等于 DSH 可加载,兼容检查与发现观察不可省略。
  • 升级/卸载通过精确不可变计划执行;本地修改、共享所有权、未知身份和计划陈旧时拒绝,不能变成强制覆盖。
  • 默认安装版本、详情内容与排序必须来自实际接口,不能将“公开”当作固定保证。
  • 首版仍面向 Linux/macOS/Windows DSH Web;桌面截图仅作视觉参考,不承诺桌面专项适配。

Verification / Rollout

M0 验证 DSH 版本、页面挂载、匿名接口及隔离临时目录中的技能发现探针,不调用尚未完成的插件安装事务。M2 完成受保护写操作后,M4 通过插件在测试目录安装并使用至少一个带资源技能,完成 CLI 回归、干净 tarball 和平台验收。

References

宿主源码与素材依据继续使用 DSH 接入设计。原生入口和构建要求均需固定实际版本;发行兼容性通过集成验收确认。

Detailed Architecture

A. 系统组成与责任

flowchart TB
  subgraph DSH[DSH Host 与 Web Client]
    subgraph Client[插件 Client]
      NAV[宿主侧栏 SkillHub 入口]
      CAT[浏览与已安装页面]
      DETAIL[详情子页面及可选 Tab]
      CONFIG[原生插件配置]
      CHAT[对话搜索卡片与安装结果]
      DRAWER[共享详情内容的抽屉容器]
    end
    subgraph Host[插件 Host]
      RPC[跨端服务契约]
      TOOLS[搜索与安装工具适配器]
      READ[匿名 Registry 适配]
      LOCAL[本地安装投影]
      INSTALL[安装升级卸载协调与操作状态]
      ADAPTER[DSH 上下文与发现适配]
    end
    CORE[复用 CLI 安装核心]
    STORE[技能目录 metadata inventory 锁和恢复日志]
    ENGINE[DSH 技能发现和执行]
  end
  NAV --> CAT
  CHAT --> DRAWER
  DRAWER --> RPC
  CHAT --> RPC
  AGENT[DSH Agent] --> TOOLS
  TOOLS --> READ
  TOOLS --> INSTALL
  CAT --> DETAIL
  CAT --> RPC
  DETAIL --> RPC
  CONFIG --> RPC
  RPC --> READ
  RPC --> LOCAL
  RPC --> INSTALL
  INSTALL --> ADAPTER
  INSTALL --> CORE
  CORE --> STORE
  LOCAL --> STORE
  STORE --> ENGINE
  READ --> REG[SkillHub Registry REST API]
  CORE --> REG

浏览器只传技能身份和 Host 发出的不透明目标引用。读取、下载、文件写入都在 Host,避免浏览器跨域和本地/远程路径混淆。无需在 SkillHub 服务端增加安装任务队列;安装是 DSH 主机本地行为。

B. 数据存放与生命周期

数据 权威位置 生命周期
技能、版本、评论、审核 SkillHub Registry 原服务维护,本插件只读
Registry 与 Tab 开关 宿主插件配置 按 DSH 配置机制保存
搜索词、选中 Tab、返回位置 Client 面板状态 Client 生命周期,刷新后可重载
detailToken、targetToken、selectionRef Host 内存 绑定来源/项目/会话,重启清空;已接受操作查持久记录,不重放失效引用
对话结果快照 DSH 对话持久化内容 保存工具返回的 accepted/context/操作引用;完成结果查询 Host 日志,重开须核验
Mutation operation Host 内存与本地原子 JSON 日志 支持同 key 恢复和崩溃核验,未解决恢复状态不自动过期;不建任务数据库
已安装文件与 metadata 实际 DSH 目标目录 安装后保留,不随插件禁用删除
inventory 和锁 现有 CLI 约定 与 CLI 共用,不能另起不互斥锁

不缓存完整远端技能库。可选 Tab 的缓存与能力判断绑定当前实例,报告绑定 versionId、评论绑定 skillId。安装版本冻结,网页刷新或发布新版本不得改变已有操作目标。

C. 版本、安全审核与评论边界

版本列表可显式选择可下载版本并重新获取精确详情凭据;升级仍走已安装目标计划,既有目标不被直接覆盖,不加入降级或批量跨技能同步。当前安全审核服务拒绝匿名用户,因而首版当前实例的 auto 模式隐藏审核 Tab;不能通过 Host 代填管理员凭证。评论只读公开投影,不提供发表或管理功能。

展示开关是 UI 产品配置,不授予数据访问权。show 可显示不可访问原因,hide 不请求模块;网络失败不能冒充模块不存在。完整配置优先级与错误语义在 interface-design.md 中唯一维护。

D. 技术事实与待实现接缝

事项 当前事实 尚需实施/验证
DSH 主面板 官方固定提交 ui-layout 说明 main keyed slot 和 selectPanel 实际选定 npm 发行版的打包与注册
CLI 查询 当前 client/controller 已有搜索、resolve、下载 无认证调用的测试 Registry 验收
详情/版本/评论 当前 portal controllers 有 /api/v1 读取端点 实例开放状态、响应解析与匿名策略
安全审核 当前 canViewAudit(null) 为 false 仅可选只读 UI;公开摘要另议
本地已安装 metadata/inventory helper 已有 有界本地投影与部分失败状态
安装核心 已有暂存、fingerprint、锁、记录和恢复 DSH 格式验证、幂等检查和结构化错误适配

E. 取舍与替代方案

采用同仓库独立包:CLI 安装核心可在同一提交下调整和回归,DSH 只安装构建产物,与仓库是否独立无关。包名未核实前不写可复制的发布安装命令。

不嵌入网站 iframe:网站身份与导航不适合本期匿名宿主体验,也不能直接完成 Host 安装。不开远端 provider 挂载全库:只把用户选定的包安装到 Host,便于明确版本、资源和冲突。

不新增详情聚合 REST API:先用已有 /api/v1 和 /api/cli/v1,由 Host 归一化;如果 M0 发现目标 SaaS 缺口,记录最小增量而非重新设计整个平台。

F. 关键风险与处理

  1. DSH 官方仍处于快速迭代,设计固定源码提交仅提供接口依据,发行兼容必须实测。
  2. 已安装记录可能残留或仅部分可读,页面必须报告异常/不完整;不做自动修复。
  3. 匿名请求受实例策略限制,可选模块降级不得影响基本浏览;主技能不可访问则禁用安装。
  4. 包格式兼容不保证模型会调用;文件、发现、加载、执行分开验收。
  5. 同名不同 namespace 最终可能占用同一 slug 目录;检查实际目标,不靠坐标不同忽略文件冲突。
  6. 远程 Host 的路径、DNS、下载可达性与浏览器不同,错误反馈指向实际 Host。

Source Index

相关实现文件:

Lifecycle and Native Integration

受保护升级、精确卸载、多目标 shared version、Suite 所有权、计划失效、锁顺序、隔离提交和崩溃恢复均以 lifecycle-design.md 为唯一细则。产品操作不调用 SkillHub 服务端删除接口。

具体 Bundle/Remote/Client/Slot/配置层次和 disposer 约定见 dsh-integration-design.md。采用官方 Typert Remote,第三方产物挂载仍是 M0 必验条件。

补充实际代码依据:升级计划与执行、版本比较、现有卸载服务、共享 inventory。

对话入口与共享架构

对话搜索与安装纳入首期。Host 工具适配器和 Client 广场 Remote 适配器调用相同应用服务:Registry API 获取内容,内置 CLI 核心写入文件;不执行 PATH CLI。Client 共用 DetailContent,分别装入广场子页面与对话抽屉。安装操作归属、锁、日志与幂等不因入口改变;详见 对话设计。

版本目录的开源接口增量

排序、可安装状态过滤和分页总数由开源后端统一计算;DSH 每页请求一次 downloadableOnly=true,不全量拉取或逐项 resolve 探测。固定版本安装仍经既有目标、指纹与包校验,管理者缺省历史行为保留。完整参数和排序契约见 Registry API;SaaS 同步单独验收。