docs(comments): 注释中文化 · internal/runtime/orchestration(29 文件,纯替换)
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
CI / Frontend (tsc + vite build) (push) Has been cancelled

- 只翻注释/文档字符串:剥离注释后代码行逐字节不变(机械校验只剩允许的行尾注释形态)
- 裁决编号与 design 节号(02.4.3 / 11.4.2 / design/05 §9 等)逐字保留
- 复核:go build 绿;orchestration 及其子包(audit/comm)测试绿;gofmt 干净
This commit is contained in:
AskaEth committed 2026-10-04 13:30:04 +08:00
1 parent fe90f64a56
commit eb1828ee7a
29 files changed
+751 -949

No files matched your search

+25 -33
View File
@@ -1,43 +1,35 @@
// Package orchestration implements the sub-agent orchestration layer of the
// Cyrene v2 runtime (DevDocs/design/04-运行时.md §2 and DevDocs/design/05-子代理.md).
// Package orchestration 实现 Cyrene v2 运行时的子代理编排层
// (DevDocs/design/04-运行时.md §2 与 DevDocs/design/05-子代理.md)。
//
// When the front session (agent loop) decides a task is complex it hot-switches to
// orchestration mode and spawns background sub-agents that run concurrently
// without blocking the front session. Each sub-agent is an agent instance bound
// to a role + behavior mode, executing in an isolated context with its own
// working memory. Progress and status are streamed back to the front session via
// the agent-to-agent bus, and once all sub-agents finish their outcomes are
// merged for the front session.
// 当前台会话(agent 循环)判定任务复杂时,它会热切换到编排模式,并派发后台
// 子代理并发运行,不阻塞前台会话。每个子代理都是绑定「角色 + 行为模式」的 agent
// 实例,在隔离上下文中执行,并持有自己的工作记忆。进度与状态经 agent 间总线回流
// 前台会话;全部子代理结束后,它们的结果被合并交给前台会话。
//
// # Lifecycle
// # 生命周期
//
// A Scheduler is created once via New with its injected dependencies (a loop
// template, the bus, an optional comm probe, memory/sink, tracer, approver). A
// sub-agent is created with Spawn, which registers it, publishes a "dispatched"
// progress event and launches its execution in the background. The execution is
// gated by MaxParallel so at most that many sub-agents run at once; excess ones
// queue. Each run is bounded by PerAgentTimeout. The sub-agent moves
// pending -> running -> one of {done, failed, aborted}, and on every terminal
// transition a summary is written and a progress event is published. Abort and
// CancelAll stop a single sub-agent or every sub-agent (anti-runaway).
// Scheduler 由 New 创建一次,并注入其依赖(一个循环模板、总线、可选的 comm 探针、
// 记忆/sink、tracer、代审者)。子代理由 Spawn 创建:它登记子代理、发布一条
// 「已派发」进度事件,并在后台启动其执行。执行受 MaxParallel 约束,同时至多这么
// 多个子代理在跑,超出的排队等待。每次运行受 PerAgentTimeout 约束。子代理状态从
// pending -> running -> {done, failed, aborted} 之一流转,每次终结态转移都会写入
// 一份摘要并发布一条进度事件。Abort 与 CancelAll 分别停掉单个子代理或全部子代理
// (防失控)。
//
// # Result merging
// # 结果合并
//
// Join waits until every spawned sub-agent reaches a terminal state (or ctx is
// canceled) and returns a MergedResult aggregating each sub-agent's summary and
// loop result.
// Join 等待每个已派发的子代理进入终结态(或 ctx 被取消),返回一个 MergedResult,
// 汇总每个子代理的摘要与循环结果。
//
// # Isolation
// # 隔离
//
// Sub-agent context and working memory are isolated by construction: Spawn deep
// copies Spec.Context into SubAgent.Context and creates a fresh WorkingMemory per
// sub-agent, so a sub-agent never shares the front session's context.
// 子代理的上下文与工作记忆在构造上即隔离:Spawn 把 Spec.Context 深拷贝进
// SubAgent.Context,并为每个子代理创建全新的 WorkingMemory,因此子代理从不共享
// 前台会话的上下文。
//
// # Governance
// # 治理
//
// Sensitive operations are audited through the injected *audit.Approver (see
// Approve): policy judgement belongs to the upper layer; the scheduler only
// triggers the audit record. Task-memory sinking is available through SinkMemory,
// which delegates to the injected *memory.Store so scope classification
// (user/persona/project) stays at the call site.
// 敏感操作经注入的 *audit.Approver 审计(见 Approve):策略判断属于上层,调度器
// 只触发审计记录。任务记忆落库经 SinkMemory 提供,它委托给注入的 *memory.Store,
// 因此作用域归类(user/persona/project)留在调用点。
package orchestration