Cordis 框架：DeepSeek Harness 的插件地基

Cordis 的上游是 github.com/cordiverse/cordis，其设计写在一篇论文《A Programming Paradigm for Spatiotemporal Composability》里。dsh 仓库的 vendor/ 目录是带上游 SHA 清单的固定源码副本，同步流程写在 vendor/README.md。

vendor 进来的包被重新命名（rescope）为 @deepseek-ai/* 且标记为 private: true。@deepseek-ai/cordis 是每个 harness 包的 peerDependency（同伴依赖，即由使用方提供而不是重复安装）。vendor 引入与分层的关系见架构总览。

写作红线：Cordis 不是 DeepSeek 自研，任何"DeepSeek 开发的 Cordis"表述都是错的。

出自官方 docs/cordis-primer.zh.md：

1. 插件：一个实现 Service 的对象——可以是带 inject 声明和 apply(ctx) 方法的函数，也可以是 Service 子类。
2. 上下文（Context）：服务容器。每个服务占据一个稳定的键名，比如 ctx.tools、ctx.sessions。
3. 依赖注入（inject）：插件用 inject 声明自己依赖哪些服务，Cordis 等依赖就绪后才启动它。
4. 类型化事件：插件之间靠类型化事件通信（下一节展开）。
5. 可逆注册：注册是可逆副作用——用 ctx.effect() / ctx.on() 注册的东西，在插件 reload（重载）或 teardown（卸载）时会被撤销。这就是 dsh"插件卸载时撤销注册"的底层机制（插件系统如何用这个机制，见插件系统页）。

示意图点击放大

Cordis 的事件有四种分发模式，分发模式是事件公开约定的一部分，官方源码里用 @mode 标签记录：

示意图点击放大

新手最常踩的坑有两个：

• emit 和 waterfall 都不会等待监听器完成。需要等监听器跑完，得用 serial 或 parallel；其中只有 serial 会带回返回值。
• waterfall 监听器必须调 next() 才能把处理委托给下游。监听器收到 (...args, next)；调用 next() 可以委托下游并包装返回值；不调 next() 直接 return，是"短路"（后面的人收不到），不是"透传"。官方 AGENTS.md 用 MUST 级别的措辞强调这一点。prepend: true 只在该监听器必须先于普通注册运行时才用。

• Cordis 的 Loader 配置由 @deepseek-ai/cordis-plugin-include 处理：!!js 会被解析为表达式节点（注意是 !!js 两个感叹号，不是 !js）。config 基于插件上下文插值，disabled 在每次挂载决策时基于 loader 上下文插值；需要按环境选择插件时应使用 overlay（覆盖层）。
• cordis.yml 里只允许 !!js 出现在插件的 config 和条目的 disabled 下，其余元数据保持字面值。
• 配置文件有三种形态：cordis.yml（插件树）、cordis.patch.yml（按 id 覆盖或插入条目）、cordis.snapshot.yml（快照回放替换，只识别特定文件 basename）。前两种在本站《Profile / 组合包 / Patch》页有展开。

你不写插件的话，不需要掌握 Cordis API。但有两个场景绕不开它：一是改 cordis.patch.yml 调整配置时，你其实就是在写 Cordis 配置（见教程《Profile 与配置分层》）；二是排查"插件装了没生效"时，理解"注册是可逆副作用、Bundle 层变更要重启"（教程实测口径，详见插件系统页第 4 节）能省很多时间。把 Cordis 想成 dsh 世界的"地基图纸"：不用会画，但看得懂图例很有用。