Skip to content
TypeScript

README: block diagram, name/judgment section, multilingual, demo how-to; purge "dike"

Claude622fe21cb4e5
diff --git a/NOTES.md b/NOTES.md
index e4be60d..e09e460 100644
--- a/NOTES.md
+++ b/NOTES.md
@@ -32,7 +32,7 @@
**AS-IS**: 빈 저장소(LICENSE 만). 비교 도구가 없어, 어떤 모델·도구 조합이 내 과제에 맞는지
직접 돌려보고 나란히 비교할 방법이 없었다.
-**TO-BE**: PRD(dike 사양)대로 비교 CLI `theseus` 를 처음부터 만들었다. 이제 한 줄 명령으로
+**TO-BE**: PRD 사양대로 비교 CLI `theseus` 를 처음부터 만들었다. 이제 한 줄 명령으로
여러 조합을 같은 과제에 돌려, **정확도·비용·시간·도구 호출·서브에이전트 흐름**을 표와
그림으로 한눈에 비교한다. 인터넷 없이도(오프라인 가짜 실행기) 전체 흐름을 확인할 수 있다.
diff --git a/README.ja.md b/README.ja.md
new file mode 100644
index 0000000..997eed9
--- /dev/null
+++ b/README.ja.md
@@ -0,0 +1,170 @@
+<div align="center">
+
+```
+ _ _
+ | |_| |__ ___ ___ ___ _ _ ___ ⛵
+ | __| '_ \ / _ \/ __|/ _ \ | | / __| ~~~~~~
+ | |_| | | | __/\__ \ __/ |_| \__ \ theseus
+ \__|_| |_|\___||___/\___|\__,_|___/ ~~~~~~~~~~
+```
+
+# theseus
+
+**自分のタスクで モデル × エージェント × ハーネス を比較し — トレードオフは自分で判断する。**
+
+[![CI](https://github.com/olympusresearch/theseus/actions/workflows/ci.yml/badge.svg)](https://github.com/olympusresearch/theseus/actions/workflows/ci.yml)
+[![Pages](https://github.com/olympusresearch/theseus/actions/workflows/pages.yml/badge.svg)](https://github.com/olympusresearch/theseus/actions/workflows/pages.yml)
+![node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
+
+🌐 [English](README.md) · [한국어](README.ko.md) · **日本語** · [中文](README.zh.md)
+
+</div>
+
+---
+
+## 何をするか
+
+theseus は **同じタスク集合** を **モデル(L0) × エージェント(L1) × ハーネス(L2)** の組み合わせごとに
+実行し、各組み合わせの **正確性 · コスト · 時間 · ツール呼び出し · サブエージェント呼び出しフロー** を
+横並びで示す。だからフローを理解し、**自分に合うトレードオフ** を自分で選べる。リーダーボードでは
+**なく**、既定では **単一スコアを出さない**。代わりに観点ごとの最良とコスト/正確性の
+**パレートフロンティア** を示す。
+
+```mermaid
+flowchart LR
+ M["<b>L0 · モデル</b><br/>opus4.8 · gpt5.5 · …"]:::layer
+ A["<b>L1 · エージェント</b><br/>cc · codex · opencode<br/>openclaw · hermes"]:::layer
+ H["<b>L2 · ハーネス</b><br/>none · omc · omo<br/>ponytail · …"]:::layer
+
+ M --> C; A --> C; H --> C
+ C["組合せ →<br/><b>有効な組合せ</b><br/><i>(非互換は理由付きで除外)</i>"]:::step
+ C --> S["<b>決定的サブセット</b><br/>sha256 · seed"]:::step
+ S --> R["<b>実行</b> · fail-soft<br/>mock · cc · codex · …"]:::step
+ R --> P["<b>トランスクリプト解析</b><br/>トークン · ツール · サブエージェント"]:::step
+ P --> X["<b>メトリクス</b><br/>正確性 · コスト · 時間 · フロー"]:::step
+ X --> O1(["📊 report.html<br/>パレートフロンティア"]):::out
+ X --> O2(["🌳 graph.html<br/>サブエージェントフロー"]):::out
+ X --> O3(["🖥️ TUI · --view term/serve"]):::out
+
+ classDef layer fill:#15324f,stroke:#c08a3e,color:#f5f1e6;
+ classDef step fill:#0b2942,stroke:#7fb2c9,color:#f5f1e6;
+ classDef out fill:#c08a3e,stroke:#0b2942,color:#0b2942;
+```
+
+実行ごとの成果物: 構造化データ(`results.jsonl` + 任意の `theseus.sqlite`)、**自己完結型** の
+`report.html`(外部 JS/CDN なし)、サブエージェント **フローグラフ** `graph.html`。
+
+## 名前 — 船、そして判断
+
+**theseus** は *[テセウスの船](https://ja.wikipedia.org/wiki/テセウスの船)*。板を一枚ずつ取り替えても
+船は船のまま。あなたのワークフローが船であり、**モデル・エージェント・ハーネスは取り替える板** だ。
+theseus は、どの板が航海を実際に変えるのかを示す。
+
+その目的は **判断(judgment)**。勝者を決めず、根拠(正確性・コスト・時間・フロー)を渡して、*あなたが*
+トレードオフを比べ、自ら判定する。この精神は正義と判断の体現である **ディケー(Δίκη, Díkē)** に由来する
+— theseus は道具であり、判断はあなたの役目だ。
+
+## ライブデモ ギャラリー
+
+自己完結型のサンプルレポート + フローグラフ。`main` への push ごとに CI が再生成する。
+
+- **ホスティング:** **<https://olympusresearch.github.io/theseus/>** *(メンテナが Pages を有効化した後 — 下記)*
+- **ローカルで開く**(ネットワーク不要):
+ ```bash
+ npm run build:site # ./site を生成 (index.html + report.html + graph.html)
+ open site/index.html # macOS · Linux: xdg-open · Windows: start
+ ```
+- **自分の実行結果から:**
+ ```bash
+ theseus --model opus4.8 --agent cc --harness none,omc --bench subagent --runner mock --view open # ブラウザでレポートを開く
+ theseus … --view serve --port 7777 # 全 run を http://localhost:7777 で配信
+ ```
+
+> ホストページの有効化: リポジトリ **Settings → Pages → Source: GitHub Actions**(`Pages` ワークフローが処理)。
+
+## インストール
+
+```bash
+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 は表にフォールバック)。
+
+## クイックスタート(オフライン・決定的)
+
+```bash
+theseus --model opus4.8,gpt5.5 --agent cc,opencode,codex \
+ --harness none,omc,omo,ponytail --bench subagent --tasks 4 --runner mock -L en
+```
+
+## マトリクス
+
+### L0 モデル
+`opus4.8 / 4.7 / 4.6`, `sonnet4.6 / 4.5`, `haiku4.5`, `fable5`(claude 系) ·
+`gpt5-codex`(アカウント既定), `gpt5.5`, `gpt5.1-codex`(gpt 系)。
+
+### 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` はモデル非依存 — theseus が `provider/id` 形式(`anthropic/…`, `openai/…`;
+`default` は省略)でモデルを渡す。
+
+### L2 ハーネス
+| ハーネス | 種別 | エージェント |
+|---|---|---|
+| `none` | ベースライン | 全部 |
+| `superpowers` | 共用 | cc, codex |
+| `omc` / `ecc` | オーケストレーション | cc |
+| `omx` / `lazycodex` | オーケストレーション | codex |
+| `omo` (oh‑my‑openagent) | オーケストレーション | opencode, codex |
+| `ponytail` | ミニマリズム規則 | 全部 |
+| `mattpocock` | スキル集 | cc, codex, opencode |
+
+非互換の組み合わせは **理由付きで除外** される(黙って捨てない)。
+
+## コマンド
+
+```bash
+theseus [compare] --model … --agent … --harness … # 既定コマンド
+theseus verify --model … --agent … --harness … # 組合せごとのサブエージェント呼び出し捕捉チェック
+theseus results [--run <id>] # 記録済み run を表示
+theseus tui [--out runs] [--open] [--rich] # 対話型 ink UI(表フォールバック)
+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)で全 run のライブインデックス |
+| `term` | 棒グラフ(正確性/トークン/コスト/サブエージェント)+ ANSI **フローツリー** を端末に — ブラウザ不要 |
+
+## サブエージェントフロー捕捉チェック
+
+`theseus verify` は委譲を促すタスクで各有効組合せを実行し、サブエージェント呼び出しが実際に捕捉されるかを
+表で報告する。ツリー型(cc + オーケストレーション, opencode + omo)は fan‑out が必要、単一ループ
+(codex・`none`・hermes)は `flat (expected)`。既定はオフライン mock、real ランナーは `--yes` が必要。
+
+## 不変条件 (PRD §20)
+ソート基準キー `subagentCount → totalTokens → wallTimeMs` · 単一スコアなし(観点別 + パレート) ·
+決定性(sha256 サブセット、`Math.random` 禁止) · fail‑soft(黙ったドロップなし、`success ≠ resolved`) ·
+`null = 未収集` · ランナー非再実装(mock フォールバック + バナー) · 自己完結型 HTML ·
+ハーネス per‑run(グローバル汚染なし) · recompute‑in‑verify · i18n。
+
+## 開発
+```bash
+pnpm typecheck && pnpm lint && pnpm test && pnpm build
+```
+詳細は [`docs/`](docs/)(アーキテクチャ · レジストリ · トランスクリプト · 可視化 · ブランド · 受け入れ基準)。
diff --git a/README.ko.md b/README.ko.md
new file mode 100644
index 0000000..f504a65
--- /dev/null
+++ b/README.ko.md
@@ -0,0 +1,169 @@
+<div align="center">
+
+```
+ _ _
+ | |_| |__ ___ ___ ___ _ _ ___ ⛵
+ | __| '_ \ / _ \/ __|/ _ \ | | / __| ~~~~~~
+ | |_| | | | __/\__ \ __/ |_| \__ \ theseus
+ \__|_| |_|\___||___/\___|\__,_|___/ ~~~~~~~~~~
+```
+
+# theseus
+
+**내 과제로 모델 × 에이전트 × 하네스를 비교하고 — trade‑off 는 당신이 판단한다.**
+
+[![CI](https://github.com/olympusresearch/theseus/actions/workflows/ci.yml/badge.svg)](https://github.com/olympusresearch/theseus/actions/workflows/ci.yml)
+[![Pages](https://github.com/olympusresearch/theseus/actions/workflows/pages.yml/badge.svg)](https://github.com/olympusresearch/theseus/actions/workflows/pages.yml)
+![node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
+
+🌐 [English](README.md) · **한국어** · [日本語](README.ja.md) · [中文](README.zh.md)
+
+</div>
+
+---
+
+## 무엇을 하나
+
+theseus 는 **같은 과제 묶음**을 **모델(L0) × 에이전트(L1) × 하네스(L2)** 조합마다 돌려, 각 조합의
+**정확도 · 비용 · 시간 · 툴콜 · 서브에이전트 호출 흐름**을 나란히 보여준다. 그래서 흐름을 이해하고
+**당신에게 맞는 trade‑off** 를 직접 고른다. 리더보드가 **아니며**, 기본적으로 **단일 점수를 만들지
+않는다**. 대신 관점별 최적과 비용/정확도 **파레토 경계**를 표시한다.
+
+```mermaid
+flowchart LR
+ M["<b>L0 · 모델</b><br/>opus4.8 · gpt5.5 · …"]:::layer
+ A["<b>L1 · 에이전트</b><br/>cc · codex · opencode<br/>openclaw · hermes"]:::layer
+ H["<b>L2 · 하네스</b><br/>none · omc · omo<br/>ponytail · …"]:::layer
+
+ M --> C; A --> C; H --> C
+ C["조합 →<br/><b>유효 조합</b><br/><i>(비호환은 사유와 함께 제외)</i>"]:::step
+ C --> S["<b>결정적 subset</b><br/>sha256 · seed"]:::step
+ S --> R["<b>실행</b> · fail-soft<br/>mock · cc · codex · …"]:::step
+ R --> P["<b>트랜스크립트 파싱</b><br/>토큰 · 툴콜 · 서브에이전트"]:::step
+ P --> X["<b>메트릭</b><br/>정확도 · 비용 · 시간 · 흐름"]:::step
+ X --> O1(["📊 report.html<br/>파레토 경계"]):::out
+ X --> O2(["🌳 graph.html<br/>서브에이전트 흐름"]):::out
+ X --> O3(["🖥️ TUI · --view term/serve"]):::out
+
+ classDef layer fill:#15324f,stroke:#c08a3e,color:#f5f1e6;
+ classDef step fill:#0b2942,stroke:#7fb2c9,color:#f5f1e6;
+ classDef out fill:#c08a3e,stroke:#0b2942,color:#0b2942;
+```
+
+매 실행 산출물: 구조화 데이터(`results.jsonl` + 선택 `theseus.sqlite`), **자기완결형(self‑contained)**
+`report.html`(외부 JS/CDN 0), 서브에이전트 **흐름 그래프** `graph.html`.
+
+## 이름 — 배, 그리고 판단
+
+**theseus** 는 *[테세우스의 배](https://ko.wikipedia.org/wiki/테세우스의_배)*다. 널빤지를 하나씩 갈아
+끼워도 배는 여전히 그 배다. 당신의 워크플로가 배이고, **모델·에이전트·하네스가 갈아끼우는 널빤지**다.
+theseus 는 어떤 널빤지가 항해를 실제로 바꾸는지 보여준다.
+
+그리고 그 목적은 **판단(judgment)** 이다. 승자를 정해 주지 않고, 근거(정확도·비용·시간·흐름)를
+건네 *당신이* trade‑off 를 저울질해 스스로 판정하게 한다. 이 정신은 정의와 판단의 화신
+**디케(Δίκη, Díkē)** 에서 왔다 — theseus 는 도구이고, 판단은 당신의 몫이다.
+
+## 라이브 데모 갤러리
+
+자기완결형 예시 리포트 + 흐름 그래프. `main` 에 푸시될 때마다 CI 가 재생성한다.
+
+- **호스팅:** **<https://olympusresearch.github.io/theseus/>** *(메인테이너가 Pages 를 켠 뒤 — 아래 참고)*
+- **로컬에서 열기** (네트워크 불필요):
+ ```bash
+ npm run build:site # ./site 생성 (index.html + report.html + graph.html)
+ open site/index.html # macOS · Linux: xdg-open · Windows: start
+ ```
+- **내 실행 결과에서 바로:**
+ ```bash
+ theseus --model opus4.8 --agent cc --harness none,omc --bench subagent --runner mock --view open # 브라우저로 리포트 열기
+ theseus … --view serve --port 7777 # 모든 run 을 http://localhost:7777 에 서빙
+ ```
+
+> 호스팅 페이지 켜기: 저장소 **Settings → Pages → Source: GitHub Actions** (`Pages` 워크플로가 나머지를 처리).
+
+## 설치
+
+```bash
+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 이 1차 소스, TUI 는 표로 폴백).
+
+## 빠른 시작 (오프라인·결정적)
+
+```bash
+theseus --model opus4.8,gpt5.5 --agent cc,opencode,codex \
+ --harness none,omc,omo,ponytail --bench subagent --tasks 4 --runner mock -L kr
+```
+
+## 매트릭스
+
+### L0 모델
+`opus4.8 / 4.7 / 4.6`, `sonnet4.6 / 4.5`, `haiku4.5`, `fable5` (claude 계열) ·
+`gpt5-codex`(계정 기본), `gpt5.5`, `gpt5.1-codex` (gpt 계열).
+
+### 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` 는 모델 불문 — theseus 가 `provider/id` 형식(`anthropic/…`, `openai/…`;
+`default` 은 생략)으로 모델을 넘긴다.
+
+### L2 하네스
+| 하네스 | 유형 | 에이전트 |
+|---|---|---|
+| `none` | 기준선 | 전체 |
+| `superpowers` | 공용 | cc, codex |
+| `omc` / `ecc` | 오케스트레이션 | cc |
+| `omx` / `lazycodex` | 오케스트레이션 | codex |
+| `omo` (oh‑my‑openagent) | 오케스트레이션 | opencode, codex |
+| `ponytail` | 미니멀리즘 룰팩 | 전체 |
+| `mattpocock` | 스킬팩 | cc, codex, opencode |
+
+비호환 조합은 **사유와 함께 제외**된다(조용히 버리지 않음).
+
+## 명령어
+
+```bash
+theseus [compare] --model … --agent … --harness … # 기본 명령
+theseus verify --model … --agent … --harness … # 조합별 서브에이전트 콜 포착 점검
+theseus results [--run <id>] # 기록된 run 보기
+theseus tui [--out runs] [--open] [--rich] # 인터랙티브 ink UI (표 폴백)
+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)에 모든 run 라이브 인덱스 |
+| `term` | 막대 차트(정확도/토큰/비용/서브에이전트) + ANSI **흐름 트리** 를 터미널에 — 브라우저 불필요 |
+
+## 서브에이전트 흐름 포착 점검
+
+`theseus verify` 는 위임 유도 과제로 각 유효 조합을 돌려, 서브에이전트 콜이 실제로 잡히는지 표로 보고한다.
+트리형 조합(cc + 오케스트레이션, opencode + omo)은 fan‑out 이 필요하고, 단일 루프(codex·`none`·hermes)는
+`flat (expected)` 로 표시된다. 기본은 오프라인 mock, real 러너는 `--yes` 필요.
+
+## 불변식 (PRD §20)
+정렬 기본키 `subagentCount → totalTokens → wallTimeMs` · 단일 점수 없음(관점별 + 파레토) ·
+결정성(sha256 subset, `Math.random` 금지) · fail‑soft(조용한 드롭 없음, `success ≠ resolved`) ·
+`null = 미수집` · 러너 비재구현(mock 폴백 + 배너) · 자기완결형 HTML · 하네스 per‑run(전역 오염 없음) ·
+recompute‑in‑verify · i18n.
+
+## 개발
+```bash
+pnpm typecheck && pnpm lint && pnpm test && pnpm build
+```
+자세한 내용은 [`docs/`](docs/) (아키텍처 · 레지스트리 · 트랜스크립트 스키마 · 시각화 · 브랜드 · 인수기준).
diff --git a/README.md b/README.md
index c9c0772..095d98c 100644
--- a/README.md
+++ b/README.md
@@ -1,33 +1,87 @@
+<div align="center">
+
```
_ _
- | |_| |__ ___ ___ ___ _ _ ___ ⛵
- | __| '_ \ / _ \/ __|/ _ \ | | / __| ~~~~~~
- | |_| | | | __/\__ \ __/ |_| \__ \ theseus
- \__|_| |_|\___||___/\___|\__,_|___/ ~~~~~~~~~~
+ | |_| |__ ___ ___ ___ _ _ ___ ⛵
+ | __| '_ \ / _ \/ __|/ _ \ | | / __| ~~~~~~
+ | |_| | | | __/\__ \ __/ |_| \__ \ theseus
+ \__|_| |_|\___||___/\___|\__,_|___/ ~~~~~~~~~~
```
# theseus
+**Compare model × agent × harness on your own tasks — then judge the trade-offs yourself.**
+
[![CI](https://github.com/olympusresearch/theseus/actions/workflows/ci.yml/badge.svg)](https://github.com/olympusresearch/theseus/actions/workflows/ci.yml)
[![Pages](https://github.com/olympusresearch/theseus/actions/workflows/pages.yml/badge.svg)](https://github.com/olympusresearch/theseus/actions/workflows/pages.yml)
![node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
![license](https://img.shields.io/badge/license-see%20LICENSE-blue)
-> **Swap the model, the agent, the harness — plank by plank. The ship is still yours.
-> theseus shows you which planks actually change the voyage.**
->
-> 📊 **[Live demo gallery](https://olympusresearch.github.io/theseus/)** (mock run, regenerated by CI)
+🌐 **English** · [한국어](README.ko.md) · [日本語](README.ja.md) · [中文](README.zh.md)
+
+</div>
+
+---
+
+## What it does
+
+theseus runs the **same task subset** across **model (L0) × agent (L1) × harness (L2)** combinations and
+lays out, side by side, each combination's **accuracy · cost · time · tool calls · subagent call flow** — so
+you understand the flow and pick the trade‑off that fits *you*. It is **not** a leaderboard and produces
+**no single score** by default; it recommends per‑perspective winners and marks the cost/accuracy
+**Pareto frontier**.
+
+```mermaid
+flowchart LR
+ M["<b>L0 · model</b><br/>opus4.8 · gpt5.5 · …"]:::layer
+ A["<b>L1 · agent</b><br/>cc · codex · opencode<br/>openclaw · hermes"]:::layer
+ H["<b>L2 · harness</b><br/>none · omc · omo<br/>ponytail · …"]:::layer
+
+ M --> C; A --> C; H --> C
+ C["combine →<br/><b>valid combos</b><br/><i>(incompatibles excluded<br/>with a reason)</i>"]:::step
+ C --> S["<b>deterministic subset</b><br/>sha256 · seed"]:::step
+ S --> R["<b>run</b> · fail-soft<br/>mock · cc · codex · opencode · …"]:::step
+ R --> P["<b>parse transcripts</b><br/>tokens · tool calls · subagents"]:::step
+ P --> X["<b>metrics</b><br/>accuracy · cost · time · flow"]:::step
+ X --> O1(["📊 report.html<br/>Pareto frontier"]):::out
+ X --> O2(["🌳 graph.html<br/>subagent flow"]):::out
+ X --> O3(["🖥️ TUI · --view term/serve"]):::out
+
+ classDef layer fill:#15324f,stroke:#c08a3e,color:#f5f1e6;
+ classDef step fill:#0b2942,stroke:#7fb2c9,color:#f5f1e6;
+ classDef out fill:#c08a3e,stroke:#0b2942,color:#0b2942;
+```
+
+Every run emits: structured data (`results.jsonl` + optional `theseus.sqlite`), a **self‑contained**
+`report.html` (no external JS/CDN), and a subagent **flow graph** `graph.html`.
-theseus is a comparison CLI (a TypeScript reimplementation of the **dike** product spec). It runs the
-**same task subset** across **model (L0) × agent (L1) × harness (L2)** combinations and lays out, side by
-side, each combination's **accuracy · cost · time · tool calls · subagent call flow** — so you understand
-the flow and pick the trade-off that fits *you*. It is **not** a leaderboard and produces **no single
-score** by default; it recommends per-perspective winners and marks the cost/accuracy **Pareto frontier**.
+## The name — a ship, and a judgment
-Every run emits:
-- structured data — `results.jsonl` (source of truth) + `theseus.sqlite` (optional query cache)
-- a **self-contained** `report.html` (no external JS/CDN) with the nautical theme, scatter + Pareto frontier
-- a subagent **flow graph** `graph.html` (inline SVG card-tree + native toggles)
+**theseus** is the *[Ship of Theseus](https://en.wikipedia.org/wiki/Ship_of_Theseus)*: replace plank after
+plank and the ship still endures. Your workflow is the ship; the **model, agent, and harness are planks**
+you swap. theseus shows you which planks actually change the voyage.
+
+And its purpose is **judgment** — it doesn't crown a winner, it hands you the evidence (accuracy, cost,
+time, flow) so *you* weigh the trade‑offs and pass your own verdict. That spirit traces to **Díkē (Δίκη)**,
+the Greek embodiment of justice and judgment; theseus is the instrument, your call is the judgment.
+
+## Live demo gallery
+
+A self‑contained example report + flow graph, regenerated by CI on every push to `main`.
+
+- **Hosted:** **<https://olympusresearch.github.io/theseus/>** *(after a maintainer enables Pages — see below)*
+- **Open it locally** (no network needed):
+ ```bash
+ npm run build:site # builds ./site (index.html + report.html + graph.html)
+ open site/index.html # macOS · Linux: xdg-open · Windows: start
+ ```
+- **From any of your own runs:**
+ ```bash
+ theseus --model opus4.8 --agent cc --harness none,omc --bench subagent --runner mock --view open # pops the report in your browser
+ theseus … --view serve --port 7777 # serves all runs at http://localhost:7777
+ ```
+
+> Enabling the hosted page: repo **Settings → Pages → Source: GitHub Actions** (the `Pages` workflow does the rest).
## Install
@@ -62,7 +116,7 @@ theseus --model opus4.8,gpt5.5 --agent cc,opencode,codex \
| `openclaw` | openclaw | claude + gpt | none, ponytail |
| `hermes` | hermes | claude + gpt | none, ponytail |
-`opencode/openclaw/hermes` are model-agnostic; theseus passes the model as `provider/id` (`anthropic/…`,
+`opencode/openclaw/hermes` are model‑agnostic; theseus passes the model as `provider/id` (`anthropic/…`,
`openai/…`; `default` omitted).
### L2 harnesses
@@ -72,8 +126,8 @@ theseus --model opus4.8,gpt5.5 --agent cc,opencode,codex \
| `superpowers` | shared | cc, codex |
| `omc` / `ecc` | orchestration | cc |
| `omx` / `lazycodex` | orchestration | codex |
-| `omo` (oh-my-openagent) | orchestration | opencode, codex |
-| `ponytail` | minimalism rule-pack | all |
+| `omo` (oh‑my‑openagent) | orchestration | opencode, codex |
+| `ponytail` | minimalism rule‑pack | all |
| `mattpocock` | skills pack | cc, codex, opencode |
Incompatible combos are **excluded with a reason** (never silently dropped).
@@ -93,16 +147,11 @@ theseus doctor # environment self-diagnosi
### Visualization modes — `--view`
| mode | what it does |
|---|---|
-| `inline` (default) | write self-contained `report.html` + `graph.html`, print paths |
+| `inline` (default) | write self‑contained `report.html` + `graph.html`, print paths |
| `open` | also pop the report open in your browser |
| `serve` | start a localhost server (`--port`, default 7777) with a live index of all runs |
| `term` | render bar charts (accuracy/tokens/cost/subagents) + an ANSI **flow tree** in the terminal — no browser |
-```bash
-theseus --model opus4.8 --agent cc --harness none,omc --bench subagent --runner mock --view term
-theseus --model opus4.8 --agent cc --harness none --bench subagent --runner mock --view serve --port 7777
-```
-
### Key flags
`--bench` (default `terminal-bench-v2`) · `--tasks` (20) · `--runs` (1) · `--seed` · `--runner`
(auto|mock|cc|codex|opencode|openclaw|hermes|tb) · `--concurrency` (4) · `--timeout` (600) · `--out` (runs)
@@ -110,15 +159,15 @@ theseus --model opus4.8 --agent cc --harness none --bench subagent --runner mock
· `--no-logo` · `--language/-L` (kr default; en).
## Benches
-- **terminal-bench-v2** — external Terminal-Bench (Docker; delegated). Falls back to mock if `tb` absent.
-- **local** — built-in, file-verified happy-path tasks (no Docker).
-- **subagent** — built-in hard tasks (`subagent-101…106`); verifiers **recompute the answer from the input
- fixtures** (no hardcoded golden → no drift). Each carries one agent-agnostic delegation hint.
+- **terminal-bench-v2** — external Terminal‑Bench (Docker; delegated). Falls back to mock if `tb` absent.
+- **local** — built‑in, file‑verified happy‑path tasks (no Docker).
+- **subagent** — built‑in hard tasks (`subagent-101…106`); verifiers **recompute the answer from the input
+ fixtures** (no hardcoded golden → no drift). Each carries one agent‑agnostic delegation hint.
## Verifying subagent flow capture
-`theseus verify` runs each valid combo once on a delegation-heavy task and reports whether subagent calls
-were captured:
+`theseus verify` runs each valid combo on a delegation‑heavy task and reports whether subagent calls were
+captured:
```
combo subagents maxDepth captured?
@@ -127,22 +176,17 @@ opencode+opus4.8+omo 3 0 ✓ captured
codex+gpt5.5+none 0 0 — flat (expected)
```
-Tree-capable combos (cc + orchestration, opencode + omo) must fan out; single-loop combos (codex, `none`,
+Tree‑capable combos (cc + orchestration, opencode + omo) must fan out; single‑loop combos (codex, `none`,
hermes) report `flat (expected)`. Defaults to the offline mock runner; real runners need `--yes`.
-## Philosophy & branding
-
-See [docs/brand.md](docs/brand.md) — the **Ship of Theseus**: every part is swappable, the vessel persists.
-The job of theseus is to reveal *which swap actually changed the voyage*, not to crown a winner.
-
## Invariants (PRD §20)
Sort key `subagentCount → totalTokens → wallTimeMs` · no single score (perspectives + Pareto) ·
-determinism (sha256 subset, no `Math.random`) · fail-soft (no silent drops; `success ≠ resolved`) ·
-`null = uncollected` · runners not reimplemented (mock fallback + banner) · self-contained HTML ·
-harness per-run (no global pollution) · recompute-in-verify · i18n (display strings only, kr fallback).
+determinism (sha256 subset, no `Math.random`) · fail‑soft (no silent drops; `success ≠ resolved`) ·
+`null = uncollected` · runners not reimplemented (mock fallback + banner) · self‑contained HTML ·
+harness per‑run (no global pollution) · recompute‑in‑verify · i18n.
## Development
```bash
pnpm typecheck && pnpm lint && pnpm test && pnpm build
```
-See `docs/` for architecture, registry, transcript schema, visualization, brand, and acceptance criteria.
+See [`docs/`](docs/) for architecture, registry, transcript schema, visualization, brand, and acceptance.
diff --git a/README.zh.md b/README.zh.md
new file mode 100644
index 0000000..95114a8
--- /dev/null
+++ b/README.zh.md
@@ -0,0 +1,167 @@
+<div align="center">
+
+```
+ _ _
+ | |_| |__ ___ ___ ___ _ _ ___ ⛵
+ | __| '_ \ / _ \/ __|/ _ \ | | / __| ~~~~~~
+ | |_| | | | __/\__ \ __/ |_| \__ \ theseus
+ \__|_| |_|\___||___/\___|\__,_|___/ ~~~~~~~~~~
+```
+
+# theseus
+
+**在你自己的任务上比较 模型 × 智能体 × 框架(harness)—— 权衡由你来判断。**
+
+[![CI](https://github.com/olympusresearch/theseus/actions/workflows/ci.yml/badge.svg)](https://github.com/olympusresearch/theseus/actions/workflows/ci.yml)
+[![Pages](https://github.com/olympusresearch/theseus/actions/workflows/pages.yml/badge.svg)](https://github.com/olympusresearch/theseus/actions/workflows/pages.yml)
+![node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
+
+🌐 [English](README.md) · [한국어](README.ko.md) · [日本語](README.ja.md) · **中文**
+
+</div>
+
+---
+
+## 它做什么
+
+theseus 在 **同一任务子集** 上运行 **模型(L0) × 智能体(L1) × 框架(L2)** 的各种组合,并把每个组合的
+**准确率 · 成本 · 时间 · 工具调用 · 子智能体调用流** 并排呈现 —— 让你看懂流程,挑选 **适合你的权衡**。
+它 **不是** 排行榜,默认 **不产出单一分数**;而是给出按视角的最优,并标出成本/准确率的
+**帕累托前沿(Pareto frontier)**。
+
+```mermaid
+flowchart LR
+ M["<b>L0 · 模型</b><br/>opus4.8 · gpt5.5 · …"]:::layer
+ A["<b>L1 · 智能体</b><br/>cc · codex · opencode<br/>openclaw · hermes"]:::layer
+ H["<b>L2 · 框架</b><br/>none · omc · omo<br/>ponytail · …"]:::layer
+
+ M --> C; A --> C; H --> C
+ C["组合 →<br/><b>有效组合</b><br/><i>(不兼容者附理由排除)</i>"]:::step
+ C --> S["<b>确定性子集</b><br/>sha256 · seed"]:::step
+ S --> R["<b>运行</b> · fail-soft<br/>mock · cc · codex · …"]:::step
+ R --> P["<b>解析转录</b><br/>令牌 · 工具调用 · 子智能体"]:::step
+ P --> X["<b>指标</b><br/>准确率 · 成本 · 时间 · 流程"]:::step
+ X --> O1(["📊 report.html<br/>帕累托前沿"]):::out
+ X --> O2(["🌳 graph.html<br/>子智能体流"]):::out
+ X --> O3(["🖥️ TUI · --view term/serve"]):::out
+
+ classDef layer fill:#15324f,stroke:#c08a3e,color:#f5f1e6;
+ classDef step fill:#0b2942,stroke:#7fb2c9,color:#f5f1e6;
+ classDef out fill:#c08a3e,stroke:#0b2942,color:#0b2942;
+```
+
+每次运行产出:结构化数据(`results.jsonl` + 可选 `theseus.sqlite`)、**自包含(self‑contained)** 的
+`report.html`(无外部 JS/CDN)、以及子智能体 **流程图** `graph.html`。
+
+## 名字 —— 一艘船,与一次判断
+
+**theseus** 取自 *[忒修斯之船](https://zh.wikipedia.org/wiki/忒修斯之船)*:逐块更换木板,船依旧是那艘船。
+你的工作流就是这艘船,**模型、智能体、框架就是可替换的木板**。theseus 让你看清哪块木板真正改变了航程。
+
+它的目的在于 **判断(judgment)**:不替你封王,而是把证据(准确率、成本、时间、流程)交给你,由 *你*
+权衡并自行裁断。这一精神源自正义与裁判的化身 **狄刻(Δίκη, Díkē)**—— theseus 是工具,判断在你。
+
+## 在线演示画廊
+
+自包含的示例报告 + 流程图,每次推送到 `main` 时由 CI 重新生成。
+
+- **托管:** **<https://olympusresearch.github.io/theseus/>** *(需维护者启用 Pages —— 见下)*
+- **本地打开**(无需联网):
+ ```bash
+ npm run build:site # 生成 ./site (index.html + report.html + graph.html)
+ open site/index.html # macOS · Linux: xdg-open · Windows: start
+ ```
+- **从你自己的运行结果:**
+ ```bash
+ theseus --model opus4.8 --agent cc --harness none,omc --bench subagent --runner mock --view open # 在浏览器中打开报告
+ theseus … --view serve --port 7777 # 在 http://localhost:7777 提供全部运行
+ ```
+
+> 启用托管页面:仓库 **Settings → Pages → Source: GitHub Actions**(其余由 `Pages` 工作流完成)。
+
+## 安装
+
+```bash
+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 回退为表格)。
+
+## 快速开始(离线、确定性)
+
+```bash
+theseus --model opus4.8,gpt5.5 --agent cc,opencode,codex \
+ --harness none,omc,omo,ponytail --bench subagent --tasks 4 --runner mock -L en
+```
+
+## 矩阵
+
+### L0 模型
+`opus4.8 / 4.7 / 4.6`、`sonnet4.6 / 4.5`、`haiku4.5`、`fable5`(claude 系) ·
+`gpt5-codex`(账号默认)、`gpt5.5`、`gpt5.1-codex`(gpt 系)。
+
+### 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` 与模型无关 —— theseus 以 `provider/id` 形式传模型(`anthropic/…`、
+`openai/…`;`default` 省略)。
+
+### L2 框架
+| 框架 | 类型 | 智能体 |
+|---|---|---|
+| `none` | 基线 | 全部 |
+| `superpowers` | 共用 | cc, codex |
+| `omc` / `ecc` | 编排 | cc |
+| `omx` / `lazycodex` | 编排 | codex |
+| `omo` (oh‑my‑openagent) | 编排 | opencode, codex |
+| `ponytail` | 极简规则包 | 全部 |
+| `mattpocock` | 技能包 | cc, codex, opencode |
+
+不兼容的组合会 **附带理由被排除**(绝不静默丢弃)。
+
+## 命令
+
+```bash
+theseus [compare] --model … --agent … --harness … # 默认命令
+theseus verify --model … --agent … --harness … # 逐组合的子智能体调用捕获检查
+theseus results [--run <id>] # 查看已记录的运行
+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 **流程树** —— 无需浏览器 |
+
+## 子智能体流程捕获检查
+
+`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。
+
+## 开发
+```bash
+pnpm typecheck && pnpm lint && pnpm test && pnpm build
+```
+详见 [`docs/`](docs/)(架构 · 注册表 · 转录模式 · 可视化 · 品牌 · 验收标准)。
diff --git a/src/flow.ts b/src/flow.ts
index b331e85..836879f 100644
--- a/src/flow.ts
+++ b/src/flow.ts
@@ -207,14 +207,14 @@ function truncateLabel(s: string): string {
}
export const DETAILS_CSS = `
-.dike-details{margin:4px 0;border:1px solid #e2e8f0;border-radius:8px;background:#fff}
-.dike-details>summary{cursor:pointer;padding:6px 10px;font-size:13px;font-weight:600;color:#1e293b;list-style:none}
-.dike-details>summary::-webkit-details-marker{display:none}
-.dike-details>summary::before{content:'▸ ';color:#94a3b8}
-.dike-details[open]>summary::before{content:'▾ '}
-.dike-details .body{padding:6px 12px;font-size:12px;color:#334155;border-top:1px solid #f1f5f9}
-.dike-details .body div{margin:3px 0;word-break:break-word}
-.dike-details .k{color:#64748b;font-weight:600;margin-right:4px}
+.theseus-details{margin:4px 0;border:1px solid #e2e8f0;border-radius:8px;background:#fff}
+.theseus-details>summary{cursor:pointer;padding:6px 10px;font-size:13px;font-weight:600;color:#1e293b;list-style:none}
+.theseus-details>summary::-webkit-details-marker{display:none}
+.theseus-details>summary::before{content:'▸ ';color:#94a3b8}
+.theseus-details[open]>summary::before{content:'▾ '}
+.theseus-details .body{padding:6px 12px;font-size:12px;color:#334155;border-top:1px solid #f1f5f9}
+.theseus-details .body div{margin:3px 0;word-break:break-word}
+.theseus-details .k{color:#64748b;font-weight:600;margin-right:4px}
`;
function row(label: string, value: string): string {
@@ -231,14 +231,14 @@ export function nodeDetailsBlock(node: FlowNode, lang: Lang): string {
row(tr(lang, "node_input"), node.summaryIn),
row(tr(lang, "node_log"), node.logText),
].join("");
- return `<details class="dike-details"><summary>${esc(node.label)} (${esc(node.harness)})</summary><div class="body">${body}</div></details>`;
+ return `<details class="theseus-details"><summary>${esc(node.label)} (${esc(node.harness)})</summary><div class="body">${body}</div></details>`;
}
/** graph.html / report.html 공용 — 한 그래프 섹션(인라인 SVG + 노드 토글) */
export function graphSection(graph: FlowGraph, lang: Lang): string {
const svg = renderGraphSvg(graph);
const toggles = graph.nodes.map((n) => nodeDetailsBlock(n, lang)).join("");
- return `<div class="dike-graph"><h3>${esc(graph.comboId)} — ${esc(graph.taskId)} #${graph.runIdx}</h3><div class="svg-wrap">${svg}</div>${toggles}</div>`;
+ return `<div class="theseus-graph"><h3>${esc(graph.comboId)} — ${esc(graph.taskId)} #${graph.runIdx}</h3><div class="svg-wrap">${svg}</div>${toggles}</div>`;
}
export function renderGraphHtml(graphs: FlowGraph[], path: string, opts: { language: Lang }): void {
@@ -251,8 +251,8 @@ body{font-family:ui-sans-serif,system-ui,sans-serif;background:#f8fafc;color:#0f
h1{font-size:20px}
.theseus-hero{background:${THEME.sea};color:${THEME.sail};border-radius:12px;padding:14px 18px;margin-bottom:16px;display:flex;align-items:center;gap:14px}
.theseus-hero .sub{font-size:13px;opacity:.85}
-.dike-graph{background:#fff;border:1px solid #e2e8f0;border-radius:12px;padding:16px;margin:16px 0;overflow:auto}
-.dike-graph h3{font-size:14px;margin:0 0 10px}
+.theseus-graph{background:#fff;border:1px solid #e2e8f0;border-radius:12px;padding:16px;margin:16px 0;overflow:auto}
+.theseus-graph h3{font-size:14px;margin:0 0 10px}
.svg-wrap{overflow:auto}
${DETAILS_CSS}
</style></head><body>
diff --git a/src/i18n.ts b/src/i18n.ts
index aacc3df..00b2970 100644
--- a/src/i18n.ts
+++ b/src/i18n.ts
@@ -30,8 +30,8 @@ export const STRINGS: Record<string, Entry> = {
run_id: { en: "Run id", kr: "런 ID" },
results_table: { en: "Results", kr: "결과" },
no_models: {
- en: "No models/agents specified. Example: dike --model opus4.8 --agent cc --harness none",
- kr: "모델/에이전트 미지정. 예: dike --model opus4.8 --agent cc --harness none",
+ en: "No models/agents specified. Example: theseus --model opus4.8 --agent cc --harness none",
+ kr: "모델/에이전트 미지정. 예: theseus --model opus4.8 --agent cc --harness none",
},
mock_banner: {
en: "MOCK runner — results are synthetic (offline). Not real measurements.",
diff --git a/src/report.ts b/src/report.ts
index cb065ab..b32636a 100644
--- a/src/report.ts
+++ b/src/report.ts
@@ -335,8 +335,8 @@ code{font-family:ui-monospace,monospace;font-size:12px}
.na{text-align:center;color:#cbd5e1}
.muted{color:#94a3b8}
.banner.mock{background:#fef3c7;border:1px solid #f59e0b;color:#92400e;padding:8px 12px;border-radius:8px;margin-bottom:12px;font-weight:600}
-.dike-graph{background:#fff;border:1px solid #e2e8f0;border-radius:12px;padding:14px;margin:12px 0;overflow:auto}
-.dike-graph h3{font-size:13px;margin:0 0 8px}
+.theseus-graph{background:#fff;border:1px solid #e2e8f0;border-radius:12px;padding:14px;margin:12px 0;overflow:auto}
+.theseus-graph h3{font-size:13px;margin:0 0 8px}
.svg-wrap{overflow:auto}
.theseus-hero{background:${THEME.sea};color:${THEME.sail};border-radius:12px;padding:16px 20px;margin:-8px 0 18px;display:flex;align-items:center;gap:16px}
.theseus-hero .sub{font-size:13px;opacity:.85}