runtime-behavior-probe

运行时行为探测

概述

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

核心规则

• 将此 skill 视为仅可手动调用。不要依赖隐式调用。
• 调用此 skill 仅授权进行规划。每次运行时探测都需要在精确探测方案提出后获得用户明确批准。不要从 skill 调用本身或一般性的“调查运行时行为”请求中推断执行批准。
• 在请求批准之前，需披露来源身份、精确命令、间接执行的材料、已知的文件系统、环境、网络和宿主服务能力、预期副作用，以及该探测的控制方式。对未知能力应标记为未知，而不要假定其不可用。
• 等待明确的肯定回复后再执行探测。批准与所披露的来源、命令、执行材料和能力范围绑定。若要更改其中任何字段、新增其他探测或扩展已批准的矩阵，需重新获得批准。
• 基线成功或冒烟测试通常是合适的入口，但当真正的问题涉及边界情况、漂移或失败行为时，不要止步于此。
• 在运行任何内容之前先进行规划。先编写用例矩阵，再用观察到的结果填充。该矩阵可以放在临时笔记、临时文件或探测脚本头部中。
• 默认提议本地或只读探测。仅当实时服务明显相关时才考虑使用，并在请求批准前应用以下轻量门控。
• 按决策需要确定探测规模。从能够否定或验证当前假设的最小矩阵开始，只有在仍存在不确定性时才扩展。
• 在进行实时探测前，应用三项轻量门控：
  • 目标门控。仅使用对该任务明确允许的实时目标。
  • 意图门控。仅当用户明确希望对该集成进行运行时验证，或在探测方案提出后明确批准时，才运行实时探测。
  • 数据门控。如果探测将读取环境变量、修改远程状态、产生实质性成本，或涉及非公开或用户数据，应写明确切的变量名或数据类别，并先获得明确批准。
• 在执行前将每个用例分类为只读、变更或高成本。对于变更或高成本用例，或任何将读取环境变量的实时用例，需在运行探测前定义清理或回滚方案。
• 对一次性探测脚本使用临时文件或临时目录。
• 在最终回复草拟完成之前保留临时产物。之后默认删除它们，除非用户要求保留或后续跟进需要它们。即使产物已删除，也要在报告中保留简短的运行摘要，包括命令形式、运行上下文和产物状态。
• 在执行将读取环境变量的实时探测之前，告知用户计划使用的确切变量名及原因，然后等待明确批准。例如 OPENAI_API_KEY，以及被测系统预期的其他默认名称。
• 当需要环境变量批准门控且 request_user_input 工具可用时，使用该工具而不是纯文本批准问题。提出一个简洁问题，并给出互斥选项，例如 Allow once (Recommended) 和 Do not allow，省略 autoResolutionMs，并将批准限定于单次探测以及确切命名的变量和目标。若该工具不可用，则回退为简洁的纯文本批准问题，并且在用户明确批准之前不要继续。
• 切勿打印机密信息，即使它们来自本 skill 可能使用的标准环境变量。
• 对于本仓库中的 OpenAI API 或 OpenAI 平台探测，应尽早使用 $openai-knowledge 来确认与契约相关的细节，例如支持的参数、字段名称和限制。运行时探测用于验证或质疑文档中记载的行为，而不是跳过文档核对。如果 docs MCP 不可用，则回退到 OpenAI 官方文档，并在报告中说明使用了回退方案。
• 对于基准测试或对比探测，在执行前明确对等性。记录保持不变的内容、被测变量、能够保证比较公平的响应结构约束，以及对解释延迟或成本有重要意义的用量或 token 计数。
• 对于 OpenAI 托管工具探测，在将负面结果归因于运行时行为之前，先消除设置上的歧义：
  • 当问题取决于工具是否被调用时，使用匹配的 tool_choice 强制走工具路径。
  • 将 container_auto 和 container_reference 视为独立的用例，而非可互换的设置细节。
  • 先清除不受支持的模型或工具选项，以免它们使探测失效。

Workflow

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

• 在可行时，从仓库根目录使用 uv run python 运行 Python 探针。
• 记录当前 commit、工作目录、Python 可执行文件路径和 Python 版本。
• 避免意外导入其他检出目录或 site-packages 中的代码。如果必须偏离 uv run python，需说明确切原因，以及所使用的解释器或环境。

14. 提交完整的探针方案，包含上述所需的全部说明，并附上每个用例或已批准矩阵的确切命令，然后请求用户明确批准并等待。
15. 只执行已批准的矩阵并记录证据。记录请求形式、环境设置、观察摘要、意外或负面结果、错误详情、耗时、运行时上下文、已批准的环境变量名、重复次数、预热处理方式、相关时的方差、清理行为；对于对比，还需记录保持不变的条件，以及影响解读的响应形式或用量说明。
16. 用实际结果而非猜测更新矩阵。
17. 在最终回复草拟完成之前保留临时产物。之后除非用户要求保留，或后续跟进需要，否则将其删除。基准测试和重复运行较多的探针通常需要后续跟进，因此当结果可能被重新审视时保留产物是正常做法。如果删除了产物，需保留并报告一份简短的运行摘要。
18. 先报告发现，并将意外或负面的发现放在最前面。然后概述验证是如何进行的，以及覆盖了哪些用例。
19. 如果探针隔离出一个明确的缺陷，可以附上简短的实现假设或最小复现方向。除非用户要求，否则不要扩展为更大的后续计划。

Validation Matrix

使用一个便于快速浏览结果的矩阵。应从运行时问题和观察摘要出发，而不仅仅依据 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。

Temporary Probe Scripts

将一次性脚本写入临时文件或临时目录，例如通过 mktemp -d 或 Python tempfile 创建的目录。默认将脚本保留在仓库之外，即使它会导入仓库中的代码。

如果探针需要使用仓库代码：

• 以仓库作为工作目录运行，或
• 显式设置 PYTHONPATH 或等效的导入路径。
• 在 openai-agents-python 中，优先在仓库根目录执行 uv run python /tmp/probe.py。

设计探针时应最大化可观测性：

• 打印或记录正在执行的具体场景。
• 在可行时捕获运行时上下文，例如 git SHA、工作目录、Python 可执行文件及版本、相关包版本、模型或部署名称、端点或 base URL 别名，以及任何会显著影响行为的重试或工具选项。
• 对于实时探针，仅记录已获批准使用的环境变量名称。切勿打印其值。
• 尽可能捕获结构化输出。
• 保留原始错误类型、错误消息和状态码。
• 对于对重复敏感的用例，记录尝试序号、预热状态以及有助于比较各次运行的稳定标识符。
• 对于重复执行或基准式探针，在条件允许时同时写入原始结果和紧凑的摘要产物。
• 保持分支逻辑最小化，使每个脚本只回答一个狭窄的问题。

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

当你需要轻量级、可随时丢弃的 Python 探针脚手架时，请打开 python_probe.py。

报告

按以下顺序报告:

1. 发现。将意外或负面的发现放在最前面。如果没有真正的新进展,需明确说明。
2. 验证方法。概述所用代码、测试的运行时范围、执行模式以及用例矩阵的覆盖情况。
3. 用例结果。包含矩阵;如果用例数量较多,可提供其精简版本。
4. 临时产物状态与运行摘要。说明临时产物是已删除还是已保留,并提供保留路径或保留的摘要。
5. 可选的实现说明。仅当隔离出一个明确的缺陷,且简短的实现方向会有所帮助时才包含此项。

对于对比性探测,报告还应说明保持不变的因素、被测试的变量,以及结果是仅支持模式一致性,还是支持更广泛的质量结论。

打开 reporting-format.md 查看推荐的回复模板。

资源

• 打开 validation-matrix.md 以设计和排定用例矩阵的优先级。
• 打开 error-cases.md 以扩展常见的失败场景。
• 打开 openai-runtime-patterns.md 查看反复出现的 OpenAI 与 Responses API 探测模式。
• 打开 reporting-format.md 查看最终报告结构。
• 打开 python_probe.py 查看最小化的一次性 Python 探测脚手架。