第三章：Cordis 框架基础

// 最简单的插件
function myPlugin(ctx: Context) {
  // 插件逻辑
}

// 带依赖声明的插件
function myPlugin(ctx: Context) {
  // 可以访问 ctx.llm、ctx.tools 等已注册服务
}
myPlugin.inject = ['llm', 'tools']  // 声明依赖

import { Service } from '@deepseek-ai/cordis'

class MyService extends Service {
  // 服务在构造时自动注册
  constructor(ctx: Context) {
    super(ctx, 'myService')  // 注册到 ctx.myService
  }
}

// Context 是一个代理对象
interface Context {
  /** 根上下文 */
  root: this
  /** 事件总线 */
  events: EventsService
  /** 日志服务 */
  logger: LoggerService
  /** 反射层，服务解析 */
  reflect: ReflectService
  /** 插件注册表 */
  registry: RegistryService
  // ... 通过声明合并添加的更多服务
}

// 运行时，Context 是一个 Proxy
class Context {
  constructor() {
    const self = new Proxy(this, ReflectService.handler)
    // ...
    return self
  }
}

// 通过 ctx.provide() 注册
ctx.provide('myService', {
  doSomething() { /* ... */ }
})

// 通过 Service 类注册
class ToolRegistryService extends Service {
  static readonly provide = 'tools'
  
  constructor(ctx: Context) {
    super(ctx, 'tools')
  }
  
  register(tool: ToolSchema) { /* ... */ }
}

function agentLoop(ctx: Context) {
  // ctx.llm、ctx.tools、ctx.sessions 保证已注册
  const llm = ctx.llm
  const tools = ctx.tools
  const sessions = ctx.sessions
}

agentLoop.inject = ['llm', 'tools', 'sessions']

// ctx.effect() 返回一个清理函数
const dispose = ctx.effect(() => {
  // 注册服务
  const service = ctx.provide('myService', { /* ... */ })
  
  // 注册事件监听
  const handler = ctx.on('some-event', (data) => { /* ... */ })
  
  // 返回清理函数
  return () => {
    service.dispose()
    handler.dispose()
  }
})

// 之后调用 dispose() 可以撤销所有注册
dispose()

ctx.emit('session/event', { type: 'user/message', data: { text: 'hello' } })

ctx.waterfall('agent/pre-step', decision, next => {
  // decision 是当前值
  // 调用 next() 委托给下一个监听者
  // 不调用 next() 则短路
  return next({ ...decision, messages: rewritten })
})

await ctx.parallel('some-parallel-event', data)

const result = await ctx.serial('some-serial-event', data)

const result = ctx.bail('some-bail-event', data)

// 监听 agent/pre-step 事件，修改模型输入
ctx.on('agent/pre-step', (decision, next) => {
  // 1. 添加上下文信息
  decision.messages.push({
    role: 'system',
    content: '当前时间: ' + new Date().toISOString()
  })
  
  // 2. 必须调用 next() 来委托
  return next(decision)
})

// 另一个监听者可以进一步修改
ctx.on('agent/pre-step', (decision, next) => {
  // 如果条件不满足，可以短路（不调用 next()）
  if (!decision.messages.length) {
    return  // 短路，不调用 next()
  }
  return next(decision)
})

// 注册顺序：1, 2, 3
const d1 = ctx.effect(() => { /* 注册 A */ return () => { /* 清理 A */ } })
const d2 = ctx.effect(() => { /* 注册 B */ return () => { /* 清理 B */ } })
const d3 = ctx.effect(() => { /* 注册 C */ return () => { /* 清理 C */ } })

// 卸载时：清理 C, 清理 B, 清理 A（反向顺序）

// ctx.isolate() 创建独立的作用域
const isolatedCtx = ctx.isolate('tools', Symbol('myScope'))

// 在隔离作用域下注册的服务不影响父作用域
isolatedCtx.provide('tools', myCustomToolRegistry)

// ctx.intercept() 添加服务特定的配置拦截
const interceptedCtx = ctx.intercept('llm', { provider: 'custom' })

import { Context } from '@deepseek-ai/cordis'

/**
 * 一个简单的工具计数器插件
 * 记录每个工具被调用的次数
 */
export function toolCounterPlugin(ctx: Context) {
  // 依赖声明：需要 tools 服务
  // 在实际 dsh 中，这会是 ctx.tools
  const counts = new Map<string, number>()
  
  // 注册事件监听器
  const disposable = ctx.on('tool/result', (result) => {
    const name = result.toolName
    counts.set(name, (counts.get(name) ?? 0) + 1)
    ctx.logger('tool-counter').info(`Tool "${name}" called ${counts.get(name)} times`)
  })
  
  // 提供一个查询服务
  ctx.provide('toolCounts', {
    getCount(toolName: string): number {
      return counts.get(toolName) ?? 0
    },
    getAllCounts(): Map<string, number> {
      return new Map(counts)
    }
  })
  
  // 返回清理函数
  return () => {
    disposable.dispose()
    // toolCounts 会随 Fiber 卸载自动清理
  }
}

// 声明依赖
toolCounterPlugin.inject = ['tools']

# cordis.patch.yml
- id: my-tool-counter
  config: {}

// package.json
{
  "dsh": {
    "plugins": {
      "my-tool-counter": "./path/to/tool-counter.ts"
    }
  }
}

# 基本格式
- id: plugin-id
  name: @scope/plugin-name
  config:
    key: value

- id: my-plugin
  config:
    # !!js 表达式在加载时求值
    apiKey: !!js process.env.API_KEY
    # disabled 也可以是 !!js 表达式
  disabled: !!js process.env.NODE_ENV === 'production'