Reasonix 命令使用手册

Reasonix — 一个配置驱动、插件化的 AI 编程代理（多模型支持），DeepSeek 原生，终端优先。

仓库：esengine/DeepSeek-Reasonix | Discord: https://discord.gg/XF78rEME2D

版本：v1.0+ (Go 重写版)

目录

• 1. CLI 命令
• 2. Chat 模式下的斜杠命令
• 3. 内置技能 (Skills)
• 4. 内置工具 (Tools)
• 5. CodeGraph 智能代码分析工具
• 6. LSP 语言服务器工具
• 7. 配置文件 reference
• 8. 自定义斜杠命令
• 9. MCP 插件
• 10. 权限系统
• 11. 沙箱
• 12. 双模型协作
• 13. @ 引用
• 14. 安装方式

1. CLI 命令

reasonix chat

启动交互式会话（多轮对话，TUI 界面）。

reasonix chat                          # 新会话
reasonix chat --continue               # 恢复最近一次会话
reasonix chat --resume                 # 从保存的会话中选择恢复
reasonix chat --model deepseek-pro     # 指定模型

reasonix run

执行单次任务并退出，结果流到 stdout。适合脚本/自动化。

reasonix run "implement the TODOs in main.go"
reasonix run --model mimo-pro "add unit tests for this function"
reasonix run --max-steps 20 "复杂的重构任务"
echo "explain this code" | reasonix run   # 管道输入

reasonix serve

通过 HTTP+SSE 提供会话服务，浏览器客户端在 /。

reasonix serve --addr 127.0.0.1:8080

reasonix acp

通过 stdio 提供 Agent Client Protocol 服务。

reasonix acp
# 或
reasonix --acp

reasonix setup

交互式配置向导，引导生成 reasonix.toml（和 .env）。

reasonix setup              # 在当前目录生成
reasonix setup /path/dir    # 在指定目录生成

reasonix config

管理配置项（当前支持 auto-plan）。

reasonix config auto-plan off    # 关闭自动计划模式
reasonix config auto-plan on     # 开启自动计划模式

reasonix mcp

管理 MCP 服务器（在 reasonix.toml 中增、删、查）。

reasonix mcp list              # 列出所有 MCP 服务器
reasonix mcp add ...           # 添加服务器
reasonix mcp remove <name>     # 移除服务器

reasonix doctor

打印本地诊断信息（已自动脱敏）。

reasonix doctor          # 文本格式
reasonix doctor --json   # JSON 格式

reasonix bot

多通道 IM 机器人网关。

reasonix bot start
reasonix bot doctor
reasonix bot weixin-login

reasonix version

显示当前版本号。

reasonix help

显示帮助总览。

2. Chat 模式下的斜杠命令

在 reasonix chat 交互式 TUI 中可用：

自定义斜杠命令

在 .reasonix/commands/（项目级）或 ~/.config/reasonix/commands/（用户级）放置 Markdown 文件即可创建自定义命令。

示例 .reasonix/commands/review.md：

---
description: 审查暂存区 diff
argument-hint: [focus-area]
---
Review the staged diff. Focus on $ARGUMENTS, list bugs with file:line.

• 文件名 review.md → 命令 /review
• 子目录 git/commit.md → 命令 /git:commit
• $ARGUMENTS 展开为所有参数，$1…$N 展开为位置参数

3. 内置技能 (Skills)

技能是可复用的剧本。调用方式：run_skill({ name: "<name>", arguments: "<task>" })。

3.1 explore [🧬 subagent]

子代理模式 — 隔离子代理中探索代码库，返回一个精炼答案。

• 适用：「找出所有 X 的地方」「Y 在项目中如何工作」「调查 Z 的代码」
• 只读，不修改文件

3.2 init [inline]

内联模式 — 分析代码库（结构、构建/测试命令、架构、约定），生成 AGENTS.md。

• 生成的文件会在每次会话加载
• 如已存在则原地改进（不覆盖）

3.3 install-capability [inline]

内联模式 — 从 URL、GitHub raw、本地路径、.mcp.json、可执行文件或 npm 包名安装/卸载 MCP 服务器和技能。

• 两步操作：先 apply=false 出计划（含风险等级），再 apply=true 执行
• 风险等级：low（自动应用）/ medium（提及即可）/ high（需用户确认）

3.4 research [🧬 subagent]

子代理模式 — 结合 web_fetch 和本地代码阅读研究问题。

• 适用：「库 Y 支不支持 X」「Z 的规范写法」「对比实现和官方 spec」

3.5 review [🧬 subagent]

子代理模式 — 审查当前分支 diff，标记：正确性、安全、缺失测试、隐藏行为变更。

• 只读，返回 file:line 级问题列表

3.6 security-review [🧬 subagent]

子代理模式 — 安全专项审查，标记注入/认证/密钥泄露/反序列化/路径穿越/加密问题，附严重等级。

3.7 test [inline]

内联模式 — 运行测试套件 → 诊断失败 → 修复 → 重新运行 → 直到绿色（同一失败最多修 2 次）。

• 自动检测 Go / npm / pnpm / yarn / pytest / cargo
• 不会跳过/删除测试来强制绿色

4. 内置工具 (Tools)

代理在任务执行中可调用的全部工具：

4.1 文件系统工具

4.2 Shell 工具

4.3 工作流工具

4.4 网络与资源工具

4.5 技能与配置工具

4.6 Notebook 工具

5. CodeGraph 智能代码分析工具

在 reasonix.toml 中配置 [codegraph].enabled = true 开启。对于「X 如何工作」/架构/调用链问题应优先使用。

6. LSP 语言服务器工具

在 reasonix.toml 中配置 [lsp].enabled = true 开启。服务器按需延迟启动。

支持为不同语言配置 LSP 服务器，例如 Go：

[lsp.servers.go]
command = "gopls"
extensions = [".go"]

7. 配置文件 reference

配置文件解析优先级：CLI flag > ./reasonix.toml > ~/.config/reasonix/config.toml > 内置默认值

密钥必须通过环境变量（api_key_env）传入，不得写入配置文件。

7.1 完整配置示例

config_version = 2
default_model = "deepseek-flash"
# language = "zh"   # UI 语言；空 = 从 $LANG / $REASONIX_LANG 自动检测

[agent]
max_steps         = 0      # executor 工具调用轮数上限；0 = 无限制
planner_max_steps = 12     # planner 只读工具调用轮数；0 = 无限制
temperature       = 0.0
auto_plan         = "off"  # off | on；off 保持手动计划模式
soft_compact_ratio  = 0.5  # 仅通知，保持缓存优先前缀完整
compact_ratio       = 0.8  # prompt 达到此比例时尝试压缩
compact_force_ratio = 0.9  # 强制压缩高水位线
# planner_model     = "mimo"              # 启用双模型协作（planner + executor）
# auto_plan_classifier = "deepseek-flash"  # 仅对边界任务调用
# subagent_model    = "deepseek-pro"      # 子代理默认模型
# subagent_models   = { review = "deepseek-pro", security_review = "deepseek-pro" }
# subagent_effort   = "high"
# subagent_efforts  = { review = "max", task = "high" }
# output_style      = "explanatory"       # explanatory | learning | concise | custom

[[providers]]
name        = "deepseek-flash"
kind        = "openai"
base_url    = "https://api.deepseek.com"
model       = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"

# 预置 provider：deepseek-pro, mimo-pro (mimo-v2.5-pro), mimo-flash (mimo-v2-flash)

[tools]
enabled               = []    # 空 = 全部启用；可指定列表
bash_timeout_seconds  = 120   # 前台命令安全上限；0 = 无上限

[codegraph]
enabled      = true   # 代码智能分析；首次运行默认关闭
auto_install = true   # 自动拉取运行时

[lsp]
enabled = true        # 语言服务器；按需延迟启动

[skills]
# paths            = ["~/my-skills"]        # 额外自定义技能路径
# excluded_paths   = ["~/.agents/skills"]   # 隐藏约定路径
# max_depth        = 3                      # 嵌套扫描深度
# disabled_skills  = ["review"]             # 禁用指定技能

[permissions]
mode  = "ask"                                    # writer 回退策略：ask | allow | deny
# deny = ["Bash(rm -rf*)", "Bash(git push*)"]   # 所有模式硬阻止
allow = ["Bash(go test:*)"]                      # 从不提示，直接放行
# ask  = ["Edit(src/**)"]                         # 强制提示

[sandbox]
bash    = "enforce"   # shell 沙箱（macOS Seatbelt；其他平台渐近回退）
network = true        # 允许网络出口

[[plugins]]
name    = "example"
command = "reasonix-plugin-example"

7.2 配置项速查

8. MCP 插件

Reasonix 是原生 MCP 客户端，支持三种传输方式：

stdio（本地子进程，默认）

[[plugins]]
name    = "example"
command = "reasonix-plugin-example"
args    = []
env     = { KEY = "value" }

http（Streamable HTTP）

[[plugins]]
name    = "stripe"
type    = "http"
url     = "https://mcp.stripe.com"
headers = { Authorization = "Bearer ${STRIPE_KEY}" }

sse（Server-Sent Events）

[[plugins]]
name = "my-server"
type = "sse"
url  = "https://example.com/mcp/sse"

• 工具以 mcp__<server>__<tool> 名称暴露给模型
• MCP prompt 以 /mcp__<server>__<prompt> 斜杠命令出现
• 资源通过 @<server>:<uri> 引用
• 声明 readOnlyHint: true 的工具会参与并行调度且走 reader 默认权限
• 服务器后台自动连接，用 /mcp 查看状态

.mcp.json 兼容

在项目根目录放置 .mcp.json，Reasonix 直接读取。与 [[plugins]] 合并；名称冲突时 reasonix.toml 优先。

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] },
    "stripe": { "type": "http", "url": "https://mcp.stripe.com", "headers": { "Authorization": "Bearer ${STRIPE_KEY}" } }
  }
}

9. 权限系统

基于规则的工具调用门控。优先级：deny > ask > allow > fallback。

规则格式：Tool 或 Tool(specifier)，例如：

• Bash(go test:*) — 匹配 go test ./...、go test -run TestX 等
• Edit(src/**) — 匹配 src/ 下所有路径的编辑
• Bash(rm -rf*) — 阻止所有 rm -rf 命令

10. 沙箱

沙箱是强制执行层（权限是策略层）：

• 文件写入器（write_file/edit_file/multi_edit）拒绝写入 workspace_root 之外的路径
• 自动解析符号链接和 .. 防止逃逸
• 读取不受限制
• bash 沙箱（macOS Seatbelt）：命令只在项目根和临时目录写入，仅在 network = true 时允许网络
• 其他平台当前回退为不限制

11. 双模型协作

设置 planner_model 启用 planner + executor 双模型模式：

[agent]
planner_model = "deepseek-pro"   # 低频 planner
planner_max_steps = 12           # planner 只读工具调用轮数

• Planner 加载 AGENTS.md 记忆，使用只读工具研究代码
• Executor 拥有全部 writer 和工作流工具
• 两者各自独立会话，缓存稳定
• 计划模式下 planner 先起草方案，等待用户批准后再执行

12. @ 引用

在消息中使用 @ 引用，Reasonix 在发送前解析为带标签的上下文块：

• @path/to/file — 注入本地文件内容
• @path/to/dir — 注入目录列表
• @<server>:<uri> — 注入 MCP 资源
• 只有实际存在的路径才被视作引用，普通 @mention 保持原样
• 输入 / 或 @ 触发自动补全菜单

13. 安装方式

# npm（推荐，跨平台；自动拉取原生二进制）
npm i -g reasonix

# Homebrew（macOS）
brew install esengine/reasonix/reasonix

# 从源码构建
make build       # → bin/reasonix(.exe)
make cross       # → dist/ (darwin|linux|windows × amd64|arm64)

每个 GitHub Release 提供预构建压缩包。

快速上手

reasonix setup                       # 配置向导 → ./reasonix.toml
export DEEPSEEK_API_KEY=sk-...      # 或写入 .env
reasonix chat                        # 启动聊天，然后执行 /init 生成 AGENTS.md
reasonix run "implement the TODOs in main.go"

更多资源：

• GitHub 仓库
• 官方网站
• Discord 社区
• SPEC.md 完整规格（仓库 docs/SPEC.md）