Agent 原理
这篇文档面向对Agent内部机制好奇的进阶用户，具有一定的理解门槛，请按需阅读。
Nephele 中的 Agent 不同于传统的聊天机器人，能够真正把输出内容转化成指令，自己完成思考，行动，观察结果，调整策略直到达成目标的过程。
这套机制的核心是 ReAct 循环（Reasoning + Acting）：先思考，再行动，观察结果，再思考下一步。除此之外再加一套规则引擎快速反应系统，触发时可以跳过LLM推理直接执行指令。
ReAct 循环
进入完整 Agent 后，Agent 跑一个 ReAct 循环，一次完整交互如下：
- 构建请求 —— 把 system prompt（含工具说明、用户记忆、当前时间）+ 对话历史 + 你的新消息，作为 SSE 流式请求发到云端
- 流式接收 —— 模型返回思维链（thinking）和正文（content），Agent 实时转发给 UI
- 工具调用 —— 如果模型决定调用工具，Agent 执行工具，把结果格式化后追加到对话历史；支持一次收集多个工具调用再批量执行
- 循环判断 —— 任务没完成就回到第 1 步，继续下一轮
迭代上限
硬上限是 50 次工具调用。达到上限后 Agent 会停止并告知你"任务可能未完全完成"。它是为了防止错误导致的无限循环或者超出预期的昂贵长运行而设立的。
停止机制
你可以随时点击停止按钮，Agent 会在以下位置检查取消信号：
- 每轮迭代开始前
- SSE 流接收过程中
- 串行工具执行间隙
停止后，已执行的工具结果不会被撤销，但后续工具调用会取消。
两条执行路径
| 规则引擎 | ReAct 循环 | |
|---|---|---|
| 延迟 | 毫秒级 | 秒级（取决于模型和网络） |
| 使用 LLM | 否 | 是 |
| 适合场景 | 明确的开/关/查指令 | 分析、创作、多步任务 |
| 工具调用次数 | 1 次 | 最多 50 次 |
分流与计费
主输入框由你手动选择模型档：默认 Axioma Zephyr（快档，适合日常任务）或 Axioma Tempest（全力档，适合最困难最复杂的任务）。
| 通道 | 处理者 | 用 LLM | 消耗 | 适合 |
|---|---|---|---|---|
| 规则引擎 | 本地，零延迟 | 否 | 零 | 明确的开/关/查命令 |
| Axioma Zephyr | 完整 Agent · 快档 | 是 | 按云晶计费（半价） | 日常分析、创作、多步任务 |
| Axioma Tempest | 完整 Agent · 全力档 | 是 | 按云晶计费（全价） | 高难度推理、复盘、画风分析 |
工具系统
意图感知的工具加载
Agent 工具数量在持续变化，但不会一次性把所有工具的详细参数都塞给模型，而是按需加载：初始只加载核心常用工具，其余工具按类别只列名字。模型需要时动态加载具体参数说明，大幅节省每轮的上下文开销。
技能（Skill）注入
工具之上还有一层技能——教 Agent 在特定任务上怎么做更好的工作流文档。内置技能（找参考、鉴赏、溯源等）会在相关任务里自动加载，Agent 也能从技能目录里自己按需调取；你的自定义的工作流则通过输入框 / 点名调用。
并行执行
如果一轮里模型要求调用多个工具，Agent 会根据每个工具自身的属性判断哪些可以并行——可并行的工具同时执行，其余串行。
run_python 永远不会被并行，且执行前需要你在弹窗中确认或编辑代码内容。
记忆系统
Agent 的记忆是卡片化的：每条记忆是一个独立的 Markdown 文件，存放在本地 ~/.nephele_workshop/memory/ 目录下，附带简短的 frontmatter（标题、一句话摘要、类型）。
记忆的五种类型
Agent 通过 memory_write 工具把对话中值得长期保留的信息存成一条记忆，每条都归到下面五类之一：
- user —— 你是谁（创作风格、个人习惯）
- workflow —— 你怎么工作（常用流程、偏好设置）
- project —— 你在做什么（当前项目背景）
- reference —— 你的账号、常用路径等参照信息
- correction —— 对 Agent 行为的校正偏好
只有跨会话值得长期保留的内容才写入；本次会话的临时偏好、工具调用细节这类中间状态不会被存。
索引与按需读取
Agent 不会把所有记忆全文塞进上下文，而是只注入一份自动维护的索引，每条记忆只占一行（标题 + 一句话摘要），按类型分组、组内按最近更新排序。Agent 看索引就知道有哪些记忆可用。
子 Agent 委派
遇到复杂任务时，Agent 可以调用 delegate_tasks 把任务拆成多个子任务。每个子任务由一个子 Agent 处理。
限制：
- 最多 6 个子任务
- 单个超时 120 秒
- 真正并行执行（ThreadPoolExecutor，最多 4 个并发）
- 仅完整 Agent 循环可用
子 Agent 有一些额外约束：
- 不能继续委派其他子 Agent（防止无限递归）
- 不能执行需要用户确认的操作（如
run_python）
内部还做了反模式检测：如果你要求找参考图，主 Agent 不应该用 delegate_tasks 拆成多个找图子任务，因为 find_references 内部已经并行搜索多个平台了。
安全与真实性约束
run_python 确认
执行 Python 代码前会弹出确认窗口，展示完整代码和描述。你可以取消、直接确认、或编辑后再确认。
图片压缩
Agent 接收图片附件时，会自动压缩到最长边 1536px、JPEG 质量 85%，减少 base64 传输体积和 token 消耗。GIF 等动画格式保持原样。
事件流架构
主要事件类型：
| 事件 | 说明 |
|---|---|
StreamChunk | 正文文本片段 |
ThinkingChunk | 思维链片段 |
ToolStart | 工具开始执行 |
ToolFinish | 工具执行完成（含成功/失败状态和结果） |
NavigateView | 需要切换界面视图 |
RateLimitUpdate | 疲劳值配额更新 |
StaminaCost | 单次请求 stamina 消耗 |
CreditsUpdate | 云晶余额更新 |
LoopError | 循环出错（网络/认证/服务不可用） |
LoopDone | 一轮对话完成 |
操作日志与撤销
每轮 Agent 对话会被记录到 OperationJournal，生成一个唯一 round ID。完成时会在消息末尾注入 <!--UNDO:round_id--> 标记。这意味着对本地的部分操作支持撤销。