pi-autoresearch .auto/会话文件体系完整指南：让实验跨越重启与上下文重置存活的5个文件-酒店常州论坛

pi-autoresearch .auto/会话文件体系完整指南：让实验跨越重启与上下文重置存活的5个文件

【免费下载链接】pi-autoresearchAutonomous experiment loop extension for pi项目地址: https://gitcode.com/gh_mirrors/pi/pi-autoresearch

pi-autoresearch 是 pi（终端 AI 编程代理）的自主实验循环扩展：代理会自动"提出想法 → 运行基准测试 → 保留改进、回滚退步 → 无限循环"。它能否长时间无人值守运行的关键，就是工作目录下那个不起眼的.auto/文件夹——一套会话文件体系。所有实验状态都落盘在这个目录里，即使终端重启、会话中断，甚至 AI 的上下文被压缩重置，新代理读一遍这些文件就能接着上次继续跑。

为什么需要 .auto/ 会话文件？

AI 代理有两个"健忘"时刻：

重启——进程退出后，内存里的所有对话记录消失
上下文重置——对话过长时，pi 的自动压缩机制会摘要掉旧对话，细节丢失

如果实验进度只存在于对话里，这两次"失忆"都会让数小时的优化工作归零。pi-autoresearch 的解法很直接：把状态全部写进.auto/这一个文件夹（路径约定见 extensions/pi-autoresearch/paths.ts）。一个文件夹的好处是：实验回滚不会误伤它、gitignore 一行搞定、清理时一删了之。

会话文件全家福

文件	状态	作用
`.auto/prompt.md`	必需	会话说明书：目标、指标、范围、已试想法
`.auto/measure.sh`	必需	基准测试脚本，输出`METRIC 名称=数值`
`.auto/log.jsonl`	工具维护	只追加的实验日志，一次运行一行
`.auto/ideas.md`	可选	想法积压清单
`.auto/checks.sh`	可选	正确性检查（测试、类型、lint）

详细说明见 site/content/configuration.md。

文件一：prompt.md —— 新代理的"重生说明书"

prompt.md是整个会话的心脏。官方要求：一个没有任何记忆的新代理，只读这个文件就能有效跑起循环。它包含：

优化目标与基准命令
主指标与次级监控指标
可修改的文件范围与"禁区"
硬约束（测试必须通过、不加新依赖等）
"What's Been Tried"（已试过什么）——记录关键胜利、架构洞察和被放弃的想法及失败原因

最后一点至关重要：被放弃（discard）的想法代码会被回滚，唯一幸存的记录就在这里。代理会定期更新这一节，所以几天后重新恢复会话时，"哪些路走不通"这类知识依然健在。文件模板见 skills/autoresearch-create/SKILL.md。

文件二：measure.sh —— 每次循环的标尺

基准测试脚本，用set -euo pipefail编写，职责是：快速预检（语法错误 1 秒内暴露）、运行工作负载、向标准输出打印METRIC 名称=数值结构化行，run_experiment工具会自动解析。

两个实用技巧：

快速且噪声大的基准（<5 秒）：脚本内部多次运行并取中位数，让置信度分数从一开始就可信
脚本可以在循环中升级——发现新的瓶颈信号（分阶段耗时、内存、缓存命中率）就补上

文件三：log.jsonl —— 只追加的实验账本

每次运行的结果（指标、状态、提交哈希、描述、代理标注）由工具自动追加到.auto/log.jsonl，一次运行一行。会话运行中请勿手工编辑。

它是"跨越重启存活"的直接功臣：

重启后：代理读这个文件即可恢复完整历史
人类可读：随时打开查看全程
分支感知：每个分支各有自己的会话
finalize 的原料：/autoresearch finalize会把保留下来的实验按逻辑分组、拆成可独立评审的分支

文件四：ideas.md —— 好想法的暂存区

发现"很有希望但太复杂、现在追会分心"的优化时，代理会把它追加为.auto/ideas.md里的一条要点，避免好想法在漫长循环里丢失。

恢复会话时（上下文耗尽、崩溃、重启），代理会先检查这个清单：删掉已试过的、对剩余想法继续实验。等所有路径都穷尽，代理才删除该文件并写总结。

文件五：checks.sh —— 防止"优化出 bug"的背压阀

可选的正确性检查脚本，典型内容是pnpm test --run+pnpm typecheck。它只在基准测试通过之后自动运行：

检查耗时不计入主指标
检查失败 → 实验记为checks_failed，不能keep，改动自动回滚
默认 300 秒超时，输出只回传最后 80 行，保持上下文精简

没有这个文件时循环行为完全不变——需要时才加。

可选增强：config.json 与 hooks/

.auto/config.json：workingDir（把实验操作指向另一个目录）和maxIterations（限制单段实验次数，控制 token 成本）
.auto/hooks/before.sh/after.sh：在每次迭代前后触发的脚本，标准输入是 JSON 会话快照，标准输出会作为"引导消息"喂给代理。仓库自带 10 个参考脚本（外部搜索、防空转、想法轮转、学习日志、macOS 通知等），见 skills/autoresearch-hooks/examples/

会话重置时到底发生了什么？

pi 的自动压缩触发后，pi-autoresearch 不会依赖"压缩摘要里碰巧剩下的东西"。它会用磁盘上的持久化状态直接合成一份无损摘要——会话目标、实验规则（prompt.md全文）、想法清单、最近 50 次运行，然后立即继续循环，整个摘要过程甚至跳过 LLM 调用。实现见 extensions/pi-autoresearch/compaction.ts。配合自动恢复守卫（连续失败自动停、恢复轮数上限），无人值守跑几小时也能安全收敛。

上手三步

pi install npm:pi-autoresearch pi

在 pi 里输入：

/autoresearch optimize unit test runtime, monitor correctness

autoresearch-create技能会问你目标、命令、指标、文件范围（或自行推断），然后创建分支、写入.auto/prompt.md和.auto/measure.sh、跑基线、直接开跑。若.auto/prompt.md已存在，同一命令就是恢复会话，你输入的文字作为额外上下文。

想离线研究源码，可克隆仓库：git clone https://gitcode.com/gh_mirrors/pi/pi-autoresearch。

企业官网建设流程全解析