Agent 如何执行任务

当你把 任务 指派给 Agent 后，HiFox 会把任务上下文、Agent 配置和电脑环境组合起来，派发给 Agent 执行。

这个过程的关键点是：任务仍然是协作中心，Agent 只是执行者。需求、讨论、运行记录、阻塞和结果都会回到同一个任务里。

从任务指派开始

最常见的触发方式，是把任务处理人设置为某个 Agent 或小队。

如果任务已经在 Todo、In Progress 或其他可执行状态中，指派给 Agent 后会自动开始执行。

如果任务还在 Backlog，Agent 会保持等待，不会立刻开始。你可以先在 Backlog 中整理需求、补充上下文，等准备开始时再把任务移动到 Todo 或其他可执行状态。

在任务详情中把任务指派给 Agent

HiFox 会准备哪些上下文？

任务开始执行时，HiFox 会把相关上下文交给 Agent，包括：

  • 任务标题和描述；
  • 当前任务状态、任务类型、优先级和处理人；
  • 最近的评论和补充信息；
  • 任务所属空间、专项和标签；
  • Agent 的指令；
  • Agent 绑定的技能；
  • 空间或 Agent 绑定的 Git 仓库；
  • Agent 运行时需要的环境变量、密钥和启动参数。

这些上下文会帮助 Agent 理解：要做什么、为什么做、在哪里做、有哪些约束，以及完成后应该如何汇报。

派发到电脑

Agent 真正执行任务时，需要一台电脑。

电脑可以是本地电脑，也可以是云端或团队共享电脑。电脑上的本地服务会与 HiFox 保持连接，接收被指派的任务。

执行流程大致是：

  1. 任务被指派给 Agent；
  2. HiFox 判断任务是否处于可执行状态；
  3. HiFox 找到 Agent 可用的电脑；
  4. 电脑上的本地服务接收任务；
  5. 本地服务准备工作目录和代码库；
  6. 本地服务启动对应的 AI 编程工具；
  7. Agent 执行任务，并把进展和结果写回 HiFox。

如果电脑离线、不可用或并发已满，任务会排队等待。

工作目录和代码库

Agent 执行代码任务时，需要进入一个工作目录。这是 Agent 的运行设置，可选 创建临时目录 或 指定已有目录。保存 Git 目录时可以选择 Worktree 隔离运行（并行） 或 直接在该目录运行（串行）。隔离运行只支持一个目录；直接运行可以选择后再添加路径。两种模式的区别、指定目录的例外规则，以及如何选择，见 Agent 工作目录。

默认建议选择 创建临时目录，或指定目录后的隔离运行。这样每个任务都有自己的 worktree，不同任务可以在同一个仓库的不同工作区里并行修改、运行测试和产出结果，不容易互相覆盖文件或污染工作区。

worktree 的作用是隔离任务改动。比如一个 Agent 在修登录问题，另一个 Agent 在补测试，它们可以分别在自己的 worktree 中工作；即使同时修改代码，也不会直接写到同一个目录里。任务运行结果提交到 <产品>-agent/<Agent 名称>/<任务编号> 分支，例如 hifox-agent/thor/HF-3341；对话产生的改动则以会话 ID 结尾。

任务完成后，你可以 review 这个任务对应 worktree 里的改动，再决定保留、合并或丢弃。这样 Agent 可以安全并行推进多个任务，而不是所有任务都挤在同一个脏工作区里。

如果指定已有目录后选择直接运行，任务会直接修改这个目录，不会为每个任务创建独立 worktree。同一目录一次只能跑一个任务，目录被占用时后来的任务会排队。因此更适合你明确需要复用已有目录、依赖缓存或特殊本地环境的情况。不是 Git 目录时，只能直接运行。完整规则见 Agent 工作目录。

代码库来源取决于 Agent 和空间配置：

  • 如果 Agent 绑定了 Git 仓库，优先使用 Agent 的仓库配置；
  • 如果 Agent 没有绑定仓库，通常使用任务所在空间设置的 Git 仓库；
  • 如果两边都没有配置仓库，Agent 可能能看到任务，但无法进入代码目录完成代码工作。

执行过程中会看到哪些状态？

任务详情里会显示 Agent 的执行状态。常见状态包括：

  • 排队中：任务已经进入队列，等待电脑、并发或目录可用；
  • 启动中：HiFox 正在把任务派发到电脑并准备运行；
  • 处理中：Agent 正在执行任务；
  • 已完成：Agent 已完成本次运行，并写回结果；
  • 失败：运行中发生错误；
  • 已取消：本次运行被停止。

这些状态帮助你判断任务是在正常等待、正在执行，还是需要人工介入。

准备环境时，任务对话里会显示克隆仓库、创建 worktree、检出代码等进度，不必再到电脑终端里确认。

「排队中」不只会出现在对话记录里，也会在任务列表、看板、收件箱和任务详情中显示。执行开始后，Agent 工作状态会切换为「工作中」，对话记录里这条对话的状态也会同步更新。执行完成、失败或取消后，会按对应的运行结果更新。这里的 Agent 工作状态用于描述执行过程，和任务本身的生命周期状态不同。

为什么显示「排队中」？

对话或任务里显示「排队中」，说明这次运行已经创建，但还没有电脑开始执行它。下方会写明它在等什么：

  • Agent 并发已满：Agent 同时处理的任务或对话数量已达到它的「最大并发数」。它手上的某一项完成后，排队的这一项会自动开始。
  • 电脑并发已满：这台电脑同时执行的数量已达到上限。电脑上任一运行结束后会自动开始。
  • Agent 正在这个任务里工作：一个对话一次只执行一项。每个对话用自己的工作目录，所以同一个 Agent 在同一个任务里的不同对话可以同时执行。不属于任何对话的执行，以及开启了“同一电脑上的小队成员共用任务目录”的小队任务，仍要等这个 Agent 在该任务里的其他执行完成。挡住它的执行完成后，这一项会自动开始。
  • 小队成员共用工作目录，需要依次执行：小队开启了“同一电脑上的小队成员共用任务目录”后，同一台电脑上、同一个任务里的小队成员会轮流执行，避免同时修改同一份代码。当前成员完成后，下一位会自动开始。
  • 等待电脑领取：没有上面这些限制时，运行会在几秒内被电脑领取。如果长时间停在这里，检查电脑是否在线、HiFox 客户端是否在运行。

排队中的运行不需要手动重试。挡住它的运行一结束，它会自动开始。如果不想再等，可以停止这次运行。

Agent 会把什么写回任务？

Agent 执行过程中或结束后，通常会把这些内容写回任务：

  • 当前进展；
  • 遇到的阻塞；
  • 需要人类确认的问题；
  • 修改了哪些内容；
  • 运行了哪些检查；
  • 成功、失败或取消的结果；
  • 建议的下一步。

如果 Agent 完成了一轮工作但需要你确认结果，对应的任务对话可能会进入等人审阅。你可以在任务里 review 结果，或在该对话中继续回复。

如果 Agent 缺少信息、权限或需要你做决定，对应的任务对话可能会进入等人回复。请在该对话中回复，或在评论里再次 @ 这个 Agent。

收件箱提醒

Agent 执行任务时，部分需要你处理的事项会进入收件箱。

常见情况包括：

  • Agent 被阻塞：Agent 遇到权限、环境、依赖或信息缺失，无法继续；
  • 任务失败：Agent 的运行失败，需要你查看原因后决定重试、补充信息或改派给成员；
  • Agent 已完成：Agent 完成任务后，你可能需要验收结果或继续推进下一步。

「等你回复」「等你审阅」这类任务对话中的交接不再进入收件箱：它们显示在主侧栏的「对话」模块里，并通过对话发起人的桌面横幅和飞书 / Slack 提醒触达（详见与 Agent 对话）。

收件箱和「对话」模块把需要你注意的事情集中起来。你不需要一直盯着每个 Agent 的运行过程；当 Agent 需要你处理、判断或追踪时，从对应入口进入任务详情，在同一个任务上下文里回复、review 或继续安排工作。

如果修改 Runtime 的执行程序后，界面显示正在重启并复核，这是本地服务复核配置时的中间状态。不要把它当作最终失败，也不要在此期间重复提交互相冲突的恢复操作。等待状态变为成功、明确失败或超时；只有明确失败、超时或复核失败时，才按错误处理。成功后刷新电脑、Machine 和 Runtime 信息，再继续执行或重试任务。

查看对话记录和运行详情

任务详情中可以查看 Agent 的对话记录。

对话记录适合用来了解：

  • Agent 是什么时候开始的；
  • 任务为什么排队或等待；
  • Agent 运行了多久；
  • 本次运行是首次运行、评论触发、重试还是自动化触发；
  • 执行过程中有哪些输出；
  • 失败时错误原因是什么。

每次运行还会显示触发者——是哪位真人让这次运行跑起来的。由其他 Agent 转交或 @ 触发的运行，会一级级追溯到最初发起的真人；从飞书、Slack 等外部渠道触发的运行显示对应的外部账号；确实无法归属到人时，会如实显示「系统」。

如果需要更细的过程，可以打开执行转录。转录会展示 Agent 执行过程中的事件和工具调用，帮助你判断它做了什么、卡在哪里、为什么失败。

从运行记录打开运行详情抽屉，可以在保留原任务页面上下文的同时查看本次结果。结果详情支持使用抽屉内的全宽区域，长输出可以滚动查看；具体按钮和布局以当前界面为准。

Agent 详情的运行队列里，点击一行即可打开该次运行的对话详情，不必先回到任务页再找记录。这和任务详情中的运行详情抽屉是同一类查看方式。如果来源是自动化，来源名称是可打开的链接。

停止和取消

如果 Agent 正在运行，但你不希望它继续，可以停止当前运行。

停止会中断当前 Agent 运行。已经完成的部分会保留，但这次运行不会继续。运行可能需要几秒钟才能完全停止。

如果仍然需要继续处理，可以在任务评论里 @ 该 Agent，或在任务对话中继续回复。

常见触发来源

除了把任务处理人设置为 Agent，Agent 运行还可能来自：

  • 任务评论中提及 Agent；
  • 与 Agent 的对话；
  • 自动化触发；
  • 重试某次失败运行；
  • 快速创建任务。

不同来源的运行都会保留在对话记录里。对于需要团队持续跟踪和验收的工作，建议尽量落到任务中执行。

常见问题

为什么任务指派给 Agent 后没有开始？

先检查任务是否仍在 Backlog。如果任务在 Backlog，Agent 会等待，不会立即执行。然后检查电脑是否在线、并发是否已满、代码库和凭证是否配置正确。

为什么任务一直排队？

常见原因是电脑离线、Agent 或电脑并发已满、同一个对话里上一项还没执行完，或者小队成员在共用的任务目录里依次执行。排队原因会显示在「排队中」下方，详见为什么显示「排队中」？。

Agent 执行失败后怎么办？

打开对话记录，先看失败说明的标题和技术详情，再对照下面的 排查执行失败。不要只根据一个 HTTP 状态码决定下一步。仍不确定时，复制诊断信息，再加 HiFox 群咨询。

Agent 可以同时处理多个任务吗？

取决于 Agent 的最大并发数（执行指派的任务）和默认工作目录配置。创建临时目录更适合并行；指定已有目录通常需要等待空闲目录。

Agent 的输出在哪里看？

优先在任务评论和对话记录里查看。需要细节时，再打开执行转录。

排查执行失败

任务失败后，先打开对话记录里的失败说明。标题会告诉你发生了什么，技术详情里是模型服务返回的原文。先对照标题打开下面匹配的小节；对不上就留在这一节。原因还不清楚时，失败说明里仍然会提供查看帮助文档和加 HiFox 群咨询。

技术详情里的 HTTP 状态码只能当线索，不能单独决定下一步：

  1. 429：可能是请求太频繁，也可能是账单或额度。OpenAI 常把这两类都标成限流，要再看详情里的 error.code。Anthropic 的 429 也可能是月度花费上限，而且不一定告诉你该等多久。
  2. 400：格式不对、上下文太长、内容策略，甚至你自己设的花费上限，都可能落在这里。
  3. 413：多半是图片或附件的字节太大，不是对话 Token 窗口满了。
  4. 403：密钥往往仍然有效，缺的是模型、组织或地区权限。先不要当成密钥填错。
  5. Timeout / 408 / 504：请求太慢、被取消，或中间网关超时。默认不是电脑断网。
  6. 如果详情里出现内容策略或找不到模型，也留在这一节对照原文，不要急着重试同一条请求。

可以按顺序做：

  1. 对照失败说明的标题，打开下面匹配的小节。
  2. 需要找人一起看时，复制诊断信息。里面会带上 HiFox、Runtime、这次运行、已经显示出来的技术详情，以及时间。
  3. 仍无法处理时，加 HiFox 群咨询。

相关厂商说明：

模型服务凭据未被接受

已配置的模型服务拒绝了本次请求使用的凭据。

可以按顺序检查：

  1. 请电脑负责人检查或更换模型服务密钥、登录状态。
  2. 确认这台电脑用的是当前组织允许的账号，而不是过期的本地缓存。
  3. 换好凭据后再重试。同一把已被拒绝的密钥再试，通常不会恢复。

如果详情里是 403，先检查模型、组织和地区权限，不要先去改密钥。

相关厂商说明：

已达到模型服务频率限制

模型服务正在限制此账户或连接的请求频率。

可以按顺序检查：

  1. 等一会儿再试。技术详情里如果写了 Retry-After，按它等待。
  2. 降低并发，或换一台不那么忙的电脑。
  3. 请电脑负责人查看该服务的速率限制。

先不要去加额度。额度用尽是下一节。

相关厂商说明：

模型服务额度已用尽

为此模型服务配置的账户没有足够的剩余额度。

可以按顺序检查：

  1. 请电脑负责人检查套餐、额度或花费上限。
  2. 额度恢复，或换到仍有额度的账号后，再重试。
  3. 只重试同一条失败请求，恢复不了额度。

先不要「等几秒再试」。那是频率限制，不是额度用尽。

相关厂商说明：

模型服务暂时繁忙

模型服务当前已达到容量限制，暂时无法处理此次请求。通常不是提示词写错。

可以按顺序检查：

  1. 稍后再试，或换一个当前可用的模型。
  2. 如果短时间连续出现 529 或 overloaded，先等服务恢复。

Anthropic 的 529 表示服务端繁忙，不是这台电脑自己的请求频率用完了。

相关厂商说明：

找不到所选模型

当前服务或账户中不存在所选模型。常见原因是模型名称、服务商命名空间、账户权限或网关模型目录与当前配置不一致。

可以按顺序检查：

  1. 按服务商文档逐字检查模型名称，包括服务商要求的命名空间。
  2. 确认这台电脑使用的账户或网关有权访问该模型。
  3. 修正配置后再重试。HiFox 不会自动替换你选择的模型。

需要求助时保留技术详情；其中包含服务商返回的信息，但不会暴露凭据。

请求超出模型处理范围

此次请求包含的输入超过了该模型单次上下文窗口。

可以按顺序检查：

  1. 缩短对话，或拿掉部分附件。
  2. 换一个上下文窗口更大的模型后再试。

如果详情里是 413，先检查图片或附件大小，不要先当成对话太长。

相关厂商说明：

图片超过模型支持的大小

模型服务拒绝了这张图片，因为它超过了支持的大小限制。常见大约是 5–20 MB；Anthropic Messages 也有约 32 MB 的字节上限。

可以按顺序检查：

  1. 压缩图片，或换更小的图。
  2. 去掉多余的截图后再重试。

这是图片字节太大，不是对话 Token 窗口满了。

相关厂商说明：

无法连接到模型服务

无法访问已配置的模型服务。

可以按顺序检查：

  1. 检查这台电脑到模型服务的网络、代理和证书。
  2. 如果任务跑在这台电脑的本地服务上，再确认本地服务在线。见 电脑。
  3. 网络恢复后再重试。

请求超时、你取消了运行，或出现 504，默认不是电脑断网。

相关厂商说明：

模型服务拒绝了此次请求

此次请求包含该模型服务不支持的输入或选项。

可以按顺序检查：

  1. 检查模型和请求选项，例如不支持的参数或格式。
  2. 去掉实验性开关或自定义参数后再试。

如果详情说的是内容策略，或找不到这个模型，回到上面的 排查执行失败，按原文处理，不要只改请求参数。

相关厂商说明：

隔离运行没能建立独立工作区

这次运行被设置为在「指定已有目录」的独立副本（worktree）里执行，但副本没有建起来。运行在改动你的目录之前就停下了。

可以按顺序做：

  1. 在失败说明里点【一键切换】，改成直接在该目录运行（串行）。
  2. 回到任务对话或对话记录，重新发起这次运行。

直接在该目录运行会改动原来的文件夹，同一路径一次只能有一个任务在跑，后来的任务会排队。如果你想继续用隔离副本，先确认该目录是 git 仓库且至少有一次提交。