docs(runtime): internal/runtime/loop 44 个文件注释改中文(逐行 1:1,代码零字节改动)

主人 2026-10-03 拍板「注释一律中文」;本模块按长期分批协议(一个模块一次派工)执行。
注释行数 1329 → 1329 逐行 1:1(含中文 33 → 1304);行尾注释 5 条一并译。
校验:机械校验(非注释改动行)= 空;独立 Go AST 程序(剥注释复渲)证明 44/44 文件代码全等;
全树 go test ./... 58 包 ok / 0 FAIL;交叉编译绿。
gofmt:capacity_loop_test.go / flow.go 改动前即未格式化,按铁律保留原样未动。
This commit is contained in:
AskaEth committed 2026-10-03 22:28:21 +08:00
1 parent 355f81d04a
commit 91e8d7a029
44 files changed
+1315 -1315

No files matched your search

+26 -26
View File
@@ -2,22 +2,22 @@ package loop
import "context"
// flowBranchKey is the context key marking a Run as a branch of another
// session's flow graph. It is set by the orchestration layer (through
// WithFlowBranch) before it drives a sub-agent's Run.
// flowBranchKey 是标记某个 Run 为另一会话 flow 图分支的 context key。
// 它由 orchestration 层(经 WithFlowBranch)在驱动
// 子代理 Run 之前设置。
type flowBranchKey struct{}
// WithFlowBranch returns ctx marking the current Run as a branch: its spans fold
// into parentSession's live flow graph and the Run neither starts nor ends a
// round of its own — the owning session's round does. It is how the orchestration
// layer attributes a sub-agent's work to the session that spawned it, so parallel
// sub-agents render as swimlanes of one graph instead of replacing the frontend's
// single flowGraph with a graph of their own (design/19 §2).
// WithFlowBranch 返回 ctx,把当前 Run 标记为分支:它的 span 并入
// parentSession 的实时 flow 图,且该 Run 自身既不开始也不结束
// 轮次 —— 由所属会话的轮次负责。orchestration 层正是靠它把
// 子代理的工作归属到派生它的会话,使并行的
// 子代理渲染为同一张图的泳道,而不是用各自的图
// 替换前端唯一的 flowGraph(design/19 §2)。
//
// An empty parentSession still marks the Run as a branch: it owns no round and
// publishes nothing. That is the state of a background sub-agent nobody attributed
// to a session, and it must not silently become a graph of its own. A nil ctx is
// returned unchanged.
// 空的 parentSession 仍把该 Run 标记为分支:它不拥有轮次、
// 不发布任何东西。这正是无人归属到会话的后台子代理的
// 状态,它不得悄悄变成属于自己的一张图。nil ctx
// 原样返回。
func WithFlowBranch(ctx context.Context, parentSession string) context.Context {
if ctx == nil {
return ctx
@@ -25,9 +25,9 @@ func WithFlowBranch(ctx context.Context, parentSession string) context.Context {
return context.WithValue(ctx, flowBranchKey{}, parentSession)
}
// flowBranch reports the parent session recorded by WithFlowBranch and whether the
// Run is a branch at all. A non-branch Run owns its own round and publishes under
// its own session id.
// flowBranch 报告 WithFlowBranch 记录的父会话以及
// 该 Run 是否本就是分支。非分支的 Run 拥有自己的轮次并在
// 自己的 session id 下发布。
func flowBranch(ctx context.Context) (string, bool) {
if ctx == nil {
return "", false
@@ -40,9 +40,9 @@ func flowBranch(ctx context.Context) (string, bool) {
return s, true
}
// flowOwner returns the session whose flow graph should receive this Run's spans:
// the branch parent when the Run is a sub-agent branch (empty when the branch is
// unattributed, which suppresses publication), otherwise the Run's own sessionID.
// flowOwner 返回应当接收该 Run span 的 flow 图所属会话:
// 当该 Run 是子代理分支时取分支父级(分支未归属时为空,
// 此时抑制发布),否则取该 Run 自身的 sessionID。
func flowOwner(ctx context.Context, sessionID string) string {
if parent, isBranch := flowBranch(ctx); isBranch {
return parent
@@ -50,14 +50,14 @@ func flowOwner(ctx context.Context, sessionID string) string {
return sessionID
}
// FlowOwnerFromContext returns the session whose flow graph owns work started
// from ctx: the branch parent when ctx runs inside a sub-agent branch, otherwise
// the session id the enclosing Run was driven with (empty when neither is set).
// FlowOwnerFromContext 返回拥有从 ctx 启动的工作的 flow 图所属会话:
// 当 ctx 运行于子代理分支内时取分支父级,否则
// 取外层 Run 被驱动的 session id(两者都未设置时为空)。
//
// A tool that dispatches background work — the sub-agent spawn tool — passes this
// as the parent session, so a sub-agent spawned from inside another sub-agent
// stays attributed to the same top-level graph instead of to an id that owns no
// graph.
// 派发后台工作的工具 —— 子代理派生工具 —— 把它
// 作为父会话传入,使在另一个子代理内部派生的子代理
// 保持在同一个顶层图的归属之下,而不是归属到一个不拥有
// 任何图的 id。
func FlowOwnerFromContext(ctx context.Context) string {
if parent, isBranch := flowBranch(ctx); isBranch {
return parent