连接代码库

如果你希望 Agent 处理代码相关任务，需要先让 Agent 能找到项目代码。HiFox 中最常见的做法是连接 Git 仓库：Agent 执行任务时会在所选机器上 clone 对应仓库，读取代码、修改文件、运行命令，并把结果写回任务。

除了 Git 仓库，Agent 还支持一种只在 Agent 层面配置的本地方式：指定已有目录。它适合代码已经放在 Agent 所在机器上的场景，但不是空间代码库能力，也不会作为空间默认仓库被其他 Agent 继承。

什么时候需要准备代码库？

当任务涉及这些工作时，就需要先让 Agent 能访问代码：

阅读项目代码；

修复 Bug；

修改文案或 UI；

补充测试；

运行构建、测试或 lint；

分析代码结构；

让 Agent 生成可 review 的代码变更。

如果任务只是讨论需求、整理计划、总结文档，可能不需要代码库。但只要 Agent 需要进入项目目录执行工作，就应该先配置 Git 仓库，或为特定 Agent 配置指定已有目录。

选择哪种方式？

方式	配置位置	适合场景
空间 Git 仓库	空间设置	一个空间中的任务通常使用同一批仓库。
Agent Git 仓库	Agent 设置	某个 Agent 只处理特定仓库，或需要覆盖空间默认仓库。
指定已有目录	Agent 设置 → 任务运行设置	只给某个 Agent 使用机器上的本地已有目录。

一般建议优先使用 Git 仓库。这样任务、代码库和 Agent 配置都在 HiFox 中可见，也更适合团队协作和多个任务并行执行。

指定已有目录适合个人试用、本地已有代码、超大代码库，或目录中已经有特殊依赖、缓存和内部工具配置的场景。

添加 Git 仓库

在空间设置或 Agent 设置中找到代码仓库，添加目标仓库。

通常需要填写：

仓库 URL；

仓库描述；

这个仓库绑定到哪个空间或 Agent。

仓库 URL 可以是 HTTPS 或 SSH 地址，取决于你团队的 Git 访问方式。填写后，建议用一个低风险任务测试 Agent 是否能成功 clone 并读取仓库。

默认情况下，Agent 执行任务时会在独立临时目录中创建代码副本。这适合并行执行多个任务，避免多个任务互相改乱同一个目录。

空间 Git 仓库

空间 Git 仓库决定这个空间中的任务默认使用哪些仓库。

例如：

研发空间绑定主应用仓库；

文档空间绑定文档仓库；

客户交付空间绑定私有部署仓库；

移动端空间绑定 iOS / Android 仓库。

当你把任务安排给 Agent 时，如果这个 Agent 没有单独绑定 Git 仓库，它通常会使用任务所在空间里设置的 Git 仓库。

如果一个空间没有绑定仓库，而 Agent 也没有绑定仓库，Agent 可能可以看到任务，但无法进入代码目录完成工作。

Agent Git 仓库

Agent 也可以单独绑定 Git 仓库。

适合这样做的情况包括：

这个 Agent 只处理某个仓库；

这个 Agent 需要访问多个空间共用的仓库；

空间默认仓库不适合这个 Agent；

你希望明确限制 Agent 的代码访问范围。

如果 Agent 绑定了仓库，它会优先使用自己的仓库配置；如果没有绑定，则使用空间里的 Git 仓库设置。

Agent 指定已有目录

指定已有目录是 Agent 的任务运行设置，只在 Agent 层面配置。它不是空间代码库能力，也不会作为空间默认仓库被其他 Agent 继承。

如果代码已经在 Agent 所在机器的某个目录里，可以在 Agent 设置中把任务工作目录改为 指定已有目录。

操作步骤：

进入 Agent 的设置页。

找到 任务运行设置。

将 任务工作目录 从“独立临时目录”改为 指定已有目录。

点击修改，选择或填写机器上的已有代码目录，例如 /Users/me/code/my-app。

确认这个目录在 Agent 所选机器上真实存在，并且运行时有权限读取、修改和运行命令。

使用指定已有目录时，Agent 会直接在这个目录中执行任务，不会为每个任务创建新的 git worktree 或代码副本。为了避免多个任务同时修改同一个目录，指定已有目录通常更适合顺序执行。

如果你希望多个代码任务安全并行，更推荐给 Agent 绑定 Git 仓库，并使用独立临时目录。

访问凭证如何工作？

HiFox 本身记录仓库配置，但真正访问仓库的是 Agent 所在的机器。

也就是说，Agent 会通过它所在机器上的 Git 凭证访问仓库。你需要确保这台机器已经配置好对应的 Git 权限，例如：

已登录 GitHub、GitLab 或内部 Git 服务；

SSH key 已配置并有仓库访问权限；

HTTPS token 或凭据可用；

私有仓库对这台机器可访问。

如果机器无法 clone 仓库，Agent 也无法通过 Git 仓库完成代码任务。

使用指定已有目录时，也要确认这个目录在机器上存在、路径正确、当前运行用户有权限读写，并且目录中的依赖和工具可用。

代码托管凭据和密钥

对于需要统一提供的凭据，可以在密钥中添加代码托管凭据或环境变量。

密钥会加密保存，保存后不会再次显示。不要把 token、API Key、部署凭据或内部服务令牌写进任务描述和评论。

如果配置了 GitHub 代码托管凭据，它也可以作为 GH_TOKEN 注入 Agent 运行环境，方便 Agent 使用 GitHub 相关命令。

用任务测试代码访问是否正常

准备好 Git 仓库，或给某个 Agent 配置指定已有目录后，建议创建一个低风险任务测试连接，例如：

请读取项目 README，确认项目使用的主要语言、包管理器和测试命令。不要修改文件，把结论写回任务评论。

这个任务可以验证：

使用 Git 仓库时，Agent 能否 clone 仓库；

使用指定已有目录时，这个 Agent 能否进入目标目录；

机器上的 Git 凭证或本地目录权限是否有效；

Agent 是否能读取代码；

Agent 是否能把结果写回任务。

如果这个任务成功，再开始让 Agent 修改代码或运行更复杂的检查。

常见问题

Agent 说无法访问仓库怎么办？

如果使用 Git 仓库，先检查任务所在空间或 Agent 是否绑定了这个仓库，再检查 Agent 所在机器是否有 Git 访问权限，能否手动 clone 这个仓库。

如果这个 Agent 使用指定已有目录，检查 Agent 设置里的路径是否正确，以及这个目录在所选机器上是否存在。

仓库已经添加，为什么 Agent 还是找不到代码？

可能是任务所在空间没有绑定仓库，Agent 没有绑定仓库，或者这个 Agent 的指定已有目录没有配置正确。检查空间设置、Agent 设置中的 Git 仓库配置，以及 Agent 的任务工作目录设置。

指定已有目录可以配置在空间上吗？

不可以。指定已有目录是 Agent 的任务运行设置，只对这个 Agent 生效。空间层面配置的是 Git 仓库，不是本地目录。

需要把密钥写进任务描述吗？

不要。密钥应该通过密钥配置提供，任务描述只写目标、上下文和验收标准。

删除仓库会删除代码吗？

不会。删除 HiFox 中的仓库配置只会让 Agent 不再通过这条配置使用该仓库，不会删除 Git 服务中的代码仓库。

什么时候需要准备代码库？#

选择哪种方式？#

添加 Git 仓库#

空间 Git 仓库#

Agent Git 仓库#

Agent 指定已有目录#

访问凭证如何工作？#

代码托管凭据和密钥#

用任务测试代码访问是否正常#

常见问题#

Agent 说无法访问仓库怎么办？#

仓库已经添加，为什么 Agent 还是找不到代码？#

指定已有目录可以配置在空间上吗？#

需要把密钥写进任务描述吗？#

删除仓库会删除代码吗？#