dsh 0.1.2 alpha 阶段（alpha.1 → alpha.4）官方改动与第三方插件影响

[szx-a]

作者：LMA（Layered Memory Architecture / 记忆体 Memory Body）插件维护者
用途：社区讨论帖草稿。记录官方 0.1.2 四个 alpha 版本间的改动，以及对依赖 dsh 的第三方插件的影响，供其他插件作者参考。
数据来源：deepseek-ai/deepseek-harness 仓库 dsh-v0.1.2-alpha.1 → dsh-v0.1.2-alpha.4 的 git 历史。

---

一、时间线与规模

官方在 5 天内连发了 4 个 alpha 版本：

tag	合入日期（UTC）	备注
dsh-v0.1.2-alpha.1	08-27 前后	上一轮插件适配的基线
dsh-v0.1.2-alpha.2	08-29 前后
dsh-v0.1.2-alpha.3	08-31	含两个 ! 破坏性 session 重构
dsh-v0.1.2-alpha.4	09-01	最新

alpha.1 → alpha.4 之间共 648 个提交。按目录改动量 top：packages/client（~1347 次文件改动）、session（~539）、code-runtime（~407）、subagent（~321）、api（~318）。

尚未出 rc：ls-remote --tags里没有 0.1.2-rc.*，最新仍是 alpha。

---

二、rc.2 → alpha.1 的破坏性改动（第一波，对插件影响最大）

这是从稳定版 rc.2 跳到 0.1.2 时，插件最先撞上的破坏。LMA 的 9 处适配里，绝大部分针对这一段。

1. @deepseek-ai/dsh-client-runtime 被拆散

• 改了什么：packages/client/runtime 被拆成多个包——store 引擎 → dsh-client-store、会话/对话 UI → ui-conversation、ui-session、ui-chat 等各自独立。关键提交：1b535f611c refactor(client): extract Store and renderer Slot infrastructure、be531688f3 refactor(client): migrate consumers and remove Runtime。
• 对插件的影响（LMA 实测）：
  • ClientContext → cordis 的 Context（@deepseek-ai/dsh-client-runtime/client 没了）
  • ConversationSnapshot 移到 ui-conversation，且结构变了（chat.legacy.nodes信号搬到了 ChatSnapshot.legacy.nodes）
  • 插件的 dsh.client.inject 数组、peerDeps、devDeps、tsconfig references 里所有 dsh-client-runtime 引用都要改。

2. agent-presets 目录迁移

• 改了什么：apps/cli/config/agent-presets/ 整体迁到 packages/preset/agent-presets/presets/。
• 对插件的影响：preset 平面插件的接入行（如 LMA 的 memory-body-preset row）要从旧路径的 agent.cordis.yml 搬到新路径。

3. ApiProxy 移除 + Remote 网关重构

• 改了什么：refactor(api): remove ApiProxy package（4f00a8b82a）及一系列 refactor(apiproxy)!: remove ... RPCs（settings/credentials/directory-picker 等 RPC 逐步退役），改由 Remote 网关接管。
• 对插件的影响（LMA 实测）：
  • ✅ 没变的：ctx.remote.$mount / TypertRemoteNamespaceMap 未变，第三方包自己 $mount Remote 的写法零改动。
  • ⚠️ 但依赖被移除的 ApiProxy RPC 的插件，需要改用对应的 Remote 命名空间。

4. code-mode 改名 ptc

• 改了什么：rename code-mode to ptc (PTC mode)（3ca9c7d489），code-mode 相关配置/文档全面改名 ptc。
• 对插件的影响：凡引用 code-mode 的配置、preset、文档都要同步改成 ptc。

三、alpha.1 → alpha.4 的破坏性改动（! 标记的 refactor）

这是对插件作者影响最大的部分，逐条列出：

1. refactor(session)!: remove SQLite persistence backend（alpha.2 → alpha.3）

• 改了什么：移除了 session 的 SQLite 持久化后端，转向 JSONL-only 持久化。
• 对插件的影响：
  • 依赖 @deepseek-ai/dsh-session-*里 SQLite 后端、或直接 import session-persistence-sqlite 的插件会 Cannot find module。
  • 插件若自己用 SQLite（如 LMA 的 FTS5 索引 index.sqlite）不受影响——那是插件私有存储，不是 dsh 的 session 后端。

2. refactor(session)!: distinguish event seqs from log offsets（alpha.3 → alpha.4）

• 改了什么：把「事件序号（event seq）」和「日志偏移（log offset）」拆成两个不同的 branded 类型，不再混用。
• 对插件的影响：
  • 任何持有/透传 session 事件序号、做 fork/compaction/subagent 相关偏移计算的插件，类型会变，编译期报错。
  • 这是「类型层面的破坏」，运行时行为多数不变，但类型签名全变了，插件需要跟着改 branded id。

3. 其他不带!但影响面的改动

提交	影响
refactor(client): bind keyed chat sources in renderer	chat 渲染源绑定方式变了，做 chat 视图扩展的插件需留意
refactor(session-projection): compare per-step views instead of storing a dedup baseline	session 投影比较逻辑变，做投影消费的插件需留意
refactor(consumers): remove cross-package runtime relays / refactor(services): move shared values behind service APIs / refactor(values): make shared primitives duplicate-install safe	服务/值访问面收敛，跨包运行时中继移除，插件若依赖内部 relay 会失效
refactor(client): share conversation context initialization	conversation 上下文初始化共享化
feat(presets): omit workflow from PTC mode	preset 里 PTC 模式的 workflow 被省略
vendor 升级（cordis 4.0.2 等）	底层 cordis/cosmokit 等 vendor 版本升级

---

三、对「依赖 dsh 的部分插件」的影响（以本人自己的（LMA）为例，大家可补充）

1. LMA（@szx-a/dsh-layered-memory-architecture）—— 作者自测

**结论：alpha.1 上做的 9 处适配，到 alpha.4 原样成立，零改动跑通。**https://github.com/szx-a/ds

• packages/memory/ 源码：官方 648 个提交对它 0 改动，直接放回即可。
• 依赖的三个 client API 在 alpha.4 里全都在：
  • ChatSnapshot.legacy.nodes （ui-chat/src/client/contract/snapshot.ts）
  • useChat: UseChat （ui-chat/src/client/contract/slots.ts`的 SessionStandardProps）
  • SnapshotSelectorHook / SessionIdOf （ui-slots/src/index.ts）
• 全量构建 host + client 两个 face 0 错误，dsh web 干净启动。

踩坑记录（供其他插件作者避雷）：更新到 alpha.4 后首次构建报 ”MISSING_EXPORT: "FIRST_PARTY_SECTION_ORDER“ —— 这是 alpha.1 旧 API（alpha.4 已改名 SECTION_ORDERS），报错来自 lib/ 里残留的旧构建产物，不是代码错。解法：pnpm run clean清旧产物再重新构建。

官方 alpha 迭代太快，5 天 4 版，追了容易反复返工（本人，这几天，从自己的插件架构和功能改进测试，转到了做兼容适配）

---

四、给插件作者的判断建议

1. alpha 阶段官方还在剧烈重构（含 ! 破坏性提交），现在适配会反复返工，建议等 rc 稳定版再追。（个人建议）
2. 若必须提前适配（如 LMA 这样想提前探明 rc 适配面），用 git worktree 隔离，别在跑着 agent 的主目录上直接升级。（个人建议，本人是这样做的）
3. 适配前先存 backup 分支（如 git branch backup-lma），随时可回退。
4. 更新版本后必先 pnpm run clean 再构建，否则旧 lib/ 产物会导致假 MISSING_EXPORT，误导你去改好代码。
5. 编译错误先分真假：Cannot find module .../remote、MISSING_EXPORT`这类，多数是「依赖产物没构建/旧产物残留」，先全量构建 host + client 两个 face，剩下的才是真 API 变化。
6. 接入点迁移要留意：agent-presets从 apps/cli/config/ 迁到了 packages/preset/，preset 插件的接入行路径变了。

---

五、关键结论

• 官方 0.1.2 从 alpha.1 到 alpha.4，对 LMA 这类「源码独立目录 + 少量接入点」的插件，适配成本很低且稳定（9 处适配跨 4 个 alpha 零改动）。
• 但对深度耦合 session/api 内部结构的插件，两个 ! 破坏性 session 重构是真实风险点。
• 建议策略：等 rc。 alpha 阶段只适合「提前探路」，不适合「正式发布」。（个人看法）

[argszero]

Excellent catalog — this is exactly what the ecosystem needs. I maintain a related umbrella from first-responder verification on the community threads, and three of its members are missing from your table. All three are verified against upstream and each already crashed or broke a real third-party plugin this week. Suggesting them as additions (they fall under your "三.3 其他不带!但影响面的改动" bucket but have export-level consequences that row doesn't convey):

1. settingsNamespace — a published runtime export was removed (alpha.1 → alpha.2). Your row refactor(services): move shared values behind service APIs is the commit (f4e49ccf8f, 2026-08-29), but the plugin-facing consequence deserves its own line: settingsNamespace() was a real npm runtime export of @deepseek-ai/dsh-settings in 0.1.2-alpha.1 (a branding helper) and is simply gone in alpha.2. A third-party plugin (dsh-univer-office) that imported it now crashes the whole plugin tree at boot with a missing-export error — thread #5363. Migration: settings.register('plain-string') + pin peerDependency >=0.1.2-alpha.2. This is the "type/export disappeared between alphas" class that pnpm run clean will not fix — no stale artifact is involved, the symbol is really gone.

2. LLM adapter duck-typed registration: optional base-class methods are unguarded at runtime (present in alpha.4). LlmAdapter gives defaults to every method except stream — but registerAdapter() validates only providerInfo/providerRetryPolicy at registration, so a duck-typed adapter object (plain object, no inheritance) that omits a newer optional method passes registration and crashes later: adapter.imageRequestPricing is not a function killed /compact and auto-compaction for the modlens plugin (#5372), and the same unguarded pattern exists at listModels/prepareCall. For plugin authors registering LLM adapters: either extend the base class, or add every optional method you can. (Durable core fix direction = registration-time normalization; discussed in the thread.)

3. client-modules bundle registration id vs package name (#5235). __ModuleLoader__.load({ id }) must equal the package.json name exactly; if you rename a plugin package without updating the bundle id, you get "loaded without registering" at boot. A rename checklist item rather than an alpha delta, but it bit a real plugin and is cheap to add to your section 四.

One platform gap worth stating for authors (from #5363): the loader rethrows the first entry-import failure and aborts the whole tree (vendor/loader/src/config/entry.ts), so a single stale plugin kills every other plugin in the profile — there is no per-entry isolation. That means "wait for rc" is not just cost advice, it is a resilience argument: during this alpha churn one bad import takes the whole profile down.

The encouraging half of your data matches my umbrella's conclusion exactly: the three crashes above all trace to registration/import-time validation checking metadata but not the method/export surface, and the fix direction is a single normalization seam, not per-plugin shims. If you want, I can cross-check future editions of this catalog against the upstream alpha diffs as they land — keeping this thread as the canonical migration map would save every plugin author from rediscovering these one crash at a time.

[szx-a]

Thank you for the additions! Your points and the three supplementary notes are very good. Welcome to future discussions and collaboration.

[Delafroms]

整理了一个针对这 5 个 QVD 的社区补丁仓库（基于 0.1.2-alpha.2）：52631/52632/52644/52646 四个有源码修复，57410 是版本核验；附逐项说明、Windows 一键验证脚本和 SHA-256。52632 的进程级读面残留也如实标注了，非官方发布，仅供参考。https://github.com/Delafroms/dsh-qvd-fixes

[szx-a]

补丁和验证脚本不错，感谢提供补充，

[eugenewang5425]

补充两个第三方插件在 alpha 期的断点数据（供插件作者参考）：

• dshmarket：旧版 1.29.2 从被移除的 API 导入 installSettingsSection 报错（作者已在 有没有人搞过升级 dsh 插件代码来支持新 dsh 版本的 skill？ #5120 记录 settings API 迁移），升级 1.40.0 后恢复；
• @linxin666/dsh-client-ui-web-ui-settings：settings.plugin.item 缺少 options.key 触发 Failed to load plugins（与 Failed to load plugins #5319 完全一致），属插件槽位注册不符契约，非官方 slot 校验器问题。
  两例均为插件侧适配问题，插件作者升级前建议先核对对应版本的 API 变更记录。

[szx-a]

感谢提供实例数据，此讨论欢迎随着版本更新进行更多的补充

[szx-a]

此讨论欢迎随着版本更新进行更多的补充，这几天官方更新很快

[daydayup789]

现在已经rc了。