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

+34 -34
View File
@@ -11,29 +11,29 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/persist"
)
// checkpointStore is the minimal surface the loop needs to persist a durable
// snapshot and resume an interrupted run (design §1 durable execution).
// *persist.Store satisfies it in production; tests substitute a fake to assert
// the resume path without a real database.
// checkpointStore 是循环持久化持久快照并恢复被中断
// run 所需的最小表面(design §1 durable execution)。
// 生产环境由 *persist.Store 满足;测试替换为假实现,以在
// 没有真实数据库的情况下断言恢复路径。
type checkpointStore interface {
// Save upserts a checkpoint.
// Save 插入或更新一个 checkpoint。
Save(ctx context.Context, cp *persist.Checkpoint) error
// LoadLatest returns the most recently updated checkpoint for agentID, or
// ErrNotFound when the agent has none.
// LoadLatest 返回 agentID 最近更新的 checkpoint;
// 该 agent 没有时返回 ErrNotFound。
LoadLatest(ctx context.Context, agentID string) (*persist.Checkpoint, error)
}
// checkpointState is the durable snapshot persisted at every step. Carrying the
// message window and the step index lets a long-running task be resumed from the
// latest checkpoint without losing context (design §1 durable execution).
// checkpointState 是每步持久化的持久快照。携带消息
// 窗口与步索引,使长任务能从最新 checkpoint 恢复而不
// 丢失上下文(design §1 durable execution)。
type checkpointState struct {
Step int `json:"step"`
Messages []model.Message `json:"messages"`
StopReason string `json:"stop_reason,omitempty"`
}
// saveCheckpoint persists a snapshot at step. It never fails the run: a nil store
// is a no-op and a marshal/save error is logged.
// saveCheckpoint 在 step 处持久化一个快照。它绝不让 run 失败:
// store 为 nil 时为空操作,marshal/save 出错则记录日志。
func (l *Loop) saveCheckpoint(ctx context.Context, sessionID string, step int, messages []model.Message, stopReason string) {
if l.checkpoint == nil {
return
@@ -59,19 +59,19 @@ func (l *Loop) saveCheckpoint(ctx context.Context, sessionID string, step int, m
}
}
// loadCheckpoint resumes an interrupted run from the session's latest durable
// checkpoint (design §1 durable execution). It returns the restored message
// window, the next loop step to run (the checkpoint step + 1) and whether a
// resumable checkpoint was found. When no checkpoint exists, or the latest one
// reflects a completed/blocked run, it returns the caller's messages with step 1
// so the loop starts fresh.
// loadCheckpoint 从该会话最新的持久 checkpoint 恢复一个被中断的
// run(design §1 durable execution)。它返回恢复后的消息
// 窗口、下一个要运行的循环步(checkpoint 步 + 1),以及
// 是否找到了可恢复的 checkpoint。不存在 checkpoint,或最新的一个
// 反映的是已完成/被阻塞的 run 时,它返回调用方的消息并置步为 1,
// 使循环从新开始。
//
// Restoration is idempotent: the checkpoint captures the message window exactly as
// it stood at the end of the last completed step (assistant tool calls plus their
// results are already fused in), so resuming at the next step rebuilds the model
// context from history and never re-executes a completed step's tool call nor
// regenerates a finished answer. Loading is read-only — a resume never deletes the
// checkpoint, so every step's snapshot stays queryable.
// 恢复是幂等的:checkpoint 精确保存了上一个已完成步结束时
// 的消息窗口(assistant 工具调用及其结果已融合在内),
// 因此从下一步恢复会由历史重建模型
// 上下文,绝不重跑已完成步的工具调用,也不
// 重新生成已完成的答案。加载是只读的 —— 恢复绝不删除
// checkpoint,因此每一步的快照始终可查询。
func (l *Loop) loadCheckpoint(ctx context.Context, sessionID string, messages []model.Message) ([]model.Message, int, bool) {
if l.checkpoint == nil {
return messages, 1, false
@@ -96,16 +96,16 @@ func (l *Loop) loadCheckpoint(ctx context.Context, sessionID string, messages []
return st.Messages, cp.Step + 1, true
}
// resumableStopReason reports whether a checkpoint whose last step ended with the
// given stop reason represents an in-flight run worth resuming. Only a
// mid-tool-loop step is genuinely "interrupted": the loop folded the tool results
// into the window and was about to continue, so picking up at the next step
// rebuilds context without duplicating work. A checkpoint carrying a final answer,
// a budget exhaustion, a safety-net termination or a guardrail denial is a
// completed/blocked run — resuming it would regenerate an already-produced answer
// (a duplicate side effect) — so those fall through to a fresh start (a caller
// opening a genuinely new conversation uses a distinct sessionID, which misses
// LoadLatest anyway).
// resumableStopReason 报告最后一个步以上述 stop reason 结束的
// checkpoint 是否代表一个值得恢复的在途 run。只有
// 工具循环中途的步才真正算「被中断」:循环已把工具结果
// 并入窗口并即将继续,因此从下一步接上
// 会重建上下文而不重复工作。携带最终答案、
// 预算耗尽、安全网终止或护栏拒绝的 checkpoint 是
// 已完成/被阻塞的 run —— 恢复它会重新生成已产出的答案
// (重复副作用)—— 因此这些一律落到全新开始(打开
// 真正新会话的调用方使用不同的 sessionID,本就错过
// LoadLatest)。
func resumableStopReason(stopReason string) bool {
switch stopReason {
case "", agent.StopReasonToolCalls: