docs(i18n): proofread active Chinese documentation

docs/user/develop/framework/events.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
+#   pnpm run verify-translation-pairing --write docs/user/develop/framework/events.md
 events.md: 5cd5d22f854d0b4e271e892cbdb1ccebe687ae49
-events.zh.md: 5fd4d5de53897e32523ab478626965ad7c9602ba
+events.zh.md: 91082694c7546c0b2b77d9fddbd36b14a38a2a8c

docs/user/develop/framework/events.zh.md

@@ -22,11 +22,11 @@ ctx.emit('event-name', payload)
 
 ## 事件模式
 
-Cordis 提供多种事件触发模式，适用于不同场景：
+Cordis 提供多种事件模式，适用于不同的交互契约：
 
 ### emit — 广播
 
-所有监听器同步执行，不关心返回值：
+所有监听器同步执行，返回值会被忽略：
 
 ```ts ignore-check
 // Emit
@@ -40,7 +40,7 @@ ctx.on('my-plugin/ready', ({ id }) => {
 
 ### bail — 短路
 
-依次调用监听器，第一个返回非 `undefined` 值的结果作为最终值：
+依次调用监听器，第一个非 `undefined` 的返回值将作为最终结果：
 
 ```ts ignore-check
 // Dispatch
@@ -61,7 +61,7 @@ ctx.on('some-check', (input) => {
 await ctx.serial('setup-phase', context)
 ```
 
-### waterfall — 管道
+### waterfall（瀑布式事件）— 流水线
 
 每个监听器可以包装下游返回值，形成处理链。**必须调用 `next()` 传递给下游**，不调用即为否决：
 
@@ -77,10 +77,10 @@ ctx.on('my-plugin/transform', async (_input, next) => {
 ```
 
 ::: warning
-Waterfall 监听器**必须调用 `next()`**。不调用 `next` 等于否决整个管道，这是故意为之的设计——用于实现拦截/网关逻辑。
+waterfall 监听器**必须调用 `next()`**。不调用 `next` 等于否决整个流水线，这是故意为之的设计——用于实现拦截/网关逻辑。
 :::
 
-## Typed Events
+## 类型安全的事件
 
 Harness 使用 TypeScript 声明合并来为事件提供类型安全：
 
@@ -101,11 +101,11 @@ declare module 'cordis' {
 
 ## Cordis 事件与会话记录
 
-Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[Events 目录](../../../cordis-catalog/events.md)。
+Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。生成的[事件目录](../../../cordis-catalog/events.md)记录了完整签名与触发模式。
 
 `turn/*`、`step/*`、`tool/call`、`tool/result` 和 `compact/*` 是持久化的会话事件类型，不是同名 Cordis 事件。需要观察它们时，监听 `session/event` 并检查 `event.type`。
 
-## 事件也是效果
+## 事件监听器也是效果
 
 通过 `ctx.on()` 注册的监听器会在插件卸载时自动移除：
 
@@ -116,9 +116,9 @@ export function apply(ctx: Context) {
 }
 ```
 
-## 实战示例：日志插件
+## 示例：日志插件
 
-一个记录所有 tool 调用的简单插件：
+这个插件记录工具调用和工具结果：
 
 ```ts
 import type { Context } from 'cordis'
@@ -139,5 +139,5 @@ export function apply(ctx: Context) {
 
 ## 下一步
 
-- [能力三件套](../practice/) — 事件在 capability seam 中的角色
-- [LLM 适配器](../practice/llm-adapter.md) — 实现一个完整的 LLM 后端
+- [能力分层](../practice/) — 了解能力接口中的事件
+- [LLM（大语言模型）适配器](../practice/llm-adapter.md) — 实现一个完整的 LLM 后端

docs/user/develop/framework/index.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
+#   pnpm run verify-translation-pairing --write docs/user/develop/framework/index.md
 index.md: 79e925b54509da41535735527e283850384257ec
-index.zh.md: 62be8c706510704f7b07286f166f14fa81235a0a
+index.zh.md: 962677dc468c9cc233a51d50758247e028d9c3ed

docs/user/develop/framework/index.zh.md

@@ -2,11 +2,11 @@
 
 [English](index.md) | 中文
 
-深入了解 Cordis 插件模型和生命周期状态机。
+本页介绍 Cordis 插件模型和生命周期状态机。
 
 ## Fiber 状态机
 
-每个被加载的插件对应一个 **Fiber**（作用域）。Fiber 有以下状态：
+每个被加载的插件都拥有一个 **Fiber** 作用域，其状态如下：
 
 ```
 PENDING → LOADING → ACTIVE
@@ -16,16 +16,16 @@ ACTIVE → UNLOADING → DISPOSED
 
 | 状态 | 含义 |
 |------|------|
-| PENDING | 已声明但依赖未就绪 |
+| PENDING | 已声明，但所需依赖未就绪 |
 | LOADING | 依赖就绪，正在执行 `apply` |
 | ACTIVE | 插件运行中 |
 | FAILED | `apply` 抛出异常 |
-| UNLOADING | 正在卸载，清理中 |
+| UNLOADING | 插件正在卸载并释放资源 |
 | DISPOSED | 已完全卸载 |
 
 ## 依赖驱动的加载
 
-声明了 `inject` 的插件不会立即加载，而是等待依赖的服务就绪：
+声明了 `inject` 的插件会等待所有必需服务就绪：
 
 ```ts ignore-check
 export const inject = ['tools', 'llm']
@@ -35,7 +35,7 @@ export function apply(ctx: Context) {
 }
 ```
 
-如果依赖的服务消失（比如提供者被热替换），插件会被自动卸载（ACTIVE → DISPOSED），待服务恢复后重新加载。
+如果依赖的服务消失（例如提供方被替换时），插件会被自动卸载（ACTIVE → DISPOSED），待服务恢复后重新加载。
 
 ## 自动清理机制
 
@@ -56,11 +56,11 @@ export function apply(ctx: Context) {
 
 以下操作都会被自动追踪和清理：
 - `ctx.on(event, handler)` — 事件监听
-- `ctx.tools.register(tool)` — tool 注册
-- `ctx.llm.registerAdapter(names, adapter)` — LLM 适配器注册
+- `ctx.tools.register(tool)` — 工具注册
+- `ctx.llm.registerAdapter(names, adapter)` — LLM（大语言模型）适配器注册
 - `ctx.effect(() => cleanup)` — 自定义资源
 
-插件卸载时，处置器按注册顺序的反向发起，但多个异步处置器会并发执行，不保证逐个完成。存在顺序依赖的清理步骤必须放进同一个 `ctx.effect()` 返回的处置器中，由该处置器负责串行等待。
+插件卸载时，处置器按注册顺序的逆序开始调用，但多个异步处置器会并发执行，不保证逐个完成。存在顺序依赖的清理步骤必须放进同一个 `ctx.effect()` 返回的处置器中，由该处置器负责串行等待。
 
 ## 嵌套上下文
 
@@ -75,7 +75,7 @@ export function apply(ctx: Context) {
 }
 ```
 
-## dispose 语义
+## dispose（资源释放）语义
 
 当你需要提前终止一个插件实例：
 
@@ -92,21 +92,21 @@ await fiber.dispose()
 ```
 
 `dispose` 保证：
-1. 该插件注册的所有东西被撤销
+1. 该插件拥有的所有注册均被移除
 2. 它的子插件也被递归卸载
-3. 所有异步清理完成后 Promise resolve
+3. 返回的 Promise 会在所有异步清理完成后兑现
 
-## 热替换 (HMR)
+## HMR（热模块替换）
 
-在开发环境中（`cordis.yml` 加载了 `@cordisjs/plugin-hmr`），修改插件源文件会自动触发：
+通过 `cordis.yml` 加载 `@cordisjs/plugin-hmr` 后，修改插件源文件会触发：
 
 1. 卸载旧插件（清理所有注册）
 2. 重新加载新代码
 3. 执行新的 `apply`
 
-因为所有注册都会被自动清理，所以热替换天然安全——不会留下旧状态。
+因为插件注册会被自动清理，所以热替换不会保留旧实例的注册。
 
-## 实战：理解生命周期
+## 生命周期示例
 
 ```ts ignore-check
 export function apply(ctx: Context) {
@@ -132,5 +132,5 @@ effect cleaned up
 
 ## 下一步
 
-- [服务与依赖](./service.md) — 让你的插件对外提供能力
-- [事件系统](./events.md) — 插件间通信的核心机制
+- [服务与依赖](./service.md) — 让插件向其他插件提供能力
+- [事件系统](./events.md) — 在插件之间通信

docs/user/develop/framework/service.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
+#   pnpm run verify-translation-pairing --write docs/user/develop/framework/service.md
 service.md: 1bf28cb3c7dfdfbd6d0babfa3b1688ac65eea01e
-service.zh.md: 17785c056ab9a0a21974e6ed8bbe7f7de05fa00e
+service.zh.md: 78b9887a734b235bcff1d94a623e37cfeb2f41e3

docs/user/develop/framework/service.zh.md

@@ -2,7 +2,7 @@
 
 [English](service.md) | 中文
 
-服务 (Service) 是插件对外暴露能力的方式。依赖 (inject) 是插件声明自己需要哪些服务。
+服务是一个插件向其他插件公开的能力。inject 声明插件需要哪些服务。
 
 ## 什么是服务
 
@@ -14,7 +14,7 @@ ctx.llm      // LLM service
 ctx.agents   // Agent service
 ```
 
-任何插件都可以提供一个新服务，供其他插件使用。
+任何插件都可以提供服务，供其他插件使用。
 
 ## 使用服务
 
@@ -52,7 +52,7 @@ export default class MetricsService extends Service {
 }
 ```
 
-加载这个插件后，其他插件就可以通过 `ctx.metrics` 访问它：
+加载这个插件后，消费方就可以通过 `ctx.metrics` 访问它：
 
 ```ts ignore-check
 export const inject = ['metrics']
@@ -86,7 +86,7 @@ export default class MetricsService extends Service {
 
 ## 依赖的行为
 
-### 必选依赖 vs 可选依赖
+### 必需依赖与可选依赖
 
 ```ts ignore-check
 // Required: the plugin does not load while the service is absent.
@@ -101,12 +101,12 @@ export function apply(ctx: Context) {
 
 ### 服务消失时的行为
 
-如果一个必选依赖的服务在运行时消失（比如提供者被卸载）：
+如果应用运行期间某项必需服务消失（例如其提供方卸载）：
 
-1. 依赖它的插件自动 dispose
+1. 依赖它的插件会自动 dispose（资源释放）
 2. 当服务重新出现时，插件自动重新加载
 
-这保证了不会出现"调用一个已不存在的服务"的情况。
+这可以防止插件调用已不存在的服务。
 
 ## 服务隔离
 
@@ -136,13 +136,13 @@ export function apply(ctx: Context) {
     - name: './src/plugin-b.ts'
 ```
 
-`plugin-a` 和 `plugin-b` 各自看到自己组内的 bash 实例，互不影响。
+`plugin-a` 和 `plugin-b` 各自看到自己组内的 Bash 实例，互不影响。
 
 ## Harness 内置服务
 
-服务名、公开方法和源码位置由仓库自动生成，见[服务目录](../../../cordis-catalog/services.md)。开发插件时应以该目录和服务接口的 TypeScript 类型为准，不要复制一份静态清单。
+仓库会自动生成[服务目录](../../../cordis-catalog/services.md)，其中包含服务名、公开方法和源码位置。开发插件时应以该目录和服务的 TypeScript 接口为准，不要维护另一份静态清单。
 
 ## 下一步
 
 - [事件系统](./events.md) — 插件间松耦合通信
-- [能力三件套](../practice/) — 服务在 seam 模式中的应用
+- [能力分层](../practice/) — 将服务用作能力接口