prime-agent 测试套件架构指南基于 AgentSession 的确定性集成测试实践【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent导读本文基于 prime-agent 仓库中 packages/coding-agent/test/suite/README.md 展开完整介绍 coding-agent 包中新式 harness 化测试套件test/suite/的定位、目录组织规则、回归测试命名规范以及其底层依赖的harness.ts测试装置、faux假模型 provider 与AgentSessionRuntime测试实现。读完本文你将掌握如何在该仓库中编写 CI 安全、确定性强、不消耗真实 API 令牌的 Agent 会话级集成测试并理解其背后的设计动机与源码佐证。一、套件定位为什么需要新的 harness 化测试目录原文档开篇即明确Usetest/suite/for the new harness-based test suite aroundAgentSessionandAgentSessionRuntime.这是 coding-agent 包中新式测试套件的唯一归属地。它围绕两个核心运行时对象展开AgentSession单次 Agent 会话的抽象负责消息收发、工具执行、事件订阅、会话持久化等AgentSessionRuntime更高一层的会话运行时负责会话创建、fork、切换、RLM 子代理运行时管理等生命周期能力。从源码结构看对应的核心实现在 packages/coding-agent/src/core/agent-session.ts 与 packages/coding-agent/src/core/agent-session-runtime.ts而套件目录 packages/coding-agent/test/suite 下的测试文件基本全部围绕这两个对象展开——例如agent-session-runtime.test.ts专门刻画AgentSessionRuntime的新建、fork、切换、销毁等行为agent-session-autonomous.test.ts、agent-session-goal.test.ts、agent-session-compaction.test.ts等则验证AgentSession的自主续跑、目标管理、上下文压缩等能力。需要说明的是该套件是新式定位仓库根目录的 test.sh 与 coding-agent 的 vitest.config.ts 中套件测试与其他测试共用同一 vitest 运行器但套件内文件共享统一的 harness 基础设施保证测试风格一致。二、套件硬性规则CI 安全与确定性优先原文档列出了五条硬性规则这是本套件区别于一般单元测试的核心约束使用test/suite/harness.ts所有测试必须通过统一的测试装置创建会话与模型禁止各自为政地手动拼接依赖使用packages/ai/src/providers/faux.ts的 faux provider以本地假模型替代真实 LLM不使用真实 provider API、真实 API 密钥、网络调用或付费 token测试过程中不能产生任何外部副作用保持测试 CI 安全且确定性deterministic同一份响应脚本在任何机器、任何顺序下都产生一致结果当更广泛的确定性集成覆盖缺少某能力时扩展test/suite/harness.tsharness 是可持续进化的公共设施而不是每个测试各自堆砌私有脚手架。这些规则在仓库中有直接实现证据test/suite/harness.ts中createHarness()创建临时目录、注册 faux provider、构造内存态SettingsManager、AuthStorage与ModelRegistry即使启用已配置认证withConfiguredAuth也仅仅是把假密钥faux-key写入内存存储AuthStorage.inMemory()不触碰磁盘或网络。测试结束时cleanup()会调用session.dispose()与fauxProvider.unregister()并带重试地删除临时目录见 harness.ts确保不残留进程与文件。如何运行套件套件测试由 vitest 驱动。在 coding-agent 包目录下执行标准 vitest 命令即可例如# 运行全部测试默认排除 process-stress 与 kernel-heavy 标签 npx vitest run # 仅运行 test/suite 套件 npx vitest run test/suitepackages/coding-agent/vitest.config.ts 中定义了process-stress与kernel-heavy两个标签前者是真实进程压力与墙钟调度覆盖后者会启动真实 Python 内核并把技能同步进共享 venv。默认分片运行会通过tagsFilter: [!process-stress, !kernel-heavy]排除它们避免多文件同时启动真实内核拖垮相邻测试需要时可单独用--tag运行。这一配置正是CI 安全规则在运行器层面的落地。三、目录组织与回归测试命名规范原文档规定了两条组织原则宽泛的生命周期与特征characterization测试直接放在test/suite/根目录下针对特定 issue 的回归测试放在test/suite/regressions/子目录下回归测试命名为issue-number-short-slug.test.ts。仓库中 packages/coding-agent/test/suite 顶层可看到agent-session-runtime.test.ts、agent-session-autonomous.test.ts、agent-session-compaction.test.ts、agent-session-goal.test.ts、agent-session-prompt.test.ts、acp-mode.test.ts、daemon-serialized-refine.test.ts等生命周期/特征测试而 packages/coding-agent/test/suite/regressions 则全部是 issue 号前缀的回归文件例如2023-queued-slash-command-followup.test.ts、2753-reload-stale-resource-settings.test.ts、4531-agent-message-ui.test.ts、6006-bundled-bedrock.test.ts等与命名规范完全一致。以原文档给出的示例2023-queued-slash-command-followup.test.ts为例该文件真实存在它验证 issue #2023 的场景——扩展来源的排队斜杠命令后续queued slash-command follow-up应当被当作原始用户文本处理而不是再次派发命令。测试断言commandRuns为空、用户消息恰为[start, /testcmd queued]同时助手消息包含模型处理结果。这正是一个 issue、一个短名、一个文件的回归组织方式的完整范例。目录选择的判断标准测试描述的是AgentSession/AgentSessionRuntime 的通用生命周期行为如新建、resume、fork、dispose、事件顺序→ 放test/suite/顶层测试针对某次具体缺陷修复需要精确锁定历史行为 → 放test/suite/regressions/并带上 issue 号便于将来通过文件名回溯修复记录。四、harness 测试装置createHarness 的组成与关键选项harness.ts是整个套件的核心设施向外暴露createHarness(options): PromiseHarness。它的职责是一键组装一个完整可用的测试环境包括临时工作目录createTempDir()生成os.tmpdir()下带时间戳与随机后缀的目录作为会话cwd避免测试间相互污染faux provider通过registerFauxProvider()注册假模型并暴露setResponses/appendResponses/getPendingResponseCount用于编排模型输出内存态服务SessionManager.inMemory()或传入existingSessionFile时用SessionManager.open模拟生产环境重水合、传入persistSession时用SessionManager.create落盘、SettingsManager.inMemory()、AuthStorage.inMemory()、ModelRegistry.inMemory()Agent 实例构造带getApiKey、convertToLlm、onPayload/onResponse/transformContext钩子的 Agent并把扩展运行器ExtensionRunner桥接到 provider 请求的前后事件AgentSession注入上述服务与可选覆盖项如baseToolsOverride自定义工具表、rlmDepth/rlmMaxDepth、autonomous、autoRefineReviewer、serializedRefine、initialGoal等事件订阅session.subscribe()收集全部AgentSessionEvent到events数组并提供eventsOfTypeT()便捷过滤清理cleanup()统一释放会话、注销 provider、删除临时目录含maxRetries: 40的重试应对子进程延迟刷盘的ENOTEMPTY。HarnessOptions 关键字段速查字段类型作用api/providerstring覆盖 faux provider 的 API 与 provider 标识modelsFauxModelDefinition[]注册多个假模型如{ id: faux-1, reasoning: true }支持多模型场景settingsPartialSettings初始化内存态设置systemPromptstring覆盖默认系统提示默认You are a test assistant.toolsAgentTool[]覆盖内置工具表baseToolsOverrideresourceLoaderResourceLoader自定义资源加载器默认经createTestResourceLoader构造extensionFactoriesExtensionFactory[]注入测试扩展用于验证扩展钩子与事件withConfiguredAuthboolean是否预置假 API 密钥默认true置false可测未认证路径existingSessionFilestring在既有会话文件上重开模拟生产环境恢复rehydrationpersistSessionboolean是否将会话持久化到临时目录rlmDepth/rlmMaxDepthnumber子代理递归深度与上限autonomousAgentAutonomousConfig自主续跑配置如{ enabled: true, maxContinuations: 1 }autoRefineReviewerAutoRefineReviewer自定义 refine 评审器serializedRefineboolean启用串行化 refineinitialGoal{ objective; tokenBudget? }初始目标配置返回的 Harness 对象要点Harness提供session被测对象、sessionManager、settingsManager、authStorage、fauxprovider 注册体、models模型元组、getModel(modelId?)、setResponses/appendResponses、getPendingResponseCount、events/eventsOfType、tempDir与cleanup。此外harness.ts还导出了一组实用的消息断言辅助函数getMessageText(message)把消息内容字符串或 content block 数组归一化为纯文本conversationMessages(source)过滤掉构造时注入的 harness 摘要消息HARNESS_DIGEST_CUSTOM_TYPE返回真实的会话消息getUserTexts(harness)/getAssistantTexts(harness)分别取出全部用户/助手文本数组是断言对话流的最常用工具。配套的 packages/coding-agent/test/suite/scheduling.ts 则提供并发编排原语createDeferred()暴露 resolve/reject 的 Promise、gatedHook()before_agent_start门控扩展工厂、withStreaming()强制会话流式标志、createWaitingHarness()构造首轮调用wait门控工具的会话配合releaseToolExecution()在运行中途排队输入。五、faux provider不花一分钱的可编排模型套件之所以能做到零网络、零真实密钥关键在于 packages/ai/src/providers/faux.ts 实现的本地假 provider。其核心 APIregisterFauxProvider(options)注册 provider返回FauxProviderRegistrationfauxAssistantMessage(content, options?)构造助手消息content可为字符串、单个 content block 或数组支持stopReason如toolUse、errorMessage、responseId、timestampfauxToolCall(name, args, options?)构造工具调用 blockfauxThinking(text)/fauxText(text)构造 thinking 与 text blocksetResponses(responses)/appendResponses(responses)设置/追加响应脚本FauxResponseStep既可以是预制的AssistantMessage也可以是接收(context, options, state, model)的工厂函数——后者可实现根据上下文动态决定响应的高级编排getPendingResponseCount()检查尚未消费的响应数量用于断言模型调用次数。默认注册模型faux-1Faux Model默认baseUrl为http://localhost:0这种不可能连通的地址从根上杜绝真实网络请求。以agent-session-runtime.test.ts为例测试通过faux.setResponses([fauxAssistantMessage(one), ...])按序喂给模型随后断言会话行为agent-session-autonomous.test.ts则用两步响应验证自主续跑逻辑第一步助手向用户提问第二步助手给出最终答案最终断言getUserTexts中出现[autonomous-continuation]续跑注入以及getAutonomousStatus()的continuationsUsed、turnsUsed计数。六、AgentSessionRuntime 测试生命周期刻画的实现示例packages/coding-agent/test/suite/agent-session-runtime.test.ts 是宽泛生命周期与特征测试的典型代表覆盖了运行时对象的关键行为会话配置透传newSession()生成的替代运行时沿用原始sessionConfig深度传播新建/分支子会话时rlmDepth会沿 parent 引用边正确复制包括从旧式 header 推导有效深度幂等销毁dispose()多次调用只触发一次session_shutdown事件即使前置清理抛错也不会重放关闭事件子运行时逐个销毁其中一个失败不阻断其余RLM 子代理运行时管理createRlmSubagentRuntime在 create resolve 之前即发布进程内会话启动被取消时正确抛错且不残留子运行时被删除时会连带释放被替换的旧会话事件顺序新建与 resume 流程依次发出session_before_switch→session_shutdown→session_start且可被cancel否决fork 流程对应session_before_fork→session_shutdown→session_start跨 cwd 切换switchSession到其他目录的会话后运行时cwd同步更新状态恢复切换会话后模型与思考级别thinking level从目标会话恢复语义血缘进程内子会话会把parent_session_id与spawned_by_request_id写入语义边账本SEMANTIC_EDGES_LEDGER_FILENAME并且通过生产运行时工厂createDefaultRuntimeFactory而非转发全部选项的测试工厂验证缺陷不会藏在工厂白名单里——这是特征测试避免假阳性的一个绝佳示例。七、回归测试实战以两个真实 issue 为例示例 1issue #2023 排队斜杠命令后续文件 packages/coding-agent/test/suite/regressions/2023-queued-slash-command-followup.test.ts注册一个wait门控工具与一个注册了testcmd命令的扩展预设三步响应先工具调用waitstopReason: toolUse再两条助手文本prompt(start)启动会话等待tool_execution_start事件在工具执行期间调用extensionApi.sendUserMessage(/testcmd queued, { deliverAs: followUp })排队后续输入释放工具执行等待会话完成断言commandRuns为空斜杠命令未被再次派发、用户文本恰为[start, /testcmd queued]、助手文本包含模型处理结果。该测试同时示范了createHarnesssetResponses 事件订阅 门控工具四种机制的协作方式。示例 2issue #2753 重启后资源设置过期文件 packages/coding-agent/test/suite/regressions/2753-reload-stale-resource-settings.test.ts 展示了另一类回归形态它在临时agentDir/prompts/下写入test.md提示词模板随后通过createAgentSessionRuntime/createAgentSessionServices/createAgentSessionFromServices手工组装运行时不经过顶层 harness验证启动后重新加载reload能应用更新后的顶层提示词设置。这类配置热更新回归测试用到了真实文件系统但仍完全本地化不触碰网络。八、编写新测试的操作清单结合原文档规则与仓库实践在test/suite/中新增测试的推荐步骤判断归属生命周期/特征测试放test/suite/顶层issue 回归测试放test/suite/regressions/命名为issue-number-short-slug.test.ts引入 harnessimport { createHarness } from ./harness.js回归目录内用../harness.js注册 faux 模型并编排响应const harness await createHarness({ ... })随后harness.setResponses([...])按序提供模型输出需要动态行为时使用FauxResponseFactory必要时注入扩展与工具通过extensionFactories注册命令、事件钩子通过tools覆盖工具表记录并清理把 harness 推入afterEach清理列表回归测试通常维护harnesses: Harness[]并在afterEach中逐个cleanup()见2023-queued-slash-command-followup.test.ts用事件与文本断言优先使用getUserTexts/getAssistantTexts/eventsOfType/getPendingResponseCount做确定性断言若缺少通用能力优先考虑扩展harness.ts或scheduling.ts而不是在单个测试里复制脚手架——这正是原文档Extend harness.ts when needed的用意确认 CI 安全不引入真实 API key、网络调用与付费 token保持响应脚本自洽可复现。九、总结test/suite/是 prime-agent 面向AgentSession与AgentSessionRuntime的确定性集成测试阵地其价值在于统一 harnessharness.ts封装了会话、模型、认证、设置、事件等全部依赖测试关注点被收敛到业务断言本身faux providerfaux.ts以脚本化响应替代真实 LLM实现了零成本、零网络、完全确定性的模型行为编排清晰的目录约定区分通用生命周期测试与 issue 回归测试回归文件以 issue 号为前缀历史缺陷一目了然运行时级刻画agent-session-runtime.test.ts覆盖会话新建、fork、切换、销毁、RLM 子代理与语义血缘等关键路径并通过生产运行时工厂验证防止测试工厂与生产实现脱节。对于希望为该仓库贡献测试或深入理解其会话运行时的开发者test/suite/既是最好的上手入口也是一份可持续演进的可运行规范。【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考