AI Agent 进阶使用指南 · 以 MiniMax Code 为例（附 Claude Code 对照）

先建立心智模型

Agent 是什么、它靠什么工作、你负责哪一段

传统聊天式 AI 的工作是「回答问题」；Agentic AI 的工作是「把事做完」。差别不在模型有多聪明，而在于它被赋予了工具和活动范围，并且被要求自己验证结果。

Part 1 · 大脑

模型：判断与规划

理解你的目标、读代码、决定下一步。模型能力决定上限，但规划质量更依赖你给的上下文。

Part 2 · 手脚

工具：真正改变世界

读写文件、执行终端命令、搜索代码、打开浏览器、调用 MCP 外部服务。改文件、跑测试这类动作才是「动手」。

Part 3 · 记忆

上下文：规则 + 记忆 + 现场

项目规则文件、长期记忆、当前会话历史、读到的文件内容，共同决定它「此刻知道什么」。

维度	聊天式 AI	Agentic AI（本指南主角）
产出	一段文字或代码片段	改好的文件、跑通的测试、可交付的成品
工作范围	你粘贴进去的那点内容	整个工作区目录，按需读取相关文件
能否执行	不能（你手动复制粘贴）	可以执行命令、装依赖、跑构建、开浏览器
典型失败	答得漂亮但不能用	看起来对但实际错、改动了不该改的文件、上下文跑偏
你的角色	提问者	定义目标、划定边界、验收结果

记住这个循环：目标 → 行动 → 观察结果 → 修正 → 直到满足验收标准。你写的每一条指令，本质都在为这个循环提供「起点」和「终点」。

两款主力工具：MiniMax Code 与 Claude Code

概念同源，学会一个，另一个迁移成本很低

主线示例

MiniMax Code（Mavis）

MiniMax 出品的智能体工作空间，主 Agent 名为 Mavis。三种入口：桌面端（macOS / Windows）、Web、CLI / TUI（命令 mcode）。桌面端开箱即用：Coding / Work 双模式、文件与变更面板、内置浏览器、插件市场、Agent Team、定时任务、远程控制。

桌面端优先Coding / WorkAgent Team插件市场

对照参考（来自附件 PDF，2026-07）

Claude Code

Anthropic 的官方 CLI 编程智能体，以终端为核心，另有 VS Code / JetBrains 扩展、桌面应用与 Web。强项是 Hooks 生命周期自动化、Subagents、Git Worktrees 并行、五层配置体系，可扩展生态成熟。

终端优先HooksSubagentsWorktrees

概念对照表：同一件事，两种叫法

概念	MiniMax Code	Claude Code
项目规则文件	工作区中的 `AGENTS.md`（`mcode init .` 生成/更新）	`CLAUDE.md`（`/init` 生成）、`CLAUDE.local.md`、`.claude/rules/`
配置与数据目录	`~/.minimax`：`config.yaml`、`mcp.json`、plugins、sessions	`~/.claude/` 与项目内 `.claude/`：`settings.json`、skills、agents
权限控制	权限确认机制；TUI 用 `Alt+M` 在 Ask / Auto / Full access 间切换	`Shift+Tab` 循环三种模式；`settings.json` 中 allow / ask / deny 规则
先规划再动手	Plan Mode（TUI `Shift+Tab`）	Plan Mode（`Shift+Tab`）
上下文命令	`/context` `/usage` `/compact` `/clear`	`/context` `/compact` `/clear` `/status` `/cost`
扩展机制	Skill、插件市场、MCP 服务、自定义 Agent、Mini App	Skills、Hooks、Subagents、Plugins、MCP
并行与分工	Agent Team、Subagent 独立会话、Worktree	Git Worktrees（`--worktree`）、Subagents（最多 5 层嵌套）、`/batch`
非交互 / CI	`mcode exec`	`claude -p "..."`、`--output-format json`
记忆	记忆摘要 + 主动记忆，会话内 `/memory` 控制	`CLAUDE.md`、Rules、`.claude/projects/` 记忆，`/memory` 查看
模型选择	MiniMax 模型 + BYOK 自定义供应商	sonnet / opus / fable / haiku 别名，专家策略：规划用强模型、执行用快模型

结论：两端都在做同一件事——把项目约定沉到文件里、把破坏性操作交给权限确认、把可重复流程封装成扩展。你在这篇里学到的思路，换任何一个 Agent 都通用。

装好它、登录、跑通第一次会话

桌面端 5 分钟，CLI 3 条命令

路线 A · 桌面端（推荐给入门者）

可视化、有审批面板、少踩坑

系统要求: macOS 12 Monterey 及以上；Windows 10 及以上
下载: 国内版 agent.minimaxi.com/download；海外版 agent.minimax.io/download
安装: macOS 拖入「应用程序」；Windows 运行安装程序按提示完成
登录: 启动后用 MiniMax 账号登录即可开始（无需自备 API Key）

当前桌面版 v3.0.73（2026-09-18），以官方更新日志为准。

路线 B · CLI / TUI

适合脚本、CI 与重度键盘用户

# 官方安装器（macOS / Linux / WSL）
curl -fsSL https://filecdn.minimax.chat/public/install.sh | bash

# Windows PowerShell
irm https://filecdn.minimax.chat/public/install.ps1 | iex

# 或手动 npm 安装（需 Node.js 22.19+ / 24 / 25 / 26）
npm install -g @minimax-ai/code

mcode --version   # 验证安装
mcode login     # 大陆账号；海外账号用 mcode login --region global

一键安装器会在需要时准备兼容的 Node.js，不需要 sudo / 管理员权限。

第一次跑通：三条命令

cd /path/to/your/project          # 进入项目目录
mcode init .                       # 分析目录结构，生成或更新 AGENTS.md
mcode "检查当前项目中失败的测试，修复后运行相关测试"

桌面端等价操作：新建任务 → 选择工作区目录 → 在输入框描述目标 → 发送。需要权限确认时，面板会停下来问你。

Claude Code 的安装对照（来自附件 PDF）： curl -fsSL https://claude.ai/install.sh | bash（原生安装器）、brew install claude-code（macOS）、 npm install -g @anthropic-ai/claude-code（不要用 sudo）；装完用 claude --version、claude doctor、claude update 验证。需要 Node.js 18+ / Python 3.10+、Git 与 Anthropic 付费计划或 API 额度。

「接入 API」到底指什么：三条路线

订阅登录 / 自己的 MiniMax Key / BYOK 任意兼容模型

Agent 本身不含模型，它需要一个「模型供应商」来思考。三条路线的差别只是谁来付费、用哪个模型，能力用法完全一致。

路线 1 · 最省事

订阅 / Token Plan 登录

桌面端用 MiniMax 账号登录即可；CLI 执行 mcode login。用量走账号额度，不需要自己保管密钥。

路线 2 · 自带 MiniMax Key

MiniMax API Key

在 设置 → 用量与模型 → MiniMax API 填入自己的 Key 并保存，用「连接测试」确认可用；CLI 侧用环境变量 MCODE_PROVIDER_API_KEY + mcode provider set-minimax-key。

路线 3 · 最灵活

BYOK 自定义供应商

用 Base URL + API Key + Model ID 接入任意兼容服务（企业网关、其他厂商模型）。可用性、上下文长度、多模态与费用由该供应商决定。

BYOK 配置流程（桌面端）

STEP 1打开设置设置 → 用量与模型 → 自定义模型 → 添加模型

STEP 2选供应商选预设提供商并填 API Key；没有就选「其他」

STEP 3填接口信息提供商名称、Base URL、API Key、API 格式

STEP 4加模型输入 Model ID，或点「自动获取」再挑

STEP 5检测并保存点「连通检测」通过后再保存，然后到模型菜单选用

CLI 等价做法（脚本化、可复现）

# 1) 把 Key 放进环境变量，不要写进仓库
export MCODE_PROVIDER_API_KEY="你的 API Key"

# 2) 添加一个兼容供应商（API 格式三选一：
#    anthropic-messages / openai-completions / openai-responses）
mcode provider add \
  --name "我的兼容服务" \
  --base-url "https://api.example.com/v1" \
  --api-format openai-completions \
  --model "model-id" \
  --use

# 3) 测试连通
mcode provider test <provider-id> --model <model-id>
mcode provider list   # 查看已配置项

三条路线怎么选

你的情况	建议
刚入门，只想跑通	路线 1，登录即用
已有 MiniMax API 额度	路线 2，独立计量
公司统一走网关 / 需要特定模型	路线 3，BYOK
要在 CI 里无人值守运行	CLI + 环境变量注入 Key

密钥红线（三条都适用）：不要把 API Key 写进对话正文、代码仓库或公开文档；只通过产品内的安全配置入口或环境变量保存。在 MCP / 插件配置里用占位符（如 ${COMPANY_MCP_TOKEN}）或系统密钥管理，不要提交真实 Token 与内部 URL。

创建项目、把本地文件夹交给 Agent

工作区是它的活动范围，越准确越不容易迷路

工作区（Workspace）是 Agent 理解本地项目的入口。选定目录后，它就能在该目录内读文件、执行命令、生成产物并汇报变更——这也是它和聊天框最本质的区别。

起手式 1

已有本地目录

在新建任务或输入框下方选择工作区，指向你的项目文件夹即可。最常用的一种。

起手式 2

从 Git 拉取仓库

让 Agent 执行 git clone <url> 再进入该目录；或你本地 clone 好后，在终端 cd 进去跑 mcode。

起手式 3

从零新建项目

新建空目录作为工作区，让 Agent 初始化脚手架、依赖与目录结构，再逐步演进。

选定工作区之后，你能用的三件「定位工具」

工具	作用	怎么用
`@` 引用文件	把具体文件拉进上下文，让 Agent 聚焦	输入框打 `@` 搜索工作区文件或目录
拖入文件	补充外部参考、截图、日志、数据表	直接把文件拖到对话区
`/` 调用技能	触发封装好的重复工作流	输入 `/` 查看可用命令与技能

模式选择

Coding 还是 Work？

场景	模式
读改代码仓库、开终端、看 diff	Coding
调试网页 / 预览 HTML 产物	Coding
只要结果，不关心实现细节	Work
文档整理、资料研究、表格处理	Work

两种模式共用同一套 Agent 能力，区别只在界面与工具暴露程度。Work 模式会隐藏部分开发面板。

执行过程可视化

右侧三块面板

文件：查看任务相关文件与交付物，Windows 端可直接预览 DOCX / XLSX / PPTX，markdown / SVG / LaTeX 可在预览与源码间切换。
变更：逐文件审查 diff，决定接受还是继续改。这是你最重要的验收入口。
终端：查看测试、构建、启动本地服务的真实输出。

项目规则文件：一次投入，长期回报

它是每次会话开始时自动加载的 Markdown。把「Agent 猜不到的事」写进去，比每次重复交代有效得多。控制在 100–200 行以内，太长会被压缩或忽略。

应该写什么

构建与测试命令（它无法从 package.json 猜到的那些）
架构概览 3–5 句：主要模块与通信方式
非显而易见的约定：「用 X 不用 Y」、命名与错误处理模式
硬性约束：「禁止编辑 /generated」「测试不得连接生产库」
已知陷阱、语言/运行时版本、Git 与 PR 规范

不要写什么

完整 API 文档（它能自己读代码）
它已经知道的标准语言约定
自明废话，如「写清晰的代码」
格式化规则——交给 Hook / linter 执行，而不是写在文字里
频繁变化的信息（过时指令比没有更糟）

# 项目上下文（AGENTS.md / CLAUDE.md 精简模板）
## 技术栈
- Next.js 15 / TypeScript / Prisma / PostgreSQL，Node.js 22+

## 常用命令
- 测试：`npm test`     - Lint：`npm run lint`
- 构建：`npm run build`  - 开发：`npm run dev`

## 架构
- pages/ 页面路由 · components/ 共享组件 · lib/ 业务逻辑 · prisma/ 数据模型

## 约定
- API 入参统一用 Zod 校验
- 组件用具名导出，不用 default export
- API 统一返回 `{ data, error }`

## 完成前必须做
- 跑通测试套件、跑 lint 与类型检查

## 契约
- 使用 pnpm，不要用 npm 安装依赖
- 禁止编辑 /generated 目录
- 不修改现有测试的断言，除非我明确要求

黄金法则：每次 Agent 做错一件事，就把正确做法写进规则文件，并对它说——「更新 AGENTS.md，这样你下次不会再犯同样的错。」
Claude Code 的对应做法完全一致：写进 CLAUDE.md；进阶还可用 .claude/rules/ 配合 YAML frontmatter 的 paths: 限定规则作用范围。

表达需求：把话说成「可验收的订单」

上下文 + 动作 + 成功标准 + 边界

在哪做+做什么+怎么算完成+不许动什么

糟糕 vs 优秀：三组真实对照

糟糕的 Prompt	优秀的 Prompt
修复认证的 Bug	在 `lib/auth.ts` 中，`validateToken()` 没有处理过期的 JWT。请在 `exp` 声明上添加检查。现有测试必须通过。
帮我生成一份 PDF	把 `docs/报告.md` 转成 PDF：A4、中文正文用思源宋体、带页码与目录。输出到 `docs/报告.pdf`，完成后报告页数。
优化一下这个页面	在 `components/UserProfile.tsx` 中补充错误状态与加载态，参考 `DashboardCard` 的写法。不要修改现有 Props 接口，改动控制在 80 行内。

十条技巧清单

用路径和行号引用：src/auth.ts:42，不要只说「认证文件」。
用精确动作动词：添加 / 替换 / 删除 / 移动，而不是「优化一下」。
用 @ 把文件主动拉进上下文，省去它到处找。
事前设约束：「不要修改现有测试」「最多 50 行」「保持 Node 22 兼容」。
给示例：贴出想要的前后样式或参考文件。

先问再写：「先解释你的计划，再修改代码」。
指定输出格式：「只输出 unified diff」「返回 3 项编号清单」。
粘贴报错原文：精确的文件名、行号、错误信息。
一个任务一个会话：不相关的工作用 /clear 隔离。
像纠正同事一样纠正它：「你改动了公共 API 签名，请保持不变」。

验收标准怎么写

「完成」必须可被检查

「所有测试通过」——可执行、可复现
「风格与 src/handlers/ 下文件一致」
「npm run build 无错误」
「产物是 output/main.pdf，页数 ≤ 12」
「与设计稿匹配」（主观项，需人工确认）

给 Agent 一个验证自己输出的方法，是最高效用户的共同特征。

长任务利器：Goal 模式

把「下一步做什么」换成「最终要做到什么」

在输入框 / 菜单或 + 菜单选择「目标」。Goal 会反复检查、修改、验证，未达标就继续推进，你不需要每轮说「继续」。

适合：问题定位（偶发失败复现→修复）、工程演进（依赖迁移、多阶段重构）、指标优化（Benchmark 驱动调优）、研究交付。
不适合：一行修改、简单解释、目标无法验收（「优化一下」）、高风险操作。

# Goal 写法模板（直接套用）
实现【最终状态】，并通过【具体测试 / 报告 / 产物】验证。
工作过程中保持【不能退步的条件，例如现有测试继续通过】。
只使用或修改【允许的文件、工具和数据范围】。
每轮尝试后记录【改动、结果和下一项实验】。
如果出现【阻塞条件】，停止继续尝试，并汇报已尝试的路径、现有证据、
阻塞原因以及继续工作所需的输入。

注意额度：Goal 会连续执行多轮，用量可能明显高于一次性 Prompt。开始前设置运行时间、尝试次数或用量上限；连续两轮无进展时及时暂停或编辑目标。

实现需求：探索 → 规划 → 编码 → 验证 → 提交

永远不要跳过前两个阶段

在陌生代码上直接动手，返工率会明显上升。探索阶段的目标是让它理解上下文，而不是产出代码——明确告诉它「不要写代码，只做分析」。

PHASE 1探索读结构、读关键文件、回答问题，禁止改代码

PHASE 2规划Plan Mode 出方案，每步 diff 有限额、有门禁

PHASE 3编码按计划小步实现，每批变更后立即验证

PHASE 4验证跑测试、跑构建、看产物，不信口头「已完成」

PHASE 5提交总结改动、开 PR、必要时回退重来

阶段	可以直接说的话	关键动作与反模式
探索	「给我这个代码库的整体概览」「解释 `src/api/` 的路由架构」「认证是怎么实现的」	加一句「不要写代码，只做分析」。反模式：一上来就让它改文件。
规划	「提出一个包含 3 个步骤的重构计划，每步 diff 不超过 200 行」「分成两阶段，每阶段有验证门禁」	切到 Plan Mode（TUI `Shift+Tab`）先看方案再放行。反模式：方案没看就让它动手。
编码	「按计划先实现第一步：创建 `userService.ts`」「把这一批改动提交」	小批量、可回退；每批之后跑一次测试。反模式：一次让它改 30 个文件。
验证	「运行 `npm test` 确认全部通过」「启动本地服务并在内置浏览器打开这个页面检查」	要求它自己验证：跑测试、跑构建、打开页面。反模式：只看它说「已完成」。
提交	「总结我对认证模块的改动」「创建一个 PR，描述包含改动摘要、测试计划、回滚方案」	先审查变更面板里的 diff 再提交。出问题用回退/检查点，不必从头开始。

放行前的闸门

权限确认

读取工作区外文件、修改或删除文件、执行命令、使用可能产生外部影响的工具时，都会先问你。TUI 用 Alt+M 切换 Ask / Auto / Full access。

建议：新项目保持较保守的授权；对删除、覆盖、上传、发送等动作保留人工确认。

验收主入口

变更面板与 Code Review

按文件逐条看 diff；内置代码审查指令可从正确性、安全性、可维护性审查「全部未提交改动」或「上一轮 Agent 产生的修改」，意见会定位到具体代码行。

审查意见是自动初审，关键改动仍要结合测试结果与人工判断。

心理预期

三次尝试规律

第一次往往理解不到位、第二次约一半可用、第三次才可作为基线起点。这不是失败，而是正常使用过程。

第 1 次

~5%

第 2 次

~50%

第 3 次

可迭代

为什么这样做：来自附件 PDF 的数据

请求 ≤100 行

91% 接受

无边界大请求

34%

结构化 Prompt

可用率 ×2.4

先问再写

误改 −55%

跳过探索直接编码

返工 ×3.1

数据引自附件《Claude Code 系统学习手册》（2026-07，整理自 Anthropic 官方文档与社区最佳实践）。用于说明「流程>灵感」这一方向，具体数值不必当成精确指标。

常见工作流：把「一句话」变成「一份交付物」

点标签切换，每个都含原话模板、验收标准与避坑

LaTeX 论文 / 排版 → 编译出 PDF

高价值可完全自动验证

Agent 能读写 .tex、跑 xelatex、读 .log 里的真实报错并迭代修复，直到 PDF 生成成功——这是最适合交给 Agent 的闭环任务之一，因为「成功」可以被程序判定。

给 Agent 的原话

在这个工作区把 main.tex 编译成 PDF：
1. 先检查是否已安装 xelatex，没有就告诉我安装方案，不要自己乱装
2. 用 xelatex 编译，中文用 ctex 宏包
3. 读 .log 里的报错，逐个修到我这边不再需要你改为止（不要改动 my-content/ 下的正文措辞）
4. 输出到 output/main.pdf，并报告页数与全部改动文件

验收：output/main.pdf 成功生成，编译无 Error，页数在 12 页以内

验收与避坑

PDF 文件真实存在，你自己打开看过一遍
日志里没有 Error；Overfull/Underfull 警告可接受
中文字体走 XeLaTeX + ctex，不用 pdflatex 硬扛
图表引用与目录页码正确

注意

别让它「顺便」重写你的正文，把正文目录设为不可改
环境没装好时让它先报告方案，而不是自行下载安装器
反复编译失败时把 .log 尾部贴给它，比描述现象有效

Markdown / Word → 规范 PDF 文档

办公高频样式可复用

适合报告、方案、简历、说明书。关键是把样式要求写具体（纸张、字体、页边距、页眉页脚、目录），否则每次生成的结果都不一样。

给 Agent 的原话

把 docs/方案.md 转成 PDF，要求：
- A4 纵向，页边距上下 2.5cm / 左右 2cm
- 中文正文用 Noto Serif SC，标题加粗，正文 11pt
- 带页码（页脚居中）和自动生成目录
- 代码块等宽字体，表格加斑马纹
输出到 docs/方案.pdf，完成后告诉我页数和用到的字体。
把生成脚本保存为 build-pdf.sh，方便我下次直接复用。

验收与避坑

PDF 打开后中文无方框/乱码
目录页码与实际页码一致
要求它把转换脚本留下，下次一条命令重建

注意

不要在对话里反复说「再好看一点」——直接给量化参数
源文件是 Word 时，先让它读结构再决定转换路径
大文档先转一章验证样式，再整篇生成

生成 PPT / 改稿 / 出讲解稿

先大纲后成稿

PPT 是典型的「改一处动全身」的产物。最省事的做法是先对齐大纲与视觉规范，再让它一次成型；桌面端可在文件面板预览 PPTX，直观检查。

给 Agent 的原话

第一步：读 项目脚本.md，先只给我 12 页大纲（每页标题 + 3 个要点），
我确认后再生成文件，不要现在就开始做 PPT。
第二步（确认后）：按大纲生成 .pptx，16:9，
- 主色 #2f6f5e，辅色 #c97b3f，白底
- 每页要点不超过 4 条，每条不超过 18 字
- 图表用真实数据，不要编造数字
- 输出 演示稿.pptx，同时给我一份逐页讲解稿 markdown

验收与避坑

用文件面板预览 PPTX，逐页过一遍版式
核对数字是否来自你提供的资料
需要可编辑性 → 要 .pptx；只要分享 → 顺带导 PDF

注意

直接说「做个 30 页 PPT」通常会得到一堆空话
改稿时说清「只改第 5–8 页」，避免全篇重排
视觉风格用色值/参考页描述，不要用形容词

表格处理与数据分析

保护原始数据

清洗、透视、汇总、画图、生成新表。核心原则：原始文件只读，结果另存新文件，让每一步都可回溯。

给 Agent 的原话

读取 data/销售明细.xlsx：
1. 不要修改原文件，所有结果输出到新文件
2. 按「月份 + 地区」做透视汇总，销售额求和、订单数计数
3. 加一列环比增长率，格式化为百分比
4. 给汇总表加数据条条件格式，冻结首行
5. 另存为 data/销售汇总.xlsx，并用 2-3 句话说明你发现的最大异常

验收与避坑

原文件时间戳未变
合计值与你手算的样本抽查一致
结论只基于表内数据，无编造

注意

数据量大时让它先给「字段与口径确认」再做计算
图表比一堆数字更容易验收——要求它同时输出图表

可视化 HTML 页面 / 看板 / 交互原型

即时预览可离线交付

纯文本讲不清的结构、流程、对比、时间线，做成单文件 HTML 最有效。Agent 能写完直接在内置浏览器里打开检查，形成「写 → 看 → 改」的闭环。

给 Agent 的原话

把 _review 目录下的审阅意见整理成一个可视化 HTML 页面：
- 单个 .html 文件，样式与脚本内联，可离线双击打开
- 左侧固定导航，点击跳转到对应章节
- 用表格呈现原文/建议对照，用条形图呈现影响程度
- 配色：底色 #f7f5f0，主色 #2f6f5e，字体用 Noto Sans SC
- 移动端不横向滚动
做完后在右侧内置浏览器打开这个页面，检查布局有没有溢出，并告诉我结论。

验收与避坑

页面上没有「占位假数据」，全部来自真实资料
窄屏（手机宽度）不出现横向滚动条
用内置浏览器亲自看一眼，而不是听描述

注意

别用「高级感」「科技感」这类词，改说具体色值与字体
要求单文件内联，避免交付后图片/字体加载失败

Bug：先复现，再定位，最后才动手改

TDD 友好

最有效的顺序：贴原文报错 → 要求先复现 → 要求给多个方案 → 你选一个 → 它实现 → 跑测试。跳过前两步，就会得到「看起来修好了」。

给 Agent 的原话

运行 npm test 时出现：
TypeError: Cannot read property 'id' of undefined
（完整堆栈见 test-output.log，见工作区）

请按顺序做：
1. 先复现这个失败，把完整的错误上下文贴出来
2. 在 userService.ts 定位根因，说明为什么 id 会是 undefined
3. 给出 3 种修复方案，各写优缺点，先不要改代码
等我选定方案后再实施，实施后运行相关测试确认通过。

验收与避坑

失败先能复现，说明根因不是猜的
修复后相关测试由红转绿
顺手补一条能覆盖该场景的回归测试

注意

警惕「过于自信的错误」——生成看起来对但实际错的代码，必须验证
不要用 @ts-ignore / 注释掉断言来「修好」
测试本身不稳定时，先稳定测试再改业务代码

代码审查与提交 PR

提交前必做

用内置的代码审查指令做「自动初审」，再从正确性、安全性、可维护性角度确认。审查结果会定位到具体代码行，可直接跳到原文件修改。

给 Agent 的原话

审查当前工作区全部未提交的改动，重点关注：
- 正确性与边界条件（空值、并发、错误处理）
- 安全（注入、权限校验、密钥泄漏）
- 是否改动了我没要求的文件或公共 API 签名
- 测试覆盖是否跟上了这次改动

输出：按严重性排序的问题清单，每条附文件:行号与修改建议。
先只给清单，不要直接改。
确认后：总结改动 → 建分支 → 提交 → 创建 PR
（标题 < 70 字符，描述含改动摘要、测试计划、回滚方案）。

验收与避坑

Diff 里没有夹带无关文件
PR 描述说清了「怎么验证」和「怎么回滚」
CI 绿灯 + 人工审批，再合并

注意

CI 里跑 Agent 要从只读权限开始，不自动合并
AI 审查意见只作参考，不是合并依据

把本地网页发布成公网链接

需人工确认对外可见

适合把本地做好的静态站点或单个 .html 交付物发成链接。要点：发布前先构建，产物目录根部必须有 index.html；发布是对外动作，必须你本人确认后再执行。

给 Agent 的原话

把这个可视化页面发布成公开链接：
1. 先确认它是自包含的（样式脚本内联，无本地相对依赖）
2. 发布前把要上传的文件清单和「该页面将公网可见」告诉我，
   等我明确确认后再发布
3. 发布后把链接和节点信息一起给我

注意：不要发布任何含密钥、账号、个人数据的文件。

验收与避坑

先自己在浏览器打开一次产物，确认无破图
清楚这是「更新已有站点」还是「新建站点」——两者结果不同
发布后自己点开链接再验一次

注意

不要把源码目录直接当成构建产物目录发布
不要把 .env、密钥文件混进发布目录

深度研究：要结论，也要来源

防编造

研究类任务的失败方式不是「写得不好」，而是看起来很确定但来源不实。所以一定要在指令里规定：来源、时间范围、不确定时怎么说。

给 Agent 的原话

调研「校园光伏 + 储能」的技术路线与成本区间，输出一份报告：
- 时间范围：近 3 年内的公开资料
- 每个关键数字必须给出可点击来源，并标注访问日期
- 区分「官方文件 / 学术论文 / 媒体报道」，不确定的明确写「未验证」
- 先给我研究大纲和检索计划，确认后再展开
- 输出：docs/调研报告.md + 一页要点摘要

验收与避坑

抽查 2–3 个关键数字，点开来源核对
报告里明确区分事实与推断
对同一个关键结论，最好有两个独立来源

注意

不要接受没有出处的精确数字
先看大纲再展开，避免它朝错误方向写 5000 字

定时任务：把重复劳动交给计划表

日报 / 周报依赖桌面端运行

适合日报周报、定期检查、信息整理。创建时设置四件事：名称、指令、执行 Agent、执行时间与会话模式；结果会回到对应会话展示，并可推送到绑定的 IM 频道。

给 Agent 的原话

创建一个每天早上 9:00 的定时任务：
- 名称：每日项目健康检查
- 指令：检查工作区 git 状态与未提交改动；
  运行测试套件并记录失败项；
  汇总成 5 条以内的简报，标出需要我决策的事项
- 执行 Agent：默认
- 结果推送到我绑定的 IM 频道

创建后先立即手动执行一次，让我看看输出质量。

验收与避坑

先手动触发一次，确认输出格式可读
输出要「可直接看」，不是一堆原始日志

注意

定时任务依赖桌面端运行环境，休眠或应用未运行可能不按时执行
不要让定时任务执行有外部副作用的动作（发布、发送、删除）

上下文管理：高效会话的生命线

窗口里同时装着规则、历史、文件与工具输出

上下文窗口同时包含：系统提示 + 项目规则 + 会话历史 + 读到的文件内容 + 工具调用结果。窗口大不代表应该塞满——越满越迟钝，也越容易出现「上下文偏移」。

使用率与行动指南

0–50%

安全

50–70%

警戒

70–90%

紧迫

90%+

临界

区间	建议操作
0–50%	正常工作
50–70%	选择性加载文件，减少无关内容
70–90%	立即压缩会话历史
90% 以上	清空重开，另起一个新会话

四个核心工具

/context: 查看上下文占用构成与优化建议
/usage: 按组件拆分消耗（消息、工具、技能、系统提示、记忆）
/compact: 压缩会话历史，在逻辑边界处执行（规划后、里程碑后、调完 bug 后）
/clear: 清空会话历史开始新对话，项目记忆保留

桌面端「用量」页面也会按消息、工具、技能、系统提示词、记忆拆分展示上下文窗口占用明细。

五条最佳实践

做法	为什么
一个会话只做一件事	单目标会话的代码被生产环境接受的概率明显更高；多目标会互相污染上下文
把读大量文件的任务交给子代理	子代理有独立上下文，只把摘要带回主会话，主上下文保持干净
优先 `/compact` 而不是 `/clear`	压缩保留讨论脉络；清空会丢掉此前所有决策背景
单次请求范围控制在 100 行以内	小块变更更容易审阅和回退，接受率也更高
每 30–60 分钟让它总结一次	「总结你学到了什么、还剩什么要做」——既是检查点，也是对账

压缩也能「带指令」：例如「压缩时保留：架构决策、API 签名变更；已完成：认证重构；下一步：实现 token 刷新」，这样压缩后关键信息不会丢。（Claude Code 的 /compact 支持这种写法，思路通用。）

进阶扩展：什么时候该上什么

先用起来，再按需求逐步加装

你的重复性需求	用什么
同一套流程重复 3 次以上	封装成 Skill（技能 / 斜杠命令）
需要在特定时点自动执行、强制拦截	Hook（生命周期自动化，Claude Code 的强项；确定性 > 提示词）
需要隔离上下文的大型子任务	Subagent / Agent Team，只把摘要带回主会话
要访问外部系统（数据库、API、浏览器、企业系统）	MCP 服务
想装现成的领域能力（金融、法律、Office、企业信息）	插件市场
希望它记住你的偏好与项目约定	记忆（+ 项目规则文件）
任务路径不确定但终点清晰	Goal 模式
要并行处理互不冲突的改动	Worktree / 多会话并行
格式、代码风格要强制执行	Hook 或 linter，别写在提示词里

可复用

Skills 技能

把重复工作流封装成带说明文档的能力，Agent 可按任务描述自动触发，也可以显式调用。渐进式加载：未使用时几乎不占上下文。

连接外部世界

MCP 服务

本地 stdio（npx/脚本）或远程 http / streamable-http / sse。配置入口在插件管理里的「MCP 服务」，支持表单或 JSON 粘贴，可测试连接状态。

mcode mcp list --human      # 已注册服务
mcode mcp tools <server>    # 该服务暴露的工具
mcode mcp auth status      # 授权是否过期

配置常存于 ~/.minimax/mcp.json。工具多时按需检索，避免把全部工具定义一次性塞进上下文。

开箱即用

插件市场

按领域安装专业能力：金融数据、企业信息、法律检索、知识整理、Office 三件套，也有 WPS 金山文档、企业微信等办公插件。

另有 Red Skill 搜索，可直接检索并复刻常见社媒内容模板。

分工协作

Subagent 与 Agent Team

复杂任务（同时涉及代码、设计、文档、测试；长时间运行；需要分工校验）交给 Agent Team：你只描述目标，拆解、分配、跟踪、汇总由它负责。自定义 Agent 还能固定角色、指令、模型与默认工作目录，拥有独立对话入口。

长期收益

记忆机制

主动识别沟通偏好、工作习惯、项目约定与调试经验，后续按需调用。可在设置里查看/编辑记忆摘要，会话内用 /memory 控制本次会话是否使用与生成记忆。

不适合写入记忆：一次性任务状态、临时日志、敏感密钥、已过期的实现细节。

长任务

Goal · 定时任务 · 远程控制

Goal 让任务围绕验收标准持续推进；定时任务把日报周报自动化并推送 IM；远程控制让你在手机上查看进度、补充指令、处理权限确认。

还有：内置浏览器（预览 HTML 产物、移动端预览模式）、无限画布（素材集中管理与标注）、自定义 Mini App（用自然语言搭个人工作台）、H3 Max 视频生成。

常见失败模式与红线

认识这些症状，比背命令更有用

失败模式	典型表现	对策
上下文偏移	偏离原始目标，开始做不相关的事	清空重开；修剪文件集；拆成更小步骤
编辑蔓延	触碰了不相关的文件	每批限制在 5–10 个文件；先要求它列出「受影响文件」再动手
过于自信的错误	生成看起来正确、实际错误的代码	始终验证；先写测试；应用前审查 diff
合并冲突	代码与远程不同步	先同步最新代码；明确指定要触碰的文件
环境混淆	假设了错误的运行时版本	在规则文件里写明版本要求
不稳定的测试	Flaky test 阻塞进展	先稳定测试；批量编辑前先隔离不确定性

绝对不要做的事

不要在缺乏测试的情况下做高影响范围的变更——先补集成/E2E 测试。
不要追求一步到位的重构——分阶段，每阶段有验收标准。
不要在早期阶段就给写入权限——前几周保持在建议/只读模式。
不要在它不知情的情况下手动改文件——否则它在操作过时版本。
不要把规则文件当配置垃圾场——从精简开始，只加必要的。
绝不发布未经人工审查的 AI 输出。
不要把密钥、PII 或生产凭据贴进对话。

十条黄金法则（精简版）

始终审查 diff，不要盲目接受
在上下文耗尽前压缩，防患于未然
保持具体：做什么、在哪里、怎么验证
复杂或高风险任务从规划模式开始
持续投资规则文件，每次纠错都写进去
给它验证自己输出的方法
把重 I/O 的活推给子代理，保持主上下文干净
预审核安全命令，减少权限摩擦但不牺牲安全
一次一个目标
用 Hook / linter 执行确定规则，不要依赖提示词

四周学习路径

从「跑通」到「形成自己的环境」

第 1 天 · 跑通第一次会话
装好桌面端或 CLI，登录，用一个小而熟悉的项目走一遍「描述 → 审查 → 验证」循环。目标不是产出，而是熟悉权限确认和 diff 审查的手感。
第 1 周 · 建立项目规则，学会管理上下文
为项目写第一版 AGENTS.md / CLAUDE.md；练习「探索 → 规划 → 编码」；开始用 /compact /clear /context 管理会话。
第 2 周 · 减少摩擦，封装重复
配置权限规则，让低风险的测试与 lint 命令不再反复确认；把 2–3 个常用流程封装成 Skill；学会把读大量文件的任务交给子代理。
第 3 周 · 硬规则与外部能力
上 Hook（自动格式化、拦截危险命令）或对应机制；尝试 TDD 工作流；接入 1–2 个 MCP 服务连接你真正在用的外部系统。
第 4 周 · 并行与自动化
用 Worktree / 多会话并行处理互不冲突的任务；把重复的日报、检查类工作做成定时任务；尝试把审查接进 CI，从只读权限开始。

核心理念：最好的用户不是写最聪明提示词的人，而是持续投资环境的人——规则文件、技能、Hook、权限规则。你投入在指导上的每一分钟，都会在之后的每次协作里收回成本。

速查表

贴在显示器边上那种

MiniMax Code CLI 常用命令
`mcode`	启动交互式 TUI
`mcode "任务描述"`	启动时直接提交第一条任务
`mcode exec "..."`	无界面模式，用于 Shell / CI
`mcode init .`	分析目录，生成/更新 `AGENTS.md`
`mcode login` / `--region global`	登录（大陆 / 海外）
`mcode --continue` / `--session`	继续最近会话 / 打开会话管理器
`mcode provider add\|test\|list`	BYOK 供应商管理
`mcode mcp list\|tools\|auth`	MCP 服务检查
`mcode plugin list\|add\|enable`	插件管理

TUI 快捷键
`Enter`	发送；运行中用于 steer 当前响应
`Alt+Enter`	把后续消息加入 Queue
`Shift+Enter`	输入框内换行
`@`	引用工作区文件或目录
`Ctrl+V`	粘贴剪贴板中的图片或视频
`Shift+Tab`	切换 Plan Mode
`Alt+M`	切换 Ask / Auto / Full access 权限模式
`Esc`	关闭面板或中断任务
`/help`	查看当前版本完整命令与快捷键

文件 / 目录	用途
`AGENTS.md`	项目规则与协作边界（放在工作区根部，`mcode init .` 可生成）
`~/.minimax/config.yaml`	默认模型、权限模式、MiniMax 凭证来源等运行时配置
`~/.minimax/mcp.json`	MCP 服务本地配置（也可在产品内图形化管理）
`~/.minimax/`	数据根目录：配置、Session、日志、Plugin、Skill
`MINIMAX_DATA_DIR`	环境变量，切换数据目录
`CLAUDE.md` / `~/.claude/settings.json`	Claude Code 对应：项目规则 / 用户全局设置；项目级还有 `.claude/settings.json`、`.claude/skills/`、`.claude/agents/`、`.claude/rules/`

官方资源与信息来源

核对时间 2026-09-23

MiniMax Code 官方文档

Claude Code 与附件资料

Claude Code 官方文档（安装、CLAUDE.md、权限、Hooks、技能、子代理、MCP、插件）
附件 PDF：《Claude Code 系统学习手册 v1.0》（2026-07，整理自 Anthropic 官方文档与社区最佳实践）——本页中 Claude Code 相关概念、命令、模板与「三次尝试规律」等数据均来自该手册
社区参考：Claude Code Guide（GitHub）、Awesome Claude Plugins、Claude Help Center — Power User Tips

说明：MiniMax Code 部分的功能描述与命令均以官方文档为准并已逐项核对；Claude Code 部分标注为「来自附件 PDF」的内容属于该文档整理口径（其数据截至 2026-07），与当前官方文档可能存在版本差异，涉及具体数值或版本时建议再核对官方页面。