◉ClassyGitShadowzzh

agents.py

agents.py
"""
实验 10-3:书籍翻译 Agent —— 管理者模式(Orchestration)

本模块实现四种专职 Agent,以及两种运行方式:
  1) 管理者模式(orchestrate):Manager 只保存任务/计划/调用记录/文件索引,
     不保存完整译文;各子 Agent 拥有独立、隔离的上下文。
  2) 单 Agent 模式(single_agent):一个 Agent 在同一条不断增长的对话里
     依次读全书、逐章翻译,用于对照“上下文膨胀”与“术语漂移”。

核心验证点:
  - 记录每个 Agent / Manager 的上下文 token 消耗;
  - 证明管理者模式下 Manager 的上下文明显小于单 Agent 的累积上下文;
  - 证明共享术语表能让术语在各章保持一致。
"""

import os
import json

import tiktoken
from openai import OpenAI


# ----------------------------------------------------------------------------
# 配置:model / base_url 可通过环境变量覆盖,默认当前便宜旗舰 gpt-5.6-luna
# ----------------------------------------------------------------------------
MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.6-luna")
BASE_URL = os.environ.get("OPENAI_BASE_URL")  # 可选,兼容自建/代理端点


def _report_issues(report: dict) -> list:
    """JSON null issues must behave like omit ([])."""
    issues = report.get("issues")
    return issues if issues is not None else []


def _to_openrouter_model(model: str) -> str:
    """把模型名映射到 OpenRouter 命名空间(用于无 OPENAI_API_KEY 的回退路径)。"""
    if "/" in model:
        return model                      # 已是 OpenRouter 命名空间,原样使用
    if model.startswith("gpt-"):
        return "openai/" + model          # gpt-* -> openai/gpt-*
    if model.startswith("claude-"):
        return "anthropic/claude-opus-4.8"
    return "openai/gpt-5.6-luna"          # 兜底:当前便宜旗舰


def get_client() -> OpenAI:
    """创建 LLM 客户端。

    通用回退策略:
      1) 有 OPENAI_API_KEY -> 直连 OpenAI(尊重可选的 OPENAI_BASE_URL);
      2) 否则有 OPENROUTER_API_KEY -> 自动改走 OpenRouter 网关,并把 MODEL
         映射到 OpenRouter 命名空间(如 gpt-5.6-luna -> openai/gpt-5.6-luna);
      3) 都没有则报清晰错误。
    """
    global MODEL
    api_key = os.environ.get("OPENAI_API_KEY")
    if api_key:
        kwargs = {"api_key": api_key}
        if BASE_URL:
            kwargs["base_url"] = BASE_URL
        return OpenAI(**kwargs)
    or_key = os.environ.get("OPENROUTER_API_KEY")
    if or_key:
        MODEL = _to_openrouter_model(MODEL)
        return OpenAI(api_key=or_key, base_url="https://openrouter.ai/api/v1")
    raise RuntimeError(
        "未设置 OPENAI_API_KEY 或 OPENROUTER_API_KEY,请参考 env.example 配置。"
    )


# tiktoken 编码器:用于统计“未真正发给模型”的上下文(如 Manager 状态)token 数
try:
    _ENC = tiktoken.encoding_for_model(MODEL)
except Exception:
    _ENC = tiktoken.get_encoding("o200k_base")


def _slug(name: str) -> str:
    """把章节名转成干净的文件名前缀,如 'Chapter 1: ...' -> 'chapter1'。"""
    import re
    m = re.search(r"chapter\s*0*(\d+)", name, re.IGNORECASE)
    if m:
        return f"chapter{m.group(1)}"
    return re.sub(r"[^0-9a-zA-Z]+", "_", name).strip("_").lower() or "chapter"


def _loads_lenient(content: str):
    """容错解析 JSON:兼容个别模型把 JSON 包在 ```json ... ``` 代码围栏里的情况。"""
    s = (content or "").strip()
    if s.startswith("```"):
        s = s.split("\n", 1)[-1] if "\n" in s else s
        s = s.rsplit("```", 1)[0].strip()
        if s.lower().startswith("json"):
            s = s[4:].strip()
    return json.loads(s)


def count_tokens(text: str) -> int:
    """统计一段文本的 token 数。"""
    return len(_ENC.encode(text or ""))


def count_messages_tokens(messages) -> int:
    """统计一组 chat messages 的 token 数(近似:内容 + 每条消息固定开销)。"""
    total = 0
    for m in messages:
        total += count_tokens(m.get("content", "")) + 4  # 每条消息约 4 token 结构开销
    return total


# ----------------------------------------------------------------------------
# Token 追踪器:记录每一次 LLM 调用的上下文规模,并按 Agent 聚合
# ----------------------------------------------------------------------------
class TokenTracker:
    """
    记录每个 Agent 每次调用的上下文 token 消耗。

    - prompt_tokens:本次调用发送给模型的“上下文”大小(真实 API usage)。
      这是衡量“上下文膨胀”的关键指标。
    - peak:某个 Agent 在其所有调用中,单次上下文的最大值(上下文峰值)。
    """

    def __init__(self):
        self.calls = []  # 每次调用一条记录

    def record(self, agent, prompt_tokens, completion_tokens, note=""):
        self.calls.append(
            {
                "agent": agent,
                "prompt_tokens": prompt_tokens,
                "completion_tokens": completion_tokens,
                "note": note,
            }
        )

    def by_agent(self):
        """按 Agent 聚合:调用次数、输入/输出总量、上下文峰值。"""
        agg = {}
        for c in self.calls:
            a = agg.setdefault(
                c["agent"],
                {"calls": 0, "in": 0, "out": 0, "peak_context": 0},
            )
            a["calls"] += 1
            a["in"] += c["prompt_tokens"]
            a["out"] += c["completion_tokens"]
            a["peak_context"] = max(a["peak_context"], c["prompt_tokens"])
        return agg

    def total_tokens(self):
        return sum(c["prompt_tokens"] + c["completion_tokens"] for c in self.calls)


# ----------------------------------------------------------------------------
# LLM 调用封装:每次调用都带上 agent 名字,便于按 Agent 记账
# ----------------------------------------------------------------------------
def llm_chat(client, tracker, agent, messages, json_mode=False, note=""):
    """
    发起一次 chat completion,并把真实 token usage 记入 tracker。

    注意:messages 是本次调用的“独立上下文”。子 Agent 每次都从零构造 messages,
    因此各 Agent 的上下文天然隔离,互不污染。
    """
    kwargs = {"model": MODEL, "messages": messages, "temperature": 0.2}
    if json_mode:
        kwargs["response_format"] = {"type": "json_object"}

    try:
        resp = client.chat.completions.create(**kwargs)
    except Exception as e:
        # 推理模型(如 gpt-5.x)只接受默认 temperature,会拒绝自定义值;
        # 此时去掉 temperature 重试一次,保持其余参数不变。
        if "temperature" in str(e).lower():
            kwargs.pop("temperature", None)
            resp = client.chat.completions.create(**kwargs)
        else:
            raise
    usage = resp.usage
    tracker.record(agent, usage.prompt_tokens, usage.completion_tokens, note)
    return resp.choices[0].message.content


# ============================================================================
# 四种专职 Agent
# ============================================================================

# 编辑部指定术语(house style):Manager 会把这些译法强制写入共享术语表,
# 让所有 Translation Agent 全书统一采用。单 Agent 看不到术语表,无法贯彻。
EDITORIAL_MANDATE = {
    "token": "词元",
    "prompt": "提示词",
    "latency": "时延",
    "embedding": "嵌入向量",
}


def translation_guide(target_lang="中文"):
    """按目标语言生成翻译指南。默认中文,保持与旧行为一致。"""
    return (
        f"翻译指南:面向{target_lang}技术读者,语言流畅自然;保留 Markdown 结构;"
        "代码块内的代码原样保留、不翻译(可保留英文注释);"
        "术语表中出现的术语必须严格使用规定译法;遇到术语表之外的新术语,"
        "先给出你推断的译法,并在其后紧跟标记 [待审] 提示人工复核。"
    )


# 向后兼容:模块级默认(英文→中文)翻译指南,供 Manager 上下文展示等引用。
TRANSLATION_GUIDE = translation_guide("中文")


# Manager 的固定执行计划(供实际运行与 --dry-run 的 Agent 图共用,避免两处漂移)。
ORCHESTRATION_PLAN = [
    "1. 调用 Glossary Agent 生成术语表并落盘",
    "2. 逐章调用 Translation Agent(各自独立上下文,共享术语表文件)",
    "3. 调用 Proofreading Agent 做一致性审校并落盘报告",
    "4. 依据报告决定是否发回个别章节修订",
]


def glossary_agent(client, tracker, book_text, source_lang="英文", target_lang="中文"):
    """
    Glossary Agent:读全书内容,识别反复出现的专业术语,
    输出结构化术语对照表(JSON)。独立上下文,产出后即可释放。
    """
    system = (
        f"你是术语抽取专家。阅读整本{source_lang}技术书,找出反复出现的专业术语,"
        f"为每个术语给出统一的{target_lang}译法。只输出 JSON。"
    )
    user = (
        "请阅读下面全书内容,抽取 6-10 个反复出现的核心专业术语,"
        "输出 JSON,格式为:"
        f'{{"glossary": [{{"en": "{source_lang}术语", "zh": "{target_lang}译法", '
        '"pos": "词性", "context": "该术语在书中的语境说明"}]}。\n\n'
        "全书内容如下:\n\n" + book_text
    )
    messages = [
        {"role": "system", "content": system},
        {"role": "user", "content": user},
    ]
    content = llm_chat(
        client, tracker, "Glossary", messages, json_mode=True, note="抽取术语表"
    )
    data = _loads_lenient(content)
    # 模型偶尔输出 JSON 数组等合法但非对象的 JSON;此时无法取 glossary,按空表处理。
    if not isinstance(data, dict):
        return []
    return data.get("glossary", [])


def translation_agent(client, tracker, chapter_text, glossary, chapter_name,
                      feedback=None, source_lang="英文", target_lang="中文"):
    """
    Translation Agent:接收「当前章节 + 术语表 + 翻译指南」,翻成流畅译文。
    每个实例都是独立上下文(只看到自己这一章 + 术语表,不看到别的章节译文)。

    feedback:可选,Manager 依据审校报告发回的针对本章的修订意见。
    """
    glossary_lines = "\n".join(
        f'- {g["en"]} → {g["zh"]}({g.get("pos","")})' for g in glossary
    )
    system = f"你是专业技术翻译。把{source_lang}章节翻译为流畅、准确的{target_lang}。"
    user = (
        f"{translation_guide(target_lang)}\n\n"
        f"【术语表(必须严格遵守)】\n{glossary_lines}\n\n"
    )
    if feedback:
        user += f"【本章修订意见(请据此修改)】\n{feedback}\n\n"
    user += (
        f"【待翻译章节:{chapter_name}】\n{chapter_text}\n\n"
        f"请直接输出该章节的{target_lang}译文(Markdown),不要额外解释。"
    )
    messages = [
        {"role": "system", "content": system},
        {"role": "user", "content": user},
    ]
    note = f"翻译 {chapter_name}" + ("(修订)" if feedback else "")
    return llm_chat(client, tracker, "Translation", messages, note=note)


def proofreading_agent(client, tracker, translations, glossary, target_lang="中文"):
    """
    Proofreading Agent:接收所有译文 + 术语表,做一致性检查
    (术语是否统一、前后是否矛盾、是否流畅),输出结构化审校报告(JSON)。

    translations:{chapter_name: 译文文本}
    """
    glossary_lines = "\n".join(f'- {g["en"]} → {g["zh"]}' for g in glossary)
    joined = "\n\n".join(
        f"===== {name} =====\n{text}" for name, text in translations.items()
    )
    system = (
        f"你是资深审校。检查多章{target_lang}译文的术语一致性、前后一致性与流畅性。"
        "只输出 JSON。"
    )
    user = (
        f"【术语表】\n{glossary_lines}\n\n"
        f"【全部译文】\n{joined}\n\n"
        "请输出 JSON:"
        '{"issues": [{"chapter": "章节名", "type": "术语不一致/前后矛盾/流畅性", '
        '"detail": "问题描述"}], "chapters_need_revision": ["需要修订的章节名"], '
        '"summary": "总体评价"}'
    )
    messages = [
        {"role": "system", "content": system},
        {"role": "user", "content": user},
    ]
    content = llm_chat(
        client, tracker, "Proofreading", messages, json_mode=True, note="一致性审校"
    )
    return _loads_lenient(content)


def manager_decision(client, tracker, task, file_index, report):
    """
    Manager Agent 的一次真实 LLM 决策调用。

    关键点:Manager 只把「任务 + 文件索引 + 审校报告摘要」这类很小的上下文
    发给模型,用来决定「哪些章节需要发回 Translation Agent 修订」。
    它从不把完整译文放进自己的上下文 —— 这正是控制 Manager 上下文膨胀的做法。
    """
    system = "你是翻译项目的管理者,只做调度决策,输出 JSON。"
    user = (
        f"任务:{task}\n"
        f"文件索引(只存路径,不存正文):{json.dumps(file_index, ensure_ascii=False)}\n"
        f"审校报告摘要:{json.dumps(report, ensure_ascii=False)}\n\n"
        "根据审校报告,决定需要修订的章节。输出 JSON:"
        '{"revise": ["章节名", ...], "reason": "简述"}'
    )
    messages = [
        {"role": "system", "content": system},
        {"role": "user", "content": user},
    ]
    content = llm_chat(
        client, tracker, "Manager", messages, json_mode=True, note="调度决策"
    )
    return _loads_lenient(content)


# ============================================================================
# 运行方式一:管理者模式(Orchestration)
# ============================================================================
def run_orchestration(chapters, out_dir, *, source_lang="英文", target_lang="中文",
                      enable_glossary=True, enable_proofreading=True, trace=None):
    """
    chapters:{chapter_name: 原文} 的有序字典
    out_dir:产物目录(术语表、各章译文、审校报告都写到这里)

    可选参数:
      source_lang / target_lang:源语言 / 目标语言(默认 英文 → 中文,与旧行为一致)。
      enable_glossary:是否启用 Glossary Agent 抽取术语表(关闭后仅保留编辑部指定术语)。
      enable_proofreading:是否启用 Proofreading Agent + Manager 修订闭环。
      trace:可选回调 trace(str),用于打印四 Agent 协作的实时轨迹。

    返回:metrics 字典,含 tracker、manager 上下文峰值、译文映射等。
    """
    os.makedirs(out_dir, exist_ok=True)
    client = get_client()
    tracker = TokenTracker()
    emit = trace if callable(trace) else (lambda *a, **k: None)

    # ---- Manager 的上下文:只保存这些“轻量”信息,绝不含完整译文 ----
    manager_context = {
        "task": f"把一本{source_lang}技术小书翻译成流畅{target_lang},保证术语全书一致。",
        "guide": translation_guide(target_lang),
        "plan": list(ORCHESTRATION_PLAN),
        "call_log": [],       # 各 Agent 调用记录(只记摘要,不记正文)
        "file_index": {},     # 文件索引:只存路径
        "progress": {},       # 进度状态
    }
    manager_peak = 0  # Manager 上下文(其状态序列化后的)token 峰值

    def snapshot_manager():
        nonlocal manager_peak
        size = count_tokens(json.dumps(manager_context, ensure_ascii=False))
        manager_peak = max(manager_peak, size)
        return size

    def log_call(agent, note, out_file, prompt_tokens, completion_tokens):
        # Manager 只记录“谁做了什么、产物在哪、花了多少 token”,不记录正文
        manager_context["call_log"].append(
            {
                "agent": agent,
                "note": note,
                "output": out_file,
                "prompt_tokens": prompt_tokens,
                "completion_tokens": completion_tokens,
            }
        )
        snapshot_manager()

    snapshot_manager()
    emit("Manager:制定计划并调度四个专职 Agent(各自独立上下文)")
    for step in manager_context["plan"]:
        emit(f"    计划 {step}")

    # ---- 步骤 1:Glossary Agent(独立上下文,读全书;产出后释放)----
    book_text = "\n\n".join(f"# {n}\n{t}" for n, t in chapters.items())
    if enable_glossary:
        emit(f"Manager → Glossary Agent:读全书({len(chapters)} 章)抽取共享术语表")
        glossary = glossary_agent(client, tracker, book_text, source_lang, target_lang)
    else:
        emit("Manager:已跳过 Glossary Agent(--no-glossary),仅保留编辑部指定术语")
        glossary = []
    # 归一化:模型偶尔返回不合规条目(如 {"term": ...} 而非 {"en"/"zh": ...},
    # 或显式 null),直接丢弃,避免后续 g["en"] / g["zh"] 索引让整轮运行崩溃。
    glossary = [
        g for g in glossary
        if isinstance(g, dict)
        and isinstance(g.get("en"), str) and g["en"].strip()
        and isinstance(g.get("zh"), str) and g["zh"].strip()
    ]
    # Manager 把“编辑部指定术语”强制写入术语表(覆盖或新增),作为全书统一契约。
    for g in glossary:
        en = g["en"].strip().lower()
        if en in EDITORIAL_MANDATE:
            g["zh"] = EDITORIAL_MANDATE[en]
    present = {g["en"].strip().lower() for g in glossary}
    for en, zh in EDITORIAL_MANDATE.items():
        if en not in present:
            glossary.append({"en": en, "zh": zh, "pos": "名词", "context": "编辑部指定术语"})
    glossary_path = os.path.join(out_dir, "glossary.json")
    with open(glossary_path, "w", encoding="utf-8") as f:
        json.dump(glossary, f, ensure_ascii=False, indent=2)
    # Manager 只在文件索引里记路径;术语表正文留在文件系统,不进 Manager 上下文
    manager_context["file_index"]["glossary"] = glossary_path
    # 仅在真正调用了 Glossary Agent 时才有 LLM usage 可记账;--no-glossary 时无调用。
    g_prompt, g_completion = (
        (tracker.calls[-1]["prompt_tokens"], tracker.calls[-1]["completion_tokens"])
        if enable_glossary and tracker.calls else (0, 0)
    )
    log_call("Glossary", f"抽取 {len(glossary)} 个术语", glossary_path,
             g_prompt, g_completion)
    if enable_glossary:
        emit(f"Glossary Agent ✓:确定 {len(glossary)} 个术语 → {os.path.basename(glossary_path)}"
             f"(Manager 只记路径,术语表正文留在文件系统)")
    else:
        emit(f"Manager:写入 {len(glossary)} 个编辑部指定术语 → {os.path.basename(glossary_path)}")

    # ---- 步骤 2:逐章 Translation Agent(每章一个独立上下文实例)----
    translations = {}
    for name, text in chapters.items():
        emit(f"Manager → Translation Agent:翻译《{name}》(独立上下文,仅见本章 + 术语表)")
        zh = translation_agent(client, tracker, text, glossary, name,
                               source_lang=source_lang, target_lang=target_lang)
        # 文件名如 chapter1_zh.md
        base = _slug(name)
        out_file = os.path.join(out_dir, f"{base}_zh.md")
        with open(out_file, "w", encoding="utf-8") as f:
            f.write(zh)
        translations[name] = zh
        manager_context["file_index"][name] = out_file
        manager_context["progress"][name] = "translated"
        last = tracker.calls[-1]
        log_call("Translation", f"翻译 {name}", out_file,
                 last["prompt_tokens"], last["completion_tokens"])
        emit(f"Translation Agent ✓:{os.path.basename(out_file)}"
             f"(上下文 {last['prompt_tokens']} tok,译文落盘不回传 Manager)")

    # ---- 步骤 3:Proofreading Agent(读所有译文 + 术语表,独立上下文)----
    if not enable_proofreading:
        emit("Manager:已跳过 Proofreading Agent 与修订闭环(--no-proofreading)")
        report = {"issues": [], "chapters_need_revision": [],
                  "summary": "(已跳过审校)"}
        snapshot_manager()
        return {
            "mode": "orchestration",
            "tracker": tracker,
            "manager_context_peak": manager_peak,
            "manager_context_final": manager_context,
            "glossary": glossary,
            "translations": translations,
            "report": report,
            "out_dir": out_dir,
        }

    emit("Manager → Proofreading Agent:读全部译文 + 术语表做一致性/流畅性审校")
    report = proofreading_agent(client, tracker, translations, glossary, target_lang)
    report_path = os.path.join(out_dir, "proofreading_report.json")
    with open(report_path, "w", encoding="utf-8") as f:
        json.dump(report, f, ensure_ascii=False, indent=2)
    manager_context["file_index"]["report"] = report_path
    last = tracker.calls[-1]
    log_call("Proofreading", "一致性审校", report_path,
             last["prompt_tokens"], last["completion_tokens"])
    emit(f"Proofreading Agent ✓:{len(_report_issues(report))} 处问题 → "
         f"{os.path.basename(report_path)}")

    # ---- 步骤 4:Manager 决策 + 至多一轮修订 ----
    # Manager 只把“文件索引 + 报告摘要”这类小上下文发给模型做决策
    report_summary = {
        "chapters_need_revision": report.get("chapters_need_revision", []) or [],
        "issues": _report_issues(report)[:5],
        "summary": report.get("summary", ""),
    }
    manager_context["progress"]["proofread"] = "done"
    snapshot_manager()

    emit("Manager:读审校报告摘要(不读正文)→ 决策哪些章节需发回修订")
    decision = manager_decision(
        client, tracker, manager_context["task"],
        manager_context["file_index"], report_summary
    )
    revise = decision.get("revise", [])
    emit(f"Manager 决策 ✓:需修订章节 {revise or '无'}")

    for name in revise:
        if name not in chapters:
            continue
        # 找到该章节的修订意见
        fb = "; ".join(
            i.get("detail", "") for i in _report_issues(report)
            if i.get("chapter") == name
        ) or "请根据术语表统一术语并提升流畅性。"
        emit(f"Manager → Translation Agent:修订《{name}》(附审校意见)")
        zh = translation_agent(client, tracker, chapters[name], glossary, name,
                               feedback=fb, source_lang=source_lang, target_lang=target_lang)
        base = _slug(name)
        out_file = os.path.join(out_dir, f"{base}_zh.md")
        with open(out_file, "w", encoding="utf-8") as f:
            f.write(zh)
        translations[name] = zh
        manager_context["progress"][name] = "revised"
        last = tracker.calls[-1]
        log_call("Translation", f"修订 {name}", out_file,
                 last["prompt_tokens"], last["completion_tokens"])

    snapshot_manager()
    emit(f"Manager:全部完成,产物目录 {out_dir}")

    return {
        "mode": "orchestration",
        "tracker": tracker,
        "manager_context_peak": manager_peak,
        "manager_context_final": manager_context,
        "glossary": glossary,
        "translations": translations,
        "report": report,
        "out_dir": out_dir,
    }


# ============================================================================
# 运行方式二:单 Agent 模式(对照组)
# ============================================================================
def run_single_agent(chapters, out_dir, *, source_lang="英文", target_lang="中文"):
    """
    朴素基线:一个 Agent 在同一条不断增长的对话里,先粗读全书,
    再逐章翻译。没有独立的术语表工具来“钉死”术语,且上下文随章节累积。

    这一模式用于暴露两个问题:
      - 上下文膨胀:单条对话的上下文峰值 = 累积到最后一章时的全部内容;
      - 术语漂移:缺少共享术语表约束,同一术语在不同章可能译法不一致。
    """
    os.makedirs(out_dir, exist_ok=True)
    client = get_client()
    tracker = TokenTracker()

    system = (
        f"你是专业技术翻译。我会逐章给你一本{source_lang}技术书,请把每一章翻译成"
        f"流畅、准确的{target_lang}。保留 Markdown 结构;代码块内的代码原样保留、不翻译。"
    )
    # 单 Agent 的“主上下文”:一条持续增长的对话
    messages = [{"role": "system", "content": system}]

    translations = {}
    for name, text in chapters.items():
        messages.append(
            {
                "role": "user",
                "content": f"请翻译下面这一章,直接输出中文译文:\n\n# {name}\n{text}",
            }
        )
        content = llm_chat(
            client, tracker, "SingleAgent", messages, note=f"翻译 {name}"
        )
        # 译文继续留在对话里 —— 这正是上下文膨胀的来源
        messages.append({"role": "assistant", "content": content})
        translations[name] = content
        base = _slug(name)
        out_file = os.path.join(out_dir, f"{base}_zh.md")
        with open(out_file, "w", encoding="utf-8") as f:
            f.write(content)

    return {
        "mode": "single_agent",
        "tracker": tracker,
        # 单 Agent 的“主上下文峰值”= 其所有调用中最大的一次 prompt_tokens
        "main_context_peak": tracker.by_agent()["SingleAgent"]["peak_context"],
        "translations": translations,
        "out_dir": out_dir,
    }