dsh-plugin-guide 0.3.41 → 0.4.0

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md

@@ -1,21 +0,0 @@
----
-kind: upgrade-guide
-description: "Plugin compatibility checks read engines.dsh before DSH peerDependencies, and refusals report requirements instead of peers."
----
-
-# Plugin compatibility reads `engines.dsh` first
-
-English | [中文](guide.zh.md)
-
-## Change
-
-In v0.2.1-alpha.3, installation and profile startup judged a plugin or bundle only by its `peerDependencies` on `@deepseek-ai/dsh` and `@deepseek-ai/dsh-*`, and ignored `engines.dsh`. In the next release, an own `engines.dsh` range decides alone and those peers are ignored; the peer rule applies only when `engines.dsh` is absent. `workspace:` values are valid only in peers; in `engines.dsh` they are incompatible. A non-object `engines` or a non-string `engines.dsh` makes the manifest unreadable for compatibility, which refuses the package. Plugin authors whose package declares `engines.dsh`, or declares `engines` as something other than an object, are affected.
-
-The `incompatible-version` refusal record that the plugin manager returns to clients, `IncompatiblePlugin`, and the app-boot `PluginCompatibility` result rename `peers` to `requirements`. Keys are `engines.dsh` for the engines rule or the peer package name for the fallback. Code that reads these records is affected.
-
-## Migration
-
-1. If your package declares `engines.dsh`, make that range cover every DSH release the package supports, because DSH peer ranges no longer widen or narrow it. Remove `engines.dsh` to keep peer-based checking.
-2. Replace `workspace:` values in `engines.dsh` with a semantic version range.
-3. Read `requirements` instead of `peers` from `IncompatiblePlugin` and `PluginCompatibility`.
-4. Confirm by installing the package with `dsh plugin --profile <profile> add <package@version>` or the plugin manager: a mismatch names `engines.dsh` or the peer package in the refusal.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.zh.md

@@ -1,21 +0,0 @@
----
-kind: upgrade-guide
-description: "插件兼容性检查先读 engines.dsh，再读 DSH peerDependencies；拒绝记录改用 requirements 代替 peers。"
----
-
-# 插件兼容性先读 `engines.dsh`
-
-[English](guide.md) | 中文
-
-## 变更
-
-在 v0.2.1-alpha.3 中，安装和 profile 启动只依据插件或组合包在 `peerDependencies` 中对 `@deepseek-ai/dsh` 和 `@deepseek-ai/dsh-*` 的声明判定兼容性，忽略 `engines.dsh`。下一版本中，包自身的 `engines.dsh` 范围单独决定结果，并忽略这些 peer；只有缺少 `engines.dsh` 时才使用 peer 规则。`workspace:` 值只在 peer 中有效；出现在 `engines.dsh` 中时视为不兼容。`engines` 不是对象或 `engines.dsh` 不是字符串时，兼容性检查无法读取清单，该包会被拒绝。受影响的是声明了 `engines.dsh`，或把 `engines` 声明为非对象值的插件作者。
-
-插件管理器返回给客户端的 `incompatible-version` 拒绝记录 `IncompatiblePlugin`，以及 app-boot 的 `PluginCompatibility` 结果，将 `peers` 重命名为 `requirements`。按 engines 规则判定时键为 `engines.dsh`，回退到 peer 规则时键为 peer 包名。读取这些记录的代码受影响。
-
-## 迁移
-
-1. 如果包声明了 `engines.dsh`，让该范围覆盖包支持的所有 DSH 版本，因为 DSH peer 范围不再放宽或收窄它。删除 `engines.dsh` 可保留基于 peer 的检查。
-2. 将 `engines.dsh` 中的 `workspace:` 值替换为语义化版本范围。
-3. 从 `IncompatiblePlugin` 和 `PluginCompatibility` 读取 `requirements`，不再读取 `peers`。
-4. 用 `dsh plugin --profile <profile> add <package@version>` 或插件管理器安装该包确认迁移：不匹配时，拒绝信息会列出 `engines.dsh` 或对应 peer 包。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.4/account-notification-fields/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-alpha.4/account-notification-fields/guide.md
-/:
-  en: 9b6666d42852a11b
-  zh: b14c7d8590c54ba5
-/update-account-notification-consumers:
-  en: 586faed9ab20343f
-  zh: fb3cc099b39b0386
-/update-account-notification-consumers/change:
-  en: 20cc8ba42b771270
-  zh: da0ca5f650c74117
-/update-account-notification-consumers/migration:
-  en: e9fe0c1ebba8acfc
-  zh: 05b94685fb4c5ead

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.4/account-notification-fields/guide.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "AccountBonusNotification exposes unvalidated optional metadata and permits notices without an expiry."
----
-
-# Update account notification consumers
-
-English | [中文](guide.zh.md)
-
-## Change
-
-The public `AccountBonusNotification` returned by `DeepSeekAccount.getUnnotifiedBonuses()` and `account/getUnnotifiedBonuses` preserves `campaign`, `amount`, `currency`, and `grantedAt` as optional, unvalidated metadata typed as `JsonValue`. Notifications retain `orderId`, `message`, and `expiresAt`, and add an optional `title`. An empty `expiresAt` means the notification never expires. `orderId` accepts arbitrary strings rather than requiring UUIDs.
-
-## Migration
-
-1. Narrow the optional metadata values before using them; their presence and format are no longer guaranteed. Display `message` and use the client's default title when `title` is absent.
-2. Treat an empty `expiresAt` as no expiry before parsing timestamps. Keep `orderId` unchanged when acknowledging a notification.
-3. Update provider fixtures to use the current fields. Confirm that a notification with a non-UUID ID and empty expiry displays and can be acknowledged.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.4/account-notification-fields/guide.zh.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "AccountBonusNotification 提供未经校验的可选元数据，并允许通知永不过期。"
----
-
-# 更新账号通知使用方
-
-[English](guide.md) | 中文
-
-## 变更
-
-`DeepSeekAccount.getUnnotifiedBonuses()` 和 `account/getUnnotifiedBonuses` 返回的公开类型 `AccountBonusNotification` 保留 `campaign`、`amount`、`currency` 和 `grantedAt`，作为类型为 `JsonValue` 的可选元数据，不做校验。通知保留 `orderId`、`message` 和 `expiresAt`，并新增可选的 `title`。空字符串 `expiresAt` 表示通知永不过期。`orderId` 接受任意字符串，不再要求 UUID 格式。
-
-## 迁移
-
-1. 使用可选元数据前先收窄类型；这些值不再保证存在或符合原有格式。展示 `message`，在 `title` 缺省时使用客户端默认标题。
-2. 解析时间戳前，将空字符串 `expiresAt` 视为永不过期。确认通知时原样传递 `orderId`。
-3. 更新提供者测试夹具以使用当前字段。确认非 UUID 标识、空过期时间的通知可以展示并确认。

package/references/official-docs/docs/user/develop/basic/config.i18n.yaml

@@ -1,28 +0,0 @@
-# Bilingual-pair consistency record for config.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/user/develop/basic/config.md
-/plugin-configuration:
-  en: f605e6e8021b82ba
-  zh: 3f33c4b0afb3f249
-/plugin-configuration/define-the-config-type:
-  en: a351a086d890f148
-  zh: 385803dd9d671391
-/plugin-configuration/schema-validation:
-  en: 6a20f3351a1c3e47
-  zh: b5ae56917fcbca2c
-/plugin-configuration/design-principles:
-  en: 79717ddc9d714ad9
-  zh: 67240f8382bbe783
-/plugin-configuration/design-principles/do-not-hardcode-tunable-values:
-  en: da67063750a52b55
-  zh: bd2c5978e10b6f79
-/plugin-configuration/design-principles/fail-loudly-on-invalid-configuration:
-  en: 98a4ff7d959783bd
-  zh: cb1410360b03b7a7
-/plugin-configuration/work-with-hmr:
-  en: 939f750af6fefbd5
-  zh: 94fbb3a0d761f098
-/plugin-configuration/next-steps:
-  en: 1151bb8b59577519
-  zh: 47a95340df47d273

package/references/official-docs/docs/user/develop/basic/config.md

@@ -1,106 +0,0 @@
-# Plugin configuration
-
-English | [中文](config.zh.md)
-
-Accept configuration supplied through `cordis.yml`.
-
-## Define the Config type
-
-Export a `Config` type and a same-named Schemastery schema. Put defaults directly on the schema fields:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-
-export const name = 'my-plugin'
-
-export interface Config {
-  greeting: string
-  maxRetries: number
-  verbose?: boolean
-}
-
-export const Config: Schema<Config> = Schema.object({
-  greeting: Schema.string().default('Hello'),
-  maxRetries: Schema.number().default(3),
-  verbose: Schema.boolean().default(false),
-})
-
-export function apply(ctx: Context, config: Config) {
-  console.log(config.greeting)  // User value or schema default.
-}
-```
-
-Add the configuration to the inserted local plugin row in `scratch-plugin/cordis.yml`:
-
-```yaml
-- insert:
-    - id: hello
-      name: './src/my-plugin.ts'
-      config:
-        greeting: 'Hi there'
-        maxRetries: 5
-```
-
-When loading the plugin, Cordis uses the exported schema to validate configuration and fill defaults. Do not export a plain object as `Config`; it does not implement the Standard Schema interface required by Cordis.
-
-## Schema validation
-
-Use Schemastery to express stricter validation:
-
-```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 is validated and type-safe.
-}
-```
-
-The schema runs while the plugin loads. Invalid configuration fails the load with an actionable error.
-
-## Design principles
-
-### Do not hardcode tunable values
-
-Harness requires **anything that two deployments may want to set differently to be a configuration field**.
-
-```ts
-// Wrong: hardcoded timeout.
-const TIMEOUT = 30000
-
-// Correct: configurable.
-export interface Config {
-  timeoutMs: number  // Defaults to 30000.
-}
-```
-
-The test is whether `cordis.yml` can change the value without a code edit.
-
-### Fail loudly on invalid configuration
-
-Express self-contained constraints in the schema so invalid configuration fails while the plugin loads. References to services or registered resources require dependency injection; the [services tutorial](../framework/service.md) introduces that contract.
-
-## Work with HMR
-
-A configuration edit hot-replaces the plugin: the framework unloads the old instance and loads a new one. Because registrations are effects and clean themselves up, replacement does not retain the old instance's registrations.
-
-## Next steps
-
-- [Package and install a plugin](./publish.md) — ship the plugin as an installable package
-- [Plugins and lifecycle](../framework/index.md) — understand the full plugin lifecycle
-- [Services and dependencies](../framework/service.md) — provide a service to other plugins

package/references/official-docs/docs/user/develop/basic/config.zh.md

@@ -1,106 +0,0 @@
-# 插件配置
-
-[English](config.md) | 中文
-
-让你的插件接受用户在 `cordis.yml` 中传入的配置。
-
-## 定义 Config 类型
-
-在插件中导出一个 `Config` 类型和同名的 Schemastery schema；默认值直接写在 schema 中：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-
-export const name = 'my-plugin'
-
-export interface Config {
-  greeting: string
-  maxRetries: number
-  verbose?: boolean
-}
-
-export const Config: Schema<Config> = Schema.object({
-  greeting: Schema.string().default('Hello'),
-  maxRetries: Schema.number().default(3),
-  verbose: Schema.boolean().default(false),
-})
-
-export function apply(ctx: Context, config: Config) {
-  console.log(config.greeting)  // User value or schema default.
-}
-```
-
-在 `scratch-plugin/cordis.yml` 新插入的本地插件行中添加配置：
-
-```yaml
-- insert:
-    - id: hello
-      name: './src/my-plugin.ts'
-      config:
-        greeting: 'Hi there'
-        maxRetries: 5
-```
-
-插件加载时，Cordis 会通过导出的 schema 校验配置，并填充未提供字段的默认值。不要导出普通对象作为 `Config`，因为它不满足 Cordis 要求的 Standard Schema 接口。
-
-## Schema 校验
-
-对于需要严格校验的场景，使用 Schemastery 定义 schema：
-
-```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 is validated and type-safe.
-}
-```
-
-Schema 在插件加载时执行校验。如果配置不合法，插件会加载失败并给出明确错误信息。
-
-## 设计原则
-
-### 无硬编码可调参数
-
-Harness 的约定：**凡是不同部署可能需要采用不同值的参数，都必须定义为配置字段**。
-
-```ts
-// Wrong: hardcoded timeout.
-const TIMEOUT = 30000
-
-// Correct: configurable.
-export interface Config {
-  timeoutMs: number  // Defaults to 30000.
-}
-```
-
-检验标准：能否在 `cordis.yml` 中改变这个值，而不需要修改代码？
-
-### 配置错误要响亮
-
-在 schema 中表达自身完备的约束，使无效配置在插件加载时失败。对服务或已注册资源的引用需要依赖注入；[服务教程](../framework/service.zh.md) 会介绍这项约定。
-
-## 配合 HMR
-
-配置变更会触发插件热替换：修改 `cordis.yml` 中某个插件的 `config` 后，框架会卸载旧实例并加载新实例。由于注册都属于 effect 并会自动清理，替换后不会保留旧实例的注册。
-
-## 下一步
-
-- [打包与安装插件](./publish.zh.md) — 把插件以可安装包的形式交付
-- [插件与生命周期](../framework/index.zh.md) — 深入了解插件的完整生命周期
-- [服务与依赖](../framework/service.zh.md) — 让你的插件对外提供服务

package/references/official-docs/docs/user/develop/basic/index.i18n.yaml

@@ -1,37 +0,0 @@
-# Bilingual-pair consistency record for index.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/user/develop/basic/index.md
-/your-first-plugin:
-  en: 66684c875e13acbb
-  zh: 48b5444386cf714c
-/your-first-plugin/create-a-local-project:
-  en: 2a9ff85da3a6ea8b
-  zh: 9ac5daf1dd3e3b95
-/your-first-plugin/what-is-a-plugin:
-  en: 0bca3ea987fecb61
-  zh: b4d398b887da6648
-/your-first-plugin/create-the-plugin-file:
-  en: 80e4e9f139d4773e
-  zh: c045d63ec04a2f3d
-/your-first-plugin/register-it-in-cordis-yml:
-  en: 216e79287d237f2a
-  zh: 16e5e8ad2b1b9263
-/your-first-plugin/automatic-cleanup:
-  en: 0a1486714b9d67d7
-  zh: 544df97baa7a8c59
-/your-first-plugin/declare-dependencies:
-  en: da59e4c09e258f94
-  zh: 1b3ef70741eccb31
-/your-first-plugin/three-plugin-forms:
-  en: 155369321743b317
-  zh: e2e98be100be297b
-/your-first-plugin/three-plugin-forms/object-form:
-  en: d674c416f5b0fd14
-  zh: a2224f5fe6ceae73
-/your-first-plugin/three-plugin-forms/class-form:
-  en: 130f504f9ebacebd
-  zh: 4e91d3fa2555390d
-/your-first-plugin/next-steps:
-  en: 9836e246d8279c8b
-  zh: 681475e2251ba006

package/references/official-docs/docs/user/develop/basic/index.md

@@ -1,144 +0,0 @@
-# Your first plugin
-
-English | [中文](index.zh.md)
-
-This tutorial creates a minimal Harness plugin and loads it into the Web UI. Start from a repository checkout that has completed the [run-from-source path](../../../../README.md#run-from-source).
-
-## Create a local project
-
-From the repository root, create a scratch project for the tutorial:
-
-```sh
-mkdir -p scratch-plugin/src
-```
-
-## What is a plugin?
-
-In Harness, a plugin is a TypeScript module that exports an `apply` function. The framework calls `apply` when loading the plugin and passes a `ctx` context object through which the plugin registers capabilities:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'my-plugin'
-
-export function apply(ctx: Context) {
-  // Register capabilities here.
-}
-```
-
-That is the complete configuration.
-
-## Create the plugin file
-
-Create `scratch-plugin/src/my-plugin.ts`:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'hello-plugin'
-
-export function apply(ctx: Context) {
-  // Required dependencies are ready before apply runs.
-  console.log('[hello-plugin] plugin loaded!')
-}
-```
-
-## Register it in cordis.yml
-
-Run `pwd` from the repository root, then create `scratch-plugin/cordis.yml` as a Web overlay that inserts the local plugin. Replace `/absolute/path/to/deepseek-harness` below with the printed path:
-
-```yaml
-- insert:
-    - id: hello
-      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
-```
-
-The plugin path must be absolute. A patch file contributes configuration but does not change the profile directory from which the loader resolves module paths.
-
-Start the Web UI with that overlay:
-
-```sh
-pnpm dsh web --patch ./scratch-plugin/cordis.yml
-```
-
-Open `http://127.0.0.1:3080`. The terminal prints `[hello-plugin] plugin loaded!` during startup.
-
-## Automatic cleanup
-
-Anything registered through `ctx`—event listeners, tools, or timers—is cleaned up when the plugin unloads. You do not need to call removeListener or clearInterval manually.
-
-For a resource that needs explicit cleanup, such as a network connection, use `ctx.effect()` to provide its disposer:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export function apply(ctx: Context) {
-  ctx.effect(() => {
-    const timer = setInterval(() => {
-      console.log('heartbeat')
-    }, 5000)
-
-    // The returned function runs when the plugin unloads.
-    return () => clearInterval(timer)
-  })
-}
-```
-
-## Declare dependencies
-
-If the plugin consumes another service such as `tools` or `llm`, declare it in `inject`:
-
-```ts ignore-check
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'my-tool-plugin'
-export const inject = ['tools']
-
-export function apply(ctx: Context) {
-  // ctx.tools is ready here.
-  ctx.tools.register(/* ... */)
-}
-```
-
-The framework waits for every required service before loading the plugin.
-
-## Three plugin forms
-
-In addition to a function module, a plugin can use object or class form.
-
-### Object form
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export default {
-  name: 'my-plugin',
-  inject: ['tools'],
-  apply(ctx: Context) {
-    // ...
-  },
-}
-```
-
-### Class form
-
-```ts
-import { Service, type Context } from '@deepseek-ai/cordis'
-
-export default class MyService extends Service {
-  static inject = ['tools']
-
-  constructor(ctx: Context) {
-    super(ctx, 'myService')
-    // Perform synchronous initialization in the constructor.
-  }
-}
-```
-
-Function form is sufficient in most cases. Use class form when the plugin provides a service to other plugins; see [services and dependencies](../framework/service.md).
-
-## Next steps
-
-- [Build a tool](./tool.md) — learn the tool definition DSL
-- [Plugin configuration](./config.md) — accept user configuration
-- [Cordis tutorial](../../../cordis-tutorial/index.md) — the plugin framework underneath, built from a scratch directory with no API key

package/references/official-docs/docs/user/develop/basic/index.zh.md

@@ -1,144 +0,0 @@
-# 第一个插件
-
-[English](index.md) | 中文
-
-本教程会创建一个最小的 Harness 插件，并将其加载到 Web UI 中。请从已完成[从源码运行路径](../../../../README.zh.md#run-from-source)的仓库检出开始。
-
-## 创建本地项目
-
-在仓库根目录创建本教程使用的临时项目：
-
-```sh
-mkdir -p scratch-plugin/src
-```
-
-## 插件是什么
-
-在 Harness 中，插件是一个导出 `apply` 函数的 TypeScript 模块。框架在加载时调用 `apply`，传入一个 `ctx`（上下文对象），你通过 `ctx` 注册能力：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'my-plugin'
-
-export function apply(ctx: Context) {
-  // Register capabilities here.
-}
-```
-
-这就是完整配置。
-
-## 创建插件文件
-
-创建 `scratch-plugin/src/my-plugin.ts`：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'hello-plugin'
-
-export function apply(ctx: Context) {
-  // Required dependencies are ready before apply runs.
-  console.log('[hello-plugin] plugin loaded!')
-}
-```
-
-## 注册到 cordis.yml
-
-在仓库根目录运行 `pwd`，然后创建 `scratch-plugin/cordis.yml`，作为插入本地插件的 Web 覆盖层。请将下文的 `/absolute/path/to/deepseek-harness` 替换为命令打印的路径：
-
-```yaml
-- insert:
-    - id: hello
-      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
-```
-
-插件路径必须是绝对路径。patch 文件只贡献配置，不会改变 loader 解析模块路径时使用的 profile 目录。
-
-使用该覆盖层启动 Web UI：
-
-```sh
-pnpm dsh web --patch ./scratch-plugin/cordis.yml
-```
-
-打开 `http://127.0.0.1:3080`。启动期间，终端会打印 `[hello-plugin] plugin loaded!`。
-
-## 自动清理
-
-通过 `ctx` 注册的任何东西——事件监听、工具、定时器——在插件卸载时都会被自动清理。你不需要手动 removeListener 或 clearInterval。
-
-如果你有需要手动清理的资源（比如一个网络连接），用 `ctx.effect()` 告诉框架怎么清理：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export function apply(ctx: Context) {
-  ctx.effect(() => {
-    const timer = setInterval(() => {
-      console.log('heartbeat')
-    }, 5000)
-
-    // The returned function runs when the plugin unloads.
-    return () => clearInterval(timer)
-  })
-}
-```
-
-## 声明依赖
-
-如果你的插件需要使用其他服务（如 `tools`、`llm`），需要声明 `inject`：
-
-```ts ignore-check
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'my-tool-plugin'
-export const inject = ['tools']
-
-export function apply(ctx: Context) {
-  // ctx.tools is ready here.
-  ctx.tools.register(/* ... */)
-}
-```
-
-框架会确保依赖的服务就绪后才加载你的插件。
-
-## 插件的三种形态
-
-除了函数形式，插件还支持对象形式和类形式：
-
-### 对象形式
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export default {
-  name: 'my-plugin',
-  inject: ['tools'],
-  apply(ctx: Context) {
-    // ...
-  },
-}
-```
-
-### 类形式
-
-```ts
-import { Service, type Context } from '@deepseek-ai/cordis'
-
-export default class MyService extends Service {
-  static inject = ['tools']
-
-  constructor(ctx: Context) {
-    super(ctx, 'myService')
-    // Perform synchronous initialization in the constructor.
-  }
-}
-```
-
-大多数情况下，函数形式足够了。当插件需要向其他插件提供服务时，可使用类形式（见 [服务与依赖](../framework/service.zh.md)）。
-
-## 下一步
-
-- [开发一个工具](./tool.zh.md) — 了解工具定义 DSL
-- [插件配置](./config.zh.md) — 让插件接受用户配置
-- [Cordis 框架教程](../../../cordis-tutorial/index.zh.md) — 底层的插件框架，在临时目录中动手构建，无需 API 密钥