Agent Engine

Agent 引擎

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

---

📑 本页目录

• 1. 两条执行路径
• 2. 六种工作模式（AgentMode）
• 3. 双层思考深度（正交）
• 4. 事件流契约（AgentEvent）
• 5. ReAct 循环的边界与安全
• 6. 配置清单（AgentConfig）
• 7. 扩展指南
• 8. 相关页面

core:agent-engine 是整个项目的心脏：六模式流式 ReAct 循环 + 编排路径， 输出统一的 AgentEvent 事件流给 UI 渲染。本文讲模式、思考深度、事件契约、 循环边界与"我该怎么扩展"。

1. 两条执行路径

路径	实现	适用	主要特性
直连	ApexAgentEngine	绝大多数对话式任务	流式文本 / 思维链 / 工具卡片事件、P7 压缩、多模附件
编排	DefaultTaskOrchestrator	多步长任务、需要计划/确认/恢复	任务状态机、批量执行、失败分类 + 恢复规划、循环检测、用户交互门

两者共享 ToolRegistry / LlmClient / HybridCompressor，所以事件语义一致： UI 不需要知道消息来自哪条路径。编排器详见 任务编排器。

2. 六种工作模式（AgentMode）

模式	行为	什么时候用
Build	边想边做，实时执行	简单任务、追求快
Plan	先产出完整计划，用户确认后逐步执行	复杂多步操作、涉及删除/安装
Spec	先产出需求规格（目标 / 需求 / 约束 / 验收标准 / 交付物），确认后逐项执行	"做什么、做成什么样才算完成"
Reflect	生成 → 评审 → 修正 的自我循环	代码生成、内容创作，追求质量
Assist	遇到多选（方案/目标/偏好）强制弹菜单人工决策	不希望它擅自猜测
Custom	附加用户自定义指令（输出格式 / 语言 / 行为约束），持久化保存	个性化

Tip

想"先看看它打算干什么"用 Plan；想"先对齐什么叫完成"用 Spec； 想让它闭嘴别猜用 Assist；想要质量用 Reflect（可配 1~N 轮评审修正）。

枚举真名：AgentMode.BUILD / PLAN / SPEC / REFLECTION / HUMAN_ASSIST / CUSTOM。

3. 双层思考深度（正交）

层	控制点	档位	作用
提示词思考	ThinkingLevel	NONE(0) / LIGHT(1) / STANDARD(2) / DEEP(3) / MAXIMUM(4)	系统提示注入推理指令强度（0=不生成推理过程，4=完整推理链 + 自我反思 + 多轮验证）
原生思考	ReasoningEffort	NONE / LOW / MEDIUM / HIGH / MAX	直接写请求体 reasoning_effort（o 系列 / R1 / Qwen3-thinking / GLM-Z1），MAX 同时抬高 max_completion_tokens 给思维链留空间

两者可以任意组合：

• NONE + HIGH：纯模型原生思考（推理模型推荐）；
• DEEP + NONE：纯提示引导（非推理模型推荐）；
• MAXIMUM + MAX：最强也最贵，谨慎使用。

原生思维链通过流式增量字段 delta.reasoning_content / delta.reasoning 被解析到 LlmStreamChunk.reasoningContent，再透传为 AgentEvent.ThinkingChunk； UI 中正文与思维链严格分流渲染（双引擎同语义）。

4. 事件流契约（AgentEvent）

UI 只消费事件，不关心内部状态机。主要事件：

sealed interface AgentEvent（core/agent-engine/.../engine/AgentEvent.kt）的真实成员：

思考阶段

事件	触发时机	UI 表现
ThinkingStart(iteration, thinkingLevel)	一轮推理开始	展开思维链区
ThinkingChunk(text)	reasoning_content / 提示词思考的增量	打字机式思维链
ThinkingComplete(fullThought)	一段思考结束	折叠思维链
IterationStart(iteration)	进入第 N 轮 ReAct	迭代计数/调试用

规划 / 规格

事件	触发时机	UI 表现
PlanGenerated(plan) / PlanAwaitingConfirmation(plan) / PlanConfirmed(plan)	Plan 模式产出与确认	计划确认卡（批准 / 重规划 / 取消）
SpecGenerated(spec) / SpecAwaitingConfirmation(spec) / SpecConfirmed(spec)	Spec 模式产出与确认	规格确认卡
StepStart	计划中某一步开始	步骤高亮
ReflectionReview	Reflect 模式的评审意见	评审块

工具与响应

事件	触发时机	UI 表现
ToolCallStart / ToolOutputChunk / ToolProgress / ToolCallComplete	工具生命周期	工具卡片 + 实时输出 + 进度条
ResponseChunk / ResponseComplete	正文流式增量 / 结束	流式气泡
UserInputRequired	ask_user / Assist 多选	选项菜单，挂起等待
ContextCompressed(before, after, strategy, …)	P7 压缩触发	系统消息说明压缩内容
Error / Complete / Aborted	失败 / 正常完成 / 被取消	收尾状态

编排路径另发射 TaskLifecycleEvent（SharedFlow），承载任务状态迁移与进度，见 任务编排器。

Note

工具内部的流式（如 shell 实时输出）通过 StreamingTool / SafeAgentTool 包装器透传。 core:tool-registry 有专门的流式透传回归测试：包装器不许吞掉流式。

5. ReAct 循环的边界与安全

机制	组件	作用
迭代上限	AgentConfig.maxIterations	防止模型陷入无限工具循环
挂起工具补全	DanglingToolCallRepair	对话被打断/重连导致 tool_call 无结果时，补齐假结果避免 OpenAI 协议报错
命令权限门	CommandPermissionGate	高危 shell 命令触发确认（配合 UI 的 RiskAwareToolGate）
用户交互门	UserInteractionGate（编排侧）+ ask_user（引擎侧）	需要人工决策时挂起而非猜测
会话记忆	ConversationMemory	短期上下文（≠ cs-mem 长期记忆，两者互补）
环境感知	PrivilegeInfoProvider（core 侧纯接口）	把当前权限级别写进系统提示：模型知道自己能干什么、缺什么（例如建议装 Shizuku）

6. 配置清单（AgentConfig）

配置	默认值	含义
mode	BUILD	六模式之一，UI 可切换
thinkingLevel	STANDARD	提示词思考强度，见 §3
maxIterations	25	ReAct 迭代上限，防死循环
maxContextTokens	128000	上下文预算，超出触发压缩
compressionThreshold	0.8	达到 ×80% 水位即压缩
preserveRecentTurns	5	最近 N 轮永不压缩
maxToolOutputLength	2000	工具输出单次截断上限
streaming / temperature	true / 0.7	流式开关与采样温度
modelOverride	null	覆盖当前选择的模型
reflectionRounds	1	Reflect 模式"评审→修正"轮数
customInstruction	null	Custom 模式附加指令（拼进 system prompt 的 ## Custom Instructions）

Note

上表前七项是 AgentConfig 的真实字段（默认值为准），与 LlmConfig.contextWindow 属于两套口径：写参考预算时务必两者对齐，否则会出现"引擎没压、模型却报上下文超长" 或反之的错配。详见 上下文压缩。

7. 扩展指南

flowchart LR
    A["要加一种模式"] --> B["AgentMode 枚举 + EnginePrompts 分支"]
    A --> C["UI 模式切换器 + ViewModel 参数"]
    A --> D["补一个减少/退出该模式的回归测试"]
    E["要加一种 'UI 事件'"] --> F["AgentEvent 新 sealed 分支"]
    E --> G["两条路径都要发射（保证同语义）"]
    E --> H["ViewModel + compose 渲染"])

Loading

Caution

ApexAgentEngine / DefaultTaskOrchestrator 都是大文件。 质量门禁限制 main 源文件 ≤1200 行（scripts/check_file_size.sh）， 加功能前先看剩余预算，超了先抽子类/拆包。

8. 相关页面

• 任务编排器 —— 复杂任务的那条路
• 上下文压缩 —— 双引擎共享的水位防线
• 工具系统 —— 引擎的手
• LLM 适配层 —— 引擎的嘴
• cs-mem 认知记忆 —— 引擎的记忆

---

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

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