#Agent

如果你已经在使用 Claude Code、Codex 等 AI 编程工具，HiFox Agent 不是另一套模型或编程工具。它把一套稳定的工作方式保存下来，再通过电脑上的 Claude Code、Codex 等运行时（Runtime）执行任务。

例如，你可以创建一个“前端修复 Agent”，配置它负责的范围、开始工作前要检查什么、修改后要运行哪些测试、使用哪个代码库和 Runtime。团队之后只需要把合适的任务指派给它，不必每次重新解释整套工作方式。

理解 Agent，需要先区分四个概念：

• 任务：这一次要完成什么，包含目标、上下文、评论和验收要求。
• Agent：应该如何工作，保存职责、指令、Skill、代码库和运行设置。
• Runtime：实际执行工作的 AI 编程工具或执行入口，例如 Claude Code、Codex。
• 电脑：Runtime 真正运行的机器，提供代码、凭据、工作目录、网络和计算资源。

一次任务的执行链路大致如下：

任务被指派给 Agent
  → HiFox 组合任务上下文和 Agent 配置
  → 派发到 Agent 选择的电脑
  → 电脑上的本地服务启动 Runtime（例如 Claude Code、Codex）
  → Runtime 读取代码、修改文件并运行命令
  → 进展、阻塞和结果写回 HiFox 任务

本页重点介绍如何设计、创建和管理 Agent。完整的电脑连接和 Runtime 状态见 电脑，完整执行过程见 Agent 如何执行任务。

#什么时候创建 Agent？

当一类工作具有稳定的职责或工作方式时，适合创建专门的 Agent。例如：

• 前端 Agent：处理 UI 修复、组件开发和前端测试；
• 测试 Agent：分析失败用例、补充测试并整理复现步骤；
• Review Agent：按团队标准检查代码质量、安全风险和测试覆盖；
• 文档 Agent：维护产品文档、术语和发布说明；
• 项目助理 Agent：拆解任务、总结进度并识别阻塞。

不要急着创建一个“什么都能做”的 Agent。职责越明确，团队越容易知道该把什么任务指派给它，它也越容易使用一致的方法完成工作。

如果要求只针对一次工作，直接写进任务；如果是一套会被多个 Agent 复用的流程，更适合整理成 Skill。

#Agent 包含哪些配置？

Agent 本身不是电脑，也不是代码仓库。它是一组“如何工作、在哪里工作”的配置，通常包括：

模型由 Runtime 决定。Agent 跟随所选 Runtime 的默认模型，不承诺也不展示具体模型名。需要更换模型时，应修改 Runtime 或电脑上的工具配置，而不是在 Agent 中寻找模型选项。

#创建一个可用的 Agent

一般流程是：

1. 确定 Agent 的稳定职责；
2. 填写便于团队判断用途的名称和描述；
3. 编写 Agent 指令；
4. 选择所属空间和可见性；
5. 选择可用的电脑和 Runtime；
6. 按需绑定 Skill、Git 仓库和运行配置；
7. 使用一个低风险任务验证它能否正常执行和回写结果。

#名称和描述写给团队看

名称应该让人一眼知道 Agent 的主要用途。描述则说明适合指派什么工作，以及不适合处理什么。

例如：

负责处理前端 UI 小修复和组件测试补齐。适合范围明确、可以独立验证的前端任务；涉及整体视觉方案或跨端架构调整时需要先由成员确认。

相比“开发 Agent”或“万能 Agent”，这样的描述更容易帮助团队正确选择处理人。

#指令写给 Agent 执行

指令会进入 Agent 的任务上下文，适合描述长期稳定的工作方式：

• 它负责什么、不负责什么；
• 接到任务后先阅读或检查什么；
• 什么情况下需要先提问；
• 修改代码后运行哪些检查；
• 遇到失败或缺少权限时如何处理；
• 最终需要汇报哪些内容；
• 哪些操作不能自行执行。

例如：

你负责处理小型前端修复。开始前先阅读任务描述、最近评论和相关代码；只有不同理解会明显改变实现时才提问。修改范围保持最小，完成后运行最接近的组件测试，并在任务中说明改动内容、验证结果和仍存在的风险。不要隐藏失败的检查。

不要把某个单次任务的具体需求长期写进 Agent 指令，否则后续不相关任务也会携带这些内容。

#用低风险任务验证

创建完成后，建议先指派一个只读任务：

请读取项目 README，确认项目使用的主要语言、包管理器和最接近的测试命令。不要修改文件，并注明支持每项结论的文件。

这个任务可以同时验证：

• Agent 是否选择了正确的电脑和 Runtime；
• Claude Code、Codex 等工具能否真正启动；
• Agent 是否获得了预期的任务上下文和指令；
• 电脑能否访问代码库和工作目录；
• Agent 能否把结果写回任务。

确认只读任务成功后，再让 Agent 修改代码或执行更复杂的命令。

#电脑、Runtime 和模型

Agent 的执行目标由电脑和 Runtime 共同决定：

• 电脑提供操作系统、代码、凭据、目录、网络和计算资源；
• Runtime 决定实际启动 Claude Code、Codex 或其他执行入口；
• Agent 保存对这个 Runtime 的使用方式和任务配置。

电脑在线并不等于 Agent 一定能工作。在线只表示本地服务心跳正常；只有 Agent 所选 Runtime 处于可用状态，任务才具备启动条件。

一台电脑可以服务多个 Agent，但任务能否立即运行还会受到电脑并发、Agent 并发和工作目录占用情况影响。连接、状态和排障方法见 电脑。

#把任务指派给 Agent

在任务的处理人中选择 Agent 后，它会成为这个任务的执行者。

• 如果任务处于 Todo、In Progress 或其他可执行状态，HiFox 会尝试开始运行；
• 如果任务仍在 Backlog，Agent 会等待，不会立即开始；
• 如果电脑、Runtime、并发或工作目录暂时不可用，任务会排队；
• 后续在任务中补充评论时，Agent 可以基于同一个任务上下文继续处理。

也可以从 Agent 详情选择指派任务。在这里可以搜索该 Agent 所属空间中的已有任务，或直接在同一空间新建任务。这个入口只提供当前成员有权访问、尚未归档的同空间任务；跨空间、已归档或无权访问的任务不会出现在选择中。只有未归档、非小队专属且当前具备执行条件的 Agent 才能用于此入口。

通过任一入口指派时，Agent 会作为执行处理人加入任务，不会移除已有的人员处理人。点击指派任务也不代表任务一定立即开始：任务状态、电脑和 Runtime 可用性、并发以及工作目录仍会决定任务是启动还是排队。

执行过程中，任务会保留 Agent 的进展、阻塞、失败、结果和执行记录。团队不需要到某个人的本地终端里寻找过程和结论。

任务状态和 Agent 工作状态是两套概念。任务可以处于 In Progress，而 Agent 运行可能仍在排队；Agent 也可能已经完成一轮运行，但任务仍需要成员 review 或继续推进。完整状态和触发方式见 Agent 如何执行任务。

#代码库和凭据

Agent 可以绑定 Git 仓库：

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

真正执行 clone、git、gh、构建和测试命令的是 Agent 所在的电脑。电脑上的 Git 凭据、目录权限和必要工具必须可用。

不要把密码、Token、API Key 或私钥写进 Agent 指令、任务描述或评论。完整配置方式见 连接代码库。

#Skill：复用团队工作方法

Skill 用来保存可以被多个任务或 Agent 复用的流程、规范和专业知识。例如：

• 代码 review 清单；
• 发布检查步骤；
• 文档写作规范；
• 前端组件测试流程；
• 故障排查方法。

如果同一套要求会反复出现，把它整理成 Skill 比复制进多个 Agent 指令更容易维护。Agent 可以绑定多个 Skill，但不要添加大量无关内容，否则会增加上下文噪音。

Skill 的创建、导入和维护方式见 Skill。

#任务运行设置

任务运行设置控制 Agent 如何使用电脑资源，主要包括：

• 任务工作目录：使用独立临时目录，或指定电脑上的已有目录；
• 最大并发运行任务数：Agent 同时可以处理多少个任务；
• 单任务最大运行时长：避免任务无限运行；
• 环境变量和启动参数：为 Runtime 或任务命令提供额外配置。

已检测 Runtime 的执行程序、默认附加参数和默认环境变量会提供基础启动配置。Agent 为同一个启动参数或环境变量设置的值优先于 Runtime 默认值。

#选择工作目录

一般建议优先使用独立临时目录。指定已有目录不会为每个任务创建独立代码副本，如果多个任务同时写入同一个目录，可能互相影响。

默认并发规则：

• 指定已有目录：默认并发等于已配置的目录数；
• 独立临时目录：默认并发是电脑并发的 50%。

可以手动调整并发，但不要盲目调高。更高并发会增加 CPU、内存、磁盘、网络和 Runtime provider 的压力；如果手动值高于指定目录数量，界面也会提示写入冲突风险。

#所属空间和可见性

每个 Agent 必须且只属于一个空间，只能用于该空间中的任务。

Agent 有两种可见性：

• 私有：只有 Agent 所有者可以看到和使用；
• 共享：所属空间中有访问权限的成员可以看到和使用。

可见性会影响成员能否找到 Agent、把任务指派给它、与它对话或通过任务评论触发它。任务只能选择与自己位于同一空间、且当前成员有权使用的 Agent。

部分 Agent 可能被设置为小队专属 Agent。这类 Agent 只能在所属小队中被调用，不会出现在普通 Agent 列表、处理人选择器或独立对话入口。详见 小队专属 Agent。

#Agent 状态和排障

Agent 列表和详情页会展示可用性、当前工作负载和最近运行。常见状态包括：

• 空闲：当前没有任务在运行；
• 工作中：正在执行任务；
• 受阻：运行遇到需要处理的问题；
• 错误：最近运行出现错误；
• 离线：电脑或 Runtime 当前不可用。

Agent 状态和单次运行状态不同。即使 Agent 在线，任务也可能因为并发已满或指定目录被占用而排队。

如果 Agent 没有开始，建议按以下顺序检查：

1. 任务是否仍在 Backlog；
2. Agent 所选电脑是否在线；
3. 所选 Runtime 是否可用；
4. 代码库、凭据和工作目录是否可访问；
5. 电脑或 Agent 并发是否已满；
6. 执行记录中是否有明确错误或等待原因。

#与 Agent 对话

除了把任务指派给 Agent，也可以直接与 Agent 对话。

对话适合临时询问、调研、解释和讨论方案；任务适合需要跟踪、指派、执行和验收的工作。如果对话中形成了明确行动项，建议创建任务并把结论带过去。

独立对话、任务中的 Agent 对话和任务评论并不是同一套记录。具体区别和使用方式见 与 Agent 对话。

#归档和恢复 Agent

不再使用的 Agent 可以归档。归档后：

• 不能再被指派新任务或在评论中提及；
• 正在执行的工作会被取消；
• 历史任务、评论和执行记录仍会保留。

归档前，先确认是否仍有运行或排队任务，以及自动化或小队是否仍依赖它。

需要恢复时，进入 Agent 列表的更多菜单，打开已归档 Agent，找到目标 Agent 后选择恢复。恢复后，它会重新出现在列表中；当空间权限、电脑和 Runtime 条件满足时，可以再次使用。

#最佳实践

• 按稳定职责创建：让一个 Agent 对应一类清晰工作，而不是覆盖所有场景。
• 描述写用途，指令写方法：描述帮助人选择，指令帮助 Agent 执行。
• 单次要求放任务：不要让临时需求长期污染 Agent 指令。
• 复用流程放 Skill：让团队维护一份规范，而不是复制多份 prompt。
• 先用只读任务验证：确认 Runtime、仓库、权限和结果回写都正常后，再执行写操作。
• 逐步提高并发：先确认电脑和 Runtime 能稳定处理当前负载。

#常见问题

#为什么 Agent 页面没有模型选择？

Agent 跟随所选 Runtime 的默认模型。HiFox 当前无法可靠读取 Runtime 实际使用的模型，因此不会在 Agent 上承诺或展示具体模型名，也不提供思考深度选项。需要更换模型时，请修改 Runtime 或电脑上的工具配置。

#Agent 没有开始运行怎么办？

先确认任务不在 Backlog，再检查电脑是否在线、Runtime 是否可用、代码库和凭据是否正确，以及并发或工作目录是否已满。执行记录通常会显示具体等待或失败原因。

#什么时候应该新建一个 Agent？

当一类工作有稳定职责、固定指令、特定代码库或固定 Skill 时，适合创建专门 Agent。只针对一次任务的要求应直接写在任务中。

#Agent 和小队有什么区别？

Agent 是单个 AI 队友，适合职责清楚、可以独立完成的工作；小队由 Leader Agent 协调多个 Agent 或成员，适合需要拆解、分工和汇总的复杂任务。详见 小队。

#为什么某个 Agent 在列表里找不到？

它可能已归档、属于其他空间、当前成员没有使用权限，或者被设置为小队专属 Agent。小队专属 Agent 只能在对应小队中使用。