Skip to content

适配上游 dsh 0.1.2-alpha.1:dsh-client-runtime / APIProxy 移除,受影响包适配清单 #323

Closed

Description

@wingsky-1

背景

上游 deepseek-ai/deepseek-harness 发布了 dsh-v0.1.2-alpha.1(2026-08-27,pre-release,尚未发 npm,npm latest 仍为 0.1.1-rc.2)。该版本对客户端运行时做了两次架构级重构,直接影响本仓库多个插件的客户端(browser half)兼容性。本文基于 dsh-v0.1.1-rc.2 → dsh-v0.1.2-alpha.1 真实 diff 复核。

上游变更(与本仓库相关)

🔴 破坏性

  1. @deepseek-ai/dsh-client-runtime 包被删除(commit be531688f "migrate consumers and remove Runtime")
    • ClientContext / createScope / ConversationSnapshot / SessionRuntime 等符号不再存在。
    • 原消费者全部迁移:createScope 迁到 @deepseek-ai/dsh-api-session-controller/client(scope.ts,签名 (ctx, SessionId) → {ctx, fiber} 不变);store 迁到 @deepseek-ai/dsh-client-store;渲染/插槽迁到 @deepseek-ai/dsh-client-ui-renderer。
  2. @deepseek-ai/dsh-host-apiproxy 包被删除(commit e14d354e8 "remove ApiProxy package")
    • IApiClient / SessionsApi / session.models 等全部移除;传输层改为 Typert Remote 网关(ctx.remote)。
  3. ctx.connection.api 移除:ConnectionHandle 只剩 isLoopback / generation / rpc / start,不再有共享 API 客户端。
  4. ctx.workspaces.openPath 移除:宿主侧改为 ctx.remote.session.openWorkspacePath。
  5. session.models RPC 移除:改为 ctx.remote.session.modelCatalog()(Host 代际目录)+ selectModel + modelSelection 投影。

🟢 保留(本仓库依赖的契约不变)

  • cordis apply(ctx) / ctx.effect / inject 数组 / ctx.get
  • 插槽:settings.section、settings.plugin.item(keyed,需 id+key 双写,key 必须等于宿主 settings 命名空间)、shell.overlay(data-shell-overlay DOM 保留)、sidebar.footer.action、conversation.input.right
  • host:dsh-host-webserver(WebRoute/register/tapIndex)、dsh-settings(register/describe)、dsh-skill(registerProvider)、dsh-agent(Agent/ModelSelection/agent/created/agent/request)、dsh-tools(ToolDefinition/PreToolDecision)、dsh-session(requestHeader/origin/parentSession)
  • dsh.client.inject 引用已删包(如 dsh-client-runtime)被 client-modules 软忽略(graphRows.get 找不到即跳过),不会导致加载失败——但注入意图失效,应清理。

✨ 上游新增、可参考的能力

  • 官方子代理模型配置:@deepseek-ai/dsh-subagent 新增 model-selection-settings(settings 命名空间 subagent-model-selection,enabled + allowedModels),UI 侧 ui-settings-plugins 有 SubagentModelSelectionCard。dsh-subagent-model-inherit 可参考此命名空间/卡片范式,甚至考虑合并/替代。
  • Webhook 包:新增 @deepseek-ai/dsh-webhook / @deepseek-ai/dsh-webhook-github(fire-and-forget 规则运行时,创建 Workspace-backed 会话)。
  • API controllers 新面:dsh-api-settings-controller(settings.describe/update/replace/mutate + credentials)、dsh-api-workspace-controller(create/rename/delete/insertBefore/archiveSession + workspace 流)、dsh-api-session-controller(list/search/create/selectModel/modelCatalog/prompt/updateQueue/cancel/page/follow 等 Remote)。
  • ctx.remote.$on 事件订阅:llm/adapters-updated、settings/document-updated、credentials/reference-updated、api-session/* 等转发事件。
  • dsh-client-store:createSnapshotStore / defineStore 成为客户端 store 标准。
  • locale 第三方注册:ctx.locale.register(ns, {zh,en}) + LocaleNamespaceMap 声明合并(本仓库客户端已大量使用,保留)。

受影响包与适配方案

1. dsh-subagent-model-inherit(host-only)— ✅ 兼容,可选增强

  • 用面 dsh-agent(Agent/ModelSelection/agent/created/agent/request/ctx.agents)、dsh-llm(LlmCallConfig)、dsh-session(requestHeader/origin/parentSession)全部保留。
  • 动作:无需改。可选:对照官方 subagent-model-selection 能力评估是否合并。

2. dsh-verify-isolated(host-only)— ✅ 兼容

  • 用面 dsh-skill(SkillProvider/registerProvider)保留。
  • 动作:无需改。

3. dsh-notifier — ✅ 兼容

  • host 用 dsh-agent(Agent 类型)、dsh-session-title、dsh-user-approval、dsh-host-webserver 均保留;client 为零 import 纯 DOM + EventSource,inject: []。
  • 动作:无需改。

4. dsh-lan-proxy — ✅ 兼容(建议清理 + 实测)

  • host WebRoute/register/tapIndex 保留;client 用 settings.plugin.item(id+key 双写)保留。
  • 动作:
    1. 清理 dsh.client.inject 中 @deepseek-ai/dsh-client-runtime 死引用(软忽略但应移除)。
    2. 实测 LAN 链路:0.1.2 对网络访问启用一次性 Token 鉴权,且 webserver 原生支持 gzip 压缩;lan-proxy 独立端口 + 自签 TLS 的转发是否与官方鉴权/TLS 交互需验证。
    3. tapIndex 注入的 crypto.randomUUID polyfill 已非必需(官方改用 dsh-util-crypto),幂等无害,可留可删。

5. dsh-mcp-manager — ✅ 兼容(建议清理)

  • host dsh-settings.register/webServer.register、client settings.plugin.item(id+key 双写)、ctx.sessions.list 快照(current/byId/cwd)均保留;fetch /api/dsh-mcp/* + SSE 自管。
  • 动作:清理 dsh.client.inject 中 dsh-client-runtime 死引用。

6. dsh-provider-usage — 🟠 软破坏(需适配)

  • 破坏点:src/client/core.ts:212 connection?.api?.sessions?.models → 0.1.2 无 connection.api、无 session.models → provider 检测恒失败,胶囊回落"未识别/默认";类型层因自定义防御式 ConnectionHandleLike 编译能过,属运行时功能降级。
  • 适配:resolveProviderFromSession 改读 ctx.remote.session:
    • 当前选择:ctx.sessions 的 modelSelection 投影(lastUsed/next)或 ctx.remote.session.modelCatalog() 的 default;
    • 会话上溯(子代理 parentId)逻辑保留,模型读取面替换即可。
  • 其余(settings.section 用量 tab、sessions.list 快照)保留。

7. dsh-web-file-preview — 🟠 软破坏(需适配)

  • 破坏点:src/client/wrapper.ts:24 包装 ctx.get("workspaces").openPath → 0.1.2 IWorkspaces 无 openPath → 包装静默跳过,"所有打开路径动作进预览"降级;对话内文件链接点击预览(document 捕获 intercept.ts → /api/fwp/)不受影响。
  • 适配:openPath 收口改到 ctx.remote.session.openWorkspacePath({ path } → {opened}),或接受降级;并清理 dsh.client.inject 中 dsh-client-runtime 死引用。

8. dsh-idle-archive — 🟠 需自查

  • package.json dsh.client.inject 也含 @deepseek-ai/dsh-client-runtime(见 grep)。若 client 有运行时引用 dsh-client-runtime 符号则硬破坏,需自查 src/client import 面。

建议动作

  • 清理全部包 dsh.client.inject 中的 @deepseek-ai/dsh-client-runtime 死引用(lan-proxy / mcp-manager / web-file-preview / idle-archive)
  • dsh-provider-usage:provider 检测迁移到 ctx.remote.session(modelCatalog / modelSelection 投影)
  • dsh-web-file-preview:openPath 迁移到 ctx.remote.session.openWorkspacePath
  • dsh-lan-proxy:LAN 链路 + 一次性 Token 鉴权实测
  • 评估 dsh-subagent-model-inherit 与官方 subagent-model-selection 的关系(合并/共存)
  • 上游 0.1.2 正式发 npm 后统一 bump peer/devDependencies 并回归

注:上游 0.1.2 仍是 alpha 且未发 npm;本 issue 先记录适配清单,实际升级回归可在正式版发布后进行。

Activity

  1. wingsky-1 commented on Aug 29, 2026

    @wingsky-1
    OwnerAuthor

    建议适配完成后锁定支持的dsh版本

  2. pinned this issue on Aug 29, 2026
  3. liyangbing commented on Aug 30, 2026

    @liyangbing

    这份清单很适合作为生态迁移索引;建议把“✅ 兼容”和“🟠 软破坏”都落成可执行的 capability receipt,避免仅依据源码 grep 得出兼容结论。

    我会把每个包的验证拆成三项:

    • static surface:runtime import、type import、inject/external、exports/lockfile 是否仍指向已删除包;
    • runtime surface:在 alpha.1 clean profile 中实际读取 ctx.sessions、ctx.remote.session、openWorkspacePath 或 model projection,并记录 supported/denied/unavailable;
    • user surface:provider capsule、open-path action、settings card、LAN auth 等行为是否保持,且失败只影响自身插件而不阻断整个 loader。

    对 dsh-provider-usage 和 dsh-web-file-preview,建议不要把缺少 projection 或 Remote capability 默认为“默认 provider”或静默跳过;应显示明确的 unavailable/degraded 状态,并保留旧 rc.2 适配分支,直到 alpha.1 的实际响应 shape 和 session scope 有测试证据。LAN 项则把一次性 token、Origin/TLS、压缩和重连分别验收。

    最终验收最好使用 pnpm pack 生成的真实 tarball,在独立 DSH_HOME 中做 add/boot/remove/re-add,并保存宿主 commit、依赖图、bundle manifest、能力 receipt 和 rollback pointer。相关记录模板:plugin install recovery 与 version evidence。

  4. wingsky-1 commented on Aug 31, 2026

    @wingsky-1
    OwnerAuthor

    适配进展:0.2.0 分支 Phase 1.1 死引用清理完成(2026-08-31)

    适配工作已在独立分支 0.2.0(基点 main v0.1.14 收官版)推进,计划文档:docs/dsh-0.1.2-适配计划.md。

    已完成(commit 44b4474,已推送 0.2.0)

    • 6 包 dsh.client.inject 中 @deepseek-ai/dsh-client-runtime 死引用全部移除:
      dsh-lan-proxy / dsh-mcp-manager / dsh-web-file-preview / dsh-idle-archive / dsh-notifier / dsh-provider-usage
    • 全包 pnpm build 通过;6 包 smoke 测试全绿

    经验 / 对本文档的修正

    1. 清单需修正:本文建议动作写 lan-proxy / mcp-manager / web-file-preview / idle-archive 4 包清理死引用,且称 dsh-notifier "inject: []"。实测 notifier 与 provider-usage 的 inject 也含 dsh-client-runtime——实际 6 包,均已清理。后续以逐包核对 package.json 为准,不照抄清单。
    2. 各包 client 均无实际 import dsh-client-runtime 符号,属软忽略清理(与本文判断一致),无运行时行为变化。
    3. 契约门禁只断言 dsh.client ⇒ exports["./client"] 联动存在、不校验 inject 具体内容——清理不触发门禁。

    下一步

    Phase 1.2(dsh-provider-usage provider 检测迁移 ctx.remote.session)进行中,结论后续在本 issue 跟进。

  5. wingsky-1 commented on Aug 31, 2026

    @wingsky-1
    OwnerAuthor

    适配进展:Phase 1.2 完成——dsh-provider-usage provider 检测迁移(commit a0abb6b)

    已落地(对照 dsh-v0.1.2-alpha.2 源码逐项实证)

    • resolveProviderFromSession 重写:modelSelection 投影优先 + modelCatalog 兜底
      • 主判据:沿 parentId 上溯链逐会话读 ctx.sessions.list 快照行的 projections.values.modelSelection(lastUsed 优先、next 次之)——per-session 投影天然保留原「按会话查询」语义,无需任何 Remote 调用
      • 兜底:全链投影缺失时读 ctx.remote.session.modelCatalog() 的 default(RemoteResult 解包)
    • 依赖面:connection(connection.api.sessions.models)体面废弃 → ctx.get("remote")(api-gateway apply 注入)
    • 单测/worker 全部迁移到投影 fake;currentProvideInfo 分支移除(上游 0.1.2 已删除该服务)
    • 构建 + unit-detect(10 组投影断言)+ worker(场景 1-5)+ smoke 全绿

    经验(对比评审 P0-1/P0-2)

    1. 投影比预期更优:评审以为 modelSelection 投影与 modelCatalog 是「两种数据面、需适配」;实测 alpha.2 的 per-session modelSelection 就在 sessions.list 快照行里(SessionSummary.projections.values.modelSelection),主判据零 RPC、上溯语义天然保留——modelCatalog 仅兜底,性能面符合评审 P1「投影优先」。
    2. 评审关键纠偏全部证实:default 属 ModelCatalog 非投影(types.ts:140-146);modelCatalog() 返回 RemoteResult 需解包(typert/protocol/src/types.ts:74-76);ctx.remote 依赖 dsh-api-gateway/client。这三条若不实证照原方案「只换函数名」会直接编译错/运行时降级。
    3. 客户端 inject 保持干净模块([]),ctx.get("remote") 防御式获取即可——无需为取 remote 改 inject(评审 P0-2 的「补 inject」在本包实测不必要)。

    下一步

    Phase 1.3(dsh-web-file-preview openPath → openWorkspacePath + canOpenWorkspacePath 降级)进行中。

  6. wingsky-1 commented on Aug 31, 2026

    @wingsky-1
    OwnerAuthor

    适配进展:Phase 1.3 完成——dsh-web-file-preview openPath 收口迁移(commit 536cefa)

    已落地(对照 dsh-v0.1.2-alpha.2 源码实证)

    • wrapper.ts 收口目标从 ctx.get("workspaces").openPath(0.1.2 已删除)迁移到 ctx.remote.session.openWorkspacePath({path})(Remote 网关)
      • 命中预览分组 → openPreview 后返回 {ok:true, value:{opened:false}}(不触底原生打开)
      • 未命中 → 放行原方法(RemoteError/signal 错误面原样透传,由上游调用方处理——实测上游 ui-chat openFile 检查 result.ok)
    • smoke 补充契约锁定断言:client 产物必须含 openWorkspacePath + get("remote")、不得再有 ws.openPath
    • 构建 + smoke 全绿

    经验(对比评审 P0-4)

    1. 错误面透传优于本地解包:评审要求「处理 RemoteError/signal」——实测上游调用方(ui-chat apply.ts:120-126)已在消费 result.ok/error,客户端包装只需放行原方法,错误语义由调用方统一处理,不必在本包重复解包(避免双份错误处理)。
    2. canOpenWorkspacePath 是宿主能力探测、客户端拦截不需要:实测它是 Host 侧方法(types.d.ts:326-335,报告「能否原生打开」),对话 openFile 调用前不探测直接调 openWorkspacePath——web-file-preview 拦截 openWorkspacePath 本身即可,无需重复探测。
    3. 契约哨兵断言对「迁移类」改动价值高:ws.openPath 禁出现 + openWorkspacePath 必出现,可防未来回退。

    下一步

    Phase 1.5(lan-proxy 一次性 Token 鉴权实测)与 1.6(subagent-model-inherit 对照评估)。

  7. wingsky-1 commented on Aug 31, 2026

    @wingsky-1
    OwnerAuthor

    适配进展:Phase 1.6 评估完成——官方 alpha.2 已原生吸收 dsh-subagent-model-inherit 核心能力(commit e08d287)

    结论(对照 dsh-v0.1.2-alpha.2 源码实证)

    本包在 0.2.0 线维持现状即可(不升级、不转聚合),标记「被上游 0.1.2 吸收」。

    实证

    1. [feature] [dsh-subagent-model-inherit] 新插件:子 Agent 自动继承父会话模型与思考等级 #153 两处断裂点 alpha.2 已原生修复:
      • AgentOptions 已含 reasoningEffort(core/agent/src/runtime-types.ts:31)
      • 官方 parentAgentOptionsForDelegation + resolveChildAgentOptions(subagent/src/child-agent.ts:68-119)子创建即继承父 provider/model/reasoningEffort/maxTokens,真实接入 continuation.ts:421 与 subagent-in-process-driver/index.ts:137
      • 官方 installModelSelection(core/agent/src/model-selection.ts)与本插件 injectSelection 的 waterfall 语义同构
    2. 官方 subagent-model-selection(model-selection-settings.ts,enabled+allowedModels 白名单、默认关)是独立新能力(受限模型路由控制),与本包「继承父模型」目标不同——无需合并
    3. 本包 host 面(dsh-agent/dsh-llm/dsh-session)均保留 → 0.1.2 兼容、无需改码

    决策

    • 本包 README 已声明 standalone 观察期、不进聚合包 → 维持该策略
    • 0.2.0 线不升级能力、不转聚合;README 将增补「alpha.2 起官方已原生支持,本包为 0.1.x 线兼容保留」

    下一步

    Phase 4(catalog 全量 bump 到 0.1.2-alpha.2 + 全量门禁)——适配收口,即将执行。

  8. wingsky-1 commented on Aug 31, 2026

    @wingsky-1
    OwnerAuthor

    适配进展:Phase 4 完成——catalog 全量 bump 到 0.1.2-alpha.2,全门禁通过(commit 769a7a2)

    已落地

    • S1 框架稳定性核对(npm pack lib diff 实证):cordis 4.0.1→4.0.2 lib 字节一致零破坏;schemastery 3.18.0→3.18.2 lib 字节一致
    • catalog 全量 bump:@deepseek-ai/cordis 4.0.2 + 9 个类型层包 0.1.2-alpha.2;minimumReleaseAgeExclude 同步(pnpm 自动补 8 条)
    • 全量门禁(alpha.2 类型层):pnpm build 10 包全过、pnpm test 全绿、pnpm contract 客户端契约 6 包全过、pnpm pack:check 全过

    经验

    1. S1 框架核对用 lib diff 而非版本号:cordis/schemastery 虽升 minor/patch,但 lib 字节一致 → 零破坏(印证 dsh-upgrade 方法论「版本号全量升 ≠ 破坏性,编译 lib 比对才是权威」)。
    2. scoped 包与裸包混淆坑:@deepseek-ai/schemastery(官方 scoped,3.18.2)≠ 裸 schemastery(npm 最新 3.18.0)——本仓库依赖裸包,bump 时不能照抄官方依赖面,须区分。已回退。

    0.2.0 分支适配进度(累计)

    Phase 状态
    0 分支基建 ✅
    1.1 死引用清理(6 包) ✅
    1.2 provider-usage 投影迁移 ✅
    1.3 web-file-preview openPath 迁移 ✅
    1.4 idle-archive 自查 ✅
    1.6 subagent-model-inherit 评估(官方已吸收) ✅
    4 catalog bump alpha.2 + 全门禁 ✅
    1.5 lan-proxy 实测 / 3 i18n / 2 通知中心 ⏳ 待维护者验证 / approved / 暂缓

    剩余:1.5 lan-proxy 需隔离浏览器实测、Phase 3 i18n 需 approved、Phase 5 发版待维护者全量验证。

  9. unpinned this issue on Aug 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions