docs: 建立 Agent 三层选型的需求审计与验证基线

[JoshuaZ16]

背景与纠偏

本 PR 用于建立主持编排 Agent 的三层技术选型基线，目前不在三个候选中做出最终决定。

Issue #86 中“先用普通 Python、后续再考虑 LangGraph”是 2026-07-20 上午基于两方案实验形成的阶段性路线。前一版 PR 错误地把它提升成了最终决定；本次已撤回该结论。加入供应商 Agent Runtime 候选后，现有普通 Python / LangGraph 双方案实验不足以支撑三选一。

当前代码需求审计

以仓库当前主持主链为证据：

• IntentModelPort.generate() 固定调用一次；
• Intent 校验后，应用编排无条件调用 ActionExecutor.execute() 恰好一次；
• NarrationModelPort.generate() 固定调用一次；
• 生产代码没有工具 schema、tool_calls、ToolMessage 回填或工具循环；
• 当前没有审核 Agent、动态路由或 fan-out/fan-in。

因此当前已实现代码中：

• 模型工具调用：0；
• 多轮工具调用：0；
• ActionExecutor.execute() 是确定性应用端口调用，不是模型自主选择的 tool call。

“玩家动作可以概念化为工具”适合指导接口设计，但不能替代对运行时工具需求的审计。

已知后续方向包含网络搜索，但其调用形态还没有定义：应用固定搜索不构成模型工具循环；模型自主决定是否搜索才是工具调用；search → fetch → refine/cite 才可能形成多轮工具调用。这部分必须先形成验收用例，再参与三方案权重判断。

三个候选层次

1. 供应商 Agent Runtime：OpenAI Agents SDK、Anthropic tool runner 等；
2. 显式 Python 编排：基础模型 SDK + 自己维护消息、工具执行和循环；
3. LangGraph：图状态、条件路由、循环、并行、checkpoint 和 interrupt。

选择依据不是“能否流式输出”，而是项目确认需要：

• 模型是否自主选择工具；
• 是否存在多轮工具调用；
• 是否需要工具执行前审核；
• 是否需要动态路由、fan-out/fan-in、暂停与恢复；
• Qwen / 多供应商兼容要求与 tracing 数据边界。

已有实验能证明什么

现有两个独立、业务无关项目已经证明：

• 普通 Python 和 LangGraph 都能实现流式工具 Agent；
• 工具调用流不能只转发文本 token，需要 TextDelta、ToolCall、ToolResult、Completed 等结构化事件；
• 普通 Python 生产代码 324 SLOC，LangGraph 生态实现 201 SLOC；Agent + 工具主体分别为 234 / 115 SLOC；
• 实测三轮端到端均值为 2.49 / 3.14 秒，但样本量与执行顺序不足以分离公网、模型推理和框架开销，不能解释为纯编排性能差；
• 普通 Python 依赖面更小，LangGraph 减少了工具 schema 与循环样板代码。

这些数据不能证明当前项目应继续普通 Python、改用 LangGraph，或供应商 Runtime 是否更合适，因为第三个方案尚未在同条件下实现和测量。

本次修改

• 将技术选型文档状态改为 proposal / 决策未定；
• 增加当前代码的工具调用与多轮工具调用审计；
• 将双方案复杂度报告降级为局部证据，删除其选型建议；
• 增加三方案同条件评估计划，覆盖：
  • S0 无工具结构化输出；
  • S1 单轮工具调用；
  • S2 连续两轮以上工具调用；
  • S3 非法参数、未知工具、超时与循环上限；
  • 仅在需求确认后纳入审核 Agent 和 fan-out/fan-in；
• 规定只有完成工具清单、轮数/拓扑需求和供应商 Runtime 实验后，才能另写 ADR 做最终决定。

不变的架构边界

• ActionExecutor.execute() 仍是唯一权威命令边界；
• 框架仅拥有成员 A 内部编排状态；
• 对外使用框架无关的结构化流事件；
• 不输出原始 reasoning、未验证 token 或内部 ToolMessage；
• 不假定 Qwen 的 OpenAI-compatible Chat Completions 一定兼容 OpenAI Agents SDK。

验证

• 文档相对链接、代码围栏与 git diff --check 通过；
• tests.test_architecture：9/9 通过；
• plain-python-tool-agent：3/3 通过；
• langgraph-tool-agent：1/1 通过。

关联 #86；本 PR 保持 Draft，合并前还需确认近期工具需求并补齐供应商 Runtime 的同条件实验。