Agent Modes

六种 Agent 模式详解

🧠 Agent 内核 · 🏠 首页 › Agent-Modes

---

📑 本页目录

• 1. 模式总览与切换机制
• 2. 系统提示注入（EnginePrompts.kt）
• 3. Spec 模式的内部流程
• 4. Reflect 模式的三步循环
• 5. Assist 模式与 ask_user_choice
• 6. 预置配置组合（companion）
• 7. 与编排器的关系
• 8. 相关页面

模式栏横向滚动切换，由 AgentConfig.mode 驱动引擎行为。本文是 Agent 引擎 的深入篇： 每种模式的系统提示措辞、内部流程、事件与 UI 表现、以及切换到底改了什么。

1. 模式总览与切换机制

模式	枚举	行为	适用
Build	AgentMode.BUILD（默认）	边想边做，ReAct 实时循环	简单任务、追求快
Plan	PLAN	先产出执行计划 → 用户确认 → 逐步执行 → 总结	复杂多步任务
Spec	SPEC	先产出需求规格 → 确认 → 按交付物逐项执行	"做什么、做成什么样才算完成"
Reflect	REFLECTION	生成 → 评审 → 修正（默认 1 轮）	代码生成 / 内容创作
Assist	HUMAN_ASSIST	遇多选强制弹选项菜单，禁止猜测	高风险 / 多目标歧义
Custom	CUSTOM	附加自定义指令（持久化）	个性化

切换是"配置热更新"，不是重启引擎：

AgentChatViewModel.setMode(mode)
  → _uiState.update { copy(mode = mode) }
  → ApexAgentEngine.patchConfig { cfg.copy(mode = …, customInstruction = …) }

patchConfig 只改 mode / customInstruction，保留其余全部引擎配置（旧的 updateConfig 会重置，已弃用）。 因此切换模式不会重建引擎、不会清空对话历史，只影响后续请求注入的 system prompt。

Custom 指令持久化键：KEY_CUSTOM_INSTRUCTION = "custom_mode_instruction"（SharedPreferences）。

2. 系统提示注入（EnginePrompts.kt）

when (config.mode) 逐模式追加 ## Mode: XXX 段落，原文措辞：

模式	关键原文（节选）
PLAN	You are in planning mode... Do NOT execute any tools yet. Only output the plan as JSON.
SPEC	(goal, requirements, constraints, acceptance criteria, deliverables)... Only output the spec as JSON.
REFLECTION	Quality matters more than speed: after drafting an answer, the engine will ask you to review it critically, then revise it into the final output.
HUMAN_ASSIST	you MUST call ask_user_choice BEFORE proceeding... NEVER guess when the choice materially changes the result. + Keep questions short and provide 2-6 clear options.
CUSTOM	Custom instructions take priority over generic behavior guidance.（仅当 customInstruction 非空时追加 ## Custom Instructions）
BUILD	Act directly. Use tools when needed. + Be efficient: prefer fewer steps, verify results between calls.

3. Spec 模式的内部流程

flowchart TD
    A["流式生成规格 JSON（作为思考流呈现）"] --> B["解析为 ExecutionSpec<br/>goal / requirements / constraints<br/>acceptance criteria / deliverables / risks"]
    B --> C["发射 SpecGenerated → SpecAwaitingConfirmation"]
    C --> D{"用户确认？"}
    D -->|否/重规划| A
    D -->|是| E["SpecConfirmed：按交付物逐项执行"]
    E --> F["每项进入 Build 子循环"]
    F --> G["生成总结 ResponseComplete"]

Loading

回退链：无交付物 → 退回需求清单 → 再退回目标。 UI 侧对应 SpecMessage 规格卡片 + 确认对话框。

4. Reflect 模式的三步循环

触发条件：最终纯文本轮次（该轮无工具调用）才触发。

① 生成   草稿按 ResponseChunk 流式呈现（UI 显示为一条 Agent 回复）
② 评审   LLM 严格审视：事实错误 / 逻辑缺口 / 歧义 / 边界情况
         完成后整段发射 ReflectionReview → UI 显示 REVIEW 卡片
③ 修正   按评审意见重写，ResponseChunk 流式，ResponseComplete 为最终回复

• 轮数由 AgentConfig.reflectionRounds（默认 1，可配多轮）控制；
• 草稿与修正稿都写入对话历史，保持上下文连贯。

5. Assist 模式与 ask_user_choice

复用了 AgentQuestion / QuestionCard 的选项菜单 UI（无新组件），新增参数 multi_select：

{
  "question": "接下来先做哪一步？",
  "options": ["安装应用", "清理缓存", "导出日志"],
  "multi_select": true,
  "allow_custom": true
}

配置	UI	返回字段
multi_select = true	Checkbox 多选（"可多选"徽章）	AgentAnswer.selectedOptionIds，工具输出 User selected: A, B
multi_select = false	单选（兼容旧字段）	selectedOptionId

Note

自定义输入与多选互斥：允许自由输入时就是单选语义。

6. 预置配置组合（companion）

预设	组合
QUICK	BUILD + ThinkingLevel.NONE + maxIterations = 10
STANDARD	BUILD + ThinkingLevel.STANDARD
CAREFUL	PLAN + ThinkingLevel.DEEP
（默认）	BUILD + STANDARD + maxIterations = 25

7. 与编排器的关系

• 模式是 AgentConfig 字段，由 ApexAgentEngine 在两处消费：构建 system prompt（EnginePrompts）与选择执行分支（executeSpecMode / Reflection 循环）；
• Plan / Spec 产生步骤粒度（TaskStepModel），Build 无步骤粒度；
• 复杂长任务仍可上 编排路径，两者正交。

8. 相关页面

• Agent 引擎 · 任务运行时与持久化 · 上下文压缩

---

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

_{Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room}