dsh-preset-guard

修复被 DeepSeek Harness 版本升级重命名弄坏的持久化预设状态 —— 一个插件覆盖 两种 preset 失效模式。

DeepSeek Harness（dsh）插件。症状搜索词：preset 加载错误、旧版本创建的 preset 打不开、升级后新建会话没反应、升级后无法新建对话、persona invalid config、 $.prefix missing required value、agent-preset/not-found、默认 preset 失效。

两种失效模式

版本改了个名字，而用户自己的持久化状态还在用旧名字。两者都是静默的：roster 一律把预设报告为健康，客户端把挂载失败折叠成一条 console 警告。

1. shipped preset 改名，导致 agent-presets.default 指向本部署不再提供的 id。 此后每次新建会话都以 agent-preset/not-found 失败，「新建会话」按钮毫无反馈。

2. 插件配置字段改名，导致用户预设无法挂载。0.1.5-rc.1 把 @deepseek-ai/dsh-persona 的 text 键改名为 prefix （提交 40792330c0，packages/preset/persona/src/index.ts:36,50），于是 <dsh-home>/.agent-presets/ 下仍写 text 的预设全部失败：

agent-presets: preset "my-preset" failed to mount: failed to apply loader
entry persona (@deepseek-ai/dsh-persona): invalid config:
  - $.prefix missing required value (at prefix)

discovery 从不拦截它：compositionProblem() （packages/preset/agent-presets/src/discovery.ts:225）只检查行的形状与包解析， entryListProblem() 的注释也明说它 "不解析插件名、也不套用 config"。 所以过期预设带着 broken: null 通过了健康检查。

插件做什么

启动时：

• 文件侧。 对每个 trust === 'user' 的预设根，扫描各个 agent.cordis.yml， 把 @deepseek-ai/dsh-persona 行 config 块里遗留的 text 键改名为 prefix。 改写极保守：除那一行外，每行、注释、空行必须逐字节相同，否则拒绝写入；会对自己的 输出重新扫描；流式写法只报告不猜测；原文件保留为 agent.cordis.yml.dsh-preset-guard.bak。这一半是同步的 —— loader 并发应用 兄弟 entry，异步改写可能在第一个会话挂载该预设时仍未落盘。
• 默认值侧。 把解析出的 agent-presets.default 与实时 roster 对比，不一致时修复 用户层：优先部署默认，其次配置的 fallback，最后 standard。

安装

最简 —— 装 umbrella，一行挂载本插件与其它已验证的社区修复：

dsh plugin --profile <你的 profile> add dsh-community-fixes

再把 dsh-community-fixes 加进该 profile 的 dsh.profile.bundles。

单独使用本包：

dsh plugin --profile <你的 profile> add dsh-preset-guard

- insert:
    - id: preset-guard
      name: 'dsh-preset-guard'

配置

| 字段 | 默认值 | 含义 | | ---------- | ------- | ---- | | fix | true | 同时修复已存储的 composition 与持久化的默认值。false 只报告，不写任何东西。 | | fallback | '' | 清除过期默认后若无可用默认，则安装该 id。缺省时优先 standard，否则取 roster 第一个。 |

验证

19 个契约测试（npm test），外加隔离环境中的两组端到端运行 —— 见 docs/verification.md。两半也都以 dsh-community-fixes umbrella 挂载的形式重新验证过。

| 半边 | 对照 | 挂上 guard | | ---- | ---- | ---------- | | 预设文件 | $.prefix missing required value，会话创建失败 | 启动时已迁移，会话创建成功 | | 过期默认值 | 新建会话以 agent-preset/not-found 失败 | 用户层被修复，部署默认生效 |

局限

• 这是插件，不是上游补丁。它只在启动时修复已存储状态；没有让 discovery 去校验 config schema，所以未来别的改名造成的损坏仍会静默失败。
• 只处理 persona 的 text → prefix 改名。
• 即便预设现在能挂载，roster 仍会显示 broken: null，因为健康检查根本不看 config。

许可证

MIT