docs: rescan rebased documentation hierarchy

2026-08-05 12:46:38 +08:00
parent 012bb0a549
commit 8af3babaea
304 changed files with 1091 additions and 1983 deletions
--- a/packages/support/README.i18n.yaml
+++ b/packages/support/README.i18n.yaml
@@ -2,5 +2,5 @@
 # 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 packages/support/README.md
-README.md: b9550fd54feb36448227faae8485fe8b6dbf4fb0
-README.zh.md: 1b7464e0cab4460e587f2b5c8afa58d28116bab1
+README.md: 15cb82d3d76a1241af8b40e1c8536292618409a9
+README.zh.md: ff8595b47f1a1220912dc77a072463adf74f7bf9
--- a/packages/support/README.zh.md
+++ b/packages/support/README.zh.md
@@ -1,16 +1,16 @@
-# support/：开发／测试／示例基础设施
+# support/：开发和测试基础设施

 [English](README.md) | 中文

-这些包用于开发、测试和示例，而非作为产品 API 发布。它们是实际的工作区包（具备类型、经过测试，并受覆盖率门禁约束），但具有**较低的兼容性预期**：当其背后的开发需求变化时，它们可以改变或被移除，无需像产品包那样谨慎执行弃用流程。
+这些包为仓库开发、测试和示例提供支持，而不是产品 API。其兼容性取决于所服务的开发需求。

-| 包 | 职责 | ctx 键 |
-|---|---|---|
-| `acp-snapshot/` | ACP（Agent Client Protocol）测试工具包：共享子进程/客户端启动器、快照 harness、规范化器和套件工厂 | （库：由 ACP e2e 和 `*.snapshot.ts` 套件导入） |
-| `agent-loop-testkit/` | 为验证具体 agent loop（智能体循环）的测试挂载共享先决条件 | （库：由 AgentLoop 集成测试导入） |
-| `invariants/` | 用于开发诊断的运行时事件契约断言 | （监听 `session/*`、`agent/*`） |
-| `loader-smoke/` | 共享的真实 Loader 子进程 harness，用于无密钥示例冒烟测试 | （库：由示例 e2e 套件导入） |
-| `llm-mock-server/` | 可编程的 OpenAI 兼容 HTTP/SSE（Server-Sent Events）故障服务器与 CLI（命令行界面），用于 LLM（大语言模型）恢复测试 | （独立服务器和测试库） |
-| `llm-replay/` | 录制/回放适配器：通过已记录的会话 JSONL 对 `llm/stream` 进行短路处理（无密钥快照测试） | （监听 `llm/stream`） |
+| 包 | 职责 |
+|---|---|
+| [`acp-snapshot/`](acp-snapshot/README.md) | 提供 ACP（Agent Client Protocol）快照测试工具包 |
+| [`agent-loop-testkit/`](agent-loop-testkit/README.md) | 为 AgentLoop 测试挂载共享先决条件 |
+| [`invariants/`](invariants/README.md) | 运行开发期运行时契约断言 |
+| [`loader-smoke/`](loader-smoke/README.md) | 启动由 Loader 组合的应用以执行冒烟测试 |
+| [`llm-mock-server/`](llm-mock-server/README.md) | 提供确定性的 OpenAI 兼容故障服务器 |
+| [`llm-replay/`](llm-replay/README.md) | 为无密钥测试和演示回放已记录的模型响应 |

-`invariants` 是开发支持，但没有环境条件限制：无论在何处注册，它都会运行；默认 `dsh-agent-spine-demo` bundle 无条件挂载它。`agent-loop-testkit` 为手工构建的 AgentLoop 测试集中管理必需服务主干，而不负责其 agent loop 或场景。`llm-replay` 支撑演示和受逐文件覆盖率门禁约束的快照测试层，`llm-mock-server` 则通过确定性 HTTP/SSE 故障驱动真实提供方适配器。`acp-snapshot` 包含 ACP 子进程/客户端边界以及快照 harness、规范化器和套件机制，`loader-smoke` 负责无密钥示例 e2e 套件使用的并列真实 Loader 启动边界。只有当某个包获得文档记载的产品消费方时，它才会从 `support/` 转入产品分组。
+当一个包获得产品契约和产品消费方时，它会移出 `support/`。
--- a/packages/support/acp-snapshot/README.i18n.yaml
+++ b/packages/support/acp-snapshot/README.i18n.yaml
@@ -2,5 +2,5 @@
 # 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 packages/support/acp-snapshot/README.md
-README.md: c8fe6907848a7b661c4bfb60c871f077753fda8b
-README.zh.md: 0aa28f4b2c3df1a30e5fd33a80401712f81d6614
+README.md: ff8b89437703e0d63542f2a004f9b0929171010e
+README.zh.md: 582285363f6556fcc68d783e2ceedc7eb007dafd
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -59,7 +59,7 @@ Every scenario compares `stdout.expected.jsonl` with cwd-rooted separators canon

 The example also ships a `cordis.snapshot.yml` replay overlay next to its `cordis.yml` (the bin swaps them under `DSH_SNAPSHOT=replay` — [single-source replay config Agent Note](../../../.agents/notes/archived/testing/2026-07-04-single-source-acp-replay-config.md)); replay fixtures are served by [`dsh-llm-replay`](../llm-replay/README.md), which this package points at via the `DSH_SNAPSHOT_*` env vars it sets on the child. `pnpm run test:snapshot:record` calls the live LLM and rewrites the recorded scenarios' model fixtures; `pnpm run test:snapshot:refresh` stays keyless, runs the replay overlay, and rewrites stdout, comparable session-log expected outputs, and owned prompt and tool-schema sidecars from the committed model scripts. Fixture roles, record/replay/refresh semantics, and scenario-table fields are documented on `Scenario` and in the [snapshot Agent Note](../../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md).

-Constraints: `suite.ts` and `harness.ts` import vitest (the harness polls its durable-boundary waits through `vi.waitFor`), so the package entry is importable only inside a vitest run (the launcher and normalizers have no such dependency but ship from the same entry). The launcher and suite factory are ACP-specific by design — the launcher speaks the SDK's `ClientSideConnection` — while the normalizers are transport-neutral session-log/text helpers also consumed by the TUI snapshot suite and the web browser e2e lane. Input scripts cover initialization, fresh-session creation, text prompting, cancellation, expected RPC failures, and durable turn-boundary waits. Permission round-trips are a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) mapped to the agent-issued `optionId`; an absent or exhausted queue answers `cancelled`, and an unoffered kind rejects the run.
+Constraints: `suite.ts` and `harness.ts` import vitest (the harness polls its durable-boundary waits through `vi.waitFor`), so the package entry is importable only inside a vitest run (the launcher and normalizers have no such dependency but ship from the same entry). The launcher and suite factory are ACP-specific by design — the launcher speaks the SDK's `ClientSideConnection` — while the normalizers are transport-neutral session-log/text helpers also consumed by the Web browser e2e lane. Input scripts cover initialization, fresh-session creation, text prompting, cancellation, expected RPC failures, and durable turn-boundary waits. Permission round-trips are a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) mapped to the agent-issued `optionId`; an absent or exhausted queue answers `cancelled`, and an unoffered kind rejects the run.

 ## Model Experience

--- a/packages/support/acp-snapshot/README.zh.md
+++ b/packages/support/acp-snapshot/README.zh.md
@@ -59,7 +59,7 @@ defineAcpSnapshotSuite({

 示例还发布 `cordis.snapshot.yml` 回放 overlay，位于 `cordis.yml` 旁边（bin 在 `DSH_SNAPSHOT=replay` 下交换它们，见[单源回放配置 Agent Note](../../../.agents/notes/archived/testing/2026-07-04-single-source-acp-replay-config.md)）；回放 fixture 由 [`dsh-llm-replay`](../llm-replay/README.md) 提供，该包通过对子级设置的 `DSH_SNAPSHOT_*` env var 指向它。`pnpm run test:snapshot:record` 调用实时 LLM，并重写已记录场景的模型 fixture；`pnpm run test:snapshot:refresh` 保持无密钥，运行回放 overlay，并从已提交模型脚本重写 stdout、可比较会话日志预期输出，以及各 pin 自有的提示词与工具 schema sidecar。Fixture 角色、录制/回放/刷新语义和场景表字段记录在 `Scenario` 以及[快照 Agent Note](../../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md) 中。

-约束：`suite.ts` 与 `harness.ts` 导入 vitest（harness 通过 `vi.waitFor` 轮询其持久边界等待），因此包入口只能在 vitest 运行中导入（启动器和规范化器没有此依赖，但从同一入口发布）。启动器和套件工厂按设计专用于 ACP，启动器使用 SDK 的 `ClientSideConnection`；规范化器是与传输无关的会话日志/文本辅助工具，还由 TUI 快照套件和 web 浏览器 e2e lane 消费。输入脚本覆盖初始化、新建会话、文本提示、取消、预期 RPC 失败和持久轮次边界等待。权限往返是选项类别选择（`allow_once`、`reject_once`等）的 FIFO 队列，映射到 agent 发出的 `optionId`；缺少或耗尽的队列回答 `cancelled`，未提供类别会拒绝运行。
+约束：`suite.ts` 与 `harness.ts` 导入 vitest（harness 通过 `vi.waitFor` 轮询其持久边界等待），因此包入口只能在 vitest 运行中导入（启动器和规范化器没有此依赖，但从同一入口发布）。启动器和套件工厂按设计专用于 ACP，启动器使用 SDK 的 `ClientSideConnection`；规范化器是与传输无关的会话日志/文本辅助工具，还由 Web 浏览器 e2e lane 消费。输入脚本覆盖初始化、新建会话、文本提示、取消、预期 RPC 失败和持久轮次边界等待。权限往返是选项类别选择（`allow_once`、`reject_once` 等）的 FIFO 队列，映射到 agent 发出的 `optionId`；缺少或耗尽的队列回答 `cancelled`，未提供类别会拒绝运行。

 ## 模型体验

--- a/packages/support/llm-replay/README.i18n.yaml
+++ b/packages/support/llm-replay/README.i18n.yaml
@@ -2,5 +2,5 @@
 # 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 packages/support/llm-replay/README.md
-README.md: 85aa56705929e7630e4cfb6c2a3c9cbbd0d843a6
-README.zh.md: dfa43cf78c2b584fe4868603feb3fbcfb909e099
+README.md: ee062d0c2804905f33f1ff476d12bb6dd57666e5
+README.zh.md: ab3420d9500a6ca77f04a2ad96095f8883aeb874
--- a/packages/support/llm-replay/README.md
+++ b/packages/support/llm-replay/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)

 A replay LLM plugin for keyless snapshot tests. It yields model streams reconstructed from a recorded **session JSONL** fixture, so a test can boot the real agent against a fixed model transcript with no API key. With `providers` configured it registers a replay-only adapter whose catalog is available to scenarios that exercise model discovery; without `providers` it installs the catch-all `llm/stream` waterfall used by tests that do not need discovery.

-Its consumers are the ACP, headless `stream-json`, and TUI snapshot suites plus the web browser e2e lane. Loader-driven suites mount this plugin in place of a real LLM adapter; the web lane installs it directly to retain the teardown consumption handle. Keeping derivation and replay here places that logic under the per-file 100% coverage gate on `packages/*/src`.
+Its consumers are the ACP and headless `stream-json` snapshot suites plus the Web browser e2e lane. Loader-driven suites mount this plugin in place of a real LLM adapter; the Web lane installs it directly to retain the teardown consumption handle.

 ## How the fixture works

--- a/packages/support/llm-replay/README.zh.md
+++ b/packages/support/llm-replay/README.zh.md
@@ -4,7 +4,7 @@

 用于无密钥快照测试的 LLM（大语言模型）回放插件。它根据已记录的**会话 JSONL** fixture（测试前置数据）重建模型流，使测试无需 API 密钥即可针对固定的模型 transcript（文本记录）启动真实 agent（智能体）。配置 `providers` 后，它会注册仅用于回放的适配器，其模型目录可供测试模型发现功能的场景使用；未配置 `providers` 时，它会安装无需模型发现功能的测试所用 catch-all `llm/stream` waterfall（瀑布式事件）。

-其消费方包括 ACP（Agent Client Protocol）、headless `stream-json` 和 TUI 快照套件，以及 Web 浏览器 e2e 流水线。Loader 驱动的套件使用此插件替代真实 LLM 适配器；Web 流水线直接安装它，以保留清理阶段的消费检查句柄。将派生和回放逻辑放在此处，可使其受 `packages/*/src` 的逐文件 100% 覆盖率门禁约束。
+其消费方包括 ACP（Agent Client Protocol）与 headless `stream-json` 快照套件，以及 Web 浏览器 e2e 流水线。Loader 驱动的套件使用此插件替代真实 LLM 适配器；Web 流水线直接安装它，以保留清理阶段的消费检查句柄。

 ## fixture 的工作方式