> ## Documentation Index
> Fetch the complete documentation index at: https://agent.minimaxi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 工作流

> 使用 MiniMax Code CLI 完成仓库协作、多轮任务、计划、权限和 Session 恢复。

<div className="code-docs">
  本页聚焦交互式 TUI 中最常见的开发闭环：理解仓库、规划任务、修改和验证、继续或恢复 Session。

  ## 从仓库开始

  ```bash theme={null}
  cd /path/to/project
  mcode init .
  mcode
  ```

  `mcode init .` 会以 `/init` 任务分析目录结构、项目规则、相关实现和可用脚本，并生成或更新 `AGENTS.md`。之后运行 `mcode`，让 Agent 在当前工作区中读取规则并执行任务。

  一个适合首轮对话的提示：

  ```text theme={null}
  先阅读项目规则和相关测试，说明失败原因；确认方案后修复，并运行最小相关测试。
  ```

  描述任务时，建议同时说明期望结果、修改边界和验证方式。Agent 会使用文件、搜索和终端工具完成代码或文档工作，并汇总修改和验证证据。

  ## 工作区上下文

  | 操作 | 用途 |
  | - | - |
  | `@` | 在工作区中搜索并引用文件或目录 |
  | `Ctrl+V` | 粘贴剪贴板中的图片或视频文件 |
  | `/add-dir <path>` | 增加一个可读写的工作区目录 |
  | `mcode exec --file <path>` | 在 Headless 任务中添加附件 |

  附件路径应使用当前工作区可访问的文件。Headless 单次最多 10 个附件，所有附件合计不超过 100 MB。

  ### 粘贴图片文件路径

  直接把图片文件的绝对路径粘贴到输入框，可以将图片添加为附件。含空格的路径可用外层引号包裹；从 0.4.11 起，macOS 和 Linux 终端也支持裸路径中的转义空格，例如：

  ```text theme={null}
  "/Users/you/Desktop/Screenshot 2026.png"
  /Users/you/Desktop/Screenshot\ 2026.png
  ```

  使用外层引号时，直接保留文件名中的空格即可。

  ### 预览粘贴的图片

  从 0.4.6 起，使用 `Ctrl+V` 粘贴图片后，输入框上方会显示预览，以及格式、尺寸、文件大小和文件名。将光标移回输入框中的图片标签，可以再次查看预览。

  按 `Esc` 收起预览；按 `Enter` 仍会提交输入内容。不支持图片显示的终端会显示图片信息；预览失败也不会阻止发送原图。

  ### 编辑带图片的消息

  从 0.4.8 起，在空输入框连续按两次 `Esc`，或使用 `/edit` 编辑上一条消息时，图片会恢复为可操作的 `[Image #1]` 标签。可以删除标签、撤销删除或重新发送；有可读本地文件时，光标移回标签可再次预览。

  当前进程内最近一次带附件提交会保留原标签位置；没有本地编辑快照的历史消息会在正文末尾重建标签。只有资源 ID、没有可读本地文件的图片仍保留标签和元信息。

  ### 查看运行耗时

  运行状态行、单轮结束摘要和 Goal 计时统一使用 `s`、`min`、`h`，例如 `30s`、`9min30s`、`2h9min30s`。运行耗时统计当前轮，Goal 统计累计活跃时间，两者数值可以不同。

  ## Plan Mode

  Plan Mode 适合目标较大、修改范围不确定或需要先审阅方案的任务。它只控制规划流程，不改变工具权限。

  ```text theme={null}
  /plan on
  ```

  常用操作：

  | 命令 | 作用 |
  | - | - |
  | `/plan on` | 开启 Plan Mode |
  | `/plan off` | 关闭 Plan Mode |
  | `/plan status` | 查看当前模式 |
  | `/plan view` | 查看最近的计划 |
  | `Shift+Tab` | 在交互界面中切换模式 |

  建议先让 Agent 给出实现范围和验证方案，再决定是否进入修改阶段。

  ## 权限与执行

  权限模式独立于 Plan Mode：

  | 模式 | 适合场景 | 注意事项 |
  | - | - | - |
  | Ask | 日常开发、希望逐项确认 | 需要交互式宿主 |
  | Auto | 常规任务和较顺畅的仓库协作 | 高风险操作仍可能询问 |
  | Full access | 已隔离、明确理解风险的工作区 | 跳过常规确认，谨慎使用 |
  | Off | 受控自动化环境 | 关闭权限模式前先确认运行边界 |

  TUI 中使用 `/permission ask`、`/permission auto`、`/permission full` 或快捷键 `Alt+M`；Headless 使用 `--permission smart|full|off`，其中 `smart` 对应 TUI 的 Auto。Headless 不接受 `ask`，因为没有人工交互界面。

  ## 队列与 Steer

  任务运行期间，按 `Enter` 会将消息 steer 给当前 Turn；按 `Alt+Enter` 才会把后续任务加入 Queue，等待当前响应结束后处理。也可以显式使用：

  ```text theme={null}
  /steer 优先修复类型错误，然后再运行完整测试
  ```

  如果已有待处理的权限或问卷，请先解决交互，再发送 steer。`/queue` 可以查看和管理等待中的消息。

  ## Goal：持续推进一个目标

  Goal 会跨多个 Turn 保留一个持久目标，适合迁移、重构或需要多轮验证的任务：

  ```text theme={null}
  /goal 完成 API 迁移并运行相关测试
  /goal budget=50K
  ```

  可用操作：

  | 命令 | 作用 |
  | - | - |
  | `/goal <objective>` | 创建或更新目标 |
  | `/goal budget=50K` | 设置或修改 Token 预算 |
  | `/goal budget=clear` | 移除预算上限 |
  | `/goal edit` | 编辑目标 |
  | `/goal pause` | 暂停自动继续 |
  | `/goal resume` | 恢复暂停或阻塞的目标 |
  | `/goal clear` | 清除当前目标 |

  ## Session 管理

  ### 启动、恢复和搜索

  ```bash theme={null}
  mcode --continue
  mcode --session
  mcode --session <session-id>
  ```

  TUI 内使用 `/sessions [query]` 搜索、恢复和管理 Session。启动参数 `--session`、`--continue` 和兼容别名 `--resume` 不能组合使用。

  ### 长对话和分支

  | 命令 | 用途 |
  | - | - |
  | `/new`（别名 `/clear`） | 新建 Session |
  | `/fork` | 从当前 Session 分叉一个分支 |
  | `/rewind` | 回退当前 Session |
  | `/edit` | 编辑当前 Session |
  | `/retry` | 失败后重试上一条消息 |
  | `/rename [title]` | 重命名 Session |
  | `/compact [instructions]` | 压缩较长上下文 |
  | `/export [path.md]` | 导出 Session |
  | `/transcript` | 浏览和搜索完整对话 |
  | `/copy` | 复制上一条响应为 Markdown |

  ## 一个可复用的开发闭环

  <Steps>
    <Step title="建立上下文">
      在仓库目录运行 `mcode`，先读取 `AGENTS.md`、相关实现和测试入口。
    </Step>

    <Step title="规划范围">
      对复杂任务使用 `/plan on`，让 Agent 说明修改范围、风险和验证方法。
    </Step>

    <Step title="执行修改">
      通过 `@` 添加关键文件，按需确认工具权限，并在运行中用队列或 `/steer` 补充信息。
    </Step>

    <Step title="验证与留档">
      运行相关测试，使用 `/status` 和 `/context` 检查运行状态，最后用 `/export` 或 `/transcript` 留存结果。
    </Step>
  </Steps>
</div>