Reasonix

Reasonix 配置指南

一个 JSON 文件 ~/.reasonix/config.json + 每个项目的 .reasonix/ 目录即可完成所有配置。本页记录每一个配置项、每一条斜杠命令，以及 Skills、Memory、Hooks 的磁盘结构。

1. config.json 文件

Reasonix 读取全局配置 ~/.reasonix/config.json（Windows: %USERPROFILE%\.reasonix\config.json）。首次运行会自动创建，你也可以随时手动编辑。使用 CLI 参数 --no-config 可跳过配置文件，适用于 CI 环境。

项目级覆盖配置放在 <project>/.reasonix/ 下------skills、memory、settings.json（hooks）。项目作用域在同名冲突时覆盖全局。

顶级配置项

json 复制代码

{
  "apiKey": "sk-...",
  "baseUrl": "https://api.deepseek.com",
  "lang": "en",
  "preset": "auto",
  "editMode": "review",
  "reasoningEffort": "high",
  "theme": "auto",
  "search": false,
  "webSearchEngine": "mojeek",
  "webSearchEndpoint": "http://localhost:8080",
  "mcp": [],
  "mcpServers": {},
  "mcpDisabled": [],
  "projects": {
    "/abs/path": {
      "shellAllowed": ["npm", "git status"]
    }
  },
  "semantic": { ... },
  "session": null
}

键	说明	可选值
`lang`	UI 语言	`en` / `zh`
`preset`	默认模型	`auto` / `flash` / `pro`
`editMode`	信任级别（信任拨盘）	`review` / `auto` / `yolo`
`reasoningEffort`	推理强度	`high` / `max`
`theme`	主题	`light` / `dark` / `auto`
`search`	启用 web_search / web_fetch 工具	`true` / `false`
`webSearchEngine`	搜索引擎后端	`mojeek` / `searxng` / `metaso`
`mcp`	MCP 服务器规格（旧版字符串格式）	字符串数组
`mcpServers`	MCP 服务器对象（规范格式）	对象
`mcpDisabled`	启动时跳过的 MCP 服务器名称	字符串数组
`projects`	每个工作区的覆盖配置	对象

信任拨盘 (editMode)

editMode 是整个会话的唯一信任开关：

review --- 编辑排队 + shell 命令需确认
auto --- 编辑自动应用 + shell 命令仍需确认
yolo --- 两者都跳过确认（仅在沙箱中使用！）

2. MCP 服务器

Reasonix 原生支持 Model Context Protocol。config.mcp 中的每一项都是一个字符串------与 --mcp CLI 参数格式相同。三种传输方式：

Stdio（子进程）

json 复制代码

{
  "mcp": [
    "fs=npx -y @modelcontextprotocol/server-filesystem /tmp",
    "git=uvx mcp-server-git --repository ."
  ]
}

格式：名称=命令参数1 参数2。名称= 前缀作为命名空间，所有该服务器暴露的工具都带此前缀。

SSE（HTTP）

json 复制代码

{
  "mcp": [
    "remote=https://example.com/mcp/sse",
    "https://other.example.com/mcp"
  ]
}

纯 http:// / https:// URL 使用 HTTP+SSE。匿名条目（无 name=）可以工作，但之后无法按名称开关。

Streamable HTTP（2025-03 规范）

json 复制代码

{
  "mcp": [
    "edge=streamable+https://edge.example.com/mcp"
  ]
}

使用 streamable+ URL 前缀选择。

mcpServers（规范格式）

json 复制代码

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_***" }
    },
    "postgres": {
      "transport": "sse",
      "url": "https://mcp.internal/pg/sse",
      "headers": { "Authorization": "Bearer ***" }
    },
    "edge": {
      "transport": "streamable-http",
      "url": "https://edge.example.com/mcp",
      "headers": { "X-API-Key": "key_***" }
    }
  }
}

mcpServers 对象格式是声明 MCP 服务器的规范方式：

每个键是服务器名称
值包含 command + args（stdio），url（SSE / Streamable HTTP）
transport 可选（有 url 时自动检测）
env（仅 stdio）、headers（仅 SSE / Streamable HTTP）
disabled（声明式开关）

当 mcp 和 mcpServers 同时存在且名称重叠时，mcpServers 静默胜出。

CLI 标记 & 斜杠命令

命令	功能
`/mcp`	打开交互式 MCP 中心
`/mcp disable <name>`	持久化到 mcpDisabled，下次启动生效
`/mcp enable <name>`	重新启用已禁用的服务器
`/mcp reconnect <name>`	重连并拾取新注册的工具

bash 复制代码

npx reasonix code --mcp "fs=npx -y @mcp/server-filesystem /tmp"
npx reasonix mcp inspect "git=uvx mcp-server-git"
npx reasonix mcp list

3. Skills（技能）

Skill 是一个 Markdown 操作手册，模型可通过 /skill <name> 调用。名称和描述固定在 prompt 中，正文按需加载。项目 Skills 覆盖同名的全局 Skills。

目录结构

bash 复制代码

~/.reasonix/skills/          # 全局
  audit-logs.md
  refactor-react/
    SKILL.md

<project>/.reasonix/skills/  # 项目（覆盖全局）
  release-notes.md

两种等效形式：扁平的 <name>.md，或当你需要附带附件时的 <name>/SKILL.md 文件夹。

Frontmatter

yaml 复制代码

---
name: audit-logs
description: 审查 git log 中的安全红线
runAs: inline                # inline | subagent
allowed-tools: bash,read     # subagent 工具白名单
model: deepseek-chat         # subagent 模型覆盖
max-iters: 32                # subagent 工具调用预算（默认 16，最大 32）
---

## 任务

1. 拉取最近 20 条 commits
2. 标记 commit message 中包含 password / secret / token 的记录
3. 汇报发现

字段	说明
`name`	1--64 字符：字母数字、`_`、`-`、内部 `.`。默认为文件名主干
`description`	一行描述，显示在 `/skill list` 中
`runAs`	`inline`（默认）：正文进入父日志；`subagent`：隔离子循环，仅返回最终答案
`allowed-tools`	逗号分隔的工具名白名单。仅 subagent 有效
`model`	仅 subagent 有效。必须以 `deepseek-` 开头
`max-iters`	仅 subagent 有效。工具调用预算，默认 16，范围 $1, 32$

斜杠命令

命令	功能
`/skill list`	列出所有 skill，带作用域标记
`/skill new <name>`	在项目作用域创建存根。加 `--global` 创建到 `~/.reasonix/skills`
`/skill show <name>`	打印完整正文
`/skill <name> [args]`	运行。Args 作为单个字符串追加到正文

4. Memory（记忆）

Memory 是用户私有知识，固定在不可变前缀中------代理每轮都能读取而无需重新注入。两个作用域：

global：跨项目的事实（关于你本人的）
project：每个工作区的上下文

与可提交的 REASONIX.md 不同，Memory 只存在于本地。

目录结构

python 复制代码

~/.reasonix/memory/
  global/
    MEMORY.md                        # 索引------固定在前缀
    user_role.md
    feedback_terse_comments.md
  <project-hash>/                    # sha1(absRoot)[0..16]
    MEMORY.md
    project_release_freeze.md

条目格式

yaml 复制代码

---
name: user_role
description: 用户是资深后端工程师，React 新手
type: user               # user | feedback | project | reference
scope: global
created: 2026-05-09
---

正文------实际记住的事实，纯 Markdown。

类型	含义
`user`	用户身份信息
`feedback`	纠正 / 偏好
`project`	项目动机 / 截止日期 / 背景
`reference`	外部系统参考指针

斜杠命令

命令	功能
`/memory list`	列出所有条目，两个作用域
`/memory show <name>`	显示正文，自动解析作用域
`/memory forget <name>`	删除一条
`/memory clear <scope> confirm`	清空整个作用域，`confirm` 必填

写入记忆：直接在聊天中说（如"记住我偏好 Vitest 而非 Jest"）。模型会调用 scaffold_memory 工具，生成文件提案等待你的 /apply。

5. Hooks（钩子）

Hooks 是 harness 在生命周期事件上触发的 Shell 命令。配置在 settings.json（非 config.json）中。项目作用域优先，其次全局。

存放位置

bash 复制代码

<project>/.reasonix/settings.json   # 项目作用域
~/.reasonix/settings.json           # 全局作用域

结构

json 复制代码

{
  "hooks": {
    "PreToolUse": [
      {
        "command": "node scripts/audit.js",
        "match": "^(write|edit_file|bash)$",
        "description": "在运行前审计危险工具调用",
        "timeout": 5000
      }
    ],
    "PostToolUse": [
      { "command": "echo done >> /tmp/reasonix.log" }
    ],
    "UserPromptSubmit": [],
    "Stop": []
  }
}

事件类型

事件	说明	默认超时
`PreToolUse`	工具运行前触发。门控：exit 2 阻止；exit 0 放行	5s
`PostToolUse`	工具运行后触发。非门控：非零退出仅警告	30s
`UserPromptSubmit`	用户输入被处理前触发。门控（exit 2 阻止消息）	---
`Stop`	`/quit` 或会话退出时触发。非门控	---

Stdin 载荷

每个 Hook 通过 stdin 接收描述事件的 JSON 对象：

json 复制代码

{
  "event": "PreToolUse",
  "cwd": "/workspace",
  "toolName": "bash",
  "toolArgs": { "command": "rm -rf /" },
  "turn": 3
}

6. 权限（Shell 命令白名单）

Shell 命令按工作区隔离。代理首次运行某个命令时，你会看到交互式 allow once / allow always / deny 提示；选择 "allow always" 会将精确前缀持久化到 config.json 对应项目下。

json 复制代码

{
  "projects": {
    "/abs/path/to/repo": {
      "shellAllowed": [
        "npm test",
        "git status",
        "ls"
      ]
    }
  }
}

命令	功能
`/permissions list`	显示当前项目的允许列表
`/permissions add <prefix>`	添加一个 Shell 前缀
`/permissions rm <prefix	index>`
`/permissions clear confirm`	清空全部，`confirm` 必填

匹配规则：精确匹配（去除首尾空白后）。git 不等于 git push origin main；请列出你真正需要绿通的每个前缀。

7. Web 搜索

web_search + web_fetch 内置。默认后端是 Mojeek（无需设置）；可切换到自托管 SearXNG 以获得对上游引擎的完全控制，或使用 Metaso（每天 100 次免费搜索）。

后端	配置
Mojeek	默认，无需配置
SearXNG	`"webSearchEngine": "searxng"`，`"webSearchEndpoint": "http://localhost:8080"`
Metaso	`"webSearchEngine": "metaso"`，可选 `"metasoApiKey": "mk-..."`

bash 复制代码

# 斜杠命令切换
/search-engine mojeek
/search-engine searxng
/search-engine searxng http://192.168.1.5:8888
/search-engine metaso

本地启动 SearXNG：

bash 复制代码

podman run -d --replace --name searxng -p 8080:8080 docker.io/searxng/searxng

8. 语义索引

reasonix index 构建代理可查询的嵌入索引。选择嵌入提供商：

json 复制代码

{
  "semantic": {
    "provider": "ollama",
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "model": "nomic-embed-text"
    },
    "openaiCompat": {
      "baseUrl": "https://api.example.com/v1",
      "apiKey": "...",
      "model": "text-embedding-3-small"
    }
  }
}

切换 provider 即可更换后端。本地 Ollama 免费且可离线运行；OpenAI 兼容模式可指向任何托管的嵌入 API。

Reasonix 配置指南

1. config.json 文件

顶级配置项

信任拨盘 (editMode)

2. MCP 服务器

Stdio（子进程）

SSE（HTTP）

Streamable HTTP（2025-03 规范）

mcpServers（规范格式）

CLI 标记 & 斜杠命令

3. Skills（技能）

目录结构

Frontmatter

斜杠命令

4. Memory（记忆）

目录结构

条目格式

斜杠命令

5. Hooks（钩子）

存放位置

结构

事件类型

Stdin 载荷

6. 权限（Shell 命令白名单）

7. Web 搜索

8. 语义索引

参考链接