Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification

# Conflicts: # .agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml # .agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md # .agents/notes/implemented/architecture/2026-06-11-event-sourced-sessions.i18n.yaml # .agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.i18n.yaml # .agents/notes/implemented/architecture/2026-06-11-microkernel-event-taxonomy.zh.md # .agents/notes/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.i18n.yaml # .agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml # .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml # .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.zh.md # .agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.i18n.yaml # .agents/notes/implemented/architecture/2026-06-30-event-domain-semantics.zh.md # .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml # .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md # .agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml # .agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md # .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml # .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md # .agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml # .agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml # .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml # .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml # .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md # .agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.i18n.yaml # .agents/notes/implemented/architecture/2026-07-24-separate-context-injection-from-turn-execution.zh.md # .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml # .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md # .agents/notes/implemented/architecture/2026-07-28-identified-immutable-message-values.i18n.yaml # .agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.i18n.yaml # .agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.zh.md # .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml # .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md # .agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml # .agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md # .agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml # .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.i18n.yaml # .agents/notes/implemented/feature/2026-06-30-hook-protocol-lib.zh.md # .agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml # .agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md # .agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml # .agents/notes/implemented/feature/2026-07-06-sandbox.zh.md # .agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml # .agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md # .agents/notes/implemented/feature/2026-07-16-harness-level-loop.i18n.yaml # .agents/notes/implemented/feature/2026-07-16-harness-level-loop.zh.md # .agents/notes/implemented/feature/2026-07-19-human-goal-command.i18n.yaml # .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml # .agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.i18n.yaml # .agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.zh.md # .agents/notes/implemented/feature/2026-07-19-plugin-command-registration.i18n.yaml # .agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml # .agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.zh.md # .agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml # .agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md # .agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml # .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml # .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml # .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md # .agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.i18n.yaml # .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.i18n.yaml # .agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.zh.md # .agents/notes/implemented/simplification/2026-07-24-agent-loop-observable-state-machine.i18n.yaml # .agents/notes/implemented/simplification/2026-07-27-request-error-retry-action.i18n.yaml # docs/core-data-structures/compaction.i18n.yaml # docs/core-data-structures/goal.i18n.yaml # docs/core-data-structures/goal.zh.md # docs/core-data-structures/llm-streaming.i18n.yaml # docs/core-data-structures/session.i18n.yaml # docs/core-data-structures/session.zh.md # docs/core-data-structures/skills.i18n.yaml # docs/core-data-structures/skills.zh.md # docs/core-data-structures/system-prompt.i18n.yaml # docs/defensive-patterns.i18n.yaml # docs/defensive-patterns.zh.md # docs/user/develop/framework/events.i18n.yaml # docs/user/develop/framework/events.zh.md # packages/acp/acp/README.i18n.yaml # packages/client/ui-goal/README.i18n.yaml # packages/compact/compact-basic/README.i18n.yaml # packages/compact/compact/README.i18n.yaml # packages/context/time-context/README.i18n.yaml # packages/context/tmux-context/README.i18n.yaml # packages/core/agent-loop/README.i18n.yaml # packages/core/agent-loop/README.zh.md # packages/core/agent/README.i18n.yaml # packages/core/agent/README.zh.md # packages/core/session/README.i18n.yaml # packages/core/session/README.zh.md # packages/core/system-prompt/README.i18n.yaml # packages/core/system-prompt/README.zh.md # packages/examples/cli-demo/README.i18n.yaml # packages/goal/command-goal/README.i18n.yaml # packages/goal/goal-session/README.i18n.yaml # packages/goal/goal/README.i18n.yaml # packages/goal/tool-goal/README.i18n.yaml # packages/goal/tool-goal/README.zh.md # packages/guard/README.i18n.yaml # packages/guard/README.zh.md # packages/guard/repeat-tool-guard/README.i18n.yaml # packages/hooks/hooks-claude/README.i18n.yaml # packages/hooks/hooks-codex/README.i18n.yaml # packages/host/apiproxy/README.i18n.yaml # packages/host/apiproxy/README.zh.md # packages/llm/llm/README.i18n.yaml # packages/plan/plan-mode/README.i18n.yaml # packages/plan/plan-mode/README.zh.md # packages/sdk/sdk-client/README.i18n.yaml # packages/sdk/sdk-client/README.zh.md # packages/sdk/sdk-protocol/README.i18n.yaml # packages/session-persistence/session-persistence/README.i18n.yaml # packages/session-persistence/session-persistence/README.zh.md # packages/skill/tool-skill/README.i18n.yaml # packages/subagent/subagent-dsh-sdk/README.i18n.yaml # packages/subagent/subagent-inprocess/README.i18n.yaml # packages/subagent/subagent-inprocess/README.zh.md # packages/ui/jsonrpc/README.i18n.yaml
2026-08-15 21:04:50 +00:00 · 2026-08-05 13:09:53 +08:00
parent 86b91f1c4c c7f693aa40
commit 02efe3ccea
948 changed files with 3046 additions and 2959 deletions
--- a/docs/user/develop/framework/events.i18n.yaml
+++ b/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: fcbdb5f39bf2078032affbc6469f7eecc795d3ba
-events.zh.md: 8b96f27fd6930ca9a481be60f93bcd834901d5dc
+events.zh.md: 1979e0bc1dbb71e46f50a051dacee8ae3a1172a7
--- a/docs/user/develop/framework/events.zh.md
+++ b/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 声明合并来为事件提供类型安全：

@@ -105,7 +105,7 @@ Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/pre-st

 `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 后端
--- a/docs/user/develop/framework/index.i18n.yaml
+++ b/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
--- a/docs/user/develop/framework/index.zh.md
+++ b/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) — 在插件之间通信
--- a/docs/user/develop/framework/service.i18n.yaml
+++ b/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
--- a/docs/user/develop/framework/service.zh.md
+++ b/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/) — 将服务用作能力接口