第 9 卷

第 9 / 43 卷作者：Un-named日期：2026-08-17

Code）→pnpm	core.hooksPath，	harness/
install时lefthook	装完再恢复	discussions/139

postinstall 失败

macOS全局安装解	pnpm add -g	pnpm全局安装的	#204https://
析不到插件	@deepseek-ai/ds	模块解析策略与	github.com/
	h后启动报~88个	npm不同；macOS	deepseek-ai/
	插件包	建议用npm i -g或	deepseek-
	ERRMODULENOT	npx	harness/

FOUND discussions/204

koffi预编译损坏	koffi 3.1.3/3.1.4的	锁死koffi@3.1.2：	#293https://
（Windows）	win32-x64预编译	pnpm add	github.com/
	binary损坏→目录	koffi@3.1.2或改	deepseek-ai/
	选择器崩溃/服务静	package.json	deepseek-
	默挂	resolution	harness/

discussions/293

koffi原生崩溃	选择器worker崩溃	同上一行锁3.1.2；	#197https://
（Windows）	（0xC0000005访	若仍崩，检查是否	github.com/
	问冲突）或启动后	STA线程	deepseek-ai/
	直接挂掉	CoUninitialize段错	deepseek-
		误（社区有补丁）	harness/

discussions/197

插件安装格式坑

格式	写法	注意	帖号
npm包名	dsh plugin add	需已发布到npm；	—
	dsh-better-	rc阶段很多社区插
	sidebar	件未发布
GitHub仓库	dsh plugin add	只加依赖，不自动	#656https://
	github:作者/仓库	append到	github.com/
		cordis.patch.yml，	deepseek-ai/
		需手动补挂载行	deepseek-

harness/ discussions/656

本地路径link:/path/to/开发调试用；路径— plugin（macOS/斜杠按平台区分

Linux）<br>link:C:

\path\to\plugin （Windows）

被拆断：apps/cli/s组）或转发前自行deepseek-ai/

rc/plugin.ts 的转义deepseekrunPlugin 用harness/

spawnSync"pnpmdiscussions/1420 ", args, { shell: true

}——Node 按空格拼接参数、不转义

（Node 22+ 起 DEP0190 警告），

调用方引号到不了转发层

> 社区踩坑总结：用 `github:` 格式装插件后，记得手动去 `cordis.patch.yml` 补 `- insert:` 挂载行，否则插件依赖装了但 dsh 不加载。

其他常见坑

坑现象解决

插件缺 maindsh: No "exports" mainhost 插件 package.json defined要暴露 . 入口（"main":

"src/index.ts" 可被 tsx 直接加载）

事件handler忘了await	请求丢失	agent/request的next
next	provider/model报错	返回Promise，必须

await 后 spread

类型报'agent/request'	npm类型未re-export	用宽松签名（ctx.on as
is not assignable to	官方类型增强	unknown as ...）在边界
keyofEvents		转换
client包产物依赖	jsdom无法直接跑client	组件级测试需dsh web
window.ModuleLoader	测试	运行时（官方CI跑）

---

> **预设挂载单例冲突（#1415/#1827 确认）**：每次挂载带 Cordis toolset 的预设，`toolcordis` 会在进程单例的 Host inspect 注册表里重复注册四个 provider ID

（`Service`/`Event`/`Builtin`/`Tool`）——第二次挂载直接抛 `already registered`，会话恢复/多预设叠加时踩到。排查：确认同一进程内 tool-cordis 只挂载一次。

动手练习（检验你是否真懂了）

**理解题**：不看原文，画出 `profiles/web/` 目录下的文件结构，并说出每个文件的

作用 > 自查：参考本章 3.1 节"profile 目录长这样"

**理解题**：解释"host 半"和"client 半"分别跑在哪里、各负责什么。一个插件可以

只有 host 半吗？

> 自查：参考本章 3.3 节表格

**动手题**：打开你的 `~/.dsh/profiles/web/package.json`，找到

`dsh.profile.bundles` 字段，说出 bundle 的加载顺序 > 自查：参考本章 3.1 节"加载顺序"段落

**动手题**：假设你要挂载一个名为 `dsh-my-widget` 的插件，写出 `package.json`

和 `cordis.patch.yml` 各需要加什么内容 > 自查：参考本章 3.2 节的两处改动示例

**动手题**：在 `cordis.patch.yml` 里加一行错误的挂载（比如拼错插件名），重启

dsh web，观察报错信息并记录 > 自查：对比本章 3.5 节"常见坑"表格

**思考题**：官方原则说"Plugins, not loop changes"。如果你想改 dsh 的"模型回

复后自动总结"行为，应该用哪个扩展点？为什么不该直接改 agent-loop 源码？

> 自查：参考本章 3.4 节扩展点表格 + "改行为优先找钩子"原则

常见疑问 FAQ

**Q1：profile 和 bundle 有什么区别？**

profile 是"一种可启动形态"（如 web、headless），bundle 是"一组预配置的插件集合"。

profile 通过 `dsh.profile.bundles` 指定要加载哪些 bundle，再叠加自己的 patch。简单说：

bundle 是积木包，profile 是拼好的成品。

**Q2：`cordis.patch.yml` 里的 `- insert:` 是什么意思？还有其他操作吗？**

`insert` 是"在插件链中插入一个新插件"。patch 文件基于 cordis 的配置合并机制，支持 insert（插入）、override（覆盖已有插件配置）等操作。新手只需掌握 insert 即可挂载大部

分插件。

**Q3：插件状态是按 profile 隔离还是按会话隔离？**

挂载是 profile 级的（装一次，该 profile 下所有会话都能用），但**状态是会话级的**。比如 `better-sidebar` 的标签布局按会话持久化，不同会话互不干扰。

**Q4：我想写一个只有 client 半的插件（纯 UI），可以吗？**

可以。`package.json` 里声明 `dsh.client` + `exports["./client"]`，不写 `exports["."]` 即可。

但注意：client 半无法直接访问文件系统或跑命令，需要通过 host 半的服务（`ctx.provide`/`ctx.get`）桥接。

**Q5：`agent/request` waterfall 和 `conversationEvents.register` 有什么区别？我该用哪个？**

`agent/request` 是"改模型请求配置"的钩子（provider/model/tools/reasoningEffort），每次请求前触发，返回新配置。`conversationEvents.register` 是"订阅/注入对话事件"的钩

全站分卷索引 · 43 卷