1  产品概述

1.1  Reasonix 是什么

Reasonix 是一款 专为 DeepSeek 深度优化的终端 AI 编码 Agent（Coding Agent），以开源（MIT）方式发布，托管于 GitHub（esengine/DeepSeek-Reasonixhttps://github.com/esengine/DeepSeek-Reasonix）。它不是 IDE 插件，而是在终端（Terminal）中运行的独立编程助手，通过调用 DeepSeek API 执行代码编写、文件读写、Shell 命令及多步骤推理任务。

项目的核心口号是：「Engineered around prefix-cache stability — leave it running.」（围绕前缀缓存稳定性设计——让它持续运行。）

1.2  核心定位与设计哲学

Reasonix 的设计哲学与大多数通用 AI 编码工具截然不同。其独特性在于以下三点：

• 单一后端策略：只支持 DeepSeek API，不追求多模型兼容。这种「刻意的局限」使得每一层优化都能针对 DeepSeek 字节稳定前缀缓存机制进行深度调校，而不是维护一套泛化的兼容层。
• 终端优先（Terminal-first）：不依赖 IDE 界面，diff 交给 git diff，文件树交给 ls。终端就是完整的工作面板。
• 长会话低成本：通过 Append-only 历史策略，确保每次 API 调用的前缀字节完全一致，从而触发 DeepSeek 的缓存命中，使长会话的输入 token 成本降至约 1/5。

1.3  与同类工具对比

对比维度	Reasonix	Claude Code	Cursor	Aider
AI 后端	DeepSeek（专用）	Anthropic	OpenAI / Anthropic	任意（OpenRouter）
开源许可	MIT ✅	闭源	闭源	Apache 2
成本模型	每任务极低	高端定价	订阅 + 用量	取决于后端
前缀缓存优化	深度工程化 ✅	不适用	不适用	偶发命中
内嵌 Web 仪表盘	有 ✅	无	N/A（IDE）	无
可配置搜索引擎	/search-engine ✅	无	无	无
持久化工作区会话	有 ✅	部分	N/A	无
MCP / Hooks / Skills	全部支持 ✅	是	是	部分

1.4  相关链接

官方网站（入门、下载、安装指引）： https://esengine.github.io/DeepSeek-Reasonix/

GitHub 仓库（源码、Issues、PR）： https://github.com/esengine/DeepSeek-Reasonix

npm 包页面（版本历史、下载量） ： https://www.npmjs.com/package/reasonix

CLI 参考（全部 Slash 命令与快捷键） ： https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/CLI-REFERENCE.md

架构文档（三大支柱技术详解） ： https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/ARCHITECTURE.md

社区讨论（Discussions、CLI 设计、功能讨论、Show & Tell） ： https://github.com/esengine/DeepSeek-Reasonix/discussions

Benchmark 数据（真实缓存命中率与成本数据）： https://github.com/esengine/DeepSeek-Reasonix/tree/main/benchmarks

更新日志（版本变更历史） ： https://github.com/esengine/DeepSeek-Reasonix/blob/main/CHANGELOG.md

贡献指南（PR 规范、注释策略、测试要求） ： https://github.com/esengine/DeepSeek-Reasonix/blob/main/CONTRIBUTING.md

安全政策（漏洞报告流程）： https://github.com/esengine/DeepSeek-Reasonix/blob/main/SECURITY.md

DeepSeek API Key（申请 DeepSeek API 密钥）： https://platform.deepseek.com/api_keys

最新 Release（最新版 v0.38.0+（含 v1.1.0 预览）） ： https://github.com/esengine/DeepSeek-Reasonix/releases

2  核心技术原理

2.1  三大支柱架构

Reasonix 的运行循环（Agent Loop）围绕三个支柱构建，每个支柱解决通用 Agent 框架在 DeepSeek 缓存机制下看不到的问题：

支柱一：缓存优先循环（Cache-first Loop）

Agent 的历史记录采用 Append-only 策略追加，从不修改已发送的消息。这确保每次 API 调用前缀的字节完全一致，满足 DeepSeek 字节稳定前缀缓存（byte-stable prefix cache）的命中条件。通用框架常因重排、注入、截断等操作破坏前缀一致性，Reasonix 将此设计为不可变的不变量（invariant）。

支柱二：工具调用修复（Tool-call Repair）

当模型输出的工具调用格式不完整或出现轻微错误时，Reasonix 内置修复层自动纠错，而不是直接报错终止。这对长会话的稳定性至关重要。

支柱三：成本控制（Cost Control）

通过精确的 token 追踪、/effort 旋钮（调整推理深度）、会话剪枝（prune-sessions）等机制，主动控制每次会话的 API 支出，避免长时间运行产生不必要的费用。

2.2  前缀缓存（Prefix Cache）机制

DeepSeek 对 API 请求实现了字节级别的前缀缓存：如果当次请求的前缀（系统提示 + 历史消息）与上次请求的前缀字节完全相同，则缓存命中，命中的 token 按约 1/10 的折扣价计费（相当于约 1/5 的正常输入价格，因为未命中的新增 token 仍按正常价格计费）。

Reasonix 专为此缓存设计了四项机制（详见 docs/ARCHITECTURE.md Pillar 1）：

• Append-only 消息历史，禁止对已发送消息的任何修改。
• 系统提示固定化，不随对话动态变化。
• 工具定义顺序锁定，不随状态变化而重排。
• 文件读取结果的确定性表达，避免时间戳等元数据污染前缀。

2.3  成本分析与实测数据

指标	实测数据	对比基准	备注
缓存命中率（长会话）	99.82%	通用框架约 30-60%	2026-05-01 真实用户记录
单日输入 Token 量	435M	—	同一工作日真实任务
实际费用	约 $12	无缓存约 $61	节省约 80%
长会话缓存命中率	90%+	—	官网宣称的典型值
输入 token 有效成本	约正常价 1/5	无缓存 = 全价	含缓存折扣

3  安装与快速上手

3.1  系统要求

条件	说明
Node.js	≥ 22（v0.53 稳定版需要）；v1.5.0 Go 重写版无需 Node
操作系统	macOS · Linux · Windows（PowerShell / Git Bash / Windows Terminal）
CPU 架构	amd64 / arm64（v1.5.0 Go 版交叉编译全覆盖）
DeepSeek API Key	必须。申请地址：https://platform.deepseek.com/api_keys
网络	需访问 api.deepseek.com

3.2  安装方式

方式 A：npx（推荐，无需全局安装）

cd my-project

npx reasonix code   # 首次运行时粘贴 DeepSeek API Key，会自动保存

方式 B：全局安装（每日使用推荐）

npm install -g reasonix       # 安装稳定版 v0.53

npm install -g reasonix@next  # 安装预览版 v1.5.0（Go 重写）

reasonix update               # 后续升级

方式 C：Homebrew（仅 v1.5.0 预览版）

brew install esengine/reasonix/reasonix

reasonix

方式 D：桌面客户端（Desktop App）

官网提供稳定版 v0.53 与预览版 v1.5.0 的桌面安装包，支持 macOS / Windows / Linux：

• macOS（v0.53）：Reasonix_0.53.0_universal.dmg
• Windows（v0.53）：Reasonix_0.53.0_x64-setup.exe
• Linux（v0.53）：Reasonix_0.53.0_amd64.AppImage

下载地址：Reasonix — DeepSeek-native coding agent for your terminal

维度	v0.53 稳定版	v1.5.0 预览版 (Go)
运行环境	Node.js >= 22	单二进制，无需 Node
实现语言	TypeScript	Go
分发方式	npm install -g reasonix	npm / brew / 预编译二进制
状态	稳定维护	积极开发中
架构	传统 Node 应用	CGO-free 静态二进制，交叉编译
配置格式	JSON (config.json)	TOML (reasonix.toml)
默认分支	v1 (legacy)	main-v2

3.3  首次运行

# 1. 进入项目目录

cd /path/to/your-project



# 2. 启动编码 Agent

npx reasonix code



# 首次运行提示输入 DeepSeek API Key，输入后自动保存到 ~/.reasonix/config.json



# 3. 健康检查（确认 Node 版本、API Key、MCP 连通性）

reasonix doctor

4  功能详解

4.1  运行模式

命令	适用场景	特性说明
reasonix code [dir]	AI 编码主模式（首选）	文件系统工具 + SEARCH/REPLACE 审核 + Shell 工具
reasonix chat	轻量对话，无磁盘访问	无文件系统权限，支持 MCP，适合思考伙伴场景
reasonix run "task"	单次任务，管道（pipe）友好	流式输出到 stdout，适合脚本集成
reasonix doctor	环境诊断	检查 Node 版本、API Key、MCP 连线
reasonix update	版本升级	升级 Reasonix 自身

code 与 chat 的能力对比

能力	code 模式	chat 模式
文件系统工具 + edit_file	✅	—
SEARCH/REPLACE → /apply 审核	✅	—
Shell 工具（带权限门控）	✅	—
Plan 模式 / /todo / /skill / /mcp	✅	—
记忆（Memory）	项目 + 全局	仅全局
MCP 服务器 / 网页搜索	✅	✅
会话范围	按目录隔离	共享默认会话

4.2  主要功能特性

① 前缀缓存稳定性（Prefix Cache Stability）

整个 Agent 循环围绕「前缀不变量」设计。所有工具定义、系统提示、历史消息均以 append-only 方式追加，保证每次 API 调用前缀字节完全一致，持续触发 DeepSeek 的缓存命中。

② SEARCH/REPLACE 差异审核

在 code 模式下，模型提出的文件修改以 SEARCH/REPLACE 格式呈现，不会直接写盘。用户输入 /apply 后才执行落盘操作，完整保留人工审核权。

③ Plan 模式（计划门控）

使用 /plan 进入只读模式。在此模式下，所有写文件、执行 Shell 的工具均被锁定，模型只能读取和分析。用户批准后方可切回正常模式。

④ MCP（Model Context Protocol）集成

支持 stdio、SSE、Streamable HTTP 三种 MCP 协议。外部服务器提供的工具以前缀形式合并进同一工具注册表，让 Reasonix 获得与外部服务（如数据库、CI/CD、浏览器控制等）交互的能力。

⑤ 子智能体（Subagents）

内置四种专用子智能体：explore（探索代码结构）、research（研究外部资料）、review（代码审查）、security-review（安全审查）。每个子智能体拥有独立隔离的工具集，通过 Skills 系统以 Markdown 脚本定义。

⑥ 技能（Skills）系统

技能是用 Markdown 写成的「剧本」文件，存放于 .reasonix/skills/（项目级）或 ~/.reasonix/skills/（全局）。支持两种调用模式：

• inline：将技能内容内联到当前对话上下文中。
• subagent：以隔离的子智能体循环运行，不污染主会话。

⑦ 记忆（Memory）系统

提供四种记忆类型：user（用户私有知识）、feedback（对模型行为的反馈）、project（项目级规范）、reference（参考资料）。记忆内容固定在前缀中，享受缓存命中带来的成本优势。

⑧ Hooks（生命周期钩子）

在关键生命周期事件上挂载 Shell 命令：

• PreToolUse：在工具调用前执行，可用于门控（gating）。
• PostToolUse：工具调用后执行。
• UserPromptSubmit：用户发送消息时触发。
• Stop：会话结束时触发。

⑨ 网页搜索

默认使用 Mojeek 搜索引擎，也支持切换到自部署的 SearXNG。在 code 和 chat 模式下均可使用 /search-engine 命令切换。

⑩ 语义索引（Semantic Index）

通过 reasonix index 对项目代码库建立本地语义索引，支持本地 Ollama 或任何 OpenAI 兼容的 Embedding 接口，实现代码语义搜索。

⑪ Web 仪表盘（Dashboard）

内置嵌入式 Web 仪表盘，可实时查看缓存命中率、Token 消耗、会话成本等数据，无需离开终端环境。

⑫ 自动检查点（Auto-checkpoints）与事件日志

会话自动创建检查点，支持通过 reasonix replay 回放历史决策过程，reasonix events 查看事件日志，reasonix stats 统计用量。

4.3  Slash 命令参考（常用）

命令	说明
/apply	将 SEARCH/REPLACE 草稿写入磁盘
/plan	进入/退出只读计划模式
/todo	查看或管理当前任务列表
/skill new <name>	创建新技能文件（--global 为全局）
/skill list	列出所有可用技能
/mcp add	添加 MCP 服务器配置
/search-engine	切换搜索引擎（Mojeek / SearXNG）
/effort <level>	调整推理深度（影响 token 消耗）
/copy	复制最后一条助手回复到剪贴板

完整命令列表（含快捷键）：CLI Referencehttps://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/CLI-REFERENCE.md

5  配置说明

5.1  配置文件结构

Reasonix 采用分层配置：

• 全局配置：~/.reasonix/config.json（API Key、默认模型、全局 MCP 等）
• 项目配置：<project>/.reasonix/（项目级技能、记忆、Hooks、权限等）

# 典型全局配置 ~/.reasonix/config.json 结构

{

  "apiKey": "sk-...",

  "model": "deepseek-v4-flash",

  "mcpServers": [],

  "permissions": {},

  "search": { "engine": "mojeek" }

}

5.2  MCP 服务器集成

在 config.json 的 mcpServers 数组中声明，同一格式同时适用于命令行 --mcp 参数：

{

  "mcpServers": [

    {

      "name": "browser",

      "type": "stdio",

      "command": "npx",

      "args": ["@playwright/mcp"]

    },

    {

      "name": "db",

      "type": "sse",

      "url": "http://localhost:3001/sse"

    }

  ]

}

5.3  技能（Skills）系统

技能文件以 Markdown 格式编写，YAML frontmatter 声明元数据：

---

description: 对代码变更进行安全审查

runAs: subagent   # 可选：inline（默认）或 subagent

---



## 安全审查技能

1. 检查输入验证...

2. 扫描注入风险...





# 创建项目级技能

/skill new security-check



# 创建全局技能（跨项目共享）

/skill new my-template --global

5.4  记忆（Memory）系统

类型	内容定位	范围
user	用户私有偏好、知识	全局
feedback	对模型行为的矫正反馈	全局
project	项目代码规范、架构说明	项目
reference	外部文档、API 文档片段	项目

5.5  Hooks（钩子）配置示例

{

  "hooks": {

    "PreToolUse": [

      {

        "matcher": "edit_file",

        "command": "echo \"即将修改文件：$TOOL_INPUT_PATH\""

      }

    ],

    "Stop": [

      { "command": "notify-send \"Reasonix 任务完成\"" }

    ]

  }

}