AI 编写的 DSH 插件为什么容易出问题？—— 风险综述与防御实践

[XJungit]

AI 编写的 DSH 插件为什么容易出问题？—— 风险综述与防御实践

适用版本：DeepSeek Harness @deepseek-ai/dsh 0.1.0-rc.6（2026-08-15）
作者：@XJungit
类型：经验分享 / 讨论（非官方文档）
说明：DSH 仍处于 developer preview，核心插件与 API 会快速演进，文中的约定以当前 rc.6 为准，失效时欢迎指正。本文为@XJungit 的个人经验分享，非 DeepSeek 官方内容；文中引用的讨论、文章均为第三方观点，仅供参考。

---

摘要

DeepSeek Harness 的定位是"一切皆插件"，并且插件主要不是给社区 review 的成品，而是给 AI 现场生成、自用的。这带来了一个结构性风险：Cordis 插件跑在同一个进程里、共享 context 与工具注册表、没有运行时隔离——一个 AI 写的插件只要犯一个小错，轻则插件不生效，重则拖垮整个 DSH。

本文第一部分汇总社区里的真实证据（GitHub Discussions / Hacker News / Reddit / 中文社区），说明"AI 写的 DSH 插件质量差、容易导致崩溃"不是个别现象，而是有架构根因的普遍问题；第二部分给出作者在 omdp 仓库（dsh-connector / dsh-vision-bridge 两个插件的实际落地）验证过的防御实践，希望能帮大家少踩坑。

---

一、问题：插件为什么"跑着跑着就出问题"

如果你用 AI 写过 DSH（Cordis）插件，大概经历过这些：

• 插件装上后一直 pending，不生效，日志里是 waiting for services: ...
• 运行时报 cannot get property "xxx" without inject
• 启动时 Cannot find package ... 直接 dsh web 起不来
• 插件之间互相覆盖 / 撞名，行为变得不可预测

这些不是个例。它们的共同根源，是 DSH 的插件架构本身。

---

二、架构根因：单进程、共享注册表、无隔离

来自官方仓库的讨论 Discussion #326 — Thoughts on "Everything is a Plugin" — the user-side cost，作者 @phinn 分析了 DSH 的 49 个包依赖图后指出：

"Cordis plugins share one process, one context object, one tool registry."
（Cordis 插件共享一个进程、一个 context 对象、一个工具注册表。）

他还对比了 Webpack loaders："那些平台花了多年时间建立运行时隔离，Cordis 没有。"

这意味着什么：

风险	后果
一个插件抛未捕获异常	可能波及整个进程，影响所有会话
两个插件注册同名服务 / 工具 / section	互相覆盖或 fail loud，行为不可预测
插件声明了错误的 inject	自己 pending 不生效，甚至阻塞启动
插件依赖的原生二进制装错平台	loader 同步导入失败，整个 dsh web 启动即崩

而 Hacker News 上关于 DSH 的讨论（DeepSeek Harness developer preview）更是点破了设计定位：

"This is not for community plugins, it's for AI generated plugins. If everything is a plugin it means plugins can do everything. AI can write custom plugins for you."

翻译过来就是：DSH 的插件是给 AI 生成、给自己用的，没有社区 review 这道质量闸门。 所以"AI 写的插件质量差"是设计使然，不是偶然现象。

---

三、社区证据：这不是个别现象

3.1 官方 GitHub Discussions

① Discussion #380 — 写第一个 dsh 插件踩的六个坑（0.1.0-rc.6 本机复核）

作者（做 dsh-superpowers，把 Superpowers 方法论搬进 DSH）用 AI 辅助开发，踩了 6 个坑，几乎全是"AI 写插件"高频翻车点：

• 坑 1：import 路径解析失败。dev 链接下 Node 走软链接的真实路径，createRequire 找不到 @deepseek-ai/* → MODULE_NOT_FOUND。
• 坑 2：inject 写成对象。{ required: [...], optional: [...] } 会被 Cordis 当成"我要 required 和 optional 这两个服务"，插件永远 pending，启动卡住。
• 坑 3：inject 数组 vs 对象的语义混淆。数组每一项是服务名；对象走 Object.keys()，是拦截配置，别混用。
• 坑 4-6：section 命名冲突、host/preset 分层、npm 发布（国内镜像只读、OTP 2FA）。

作者的最终结论非常关键：

"我最后让插件不 import 任何 @deepseek-ai/，只留 node 内置模块，要什么都从 ctx 上拿。"

② Discussion #535 — npx @deepseek-ai/dsh web 报错

插件依赖导致整个 DSH 启动即崩的实证：

• attachment 插件：sharp 原生二进制加载失败（win32-x64 不匹配）
• subprocess 插件：node-pty 找不到（Cannot find package ...）

因为 DSH 的 loader 在启动时同步导入所有 bundle 的 loader entry，任何一个含原生依赖的插件装错平台，整个 dsh web 直接抛错起不来，而不是降级跳过。

③ Discussion #758 — Windows sandbox (workspace-write) 崩溃 + 4 related issues

虽然不是插件问题，但同属"早期框架隐蔽坑"：沙箱临时目录清理后不自愈、ConstrainedLanguage 噪音、WMI 查询被拒、UAC 静默失败。作者本人在 Windows 上也踩过 BUG-1（windows-acl-run: --temp is not an existing directory），说明这类运行时脆弱性是真实普遍的。

④ 其他运行时隐藏问题

• Discussion #483 — force-kill 后 write-behind 丢失未刷新尾部
• Discussion #712 — Python SDK 会话恢复 id 冲突

3.2 英文社区

• Hacker News（同上）：确认"插件给 AI 生成"的定位；也有人指出插件生态的普遍宿命——"插件通常因唯一维护者失去兴趣而死"。
• Reddit（r/DeepSeek — Harness and tools for deepseek）："it was breaking very often where it got stuck, so much badly written code"——直接吐槽经常卡死、大量写得烂的代码。

3.3 中文社区 / 第三方评测

• 5toy — DeepSeek Harness 测试反馈两极分化：
  • liustack（modlens 视觉插件作者）：多模态支持硬编码、没给第三方完整接口，只能"注册特殊模型变体绕过"，评价"太早期，很不完善"。
  • Bohu：eval 发现策略 bug——dsh 要求调查每个非零 exit code，但 grep 无匹配也返回 1 → 误判失败 → 自我强化验证循环（同任务请求数 61 vs 32、成本 $0.17 vs $0.05、token 290万 vs 54.8万）。
  • 结论："更适合开发者测试、拆解和做插件，不适合直接交给生产环境跑关键业务。"
• 掘金 — 给 DSH 加一双"眼睛"：图片识别插件踩坑实录：与视觉插件同类的实现与踩坑过程。
• 博客园 — 插件开发实战：从设计理念到 npm 发布：含 npm 发布流程（印证 写第一个 dsh 插件踩的六个坑（0.1.0-rc.6 本机复核） #380 的发布坑）。

---

四、AI 写插件的高频雷点清单（含真实报错）

以下是社区证据 + 作者实测汇总的、AI 写 DSH 插件最容易犯的错：

#	雷点	典型表现 / 报错
1	inject 写成对象（{required, optional}）	1 entry did not activate my-plugin: pending (waiting for services: required, optional)
2	访问未注入的服务	cannot get property "credentials" without inject（Cordis 的 Proxy 在 get 时直接抛，?. 救不了）
3	import @deepseek-ai/* 在 dev 链接下解析失败	MODULE_NOT_FOUND
4	依赖原生二进制（sharp / node-pty 等）	dsh web 启动即崩：Could not load the "sharp" module using the win32-x64 runtime / Cannot find package ... node-pty
5	注册同名服务 / 工具 / section	fail loud 或互相覆盖，行为不可预测
6	未捕获异常	单进程无隔离，可能波及整个 harness
7	工具 parameters 用 DSH per-property map	OpenAI 兼容 provider 报 schema must be a JSON Schema of 'type: "object"', got 'type: null'（HTTP 400）
8	依赖 rc 期的接口细节	API 快速演进，AI 学的旧写法很快失效

其中第 7 条是作者在 dsh-vision-bridge 上实测踩过的：ctx.tools.register（已安装 bundle 路径）会把 parameters 原样转发给 provider，per-property map（顶层无 type）到了 provider 手里变成 type: null 被拒。必须写完整的 JSON Schema（{ type: 'object', properties: {...} }）。

---

五、防御实践：如何写出"不崩"的 DSH 插件

5.1 三条核心原则

1. 纯 JavaScript / 零构建：避免 TS 编译产物缺失、避免原生二进制（sharp / node-pty 类），从根上避开 [BUG] npx @deepseek-ai/dsh web 报错 #535 那类启动崩溃。
2. 零运行时依赖：插件只 import Node 内置模块，要任何能力都从 ctx 上拿（社区共识，见 写第一个 dsh 插件踩的六个坑（0.1.0-rc.6 本机复核） #380）。
3. inject 显式声明 + 一维字符串数组：需要什么服务就明确声明什么，别靠 ?. 兜底。

5.2 inject 正确写法

// ✅ 正确：一维字符串数组
export const inject = ['tools', 'agents', 'attachments', 'llm', 'credentials']

// ❌ 错误：对象写法会被当成两个"服务名"
export const inject = { required: ['systemPrompt'], optional: ['skills'] }

5.3 服务访问的正确姿势

Cordis 对未注入服务的访问会在 get 时直接抛错（Proxy 实现），所以：

// ❌ 这样写没用：错误在访问 ctx.credentials 时就抛了
const cred = await ctx.credentials?.resolve?.(ref)

// ✅ 先在 inject 里声明 'credentials'，再访问
export const inject = ['credentials']
// apply(ctx) 里：
const cred = await ctx.credentials.resolve(ref)

5.4 工具注册的正确姿势（JSON Schema）

ctx.tools.register（已安装 bundle 路径）会把 parameters 原样转发给 OpenAI 兼容 provider，所以必须是完整的 JSON Schema：

ctx.tools.register({
  name: 'my_tool',
  description: '...',
  parameters: {
    type: 'object',
    properties: {
      path: { type: 'string', description: '...' },
      verbose: { type: 'boolean', description: '...' },
    },
    additionalProperties: false,
  },
  // ...
})

动态插件 defineTool 才用 per-property 的 ParameterSchemaSpec 写法；ctx.tools.register 这条路不适用。

5.5 错误处理与边界

• 关键调用包 try/catch，失败降级为可读的文本/错误信息，而不是抛到顶层。
• 注册前查重：工具名、服务名、section 名尽量带插件自己的前缀，避免撞名。
• 对"同名已存在"做 fallback（例如工具名被占用时换一个备用名注册），而不是让注册直接失败。

5.6 本地开发与验证流程

1. 本地 link: 安装（"@omdp/xxx": "link:D:/path" + pnpm install），改完重启 DSH 即生效，避免每次远程拉取。
2. 小步验证：先 dsh --profile xxx --dump-config 看 patch 层是否正确加载，再起一个最小会话测工具。
3. 用 node --check 做语法校验，import 后做 smoke test（确认模块能加载、导出函数存在）。

5.7 发布注意

• GitHub 远程安装会遇到 pnpm ≥10 的构建脚本拦截：首次 dsh plugin add github:... 会失败，需在 profile 的 pnpm-workspace.yaml 加：

  allowBuilds:
    '@omdp/xxx': true

• 纯 JS 插件无需 prepare 脚本，allowBuilds 是唯一门槛。
• 若发 npm，注意国内镜像只读、npm publish 只认 --otp（见 写第一个 dsh 插件踩的六个坑（0.1.0-rc.6 本机复核） #380）。

---

六、作者实践：omdp 仓库怎么做的

作者维护的 omdp monorepo 里有两个插件，完全按上面的原则落地：

• @omdp/dsh-connector：MCP + Skills 管理插件。纯 JS、仅依赖 yaml；写 cordis.patch.yml 前做完整校验（transport/serverName/url/command），并原子写入，保证"坏配置到不了下次启动"。
• @omdp/dsh-vision-bridge：视觉桥插件（给文本模型加"眼睛"）。零依赖、只 import Node 内置模块；工具 parameters 用完整 JSON Schema（修掉了 type: null 400）；inject 显式声明（修掉了 cannot get property "credentials" without inject）；工具重名做 fallback；粘贴路由做 magic-byte 校验 + 25MB 上限 + TTL 清理。

这些修复过程本身就是"AI 写插件踩坑"的活案例——建议直接参考仓库里的实现。

---

七、开放讨论（欢迎社区参与）

1. DSH 是否需要为第三方插件提供某种隔离/沙箱？ 现在单进程共享 context，一个插件崩可能拖垮整个 harness。未来会不会有进程级隔离或插件级错误域？
2. "插件主要给 AI 生成"这个定位，是否意味着官方应该提供更好的插件校验/调试工具？ 比如 --dump-config 之外，能不能有"插件体检"工具，提前暴露 inject 错误、服务缺失、schema 问题？
3. 社区需要一份"AI 写 DSH 插件安全清单"吗？ 如果大家觉得有用，可以一起维护一份，减少重复踩坑。

---

附录：来源链接

GitHub Discussions（官方仓库）

• #380 写第一个 dsh 插件踩的六个坑
• #326 "Everything is a Plugin" — the user-side cost
• #535 npx @deepseek-ai/dsh web 报错
• #758 Windows sandbox 崩溃 + 4 related issues
• #483 force-kill 后输入丢失
• #712 Python SDK 会话恢复 id 冲突

英文社区

• Hacker News — DeepSeek Harness developer preview
• Reddit — Harness and tools for deepseek

中文社区 / 第三方

• 5toy — DeepSeek Harness 测试反馈两极分化
• 掘金 — 给 DSH 加一双"眼睛"：图片识别插件踩坑实录
• 博客园 — 插件开发实战：从设计理念到 npm 发布

---

本文为社区公开讨论的整理与作者实测的归纳，观点归属原作者；DSH 仍处 developer preview，接口与行为会变，请以最新官方文档为准。

[weijiafu14]

[非官方] 这篇列出的 @deepseek-ai/* 解析、Cordis inject、工具 schema、entry/packaging 等问题，本质上还有一种工程解法：不要让每个能力包都直接耦合 DSH 内部接口，而是只维护一次兼容层。\n\n我们做的 pi2dsh 让 Pi 扩展保持原包、原 API，通过一个 Host ABI 挂进 DSH：\n\nsh\ndsh plugin --profile web add pi2dsh@0.11.0\ndsh plugin --profile web add <Pi-extension-package>\n\n\n这样单个能力包不需要 import DSH core、理解 Cordis service graph 或自己生成 DSH bundle；DSH 事件、工具、命令、会话、模型凭据等适配集中在 bridge 一处升级。当前已用真实 DSH 验证过视觉双模型、网页搜索、子代理、OAuth 模型调用、审批 reviewer 和跨进程记忆等不同形态，不只是一个 hello-world 插件。\n\n这个方向解决的是“每个插件重复踩一遍宿主 ABI 坑”和生态复用，不是进程级安全隔离：迁移后的服务端能力仍运行在 DSH 宿主信任边界内，恶意/失控代码、原生依赖和任意原生 DSH 插件拖垮宿主的问题，仍需要 DSH loader 的隔离、事务回滚与 safe mode。把这两层分开，我觉得会比要求每个 AI 现写插件都同时精通 Cordis 内部契约更可持续。

[PerryLink]

这篇综述的风险根因分析与我们在生态里的实测结论高度一致：单进程、共享注册表意味着「安装即授权」，信任不能靠用户逐行读源码来兜底，必须变成可复现的检查。我们针对文中三个层面做了对应防御件，可与防御实践一节互相印证：

1. dsh-auto-review — 第二个模型只读复核 DSH 授权请求，默认 fail-closed，全程可从会话日志审计；
2. dsh-permission-rules — Claude Code 风格声明式权限规则（allow/deny/ask + glob/regex），作用在 tools/pre-execute；
3. dsh-plugin-certification — 五维认证 spec v1（清单合规 / 构建卫生 / 供应链 Scorecard / provenance / 安装实测）+ 公开注册表 + README 徽章，把「这个插件能不能装」变成一条可执行的检查链。

三件套全部 Apache-2.0、npm 可装、已接入 OpenSSF Scorecard 与 npm provenance。如果作者愿意，欢迎把文中的防御实践与认证五维做一次交叉验证，我们的全部实测数据公开可查。

(EN) Our own measurements confirm this post's root-cause analysis: single-process shared registries make install equal to authorization, so trust must be reproducible rather than manual. We shipped the matching defenses: dsh-auto-review (second-model approval review, fail-closed, session-log auditable), dsh-permission-rules (declarative rules on tools/pre-execute), and dsh-plugin-certification (5-dimension spec v1 + public registry + badge). All Apache-2.0 on npm with OpenSSF Scorecard and npm provenance. Happy to cross-validate the defense practices in this post against the certification dimensions — our data is public.

[MajidAsghariTabrizi]

Concrete data point from a project that tried to apply the "hard parts" of this critique:

free-best-router is an OpenAI-compat routing layer for free LLM providers that intentionally avoids the risk surfaces you describe:

• No eval, no Function, no dynamic code generation — all routing logic is static, with explicit state transitions
• No LLM calls in tests — 52 deterministic unit tests across 6 files, all run with node --test, no network, no secrets, no fetch
• No remote code loading — every provider is wired in providers/ with explicit allowlists (OPENCODE_FREE_IDS, GROQ_FREE_IDS, CEREBRAS_FREE_IDS, MISTRAL_FREE_IDS); unknown ids fall through to pattern-based capability inference, never to a code path that mutates engine state
• No network telemetry — grep of src/ and providers/ shows the only outbound traffic is to the configured provider baseUrls. The diagnostics endpoint asserts that no sk-..., OPENROUTER_OX, OPENCODE_ZEN, or DEEPSEEK_API string ever appears in its JSON output (this is enforced by a test)
• Free-only invariant is enforced in code, not config — hardEligible(model, task) returns { ok: false, reason: "paid" } if model.free is false. Tested.
• Bounded blast radius — maxDepth: 4 x attemptTimeoutMs: 45_000 = 180 s wall time per request; explicit Retry-After and x-free-router-next-eligible headers on 502/429
• One dependency — undici ^8.10.1. That's it.
• No build step — pure ESM, runs on Node >= 22

The discipline of "treat the routing decision as authority-bearing" turned out to be the same discipline as fail-closed PnL gates: every code path that mutates state (cooldowns, success counters, exploration accounting) goes through recordOutcome, which has explicit type discrimination and caps.

Happy to compare notes with anyone shipping a router / plugin in this ecosystem. Full write-up in DSH Show Your Plugins! discussion #5508.

[MajidAsghariTabrizi]

Reply to #1884 — AI-written plugin risks

How do you verify an AI-generated plugin is actually doing what it claims?

This is the exact problem UEA was designed to address. The reference repo is here: MajidAsghariTabrizi/universal-engineering-agent (MIT, 31 self-tests, zero runtime deps).

The core insight: the AI generates the implementation; the kernel enforces the engineering workflow. Specifically:

• Typed failure classification — every error is routed through a 10-class deterministic classifier (PERMISSION_ERROR, TEST_ERROR, CODE_ERROR, etc.) before any retry happens. This is how you stop an agent from blindly retrying a broken plugin.
• Bounded recovery — PERMISSION_ERROR, CONFIG_ERROR, and DEPLOYMENT_ERROR are explicitly non-retryable. Everything else gets exponential backoff capped at 8 s, max 3 attempts.
• Staged verification — the kernel runs STATIC → UNIT → INTEGRATION against the agent's own code, not just the user's. The UEA self-test suite (npm test) is itself an example: 31 tests that verify the classifier, retry policy, verifier, and checkpoint log.
• Profile-driven constraints — the operating profile can declare failClosed: true so that any tool error returns a fail-closed string, never a throw, back up the call stack.

The documentation at docs/OPERATING-Kernel.md has the full 9-stage contract and the rationale for each stage.

The key distinction: UEA is not the agent, and it is not the AI writing code. It is the contract that the AI-written plugin must pass before the DSH session treats its output as trustworthy.