企业官网建设流程全解析

Agent-Skills-for-Context-Engineering：AGENTS.md 作为 Agent 工作区记忆的持久化工程范式

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

本篇以仓库根目录的 AGENTS.md 为核心，讲解它如何被设计为"Agent 工作区记忆"（workspace memory）：三条结构（学习到的用户偏好、学习到的工作区事实、仓库操作默认值）分别承载什么信息、为什么这样分层，以及这些记忆条目如何与researcher/目录下的确定性脚本、CI 门禁和 launchd 持续循环一一对应、形成可验证的落地机制。读完后你能掌握：如何为协作 Agent 编写不腐化的持久记忆文件，如何用状态机、只读表面（locked surfaces）和基准测试让记忆中的每一条操作规范都有代码级依据。

一、什么是"工作区记忆"：AGENTS.md 的定位

AGENTS.md 的第一句话定义了它的职责边界：

Workspace memory for agents collaborating on this repository. Keep entries durable and broadly applicable; one-off task state belongs in chat or in a run thread, not here.

也就是说，这个文件不是给人看的 README，而是写给后续接手仓库的 Agent 的"长期记忆"。它有一条明确的准入标准：条目必须持久（durable）且广泛适用（broadly applicable）；一次性的任务状态应该留在聊天记录或某个 run 的线程文件里，而不是写进这个文件。这条规则直接决定了文件的结构：全文只有三个小节，分别对应三种不同半衰期的"知识"。

这种分层与仓库自身的运行机制是自洽的。仓库是"研究到技能"（research-to-skill）的自主组织，外部研究经过评分标准（rubrics）蒸馏后更新为上下文工程与 harness 工程技能；按次运行的状态存放在researcher/runs/<run-id>/run-state.json中，而 researcher/README.md 明确说明该目录"刻意做成基于文件的（file-based），这样 Agent 可以在没有托管调度器的情况下检查、恢复和审计工作"。AGENTS.md 存跨 run 的共识，run-state.json存单次 run 的状态，THREAD.md 存单次 run 的决策流水，三层各管各的，互不污染。

二、三条分层结构：偏好、事实、操作默认值

2.1 Learned User Preferences：把"人的口味"固化为 Agent 约束

第一条偏好条目要求自主研究类工作"在范围清晰时通过具体研究循环、子 Agent、验证与编辑推进，而不是提出宽泛的流程问题"；语气条目要求"技术型 CTO 风格：直接、无营销语言、无感叹号、无 emoji、无 em dash，先陈述取舍与复杂度"。这类条目看似主观，但它解决的是 Agent 协作中最常见的摩擦：每个新 Agent 都要重新试探用户的沟通边界。把试探结果写回 AGENTS.md，后续 Agent 直接继承。

另一条值得注意的偏好是："技能与脚本中避免过时的正则或关键词列表启发式；优先采用机制级判据、评分标准和有证据支撑的验证"。这条偏好不是口号，仓库的校验脚本本身就是按这个标准写的：researcher/scripts/validate_repo.py 与 researcher/scripts/validate_platform_compat.py 走的是结构化检查（frontmatter 解析、manifest 同步、行上限），而不是"文件名里必须包含某关键词"之类的脆弱匹配。

2.2 Learned Workspace Facts：每个事实条目都指向可查证的仓库位置

第二节是全文信息密度最高的部分。它的写法有一个可复用的特点：每条事实都绑定一个具体文件路径或命令，使"记忆"可以被随时回查证伪。逐条对应如下：

• 按次运行状态机：researcher/runs/<run-id>/run-state.json记录状态，且明确规定"用research_loop.py的子命令推进状态，绝不手改 run-state.json"。从源码结构看，researcher/scripts/research_loop.py 的set_state()（第 110-122 行）是唯一的状态写入路径：更新current_state、向state_history追加带时间戳和证据的记录、写回 JSON，并同步向THREAD.md追加一条决策。子命令层面，retrieve/evaluate/propose/novelty/validate-run/pr-ready/close分别驱动状态迁移；close只接受accepted、rejected、reference-only、abandoned四种状态（VALID_CLOSE_STATUS，第 33 行）。
• 两级校验是不同问题：仓库健康（validate_repo.py）和单次 run 的就绪度（validate_run.py）被明确区分为"不同的问题"，对应源码中run_validator()与run_run_validator()两个独立函数，各自生成独立的报告文件（validation-report.*与run-readiness.*）。
• 机制注册表是"百科主干"：researcher/mechanisms/registry.jsonl的晋升必须经research_loop.py promote-mechanisms且记录审查人，台账（accepted/rejected）落在researcher/mechanisms/ledgers/。源码中promote_mechanisms()（第 508-572 行）强制执行这一点：缺少--reviewed-by直接抛错；accepted/candidate机制在 run 就绪度未通过时拒绝晋升（除非显式--allow-unready，注释标明"仅用于引导期 fixtures"）；重复mechanism_id直接报错。
• 声明溯源：任何数字型或易变声明（数值、基准结果）必须在researcher/claims/index.jsonl登记溯源；语料地图在researcher/corpus/index.json。
• 持续循环的成本边界：researcher/scripts/loop_*.py由 launchd 驱动，"从不调用付费 LLM；HTTP 抓取只用标准库，1.5 MB 上限、30 秒超时"。与 researcher/orchestration/launchd/run-loop-step.sh 一致：守护进程只跑loop_step.py --allow-fetch --json（stdlib HTTP，无付费 API），且文档注明--allow-fetch可移除以退化为纯记账模式。
• 运行时状态不入库：.gitignore实际规则与文档逐条对应，见下文第五节。种子 run20260515-035228-executable-autonomous-research-frameworks是唯一被提交的 run，closure.json 显示其关闭状态为reference-only、审查人release-team，作用是"可运行的完整示例（worked example）"。
• 版本一致性：发布版本 2.5.0 同时出现在 .claude-plugin/marketplace.json、.plugin/plugin.json 与根 SKILL.md 三处，当前发布 17 个技能目录。
• 基准分阶段：Stage 0 确定性 harness（已交付）、Stage 1 逐技能健康度（skill_health.py）、Stage 2 路由器（已交付，结果发布在researcher/benchmarks/router/results-published/）、Stage 3 有效性（脚手架就绪，已完成一个任务）、Stage 4 组合（规划中），方法论单一事实源是 researcher/benchmarks/PLAN.md。
• 语料加固基线与 SDK 运行器：当前基线为 16 个已接受机制、12 条带溯源声明、19 个激活用例、严格技能健康分 0.9117 且 0 个被标记技能；且规定"除非文案、机制注册表、声明索引、语料索引、激活 fixtures 与校验器全部一致，不得把一次技能改进描述为完成"。基准执行用researcher/benchmarks/sdk-runner/（TypeScript，Cursor SDK 1.0.13），支持--concurrency N、--no-resume、逐 run 进度日志、格式失败重试与最坏情况成本预估；已发布的 Stage 2 结果在 2026-05-19.md：600/600 可用记录、0 格式失败，top-1 Gemini 0.920 / Composer 0.913 / GPT-5.5 0.913 / Claude Opus 4.7 0.840；定向改写使context-fundamentalstop-1 提升 +23.4pp、project-developmenttop-1 到 1.000。

需要说明适用前提：以上基线数字是 AGENTS.md 在 2.5.0 发布点的快照，属于"易变声明"，仓库约定其权威溯源在researcher/claims/index.jsonl，读者引用时应以该索引和最新发布文档为准，而不是以本文转述为准。

2.3 Repository Operating Defaults：操作默认值即防呆设计

第三节列出 9 条操作默认值。它们与第二节不同，不是"这个仓库是什么"，而是"在这个仓库里做事时必须遵守什么"。挑几条有源码支撑的展开。

先确定性检查，后模型裁判。任何技能格式或打包变更声明完成前，必须先跑validate_platform_compat.py --require-reference-validator和validate_repo.py --strict。CI 工作流 .github/workflows/validate.yml 把这条默认值变成了硬性门禁：在pull_request与push到 main 时依次执行全部 researcher 脚本的py_compile、frontmatter 解析器单元测试、平台兼容性校验、validate_repo.py --strict、skill_health.py --strict --no-history、check_activation_cases.py与run_benchmarks.py，整条流水线超时 5 分钟。

原子写与文件锁。凡循环触碰的共享文件，必须原子写（tempfile+os.replace）并加fcntl锁。researcher/scripts/loop_common.py 完整实现了这两条：_atomic_write()（第 47-65 行）用tempfile.mkstemp在同目录建临时文件、写盘、fsync后再os.replace原子替换，失败时清理临时文件；queue_lock()（第 123-142 行）用fcntl.flock排它锁，按队列文件族一把锁，防止loop_step与loop_discover并发抢改 inbox 或 parked 队列。容错层面，read_jsonl()对坏行不是崩溃，而是隔离到researcher/reports/jsonl-quarantine/（gitignored）并继续。

付费 API 的三件套约束。任何在循环里调付费 API 的 runner，执行前必须具备：--concurrency有界并行、基于结果目录扫描的断点续跑、以及能暴露单次调用内部卡顿的逐 run 进度日志。researcher/benchmarks/sdk-runner/src/common.ts 中可以看到前两条的实现：参数解析支持--dry-run、--no-resume、--max-runs、--max-budget-usd、--concurrency；并且拒绝在无成本上限时运行（"Refusing to run without a cost cap"），--dry-run可打印执行计划与成本预估而零 API 调用。这与 AGENTS.md 中"成本门禁必须在任何 SDK 调用之前设置"一一对应。

技能是"多表面产物"。只改 frontmatter 的description不算完成：SKILL.md 正文的When to Activate与Integration小节必须在同一天审计，否则正文会与路由它的 description 矛盾。这条默认值点出了一个真实的测量盲区：路由器基准只看到 description（settingSources: []），测不到正文不一致；只有真正加载技能正文的 Stage 3 有效性基准才能度量正文对齐的影响。

密钥即视为泄露。聊天中提供的 API key 用后必须立即轮换；runner 侧通过apiKeyFingerprint()只记录 key 的最后 4 位来配合这一策略（见 common.ts 第 208 行起的导出函数）。

三、状态机实践：种子 run 的完整生命周期

AGENTS.md 要求"用子命令推进状态，绝不手改 run-state.json"。仓库里唯一提交的种子 run 给出了这条规则的标准答案，可以直接当教程读。

run 目录 researcher/runs/20260515-035228-executable-autonomous-research-frameworks/ 的结构由research_loop.py init一次性生成（create_run()，第 575-606 行）：sources/（含queue.jsonl、evaluations/、evidence/raw/）、proposals/、reports/、logs/，外加THREAD.md、run-state.json、从模板填充的source-evaluation-draft.json和skill-proposal.md。目录名本身是时间戳-slug格式（slugify()截断到 64 字符）。

run-state.json的关键字段值得逐一看：

• current_state/close_status/close_reason：当前状态与关闭语义；
• locked_surfaces：本 run 不可触碰的表面，包括三份 rubric、机制注册表、两处 manifest（.claude-plugin/marketplace.json、.plugin/plugin.json）和validate_repo.py本身。设计意图很清楚：被评分的对象不能修改评分标准，这对应 researcher/README.md 治理规则第 1 条"rubric 必须比产出物更难被改"；
• editable_surfaces：只有本 run 自己的sources/、proposals/、reports/、logs/；
• state_history：每次迁移都追加state / timestamp / reason / evidence四元组，形成不可删改的审计轨迹。

关闭语义也有讲究。该 run 的 closure.json 记录status: reference-only，理由写明：它的原始证据和 THREAD.md 留作自主循环生命周期的完整示例，而技能变更本身早已发布，不会再从这个 run 派生 PR。也就是说reference-only与accepted/rejected是两个维度的关闭：前者回答"这个 run 是否完成使命"，后者才回答"产物是否被采纳"。

机制晋升的门禁流程可以在promote-mechanisms子命令中完整复现：读取proposals/mechanism-proposal.jsonl，逐条检查mechanism_id非占位符、先跑validate_run.py确认 run 就绪（除非--allow-unready）、检查注册表去重，然后把注册表条目追加到registry.jsonl、事件追加到 accepted 或 rejected 台账，最后把 run 状态迁到validated（有晋升）或closed（全被拒）。整个过程没有任何人工判断入口被绕过：审查人以--reviewed-by参数显式记录。

四、持续循环：launchd 编排与零付费默认

AGENTS.md 声明持续循环"从不调用付费 LLM"。编排层落在 researcher/orchestration/launchd/：三个 plist（loop-step、loop-discover、loop-daily）配合install.sh/uninstall.sh安装到 macOS launchd，三个run-loop-*.sh包装脚本把输出重定向到researcher/reports/logs/。

researcher/orchestration/config.json 给出了循环的全部预算与节律，这是 AGENTS.md 未逐字展开、但读源码时应补上的参数面：

• mode: "dry-run"，配置注释明确 HTTP 抓取由loop_step的--allow-fetch开关控制；
• budgets：最多 3 个活跃 run、每天最多新建 6 个 run、最多 12 个 parked、每天最多 5 次失败、inbox 上限 200；
• intervals：loop_step 每 10 分钟、loop_discover 每 12 小时、loop_daily 在 UTC 6 点；
• human_review：判定为HUMAN_REVIEW/REJECT或新颖度检查为human_review/likely_duplicate的 run 自动 park 到researcher/reports/parked-review.md等待人工；
• limits：每轮 discover 最多新增 8 个候选、loop_step每轮最多推进 1 个状态。

从源码结构看，researcher/scripts/loop_discover.py 的默认数据源只有researcher/discovery/manual-seed.jsonl；enable_parallel_deep_research与enable_web_search两个 feed 即使被打开，当前也只打印"未实现适配器、跳过"的提示。去重逻辑（existing_urls()）覆盖 inbox、quarantine 以及所有活跃/已关闭 run 的 source URL。run-loop-step.sh 的注释还解释了一个运维细节：loop_step在无工作时以退出码 78 结束，属正常现象，不能中断随后的状态刷新。

五、运行时状态与仓库卫生：gitignore 即契约

AGENTS.md 把"什么进版本库、什么不进"写成显式事实条目，而 .gitignore 中第 49-75 行提供了逐条对应的实际规则：

这里唯一提交进版本库的 run 就是文档所称的"唯一已提交 run"，gitignore 中的例外规则（!行）是这条记忆的直接代码证据。这个设计使仓库同时满足两个矛盾需求：Agent 本地跑循环产生的大量中间态不污染历史，同时保留一个经过审计、可复现的参考 run 供新 Agent 学习完整生命周期。

六、如何复现与核验：命令清单

以下命令均可在仓库根目录直接执行，来自 AGENTS.md、researcher/README.md 与源码 argparse 定义，构成该工作区记忆的"可操作接口"：

# 仓库健康（PR 门禁同款） python researcher/scripts/validate_platform_compat.py --require-reference-validator python researcher/scripts/validate_repo.py --strict python researcher/scripts/skill_health.py --strict --no-history python researcher/scripts/check_activation_cases.py python researcher/scripts/run_benchmarks.py # 创建一次研究 run（生成目录、THREAD.md、run-state.json、评估与提案草稿） python researcher/scripts/research_loop.py init --title "Source title" --url "https://example.com/source" # 推进状态（子命令：retrieve / evaluate / propose / novelty / validate-run / pr-ready / close / promote-mechanisms） python researcher/scripts/research_loop.py retrieve --run-dir researcher/runs/<run-id> --file ./evidence.md python researcher/scripts/research_loop.py novelty --run-dir researcher/runs/<run-id> python researcher/scripts/research_loop.py close --run-dir researcher/runs/<run-id> --status reference-only --reason "..." # 机制晋升（需审查人） python researcher/scripts/research_loop.py promote-mechanisms --run-dir researcher/runs/<run-id> --reviewed-by <name> # 单次 run 就绪度 python researcher/scripts/validate_run.py --run-dir researcher/runs/<run-id> --json # 新颖度与技能修订预检 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 # 持续循环（本地模拟 launchd；exit 78 表示无工作，属正常） python researcher/scripts/loop_discover.py --json python researcher/scripts/loop_step.py --allow-fetch --json python researcher/scripts/loop_status.py --json # SDK 基准运行器（成本门禁先于调用；--dry-run 零 API 调用） # 见 researcher/benchmarks/sdk-runner/src/common.ts 参数解析： # --concurrency N / --no-resume / --max-runs / --max-budget-usd / --dry-run

七、可借鉴的三条设计原则

1. 记忆条目必须可回查。AGENTS.md 中每条"工作区事实"都绑定文件路径或命令，新 Agent 接手时不需要信任记忆本身，只需要跑一遍对应的校验器。这把"文档漂移"问题转化为"校验失败"问题，而后者 CI 会替它发现。
2. 状态推进必须经过唯一入口。run-state.json不允许手改，set_state()是唯一的写路径且自动留痕；promote-mechanisms必须带审查人且前置 run 就绪检查。凡是"Agent 可能绕过"的地方都设了代码级栅栏，而不是依赖提示词自觉。
3. 成本与安全边界写进默认值而非文档。无成本上限拒绝运行、API key 指纹化、循环默认零付费 LLM、坏行隔离而非崩溃，这些默认值使"安全运行"不依赖操作者记住清单。对任何要托管自主 Agent 的仓库，AGENTS.md 加上这套researcher/scripts/的确定性校验骨架，是一个可以直接照搬的最小参考实现。

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