Merge origin/master into xjt/proofreading-active-docs-2-apply

2026-08-05 10:57:53 +08:00
parent 8320c3666d a1221f315f
commit 7bd111b2af
371 changed files with 7567 additions and 1104 deletions
@@ -1,4 +1,4 @@
-# Agent Note: 同会话目标回合驱动器
+# Agent Note: 同会话 Goal Round 驱动器

 Status: implemented

@@ -14,7 +14,7 @@ Status: implemented

 位于 `packages/goal/goal-session/` 的 `@deepseek-ai/dsh-goal-session` 是构建在 `ctx.goals`、公共 `Agent` 接口和持久会话事件之上的策略插件。它不导入具体 agent-loop 实现。对于每个对应的同一个实时 `Agent` 对象，它维护进程内调度状态，并且最多保留一个自动回合预留。

-层次关系为目标（Goal）→ 目标回合（Goal Round）→ 轮次（Turn）→ 步骤（Step）。目标回合是外层继续执行策略的一次迭代；它会成为一个归属于目标的会话轮次，而该轮次可以包含任意数量的普通模型或工具步骤。同一会话中的人类轮次不是目标回合，也绝不会增加 `roundsStarted`。
+层次关系为目标（Goal）→ Goal Round → 轮次（Turn）→ 步骤（Step）。Goal Round 是外层继续执行策略的一次迭代；它会成为一个归属于目标的会话轮次，而该轮次可以包含任意数量的普通模型或工具步骤。同一会话中的人类轮次不是 Goal Round，也绝不会增加 `roundsStarted`。

 该插件没有配置项。`maxGoalRounds` 由 `dsh-goal` 解析并持久化；“相同阻塞条件”的门槛由 `dsh-tool-goal` 解析并写入提示词。若驱动器重复声明这些可调值，一个策略就会出现多个所有者。

@@ -24,11 +24,11 @@ Status: implemented

 `agent/prompt-submit` waterfall（瀑布式事件）是接纳栅栏。正数目标来源只有在完全匹配驱动器待处理的身份和内容、实时目标仍具有相同 id 与修订号、激活态仍为 armed，并且该回合仍是下一个编号时才会获准。插件在委托下游监听器前检查一次，在下游返回后再检查一次。第二次检查防止异步钩子编辑或暂停目标后，旧提示词仍被接纳。

-只有最终产生的 `user/message` 才是已接纳目标回合，并推进目标折叠。陈旧预留会在轮次打开前被丢弃；驱动器会把它标记为陈旧，不消耗回合数。若下游策略拒绝并非由陈旧状态导致，目标会进入 blocked，而不会绕过该策略自动重试。
+只有最终产生的 `user/message` 才是已接纳 Goal Round，并推进目标折叠。陈旧预留会在轮次打开前被丢弃；驱动器会把它标记为陈旧，不消耗 Round 数。若下游策略拒绝并非由陈旧状态导致，目标会进入 blocked，而不会绕过该策略自动重试。

 ### 人类工作与修订竞争

-`agent/queued` 会区分驱动器自己的完整已接受记录与其他所有提示词。预留之前已经排队的普通工作会阻止调度；自动提示词待处理时进入的普通工作会使该预留过期，因此混合批次只接纳人类提示词而拒绝自动提示词。目标回合已经接纳后到达的普通工作会保留在队列中，成为下一个独立轮次；只有 agent 再次空闲后才重新考虑继续执行。
+`agent/queued` 会区分驱动器自己的完整已接受记录与其他所有提示词。预留之前已经排队的普通工作会阻止调度；自动提示词待处理时进入的普通工作会使该预留过期，因此混合批次只接纳人类提示词而拒绝自动提示词。Goal Round 已经接纳后到达的普通工作会保留在队列中，成为下一个独立轮次；只有 agent 再次空闲后才重新考虑继续执行。

 目标在回合内发生变更时会推进持久修订号。旧修订的结算不得覆盖该变更。驱动器会丢弃旧尝试的结果、读取新投影，并且只在新修订仍为 active 与 armed 时继续。因此，模型记录的完成、暂停、阻塞和编辑相对于物理轮次稍后的关闭原因具有最终权威。

@@ -39,7 +39,7 @@ Status: implemented
 | 轮次结果 | 动作 |
 |---|---|
 | 持久化的 `completed` | 目标仍 active/armed 且未到上限时继续 |
-| 取消已预留/接纳的目标回合，或该回合产生 `aborted` 结果 | 暂停并解除激活 |
+| 取消已预留/接纳的 Goal Round，或该 Round 产生 `aborted` 结果 | 暂停并解除激活 |
 | 代码为 `RATE_LIMIT` 或 `QUOTA` 的 `error` | 以 `usage-limited` 代码阻塞 |
 | 其他 `error` | 以 `turn-error` 代码阻塞 |
 | `max-tokens` | 以 `max-tokens` 代码阻塞 |
@@ -76,7 +76,7 @@ Status: implemented
 ## 考虑过的替代方案

 - **在 `dsh-agent-loop` 内添加目标循环**——不予采纳，因为公共队列、提示词、会话、取消和状态 seam 已经足够，具体循环分支还会赋予某种策略特权。
- **使用 `agent/turn-continuation` 把每个回合变成另一个步骤**——不予采纳，因为目标回合是外层策略迭代，必须拥有自己的持久用户提示词、轮次边界、回合计数和失败结算。
+- **使用 `agent/turn-continuation` 把每个 Round 变成另一个步骤**——不予采纳，因为 Goal Round 是外层策略迭代，必须拥有自己的持久用户提示词、轮次边界、Round 计数和失败结算。
 - **持久化待处理预留**——不予采纳，因为崩溃无法证明进程内队列已经达到接纳点；只有持久 `user/message` 才消耗回合。
 - **自动重试提供方或持久化错误**——不予采纳，因为重试会消耗资源，需要显式授权；停止阶段加之后的人类恢复更简单，也可观察。
 - **每回合 fork 对话历史或生成新 agent**——本包不采用，因为此目标明确属于同会话工作。新 agent 的 Ralph 执行仍是基于 subagent 与 workflow 原语的独立工作流插件。