智能体行为

本页描述 Flue 智能体开箱即用的行为：模型获得的工具、运行环境、传入消息的处理方式、上下文窗口的内容，以及运行时强制执行的限制。这是一份运行时行为的地图，而非编写 API——定义这些行为的页面在各小节中均有链接。Flue 的内部智能体循环基于 pi 的智能体核心构建；以下内容均为 Flue 自身的契约，如需了解 pi 编程智能体的对应内容，请参阅 pi 的使用文档。

内置工具

附加了沙盒的智能体会获得六个操作沙盒的工具。这些是模型调用的工具——应用代码和沙盒适配器使用的是这些工具所构建的底层 Sandbox 接口，它刻意设计为更低层级（整体文件操作、无截断）。

read

读取文件。参数：path，可选 offset（起始行号，从 1 开始），可选 limit（最大行数）。

• 输出截断至 2000 行或 50 KB（以先到者为准），且不会在行中间截断。截断的输出末尾会附加一个标记，标明显示范围和继续读取的偏移量（Use offset=N to continue.），因此模型可以分页读取任意长度的文件。
• offset 超过文件末尾会报错，并显示文件的实际行数。
• 单行超过字节限制时，只显示前 50 KB，并提示剩余部分无法通过 offset/limit 访问。

write

整体写入文件。参数：path、content。创建文件及缺失的父目录；文件已存在时静默覆盖。

edit

精确文本替换。参数：path、oldText、newText，可选 replaceAll。

• oldText 必须精确匹配文件中的一个区域：零个匹配会报错，提示模型检查空白和缩进；多个匹配会报错，要求提供更多上下文——除非设置了 replaceAll，它会替换所有匹配项并报告数量。
• 读取 → 替换 → 写入的事务对每个文件是原子性的：同一批次中的工具调用并行执行，来自 write 和 edit 的同文件变更通过逐路径锁序列化，因此真正的冲突会表现为”找不到”错误，而非静默丢失编辑。同时修改同一文件的 bash 命令不会被同步。

bash

在沙盒中执行 shell 命令。参数：command，可选 timeout（秒）。

• 返回合并的 stdout/stderr，截断至最后 2000 行或 50 KB（尾部是错误和最终结果所在的位置）。非零退出码会附加退出码。
• 超过 timeout 的命令会返回可恢复的 exit-124 结果，而不是使操作失败，以便模型可以做出反应。

grep

搜索文件内容。参数：pattern（正则表达式），可选 path、include（glob 过滤器）、literal。

• 当沙盒中有 rg 时使用它（仅探测一次），否则回退到 POSIX grep -E。
• 返回匹配行及文件路径和行号，上限为 100 个匹配和每行 500 个字符；达到上限时会报告并建议缩小搜索范围。

glob

按名称查找文件。参数：pattern，可选 path。使用 shell find -name 语义——模式匹配文件名而非路径——最多返回 1000 个路径。

框架工具

与沙盒无关，框架会在能力存在时添加自己的工具：task 用于子智能体委派（始终存在；在声明智能体之前无效），activate_skill 用于智能体拥有技能时，read_skill_resource 用于导入的技能包含资源文件时。这些名称是保留的——自定义工具不能使用它们。

沙盒适配器可以用自己的工具集替换这六个沙盒工具——参见沙盒提供的工具——因此在假定存在普通文件或命令工具之前，请查看集成的文档。

环境默认值

智能体没有沙盒，除非你用 useSandbox() 附加一个，且最多一个。没有沙盒时：六个文件和 shell 工具不在工具集中，没有工作区上下文进入系统提示词，工作区技能不会被发现，harness.sandbox 会抛出异常。其他一切——自定义工具、导入的技能、子智能体、状态——无论有无沙盒都同样工作。

附加沙盒会同时定义多个行为（工具、工作区发现、技能、子智能体继承的内容）——沙盒指南详细介绍了这些。沙盒的存在会在每个轮次边界重新读取，因此条件性的 useSandbox() 可以在对话中途附加或移除环境；切换会作为 environment 信号告知模型。

消息处理

每个输入——HTTP 提示、dispatch()、频道投递、定时触发——都作为提交被接纳，在任何模型工作开始之前被持久记录。同一对话的提交形成一个按接纳顺序处理的队列，智能体不会在繁忙对话的轮次后面空闲等待：

• 一次只运行一个提交。
• 智能体繁忙时到达的消息会在下一个轮次边界加入实时响应（如果可以），否则作为自己的提交等待轮次。没有任何消息会被丢弃：错过实时响应的投递之后会独立运行。
• 每个被接纳的提交都会到达一个精确的持久终端结果——completed、failed 或 aborted——无论中间发生了多少次崩溃。

重试、恢复和中止机制属于持久性指南的范畴；线路契约（202 接纳响应、流式传输）在路由中。

上下文组成

初始化时，运行时根据发现的内容组成系统提示词：智能体函数返回的指令，以及——当附加了沙盒时——工作目录路径、目录列表、AGENTS.md 的内容（如果存在），加上发现的技能、子智能体和工具名册。

系统提示词随后被冻结：它持续描述初始化时发现的工作区和目录，直到下一次压缩根据当前环境重新基准化。中途的变更——工具的挂载或卸载、技能的切换、环境的交换——作为追加式的信号告知模型，而非重写提示词，这保持了对话早期轮次与它们实际运行时提示词的一致性（并保持系统提示词在提供者提示缓存中的热度，尽管工具变更会通过原生工具数组使缓存失效）。

上下文管理

当对话接近模型的上下文窗口时，运行时会进行压缩：较旧的消息折叠为摘要，较新的消息逐字保留。阈值压缩在使用的 token 超过窗口减去模型感知的预留量（上限为 20,000 个 token）时触发；最近的 8,000 个 token 默认逐字保留。这两个参数、摘要模型和禁用选项都在 CompactionConfig 中；溢出恢复和显式的 harness.compact() 即使在禁用阈值压缩时也会进行压缩。

限制

运行时强制执行的数值，从以上各节和委派机制中收集：

限制	值
read 输出	2000 行 / 50 KB，头部截断并附带继续标记
bash 输出	2000 行 / 50 KB，尾部截断
grep 结果	100 个匹配，每行 500 个字符
glob 结果	1000 个路径
委派深度	4——超过此深度的 task 链（包括 harness 调用）会以 delegation_depth_exceeded 失败
压缩预留	模型感知，上限 20,000 个 token
压缩后逐字保留	默认 8,000 个 token

工具集大小没有框架上限，但每个挂载的工具都会消耗上下文——参见条件工具以保持精简。