dsh-plugin-guide 0.3.41 → 0.4.0

package/references/official-docs/docs/user/develop/framework/events.md

@@ -1,143 +0,0 @@
-# Event system
-
-English | [中文](events.zh.md)
-
-Events are the core communication mechanism between Cordis plugins. Harness uses them extensively for loosely coupled extension points.
-
-## Basic use
-
-### Listen for an event
-
-```ts ignore-check
-ctx.on('event-name', (payload) => {
-  // Handle the event.
-})
-```
-
-### Emit an event
-
-```ts ignore-check
-ctx.emit('event-name', payload)
-```
-
-## Event modes
-
-Cordis provides several event modes for different interaction contracts.
-
-### emit — broadcast
-
-Every listener runs synchronously and return values are ignored:
-
-```ts ignore-check
-// Emit
-ctx.emit('my-plugin/ready', { id: 'worker-1' })
-
-// Listen
-ctx.on('my-plugin/ready', ({ id }) => {
-  console.log(`${id} is ready`)
-})
-```
-
-### bail — short circuit
-
-Listeners run in order; the first result other than `null`, `false`, or `undefined` becomes the final result:
-
-```ts ignore-check
-// Dispatch
-const result = ctx.bail('some-check', input)
-
-// Listen: a returned value stops later listeners.
-ctx.on('some-check', (input) => {
-  if (shouldBlock(input)) return 'blocked'
-  // Return null, false, or undefined to continue to the next listener.
-})
-```
-
-### serial — ordered execution
-
-Listeners run in registration order and asynchronous results are awaited. The first result other than `null`, `false`, or `undefined` stops further execution:
-
-```ts ignore-check
-await ctx.serial('setup-phase', context)
-```
-
-### waterfall — pipeline
-
-Each listener may wrap the downstream result to form a processing chain. A listener **must call `next()` to delegate downstream**; omitting the call short-circuits the pipeline:
-
-```ts ignore-check
-// Dispatch
-const output = await ctx.waterfall('my-plugin/transform', input, async () => input)
-
-// Listen: next() is mandatory.
-ctx.on('my-plugin/transform', async (_input, next) => {
-  const downstream = await next()
-  return downstream.trim()
-})
-```
-
-::: warning
-A waterfall listener **must call `next()`**. Omitting it short-circuits the pipeline by design, enabling interception and gateway behavior.
-:::
-
-## Typed events
-
-Harness uses TypeScript declaration merging for type-safe events:
-
-```ts
-import '@deepseek-ai/cordis'
-
-declare module '@deepseek-ai/cordis' {
-  interface Events {
-    'my-plugin/ready': (payload: { id: string }) => void
-    'my-plugin/check': (input: string) => boolean | undefined
-    'my-plugin/transform': (input: string, next: () => Promise<string>) => Promise<string>
-  }
-}
-
-// ctx.on('my-plugin/ready', ...) and ctx.emit('my-plugin/ready', ...)
-// are now inferred correctly.
-```
-
-## Cordis events and session records
-
-Harness Cordis events use `namespace/action` names, including `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/result`, and `session/event`. The generated `cordis-surface` regions on the [subsystem pages](../../../subsystems/core.md) record complete signatures and modes.
-
-`turn/*`, `step/*`, `tool/call`, `tool/result`, and `compaction/*` are durable session-event types, not same-named Cordis events. To observe them, listen to `session/event` and inspect `event.type`.
-
-## Event listeners are effects
-
-A listener registered with `ctx.on()` is removed automatically when its plugin unloads:
-
-```ts ignore-check
-export function apply(ctx: Context) {
-  // This listener is removed when the plugin disposes.
-  ctx.on('tools/result', handler)
-}
-```
-
-## Example: logging plugin
-
-This plugin logs tool calls and results:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import '@deepseek-ai/dsh-tools'
-
-export const name = 'tool-logger'
-
-export function apply(ctx: Context) {
-  ctx.on('tools/result', (exec, result) => {
-    console.log(`[tool] ${exec.name}(${JSON.stringify(exec.arguments)})`)
-    const text = result.content
-      .map(block => block.type === 'text' ? block.text : '')
-      .join('')
-    console.log(`[tool result] ${text.slice(0, 100)}`)
-  })
-}
-```
-
-## Next steps
-
-- [Capability layering](../practice/index.md) — understand events within capability interfaces
-- [LLM adapters](../practice/llm-adapter.md) — implement a complete LLM backend

package/references/official-docs/docs/user/develop/framework/events.zh.md

@@ -1,143 +0,0 @@
-# 事件系统
-
-[English](events.md) | 中文
-
-事件是 Cordis 插件间通信的核心机制。Harness 大量使用事件来实现松耦合的扩展点。
-
-## 基本用法
-
-### 监听事件
-
-```ts ignore-check
-ctx.on('event-name', (payload) => {
-  // Handle the event.
-})
-```
-
-### 触发事件
-
-```ts ignore-check
-ctx.emit('event-name', payload)
-```
-
-## 事件模式
-
-Cordis 提供多种事件模式，适用于不同的交互契约：
-
-### emit — 广播
-
-所有监听器同步执行，返回值会被忽略：
-
-```ts ignore-check
-// Emit
-ctx.emit('my-plugin/ready', { id: 'worker-1' })
-
-// Listen
-ctx.on('my-plugin/ready', ({ id }) => {
-  console.log(`${id} is ready`)
-})
-```
-
-### bail — 短路
-
-监听器按顺序运行，第一个不是 `null`、`false` 或 `undefined` 的返回值会成为最终结果：
-
-```ts ignore-check
-// Dispatch
-const result = ctx.bail('some-check', input)
-
-// Listen: a returned value stops later listeners.
-ctx.on('some-check', (input) => {
-  if (shouldBlock(input)) return 'blocked'
-  // Return null, false, or undefined to continue to the next listener.
-})
-```
-
-### serial — 顺序执行
-
-监听器按注册顺序依次执行，并等待异步结果；第一个不是 `null`、`false` 或 `undefined` 的返回值会终止后续执行：
-
-```ts ignore-check
-await ctx.serial('setup-phase', context)
-```
-
-### waterfall（瀑布式事件）— 流水线
-
-每个监听器可以包装下游返回值，形成处理链。**必须调用 `next()` 传递给下游**，不调用即会短路流水线：
-
-```ts ignore-check
-// Dispatch
-const output = await ctx.waterfall('my-plugin/transform', input, async () => input)
-
-// Listen: next() is mandatory.
-ctx.on('my-plugin/transform', async (_input, next) => {
-  const downstream = await next()
-  return downstream.trim()
-})
-```
-
-::: warning
-waterfall 监听器**必须调用 `next()`**。不调用 `next` 会短路整个流水线，这是故意为之的设计——用于实现拦截/网关逻辑。
-:::
-
-## 类型安全的事件
-
-Harness 使用 TypeScript 声明合并来为事件提供类型安全：
-
-```ts
-import '@deepseek-ai/cordis'
-
-declare module '@deepseek-ai/cordis' {
-  interface Events {
-    'my-plugin/ready': (payload: { id: string }) => void
-    'my-plugin/check': (input: string) => boolean | undefined
-    'my-plugin/transform': (input: string, next: () => Promise<string>) => Promise<string>
-  }
-}
-
-// ctx.on('my-plugin/ready', ...) and ctx.emit('my-plugin/ready', ...)
-// are now inferred correctly.
-```
-
-## Cordis 事件与会话记录
-
-Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/pre-step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[子系统页面](../../../subsystems/core.zh.md)上生成的 `cordis-surface` 区块。
-
-`turn/*`、`step/*`、`tool/call`、`tool/result` 和 `compaction/*` 是持久化的会话事件类型，不是同名 Cordis 事件。需要观察它们时，监听 `session/event` 并检查 `event.type`。
-
-## 事件监听器也是效果
-
-通过 `ctx.on()` 注册的监听器会在插件卸载时自动移除：
-
-```ts ignore-check
-export function apply(ctx: Context) {
-  // This listener is removed when the plugin disposes.
-  ctx.on('tools/result', handler)
-}
-```
-
-## 示例：日志插件
-
-这个插件记录工具调用和工具结果：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import '@deepseek-ai/dsh-tools'
-
-export const name = 'tool-logger'
-
-export function apply(ctx: Context) {
-  ctx.on('tools/result', (exec, result) => {
-    console.log(`[tool] ${exec.name}(${JSON.stringify(exec.arguments)})`)
-    const text = result.content
-      .map(block => block.type === 'text' ? block.text : '')
-      .join('')
-    console.log(`[tool result] ${text.slice(0, 100)}`)
-  })
-}
-```
-
-## 下一步
-
-- [能力分层](../practice/index.zh.md) — 了解能力接口中的事件
-- [LLM（大语言模型）适配器](../practice/llm-adapter.zh.md) — 实现一个完整的 LLM 后端

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

@@ -1,31 +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/framework/index.md
-/plugins-and-lifecycle:
-  en: bc1c66795191727b
-  zh: e0666a674ca9921c
-/plugins-and-lifecycle/fiber-state-machine:
-  en: 66b51bb63094de1a
-  zh: 1d9f70611c9930ea
-/plugins-and-lifecycle/dependency-driven-loading:
-  en: 726a61e5c20db20f
-  zh: bd935ca733c30a15
-/plugins-and-lifecycle/automatic-cleanup:
-  en: e9bcc83f7a752d13
-  zh: c8df4bd5c23c8875
-/plugins-and-lifecycle/nested-contexts:
-  en: 2862ee99034d4423
-  zh: 7180298e3eff6524
-/plugins-and-lifecycle/dispose-semantics:
-  en: 1d23337dbcc4ae61
-  zh: ad003f8b5e325801
-/plugins-and-lifecycle/hot-replacement-hmr:
-  en: ca8495ec7369856c
-  zh: 54db7540aceb4b09
-/plugins-and-lifecycle/example-lifecycle:
-  en: e17160970571b690
-  zh: e49149cd82e77801
-/plugins-and-lifecycle/next-steps:
-  en: c245d538e75eef67
-  zh: 2e0ad34a2022aee3

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

@@ -1,137 +0,0 @@
-# Plugins and lifecycle
-
-English | [中文](index.zh.md)
-
-This page describes the Cordis plugin model and lifecycle state machine.
-
-## Fiber state machine
-
-Every loaded plugin owns a **Fiber** scope with the following states:
-
-```
-PENDING → LOADING → ACTIVE
-                 ↘ FAILED
-ACTIVE → UNLOADING → DISPOSED
-```
-
-| State | Meaning |
-|------|------|
-| PENDING | Declared, but required dependencies are not ready |
-| LOADING | Dependencies are ready and `apply` is running |
-| ACTIVE | The plugin is running |
-| FAILED | `apply` threw an error |
-| UNLOADING | The plugin is unloading and disposing resources |
-| DISPOSED | The plugin is fully unloaded |
-
-## Dependency-driven loading
-
-A plugin with `inject` waits for every required service before loading:
-
-```ts ignore-check
-export const inject = ['tools', 'llm']
-
-export function apply(ctx: Context) {
-  // ctx.tools and ctx.llm are ready here.
-}
-```
-
-If a required service disappears, for example during provider replacement, the plugin unloads automatically (ACTIVE → DISPOSED) and loads again when the service returns.
-
-## Automatic cleanup
-
-Every registration made through `ctx` is undone when the plugin unloads:
-
-```ts ignore-check
-export function apply(ctx: Context) {
-  // Event listener: removed automatically on unload.
-  ctx.on('some-event', handler)
-
-  // Custom resource: the returned disposer runs on unload.
-  ctx.effect(() => {
-    const connection = createConnection()
-    return () => connection.close()
-  })
-}
-```
-
-The framework tracks and disposes all of these operations:
-- `ctx.on(event, handler)` — event listener
-- `ctx.tools.register(tool)` — tool registration
-- `ctx.llm.registerAdapter(names, adapter)` — LLM adapter registration
-- `ctx.effect(() => cleanup)` — custom resource
-
-During unload, disposer invocation starts in reverse registration order, but multiple async disposers run concurrently and have no serial completion guarantee. Put order-dependent cleanup in one disposer returned from a single `ctx.effect()` and await its steps serially there.
-
-## Nested contexts
-
-`ctx.plugin()` creates a child Fiber that inherits the parent context but has an independent lifecycle:
-
-```ts ignore-check
-export function apply(ctx: Context) {
-  // Register a child plugin.
-  ctx.plugin(childPlugin)
-
-  // The child has its own Fiber and unloads with its parent.
-}
-```
-
-## Dispose semantics
-
-To stop a plugin instance early:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-declare const ctx: Context
-declare function myPlugin(ctx: Context): void
-
-const fiber = ctx.plugin(myPlugin)
-
-// Dispose it manually later.
-await fiber.dispose()
-```
-
-`dispose` guarantees:
-1. All registrations owned by the plugin are removed.
-2. Child plugins are recursively unloaded.
-3. The returned promise resolves after all asynchronous cleanup finishes.
-
-## Hot replacement (HMR)
-
-With `@deepseek-ai/dsh-hmr` loaded from `cordis.yml`, editing a plugin source file triggers:
-
-1. Unload the old plugin and clean up its registrations.
-2. Load the new code.
-3. Run the new `apply`.
-
-Because plugin registrations clean themselves up, hot replacement does not retain registrations from the old instance.
-
-## Example lifecycle
-
-```ts ignore-check
-export function apply(ctx: Context) {
-  console.log('plugin loading')
-
-  ctx.effect(() => {
-    console.log('effect registered')
-    return () => console.log('effect cleaned up')
-  })
-}
-```
-
-Loading prints:
-```
-plugin loading
-effect registered
-```
-
-Unloading prints:
-```
-effect cleaned up
-```
-
-## Next steps
-
-- [Services and dependencies](./service.md) — expose a capability to other plugins
-- [Event system](./events.md) — communicate between plugins
-- [Cordis tutorial](../../../cordis-tutorial/index.md) — the same lifecycle, services, and events built step by step against the Cordis runtime

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

@@ -1,137 +0,0 @@
-# 插件与生命周期
-
-[English](index.md) | 中文
-
-本页介绍 Cordis 插件模型和生命周期状态机。
-
-## Fiber 状态机
-
-每个被加载的插件都拥有一个 **Fiber** 作用域，其状态如下：
-
-```
-PENDING → LOADING → ACTIVE
-                 ↘ FAILED
-ACTIVE → UNLOADING → DISPOSED
-```
-
-| 状态 | 含义 |
-|------|------|
-| PENDING | 已声明，但所需依赖未就绪 |
-| LOADING | 依赖就绪，正在执行 `apply` |
-| ACTIVE | 插件运行中 |
-| FAILED | `apply` 抛出异常 |
-| UNLOADING | 插件正在卸载并释放资源 |
-| DISPOSED | 已完全卸载 |
-
-## 依赖驱动的加载
-
-声明了 `inject` 的插件会等待所有必需服务就绪：
-
-```ts ignore-check
-export const inject = ['tools', 'llm']
-
-export function apply(ctx: Context) {
-  // ctx.tools and ctx.llm are ready here.
-}
-```
-
-如果依赖的服务消失（例如提供方被替换时），插件会被自动卸载（ACTIVE → DISPOSED），待服务恢复后重新加载。
-
-## 自动清理机制
-
-通过 `ctx` 做的任何注册，在插件卸载时都会自动撤销：
-
-```ts ignore-check
-export function apply(ctx: Context) {
-  // Event listener: removed automatically on unload.
-  ctx.on('some-event', handler)
-
-  // Custom resource: the returned disposer runs on unload.
-  ctx.effect(() => {
-    const connection = createConnection()
-    return () => connection.close()
-  })
-}
-```
-
-以下操作都会被自动追踪和清理：
-- `ctx.on(event, handler)` — 事件监听
-- `ctx.tools.register(tool)` — 工具注册
-- `ctx.llm.registerAdapter(names, adapter)` — LLM（大语言模型）适配器注册
-- `ctx.effect(() => cleanup)` — 自定义资源
-
-插件卸载时，处置器按注册顺序的逆序开始调用，但多个异步处置器会并发执行，不保证逐个完成。存在顺序依赖的清理步骤必须放进同一个 `ctx.effect()` 返回的处置器中，由该处置器负责串行等待。
-
-## 嵌套上下文
-
-`ctx.plugin()` 创建子 Fiber，它继承父上下文但有独立的生命周期：
-
-```ts ignore-check
-export function apply(ctx: Context) {
-  // Register a child plugin.
-  ctx.plugin(childPlugin)
-
-  // The child has its own Fiber and unloads with its parent.
-}
-```
-
-## dispose（资源释放）语义
-
-当你需要提前终止一个插件实例：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-declare const ctx: Context
-declare function myPlugin(ctx: Context): void
-
-const fiber = ctx.plugin(myPlugin)
-
-// Dispose it manually later.
-await fiber.dispose()
-```
-
-`dispose` 保证：
-1. 该插件拥有的所有注册均被移除
-2. 它的子插件也被递归卸载
-3. 返回的 Promise 会在所有异步清理完成后兑现
-
-## HMR（热模块替换）
-
-通过 `cordis.yml` 加载 `@deepseek-ai/dsh-hmr` 后，修改插件源文件会触发：
-
-1. 卸载旧插件（清理所有注册）
-2. 重新加载新代码
-3. 执行新的 `apply`
-
-因为插件注册会被自动清理，所以热替换不会保留旧实例的注册。
-
-## 生命周期示例
-
-```ts ignore-check
-export function apply(ctx: Context) {
-  console.log('plugin loading')
-
-  ctx.effect(() => {
-    console.log('effect registered')
-    return () => console.log('effect cleaned up')
-  })
-}
-```
-
-加载时输出：
-```
-plugin loading
-effect registered
-```
-
-卸载时输出：
-```
-effect cleaned up
-```
-
-## 下一步
-
-- [服务与依赖](./service.zh.md) — 让插件向其他插件提供能力
-- [事件系统](./events.zh.md) — 在插件之间通信
-- [Cordis 框架教程](../../../cordis-tutorial/index.zh.md) — 在 Cordis 运行时上逐步搭出同一套生命周期、服务与事件

package/references/official-docs/docs/user/develop/framework/service.i18n.yaml

@@ -1,40 +0,0 @@
-# Bilingual-pair consistency record for service.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/framework/service.md
-/services-and-dependencies:
-  en: 03fe9a674163a484
-  zh: 45374665fa3bb8e3
-/services-and-dependencies/what-is-a-service:
-  en: fb06be7799d75fc0
-  zh: a59fdde61e557b24
-/services-and-dependencies/consume-a-service:
-  en: 6655ebf5abce2a59
-  zh: 0c91cac86768d63e
-/services-and-dependencies/provide-a-service:
-  en: ed1d04f41f64b6ce
-  zh: e0ddcb48bf3207c1
-/services-and-dependencies/provide-a-service/extend-service:
-  en: 3de1c24498e2c62f
-  zh: 57836dc4fa8d5c9a
-/services-and-dependencies/provide-a-service/declare-its-type:
-  en: fc1a29f46715ade5
-  zh: b1edb281077df180
-/services-and-dependencies/dependency-behavior:
-  en: 6678917fe40eea55
-  zh: 6227580b94a50855
-/services-and-dependencies/dependency-behavior/required-and-optional-dependencies:
-  en: 8a98845896146946
-  zh: 2383ad4ba5d2943d
-/services-and-dependencies/dependency-behavior/when-a-service-disappears:
-  en: 689e4b95dd320122
-  zh: 674ffba2733ec745
-/services-and-dependencies/service-isolation:
-  en: cc4be89f19cb7615
-  zh: e00e86a615f59003
-/services-and-dependencies/built-in-harness-services:
-  en: 07eb5bcc03955284
-  zh: 5eec0f3c6e01c0f9
-/services-and-dependencies/next-steps:
-  en: 1537e6955eb02c62
-  zh: 6430f34e63cfa533