# DSH 0.2.1-rc.2 兼容修复记录

日期：2026-10-19。插件版本：0.1.8 → **0.1.9**。
本任务仅修复 `dsh-ob-agent`，未升级其他插件，未重启现有 GUI，也未启动替代 Web 服务器。

## 已确认的问题与修复

| 问题 | 修复 |
| --- | --- |
| 新版子代理工具拒绝 `persona` / `toolFilter` | 不再向原生工具传入废弃字段；在公开 activation 边界预留受管 ID，创建前落盘策略，串行 `agent/created` 装配子代理作用域身份和白名单。 |
| 原生 `apply` 变为 Promise，旧同步 try/catch 接不住拒绝 | 注入回调内 `await/catch`，等待 fiber 激活；失败释放 fiber，返回不可用原因，不把失败工具宣传给模型。 |
| 新版不再提供本地一次性委派选项 | 按用户要求完全移除一次性新建和模拟；所有新条目固定 continuable，旧一次性/双模式条目迁移，不删除角色。 |
| provider 晚注册时无法自动重挂 | 监听 provider-added / provider-removed 触发重算。 |
| 工作流直接 `apply(undefined)`，且缺 workflowEngine 注入 | 消费原生模块声明的 `inject` 与 `Config`，补齐默认值；异步失败同样等待处理。Ralph 采用相同路径。 |
| UI 开发类型仍是 0.2.0 | primitives 钉为 0.2.1-rc.2，通过 typecheck；移除一次性/双模式控件。 |

不复制父 preset，不注册动态替代 provider，不使用宿主私有字段，不伪造历史 descriptor。
spawn/fork 继续由原生服务管理路由预检、父子关系、完成通知、续话和中止。

## 策略目录

默认 `$DSH_HOME/plugins/dsh-ob-agent/child-policies/`；未指定 DSH_HOME 时为用户 `.dsh` 下同名目录。
可用 `DSH_OB_AGENT_POLICY_DIR` 覆盖。快照写入使用独占创建并 flush，成功后才调用创建接口。
路径由严格的 `obagent-<UUID>` 标识生成，不接受模型输入文件路径。

快照绑定父子身份、版本、模式、persona 与白名单。缺失、损坏、未知版本、父子不符或装配服务缺失均拒绝，
不会把只读恢复为完全权限。继承工具被白名单隐藏；自有层和后续新增工具由单调守卫拒绝。
只读回发只允许直接父代理。原生非受管 ID 不读取本插件策略。

备份会话时必须同时备份此目录。本版不做 TTL/自动 GC，不依赖可能被迁移丢弃的实验性 Session record。
快照不是 OS 安全边界；升级应停止原进程后重启，不承诺热卸载期间仍安全保留全部约束。

## 配置与安装

- 上游源码 `git pull --ff-only` 无更新；npm 无该插件发布包，因此在本地源码修复并构建。
- 通过当前宿主的官方 `plugin --profile web add file:<checkout>` 安装 0.1.9。
- 恢复禁用前保存的本插件配置段，迁移全部子代理模式，并合并安装期间新增的会话选择。
- 保留 9 个角色、85 条会话选择及原模型/思考档位/身份/权限；其他插件配置前缀原文字节保持不变。
- 其他 dependency 的声明比较无变化，不安装其他插件新版本。
- 安装前四件套备份位于用户 profile 的 `_backup-before-ob-agent-repair-20261019-164437/`。
  此目录包含私密 profile 数据，不要公开提交。保留更早禁用前备份。
- Windows 安装器创建了源码产物与 profile 副本的 hardlink；本机哈希实测一致。
  不能泛化为所有安装方式均会自动同步，维护时始终核对哈希。

## 验证

1. 局部测试：配置生成、模式迁移、自助创建拒绝退役模式、快照不可覆盖、缺失/损坏拒绝、
   首次/冷恢复策略、原生子代理不受影响、缺服务拒绝、白名单和父目标限制。
2. 真实 DSH 0.2.1-rc.2 Cordis / ToolRuntime：原生 apply 拒绝旧字段；spawn/fork 登记和 activation 参数；
   身份前后缀覆盖、继承工具隐藏、自有层新写工具执行被拒。
3. 真实安装副本的插件生命周期：provider 先缺席再注册后自动重挂；workflow / Ralph / send_message /
   interrupt_agent / list_agents 登记成功。工作流引擎与模型执行为桩，不执行真实任务。
4. `npm run check`：类型、**236/236 测试、13 个测试文件**及构建均通过，0 失败、0 跳过；其中真实宿主组 6/6。
5. 当前 web profile `--dump-config` 退出 0，共 **3079 行**、一次插件条目，未发现 fatal、incompatible-version、entry not found。
   配置预检并不等同浏览器和所有模型路由端到端通过。
6. 本机原进程与 3080 端口保持，不运行 `dev:web` watcher，不承诺客户端自动更新。

## 生效与未验证边界

**需要用户重启原 DSH 进程，并刷新原 GUI。** 不在当前会话中强制结束宿主。
未进行付费模型往返、真实子代理完整任务、浏览器面板点击、真实工作流/Ralph 执行或业务文件写入测试。

其他插件已知的 `webRuntime` 缺失等问题不在本轮实施范围，可能继续出现在启动日志；
不能据本插件修复成功宣称整个 profile 全部正常。recall 的 EPIPE/格式文案也不通过删除快照索引绕过。

## 回退

需要回退时先停止 DSH，再按本次备份恢复本插件对应的 profile 清单/配置与旧代码版本；
不要把其他插件后续新增配置整份覆盖。**不建议在 DSH 0.2.1-rc.2 上重新启用 0.1.8**，
它会再次触发废弃字段错误。更安全的应急方案是仅禁用本插件并保留配置、会话及策略目录。