DeepSeek-Reasonix 入门指南: 低成本 AI 编程 Agent

项目简介

DeepSeek-Reasonix 是一个面向终端的 AI coding agent。它不是单纯的聊天命令行，而是把模型、工具、插件、项目上下文和审批流程组织成一套可配置的本地 Agent 引擎。

它的核心特色有三个：第一，默认围绕 DeepSeek 做了长会话优化，尤其重视 prefix cache，让连续开发任务的 token 成本更低；第二，Provider、模型、工具和插件都写在 reasonix.toml，不是硬编码在程序里；第三，它用 Go 单二进制分发，CLI/TUI、桌面端、VS Code 扩展都可以复用同一套 Reasonix 引擎。

这篇文章我们一起来搭一个最小实践：安装 Reasonix，配置 DeepSeek API Key，初始化项目指令，让它完成一次代码修改任务，再把 OpenAI-compatible 网关接进去。到最后你会知道：什么时候直接用 DeepSeek，什么时候把 Defapi 作为统一接口会更省心。

难度: 中级 | 时长: 20-40 分钟 | 收获: 跑通 DeepSeek-Reasonix，并理解配置驱动、项目指令、双模型协作和低成本接口接入方式

目标读者画像

• 想用 DeepSeek 搭建低成本编程 Agent 的开发者
• 经常在终端里改代码，希望有一个本地 AI 助手的工程师
• 想把 AI Agent 接入团队代码库，但又关心 token 成本的人
• 已经用过 Claude Code、Codex、OpenClaw，想比较 DeepSeek 生态工具的人

核心依赖与环境

完整项目结构树

我们准备一个最小演示项目：

reasonix-agent-demo/
├── .env.example
├── reasonix.toml
├── REASONIX.md
├── tasks/
│   └── bugfix.md
└── demo-app/
    ├── package.json
    └── src/
        └── price.ts

1. 安装 Reasonix CLI

最简单的方式是通过 npm 安装：

npm i -g reasonix

确认安装结果：

reasonix --version

如果你使用 macOS，也可以用 Homebrew：

brew install esengine/reasonix/reasonix

Windows 用户建议在 PowerShell 或 Windows Terminal 中运行：

npm i -g reasonix
reasonix --version

2. 配置 DeepSeek API Key

新建一个演示目录：

mkdir reasonix-agent-demo
cd reasonix-agent-demo

准备 .env.example：

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
DEFAPI_API_KEY=defapi_xxxxxxxxxxxxxxxxxxxxx

复制为本地环境文件：

cp .env.example .env

PowerShell 写法：

Copy-Item .env.example .env

然后填入自己的 DeepSeek API Key。

3. 运行 setup 完成初始配置

现在运行初始化命令：

reasonix setup

按照提示选择 Provider 和模型。DeepSeek-Reasonix 默认对 DeepSeek 比较友好，我们可以先选 DeepSeek Provider，再选择一个适合日常编码任务的模型。

配置完成后，启动交互式会话：

reasonix

你可以先问一个简单问题：

请说明当前项目目录里有哪些文件，以及你建议从哪里开始初始化。

如果 Reasonix 能正常回复，说明 CLI、模型和 API Key 这条链路已经通了。

4. 新建 reasonix.toml 固定 Provider

为了让配置可复现，我们把关键配置写进 reasonix.toml：

default_model = "deepseek"
language = "zh"

[ui]
theme = "auto"

[agent]
temperature = 0.0
reasoning_language = "zh"
soft_compact_ratio = 0.5
tool_result_snip_ratio = 0.6
compact_ratio = 0.8
compact_force_ratio = 0.9

[[providers]]
name = "deepseek"
kind = "openai"
base_url = "https://api.deepseek.com"
models = ["deepseek-v4-flash", "deepseek-v4-pro"]
default = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

[environment]
enabled = true

这里有几个关键点：

• default_model 指向 Provider 名，后续可以在 Provider 内切换默认模型。
• temperature = 0.0 更适合代码修改任务，输出更稳定。
• context_window 给长会话预留空间。
• soft_compact_ratio 和 compact_ratio 让上下文维护更可控。

启动时显式加载环境变量：

export $(grep -v '^#' .env | xargs)
reasonix

PowerShell 可以这样写：

Get-Content .env | ForEach-Object {
  if ($_ -match "^(.*?)=(.*)$") {
    [Environment]::SetEnvironmentVariable($matches[1], $matches[2], "Process")
  }
}
reasonix

5. 用 /init 生成项目指令

Agent 做代码任务时，最怕每次都重新解释项目规范。Reasonix 支持在交互式会话里运行：

/init

它会根据当前项目生成一份项目指令。我们也可以手动准备 REASONIX.md：

# Reasonix 项目指令

## 项目目标

这是一个用于验证 Reasonix 编程 Agent 的最小示例项目。

## 开发规则

- 修改代码前先说明计划。
- 关键函数添加中文注释。
- 修改完成后运行项目测试。
- 不要提交 Git commit，除非用户明确要求。

## 常用命令

```bash
npm test

> [!TIP]
> 项目指令越稳定，DeepSeek 的 prefix cache 越容易命中。不要把每天都变化的任务细节写进长期指令，把它们放进单独的任务文件更合适。

## 6. 准备一个真实代码任务

我们创建一个最小 TypeScript 项目：

```bash
mkdir -p demo-app/src tasks
cd demo-app
npm init -y
npm i -D typescript tsx
npx tsc --init
cd ..

新建 demo-app/src/price.ts：

export type PriceInput = {
  amount: number;
  discountRate?: number;
};

export function calculateFinalPrice(input: PriceInput): number {
  const discount = input.discountRate || 0;
  return input.amount * (1 - discount);
}

这个函数有一个常见问题：discountRate 没有边界校验，传入 1.5 会得到负数价格。

新建 tasks/bugfix.md：

# 任务：修复价格计算边界问题

请修改 demo-app/src/price.ts：

1. amount 必须大于等于 0。
2. discountRate 默认为 0。
3. discountRate 只能在 0 到 1 之间。
4. 为 calculateFinalPrice 添加中文注释。
5. 补一个最小测试或可运行校验脚本。

现在让 Reasonix 执行任务：

reasonix run "阅读 tasks/bugfix.md，并完成里面描述的代码修改。"

你会看到 Reasonix 读取任务、检查文件、提出修改方案，然后调用工具写入代码。这个过程就是 coding agent 和普通聊天机器人的区别：它不仅解释问题，还会进入项目并改文件。

7. 配置 planner/executor 双模型模式

单模型模式已经能完成不少任务，但复杂需求通常需要先规划再执行。Reasonix 支持在配置里拆分 planner 和 executor：

[agent]
temperature = 0.0
planner_model = "deepseek-pro"
reasoning_language = "zh"

[[providers]]
name = "deepseek"
kind = "openai"
base_url = "https://api.deepseek.com"
models = ["deepseek-v4-flash", "deepseek-v4-pro"]
default = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

[[providers]]
name = "deepseek-pro"
kind = "openai"
base_url = "https://api.deepseek.com"
model = "deepseek-v4-pro"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

一种实用搭配是：

这样既能控制成本，又能在关键步骤让更强模型参与判断。

8. 接入 Defapi 兼容接口

Reasonix 的 Provider 是配置驱动的，只要目标服务兼容 OpenAI 风格接口，就可以作为 Provider 接进去。这很适合接入 Defapi。

Defapi 的优势是价格通常只有官方的一半，并且模型基本兼容以下协议：

• v1/chat/completions
• v1/messages
• v1beta/models/

我们可以在 reasonix.toml 里新增一个 Defapi Provider：

[[providers]]
name = "defapi-claude"
kind = "openai"
base_url = "https://api.defapi.org/api/v1"
model = "anthropic/claude-sonnet-4.5"
api_key_env = "DEFAPI_API_KEY"
context_window = 200000

然后切换默认模型：

default_model = "defapi-claude"

也可以保留 DeepSeek 作为默认执行器，把 Defapi 上的强模型作为 planner：

default_model = "deepseek"

[agent]
planner_model = "defapi-claude"
temperature = 0.0

[[providers]]
name = "deepseek"
kind = "openai"
base_url = "https://api.deepseek.com"
models = ["deepseek-v4-flash", "deepseek-v4-pro"]
default = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

[[providers]]
name = "defapi-claude"
kind = "openai"
base_url = "https://api.defapi.org/api/v1"
model = "anthropic/claude-sonnet-4.5"
api_key_env = "DEFAPI_API_KEY"
context_window = 200000

这个组合很适合实际开发：常规任务走 DeepSeek 控制成本，复杂规划或代码审查走 Defapi 上的强模型。Provider 层统一后，Reasonix 不需要为每个模型供应商写新代码。

9. 跑一次完整验证

现在我们做一次完整验证：

reasonix run "检查 demo-app/src/price.ts 的实现，说明还有没有边界问题。"

再让它执行一个更贴近真实工作的任务：

reasonix run "请为 demo-app 增加一个 npm test 命令，用最小脚本验证 calculateFinalPrice 的正常价格、折扣、非法折扣三个场景。"

最后查看 Git 变更：

git diff

如果你看到 Reasonix 改了代码、补了测试、解释了变更原因，说明这个最小 Agent 工作流已经跑通。

常见问题排查

1. reasonix 命令找不到

先确认 npm 全局目录：

npm config get prefix
npm bin -g

如果 npm bin -g 不可用，可以用：

npm root -g

找到全局安装目录后，把对应的可执行文件目录加入 PATH。Windows 用户通常需要重新打开终端。

2. npm 全局安装权限不足

macOS/Linux 不建议直接加 sudo 硬装。我们可以把 npm 全局目录改到用户目录：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm i -g reasonix

然后把 PATH 配置写入 shell 启动文件。

3. DeepSeek API Key 没生效

先检查环境变量是否存在：

echo "$DEEPSEEK_API_KEY"

PowerShell：

$env:DEEPSEEK_API_KEY

如果为空，说明当前终端没有加载 .env。可以先手动注入：

export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"
reasonix

4. reasonix.toml 没被读取

Reasonix 的配置通常按“命令参数、当前目录配置、用户全局配置、内置默认值”的顺序解析。先确认你是在项目根目录运行：

pwd
ls reasonix.toml

然后运行：

reasonix run "请说明当前使用的模型和 Provider。"

如果输出和配置不一致，优先检查命令行参数或全局配置是否覆盖了当前目录配置。

5. 模型返回慢或成本偏高

先把任务拆小：

reasonix run "只阅读 demo-app/src/price.ts，先不要修改，指出潜在问题。"

再让它修改：

reasonix run "根据刚才的问题，只修改 demo-app/src/price.ts。"

长会话里，稳定的项目指令和少量变化的任务描述更有利于缓存命中。复杂任务可以启用 planner/executor 双模型，把高成本模型只放在规划环节。

6. Agent 修改文件前没有审批

检查当前工作模式。交互式会话里可以切换到更保守的模式，要求工具调用前先确认。团队项目建议默认开启审批，不要直接进入无人看管的自动修改模式。

你可以先让 Reasonix 只读分析：

reasonix run "只分析，不要修改文件：请检查 demo-app/src/price.ts 的问题。"

确认方案后再执行修改。

7. Windows 终端中文乱码

PowerShell 可以先设置 UTF-8：

chcp 65001
$OutputEncoding = [System.Text.Encoding]::UTF8

如果输出仍然异常，建议使用 Windows Terminal，并确认编辑器、终端、Git 都使用 UTF-8。

扩展阅读 / 进阶方向

• 使用 Reasonix 桌面端，把终端 Agent 工作流切到图形界面。
• 安装 VS Code 扩展，让 Reasonix 读取编辑器上下文并处理工具审批。
• 配置 MCP-compatible 插件，把内部脚本、数据库查询、文档检索接入 Agent。
• 使用子 Agent 做 review、security_review、research 等分工任务。
• 把 Reasonix 接入 OpenClaw 工作流，让聊天入口触发真实代码任务。
• 接入 Defapi 的 v1/chat/completions 或 v1/messages，统一管理 DeepSeek、Claude、Gemini 等模型供应商。