可执行自治研究循环实战：以 Agent-Skills-for-Context-Engineering 的 THREAD.md 工作流为蓝本

可执行自治研究循环实战：以 Agent-Skills-for-Context-Engineering 的 THREAD.md 工作流为蓝本

【免费下载链接】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

导读

本文以仓库中一次真实研究运行（20260515-035228-executable-autonomous-research-frameworks）的THREAD.md为核心，完整拆解"可执行自治研究框架"从初始化、检索、评估、提案到关闭的生命周期。你将掌握如何用文件即状态（file-based state）组织一个不依赖 LLM 即可运行的自治研究循环，理解锁定面（Locked Surfaces）与可编辑面（Editable Surfaces）的边界设计，并学会通过research_loop.py的十余个 CLI 子命令驱动研究到技能提案的流水线。

一次研究运行的解剖：THREAD.md 是什么

在researcher/runs/20260515-035228-executable-autonomous-research-frameworks/这个运行目录中，THREAD.md 是该研究运行的中枢文档。它的设计目标是：即使运行被中断、模型被替换、上下文被压缩，任何后继 Agent 或人类只凭这份文件就能完整恢复运行状态。这正是runbook中"Handover"（交接）要求的物化形态。

一份规范的 THREAD.md 至少包含以下区块：

本次运行的 Mission 是"Executable autonomous research frameworks"（可执行自治研究框架），由autonomous-research-loop于 2026-05-15T03:52:28+00:00 启动，评估候选源并产出可评审的技能提案。run-state.json中的记录显示，该运行最终以closed+reference-only状态收尾，其原始证据与 THREAD.md 被保留为自治循环生命周期的"工作示例"（worked example）。

边界设计：Locked Surfaces 与 Editable Surfaces

THREAD.md 中最关键的设计是明确划分"谁可以改、谁不能动"。本次运行声明了 7 项锁定面：

• researcher/rubrics/content-curation.md
• researcher/rubrics/skill-change.md
• researcher/rubrics/harness-change.md
• researcher/mechanisms/registry.jsonl
• .claude-plugin/marketplace.json
• .plugin/plugin.json
• researcher/scripts/validate_repo.py
• 合并策略：Agent 可以准备 PR，但 push 与 merge 必须由人类批准

这一设计在源码中有直接印证：research_loop.py 中硬编码了LOCKED_SURFACES列表，任何init新运行都会自动继承这份边界清单；run-state.json 则把锁定面与可编辑面一并持久化。

可编辑面被限定在运行目录内部：

• .../sources/（原始证据、摘要、评估草稿）
• .../proposals/（技能提案与机制提案）
• .../reports/（验证报告与关闭报告）

这种"评审面冻结、产物面开放"的结构，从机制上杜绝了运行过程中私自篡改评分规则或注册表的风险——评分时改规则、发现重复后悄悄改注册表，都会破坏整个研究的可信度。

状态机驱动：run-state.json 与 research_loop.py

THREAD.md 之外，运行目录还维护着机器可读的状态文件run-state.json。本次运行的完整状态历史为：

1. initialized（T+00:00）：research_loop.py init创建运行目录与持久化状态；
2. retrieved（T+04:12）：原始 deep research 证据落入sources/evidence/raw/；
3. closed（T+05:19:20）：以reference-only理由关闭，证据指向reports/closure.json。

状态流转由 research_loop.py 的 CLI 子命令强制驱动，全部为确定性操作（不调用 LLM）：

# 初始化一次研究运行（创建运行目录、run-state.json、队列等） python researcher/scripts/research_loop.py init --title "..." --url "..." # 记录已检索的源证据 python researcher/scripts/research_loop.py retrieve --run-dir <run> ... # 标记运行已完成源评估 python researcher/scripts/research_loop.py evaluate --run-dir <run> # 标记运行已产出提案 python researcher/scripts/research_loop.py propose --run-dir <run> # 运行新颖性检查并持久化结果 python researcher/scripts/research_loop.py novelty --run-dir <run> # 验证运行是否达到可发布状态 python researcher/scripts/research_loop.py validate-run --run-dir <run> # 写入 PR 就绪说明 python researcher/scripts/research_loop.py pr-ready --run-dir <run> # 以 accepted / rejected / reference-only / abandoned 之一关闭运行 python researcher/scripts/research_loop.py close --run-dir <run> --status reference-only --reason "..." # 运行通过后，将已评审的机制提案提升进注册表 python researcher/scripts/research_loop.py promote-mechanisms --run-dir <run>

关闭状态枚举{accepted, rejected, reference-only, abandoned}同样在 research_loop.py 中做了常量约束。这套"命令驱动状态机"的价值在于：任何一步都可以被验证、被重放，运行不会因为"只写在对话里"而丢失进度。从提案的 mechanism-proposal.jsonl 中可以看到，本次运行还沉淀出一条候选机制researcher-run-state-machine——"研究到技能循环需要可强制执行的显式状态流转，而非仅仅靠文字日志"，这正指向该状态机设计本身。

源队列：一次一个候选源，记录状态与下一步

THREAD.md 的 Source Queue 表格记录了本次运行的唯一候选源 S001：

机器可读版本存在于 queue.jsonl，字段包括id、url、title、author_or_org、source_type、retrieval_status（本次为partial）与candidate_reason。

值得注意：队列中retrieval_status是partial而非completed。runbook autonomous-research-loop.md 明确规定："Fetch primary sources whenever available and record them withresearch_loop.py retrieve"、"Record retrieval status before evaluating"。先记录检索状态、再进入评估是硬性纪律——未经检索的源不得被引用为证据，提案模板中甚至专门声明"Only include evidence from retrieved sources. If a source was discovered but not fetched, record it under gaps instead of citing it."

决策日志：带证据的不可变记录

THREAD.md 的 Decisions 区块用带时间戳的代码块记录关键决策，本次运行有三条：

T+00:00 decision: run initialized reason: file-based research loop created durable state evidence: researcher/runs/20260515-035228-executable-autonomous-research-frameworks next: fill source evaluation and skill proposal T+05:16 decision: deep research result captured reason: Parallel returned implementable framework patterns for deterministic validation, durable scratchpads, novelty gates, pairwise skill evaluation, and auto-PR governance evidence: sources/evidence/deep-research-summary.md next: implement novelty and pairwise revision gates in a later loop 2026-05-15T05:19:20+00:00 decision: closed as reference-only reason: Seed run captured the deep-research evidence that bootstrapped the harness-engineering skill, the mechanism registry, and the researcher OS. ... evidence: researcher/runs/.../reports/closure.json next: stop run

每条决策都遵循同一模式：时间 + 决策 + 原因 + 证据路径 + 下一步。这使整条运行历史可以被审计、被追溯，也恰好呼应了 THREAD.md 自身的交接要求——"Files to read first:THREAD.md,sources/evidence/deep-research-summary.md,reports/validation-report.md"。关闭决策的机器可读版本在 closure.json，由release-team评审，状态为reference-only。

评估与实验：rubric 门控下的证据捕获

Experiments And Evaluations 表格记录了实验 E001：

评估产物 source-evaluation-draft.json 展示了评分脚手架的结构：先过门禁（Gatekeeper），再行维度打分，最后给决策。门禁来自 content-curation.md 的四个关卡：

任一门禁失败即REJECT并停止。全部通过后进入四维打分：D1 技术深度与可执行性（权重 35%）、D2 仓库相关性（30%）、D3 证据严谨度（20%）、D4 新颖性与洞察（15%），加权公式为weighted_total = D1*0.35 + D2*0.30 + D3*0.20 + D4*0.15。>= 1.4判APPROVE，0.9 ~ 1.4判HUMAN_REVIEW，低于 0.9 或任何门禁失败判REJECT；另有四条强制覆写规则（如 D1=0 或 D2=0 直接 REJECT）。

本运行的评估草稿当前是HUMAN_REVIEW状态，justification明确写着 "Draft scaffold. Complete gates and scoring after retrieval."——即在检索完成前，评估只允许是草稿，这展示了评估管道的诚实性约束：宁可不打分，也不要在证据不足时假装通过。

证据摘要：五个可落地的框架模式

本次运行捕获的核心证据是 deep-research-summary.md，它把 Parallel deep research 的结果收敛为五个可落地模式，这些模式与仓库现有实现一一对应：

1. 确定性验证优先（Deterministic validation first）：在引入模型评判门禁之前，先冻结仓库结构检查与 schema 验证——对应validate_repo.py与验证报告"0 errors, 0 warnings"的确定性输出；
2. 持久化运行目录（Durable run directories）：每个研究循环都应创建含THREAD.md、源队列、评估、提案、报告、日志的目录——正是本运行目录的结构；
3. 新颖性门禁（Novelty gate）：起草前将拟议技能增量与已接受机制、既有技能、fixtures 与已拒绝想法比较——对应novelty_check.py与机制注册表；
4. 成对修订（Pairwise revisions）：两份技能草稿竞争时，用同一 rubric、同一源证据评估，并以简洁性作为平局决胜——对应compare_skill_revisions.py与pairwise-skill-revision.md；
5. 人类控制的合并（Human-controlled merge）：Agent 可在检查通过后准备 PR 内容，但合并权保留在自治循环之外。

摘要还列出了候选后续变更，其中"机制注册表"与"成对技能修订脚本"这两项已在当前仓库落地，验证了"研究 → 提案 → 落地"的闭环确实发生。原始证据 JSON 保存在sources/evidence/raw/下，遵守 runbook 的硬性要求：原始源导出只存运行目录，绝不放到仓库根目录。

提案与新颖性检查：从证据到技能变更

运行目录中的 skill-proposal.md 是模板化的提案骨架，包含 Source（源信息与检索状态）、Mechanism（3-6 句机制描述）、Skill Target、Novelty Check、Evidence 表格、Proposed Delta（YAML 变更清单）、Quality Checks（8 项勾选）、Risks And Gaps、Recommendation 等区块。Recommendation 必须是五个值之一：publish-new-skill/update-existing-skill/add-reference-only/human-review/reject。

新颖性检查的推荐命令为：

python researcher/scripts/novelty_check.py --file \ researcher/runs/20260515-035228-executable-autonomous-research-frameworks/proposals/skill-proposal.md \ --json

runbook 强调：起草新技能前必须对照已接受机制与既有技能边界，用novelty_check.py做快速机制重叠门禁，再用人类或 LLM 判断语义新颖性；机制注册表重叠是主要的重复信号。同时，一个提案若新增多条规则或概念，必须做"修剪"（pruning pass）——删除任何不改变行为的条目。本运行的机制提案 mechanism-proposal.jsonl 记录了researcher-run-state-machine机制，其activation_scenario、behavior_change、failure_modes（如"未完成的运行看起来可发布""丢失转移历史""无证据的 PR 就绪"）、evidence_claim_ids与status_recommendation: candidate字段构成了机制注册的完整要素。

关闭与交接：reference-only 的正确姿势

本次运行的最终关闭理由值得完整引述：

Seed run captured the deep-research evidence that bootstrapped the harness-engineering skill, the mechanism registry, and the researcher OS. Closed as reference-only: its raw evidence and THREAD.md remain as a worked example of the autonomous-loop lifecycle. The skill change itself was already published; no further PR derives from this run.

这段文字说明了三个要点：一是该运行作为"种子运行"（seed run）已经完成了它的使命（把 deep-research 证据转化为技能与注册表）；二是虽然不再派生新 PR，其原始证据与 THREAD.md 作为生命周期的工作示例保留；三是关闭前验证已通过——validation-report.md 显示 "Validation passed: 0 errors, 0 warnings"，JSON 版记录skill_count: 14、findings: []。

Handover Summary 则是关闭前一刻的运行快照：

• 最佳候选：确定性验证 + 持久化运行目录
• 被拒候选：暂无
• 未决风险：源评估在 rubric 字段补全前仍是草稿
• 优先阅读文件：THREAD.md、deep-research-summary.md、validation-report.md
• 下一步动作：在后续循环中实现新颖性与成对修订门禁

完整的自治循环：从 runbook 到日常操作

将上述机制串联起来，就得到 autonomous-research-loop.md 定义的完整循环：初始化 → 读源注册表选源类 → 读机制注册表 → 读 rubric → 声明锁定面/可编辑面 → 循环（发现 → 检索 → 记录状态 → 应用 content-curation rubric → 立即拒绝失败源 → 提取机制 → 应用 skill/harness rubric → 起草提案 → 新颖性检查 → 成对修订 → 准备仓库变更 → 确定性验证 → 准备 PR 但不得合并）→ 关闭运行。

runbook 还提供了失败处理表，是运行中最实用的决策速查：

PR 准备政策同样严格：只有内容与技能/框架 rubric 通过、确定性检查通过、变更中引用的每个源都已检索、PR 正文包含未决风险、且 PR 声明合并需人工批准，Agent 才可准备 PR。runbook 最后重申硬约束："do not push anything to GitHub without explicit approval."

结语：把研究循环当作可验证的工程系统

从这份 THREAD.md 中可以看到一个核心理念：自治研究不是"让模型自由探索"，而是一个由文件、命令、rubric 与状态机共同约束的工程系统。锁定面守住评审纪律，可编辑面提供创作空间，决策日志保证可审计，状态机保证可恢复，rubric 门禁保证证据质量，人类合并权保证最终控制权。对于任何希望建设"研究 → 提案 → 技能发布"流水线的团队，researcher/runs/下的这份运行记录与 autonomous-research-loop.md 运行手册，是一份可以直接照抄、复用的工作蓝本。

【免费下载链接】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