website: wire the site into the repo gates; make every tutorial example compile
- website joins the pnpm workspace; root scripts website:dev/website:build; run-gates gains a website-build gate (ci-primary + ci-static) — the VitePress build doubles as the site's dead-link check; AGENTS.md documents the commands. - doc-typecheck + verify-type-equiv now scan website/zh-CN/**/*.md; every ```typescript fence converted to ```ts and made standalone-compilable (55 compiled, 1 ignore-check). Phantom APIs the compiler caught are fixed: invented event names (agent/turn-end, tool/call, llm/pre-request, ready, dispose) replaced with real catalog events or per-plugin declare-module merges; presentCall/inject/Config claims corrected to the real shapes. - guide/config.md entry-fields table completed against loader EntryOptions; its coding-agent example brought in line with examples/coding-agent.
This commit is contained in:
lintianle
@@ -6,7 +6,17 @@
|
||||
|
||||
### 监听事件
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
|
||||
declare module 'cordis' {
|
||||
interface Events {
|
||||
'event-name'(payload: string): void
|
||||
}
|
||||
}
|
||||
|
||||
declare const ctx: Context
|
||||
|
||||
ctx.on('event-name', (payload) => {
|
||||
// 处理事件
|
||||
})
|
||||
@@ -14,7 +24,18 @@ ctx.on('event-name', (payload) => {
|
||||
|
||||
### 触发事件
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
|
||||
declare module 'cordis' {
|
||||
interface Events {
|
||||
'event-name'(payload: string): void
|
||||
}
|
||||
}
|
||||
|
||||
declare const ctx: Context
|
||||
declare const payload: string
|
||||
|
||||
ctx.emit('event-name', payload)
|
||||
```
|
||||
|
||||
@@ -26,12 +47,24 @@ Cordis 提供多种事件触发模式，适用于不同场景：
|
||||
|
||||
所有监听器并行执行，不关心返回值：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
|
||||
declare module 'cordis' {
|
||||
interface Events {
|
||||
'my-plugin/turn-end'(agentId: string, turnIndex: number): void
|
||||
}
|
||||
}
|
||||
|
||||
declare const ctx: Context
|
||||
declare const agentId: string
|
||||
declare const turnIndex: number
|
||||
|
||||
// 触发
|
||||
ctx.emit('agent/turn-end', { agentId, turnIndex })
|
||||
ctx.emit('my-plugin/turn-end', agentId, turnIndex)
|
||||
|
||||
// 监听
|
||||
ctx.on('agent/turn-end', ({ agentId, turnIndex }) => {
|
||||
ctx.on('my-plugin/turn-end', (agentId, turnIndex) => {
|
||||
console.log(`Turn ${turnIndex} ended`)
|
||||
})
|
||||
```
|
||||
@@ -40,7 +73,19 @@ ctx.on('agent/turn-end', ({ agentId, turnIndex }) => {
|
||||
|
||||
依次调用监听器，第一个返回非 `undefined` 值的结果作为最终值：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
|
||||
declare module 'cordis' {
|
||||
interface Events {
|
||||
'some-check'(input: string): string | undefined
|
||||
}
|
||||
}
|
||||
|
||||
declare const ctx: Context
|
||||
declare const input: string
|
||||
declare function shouldBlock(input: string): boolean
|
||||
|
||||
// 触发
|
||||
const result = ctx.bail('some-check', input)
|
||||
|
||||
@@ -48,6 +93,7 @@ const result = ctx.bail('some-check', input)
|
||||
ctx.on('some-check', (input) => {
|
||||
if (shouldBlock(input)) return 'blocked'
|
||||
// 返回 undefined 继续传递给下一个监听器
|
||||
return undefined
|
||||
})
|
||||
```
|
||||
|
||||
@@ -55,24 +101,47 @@ ctx.on('some-check', (input) => {
|
||||
|
||||
所有监听器按注册顺序依次执行（异步安全）：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
|
||||
declare module 'cordis' {
|
||||
interface Events {
|
||||
'setup-phase'(context: object): Promise<void> | void
|
||||
}
|
||||
}
|
||||
|
||||
declare const ctx: Context
|
||||
declare const context: object
|
||||
|
||||
await ctx.serial('setup-phase', context)
|
||||
```
|
||||
|
||||
### waterfall — 管道
|
||||
|
||||
每个监听器接收前一个的输出，形成数据管道。**必须调用 `next()` 传递给下游**，不调用即为否决：
|
||||
监听器围绕默认实现层层包裹，形成数据管道。**必须调用 `next()` 委托给下游**，不调用即为否决：
|
||||
|
||||
```typescript
|
||||
// 触发
|
||||
const finalMessages = await ctx.waterfall('llm/pre-request', messages)
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
import type { Message } from '@deepseek-ai/dsh-llm'
|
||||
|
||||
declare module 'cordis' {
|
||||
interface Events {
|
||||
'my-plugin/messages'(messages: Message[], next: () => Promise<Message[]>): Promise<Message[]>
|
||||
}
|
||||
}
|
||||
|
||||
declare const ctx: Context
|
||||
declare const messages: Message[]
|
||||
declare const extraMessage: Message
|
||||
|
||||
// 触发：最后一个参数是默认实现（所有监听器都调用 next 时的最终值）
|
||||
const finalMessages = await ctx.waterfall('my-plugin/messages', messages, async () => messages)
|
||||
|
||||
// 监听（必须调用 next）
|
||||
ctx.on('llm/pre-request', async (messages, next) => {
|
||||
// 可以修改 messages
|
||||
messages.push(extraMessage)
|
||||
// 必须调用 next() 传递给下一个监听器
|
||||
return next(messages)
|
||||
ctx.on('my-plugin/messages', async (messages, next) => {
|
||||
// next() 委托给下游监听器（最终到达默认实现），返回值可以被加工
|
||||
const result = await next()
|
||||
return [...result, extraMessage]
|
||||
})
|
||||
```
|
||||
|
||||
@@ -84,11 +153,13 @@ Waterfall 监听器**必须调用 `next()`**。不调用 `next` 等于否决整
|
||||
|
||||
Harness 使用 TypeScript 声明合并来为事件提供类型安全：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type {} from 'cordis'
|
||||
|
||||
declare module 'cordis' {
|
||||
interface Events {
|
||||
'my-plugin/ready': (payload: { id: string }) => void
|
||||
'my-plugin/check': (input: string) => boolean | undefined
|
||||
'my-plugin/ready'(payload: { id: string }): void
|
||||
'my-plugin/check'(input: string): boolean | undefined
|
||||
}
|
||||
}
|
||||
|
||||
@@ -101,24 +172,30 @@ declare module 'cordis' {
|
||||
Harness 事件遵循 `namespace/action` 命名：
|
||||
|
||||
```
|
||||
agent/pre-step — agent 执行一步之前
|
||||
agent/post-step — agent 执行一步之后
|
||||
tool/call — tool 被调用
|
||||
tool/result — tool 返回结果
|
||||
llm/pre-request — LLM 请求发送前
|
||||
session/event — 会话事件被记录
|
||||
compact/start — 压缩开始
|
||||
compact/end — 压缩结束
|
||||
agent/pre-step — 每个 step 开始前的检查点（serial）
|
||||
agent/step-result — step 的 assistant 消息组装完成（waterfall）
|
||||
tools/pre-execute — tool 执行前的允许/拒绝门（waterfall）
|
||||
tools/post-execute — tool 执行后的检查/改写缝（waterfall）
|
||||
llm/stream — 每次流式模型调用的环绕点（waterfall）
|
||||
session/event — 会话事件被记录（emit）
|
||||
session/flush — 会话持久化检查点（parallel）
|
||||
```
|
||||
|
||||
完整的事件列表（含每个事件的签名与派发模式）见仓库中的 `docs/cordis-catalog/events.md`。
|
||||
|
||||
## 事件也是效果
|
||||
|
||||
通过 `ctx.on()` 注册的监听器会在插件卸载时自动移除：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
|
||||
|
||||
declare function handler(agent: Agent, status: AgentStatus): void
|
||||
|
||||
export function apply(ctx: Context) {
|
||||
// 这个监听器在插件 dispose 时自动清理
|
||||
ctx.on('agent/turn-end', handler)
|
||||
ctx.on('agent/status', handler)
|
||||
}
|
||||
```
|
||||
|
||||
@@ -126,22 +203,21 @@ export function apply(ctx: Context) {
|
||||
|
||||
一个记录所有 tool 调用的简单插件：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
import type {} from '@deepseek-ai/dsh-tools'
|
||||
|
||||
export const name = 'tool-logger'
|
||||
|
||||
export function apply(ctx: Context) {
|
||||
ctx.on('tool/call', ({ name, args }) => {
|
||||
console.log(`[tool] ${name}(${JSON.stringify(args)})`)
|
||||
})
|
||||
|
||||
ctx.on('tool/result', ({ name, result }) => {
|
||||
ctx.on('tools/execute', async (exec, next) => {
|
||||
console.log(`[tool] ${exec.name}(${JSON.stringify(exec.arguments)})`)
|
||||
const result = await next()
|
||||
const text = result.content
|
||||
.filter(b => b.type === 'text')
|
||||
.map(b => b.text)
|
||||
.map(b => b.type === 'text' ? b.text : '')
|
||||
.join('')
|
||||
console.log(`[tool result] ${text.slice(0, 100)}`)
|
||||
return result
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
@@ -25,7 +25,11 @@ ACTIVE → UNLOADING → DISPOSED
|
||||
|
||||
声明了 `inject` 的插件不会立即加载，而是等待依赖的服务就绪：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
import type {} from '@deepseek-ai/dsh-tools'
|
||||
import type {} from '@deepseek-ai/dsh-llm'
|
||||
|
||||
export const inject = ['tools', 'llm']
|
||||
|
||||
export function apply(ctx: Context) {
|
||||
@@ -39,10 +43,21 @@ export function apply(ctx: Context) {
|
||||
|
||||
通过 `ctx` 做的任何注册，在插件卸载时都会自动撤销：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
|
||||
declare module 'cordis' {
|
||||
interface Events {
|
||||
'my-plugin/some-event'(): void
|
||||
}
|
||||
}
|
||||
|
||||
declare function handler(): void
|
||||
declare function createConnection(): { close(): void }
|
||||
|
||||
export function apply(ctx: Context) {
|
||||
// 事件监听——卸载时自动移除
|
||||
ctx.on('some-event', handler)
|
||||
ctx.on('my-plugin/some-event', handler)
|
||||
|
||||
// 自定义资源——卸载时调用返回的函数
|
||||
ctx.effect(() => {
|
||||
@@ -64,7 +79,11 @@ export function apply(ctx: Context) {
|
||||
|
||||
`ctx.plugin()` 创建子 Fiber，它继承父上下文但有独立的生命周期：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
|
||||
declare function childPlugin(ctx: Context): void
|
||||
|
||||
export function apply(ctx: Context) {
|
||||
// 注册一个子插件
|
||||
ctx.plugin(childPlugin)
|
||||
@@ -77,11 +96,16 @@ export function apply(ctx: Context) {
|
||||
|
||||
当你需要提前终止一个插件实例：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
|
||||
declare const ctx: Context
|
||||
declare function myPlugin(ctx: Context): void
|
||||
|
||||
const fiber = ctx.plugin(myPlugin)
|
||||
|
||||
// 之后可以手动 dispose
|
||||
fiber.dispose()
|
||||
await fiber.dispose()
|
||||
```
|
||||
|
||||
`dispose` 保证：
|
||||
@@ -101,18 +125,14 @@ fiber.dispose()
|
||||
|
||||
## 实战：理解生命周期
|
||||
|
||||
```typescript
|
||||
`apply` 函数体就是加载钩子；卸载没有专门的事件——把清理逻辑放进 `ctx.effect()` 的返回函数即可：
|
||||
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
|
||||
export function apply(ctx: Context) {
|
||||
console.log('plugin loading')
|
||||
|
||||
ctx.on('ready', () => {
|
||||
console.log('context ready')
|
||||
})
|
||||
|
||||
ctx.on('dispose', () => {
|
||||
console.log('plugin disposing')
|
||||
})
|
||||
|
||||
ctx.effect(() => {
|
||||
console.log('effect registered')
|
||||
return () => console.log('effect cleaned up')
|
||||
@@ -124,12 +144,10 @@ export function apply(ctx: Context) {
|
||||
```
|
||||
plugin loading
|
||||
effect registered
|
||||
context ready
|
||||
```
|
||||
|
||||
卸载时输出（逆序）：
|
||||
卸载时输出：
|
||||
```
|
||||
plugin disposing
|
||||
effect cleaned up
|
||||
```
|
||||
|
||||
|
||||
@@ -6,10 +6,17 @@
|
||||
|
||||
在 Harness 中，`tools`、`llm`、`agents` 都是服务。服务是挂载在 `ctx` 上的命名能力：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
import type {} from '@deepseek-ai/dsh-tools'
|
||||
import type {} from '@deepseek-ai/dsh-llm'
|
||||
import type {} from '@deepseek-ai/dsh-agent'
|
||||
|
||||
declare const ctx: Context
|
||||
|
||||
ctx.tools // ToolRegistry 服务
|
||||
ctx.llm // LLM 服务
|
||||
ctx.agents // Agent 服务
|
||||
ctx.agents // Agent 注册表服务
|
||||
```
|
||||
|
||||
任何插件都可以提供一个新服务，供其他插件使用。
|
||||
@@ -18,12 +25,22 @@ ctx.agents // Agent 服务
|
||||
|
||||
声明 `inject` 来使用已有服务：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
import { defineTool } from '@deepseek-ai/dsh-tools'
|
||||
|
||||
export const inject = ['tools']
|
||||
|
||||
export function apply(ctx: Context) {
|
||||
// ctx.tools 在这里一定存在且就绪
|
||||
ctx.tools.register(/* ... */)
|
||||
ctx.tools.register(defineTool({
|
||||
name: 'demo',
|
||||
description: 'Demo tool.',
|
||||
parameters: {},
|
||||
async execute() {
|
||||
return []
|
||||
},
|
||||
}))
|
||||
}
|
||||
```
|
||||
|
||||
@@ -33,8 +50,9 @@ export function apply(ctx: Context) {
|
||||
|
||||
### 使用 Service 基类
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import { Service, type Context } from 'cordis'
|
||||
import type {} from '@deepseek-ai/dsh-llm'
|
||||
|
||||
export default class MetricsService extends Service {
|
||||
static inject = ['llm'] // 本服务也可以依赖其他服务
|
||||
@@ -52,7 +70,9 @@ export default class MetricsService extends Service {
|
||||
|
||||
加载这个插件后，其他插件就可以通过 `ctx.metrics` 访问它：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
|
||||
export const inject = ['metrics']
|
||||
|
||||
export function apply(ctx: Context) {
|
||||
@@ -64,7 +84,7 @@ export function apply(ctx: Context) {
|
||||
|
||||
使用 TypeScript 声明合并让 `ctx.metrics` 有正确类型：
|
||||
|
||||
```typescript
|
||||
```ts
|
||||
import { Service, type Context } from 'cordis'
|
||||
|
||||
declare module 'cordis' {
|
||||
@@ -84,14 +104,21 @@ export default class MetricsService extends Service {
|
||||
|
||||
## 依赖的行为
|
||||
|
||||
### 必选依赖 vs 可选依赖
|
||||
### 必选依赖 vs 可选读取
|
||||
|
||||
`inject` 声明的依赖都是必选的：服务不存在时，插件不会加载。如果只想"有则用之"，用 `ctx.get()` 读取——服务不存在时返回 `undefined`，插件照常加载：
|
||||
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
|
||||
```typescript
|
||||
// 必选：服务不存在时，插件不会加载
|
||||
export const inject = ['tools']
|
||||
|
||||
// 可选：服务不存在时，插件仍然加载，但 ctx.xxx 可能是 undefined
|
||||
export const inject = { optional: ['metrics'] }
|
||||
export function apply(ctx: Context) {
|
||||
// 可选读取：不声明 inject，服务不存在时返回 undefined
|
||||
const metrics = ctx.get('metrics')
|
||||
metrics?.record('plugin_loaded', 1)
|
||||
}
|
||||
```
|
||||
|
||||
### 服务消失时的行为
|
||||
@@ -133,13 +160,14 @@ export const inject = { optional: ['metrics'] }
|
||||
|--------|--------|------|
|
||||
| `tools` | dsh-tools | Tool 注册表 |
|
||||
| `llm` | dsh-llm | LLM 调用 + 适配器注册 |
|
||||
| `agents` | dsh-agent | Agent 实例管理 |
|
||||
| `session` | dsh-session | 会话事件流 |
|
||||
| `agents` | dsh-agent | Agent 注册表 |
|
||||
| `agentLoop` | dsh-agent-loop | Agent 创建与循环执行 |
|
||||
| `sessions` | dsh-session | 会话存储与事件流 |
|
||||
| `systemPrompt` | dsh-system-prompt | 系统提示词组装 |
|
||||
| `bash` | dsh-bash-local | Bash 命令执行 |
|
||||
| `fs` | dsh-fs-local | 文件系统操作 |
|
||||
| `subagent` | dsh-subagent | 子代理委派 |
|
||||
| `persistence` | dsh-session-persistence | 会话持久化 |
|
||||
| `bash` | dsh-bash（实现：dsh-bash-local） | Bash 命令执行 |
|
||||
| `fs` | dsh-fs（实现：dsh-fs-local） | 文件系统操作 |
|
||||
| `subagents` | dsh-subagent | 子代理委派 |
|
||||
| `sessionPersistence` | dsh-session-persistence（实现：-jsonl / -sqlite） | 会话持久化 |
|
||||
|
||||
## 下一步
|
||||
|
||||
|
||||
Reference in New Issue
Block a user