Skip to content

Commit a458906

Browse files
miniLVminiLV
committed
docs: add Plexus-style README and release workflow
1 parent 6049f52 commit a458906

7 files changed

Lines changed: 290 additions & 39 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
test:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
- uses: actions/setup-node@v4
13+
with:
14+
node-version: 22
15+
cache: npm
16+
- run: npm ci
17+
- run: npm run typecheck
18+
- run: npm test

‎.github/workflows/release.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
id-token: write
12+
13+
jobs:
14+
publish:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: 22
21+
registry-url: https://registry.npmjs.org
22+
cache: npm
23+
- run: npm ci
24+
- run: npm run typecheck
25+
- run: npm test
26+
- run: npm pack --dry-run
27+
- run: npm publish --provenance --access public
28+
env:
29+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.nvmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
22

‎README.en.md‎

Lines changed: 85 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,103 @@
1-
# Jev Auto Router
1+
<h1 align="center">Jev Auto Router</h1>
22

3-
[中文](README.md) | **[English](README.en.md)**
3+
<p align="center">
4+
<strong>One model decision per Codex user turn.</strong>
5+
</p>
46

5-
**One model decision per Codex user turn.** `jev-codex` launches the real Codex CLI, adds a virtual `jev-auto` model to the picker, asks [TypeSafe Jev](https://docs.typesafe.ai/introduction) once per fresh user turn, and keeps the selected model pinned through the entire tool loop.
7+
<p align="center">
8+
<code>jev-codex</code> launches the real Codex CLI, adds <code>Jev Auto Router</code> to the model picker, asks TypeSafe Jev once per fresh user turn, and keeps the selected model pinned through the tool loop. Effort moves through cache-preserving <code>configuration_update</code> items.
9+
</p>
610

7-
This is the first **turn-pinned Codex router**. It prioritizes a working loop, fewer switches, and cache-friendly behavior. The old per-call path is gone from the main entrypoint.
11+
<p align="center">
12+
<a href="https://github.com/miniLV/Jev-Auto-Router/tags">Releases</a> ·
13+
<a href="https://minilv.github.io/Jev-Auto-Router/">Homepage</a> ·
14+
<a href="./README.md">简体中文</a> ·
15+
<strong>English</strong>
16+
</p>
817

9-
![Codex Turn Router main flow](docs/assets/codex-turn-router-flow-en.png)
18+
<p align="center">
19+
<a href="https://github.com/miniLV/Jev-Auto-Router/actions/workflows/ci.yml">
20+
<img alt="CI" src="https://github.com/miniLV/Jev-Auto-Router/actions/workflows/ci.yml/badge.svg" />
21+
</a>
22+
<img alt="Release v0.1.0" src="https://img.shields.io/badge/release-v0.1.0-blue" />
23+
<a href="./LICENSE">
24+
<img alt="License" src="https://img.shields.io/github/license/miniLV/Jev-Auto-Router" />
25+
</a>
26+
<img alt="Node 22+" src="https://img.shields.io/badge/node-22%2B-339933" />
27+
<img alt="npm not published" src="https://img.shields.io/badge/npm-not%20published-lightgrey" />
28+
</p>
1029

11-
![Codex Turn Router control loop](docs/assets/codex-turn-router-control-plane-en.png)
30+
<p align="center">
31+
<img src="docs/assets/model-picker-jev-auto.png" alt="Codex model picker with Jev Auto Router" width="860" />
32+
</p>
1233

13-
The control loop: pick → gate → run → learn.
34+
---
35+
36+
## 30-second version
37+
38+
If you use Codex and often spend `frontier + high effort` on routine turns:
39+
40+
- **one Jev decision per user turn**, not per model call;
41+
- **the model stays pinned** through the tool loop, avoiding repeated prefix rebuilds;
42+
- **effort is the fine control**, changed through `configuration_update` while preserving cache;
43+
- price break-even, cache warmth, session guards and upgrade triggers are deterministic policy;
44+
- supports **Codex CLI** and the **Codex app**.
45+
46+
> **Status:** `v0.1.0` alpha; 63 deterministic tests pass; live GPT cache/quality evaluation is still pending. Effort routing is off by default.
47+
48+
## What it does
49+
50+
| Capability | What it means |
51+
| --- | --- |
52+
| Turn-pinned routing | One Jev decision per user turn; the model does not change inside the tool loop |
53+
| Effort routing | Same model; low/medium/high/xhigh/max can move per turn |
54+
| Cache-aware gates | Price break-even, cache warmth, large-context and session guards |
55+
| Codex CLI | `jev-codex` launches real Codex with the `Jev Auto Router` entry |
56+
| Codex app | `jev-codex setup-app` configures the local provider and model catalog |
57+
| Evidence | 63 deterministic tests; a live savings evaluation plan is in the repo |
58+
59+
- Design notes: [docs/codex-turn-router.md](docs/codex-turn-router.md)
60+
- Evaluation plan: [docs/evaluation-plan.md](docs/evaluation-plan.md)
61+
- Releasing: [docs/releasing.md](docs/releasing.md)
1462

15-
- Usage, configuration and design trade-offs: [docs/codex-turn-router.md](docs/codex-turn-router.md)
16-
- Test samples and methods: [docs/evaluation-plan.md](docs/evaluation-plan.md)
1763

1864
## Install
1965

20-
After the npm package is published:
66+
> [!IMPORTANT]
67+
> The npm registry release does not exist yet (`npm view jev-auto-router` returns 404). Use the source install now; the npm commands below become available after the first publish.
68+
69+
### From source (available now)
70+
71+
```sh
72+
git clone https://github.com/miniLV/Jev-Auto-Router.git
73+
cd Jev-Auto-Router
74+
npm ci
75+
npm run build
76+
npm link
77+
jev-codex
78+
```
79+
80+
### npm (after release)
2181

2282
```sh
2383
npm install -g jev-auto-router
2484
jev-codex
2585
```
2686

27-
Or run it without a global install:
87+
Or:
2888

2989
```sh
3090
npx -y jev-auto-router
3191
```
3292

33-
From source:
93+
### Codex app
3494

3595
```sh
36-
git clone https://github.com/miniLV/Jev-Auto-Router.git
37-
cd Jev-Auto-Router
38-
npm ci
39-
npm run build
40-
npm link
41-
jev-codex
96+
jev-codex setup-app
4297
```
4398

99+
Then fully quit and reopen the ChatGPT/Codex app, create a new task, and select `Jev Auto Router`. See [Codex app](#codex-app) and [releasing](docs/releasing.md).
100+
44101
## Result: one extra model in the picker
45102

46103
`jev-codex` does not fork Codex. It launches the real Codex CLI, injects a temporary provider, and (by default) adds one virtual model to the Codex CLI model picker / `/model`:
@@ -123,7 +180,7 @@ Illustrative, not a measured bill. Real savings depend on the cache hit rate, th
123180
> [!WARNING]
124181
> Alpha: effort routing is off by default, and `configuration_update` has not been validated against a live Codex + GPT cache yet. Set `JEV_CODEX_EFFORT_ROUTING=turn` for a small smoke test before enabling it long-term.
125182
126-
## Quickstart
183+
## Usage
127184

128185
Requires Node.js 22+, a signed-in Codex CLI, and a TypeSafe Jev key.
129186

@@ -246,6 +303,15 @@ src/codex-router/
246303
- Encrypted reasoning cleanup is opt-in; compaction still needs live-session tests.
247304
- Commentary modifies the Codex event stream; set `JEV_CODEX_COMMENTARY=0` for byte-identical forwarding.
248305

306+
## Release status
307+
308+
- Version: `0.1.0`
309+
- Git tag: `v0.1.0`
310+
- npm registry: **not published**
311+
- Release process: [docs/releasing.md](docs/releasing.md)
312+
- CI: `.github/workflows/ci.yml`
313+
- Release workflow: `.github/workflows/release.yml` (tag `v*` or manual)
314+
249315
## License
250316

251317
[Apache License 2.0](LICENSE)

‎README.md‎

Lines changed: 85 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,103 @@
1-
# Jev Auto Router
1+
<h1 align="center">Jev Auto Router</h1>
22

3-
**[中文](README.md)** | [English](README.en.md)
3+
<p align="center">
4+
<strong>Codex 一轮对话，一次模型选择。</strong>
5+
</p>
46

5-
**Codex 一轮对话，一次模型选择。** `jev-codex` 启动真实的 Codex CLI，在模型选择器里加入虚拟模型 `jev-auto`；每个新 user turn 问一次 [TypeSafe Jev](https://docs.typesafe.ai/introduction)，然后把选中的模型固定到这一轮的整个 tool loop。
7+
<p align="center">
8+
<code>jev-codex</code> 启动真实 Codex CLI，在 model picker 里加入 <code>Jev Auto Router</code>；每个新 user turn 问一次 TypeSafe Jev，模型固定跑完整个 tool loop，effort 用 cache-preserving 的 <code>configuration_update</code> 调整。
9+
</p>
610

7-
这是 **turn-pinned Codex router** 的第一版。它优先保证能跑、切换少、缓存友好；旧逐调用路径已经从主入口移除。
11+
<p align="center">
12+
<a href="https://github.com/miniLV/Jev-Auto-Router/tags">Releases</a> ·
13+
<a href="https://minilv.github.io/Jev-Auto-Router/">Homepage</a> ·
14+
<strong>简体中文</strong> ·
15+
<a href="./README.en.md">English</a>
16+
</p>
817

9-
![Codex Turn Router 主流程](docs/assets/codex-turn-router-flow.png)
18+
<p align="center">
19+
<a href="https://github.com/miniLV/Jev-Auto-Router/actions/workflows/ci.yml">
20+
<img alt="CI" src="https://github.com/miniLV/Jev-Auto-Router/actions/workflows/ci.yml/badge.svg" />
21+
</a>
22+
<img alt="Release v0.1.0" src="https://img.shields.io/badge/release-v0.1.0-blue" />
23+
<a href="./LICENSE">
24+
<img alt="License" src="https://img.shields.io/github/license/miniLV/Jev-Auto-Router" />
25+
</a>
26+
<img alt="Node 22+" src="https://img.shields.io/badge/node-22%2B-339933" />
27+
<img alt="npm not published" src="https://img.shields.io/badge/npm-not%20published-lightgrey" />
28+
</p>
1029

11-
![Codex Turn Router 控制回路](docs/assets/codex-turn-router-control-plane.png)
30+
<p align="center">
31+
<img src="docs/assets/model-picker-jev-auto.png" alt="Codex model picker with Jev Auto Router" width="860" />
32+
</p>
1233

13-
控制回路：选 → 闸 → 跑 → 学。
34+
---
35+
36+
## 30 秒看懂
37+
38+
如果你用 Codex，并且经常用 `frontier + high effort` 处理本来很简单的 turn，这个项目解决的就是这件事：
39+
40+
- **一个 user turn 只问一次 Jev**，不是每次 model call 都问；
41+
- **模型固定**到这一轮的整个 tool loop，避免反复重建 prompt cache；
42+
- **effort 单独调整**，用 `configuration_update` 保留 cache；
43+
- 价格 break-even、缓存热度、session 稳定和升级触发都由本地 policy 决定；
44+
- 支持 **Codex CLI** 和 **Codex app**。
45+
46+
> **当前状态：** `v0.1.0` alpha；63 个确定性测试通过；真实 GPT cache/质量评测还在补。effort routing 默认关闭。
47+
48+
## 能做什么
49+
50+
| 能力 | 说明 |
51+
| --- | --- |
52+
| Turn-pinned routing | 一个 user turn 一次 Jev 决策；tool loop 内模型不变 |
53+
| Effort routing | 模型不变，按 turn 调整 low/medium/high/xhigh/max |
54+
| Cache-aware gates | 价格 break-even、cache 热度、大上下文和 session 稳定保护 |
55+
| Codex CLI | `jev-codex` 启动真实 Codex，并注入 `Jev Auto Router` |
56+
| Codex app | `jev-codex setup-app` 配置本地 provider 和 model catalog |
57+
| Evidence | 63 个确定性测试；真实收益评测计划已落地 |
58+
59+
- 设计文档：[docs/codex-turn-router.md](docs/codex-turn-router.md)
60+
- 评测计划：[docs/evaluation-plan.md](docs/evaluation-plan.md)
61+
- 发布说明：[docs/releasing.md](docs/releasing.md)
1462

15-
- 使用、配置与设计取舍：[docs/codex-turn-router.md](docs/codex-turn-router.md)
16-
- 测试样本与方法：[docs/evaluation-plan.md](docs/evaluation-plan.md)
1763

1864
## 安装
1965

20-
发布到 npm 后：
66+
> [!IMPORTANT]
67+
> npm registry 版本还没有发布（`npm view jev-auto-router` 是 404）。当前请从源码安装；npm 发布后再使用下面的 npm 命令。
68+
69+
### 从源码（当前可用）
70+
71+
```sh
72+
git clone https://github.com/miniLV/Jev-Auto-Router.git
73+
cd Jev-Auto-Router
74+
npm ci
75+
npm run build
76+
npm link
77+
jev-codex
78+
```
79+
80+
### npm（发布后可用）
2181

2282
```sh
2383
npm install -g jev-auto-router
2484
jev-codex
2585
```
2686

27-
或者不全局安装：
87+
或者：
2888

2989
```sh
3090
npx -y jev-auto-router
3191
```
3292

33-
从源码：
93+
### Codex app
3494

3595
```sh
36-
git clone https://github.com/miniLV/Jev-Auto-Router.git
37-
cd Jev-Auto-Router
38-
npm ci
39-
npm run build
40-
npm link
41-
jev-codex
96+
jev-codex setup-app
4297
```
4398

99+
然后完全退出并重开 ChatGPT/Codex app，新建 task，选择 `Jev Auto Router`。详见下面的 [Codex app](#codex-app) 和 [发布说明](docs/releasing.md)。
100+
44101
## 结果：model list 里多一个 `jev-auto`
45102

46103
`jev-codex` 不需要 fork Codex。它启动真实的 Codex CLI，注入一个临时 provider；默认启动时，在 Codex CLI 的 model picker / `/model` 里会多出一个虚拟模型：
@@ -123,7 +180,7 @@ Session
123180
> [!WARNING]
124181
> Alpha：effort routing 默认关闭，且 `configuration_update` 的实机 cache 行为还没有在真实 Codex + GPT 会话中验证。先设 `JEV_CODEX_EFFORT_ROUTING=turn` 做一次小任务 smoke，再长期开启。
125182
126-
## 快速开始
183+
## 运行
127184

128185
需要 Node.js 22+、已登录的 Codex CLI、TypeSafe Jev key。
129186

@@ -246,6 +303,15 @@ src/codex-router/
246303
- encrypted reasoning 清理是 opt-in，压缩行为仍需要实机验证。
247304
- commentary 会修改 Codex 事件流；需要字节级原样转发时设 `JEV_CODEX_COMMENTARY=0`。
248305

306+
## 发布与版本
307+
308+
- 当前版本：`0.1.0`
309+
- Git tag：`v0.1.0`
310+
- npm registry：**尚未发布**
311+
- 发布流程：[docs/releasing.md](docs/releasing.md)
312+
- CI：`.github/workflows/ci.yml`
313+
- Release workflow：`.github/workflows/release.yml`（tag `v*` 或手动触发）
314+
249315
## License
250316

251317
[Apache License 2.0](LICENSE)

0 commit comments

Comments
 (0)