tori/doc/context.md

Agent Runtime 设计

Context 管理现状与设计

现状

当前没有做 context 长度限制，存在超过 model token limit 的风险。

已有的缓解机制

1. Phase transition 时 clear：step_messages 在 planning→executing 和 step→step 切换时会 clear()，避免跨阶段累积
2. 单条 tool output 截断：bash 输出限制 8000 bytes，read_file 超长时也截断
3. Step context 摘要：已完成步骤只保留 summary（step_summaries），不带完整输出

风险场景

• 一个 execution step 内 tool call 轮次过多（反复 bash、read_file），step_messages 无限增长
• 每轮 LLM 的 assistant message + tool result 都 push 进 step_messages，没有上限
• 最终整个 messages 数组超过模型 context window

方案设计

策略：滑动窗口 + 早期消息摘要

当 step_messages 长度超过阈值时，保留最近 N 轮完整对话，早期的 tool call/result 对折叠为一条摘要消息。

[system prompt]
[user: step context]
[summary of early tool interactions]  ← 压缩后的历史
[recent assistant + tool messages]    ← 完整保留最近 N 轮

具体实现

1. Token 估算：用字符数粗估（1 token ≈ 3-4 chars 中英混合），不需要精确 tokenizer
2. 阈值：可配置，默认如 80000 chars（约 20k-25k tokens），给 system prompt 和 response 留余量
3. 压缩触发：每次构建 messages 时检查总长度，超过阈值则压缩
4. 压缩方式：
   • 简单版：直接丢弃早期 tool call/result 对，替换为 [已执行 N 次工具调用，最近结果见下文]
   • 进阶版：用 LLM 生成摘要（额外一次 API 调用，但质量更好）
5. 不压缩的部分：system prompt、user context、最近 2-3 轮完整交互

实现位置

在 run_agent_loop 中构建 messages 之后、调用 LLM 之前，插入压缩逻辑：

// agent.rs run_agent_loop 内，约 L706-L725
let (mut messages, tools) = match &state.phase { ... };

// 压缩 context
compact_messages(&mut messages, MAX_CONTEXT_CHARS);

compact_messages 函数：从前往后扫描，保留 system/user 头部，计算总长度，超限时将早期 assistant+tool 消息替换为摘要。

---

执行中用户反馈处理 (Plan-Centric Feedback)

核心原则

Agent loop 是 以 plan 为中心线性推进 的。用户反馈的处理不应该是简单的"中断/不中断"二元决策，而应该根据反馈落在 plan 的哪个位置来决定行为：

Plan: [step1 ✓] [step2 ✓] [step3 🔄 executing] [step4 ○] [step5 ○]
                                    ↑
                              当前执行位置

用户反馈 →  影响哪里？
  ├─ 影响已完成部分 (step1/step2) → 回退：中断当前执行，replan from affected step
  ├─ 改了需求本身              → 回退：中断当前执行，全部 replan
  ├─ 影响未完成部分 (step4/step5) → 前进：不中断，调整后续 plan steps
  └─ 影响当前步骤 (step3)       → 视情况：注入到当前 step context 或中断重做

与"中断"的关系

"中断"只是一个实现手段，不是目的。真正的决策是：

1. 反馈是否影响当前或已完成的工作？ → 必须中断（继续执行是浪费）
2. 反馈只影响未来的步骤？ → 不中断，修改 plan 里的 pending steps，执行到那里时自然生效

这意味着 cancel token 之类的机制仍然需要（作为中断的执行手段），但决策逻辑是 plan-aware 的。

决策流程

用户 comment 到达
    │
    ├─ workflow idle (done/failed)
    │   └─ 当前逻辑：以 comment 为 context 重新执行
    │
    └─ workflow executing (step N)
        │
        ├─ 1. 分类 LLM 调用（轻量，不阻塞执行）
        │     输入：原始需求、当前 plan、当前步骤进度、用户 comment
        │     输出：{ impact: "past" | "current" | "future" | "requirement_change" }
        │
        ├─ impact = "past" 或 "requirement_change"
        │   → cancel 当前执行
        │   → replan（带上已完成步骤的摘要 + 用户反馈）
        │
        ├─ impact = "current"
        │   → 注入到 step_messages（当前步骤的 context）
        │   → agent 在下一次 LLM 调用时自然看到
        │   → 如果反馈是否定性的（"这样不行"），cancel 当前步骤，重做
        │
        └─ impact = "future"
            → 修改 plan 中 pending steps（update/insert/delete）
            → 不中断当前执行
            → 执行到对应步骤时自然生效

实现要点

1. Plan 作为可变数据结构

当前 plan steps 存在 DB 里，但 agent 执行时是线性推进的，没有"修改后续步骤"的能力。需要：

• plan steps 支持运行时增删改（不仅是状态更新）
• agent 每执行完一步，从 DB 重新读 plan（而不是用内存快照），这样外部修改能被感知

2. 并发：分类 LLM 与执行 LLM 并行

分类调用不应该阻塞执行。用 tokio::spawn 做分类，分类结果通过 channel 或 shared state 回传。如果分类结果是"需要中断"，设置 cancel token。

// 伪代码
tokio::spawn(async move {
    let impact = classify_feedback(&llm, &plan, current_step, &comment).await;
    match impact {
        Impact::Past | Impact::RequirementChange => {
            cancel_token.cancel();
            // replan 会在 cancel 生效后由主循环触发
        }
        Impact::Current => {
            // 注入到 step context
            step_messages_tx.send(comment).await;
        }
        Impact::Future => {
            // 调用 LLM 修改后续 plan steps
            replan_future_steps(&llm, &plan, current_step, &comment).await;
        }
    }
});

3. 中断后的 Context 衔接

中断执行后重启时，需要构建的 context：

• 已完成步骤的摘要（已有 step_summaries 机制）
• 被中断步骤的部分执行记录
• 用户反馈内容
• "请根据用户反馈重新规划剩余步骤"的指令

这和上面 context 压缩的滑动窗口方案互补——中断后重启本质上就是一次强制的 context 压缩。

与 context 压缩的统一视角

两个问题其实是同一件事的两面：

	Context 压缩	用户反馈
触发条件	token 数超阈值	用户发了 comment
本质操作	摘要化早期历史，保留近期	根据反馈位置，决定哪些历史需要保留/丢弃/重做
共享机制	step_summaries、compact_messages	同上 + plan 的增删改

两者都需要一个健壮的"摘要化已完成工作"的基础能力。先把这个基础能力做好，上面两个场景都能受益。

Plan-Centric Context 优先级

Context 管理也应该围绕 plan 展开。Plan 本身是结构化的、紧凑的，基本不会超。撑爆 context 的是执行日志（一个 step 内反复 tool call 的历史）。这就有了清晰的层级和主次：

优先级（从高到低，压缩时从低往高砍）：

1. System prompt + 需求                  ← 不可压缩，恒定大小
2. Plan 全貌（步骤标题 + 状态）            ← 不可压缩，O(步骤数) 很短
3. 用户 comments                        ← 保留原文，通常很短
4. 当前步骤的最近 N 轮 tool call           ← 完整保留（agent 需要看到最近的执行结果）
5. 当前步骤的早期 tool call               ← 第一优先压缩目标，摘要化
6. 已完成步骤的执行摘要                    ← 已经是一句话/步骤，极紧凑

关键洞察：Plan 是骨架，执行日志是血肉。 骨架永远保留，血肉按新鲜度裁剪。这和人类记忆一样——你记得"今天做了什么"（plan），但不记得每一步的具体命令输出（执行日志）。

压缩算法因此变得很简单：

1. 算总 token 估计
2. 如果超阈值，从"当前步骤的早期 tool call"开始砍，替换为 [前 N 次工具调用已折叠，关键结果：...]
3. 如果还超，压缩已完成步骤的摘要（合并多步为一段）
4. Plan 和 system prompt 永远不动

---

状态管理、并发与一致性

系统中的参与者和他们各自的"世界观"

一致性问题的本质是：多个参与者对同一份状态有各自的视图，这些视图会因为延迟和并发而产生分歧。

参与者	看到的世界	更新方式	延迟
Agent loop	内存 AgentState	直接修改	0（权威源）
LLM	上一次调用时传入的 messages	每次调用时重建	一次 LLM 调用的时间（数秒）
DB	持久化的 plan_steps, workflow.status	agent 写入	取决于 agent 何时 flush
前端	最近一次 WS 推送 / API 响应	WS broadcast	网络延迟 + WS 推送时机
用户	看着前端 + 自己的判断	发 comment	人类反应时间（秒~分钟）

问题出在哪：

时间线：
  t0  agent 开始执行 step 3
  t1  前端显示 step 3 running（WS 推送）
  t2  用户看到 step 3，觉得方向不对，开始打字
  t3  agent 完成 step 3，开始 step 4
  t4  前端显示 step 4 running
  t5  用户发出 comment："step 3 不对，应该这样做"
      → 但此时 step 3 已经做完了，step 4 在跑了
      → 用户的反馈是基于 t1 时的世界观

这种"用户看到的是过去"是不可消除的（人类反应时间），关键是系统怎么处理这个 gap。

核心设计：统一状态 + 单写者

状态 Schema

一个 project 的完整运行时状态 = 一个 ProjectState 对象：

struct ProjectState {
    workflow_id: String,
    requirement: String,
    status: WorkflowStatus,             // Idle / Executing / Done / Failed

    plan: Vec<PlanStep>,                // 有序步骤，每步有 status
    current_step: Option<usize>,        // 正在执行哪一步

    step_summaries: Vec<StepSummary>,   // 已完成步骤的紧凑摘要
    step_messages: Vec<ChatMessage>,    // 当前步骤的 tool call 历史（临时，会膨胀）

    memo: String,                       // agent 备忘
    iteration: u32,                     // LLM 调用轮次

    cancel: CancellationToken,          // 中断信号
}

用 Arc<RwLock<ProjectState>> 持有。

单写者规则

只有 agent loop 修改 ProjectState。 没有例外。

其他所有参与者（反馈分类器、API handler、WS handler）都是读者或事件发送者：

• 想看状态 → read lock，clone 出快照，立即释放
• 想改状态 → 发 event 到 agent loop 的 channel，由 agent loop 决定怎么改

这彻底消除了写-写竞争。不需要事务，不需要 CAS，不需要冲突解决。

数据流

用户 comment ─→ API handler ─→ mpsc channel ─→ agent loop (唯一写者)
                                                    │
                                              write lock ──→ ProjectState
                                                    │
                                              write DB (flush)
                                                    │
                                              broadcast WS ──→ 前端

一致性分析：三对关系

1. 内存 ↔ DB 一致性

当前问题：AgentState（内存）和 plan_steps（DB）是两套独立数据，各管各的。

解法：内存是 master，DB 是 checkpoint。

• Agent loop 修改 ProjectState（内存），在关键节点 flush 到 DB
• 前端 API 读内存（read lock），不读 DB（运行时）
• DB 只在重启恢复时读

Flush 时机（从密到疏）：

事件	写 DB	原因
workflow.status 变更	立即	重启恢复必需
plan 变更（新建/修改步骤）	立即	重启恢复 + 持久记录
步骤完成（summary 产出）	立即	重启恢复的关键数据
step_messages 增长	不写	临时数据，中断时才摘要化
memo 更新	步骤切换时	丢了问题不大

重启恢复 = 从 DB 重建 ProjectState，step_messages 为空（丢失可接受，summaries 提供足够上下文）。

2. 后端 ↔ 前端 一致性

前端通过两个渠道获取状态：

• WS 推送：agent loop 每次修改状态后 broadcast
• API 拉取：前端 mount 时、切换 project 时

一致性模型：最终一致。前端可能落后几百毫秒，但不会出现永久分歧。

需要保证的不变量：

• WS 推送的顺序和状态变更顺序一致（单写者天然保证）
• 前端收到 WS 消息后，可以安全地 patch 本地状态（不需要全量刷新）
• 如果 WS 断连，重连后拉一次全量状态即可恢复

3. Agent loop ↔ LLM ↔ 用户反馈 一致性

这是最微妙的。三方的时间线：

Agent loop:  ──[step3 执行中]──[step3 完成]──[step4 开始]──...
LLM:         ──[thinking...]──[返回 tool calls]──
用户:        ──[看到 step3]──[打字中...]──[发送 comment]──

三个视角可能同时看到不同的状态。处理方式：

a) LLM 的"冻结视角"

每次 LLM 调用时，传入的 messages 是一个 point-in-time 快照。LLM 返回的 tool calls 是基于那个快照的。在 LLM 思考期间，状态可能已经变了（比如用户发了 comment），但 LLM 不知道。

这没关系——LLM 返回后，agent loop 先检查 cancel flag，再决定是否执行 tool calls。如果 cancel 了，丢弃 LLM 的响应，不浪费。

b) 用户反馈的"过时性"

用户发 comment 时看到的可能是几秒前的状态。反馈里提到的"step 3"可能已经完成了。

处理：反馈分类器拿当前快照（read lock），对比用户反馈和当前进度，判断反馈是关于：

• 已完成的步骤 → 需要 revert/redo
• 当前步骤 → 注入或中断
• 未来步骤 → 修改 plan
• 需求级别 → 全部 replan

分类结果作为 event 发给 agent loop。Agent loop 收到时再次基于最新状态做最终决策（双重检查）。

c) 反馈分类器的并发

反馈分类器 tokio::spawn 出去，和 agent loop 并行：

Agent loop:        ──[step4 执行中]──────────[step4 完成]──[处理 feedback event]──
                                                              ↑
Feedback classifier: ──[拿 snapshot]──[LLM 分类...]──[发 event]─┘

分类器拿的 snapshot 可能已经过时了（分类期间 agent 又推进了一步）。但因为分类结果是建议性的，agent loop 收到后基于最新状态做最终决策，所以不会出错。最坏情况：建议无效，忽略。

Agent loop 内部的事件处理

Agent loop 不再是"拿 event → 跑完整个 run_agent_loop → 拿下一个 event"。而是在 tool call 循环内部也能感知新事件：

for iteration in 0..MAX_ITERATIONS {
    // 1. 检查中断
    if state.cancel.is_cancelled() {
        // 摘要化当前 step_messages，存 DB
        break;
    }

    // 2. 检查是否有 pending feedback events（非阻塞）
    while let Ok(event) = feedback_rx.try_recv() {
        handle_feedback(&mut state, event);
        // 可能修改了 plan、设置了 cancel、注入了 step_messages
    }

    // 3. 构建 messages，调 LLM
    let messages = build_messages(&state);
    let response = llm.chat(messages).await?;

    // 4. 执行 tool calls，更新 state
    // ...
}

关键：feedback_rx.try_recv() 是非阻塞的。在每次 LLM 调用之间检查一次。如果有 feedback，立即在 agent loop 内处理（修改 plan / 设置 cancel / 注入 context），然后继续循环。

这保持了单写者——所有状态变更都在这个循环里发生。

实现顺序

1. 定义 ProjectState — 集中状态，Arc<RwLock<_>>。Agent loop 内部用起来，行为不变。
2. DB flush 策略 — 关键节点写 DB（status 变更、步骤完成），前端 API 改为读内存。
3. Step 摘要持久化 — 步骤完成时写 summary 到 DB，重启时重建 ProjectState。
4. Context 压缩 — step_messages 滑动窗口。
5. CancellationToken + feedback channel — agent loop 内部 try_recv，单写者处理反馈。
6. Feedback 分类器 — tokio::spawn，read lock 拿快照，LLM 分类，结果发回 agent loop。