第一个插件：函数插件三件套

一、创建项目骨架Scaffold

在仓库根目录下建练习目录，目标结构：

mkdir -p scratch-plugin/src

scratch-plugin/
├── cordis.yml      # 声明"挂哪些插件"的配置（下一步创建）
└── src/
    └── my-plugin.ts  # 你的插件本体

二、写插件本体The Plugin

创建 scratch-plugin/src/my-plugin.ts：

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

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  // 走到这里，inject 声明的依赖都已就绪（本例没有依赖）
  console.log('[hello-plugin] plugin loaded!')
}

三、写配置并挂载Mount It

先在仓库根目录跑 pwd 拿到绝对路径，然后创建 scratch-plugin/cordis.yml（路径必须是绝对的）：

- insert:
    - id: hello
      name: '/把这里换成pwd输出的绝对路径/scratch-plugin/src/my-plugin.ts'

pnpm dsh web --patch ./scratch-plugin/cordis.yml

启动时终端会打印 [hello-plugin] plugin loaded!——你的第一个插件已在一棵完整的产品插件树里运行。相当于给一辆行驶中的车换了个零件。

四、体验"注册即效果"Feel the Effect

把插件改成会心跳的版本（ctx.effect 的标准用法）：

export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => {
      console.log('[hello-plugin] heartbeat')
    }, 5000)
    return () => clearInterval(timer)   // 卸载时自动执行
  })
}

任何注册在 ctx 上的东西——监听器、工具、定时器——插件卸载时自动清理，无需手写 removeListener / clearInterval。

五、声明依赖Dependencies

要用别人的服务（比如工具注册表），在 inject 里声明：

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

export const name = 'my-tool-plugin'
export const inject = ['tools']          // ← 等到 ctx.tools 就绪才加载我

export function apply(ctx: Context) {
  ctx.tools.register(/* ... */)   // 此处 ctx.tools 必然可用
}

六、三种插件形态Three Forms

// ① 函数形式（本课主角，大多数场景够用）
export const name = 'my-plugin'
export function apply(ctx: Context) { /* ... */ }

// ② 对象形式：同样三件套，收进一个对象
export default {
  name: 'my-plugin',
  inject: ['tools'],
  apply(ctx: Context) { /* ... */ },
}

// ③ 类形式：继承 Service，适合"给别人提供服务"（L16 专讲）
import { Service } from '@deepseek-ai/cordis'
export default class MyService extends Service {
  static inject = ['tools']
  constructor(ctx: Context) { super(ctx, 'myService') }
}