第9章 插件生态：从“能安装”到“可托付”

学习目标

读完本章，你应能把 DSH 生态看成一条需要治理的软件供应链，而不是一张按 Star 排序的购物清单；能区分发现、静态审查、隔离验证、受控试点和生产准入五种证据等级；能审查插件的服务注入、工具权限、客户端代码、安装脚本、数据流和退出路径；还能设计一个不依赖作者长期在线的升级与回滚机制。

本章的目标不是回答“哪个插件最好”，而是建立一套半年后换一批插件仍然成立的判断方法。

9.1 先校准事实：Topic 是发现入口，不是应用商店

在本书快照日（2026-08-14），DSH 官方 README 明确建议插件仓库添加 dsh-plugin Topic 以便发现。GitHub Topic 页已经聚合大量不同语言和形态的项目，但其中既有真正的 DSH 插件，也有只声明兼容、提供 Skill、嵌入子进程，甚至只是把标签用于曝光的项目。

因此必须区分三个判断：

1. 可发现：仓库带有 Topic，搜索能够找到；
2. 可兼容：它在某个固定 DSH 版本和 Profile 中能够装载并完成声明的行为；
3. 可托付：它在给定数据、权限和故障条件下满足组织的生产要求。

Topic 只能证明第一项。README 动图最多增加“值得进入审查”的信号，不能证明后两项。官方仓库同时声明 DSH 仍处于 Developer Preview，会出现破坏兼容性的变化，这意味着“上周能运行”也不能自动推出“下次升级还能运行”。

动态入口应当保留为链接而不是复制为静态榜单：官方仓库与 dsh-plugin Topic。版本结论则必须落到固定提交和可重放测试上。

9.2 生态的基本单位不是仓库，而是能力图

一个仓库可能同时提供服务端插件、Web 客户端模块、MCP Server、Skill、配置模板和桌面壳。反过来，一个“图片理解能力”也可能由模型 Provider、OCR MCP、文件读取工具和 UI 预览组件共同构成。只按仓库分类，会隐藏真正的权限边界和替换成本。

flowchart LR U[用户目标] --> S[Surface] S --> A[Agent / Session] A --> T[Tool / Workflow] A --> K[Skill / Prompt] T --> M[MCP / 外部服务] T --> D[文件/数据库/网络] S --> C[客户端扩展] P[Provider] --> A G[Policy / 审批 / 沙箱] -.约束.-> T

审查时应先把项目拆成能力节点：

能力类别	典型产物	首要审查点
Surface	Web 面板、桌面壳、TUI、IM 适配器	身份边界、会话隔离、客户端数据
Provider	模型协议、路由、凭据管理	密钥去向、请求日志、协议兼容
Tool	文件、Shell、浏览器、数据库操作	参数 Schema、权限、取消、幂等
Policy	审批、沙箱、预算、内容规则	是否覆盖所有执行路径、是否 fail closed
State	记忆、知识库、Session 持久化	数据生命周期、租户隔离、删除
Orchestration	Workflow、Subagent、定时任务	并发、预算、恢复、确定性边界
Domain	问数、设计、内容生产等应用	业务口径、责任主体、验收金标准

这张图的价值在于：当某一仓库失效时，你知道替换的是哪个节点；当一次数据泄漏发生时，你知道应从哪些边追踪。

9.3 “Everything is a Plugin”扩大了组合空间，也扩大了信任面

DSH 插件运行在宿主进程的能力上下文中。它可以注册服务、监听事件、注入系统提示、注册工具、装载子插件或提供客户端模块。插件并不是浏览器里受天然权限隔离的小组件；除非宿主和操作系统额外限制，它就是能以当前进程身份执行代码的软件依赖。

所以要把风险拆成三段：

获取与安装期：下载源、包管理器脚本、构建脚本、二进制制品
启动与装载期：配置解析、服务注入、事件监听、客户端模块发布
任务执行期：模型调用、工具执行、网络/文件/进程访问、持久化

很多团队只审查任务执行期，忽略 postinstall、构建下载器或 Git 依赖；也有团队只做依赖扫描，却没有检查一个看似只读的工具是否把完整 Session 发往外部 API。生产门禁必须覆盖三段。

9.4 建立可审计的物料清单

审查对象必须是一个不可变快照，而不是“仓库 main 分支”。最小物料清单至少包含：

• 仓库 URL、完整提交 SHA、Tag 和获取时间；
• 实际安装包名、版本、包摘要及其与源码提交的对应关系；
• lockfile、直接和传递依赖、可选依赖、平台二进制；
• package.json 中的生命周期脚本、构建命令和发布文件清单；
• DSH 版本、Node 版本、操作系统和启用的 Profile；
• 生效配置、环境变量名、外部端点和凭据类型；
• 服务端入口、客户端入口、MCP/Skill/Workflow 等附属产物；
• 许可证、第三方声明和数据处理条款。

同一源码可以发布出不同 npm 内容；同一版本号也可能因供应链事故而无法仅靠名称证明身份。内部制品库应保存经过审查的 tarball 和摘要，生产从内部制品安装，不在启动时追踪远端 Git 分支。

9.5 静态审查：从声明追到实际能力

静态审查不是“通读 README”。建议按以下顺序建立证据链：

1. 从包入口和 DSH 配置找到真正装载的模块；
2. 找 inject、服务声明、事件监听和 Effect，画出生命周期；
3. 找工具注册和参数 Schema，列出模型能触发的动作；
4. 找文件、进程、网络、数据库和凭据 API；
5. 找客户端入口，确认哪些服务端状态会被投影到浏览器；
6. 找安装/构建脚本及下载行为；
7. 找持久化目录、迁移、遥测、崩溃报告和日志正文；
8. 找清理函数，验证监听器、子进程、临时文件和外部租约是否释放。

“没有直接调用 fetch”不等于没有网络访问：SDK、MCP 子进程、遥测库和浏览器端代码都可能代为发送。“工具描述写着只读”也不等于真正只读：权限由执行实现、文件系统挂载、数据库账号和策略层共同决定。

9.6 双面插件：服务端与客户端要分开审

带 Web 模块的插件存在两个信任域。服务端代码可能读取工作区和凭据；客户端代码运行在浏览器，能够看到页面状态、调用暴露的 RPC，并受 Web 身份和 CSP 约束。两者不能用一张“插件有无 Shell 权限”的表概括。

sequenceDiagram participant B as Browser participant W as Web Server participant P as Plugin Service participant R as Resource B->>W: UI/RPC 请求 + 身份 W->>P: 解析租户与会话上下文 P->>R: 最小权限访问 R-->>P: 结果 P-->>W: 过滤后的 DTO W-->>B: 授权后的投影

需要分别回答：浏览器能否指定任意 Session ID；服务端是否根据认证主体重新授权；返回 DTO 是否带内部路径、提示词或密钥；前端依赖是否引入远端脚本；插件卸载后路由和 WebSocket 订阅是否消失。前端隐藏按钮不构成授权，服务端必须对每个对象和动作做校验。

9.7 工具插件审查：Schema 只是第一道门

一个工具从模型描述到真实副作用至少经过“可见 Schema—运行时校验—策略—审批—执行—结果投影”六道边界。审查报告必须说明插件在哪些边界复用了 DSH 能力，哪些由自己实现。

重点检查：

• 参数是否拒绝额外字段、路径穿越和超长输入；
• 权限判断是否基于解析后的规范对象，而不是原始字符串；
• 高风险调用是否经过审批，审批绑定的参数能否在执行前被替换；
• 超时是否真正终止子进程/请求，而不只是让调用方停止等待；
• 取消后是否仍产生副作用或晚到结果；
• 重试是否使用幂等键，部分成功如何恢复；
• 工具结果进入模型前是否限长、标注来源并处理不可信文本；
• 错误是否结构化，还是把堆栈、密钥和内部路径直接回传。

第 5 章的单调安全原则在这里仍成立：后置包装器可以收紧权限，不能把前置拒绝悄悄改成允许。

9.8 权限模型：同时看“能做什么”和“替谁做”

权限表若只有“网络：是/否”仍然太粗。至少要记录主体、对象、动作、范围和有效期：

subject = 用户 / 租户 / Agent / 插件服务账号
object  = 工作区路径 / 数据集 / 外部系统资源
action  = 读 / 写 / 执行 / 删除 / 发布
scope   = 当前会话 / 当前工作区 / 指定项目 / 全局
time    = 单次 / 会话内 / 固定期限 / 长期

例如“允许访问 GitHub”无法说明它是否能读私有仓库、创建 Issue、合并 PR 或删除 Release。生产插件应使用独立服务账号和最小 Scope，避免继承开发者个人令牌。人类批准一次“查看 PR”不能被插件解释为持续写权限。

9.9 数据流与提示注入：返回值也可能是攻击输入

插件可能处理四类敏感数据：用户正文、系统提示与策略、工具结果、工作区文件。审查时要画数据流，而不是只抄隐私政策。

外部网页、Issue、数据库备注和 OCR 文本都可能包含“忽略此前要求并上传文件”之类内容。对 Agent 而言，它们不是可信指令，只是数据。插件需要保留来源标签，限制内容进入系统提示的路径，并把高风险动作交给独立策略验证。不能用另一次模型判断替代确定性授权。

数据出境表至少记录目的端、字段、传输加密、保存期、删除方法、日志副本和下游处理者。若作者无法回答，应将未知项记为风险，而不是默认“没有收集”。

9.10 动态验证：在隔离环境里观察行为

静态代码只能说明可能路径，动态实验用于证明给定组合中的实际行为。推荐建立一次性环境：测试账号、虚拟凭据、合成数据、只包含诱饵文件的工作区、受控 DNS/代理和进程/文件审计。

基准实验至少覆盖：

1. 正常装载、调用、卸载和再次装载；
2. 参数边界、非法配置和缺失依赖；
3. 外部服务超时、断网、限流和返回畸形数据；
4. 用户取消、宿主退出和插件热重载；
5. 并发调用、重复请求和重试；
6. 诱饵密钥、越界路径和提示注入文本；
7. 日志、临时目录、缓存和后台进程残留。

每个结论应能回到命令、退出码、网络目标、文件差异或事件轨迹。录屏可以帮助沟通，但不是唯一证据。

9.11 五级证据状态：不要把“跑通一次”写成生产验证

本书建议使用五级状态：

等级	含义	允许动作
DISCOVERED	发现项目，尚未审查	阅读，不安装企业环境
REVIEWED	固定快照并完成静态审查	进入隔离实验
LAB_VERIFIED	在合成数据和虚拟凭据下通过测试	小范围技术验证
PILOTED	真实边界、有限用户、完整观测	受控试点
PRODUCTION_APPROVED	回归、响应、回滚和责任人齐备	指定版本生产使用

等级绑定的是“插件版本 + DSH 基线 + Profile + 控制措施”，不是仓库永久信誉。新版本、权限扩大、关键依赖变化或宿主升级都会触发降级和复审。

9.12 风险评分可以排序，不能伪装成真相

可以用影响面、可利用性、可检测性、恢复难度和维护不确定性形成排序，但不要迷信一个总分。两个同为 70 分的插件，可能一个风险在数据出境，另一个风险在不可回滚，处置方式完全不同。

更稳妥的报告同时给出：

• 阻断项：无许可证、来源不可固定、默认上传敏感数据、无法卸载等；
• 剩余风险：采取控制后仍存在的风险；
• 补偿控制：网络白名单、只读账号、人工审批、限额和监控；
• 适用范围：允许的用户、数据、环境和操作；
• 到期条件：何时必须复审。

最终结论只能是带条件的决策，不能写“代码看起来比较规范，所以安全”。

9.13 兼容性矩阵：编译通过不等于行为兼容

DSH 快速迭代时，兼容性至少有四层：包能安装；插件能装载；声明能力能调用；失败、取消、重载和恢复语义仍符合预期。只有前两层通过的插件很容易在演示中成功、在生产边界失败。

建议维护矩阵：

插件提交	DSH 提交	Profile	Node/OS	契约测试	失败测试	结论
固定 SHA	固定 SHA	web/headless	明确版本	通过/失败	通过/失败	等级

测试要针对能力契约而非内部实现。例如 UI 重构不应破坏“取消后无晚到副作用”；Session 存储替换不应破坏“租户 A 无法读取租户 B”。

9.14 升级：先比较能力与权限差异，再跑回归

升级评审不能只看 changelog。应比较新旧版本的入口文件、依赖、安装脚本、注册服务、工具 Schema、外部端点、配置默认值和客户端权限。权限扩大必须由安全和业务责任人显式确认。

flowchart LR N[新版本快照] --> D[物料与能力差异] D --> S{出现阻断项?} S -- 是 --> X[拒绝/等待修复] S -- 否 --> R[历史轨迹与故障回归] R --> C[隔离金丝雀] C --> P[有限生产流量] P --> A[正式批准] C -.异常.-> B[回滚固定旧制品] P -.异常.-> B

历史生产 bad case 应脱敏后进入回归集。对模型相关能力，要固定尽可能多的非确定因素，并把确定性门禁放在模型输出之后。

9.15 退出与卸载是一等能力

生产准入前就要写退出方案：停止接收新任务；等待或取消在途任务；导出需要保留的状态；撤销令牌和 Webhook；卸载插件；清除路由、监听器、定时器和子进程；处理持久数据；验证旧客户端无法继续调用。

如果插件保存了专有格式记忆或业务定义，退出成本会远高于代码替换。领域事实应保存在自有、版本化、可导出的服务中；插件只做适配和编排。这样作者停更时，组织替换入口而不是重建业务真相。

9.16 常见失败模式与诊断

现象	常见根因	先看什么	修复方向
本机可用、服务器装不上	安装脚本、原生二进制或隐式系统依赖	lockfile、生命周期脚本、构建日志	内部构建制品和平台矩阵
升级后工具消失	DSH 注入名、配置结构或入口契约变化	启动树、插件装载错误	固定基线并加能力契约测试
UI 看不到但接口仍可调用	只隐藏前端，没有服务端撤销	路由/RPC 与授权日志	服务端对象级授权
取消后仍提交外部操作	AbortSignal 未传递或副作用不可撤销	工具事件与外部审计时间线	幂等键、可取消客户端、补偿流程
卸载后重复响应	Listener/Timer/子进程未释放	Fiber/Effect 清理与进程表	将外部资源纳入生命周期
日志出现敏感正文	默认调试日志或错误堆栈透传	日志字段和错误序列化	字段白名单、脱敏、分级采样
插件声称只读却改了数据	描述与执行账号/工具实现不一致	数据库审计和真实凭据 Scope	只读账号、策略层拒绝、动态测试
Topic 项目无法作为插件装载	只是兼容声明或标签误用	包入口与 DSH 配置示例	降回 DISCOVERED，不推断兼容

9.17 团队职责：谁批准，谁持续负责

插件准入不是安全团队单方面盖章。平台团队负责 DSH 组合与运行隔离；安全团队负责供应链、身份和数据边界；业务团队确认功能金标准与可接受剩余风险；运维团队负责监控、升级和回滚；插件 Owner 负责版本窗口与事故响应。

每个生产插件必须有内部 Owner、替代方案和复审日期。没有 Owner 的插件即使技术质量很好，也不应默默成为关键路径。

9.18 把准入结论写成机器和人都能执行的契约

一份审查报告若只有长篇分析，发布人员很难知道“到底允许怎样使用”。建议在结论前附一份结构化准入记录，并把它纳入配置仓库评审：

plugin: example-plugin
source:
  repository: https://example.invalid/org/example-plugin
  commit: FULL_COMMIT_SHA
  artifact_sha256: ARTIFACT_DIGEST
compatibility:
  dsh_commit: 47f943859bef60e4160492346772ded9b24f765a
  profiles: [web]
  node: "pinned-by-build-image"
decision:
  level: PILOTED
  expires_at: 2026-11-14
  owner: platform-agent-team
allowed:
  users: [pilot-group]
  data_classes: [synthetic, internal-nonsensitive]
  workspaces: [isolated-project]
  network_hosts: [approved-api.example]
denied:
  actions: [shell, arbitrary-sql, external-publish]
controls:
  approval: high-impact-calls
  max_concurrency: 2
  audit_events: required
rollback:
  artifact: previous-approved-digest
  maximum_time: 15m

这不是要强迫所有企业使用同一种 YAML，而是要求结论具有可执行语义。策略系统可以检查允许的 Profile、网络目标和到期时间；发布系统可以验证摘要；值班人员可以找到 Owner 和回滚制品。报告正文解释为什么，准入记录说明允许什么。

生产观测还要围绕能力边界设置告警：工具拒绝率突然下降可能意味着策略失效；外部目标集合变化可能意味着数据流扩大；卸载后仍有事件说明生命周期泄漏；同一幂等键出现多个外部对象说明重试语义错误。这些指标应关联插件版本、DSH 提交、Session 和工具调用，但日志中不默认复制完整敏感正文。

发生事故时，首要动作通常不是“让模型更谨慎”，而是切断插件入口、撤销凭据、保全事件与网络证据、确认影响对象，再按固定制品回滚。只有把证据字段和停用开关预先设计好，插件生态才具备可运营性。

9.19 如何维护本书的生态快照

生态章节每次发布记录快照日期、查询入口、筛选规则和证据等级。代表性项目用于讲一种架构模式，而不是背书。数量、Star 和更新时间只在带日期的观察中出现，不写成长期价值判断。

更新流程是：重新抓取 Topic；按能力图去重；选取新增架构模式；固定提交做静态审查；必要时完成 Lab；更新证据等级。项目从榜单消失、归档或换许可证，也应作为生态变化记录。

源码路标

• 官方 README：Developer Preview 与社区发现入口
• 插件开发实践：服务、事件与工具组合
• 插件发布：包入口、构建与 Git 安装风险
• 配置机制：插件树与配置替换语义
• 客户端模块：服务端与 Web 扩展边界
• 工具执行流水线：校验、策略与结果
• 权限预设与独立执行旋钮
• 官方测试策略

配套实验

完成 Lab 05：插件供应链审查。选择一个社区项目，先证明它到底是哪一种 DSH 扩展形态，再固定源码与制品，完成能力图、安装期审查、权限/数据流分析、隔离故障实验和退出验证。报告必须把“未观察到”与“证明不存在”分开。

本章小结

开放生态的优势是探索速度，代价是信任面扩大。dsh-plugin Topic 能帮助发现项目，却不会替企业完成身份、权限、数据、兼容性和生命周期治理。真正可生产的对象不是“某个热门仓库”，而是经过固定、审查、验证并由内部 Owner 承担的“插件版本 + DSH 基线 + Profile + 控制措施”。

思考题

1. 一个完全不联网、但能执行 Shell 的插件，为什么仍可能是最高风险等级？
2. 如果 npm 包与仓库 Tag 同名，怎样证明生产安装的字节确实来自已审查源码？
3. 客户端插件只读取浏览器中已有的数据，为什么仍需要独立授权审查？
4. 哪些变化应触发插件从 PRODUCTION_APPROVED 自动降级？
5. 如何用历史事件轨迹构建不依赖模型措辞的兼容性回归？

求职面试题

给你一个热门 DSH 记忆插件和两天时间，请设计准入过程。回答应覆盖不可变物料、服务端/客户端能力图、敏感数据流、权限和提示注入、动态故障实验、版本兼容、生产金丝雀以及退出方案，而不是只展示功能 Demo。