| 1 | --- |
| 2 | import Base from '../layouts/Base.astro'; |
| 3 | import SiteHeader from '../components/SiteHeader.astro'; |
| 4 | |
| 5 | const base = import.meta.env.BASE_URL.replace(/\/$/, ''); |
| 6 | const repo = 'https://github.com/esengine/DeepSeek-Reasonix'; |
| 7 | const desktopStableFallback = `${repo}/releases/latest/download`; |
| 8 | const goVer = 'latest'; |
| 9 | --- |
| 10 | <Base |
| 11 | title="Docs — Reasonix" |
| 12 | titleEn="Docs — Reasonix" |
| 13 | titleZh="文档 — Reasonix" |
| 14 | description="Install Reasonix, start your first session, search version-matched embedded docs and release notes, connect ACP-compatible editors, configure providers and credentials, and understand prefix cache, permissions, sandboxing, MCP plugins, memory, rewind, desktop and bot workflows."> |
| 15 | |
| 16 | <SiteHeader active="docs" scrolled /> |
| 17 | |
| 18 | <main class="docs-layout"> |
| 19 | <aside class="docs-side" aria-label="Documentation navigation"> |
| 20 | <nav class="side-nav" aria-label="Docs sections"> |
| 21 | <div class="side-group"> |
| 22 | <span class="gh"><span class="l-en">Start</span><span class="l-zh">开始使用</span></span> |
| 23 | <a href="#install"><strong><span class="l-en">Install</span><span class="l-zh">安装入口</span></strong><small><span class="l-en">CLI/TUI and desktop builds</span><span class="l-zh">CLI/TUI 与桌面端</span></small></a> |
| 24 | <a href="#config"><strong><span class="l-en">Model keys</span><span class="l-zh">模型密钥</span></strong><small><span class="l-en">Where API keys are saved</span><span class="l-zh">API Key 存在哪里</span></small></a> |
| 25 | <a href="#quickstart"><strong><span class="l-en">First session</span><span class="l-zh">第一次会话</span></strong><small><span class="l-en">Open a repo and ask</span><span class="l-zh">打开仓库并提问</span></small></a> |
| 26 | <a href="#serve"><strong><span class="l-en">Browser UI</span><span class="l-zh">浏览器界面</span></strong><small><span class="l-en">Run <code>reasonix serve</code></span><span class="l-zh">运行 <code>reasonix serve</code></span></small></a> |
| 27 | </div> |
| 28 | <div class="side-group"> |
| 29 | <span class="gh"><span class="l-en">Daily use</span><span class="l-zh">日常使用</span></span> |
| 30 | <a href="#cli"><strong><span class="l-en">Commands</span><span class="l-zh">命令与快捷键</span></strong><small><span class="l-en">Slash commands, mouse, Goal</span><span class="l-zh">斜杠命令、鼠标、Goal</span></small></a> |
| 31 | <a href="#embedded-docs"><strong><span class="l-en">Built-in docs</span><span class="l-zh">内置文档检索</span></strong><small><span class="l-en">Offline guides and release notes</span><span class="l-zh">离线指南与更新日志</span></small></a> |
| 32 | <a href="#permissions"><strong><span class="l-en">Approvals</span><span class="l-zh">审批与沙箱</span></strong><small><span class="l-en">Ask, Auto, YOLO, sandbox</span><span class="l-zh">Ask、Auto、YOLO、沙箱</span></small></a> |
| 33 | <a href="#extensions"><strong><span class="l-en">Extensions</span><span class="l-zh">扩展与 Sidecar</span></strong><small><span class="l-en">Providers, UI, runtime hooks</span><span class="l-zh">Provider、UI、运行时拦截</span></small></a> |
| 34 | <a href="#mcp"><strong><span class="l-en">Plugins</span><span class="l-zh">插件 MCP</span></strong><small><span class="l-en">Tools, prompts, resources</span><span class="l-zh">工具、提示词、资源</span></small></a> |
| 35 | <a href="#acp"><strong><span class="l-en">Editor integration</span><span class="l-zh">编辑器接入</span></strong><small><span class="l-en">ACP sessions and steering</span><span class="l-zh">ACP 会话与回合中引导</span></small></a> |
| 36 | <a href="#surfaces"><strong><span class="l-en">Desktop & bots</span><span class="l-zh">桌面端与 Bot</span></strong><small><span class="l-en">Use Reasonix from IM</span><span class="l-zh">从 IM 使用 Reasonix</span></small></a> |
| 37 | </div> |
| 38 | <div class="side-group"> |
| 39 | <span class="gh"><span class="l-en">Understand</span><span class="l-zh">理解机制</span></span> |
| 40 | <a href="#cache"><strong><span class="l-en">Prefix cache</span><span class="l-zh">前缀缓存</span></strong><small><span class="l-en">Why long sessions stay cheap</span><span class="l-zh">长会话为什么更省</span></small></a> |
| 41 | <a href="#memory"><strong><span class="l-en">Memory & rewind</span><span class="l-zh">记忆与回退</span></strong><small><span class="l-en">Recall facts, restore snapshots</span><span class="l-zh">记住事实、恢复快照</span></small></a> |
| 42 | <a href="#configfile"><strong><span class="l-en">Config file</span><span class="l-zh">配置文件</span></strong><small><span class="l-en">TOML, paths, priority</span><span class="l-zh">TOML、路径、优先级</span></small></a> |
| 43 | </div> |
| 44 | </nav> |
| 45 | <div class="docs-side-links"> |
| 46 | <span class="side-card-kicker"><span class="l-en">Source docs</span><span class="l-zh">完整文档</span></span> |
| 47 | <a href={`${repo}/blob/main-v2/docs/GUIDE.md`}><span class="l-en">Guide</span><span class="l-zh">使用指南</span></a> |
| 48 | <a class="l-en" href={`${repo}/blob/main-v2/docs/ACP.md`}>ACP editor integration</a> |
| 49 | <a class="l-zh" href={`${repo}/blob/main-v2/docs/ACP.zh-CN.md`}>ACP 编辑器接入</a> |
| 50 | <a class="l-en" href={`${repo}/blob/main-v2/docs/EXTENSIONS.md`}>Extensions & sidecars</a> |
| 51 | <a class="l-zh" href={`${repo}/blob/main-v2/docs/EXTENSIONS.zh-CN.md`}>扩展与 Sidecar</a> |
| 52 | <a href={`${repo}/blob/main-v2/docs/CAPABILITY_DIAGNOSTICS.md`}><span class="l-en">Capability diagnostics</span><span class="l-zh">能力诊断</span></a> |
| 53 | <a href={`${repo}/blob/main-v2/docs/SPEC.md`}><span class="l-en">Engineering spec</span><span class="l-zh">工程规范</span></a> |
| 54 | <a href={`${repo}/blob/main-v2/docs/CONFIG_PATHS.md`}><span class="l-en">Config paths</span><span class="l-zh">配置路径</span></a> |
| 55 | </div> |
| 56 | </aside> |
| 57 | |
| 58 | <article class="docs-main"> |
| 59 | <section class="docs-hero" id="overview"> |
| 60 | <span class="docs-kicker"><span class="l-en">Reasonix docs</span><span class="l-zh">Reasonix 文档</span></span> |
| 61 | <h1><span class="l-en">Install, configure, and run coding work locally.</span><span class="l-zh">安装、配置，并在本地运行编码任务。</span></h1> |
| 62 | <p class="lede"><span class="l-en">This page is the concise website guide. It covers the normal path first, then links out to the full repo docs when you need every field or internal contract.</span><span class="l-zh">这是官网上的精简使用说明：先讲最常用路径，再把完整字段和工程契约链接到仓库文档。</span></p> |
| 63 | <div class="docs-path-grid" aria-label="Documentation overview"> |
| 64 | <a href="#install"> |
| 65 | <strong><span class="l-en">New user path</span><span class="l-zh">新手路径</span></strong> |
| 66 | <span><span class="l-en">Install, add an API key, open a repo, and start chatting.</span><span class="l-zh">安装、配置密钥、打开仓库，然后开始对话。</span></span> |
| 67 | </a> |
| 68 | <a href="#permissions"> |
| 69 | <strong><span class="l-en">Control work</span><span class="l-zh">控制执行</span></strong> |
| 70 | <span><span class="l-en">Use approvals, sandboxing, Goal, and rewind to keep changes manageable.</span><span class="l-zh">用审批、沙箱、Goal 和回退管理改动。</span></span> |
| 71 | </a> |
| 72 | <a href="#extensions"> |
| 73 | <strong><span class="l-en">Extend Reasonix</span><span class="l-zh">扩展 Reasonix</span></strong> |
| 74 | <span><span class="l-en">Build sidecars, Providers, UI, prompts, themes, and MCP tools.</span><span class="l-zh">开发 Sidecar、Provider、UI、提示词、主题与 MCP 工具。</span></span> |
| 75 | </a> |
| 76 | <a href="#configfile"> |
| 77 | <strong><span class="l-en">Look up details</span><span class="l-zh">查阅细节</span></strong> |
| 78 | <span><span class="l-en">Find config paths, TOML examples, and full reference docs.</span><span class="l-zh">查看配置路径、TOML 示例和完整参考。</span></span> |
| 79 | </a> |
| 80 | </div> |
| 81 | </section> |
| 82 | |
| 83 | <h2 id="install"><span class="l-en">CLI / TUI</span><span class="l-zh">CLI / TUI</span></h2> |
| 84 | <p><span class="l-en">Install the terminal app with one command on macOS, Linux, Windows, or WSL. <code>reasonix</code> opens the interactive TUI; <code>reasonix run</code> is the headless automation entry.</span><span class="l-zh">一条命令安装终端应用,支持 macOS、Linux、Windows 或 WSL。<code>reasonix</code> 打开交互式 TUI；<code>reasonix run</code> 用于无界面自动执行。</span></p> |
| 85 | <div class="codeblock codeblock--copy"><button data-copy="npm i -g reasonix">Copy</button><span class="c"># npm (recommended · 推荐)</span> |
| 86 | npm i -g reasonix |
| 87 | |
| 88 | <span class="c"># Homebrew</span> |
| 89 | brew install esengine/reasonix/reasonix</div> |
| 90 | <div class="doc-choice-grid"> |
| 91 | <div> |
| 92 | <strong><span class="l-en">Use the CLI when</span><span class="l-zh">适合用 CLI</span></strong> |
| 93 | <p><span class="l-en">You live in the terminal, want fast repo work, or need scriptable <code>reasonix run</code> automation.</span><span class="l-zh">你主要在终端工作、需要快速处理仓库任务，或要用 <code>reasonix run</code> 做自动化。</span></p> |
| 94 | </div> |
| 95 | <div> |
| 96 | <strong><span class="l-en">Use the desktop app when</span><span class="l-zh">适合用桌面端</span></strong> |
| 97 | <p><span class="l-en">You want visual sessions, settings, MCP status, checkpoints, approvals, and bot connections in one place.</span><span class="l-zh">你希望在一个界面里管理会话、设置、MCP 状态、checkpoint、审批和 Bot 连接。</span></p> |
| 98 | </div> |
| 99 | </div> |
| 100 | <div class="tui-panel"> |
| 101 | <span class="desktop-kicker"><span class="l-en">Terminal-first workflow</span><span class="l-zh">终端优先工作流</span></span> |
| 102 | <ul class="desktop-feature-list"> |
| 103 | <li><span class="l-en">Interactive TUI with Plan, Ask, Auto, YOLO, transcript scrolling, and tool approval prompts.</span><span class="l-zh">交互式 TUI 支持 Plan、Ask、Auto、YOLO、对话滚动与工具审批提示。</span></li> |
| 104 | <li><span class="l-en">Drag-select transcript text to copy through the verified local system clipboard; SSH uses a clearly labelled OSC 52 fallback. Run <code>/mouse</code> to use your terminal's native selection instead.</span><span class="l-zh">拖选对话文本会通过可验证的本地系统剪贴板复制；SSH 使用明确标记的 OSC 52 回退。也可用 <code>/mouse</code> 切回终端原生选择。</span></li> |
| 105 | <li><span class="l-en">Text paste stays terminal-native. Image paste is explicit: <code>Ctrl+V</code> on macOS/Linux, <code>Alt+V</code> on Windows, or <code>/paste-image</code>, with a live <code>Pasting image…</code> footer state.</span><span class="l-zh">文本粘贴保持终端原生；图片粘贴使用独立入口：macOS/Linux 按 <code>Ctrl+V</code>，Windows 按 <code>Alt+V</code>，或运行 <code>/paste-image</code>，读取时底栏显示“正在粘贴图片…”。</span></li> |
| 106 | <li><span class="l-en">Scriptable runs through <code>reasonix run</code>, including piped input and explicit model selection.</span><span class="l-zh">可脚本化的 <code>reasonix run</code>,支持管道输入和显式模型选择。</span></li> |
| 107 | </ul> |
| 108 | </div> |
| 109 | <div class="callout"><span class="ico">!</span><span><span class="l-en">To install the legacy <strong>0.x</strong> version, pin it explicitly with <code>npm i -g reasonix@0.53.2</code>. The commands above, Homebrew, and desktop/release downloads install Reasonix 1.x; the current desktop download build is <strong><span data-release-version="desktop">{goVer}</span></strong>.</span><span class="l-zh">如需安装 legacy <strong>0.x</strong> 版本,请显式 pin: <code>npm i -g reasonix@0.53.2</code>。上方命令、Homebrew 与桌面端/Release 下载对应 Reasonix 1.x；当前桌面端下载构建为 <strong><span data-release-version="desktop">{goVer}</span></strong>。</span></span></div> |
| 110 | |
| 111 | <h2 id="desktop"><span class="l-en">Desktop app</span><span class="l-zh">桌面端</span></h2> |
| 112 | <div class="desktop-panel"> |
| 113 | <div class="desktop-panel-head"> |
| 114 | <span class="desktop-kicker"><span class="l-en">Native app · <span data-release-version="desktop">{goVer}</span></span><span class="l-zh">原生桌面端 · <span data-release-version="desktop">{goVer}</span></span></span> |
| 115 | <h3><span class="l-en">Use Reasonix with a full desktop workspace</span><span class="l-zh">用完整桌面工作区运行 Reasonix</span></h3> |
| 116 | <p><span class="l-en">The desktop app runs the same local Reasonix engine as the CLI, with visual sessions, settings, MCP status, memory, checkpoints, tool approvals, and IM bot connections in one place.</span><span class="l-zh">桌面端运行与 CLI 相同的本地 Reasonix 引擎,并把可视化会话、设置、MCP 状态、记忆、检查点、工具审批和 IM Bot 连接集中到一个工作区。</span></p> |
| 117 | </div> |
| 118 | <div class="desktop-downloads" aria-label="Desktop downloads"> |
| 119 | <a class="desktop-download" href={`${desktopStableFallback}/Reasonix-darwin-universal.dmg`} data-desktop-asset="Reasonix-darwin-universal.dmg" download> |
| 120 | <strong>macOS</strong> |
| 121 | <span><span class="l-en">Universal DMG · Apple Silicon + Intel</span><span class="l-zh">通用 DMG · Apple Silicon + Intel</span></span> |
| 122 | </a> |
| 123 | <a class="desktop-download" href={`${desktopStableFallback}/Reasonix-windows-amd64-installer.exe`} data-desktop-asset="Reasonix-windows-amd64-installer.exe" download> |
| 124 | <strong>Windows</strong> |
| 125 | <span><span class="l-en">x64 installer</span><span class="l-zh">x64 安装器</span></span> |
| 126 | </a> |
| 127 | <a class="desktop-download" href={`${desktopStableFallback}/Reasonix-linux-amd64.deb`} data-desktop-asset="Reasonix-linux-amd64.deb" download> |
| 128 | <strong>Linux</strong> |
| 129 | <span><span class="l-en">Debian / Ubuntu .deb</span><span class="l-zh">Debian / Ubuntu .deb</span></span> |
| 130 | </a> |
| 131 | </div> |
| 132 | <div class="desktop-downloads desktop-downloads--secondary" aria-label="Alternate desktop downloads"> |
| 133 | <a class="desktop-download" href={`${desktopStableFallback}/Reasonix-darwin-arm64.zip`} data-desktop-asset="Reasonix-darwin-arm64.zip" download> |
| 134 | <strong>macOS</strong> |
| 135 | <span>Apple Silicon zip</span> |
| 136 | </a> |
| 137 | <a class="desktop-download" href={`${desktopStableFallback}/Reasonix-windows-arm64-installer.exe`} data-desktop-asset="Reasonix-windows-arm64-installer.exe" download> |
| 138 | <strong>Windows</strong> |
| 139 | <span>ARM64 installer</span> |
| 140 | </a> |
| 141 | <a class="desktop-download" href={`${desktopStableFallback}/Reasonix-linux-amd64.tar.gz`} data-desktop-asset="Reasonix-linux-amd64.tar.gz" download> |
| 142 | <strong>Linux</strong> |
| 143 | <span><span class="l-en">Generic amd64 tarball</span><span class="l-zh">通用 amd64 压缩包</span></span> |
| 144 | </a> |
| 145 | </div> |
| 146 | <ul class="desktop-feature-list"> |
| 147 | <li><span class="l-en">Open and resume project sessions from a visual sidebar.</span><span class="l-zh">从可视化侧边栏打开和恢复项目会话。</span></li> |
| 148 | <li><span class="l-en">Approve tools, review checkpoints, and rewind code or conversation without leaving the app.</span><span class="l-zh">在应用内审批工具、查看 checkpoint,并回退代码或对话。</span></li> |
| 149 | <li><span class="l-en">Connect Feishu, Lark, or WeChat bots from Settings and handle remote approvals locally.</span><span class="l-zh">在设置中连接飞书、Lark 或微信 Bot,并在本地处理远程审批。</span></li> |
| 150 | </ul> |
| 151 | </div> |
| 152 | <h3 id="macos-quarantine"><span class="l-en">macOS quarantine warning</span><span class="l-zh">macOS 隔离属性提示</span></h3> |
| 153 | <p><span class="l-en">Use this only when Reasonix was downloaded from the official site or GitHub release, moved to <code>/Applications</code>, and macOS still says the app cannot be opened, cannot be verified, or is damaged. This removes the quarantine flag that macOS attaches to downloaded apps.</span><span class="l-zh">仅在 Reasonix 来自官网或 GitHub Release、已经放入 <code>/Applications</code>,但 macOS 仍提示“无法打开”“无法验证开发者”或“应用已损坏”时使用。它会移除 macOS 给下载应用附加的隔离属性。</span></p> |
| 154 | <div class="codeblock codeblock--copy"><button data-copy="sudo xattr -rd com.apple.quarantine /Applications/Reasonix.app">Copy</button><span class="c"># Quit Reasonix first, then run in Terminal.</span> |
| 155 | sudo xattr -rd com.apple.quarantine /Applications/Reasonix.app</div> |
| 156 | <div class="callout"><span class="ico">!</span><span><span class="l-en">Only run this for an official Reasonix app you trust. If the app is installed somewhere else, replace <code>/Applications/Reasonix.app</code> with that exact app path, then reopen Reasonix.</span><span class="l-zh">只对可信的官方 Reasonix 应用执行这条命令。如果安装在其他位置,请把 <code>/Applications/Reasonix.app</code> 替换为实际 app 路径,然后重新打开 Reasonix。</span></span></div> |
| 157 | |
| 158 | <h2 id="quickstart"><span class="l-en">Quick start</span><span class="l-zh">快速上手</span></h2> |
| 159 | <p><span class="l-en">First run is minimal — <code>reasonix setup</code> walks you through picking a provider and key, then saves it under Reasonix home. Then point Reasonix at a repo and start a session:</span><span class="l-zh">首次运行很简单——<code>reasonix setup</code> 引导你选择 provider 并填写密钥,然后保存到 Reasonix home。接着指向仓库、开始会话:</span></p> |
| 160 | <div class="codeblock codeblock--copy"><button data-copy="cd your-project && reasonix">Copy</button>cd your-project |
| 161 | reasonix</div> |
| 162 | <p><span class="l-en">Then just describe the task:</span><span class="l-zh">然后直接描述任务:</span></p> |
| 163 | <div class="codeblock"><span class="a">›</span> add retry with backoff to the http client |
| 164 | <span class="a">›</span> refactor the auth flow, keep the public API stable |
| 165 | <span class="a">›</span> why is the worker leaking memory?</div> |
| 166 | <p><span class="l-en">Run <code>/init</code> when you want project memory, then leave the session running — context is append-only, so every new turn starts from a cache hit instead of a cold start.</span><span class="l-zh">需要项目记忆时运行 <code>/init</code>,然后让会话持续运行——上下文只追加,每一轮都从缓存命中开始,而不是冷启动。</span></p> |
| 167 | |
| 168 | <h2 id="serve"><span class="l-en">Web frontend</span><span class="l-zh">Web 前端</span></h2> |
| 169 | <p><span class="l-en"><code>reasonix serve</code> starts the same local Reasonix engine behind a browser UI. Use it when you want a desktop-style surface without installing the desktop app, when running Reasonix on a remote development box through a tunnel, or when you want a shareable view of a live session.</span><span class="l-zh"><code>reasonix serve</code> 会用同一个本地 Reasonix 引擎启动浏览器 UI。适合不安装桌面端但想用可视化界面、在远程开发机上通过 tunnel 使用,或把当前会话临时共享给浏览器查看。</span></p> |
| 170 | <div class="codeblock codeblock--copy"><button data-copy="cd your-project && reasonix serve">Copy</button>cd your-project |
| 171 | reasonix serve |
| 172 | <span class="c"># open http://127.0.0.1:8787</span></div> |
| 173 | <div class="web-panel"> |
| 174 | <span class="desktop-kicker"><span class="l-en">Browser UI</span><span class="l-zh">浏览器界面</span></span> |
| 175 | <h3><span class="l-en">Chat, approvals, goals, todos, and balance</span><span class="l-zh">聊天、审批、Goal、Todo 与余额</span></h3> |
| 176 | <ul class="desktop-feature-list"> |
| 177 | <li><span class="l-en">Use chat, tool approvals, session history, rewind, fork, summarize, model switching, and reasoning-effort controls from the browser.</span><span class="l-zh">在浏览器里使用聊天、工具审批、会话历史、rewind、fork、summarize、模型切换与 reasoning effort 控件。</span></li> |
| 178 | <li><span class="l-en">Start or inspect Goal work, and follow the live todo panel fed by the <code>todo_write</code> tool.</span><span class="l-zh">启动或查看 Goal,并跟随由 <code>todo_write</code> 工具驱动的实时 Todo 面板。</span></li> |
| 179 | <li><span class="l-en">Show provider balance when configured; pass <code>--model</code>, <code>--max-steps</code>, or <code>--resume</code> for one-off launches.</span><span class="l-zh">已配置 provider 时显示余额；临时启动可传 <code>--model</code>、<code>--max-steps</code> 或 <code>--resume</code>。</span></li> |
| 180 | </ul> |
| 181 | </div> |
| 182 | <p><span class="l-en">The default listen address is <code>127.0.0.1:8787</code> with <code>auth_mode = "none"</code>. Keep that for local-only use. If the server is reachable from another machine, enable auth before sharing the URL.</span><span class="l-zh">默认监听 <code>127.0.0.1:8787</code>,认证模式是 <code>auth_mode = "none"</code>。这个默认值只适合本机使用；如果其他机器能访问,请先开启认证再分享 URL。</span></p> |
| 183 | <div class="codeblock codeblock--copy"><button data-copy="reasonix serve --auth token">Copy</button><span class="c"># token auth prints a share URL with ?token=...</span> |
| 184 | reasonix serve --auth token |
| 185 | reasonix serve --addr 0.0.0.0:8787 --auth token |
| 186 | |
| 187 | <span class="c"># password auth can use a startup password or a stored bcrypt hash</span> |
| 188 | reasonix serve --auth password --password 'temporary-password' |
| 189 | reasonix serve --hash-password --password 'strong-password'</div> |
| 190 | <div class="codeblock"><span class="c"># ~/.reasonix/config.toml</span> |
| 191 | [serve] |
| 192 | auth_mode = "password" <span class="c"># none|token|password</span> |
| 193 | password_hash = "$2a$12$..." |
| 194 | behind_proxy = true <span class="c"># only behind a trusted reverse proxy</span></div> |
| 195 | |
| 196 | <h2 id="config"><span class="l-en">Configuration</span><span class="l-zh">配置</span></h2> |
| 197 | <p><span class="l-en">Reasonix talks directly to configured OpenAI-compatible providers such as DeepSeek or MiMo with your own API keys. Provider config stores only the key name in <code>api_key_env</code>; the actual secret saved by <code>reasonix setup</code> or desktop Settings lives in the global <code><Reasonix home>/.env</code>.</span><span class="l-zh">Reasonix 使用你自己的 API Key 直连配置好的 OpenAI-compatible provider,例如 DeepSeek 或 MiMo。Provider 配置只在 <code>api_key_env</code> 里记录密钥名称；通过 <code>reasonix setup</code> 或桌面端设置保存的真实密钥会写入全局 <code><Reasonix home>/.env</code>。</span></p> |
| 198 | <div class="codeblock codeblock--copy"><button data-copy="reasonix setup">Copy</button>reasonix setup |
| 199 | <span class="c"># saves provider keys to <Reasonix home>/.env, for example:</span> |
| 200 | DEEPSEEK_API_KEY=sk-...</div> |
| 201 | <p><span class="l-en">Project <code>.env</code> files are not provider-key fallbacks. They are only used for workspace-scoped variable expansion in MCP/plugin settings. Persistent options live in the <a href="#configfile">config file</a>.</span><span class="l-zh">项目 <code>.env</code> 不是 provider key 的 fallback。它只用于 MCP/plugin 配置里的工作区级变量展开。持久化选项见<a href="#configfile">配置文件</a>。</span></p> |
| 202 | <div class="doc-note-grid"> |
| 203 | <div><strong><span class="l-en">Global secret file</span><span class="l-zh">全局密钥文件</span></strong><span><code><Reasonix home>/.env</code></span></div> |
| 204 | <div><strong><span class="l-en">Project config</span><span class="l-zh">项目配置</span></strong><span><code>./reasonix.toml</code></span></div> |
| 205 | <div><strong><span class="l-en">User config</span><span class="l-zh">用户配置</span></strong><span><code>~/.reasonix/config.toml</code></span></div> |
| 206 | </div> |
| 207 | |
| 208 | <h2 id="cache"><span class="l-en">Prefix cache</span><span class="l-zh">前缀缓存</span></h2> |
| 209 | <p><span class="l-en">DeepSeek bills cached prefix tokens at a fraction of fresh computation. Most agents waste this: they reorder messages, rewrite summaries mid-session, or inject volatile timestamps — every change invalidates the cache from that point on.</span><span class="l-zh">DeepSeek 对缓存前缀 token 的计费远低于新计算。多数智能体浪费了这一点:重排消息、会话中改写摘要、注入易变的时间戳——任何改动都会让其后的缓存全部失效。</span></p> |
| 210 | <p><span class="l-en">Reasonix serializes context deterministically and only ever appends. The practical effect: hours-long sessions where 90%+ of every request replays from cache, and input-token cost collapses to ~1/5.</span><span class="l-zh">Reasonix 以确定性方式序列化上下文,并且永远只追加。实际效果:数小时的会话中每次请求 90% 以上从缓存重放,输入 token 成本降到约 1/5。</span></p> |
| 211 | <p><span class="l-en">Automatic compaction starts at 80% of the model context by default. Desktop Settings and <code>reasonix config compact-ratio</code> share the user-level value; choose 65–85%, or use <code>--local</code> for a project override. Lower values compact earlier and can reduce prefix-cache reuse.</span><span class="l-zh">自动压缩默认在模型上下文达到 80% 时启动。桌面端设置与 <code>reasonix config compact-ratio</code> 共用用户级设置；可在 65–85% 之间选择，也可用 <code>--local</code> 添加项目覆盖。阈值越低越早压缩，也可能降低前缀缓存复用率。</span></p> |
| 212 | |
| 213 | <h2 id="permissions"><span class="l-en">Permissions & sandbox</span><span class="l-zh">权限与沙箱</span></h2> |
| 214 | <p><span class="l-en">Permissions gate each tool call: <code>deny</code> > <code>ask</code> > <code>allow</code> > fallback. Read-only tools generally pass; writers fall back to <code>[permissions] mode</code>. Ask is not read-only: an approved writer can still run. The sandbox is the enforced capability boundary. Headless <code>reasonix run</code> defaults to Ask and fails closed when a writer needs approval; use <code>-y</code>, <code>--auto</code>, or <code>--permission-mode auto</code> for intentional unattended writes. <code>[permissions] allow_dynamic_bash = true</code> is an advanced opt-in that lets an Allow fallback cover nested or indirect Bash. Explicit ask and deny rules still apply.</span><span class="l-zh">权限逐个把关工具调用:<code>deny</code> > <code>ask</code> > <code>allow</code> > 兜底。只读工具通常放行；写工具回退到 <code>[permissions] mode</code>。Ask 不是只读：writer 获得批准后仍会执行；沙箱才是强制能力边界。无界面的 <code>reasonix run</code> 默认使用 Ask，写操作需要审批时会安全拒绝；要显式启用无人值守写入，请使用 <code>-y</code>、<code>--auto</code> 或 <code>--permission-mode auto</code>。高级用户可设置 <code>[permissions] allow_dynamic_bash = true</code>，让 Allow fallback 覆盖嵌套或间接 Bash。显式 ask 与 deny 规则仍然生效。</span></p> |
| 215 | <p><span class="l-en">The sandbox is enforcement: file-writers refuse any path outside <code>[sandbox] workspace_root</code> (default: the current dir), resolving symlinks and <code>..</code> so a link cannot tunnel out. <code>bash = "enforce"</code> jails shell commands when an OS sandbox backend is available (Seatbelt on macOS, bubblewrap on Linux); without one, bash is refused instead of running unconfined. Install the backend or set <code>bash = "off"</code> to explicitly restore the pre-1.16 unconfined behavior.</span><span class="l-zh">沙箱负责强制执行:写文件工具拒绝 <code>[sandbox] workspace_root</code>(默认当前目录)之外的任何路径,并解析符号链接与 <code>..</code>,防止借链接逃逸。<code>bash = "enforce"</code> 会在存在 OS 沙箱后端时隔离 shell 命令（macOS Seatbelt、Linux bubblewrap）；没有后端时会拒绝执行 bash，而不是非隔离运行。安装对应后端，或显式设置 <code>bash = "off"</code> 来恢复 1.16 之前的非隔离行为。</span></p> |
| 216 | |
| 217 | <h2 id="extensions"><span class="l-en">Extensions & sidecars</span><span class="l-zh">扩展与 Sidecar</span></h2> |
| 218 | <p><span class="l-en">Plugin packages have two layers. Declarative contributions ship skills, agents, commands, prompts, hooks, MCP servers, and themes. A Manifest v1 <code>runtime</code> adds an out-of-process Sidecar speaking the stable Extension Protocol v1; it can intercept runtime events, own replacement strategies, contribute streaming model Providers, and publish structured UI.</span><span class="l-zh">插件包分为两层：声明式贡献可以分发 skills、agents、commands、prompts、hooks、MCP server 与主题；Manifest v1 的 <code>runtime</code> 则启动独立 Sidecar，通过稳定的 Extension Protocol v1 拦截运行时事件、持有替换策略、提供流式模型 Provider，并发布结构化 UI。</span></p> |
| 219 | <div class="doc-choice-grid"> |
| 220 | <div> |
| 221 | <strong><span class="l-en">MCP or Extension Protocol?</span><span class="l-zh">MCP 还是 Extension Protocol？</span></strong> |
| 222 | <p><span class="l-en">Use MCP for portable tools, prompts, and resources. Use a code extension when the feature must participate in the Agent lifecycle, replace host behavior, provide models, or render native surfaces.</span><span class="l-zh">可移植的工具、提示词与资源优先使用 MCP；需要进入 Agent 生命周期、替换宿主行为、提供模型或原生界面时，才使用代码型扩展。</span></p> |
| 223 | </div> |
| 224 | <div> |
| 225 | <strong><span class="l-en">Stable and cache-aware</span><span class="l-zh">稳定且缓存友好</span></strong> |
| 226 | <p><span class="l-en">Each turn pins one runtime generation. Sidecars initialize with four-way concurrency inside one shared 30-second startup budget. No-op reloads keep the prompt prefix byte-identical; stable replacements remain cacheable, while per-turn timestamps or random values in prompts and schemas destroy reuse.</span><span class="l-zh">每个回合固定使用一个 runtime generation；Sidecar 最多 4 路并行初始化，并共享 30 秒总启动预算。空操作重载保持提示词前缀字节不变；稳定替换仍可缓存，把时间戳或随机值逐回合写入提示词与 Schema 则会破坏复用。</span></p> |
| 227 | </div> |
| 228 | </div> |
| 229 | <p><span class="l-en">The repository includes a complete starter with its manifest, Go Sidecar, build commands, linked installation, reload loop, and visible input rewrite:</span><span class="l-zh">仓库提供了完整 starter，包含 Manifest、Go Sidecar、构建命令、链接安装、重载循环与可观察的输入改写：</span></p> |
| 230 | <div class="codeblock">git clone https://github.com/esengine/DeepSeek-Reasonix.git |
| 231 | cd DeepSeek-Reasonix/sdk/go/examples/starterextension |
| 232 | go build -o bin/starter-extension.exe . |
| 233 | plugin_root="$(pwd -P)" |
| 234 | reasonix plugin install "$plugin_root" --dry-run |
| 235 | reasonix plugin install "$plugin_root" --link --replace --yes |
| 236 | <span class="c"># Start a session, or reload while idle</span> |
| 237 | /reload</div> |
| 238 | <p><span class="l-en">On Windows PowerShell, set <code>$pluginRoot = (Resolve-Path .).Path</code> and pass <code>$pluginRoot</code> to both install commands. Then send <code>starter: explain sidecars</code> to verify the intercept. The first public Go SDK release is <code>sdk/go/v1.0.0</code>; before that immutable tag exists, use the starter from a source checkout.</span><span class="l-zh">Windows PowerShell 请先设置 <code>$pluginRoot = (Resolve-Path .).Path</code>，再把 <code>$pluginRoot</code> 传给两条安装命令。随后发送 <code>starter: 解释 Sidecar</code> 验证拦截。Go SDK 的首个公开版本是 <code>sdk/go/v1.0.0</code>；该不可变标签发布前，请直接从源码 checkout 使用 starter。</span></p> |
| 239 | <div class="callout"><span class="ico">!</span><span><span class="l-en"><strong>Full trust:</strong> a code Sidecar runs outside the Reasonix sandbox with the inherited environment and can override permission decisions. Dry-run the install, review the runtime command and declared capabilities, and install only code you trust completely.</span><span class="l-zh"><strong>完全信任：</strong>代码型 Sidecar 运行在 Reasonix Sandbox 之外，继承宿主环境并可覆盖权限决定。请先 dry-run，检查 Runtime 命令与声明能力，只安装完全信任的代码。</span></span></div> |
| 240 | <p><span class="l-en">Continue with the <a href={`${repo}/blob/main-v2/docs/EXTENSIONS.md`}>extension guide</a>, <a href={`${repo}/blob/main-v2/docs/PLUGIN_PACKAGES.md#manifest-v1-extensions`}>Manifest v1 reference</a>, <a href={`${repo}/blob/main-v2/sdk/go/README.md`}>Go SDK</a>, and <a href={`${repo}/blob/main-v2/docs/EXTENSION_PROTOCOL.md`}>wire protocol</a>.</span><span class="l-zh">后续请阅读<a href={`${repo}/blob/main-v2/docs/EXTENSIONS.zh-CN.md`}>扩展指南</a>、<a href={`${repo}/blob/main-v2/docs/PLUGIN_PACKAGES.zh-CN.md#manifest-v1扩展`}>Manifest v1 参考</a>、<a href={`${repo}/blob/main-v2/sdk/go/README.md`}>Go SDK</a>和<a href={`${repo}/blob/main-v2/docs/EXTENSION_PROTOCOL.zh-CN.md`}>线协议</a>。</span></p> |
| 241 | |
| 242 | <h2 id="mcp"><span class="l-en">Plugins (MCP)</span><span class="l-zh">插件(MCP)</span></h2> |
| 243 | <p><span class="l-en">Reasonix is an MCP client. A <code>[[plugins]]</code> entry's <code>type</code> selects the transport: <code>stdio</code> launches a local subprocess, while <code>http</code> connects to a Streamable HTTP server with optional headers expanded from the environment. Tools surface to the model as <code>mcp__<server>__<tool></code>.</span><span class="l-zh">Reasonix 是一个 MCP 客户端。<code>[[plugins]]</code> 条目的 <code>type</code> 选择传输方式：<code>stdio</code> 启动本地子进程；<code>http</code> 连接 Streamable HTTP server,可从环境变量展开静态 headers。工具以 <code>mcp__<server>__<tool></code> 呈现给模型。</span></p> |
| 244 | <div class="codeblock"><span class="c"># reasonix.toml</span> |
| 245 | [[plugins]] <span class="c"># local stdio server</span> |
| 246 | name = "example" |
| 247 | command = "reasonix-plugin-example" |
| 248 | |
| 249 | [[plugins]] <span class="c"># remote server over Streamable HTTP</span> |
| 250 | name = "stripe" |
| 251 | type = "http" |
| 252 | url = "https://mcp.stripe.com" |
| 253 | headers = { Authorization = "Bearer ${STRIPE_KEY}" }</div> |
| 254 | <p><span class="l-en">Installing an MCP server is the authorization decision, so its tools are directly usable without server-level, per-tool, writer, or destructive approval settings. Repository-declared servers require one exact identity confirmation before startup and ask again only when that identity changes. Explicit global deny rules still win. <code>readOnlyHint</code> and <code>destructiveHint</code> remain internal facts for parallel dispatch, Plan restrictions, strict read-only children, and cached-to-live safety reclassification; schema-only changes refresh the next-session cache without interrupting an authorized call. Plan hard-blocks MCP writer/destructive targets and unauthorized readers; <code>read_only_task</code> / <code>read_only_skill</code> never expose writers.</span><span class="l-zh">安装 MCP server 本身就是授权决定，安装后工具直接可用，不再需要 server、逐工具、writer 或 destructive 审批设置。仓库声明的 server 只在启动前确认一次精确身份，身份变化时才重新确认；显式全局 deny 仍然优先。<code>readOnlyHint</code> 与 <code>destructiveHint</code> 只作为并行调度、Plan 限制、严格只读子会话和缓存到实时安全分类复核的内部事实；仅 schema 变化会刷新下一会话缓存，不再中断已授权调用。Plan 会硬阻断 MCP writer/destructive 目标和未授权 reader；<code>read_only_task</code> / <code>read_only_skill</code> 完全不暴露 writer。</span></p> |
| 255 | <p><span class="l-en">MCP prompts also become slash commands such as <code>/mcp__server__prompt</code>, and MCP resources can be referenced with <code>@server:uri</code>. Enabled servers connect in the background after a session starts; use <code>/mcp</code> or the desktop MCP panel to inspect, refresh, reconnect, or disable servers. Already have an <code>.mcp.json</code>? Put it in the project root; Reasonix reads the Claude Code <code>mcpServers</code> schema as-is and lets <code>reasonix.toml</code> win on name collisions.</span><span class="l-zh">MCP prompts 也会变成 <code>/mcp__server__prompt</code> 这样的斜杠命令,MCP resources 可通过 <code>@server:uri</code> 引用。启用的 server 会在会话开始后后台连接；用 <code>/mcp</code> 或桌面端 MCP 面板查看、刷新、重连或临时禁用。已有 <code>.mcp.json</code>?放到项目根目录即可；Reasonix 会原样读取 Claude Code 的 <code>mcpServers</code> schema,同名时 <code>reasonix.toml</code> 优先。</span></p> |
| 256 | |
| 257 | <h2 id="acp"><span class="l-en">Editor integration (ACP)</span><span class="l-zh">编辑器接入（ACP）</span></h2> |
| 258 | <p><span class="l-en">Reasonix implements Agent Client Protocol (ACP) v1 as an NDJSON JSON-RPC 2.0 agent over stdio. An ACP-compatible editor or host starts <code>reasonix acp</code>, opens workspace-scoped sessions, and receives streamed messages, tool activity, plans, permission requests, and configuration updates.</span><span class="l-zh">Reasonix 实现了 Agent Client Protocol（ACP）v1，通过 stdio 提供 NDJSON JSON-RPC 2.0 agent。兼容 ACP 的编辑器或 host 启动 <code>reasonix acp</code>、打开工作区会话，并接收流式消息、工具活动、计划、权限请求和配置更新。</span></p> |
| 259 | <div class="codeblock codeblock--copy"><button data-copy="reasonix acp">Copy</button>reasonix acp <span class="c"># use the configured default model</span> |
| 260 | reasonix acp --model <name> <span class="c"># choose the startup model</span> |
| 261 | reasonix acp --profile delivery <span class="c"># economy | balanced | delivery</span></div> |
| 262 | <div class="doc-choice-grid"> |
| 263 | <div> |
| 264 | <strong><span class="l-en">Independent sessions</span><span class="l-zh">独立会话</span></strong> |
| 265 | <p><span class="l-en">Each session owns its workspace, history, model, reasoning effort, work mode, collaboration mode, approval posture, and host-supplied MCP servers.</span><span class="l-zh">每个会话独立持有工作区、历史、模型、推理强度、工作模式、协作模式、审批策略和 host 提供的 MCP server。</span></p> |
| 266 | </div> |
| 267 | <div> |
| 268 | <strong><span class="l-en">Editor-owned capabilities</span><span class="l-zh">编辑器持有的能力</span></strong> |
| 269 | <p><span class="l-en">When advertised by the client, file operations use unsaved editor buffers and foreground commands run in a client-owned terminal.</span><span class="l-zh">客户端声明相关能力后，文件操作会经过编辑器未保存的 buffer，前台命令则在客户端持有的 terminal 中运行。</span></p> |
| 270 | </div> |
| 271 | </div> |
| 272 | <p><span class="l-en">Reasonix also advertises the vendor method <code>_reasonix.io/session/steer</code> through <code>agentCapabilities._meta</code>. A host may call it while <code>session/prompt</code> is active to queue user guidance for the next safe model boundary without cancelling the turn. Clients must discover the method first and treat <code>InvalidRequest</code> as not queued.</span><span class="l-zh">Reasonix 还会通过 <code>agentCapabilities._meta</code> 声明厂商方法 <code>_reasonix.io/session/steer</code>。Host 可在 <code>session/prompt</code> 活动期间调用它，把用户引导排入下一个安全模型边界，而无需取消当前回合。客户端必须先发现该方法，并把 <code>InvalidRequest</code> 视为“未入队”。</span></p> |
| 273 | <div class="callout"><span class="ico">i</span><span><span class="l-en">ACP steering is a namespaced ACP v1 extension, not a core <code>session/steer</code> method and not the unreleased ACP v2 <code>session/inject</code> proposal. See the <a href={`${repo}/blob/main-v2/docs/ACP.md`}>complete ACP integration guide</a> for lifecycle methods, capability negotiation, MCP transport shapes, compatibility, errors, and a client checklist.</span><span class="l-zh">ACP 回合中引导是带命名空间的 ACP v1 扩展，不是核心 <code>session/steer</code> 方法，也不是尚未发布的 ACP v2 <code>session/inject</code> 提案。生命周期方法、能力协商、MCP transport 结构、兼容性、错误处理和客户端检查清单见<a href={`${repo}/blob/main-v2/docs/ACP.zh-CN.md`}>完整 ACP 接入文档</a>。</span></span></div> |
| 274 | |
| 275 | <h2 id="memory"><span class="l-en">Memory & rewind</span><span class="l-zh">记忆与回退</span></h2> |
| 276 | <p><span class="l-en">Reasonix keeps project memory in <code>REASONIX.md</code> or <code>AGENTS.md</code>, and stores approved auto-memory facts under Reasonix home. During turns, read-only <code>history</code> and <code>memory</code> tools retrieve prior sessions, compacted archives, and saved facts on demand instead of injecting noisy dynamic state into the stable prompt prefix.</span><span class="l-zh">Reasonix 将项目记忆放在 <code>REASONIX.md</code> 或 <code>AGENTS.md</code>,并把经过批准的 auto-memory fact 存在 Reasonix home 下。运行时,只读 <code>history</code> 与 <code>memory</code> 工具按需检索历史会话、压缩归档和已保存事实,而不是把易变状态塞进稳定 prompt 前缀。</span></p> |
| 277 | <p><span class="l-en">Agent-initiated <code>remember</code> and <code>forget</code> always ask for fresh approval, even in YOLO. <code>/memory</code> shows active and archived facts; <code>/forget</code> archives rather than permanently erasing a fact from traceability.</span><span class="l-zh">模型主动调用 <code>remember</code> 与 <code>forget</code> 时,即使在 YOLO 下也会重新请求批准。<code>/memory</code> 可查看 active 与 archived facts；<code>/forget</code> 会归档而不是永久抹掉可追溯记录。</span></p> |
| 278 | <p><span class="l-en">Rewind is snapshot-based, not git-based. Press double <code>Esc</code> in the CLI, use <code>/rewind</code>, or use the desktop hover control to restore code, conversation, or both from an earlier turn without touching <code>.git</code>.</span><span class="l-zh">回退基于文件快照,不是 git。CLI 中双击 <code>Esc</code>、使用 <code>/rewind</code>,或在桌面端用户消息上使用 hover 控件,即可从较早 turn 恢复代码、对话或两者,不会触碰 <code>.git</code>。</span></p> |
| 279 | |
| 280 | <h2 id="cli"><span class="l-en">CLI & slash commands</span><span class="l-zh">命令行与斜杠命令</span></h2> |
| 281 | <div class="codeblock">reasonix setup <span class="c"># first-run: pick provider + keys</span> |
| 282 | reasonix <span class="c"># interactive session, prompts before writes</span> |
| 283 | reasonix run "<task>" <span class="c"># headless Ask; writers fail closed</span> |
| 284 | reasonix run -y "<task>" <span class="c"># opt into unattended ordinary writes</span> |
| 285 | reasonix serve <span class="c"># browser UI at 127.0.0.1:8787</span> |
| 286 | reasonix bot doctor <span class="c"># check saved IM bot connections</span></div> |
| 287 | <div class="codeblock">reasonix config compact-ratio <span class="c"># effective value + source</span> |
| 288 | reasonix config compact-ratio 75 <span class="c"># user-global default</span> |
| 289 | reasonix config compact-ratio --local 75 <span class="c"># project override</span></div> |
| 290 | <p><span class="l-en">Run <code>reasonix upgrade</code> to install the latest official release. Legacy channel arguments and saved channel settings remain accepted during the 1.x compatibility period, but they resolve to the same official release and are removed when configuration is saved.</span><span class="l-zh">运行 <code>reasonix upgrade</code> 安装最新正式版。1.x 兼容期内仍接受旧渠道参数与已保存设置，但它们都会解析为同一正式版，并在下次保存配置时移除。</span></p> |
| 291 | <div class="codeblock">reasonix upgrade |
| 292 | reasonix upgrade</div> |
| 293 | <p><span class="l-en">Inside a session, slash commands run locally — <code>/help</code> lists them all:</span><span class="l-zh">会话中,斜杠命令在本地运行——<code>/help</code> 列出全部:</span></p> |
| 294 | <div class="codeblock">/compact /new /clear /rewind /tree |
| 295 | /branch /switch /todo /model /mouse /mcp |
| 296 | /skills /hooks /memory /sandbox /docs |
| 297 | /language /theme /work-mode /paste-image /goal |
| 298 | /reasoning-language /output-style /help</div> |
| 299 | <p><span class="l-en"><code>Shift+Tab</code> cycles Ask → Auto → Plan, while <code>Ctrl+Y</code> toggles YOLO independently. Use <code>/theme auto|light|dark</code> for the terminal background mode or choose a named accent from bare <code>/theme</code>. Long drafts grow and then scroll inside the composer; wheel events over the transcript continue to scroll the conversation.</span><span class="l-zh"><code>Shift+Tab</code> 按 Ask → Auto → Plan 循环，<code>Ctrl+Y</code> 独立切换 YOLO。用 <code>/theme auto|light|dark</code> 选择终端背景模式，也可从不带参数的 <code>/theme</code> 中选择命名强调色。长草稿会先增长，超过上限后在输入框内滚动；鼠标位于 transcript 时仍滚动对话。</span></p> |
| 300 | <p><span class="l-en">The responsive footer shows the active permission posture and interaction state first. Wide terminals keep model, effort, and work mode together on the right, with available Git, cache, context, compaction, job, and balance telemetry below. <code>ready</code> means the composer is idle; pickers, approvals, image paste, shell mode, and other interactions replace it. Narrow terminals move or compact complete groups, and visible labels follow <code>/language</code>.</span><span class="l-zh">响应式底栏优先显示当前权限姿态和交互状态；终端较宽时，模型、推理强度和工作模式在右侧成组显示，下方按可用性显示 Git、缓存、上下文、压缩余量、任务和余额。“就绪”表示输入框空闲；选择器、审批、图片粘贴、shell 模式等活动会替换它。窄终端会移动或压缩完整信息组，可见标签跟随 <code>/language</code>。</span></p> |
| 301 | <p><span class="l-en">Mouse capture is on by default so Reasonix can handle transcript selection, wheel scroll, and the scrollbar. Turn it off with <code>/mouse</code>, or start with <code>REASONIX_DISABLE_MOUSE=1</code>, when you prefer the terminal's own selection behavior.</span><span class="l-zh">默认会开启鼠标接管，用于对话选中、滚轮滚动和滚动条。需要终端自己的选中行为时，用 <code>/mouse</code> 关闭；也可以用 <code>REASONIX_DISABLE_MOUSE=1</code> 默认关闭。</span></p> |
| 302 | <p><span class="l-en">In a local session, releasing an in-app text selection copies through the native system clipboard and shows success only after the write completes. SSH falls back to a clearly labelled OSC 52 request. Text paste remains your terminal's bracketed-paste shortcut, such as <code>Cmd+V</code> on macOS. Image paste is separate: use <code>Ctrl+V</code> on macOS/Linux, <code>Alt+V</code> on Windows, or <code>/paste-image</code>; the footer shows <code>Pasting image…</code> while the attachment is prepared.</span><span class="l-zh">本地会话中，应用内文本选区会写入系统剪贴板，只有写入完成后才提示成功；SSH 会回退到明确标记的 OSC 52 请求。文本继续使用终端原生 bracketed-paste 快捷键，例如 macOS 的 <code>Cmd+V</code>。图片粘贴使用独立入口：macOS/Linux 按 <code>Ctrl+V</code>，Windows 按 <code>Alt+V</code>，或运行 <code>/paste-image</code>；附件准备期间底栏显示“正在粘贴图片…”。</span></p> |
| 303 | <p><span class="l-en"><code>/branch [name]</code> forks the current conversation tip, <code>/switch <id|name></code> loads another branch, and <code>/clear</code> confirms before discarding unsaved context. Custom commands are Markdown files under <code>.reasonix/commands/</code> or <code>~/.reasonix/commands/</code>.</span><span class="l-zh"><code>/branch [name]</code> 从当前会话尖端分叉,<code>/switch <id|name></code> 加载另一条分支,<code>/clear</code> 会确认后丢弃未保存上下文。自定义命令是 <code>.reasonix/commands/</code> 或 <code>~/.reasonix/commands/</code> 下的 Markdown 文件。</span></p> |
| 304 | <p><span class="l-en"><code>/goal</code> is for long-running objectives. Ordinary chat never changes mode automatically. Goals run under a per-class budget (simple 10 turns / 200k tokens, write 20 turns / 400k tokens, AutoResearch 40 turns / 800k tokens; 4 turns without host-verifiable progress pause) — <code>/goal status</code> shows the runtime, <code>/goal pause</code> suspends, <code>/goal resume</code> continues (budget pauses add one more slice). Each goal turn ends with a structured <code>update_goal</code> report (continue/complete/blocked) that the host validates against Delivery readiness; without a report, an independent bounded evaluator judges the turn once and any failure pauses safely. Clearly long-horizon work can use the AutoResearch strategy, which keeps state under <code>.reasonix/autoresearch/...</code>, tracks evidence, and forces a new direction when progress stalls. Use <code>/goal --research <objective></code> to force it or <code>/goal --simple <objective></code> to keep the lightweight path. AutoResearch is a Goal strategy, not a separate app-start daemon or standalone built-in skill.</span><span class="l-zh"><code>/goal</code> 用于长目标。普通聊天不会自动切换模式。Goal 按类别运行在预算内（简单 10 轮 / 20 万 token，写入型 20 轮 / 40 万 token，AutoResearch 40 轮 / 80 万 token；连续 4 轮无宿主可验证进展会暂停）——<code>/goal status</code> 显示运行摘要，<code>/goal pause</code> 暂停，<code>/goal resume</code> 继续（预算型暂停追加一档额度）。每个目标 turn 结束时通过结构化的 <code>update_goal</code> 报告（continue/complete/blocked），宿主会用 Delivery readiness 校验；没有报告时由独立有界 evaluator 判定一次，任何故障都会安全暂停。明显长周期的任务可以启用 AutoResearch 策略，在 <code>.reasonix/autoresearch/...</code> 下保存状态、记录证据，并在进展停滞时强制换方向。用 <code>/goal --research <目标></code> 强制启用，或用 <code>/goal --simple <目标></code> 保持轻量路径。AutoResearch 是 Goal 的策略，不是 App 启动即运行的 daemon，也不是独立内置 skill。</span></p> |
| 305 | <p><span class="l-en">Use <code>@path</code> to inject files or directories, and <code>@server:uri</code> for MCP resources. Plan Mode is an explicit user choice: select it in the desktop collaboration control or cycle to it with <code>Shift+Tab</code> in the CLI. <code>reasonix config reasoning-language auto|zh|en</code> updates the user default from scripts; <code>--local</code> remains available for settings that support project-local overrides.</span><span class="l-zh">用 <code>@path</code> 注入文件或目录,用 <code>@server:uri</code> 引入 MCP resource。计划模式始终由用户显式选择：桌面端在协作方式中选择，CLI 用 <code>Shift+Tab</code> 切换。脚本中可用 <code>reasonix config reasoning-language auto|zh|en</code> 更新用户级默认值；<code>--local</code> 仍可用于支持项目级覆盖的设置。</span></p> |
| 306 | |
| 307 | <h2 id="embedded-docs"><span class="l-en">Built-in documentation search</span><span class="l-zh">内置文档检索</span></h2> |
| 308 | <p><span class="l-en">Every CLI and Desktop release bundles the reviewed Markdown guides and release-note catalog from that exact source revision. Search is local and offline, and every result identifies the product version, source revision, and corpus digest. Release CI rejects a build when its embedded corpus does not match the release candidate, so an installed version keeps version-matched guidance instead of silently switching to newer website content.</span><span class="l-zh">每个 CLI 与桌面端版本都会内置该源码 revision 对应的、经过审查的 Markdown 指南和更新日志目录。检索完全在本地离线完成，每条结果都会标明产品版本、源码 revision 与语料 digest。发布 CI 会拒绝内置语料与候选版本不匹配的构建，因此已安装版本始终使用与自身版本匹配的说明，不会静默切换到更新的官网内容。</span></p> |
| 309 | <div class="codeblock">/docs <span class="c"># corpus version, revision, digest, and examples</span> |
| 310 | /docs 1.19.5 changelog <span class="c"># search locally, then answer with the configured AI</span> |
| 311 | /docs 1.19.5 更新日志 <span class="c"># 中文问题会优先返回中文证据</span></div> |
| 312 | <p><span class="l-en">Bare <code>/docs</code> only displays local corpus information and does not call a model. With a question, Reasonix retrieves version-matched evidence first, then asks the AI configured for the current session to produce a sourced answer. Ordinary natural-language questions can also trigger the read-only <code>docs</code> tool automatically, but the slash command guarantees retrieval before the answer instead of relying on the model to choose the tool.</span><span class="l-zh">直接输入 <code>/docs</code> 只显示本地语料信息，不调用模型。带问题时，Reasonix 会先检索与版本匹配的证据，再交给当前会话配置的 AI 生成带来源的回答。普通自然语言问题也可能自动触发只读 <code>docs</code> 工具；斜杠命令则保证先检索再回答，不依赖模型自行决定是否调用工具。</span></p> |
| 313 | <div class="callout"><span class="ico">i</span><span><span class="l-en">Custom commands and compatible plugin or skill aliases keep ownership of <code>/docs</code>. If it is already taken, choose the built-in entry shown in the slash menu—normally <code>/reasonix:docs</code>, or the next free <code>reasonix:</code>-qualified name. Reasonix never overwrites the existing command. CLI and Desktop use the same rule; a remote Desktop displays the command catalog resolved by its host.</span><span class="l-zh">自定义命令以及兼容插件或 Skill 别名会继续拥有 <code>/docs</code>。如果该名称已被占用，请使用斜杠菜单中显示的内置入口——通常是 <code>/reasonix:docs</code>，或下一个空闲的 <code>reasonix:</code> 限定名。Reasonix 不会覆盖已有命令。CLI 与桌面端遵循同一规则；远程桌面端显示由主机解析后的命令目录。</span></span></div> |
| 314 | <p><span class="l-en">For the complete retrieval contract, corpus filters, tool schema, and maintainer release checks, see the <a href={`${repo}/blob/main-v2/docs/GUIDE.md#embedded-documentation-retrieval`}>full guide</a> and <a href={`${repo}/blob/main-v2/docs/TOOL_CONTRACT.md`}>tool contract</a>.</span><span class="l-zh">完整检索约定、语料筛选、工具 schema 与维护者发版检查见<a href={`${repo}/blob/main-v2/docs/GUIDE.zh-CN.md#内置文档检索`}>完整指南</a>和<a href={`${repo}/blob/main-v2/docs/TOOL_CONTRACT.zh-CN.md`}>工具契约</a>。</span></p> |
| 315 | |
| 316 | <h2 id="configfile"><span class="l-en">Config file</span><span class="l-zh">配置文件</span></h2> |
| 317 | <p><span class="l-en">Resolution order: flags > <code>./reasonix.toml</code> > global <code>config.toml</code> under Reasonix home > compatible legacy config > built-in defaults. Starting with v1.8.1, Reasonix home is <code>~/.reasonix</code> on macOS/Linux and <code>%APPDATA%\reasonix</code> on Windows; set <code>REASONIX_HOME</code> only for tests, CI, or portable installs.</span><span class="l-zh">解析顺序:flags > <code>./reasonix.toml</code> > Reasonix home 下的全局 <code>config.toml</code> > 兼容 legacy config > 内置默认值。从 v1.8.1 起,Reasonix home 在 macOS/Linux 为 <code>~/.reasonix</code>,Windows 为 <code>%APPDATA%\reasonix</code>；只有测试、CI 或便携安装才需要设置 <code>REASONIX_HOME</code>。</span></p> |
| 318 | <div class="codeblock"><span class="c"># ~/.reasonix/config.toml (macOS/Linux)</span> |
| 319 | default_model = "deepseek-flash" |
| 320 | |
| 321 | [ui] |
| 322 | shortcut_layout = "desktop" <span class="c"># optional compatibility setting</span> |
| 323 | |
| 324 | [agent] |
| 325 | reasoning_language = "auto" <span class="c"># auto|zh|en</span> |
| 326 | compact_ratio = 0.8 <span class="c"># editable as 65–85% in Settings or CLI</span> |
| 327 | planner_model = "deepseek-pro" <span class="c"># optional read-only planner</span> |
| 328 | |
| 329 | [[providers]] |
| 330 | name = "deepseek-flash" |
| 331 | kind = "openai" |
| 332 | base_url = "https://api.deepseek.com" |
| 333 | model = "deepseek-v4-flash" |
| 334 | api_key_env = "DEEPSEEK_API_KEY" |
| 335 | |
| 336 | [tools] |
| 337 | enabled = [] <span class="c"># empty = all built-ins</span> |
| 338 | bash_timeout_seconds = 120 |
| 339 | mcp_call_timeout_seconds = 300 |
| 340 | |
| 341 | [permissions] |
| 342 | mode = "ask" <span class="c"># ask|allow|deny</span> |
| 343 | deny = ["Bash(rm -rf*)", "Bash(git push*)"] |
| 344 | allow = ["Bash(go test:*)"] |
| 345 | |
| 346 | [sandbox] |
| 347 | workspace_root = "" <span class="c"># empty = current dir</span> |
| 348 | allow_write = ["/tmp"] |
| 349 | forbid_read = ["${HOME}/.ssh"] |
| 350 | |
| 351 | [serve] |
| 352 | auth_mode = "none" <span class="c"># none|token|password</span> |
| 353 | behind_proxy = false <span class="c"># true only behind trusted proxy</span> |
| 354 | |
| 355 | [[plugins]] |
| 356 | name = "example" |
| 357 | command = "reasonix-plugin-example" |
| 358 | call_timeout_seconds = 600</div> |
| 359 | <p><span class="l-en">Legacy config, credentials, memory, and sessions are migrated non-destructively when v1.8.1+ starts. If Reasonix was opened before old paths were available, run <code>/migrate</code> from the CLI TUI or desktop composer. For the full schema and every field's contract, see <a href={`${repo}/blob/main-v2/docs/SPEC.md`}>SPEC.md §5</a>.</span><span class="l-zh">v1.8.1+ 启动时会非破坏性迁移 legacy config、credentials、memory 与 sessions。如果旧路径尚不可用时已经打开过 Reasonix,可在 CLI TUI 或桌面端 composer 中运行 <code>/migrate</code>。完整 schema 与每个字段的契约见 <a href={`${repo}/blob/main-v2/docs/SPEC.md`}>SPEC.md §5</a>。</span></p> |
| 360 | |
| 361 | <h2 id="surfaces"><span class="l-en">Desktop & bots</span><span class="l-zh">桌面端与 Bot</span></h2> |
| 362 | <p><span class="l-en">The desktop app shares the same config, global provider-key file, controller, permissions, sandbox, MCP lifecycle, memory, and checkpoint model as the CLI. Desktop-only settings such as shortcuts and bot connections are stored under Reasonix home.</span><span class="l-zh">桌面端与 CLI 共用同一套 config、全局 provider 密钥文件、controller、权限、沙箱、MCP 生命周期、记忆与 checkpoint 模型。快捷键、Bot 连接等桌面端设置存储在 Reasonix home 下。</span></p> |
| 363 | <p><span class="l-en">From <strong>Settings -> Bots</strong>, connect Feishu, Lark, or WeChat, then send Reasonix messages from IM. The local desktop runtime handles model calls, tools, approvals, and sandboxing, while IM receives progress, approval cards or text commands, and final results. Headless gateways can be started with <code>reasonix bot start --channels feishu,lark,weixin --dir /path/to/project</code>.</span><span class="l-zh">在 <strong>Settings -> Bots</strong> 中连接飞书、Lark 或微信后,即可从 IM 给 Reasonix 发消息。本地桌面运行时负责模型调用、工具、审批和沙箱,IM 侧接收进度、审批卡片或文本命令以及最终结果。也可以用 <code>reasonix bot start --channels feishu,lark,weixin --dir /path/to/project</code> 启动 headless gateway。</span></p> |
| 364 | |
| 365 | <div class="doc-cards"> |
| 366 | <a class="doc-card" href={`${base}/#surfaces`}> |
| 367 | <h3><span class="l-en">One engine, four surfaces →</span><span class="l-zh">一个引擎,四个入口 →</span></h3> |
| 368 | <p><span class="l-en">Terminal, desktop app, browser, and ACP editors share this config.</span><span class="l-zh">终端、桌面端、浏览器与 ACP 编辑器共用这套配置。</span></p> |
| 369 | </a> |
| 370 | <a class="doc-card" href={`${repo}/blob/main-v2/docs/CONFIG_PATHS.md`}> |
| 371 | <h3><span class="l-en">Configuration paths →</span><span class="l-zh">配置路径 →</span></h3> |
| 372 | <p><span class="l-en">Reasonix home, credentials, sessions, archives, memory, and migration rescue.</span><span class="l-zh">Reasonix home、凭据、会话、归档、记忆与迁移救援。</span></p> |
| 373 | </a> |
| 374 | <a class="doc-card" href={`${repo}/blob/main-v2/docs/REASONING_LANGUAGE.md`}> |
| 375 | <h3><span class="l-en">Reasoning language →</span><span class="l-zh">思考语言 →</span></h3> |
| 376 | <p><span class="l-en">Visible thinking language preference without changing the stable prompt prefix.</span><span class="l-zh">可见思考语言偏好,不改变稳定 prompt 前缀。</span></p> |
| 377 | </a> |
| 378 | <a class="doc-card" href={`${repo}/blob/main-v2/docs/CHECKPOINTS.md`}> |
| 379 | <h3><span class="l-en">Checkpoints & rewind →</span><span class="l-zh">检查点与回退 →</span></h3> |
| 380 | <p><span class="l-en">Restore code, conversation, or both from snapshot-based checkpoints.</span><span class="l-zh">通过快照式 checkpoint 恢复代码、对话或两者。</span></p> |
| 381 | </a> |
| 382 | <a class="doc-card" href={`${repo}/blob/main-v2/docs/CAPABILITY_DIAGNOSTICS.md`}> |
| 383 | <h3><span class="l-en">Capability diagnostics →</span><span class="l-zh">能力诊断 →</span></h3> |
| 384 | <p><span class="l-en"><code>reasonix doctor capabilities</code>, desktop Diagnostics, and <code>/reasonix-guide</code>.</span><span class="l-zh"><code>reasonix doctor capabilities</code>、桌面端诊断与 <code>/reasonix-guide</code>。</span></p> |
| 385 | </a> |
| 386 | <a class="doc-card" href={`${repo}/blob/main-v2/docs/EXTENSIONS.md`}> |
| 387 | <h3><span class="l-en">Build an extension →</span><span class="l-zh">开发扩展 →</span></h3> |
| 388 | <p><span class="l-en">Start with a complete Sidecar, Manifest v1, Go SDK, reload loop, and security model.</span><span class="l-zh">从完整 Sidecar、Manifest v1、Go SDK、重载循环与安全模型开始。</span></p> |
| 389 | </a> |
| 390 | <a class="doc-card" href={`${repo}/blob/main-v2/docs/BOT_GUIDE.md`}> |
| 391 | <h3><span class="l-en">Bot guide →</span><span class="l-zh">Bot 指南 →</span></h3> |
| 392 | <p><span class="l-en">Connect Feishu, Lark, and WeChat bots, then approve work from IM.</span><span class="l-zh">连接飞书、Lark 与微信 Bot,并从 IM 中审批任务。</span></p> |
| 393 | </a> |
| 394 | <a class="doc-card" href={`${repo}/graphs/contributors`}> |
| 395 | <h3><span class="l-en">Contribute →</span><span class="l-zh">参与贡献 →</span></h3> |
| 396 | <p><span class="l-en">Reasonix is MIT-licensed and open source — good first issues are waiting.</span><span class="l-zh">Reasonix 采用 MIT 许可、开源——新手友好任务等着你。</span></p> |
| 397 | </a> |
| 398 | </div> |
| 399 | </article> |
| 400 | </main> |
| 401 | |
| 402 | <footer> |
| 403 | <div class="foot-inner"> |
| 404 | <a class="brand" href={`${base}/`}><img src={`${base}/logo.svg`} alt="Reasonix logo" /><span>Reasonix</span></a> |
| 405 | <span><span class="l-en">© 2026 Reasonix · MIT licensed · built to be left running.</span><span class="l-zh">© 2026 Reasonix · MIT 许可 · 为常驻运行而生。</span></span> |
| 406 | <nav class="foot-links"> |
| 407 | <a href={repo}>GitHub</a> |
| 408 | <a href={`${base}/docs/`}><span class="l-en">Docs</span><span class="l-zh">文档</span></a> |
| 409 | <a href={`${base}/#start`}><span class="l-en">Install</span><span class="l-zh">安装</span></a> |
| 410 | <a href="https://crash.reasonix.io/stats" rel="nofollow"><span class="l-en">Stats</span><span class="l-zh">统计</span></a> |
| 411 | </nav> |
| 412 | </div> |
| 413 | </footer> |
| 414 | </Base> |
| 415 |