Agent Presets zh

Agent Presets

Edge 的静态单 preset 组装 vs 上游的动态 per-session YAML preset 系统。

无独立上游文档页。包：@deepseek-ai/dsh-agent-presets。参见 #43。

上游提供了什么

上游的 preset 系统支持 per-session 的 Agent 组装——不同 session 可以使用不同的工具集、系统提示词和模型选择：

• dsh-agent-presets — 读取 cordis.yml preset 文件，解析插件依赖，组装 per-session 的 cordis 子图。支持多 preset 选择、recompose() 热切换和用户自建 preset。
• cordis-plugin-loader — 运行时动态包加载。读取 YAML，解析 node_modules，调用 import() 按需加载插件模块。
• dsh-host-plugin-inventory — 通过 Typert Remote 向客户端暴露当前插件图，让设置页显示已加载的插件。
• dsh-client-ui-agent-preset — 客户端 UI：preset 选择下拉菜单、组装查看器、preset 管理（复制、删除、打开文档）。

当前 Edge 状态

一个硬编码的 preset

Edge 没有安装 dsh-agent-presets、cordis-plugin-loader 或 dsh-host-plugin-inventory。所有约 30 个插件在 EdgeSessionStore.initialize() 中静态安装——每个 session 得到相同的组装。apiproxy 返回固定的 preset 列表：

agentPresets: {
  list: () => ok({ presets: [{
    id: 'dsh-edge',
    trust: 'system',
    isDefault: true,
    name: 'DSH Edge',
    description: 'DeepSeek Harness running in a Cloudflare Durable Object.',
  }], authorable: false, hasDocument: false }),
  select: (req) => req.payload.agentPreset === 'dsh-edge'
    ? ok({ agentPreset: 'dsh-edge' })
    : fail('agent-preset-not-found')
}

客户端 UI

dsh-client-ui-agent-preset 包含在 33 个客户端插件中。它渲染 preset 选择下拉菜单和组装查看器。只有一个 preset（'dsh-edge'）时，选择器显示单个选项，组装查看器显示硬编码的 preset 描述。

Edge 没有改什么

• Agent 生命周期（创建、销毁、scope 隔离）——由 AgentRegistry 处理
• Per-session 模型选择——在单 preset 内正常工作
• 客户端 preset UI 渲染——上游代码，只显示一个选项

上游 vs Edge 对比

能力	上游	Edge
Preset 数量	从 YAML 文件加载多个	一个硬编码
插件加载	动态 import()	静态 ctx.plugin()
Per-session 组装	不同 session 不同 preset	所有 session 相同组装
用户自建 preset	可通过复制 + 编辑 YAML 创建	不可用
热切换 (recompose())	空白 session 上切换 preset	不可用
插件清单 UI	设置页显示完整插件图	空（无 host-plugin-inventory）
客户端 bundle	运行时模块扫描 + HMR	构建时静态组装

为什么 Edge 使用静态组装

Cloudflare Workers 有三个硬性约束阻止了上游的动态加载：

• 无文件系统 — cordis-plugin-loader 通过 node:fs 读取 cordis.yml。Workers 没有配置文件的文件系统。
• 无动态 import() — Workers 在部署时打包所有代码。运行时 import() npm 包不被支持。
• 单 JS 包 — Worker 是一个 JavaScript 文件。所有插件代码必须在部署时存在于该包中。

静态组装不是临时方案——而是为 Cloudflare 兼容性做出的有意设计取舍。

两种模型的并排对比

方面	上游（动态）	Edge（静态）
插件发现	cordis-plugin-loader 运行时从文件系统读取 cordis.yml	assemble-standalone-web.mjs 构建时复制已发布的插件包
插件加载	import() 动态加载包	所有插件打包进一个 Worker JS 文件
Preset	每个部署多个 YAML preset；用户可创建/复制/编辑	一个硬编码 preset 'dsh-edge'；所有 session 相同
服务端插件	按 preset 从 YAML 组合加载	EdgeSessionStore.initialize() 中约 31 个 ctx.plugin() 调用
客户端插件	运行时构建启动图；开发时 HMR	33 个插件预构建；expected-boot-graph.json 在审查时冻结
插件清单	dsh-host-plugin-inventory 向 UI 投影实时状态	不可用——设置页插件列表为空
热重载	通过 dsh-client-hmr 实现 HMR	完整重建 + 重新部署（无 HMR）
添加插件	编辑 cordis.yml → 重载	编辑 session-store.ts + package.json → 重建 → 重新部署

构建管线

服务端

session-store.ts（31 个 ctx.plugin() 调用）
  → standalone/scripts/bundle-standalone.mjs
  → worker/direct/index.js（单个 Worker 包）
  → gzip 预算检查：最大 921,600 字节

客户端

上游已发布的客户端包
  → standalone/scripts/assemble-standalone-web.mjs
  → dist/plugins/@deepseek-ai/*（33 个插件目录）
  → expected-boot-graph.json（冻结的契约）
  → verify-standalone.mjs（CI 门控）

排除的客户端包

9 个上游客户端包被显式排除，因为它们依赖 Edge 没有的功能：

• dsh-client-hmr — HMR（无 dev server）
• dsh-cordis-client-runner — 动态加载器客户端半
• dsh-client-ui-cordis — 组合检查器
• dsh-client-ui-message-feedback — 消息评分（服务端未安装）
• dsh-client-ui-plan — 计划模式（服务端未安装）
• dsh-client-ui-reference — @提及（服务端未安装）
• dsh-client-ui-settings-plugin-inventory — 插件列表（无清单服务）
• dsh-client-ui-settings-plugins — 插件设置（无 preset 编辑）
• dsh-session-log-export — 会话导出（未接线）

验证

verify-standalone.mjs 在 CI 中运行并检查：

• 所有 @deepseek-ai/dsh-* 依赖锁定在同一个上游版本
• 组装的启动图匹配 expected-boot-graph.json
• 排除的客户端包列表是最新的
• Worker gzip 预算不超过 921,600 字节

任何偏差——上游升级新增客户端插件、新排除项、包大小飙升——都会在到达生产环境之前让 CI 失败。

性能影响

指标	上游	Edge
冷启动	插件发现 + 动态 import + YAML 解析	零发现——所有代码在包内，ctx.plugin() 是同步调用
包大小	不适用（从磁盘加载）	约 774 KB gzip（预算 900 KB）——所有服务端 + 客户端代码在一次部署中
开发迭代	HMR — 亚秒级重载	完整重建约 15s → wrangler dev 自动重启
插件变更	编辑 YAML，无需重启	代码修改 → 重建 → 重新部署

架构总结

组件	分类	Edge 代码
dsh-agent-presets	未安装	edge-api.ts 硬编码单 preset
cordis-plugin-loader	未安装	静态 ctx.plugin() 调用
dsh-host-plugin-inventory	未安装	设置页无插件列表
dsh-client-ui-agent-preset	复用	在客户端 bundle 中，显示单 preset

TODO

评估配置驱动的插件激活。（#43）所有插件代码已在包中。DO KV 配置可以在不重建的情况下按 session 切换激活的插件——仍是静态代码，但动态组合。这将使多个"preset"以 JSON 配置而非 YAML 文件的形式存在，完全绕开动态加载的约束。