reasonix 0.15.0 → 0.16.1

package/README.md

@@ -72,7 +72,26 @@ command list.
 
 ---
 
-## Web dashboard *(new in 0.12)*
+## At a glance
+
+|                                    | Reasonix       | Claude Code    | Cursor         | Aider          |
+|------------------------------------|----------------|----------------|----------------|----------------|
+| Backend                            | DeepSeek V4    | Anthropic      | OpenAI / Anthropic | any        |
+| Cost / typical task                | **~$0.001–0.005** | ~$0.05–0.50 | $20/mo + usage | varies         |
+| Where it runs                      | terminal       | terminal + IDE | IDE (Electron) | terminal       |
+| License                            | **MIT**        | closed         | closed         | Apache 2       |
+| DeepSeek prefix-cache hit rate     | **90.2%**      | n/a            | n/a            | ~33%           |
+| Reviewable edits (no auto-write)   | **yes** (`/apply`) | yes        | partial        | yes            |
+| MCP servers                        | **first-class**| first-class    | —              | —              |
+
+Numbers from `benchmarks/tau-bench-lite` (8 multi-turn coding tasks ×
+3 repeats, live `deepseek-chat`). Same workload, sole variable is
+prefix stability — committed transcripts in [`benchmarks/`](./benchmarks/).
+The full feature comparison [is below](#why-reasonix-vs-cursor--claude-code--cline--aider).
+
+---
+
+## Web dashboard
 
 Type `/dashboard` inside any session and Reasonix prints a localhost
 URL with a one-time token. Open it for a 13-tab control surface that
@@ -98,15 +117,14 @@ keep alive.
 
 Three things you'd come to Reasonix for, that nothing else combines:
 
-- **The cost economics actually land in your bill.** DeepSeek V4 is
-  ~30× cheaper than Claude Sonnet per token. Cheaper tokens alone
-  isn't the win — *cheap tokens with a 90%+ prefix-cache hit* is.
-  Reasonix's loop is engineered around append-only prompt growth so
-  the cache-stable prefix survives every tool call, which the
-  benchmarks section below verifies end-to-end (94.4% live, vs 46.6%
-  for a generic harness against the same workload). The `/stats`
-  panel tracks "vs Claude Sonnet 4.6" savings every turn so you can
-  watch your bill not happen.
+- **Cost economics that land in your bill.** DeepSeek V4 is ~30×
+  cheaper than Claude Sonnet per token. Cheap tokens alone isn't the
+  win — *cheap tokens with a 90%+ prefix-cache hit* is. Reasonix's
+  loop is engineered around append-only prompt growth so the
+  cache-stable prefix survives every tool call. The benchmarks
+  section verifies this end-to-end: 90.2% live cache hit, versus
+  32.8% for a generic harness on the same workload. The `/stats`
+  panel surfaces "vs Claude Sonnet 4.6" savings on every turn.
 
 - **It lives in your terminal.** Pure CLI — no Electron, no VS Code
   extension, no IDE plugin to wedge into your editor. Sits next to
@@ -136,6 +154,9 @@ Three things you'd come to Reasonix for, that nothing else combines:
 | Cross-session cost dashboard | **yes** (`/stats`) | — | — | — | — |
 | Sandbox boundary enforcement | **strict** (refuses `..` escape) | yes | partial | yes | partial |
 
+<details>
+<summary><strong>When reasonix is the wrong choice · DeepSeek/Anthropic-compat caveats · vs Aider/Cline/Continue</strong></summary>
+
 ### Pick something else when
 
 - **You want multi-provider flexibility** (mix Claude / GPT / Gemini /
@@ -194,8 +215,8 @@ to.
 
 Reasonix's loop was designed around byte-stable prefix from line one.
 No markers, no breakpoints — append-only is the invariant. That's why
-the same τ-bench workload lands at **94.4% cache hit** on Reasonix
-and **46.6%** on a cache-hostile baseline (committed transcripts;
+the same τ-bench workload lands at **90.2% cache hit** on Reasonix
+and **32.8%** on a cache-hostile baseline (committed transcripts;
 benchmarks section below). At DeepSeek's pricing — $0.07/Mtok
 uncached, ~$0.014/Mtok cached — the difference between 50% and 94%
 hit is **roughly 2.5× on input cost alone**.
@@ -223,6 +244,8 @@ handful of DeepSeek-specific quirks generic loops don't handle:
 > CLI — it's an agent CLI built around DeepSeek's specific cache
 > mechanic and pricing model.
 
+</details>
+
 ---
 
 ## `reasonix code` — pair programmer in your terminal
@@ -311,7 +334,7 @@ assistant
 ```
 
 No allowlist gate — user-typed shell = explicit consent. 60s timeout,
-32k char cap, survives session resume since 0.5.14.
+32k char cap, survives session resume.
 
 **`@path/to/file` — inline a file under "Referenced files."** Start
 typing `@` and a picker appears (↑/↓ navigate, Tab/Enter to insert).
@@ -578,6 +601,9 @@ rendering, retries.
 
 ## Commands inside the session
 
+<details>
+<summary><strong>Slash command reference</strong> (click to expand)</summary>
+
 **Core**
 
 | command | what it does |
@@ -654,6 +680,8 @@ rendering, retries.
   in-flight tool, rejects pending MCP requests)
 - `y` / `n` on confirm prompts — hotkey accept / reject
 
+</details>
+
 ---
 
 ## Sessions and safety nets
@@ -755,6 +783,9 @@ Supported transports: **stdio** (local command) and **HTTP+SSE**
 
 ## CLI reference
 
+<details>
+<summary><strong>Commands, flags, env vars</strong> (click to expand)</summary>
+
 ```bash
 npx reasonix code [path]                 # coding mode scoped to path (default: cwd)
 npx reasonix                             # chat (uses saved config)
@@ -794,10 +825,16 @@ export REASONIX_SEARCH=off              # disable web_search / web_fetch
 export REASONIX_UI=plain                # disable live rows (ghosting workaround)
 ```
 
+</details>
+
 ---
 
 ## Library usage
 
+<details>
+<summary><strong>Programmatic API — embed reasonix in your own Node project</strong> (click to expand)</summary>
+
+
 ```ts
 import {
   CacheFirstLoop,
@@ -842,6 +879,8 @@ callers who want the `reasonix code` loop wiring without the CLI
 wrapper. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for
 internals.
 
+</details>
+
 ---
 
 ## Benchmarks — verify the cache-hit claim yourself
@@ -865,9 +904,9 @@ variable prefix stability:
 
 | metric | baseline (cache-hostile) | Reasonix | delta |
 |---|---:|---:|---:|
-| cache hit | 46.6% | **94.4%** | +47.7 pp |
-| cost / task | $0.002599 | $0.001579 | **−39%** |
-| pass rate | 96% (23/24) | **100% (24/24)** | — |
+| cache hit | 32.8% | **90.2%** | +57.4 pp |
+| cost / task | $0.000992 | $0.000593 | **−40%** |
+| pass rate | 100% (24/24) | **100% (24/24)** | — |
 
 **Reproduce without spending an API credit:**
 

package/README.zh-CN.md

@@ -69,7 +69,26 @@ Windows Terminal）。任何时候按 `Esc` 中断；`/help` 查看完整命令
 
 ---
 
-## Web 控制台 *(0.12 新功能)*
+## 一览
+
+|                                  | Reasonix       | Claude Code    | Cursor             | Aider     |
+|----------------------------------|----------------|----------------|--------------------|-----------|
+| 后端                             | DeepSeek V4    | Anthropic      | OpenAI / Anthropic | 任意      |
+| 单任务成本                       | **~$0.001–0.005** | ~$0.05–0.50 | $20/月 + 用量      | 不一      |
+| 运行环境                         | 终端           | 终端 + IDE     | IDE (Electron)     | 终端      |
+| 协议                             | **MIT**        | 闭源           | 闭源               | Apache 2  |
+| DeepSeek 前缀缓存命中率          | **90.2%**      | n/a            | n/a                | ~33%      |
+| 编辑可审 (不自动落盘)            | **支持** (`/apply`) | 支持      | 部分               | 支持      |
+| MCP servers                      | **一等公民**   | 一等公民       | —                  | —         |
+
+数据来自 `benchmarks/tau-bench-lite`（8 个多轮工具任务 × 3 次重放，
+真实 `deepseek-chat`）。同一负载、唯一变量是前缀稳定性 ——
+完整 transcript 提交在 [`benchmarks/`](./benchmarks/) 目录里。详细对比
+见[下方](#为什么选-reasonixvs-cursor--claude-code--cline--aider)。
+
+---
+
+## Web 控制台
 
 会话内输入 `/dashboard`，Reasonix 会打印一个带一次性 token 的本地 URL。
 浏览器打开后是一个 13 个面板的控制面 —— 与正在运行的 TUI 实时双向同步：
@@ -95,9 +114,8 @@ TUI 继续可用 —— 弹窗（shell 确认、plan 审阅、edit 闸门）会
 - **成本节省落到账单上。** DeepSeek V4 的 token 单价大约是 Claude Sonnet
   的 1/30。光便宜还不够 —— *便宜的 token 配上 90%+ 的前缀缓存命中*才是关键。
   Reasonix 的循环按 append-only 增长设计，缓存稳定的前缀在每次工具调用之间
-  都活着，下面的 benchmark 章节端到端验证过：实测 94.4% 缓存命中，对照组通用
-  框架只有 46.6%。`/stats` 面板每轮都跟踪 "vs Claude Sonnet 4.6" 的节省额，
-  你可以亲眼看着账单不涨。
+  都活着，下面的 benchmark 章节端到端验证过：实测 90.2% 缓存命中，对照组通用
+  框架只有 32.8%。`/stats` 面板每轮都跟踪 "vs Claude Sonnet 4.6" 的节省额。
 
 - **它住在终端里。** 纯 CLI —— 没有 Electron，没有 VS Code 插件，没有要
   塞进编辑器的 IDE 插件。和 git、tmux、shell 历史并排。macOS / Linux /
@@ -123,6 +141,9 @@ TUI 继续可用 —— 弹窗（shell 确认、plan 审阅、edit 闸门）会
 | 跨会话成本面板 | **支持**（`/stats`）| — | — | — | — |
 | 沙箱边界强制 | **严格**（拒绝 `..` 逃逸）| 支持 | 部分 | 支持 | 部分 |
 
+<details>
+<summary><strong>什么时候 reasonix 不适合 · DeepSeek/Anthropic-compat 细节 · vs Aider/Cline/Continue</strong></summary>
+
 ### 这些情况下应该选别的
 
 - **你想要多模型混用**（在一个工具里同时切 Claude / GPT / Gemini / 本地 Llama）。
@@ -175,9 +196,9 @@ loop 的 invariant 跟它现在对话的缓存机制不匹配。
 
 Reasonix 的 loop 从第一行起就是按 byte-stable prefix 的不变量设计的。没有
 marker、没有断点 —— append-only 就是 invariant。这就是为什么同一份 τ-bench
-负载在 Reasonix 上是 **94.4% 缓存命中**、在 cache-hostile baseline 上是
-**46.6%**（已 commit 的 transcript，见下面 benchmark 段）。按 DeepSeek 的
-单价 —— $0.07/Mtok 非缓存、约 $0.014/Mtok 缓存命中 —— 50% 和 94% 命中之间
+负载在 Reasonix 上是 **90.2% 缓存命中**、在 cache-hostile baseline 上是
+**32.8%**（已 commit 的 transcript，见下面 benchmark 段）。按 DeepSeek 的
+单价 —— $0.07/Mtok 非缓存、约 $0.014/Mtok 缓存命中 —— 33% 和 90% 命中之间
 **仅 input 这一侧就大约是 2.5× 的差距**。
 
 ### "那 Aider / Cline / Continue 呢？"
@@ -200,6 +221,8 @@ byte-stability 的通用压缩 / 摘要模式。命中率落在和 baseline 同
 > 不是"又一个 agent CLI"，是**围绕 DeepSeek 具体的缓存机制和定价模型
 > 设计的 agent CLI**。
 
+</details>
+
 ---
 
 ## `reasonix code` — 终端里的结对编程
@@ -281,7 +304,7 @@ assistant
 ```
 
 无白名单门 —— 用户主动输入的 shell 命令就是显式同意。60 秒超时、32k 字符
-上限，0.5.14 起会话恢复后依然保留。
+上限，会话恢复后依然保留。
 
 **`@path/to/file` —— 内联一个文件作为 "Referenced files"。** 输入 `@`
 弹出选择器（↑/↓ 切换、Tab/Enter 插入）。比让模型 `read_file` 后再问更省事：
@@ -517,6 +540,9 @@ MCP 工具走和原生工具一样的 Cache-First + 修复 + 上下文安全管
 
 ## 会话内命令
 
+<details>
+<summary><strong>斜杠命令清单</strong>（点击展开）</summary>
+
 **核心**
 
 | 命令 | 作用 |
@@ -592,6 +618,8 @@ MCP 工具走和原生工具一样的 Cache-First + 修复 + 上下文安全管
 - `Esc` —— 中断当前轮（停 API 调用、取消进行中的工具、拒绝待响应的 MCP 请求）
 - 确认弹窗里的 `y` / `n` —— 快捷接受 / 拒绝
 
+</details>
+
 ---
 
 ## 会话与安全网
@@ -680,6 +708,9 @@ spec）。
 
 ## CLI 参考
 
+<details>
+<summary><strong>命令、flags、环境变量</strong>（点击展开）</summary>
+
 ```bash
 npx reasonix code [path]                 # 编程模式，作用域 path（默认 cwd）
 npx reasonix                             # 聊天（用已保存配置）
@@ -719,10 +750,16 @@ export REASONIX_SEARCH=off              # 关闭 web_search / web_fetch
 export REASONIX_UI=plain                # 关闭实时行（鬼影绕开）
 ```
 
+</details>
+
 ---
 
 ## 库用法
 
+<details>
+<summary><strong>程序化 API —— 在自己的 Node 项目里嵌入 reasonix</strong>（点击展开）</summary>
+
+
 ```ts
 import {
   CacheFirstLoop,
@@ -766,6 +803,8 @@ console.log(loop.stats.summary());
 `reasonix code` 的 loop 接线、不要 CLI 包装。详见
 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
 
+</details>
+
 ---
 
 ## 性能对比 —— 缓存命中率自己也能验证
@@ -787,9 +826,9 @@ console.log(loop.stats.summary());
 
 | 指标 | 基线（缓存敌对） | Reasonix | 差值 |
 |---|---:|---:|---:|
-| 缓存命中 | 46.6% | **94.4%** | +47.7 pp |
-| 单任务成本 | $0.002599 | $0.001579 | **−39%** |
-| 通过率 | 96% (23/24) | **100% (24/24)** | — |
+| 缓存命中 | 32.8% | **90.2%** | +57.4 pp |
+| 单任务成本 | $0.000992 | $0.000593 | **−40%** |
+| 通过率 | 100% (24/24) | **100% (24/24)** | — |
 
 **无需消耗 API 额度即可复现：**
 

package/dist/cli/{chunk-7546PPEL.js → chunk-3ALFOYE6.js}

@@ -4,6 +4,24 @@
 import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
 import { join as join4 } from "path";
 
+// src/memory/user.ts
+import { createHash } from "crypto";
+import {
+  existsSync as existsSync3,
+  mkdirSync,
+  readFileSync as readFileSync3,
+  readdirSync as readdirSync2,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join3, resolve as resolve2 } from "path";
+
+// src/skills.ts
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+
 // src/prompt-fragments.ts
 var TUI_FORMATTING_RULES = `Formatting (rendered in a TUI with a real markdown renderer):
 - Tabular data \u2192 GitHub-Flavored Markdown tables with ASCII pipes (\`| col | col |\` header + \`| --- | --- |\` separator). Never use Unicode box-drawing characters (\u2502 \u2500 \u253C \u250C \u2510 \u2514 \u2518 \u251C \u2524) \u2014 they look intentional but break terminal word-wrap and render as garbled columns at narrow widths.
@@ -28,66 +46,7 @@ If you have a search tool (\`search_content\`, \`grep\`, web search), call it FI
 
 If you have no search tool, qualify hard: "I haven't verified \u2014 this is a guess." Never assert absence with fake authority.`;
 
-// src/user-memory.ts
-import { createHash } from "crypto";
-import {
-  existsSync as existsSync3,
-  mkdirSync,
-  readFileSync as readFileSync3,
-  readdirSync as readdirSync2,
-  unlinkSync,
-  writeFileSync
-} from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join3, resolve as resolve2 } from "path";
-
-// src/project-memory.ts
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
-var PROJECT_MEMORY_FILE = "REASONIX.md";
-var PROJECT_MEMORY_MAX_CHARS = 8e3;
-function readProjectMemory(rootDir) {
-  const path = join(rootDir, PROJECT_MEMORY_FILE);
-  if (!existsSync(path)) return null;
-  let raw;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return null;
-  }
-  const trimmed = raw.trim();
-  if (!trimmed) return null;
-  const originalChars = trimmed.length;
-  const truncated = originalChars > PROJECT_MEMORY_MAX_CHARS;
-  const content = truncated ? `${trimmed.slice(0, PROJECT_MEMORY_MAX_CHARS)}
-\u2026 (truncated ${originalChars - PROJECT_MEMORY_MAX_CHARS} chars)` : trimmed;
-  return { path, content, originalChars, truncated };
-}
-function memoryEnabled() {
-  const env = process.env.REASONIX_MEMORY;
-  if (env === "off" || env === "false" || env === "0") return false;
-  return true;
-}
-function applyProjectMemory(basePrompt, rootDir) {
-  if (!memoryEnabled()) return basePrompt;
-  const mem = readProjectMemory(rootDir);
-  if (!mem) return basePrompt;
-  return `${basePrompt}
-
-# Project memory (REASONIX.md)
-
-The user pinned these notes about this project \u2014 treat them as authoritative context for every turn:
-
-\`\`\`
-${mem.content}
-\`\`\`
-`;
-}
-
 // src/skills.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync, statSync } from "fs";
-import { homedir } from "os";
-import { join as join2, resolve } from "path";
 var SKILLS_DIRNAME = "skills";
 var SKILL_FILE = "SKILL.md";
 var SKILLS_INDEX_MAX_CHARS = 4e3;
@@ -130,18 +89,18 @@ var SkillStore = class {
     const out = [];
     if (this.projectRoot) {
       out.push({
-        dir: join2(this.projectRoot, ".reasonix", SKILLS_DIRNAME),
+        dir: join(this.projectRoot, ".reasonix", SKILLS_DIRNAME),
         scope: "project"
       });
     }
-    out.push({ dir: join2(this.homeDir, ".reasonix", SKILLS_DIRNAME), scope: "global" });
+    out.push({ dir: join(this.homeDir, ".reasonix", SKILLS_DIRNAME), scope: "global" });
     return out;
   }
   /** Higher-priority root wins on collision (project > global > builtin); sorted for stable prefix hash. */
   list() {
     const byName = /* @__PURE__ */ new Map();
     for (const { dir, scope } of this.roots()) {
-      if (!existsSync2(dir)) continue;
+      if (!existsSync(dir)) continue;
       let entries;
       try {
         entries = readdirSync(dir, { withFileTypes: true });
@@ -165,13 +124,13 @@ var SkillStore = class {
   read(name) {
     if (!isValidSkillName(name)) return null;
     for (const { dir, scope } of this.roots()) {
-      if (!existsSync2(dir)) continue;
-      const dirCandidate = join2(dir, name, SKILL_FILE);
-      if (existsSync2(dirCandidate) && statSync(dirCandidate).isFile()) {
+      if (!existsSync(dir)) continue;
+      const dirCandidate = join(dir, name, SKILL_FILE);
+      if (existsSync(dirCandidate) && statSync(dirCandidate).isFile()) {
         return this.parse(dirCandidate, name, scope);
       }
-      const flatCandidate = join2(dir, `${name}.md`);
-      if (existsSync2(flatCandidate) && statSync(flatCandidate).isFile()) {
+      const flatCandidate = join(dir, `${name}.md`);
+      if (existsSync(flatCandidate) && statSync(flatCandidate).isFile()) {
         return this.parse(flatCandidate, name, scope);
       }
     }
@@ -185,21 +144,21 @@ var SkillStore = class {
   readEntry(dir, scope, entry) {
     if (entry.isDirectory()) {
       if (!isValidSkillName(entry.name)) return null;
-      const file = join2(dir, entry.name, SKILL_FILE);
-      if (!existsSync2(file)) return null;
+      const file = join(dir, entry.name, SKILL_FILE);
+      if (!existsSync(file)) return null;
       return this.parse(file, entry.name, scope);
     }
     if (entry.isFile() && entry.name.endsWith(".md")) {
       const stem = entry.name.slice(0, -3);
       if (!isValidSkillName(stem)) return null;
-      return this.parse(join2(dir, entry.name), stem, scope);
+      return this.parse(join(dir, entry.name), stem, scope);
     }
     return null;
   }
   parse(path, stem, scope) {
     let raw;
     try {
-      raw = readFileSync2(path, "utf8");
+      raw = readFileSync(path, "utf8");
     } catch {
       return null;
     }
@@ -434,7 +393,50 @@ var BUILTIN_SKILLS = Object.freeze([
   })
 ]);
 
-// src/user-memory.ts
+// src/memory/project.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+var PROJECT_MEMORY_FILE = "REASONIX.md";
+var PROJECT_MEMORY_MAX_CHARS = 8e3;
+function readProjectMemory(rootDir) {
+  const path = join2(rootDir, PROJECT_MEMORY_FILE);
+  if (!existsSync2(path)) return null;
+  let raw;
+  try {
+    raw = readFileSync2(path, "utf8");
+  } catch {
+    return null;
+  }
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  const originalChars = trimmed.length;
+  const truncated = originalChars > PROJECT_MEMORY_MAX_CHARS;
+  const content = truncated ? `${trimmed.slice(0, PROJECT_MEMORY_MAX_CHARS)}
+\u2026 (truncated ${originalChars - PROJECT_MEMORY_MAX_CHARS} chars)` : trimmed;
+  return { path, content, originalChars, truncated };
+}
+function memoryEnabled() {
+  const env = process.env.REASONIX_MEMORY;
+  if (env === "off" || env === "false" || env === "0") return false;
+  return true;
+}
+function applyProjectMemory(basePrompt, rootDir) {
+  if (!memoryEnabled()) return basePrompt;
+  const mem = readProjectMemory(rootDir);
+  if (!mem) return basePrompt;
+  return `${basePrompt}
+
+# Project memory (REASONIX.md)
+
+The user pinned these notes about this project \u2014 treat them as authoritative context for every turn:
+
+\`\`\`
+${mem.content}
+\`\`\`
+`;
+}
+
+// src/memory/user.ts
 var USER_MEMORY_DIR = "memory";
 var MEMORY_INDEX_FILE = "MEMORY.md";
 var MEMORY_INDEX_MAX_CHARS = 4e3;
@@ -971,4 +973,4 @@ export {
   CODE_SYSTEM_PROMPT,
   codeSystemPrompt
 };
-//# sourceMappingURL=chunk-7546PPEL.js.map
+//# sourceMappingURL=chunk-3ALFOYE6.js.map