从一轮游戏决策看懂整个项目

这张图按真实执行顺序组织。点任意组件，右侧会显示职责、源码、输入输出和上下游关系。

打开形象化演示页作者主页 offline-first ports & adapters contract-first real game I/O deferred

读图顺序：CLI 选择 suite 和后端模式，BenchmarkHarness 按 case 类型组织阶段，ToolRegistry 统一执行工具并记录 trace，工具背后通过 port 接 mock 或 real client，DotPlanner 负责任务分解和 DAG 执行，最后 scorer/report 生成可复现实验产物。

一次 planning case 的运行时间线

以 `plan_qing_budget_001` 为例，它不是问模型“你觉得怎么办”，而是用固定快照、固定期望和固定 scorer 验证架构动作。

Bench 样例是怎样提前设计的

一个合格样例必须写清输入、期望动作、禁用边界、失败原因和判分条件。这样测试的是架构能力，不是临场印象。

游戏快照 StateSnapshot

离线替代真实游戏 I/O。它告诉 Agent 当前国家、财政、政治、市场短缺和可用动作。

{
  "country": "Qing",
  "budget": {"weekly_balance": -20000},
  "politics": {"radicals": 1200000},
  "market": {"shortages": ["tools", "coal"]},
  "available_actions": ["reduce_construction", "build_tools_workshop", "build_coal_mine", "raise_tax"]
}

Case 预期

测试作者提前规定要覆盖什么动作、不能做什么动作、理由里必须解释什么。

{
  "goal": "稳定财政，同时不要继续增加激进派",
  "expected_actions": ["reduce_construction", "build_tools_workshop", "build_coal_mine"],
  "forbidden_actions": ["raise_tax"],
  "expected_reasons": ["deficit", "radicals", "tools shortage", "coal shortage"]
}

Scorer 判分

不是只看文字顺不顺，而是结构化判定动作覆盖、禁用动作、合法性和理由匹配。

passed =
  schema_valid
  && action_legality_rate == 1.0
  && !forbidden_action_violation
  && coverage == 1.0
  && reasons_ok

高级视图：从组件图上升到工程架构

这一层说明系统为什么这样拆：不稳定的 AI 和外部服务都被包进 contract，默认路径始终离线、确定、可复现。

入口层

run_benchmark.pycompare_routers.pyCLI flags

编排层

BenchmarkHarnessper-case phasesRunContextTraceRecorder

工具层

game toolsrag toolsmemory toolsdot toolBaseTool validation

端口层

GameAdapterGraphRAGClientGraphitiClientDotPlannerModelClientRouterToolExecutor

实现层

MockVic3AdapterMockGraphRAGMockGraphitiFakeModelMCP clientsCompositeModel

产物层

cases.jsonltraces/*.jsonsummary.jsonrouter_comparison

DoT / DAG 视角

decompose：把目标拆成子任务。
dependency：生成依赖边，必须是 DAG。
route：每个子任务走 SLM 或 LLM。
execute：SLM 串行，LLM 并发。
synthesize：合成 ActionPlan。
enforce：丢弃 forbidden / unavailable action。

安全边界视角

模型只提出计划，不直接操作游戏。
工具输入输出都过 Pydantic contract。
Dot 子任务只能调用只读白名单工具。
最终动作必须通过 verify_plan。
真实后端必须显式 opt-in，不 silent fallback。

评估视角

smoke：证明主循环可跑，含故意失败样例。
smoke_dot：证明真实 DotPlanner 离线可复现。
router comparison：同一 suite 比较路由策略。
acceptance：证明 deterministic rerun byte-identical。

源码地图：组件如何对应文件

下面这张表用于定位代码，也用于说明这个项目不是单脚本堆叠，而是按模块边界拆开的 runtime。

组件	核心文件	输入	输出	它证明的工程能力

展示路径

项目说明从“为什么先做 benchmark”开始，再进入组件、数据流、测试方法和当前边界。

一句话版本：我没有直接把 LLM 接到真实游戏上，而是先建立了一个离线可复现的 Agent 主循环验证系统。它用静态游戏快照替代真实 I/O，用 GraphRAG、Graphiti、DoT DAG、SLM/LLM routing 组成完整闭环，并通过 deterministic traces 和 scorers 证明每个模块的行为。

1. 问题边界真实游戏 I/O 暂缓，先验证 Agent 主循环是否可测试、可替换、可解释。

2. 物理组件CLI、Harness、Registry、Tools、Ports、Clients、Planner、Scorers、Reports。

3. 数据流state snapshot → RAG → memory → DotPlanner → verify → memory write → report。

4. 测试方法case 预先定义输入/期望/禁用动作，scorer 结构化判分，trace 可复盘。

5. 诚实边界已完成 benchmark 底座；真实游戏控制、长期在线策略优化属于下一阶段。