编辑文档 - DeepSeek-Reasonix：专为 DeepSeek 打造的终端 AI 编程 Agent

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

## 一、它是什么？

Reasonix 是一个开源的终端 AI 编程 Agent，专门为 DeepSeek API 定制。它在设计上只有一个目标：让你在终端里用 DeepSeek 写代码时，token 成本始终压在低位——长会话不需要频繁重启，缓存命中率能够稳定保持在 90% 以上。

用一句话概括：Reasonix 把 DeepSeek 的前缀缓存机制压榨到了极致。

## 二、为什么只支持 DeepSeek？

这不是偷懒，而是一个刻意的设计选择。

DeepSeek API 默认启用了**前缀缓存（Prefix Cache）**机制：如果两次请求的前缀部分字节完全相同，缓存的 KV 状态可以直接复用，缓存命中的输入 token 仅按原价约 10% 计费。这意味着在多轮对话中，只要保持 prompt 前缀稳定，越往后的轮次成本越低。

但问题是：大多数通用 Agent 框架在多轮交互中会频繁重排消息顺序、重新序列化工具描述、插入时间戳等，每次请求的前缀都在变化，缓存命中率通常只有 20%–60%。

Reasonix 的整个运行循环（系统提示词、内存管理、工具调用格式、会话组织）全部围绕**维持前缀字节稳定**来设计。用项目官方的话说：“缓存稳定性不是一个可以开关的功能，而是整个循环设计的不变量。”

这个选择意味着它彻底放弃多后端兼容，只服务 DeepSeek。但换来的结果是：缓存命中率可以做到 99.82%。

## 三、实测数据：一天花了多少钱？

Reasonix 项目仓库中公开了一份真实用户数据（2026 年 5 月 1 日，单用户单日，4.35 亿输入 token，99.82% 缓存命中）。该数据分别基于 `v4-pro` 和 `v4-flash` 两个模型版本估算了费用：

**基于 v4-flash 模型：**

| 指标 | 数值 |
|------|------|
| 输入 token（缓存命中） | 4.35 亿 |
| 输入 token（缓存未命中） | 76.7 万 |
| 输出 token | 17.9 万 |
| **缓存命中率** | **99.82%** |
| 当日实际费用 | **约 $12** |
| 同等负载无缓存环境费用 | **约 $61** |
| **节省比例** | **约 80%** |

**基于 v4-pro 模型：**

| 指标 | 数值 |
|------|------|
| 当日实际费用 | **约 $1.38（≈¥10）** |
| 同等负载无缓存环境费用 | **约 $124** |
| **节省比例** | **约 98.9%** |

可以看到，同样的缓存命中率，在不同模型上节省的绝对金额和比例差异很大。**v4-flash 下约 $12 一天，v4-pro 下只需约 $1.38**。这只是单用户单日数据，如果是团队长期高频使用，缓存带来的成本优势会进一步放大。

对比其他工具：
- DeepSeek 官方 Web Chat：同一会话内缓存命中率约 60%–80%，新建会话直接掉到 0%
- 基于通用 OpenAI-shape SDK 的工具（如 Cherry Studio、Open WebUI）：长会话约 30%–60%
- 使用 XML 工具调用格式的客户端（如 Cline、Continue）：命中率更低，因为每次工具返回都会插入对话，改变缓存前缀的字节序列

同样的 DeepSeek API，不同的客户端设计，成本能差出一个数量级。

## 四、它是怎么做到的？——四大核心设计

Reasonix 的架构文档将设计理念概括为“四大支柱”：

### 支柱 1：缓存优先循环（Cache-First Loop）

将上下文划分为三个区域：

```
┌─────────────────────────────────┐
│  IMMUTABLE PREFIX               │ ← 会话级别固定
│  system + tool_specs + few_shots │   缓存命中候选
├─────────────────────────────────┤
│  APPEND-ONLY LOG                │ ← 单向追加
│  [assistant₁][tool₁][assistant₂]│   保留前序轮次前缀
├─────────────────────────────────┤
│  VOLATILE SCRATCH               │ ← 每轮重置
│  推理过程、临时计划              │   不发送给 API
└─────────────────────────────────┘
```

四项保证机制：
- **固定系统提示词**：不变的前缀段，每次请求完全一致
- **追加式日志**：消息只往后追加，不重排、不原地修改
- **挥发性草稿区**：推理过程和临时计划放在缓存前缀之外，不污染下一次命中
- **自动压缩**：上下文接近上限时，旧轮次折叠成摘要追加到前缀，前缀本身不重写，缓存得以延续

### 支柱 2：工具调用修复

DeepSeek 的推理模型在工具调用上有几个已知的失效模式：工具调用 JSON 被包裹在 `<think>` 标签里、参数过多时字段丢失、相同工具调用重复发送（call-storm）、`max_tokens` 截断导致 JSON 不完整。

Reasonix 内置四道修复管道：
- **flatten**：深嵌套 schema 自动扁平化
- **scavenge**：从 `<think>` 标签中捞回被误包裹的工具调用
- **storm**：检测并阻止重复调用
- **truncation**：截断的 JSON 尝试补全后重发

### 支柱 3：成本控制

Reasonix 在客户端做精细的 token 预算管理：
- 裁剪对话历史，合并连续消息
- 截断过长的工具返回
- 控制每个请求的上下文窗口大小
- 提供 `/effort` 命令让用户调节推理深度
- 内置实时成本统计面板

### 支柱 4：并行工具调度

每个工具可以声明 `parallelSafe?: boolean`。循环调度器将连续的可并行调用打包，通过 `Promise.allSettled` 并发执行（默认最多 3 个并发）。工具返回和对话历史的追加仍然按照声明顺序排列，保证模型看到的序列与串行执行一致。

## 五、两个模式：code vs chat

| 对比项 | `reasonix code` | `reasonix chat` |
|--------|-----------------|-----------------|
| 定位 | 编码代理（主力） | 纯对话 |
| 文件系统工具 | ✅ | ❌ |
| Shell 工具 | ✅（可配置门控） | ❌ |
| 搜索/替换审阅 | ✅ | ❌ |
| Plan 模式 | ✅ | ❌ |
| Skills 系统 | ✅ | ❌ |
| MCP 支持 | ✅ | ✅ |
| 编码导向系统提示词 | ✅ | 通用 |

日常工作直接用 `reasonix code`，纯聊天问题用 `reasonix chat`。

## 六、安装与使用

### 环境要求

- Node ≥ 22
- macOS / Linux / Windows（PowerShell / Git Bash / Windows Terminal）

### 安装

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

# 或使用更短的别名
npm install -g dsnix

# 不想全局安装？一行 npx 直接跑
npx reasonix code my-project
```

### 获取 API Key

到 [DeepSeek 开放平台](https://platform.deepseek.com/api_keys) 获取 API Key。首次运行 Reasonix 时，内置向导会提示粘贴 Key 并持久化到 `~/.reasonix/config.json`，无需配置环境变量。

### 常用命令

```bash
reasonix code [dir]    # 编码代理，从这里开始
reasonix chat          # 纯聊天模式
reasonix run "task"    # 一次性任务，流式输出到 stdout
reasonix doctor        # 体检：Node 版本、API Key、MCP 连接状态
reasonix update        # 升级到最新版
```

### 配置

所有配置集中在一个 JSON 文件 `~/.reasonix/config.json` 中，首次运行自动生成。支持项目级覆盖（`<project>/.reasonix/`）。

```json
{
  "apiKey": "sk-...",
  "lang": "zh",
  "preset": "auto",
  "reasoningEffort": "high",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}
```

中文用户设置 `"lang": "zh"` 即可切换为中文界面。

## 七、Skills 技能系统

Reasonix 支持本地 Skills，无需远程注册中心，直接在本地写 Markdown 剧本：

```bash
# 创建项目级 skill
/reasonix skill new my-skill

# 创建跨项目全局 skill
/reasonix skill new my-skill --global
```

两种运行模式：
- **inline**（默认）：将剧本内容内联到父 prompt 中执行
- **subagent**：以隔离子 Agent 运行，返回最终结果，不污染上下文

同时兼容 Claude 格式的 skill——`.claude/skills/` 目录会被自动识别加载。

## 八、桌面客户端（预发布版）

Reasonix 也提供了基于 Tauri 的 GUI 桌面客户端，与 CLI 共享同一个 `~/.reasonix` 配置：多标签会话管理、右侧文件面板、实时仪表盘显示成本/缓存命中率/token 消耗、自带 Node 运行时，无需额外 `npm install`。

## 九、选型建议

### 适合你，如果：

- 每天在终端里写代码，对 DeepSeek API 成本敏感
- 需要长会话编程，希望 Agent 一直开着不重启
- 对 token 消耗有精细追踪习惯
- 项目技术栈以 Node.js / TypeScript 为主

### 不适合你，如果：

- 需要多后端切换（Claude / GPT 等）
- 追求 IDE 深度集成（VS Code 插件等）
- 需要云端部署或团队共享 Agent 状态
- 项目为小型个人项目（< 50 文件），边际收益有限

## 十、社区与反馈

Reasonix 是一个独立开源项目（MIT 协议），目前 GitHub 已获得 7,600+ Stars。

项目维护者活跃于 GitHub Issues 和 Discord 社区（双语，含中文频道 `#求助`），欢迎提交 Bug 反馈、功能建议和 PR 贡献。

---

**写在最后**：Reasonix 是一个有立场的工具。它不做多后端、不追推理榜单、不集成 IDE——只做一件事：在终端里用 DeepSeek 高效编程，把缓存优化做到极致，让 token 账单不再吓人。如果你刚好是 DeepSeek API 的重度用户、每天在终端里做开发，Reasonix 值得一试。

摘要

标签多个标签用逗号分隔

分类