如何在 DeepSeek Harness 中使用 Apifox CLI

DeepSeek Harness 是一个循环。agent 会读取您的工作区、编辑文件、通过其 bash 工具运行命令，并根据输出结果决定下一步的操作。那么，为什么您的 API 测试没有被纳入到这个循环中呢？它们静静地呆在 Apifox 的 GUI 界面背后，只有当有人想起去点击时才会运行。agent 根本接触不到它们。

解决办法只需要一个配置块。Apifox CLI 是一个 npm 包（即 apifox-cli），可以直接在终端中运行您在 Apifox 中构建的测试场景。一旦安装了 CLI 并且 DeepSeek Harness 知道了它的存在，agent 运行 Apifox 场景的方式就与运行单元测试完全相同：执行命令、读取退出码，如果代码出错就进行修复。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

此外，从 Token 消耗的角度来看也是如此。如果一个 agent 每次都要通过重新阅读处理程序代码并推理响应结构来确认您的 API 是否仍在正常工作，那么它在每次交互中都会消耗大量的上下文。而运行单个命令的 agent 只需几行输出就能获取真实结果。CLI 将“API 是否正确？”这一问题压缩为一个简单的退出码，从而让 agent 可以将上下文额度花在代码修复上。

本指南将介绍通用安装指南中忽略的、针对特定 harness 的部分：DeepSeek Harness 实际读取的是哪个指令文件、其 bash 工具如何执行 apifox run，以及如何保持该循环的可靠性。如果您还没有安装 CLI，请先完成安装。《如何使用 AI 编码 agent 安装 Apifox CLI》一文详细介绍了 npm 安装、身份验证以及首次运行的步骤。本文假设您的终端运行 apifox --version 时会输出版本号，且您的机器已通过身份验证。

本文适用于哪个 DeepSeek Harness 版本

DeepSeek Harness（命令行中为 dsh）是 DeepSeek 于 2026 年 8 月 13 日发布的开源 agent harness，与之一同发布的还有 API 上的 V4-Pro。它采用 MIT 许可证授权，项目托管在 github.com/deepseek-ai/deepseek-harness，截至 8 月 20 日已收获超过 16.9 万个 Star。您可以通过 npx @deepseek-ai/dsh web 启动它，这会在 http://127.0.0.1:3080 启动一个本地 Web UI。在界面中，您可以选择一个工作区（即您启动该命令的项目目录），随后 agent 就会在该目录中开始工作：读取和编辑文件、运行命令，并在执行当前权限策略下需要授权的操作前进行询问。

有两件事决定了下文的所有内容。首先，该 harness 是一个 developer preview（开发者预览版）。README 中使用大写字母警告过，后续会存在不兼容的破坏性变更，因此如果遇到无法加载的情况，请将本文中的文件名和配置键视为 2026 年 8 月底的准确版本，并对照仓库文档进行重新核对。其次，dsh 中的一切都是插件，基于 Cordis 架构构建，这让以下实际问题有了答案：哪个插件会读取您的项目规则，它又在寻找什么？要了解更广泛的介绍，请参阅什么是 DeepSeek Harness；要了解它与老牌工具的对比，请参阅 DeepSeek Harness vs Claude Code。

步骤 1：将 CLI 放入 AGENTS.md

DeepSeek Harness 通过其 @deepseek-ai/dsh-agent-instructions 插件读取工作区指令，如果您使用过其他 Agent，会发现其默认设置非常友好。根据该插件的源码和配置目录，加载器会从会话的工作目录向上遍历到您的项目根目录（以 .git 为标志），并在沿途的每个目录中加载 AGENTS.md，若不存在则回退加载 CLAUDE.md。名为 AGENTS.local.md 或 CLAUDE.local.md 的本地覆盖文件会在基础文件之后加载，而位于 $DSH_HOME（默认为 ~/.dsh）中的固定用户全局 AGENTS.md 则适用于所有项目。超过 1 MiB 的文件会被忽略，而您的规则文件绝不会达到这个大小。

实际效果：如果您的仓库中已经有了针对 Codex 的 AGENTS.md 或针对 Claude Code 的 CLAUDE.md，DeepSeek Harness 无需额外配置即可直接读取。只需在其中添加一段简短的 Apifox 内容：

## API testing with the Apifox CLI
- To test the API, run the Apifox scenario. Do not click through the GUI.
- Command: apifox run -t <scenario_id> -e <env_id> -r cli
- Exit code 0 means every assertion passed. Non-zero means a failure; read the report and fix the code.
- The machine is already authenticated. Never add an --access-token flag and never put a token in this file.

这就是为什么规则文件优于聊天交互。在会话构建器中输入的测试场景 ID 会在会话结束时消失。而写入 AGENTS.md 的测试场景 ID 会在每次新建会话时加载，适用于克隆了该仓库的每台机器上的每位团队成员。如果您在多个项目之间切换工作，用户全局的 ~/.dsh/AGENTS.md 可以用来培养习惯（例如“始终使用项目的 apifox run 命令来验证 API 变更”），而每个仓库自身的文件则包含实际的 ID。

步骤 2：从 Apifox 获取命令

您无需猜测测试场景和环境 ID。在 Apifox 中打开测试场景，转到其 CI/CD 标签页，然后复制生成的命令。它看起来像这样：

apifox run -t 123456 -e 789012 -r cli

`-t` 参数是测试场景 ID，`-e` 是环境 ID，而 `-r cli` 用于选择在行内打印结果的 reporter，这正是 Agent 读取数据所需要的。将真实的 ID 粘贴到你的 `AGENTS.md` 块中，以便 Agent 运行 Apifox 生成的实际命令，而不是凭空猜测。

## 步骤 3：让 Agent 运行测试

在已选择工作区的 dsh Web 界面中启动会话。指令加载器已经将你的 `AGENTS.md` 馈送到 Agent 的上下文中，因此它知道该 CLI 的存在。进行一次涉及你的 API 的修改，或者直接提问：

Run the Apifox test scenario and tell me the exit code.

Agent 会通过其 bash 工具执行该命令，了解该工具的行为特征可以免去你日后进行调试的麻烦。根据 [tool catalog](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/tool-catalog.md?ref=apifox.com)，默认的 bash 工具会在**全新的 shell** 中运行每个命令：调用之间不会保留任何工作目录、变量或函数，并且除非传入了 `workdir`，否则命令会从会话工作区中运行。这对于 `apifox run` 这种单一且自包含的命令来说没问题，但 Agent 无法先 `cd` 到某个目录，然后再将运行测试作为第二步执行。如果你的场景必须从子目录运行，请在规则文件中将完整的调用命令写在同一行。

还有两个值得注意的行为特征。非零退出会返回一个显式的 `[exit code: N]` 标记，因此即使长输出被截断至尾部，通过/失败的信号仍能保留。此外，命令可能会在文件沙箱下运行：被拦截的操作会被报告为策略拒绝，而不是命令失败。只读的测试运行很少会触发此限制，但根据当前启用的策略，写入 `./apifox-reports` 的 HTML reporter 可能会受到影响。

运行是否需要你先点击确认取决于相同的权限策略。根据 [user guide](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/index.md?ref=apifox.com)，Web 界面会在执行需要审批的操作之前进行提示。当它提示需要运行 `apifox run` 时，请予以批准：针对 staging 环境运行的测试场景正是那种安全的、以只读为主的命令，而审批流的存在就是为了快速放行此类命令。

## 步骤 4：阅读报告

当运行结果变红（失败）时，报告中会有答案。通过 `-r cli`，Agent 可以在行内获得可读的细分结果：每个请求、每个断言，以及具体哪一个断言失败并显示预期值与实际值。失败的断言会命名具体的数据字段或状态码，这通常足以让 Agent 定位修复方法，而无需你进行解释。

如果你需要一份可以在浏览器中打开或提交给团队成员的报告，可以添加 HTML reporter：

apifox run -t 123456 -e 789012 -r cli,html ```

html reporter 会将一个自包含的文件写入 ./apifox-reports。请在列表中保留 cli，以便 Agent 仍能获取其读取的行内输出，从而决定其下一步操作。

端到端闭环

这就是此配置能为你带来的好处。假设 agent 正在编辑一个结账处理器（checkout handler）。如果没有 CLI，它的循环就会在“代码看起来正确”时结束。而有了 AGENTS.md 中的配置块，循环得以延伸：它编辑处理器，运行 apifox run -t 123456 -e 789012 -r cli，并读取结果。如果测试通过（Green），它就继续下一步；如果测试失败（Red），它会看到 [exit code: 1]，读取是哪个断言失败了（例如本应返回 200 却返回了 500、缺少 total 字段或货币代码错误），然后修复处理器并重新运行。API 契约校验就此融入到了 agent 运行单元测试时所采用的“编辑-测试-修复”循环中。

请注意 agent 并没有做什么：它不需要重新阅读每个路由文件来向自己证明该 API 可以正常工作。测试场景已经编码了预期的行为，这是由 API 的所有者在 Apifox 中可视化构建的。Agent 将校验工作委托给一个确定性的工具，从而将 token 花在需要判断的地方。这种分工就是整个模式的核心：dsh 编写代码，CLI 校验 API 层，而你只需在 Apifox 中撰写测试场景，完全无需编写测试代码。

验证 dsh 是否确实运行了它

Agent 可能会汇报它们并未实际取得的成功，而在开发者预览版的测试框架中，绝不能轻信它们的文字表述。以下是三项检查，按它们捕获问题的先后顺序排列。

第一，确认命令已运行。dsh 的 Web 界面会显示会话中 agent 的工具调用及其输出。寻找字面上的 apifox run ... bash 调用及其结果。如果 agent 声称它运行了测试，但没有出现这样的调用，那么它只是在总结一件它从未做过的事。要求它重新运行并显示原始输出。

第二，确认退出代码。直接询问：“那个 apifox run 命令的 exit code 是多少？”测试框架在失败时会给 agent 传递一个明确的 [exit code: N] 标记，因此没有任何可以掩饰的歧义。当 agent 的总结写着“测试通过”，但标记显示非零时，以标记为准。

第三，确认它使用的是真实的测试场景。——“找不到测试场景”的失败通常意味着 agent 虚构或记错了 ID。根据你的 AGENTS.md 配置块以及 Apifox 的 CI/CD 选项卡中的命令，重新核对 -t 和 -e 的值。规则文件中的 ID 才是真实的；agent 输入的任何其他内容都只是猜测。

可选：添加 Apifox MCP 服务端以获取接口定义/规范访问权限

运行测试场景可以完成校验工作。如果你还希望 agent 在编写代码时能够读取你的接口定义/规范，那就是 MCP 的工作了。但在此需要说明真实情况：截至 2026 年 8 月下旬，MCP 支持尚未在 DeepSeek Harness 的核心 README 或用户指南中进行文档说明。目前存在的是一个社区插件 hyqhyq3/dsh-mcp-manager，它是和生态系统中的其他插件一样，通过 GitHub 的 dsh-plugin 主题被发现的。它在“设置”下添加了一个 MCP 页面，支持远程 HTTP 和本地 stdio 服务端，将工具注册为 mcp__<name>__*，并从 <workspace>/.dsh/dshmm/mcp.json 中读取每个项目的服务端定义。

通过它，你可以连接 Apifox MCP 服务端。该服务端通过 MCP 暴露你的接口定义/规范，以便 Agent 在编写处理程序之前（而不是在测试场景失败之后）能够检查接口的实际数据模型。社区插件加上开发者预览版主机的组合意味着两者的任何一方更新都可能导致这一搭配失效，因此请将其视为一个附加层。上述 CLI 路径才是核心支撑：它只需要一个 Shell 即可运行。

预览版注意事项及未来走向

DeepSeek Harness 更新迭代非常快，并且会警告你它可能会破坏现有功能。最有可能发生变化的内容正是这里提到的：指令插件的备选文件、bash 工具的沙箱报告，以及社区 MCP 插件涉及的任何内容。不过，这种模式是通用的。一条规则文件写着“用这行命令验证 API”，再加上一个返回正常退出码的 CLI，今天在 dsh 中能够奏效，其原因与在 Claude Code 以及本系列中的其他测试工具中能够奏效是一样的：Agent 善于读取命令输出，但如果在没有输出的情况下，它们是无法被盲目信任的。

因此：下载 Apifox，可视化构建一个测试场景，从 CI/CD 选项卡中复制其 apifox run 命令，然后将该代码块放入你的仓库中可能已经存在的 AGENTS.md 文件中。下一次 DeepSeek Harness 修改你的 API 代码时，它会在告诉你完成之前，先检查自己的工作。

常见问题

DeepSeek Harness 是否原生读取 AGENTS.md？是的。@deepseek-ai/dsh-agent-instructions 插件会从你的项目根目录以及会话工作目录之上的目录中加载 AGENTS.md（或以 CLAUDE.md 作为备用），此外还会加载 AGENTS.local.md/CLAUDE.local.md 覆盖文件以及 ~/.dsh 中用户全局的 AGENTS.md。如果你已经为其他 Agent 维护了一个 AGENTS.md，dsh 会直接使用它，无需任何修改。

在 dsh 中使用 Apifox CLI 是否需要付费的 DeepSeek 计划？ 不需要。该测试工具是基于 MIT 许可证开源的，你需要自己提供模型：支持的服务商包括 Anthropic、OpenAI、Bedrock、Vertex 和 Azure，自定义网关可以通过 settings.yaml 进行配置，正如“如何在 DeepSeek Harness 中运行任何模型”中所介绍的那样。Apifox CLI 本身是一个免费的 npm 包；它需要的是 Apifox 测试场景和认证，而不是特定的模型。

为什么 Agent 的第二个命令会忘记第一个命令切换到的目录？ 这是设计使然。默认的 dsh bash 工具在全新的 shell 中运行每次调用，因此 cd 无法在命令之间持久化。你可以传递该工具的 workdir 参数，或者更简单的是，在你的规则文件中将完整的 apifox run 调用保持在单行中，这样就不会遗忘任何内容。

dsh 是否可以运行测试场景而无需每次都询问我？ 这取决于当前启用的权限策略。Web UI 会在需要审批的操作之前进行询问；用户指南中并未列出具体的权限策略级别，因此请检查你构建版本中的“设置（Settings）”，以查看你的部署允许哪些操作。当它确实弹出提示时，批准针对 staging 环境运行 apifox run 是一个安全的选项。