导演Showrunner

任务简报Brief

学习目标Learning goals

• 用 SOP / 手工循环表达“执行 → 验证 → 重试 → 交接”。

  Express execute → verify → retry → hand over with SOP or a manual loop.

• 让验证器返回结构化 verdict，而不是自然语言“还行”。

  Make the verifier return a structured verdict, not a vague “looks fine.”

• 验证首次被拒、第二次通过，且执行器/验证器调用次数符合预算。

  Verify a rejection then a pass, with executor/verifier call counts within budget.

• 把流程状态落盘，形成可观测的产物。

  Persist the flow state as an observable artifact.

核心概念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.

from agentscope.sop import SOP, SOPEngine, SOPStep

sop = SOP(
    name="launch-review",
    description="Draft a launch checklist, survive review, then approve release.",
    steps=[
        SOPStep(subject="Draft launch checklist",
                executor=executor, verifier=verifier, max_attempts=3),
        SOPStep(subject="Approve release", executor=executor),
    ],
)
engine = SOPEngine(sop)

class Verdict(BaseModel):
    passed: bool
    message: str

class Handover(BaseModel):
    handover: str

verifier_model = ScriptedModel([
    structured_response({"passed": False,
                         "message": "Missing a rollback rehearsal; add it."}),
    structured_response({"passed": True,
                         "message": "Rollback is covered."}),
])

python lab.py check m4
cat work/m4/sop_run.json

# 期望看到
# PASS CODE: AS-M4-W3JZ

python lab.py check m4

public record Handover(String handover) {}
public record Verdict(boolean passed, String message) {}

Handover draft = callStructured(executor, task, Handover.class, "m4-executor");
Verdict verdict = callStructured(verifier,
        "Review this launch checklist:\n" + draft.handover(),
        Verdict.class, "m4-verifier");

String feedback = "";
String accepted = "";
List<Boolean> verdicts = new ArrayList<>();
for (int attempt = 1; attempt <= 3; attempt++) {
    String task = attempt == 1
            ? "Draft a launch checklist with rollback."
            : "Revise the checklist. Reviewer said: " + feedback;
    Handover draft = callStructured(executor, task, Handover.class, "m4-executor");
    Verdict verdict = callStructured(verifier,
            "Review:\n" + draft.handover(), Verdict.class, "m4-verifier");
    verdicts.add(verdict.passed());
    if (verdict.passed()) { accepted = draft.handover(); break; }
    feedback = verdict.message();
}

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

# 期望看到
# PASS CODE: AS-M4-W3JZ

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

Python ↔ Java 差异Python ↔ Java differences

• Python 用 SOP/SOPEngine 表达流程；Java 2.0.4 没有对应 API，需要手工维护 steps、attempts 和 verdicts。

  Python uses SOP/SOPEngine; Java 2.0.4 has no equivalent, so steps, attempts and verdicts are maintained by hand.

• 两条轨道都用结构化裁决；Python 通过 structured_response 脚本，Java 通过 generate_response + record。

  Both use structured verdicts; Python scripts structured_response, Java uses generate_response + records.

• Python 的 SOPEngine 会发出 CustomEvent；Java 只有 Agent 事件，流程事件需要自己发。

  Python's SOPEngine emits CustomEvents; Java only has agent events, so flow events are yours to emit.

常见坑Pitfalls

1. 没有重试上限：验证器一直拒绝，循环会烧光预算。必须设置 max_attempts 或手工计数。

   No retry cap: a verifier that keeps rejecting burns the budget. Set max_attempts or count manually.

2. 验证器返回自由文本：状态机无法判断“通过”，只能靠字符串匹配，极其脆弱。

   A verifier returning free text: the state machine cannot tell “passed” and must string-match, which is brittle.

3. 验证器和执行器共用同一个模型/提示词：容易出现“自己审自己”，拒绝率过低。生产应使用不同提示词、模型或规则。

   Sharing one model/prompt between executor and verifier invites self-approval. Use different prompts, models or rules in production.

4. 交接内容缺少证据：只写“已完成”而不写回滚演练、测试结果或负责人，验证器只能拒绝或放水。

   Handovers without evidence: “done” without rollback, test results or owners forces the verifier to reject or rubber-stamp.

领取通行码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.