用途
该技能用于调试 run-examples.yml 工作流中失败的示例测试。run-examples.yml 工作流会运行 examples/ 目录下的示例脚本，其触发方式有两种：为 PR 添加 test-examples 标签，或手动触发工作流（manual workflow dispatch）。当 CI 中的 run-examples.yml 出现失败时，可使用本技能进行排查。
主要能力与调试步骤
1. 隔离失败测试
修改 tests/examples/test_examples.py，将测试聚焦到特定目录，例如：
_TARGET_DIRECTORIES = (
# EXAMPLES_ROOT / "01_standalone_sdk",
EXAMPLES_ROOT / "02_remote_agent_server", # Keep only failing directory
)
2. 排除测试
将失败的示例加入 _EXCLUDED_EXAMPLES，并附上排除原因，例如：
_EXCLUDED_EXAMPLES = {
# Reason for exclusion
"examples/path/to/failing_test.py",
}
3. 触发工作流
通过切换 test-examples 标签来触发：
移除标签：
curl -X DELETE -H "Authorization: token $GITHUB_TOKEN" \
"https://api.github.com/repos/OpenHands/software-agent-sdk/issues/${PR_NUMBER}/labels/test-examples"
添加标签：
curl -X POST -H "Authorization: token $GITHUB_TOKEN" \
-H "Accept: application/vnd.github.v3+json" \
"https://api.github.com/repos/OpenHands/software-agent-sdk/issues/{PR_NUMBER}/labels" \
-d '{"labels":["test-examples"]}'
4. 监控进度
检查状态：
curl -s -H "Authorization: token $GITHUB_TOKEN" \
"https://api.github.com/repos/OpenHands/software-agent-sdk/actions/runs/{RUN_ID}" | jq '{status, conclusion}'
下载日志：
curl -sL -H "Authorization: token $GITHUB_TOKEN" \
"https://api.github.com/repos/OpenHands/software-agent-sdk/actions/runs/{RUN_ID}/logs" -o logs.zip
unzip logs.zip -d logs
常见失败模式
- 端口冲突：固定端口（8010、8011）导致冲突，解决方案为使用 -n 1 运行或改用不同端口。
- 容器问题：Docker/Apptainer 配置问题，需检查 Docker 是否可用、镜像能否拉取。
- LLM 失败：瞬时 API 错误，重试测试即可。
- 示例缺陷：代码错误，需检查 traceback。
关键配置
工作流（.github/workflows/run-examples.yml）：
- Runner：blacksmith-2vcpu-ubuntu-2404
- 超时：60 分钟
- 并行度：-n 4（pytest-xdist：4 个并行工作进程）
测试文件（tests/examples/test_examples.py）：
- 每个示例超时：600 秒
- 目标目录：_TARGET_DIRECTORIES
- 排除的示例：_EXCLUDED_EXAMPLES