> ## 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 恢复。

本页聚焦交互式 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 |

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

**1. 建立上下文**

在仓库目录运行 `mcode`，先读取 `AGENTS.md`、相关实现和测试入口。

**2. 规划范围**

对复杂任务使用 `/plan on`，让 Agent 说明修改范围、风险和验证方法。

**3. 执行修改**

通过 `@` 添加关键文件，按需确认工具权限，并在运行中用队列或 `/steer` 补充信息。

**4. 验证与留档**

运行相关测试，使用 `/status` 和 `/context` 检查运行状态，最后用 `/export` 或 `/transcript` 留存结果。