从 v0.x 升级到 v1.x：TypeScript 到 Go 重写版，迁移指南

如果你是从 Reasonix 的旧版（v0.x TypeScript 版）升级到新版（v1.x+ Go 重写版），这篇是你的专属指南。

如果你是新用户——这篇你可以跳过了，第一篇的安装方式就是装的 Go 版。

一、为什么会有两个版本？

Reasonix 的版本历史：

v0.x（TypeScript 版）
  ├── 基于 Node.js 运行
  ├── 分支：v1（旧分支，仅维护）
  ├── npm 标签：latest
  └── 状态：不再开发新功能

v1.x+（Go 重写版，当前主线）
  ├── 单二进制运行，不需要 Node
  ├── 分支：main-v2（默认分支，活跃开发）
  ├── npm 标签：next（v1.x）/ latest（仍指向 v0.x）
  └── 状态：当前开发主线

为什么重写？ 项目作者决定从 TypeScript 完全重写成 Go，原因包括：

• 单二进制分发（不需要 Node.js 运行时）
• 更好的跨平台支持
• 性能提升
• 更简洁的架构

npm i -g reasonix@next

或者用 Homebrew：

brew install esengine/reasonix/reasonix

二、v1.x 变了什么？

相同的地方

核心能力都保留了：

不同的地方

核心改进

三、迁移步骤

第一步：安装 Go 版

# 装到 Go 版
npm i -g reasonix@next

# 验证版本
reasonix version
# 应该看到 reasonix npm-v1.3.0 类似的输出
# 如果看到 0.x，说明装到了旧版

第二步：配置自动迁移（大部分情况不需要动手）

首次启动 Go 版时，它会自动做一次非破坏性导入：

1. 读取你的旧配置 ~/.reasonix/config.json（API Key、base URL、语言、MCP 服务器） 2. 读取旧会话 ~/.reasonix/sessions/ 3. 生成新的 TOML 配置 4. 旧的配置文件和会话文件不会被删除

你会看到一条启动提示：

检测到旧版 Reasonix 配置，正在导入……
✓ 配置已迁移
✓ N 个历史会话已导入
旧文件保留在 ~/.reasonix/，可手动清理

第三步：验证配置

reasonix doctor

检查输出中是否有以下内容：

config    source  ~/.config/reasonix/config.toml
model     deepseek-flash
providers deepseek-flash   openai  api.deepseek.com   key:present  default
sessions  dir     ~/.config/reasonix/sessions
          saved   N         # 你的历史会话数量

如果一切正常，你的 MCP 服务器、API Key、历史会话都已经过来了。

第四步：验证会话恢复

# 列出可恢复的会话
reasonix chat --resume

# 选择一条旧的对话，看是否能正常打开

第五步（可选）：手动清理旧文件

确认一切正常后，可以清理旧版文件：

# 备份旧配置
cp -r ~/.reasonix ~/.reasonix.backup

# 删除旧版
rm -rf ~/.reasonix
rm -rf ~/.reasonix.json   # 如果存在

四、配置文件的对照转换

如果你偏好手写配置，下面的对照表帮你把旧配置翻译成新配置：

旧版 JSON → 新版 TOML

// v0.x ~/.reasonix/config.json
{
  "apiKey": "sk-xxx",
  "baseUrl": "https://api.deepseek.com",
  "language": "zh",
  "mcpServers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "@tavily/mcp"]
    }
  }
}

# v1.x+ ~/.config/reasonix/config.toml
config_version = 2
default_model = "deepseek-flash"
language = "zh"

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

# API Key 存在环境变量中，不在配置文件里
# export DEEPSEEK_API_KEY=sk-xxx

[[plugins]]
name    = "tavily"
command = "npx"
args    = ["-y", "@tavily/mcp"]

核心差异速查

五、常见问题

Q：旧版写的 Skills 还能用吗？

能用。 Skills 是纯 Markdown 文件，跟版本无关。只要把文件复制到新目录即可：

# 旧版 Skill 位置
cp ~/.reasonix/skills/*.md .reasonix/skills/

# 或全局位置
cp ~/.reasonix/skills/*.md ~/.config/reasonix/skills/

Q：旧版的 MCP 配置还能用吗？

能用。 v1.x 会从 ~/.reasonix/config.json 读取旧版 MCP 配置（最低优先级）。你也可以把配置迁移到 reasonix.toml 的 [[plugins]] 中，或者直接放一个 .mcp.json 在项目根目录。

Q：旧版会话能恢复吗？

能。 首次启动 v1.x 时会自动导入旧版会话。导入后，用 reasonix chat --resume 可以看到所有历史会话。

Q：v1.x 的开发进度如何？

当前 v1.x 已经很稳定了（当前版本 v1.3.0）。核心功能齐全：

• ✅ Chat / Run / Serve 三种模式
• ✅ 9 个内置工具
• ✅ MCP 客户端（stdio + Streamable HTTP）
• ✅ 权限系统 + 沙盒
• ✅ Plan Mode + auto_plan
• ✅ Skills + 斜杠命令
• ✅ 自定义状态栏
• ✅ 桌面客户端
• ✅ 双模型协同
• ✅ CodeGraph 代码理解
• 🔄 Anthropic 原生 provider（开发中）

Q：我要不要迁移？

建议迁移。 v0.x 不再开发新功能，只有 bug 修复。Go 版不仅更快、更小，而且所有新功能（桌面端、双模型协同、CodeGraph 等）只在 Go 版上开发。

写在最后

迁移总结成三件事：

🔜 下一篇预告：CodeGraph——不花一分钱的代码智能分析

别的 AI 编程工具的"代码理解"功能，大多需要 embedding 服务——每次调用都要花钱。Reasonix 内置的 CodeGraph 用 tree-sitter 做代码解析，纯本地运行，完全免费。

关注我，带你用最少的钱，薅最狠的 AI 羊毛。

📌 互动话题：你从 v0.x 升级到 v1.x 遇到过什么问题吗？评论区分享你的迁移经验。