Install, configure, and run coding work locally.安装、配置，并在本地运行编码任务。

CLI / TUICLI / TUI

Install the terminal app with one command on macOS, Linux, Windows, or WSL. reasonix opens the interactive TUI; reasonix run is the headless automation entry.一条命令安装终端应用,支持 macOS、Linux、Windows 或 WSL。reasonix 打开交互式 TUI；reasonix run 用于无界面自动执行。

Desktop app桌面端

macOS quarantine warningmacOS 隔离属性提示

Use this only when Reasonix was downloaded from the official site or GitHub release, moved to /Applications, 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.仅在 Reasonix 来自官网或 GitHub Release、已经放入 /Applications,但 macOS 仍提示“无法打开”“无法验证开发者”或“应用已损坏”时使用。它会移除 macOS 给下载应用附加的隔离属性。

Quick start快速上手

First run is minimal — reasonix setup walks you through picking a provider and key, then saves it under Reasonix home. Then point Reasonix at a repo and start a session:首次运行很简单——reasonix setup 引导你选择 provider 并填写密钥,然后保存到 Reasonix home。接着指向仓库、开始会话:

Then just describe the task:然后直接描述任务:

Run /init 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.需要项目记忆时运行 /init,然后让会话持续运行——上下文只追加,每一轮都从缓存命中开始,而不是冷启动。

Web frontendWeb 前端

reasonix web starts the same local Reasonix engine and opens its browser UI. Inside the CLI, /web hands the current session to that UI. Keep reasonix serve for supervisors, tunnels, reverse proxies, and remote development boxes.reasonix web 会启动同一个本地 Reasonix 引擎并打开浏览器 UI；在 CLI 中执行 /web 可把当前会话交接到该界面。进程托管、tunnel、反向代理和远程开发机继续使用 reasonix serve。

reasonix web starts at 127.0.0.1:8787, walks upward when the port is busy, and defaults to an automatically generated token. reasonix serve keeps its config-driven auth_mode = "none" default; enable auth before making Serve reachable from another machine.reasonix web 从 127.0.0.1:8787 开始监听，端口占用时自动递增，并默认生成 Token。reasonix serve 保持由配置决定的 auth_mode = "none" 默认值；如果其他机器可以访问 Serve，请先开启认证。

Configuration配置

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 api_key_env; the actual secret saved by reasonix setup or desktop Settings lives in the global <Reasonix home>/.env.Reasonix 使用你自己的 API Key 直连配置好的 OpenAI-compatible provider,例如 DeepSeek 或 MiMo。Provider 配置只在 api_key_env 里记录密钥名称；通过 reasonix setup 或桌面端设置保存的真实密钥会写入全局 <Reasonix home>/.env。

Project .env files are not provider-key fallbacks. They are only used for workspace-scoped variable expansion in MCP/plugin settings. Persistent options live in the config file.项目 .env 不是 provider key 的 fallback。它只用于 MCP/plugin 配置里的工作区级变量展开。持久化选项见配置文件。

Prefix cache前缀缓存

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.DeepSeek 对缓存前缀 token 的计费远低于新计算。多数智能体浪费了这一点:重排消息、会话中改写摘要、注入易变的时间戳——任何改动都会让其后的缓存全部失效。

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.Reasonix 以确定性方式序列化上下文,并且永远只追加。实际效果:数小时的会话中每次请求 90% 以上从缓存重放,输入 token 成本降到约 1/5。

Automatic compaction starts at 80% of the model context by default. Desktop Settings and reasonix config compact-ratio share the user-level value; choose 30–85%, or use --local for a project override. Lower values compact earlier, may increase summary calls and cost, and can reduce prefix-cache reuse.自动压缩默认在模型上下文达到 80% 时启动。桌面端设置与 reasonix config compact-ratio 共用用户级设置；可在 30–85% 之间选择，也可用 --local 添加项目覆盖。阈值越低越早压缩，可能增加摘要调用和成本，也可能降低前缀缓存复用率。

Permissions & sandbox权限与沙箱

Every surface uses one permission preset. Read only mounts session files read only; Workspace write allows the workspace and session-private temporary directory and is the default; Full access runs as the current OS user without Reasonix filesystem or network sandboxing, while explicit host denies still run before launch. Pipes, command substitution, and inline Python or Node do not trigger approval merely because of their syntax.所有入口共用同一权限模式：仅可查看强制会话文件只读；默认的工作区内修改允许写入工作区和会话私有临时目录；完全权限以当前系统账户运行，不使用 Reasonix 文件和网络沙箱，宿主仍会在启动前执行显式禁止规则。管道、命令替换及 Python/Node 内联脚本不会仅因语法触发审批。

Restricted presets use Seatbelt on macOS, bubblewrap on Linux, and a restricted token plus ACLs and Job Objects on Windows. If enforcement cannot start, the operation fails closed. Approvals are limited to Allow once, Allow for this session, and Deny; permanent grants are not offered.受限模式在 macOS 使用 Seatbelt，在 Linux 使用 bubblewrap，在 Windows 使用受限令牌、ACL 和 Job Object。强制边界无法启动时操作会失败关闭。审批只提供“允许一次／本会话允许／拒绝”，不再提供永久授权。

Extensions & sidecars扩展与 Sidecar

Plugin packages have two layers. Declarative contributions ship skills, agents, commands, prompts, hooks, MCP servers, and themes. A Manifest v2 runtime 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. Native Manifest v2 is an explicit capability boundary: Reasonix loads only resources declared in reasonix-plugin.json and does not implicitly import host-specific companion files such as a root CLAUDE.md or .mcp.json. Codex and Claude compatibility manifests keep their own mappings; Claude manifests do not load a plugin-root CLAUDE.md as project context.插件包分为两层：声明式贡献可以分发 skills、agents、commands、prompts、hooks、MCP server 与主题；Manifest v2 的 runtime 则启动独立 Sidecar，通过稳定的 Extension Protocol v1 拦截运行时事件、持有替换策略、提供流式模型 Provider，并发布结构化 UI。原生 Manifest v2 是显式能力边界：Reasonix 只加载 reasonix-plugin.json 中声明的资源，不会隐式导入根 CLAUDE.md、.mcp.json 等宿主专用伴随文件。Codex 与 Claude 兼容 manifest 继续采用各自映射；Claude manifest 不会把插件根 CLAUDE.md 当作项目上下文。

The repository includes a complete starter with its manifest, Go Sidecar, build commands, linked installation, reload loop, and visible input rewrite:仓库提供了完整 starter，包含 Manifest、Go Sidecar、构建命令、链接安装、重载循环与可观察的输入改写：

On Windows PowerShell, set $pluginRoot = (Resolve-Path .).Path and pass $pluginRoot to both install commands. Then send starter: explain sidecars to verify the intercept. The first public Go SDK release is sdk/go/v1.0.0; before that immutable tag exists, use the starter from a source checkout.Windows PowerShell 请先设置 $pluginRoot = (Resolve-Path .).Path，再把 $pluginRoot 传给两条安装命令。随后发送 starter: 解释 Sidecar 验证拦截。Go SDK 的首个公开版本是 sdk/go/v1.0.0；该不可变标签发布前，请直接从源码 checkout 使用 starter。

Continue with the extension guide, Manifest v2 reference, Go SDK, and wire protocol.后续请阅读扩展指南、Manifest v2 参考、Go SDK和线协议。

Plugins (MCP)插件(MCP)

Reasonix is an MCP client. A [[plugins]] entry's type selects the transport: stdio launches a local subprocess, while http connects to a Streamable HTTP server with optional headers expanded from the environment. Tools surface to the model as mcp__<server>__<tool>.Reasonix 是一个 MCP 客户端。[[plugins]] 条目的 type 选择传输方式：stdio 启动本地子进程；http 连接 Streamable HTTP server,可从环境变量展开静态 headers。工具以 mcp__<server>__<tool> 呈现给模型。

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. readOnlyHint and destructiveHint 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; read_only_task / read_only_skill never expose writers.安装 MCP server 本身就是授权决定，安装后工具直接可用，不再需要 server、逐工具、writer 或 destructive 审批设置。仓库声明的 server 只在启动前确认一次精确身份，身份变化时才重新确认；显式全局 deny 仍然优先。readOnlyHint 与 destructiveHint 只作为并行调度、Plan 限制、严格只读子会话和缓存到实时安全分类复核的内部事实；仅 schema 变化会刷新下一会话缓存，不再中断已授权调用。Plan 会硬阻断 MCP writer/destructive 目标和未授权 reader；read_only_task / read_only_skill 完全不暴露 writer。

MCP prompts also become slash commands such as /mcp__server__prompt, and MCP resources can be referenced with @server:uri. Enabled servers connect in the background after a session starts; use /mcp or the desktop MCP panel to inspect, refresh, reconnect, or disable servers. Already have an .mcp.json? Put it in the project root; Reasonix reads the Claude Code mcpServers schema as-is and lets reasonix.toml win on name collisions.MCP prompts 也会变成 /mcp__server__prompt 这样的斜杠命令,MCP resources 可通过 @server:uri 引用。启用的 server 会在会话开始后后台连接；用 /mcp 或桌面端 MCP 面板查看、刷新、重连或临时禁用。已有 .mcp.json?放到项目根目录即可；Reasonix 会原样读取 Claude Code 的 mcpServers schema,同名时 reasonix.toml 优先。

Editor integration (ACP)编辑器接入（ACP）

Reasonix implements Agent Client Protocol (ACP) v1 as an NDJSON JSON-RPC 2.0 agent over stdio. An ACP-compatible editor or host starts reasonix acp, opens workspace-scoped sessions, and receives streamed messages, tool activity, plans, permission requests, and configuration updates.Reasonix 实现了 Agent Client Protocol（ACP）v1，通过 stdio 提供 NDJSON JSON-RPC 2.0 agent。兼容 ACP 的编辑器或 host 启动 reasonix acp、打开工作区会话，并接收流式消息、工具活动、计划、权限请求和配置更新。

Reasonix also advertises the vendor method _reasonix.io/session/steer through agentCapabilities._meta. A host may call it while session/prompt is active to queue user guidance for the next safe model boundary without cancelling the turn. Clients must discover the method first and treat InvalidRequest as not queued.Reasonix 还会通过 agentCapabilities._meta 声明厂商方法 _reasonix.io/session/steer。Host 可在 session/prompt 活动期间调用它，把用户引导排入下一个安全模型边界，而无需取消当前回合。客户端必须先发现该方法，并把 InvalidRequest 视为“未入队”。

Memory & rewind记忆与回退

Reasonix keeps project memory in REASONIX.md or AGENTS.md, and stores approved auto-memory facts under Reasonix home. During turns, read-only history and memory tools retrieve prior sessions, compacted archives, and saved facts on demand instead of injecting noisy dynamic state into the stable prompt prefix.Reasonix 将项目记忆放在 REASONIX.md 或 AGENTS.md,并把经过批准的 auto-memory fact 存在 Reasonix home 下。运行时,只读 history 与 memory 工具按需检索历史会话、压缩归档和已保存事实,而不是把易变状态塞进稳定 prompt 前缀。

Agent-initiated remember and forget remain explicit user decisions. /memory shows active and archived facts; /forget archives rather than permanently erasing a fact from traceability.模型主动调用 remember 与 forget 时仍需用户明确决定。/memory 可查看 active 与 archived facts；/forget 会归档而不是永久抹掉可追溯记录。

Rewind is snapshot-based, not git-based. Press double Esc in the CLI, use /rewind, or use the desktop hover control to restore code, conversation, or both from an earlier turn without touching .git.回退基于文件快照,不是 git。CLI 中双击 Esc、使用 /rewind,或在桌面端用户消息上使用 hover 控件,即可从较早 turn 恢复代码、对话或两者,不会触碰 .git。

CLI & slash commands命令行与斜杠命令

Run reasonix upgrade 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.运行 reasonix upgrade 安装最新正式版。1.x 兼容期内仍接受旧渠道参数与已保存设置，但它们都会解析为同一正式版，并在下次保存配置时移除。

Inside a session, slash commands run locally — /help lists them all:会话中,斜杠命令在本地运行——/help 列出全部:

Shift+Tab cycles Read only → Workspace write → Plan. Full access is selected explicitly with --permission-mode danger-full-access. Use /theme auto|light|dark for the terminal background mode or choose a named accent from bare /theme.Shift+Tab 按“仅可查看 → 工作区内修改 → 计划”循环。完全权限必须用 --permission-mode danger-full-access 显式选择。可用 /theme auto|light|dark 选择终端背景模式。

The responsive footer shows the active permission posture and interaction state first. Wide terminals keep model and effort together on the right, with available Git, cache, context, compaction, job, and balance telemetry below. ready 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 /language.响应式底栏优先显示当前权限姿态和交互状态；终端较宽时，模型和推理强度在右侧成组显示，下方按可用性显示 Git、缓存、上下文、压缩余量、任务和余额。“就绪”表示输入框空闲；选择器、审批、图片粘贴、shell 模式等活动会替换它。窄终端会移动或压缩完整信息组，可见标签跟随 /language。

Mouse capture is on by default so Reasonix can handle transcript selection, wheel scroll, and the scrollbar. Turn it off with /mouse, or start with REASONIX_DISABLE_MOUSE=1, when you prefer the terminal's own selection behavior.默认会开启鼠标接管，用于对话选中、滚轮滚动和滚动条。需要终端自己的选中行为时，用 /mouse 关闭；也可以用 REASONIX_DISABLE_MOUSE=1 默认关闭。

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 Cmd+V on macOS. Image paste is separate: use Ctrl+V on macOS/Linux, Alt+V on Windows, or /paste-image; the footer shows Pasting image… while the attachment is prepared.本地会话中，应用内文本选区会写入系统剪贴板，只有写入完成后才提示成功；SSH 会回退到明确标记的 OSC 52 请求。文本继续使用终端原生 bracketed-paste 快捷键，例如 macOS 的 Cmd+V。图片粘贴使用独立入口：macOS/Linux 按 Ctrl+V，Windows 按 Alt+V，或运行 /paste-image；附件准备期间底栏显示“正在粘贴图片…”。

/branch [name] forks the current conversation tip, /switch <id|name> loads another branch, and /clear confirms before discarding unsaved context. Custom commands are Markdown files under .reasonix/commands/ or ~/.reasonix/commands/./branch [name] 从当前会话尖端分叉,/switch <id|name> 加载另一条分支,/clear 会确认后丢弃未保存上下文。自定义命令是 .reasonix/commands/ 或 ~/.reasonix/commands/ 下的 Markdown 文件。

/goal is for long-running objectives. Ordinary chat never changes mode automatically. Goal selects a simple (10), write (20), or research (40) turn budget and pauses after four turns without host-verifiable progress. /goal status shows the runtime, /goal pause suspends, and /goal resume continues. Every class uses the same Goal state machine, structured update_goal reports, host receipts, Delivery readiness, and bounded evaluator. Legacy research archives are read-only and new Goals never create them./goal 用于长目标。普通聊天不会自动切换模式。Goal 自动选择简单（10）、写入（20）或研究（40）轮预算，连续 4 轮无宿主可验证进展会暂停。/goal status 显示运行摘要，/goal pause 暂停，/goal resume 继续。所有预算类别共用同一个 Goal 状态机、结构化 update_goal、宿主 receipt、Delivery readiness 与有界 evaluator。旧研究归档保持只读，新 Goal 不再创建这些目录。

Use @path to inject files or directories, and @server:uri for MCP resources. Plan Mode is an explicit user choice: select it in the desktop collaboration control or cycle to it with Shift+Tab in the CLI. reasonix config reasoning-language auto|zh|en updates the user default from scripts; --local remains available for settings that support project-local overrides.用 @path 注入文件或目录,用 @server:uri 引入 MCP resource。计划模式始终由用户显式选择：桌面端在协作方式中选择，CLI 用 Shift+Tab 切换。脚本中可用 reasonix config reasoning-language auto|zh|en 更新用户级默认值；--local 仍可用于支持项目级覆盖的设置。

Built-in documentation search内置文档检索

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.每个 CLI 与桌面端版本都会内置该源码 revision 对应的、经过审查的 Markdown 指南和更新日志目录。检索完全在本地离线完成，每条结果都会标明产品版本、源码 revision 与语料 digest。发布 CI 会拒绝内置语料与候选版本不匹配的构建，因此已安装版本始终使用与自身版本匹配的说明，不会静默切换到更新的官网内容。

Bare /docs 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 docs tool automatically, but the slash command guarantees retrieval before the answer instead of relying on the model to choose the tool.直接输入 /docs 只显示本地语料信息，不调用模型。带问题时，Reasonix 会先检索与版本匹配的证据，再交给当前会话配置的 AI 生成带来源的回答。普通自然语言问题也可能自动触发只读 docs 工具；斜杠命令则保证先检索再回答，不依赖模型自行决定是否调用工具。

For the complete retrieval contract, corpus filters, tool schema, and maintainer release checks, see the full guide and tool contract.完整检索约定、语料筛选、工具 schema 与维护者发版检查见完整指南和工具契约。

Config file配置文件

Resolution order: flags > ./reasonix.toml > global config.toml under Reasonix home > compatible legacy config > built-in defaults. Starting with v1.8.1, Reasonix home is ~/.reasonix on macOS/Linux and %APPDATA%\reasonix on Windows; set REASONIX_HOME only for tests, CI, or portable installs.解析顺序:flags > ./reasonix.toml > Reasonix home 下的全局 config.toml > 兼容 legacy config > 内置默认值。从 v1.8.1 起,Reasonix home 在 macOS/Linux 为 ~/.reasonix,Windows 为 %APPDATA%\reasonix；只有测试、CI 或便携安装才需要设置 REASONIX_HOME。

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 /migrate from the CLI TUI or desktop composer. For the full schema and every field's contract, see SPEC.md §5.v1.8.1+ 启动时会非破坏性迁移 legacy config、credentials、memory 与 sessions。如果旧路径尚不可用时已经打开过 Reasonix,可在 CLI TUI 或桌面端 composer 中运行 /migrate。完整 schema 与每个字段的契约见 SPEC.md §5。

Desktop & bots桌面端与 Bot

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.桌面端与 CLI 共用同一套 config、全局 provider 密钥文件、controller、权限、沙箱、MCP 生命周期、记忆与 checkpoint 模型。快捷键、Bot 连接等桌面端设置存储在 Reasonix home 下。

From Settings -> Bots, 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 reasonix bot start --channels feishu,lark,weixin --dir /path/to/project.在 Settings -> Bots 中连接飞书、Lark 或微信后,即可从 IM 给 Reasonix 发消息。本地桌面运行时负责模型调用、工具、审批和沙箱,IM 侧接收进度、审批卡片或文本命令以及最终结果。也可以用 reasonix bot start --channels feishu,lark,weixin --dir /path/to/project 启动 headless gateway。