Harness Engineering 实战指南为自主 Agent 设计可控、可审计、抗作弊的控制系统Agent-Skills-for-Context-Engineering【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering导读本文以本仓库skills/harness-engineering技能为核心系统讲解如何在 Agent 周围设计控制面harness——它能编辑什么、如何获得反馈、状态写在哪里、故障如何恢复、谁有权批准不可逆操作。你将掌握 Harness Boundary 四类表面Locked / Editable / Append-only / Human-controlled、紧反馈循环、持久化状态、搜索纪律、机制注册表与治理边界六大核心概念并能基于仓库中researcher/目录的真实实现直接搭建出可运行数天而不损害目标的自主研究循环与 Research-to-Skill 流水线。什么是 Harness EngineeringHarness engineering 设计的是 Agent 周边的控制系统允许编辑哪些表面、如何接收反馈、状态写入哪里、失败如何恢复、以及谁能批准不可逆的操作。它区别于写提示词或写工具——它决定的是一个 Agent 会话与一个能持续运行数天且不破坏自身目标的自主循环之间的差别。本仓库对该技能的定位见 SKILL.md 前置元数据是设计自主 Agent harness 时使用研究循环、评估脚手架、锁定与可编辑表面、持久化日志、新颖性门控、剪枝、回滚、PR 准备与人工审批边界。在仓库中harness-engineering 同时也是 researcher 操作系统researcher/README.md首个发布的研究技能——它把如何约束自主 Agent这一命题落实为了一系列可执行的脚本、rubric 与运行目录结构本文会逐层展开。何时启用 / 何时不启用激活场景在以下场景激活本技能构建自主研究或实验循环autonomous research/experimentation loops设计指标锁定 代码/内容可编辑的 Agent 环境创建 PR 生成型 Agent 或后台 Agent评估 Agent 能否在无频繁人工提示下安全运行为 Agent 工作流增加新颖性检查、消融、剪枝、回滚或持久化日志防止 Agent 刷分gaming benchmarks、削弱 rubric、或在上下文压缩后丢失状态边界划分不属于本技能的工作以下相邻工作由其他技能负责不要在 harness-engineering 中重复实现无自主控制面的通用质量门、回归套件、结果指标 →evaluationharness 工具的工具 schema、响应格式与恢复错误 →tool-design项目级任务-模型匹配、流水线形态与成本规划 →project-development远程沙箱、温池warm-pool与会话托管基础设施 →hosted-agents这一边界与仓库其他技能的 Integration 映射一致见 SKILL.md Integration 章节evaluation / advanced-evaluation / filesystem-context / multi-agent-patterns / tool-design / project-development / hosted-agents 分别承接 rubric 反馈面、成对比较评审、持久化日志、多 Agent 上下文隔离、工具契约、文件流水线与后台执行沙箱。核心概念Harness Boundary四类表面核心原则是把 Agent 与它运行的环境分离Agent 提出动作harness 定义允许的表面、反馈、持久化与晋升规则。使用四类表面表面示例规则Locked锁定评估指标、rubric、校验脚本、合并策略Agent 可以读取并提出修改建议但不能用改过的规则给自己打分Editable可编辑技能草稿、实验文件、提示词、被测配置Agent 可在循环中变更Append-only只追加结果日志、研究线程、被拒绝的想法Agent 只能追加不能重写Human-controlled人工控制合并、生产部署、凭据、破坏性操作需要明确的人工审批仓库源码将这一分类落成了可执行事实在 research_loop.py 中定义了一组LOCKED_SURFACES包括三个 rubric 文件、mechanisms/registry.jsonl、插件 manifest 与validate_repo.py本身initial_state()则为每次运行显式写出locked_surfaces与editable_surfaces数组research_loop.py#L78-L84Editable 仅限运行目录内的sources/、proposals/、reports/、logs/。rubric 侧同样要求每个 harness 变更提案必须按此四分类声明每个文件或设置researcher/rubrics/harness-change.md。紧反馈循环Tight Feedback Loops自主性成立的前提是反馈快速、无歧义、难以作弊。Karpathy 的autoresearch是最小模式一个可编辑文件、一个锁定的评估文件、固定的墙钟预算、一个标量指标、git 回滚、一个持久化结果日志。关键教训不是每个 harness 都需要一个指标而是模糊的反馈产生模糊的自主性。对于开放式的 research-to-skill 工作用锁定的 rubric、确定性结构检查、来源可追溯性与人工审查阈值替代标量指标——本仓库正是这样实践的harness-change rubric 的 H2 门Metric Integrity明确要求指标锁定、外部化、抗作弊否则判为 Fail 并转人工researcher/rubrics/harness-change.md#L22-L30。持久化状态Durable State长时间运行的 Agent 必须外部化状态把计划、来源队列、结果、失败与交接信息写入文件让未来的 Agent 无需依赖聊天历史即可恢复。Prime Intellect 的自主 nanoGPT 工作展示了持久化草稿本与THREAD.md风格日志在恢复、监控与审计中的价值。使用只追加日志记录尝试过什么什么改进了、什么失败了为什么一个候选被保留、丢弃或转入评审检查了哪些上游来源下一个 Agent 应该做什么仓库实现印证了这一点research_loop.py init会一次性创建带THREAD.md、sources/queue.jsonl、sources/evaluations/、proposals/、reports/、logs/、sources/evidence/raw/的运行目录research_loop.py#L575-L606每次状态迁移都会以追加方式写入 THREAD 决策块格式固定为decision / reason / evidence / nextappend_thread_decision。仓库还提供 templates/research-thread.md 作为通用模板其 Handover Summary 章节要求记录 best candidate、rejected candidates、unresolved risks、files to read first、next action——这正是压缩/交接前必须写盘的落地形态。搜索纪律Search DisciplineAgent 倾向于利用最近的表面、堆叠复杂度、少做剪枝。添加显式搜索规则按计划刷新上游来源在花费大额预算前要求新颖性检查保留被拒绝的尝试避免重复发现当栈中有多个新增时运行留一法剪枝leave-one-out pruning质量相同时奖励简化晋升前使用独立的验证仓库中novelty_check.py是搜索纪律第 2、3 条的可执行实现它把提案的 Mechanism / Skill Target / Proposed Delta / Risks And Gaps / Recommendation 五个结构化章节抽取为 token 集合分别与机制注册表researcher/mechanisms/registry.jsonl和语料skills/*/SKILL.md、researcher/fixtures/、researcher/runs/下的历史提案计算 Jaccard 重叠度默认阈值 0.18 判human_review、0.3151.75 倍判likely_duplicatenovelty_check.py#L200-L272。关键设计机制重叠优先于宽泛语料重叠因为关键词重叠只能抓到过时措辞而机制对比能抓到真正的重复。机制注册表Mechanism Registry对 research-to-skill 系统把被接受的机制与散文分开追踪。一条机制记录应包含稳定的mechanism_id、owning_skill、status、激活场景、行为变化、证据与失败模式。新颖性门应优先与注册表对比再使用更宽泛的语料重叠。仓库的 mechanisms/registry.jsonl 正是这样的注册表前几条记录与本文主题直接对应locked-editable-surfacesowning_skill: harness-engineering, status: accepted——在循环开始前把表面分为锁定/可编辑/只追加/人工控制防止 Agent 用改过的评估器批准自己的工作durable-research-threadowning_skill: filesystem-context——运行前创建含 THREAD.md、来源队列、评估、提案、报告与只追加日志的运行目录structured-novelty-gateowning_skill: harness-engineering——起草或发布技能变更前用机制摘要、激活场景、行为变化、失败模式与注册表比对。机制晋升也有严格程序research_loop.py promote-mechanisms要求--reviewed-by人工署名、run readiness 必须先通过除非--allow-unready仅用于引导 fixtures、机制 ID 不得与注册表重复accepted/candidate 写ledgers/accepted.jsonlrejected 写ledgers/rejected.jsonlresearch_loop.py#L508-L572。治理Governance自主 Agent 可以准备 PR但治理必须显式。它们可以起草变更、运行检查、写 PR 摘要未经人工批准不得合并、部署或推送除非用户已明确授予特定动作的权限。本仓库的 governance 规则进一步细化researcher/README.md#L61-L67让 rubric 比输出更难修改——来源不能放松用于接纳自己的 rubric只引用已检索的来源抓取失败就记录失败而不作为证据引用来源质量与技能质量分离——强论文也可能产生不了可落地的技能增量优先更新现有技能而非新增除非激活场景、机制与操作流程确实不同证据零散、来源声明易变、或技能变更影响全仓指导时必须人工评审所有生成的技能变更对齐template/SKILL.md、500 行上限与 manifest 同步规则。详细主题Autoresearch 风格循环用于针对稳定评估器优化某个工件的场景read locked context - choose hypothesis - edit allowed surface - commit/checkpoint - run evaluator - log result - keep if better - discard or rollback if worse - repeat必备属性评估器位于可编辑表面之外反馈节奏固定足以比较不同尝试失败尝试留下审计轨迹回滚成本低Agent 有崩溃与超时策略Research-to-Skill 循环用于来源变成技能变更的场景discover - retrieve - gate - score - extract mechanism - map to existing or new skill - draft proposal - validate structure - prepare PR - human review锁定评估器是来源 rubric 技能变更 rubric 结构检查 评审人批准的组合可编辑工件是提案的技能增量skill delta。本仓库把这一模式固化为 researcher 操作系统的完整生命周期researcher/README.md#L17-L32discover - triage - evaluate - extract - map - draft - validate - prepare-pr - human-merge每个阶段有明确产出物来源候选 → 分类与排除检查 → 符合templates/source-evaluation.json的 JSON → 机制/工件/证据/失败模式 → 技能提案 → 常规仓库结构草稿 → rubric 分数加确定性检查 → PR 摘要/测试计划/未决评审意见。执行时通过research_loop.py的子命令逐步推进init→retrieve→evaluate→propose→novelty→validate-run→pr-ready→closeresearch_loop.py#L609-L693每个命令都会把状态迁移追加进 THREAD.md 与run-state.json。指标作弊抵抗Metric Gaming Resistance假设优化中的 Agent 会学会利用 harness。防护以下行为编辑评估代码或 rubric然后用新版本自我批准添加取悦评审但损害技能激活的冗余内容引用未检索的来源优化总分而关键维度不达标在日志中隐藏失败结果缓解措施按轮次锁定 rubric、报告分维度分数、要求来源检索证据、保留被拒尝试、把治理变更路由到人工评审。harness-change rubric 的 H2 门与五维评分表正是为此设计的researcher/rubrics/harness-change.md#L34-L44Feedback Quality25%、Search Discipline20%、Auditability20%、Safety and Governance20%、Cost Control15%各打 0/1/2 分总分 ≥ 1.5 且全部门通过才批准 harness 变更否则转人工。这是报告分维度分数而非总分在评分数学层面的强制。监控 Agent长任务中使用监控 Agent但除非明确授权只能做只读报告。监控输出应报告当前最佳候选活跃作业或草稿最近一次上游刷新失败或停滞的循环日志与声称状态之间的不一致下一步动作与阻塞项仓库在 researcher/runbooks/autonomous-research-loop.md 的 Handover 一节要求交接前更新当前最佳候选、已完成的评估及其文件路径、被拒候选及原因、未决风险、下一步动作——这等价于把监控 Agent 的只读报告落到文件层面保证压缩/中断/模型交接后依然可恢复。实操指南Harness 设计清单用一句话定义目标识别锁定、可编辑、只追加、人工控制四类表面选择反馈机制标量指标 / rubric / 确定性测试 / 人工评审 / 组合定义 keep、discard、crash、timeout、review 状态循环开始前创建持久化线程日志为长循环添加来源刷新、机制注册表新颖性、剪枝规则定义 Agent 无需询问即可做什么、什么必须审批用一个已知好工件和一个已知坏工件验证 harness仓库的 harness-change rubric 给出了配套的必做检查researcher/rubrics/harness-change.md#L46-L55新旧 harness 在同一已知工件上对比决策、确认更严的检查不阻挡显然有效的例子、更松的检查不放行已知坏例子、记录变更只影响未来提案还是会作废先前结果。文件布局research-run/ THREAD.md sources/ queue.md evaluations/ proposals/ logs/ results.tsv rejected.md drafts/机器可读的只追加日志用 TSV 或 JSONL交接与人读摘要用 Markdown。仓库实际运行目录与之一致例如种子运行researcher/runs/20260515-035228-executable-autonomous-research-frameworks/包含THREAD.md、sources/queue.jsonl、sources/evaluations/、sources/evidence/raw/、proposals/、reports/、run-state.json运行目录结构其中closure.json以reference-only状态关闭说明该运行作为自主循环生命周期的完整工作示例保留。可执行命令速查以下命令均可在仓库根目录运行详见 researcher/README.md#L69-L79# 确定性仓库校验结构、schema、行数上限、manifest 同步、rubric 数学 python researcher/scripts/validate_repo.py # 单个运行目录的发布就绪校验 python researcher/scripts/validate_run.py --run-dir researcher/runs/run-id # 初始化一个自主研究运行生成 THREAD.md、来源队列、评估与提案脚手架 python researcher/scripts/research_loop.py init --title Source title --url https://example.com/source # 新颖性门提案 vs 机制注册表 既有语料 python researcher/scripts/novelty_check.py --file researcher/fixtures/skill-proposals/harness-engineering-proposal.md # 成对技能修订的确定性预检 python researcher/scripts/compare_skill_revisions.py skills/evaluation/SKILL.md skills/advanced-evaluation/SKILL.md # 激活边界回归检查 python researcher/scripts/check_activation_cases.py # 确定性 benchmark 运行可选记录历史 python researcher/scripts/run_benchmarks.py注意research_loop.py本身不调用 LLM——它只创建可被自主 Agent 或人类填写的持久化工件然后运行确定性校验research_loop.py 文档字符串。这是确定性优先验证机制registry 中deterministic-first-validation的直接体现先用机器可查的结构/schema/检索状态检查再调用 LLM 评审。示例示例 1锁定指标Agent 优化train.py但prepare.py负责数据加载与评估。Agent 可以编辑模型但不能改动指标。失败的实验被记录并回滚。示例 2锁定 rubricAgent 评估一篇新的工程博文但来源策展 rubric 在本次运行中锁定。若来源通过Agent 起草技能提案它不能降低 rubric 阈值来接纳该来源。这正是 governance 规则第 1 条rubric 比输出更难修改的运作方式。示例 3自动 PR 但不自动合并Agent 在通过来源、技能与结构检查后准备分支与 PR 正文。PR 中写明未决风险等待人工合并审批。对应 runbook 的 PR 准备策略autonomous-research-loop.md#L56-L64内容与 rubric 通过、确定性检查通过、每个引用来源都被检索过、PR 正文包含未决风险、并声明合并需人工批准。十条指导原则循环开始前锁定评估器保持可编辑表面足够窄保证 diff 可靠在上下文压缩抹掉状态前写好持久化日志报告分维度分数而非只有总分引用前必须完成来源检索广域搜索加新颖性门复杂栈加剪枝门质量相同时优先简化PR 准备与合并权限分离用新旧评估器重新验证 harness 变更把停止的自主循环视为 harness 故障而非 Agent 的性格问题常见陷阱Gotchas可变评估器Agent 能改指标就会去优化 benchmark 而不是任务。运行期间锁定 rubric 与评估代码。仅聊天内存计划只存在于对话历史中压缩后长任务必失败。一开始就写线程日志与结果文件。无丢弃记录没有被拒尝试日志Agent 会重复失败想法。保留足够细节的失败记录以避免重复发现。复杂度堆积Agent 只会堆叠变更、很少删除。要求剪枝轮次奖励等质量简化。过早宣称新颖Agent 把重组当新颖。宣称前与既有技能、来源队列、被拒日志逐一对比。监控误报监控 Agent 可能总结过期或不一致状态。要求其引用结论背后的文件或日志。人工审批歧义准备 PR不等于合并 PR。在 harness 中显式划定审批边界。易变来源漂移实验室快节奏声明很快过时。在 references 中放带日期的证据并安排再验证。与仓库其他技能/系统的集成本技能在仓库中的落地不只是一份文档而是一个闭环系统评估面researcher/rubrics/下的 content-curation、skill-change、harness-change、pairwise-skill-revision 四份 rubric 构成锁定反馈面harness-change.md 专门评审研究循环/评估脚手架/操作流程/PR 自动化策略的变更并列出自我评分 harness 编辑、可变 benchmark、无丢弃路径、无剪枝轮、上游视图过期五大反模式运行编排autonomous-research-loop.md 定义了从 setup、loop、novelty/refresh、failure handling 到 PR 准备与交接的完整 runbook其中失败处理表来源抓取失败重试一次后记录 partial/failed、JSON 评估无效转人工、草稿超 500 行移入 references 或拒绝、manifest 同步不确定停止并请求人工直接落实了 harness 的 crash/timeout 策略提案格式skill-proposal.md 要求提案携带 Source / Mechanism / Skill Target / Novelty Check / Evidence / Proposed Delta / Quality Checks / Risks And Gaps / Recommendation 九个部分其中 Novelty Check 必须记录命令与 verdict、Evidence 只允许来自已检索来源——从文件格式层面堵住了引用未检索来源与过早新颖性声明两类陷阱。参考资源仓库内部参考均以仓库根目录为基准researcher/README.md —— 实现仓库原生的 research-to-skill 操作系统时阅读researcher/rubrics/harness-change.md —— 评审 Agent harness 变更时阅读researcher/runbooks/autonomous-research-loop.md —— 运行 source-to-skill 循环时阅读researcher/scripts/research_loop.py —— 运行目录脚手架与状态机的源码实现researcher/scripts/novelty_check.py —— 机制级新颖性门的源码实现researcher/mechanisms/registry.jsonl —— 已接受机制注册表含多条 harness-engineering 机制researcher/templates/research-thread.md —— 持久化线程日志模板researcher/templates/skill-proposal.md —— 技能增量提案模板外部参照行业背景非本仓库内容Karpathyautoresearch锁定评估的受限自主实验循环、Prime Intellect 自主 nanoGPT speedrun持久化草稿本、交接、监控与自主性失败模式、AlphaEvolve 与 FunSearchLLM 生成候选配系统化评估器、HELM 与 LM Evaluation Harness透明可复现的评估基础设施。元数据Created 2026-05-14 · Last Updated 2026-05-15 · Version 1.1.0来源SKILL.md 元数据。本文所有命令与路径均以当前仓库实际内容为准research_loop.py等脚本面向 Python 3 环境运行前请确认已安装requirements-dev.txt所列依赖。【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考