// 文件路径：scratch-plugin/src/my-plugin.ts
import type { Context } from '@deepseek-ai/cordis'

// name 是插件名，用于在日志与配置中标识这个插件
export const name = 'hello-plugin'

// apply 是插件的入口：框架加载插件时调用它
export function apply(ctx: Context) {
   // 在这里注册工具、服务、事件等能力
}

// 文件路径：scratch-plugin/src/my-plugin.ts（函数形式）
import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-plugin'

export function apply(ctx: Context) {
  // 在这里注册能力
}

// 对象形式：一个默认导出对象
import type { Context } from '@deepseek-ai/cordis'

export default {
  name: 'my-plugin',
  inject: ['tools'],
  apply(ctx: Context) {
    // ...
  },
}

// 类形式：Service 子类，可对外提供服务
import { Service, type Context } from '@deepseek-ai/cordis'

export default class MyService extends Service {
  static inject = ['tools']

  constructor(ctx: Context) {
    // 第一个参数是 ctx，第二个参数是服务名
    super(ctx, 'myService')
    // 同步初始化放在构造函数里
  }
}

// 文件路径：scratch-plugin/src/heartbeat.ts
import type { Context } from '@deepseek-ai/cordis'

export function apply(ctx: Context) {
  ctx.effect(() => {
    // 创建定时器：每 5 秒打印一次 heartbeat
    const timer = setInterval(() => {
      console.log('heartbeat')
    }, 5000)

    // 返回的清理函数在插件卸载时执行
    // 等价于：不需要你在卸载逻辑里手动 clearInterval
    return () => clearInterval(timer)
  })
}

// 文件路径：scratch-plugin/src/my-tool-plugin.ts
import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-tool-plugin'
// 声明依赖：需要 tools 服务
export const inject = ['tools']

export function apply(ctx: Context) {
  // 走到这里时，ctx.tools 一定已就绪
  ctx.tools.register(/* ... */)
}

// 可选依赖：省略 inject，用 ctx.get() 查询
import type { Context } from '@deepseek-ai/cordis'

export function apply(ctx: Context) {
  // metrics 服务可能在也可能不在
  const metrics = ctx.get('metrics')
  // 可选链：不存在就跳过，不报错
  metrics?.record('plugin_loaded', 1)
}

// 文件路径：scratch-plugin/src/my-plugin.ts
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
// 需要 tools 服务：注册工具的前提
export const inject = ['tools']

export function apply(ctx: Context) {
  // 注册一个名为 greet 的工具
  ctx.tools.register(defineTool({
    // 工具名：模型会以这个名字发起调用
    name: 'greet',
    // 工具说明：告诉模型什么时候用
    description: 'Greet someone by name.',
    // 入参 schema：defineTool 会推导并校验 args
    parameters: {
      name: { type: 'string', required: true, description: 'The name to greet' },
    },
    // 输出定义
    output: {
      // 规范值类型：execute 的返回值
      schema: { type: 'string' },
      // render：把规范值转成面向模型的内容
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    // 工具实现：真正执行逻辑
    async execute(args) {
      // 返回规范值，这里是一个字符串
      return `Hello, ${args.name}!`
    },
  }))
}

// 文件路径：scratch-plugin/src/my-plugin.ts
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'

export const name = 'my-plugin'

// Config 接口：定义插件接受哪些配置项
export interface Config {
  greeting: string    // 问候语
  maxRetries: number  // 最大重试次数
  verbose?: boolean   // 是否输出详细日志（可选）
}

// 同名的 Config schema：默认值写在这里
export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  maxRetries: Schema.number().default(3),
  verbose: Schema.boolean().default(false),
})

// apply 的第二个参数就是校验后的配置
export function apply(ctx: Context, config: Config) {
  // 打印的是用户传入的值或 schema 默认值
  console.log(config.greeting)
}

// 文件路径：scratch-plugin/src/validated-plugin.ts
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'

export const name = 'validated-plugin'

export interface Config {
  apiKey: string                 // 必填
  timeout: number                // 超时毫秒数
  mode: 'fast' | 'accurate'      // 只能取这两个值之一
}

export const Config = Schema.object({
  apiKey: Schema.string().required(),
  timeout: Schema.number().default(30000),
  mode: Schema.union(['fast', 'accurate']).default('fast'),
})

export function apply(ctx: Context, config: Config) {
  // config 已经过校验，类型安全
}

// 错误：把超时时间硬编码
const TIMEOUT = 30000

// 正确：定义为配置字段，默认值仍由 schema 提供
export interface Config {
  timeoutMs: number  // 默认 30000
}

// 文件路径：scratch-plugin/src/use-tools.ts
// 声明依赖 tools 服务
export const inject = ['tools']

export function apply(ctx: Context) {
  // ctx.tools 一定存在且已就绪
  ctx.tools.register(/* ... */)
}

// 文件路径：scratch-plugin/src/metrics-service.ts
import { Service, type Context } from '@deepseek-ai/cordis'

// 写一个指标服务，继承Service基类
export default class MetricsService extends Service {
  // static inject：这个服务自身还要依赖别的服务！
  static inject = ['llm']

  constructor(ctx: Context) {
    // super(上下文, "服务名字")
    // 这句执行完，内核自动把实例挂载到 ctx.metrics
    super(ctx, 'metrics')
  }

  // 对外暴露给其他插件调用的方法
  record(event: string, value: number) {
    console.log("指标记录：", event, value)
  }
}

// 文件路径：scratch-plugin/src/use-metrics.ts
// 消费方声明依赖 metrics 服务
export const inject = ['metrics']

export function apply(ctx: Context) {
  // 调用服务方法：记录一次工具调用
  ctx.metrics.record('runoob_tool_call', 1)
}

// 文件路径：scratch-plugin/src/metrics-service.ts
import { Service, type Context } from '@deepseek-ai/cordis'

// 声明合并：告诉 TypeScript，Context 上有一个 metrics 字段
declare module '@deepseek-ai/cordis' {
  interface Context {
    metrics: MetricsService
  }
}

export default class MetricsService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'metrics')
  }

  record(event: string, value: number) {
    /* 实现省略 */
  }
}

# 文件路径：scratch-plugin/cordis.yml
# 定义两个插件组 group-a 与 group-b，各自隔离一份 shell 服务
- id: group-a
  name: '@deepseek-ai/cordis-plugin-group'
  group: true
  isolate:
    shell: true              # 让本组内的 shell 服务独立实例化
  config:
    - name: '@deepseek-ai/dsh-bash-local'
      config:
        timeoutMs: 5000      # group-a 的 Bash 超时 5 秒
    - name: './src/plugin-a.ts'

- id: group-b
  name: '@deepseek-ai/cordis-plugin-group'
  group: true
  isolate:
    shell: true
  config:
    - name: '@deepseek-ai/dsh-bash-local'
      config:
        timeoutMs: 60000     # group-b 的 Bash 超时 60 秒
    - name: './src/plugin-b.ts'

// 监听事件：注册一个回调
ctx.on('event-name', (payload) => {
  // 处理事件
})

// 触发事件：广播给所有监听器
ctx.emit('event-name', payload)

// 文件路径：packages/my-cap/my-cap/src/index.ts
import { Service, type Context } from '@deepseek-ai/cordis'

// 声明合并：让 ctx.myCap 在 TypeScript 里有类型提示
declare module '@deepseek-ai/cordis' {
  interface Context {
    myCap: MyCapService
  }
}

// 抽象类：Definition 包只声明契约，不写实现
export abstract class MyCapService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'myCap') // 注册为命名服务 ctx.myCap
  }

  /** Execute the capability. */
  abstract execute(request: MyCapRequest): Promise<MyCapResult>
}

// 请求类型：调用方必须提供 input
export interface MyCapRequest {
  input: string
}

// 结果类型：能力返回 output
export interface MyCapResult {
  output: string
}

// 文件路径：packages/my-cap/my-cap-local/src/index.ts
import type { Context } from '@deepseek-ai/cordis'
import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/dsh-my-cap'

// 实现类：只依赖 Definition 包
class MyCapLocal extends MyCapService {
  async execute(request: MyCapRequest): Promise<MyCapResult> {
    // Local provider behavior.
    return { output: request.input.toUpperCase() }
  }
}

export const name = 'my-cap-local'

export function apply(ctx: Context) {
  // 把实现类作为插件加载，注册成 ctx.myCap 的实际服务
  ctx.plugin(MyCapLocal)
}

// 文件路径：packages/my-cap/tool-my-cap/src/index.ts
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'tool-my-cap'
// 依赖声明：tools 提供注册入口，myCap 提供服务实现
export const inject = ['tools', 'myCap']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'my_cap', // 面向模型的工具名
    description: 'Execute my capability.',
    // 参数 schema：模型按它生成参数
    parameters: {
      input: { type: 'string', required: true },
    },
    // 输出 schema 与渲染方式
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    // 真正执行：调用能力服务
    async execute(args) {
      const result = await ctx.myCap.execute({ input: args.input })
      return result.output
    },
  }))
}

# 文件路径：cordis.yml
# 先加载 Provider，让 ctx.myCap 有实现
- name: '@deepseek-ai/dsh-my-cap-local'

# 再加载 Consumer，让模型能用 my_cap 工具
- name: '@deepseek-ai/dsh-tool-my-cap'

// 文件路径：src/my-llm-adapter.ts
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'

// 适配器：继承抽象类，实现 stream()
class MyAdapter extends LlmAdapter {
  private apiKey: string

  constructor(apiKey: string) {
    super()
    this.apiKey = apiKey
  }

  // stream() 返回异步生成器，逐片产出 StreamChunk
  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
    // 1. Convert options.messages to the provider format.
    // 2. Call the streaming API.
    // 3. Convert the response into StreamChunk values.
  }
}

// 插件配置：apiKey 与 providers 都必填
export interface Config {
  apiKey: string
  providers: string[]
}

// 同名的 Schemastery schema，加载时校验配置
export const Config: Schema<Config> = Schema.object({
  apiKey: Schema.string().required(),
  providers: Schema.array(Schema.string()).required(),
})

export const name = 'my-llm-adapter'
// 声明依赖 llm 服务，保证 ctx.llm 已就绪
export const inject = ['llm']

export function apply(ctx: Context, config: Config) {
  const adapter = new MyAdapter(config.apiKey)
  // 把提供方路由列表绑定到这个适配器
  ctx.llm.registerAdapter(config.providers, adapter)
}

# 文件路径：cordis.yml
# 加载适配器插件，apiKey 从环境变量读取
- id: my-llm
  name: './src/my-llm-adapter.ts'
  config:
    apiKey: !!js process.env.MY_API_KEY
    providers:
     - my-provider

# 配置 agent-loop 使用新适配器的 provider 与 model
- id: agent-loop
  name: '@deepseek-ai/dsh-agent-loop'
  config:
    agents:
      - id: main
        provider: my-provider
        model: my-model-v1