| 1 | # 协作方式与运行模式 |
| 2 | |
| 3 | Reasonix 桌面端输入框左下角的菜单包含两条互相独立的轴： |
| 4 | |
| 5 | - **计划模式**：要求模型先产出计划，确认后再切换到实施。 |
| 6 | - **目标模式**：给 Reasonix 一个目标，让它持续推进直到完成、阻塞或停止。 |
| 7 | - **运行模式**：在“轻量”“均衡”“交付优先”三档之间选择成本与交付质量倾向。 |
| 8 | |
| 9 | 计划模式和目标模式属于“协作方式”轴，通常二选一；运行模式是独立轴，可以和普通聊天、计划模式、目标模式任意组合。 |
| 10 | |
| 11 | ## 计划模式 |
| 12 | |
| 13 | 计划模式适合在动手前先确认方案。开启后，Reasonix 会收到“先规划、不要开始实施”的工作流指令，读取必要上下文、分析问题并给出计划。它不是权限边界：规划期间的任何工具调用仍由当前 Ask/Auto/Yolo、权限规则与 Sandbox 决定；`complete_step` 等显式执行阶段工具会等到计划批准后。 |
| 14 | |
| 15 | ### 怎么开启 |
| 16 | |
| 17 | - 点击输入框左下角的“协作方式”按钮，选择“计划”。 |
| 18 | - 也可以使用 `Shift+Tab` 切换计划模式。 |
| 19 | - 开启后输入框下方会显示“计划”标签；点击该标签或再次使用 `Shift+Tab` 可退出。 |
| 20 | |
| 21 | ### 建议使用场景 |
| 22 | |
| 23 | - 你还不确定实现方案，希望先看 Reasonix 的拆解。 |
| 24 | - 改动范围可能跨多个文件、模块或配置。 |
| 25 | - 需要先评估风险、测试面、兼容性或发布影响。 |
| 26 | - 你希望先让 Reasonix 阅读代码和文档、给出方案，再决定是否继续实施。 |
| 27 | |
| 28 | ### 注意事项 |
| 29 | |
| 30 | - 计划模式不是“自动完成任务”。它会先暂停在计划阶段，等待你确认。 |
| 31 | - 计划模式通过模型指令和确认步骤减少误改风险，但不替代 Ask、`deny` 规则或 Sandbox。 |
| 32 | - 如果你已经明确要直接改一个小问题，普通模式通常更快。 |
| 33 | - 计划模式只控制“先规划再执行”的流程，不决定成本或交付倾向；可按任务选择任一运行模式。 |
| 34 | - Ask 不是只读模式：需审批的 writer 在批准后仍可执行。需要技术上严格只读时，应使用显式只读 subagent/权限配置，而不是依赖 Plan 或 Ask。 |
| 35 | |
| 36 | ## 目标模式 |
| 37 | |
| 38 | 目标模式适合给 Reasonix 一个更长线的目标，让它持续推进。目标启动后，Reasonix 会围绕该目标工作，直到任务完成、遇到阻塞、被你停止，或需要你确认关键决策。 |
| 39 | |
| 40 | ### 怎么开启 |
| 41 | |
| 42 | - 点击“协作方式”按钮，选择“目标”。 |
| 43 | - 如果输入框里已有文字，选择“目标”会把当前文字作为目标启动。 |
| 44 | - 如果输入框为空，选择“目标”后会进入目标输入状态，输入目标并发送即可启动。 |
| 45 | - 开启后输入框下方会显示“目标”标签；点击该标签可退出目标模式。 |
| 46 | |
| 47 | ### 建议使用场景 |
| 48 | |
| 49 | - 你希望 Reasonix 连续完成一组相关步骤，例如“修复这个问题并补测试”。 |
| 50 | - 任务需要探索、实现、验证多个阶段。 |
| 51 | - 你希望减少中途反复下指令，让 Reasonix 在目标范围内持续推进。 |
| 52 | - 目标明显是长周期研究、排障或优化，例如“持续排查直到根因明确”“彻底实现并验证” |
| 53 | “不要原地打转”。这类目标会自动进入 AutoResearch 策略，把状态写到 |
| 54 | `.reasonix/autoresearch/<task-id>/`。 |
| 55 | |
| 56 | ### 推荐目标写法 |
| 57 | |
| 58 | 复杂目标可以写成一份任务合约：Context、Request、Output format、Constraints、Pause policy。 |
| 59 | Goal 模式会把这些部分当作任务边界；除非下一步涉及不可逆或对外可见操作、任务范围变化， |
| 60 | 或需要你提供信息，否则会继续完成任务后再汇报。完整模板见 |
| 61 | [`TASK_CONTRACT.zh-CN.md`](./TASK_CONTRACT.zh-CN.md)。 |
| 62 | |
| 63 | ### 注意事项 |
| 64 | |
| 65 | - 目标要写得具体。推荐包含范围、成功标准和限制，例如“只改桌面端输入栏，补前端测试，不改后端协议”。 |
| 66 | - 目标模式不是跳过审批。遇到高风险操作、权限限制、阻塞或需要产品判断时，仍可能停下来询问。 |
| 67 | - 如果目标过大或边界不清，Reasonix 可能需要更多探索轮次，也会消耗更多 token。 |
| 68 | - AutoResearch 是 Goal 的自动持久化策略，不是独立的后台 daemon，也不是 Settings 里的全局 skill。 |
| 69 | 可以用 `/goal --research <目标>` 强制启用，或用 `/goal --simple <目标>` 强制保持轻量 Goal。 |
| 70 | - 普通聊天不会因为目标文本看起来复杂或长周期而自动切换模式。只有明确选择“目标”或使用 |
| 71 | `/goal` 后，Reasonix 才会进入 Goal，并在 Goal 内判断是否采用 AutoResearch。 |
| 72 | - 目标模式和计划模式是同一协作轴。切到计划模式时，会退出目标草稿/目标显示状态；运行模式不会因此改变。 |
| 73 | |
| 74 | ## 运行模式 |
| 75 | |
| 76 | 运行模式决定会话启动时的工具面和执行合约。每个标签页独立保存选择；切换模式会重建当前会话运行时，但保留会话历史。 |
| 77 | |
| 78 | ### 轻量 · 节省 Token（Economy） |
| 79 | |
| 80 | Economy 对应原来的“省 token”模式。它不加载初始技能索引，只保留 `read_file`、`bash`、 |
| 81 | `edit_file`、`write_file`、后台 shell 生命周期工具、`ask` 和 `connect_tool_source`。 |
| 82 | 专用搜索/文件操作、workflow、session、memory、slash command、Skills、MCP、 |
| 83 | CodeGraph/LSP、`web_fetch`、安装来源和 subagent 等能力都放到 |
| 84 | `connect_tool_source` 后按需启用。 |
| 85 | |
| 86 | - 适合日常问答、代码解释、小范围阅读和成本敏感任务。 |
| 87 | - 主要降低每轮固定携带的提示词与工具 schema token，不会降低模型本身的推理能力。 |
| 88 | - 首次使用某类可选工具时可能多一个按需启用步骤。 |
| 89 | - 简单阅读和编辑可直接开始；目录查看与搜索默认通过 `bash` 完成。 |
| 90 | |
| 91 | ### 均衡 · 默认（Balanced） |
| 92 | |
| 93 | Balanced 是默认档，对应旧版本持久化值 `full`。它一次性提供完整工具面，不增加额外执行合约，由模型根据任务自主决定探索、实现与验证深度。 |
| 94 | |
| 95 | - 适合大多数普通开发与聊天任务。 |
| 96 | - `--profile balanced` 和不传 `--profile` 的运行语义不变；精简后的系统提示词会形成一次新的 provider 缓存前缀。 |
| 97 | - 旧 session/tab 中空值或 `full` 都会继续解释为 Balanced。 |
| 98 | |
| 99 | ### 交付优先 · 完整验证（Delivery） |
| 100 | |
| 101 | Delivery 使用与 Balanced 相同的完整工具面，额外增加稳定的能力代理工具 `use_capability`（list/inspect/call/decline，用于按需调用含 `auto_start=false` 的 MCP，且不把动态工具写入主 Registry），并增加稳定的交付合约：明确验收标准；条件允许时先复现；检查项目规则和相关代码；修复根因；运行聚焦验证；复审 diff 与相邻行为；没有证据时不宣称成功，并明确标注未验证项或假设。配置了独立 `planner_model` 时，Balanced 会为 Planner 与 Executor 分别挂载固定代理 frontend（ledger/audit 隔离、Host 共享），使规划阶段发现的 MCP capability 能在 handoff 后按同一 ID 直接执行。 |
| 102 | |
| 103 | - 适合编码、修 bug、跨文件实现和需要可靠交付证据的任务。 |
| 104 | - 通常会使用更多模型调用和 token，耗时也可能更长。 |
| 105 | - 宿主会在变更或验证命令前检查是否已有具体的 `todo_write` 验收清单；缺失时直接阻止执行并要求补齐。 |
| 106 | - 发生变更后，宿主会要求在最后一次变更之后复查结果、运行成功的验证命令，并用引用该命令的 `complete_step` 正式签收；不满足时拦截最终回答并自动要求继续。 |
| 107 | - 对明确要求实现、修复或修改的任务，如果没有观察到真实变更，宿主会拒绝“已经完成”的纯文本声明；只读分析仍可凭读取/检查证据正常结束。 |
| 108 | - Skill/MCP 的 `require`/`prefer` 路由由宿主门禁强制：`require` 必须成功调用（宿主确认不可用时可带真实 blocker 结束），`prefer` 缺失会提醒一次，之后必须调用或 `use_capability(action="decline")` 提交非空理由。 |
| 109 | - 中/高风险改动会强制运行结构化 `review` / `security_review`（通过审查子 Agent 的 `review_report`）；`task`/`run_skill` 等元工具本身不算 mutation，子 Agent 的真实写入会回传父级证据账本。 |
| 110 | - Delivery 的 system contract 与 `use_capability` Schema 是每个该 Profile 会话固定的 provider 前缀；按需连接 MCP 不会改变该固定代理 Schema。Balanced 双模型中的 Planner 代理同样稳定；Executor 刻意保留直接 `mcp__*` 工具，因此这些直接工具安装、连接或刷新时，Executor 的整体 provider 前缀仍可能变化。升级到本版本或从其他 Profile 切换过来会产生一次新的缓存前缀。 |
| 111 | |
| 112 | ### 怎么选择 |
| 113 | |
| 114 | - 桌面端点击输入框左下角菜单，在“运行模式”下选择“轻量 · 节省 Token”“均衡 · 默认”或“交付优先 · 完整验证”。 |
| 115 | - 轻量和交付优先模式会在输入框下方显示“轻量”或“交付优先”标签；点击标签可回到均衡模式。 |
| 116 | - CLI 启动时使用 `reasonix --profile economy|balanced|delivery`，非交互运行使用 `reasonix run --profile ...`。 |
| 117 | - TUI 会话内使用 `/work-mode economy|balanced|delivery` 热切换；不带参数的 `/work-mode` 会列出三档并标记当前项。`/profile` 保留为技术兼容别名，但帮助和补全以 `/work-mode` 为主。 |
| 118 | - 会话内切换会在保留 history、session 路径、审批/Yolo 状态的前提下原子重建 Controller。当前 turn、审批/询问或后台任务仍在运行时不能切换；构建失败时旧运行时继续可用。 |
| 119 | - `/work-mode` 只修改当前会话，不写入全局默认值。跨 Profile 切换会形成一次新的 provider 缓存前缀；均衡与交付优先模式内 system contract 与工具 Schema 保持稳定，轻量模式内每次成功连接工具来源都会形成一次新前缀，之后在工具面再次变化前保持稳定。 |
| 120 | |
| 121 | ## 协作方式与 Profile 如何组合 |
| 122 | |
| 123 | | 组合 | 是否支持 | 说明 | |
| 124 | | --- | --- | --- | |
| 125 | | 普通 + 轻量 | 支持 | 日常聊天的低开销选择。 | |
| 126 | | 计划 + 均衡 | 支持 | 先用完整工具面研究并确认方案，再执行。 | |
| 127 | | 目标 + 交付优先 | 支持 | 持续推进明确目标，并强调实现与验证闭环。 | |
| 128 | | 计划 + 目标 | 不建议同时使用 | 两者都是协作方式轴，切换计划会退出目标草稿/目标显示状态。 | |
| 129 | | 工具权限（询问/自动/Yolo）+ 任一组合 | 支持 | 工具权限控制工具审批；Sandbox 继续控制文件、进程与网络边界。 | |
| 130 | |
| 131 | 工具权限的详细区别和使用场景，见 [`TOOL_APPROVAL_MODES.zh-CN.md`](./TOOL_APPROVAL_MODES.zh-CN.md)。 |
| 132 | |
| 133 | ## 推荐选择 |
| 134 | |
| 135 | - **不确定怎么选**：保持均衡和普通模式。 |
| 136 | - **成本敏感或简单问答**：选择轻量。 |
| 137 | - **担心 Reasonix 改错**：开启计划模式先确认方案，并保持 Ask 与合适的 Sandbox 边界。 |
| 138 | - **想让 Reasonix 持续推进一个明确目标**：开启目标模式，目标写清楚成功标准。 |
| 139 | - **编码、修 bug 或复杂实现更看重最终质量**：选择交付优先，可再搭配目标模式。 |
| 140 |