# 三个角色 = 三段岗位说明书（system prompt）
RESEARCHER = """你是研究员。只负责检索与整理，不写成文。
输出格式：要点清单，每条要点后用【出处：文件名】标注来源。资料没有的绝不编。"""

WRITER = """你是写手。把研究员给的【要点清单】组织成一篇 500 字结构化简报。
只能使用清单里的内容，不得自行添加清单里没有的事实。保留每个论点的【出处】。"""

REVIEWER = """你是审校（主编）。检查写手的稿子：
1) 是否有清单/出处里没有的说法（编造）？
2) 出处是否对得上？
输出 JSON：{"pass": true/false, "problems": ["..."]}。有问题就 pass=false，列出问题。"""

def run_agent(system, user_input):     # 一个通用"员工"：换 system 就换角色
    resp = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "system", "content": system},
                  {"role": "user",   "content": user_input}])
    return resp.choices[0].message.content

# 编排骨架：手写版流水线（先不上框架，看清流程）
import json
def workflow(topic):
    state = {"topic": topic, "retries": 0}
    state["points"] = run_agent(RESEARCHER, f"主题：{topic}，检索并整理要点")
    while state["retries"] <= 2:                          # 返工上限 2 次
        state["draft"]  = run_agent(WRITER, state["points"])
        review = json.loads(run_agent(REVIEWER,
                    f"要点：{state['points']}\n稿子：{state['draft']}"))
        if review["pass"]:                               # 审校通过 → 出稿
            return state["draft"]
        # 不过：把问题贴回黑板，让写手带着问题返工
        state["points"] += f"\n【审校要求修正】{review['problems']}"
        state["retries"] += 1
    return state["draft"] + "\n（注：已达返工上限，请人工复核）"  # 兜底不硬崩

# 极简可观测：给每一步打结构化日志（trace 的雏形，Day55）
import time, json
def traced(role, fn, inp):
    t0 = time.time()
    out = fn(inp)
    print(json.dumps({                     # 结构化日志：一行一步，好检索、好统计
        "role": role, "ms": int((time.time()-t0)*1000),
        "in_len": len(inp), "out_len": len(out)}, ensure_ascii=False))
    return out
# 每步都包一层：traced("研究员", lambda x: run_agent(RESEARCHER, x), topic)
# 跑完一条链，日志就是一份"工时台账"：哪步慢、哪步输出异常短，一目了然

# 可复用项目骨架（压轴项目，集大成）
report-crew/
├── agents/
│   ├── researcher.py   # 研究员：复用作品①的 RAG 检索
│   ├── writer.py       # 写手
│   └── reviewer.py     # 审校（质检闸，L04）
├── workflow.py         # 编排：研究→写→审→返工（L03）
├── tools/              # 复用作品②的工具（联网/查库等）
├── trace.py            # 可观测：结构化日志 / trace（L05）
├── app.py              # FastAPI：POST /report {topic} → 出简报（Day09）
├── eval.py             # 评测：通过率 / 编造率 / 耗时成本（L05）
├── golden.json
├── requirements.txt
├── Dockerfile          # 打包（Day57）
└── README.md           # 架构图 + 效果数字 + demo（Day65）

✋ 动手 10 分钟：手动扮演三个角色跑一遍流水线

不接大模型,你亲自当研究员/写手/审校,把"黑板 + 返工"的流程走通,体会编排逻辑:

state = {"topic": "咖啡因对睡眠的影响", "retries": 0}
# 你扮研究员：写 2 条带出处的要点
state["points"] = "1) 咖啡因阻断腺苷【出处：A.pdf】\n2) 半衰期约5小时【出处：B.pdf】"
# 你扮写手：只用上面要点写一句话（故意混进一条没出处的“编造”试试）
state["draft"] = "咖啡因阻断腺苷、半衰期约5小时，且能提升智商20%。"
# 你扮审校：对照要点挑错 → 第三句“提升智商”查无出处 → 打回
review = {"pass": False, "problems": ["‘提升智商20%’在要点里查无出处，疑似编造"]}
print("审校结果：", review)     # pass=False → 该带着 problems 返工
# 想想：如果 retries 已经=2 了，流程该怎么兜底不死循环？

能说清"黑板上此刻有什么、审校为什么打回、返工怎么终止",今天就通关了。