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:
1 parent
355f81d04a
commit
91e8d7a029
44 files changed
+1315
-1315
No files matched your search
@@ -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:
|
||||
|
||||
Reference in new issue
Block a user