Merge remote-tracking branch 'origin/master' into web-e2e-lane

# Conflicts: # docs/config-catalog.md # docs/testing.i18n.yaml # docs/testing.md # docs/testing.zh.md # packages/host/runtime/src/start.ts # packages/support/acp-snapshot/README.md
2026-07-25 14:20:19 +08:00
parent 9c4bc3e516 cd68b00d15
commit fb17d5ec49
650 changed files with 13582 additions and 24526 deletions
@@ -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
-2026-07-03-documentation-graph-atlas.md: 9a30b13f9db6ceb2715517230e349cbe083850ec
-2026-07-03-documentation-graph-atlas.zh.md: 0734a2c659459f40ee81b9960f259681cb35891c
+2026-07-03-documentation-graph-atlas.md: 8b532fdd6f600eba05411588f8277b7cc43b3613
+2026-07-03-documentation-graph-atlas.zh.md: d426735407c0395fd96aed65a49aea0f0fdf6a90
@@ -28,7 +28,7 @@ Every graph page declares one maintenance mode:

 ### First shipped index

-The index links eleven relationship surfaces. Package topology and tool-package affordances live in the existing generated catalogs that already own those facts; the remaining focused diagrams are generated by `scripts/gen-doc-graphs.ts`.
+The index links ten relationship surfaces. Package topology and tool-package affordances live in the existing generated catalogs that already own those facts; the remaining focused diagrams are generated by `scripts/gen-doc-graphs.ts`.

 | Graph | Maintenance mode | Source of truth |
 |---|---|---|
@@ -42,7 +42,6 @@ The index links eleven relationship surfaces. Package topology and tool-package
 | [event producer/consumer matrix](../../../../docs/event-producer-consumer.md) | hybrid generated | Cordis event declarations, AST-scanned `ctx.on/emit/parallel/serial/waterfall` sites, and explicit dynamic dispatch overrides |
 | [agent turn and step lifecycle](../../../../docs/agent-lifecycle.md) | curated | architecture.md loop lifecycle, Cordis catalog links, and session event semantics |
 | [tool execution pipeline](../../../../docs/tool-execution-pipeline.md) | curated | tool pipeline semantics and the `tools/execute` waterfall |
-| [ACP snapshot replay](../../../../packages/ui/acp/snapshot-replay.md) | curated | snapshot harness behavior |

 ### Why generators own the docs

@@ -64,7 +63,7 @@ Committed diagrams use Mermaid because GitHub renders it in Markdown and it adds

 ## Consequences

- Maintainers get visual entry points for topology, seams, event flow, lifecycle, app composition, and snapshot behavior.
+- Maintainers get visual entry points for topology, seams, event flow, lifecycle, and app composition.
 - SDK users get a path from use case to package composition instead of only bottom-up package references.
 - `doc-sync` now includes `verify-doc-graphs` and `verify-mermaid`, so graph drift and Mermaid syntax errors are caught with the other doc freshness gates.
 - Future fs and hooks work has a concrete place to land new complexity: fs should expand the capability docs and tool catalog, while hooks should expand the event matrix and tool execution pipeline.
@@ -28,7 +28,7 @@ Status: implemented

 ### 首批发布的索引

-该索引链接十一种关系表面。包拓扑和工具包所提供的功能位于已经拥有这些事实的现有生成式目录中；其余聚焦图表由 `scripts/gen-doc-graphs.ts` 生成。
+该索引链接十种关系表面。包拓扑和工具包所提供的功能位于已经拥有这些事实的现有生成式目录中；其余聚焦图表由 `scripts/gen-doc-graphs.ts` 生成。

 | 关系图 | 维护模式 | 真源 |
 |---|---|---|
@@ -42,7 +42,6 @@ Status: implemented
 | [事件生产者/消费方矩阵](../../../../docs/event-producer-consumer.md) | 混合生成式 | Cordis 事件声明、经 AST 扫描的 `ctx.on/emit/parallel/serial/waterfall` 位置，以及显式动态分派覆盖 |
 | [agent 轮次与步骤生命周期](../../../../docs/agent-lifecycle.md) | 人工维护 | architecture.md 循环生命周期、Cordis 目录链接，以及会话事件语义 |
 | [工具执行管线](../../../../docs/tool-execution-pipeline.md) | 人工维护 | 工具管线语义与 `tools/execute` waterfall（瀑布式事件）|
-| [ACP（Agent Client Protocol）快照回放](../../../../packages/ui/acp/snapshot-replay.md) | 人工策划 | 快照 harness 行为 |

 ### 为什么由生成器拥有文档

@@ -64,7 +63,7 @@ Status: implemented

 ## 后果

- 维护者获得了拓扑、seam、事件流、生命周期、应用组合与快照行为的可视化入口。
+- 维护者获得了拓扑、seam、事件流、生命周期与应用组合的可视化入口。
 - SDK 用户获得了从用例到包组合的路径，而非仅有自底向上的包参考。
 - `doc-sync` 现在包含 `verify-doc-graphs` 和 `verify-mermaid`，因此关系图漂移和 Mermaid 语法错误与其他文档新鲜度门禁一起被捕获。
 - 未来的文件系统和钩子工作有了承载新复杂度的具体位置：文件系统应扩展能力文档和工具目录，钩子应扩展事件矩阵和工具执行流水线。
@@ -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
-2026-07-04-doc-tiers-and-budgets.md: 9993eda6b0c7f1f8e5908dbd85fcfb4e5c6b3d1d
-2026-07-04-doc-tiers-and-budgets.zh.md: a40e7c2fe56ef86137bb7bb3ee8c818bdeed7eb9
+2026-07-04-doc-tiers-and-budgets.md: 7acdba8bfd96d183c418b3935d7b8e7f237d3607
+2026-07-04-doc-tiers-and-budgets.zh.md: 0f07a92740d31dd13cb523d73ac8a3699d666d30
@@ -18,7 +18,7 @@ Standing docs accumulated repeated rules, retold incidents, duplicated package m
 ## Alternatives considered

 - **Skill and review discipline without a gate** — rejected: the accretion above happened while the current-state rule and reviewer attention already existed; a prose rule with no mechanical backstop demonstrably does not hold here, and this repo's own [quality-gates stance](2026-06-11-quality-gates.md) says invariants worth keeping are worth encoding.
- **A broad gate over every doc tier** — rejected: a blanket ceiling punishes exactly the right kind of long doc (a feature matrix or type catalog where every row is a fact, e.g. `packages/ui/acp/acp-feature-support.md`) and generates per-file override churn that trains contributors to rubber-stamp raises.
+- **A broad gate over every doc tier** — rejected: a blanket ceiling punishes exactly the right kind of long doc (a feature matrix or type catalog where every row is a fact) and generates per-file override churn that trains contributors to rubber-stamp raises.
 - **Housing the standard inside the skill** — rejected: contracts live in docs and workflows in skills; a standard packed into SKILL.md is invisible to an agent that edits docs without invoking the skill, and `docs/AGENTS.md` already loads as subtree instructions for anyone working under `docs/`.

 ## Consequences
@@ -18,7 +18,7 @@ Status: implemented
 ## 曾考虑的替代方案

 - **仅靠 skill 和评审纪律，不设门禁**：否决。上述膨胀正是在现行规则和评审注意力已经存在的情况下发生的；一条没有机械后盾的行文规则在此处已被证明无法维持，而本仓库自身的[质量门禁立场](2026-06-11-quality-gates.md)认为值得保持的不变式就值得编码。
- **对所有文档层级全面设限**：否决。一刀切的上限恰好惩罚了那些正当的长文档（如特性矩阵或类型目录，每一行都是事实，例如 `packages/ui/acp/acp-feature-support.md`），并产生逐文件的例外变更，训练贡献者机械地批准提限。
+- **对所有文档层级全面设限**：否决。一刀切的上限恰好惩罚了那些正当的长文档（如特性矩阵或类型目录，每一行都是事实），并产生逐文件的例外变更，训练贡献者机械地批准提限。
 - **将标准放在 skill 内部**：否决。契约归文档，工作流归 skill；如果标准被塞进 SKILL.md，那些不调用该 skill 而直接编辑文档的 agent（智能体）就看不到它，而 `docs/AGENTS.md` 已经作为子树指令被任何在 `docs/` 下工作的人加载。

 ## 后果