初始化脚本 — 一次性支付启动税

每个冷启动的会话都支付一笔税。Agent读取相同文件，重试相同探测，重新发现相同路径。初始化脚本支付一次税并将答案写入状态。

类型： 构建 语言： Python（标准库） 前置条件： Phase 14 · 32（最小工作台），Phase 14 · 34（仓库记忆） 时间： ~45分钟

学习目标

• 识别Agent永远不应该每个会话重做的工作。
• 构建探测运行时、依赖和仓库健康的确定性初始化脚本。
• 持久化探测结果，使Agent读取它而不是重新运行检查。
• 初始化失败时快速、大声地失败，在一个地方查找。

问题所在

打开一个会话。Agent猜测Python版本。猜测测试命令。列出仓库根目录五次以找到入口点。尝试导入未安装的包。问用户配置文件在哪里。等到它做出真正编辑时，一万个token已经用于应该是单个脚本的设置工作。

修复是一个初始化脚本，在Agent做任何其他事情之前运行并写入 init_report.json，Agent在启动时读取。

核心概念

初始化脚本探测什么

快速失败，大声失败，在一个地方失败

探测失败意味着停止并向人类展示。没有”Agent会搞定的”。初始化的全部意义是在工作台损坏时拒绝启动。

幂等

连续运行两次。第二次运行应该是空操作，除了新的时间戳。幂等性让你可以将脚本连接到CI、钩子或任务前斜杠命令。

初始化 vs 启动规则

规则（Phase 14 · 33）描述了行动前必须为真的条件。初始化是建立这些规则可以被检查的脚本。没有初始化的规则变成”小心”。没有规则的初始化变成一个精致的失败。

生产模式

• 最后已知良好提交锚定。 将当前提交与上次成功合并写入的 LKG 文件进行探测。如果diff超过预算（默认50个文件），拒绝启动并要求人类批准新基线。
• 带TTL的锁文件。 在首次成功探测通过后写入 prereqs.lock。后续运行信任锁N小时（默认24小时）并跳过昂贵探测。
• 热路径中无网络、无LLM、无惊喜。 初始化探测是确定性管道。调用LLM分类失败或命中外部服务检查许可证的探测不是探测；它是工作流。

实践

code/main.py实现 init_agent.py：五个探测（Python版本、依赖可用性、测试命令可解析性、必需环境变量、状态文件新鲜度），每个返回 (name, status, detail)，写入 init_report.json，在任何阻止级探测失败时以非零退出。

交付

outputs/skill-init-script.md访谈项目，将设置工作分类为探测，并发出项目特定的 init_agent.py 加上在任何Agent步骤之前运行它的CI工作流。

练习

1. 添加一个探测，将当前提交与最后已知良好提交进行diff，如果超过50个文件变更则拒绝启动。
2. 将脚本连接到写入 prereqs.lock 文件，如果锁超过七天则拒绝启动。
3. 添加 --fix 标志，自动安装缺少的开发依赖但永远不修改运行时依赖。
4. 将探测从硬编码函数移动到YAML注册表。辩护权衡。
5. 为每个探测添加时间预算。运行超过三秒的探测是工作台异味。

关键术语

延伸阅读

• Anthropic, Effective harnesses for long-running agents
• Augment Code, How to Build Your AGENTS.md