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
1 parent
355f81d04a
commit
91e8d7a029
44 files changed
+1315
-1315
No files matched your search
@@ -1,14 +1,14 @@
|
||||
// Package loop implements the default agent execution engine of the Cyrene v2
|
||||
// runtime (DevDocs/design/04-运行时.md §1). It owns the loop that package agent
|
||||
// deliberately leaves out: assemble context from memory, drive the model for up
|
||||
// to MaxRounds steps, execute any requested tool calls under a per-invoke
|
||||
// timeout, feed tool results back to the model, persist a checkpoint at every
|
||||
// step, emit structured traces, deliver streamed deltas and run the
|
||||
// memory-extraction hook.
|
||||
// Package loop 实现 Cyrene v2 运行时默认的 agent 执行引擎
|
||||
// （DevDocs/design/04-运行时.md §1）。它拥有 package agent 刻意
|
||||
// 不做的那个循环：从记忆组装上下文、驱动模型至多
|
||||
// MaxRounds 个 step、在每次调用的超时下执行所有被请求的工具调用、
|
||||
// 把工具结果回灌给模型、每步持久化一个 checkpoint、
|
||||
// 发出结构化 trace、下发流式增量并运行
|
||||
// 记忆提取钩子。
|
||||
//
|
||||
// The loop is configured with injected dependencies rather than concrete wiring,
|
||||
// so it stays leaf-testable with mocks (a mock adapter, mock guardrail and mock
|
||||
// tool, plus real in-memory memory/persist stores and a buffered trace recorder).
|
||||
// 循环以注入依赖而非具体接线来配置，
|
||||
// 因此它保持可用 mock 做叶子测试（mock 适配器、mock 护栏与 mock
|
||||
// 工具，加上真实的内存 memory/persist store 与带缓冲的 trace 记录器）。
|
||||
package loop
|
||||
|
||||
import (
|
||||
@@ -28,62 +28,62 @@ import (
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/trace"
|
||||
)
|
||||
|
||||
// Constants that bound the loop. These are compile-time so no magic number
|
||||
// appears in the run path.
|
||||
// 界定循环的常量。它们是编译期常量，使运行路径中
|
||||
// 不出现魔法数字。
|
||||
const (
|
||||
// DefaultMaxRounds is the tool-loop upper bound used when Options.MaxRounds
|
||||
// is non-positive. It matches the agent package's own default.
|
||||
// DefaultMaxRounds 是 Options.MaxRounds 非正时使用的
|
||||
// 工具循环上限。它与 agent 包自身的默认值一致。
|
||||
DefaultMaxRounds = 8
|
||||
|
||||
// StopReasonMaxRounds reports that the loop exhausted its round budget
|
||||
// before reaching a final answer.
|
||||
// StopReasonMaxRounds 报告循环在达到最终答案前
|
||||
// 用尽了轮次预算。
|
||||
StopReasonMaxRounds = "max_rounds"
|
||||
|
||||
// StopReasonToolLoopTerminated reports that the critical-tool-loop safety net
|
||||
// stopped the run after the same tool call was repeated identically across
|
||||
// consecutive rounds.
|
||||
// StopReasonToolLoopTerminated 报告关键工具循环安全网在
|
||||
// 同一个工具调用跨连续轮次被完全重复后
|
||||
// 停止了 run。
|
||||
StopReasonToolLoopTerminated = "tool_loop_terminated"
|
||||
|
||||
// DefaultToolParallelism caps how many tool calls run concurrently when the
|
||||
// loop runs a batch in parallel mode and no explicit cap is configured.
|
||||
// DefaultToolParallelism 限制循环以并行模式运行一批时
|
||||
// 并发执行的工具调用数，未配置显式上限时生效。
|
||||
DefaultToolParallelism = 4
|
||||
)
|
||||
|
||||
// Sentinel errors returned by the Loop. Use errors.Is to test for them; they are
|
||||
// returned directly or wrapped with %w so the underlying cause stays available.
|
||||
// Loop 返回的哨兵错误。用 errors.Is 检测它们；它们
|
||||
// 被直接返回或以 %w 包装，使底层原因始终可用。
|
||||
var (
|
||||
// ErrNilAgent is returned by Run when neither a default agent (Options.Agent)
|
||||
// nor a per-role agent pool (Options.Agents) was configured.
|
||||
// ErrNilAgent 在既未配置默认 agent（Options.Agent）
|
||||
// 也未配置按角色 agent 池（Options.Agents）时由 Run 返回。
|
||||
ErrNilAgent = errors.New("loop: nil agent")
|
||||
|
||||
// ErrNoAdapter is returned by Run (streaming path) when the agent was built
|
||||
// without a model Adapter.
|
||||
// ErrNoAdapter 在 agent 构建时未带 model Adapter 时
|
||||
// 由 Run（流式路径）返回。
|
||||
ErrNoAdapter = errors.New("loop: no model adapter")
|
||||
)
|
||||
|
||||
// Result is the outcome of a completed Run.
|
||||
// Result 是一次已完成 Run 的结果。
|
||||
type Result struct {
|
||||
// Text is the final assistant text, or empty when the loop exhausted its
|
||||
// budget without a final answer.
|
||||
// Text 是最终的 assistant 文本；循环在无最终答案的情况下
|
||||
// 耗尽预算时为空。
|
||||
Text string
|
||||
// Steps is the number of model steps executed.
|
||||
// Steps 是执行的模型步数。
|
||||
Steps int
|
||||
// StopReason classifies how the loop ended: an agent StopReason* value or
|
||||
// StopReasonMaxRounds.
|
||||
// StopReason 归类循环如何结束：一个 agent StopReason* 值或
|
||||
// StopReasonMaxRounds。
|
||||
StopReason string
|
||||
// ToolCallsExecuted is the number of tool calls the loop invoked, including
|
||||
// those that failed.
|
||||
// ToolCallsExecuted 是循环调用的工具调用数，含
|
||||
// 失败的那些。
|
||||
ToolCallsExecuted int
|
||||
// Mood is the persona's mood label for this turn, as returned by the
|
||||
// OnTurnEnd hook ("" when no hook is wired). The persistence layer carries it
|
||||
// onto the assistant message (design/16 §3.3).
|
||||
// Mood 是该 turn 的人格情绪标签，由
|
||||
// OnTurnEnd 钩子返回（未接线钩子时为 ""）。持久化层把它
|
||||
// 带到 assistant 消息上（design/16 §3.3）。
|
||||
Mood string
|
||||
}
|
||||
|
||||
// Loop is the default agent execution engine. It is configured once via New and
|
||||
// safe for concurrent Run calls as long as the injected dependencies (agent,
|
||||
// dispatcher, stores, recorder, tracer) are themselves concurrency-safe, which
|
||||
// they are by contract. Run keeps all loop state on the stack.
|
||||
// Loop 是默认的 agent 执行引擎。它经 New 一次性配置，
|
||||
// 只要注入的依赖（agent、dispatcher、store、recorder、tracer）自身
|
||||
// 并发安全（按契约它们是），就安全支持并发 Run 调用。
|
||||
// Run 把所有循环状态保留在栈上。
|
||||
type Loop struct {
|
||||
agent *agent.Agent
|
||||
agents map[string]*agent.Agent
|
||||
@@ -120,11 +120,11 @@ type Loop struct {
|
||||
log *slog.Logger
|
||||
}
|
||||
|
||||
// New builds a Loop from opts, applying defaults. A non-positive MaxRounds
|
||||
// selects DefaultMaxRounds; a nil Log is replaced by a discard logger tagged with
|
||||
// source "runtime/loop". Every dependency may be nil and is tolerated until the
|
||||
// step that needs it (mirroring the run-time nil-tolerance of the underlying
|
||||
// packages); Run returns ErrNilAgent when no agent is configured.
|
||||
// New 由 opts 构建 Loop 并应用默认值。MaxRounds 非正时
|
||||
// 选用 DefaultMaxRounds；Log 为 nil 时替换为标记来源
|
||||
// "runtime/loop" 的丢弃 logger。每个依赖都可以为 nil，并容忍到
|
||||
// 需要它的那一步（与底层包的运行时 nil 容忍一致）；
|
||||
// 未配置 agent 时 Run 返回 ErrNilAgent。
|
||||
func New(opts Options) *Loop {
|
||||
maxRounds := opts.MaxRounds
|
||||
if maxRounds <= 0 {
|
||||
@@ -180,15 +180,15 @@ func New(opts Options) *Loop {
|
||||
}
|
||||
}
|
||||
|
||||
// MaxRounds returns the tool-loop upper bound configured for the loop.
|
||||
// MaxRounds 返回为该循环配置的工具循环上限。
|
||||
func (l *Loop) MaxRounds() int { return l.maxRounds }
|
||||
|
||||
// Agent returns the injected default agent (Options.Agent). The per-role pool is
|
||||
// reached through the turn's context, not this getter.
|
||||
// Agent 返回注入的默认 agent（Options.Agent）。按角色池
|
||||
// 经该 turn 的 context 触达，而不是经这个 getter。
|
||||
func (l *Loop) Agent() *agent.Agent { return l.agent }
|
||||
|
||||
// sourcedLog returns a logger tagged with the module source "runtime/loop",
|
||||
// replacing a nil logger with a discard one so the loop can always log safely.
|
||||
// sourcedLog 返回标记模块来源 "runtime/loop" 的 logger，
|
||||
// 把 nil logger 替换为丢弃 logger，使循环总能安全地记录日志。
|
||||
func sourcedLog(l *slog.Logger) *slog.Logger {
|
||||
if l == nil {
|
||||
l = slog.New(slog.NewTextHandler(io.Discard, nil))
|
||||
|
||||
Reference in new issue
Block a user