第4章 ReactLoopAgent：ReAct 循环引擎

// ReactLoopAgent.java · 三级驱动（简化注释版）
private CompletableFuture<Void> kick(Phase.Running running) {   // 246行：驱动器
    return CompletableFuture.runAsync(() -> {
        while (true) {
            if (running.abort().get()) break;                    // 被取消则停
            if (!inbox.hasPending()) break;                      // 没消息则停
            if (!turn(running)) break;                           // 执行一轮
        }
        // finally 里：若期间又来了新消息，递归 kick 继续处理
    }, Executors.newCachedThreadPool());
}

private boolean turn(Phase.Running running) {                    // 282行：一轮
    session.append(SessionEventFactory.turnStart());
    final long MAX_STEPS_PER_TURN = 50;                          // 安全上限
    final int MAX_TOKEN_CONTINUATIONS = 4;                       // 续写上限
    boolean midTurnContinuation = false;                         // 关键标志（见4.6）
    while (true) {
        // ... 检查步数上限、取消、抢占 inbox 消息
        TurnEndReason stepResult = step(running, turn, step);    // 执行一步
        if (stepResult == null) { midTurnContinuation = true; continue; }  // 工具续步
        // ... 根据 Completed/MaxTokens/Blocked/Aborted/Error 决定 turn 结局
    }
}

private TurnEndReason step(Phase.Running running, long turn, long step) {  // 404行：一步
    // 1. 组装系统提示词  2. 构建请求  3. 流式调用 LLM
    // 4. BlockAssembler 组装响应  5. 有工具调用则执行并回填
}

// 取消：只设置标志位，不断线程
public synchronized void cancel(AgentCancelCause cause, boolean keepInbox) {
    if (phase instanceof Phase.Running r) {
        r.abort().set(true);   // AtomicBoolean，运行中的循环自己检查发现
    }
}

// step 内等待流式结束时的检查（485行）
while (!done.await(100, TimeUnit.MILLISECONDS)) {
    if (running.abort().get()) { aborted.set(true); break; }  // 100ms 轮询
}

// 流式订阅 onNext 里也检查（442行）：一旦发现 abort 立即 subscription.cancel()

// 修复：引入 midTurnContinuation 标志
boolean midTurnContinuation = false;
while (true) {
    if (!midTurnContinuation) {
        claimed = inbox.claim(InboxTarget.NEXT_TURN, (int) turn);
        if (claimed.isEmpty() && !inbox.hasPending() && !continuationRequested) break;
        // ...
    }
    TurnEndReason stepResult = step(running, turn, step);
    if (stepResult == null) {           // null = 工具调用已完成，模型应继续推理
        midTurnContinuation = true;      // 后续 step 跳过 inbox 检查
        continue;
    }
}

final int MAX_TOKEN_CONTINUATIONS = 4;
// ...
} else if (stepResult instanceof TurnEndReason.MaxTokens) {
    if (++tokenContinuations > MAX_TOKEN_CONTINUATIONS) {
        session.append(SessionEventFactory.turnEnd(new TurnEndReason.MaxTokens()));
        return true;   // 续写 4 次还不够，放弃，turn 结束
    }
    continuationRequested = true;   // 标记：下一步是续写，不要从 inbox 取新消息
    continue;
}

// Inbox.claim()（简化）
public List claim(InboxTarget target, int turn) {
    List claimed = new ArrayList<>(mutate(NEXT_STEP, 0, nextStep.size(), List.of(), false));
    if (target == InboxTarget.NEXT_TURN) {
        claimed.addAll(mutate(NEXT_TURN, 0, 1, List.of(), false));  // 抢占 1 条
    }
    for (Message m : claimed) notifications.claimed(m, turn);  // 发布 claimed 通知
    return claimed;
}

// Inbox.mutate()（简化）
public List splice(target, start, deleteCount, inserted) {
    var event = SessionEventFactory.inboxSpliced(...);  // 1. 构造事件
    session.append(event);                              // 2. 先追加到 WAL
    // 3. 再改内存列表
    inbox.subList(start, start + actualDeleteCount).clear();
    for (int i = inserted.size() - 1; i >= 0; i--) inbox.add(start, inserted.get(i));
    // 4. 发通知
    if (discardRemoved) removed.forEach(notifications::discarded);
    inserted.forEach(notifications::inserted);
}

private static final int CONTEXT_WINDOW_FALLBACK = 128_000;  // 对应 yml context-window

private GenerateOptions buildRequest(PromptAssembly assembly, long turn, long step) {
    List history = session.deriveMessages();
    if (continuationRequested) {  // 续写场景：注入"接着写"指令
        history.add(Message.createUser(
            List.of(new TextBlock(CONTINUATION_PROMPT)),
            new PluginSource("react-loop")));
    }
    int maxContext = CONTEXT_WINDOW_FALLBACK;
    int systemTokens = estimateTokens(assembly.system());
    int budget = maxContext - systemTokens - options.maxTokens() - 1024;
    if (budget < 4096) budget = 4096;  // 保底
    history = truncateToBudget(history, budget);
    return new GenerateOptions(...);
}

budget = context_window(128k)
       - system_tokens        // 系统提示词占的 token
       - max_tokens            // 本次回复的预留 token
       - 1024                  // 安全余量
（最低 4096）

// 读系统属性 / 环境变量；null = 不发送 temperature
private static final Double SAMPLING_TEMPERATURE = parseTemperature(
    System.getProperty("harness.agent.temperature",
            System.getenv("HARNESS_AGENT_TEMPERATURE")));

private static Double parseTemperature(String raw) {
    if (raw == null || raw.isBlank()) return null;  // 关键：null → 不发送
    try { return Double.parseDouble(raw.trim()); }
    catch (NumberFormatException e) { return null; }
}

# 方式 1：环境变量
export HARNESS_AGENT_TEMPERATURE=1

# 方式 2：JVM 启动参数
java -Dharness.agent.temperature=1 -jar app.jar

# 不设 = 不发送 temperature 字段，让上游自己决定

// AgentDispatchNode.buildDirectoryInstruction()（当前版本，:115 起）
private static String buildDirectoryInstruction(String messageText) {
    if (messageText == null || !DIRECTORY_QUESTION.matcher(messageText).find()) return null;
    Matcher matcher = ABSOLUTE_PATH.matcher(messageText);
    if (!matcher.find()) return null;
    String directory = matcher.group(1);
    return "你需要列出这个目录的一级子目录和文件。推荐用 `shell_execute` 执行 `ls -la \""
         + directory + "\"` 获取完整列表，\n"
         + "或者用 `find \"" + directory + "\" -maxdepth 1 -type d` 只列目录。\n"
         + "拿到真实结果后，用 Markdown 列表展示所有一级项目，不要遗漏、不要模糊化。\n\n"
         + "用户原始请求：" + messageText;
}