Token Overload

让强模型只动嘴，弱模型干所有脏活。 强模型负责规划和验收，弱模型负责读文件、写代码、跑测试、试错—— 用机器验证自动兜底，强模型 token 省约 60%，总成本省约 70%。

编程任务里，读文件、写代码、跑命令、试错占了 80%+ 的 token 消耗，而这些活弱模型完全干得了（价格差 ~16x）。Token Overload 把这部分全部转移给弱模型，强模型只做两件高杠杆的事：规划（把目标变成结构化任务卡）和验收（看摘要判断 pass/rework）。中间用程序自动验证（跑测试、查 scope），测试通过就自动放行，强模型一次都不用出场。

export OPENAI_API_KEY=sk-xxx
python -m orchestrator "fix the divide-by-zero bug in src/calc.py"
# 强模型规划 → 弱模型改代码 → 自动跑测试 → 通过则 0 token 验收

凭什么省 token

机制	效果
验证通过自动 pass	测试全过就跳过强模型 review，0 token
弱模型承担试错	改错了→rework→弱模型重试，强模型只花 ~0.5k 说"不行"
`--scope` 跳过 planner	用户指定文件范围，省 1 次强模型调用
MCP 模式强模型自己 plan	Agent 在对话里直接写 TaskCard，不额外调 API
diff 摘要化	review 时只给文件列表和行数，不给完整 diff
连续失败才 revise	第 1 次 rework 只喂反馈，不调强模型重新规划

一句话原则：

用程序把强模型的判断力翻译成弱模型可执行的结构化任务；再用机器验证和强模型验收，把弱模型的低成本试错变成可控产能。

架构

Orchestrator 是纯代码，0 token 消耗。 它不读文件、不写代码、不跑命令——只做调度：plan → delegate → validate → review → decide。强模型（Planner/Reviewer/Escalator）只做高杠杆判断，弱模型（Worker Session）承担全部执行型试错。

flowchart LR
    U["用户任务"] --> O["Orchestrator<br/>纯代码 · 0 token"]
    O -->|plan / review / escalate| P["强模型<br/>Planner · Reviewer · Escalator"]
    O -->|assign / feed events| W["弱模型<br/>Worker Session"]
    O --> V["Validator<br/>测试 + scope 检查"]
    O --> E["Executor<br/>跑命令 / 应用 patch"]
    P -.->|TaskCard / 验收决策| O
    W -.->|tool_request / patch| O
    V -.->|pass / fail| O
    E -.->|diff / 输出| O

Worker 是可插拔的，三种后端共用同一套调度逻辑：

flowchart TD
    O["Orchestrator"] --> WB["WorkerBackend<br/>(抽象接口)"]
    WB --> B["BuiltinWorker<br/>内置弱模型，orchestrator 代执行工具"]
    WB --> X["ExternalAgentWorker<br/>外部 Agent (Cline / OpenCode / Claude Code)"]
    WB --> M["MCP Server<br/>强模型 Agent 当调度者，弱模型内部干活"]

主状态机

Orchestrator 是一个状态机，核心是 validate 通过则 auto-pass、失败才进 review 的省 token 回路：

stateDiagram-v2
    [*] --> PLAN_READY: planner 生成 TaskCard
    PLAN_READY --> WORKER_RUNNING: 派给 worker
    WORKER_RUNNING --> VALIDATING: worker 提交 patch
    VALIDATING --> DONE: 验证通过 (auto-pass, 0 token)
    VALIDATING --> REVIEWING: 验证失败 / 结果模糊
    REVIEWING --> DONE: reviewer pass
    REVIEWING --> WORKER_RUNNING: rework (回喂同一 session)
    REVIEWING --> ESCALATED: 超出弱模型能力
    WORKER_RUNNING --> FAILED: 预算耗尽
    DONE --> [*]
    ESCALATED --> [*]
    FAILED --> [*]

明显的失败（语法错误、import 错误、scope 越界）会 auto-rework，连强模型 review 都跳过，直接回喂弱模型。只有结果模糊时才动用强模型判断。

Worker Session：弱模型是会话，不是一次调用

关键设计：弱模型不是「一次 complete() 吐 patch」，而是一个带状态的持续会话——会先汇报计划、请求读文件/跑命令、提交 patch、根据测试报错继续修，rework 时回到同一个 session 而不是重开。这样它保留了已读上下文和失败经验，返工更省 token。

stateDiagram-v2
    [*] --> Created
    Created --> Running: 分配 TaskCard
    Running --> WaitingTool: 请求读文件 / 跑命令
    WaitingTool --> Running: 工具结果回传
    Running --> PatchProposed: 提交 patch_ready
    PatchProposed --> Validating: 应用 patch 并验证
    Validating --> Running: 验证失败，继续返工
    Validating --> ReviewPending: 验证完成
    ReviewPending --> Running: reviewer 要求 rework
    ReviewPending --> Completed: reviewer pass
    ReviewPending --> Escalated: reviewer escalate
    Running --> Blocked: worker 主动 report_blocked
    Completed --> [*]
    Escalated --> [*]

弱模型每轮只输出四种结构化 JSON 之一——status_update（汇报计划）、tool_request（读文件/跑命令/搜代码）、patch_ready（提交完整文件）、blocked（卡住）。所有命令受白名单限制，所有 patch 只能改 scope_files。

一条真实返工回路

sequenceDiagram
    participant K as 强模型 (Reviewer)
    participant O as Orchestrator
    participant W as Worker Session (弱模型)
    participant V as Validator

    O->>W: 注入 TaskCard + 初始上下文
    W->>O: tool_request 读文件
    O->>W: 返回文件内容
    W->>O: patch_ready 提交修改
    O->>V: 应用 patch + 跑 acceptance_commands
    V-->>O: 验证失败 (测试不过)
    O->>W: auto-rework：回喂报错（不动强模型）
    W->>O: 再次 patch_ready
    O->>V: 重新验证
    V-->>O: 通过 ✓
    O-->>O: auto-pass，强模型 0 token
    Note over K: 仅当验证模糊时才出场

三种 Worker 模式

三种模式的核心目标一致：把强模型的 token 消耗降到最低。 强模型只做规划和验收，执行全部转移出去。

1. Builtin（默认）

全自动，零依赖。Orchestrator 调强模型 API 做 plan/review，内置弱模型做执行。弱模型只能输出 JSON 指令（读文件、跑命令、改代码），Orchestrator 代为执行。

省 token 方式：读文件、写代码、跑命令、试错全是弱模型（价格差 ~16x），强模型只在 plan 和 review 时出场。验证通过自动跳过 review。

python -m orchestrator "fix the login bug"

2. External Agent（指挥另一个 Agent）

主 agent（Kiro/Codex）指挥另一个完整 agent（opencode/claude code）当苦力。外部 agent 有自己的完整能力——读写文件、跑命令、多轮推理、自主试错，不需要任何人代执行。

省 token 方式：强模型只做两件事——写 TaskCard（规划）和看 git diff（验收）。中间所有吃力的活（理解代码、写代码、调试、试错）全是外部 agent 在干，强模型完全不参与。

python -m orchestrator --worker-mode external \
  --agent-cmd "opencode --task {task_file}" \
  "fix the login bug"

工作流程：

Orchestrator 生成 task_card.json 写到 .orchestrator/<task_id>/
启动外部 agent 子进程（{task_file} 和 {repo_root} 会被替换）
外部 agent 自己读 task card、改代码、干完退出
Orchestrator 检查 git diff，跑验证，决定 pass/rework
如果 rework，写 rework_feedback.json，重新启动 agent

3. MCP Server（强模型驾驶模式）

强模型 Agent（如 Kiro/Claude Code）通过 MCP 协议当调度者，弱模型在 server 内部自动干活。弱模型只能输出 JSON 指令，由 server 代为执行。

省 token 方式：强模型 Agent 自己做 plan 和 review（在对话中完成，不额外调 API），执行 token 全部转移给弱模型。最优情况下强模型 API 调用为 0。

# 启动 MCP server（只需弱模型配置）
python -m orchestrator --worker-mode mcp --mcp-port 9999

# 强模型 Agent 连接 http://localhost:9999/mcp
# 可用 tools:
#   start_task(goal, repo_root, scope_files?, acceptance_commands?)
#                             → 派任务，弱模型自动开始干活
#   start_task_with_card(json)→ 用自定义 TaskCard 精准控制
#   get_status()              → 查看进度（worker_running/waiting_review/done）
#   get_task()                → 查看当前 TaskCard
#   get_result()              → 拿弱模型产出（diff + validation）
#   review_pass()             → 验收通过
#   review_rework(must_fix)   → 打回重做，弱模型自动重试
#   get_feedback()            → 查看当前结果（兼容接口）

工作流程：

强模型 Agent 调 start_task() 或 start_task_with_card() 派任务
弱模型在 server 内部自动读文件、改代码、提交 patch
Validator 自动跑 acceptance_commands + scope 检查
状态变为 waiting_review，强模型 Agent 调 get_result() 查看产出
强模型 Agent 决定 review_pass() 或 review_rework(feedback)
如果 rework，弱模型自动重试

怎么选：

不装任何 agent，全自动       → Builtin 模式（默认）
有主 agent，想精细控制弱模型  → MCP 模式
有主 agent，想指挥另一个 agent → External 模式

省 Token 分析

省在哪

省的是强模型的"执行 token"。 编程任务中，读文件、写代码、跑命令、试错占了 80%+ 的 token 消耗。这些全部转移给弱模型（价格差 ~16x）。

强模型只负责：

规划：生成 TaskCard（1 次调用，~2k tokens）
验收：review 弱模型产出（0~1 次调用，看 validation 是否通过）

具体省 token 的机制见上文凭什么省 token。

什么时候省得多

任务需要多轮试错 — 弱模型试错 3 轮 ≈ 强模型试错 1 轮的成本
有 acceptance_commands — auto-pass 生效，强模型 review 完全跳过
批量任务 — 10 个任务并行，强模型只做 10 次轻量决策
MCP 模式 — 强模型 Agent 自己做 plan/review，不调 API，执行 token 全转移

什么时候不省

简单任务（改一行代码）— MCP 交互的 overhead 可能比直接改还多
弱模型能力不够 — 改不对就白花了弱模型 token，最后还得强模型接手

诚实的对比

以"给一个文件加 3 个方法"为例：

	强模型直接干	用本系统（MCP 模式）
读文件	~1k 强模型 tokens	0（弱模型干）
写代码	~2k 强模型 tokens	0（弱模型干）
跑测试	~0.5k 强模型 tokens	0（弱模型干）
规划	0（直接开干）	~0.5k 强模型 tokens（写 TaskCard）
验收	0（自己看）	~1k 强模型 tokens（看 get_result）
合计强模型	~3.5k	~1.5k
弱模型	0	~8k（≈ 0.5k 强模型等价成本）

强模型 token 省了约 60%，总成本省了约 70%。 任务越复杂、试错越多，省得越多。

快速开始

export OPENAI_API_KEY=sk-xxx

# 最简用法（Builtin 模式）
python -m orchestrator "给登录页增加 loading 和错误提示"

# 指定模型
python -m orchestrator --strong-model gpt-4o --weak-model gpt-4o-mini "add tests"

# 跳过 planner（省 token）
python -m orchestrator --scope src/login.tsx -- "fix the loading state"

# 外部 Agent 模式
python -m orchestrator --worker-mode external \
  --agent-cmd "opencode --task {task_file}" \
  "fix the login bug"

# MCP Server 模式（强模型 Agent 驾驶）
python -m orchestrator --worker-mode mcp --mcp-port 9999

# 从中断恢复
python -m orchestrator --resume task_abc123

MCP 模式接入

启动 server：

python -m orchestrator --worker-mode mcp --mcp-port 9999

在你的 IDE Agent 中配置 MCP server：

{
  "mcpServers": {
    "orchestrator": {
      "url": "http://localhost:9999/mcp"
    }
  }
}

Agent 通过 MCP tool 调度：

start_task(goal="fix the bug", repo_root="/path/to/repo", scope_files="src/app.py")
→ 弱模型自动干活
get_status() → "waiting_review"
get_result() → 看 diff 和 validation
review_pass() → 完成

配置

支持三层配置，优先级：CLI 参数 > 环境变量 > .orchestrator.yaml > 默认值。

在项目根目录创建 .orchestrator.yaml：

strong:
  model: gpt-4o
  api_key: sk-xxx
  base_url: ""
weak:
  model: gpt-4o-mini
  api_key: sk-xxx
  base_url: ""
max_worker_rounds: 6
max_review_rounds: 3

MCP 模式只需要弱模型配置（强模型是连进来的 Agent 自己）。

模块说明

文件	职责
`app.py`	项目经理：plan → delegate → validate → review
`worker_backend.py`	Worker 抽象接口
`builtin_worker.py`	内置弱模型 worker
`external_worker.py`	外部 Agent worker
`mcp_server.py`	MCP Server：暴露 orchestrator tool 给强模型 Agent，内置弱模型 worker
`worker_session.py`	弱模型多轮会话封装
`schemas.py`	所有数据模型
`planner.py`	强模型生成 TaskCard
`reviewer.py`	强模型验收
`validator.py`	自动验证（scope check + acceptance commands）
`policy.py`	白名单、预算、权限
`executor.py`	Shell 命令执行
`context_builder.py`	上下文裁剪
`state_store.py`	持久化
`config.py`	配置加载
`adapters/`	模型接入层（OpenAI / Anthropic）
`prompts/`	System prompts

测试

# 全量测试（53 个）
python -m pytest tests/ -v

# 单元测试（40 个）
python -m pytest tests/test_unit.py -v

# 集成测试（13 个）
python -m pytest tests/test_integration.py -v

接入其他 Agent

import asyncio
from orchestrator.app import Orchestrator
from orchestrator.adapters.openai_adapter import OpenAIAdapter
from orchestrator.builtin_worker import BuiltinWorker
from orchestrator.state_store import StateStore
from orchestrator.schemas import UserTask

strong = OpenAIAdapter("gpt-4o", api_key="sk-xxx")
weak = OpenAIAdapter("gpt-4o-mini", api_key="sk-xxx")
task = UserTask(user_goal="fix the bug", repo_root="/path/to/repo")
store = StateStore(task.repo_root, task.id)
worker = BuiltinWorker(weak, store, task.budget)

orch = Orchestrator(strong, worker, task)
state = asyncio.run(orch.run())
print(state.status)  # done / failed / escalated

依赖

Python >= 3.11
openai >= 1.0.0
pyyaml >= 6.0
fastmcp >= 3.0.0（MCP 模式）

深入设计

完整的架构推理、数据模型、prompt 体系和 worker session 持久化机制：

强带弱编程调度系统设计 — 系统边界、角色划分、主循环、上下文裁剪、成本控制
Worker Session 持久化与返工机制 — 弱模型会话化、返工注入、状态恢复

License

MIT © ladydd

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
docs		docs
orchestrator		orchestrator
src		src
tests		tests
.gitignore		.gitignore
.orchestrator.yaml.example		.orchestrator.yaml.example
LICENSE		LICENSE
README.md		README.md
TODO.md		TODO.md
pyproject.toml		pyproject.toml

Navigation Menu

Repository files navigation

Token Overload

凭什么省 token

架构

主状态机

Worker Session：弱模型是会话，不是一次调用

一条真实返工回路

三种 Worker 模式

1. Builtin（默认）

2. External Agent（指挥另一个 Agent）

3. MCP Server（强模型驾驶模式）

省 Token 分析

省在哪

什么时候省得多

什么时候不省

诚实的对比

快速开始

MCP 模式接入

配置

模块说明

测试

接入其他 Agent

依赖

深入设计

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Token Overload

凭什么省 token

架构

主状态机

Worker Session：弱模型是会话，不是一次调用

一条真实返工回路

三种 Worker 模式

1. Builtin（默认）

2. External Agent（指挥另一个 Agent）

3. MCP Server（强模型驾驶模式）

省 Token 分析

省在哪

什么时候省得多

什么时候不省

诚实的对比

快速开始

MCP 模式接入

配置

模块说明

测试

接入其他 Agent

依赖

深入设计

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages