[!NOTE] 这是 Reasonix 的 CNB 托管分支 —— 基于 esengine 原版代码，增加了 CNB 专用打包和制品库配置。原版仓库见 esengine/DeepSeek-Reasonix。

[!TIP] 缓存稳定不是开关，而是循环要围绕设计的不变量。 这就是 Reasonix 只支持 DeepSeek 的根本原因 —— 每一层都为 DeepSeek 字节稳定的前缀缓存机制调过。

[!IMPORTANT] 加入社区 · Community — 中英双语 Discord，频道包括 #求助 / #help、#分享 / #showcase、#想法反馈、贡献者专属 PR 协调区。在群内绑定 GitHub 后自动识别贡献者身份。→ https://discord.gg/XF78rEME2D

安装

要求 Node ≥ 22。在 macOS · Linux · Windows（PowerShell · Git Bash · Windows Terminal）都跑得顺。

安装

Reasonix 发布在 npm 上，直接安装即可：

# 全局安装 —— `reasonix` 命令直接可用
npm install -g @bestzyq/reasonix
reasonix code my-project   # 首次运行粘贴 DeepSeek API Key，之后会记住

# 或者不装，直接用 npx 跑一次
cd my-project
npx @bestzyq/reasonix code          # 每次都拿最新版

| 命令 | 何时用 | |---|---| | reasonix code [dir] | 编码 agent。先用这个。 | | reasonix chat | 纯聊天 —— 不挂文件系统 / shell 工具。 | | reasonix run "task" | 一次性，结果流到 stdout。适合 shell 管道。 | | reasonix doctor | 体检：Node 版本、API Key、MCP 接线。 | | reasonix update | 升级 Reasonix 本身。 |

其他子命令（replay · diff · events · stats · index · mcp · prune-sessions）在 reasonix --help 和 CLI 参考。

QQ 通道

Reasonix 可以把现有的 chat、code 或桌面端会话延伸到 QQ 上，作为远程通道使用；它扩展的是当前会话，不是独立的新运行模式。

• CLI：先启动会话，再执行 /qq connect
• 桌面端：打开 设置 -> 通用 -> QQ通道

连接成功后，QQ 消息可以进入当前会话，助手回复会回到 QQ，后续确认和跟进交互也可以继续在 QQ 上完成。

完整配置、桌面端快速上手与排障说明见：QQ 连接指南。

切换工作区。 Reasonix 把文件系统工具作用域绑定在启动目录，传 --dir 可以指别处。中途切换是有意不支持的（消息日志和 memory 路径会和旧根目录混在一起）—— 退出再启动。

npx reasonix code --dir /path/to/project

chat 还是 code？ code 是默认入口、唯一带文件系统 / shell 工具和 SEARCH/REPLACE 审阅的模式。chat 是更轻量的纯对话壳——想要一个挂着 MCP 但没有磁盘权限的“思路助手”时用它。

| 你拿到什么 | code | chat | |---|---|---| | 文件系统工具 + edit_file | ✓ | — | | SEARCH/REPLACE → /apply 审阅 | ✓ | — | | Shell 工具（带 gate） | ✓ | — | | Plan 模式 · /todo · /skill new · /mcp add | ✓ | — | | Memory（remember / recall_memory） | 项目 + 全局 | 仅全局 | | 配置里的 MCP · web 搜索 · ask_choice | ✓ | ✓ | | 编码导向系统提示词 | ✓ | 通用 | | Session 作用域 | 按目录 | 共享默认 |

写第一个 Skill。 暂无在线市场——自己写。编辑文件（description: frontmatter + 正文），然后 /skill list 就能看到。frontmatter 加 runAs: subagent 会以隔离 subagent 跑，而不是把正文内联进父 prompt。

/skill new my-skill              # <project>/.reasonix/skills/my-skill.md
/skill new my-skill --global     # ~/.reasonix/skills，跨项目共用

配置

一个全局 JSON 文件 ~/.reasonix/config.json，加上项目级 <project>/.reasonix/ 下的覆盖。完整的双语参考 —— 每一个 key、每一条斜杠命令、skills / memory / hooks 在磁盘上的形状 —— 都在这里：

📘 配置指南 · English

| 主题 | 速读 | |---|---| | MCP 服务器 | stdio · SSE · Streamable HTTP。config.json 和 --mcp 共用同一种 spec 格式。 | | Skills | 模型可以调用的 markdown 剧本。inline 或 subagent 两种模式。 | | Memory | 用户私有的知识，钉进前缀。user / feedback / project / reference 四类。 | | Hooks | 生命周期事件触发的 shell 命令。PreToolUse（拦截）· PostToolUse · UserPromptSubmit · Stop。 | | 权限 | 按工作区的 shell 白名单，精确前缀匹配。 | | Web 搜索 | 默认 Bing；可用 /search-engine 切到百度 AI Search、自托管 SearXNG、Metaso、Tavily、Perplexity、Exa、Brave 或 Ollama。 | | 语义索引 | reasonix index —— 本地 Ollama，或任何 OpenAI 兼容的 embedding 接口。 |

Reasonix 的不同之处

整个循环围绕三根支柱组织。每一根解决的都是通用 agent 框架根本看不见的问题 —— 因为它们是为另一种缓存机制设计的。

各支柱完整说明 → Pillar 1 — 缓存优先循环 · Pillar 2 — 工具调用修复 · Pillar 3 — 成本控制

能力一览

横向对比

| | Reasonix | Claude Code | Cursor | Aider | |----------------------------|-------------------|-------------------|---------------------|--------------------| | 后端 | DeepSeek | Anthropic | OpenAI / Anthropic | 任意（OpenRouter） | | 协议 | MIT | 闭源 | 闭源 | Apache 2 | | 单任务成本 | 低 | 高 | 订阅 + 用量 | 不一 | | DeepSeek 前缀缓存 | 专门工程化 | 不适用 | 不适用 | 偶发命中 | | 内嵌 web 仪表盘 | 支持 | — | 不适用 (IDE) | — | | 持久化的工作区会话 | 支持 | 部分 | 不适用 | — | | 计划模式 · MCP · Hooks | 支持 | 支持 | 支持 | 部分 | | 开放社区共建 | 支持 | — | — | 支持 |

实测缓存命中率、成本、方法论看 benchmarks/ —— 这些数会随模型定价变化，所以归在 harness 里，不进 README。

文档

• 架构 —— 四大支柱、缓存优先循环、思维提取、脚手架
• CLI 参考 —— 每个 shell 子命令、每个 slash 命令、每个快捷键
• QQ 连接指南 —— CLI 首次连接流程、桌面端入口和 QQ 开放平台凭据
• 基准测试 —— τ-bench-lite harness、transcript、成本方法论
• 官方网站 —— 入门、Dashboard 设计稿、TUI 设计稿
• 贡献指南 —— 注释规则、错误处理、用现成库不手写
• 行为准则 · 安全策略

社区

[!NOTE] Reasonix 是开源、社区共建的项目。文末"致谢"那面贡献者墙上的每一个头像，都对应一次真实合并的 PR。

给新手准备的入门 issue 见 CNB Issues。

这是 CNB 分支，原版讨论、Issue 和贡献见 esengine/DeepSeek-Reasonix。

第一次提 PR 之前：先读 AGENTS.md —— 短小、严格的项目规则（注释、错误处理、用现成库不手写）。tests/comment-policy.test.ts 静态强制执行注释那部分，npm run verify 是 push 前的闸。参与本项目即同意 行为准则。安全相关问题请走 SECURITY.md。

不做的事

[!IMPORTANT] Reasonix 是有立场的。有些事它故意 不做 —— 列在这里方便你为自己的工作挑对工具。

• 多供应商灵活性。 故意只做 DeepSeek。绑死一个后端是 feature，不是限制。
• IDE 集成。 终端优先。diff 在 git diff，文件树在 ls。仪表盘是 TUI 的伴生，不是 Cursor 的替代。
• 追最难的 reasoning 榜单。 Claude Opus 在某些榜单上还是赢家。DeepSeek 在编程任务上有竞争力；如果你的工作是"解一个 PhD 级证明"而不是"修个 auth bug"，先用 Claude。
• 完全离线 / 永远免费。 Reasonix 需要付费的 DeepSeek API Key。要离线 / 零成本，看 Aider + Ollama 或 Continue。

致谢

下面这些朋友的工作塑造了 Reasonix 今天的样子 —— 综合 commit 数和代码量两个维度。 按字母顺序排列，排名不分先后。 完整贡献者列表在 CNB。

• ctharvey
• dimasd-angga（Dimas D. Angga）
• Evan-Pycraft
• ForeverYoungPp
• GTC2080（TaoMu）
• kabaka9527
• lisniuse（Richie）
• wade19990814-hue
• wviana（Wesley Viana）

另外特别感谢 Bernardxu123 设计的项目 logo （见 docs/brand/），以及 AIGC Link 在小红书上的推广。