Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: sync bilingual pairs and static gates with the message-machine refactor

Browse Source 
The branch edited the English side of 17 doc pairs without their Chinese
counterparts. Bring every .zh.md up to date (loop.ts references now point
at agent.ts, send/steer/inject unification, context/message folded into
user/message, HookContext replaced by UserMessageData in tool decision
blocks, plan/skill delivery moved to agent/step) and re-record the pairing
hashes. Deduplicate type-equiv.manifest.json entries duplicated by the
master merge and drop entries for symbols the refactor removed. Complete
the missing JSDoc on extractSnapshotSpillPaths.
This commit is contained in:
_Kerman
2026-07-26 11:48:06 +08:00
parent 3df3a0dc00
commit 8432c68b6a
35 changed files with 215 additions and 532 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.i18n.yaml
View File

@@ -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-06-20-drop-unconsumed-llm-assembled-surfaces.md: b6b596e822b4bd6fd1bd891c336c622ad675ad45
2026-06-20-drop-unconsumed-llm-assembled-surfaces.zh.md: bafc5d3bc630d89c776bbcf53719b29223e1c90d
2026-06-20-drop-unconsumed-llm-assembled-surfaces.md: 40fa71a7bcf00d8933165ee8d4594112fdb8c0a8
2026-06-20-drop-unconsumed-llm-assembled-surfaces.zh.md: 00b3b907eed9cbbb37eac028f32ca5cf3f796ac5

2
.agents/notes/implemented/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.zh.md
View File

@@ -12,7 +12,7 @@ Status: implemented
- `streamBlocks()`：一个「便捷视图」，将分片送入 `BlockAssembler` 并按流顺序产出已组装的 `ContentBlock`（[index.ts:137-144](../../../../packages/llm/llm/src/index.ts)）。
- `generate()`：一个完整组装的 `GenerateResult`，通过第二条 `llm/generate` waterfall 分发（[index.ts:151-157](../../../../packages/llm/llm/src/index.ts)）。
LLM（大语言模型）服务唯一的生产消费方是 agent loop（智能体循环），它只使用 `stream()`：将原始分片送入自己的 `BlockAssembler`，以便在并行组装的同时记录分片，保证回放保真度（[packages/core/agent-loop/src/loop.ts](../../../../packages/core/agent-loop/src/loop.ts)，`ctx.llm.stream(req)` 步骤）。在 `packages/*/src` 和 `examples/*/src` 中 grep `streamBlocks` 与 `ctx.llm.generate`，找不到任何生产调用方。仅有的引用来自服务方法定义、文档和测试；适配器测试用 `generate()` 作为便捷驱动，但它们完全可以通过同一个 assembler 辅助函数手动消费 `stream()`，无需为此保留一个公开的生产 API。
LLM（大语言模型）服务唯一的生产消费方是 agent loop（智能体循环），它只使用 `stream()`：将原始分片送入自己的 `BlockAssembler`，以便在并行组装的同时记录分片，保证回放保真度（[packages/core/agent-loop/src/agent.ts](../../../../packages/core/agent-loop/src/agent.ts)，`ctx.llm.stream(req)` 步骤）。在 `packages/*/src` 和 `examples/*/src` 中 grep `streamBlocks` 与 `ctx.llm.generate`，找不到任何生产调用方。仅有的引用来自服务方法定义、文档和测试；适配器测试用 `generate()` 作为便捷驱动，但它们完全可以通过同一个 assembler 辅助函数手动消费 `stream()`，无需为此保留一个公开的生产 API。
这属于[删除可变会话 summary](2026-06-19-drop-mutable-session-summary.md) 的同类模式：带有受测契约的组装视图 API，由测试而非生产代码消费。它们是为不关心 token 级增量的消费方推测性构建的，但唯一的真实消费方恰恰关心增量，以便持久化高保真重放数据。

4
.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.i18n.yaml
View File

@@ -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-02-remove-stream-chunk-mirror.md: 5dd816940a4b2c2b63980e01f1bd4e0aac53a3e2
2026-07-02-remove-stream-chunk-mirror.zh.md: ca65a3c2ad46d14835416c14d0087ef542de03bb
2026-07-02-remove-stream-chunk-mirror.md: 62421bfd6032d3be6e942c00abefe17ec947c986
2026-07-02-remove-stream-chunk-mirror.zh.md: 6e006a2c1930e47a651813252d3fd2c4471e6e9e

2
.agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.zh.md
View File

@@ -6,7 +6,7 @@ Status: implemented
## 问题
agent loop（智能体循环）将模型的每个 token delta 同时记录为持久的 `assistant/chunk` 会话事件，并发射一个携带相同数据的并行实时 `agent/stream-chunk` Cordis 事件。在 `packages/core/agent-loop/src/loop.ts` 中，二者仅相隔一行：
agent loop（智能体循环）将模型的每个 token delta 同时记录为持久的 `assistant/chunk` 会话事件，并发射一个携带相同数据的并行实时 `agent/stream-chunk` Cordis 事件。在 `packages/core/agent-loop/src/agent.ts` 中，二者仅相隔一行：
```ts ignore-check
const chunkEvent = session.append('assistant/chunk', { turn, step, chunk })

4
.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.i18n.yaml
View File

@@ -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-prune-producerless-vocabulary-variants.md: 34492e6906cd2d795f880310b1bcd120e3953fcf
2026-07-04-prune-producerless-vocabulary-variants.zh.md: a68a8b04fedefed8a2ab92f08baf5e8b3ea90222
2026-07-04-prune-producerless-vocabulary-variants.md: aa8c0500e79b91443e8b224c586a07644068799b
2026-07-04-prune-producerless-vocabulary-variants.zh.md: 0ef2b68d7f6812c5f9ae380e6086a442d336c6cb

2
.agents/notes/implemented/simplification/2026-07-04-prune-producerless-vocabulary-variants.zh.md
View File

@@ -30,4 +30,4 @@ Status: implemented
## 后果
操作行为没有变化——原本就没有内容能够构造这些值。镜像事件移除（[边界镜像 Agent Note](2026-06-20-remove-agent-boundary-mirror-events.md)、[流分片 Agent Note](2026-07-02-remove-stream-chunk-mirror.md)）只触及瞬态 `agent/*` 事件，从不触及持久词汇，因此不存在冲突。其他位置已经遵守准入策略：`rejected`、`prompt/blocked` 和 `hook/invoked`/`hook/result` 都有实时生产者——本 Agent Note 将同一门槛扩展到缺少生产者的三个变体。图像块自身的 `cache?` 字段归属[删除图像 Agent Note](2026-07-04-drop-image-content-block.md)，后者将其与该块一同移除；本 Agent Note 覆盖剩余块类型上的两个字段。
操作行为没有变化——原本就没有内容能够构造这些值。镜像事件移除（[边界镜像 Agent Note](2026-06-20-remove-agent-boundary-mirror-events.md)、[流分片 Agent Note](2026-07-02-remove-stream-chunk-mirror.md)）只触及瞬态 `agent/*` 事件，从不触及持久词汇，因此不存在冲突。后来的轮次前准入清理将 `rejected` 和 `prompt/blocked` 连同其生产者一并移除；轮中的 `hook/invoked`/`hook/result` 仍然体现同一条以生产者为准的准入规则。图像块自身的 `cache?` 字段归属[删除图像 Agent Note](2026-07-04-drop-image-content-block.md)，后者将其与该块一同移除；本 Agent Note 覆盖剩余块类型上的两个字段。

4
.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.i18n.yaml
View File

@@ -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-remove-agent-steering-mirror.md: 9f7cd5abe968ff216cbd7012163ea1c04dc00599
2026-07-04-remove-agent-steering-mirror.zh.md: 63f575347d989f288b3129e0a53e5690b85bb4e8
2026-07-04-remove-agent-steering-mirror.md: 6d78217a4939c4a87325cd120638042acbd68dc1
2026-07-04-remove-agent-steering-mirror.zh.md: 6aabb71903eaeb7204df2d5880a52acabc6d612a

4
.agents/notes/implemented/simplification/2026-07-04-remove-agent-steering-mirror.zh.md
View File

@@ -6,7 +6,7 @@ Status: implemented
## 问题
`agent/steering` 是最后一个仍存在的、对持久会话事件的瞬态镜像。agent loop（智能体循环）的 steering（中途引导）drain 逻辑先追加持久事件 `steering/message { turn, content, source }`，紧接着下一行就 emit `agent/steering(agent, turn, content, source)`——同一个事实以 fire-and-forget 事件的形式重复发出（`packages/core/agent-loop/src/loop.ts`，`drainSteering`）。它在生产环境中没有任何监听者：唯一的订阅方是一个 agent loop 回归测试，断言 emit 携带了 `source`——而这同一个事实已经由上一行的持久事件记录。
`agent/steering` 是最后一个仍存在的、对持久会话事件的瞬态镜像。agent loop（智能体循环）的 steering（中途引导）drain 逻辑先追加持久事件 `steering/message { turn, content, source }`，紧接着下一行就 emit `agent/steering(agent, turn, content, source)`——同一个事实以 fire-and-forget 事件的形式重复发出（`packages/core/agent-loop/src/agent.ts`，`drainOutbox`）。它在生产环境中没有任何监听者：唯一的订阅方是一个 agent loop 回归测试，断言 emit 携带了 `source`——而这同一个事实已经由上一行的持久事件记录。
`agent/steering` 以相同的 payload 重复了紧接其前的持久事件 `steering/message`。`agent/queued` 仍保留为纯瞬态信号，因为它在持久化之前触发，覆盖了可能在进入日志前被取消的工作。
@@ -14,7 +14,7 @@ Steering 承载真实生产流量——钩子 bridge 的轮次延续决策通过
## 决策
`agent/steering` 已从 agent 事件分类中移除：包括 `packages/core/agent/src/types.ts` 中的声明（以及其中实时事件 JSDoc 列表对它的提及）、`drainSteering` 中的 emit（当时已无用的 `ctx` 参数也随之移除）、`packages/core/agent/README.md` 中的表格行，以及循环伪代码块（`packages/core/agent-loop/src/loop.ts` 模块文档和 [architecture.md](../../../../docs/architecture.md)）中的 emit 行；Cordis 目录重新生成后不再包含它。唯一的回归测试改为在持久 `steering/message` 事件上固定来源保留行为——所固定的事实存在于日志上。
`agent/steering` 已从 agent 事件分类中移除：包括 `packages/core/agent/src/types.ts` 中的声明（以及其中实时事件 JSDoc 列表对它的提及）、`drainOutbox` 中的 emit、`packages/core/agent/README.md` 中的表格行，以及循环伪代码块（`packages/core/agent-loop/src/agent.ts` 模块文档和 [architecture.md](../../../../docs/architecture.md)）中的 emit 行；Cordis 目录重新生成后不再包含它。唯一的回归测试改为在持久 `steering/message` 事件上固定来源保留行为——所固定的事实存在于日志上。
三份已实现 Agent Note（agent 决策记录）曾说明保留该事件；按照 [implemented/AGENTS.md](../AGENTS.md)，每份记录都已修改并指向本文作为移除记录：包括[边界 Agent Note](2026-06-20-remove-agent-boundary-mirror-events.md) 的保留列表条目、[流分片 Agent Note](2026-07-02-remove-stream-chunk-mirror.md) 的范围条款，以及[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md) 的瞬态 emit 枚举。