black-yt ResearchHarness
总览
- ResearchHarness 是轻量、可审计的 tool-using LLM agent runtime，支持 CLI、本地前端、Python API 和 OpenAI-compatible API server。
- 主文件保留使用边界和 reference 导航；涉及安装、环境变量、API 协议、tools、workspace、trace 或测试时，按下面导航读取对应 reference。
- 任何源码阅读都只用于确认行为和参数，不能修改第三方源码、
site-packages、editable checkout 或共享环境。
上游版本锚点
- 当前 skill 对照 ResearchHarness GitHub
VERSION：v0.0.52。 - 当前 skill 对照 GitHub HEAD：
72e8a44737aadabc8c3f9e5c7ea76883b9c7032f。 - 维护本 skill 前，先重新检查上游
VERSION和 HEAD；如果任一变化，必须阅读 README、.env.example、官方教程和相关源码后再更新。
文件导航
| 序号 | 文件内容概览 | 关键词 | 触发时机 | 文件路径 |
|---|---|---|---|---|
| 1 | 概括 ResearchHarness 的定位和边界，说明 CLI、本地 UI、Python API、OpenAI-compatible server 四种模式、必须先配置工具 key、workspace/trace 安全和禁止修改源码/共享环境。 | ResearchHarness、agent runtime、CLI、local UI、Python API、OpenAI-compatible API、tool keys、workspace、trace、source read-only、shared env、safety boundary | 触发本 skill 后默认读取；判断是否适合用 ResearchHarness 前；开始安装/运行/部署/调试前；涉及工具 key、workspace、trace 或源码阅读边界时读取 | SKILL.md |
| 2 | 说明如何通过 PyPI 或 GitHub 获取 ResearchHarness、如何确认版本和仓库结构、如何阅读官方中英文教程、如何处理 relaxed dependency constraints、如何用 module.__file__/inspect 只读定位包内源码和关键模块。 |
PyPI、pip install、GitHub repo、requirements.txt、dependency constraints、structai>=0.1.23、source tree、docs/tutorial_en.md、docs/tutorial_zh.md、agent_base/model_profiles.py、agent_base/provider_compat.py、agent_base/tools/README.md、module.__file__、__version__、inspect.getsource、package path、read-only source、do not patch |
安装或升级前；排查依赖版本兼容前；需要确认当前版本行为前；需要从源码追溯工具 schema、参数默认值、provider 兼容性、token budget 或模块路径前；遇到文档和实际行为不一致时必须读取 | references/setup-and-source.md |
| 3 | 记录 CLI、本地浏览器前端和 Python API 的运行方法，列出 .env、模型、工具 key、生命周期、上下文压缩、token budget 校验、LLM wrapper、工具 timeout guard、provider sampling 参数省略和最新测试矩阵。 |
CLI、local frontend、Python API、.env、env.example、tool API keys、model config、lifecycle、compaction、token budget、RECENT_HISTORY_BUDGET_TOKENS、COMPACT_SUMMARY_MAX_TOKENS、READPDF_TIMEOUT_SECONDS、WEBFETCH_TIMEOUT_SECONDS、OMIT_GENERATE_PARAMS、omit_generate_params、--omit-generate-param、custom tool timeout、LLM wrapper、workspace root、interactive run、test_tool_availability、test_local_tools_validation、test_token_counting |
运行 CLI 前；启动本地 UI 前；写 Python 调用前；配置 .env/工具 key/模型参数/工具 timeout 前；处理 provider 拒绝 temperature、top_p、presence_penalty 前；选择 ResearchHarness 测试命令前；排查生命周期、上下文压缩、token budget、workspace root、PDF 超时或交互运行问题时必须读取 |
references/runtime-cli-python.md |
| 4 | 说明如何启动和调用 OpenAI-compatible API server，覆盖 /v1/chat/completions、请求/响应结构、extra_body object 约束、omit-generate-params、非 object/非法字段拒绝、multimodal 内容和协议兼容边界。 |
API server、OpenAI-compatible、chat completions、/v1/chat/completions、extra_body、llm-extra-body、omit-generate-params、object only、request schema、multimodal、streaming、OpenAI SDK、protocol boundary |
部署 API server 前；用 OpenAI SDK 调 ResearchHarness 前；新增 provider 参数、extra_body 或 omit-generate-params 前；排查 400/422、非 object 值被拒绝、非法 sampling omit 字段、协议兼容或多模态请求问题时必须读取 |
references/api-server-and-protocol.md |
| 5 | 记录工具可用性测试和 workspace 约束，覆盖 env.example 必要工具 key、联网工具代理排错、工具返回字符上限、ReadPDF/custom tool timeout、Bash 输出安全处理、前端 Markdown/图片/Mermaid/AskUser 行为、trace/compaction 产物、benchmark adapter、路径边界和测试验证顺序。 | tools、tool tests、env.example、workspace path、path safety、tool output limits、ReadPDF timeout、READPDF_TIMEOUT_SECONDS、custom Python tool、timeout_seconds、Bash binary output、non-UTF-8、frontend Markdown、workspace image、Mermaid、AskUser card、trace、compaction、benchmark adapter、network tools、proxy off、validation、test tool availability | 配置或测试 tools 前；接 benchmark adapter 前；处理 workspace/trace/compaction 前；联网工具失败或代理污染时；排查 PDF 解析卡死、custom tool 长时间不返回、Bash 输出截断、二进制输出、前端 Markdown/图片/Mermaid/AskUser 展示或工具 key 是否可用时必须读取 | references/tools-workspace-testing.md |
使用边界
- ResearchHarness 是轻量、可审计的 tool-using LLM agent harness。
- 适合本地 agent 工作、benchmark 公平执行底座、OpenAI-compatible agent API 后端、代码/文件/PDF/图片/网页任务。
- 它是 base harness，不是大型 workflow platform、多租户服务或完整产品平台。
- 不要擅自安装依赖、升级共享环境、修改长期配置或暴露公网服务；需要时先征得用户同意。
- API server 默认没有用户认证；公开暴露前必须加外层认证、访问控制或只绑定可信内网。
- trace/session state 不要放进 agent 可见 workspace，避免 agent 读取自己的执行记录。
- 推荐通过源码阅读确认复杂行为、参数默认值、工具 schema 和 API contract，不要只凭经验猜测。
- 源码只读：只用于阅读和定位问题，不要改源码，不要直接修改
site-packages、editable checkout 或共享环境。