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.

website/zh-CN/develop/basic/config.md

@@ -4,27 +4,21 @@
 
 ## 定义 Config 类型
 
-在插件中导出一个 `Config` 类型和可选的默认值：
+在插件中导出一个 `Config` 类型，`apply` 的第二个参数就是用户配置：
 
-```typescript
+```ts
 import type { Context } from 'cordis'
 
 export const name = 'my-plugin'
 
 export interface Config {
-  greeting: string
-  maxRetries: number
+  greeting?: string
+  maxRetries?: number
   verbose?: boolean
 }
 
-export const Config = {
-  greeting: 'Hello',
-  maxRetries: 3,
-  verbose: false,
-}
-
 export function apply(ctx: Context, config: Config) {
-  console.log(config.greeting)  // 用户配置或默认值
+  console.log(config.greeting ?? 'Hello')  // 用户配置或默认值
 }
 ```
 
@@ -37,32 +31,32 @@ export function apply(ctx: Context, config: Config) {
     maxRetries: 5
 ```
 
-未提供的字段使用导出的 `Config` 对象中的默认值。
+只导出类型时，配置原样传入，默认值由代码自己兜底（如上面的 `??`）。想让框架代管默认值和校验，导出一个 schema（见下节）。
 
 ## Schema 校验
 
-对于需要严格校验的场景，使用 Schemastery 定义 schema：
+对于需要默认值和严格校验的场景，额外导出一个 Schemastery schema（仓库约定以 `z` 引入）。加载时框架先用它校验并填充默认值，再把结果传给 `apply`：
 
-```typescript
+```ts
 import type { Context } from 'cordis'
-import Schema from 'schemastery'
+import z from 'schemastery'
 
 export const name = 'validated-plugin'
 
 export interface Config {
   apiKey: string
-  timeout: number
-  mode: 'fast' | 'accurate'
+  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 const Config: z<Config> = z.object({
+  apiKey: z.string().required(),
+  timeout: z.number().default(30000),
+  mode: z.union(['fast', 'accurate'] as const).default('fast'),
 })
 
 export function apply(ctx: Context, config: Config) {
-  // config 已经过校验，类型安全
+  // config 已经过校验，类型安全，默认值已填充
 }
 ```
 
@@ -74,13 +68,14 @@ Schema 在插件加载时执行校验。如果配置不合法，插件会加载
 
 Harness 的约定：**任何两个部署可能想要不同值的东西，都应该是配置字段**。
 
-```typescript
+```ts
 // 错误 — 硬编码超时时间
 const TIMEOUT = 30000
 
 // 正确 — 可配置
 export interface Config {
-  timeoutMs: number  // 默认 30000
+  /** 默认 30000 */
+  timeoutMs?: number
 }
 ```
 
@@ -90,9 +85,16 @@ export interface Config {
 
 如果配置引用了不存在的东西（比如一个不存在的模型名），应该尽早报错，而不是静默跳过：
 
-```typescript
+```ts
+import type { Context } from 'cordis'
+import type {} from '@deepseek-ai/dsh-llm'
+
+export interface Config {
+  model: string
+}
+
 export function apply(ctx: Context, config: Config) {
-  if (!ctx.llm.hasAdapter(config.model)) {
+  if (!ctx.llm.models().includes(config.model)) {
     throw new Error(`Model "${config.model}" is not registered by any LLM adapter`)
   }
 }

website/zh-CN/develop/basic/index.md

@@ -6,7 +6,7 @@
 
 在 Harness 中，插件是一个导出 `apply` 函数的 TypeScript 模块。框架在加载时调用 `apply`，传入一个 `ctx`（上下文对象），你通过 `ctx` 注册能力：
 
-```typescript
+```ts
 import type { Context } from 'cordis'
 
 export const name = 'my-plugin'
@@ -22,16 +22,14 @@ export function apply(ctx: Context) {
 
 在你的项目目录下创建 `src/my-plugin.ts`：
 
-```typescript
+```ts
 import type { Context } from 'cordis'
 
 export const name = 'hello-plugin'
 
 export function apply(ctx: Context) {
-  // 监听 agent-loop 的 ready 事件
-  ctx.on('ready', () => {
-    console.log('[hello-plugin] 插件已加载!')
-  })
+  // apply 函数体在插件加载时执行
+  console.log('[hello-plugin] 插件已加载!')
 }
 ```
 
@@ -52,7 +50,9 @@ export function apply(ctx: Context) {
 
 如果你有需要手动清理的资源（比如一个网络连接），用 `ctx.effect()` 告诉框架怎么清理：
 
-```typescript
+```ts
+import type { Context } from 'cordis'
+
 export function apply(ctx: Context) {
   ctx.effect(() => {
     const timer = setInterval(() => {
@@ -69,13 +69,23 @@ export function apply(ctx: Context) {
 
 如果你的插件需要使用其他服务（如 `tools`、`llm`），需要声明 `inject`：
 
-```typescript
+```ts
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
 export const name = 'my-tool-plugin'
 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 []
+    },
+  }))
 }
 ```
 
@@ -87,7 +97,10 @@ export function apply(ctx: Context) {
 
 ### 对象形式
 
-```typescript
+```ts
+import type { Context } from 'cordis'
+import type {} from '@deepseek-ai/dsh-tools'
+
 export default {
   name: 'my-plugin',
   inject: ['tools'],
@@ -99,8 +112,9 @@ export default {
 
 ### 类形式
 
-```typescript
-import { Service } from 'cordis'
+```ts
+import { Service, type Context } from 'cordis'
+import type {} from '@deepseek-ai/dsh-tools'
 
 export default class MyService extends Service {
   static inject = ['tools']
@@ -109,8 +123,9 @@ export default class MyService extends Service {
     super(ctx, 'myService')
   }
 
-  start() {
-    // 服务启动逻辑
+  // 服务的公开方法
+  greet(name: string) {
+    return `Hello, ${name}!`
   }
 }
 ```
@@ -121,7 +136,7 @@ export default class MyService extends Service {
 
 参考仓库中的 `examples/echo-agent/src/echo-tool.ts`，这是一个注册 tool 的插件：
 
-```typescript
+```ts
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 

website/zh-CN/develop/basic/tool.md

@@ -4,7 +4,7 @@ Tool 是模型可以调用的能力。本文介绍如何用 `defineTool` 编写
 
 ## 最小示例
 
-```typescript
+```ts
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 
@@ -32,28 +32,34 @@ export function apply(ctx: Context) {
 
 ### 基本类型
 
-```typescript
-parameters: {
+```ts
+import type { SchemaSpec } from '@deepseek-ai/dsh-tools'
+
+const parameters = {
   path: { type: 'string', required: true },
   limit: { type: 'number' },
   recursive: { type: 'boolean' },
-}
+} satisfies SchemaSpec
 // 推导类型: { path: string; limit?: number; recursive?: boolean }
 ```
 
 ### 枚举
 
-```typescript
-parameters: {
+```ts
+import type { SchemaSpec } from '@deepseek-ai/dsh-tools'
+
+const parameters = {
   mode: { type: 'string', required: true, enum: ['read', 'write', 'append'] },
-}
+} satisfies SchemaSpec
 // 推导类型: { mode: string }  (运行时校验 enum 值)
 ```
 
 ### 嵌套对象
 
-```typescript
-parameters: {
+```ts
+import type { SchemaSpec } from '@deepseek-ai/dsh-tools'
+
+const parameters = {
   options: {
     type: 'object',
     properties: {
@@ -61,19 +67,21 @@ parameters: {
       retries: { type: 'number' },
     },
   },
-}
+} satisfies SchemaSpec
 // 推导类型: { options?: { timeout?: number; retries?: number } }
 ```
 
 ### 数组
 
-```typescript
-parameters: {
+```ts
+import type { SchemaSpec } from '@deepseek-ai/dsh-tools'
+
+const parameters = {
   tags: {
     type: 'array',
     items: { type: 'string' },
   },
-}
+} satisfies SchemaSpec
 // 推导类型: { tags?: string[] }
 ```
 
@@ -92,29 +100,44 @@ parameters: {
 
 `execute` 接收经过校验的 `args`（类型自动推导）和一个 `exec` 上下文对象：
 
-```typescript
-async execute(args, exec) {
-  // args: 根据 parameters 自动推导的类型
-  // exec: ToolExecution 对象，提供执行上下文
+```ts
+import { defineTool } from '@deepseek-ai/dsh-tools'
 
-  // 返回 ContentBlock 数组
-  return [{ type: 'text', text: 'result here' }]
-}
+defineTool({
+  name: 'demo',
+  description: 'Demo tool.',
+  parameters: {},
+  async execute(args, exec) {
+    // args: 根据 parameters 自动推导的类型
+    // exec: ToolExecution 对象，提供执行上下文
+
+    // 返回 ContentBlock 数组
+    return [{ type: 'text', text: 'result here' }]
+  },
+})
 ```
 
 ### 返回值
 
 `execute` 必须返回一个 `ContentBlock[]`，告诉模型 tool 的执行结果：
 
-```typescript
+```ts
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+
+declare const matchResults: string[]
+
 // 文本结果
-return [{ type: 'text', text: 'file content here...' }]
+function textResult(): ContentBlock[] {
+  return [{ type: 'text', text: 'file content here...' }]
+}
 
 // 多个 block
-return [
-  { type: 'text', text: 'Found 3 matches:' },
-  { type: 'text', text: matchResults.join('\n') },
-]
+function multiBlockResult(): ContentBlock[] {
+  return [
+    { type: 'text', text: 'Found 3 matches:' },
+    { type: 'text', text: matchResults.join('\n') },
+  ]
+}
 ```
 
 ### 参数校验
@@ -127,20 +150,28 @@ return [
 
 Tool 可以定义 UI 渲染方法，用于在终端或 ACP 客户端中展示 tool call 和 result：
 
-```typescript
+```ts
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
 defineTool({
   name: 'bash',
-  // ...
+  description: 'Run a shell command.',
+  parameters: {
+    command: { type: 'string', required: true },
+  },
+  async execute(args) {
+    return [{ type: 'text', text: `ran: ${args.command}` }]
+  },
   presentCall(args) {
     return {
-      intent: 'terminal',
-      title: `bash(${JSON.stringify(args.command).slice(0, 60)})`,
+      card: 'terminal',
+      title: args.command.slice(0, 60),
     }
   },
   presentResult(args, result) {
     return {
-      intent: 'terminal',
-      body: result.content.map(b => b.type === 'text' ? b.text : '').join(''),
+      card: 'terminal',
+      output: result.content.map(b => b.type === 'text' ? b.text : '').join(''),
     }
   },
 })
@@ -152,20 +183,32 @@ defineTool({
 
 `ctx.tools.register()` 返回值就是 disposer。但由于你在 `ctx` 上调用，框架已经自动追踪了这个注册——插件卸载时会自动移除 tool。你不需要手动调用 disposer。
 
-```typescript
+```ts
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+declare const ctx: Context
+
 // 这样就够了:
-ctx.tools.register(defineTool({ /* ... */ }))
+ctx.tools.register(defineTool({
+  name: 'noop',
+  description: 'Do nothing.',
+  parameters: {},
+  async execute() {
+    return []
+  },
+}))
 
 // 不需要:
 // const dispose = ctx.tools.register(...)
-// ctx.on('dispose', dispose)
+// ctx.effect(() => dispose)
 ```
 
 ## 完整实战示例
 
 一个文件计数 tool：
 
-```typescript
+```ts
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { readdir } from 'node:fs/promises'