Reasonix

Why this agent

Reasonix 是 DeepSeek 原生的终端编程 agent —— cache-first 循环、flash-first 成本控制、自动 tool-call 修复 —— 直接对接 api.deepseek.com。按 README 它“原生支持 MCP“,有三种传输(stdio / SSE / Streamable HTTP),以及运行时 /mcp add 命令做临时添加。

Prerequisites

已安装 Node.js 20.10+。
Reasonix 通过 npx reasonix code 调用(不需要全局安装)。
DeepSeek API key(Reasonix 首次运行的向导会问,然后写到 ~/.reasonix/config.json)。
espctl 已安装在磁盘上某个稳定位置(下文需要完整路径)。
(可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET。

Install snippet (or alternative)

Reasonix 的标准 MCP-server 格式写在 ~/.reasonix/config.json(或 <project>/.reasonix/config.json 项目级)的 mcpServers 字段下。形状和 Claude Code 的 mcpServers 完全一致:

{
  "mcpServers": {
    "espctl": {
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "env": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      }
    }
  }
}

替换:

/path/to/espctl —— 你电脑上 espctl 程序的完整路径。
CONTROL_BASE_URL —— 你的 Aegis 构建服务器地址。
MCP_AUTH_SECRET —— 构建服务器给你的访问密钥。

或者 —— 拿到预填好的代码片段:

读取 install://reasonix 资源。

或者用 Reasonix 运行时的 /mcp add 斜杠命令,不动配置文件直接加:

/mcp add espctl=/path/to/espctl mcp serve

(Reasonix 兼容 CLI flag 的旧式字符串格式。完整 schema 见 esengine.github.io/DeepSeek-Reasonix/configuration.html#mcp。)

First-run verification

cd /path/to/your/esp-idf/project
npx reasonix code

在 Reasonix 会话里问:

你有哪些 espctl 工具?

预期:列出约 40 个 espctl 工具。也可以跑 reasonix doctor 做 Node + API key + MCP 接线的健康检查。

Troubleshooting

启动时 config.json 解析错 —— ~/.reasonix/config.json 把很多 section(auth、mcpServers、skills、hooks 等)放一起。解析失败时跑 reasonix doctor,它会指出哪一行有问题。常见原因: 最后一个 mcpServers 条目后多了一个逗号。
列出了工具但每次调用返回 “auth required” —— MCP_AUTH_SECRET 缺失或已失效。回到控制面重新签发一份访问密钥再填进配置。

想用 HTTP 传输而不是 stdio? Reasonix 支持 transport: "sse"(或 "streamable+https://...")形态 —— 把 espctl 条目换成:

"espctl": {
  "transport": "sse",
  "url": "https://esphome.cloud/mcp/esp-idf",
  "headers": {
    "Authorization": "Bearer your-access-key"
  }
}

Claude 格式的 skills 也会加载 —— 按 README,Reasonix 读 <project>/.claude/skills/ 和 ~/.claude/skills/,和它自己的 skill 路径并行。所以给 Claude Code 写的 skill 在 Reasonix 里也能用。

Tested as-of 2026-05-19

Reasonix 特有注意事项

两种 MCP 配置格式都被接受:旧式字符串数组 ("mcp": ["name=cmd args"],兼容 CLI flag)和标准对象形态 ("mcpServers": {...},上面用的这种)。标准形态推荐,因为可以写带命名空间的环境变量、每服务 disabled 标志等。
reasonix mcp 子命令列出/管理已注册的 MCP server;完整说明见 reasonix --help。
Reasonix 文档站 esengine.github.io/DeepSeek-Reasonix 覆盖 config.json 所有 section(auth、MCP、skills、memory、 hooks、permissions、web search、semantic index)。

Keyboard shortcuts

ESP-IDF MCP 用户手册