plugin-test

测试 DeepSeek Harness 插件

选择能够证明更改正确的最小测试级别集合。默认不要运行完整测试套件，也不要重复已经通过的检查。

测试 Harness 版本迁移

将现有插件适配到新版 DSH 主机时：

1. 阅读 references/version-migration-testing.md，针对确切的迁移源版本和目标版本建立迁移清单，并扫描全部七类接触点。
2. 为每项适用的 breaking 或 behavior 变更添加有针对性的回归测试。变更级测试只能证明相应的迁移映射，不能证明整个插件有效。
3. 通过真实产品入口冷启动确切的目标版本，并完成一个完整的用户回合。类型检查、配置解析、Loader 冒烟测试和模拟 Context 均无法取代这项运行时验证。
4. 如实报告无法验证的凭据、提供方、操作系统、浏览器、PTY 和破坏性迁移边界。只要其中任何一项仍未验证，就不要声称已全面兼容。

以下命令和仓库路径使用官方 Harness 单体仓库中的测试级别名称。对于外部插件，请使用其各自仓库中的等效脚本和路径。不要添加不存在的 Harness 根命令，也不要强行要求它们采用单体仓库布局。

运行 Docker 发布冒烟测试

在发布前检查外部插件时，阅读 references/docker-release-smoke.md，并使用其中附带的运行器测试打包后的制品。固定一个确切的 DSH 版本和一个非 latest 的 Node 镜像，将制品安装到隔离的 Profile 中，通过真实 DSH 入口冷启动；如果仅靠启动无法触发已更改的行为，再添加一个基于 argv 的功能探测。

将生成的 JSON 和 Markdown 视为该制品和目标版本的有限证据。如实报告跳过的提供方、浏览器、操作系统、安全检查和其他版本，并将其标记为未验证；Docker 冒烟测试通过并不会扩大其自身的覆盖范围。生成的报告、原始日志、临时 Profile 和 Docker 缓存都应放在 Skill 目录之外。

测试级别

级别	命令	验证内容
单元测试	pnpm run test	运行各个包下 tests/** 中的 vitest 用例，以及仓库 scripts/**/*.spec.ts 中的脚本测试。覆盖边界情况、错误路径、事件顺序、并发竞争和契约回归。每个注册表都需要进行 HMR 安全性测试：销毁贡献该注册项的 fiber，并断言资源已移除。
覆盖率门槛	pnpm run test:coverage	在 Harness monorepo 中，packages/*/*/src 下的每个文件都必须达到 100% 覆盖率。在外部插件中，遵循其仓库声明的覆盖率阈值。覆盖率只能证明代码行已执行，不能证明已发布的功能确实有效。
真实 API 端到端测试	pnpm run test:e2e	针对真实提供商 API 验证行为，包括 DeepSeek 模型，以及由各自凭据（如 EXA_API_KEY 和 PERPLEXITY_API_KEY）控制的提供商冒烟测试。缺少凭据时，每个套件都会自行跳过，以确保不需要凭据的 CI 仍能通过。
快照测试	pnpm run test:snapshot	验证预期的免凭据输出，在使用持久化日志固定组装后的后端行为的同时，锁定传输契约和呈现效果。
Web 浏览器快照	pnpm run test:web	将 Chromium 回放输出与 apps/web/tests/snapshots/ 进行比较。这是 Linux PR 的必需门禁。CI 会强制使用只读的 DSH_SNAPSHOT=replay，绝不会写入预期输出。只能在本地录制或刷新快照，并审查每一处差异。

当提供商凭据可用且已获准执行真实 API 测试时，请运行相应的端到端测试。不要仅仅为了节省推理开销而跳过这些测试。无凭据测试只能证明流水线已连接；只有使用凭据运行，才能证明 Agent 能够使用真实模型。根据变更内容，覆盖文件写入提示词、多轮会话、工具使用，以及流式输出期间的取消操作。最有价值的冒烟测试是启动一个真实示例、发送一条提示词，并从 Agent 外部验证结果。自动跳过机制可确保不需要凭据的 CI 不受阻碍。记录每个跳过的提供商边界；切勿仅为通过测试而索取、暴露或持久化凭据。

根据变更范围选择测试级别

• 纯逻辑或内部辅助函数 → 仅运行单元测试。
• 新增或修改的包源码 → 运行仓库的覆盖率门槛。仅当 Harness monorepo 明确规定时，才应用单文件 100% 规则。
• 模型可见行为，例如提示词、工具 Schema、工具输出或 Skill 目录 → 在所属示例套件中添加免凭据快照，然后添加真实组合测试。
• 协议可见行为，例如 ACP、JSON-RPC 或线缆传输 → 在所属示例套件中添加免凭据快照。
• 用户可见行为，例如 CLI 对话记录、交互式终端或 GUI 流程 → 在 Harness monorepo 中，使用 apps/cli/tests/snapshots/ 或 apps/web/tests/snapshots/；在外部插件中，使用该仓库负责维护的产品入口测试套件。
• 提供商行为，例如新增适配器或真实提供商功能 → 凭据可用且已获准执行时，运行真实 API 端到端测试。
• 用户实际会运行的插件 → 按下文所述执行非单元级真实组合测试。切勿只测试手动组装的 ctx.plugin(...)。

快照测试的强制要求

每项非平凡的模型可见、协议可见或用户可见更改，都必须通过由仓库维护、可运行的组合，新增或更新一个不含凭据的场景。软件包测试、端到端断言、仅用于测试的模拟组合和 PR 描述，都不能替代完整的组装记录。在 Harness 单体仓库中，ACP 快照位于 examples/<name>/tests/snapshots/，无头 JSONL 快照位于 examples/headless-agent，终端流程位于 apps/cli/tests/snapshots/，浏览器流程位于 apps/web/tests/snapshots/。使用目标检出版本提供的记录或刷新命令，并检查所有生成的差异。外部插件应使用自己的快照框架。如果没有，则添加一个通过真实 Loader 运行的最小组合。

测试真实入口路径

• 面向用户的插件需要进行真实组合测试。通过 Loader 和应用或进程入口点启动仅用于测试的 cordis.yml。仅模拟外部服务或非确定性输入。断言模型可见的请求或日志、持久化状态或用户可见的输出。不要向已发布的默认配置添加测试选项。
• 只有当回归确实会导致测试失败时，守护测试才有用。当目标版本的确切契约要求不带 inject 的捆绑模块或组合模块使用命名导出时，添加显式的 expect('default' in mod).toBe(false) 和 unwrapExports 往返断言。证明引入回归时测试会变红，修复后会变绿。不要将此守护测试用于目标版本支持的默认插件对象或 Service 类。应根据它们实际的 Loader 契约进行验证。
• “真实入口路径”指已发布的构件。软件包的 bin 必须在原生 Node 下运行其构建入口，以暴露 tsx 可能掩盖的问题，包括关闭竞态、模块解析和加载失败被吞掉的问题。默认索引之外的运行时入口，以及不同捆绑组合共享的单例模块，也遵循相同规则。在 Harness 单体仓库中，确保其构建构件冒烟测试保持通过，例如目标版本中存在时的 packages/examples/*/tests/built-bin.e2e.ts 和 packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts。在外部插件中，对其打包入口进行冒烟测试。当确实缺少必需配置时，断言进程以非零状态退出。
• 在 Harness 单体仓库中，常规测试通过配置的源代码平面解析，只有显式的构建入口冒烟测试会使用构建构件。在外部插件中，遵循其解析器，但仍需添加一个显式的打包构件使用方，以确保源代码别名不会掩盖导出缺失或第二个运行时单例。
• 对于 Harness 单体仓库中的子进程启动，CI 和构建测试通道必须使用目标检出版本中的共享启动器，从构建后的 lib/ 运行每个示例或 Cordis 配置子进程。切勿为这些子进程手写 --import tsx。不加载 Cordis 的协议和操作系统测试固件，应遵循目标仓库当前的 Node/TypeScript 约定。外部插件应遵循自己的启动器，但必须覆盖打包构件。仅当源代码路径解析本身是测试对象时才选择 src，并在测试中说明这一契约。

确保测试有效

• 优先使用真实实现，而不是模拟对象。只对 LLM 适配器、网络和时钟等昂贵或非确定性边界进行模拟，同时让下游部分保持真实。手写的伪实现只能证明桥接层传输了字节，无法证明已发布的工具确实实现了所声称的行为。测试桥接工具调用时，应使用脚本化的模拟模型，同时让工具和执行器保持真实。
• 验证外部实际情况，而不是相信 Agent 的报告。端到端断言应在 Agent 外部重新运行命令或重新读取文件。只检查 Agent 输出中的关键词，会让作弊的 Agent 蒙混过关。断言未触及的文件保持逐字节不变。
• 端到端测试必须自行管理资源。在测试内部创建 Harness，并在 afterEach 中释放它，包括失败、重试或超时之后。将共享测试固件放在普通的 tests/harness.ts 中，绝不要放在另一个 *.e2e.ts 文件中；导入测试文件会再次注册其 describe，导致重复调用真实 API。
• 恢复测试必须区分每个块边界之前和之后发生的故障，并证明失败的块不会产生任何消息或工具副作用。覆盖耗尽、取消、策略组合、持久化、状态、传输次数、传输关闭后的空闲超时，以及生产环境中的 Loader 组合。

命令

在 Harness monorepo 中，使用目标检出版本中确实存在的命令，例如 pnpm run test、test:coverage、test:e2e、test:snapshot 和 test:web。确认每个脚本确实存在，不要假设历史命令列表仍然有效。在外部插件中，使用其自身的脚本，打包产物，将其安装到运行精确目标版本的隔离 Profile 中，并通过产品入口执行冷启动和核心路径冒烟测试。只运行一次能够覆盖已更改部分的最小测试集。CI 只能证明它实际定义的检查项。

请参阅 references/README.md 中的参考索引。