env-doctor

env-doctor — 执行环境诊断与修复

运行不变量

• 幂等的本地边界：严格将修复限制在项目范围内的操作（声明的依赖同步、本地服务启动、测试数据存储迁移、合成测试密钥）；禁止系统范围的修改（sudo、brew）、篡改主机 PATH 或获取远程密钥。遇到端口冲突、缺少守护进程或破坏性操作时，停止并返回 UNRESOLVED。
• 零密钥暴露：绝不检查或复制生产密钥文件（.env*，.env.example 除外）；向 .env.test 或环境存根注入确定性模拟值。
• 以清单 SSOT 为准：将 .agents/environment.md 作为权威规范。对于可省略的部分（纯库的服务、外部数据存储），若不存在则视为 PASS。
• 自适应调用输出：由人类调用时，输出完整的规范输出契约；由自主运行器调用时，仅输出单行微摘要标记（READY 或 UNRESOLVED: <blocker>）。

领域准则

1. 维度审计与探测规范

将声明的清单与主机运行时和执行封装器（pnpm、cargo、uv）交叉核对。执行已声明的服务就绪探测（套接字、HTTP /healthz、数据库 ping），并采用指数退避（最长 15s）；禁止将进程状态（Up）视为就绪。验证测试数据存储迁移、测试夹具和合成 .env.test 存根。

规范输出契约

# Environment Health Report: <Scope> · <READY | STAGED | UNRESOLVED>

Basis: .agents/environment.md

| Dimension | Declared / Target | Active / Detected | State |
| :--- | :--- | :--- | :--- |
| **Toolchain** | <Target runtime version> | <Active version / wrapper> | <PASS | FAIL> |
| **Services** | <Declared services or N/A> | <Probe outcome or Standalone>| <PASS | FAIL> |
| **Datastore** | <Target test datastore> | <Migration & seed status> | <PASS | FAIL> |
| **Test Stubs** | <Test env / secrets> | <Stubs presence (.env.test)> | <PASS | FAIL> |

*(omit if clean)* ## Applied Remediation
- **[<Auto | Staged>] <Action>**: <Command and outcome or pending approval>

*(omit if READY)* Gap: <Root cause blocker and required human action.>

自主微标记契约：

READY | runtime: <version> | services: <healthy|standalone> | fixtures: verified

（失败时，输出 UNRESOLVED: <single-sentence blocker>）。

路由

• 环境为 READY，继续进行任务分解 →（通过 /split-tasks）。
• 环境为 READY，继续进行代码实现 →（通过 /forge）。
• 环境为 READY，继续进行根因诊断 →（通过 /diagnose）。
• 缺少服务架构，需要做出设计决策 →（通过 /architect-decision）。

执行协议

1. 阅读 .agents/environment.md，并探测已声明的主机工具、运行时、服务和测试夹具。若全部通过，则直接返回 READY。
2. 执行安全的自动修复（启动已声明的服务、同步依赖、运行测试数据存储迁移/测试夹具）。重新探测健康状态；报告 READY，若遇到阻碍则停止本轮并返回 UNRESOLVED。