reasonix 0.36.1 → 0.37.0

package/README.md

@@ -9,6 +9,8 @@
    · 
   <a href="https://esengine.github.io/DeepSeek-Reasonix/">Website</a>
   &nbsp;·&nbsp;
+  <a href="https://esengine.github.io/DeepSeek-Reasonix/configuration.html">Guide</a>
+  &nbsp;·&nbsp;
   <a href="./docs/ARCHITECTURE.md">Architecture</a>
   &nbsp;·&nbsp;
   <a href="./benchmarks/">Benchmarks</a>
@@ -46,49 +48,6 @@
 
 <br/>
 
-## Web search
-
-Reasonix includes `web_search` and `web_fetch` tools. By default it uses **Mojeek** (no setup required). You can switch to a **self-hosted SearXNG** instance — a metasearch engine that aggregates whatever upstream engines your instance is configured for.
-
-### Switching engines (persists to disk)
-
-The `/search-engine` slash command (alias `/se`) writes your choice to `~/.reasonix/config.json` immediately — it survives restarts:
-
-```
-/search-engine mojeek              # default, no external deps
-/search-engine searxng             # SearXNG at http://localhost:8080
-/search-engine searxng http://192.168.1.100:8888  # custom endpoint
-```
-
-Equivalent `~/.reasonix/config.json`:
-
-```json
-{
-  "webSearchEngine": "searxng",
-  "webSearchEndpoint": "http://localhost:8080"
-}
-```
-
-The tool picks up the change on the next call — no restart needed.
-
-### Starting SearXNG
-
-```sh
-podman run -d --replace --name searxng -p 8080:8080 docker.io/searxng/searxng
-# or: docker run -d -p 8080:8080 searxng/searxng
-```
-
-Verify it's running:
-
-```sh
-curl http://localhost:8080/search?q=test
-# → HTML search results page
-```
-
-> **Note:** The endpoint must include the protocol (`http://`). `localhost:8080` alone will fail — the tool will show a clear error telling you to install SearXNG if the server is unreachable.
-
-<br/>
-
 ## Install
 
 ```bash
@@ -96,55 +55,68 @@ cd my-project
 npx reasonix code   # paste a DeepSeek API key on first run; persists after
 ```
 
-Requires Node ≥ 22. Tested on macOS · Linux · Windows (PowerShell · Git Bash · Windows Terminal). Get a [DeepSeek API key →](https://platform.deepseek.com/api_keys) · `reasonix code --help` for flags.
+Requires Node ≥ 22. Works on macOS · Linux · Windows (PowerShell · Git Bash · Windows Terminal). Grab a [DeepSeek API key →](https://platform.deepseek.com/api_keys) · `reasonix code --help` for flags.
 
-`npx` is the recommended path — no global install, always picks up the latest version. If you'll use Reasonix daily and want `reasonix` on your `PATH`, run `reasonix update` once and it'll do the `npm install -g` for you.
+`npx` is the recommended path — no global install, always latest. If you use Reasonix daily and want it on `PATH`, run `reasonix update` once.
 
-### Subcommand cheatsheet
-
-| Command | When to use |
+| Command | When |
 |---|---|
-| `reasonix code [dir]` | Coding agent rooted at a project. **Start here.** |
-| `reasonix chat` | Plain chat — no filesystem tools, just a conversation with persisted history. |
-| `reasonix run "task"` | One-shot, streams the answer to stdout. Good for shell pipes. |
-| `reasonix doctor` | Environment health check (Node version, API key, MCP wiring). |
+| `reasonix code [dir]` | The coding agent. **Start here.** |
+| `reasonix chat` | Plain chat — no filesystem or shell tools. |
+| `reasonix run "task"` | One-shot, streams to stdout. Good for pipes. |
+| `reasonix doctor` | Health check: Node, API key, MCP wiring. |
 | `reasonix update` | Upgrade Reasonix itself. |
 
-Other subcommands (`replay` · `diff` · `events` · `stats` · `index` · `mcp` · `prune-sessions`) are listed in `reasonix --help` and on the [CLI reference](https://esengine.github.io/DeepSeek-Reasonix/#cli).
+Other subcommands (`replay` · `diff` · `events` · `stats` · `index` · `mcp` · `prune-sessions`) are in `reasonix --help` and the [CLI reference](https://esengine.github.io/DeepSeek-Reasonix/#cli).
 
-#### When to pick `chat` over `code`
+<details>
+<summary><strong>Working in another folder · chat vs. code · author a skill</strong></summary>
 
-`code` is the default — it's the only mode that can read, write, or edit files, run shell commands, or apply SEARCH/REPLACE blocks. `chat` strips all of that down to a plain conversation; reach for it when you want a thinking-partner shell without granting filesystem or shell access.
+**Working in a different folder.** Reasonix scopes filesystem tools to the launch directory; pass `--dir` to retarget. Mid-session switching isn't supported by design (memory paths would tangle with stale roots) — quit and relaunch.
 
-| What you get | `reasonix code` | `reasonix chat` |
-|---|---|---|
-| Native filesystem tools (read · write · `edit_file`) | ✓ | — |
-| SEARCH/REPLACE edit blocks → `/apply` review | ✓ | — |
-| Shell tool (with confirm gate, `/mode yolo` to skip) | ✓ | — |
-| Plan mode · `submit_plan` · `/todo` · `/skill new` · `/mcp add` scaffolding | ✓ | — |
-| Memory tools (`remember` / `recall_memory`) | project + global | global only |
-| Web search · `ask_choice` · MCP servers from config | ✓ | ✓ |
-| Coding-focused system prompt (SEARCH/REPLACE, repo etiquette) | ✓ | generic |
-| Session scope | per-directory (`code-<basename>`) | shared default |
+```bash
+npx reasonix code --dir /path/to/project
+```
 
-`chat` still picks up MCP servers from `~/.reasonix/config.json`, so if all you want is a chat shell with one or two MCP integrations, it's the lighter entrypoint. Otherwise `code` is what every screenshot, benchmark, and slash-command example in the docs assumes.
+**Picking `chat` vs `code`.** `code` is the default and the only mode with filesystem / shell tools and SEARCH/REPLACE review. `chat` is the lighter, tools-off shell — reach for it when you want a thinking partner with MCP attached but no disk access.
 
-**Working in a different folder:** Reasonix scopes filesystem tools to the launch directory. To work elsewhere, pass `--dir`:
+| What you get | `code` | `chat` |
+|---|---|---|
+| Filesystem tools + `edit_file` | ✓ | — |
+| SEARCH/REPLACE → `/apply` review | ✓ | — |
+| Shell tool (gated) | ✓ | — |
+| Plan mode · `/todo` · `/skill new` · `/mcp add` | ✓ | — |
+| Memory (`remember` / `recall_memory`) | project + global | global only |
+| MCP servers from config · web search · `ask_choice` | ✓ | ✓ |
+| Coding system prompt | ✓ | generic |
+| Session scope | per-directory | shared default |
+
+**Author your first skill.** No remote registry — write them directly. Edit the file (`description:` frontmatter + body), then `/skill list`. Add `runAs: subagent` to spawn an isolated subagent loop instead of inlining the body.
 
 ```bash
-npx reasonix code --dir /path/to/project   # or use a relative path
+/skill new my-skill              # <project>/.reasonix/skills/my-skill.md
+/skill new my-skill --global     # ~/.reasonix/skills for cross-project use
 ```
 
-Mid-session switching isn't supported by design (the message log + memory paths get tangled with stale roots). Quit and relaunch with a new `--dir` to retarget. `/status` always shows the current pinned workspace.
+</details>
 
-**Author your first skill:** Skills are markdown playbooks the model can invoke (`/skill <name>`). There's no remote registry yet — you author them directly:
+<br/>
 
-```bash
-/skill new my-skill          # scaffolds <project>/.reasonix/skills/my-skill.md
-/skill new my-skill --global # or under ~/.reasonix/skills for cross-project use
-```
+## Configuration
+
+One JSON file at `~/.reasonix/config.json` plus per-project overrides under `<project>/.reasonix/`. The full bilingual reference — every key, every slash command, the on-disk shape of skills/memory/hooks — lives at:
 
-Edit the file (`description:` frontmatter + body), then `/skill list` to see it. Add `runAs: subagent` to the frontmatter to spawn an isolated subagent loop instead of inlining the body.
+> 📘 **[Configuration Guide](https://esengine.github.io/DeepSeek-Reasonix/configuration.html)** · [中文](https://esengine.github.io/DeepSeek-Reasonix/configuration.html?lang=zh)
+
+| Topic | Quick read |
+|---|---|
+| [MCP servers](https://esengine.github.io/DeepSeek-Reasonix/configuration.html#mcp) | stdio · SSE · Streamable HTTP. One spec format works for both `config.json` and `--mcp`. |
+| [Skills](https://esengine.github.io/DeepSeek-Reasonix/configuration.html#skills) | Markdown playbooks the model can invoke. `inline` or `subagent` mode. |
+| [Memory](https://esengine.github.io/DeepSeek-Reasonix/configuration.html#memory) | User-private knowledge pinned into the prefix. `user` / `feedback` / `project` / `reference` types. |
+| [Hooks](https://esengine.github.io/DeepSeek-Reasonix/configuration.html#hooks) | Shell commands on lifecycle events. `PreToolUse` (gating) · `PostToolUse` · `UserPromptSubmit` · `Stop`. |
+| [Permissions](https://esengine.github.io/DeepSeek-Reasonix/configuration.html#permissions) | Per-workspace shell allowlist. Exact-prefix match. |
+| [Web search](https://esengine.github.io/DeepSeek-Reasonix/configuration.html#search) | Mojeek by default; switch to self-hosted SearXNG with `/search-engine`. |
+| [Semantic index](https://esengine.github.io/DeepSeek-Reasonix/configuration.html#index) | `reasonix index` — local Ollama or any OpenAI-compatible embedding endpoint. |
 
 <br/>
 

package/README.zh-CN.md

@@ -9,6 +9,8 @@
    · 
   <a href="https://esengine.github.io/DeepSeek-Reasonix/">官方网站</a>
   &nbsp;·&nbsp;
+  <a href="https://esengine.github.io/DeepSeek-Reasonix/configuration.html?lang=zh">配置指南</a>
+  &nbsp;·&nbsp;
   <a href="./docs/ARCHITECTURE.md">架构文档</a>
   &nbsp;·&nbsp;
   <a href="./benchmarks/">基准测试</a>
@@ -50,55 +52,68 @@ cd my-project
 npx reasonix code   # 首次运行粘贴 DeepSeek API Key，之后会记住
 ```
 
-要求 Node ≥ 22。已在 macOS · Linux · Windows（PowerShell · Git Bash · Windows Terminal）测过。[去拿 DeepSeek API Key →](https://platform.deepseek.com/api_keys) · 完整 flag 看 `reasonix code --help`。
-
-`npx` 是推荐路径 —— 不用全局安装，每次都拿到最新版本。如果你天天用、想把 `reasonix` 装到 `PATH` 上，跑一次 `reasonix update` 就行，它会替你跑 `npm install -g`。
+要求 Node ≥ 22。在 macOS · Linux · Windows（PowerShell · Git Bash · Windows Terminal）都跑得顺。[去拿 DeepSeek API Key →](https://platform.deepseek.com/api_keys) · 完整 flag 看 `reasonix code --help`。
 
-### 子命令速查
+`npx` 是推荐路径 —— 不用全局安装，每次都拿最新版。如果你天天用、想把 `reasonix` 装到 `PATH`，跑一次 `reasonix update`。
 
-| 命令 | 适用场景 |
+| 命令 | 何时用 |
 |---|---|
-| `reasonix code [dir]` | 锁在某个项目根目录的编码 agent。**先用这个。** |
-| `reasonix chat` | 纯聊天 —— 不挂文件系统工具，只是带历史的对话。 |
-| `reasonix run "task"` | 一次性，把答案直接流到 stdout。适合 shell 管道。 |
-| `reasonix doctor` | 环境体检（Node 版本、API Key、MCP 接线）。 |
+| `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 参考](https://esengine.github.io/DeepSeek-Reasonix/#cli)。
+其他子命令（`replay` · `diff` · `events` · `stats` · `index` · `mcp` · `prune-sessions`）在 `reasonix --help` 和 [CLI 参考](https://esengine.github.io/DeepSeek-Reasonix/#cli)。
 
-#### 什么时候用 `chat` 而不是 `code`
+<details>
+<summary><strong>切换工作区 · chat vs. code · 写第一个 Skill</strong></summary>
 
-`code` 是默认入口 —— 只有它能读写、编辑文件、跑 shell 命令、解析 SEARCH/REPLACE 块。`chat` 把这些全砍掉，只剩一个纯对话外壳；当你只想找模型对一对思路、又不想授予文件系统或 shell 权限时用它。
+**切换工作区。** Reasonix 把文件系统工具作用域绑定在启动目录，传 `--dir` 可以指别处。中途切换是有意不支持的（消息日志和 memory 路径会和旧根目录混在一起）—— 退出再启动。
 
-| 你拿到什么 | `reasonix code` | `reasonix chat` |
-|---|---|---|
-| 原生文件系统工具（read · write · `edit_file`） | ✓ | — |
-| SEARCH/REPLACE 编辑块 → `/apply` 审核 | ✓ | — |
-| Shell 工具（带 confirm gate，`/mode yolo` 跳过） | ✓ | — |
-| Plan 模式 · `submit_plan` · `/todo` · `/skill new` · `/mcp add` 脚手架 | ✓ | — |
-| 记忆工具（`remember` / `recall_memory`） | 项目 + 全局 | 仅全局 |
-| Web 搜索 · `ask_choice` · 从配置加载的 MCP 服务 | ✓ | ✓ |
-| 编码导向系统提示词（SEARCH/REPLACE、仓库礼仪） | ✓ | 通用 |
-| Session 作用域 | 按目录（`code-<basename>`） | 共享默认 |
+```bash
+npx reasonix code --dir /path/to/project
+```
+
+**`chat` 还是 `code`？** `code` 是默认入口、唯一带文件系统 / shell 工具和 SEARCH/REPLACE 审阅的模式。`chat` 是更轻量的纯对话壳——想要一个挂着 MCP 但没有磁盘权限的“思路助手”时用它。
 
-`chat` 同样会从 `~/.reasonix/config.json` 读取 MCP 服务器，所以如果你只是想要一个聊天外壳挂一两个 MCP 集成，它是更轻量的入口。其他场景下，文档里所有截图、基准测试、slash 命令例子默认都是 `code`。
+| 你拿到什么 | `code` | `chat` |
+|---|---|---|
+| 文件系统工具 + `edit_file` | ✓ | — |
+| SEARCH/REPLACE → `/apply` 审阅 | ✓ | — |
+| Shell 工具（带 gate） | ✓ | — |
+| Plan 模式 · `/todo` · `/skill new` · `/mcp add` | ✓ | — |
+| Memory（`remember` / `recall_memory`） | 项目 + 全局 | 仅全局 |
+| 配置里的 MCP · web 搜索 · `ask_choice` | ✓ | ✓ |
+| 编码导向系统提示词 | ✓ | 通用 |
+| Session 作用域 | 按目录 | 共享默认 |
 
-**在其他目录工作：** Reasonix 把文件系统工具作用域绑定在启动目录。要在别的目录工作，传 `--dir`：
+**写第一个 Skill。** 暂无在线市场——自己写。编辑文件（`description:` frontmatter + 正文），然后 `/skill list` 就能看到。frontmatter 加 `runAs: subagent` 会以隔离 subagent 跑，而不是把正文内联进父 prompt。
 
 ```bash
-npx reasonix code --dir /path/to/project   # 也可以用相对路径
+/skill new my-skill              # <project>/.reasonix/skills/my-skill.md
+/skill new my-skill --global     # ~/.reasonix/skills，跨项目共用
 ```
 
-中途切换工作区是有意不支持的（消息日志和 memory 路径会和旧的根目录混在一起，状态错乱）。退出后用新的 `--dir` 重新启动来切换。`/status` 始终显示当前锁定的工作区。
+</details>
 
-**写第一个 Skill：** Skills 是模型可以调用的 markdown 剧本（`/skill <name>`）。暂无在线市场 —— 自己写：
+<br/>
 
-```bash
-/skill new my-skill          # 在 <project>/.reasonix/skills/my-skill.md 生成模板
-/skill new my-skill --global # 或者放到 ~/.reasonix/skills，跨项目共用
-```
+## 配置
 
-编辑文件（`description:` frontmatter + 正文），然后 `/skill list` 就能看到。frontmatter 里加 `runAs: subagent` 会以独立 subagent 跑，而不是把正文内联进父 prompt。
+一个全局 JSON 文件 `~/.reasonix/config.json`，加上项目级 `<project>/.reasonix/` 下的覆盖。完整的双语参考 —— 每一个 key、每一条斜杠命令、skills / memory / hooks 在磁盘上的形状 —— 都在这里：
+
+> 📘 **[配置指南](https://esengine.github.io/DeepSeek-Reasonix/configuration.html?lang=zh)** · [English](https://esengine.github.io/DeepSeek-Reasonix/configuration.html)
+
+| 主题 | 速读 |
+|---|---|
+| [MCP 服务器](https://esengine.github.io/DeepSeek-Reasonix/configuration.html?lang=zh#mcp) | stdio · SSE · Streamable HTTP。`config.json` 和 `--mcp` 共用同一种 spec 格式。 |
+| [Skills](https://esengine.github.io/DeepSeek-Reasonix/configuration.html?lang=zh#skills) | 模型可以调用的 markdown 剧本。`inline` 或 `subagent` 两种模式。 |
+| [Memory](https://esengine.github.io/DeepSeek-Reasonix/configuration.html?lang=zh#memory) | 用户私有的知识，钉进前缀。`user` / `feedback` / `project` / `reference` 四类。 |
+| [Hooks](https://esengine.github.io/DeepSeek-Reasonix/configuration.html?lang=zh#hooks) | 生命周期事件触发的 shell 命令。`PreToolUse`（拦截）· `PostToolUse` · `UserPromptSubmit` · `Stop`。 |
+| [权限](https://esengine.github.io/DeepSeek-Reasonix/configuration.html?lang=zh#permissions) | 按工作区的 shell 白名单，精确前缀匹配。 |
+| [Web 搜索](https://esengine.github.io/DeepSeek-Reasonix/configuration.html?lang=zh#search) | 默认 Mojeek；用 `/search-engine` 可切到自托管的 SearXNG。 |
+| [语义索引](https://esengine.github.io/DeepSeek-Reasonix/configuration.html?lang=zh#index) | `reasonix index` —— 本地 Ollama，或任何 OpenAI 兼容的 embedding 接口。 |
 
 <br/>