diff --git a/README.md b/README.md index 75b09de1..1beb782d 100644 --- a/README.md +++ b/README.md @@ -26,14 +26,16 @@
-# 🐋🔥 DeepSeek Prefix Cache +# 🌿✂️ /eco Token Compression -# Run long agentic coding sessions for *pennies* +# Same session, **80% fewer** Bash-output tokens -### Cache-hit input bills at **`~$0.0435` / 1M tokens** — about **230× cheaper** than Claude Fable 5 (`$10` / 1M). +### Measured, not estimated: 27 real command outputs replayed through the production pipeline — **92,989 → 17,767 tokens (-80%)**. Failure summaries keep the error lines that matter; anything lossy is teed to disk, one `tail` away. -ClawCodex keeps your request prefix **byte-stable**, so DeepSeek's prompt cache covers your whole -`system + tools + history` span across turns. **The longer you code, the more you save.** +One toggle, deterministic filters — failure-focused test summaries, `git`/`pip`/`npm` ceremony +stripping, log dedup, recoverable head-caps — guarded to be **never worse** than the raw rendering. +Stacks with the DeepSeek prefix cache: the cache makes your stable prefix nearly free, `/eco` +shrinks the fresh suffix every turn actually pays for. **[See the measured benchmark ↓](#eco-benchmark)**
@@ -101,6 +103,7 @@ The `session`, `settings`, and `env` blocks are optional — sensible defaults a ## 📰 News +- **2026-07-13:** **`/eco` token compression — -80% Bash-output tokens, measured, now the headline (#708, #712)** — a new session toggle compresses the model-bound rendering of every Bash result with deterministic filters ported from [RTK](https://github.com/rtk-ai/rtk)'s method set: failure-focused test summaries (kept error lines are never rewritten), `git`/`pip`/`npm` ceremony stripping, log dedup with `[×N]` counts, and a recoverable head-cap — all behind a **never-worse** guard, with every lossy compression teeing the full output to disk behind a runnable recovery hint (#708). A reproducible benchmark (`eval/eco/`) replays 27 real command outputs through the exact production pipeline and counts real tokenizer tokens: **92,989 → 17,767 (-80%)** corpus-wide, -88% on filter hits, plus an honestly conservative recompute of RTK's own 30-minute-session model (-19% under their averaged assumptions — real sessions are fat-tailed) (#712). Full tables: the [`/eco` section](#eco-benchmark) and [`eval/eco/results/`](eval/eco/results/results.md). - **2026-07-12 (v1.1.0):** **ClawCodex v1.1.0 — run OpenAI *and* Claude models on your subscription, not metered API billing** — the headline of 1.1.0 is **subscription auth for the two biggest model families**, so you can point ClawCodex at a plan you already pay for. **Sign in with ChatGPT (#698):** `clawcodex login → openai → subscription` (browser, device-code, or import from an existing Codex CLI login) routes requests through the ChatGPT Codex backend's Responses API — `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, and `gpt-5.3-codex-spark` on your Plus/Pro allowance, with encrypted-reasoning replay across turns and **$0** metered cost. **Claude Pro/Max (#697):** `clawcodex login → anthropic → subscription` connects a Claude subscription via OAuth (PKCE) with automatic token refresh and the same $0 accounting; follow-ups repaired the login after Anthropic moved its OAuth endpoints to `platform.claude.com` (#702) and stopped sending adaptive thinking to models that don't support it (#699). A configured API key always wins, and subscription usage reports `billing_mode: subscription`. **More models:** a Meta (`api.meta.ai`) provider with the 1M-context `muse-spark-1.1` reasoning model (#692) and refreshed MiniMax parameters (#696). **Workflow & TUI:** `/plan` mode with implicit plan-mode entry/exit (#676), `--worktree/-w` session isolation for parallel runs in separate git worktrees (#672), the `/memory` picker + `$EDITOR` spawn (#693), config/state directories rebranded `.claude → .clawcodex` with a one-time migration (#678), `/logo` startup color schemes (#677), plus TUI polish — Tab accepts the suggested placeholder (#690), past inputs get the Claude-Code highlight band (#691), clickable agent URLs (#694), and a per-terminal link-open affordance (#701). **Quality:** semantic tool-input coercion with parity validation errors (#700) and looser, Claude-Code-faithful permission granting (#673). - **2026-07-07:** **`/loop` scheduled tasks now actually fire — full port of Claude Code's session-scoped scheduler (#680)** — the bundled `/loop` skill finally has a real engine behind it: a new `src/scheduled_tasks` module parses standard 5-field cron expressions and fires due prompts **between turns** from the agent-server's idle poll. `CronCreate`/`CronList`/`CronDelete` register real firing jobs (8-char IDs, 50-job cap, deterministic jitter, 7-day recurring expiry with one final fire), and the new **`ScheduleWakeup`** tool drives self-paced `/loop` mode — the model picks each next delay (1 min–1 hr), `stop: true` ends the loop, and a ~20-minute fallback wakeup catches iterations that forget to reschedule. Typed skill slash commands now reach the backend (new `skill_command` control), so `/loop 5m check ci` works from the composer with completion + argument hint; the TUI shows a live countdown indicator (`⟳ loop wakeup in 2m 14s · ⏰ 1 scheduled`) and **Esc while idle stops a waiting loop**. `/clear` drops session tasks, `--resume` restores unexpired ones, `CLAWCODEX_DISABLE_CRON=1` disables the scheduler. 117 new tests; verified live over stdio NDJSON and a real PTY TUI drive (typed dispatch → CronCreate → a real wakeup fire between turns → Esc-stop). - **2026-07-07:** **Bounded the ESC-cancel chunk queue in OpenAI-compatible streaming (#278)** — `OpenAICompatibleProvider.chat_stream_response`'s worker-thread queue (added in #148) was an unbounded `queue.Queue`. A non-graceful disconnect from a proxy that keeps sending bytes after ESC (and never closes the SDK iterator) let the orphaned worker thread accumulate chunks in memory indefinitely. The queue is now capped at 64 chunks, so `put()` blocks the worker once full instead of growing without bound. @@ -110,7 +113,6 @@ The `session`, `settings`, and `env` blocks are optional — sensible defaults a - **2026-06-23:** **One-click installer** — `curl -fsSL https://clawcodex.app/install.sh | bash` installs uv (no sudo), provisions Python 3.10+, clones to `~/.clawcodex`, creates a lock-pinned venv, and registers `clawcodex` on PATH; ships status / doctor / verify / update / uninstall subcommands, is safe to re-run, and works on macOS / Linux / WSL. - **2026-06-21:** **18 new LLM providers — the registry grows 7 → 25 (#377)** — a data-driven `ProviderSpec` registry adds 18 OpenAI-compatible backends (nvidia-nim, fireworks, together, moonshot/Kimi, novita, siliconflow, deepinfra, stepfun, arcee, huggingface, volcengine, xiaomi-mimo, atlascloud, wanjie-ark, plus local ollama / vllm / sglang) alongside the hand-written providers; alias-aware config resolution, standard env-var key fallback (e.g. `TOGETHER_API_KEY`), and keyless local servers. - **2026-06-18:** **DeepSeek prefix-cache exploitation — a HUGE token-cost win (#363)** — ClawCodex now keeps its request prefix **byte-stable** across turns so DeepSeek's automatic prompt-prefix cache covers the entire `system + tools + history` span. Per-request-volatile sections (env, the mutable `MEMORY.md` body, plan-mode, etc.) are relocated to a trailing `` *after* the conversation history, so the cached prefix never breaks even when memory/env change. We also register DeepSeek's **1M-token context window**, map its prompt-cache usage onto the Anthropic `cache_read_input_tokens` convention, and surface a per-model **prompt-cache hit-rate** + cost in `/cost`. **Why this is enormous — the token economics:** Claude Fable 5 runs **$10 / $50** per 1M input/output tokens, while **DeepSeek-V4-Pro is just $0.435 / $0.87** — already **~23× cheaper on input** and **~57× cheaper on output**. And because **cache-hit input is billed at only 10%** of the normal input rate, the long, context-heavy sessions that agentic coding actually produces pay just **~$0.0435 per 1M input tokens** — roughly **230× cheaper than Fable 5 input**. The token efficiency ClawCodex unlocks here is **HUGE**. Everything is gated to the `deepseek` provider — every other provider's request is byte-for-byte unchanged. Follow-up: truncated tool-call argument JSON is now best-effort recovered in the shared OpenAI-compatible layer, so an interrupted DeepSeek stream keeps its partial tool args instead of dropping them to `{}` (#364). -- **2026-06-16:** **Z.ai GLM-5.2 support (#343)** — new `zai` provider for Z.ai's OpenAI-compatible GLM Coding Plan (`https://api.z.ai/api/coding/paas/v4`), shipping `GLM-5.1` and the `GLM-5.2` preview; GLM-5.2 delivers coding capability comparable to Claude Opus 4.7. First app built end-to-end with GLM-5.2 — a [FIFA World Cup 2026 intro page](demos/wc26-intro/index.html) (animated hero + live countdown, three host nations, 16 stadiums, tournament format, and record-breaking facts). 📚 Older items have moved to the full **[News archive](docs/NEWS.md)**. *** @@ -147,6 +149,8 @@ Reproduce locally — see [`eval/README.md`](eval/README.md) for the full workfl *** + + ## 🌿 `/eco` Token Compression — **-80% Bash-output tokens, measured** Long agentic sessions drown in tool output: failing test logs, `git` progress spam, @@ -256,8 +260,8 @@ rewriting commands. interrupted runs are never altered; any filter exception falls back to passthrough. `/eco status` shows per-filter savings for the session. Compression stacks with the -[DeepSeek prefix cache](#-deepseek-prefix-cache): the cache makes the stable prefix -nearly free, `/eco` shrinks the fresh suffix every turn actually pays for. Reproduce: +**DeepSeek prefix cache** (see [News](#-news), 2026-06-18): the cache makes the stable +prefix nearly free, `/eco` shrinks the fresh suffix every turn actually pays for. Reproduce: ```bash python3 eval/eco/capture_corpus.py --workdir /tmp/eco-bench # capture real outputs diff --git a/docs/NEWS.md b/docs/NEWS.md index 29b08b6a..5396ff8a 100644 --- a/docs/NEWS.md +++ b/docs/NEWS.md @@ -2,6 +2,7 @@ Full news history for ClawCodex. The [README News section](../README.md#-news) keeps only the 10 most recent items. +- **2026-07-13:** **`/eco` token compression — -80% Bash-output tokens, measured, now the headline (#708, #712)** — a new session toggle compresses the model-bound rendering of every Bash result with deterministic filters ported from [RTK](https://github.com/rtk-ai/rtk)'s method set: failure-focused test summaries (kept error lines are never rewritten), `git`/`pip`/`npm` ceremony stripping, log dedup with `[×N]` counts, and a recoverable head-cap — all behind a **never-worse** guard, with every lossy compression teeing the full output to disk behind a runnable recovery hint (#708). A reproducible benchmark (`eval/eco/`) replays 27 real command outputs through the exact production pipeline and counts real tokenizer tokens: **92,989 → 17,767 (-80%)** corpus-wide, -88% on filter hits, plus an honestly conservative recompute of RTK's own 30-minute-session model (-19% under their averaged assumptions — real sessions are fat-tailed) (#712). Full tables: the [`/eco` section](../README.md#eco-benchmark) and [`eval/eco/results/`](../eval/eco/results/results.md). - **2026-07-12 (v1.1.0):** **ClawCodex v1.1.0 — run OpenAI *and* Claude models on your subscription, not metered API billing** — the headline of 1.1.0 is **subscription auth for the two biggest model families**, so you can point ClawCodex at a plan you already pay for. **Sign in with ChatGPT (#698):** `clawcodex login → openai → subscription` (browser, device-code, or import from an existing Codex CLI login) routes requests through the ChatGPT Codex backend's Responses API — `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, and `gpt-5.3-codex-spark` on your Plus/Pro allowance, with encrypted-reasoning replay across turns and **$0** metered cost. **Claude Pro/Max (#697):** `clawcodex login → anthropic → subscription` connects a Claude subscription via OAuth (PKCE) with automatic token refresh and the same $0 accounting; follow-ups repaired the login after Anthropic moved its OAuth endpoints to `platform.claude.com` (#702) and stopped sending adaptive thinking to models that don't support it (#699). A configured API key always wins, and subscription usage reports `billing_mode: subscription`. **More models:** a Meta (`api.meta.ai`) provider with the 1M-context `muse-spark-1.1` reasoning model (#692) and refreshed MiniMax parameters (#696). **Workflow & TUI:** `/plan` mode with implicit plan-mode entry/exit (#676), `--worktree/-w` session isolation for parallel runs in separate git worktrees (#672), the `/memory` picker + `$EDITOR` spawn (#693), config/state directories rebranded `.claude → .clawcodex` with a one-time migration (#678), `/logo` startup color schemes (#677), plus TUI polish — Tab accepts the suggested placeholder (#690), past inputs get the Claude-Code highlight band (#691), clickable agent URLs (#694), and a per-terminal link-open affordance (#701). **Quality:** semantic tool-input coercion with parity validation errors (#700) and looser, Claude-Code-faithful permission granting (#673). - **2026-07-07:** **`/loop` scheduled tasks now actually fire — full port of Claude Code's session-scoped scheduler (#680)** — the bundled `/loop` skill finally has a real engine behind it: a new `src/scheduled_tasks` module parses standard 5-field cron expressions and fires due prompts **between turns** from the agent-server's idle poll. `CronCreate`/`CronList`/`CronDelete` register real firing jobs (8-char IDs, 50-job cap, deterministic jitter, 7-day recurring expiry with one final fire), and the new **`ScheduleWakeup`** tool drives self-paced `/loop` mode — the model picks each next delay (1 min–1 hr), `stop: true` ends the loop, and a ~20-minute fallback wakeup catches iterations that forget to reschedule. Typed skill slash commands now reach the backend (new `skill_command` control), so `/loop 5m check ci` works from the composer with completion + argument hint; the TUI shows a live countdown indicator (`⟳ loop wakeup in 2m 14s · ⏰ 1 scheduled`) and **Esc while idle stops a waiting loop**. `/clear` drops session tasks, `--resume` restores unexpired ones, `CLAWCODEX_DISABLE_CRON=1` disables the scheduler. 117 new tests; verified live over stdio NDJSON and a real PTY TUI drive (typed dispatch → CronCreate → a real wakeup fire between turns → Esc-stop). - **2026-07-07:** **Bounded the ESC-cancel chunk queue in OpenAI-compatible streaming (#278)** — `OpenAICompatibleProvider.chat_stream_response`'s worker-thread queue (added in #148) was an unbounded `queue.Queue`. A non-graceful disconnect from a proxy that keeps sending bytes after ESC (and never closes the SDK iterator) let the orphaned worker thread accumulate chunks in memory indefinitely. The queue is now capped at 64 chunks, so `put()` blocks the worker once full instead of growing without bound. diff --git a/docs/i18n/README_ZH.md b/docs/i18n/README_ZH.md index 4e7c1157..a35b90a2 100644 --- a/docs/i18n/README_ZH.md +++ b/docs/i18n/README_ZH.md @@ -63,6 +63,7 @@ python -m src.cli --dangerously-skip-permissions # 启动 REPL ## 📰 新闻 +- **2026-07-13：** **`/eco` token 压缩 —— Bash 输出 token 实测 -80%，并登上（英文版）头条（#708、#712）** —— 新的会话开关用一组从 [RTK](https://github.com/rtk-ai/rtk) 方法集移植的确定性过滤器压缩每个 Bash 结果的模型侧渲染：聚焦失败的测试摘要（保留的错误行从不改写）、`git`/`pip`/`npm` 仪式性输出裁剪、带 `[×N]` 计数的日志去重、可恢复的头部截断 —— 全部处于**绝不更差**守卫之下，所有有损压缩都会把完整输出 tee 到磁盘并附一条可直接运行的恢复提示（#708）。可复现的基准测试（`eval/eco/`）将 27 个真实命令输出经由生产管线逐字节重放并统计真实分词器 token：语料整体 **92,989 → 17,767（-80%）**，过滤器命中子集 -88%，另附对 RTK 自身 30 分钟会话模型的保守重算（在其平均化假设下为 -19% —— 真实会话是重尾分布）（#712）。完整表格见下文 `/eco` 章节与 [`eval/eco/results/`](../../eval/eco/results/results.md)。 - **2026-07-12（v1.1.0）：** **ClawCodex v1.1.0 —— 用订阅方案运行 OpenAI 和 Claude 模型，而非按 API 计费** —— 1.1.0 的重头戏是**为两大模型家族提供订阅认证**，让你可以把 ClawCodex 接到你已经付费的方案上。**用 ChatGPT 登录（#698）：** `clawcodex login → openai → subscription`（浏览器、设备码，或从已有的 Codex CLI 登录导入）通过 ChatGPT Codex 后端的 Responses API 路由请求 —— 在你的 Plus/Pro 额度内使用 `gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini` 与 `gpt-5.3-codex-spark`，跨轮次重放加密推理，计费为 **$0**。**Claude Pro/Max（#697）：** `clawcodex login → anthropic → subscription` 通过 OAuth（PKCE）连接 Claude 订阅，自动刷新 token，同样按 $0 计账；后续修复了 Anthropic 将 OAuth 端点迁移到 `platform.claude.com` 后的登录（#702），并停止向不支持自适应思考（adaptive thinking）的模型发送该参数（#699）。已配置的 API key 始终优先，订阅用量报告为 `billing_mode: subscription`。**更多模型：** 新增 Meta（`api.meta.ai`）provider 及 1M 上下文的 `muse-spark-1.1` 推理模型（#692），并刷新 MiniMax 参数（#696）。**工作流与 TUI：** `/plan` 模式及隐式 plan 模式进入/退出（#676）、`--worktree/-w` 会话隔离（在独立 git worktree 中并行运行，#672）、`/memory` 选择器 + `$EDITOR` 打开（#693）、配置/状态目录从 `.claude` 更名为 `.clawcodex` 并一次性迁移（#678）、`/logo` 启动配色（#677），以及 TUI 打磨 —— Tab 接受建议占位符（#690）、历史输入显示 Claude Code 高亮条（#691）、可点击的 agent URL（#694）、按终端适配的链接打开提示（#701）。**质量：** 语义化工具输入强制转换与对齐的校验错误信息（#700），以及更宽松、忠于 Claude Code 的权限授予（#673）。 - **2026-07-07：** **`/loop` 定时任务现在真正触发 —— 完整移植 Claude Code 的会话级调度器（#680）** —— 内置的 `/loop` 技能终于有了真正的引擎：新的 `src/scheduled_tasks` 模块解析标准 5 字段 cron 表达式，并在 agent-server 空闲轮询时**在轮次之间**触发到期的提示。`CronCreate`/`CronList`/`CronDelete` 注册真正触发的任务（8 字符 ID、50 个任务上限、确定性抖动、7 天循环到期并最后触发一次），新的 **`ScheduleWakeup`** 工具驱动自定节奏的 `/loop` 模式 —— 模型自行挑选每次的下一个延迟（1 分钟–1 小时），`stop: true` 结束循环，约 20 分钟的回退唤醒兜底忘记重新调度的迭代。带类型的技能斜杠命令现在可达后端（新的 `skill_command` 控制），因此 `/loop 5m check ci` 可从 composer 键入运行，带补全与参数提示；TUI 显示实时倒计时指示（`⟳ loop wakeup in 2m 14s · ⏰ 1 scheduled`），且**空闲时按 Esc 停止等待中的循环**。`/clear` 丢弃会话任务，`--resume` 恢复未到期的任务，`CLAWCODEX_DISABLE_CRON=1` 禁用调度器。117 个新测试；已在 stdio NDJSON 与真实 PTY TUI 驱动下实测验证。 - **2026-07-07：** **为 OpenAI 兼容流式传输的 ESC 取消块队列设置上限（#278）** —— `OpenAICompatibleProvider.chat_stream_response` 的工作线程队列（#148 引入）此前是无上限的 `queue.Queue`。当代理在 ESC 后仍持续发送字节（且从不关闭 SDK 迭代器）时，被孤立的工作线程会无限累积内存中的块。队列现在上限为 64 个块，队满后 `put()` 阻塞工作线程而非无限增长。 @@ -72,7 +73,6 @@ python -m src.cli --dangerously-skip-permissions # 启动 REPL - **2026-06-23：** **一键安装器** —— `curl -fsSL https://clawcodex.app/install.sh | bash` 自动安装 uv（无需 sudo）、准备 Python 3.10+、克隆到 `~/.clawcodex`、创建锁定版本的 venv，并把 `clawcodex` 注册到 PATH；附带 status / doctor / verify / update / uninstall 子命令，可安全重复运行，支持 macOS / Linux / WSL。 - **2026-06-21：** **新增 18 个 LLM provider —— 注册表从 7 增至 25（#377）** —— 数据驱动的 `ProviderSpec` 注册表在手写 provider 之外新增 18 个 OpenAI 兼容后端（nvidia-nim、fireworks、together、moonshot/Kimi、novita、siliconflow、deepinfra、stepfun、arcee、huggingface、volcengine、xiaomi-mimo、atlascloud、wanjie-ark，以及本地 ollama / vllm / sglang）；支持别名感知的配置解析、标准环境变量密钥回退（如 `TOGETHER_API_KEY`）与免密钥的本地服务器。 - **2026-06-18：** **DeepSeek 前缀缓存利用 —— 巨大的 token 成本优势（#363）** —— ClawCodex 现在让请求前缀在多轮之间保持**字节级稳定**，使 DeepSeek 的自动 prompt 前缀缓存覆盖整个 `system + tools + history` 区段。每请求可变的部分（env、可变的 `MEMORY.md` 正文、plan 模式等）被移到对话历史*之后*的尾部 ``，即使 memory/env 变化也不会击穿缓存前缀。同时注册 DeepSeek 的 **1M token 上下文窗口**，把其 prompt 缓存用量映射到 Anthropic 的 `cache_read_input_tokens` 约定，并在 `/cost` 中展示每模型的**缓存命中率**与成本。**为什么意义重大 —— token 经济学：** Claude Fable 5 每 1M 输入/输出 token 收费 **$10 / $50**，而 **DeepSeek-V4-Pro 仅为 $0.435 / $0.87** —— 输入已**便宜约 23×**、输出**便宜约 57×**。由于**缓存命中的输入仅按正常输入价的 10% 计费**，agentic 编码实际产生的长上下文会话每 1M 输入 token 只需**约 $0.0435** —— 比 Fable 5 的输入**便宜约 230×**。ClawCodex 在这里解锁的 token 效率是**巨大的**。全部逻辑仅对 `deepseek` provider 生效 —— 其他 provider 的请求逐字节不变。后续修复：被截断的工具调用参数 JSON 现在会在共享的 OpenAI 兼容层尽力恢复，DeepSeek 流中断时保留部分工具参数而不是丢弃为 `{}`（#364）。 -- **2026-06-16：** **Z.ai GLM-5.2 支持（#343）** —— 新增 `zai` provider，对接 Z.ai 的 OpenAI 兼容 GLM 编程套餐（`https://api.z.ai/api/coding/paas/v4`），提供 `GLM-5.1` 与 `GLM-5.2` 预览版；GLM-5.2 的编码能力可比肩 Claude Opus 4.7。首个用 GLM-5.2 端到端生成的应用——一个 [2026 世界杯介绍页](../../demos/wc26-intro/index.html)（动效首屏 + 实时倒计时、三个主办国、16 座球场、赛制说明与破纪录数据）。 📚 更早的条目已移至完整的 **[News 归档](../NEWS.md)**。