Reasonix：DeepSeek 原生终端 AI 编程 Agent

围绕 DeepSeek prefix cache 设计的终端 AI 编程 Agent，1M 上下文窗口，单日 99.82% cache 命中，双模型协作，MCP 插件系统，MIT 开源。

项目地址：https://github.com/esengine/DeepSeek-Reasonix ｜ MIT 开源协议 ｜ ⭐ 16.4K Stars

这是什么

Reasonix 是一个围绕 DeepSeek prefix cache 设计的终端 AI 编程 Agent。它不是"支持 DeepSeek"的通用 Agent——它是"为 DeepSeek 而生"的专用 Agent。整个架构的每一层（prompt 前缀、会话结构、上下文压缩、工具调度）都围绕 DeepSeek 的字节级 prefix cache 机制优化，目的是让长会话的 token 成本降到最低。

"Cache stability isn't a feature you turn on; it's an invariant the loop is designed around."

真实案例（2026-05-01）：单日 4.35 亿 input tokens，99.82% cache hit rate，花费 ~$12。同等 workload 无 cache 要 ~$61。

为什么存在

大多数 AI 编程 Agent（Claude Code、Cursor、Aider）是通用多模型工具。它们的 cache hit rate 通常低于 20%，因为每轮都会重排、改写、注入新数据到 prompt 里，导致前缀不断变化。

Reasonix 的思路完全不同：不追求模型通用性，而是把 DeepSeek 的 prefix cache 压榨到极致。

代价是绑定 DeepSeek——但这恰恰是设计意图，不是限制。

核心原理：Cache-First 上下文设计

DeepSeek Prefix Cache 的触发条件

DeepSeek 提供自动 prefix cache，cached input 价格是未命中的 1/50：

触发条件：请求的字节级前缀必须和上一次请求完全一致。差一个字节就失效。

上下文三区划分

Reasonix 把整个上下文严格分成三个区域，保证每轮请求的前缀不变：

┌─────────────────────────────────────────┐
│         不可变前缀（Immutable Prefix）    │  ← 整个会话内固定不动
│  系统 prompt + 工具定义 + few-shot        │     计算一次，hash 钉死
├─────────────────────────────────────────┤
│         只追加日志（Append-Only Log）     │  ← 只增不改
│  assistant 回复 + 工具结果                │     每轮新内容追加到尾部
├─────────────────────────────────────────┤
│         临时草稿（Volatile Scratch）      │  ← 每轮重置
│  R1 推理链 + 临时规划状态                 │     提炼后才写入日志
└─────────────────────────────────────────┘

前缀是上一次请求的字节前缀。只要前缀区和日志区的内容不变，新追加的内容只出现在尾部，DeepSeek 就能命中 cache——它只需要计算尾部新增的部分。

四个具体机制

机制一：前缀计算一次，钉死整个会话

系统 prompt + 工具定义 + few-shot example 在会话开始时计算一次，hash 后固定。整个会话内绝不修改。即使你在会话中用 remember 学到了新知识，新知识也只在下次会话的前缀中生效。

机制二：日志只追加，永不重写

assistant 的每轮回复和工具调用结果，序列化后严格按时间追加到日志尾部。永远不会回头修改之前的条目。第 N 轮的请求 = 第 N-1 轮的完整请求 + 新增尾部，DeepSeek 只需计算新增部分。

机制三：临时内容先提炼再写入

R1 的推理链放在 scratch 区，每轮重置。scratch 区的内容不会直接写入日志——经过提炼处理后，才以精简形式进入 append-only log。防止冗长的推理链污染日志。

机制四：变量内容推到轮次尾部

需要注入变化的内容（当前时间、文件变化等）不放在前缀里，而是通过 control.Compose 追加到轮次尾部。前缀永远不变，变的东西永远在尾巴上。

三大架构支柱

支柱一：Cache-First Loop

除了上述四个机制，还有并行工具调度保证消息结构一致：

• 每个工具声明 parallelSafe: boolean
• 连续的 parallel-safe 调用用 Promise.allSettled 并行执行
• 非 parallel-safe 的调用作为串行屏障，保证读写顺序
• 结果按声明顺序落盘，不管谁先完成——模型看到的消息结构始终一致
• 默认并行上限 3（硬上限 16）

支柱二：Tool-Call Repair

DeepSeek 的工具调用能力弱于 Claude 和 GPT，Reasonix 用四个修复 pass 弥补：

支柱三：Cost Control

安装与使用

安装

需要 Node ≥ 22。支持 macOS、Linux、Windows。

# 全局安装（推荐日常使用）
npm install -g reasonix

# 或用短别名
npm install -g dsnix

# 不安装，一次性运行
npx reasonix code

# 从源码构建 Go 版本（最新）
git clone https://github.com/esengine/DeepSeek-Reasonix.git
cd DeepSeek-Reasonix
git checkout main-v2
make build      # -> bin/reasonix
make cross      # -> 跨平台二进制

首次使用

# 1. 运行配置向导
reasonix setup                      # 生成 ./reasonix.toml

# 2. 设置 API Key
export DEEPSEEK_API_KEY=sk-...      # 或放在 .env 文件

# 3. 开始使用
reasonix code                       # 编程模式（有文件系统 + shell 工具）
reasonix chat                       # 聊天模式（无文件系统，有 MCP）
reasonix run "implement the TODOs"  # 一次性任务
reasonix doctor                     # 健康检查

子命令速查

chat vs code

配置系统

配置文件：./reasonix.toml（项目级）+ ~/.config/reasonix/config.toml（全局）

解析优先级：flag > 项目 toml > 全局 toml > 内置默认

default_model = "deepseek-flash"

[agent]
# planner_model = "deepseek-pro"        # 可选：双模型协作
# subagent_model = "deepseek-pro"       # 可选：subagent 默认模型
auto_plan = "ask"                        # off|ask|on

[[providers]]
name        = "deepseek-flash"
kind        = "openai"
base_url    = "https://api.deepseek.com"
model       = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"

[permissions]
mode  = "ask"                            # ask|allow|deny
deny  = ["bash(rm -rf*)", "bash(git push*)"]
allow = ["bash(go test*)"]

[sandbox]
workspace_root = ""                      # 文件写入限制目录

[[plugins]]
name    = "example"
command = "reasonix-plugin-example"

内置预设：deepseek-flash、deepseek-pro、mimo-pro、mimo-flash。任何 OpenAI 兼容端点只需一行配置。

双模型协作

[agent]
planner_model = "deepseek-pro"       # 低频规划模型

两个模型在独立的 cache-stable session 中运行：

auto_plan = "ask" 让复杂任务自动进入 plan 模式：先生成只读计划，等你批准后再编辑。auto_plan_classifier 可以指定一个便宜模型来做分类判断。

插件系统（MCP 兼容）

Reasonix 是 MCP 客户端，支持 stdio 和 HTTP 两种传输：

[[plugins]]                       # 本地 stdio 服务器
name    = "example"
command = "reasonix-plugin-example"

[[plugins]]                       # 远程 HTTP 服务器
name    = "stripe"
type    = "http"
url     = "https://mcp.stripe.com"
headers = { Authorization = "Bearer ${STRIPE_KEY}" }

• 工具暴露为 mcp__<server>__<tool>
• MCP Prompts 变成 /mcp__<server>__<prompt> 斜杠命令
• MCP Resources 通过 @<server>:<uri> 引用
• 兼容 .mcp.json（项目根目录放一个就行）
• /mcp 查看已连接的服务器和暴露的能力

斜杠命令与自定义命令

内置命令

自定义命令

在 .reasonix/commands/ 下放 Markdown 文件即可：

---
description: Review the staged diff
argument-hint: [focus-area]
---
Review the staged diff. Focus on $ARGUMENTS, list bugs with file:line.

• review.md → /review
• git/commit.md → /git:commit
• $ARGUMENTS 展开为所有参数，$1...$N 为位置参数

@ 引用

在消息中嵌入上下文：

• @path/to/file — 注入文件内容
• @dir — 注入目录列表
• @<server>:<uri> — 注入 MCP resource

权限与沙盒

权限控制

权限是按工具调用级别控制的：

deny > ask > allow > fallback

• reader 工具（read_file、glob、grep）默认 allow
• writer 工具（write_file、edit_file）回退到 mode 设置
• reasonix chat：writer 逐个问你（y 本次 / a 本会话 / n 拒绝）
• reasonix run：自主执行，但仍遵守 deny 规则

沙盒

• macOS：通过 Seatbelt 限制 bash，只允许写入指定目录 + 临时文件 + 工具链缓存
• 所有平台：write_file/edit_file/multi_edit 拒绝 [sandbox] workspace_root 以外的路径，解析 symlink 和 .. 防逃逸
• 网络访问需要显式配置 [sandbox] network

上下文管理与压缩策略

Reasonix 的上下文管理围绕两个阈值：

0%          40%                     80%                    100%
├───────────┼───────────────────────┼──────────────────────┤
│  正常运行  │  主动压缩（预防性）     │  紧急压缩             │  溢出

• 40% 阈值（~400K token）：长多轮任务中，主动把工具返回结果压缩为摘要
• 80% 阈值（~800K token）：紧急压缩，如果预防措施没拦住
• 轮末压缩：每轮结束时，超过 3000 token 的工具结果被压缩
• Scratch 提炼：R1 推理链提炼后才写入日志，不直接追加

压缩逻辑：模型当轮有完整访问，后续轮次只看摘要。需要细节时可重新 read_file。

设计取舍：优势与代价

Reasonix 的 cache-first 设计带来了极致的成本控制，但也付出了明确的代价。

优势

• 成本极低：99.82% cache hit，同等 workload 比无 cache 方案便宜 5 倍
• 长会话友好：1M 上下文窗口 + 自动压缩，可以跑很久
• Go 单二进制：CGO_ENABLED=0，零依赖，跨平台交叉编译
• MCP 兼容：支持 stdio + HTTP，兼容 .mcp.json
• 双模型协作：executor + planner 分离，各司其职
• MIT 开源：完全开源，社区活跃

代价

前缀钉死 = 会话内学习能力为零

前缀在整个会话内不可变。remember 学到的新知识只在下次会话才生效。项目结构在会话中变化了，前缀里的上下文是过时的。你无法在会话中途调整 prompt 或工具定义。

只追加日志 = 上下文质量渐进衰减

日志只增不改。早期工作的细节会被压缩为摘要，压缩是有损的。长会话后上下文里堆满了压缩摘要，有效信息密度下降。模型后续如果需要被压缩掉的细节，必须重新读文件——但它可能已经不知道该读哪个文件了。

Scratch 提炼 = 丢掉推理细节

R1 的推理链经过提炼后才写入日志。中间推理过程被丢弃，后续轮次看不到"它之前怎么想的"。如果提炼漏掉了关键推理步骤，后续轮次会重复犯同样的错。

注意力稀释

LLM 对上下文中间位置的信息关注度最低（"Lost in the Middle"现象）。Reasonix 的前缀钉死 + 只追加日志意味着中间部分不断膨胀——恰好是模型最不擅长关注的区域。虽然 1M 窗口很大，但有效利用率远低于 100%。

压缩 = 用信息换空间

轮次 1-3 ：完整上下文，模型看到所有细节
轮次 4+  ：早期工具结果被压缩为摘要，细节丢失
轮次 10+ ：大量摘要堆积，有效信息密度下降
轮次 20+ ：上下文混杂压缩摘要和新内容，模型需要从摘要中"猜"之前发生了什么

DeepSeek 模型能力上限

DeepSeek 的工具调用弱于 Claude 和 GPT，Reasonix 用四个 Tool-Call Repair pass 弥补。这是用工程手段弥补模型缺陷，增加了额外的复杂度。

服务依赖风险

DeepSeek 挂了 → 完全不能用。DeepSeek 涨价 → 核心卖点消失。DeepSeek 改 cache 策略 → 架构假设失效。

一句话总结

Reasonix 用灵活性和上下文质量换取了极致的成本控制。 适合"大量重复编码、长会话、对成本敏感"的场景。不适合"需要会话内快速学习、动态调整、复杂推理"的场景。

与同类工具对比

使用建议

适合的场景：

• 日常编码任务，对成本敏感
• 长会话持续开发，需要低 token 成本
• 不需要最强推理能力的编程任务
• 想用 DeepSeek 但不想手动管理 cache

不太适合的场景：

• 需要 Claude/GPT 级别的推理能力
• 需要会话内快速学习和动态调整
• 项目在会话中频繁变化，前缀会过时
• 对 DeepSeek 服务稳定性有顾虑

成本参考：

• Flash 模型 cache hit：$0.0028/百万 token
• Flash 模型 cache miss：$0.14/百万 token（50x 贵）
• 日常编码一天大概 $5-15（重度使用 $12 左右）
• 比 Claude Code 便宜一个数量级