舰长Captain

任务简报Brief

学习目标Learning goals

• 复用 M3 的检索，拿到 Session loss 作为 top-1 证据。

  Reuse M3 retrieval and get Session loss as the top-1 evidence.

• 通过 write_report 工具写出包含证据、行动计划和引用的报告。

  Write a report with evidence, action plan and citations through the write_report tool.

• 用独立评审 Agent 返回结构化 Review。

  Get a structured Review from an independent reviewer agent.

• 持久化 AgentState，并在同一 session id 下恢复对话。

  Persist AgentState and resume the conversation under the same session id.

核心概念Core concepts

双轨实现Build it twice

先完整跑通一条轨道，再切换重来。两条轨道写出同一种产物，方便直接对照行为。Run one track end to end, then switch and repeat. Both tracks write the same artifact so you can compare behavior directly.

question = "Why does a restarted service forget the conversation session?"
hits = await evidence(question)
top = (hits[0].chunk.metadata or {}).get("heading")
assert top == "Session loss"

report = render_report(question, hits)
assert report.count("runbook.md") >= 3

model = ScriptedModel([
    tool_response("write_report", call_id="report-1",
                  path="report.md", content=report),
    "Report written and ready for review.",
])
agent = build_agent(model)
async for event in agent.reply_stream(UserMsg("user", question)):
    print(type(event).__name__)

state_path.write_text(agent.state.model_dump_json(indent=2), encoding="utf-8")
reloaded = AgentState.model_validate_json(
    state_path.read_text(encoding="utf-8"))
resumed = build_agent(resumed_model, state=reloaded)
await resumed.reply(UserMsg("user", "Continue after the restart."))

assert len(resumed.state.context) > len(agent.state.context)
assert resumed.state.session_id == agent.state.session_id

# python lab.py check m6
# PASS CODE: AS-M6-G5PF

python lab.py check m6

SimpleKnowledge knowledge = M3Librarian.buildKnowledge();
List<Document> hits = knowledge.retrieve(QUESTION,
        RetrieveConfig.builder().limit(3).scoreThreshold(0.0).build()).block();
String report = renderReport(QUESTION, hits);

FakeChatModel model = new FakeChatModel(List.of());
model.queue(LabSupport.toolCall("report-1", "write_report",
        Map.of("path", "report.md", "content", report)));
model.queue(LabSupport.text("Report written."));

Review review = review(written);  // structured generate_response

AgentStateStore store = new JsonFileAgentStateStore(
        LabSupport.missionWork("m6").resolve("state-store"));

ReActAgent agent = ReActAgent.builder()
        .name("captain").model(model).toolkit(toolkit())
        .stateStore(store).defaultSessionId("m6-capstone")
        .build();

AgentState state = agent.getAgentState(context);
agent.saveAgentState(context);
Files.writeString(statePath, state.toJson(), UTF_8);

try (ReActAgent resumed = agent(resumedModel, store)) {
    resumed.call(List.of(LabSupport.user("Continue after the restart.")), context).block();
    AgentState resumedState = resumed.getAgentState(context);
    assert resumedState.getContext().size() > state.getContext().size();
}

// cd lab/java && mvn -q -o compile exec:java -Dexec.args="check m6"

cd lab/java && mvn -q -o compile exec:java -Dexec.args="check m6"

Python ↔ Java 差异Python ↔ Java differences

• Python 直接序列化 AgentState 并作为构造参数传回；Java 通过 AgentStateStore 按 session 存取，Agent 重建后按 session id 加载。

  Python serializes AgentState and passes it back into the constructor; Java uses AgentStateStore keyed by session, loaded after rebuilding the agent.

• Python 有 SOPEngine，m6 仍是单 Agent + 工具；Java 则把检索、报告、评审和恢复显式串起来。两边的“编排感”不同。

  Python has SOPEngine but m6 is still a single agent plus tools; Java explicitly wires retrieval, report, review and resume. The orchestration feel differs.

• Python 用 reply_stream 收集事件名；Java 用 streamEvents + AgentEventType。产物格式保持一致，便于对照。

  Python collects event names from reply_stream; Java uses streamEvents + AgentEventType. Artifact shapes stay aligned for comparison.

常见坑Pitfalls

1. 恢复时换了 session id：状态存储找不到旧会话，表现就像“重启后失忆”。session id 必须稳定并可配置。

   Changing session id on resume: the store cannot find the old session, causing exactly the “amnesia” symptom. Keep the id stable and configurable.

2. 只保存摘要、不保存上下文：模型看不到之前的消息，恢复后答复会自相矛盾。持久化要覆盖真正影响推理的状态。

   Saving only a summary, not context: the model cannot see earlier messages and contradicts itself. Persist what actually affects reasoning.

3. 报告引用与检索结果不一致：模型“记得”某个段落但没引用它，或引用了未检索到的段落。生成报告时应以 hits 为唯一事实源。

   Report citations diverging from retrieval: the model “remembers” a section it did not retrieve or cites an absent one. Generate reports from hits as the only source of truth.

4. 评审 Agent 与执行 Agent 共用状态/提示词：容易自审自过。评审应是独立会话、独立提示词，至少独立上下文。

   Reviewer and executor sharing state/prompts invites self-approval. The reviewer should use a separate session, prompt and at least separate context.

5. 状态文件无限增长：每轮都追加完整上下文，长期运行会撑爆磁盘和上下文窗口。生产需要截断、摘要或分层记忆。

   Unbounded state files: appending full context every turn eventually blows disk and context windows. Production needs truncation, summaries or tiered memory.

领取通行码Claim your pass code

先运行当前轨道的 check。CLI 会打印 PASS CODE、XP 与徽章。粘贴到这里；同一关在每条轨道可各领取一次。Run the check for the current track. The CLI prints PASS CODE plus the exact XP and badge. Paste it here; the same mission can be claimed once on each track.

费曼复述Feynman recall

合上教程，用自己的话讲清机制。关键点覆盖 65%、篇幅 20%、结构 15%；60 分通过并一次性获得 20 XP。Explain the mechanism without looking. Coverage 65%, length 20%, structure 15%; 60 passes and earns +20 XP once.

间隔复习Spaced review

首次领取后会在明天安排复习。按真实感受评分，下一次间隔会自适应。After the first claim a review is scheduled for tomorrow. Rate how it felt; the next interval adapts.