加载方式对比：静态配置 vs 手动加载

August 14, 2026 · View on GitHub

本文档对比 prompt-optimizer 插件的两种加载方式，帮助你在「重启后自动加载」与「零配置快速试用」之间做出选择，并给出推荐建议与完整操作步骤。

方式一：静态配置（推荐）方式二：动态加载（手动）
持久性✅ 服务重启后自动加载❌ 进程重启后丢失，需手动恢复
代码位置$DSH_HOME/profiles/<profile>/plugins/prompt-optimizer/（npm 包）进程内（cordis_define 定义）
配置位置cordis.patch.yml + profile package.json无配置文件
激活方式启动时由 loader 自动扫描加载每次重启后手动 cordis_define + cordis_run（需批准）
适用场景长期使用、多会话共享、团队部署快速试用、调试迭代、临时验证
维护成本低（装一次永久生效）高（每次重启重装）

工作方式

方式一：静态配置（本仓库 static/ 目录）

插件被打包成标准 npm 包，放在 DSH profile 的 plugins/ 目录下，通过两处配置接入组合：

  1. profile package.json 的 dependencies 增加 file:plugins/prompt-optimizer；
  2. cordis.patch.yml 的 insert 列表增加一行 { id: prompt-optimizer, name: 'prompt-optimizer' }。

DSH 启动时，cordis-plugin-loader 按 patch 层解析组合，加载该包：

  • Host 半（lib/index.js）：注册 promptOptimizer Typert Remote 服务（方法 optimize）；
  • Client 半（lib/client.js）：通过 dsh.client 声明由 client-modules 服务扫描，作为 /plugins/prompt-optimizer/client.js bundle 注入浏览器，注册 conversation.input.right 插槽按钮。

Client → Host 通信走 Typert Remote 通道（ctx.remote.promptOptimizer.optimize(...)），替代动态插件的 host.call。

方式二：动态加载（本仓库根目录 host.js / client.js）

通过 DSH 动态插件机制（cordis_define / cordis_run）把两个函数体注入当前进程：

  • host.js：注册 harness.handle('prompt.optimize') RPC；
  • client.js：注册 conversation.input.right 插槽按钮，用 host.call('prompt.optimize', ...) 调用。

定义只存在于当前进程内存，服务重启即丢失。

优缺点

静态配置

优点

  • 重启自动加载，无需人工干预；
  • 与 DSH 官方插件（如 dsh-tool-see-image）同构，可被 dsh plugin 命令管理；
  • 适合长期部署与团队共享（随 profile 一起分发）。

缺点

  • 需要安装依赖（pnpm install）；
  • 需要手写/维护 __ModuleLoader__.load 格式的 Client bundle（无 bundler 时）；
  • 配置层级更多（package.json + cordis.patch.yml 两处）。

动态加载

优点

  • 零文件、零配置，一条命令即可试用；
  • 迭代快：改代码 → cordis_define → cordis_run；
  • 适合验证思路、临时功能。

缺点

  • 重启即丢失（本插件历史踩坑点：重启后按钮消失）；
  • 不随 profile 持久化，无法共享给其他会话/机器；
  • 需每次批准运行（approval）。

推荐建议

你的场景推荐方式
日常长期使用、希望重启不丢静态配置
团队/多机部署同一 Harness静态配置（随 profile 分发）
快速试用、临时验证动态加载
插件开发迭代中动态加载（迭代稳定后再静态化）

推荐：正式使用一律采用静态配置。开发调试阶段可先用动态加载快速验证逻辑，稳定后按下方步骤静态化。

静态配置：完整示例与操作步骤

目录结构

$DSH_HOME/profiles/web/
├── package.json                  # ① dependencies 增加 file: 依赖
├── cordis.patch.yml              # ② insert 插件行
├── pnpm-lock.yaml
└── plugins/
    └── prompt-optimizer/         # ③ 插件包（本仓库 static/ 目录内容）
        ├── package.json          #    含 dsh.client 声明 + exports["./client"]
        └── lib/
            ├── index.js          #    Host 半：promptOptimizer Remote 服务
            └── client.js         #    Client 半：__ModuleLoader__.load bundle

步骤 1：放置插件包

把本仓库 static/ 目录整体复制为：

$DSH_HOME/profiles/<你的profile>/plugins/prompt-optimizer/

（$DSH_HOME 默认是 ~/.dsh；web profile 即 $DSH_HOME/profiles/web）

步骤 2：profile package.json 增加依赖

在 profiles/<profile>/package.json 的 dependencies 中增加：

{
  "name": "dsh-profile-web",
  "private": true,
  "dependencies": {
    "dsh-tool-see-image": "file:plugins/dsh-tool-see-image",
    "prompt-optimizer": "file:plugins/prompt-optimizer"
  }
}

步骤 3：cordis.patch.yml 增加插件行

在 profiles/<profile>/cordis.patch.yml 的 insert 列表末尾增加：

- insert:
    # ... 已有的行 ...
    - id: prompt-optimizer
      name: 'prompt-optimizer'

步骤 4：安装依赖并验证

cd $DSH_HOME/profiles/<profile>
pnpm install          # 链接 file: 依赖，生成 node_modules/prompt-optimizer

# 验证配置可解析（不启动服务）
dsh --profile <profile> --dump-config | grep prompt-optimizer

步骤 5：重启 DSH

重启后插件自动加载：输入框工具行（发送按钮左侧）出现 ✨ 按钮即成功。

插件包 package.json 关键字段

{
  "name": "prompt-optimizer",
  "type": "module",
  "main": "lib/index.js",
  "exports": {
    ".": "./lib/index.js",
    "./client": "./lib/client.js"
  },
  "dsh": {
    "client": {
      "platform": "web",
      "inject": [
        "@deepseek-ai/dsh-client-connection",
        "@deepseek-ai/dsh-client-runtime",
        "@deepseek-ai/dsh-client-locale",
        "@deepseek-ai/dsh-client-ui-conversation",
        "@deepseek-ai/dsh-api-remotes"
      ]
    }
  }
}
字段作用
exports["./client"]指向 Client 半 bundle，由 client-modules 以 /plugins/<id>/client.js 提供
dsh.client.platform: "web"声明这是一个 web 端浏览器插件
dsh.client.inject声明 Client 半依赖的运行时服务（远程通道、运行时、会话 UI 等）
lib/index.jsHost 半，注册 promptOptimizer Typert Remote 服务

Host 半与动态版的差异

动态版静态版
Host 注册 RPCharness.handle('prompt.optimize', ...)TypertRemoteService 子类 + Remote("optimize")
Client 调用host.call('prompt.optimize', args)ctx.remote.promptOptimizer.optimize(args)
模块格式函数体（return { apply(ctx) }）npm 包（export default 插件 + dsh.client 声明）
加载进程内 cordis_define启动时 loader 自动扫描

常见问题

Q：静态化后 peer 依赖警告（missing peer @deepseek-ai/cordis 等）正常吗？ A：正常。@deepseek-ai/* 运行时由 DSH 宿主（bareModuleBaseUrl 机制）解析，dsh-tool-see-image 等官方/社区静态插件同样存在这些警告，不影响加载。

Q：两种方式能同时启用吗？ A：不建议。动态版注册 prompt.optimize（harness RPC），静态版注册 promptOptimizer（Remote 服务），两者并存会重复注册同名插槽 conversation.input.right。静态化后请勿再手动加载动态版。

Q：改代码后如何生效？ A：静态版需重启 DSH（或触发 HMR 重打包 Client bundle）；动态版 cordis_define 新 Package 并 cordis_run 即可。

Q：dsh --dump-config 报 EPERM？ A：说明 DSH 正在运行占用 cordis.yml。停掉服务后再验证，或直接重启后观察按钮是否出现。