02 · Cordis

1. 为什么必须先学 Cordis

可以先把 Cordis 粗略理解成：

Dependency Injection
+
Plugin Runtime
+
Lifecycle Manager
+
Typed Event Bus
+
Hierarchical Scope

2. Context

ctx 不是“全局变量袋子”，而是当前作用域里的 Service Repository。消费者通过 ctx.llm、ctx.tools、ctx.sessions 请求能力，不直接 import 某个 provider。

3. Plugin / Service / inject

Plugin 安装行为或能力；Service 通过 Context 暴露长期能力；inject 声明依赖，让启动顺序成为 dependency graph 的结果。

plugin needs: llm + tools + sessions
        │
        ▼
Cordis resolves dependency graph
        │
        ▼
plugin mounts only when dependencies are ready

4. Effect：注册是可逆的

mount plugin
   ↓
register tool / listener / provider / prompt section
   ↓
effect alive
   ↓
unmount
   ↓
undo effect

因此插件卸载后，自己注册的工具、监听器、prompt section 等应该自然消失。

5. Event 与 Waterfall

Agent
 │
 ▼
permission plugin
 │ next()
 ▼
sandbox plugin
 │ next()
 ▼
metrics plugin
 │ next()
 ▼
actual executor

某一层如果不调用 next()，链条就被 short-circuit。权限、sandbox、retry、metrics、redaction 都可以独立组合。

6. Scope

Global:
  read_file
  grep
  bash

Agent A:
  + deploy_production

Agent B:
  + database_query
  - bash

不要写 if (agent.id === ...)，而应该让 registration 进入相应 Agent 的 scoped context。