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

安装

cd my-project
npx reasonix code   # 首次运行粘贴 DeepSeek API Key，之后会记住

要求 Node ≥ 22。在 macOS · Linux · Windows（PowerShell · Git Bash · Windows Terminal）都跑得顺。去拿 DeepSeek API Key → · 完整 flag 看 reasonix code --help。

npx 是推荐路径 —— 不用全局安装，每次都拿最新版。如果你天天用、想把 reasonix 装到 PATH，跑一次 reasonix update。

| 命令 | 何时用 | |---|---| | 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 参考。

切换工作区。 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 搜索 | 默认 Mojeek；用 /search-engine 可切到自托管的 SearXNG。 | | 语义索引 | 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 命令、每个快捷键
• 基准测试 —— τ-bench-lite harness、transcript、成本方法论
• 官方网站 —— 入门、Dashboard 设计稿、TUI 设计稿
• 贡献指南 —— 注释规则、错误处理、用现成库不手写
• 行为准则 · 安全策略

社区

[!NOTE] Reasonix 是开源、社区共建的项目。下面贡献者墙不是装饰 —— 每一个头像都对应一次真实合并的 PR。

给新手准备的入门 issue —— 每个都带背景说明、代码定位、验收标准、提示 —— 全部挂在 good first issue 标签下。挑任意一个还没人认领的就行。

正在征集意见的 Discussions：

• #20 · CLI / TUI 设计 —— 哪里坏了、哪里少东西、哪里你会怎么改？
• #21 · Dashboard 设计 —— 对着设计稿拍砖
• #22 · 未来功能愿望单 —— 你希望 Reasonix 长出什么功能？

正在使用 Reasonix，愿意让更多人了解它？ 欢迎将相关博客、文章、截图、演讲或视频发布到 Show and tell。项目没有营销预算，新用户主要通过社区口碑找到这里。持续参与传播的用户将获得下方这枚徽章，颁发后会展示在贡献者墙旁：

第一次提 PR 之前：先读 CONTRIBUTING.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。

Star 趋势