Skip to content
TypeScript
9.9 KB
Raw Blame
theseus — 比较模型 × 智能体 × 框架,并由你判断权衡

theseus

在你自己的任务上比较 模型 × 智能体 × 框架(harness)—— 权衡由你来判断。

CI Pages node

🌐 English · 한국어 · 日本語 · 中文


它做什么

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/(架构 · 注册表 · 转录模式 · 可视化 · 品牌 · 验收标准)。