diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml index 451843a4c0..e226be3a7d 100644 --- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write 2026-07-12-agent-scope-runtime-design.md: ff7fba1e6f8d496080acbceddb06691c8cddc5f5 -2026-07-12-agent-scope-runtime-design.zh.md: e2aa894b638fb3183750bee96d8a678f25f53de1 +2026-07-12-agent-scope-runtime-design.zh.md: 1225c10b4780c9c0c58ab7d8ff2dafa1379d01be diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md index e2aa894b63..1225c10b47 100644 --- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md @@ -14,19 +14,19 @@ Status: implemented ## 决策 -运行时对每个独立事实使用一种机制。作用域路由有一个不透明载体与共享 layer store；每个活跃的注册表对象有一条入口记录；每个创建或恢复操作有一个事务；类型化的同进程调用借用 readonly 值；真实数据边界只物化一次；协作式 prompt 组装的结果即为权威；worker/进程代码仅在不同所有者确实可能竞争时才保留独立的终止态和静默态。 +运行时对每个独立事实使用一种机制。作用域路由有一个不透明载体与共享 layer store；每个活跃的注册表对象有一条注册表条目；每个创建或恢复操作有一个事务；类型化的同进程调用借用 readonly 值；真实数据边界只物化一次；协作式 prompt 组装的结果即为权威；worker/进程代码仅在不同所有者确实可能竞争时才保留独立的终止态和完全停稳态。 该设计可概括为七项选择： | 问题 | 权威机制 | |---|---| | 选择全局加某个 agent 的注册 | 不透明作用域键、路由载体与共享 layer store | -| 拥有一个活跃的 agent 或会话 | 由其 disposer 捕获的单条注册表入口 | +| 拥有一个活跃的 agent 或会话 | 由其 disposer 捕获的单条注册表条目 | | 协调创建/恢复 | 单个 `AgentCreationTransaction` | | 保护持久化、队列、模型或协议格式数据 | 在该边界处一次性物化 | | 在同一进程内传递类型化值 | Readonly 借用契约 | | 组合模型可见的 prompt 与工具表面 | 单个共享工具视图加权威的 assembly-waterfall 结果 | -| 协调 subagent、worker 和进程关闭 | 单个取消信号加该边界独立的终止态/静默态事实 | +| 协调 subagent、worker 和进程关闭 | 单个取消信号加该边界独立的终止态/完全停稳态事实 | 本 Agent Note 余下部分按依赖顺序展开这些选择：Cordis 机制、作用域路由、创建与会话提交、工具与 prompt、subagent 与工作流，最后是可执行检查。 @@ -60,7 +60,7 @@ Cordis waterfall 是中间件风格的 dispatch。每个监听器接收 `next()` ## 作用域路由：一个不透明键选择一层 -scope 包实现了 Cordis 路由所需的最小对象。其载体仅持有一个组合的服务过滤器和作用域谓词，而包私有地记录不透明键，并单独暴露作用域 fiber 的静默 disposer。 +scope 包实现了 Cordis 路由所需的最小对象。其载体仅持有一个组合的服务过滤器和作用域谓词，而包私有地记录不透明键，并单独暴露会等待作用域 fiber 完全停稳的 disposer。 ### 作用域标识使用对象标识 @@ -86,13 +86,13 @@ Receiver 是一个小型载体而非领域对象的透明代理。需要 agent 创建和恢复是一个具有多个阶段的异步生命周期，而非多个生命周期。`AgentCreationTransaction` 拥有调用方和工厂的活跃性、可选取消、私有资源、发布、回滚，以及每个所有者观察到的记忆化拆除。 -### 注册表入口是唯一的活跃标识记录 +### 注册表条目是唯一的活跃标识记录 -AgentRegistry 和 SessionStore 各为每个活跃对象保留一条入口。入口持有稳定 ID、对象、作用域载体，以及属于该对象的少量发布或追加状态。 +AgentRegistry 和 SessionStore 各为每个活跃对象保留一条注册表条目。注册表条目持有稳定 ID、对象、作用域载体，以及属于该对象的少量发布或追加状态。 -detach 闭包捕获其确切入口。它仅在映射仍指向该入口时才删除，因此旧的 disposer 无法删除一个复用相同 ID 的后续对象。注册表不会重读可变的调用方对象来决定标识。 +detach 闭包捕获其确切注册表条目。它仅在映射仍指向该注册表条目时才删除，因此旧的 disposer 无法删除一个复用相同 ID 的后续对象。注册表不会重读可变的调用方对象来决定标识。 -没有预留 API。调用方提供的 ID 在最终入口时被接纳。并发的同 ID 操作可能都完成私有 setup；恰好一个最终 `enter()` 成功，每个失败者回滚其私有资源。前一个 disposer 达到静默后，顺序复用即为有效。 +没有预留 API。调用方提供的 ID 在最终写入注册表时被接纳。并发的同 ID 操作可能都完成私有 setup；恰好一个最终 `enter()` 成功，每个失败者回滚其私有资源。前一个 disposer 达到完全停稳态后，顺序复用即为有效。 ### 事务在等待之前就拥有准备工作 @@ -112,8 +112,8 @@ Setup 接收完整的子 context，可以等待插件激活。它可以注册工 发布按观察者所需的顺序接纳和宣告资源： -1. 入口 session。 -2. 入口 agent。 +1. 将 session 写入注册表。 +2. 将 agent 写入注册表。 3. 宣告 `session/created`。 4. 宣告 `agent/created`。 5. 启用公开驱动。 @@ -122,7 +122,7 @@ Setup 接收完整的子 context，可以等待插件激活。它可以注册工 Agent 在两个注册表和创建通知都达成一致之前绝不驱动。同步监听器可以否决或 dispose 一个所有者；事务记录发布进行中，并等待该回调栈展开后再继续拆除。每个已开始的创建宣告在回滚期间都有匹配的销毁宣告。 -以下序列图隔离了非显而易见的竞态：同步创建监听器可以在发布调用栈仍拥有两个注册表入口时请求 dispose。拆除必须立即停用，但要等待该栈展开后才停止和分离任何东西。 +以下序列图隔离了非显而易见的竞态：同步创建监听器可以在发布调用栈仍拥有两个注册表条目时请求 dispose。拆除必须立即停用，但要等待该栈展开后才停止和分离任何东西。 ```mermaid sequenceDiagram @@ -160,7 +160,7 @@ sequenceDiagram ## 会话追加：物化、验证、提交、通知 -会话事件跨越持久化边界，因此追加操作拥有其数据。算法的其余部分使用一条附加的入口和一个提交点。 +会话事件跨越持久化边界，因此追加操作拥有其数据。算法的其余部分使用一条已附加的注册表条目和一个提交点。 ### 持久化数据一次性物化 @@ -173,7 +173,7 @@ Session 头部、种子和追加的事件是无损 JSON 数据。Session 构造 追加遵循一个序列： 1. 物化持久化事件和表面意图。 -2. 声明 SessionEntry 并拒绝该入口上的重入追加。 +2. 取得 SessionEntry 的独占所有权，并拒绝该注册表条目上的重入追加。 3. 解析作用域回调并运行内部不变式验证。 4. 恰好推送一次；这是提交点。 5. 逐个通知每个观察者，隔离同步和异步失败。 @@ -268,7 +268,7 @@ Subagent 启动有一次所有权转移。提供方拥有部分资源直到其 s `SubagentProvider.start()` 和 `SubagentService.start()` 返回 `Promise`。Promise 仅在后端建立了它所承诺的子级之后才兑现，因此调用方和 `subagent/start` 观察者从不需要第二个 `run.started` 就绪 promise。 -`SubagentStartRequest.signal` 是必需的。中止它会在启动期间和就绪之后请求取消。`SubagentRun.dispose()` 也请求取消并等待静默。没有单独的公开 `run.cancel()` 通道。 +`SubagentStartRequest.signal` 是必需的。中止它会在启动期间和就绪之后请求取消。`SubagentRun.dispose()` 也请求取消并等待完全停稳。没有单独的公开 `run.cancel()` 通道。 可选的 `sendMessage()` 支持能接受 steering 的活跃后端。可选的 `resume()` 返回 `Promise`，因为恢复的子级有相同的异步就绪边界。 @@ -284,7 +284,7 @@ Spawn 使用空会话种子。Fork 使用经验证的已完成轮次前缀。对 ### ACP 提供方拥有进程直到就绪或清理 -ACP 提供方跨越真实的进程和协议格式边界，因此它保留验证、环境清洗、消息序列化、abort/进程竞争和 kill-to-exit 静默。 +ACP 提供方跨越真实的进程和协议格式边界，因此它保留验证、环境清洗、消息序列化、abort/进程竞争，以及从 kill 到进程退出并完全停稳的过程。 Start 仅在 `initialize` 和 `newSession` 成功后才 resolve。Abort、spawn 失败、RPC 失败或无效启动响应在拒绝前回收进程。就绪后，result 映射 ACP prompt 结果和流式输出；dispose 请求取消、关闭连接并通过一条记忆化路径等待进程退出。 @@ -296,15 +296,15 @@ Worker 和编辑器桥接比同进程注册表需要更多状态，因为消息 工作流宿主保持待定的提供方 start promise 和已发布的子级记录。子级仅在异步 `SubagentService.start()` 兑现时才从待定变为已发布；被拒绝的 start 清理其部分提供方工作且不产生子级生命周期对。 -一个宿主拥有的 AbortController 向待定和活跃子级提供必需的 signal。关闭工作流准入中止该 signal，因此没有重复的 `ChildCancel` worker RPC 或显式的宿主侧 `run.cancel()` 扇出。静默等待待定 start 和已发布子级 dispose 两者。 +一个宿主拥有的 AbortController 向待定和活跃子级提供必需的 signal。关闭工作流准入中止该 signal，因此没有重复的 `ChildCancel` worker RPC 或显式的宿主侧 `run.cancel()` 扇出。完全停稳需要等待待定 start 和已发布子级 dispose 两者。 -Worker 边界仍然序列化请求和结果。宿主保留首个终端结果仲裁、精确的子级计数、worker 死亡处理、优雅终止、迟到/重复消息拒绝和有界清理，因为结果接收、worker 退出和子级静默是真正独立的事实。 +Worker 边界仍然序列化请求和结果。宿主保留首个终端结果仲裁、精确的子级计数、worker 死亡处理、优雅终止、迟到/重复消息拒绝和有界清理，因为结果接收、worker 退出和子级完全停稳是真正独立的事实。 ### 终端结果与物理清理保持分离 工作流结果按公开优先级规则记录首个被接受的终端结果。该结果选定后清理可以继续：活跃子级仍需 dispose，worker 仍需终止，慢速外部后端可能超出配置的优雅期限。 -公开 dispose 在调用回调之前声明其记忆化 promise。Worker 死亡在处理任何排队的迟到子级请求之前关闭准入，合成缺失的生命周期结束，并启动子级/进程清理而不重写已声明的结果。 +公开 dispose 在调用回调之前取得其记忆化 promise 的所有权。Worker 死亡在处理任何排队的迟到子级请求之前关闭准入，合成缺失的生命周期结束，并启动子级/进程清理而不重写已声明的结果。 ### ACP prompt 结算不依赖渲染成功 @@ -332,7 +332,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进 事件目录、服务目录、生产者/消费方矩阵、配置目录、模块图、工具目录、type-equiv 块和作用域事件解析器映射都是从源码生成或受新鲜度门禁约束的。[TypeScript 语义门禁 Agent Note](../process/2026-07-14-typescript-program-backed-semantic-gates.md)拥有 Program 构造、语义事件发现和解析器生成规则。 -行为测试固定了作用域路由和 dispose、最终入口碰撞清理、发布回滚、有序静默、持久化前/后提交行为、跨展示和执行的活跃工具过滤、协作式 prompt 组装、原生和 Code Mode 中的结构化输出提交、异步 subagent 启动和信号取消、worker 终端仲裁、ACP 结算和进程拆除。 +行为测试固定了作用域路由和 dispose、最终写入注册表时的碰撞清理、发布回滚、有序完全停稳、持久化前/后提交行为、跨展示和执行的活跃工具过滤、协作式 prompt 组装、原生和 Code Mode 中的结构化输出提交、异步 subagent 启动和信号取消、worker 终端仲裁、ACP 结算和进程拆除。 ## 曾考虑的替代方案 @@ -344,7 +344,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进 ### 在 setup 前预留 agent 和 session ID -预留防止重复的私有 setup 工作，但需要跨服务能力、释放排序、废弃预留清理和已准备对象绑定。ID 由调用方提供，并发复用是调用方错误；最终入口可以选择赢家，而失败的事务干净地回滚。 +预留防止重复的私有 setup 工作，但需要跨服务能力、释放排序、废弃预留清理和已准备对象绑定。ID 由调用方提供，并发复用是调用方错误；最终写入注册表时可以选择赢家，而失败的事务干净地回滚。 ### 对每个类型化的同进程参数做快照 @@ -352,7 +352,7 @@ TypeScript 无法管控 JavaScript 强制转换、直接 Cordis dispatch、进 ### 为就绪、取消和 dispose 提供独立控制器 -并行哨兵可能都镜像一个操作是否活跃。一个事务或 start promise 拥有操作；独立 promise 仅在发布展开、外部工作、终端结果和物理静默可以独立结算时才保留。 +并行哨兵可能都镜像一个操作是否活跃。一个事务或 start promise 拥有操作；独立 promise 仅在发布展开、外部工作、终端结果和物理层面的完全停稳可以独立结算时才保留。 ### 保留同步 subagent start 加 `run.started` @@ -364,21 +364,21 @@ Waterfall 之后的恢复步骤会在文档化的协作式 seam 之后创建第 ### 用同进程加固替代 worker/进程生命周期守卫 -Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化边界。首个结果仲裁、验证、环境清洗和静默进程清理即使在敌对的同进程回调机制不存在时仍然必要。 +Worker 消息、进程死亡和持久化输入确实跨越所有权和序列化边界。首个结果仲裁、验证、环境清洗和使进程完全停稳的清理即使在敌对的同进程回调机制不存在时仍然必要。 ## 后果 -实现更小，其证明与所有权图具有相同的形状。一个键选择一层，一条入口拥有一个活跃注册表对象，一个事务拥有创建，一个解析器拥有工具视图，一个异步 promise 转移 subagent 所有权。 +实现更小，其证明与所有权图具有相同的形状。一个键选择一层，一条注册表条目拥有一个活跃注册表对象，一个事务拥有创建，一个解析器拥有工具视图，一个异步 promise 转移 subagent 所有权。 ### 设计保证的内容 - 作用域贡献仅在其精确的 agent 视图中可见，并随该作用域一起 dispose。 -- 创建和恢复不暴露部分配置的句柄；最终入口的失败者和发布失败清理每个已准备的资源。 +- 创建和恢复不暴露部分配置的句柄；最终写入注册表时的失败者和发布失败清理每个已准备的资源。 - Dispose 在 driver 排空和最终会话工作期间保留作用域监听器和持久化，然后撤销作用域。 - 持久化、队列、模型、worker、进程和协议格式的值在其真实边界处被拥有；类型化的同进程值遵循 readonly 契约。 - ToolRegistry 的展示、查找和执行在专家 assembly 变换之前解析相同的活跃视图，已提交的结果有一个不可变的观察点。 - 注册表贡献是确定性输入，而可信的 assembly waterfall 拥有最终的模型可见组合。 -- Subagent start 仅返回就绪的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的静默契约。 +- Subagent start 仅返回就绪的 run，必需的 signal 取消待定或活跃的工作，dispose 到达后端的完全停稳契约。 - Worker/进程结果优先级和清理在死亡、迟到消息和有界拆除下保持正确。 ### 代价与局限 diff --git a/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.i18n.yaml index c775a6113b..3024b92250 100644 --- a/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write 2026-06-30-subagent-observe-enrich.md: a07cef95630689d1ca8cacd3eb7c50e691cb304a -2026-06-30-subagent-observe-enrich.zh.md: ce8374b4f046e97c1366256c5c6626013aa8c73f +2026-06-30-subagent-observe-enrich.zh.md: f433c3cbd451e982cfe96457794895120f9bc200 diff --git a/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.zh.md b/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.zh.md index ce8374b4f0..f433c3cbd4 100644 --- a/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.zh.md +++ b/.agents/notes/implemented/feature/2026-06-30-subagent-observe-enrich.zh.md @@ -18,7 +18,7 @@ Status: implemented ## 曾考虑的替代方案 -**`agentType` subagent 类别标签**（CC 的 `subagent_type` 在 harness 中的对应物），放在请求与两个生命周期载荷上。早期草案曾包含它；评审中移除，因为它是 Claude Code 的概念，不适合我们自己的 seam（此处没有任何逻辑解释它，唯一消费方是 CC 方言桥接层）。CC 桥接层改为直接为其 SubagentStart/Stop 的 `agent_type` matcher 填入 Claude Code 自身的默认值 `"general-purpose"`，因此本 Agent Note 只交付一项丰富化：`lastAssistantMessage`。 +**`agentType` subagent 类别标签**（CC 的 `subagent_type` 在 harness 中的对应物），放在请求与两个生命周期载荷上。早期草案曾包含它；评审中移除，因为它是 Claude Code 的概念，不适合我们自己的 seam（此处没有任何逻辑解释它，唯一消费方是 CC 方言桥接层）。CC 桥接层改为直接为其 SubagentStart/Stop 的 `agent_type` matcher 填入 Claude Code 自身的默认值 `"general-purpose"`，因此本 Agent Note 只交付**一项**丰富化：`lastAssistantMessage`。 **控制流式 `subagent/end`**：推迟；见下文。