它做什么
theseus 在 同一任务子集 上运行 模型(L0) × 智能体(L1) × 框架(L2) 的各种组合,并把每个组合的 准确率 · 成本 · 时间 · 工具调用 · 子智能体调用流 并排呈现 —— 让你看懂流程,挑选 适合你的权衡。 它 不是 排行榜,默认 不产出单一分数;而是给出按视角的最优,并标出成本/准确率的 帕累托前沿(Pareto frontier)。
flowchart LR
S(["<b>选择</b><br/>模型 × 智能体 × 框架"]):::pick
S --> SUB["<b>子集</b><br/>确定性 · seed"]:::step
SUB --> J["<b>运行作业</b><br/>组合 × 任务 · fail-soft"]:::step
J --> RM["<b>结果 + 指标</b><br/>准确率 · 成本 · 时间 · 流程"]:::step
RM --> V(["<b>可视化</b><br/>report · graph · TUI · view"]):::out
V -. "调整选择后再次运行" .-> S
classDef pick fill:#cdd2d8,stroke:#0a0b0d,color:#0a0b0d;
classDef step fill:#15171b,stroke:#8b929b,color:#eef0f2;
classDef out fill:#1d2b33,stroke:#cdd2d8,color:#eef0f2;
每次运行产出:结构化数据(results.jsonl + 可选 theseus.sqlite)、自包含(self‑contained) 的
report.html(无外部 JS/CDN)、以及子智能体 流程图 graph.html。
名字 —— 一艘船,与一次判断
theseus 取自 忒修斯之船:逐块更换木板,船依旧是那艘船。 你的工作流就是这艘船,模型、智能体、框架就是可替换的木板。theseus 让你看清哪块木板真正改变了航程。
它的目的在于 判断(judgment):不替你封王,而是把证据(准确率、成本、时间、流程)交给你,由 你 权衡并自行裁断。这一精神源自正义与裁判的化身 狄刻(Δίκη, Díkē)—— theseus 是工具,判断在你。
在线演示画廊
自包含的示例报告 + 流程图,每次推送到 main 时由 CI 重新生成。
- 托管: https://olympusresearch.github.io/theseus/ (需维护者启用 Pages —— 见下)
- 本地打开(无需联网):
npm run build:site # 生成 ./site (index.html + report.html + graph.html) open site/index.html # macOS · Linux: xdg-open · Windows: start - 从你自己的运行结果:
# 记录一次运行并在浏览器中打开其报告 theseus --model opus4.8 --agent cc --harness none,omc --bench subagent --runner mock --view open # 记录一次运行并在 http://localhost:7777 提供全部运行 theseus --model opus4.8 --agent cc --harness none,omc --bench subagent --runner mock --view serve --port 7777 - 查看已记录的全部轨迹(无需新运行,整条流水线的历史):
theseus view --open # 在 localhost 提供全部已记录运行并打开画廊
启用托管页面:仓库 Settings → Pages → Source: GitHub Actions(其余由
Pages工作流完成)。
安装
pnpm install # 或 npm install
pnpm build # → dist/cli.js
npm link # 暴露 `theseus` (或运行: node dist/cli.js …)
Node ≥ 20,ESM。better-sqlite3、ink、react 为 可选 依赖 —— 即使原生构建或 TUI 依赖缺失,
theseus 也会优雅降级(JSONL 为一手数据源,TUI 回退为表格)。
快速开始(离线、确定性)
theseus --model opus4.8,gpt5.5 --agent cc,opencode,codex \
--harness none,omc,omo,ponytail --bench subagent --tasks 4 --runner mock -L en
矩阵
L0 模型
- claude 系 —
opus4.8 / 4.7 / 4.6、sonnet4.6 / 4.5、haiku4.5、fable5 - gpt 系 —
gpt5-codex(账号默认)、gpt5.5、gpt5.1-codex - open 系(OpenRouter) —
qwen3-coder、qwen3-coder-free(免费额度)、glm4.6、kimi-k2、deepseek-v3.2… 由模型无关智能体以openrouter/<vendor>/<model>传入。向src/config.ts添加任意 OpenRouter id 即可扩展;:free模型按 $0 计费。
L1 智能体
| 智能体 | 二进制 | 模型系 | 框架 |
|---|---|---|---|
cc |
claude | claude | none, superpowers, omc, ecc, ponytail, mattpocock |
codex |
codex | gpt | none, superpowers, omx, lazycodex, omo, ponytail |
opencode |
opencode | claude + gpt | none, omo, ponytail, mattpocock |
openclaw |
openclaw | claude + gpt | none, ponytail |
hermes |
hermes | claude + gpt | none, ponytail |
opencode/openclaw/hermes 与模型无关 —— 接受任意 family,由 theseus 以 provider/id 形式传入:
anthropic/…、openai/…,或 openrouter/<vendor>/<model>(例如免费的 Qwen)。default 省略。
(cc 仅 claude,codex 仅 gpt。)
L2 框架
| 框架 | 类型 | 智能体 |
|---|---|---|
none |
基线 | 全部 |
superpowers |
共用 | cc, codex |
omc / ecc |
编排 | cc |
omx / lazycodex |
编排 | codex |
omo (oh‑my‑openagent) |
编排 | opencode, codex |
ponytail |
极简规则包 | 全部 |
mattpocock |
技能包 | cc, codex, opencode |
不兼容的组合会 附带理由被排除(绝不静默丢弃)。
交互式会话
不带参数运行 theseus 即可打开会话 —— 就像 claude/codex。用自然语言描述目标,
再用每个功能统一的斜杠命令进行配置,然后 /run:
$ theseus
theseus [1m×1a×1h] ▸ 在一个不稳定的 bug 上比较 cc 与 opencode
theseus [1m×1a×1h] ▸ /agents cc,opencode
theseus [2m×2a×1h] ▸ /models opus4.8,gpt5.5
theseus [2m×2a×1h] ▸ /run # → 决策表 + report.html
theseus [2m×2a×1h] ▸ /view # → 在 localhost 上服务所有已记录的轨迹
theseus [2m×2a×1h] ▸ /exit
| 命令 | 说明 |
|---|---|
自然语言 · /goal <text> |
你想达成的目标 — 自然语言累加,记录到 run meta 并显示在报告中 |
/models /agents /harness /bench |
L0×L1×L2 —— 无参数列出,有参数选择 |
/runs /tasks /seed /runner /judge /score /lang |
扫描参数 |
/run · /view [open] · /config /clear /help /exit |
运行 · 可视化 · 查看/重置/帮助/退出 |
也可显式使用 theseus session(别名:chat、repl)。同样的操作也有一次性命令行标志,便于脚本化(见下)。
命令
theseus # 交互式会话(斜杠命令)
theseus session | chat | repl # 同上(显式)
theseus [compare] --model … --agent … --harness … # 默认命令
theseus verify --model … --agent … --harness … # 逐组合的子智能体调用捕获检查
theseus results [--run <id>] # 查看已记录的运行
theseus view [--open] [--port 7777] # 提供并可视化每一条已记录轨迹
theseus tui [--out runs] [--open] [--rich] # 交互式 ink 界面(表格回退)
theseus install <cc|codex|opencode|openclaw|hermes|tb|<harness>|all>
theseus install --check # 状态表
theseus doctor # 运行环境自检
可视化模式 — --view
| 模式 | 行为 |
|---|---|
inline(默认) |
写出自包含的 report.html + graph.html,打印路径 |
open |
同上 + 在浏览器中打开报告 |
serve |
启动 localhost 服务(--port,默认 7777),含全部运行的实时索引 |
term |
在终端渲染柱状图(准确率/令牌/成本/子智能体)+ ANSI 流程树 —— 无需浏览器 |
主要标志
--bench(默认 terminal-bench-v2)· --tasks(20) · --runs(1) · --seed · --runner
(auto|mock|cc|codex|opencode|openclaw|hermes|tb) · --concurrency(4) · --timeout(600) · --out(runs)
· --goal · --judge(none|heuristic|cc) · --score · --balanced · --dry-run · --yes/-y · --view
· --port · --no-logo · --language/-L(默认 kr;en|ja|zh)。
基准(Bench)
- terminal-bench-v2 — 外部 Terminal‑Bench(Docker;委托执行)。缺少
tb时回退到 mock。 - local — 内置 happy‑path 任务(文件校验,无需 Docker)。
- subagent — 内置高难度任务(
subagent-101…106);校验器从输入 fixture 重新计算答案 (无硬编码 golden → 无漂移)。每个任务含一句与代理无关的委托提示。
子智能体流程捕获检查
theseus verify 用强制委派的任务运行每个有效组合,并用表格报告子智能体调用是否被真正捕获。
树型组合(cc + 编排、opencode + omo)应当扇出(fan‑out);单循环组合(codex、none、hermes)显示
flat (expected)。默认离线 mock,真实 runner 需 --yes。
不变量 (PRD §20)
排序主键 subagentCount → totalTokens → wallTimeMs · 无单一分数(按视角 + 帕累托) ·
确定性(sha256 子集,禁用 Math.random) · fail‑soft(无静默丢弃,success ≠ resolved) ·
null = 未采集 · 不重写 runner(mock 回退 + 横幅) · 自包含 HTML ·
框架 per‑run(无全局污染) · recompute‑in‑verify · i18n。
开发
pnpm typecheck && pnpm lint && pnpm test && pnpm build
详见 docs/(架构 · 注册表 · 转录模式 · 可视化 · 品牌 · 验收标准)。