runtime-behavior-probe

运行时行为探测

概述

使用此技能来调查真实的运行时行为，而不是复述代码或文档。先规划调查方案，然后执行用例矩阵，记录观察到的行为，并同时报告发现的结果以及获取这些结果所用的方法。

核心规则

• 将此技能视为仅供手动使用。不要依赖隐式调用。
• 调用此技能仅授权制定计划。每次运行时探测都必须先提出确切的探测方案，再获得用户明确批准。不要从技能调用或一般性的运行时行为调查请求中推断已获准执行。
• 请求批准前，披露来源身份、确切命令、传递执行的材料、已知的文件系统、环境、网络和主机服务能力、预期副作用，以及对拟议探测的控制措施。将未知能力标记为未知，不要假设其不可用。
• 等待用户明确肯定回复后再执行探测。批准仅适用于已披露的来源、命令、执行材料和能力范围。更改其中任何一项、添加其他探测或扩大已批准的测试矩阵前，都必须重新获得批准。
• 对于 openai-agents-js，将此技能视为一次性探测工作流，而非仓库实现工作流。
• 除非用户明确要求可复用的仓库产物，否则允许的写入范围仅限于：
  • 用于存放探测脚本或产物的临时目录
  • 用户正在编辑此技能本身时的 .agents/skills/runtime-behavior-probe/**
• 对于 openai-agents-js 中的一次性探测，不要修改 examples/**、packages/**、任何 package.json、README.md、工作区配置或构建配置。
• 如果草拟的计划会触及不允许的路径，请停止并重写计划，然后再编辑任何内容。
• 基线成功用例或冒烟测试通常是合适的切入点，但如果实际问题涉及边缘情况、漂移或故障行为，不要止步于此。
• 运行任何内容前先制定计划。先编写用例矩阵，再根据观察到的结果填写。矩阵可以放在临时笔记、临时文件或探测脚本头部。
• 默认提出本地或只读探测。仅在与任务明确相关时考虑实时服务，并在请求批准前应用以下轻量级门槛。
• 探测规模应与决策相称。从能够排除或验证当前假设的最小矩阵开始，仅在仍有不确定性时扩展。
• 进行实时探测前，应用以下三个轻量级门槛：
  • 目标门槛。仅使用任务明确允许的实时目标。
  • 意图门槛。只有用户明确要求对该集成进行运行时验证时，才提出实时探测。执行仍需在提出确切探测方案后另行获得批准。
  • 数据门槛。如果探测将读取环境变量、修改远程状态、产生重大费用，或使用非公开数据或用户数据，请说明确切的变量名称或数据类别，并事先获得明确批准。
• 执行前，将每个用例分类为只读、会修改状态或会产生费用。对于会修改状态或产生费用的用例，以及任何将读取环境变量的实时用例，运行探测前须定义清理或回滚方案。
• 一次性探测脚本应使用临时文件或临时目录。
• 在 openai-agents-js 中，默认将一次性探测文件放在 git 跟踪路径之外。除非用户明确要求提交到仓库的产物，否则不要在 examples/、packages/ 或其他仓库目录下添加一次性探测、测试框架、基准测试或示例。
• 保留临时产物，直到最终回复草拟完成。之后默认将其删除，除非用户要求保留或后续工作需要这些产物。即使删除了产物，报告中仍须简要说明命令形式、运行时环境和产物状态。
• 执行会读取环境变量的实时探测前，告知用户计划使用的确切变量名称及原因，然后等待明确批准。例如 OPENAI_API_KEY 和被测系统预期使用的其他默认名称。
• 当需要环境变量审批且 request_user_input 工具可用时，请使用该工具，而不是以纯文本询问是否批准。提出一个简洁的问题，并提供互斥选项，例如 允许一次（推荐） 和 不允许；省略 autoResolutionMs，并将批准限定为单次探测、明确列出的变量和目标。如果该工具不可用，则改用简洁的纯文本审批问题，并在用户明确批准前不要继续。
• 即使秘密来自此技能可能使用的标准环境变量，也绝不要打印秘密。
• 对于此仓库中的 OpenAI API 或 OpenAI 平台探测，尽早使用 $openai-knowledge 确认依赖契约的细节，例如支持的参数、字段名称和限制。使用运行时探测来验证或质疑文档所述行为，而非跳过文档查阅。如果 docs MCP 不可用，请改用 OpenAI 官方文档，并在报告中说明使用了备用方式。
• 对于基准测试或比较探测，执行前明确公平性条件。记录哪些因素保持不变、测试的变量是什么、哪些响应形状约束可确保比较公平，以及哪些用量或令牌计数器会影响延迟或成本的解读。
• 在 openai-agents-js 中，默认采用轻量级本地探测编写流程：临时 probe.ts 加临时 tsconfig.json，然后运行 pnpm exec tsc --noEmit -p <tmp-tsconfig>，再运行 pnpm exec tsx <tmp-probe>。仅当运行时问题专门涉及 dist/、生成的导出项或打包产物时，才升级为运行 pnpm build。
• 在 openai-agents-js 中，不要将运行时验证、基准测试或模型比较请求视为添加可复用示例、基准测试框架、包脚本或已纳入版本控制的样例的授权。此类仓库更改必须有用户的明确意图。
• 对于 OpenAI 托管工具探测，在将否定结果归因于运行时行为之前，先排除设置上的歧义：
  • 如果问题取决于是否调用工具，请使用匹配的 tool_choice 强制走工具调用路径。
  • 将 container_auto 和 container_reference 视为不同用例，而非可互换的设置细节。
  • 先清除不受支持的模型或工具选项，避免其使探测结果无效。

Workflow

1. 用实际操作的方式重述调查目标。说明运行时表面、关键不确定因素，以及风险最高、需要测试的行为。
2. 对于 openai-agents-js，在进行任何实现工作之前，明确允许的写入范围。对于普通的一次性探测，这意味着只能写入临时目录。
3. 做简短的预检。先检查相关代码或文档，判断问题需要本地验证还是在线验证，并记下重要的仓库、基线或发布边界。
4. 在构建矩阵之前，先定义决策信号。对于疑似缺陷，明确指出用户可见的具体症状、可将其与正确行为区分开的命令或探测、预期的失败观测结果，以及已知正常的对照。确认该信号会经过真正的生产方和调用方路径，而不只是相邻的辅助函数。如果快速、确定性的本地测试能够回答问题，优先采用。如果无法构建可信的信号，请说明缺少的访问权限或构件，不要用相近行为代替证据。
5. 执行探测前先创建验证矩阵。覆盖基线行为以及最相关的失败或漂移情形。矩阵可以记录在临时笔记、临时文件中，或探测脚本的结构化头部中。
6. 预先为每种情况选择执行模式：
   • single-shot：用于确定性的一次运行检查。
   • repeat-N：用于缓存、重试、流式处理、中断、速率限制、并发或其他对不同运行敏感的行为。
   • warm-up + repeat-N：用于首次运行的冷启动效应可能扭曲结果的情况。除非任务显然需要其他方式，否则采用以下默认值：
   • 对运行敏感问题进行快速筛查：repeat-3。
   • 用于决策的延迟或发布建议：warm-up + repeat-10。
   • 成本较高的在线测试：从 repeat-3 开始，只有答案仍不明确时才增加次数。如果确实不确定额外运行是否值得花费时间或成本，请在扩大探测前询问用户。
7. 如果问题类似基准测试或涉及比较，分阶段运行。先针对对照组运行高信号试点矩阵，然后仅扩展仍有希望的候选项或尚未解决的情况。
8. 如果问题涉及疑似回归或行为变化，至少添加一个已知正常的对照案例，例如 origin/main、最新版本，或不使用疑似选项的相同请求。
9. 对于比较性探测，执行前先定义公平性条件。记录提示词或输入的形式、工具选择设置、模型设置的公平性、状态复用规则，以及确保比较公平的响应形式限制。如果输出长度差异可能造成显著偏差，也要记录用量或令牌数相关信息。
10. 如果问题是某个选项是否与另一个选项具有相同的智能或质量，请判断该矩阵只能支持示例模式的同等性，还是足以支持更广泛的质量结论。若要支持更广泛的结论，至少增加一个更难或更开放的问题；否则，明确说明结果仅适用于已覆盖的模式。
11. 如果隐藏状态可能影响结果，请在执行前规划状态控制。记录每种情况使用的是全新状态还是复用状态、如何处理缓存复用或缓存绕过、用于隔离重复运行的唯一 ID，以及如何验证清理结果。
12. 如果任何在线测试会读取环境变量，请列出每种情况涉及的确切变量名及其用途，并在执行前征求用户批准。如果可用，请优先使用 request_user_input 完成此审批，禁用自动决策，并仅提供批准或拒绝本次特定探测的选项。审批请求应简短，并包含目标位置、只读与修改或成本风险、确切变量名，以及相关的清理或回滚方式。
13. 在临时位置构建针对任务的探测脚本。脚本应小巧、易于观察，并且便于丢弃。
14. 如果你准备为 openai-agents-js 提交仓库内脚本、示例、基准测试或工作区脚本，请暂停并确认用户明确要求创建可复用的仓库构件。如果没有明确要求，请将探测保留在临时位置。
15. 在 openai-agents-js 中，明确运行时上下文：

• 实际可行时，从仓库根目录使用 pnpm exec tsx 运行 TypeScript 探针。
• 编写探针时，在 mktemp -d 下创建 probe.ts 和同级的临时 tsconfig.json，并在首次实际运行前执行 pnpm exec tsc --noEmit -p <tmp-tsconfig>。
• 记录当前提交、工作目录、Node 可执行文件、Node 版本，以及导入的包或源码路径。
• 避免意外从其他检出目录或 /tmp/node_modules 导入内容。如果探针需要仓库代码，请从以 process.cwd() 为根目录的仓库相对 file:// URL 导入。
• 如果问题是“此分支现在的行为是什么？”，优先导入当前分支的 src/；只有问题明确针对构建后的打包输出时，才优先导入 dist/。
• 不要仅为检查一次性探针的类型而运行全仓库构建。只有 dist/ 探针需要，或输出产物本身属于问题范围时，才运行 pnpm build。

16. 提交完整的探针方案，并披露上述要求的信息，包括每种情况或获批矩阵的确切命令，然后征求用户明确批准并等待。
17. 仅执行获批矩阵并收集证据。记录请求形式、设置、观察摘要、意外或负面结果、错误详情、耗时、运行时上下文、获批的环境变量名称、重复次数、预热处理、相关的方差、清理行为；进行对比时，说明哪些条件保持不变，以及影响结果解读的响应形式或用量说明。
18. 使用实际结果而非猜测更新矩阵。
19. 保留临时产物，直至起草最终回复。之后将其删除，除非用户要求保留或需要用于后续工作。基准测试和大量重复的探针通常需要后续跟进；结果可能需要复查时，通常应保留产物。若已删除，请保留并报告简短的运行摘要。
20. 先报告发现，优先列出意外或负面发现。然后总结验证方式及覆盖的情况。
21. 如果探针定位到一个明确缺陷，可以简要提出实现假设或最小复现方向。除非用户要求，否则不要扩展为更大的后续计划。

验证矩阵

使用便于快速浏览的矩阵。应从运行时问题和观察摘要入手，而不只是列出 expected 和 pass 或 fail。

矩阵至少包含以下列：

• case_id
• scenario
• mode
• question
• setup
• observation_summary
• result_flag
• evidence

在能实质性改进调查时，添加以下列：

• comparison_basis
• variable_under_test
• held_constant
• output_constraint
• status
• confidence
• state_setup
• repeats
• warm_up
• variance
• usage_note
• risk_profile
• env_vars
• approval
• control

将 result_flag 作为便于快速浏览的字段，例如 unexpected、negative、expected 或 blocked。只有在存在可信的对比依据、基线或文档约定可供比较时，才使用 status。

始终考虑矩阵是否应包含以下类别：

• 基线成功。
• 怀疑存在回归时的对照或基线比较。
• 边界输入或参数变化。
• 无效或不受支持的输入。
• 配置缺失或错误。
• 超时、网络中断或速率限制等暂时性外部故障。
• 重试、幂等性或清理行为。
• 共享状态或操作顺序可能产生影响时的并发或重叠操作。
• 问题不只是模式一致性时的开放式质量或智能样例。

需要更完善的优先级模型或可复用的案例模板时，请打开 validation-matrix.md。

临时探测脚本

将一次性脚本写入临时文件或临时目录，例如使用 mktemp -d 创建的目录。默认情况下，即使脚本会导入仓库中的代码，也应将其放在仓库之外。

对于 openai-agents-js，一次性运行时探测应保持一次性。除非用户明确要求创建可复用的仓库产物，否则不要添加 package 脚本、修改工作区配置，也不要创建纳入版本控制的基准测试或示例。

对于 openai-agents-js，默认编写流程应为：

1. tmpdir=$(mktemp -d)
2. 将 probe.ts 和 tsconfig.json 写入 $tmpdir
3. 在仓库根目录运行 pnpm exec tsc --noEmit -p "$tmpdir/tsconfig.json"
4. 如果快速类型检查通过，运行 pnpm exec tsx "$tmpdir/probe.ts"
5. 仅当探测有意导入 dist/ 或验证打包产物时，才运行 pnpm build

使用临时 tsconfig.json 扩展仓库的示例设置，但只包含一次性探测脚本，例如：

{
  "extends": "/absolute/path/to/openai-agents-js/tsconfig.examples.json",
  "compilerOptions": {
    "noEmit": true
  },
  "include": ["./probe.ts"]
}

如果探测需要仓库代码：

• 以仓库根目录作为工作目录运行。
• 在实际可行时，从仓库根目录运行 pnpm exec tsx /tmp/probe.ts。
• 将 pnpm exec tsc --noEmit -p /tmp/probe-tsconfig.json 作为执行探测前默认的快速类型检查步骤。
• 使用基于 process.cwd() 和仓库相对路径构建的 file:// URL 导入仓库模块。不要假设 /tmp 中可以解析 @openai/agents-core 等裸工作区导入。
• 探测当前分支行为时导入 src/，探测打包产物时导入 dist/。

设计探测时应尽可能提高可观测性：

• 打印或记录正在测试的确切场景。
• 捕获运行时上下文，例如 git SHA、工作目录、Node 可执行文件及版本、相关 package 版本、模型或部署名称、端点或 base URL 别名，以及会实质影响行为的任何重试或工具选项。
• 对于实时探测，只记录获准使用的环境变量名称。绝不打印其值。
• 尽可能捕获结构化输出。
• 保留原始错误类型、消息和状态代码。
• 对于对重复运行敏感的情况，捕获尝试索引、预热状态，以及有助于比较运行结果的稳定标识符。
• 对于重复运行或基准测试式的探测，在实际可行时同时写入原始结果和精简摘要产物。
• 尽量减少分支，让每个脚本只回答一个具体问题。

删除临时脚本或目录之前，保留一份简短的运行摘要，包含脚本路径、所用命令、运行时上下文，以及证据是保留还是删除。

需要轻量、一次性的 TypeScript 探测脚手架时，请打开 typescript_probe.ts。需要从临时脚本加载当前分支的工作区代码时，请打开 repo-import-patterns.md。

报告

按以下顺序报告：

1. 发现。先列出意外或负面发现。如果没有新发现，请明确说明。
2. 验证方法。总结所用代码、测试的运行时范围、执行模式和案例矩阵覆盖情况。
3. 案例结果。案例数量较多时，提供矩阵或其精简版本。
4. 产物状态和简短运行摘要。说明临时产物是已删除还是已保留，并提供保留的路径或摘要。
5. 可选的实现说明。仅当明确定位到一个缺陷，且简短的实现方向有所帮助时，才包含此项。

对于对比探测，报告还应说明哪些条件保持不变、测试了哪个变量，以及结果仅支持模式一致性还是支持更广泛的质量结论。

推荐的回复模板请参阅 reporting-format.md。

资源

• 打开 validation-matrix.md，用于设计和确定案例矩阵的优先级。
• 打开 error-cases.md，以扩展常见故障场景。
• 打开 openai-runtime-patterns.md，了解 OpenAI 和 Responses API 的常见探测模式。
• 打开 repo-import-patterns.md，了解相对于仓库的 TypeScript 导入指南。
• 打开 reporting-format.md，了解最终报告的结构。
• 打开 typescript_probe.ts，查看最简临时 TypeScript 探测脚手架。