📄 为项目命令补充条件式环境恢复指引

[cyfung1031]

Checklist / 检查清单

• Fixes mentioned issues / 修复已提及的问题
• Code reviewed by human / 代码通过人工检查
• Changes tested / 已完成测试

背景

AI 编码代理在执行项目命令时，不应因为本地依赖或 Playwright 浏览器缺失就直接把任务报告为环境阻塞；同时也不应让正常、稳定环境长期加载一整段一次性恢复说明。

本次改动

• 先将 PR 分支同步到最新 main（b75124c0c450d73a90347f0ac555f66238d5b1af）。
• 在 AGENTS.md 的 Before you… 路由表中保留一个轻量入口：运行项目命令前读取 docs/develop.md。
• 在 docs/develop.md 的现有 Commands 旁增加一段条件式规则：只有命令因本地 prerequisite 缺失而失败时才恢复环境并重试原命令。
• Node 依赖缺失使用 pnpm install；Playwright Chromium 缺失使用 pnpm run test:e2e:install；pnpm 本身缺失时在 Corepack 可用的情况下启用仓库声明的 pnpm。
• 如果恢复失败或导致 tracked files 变化，则报告 blocker/mismatch；不切换 package manager，也不把环境恢复产生的变更提交进功能改动。

范围

最终 diff 仅修改 AGENTS.md 和 docs/develop.md，共新增 7 行；不修改产品代码、依赖声明、lockfile 或测试实现。

验证

• 重新读取当前 main，确认 base SHA 为 b75124c0c450d73a90347f0ac555f66238d5b1af。
• 静态检查 GitHub 最终 PR diff：只有一行项目命令路由和一段条件式恢复规则，没有 recovery-specific 路由、独立恢复章节或额外格式改动。
• 本轮未执行测试或项目命令。

[CodFrm]

这种一次性的，并且AI也懂的，就不加入来浪费上下文了吧

[cyfung1031]

这种一次性的，并且AI也懂的，就不加入来浪费上下文了吧

就是我发现Agent不懂执行 docs/develop.md 里的指令
你只列出来，没有跟Agent说明什么时候用
它就不会调用

所以要在 Before you… 那里连结一下，再在 docs/develop.md 里写清楚，它就知道要怎样处理
不然一直都是「这个环境没有 node_modules ，所以我很诚实告诉你我没有跑测试」

[CodFrm]

这种一次性的，并且AI也懂的，就不加入来浪费上下文了吧

就是我发现Agent不懂执行 docs/develop.md 里的指令 你只列出来，没有跟Agent说明什么时候用 它就不会调用

所以要在 Before you… 那里连结一下，再在 docs/develop.md 里写清楚，它就知道要怎样处理 不然一直都是「这个环境没有 node_modules ，所以我很诚实告诉你我没有跑测试」

我没有遇到过，而且一般情况下，不会没有node_modules吧，就算有，跑一次就好了，不用加入上下文

[cyfung1031]

已重新处理这一轮：先把分支同步到当前最新 main (b75124c0c450d73a90347f0ac555f66238d5b1af)，再基于最新文档结构补回原始需求。

这次不再只解决上下文大小问题，而是同时保留「异常环境下要先恢复再重试」的行为：AGENTS.md 只增加 run project commands → docs/develop.md 的轻量路由；具体恢复逻辑放在 docs/develop.md Commands 旁，并且只在命令因本地 prerequisite 缺失而失败时触发。Node 依赖缺失用 pnpm install，Playwright Chromium 缺失用 pnpm run test:e2e:install，pnpm 缺失时在 Corepack 可用时启用仓库声明的 pnpm；恢复失败或产生 tracked-file mismatch 才报告 blocker，不切换 package manager，也不提交环境恢复产生的文件变化。

已重新检查当前 PR 的 base-to-head diff：最终只有上述 1 行路由 + 1 段条件式恢复规则，没有独立 recovery section、recovery-specific 路由或额外格式改动。本轮按原约定只做静态检查，没有执行测试/项目命令。