# AGENTS.md

本文件适用于整个仓库。

## 1. 项目目标

- 目标不是“看起来完成”，而是形成可验证、可审计、可上线的真实闭环。
- 任何“已完成”“已收口”“可上线”的表述，都必须以本地实际执行过的命令和证据为依据。

## 2. 真实边界

- 当前受支持的真实浏览器主验收路径是：
  - `cd frontend/admin && npm.cmd run e2e:full:win`
- 当前可诚实宣称的是“浏览器级真实 E2E 已闭环”，不是“完整 OS 级自动化已闭环”。
- `smoke` 脚本仅用于补充诊断，不能被当成产品运行时依赖，也不能被当成主验收结论。
- `agent-browser` 目前只能辅助观察和诊断，不能替代受支持的项目 E2E 主链路。

## 3. 运行时规则

- 禁止在非测试代码中保留 `panic` 作为常规失败路径。
- 禁止运行时使用 mock provider、fake success 或“假成功返回”掩盖真实依赖缺失。
- 邮件、短信、OAuth、文件上传、外部调用必须 fail closed，不能失败后伪装成功。
- 对外部副作用必须考虑回滚：
  - 文件写入失败要清理半成品
  - 持久化失败要回滚已创建的文件或缓存状态
- 安全敏感接口必须保持 `no-store` 等防缓存约束。
- 前端原生弹窗和弹出页视为缺陷信号：
  - `window.alert`
  - `window.confirm`
  - `window.prompt`
  - `window.open`

## 4. 设计规则

- 优先使用显式错误分类，不要依赖字符串子串猜测错误类型。
- service 层依赖接口能力，不依赖具体 repository 实现断言。
- 配置模板中的敏感值必须留空或使用占位说明，真实密钥只能通过环境变量或密钥管理系统注入。
- release 约束必须在启动期失败，而不是运行中放任危险配置继续启动。

## 5. 编码与编码问题

- 如果终端显示乱码，不要把终端渲染出来的中文直接复制回业务逻辑。
- 遇到编码不稳定场景时，优先使用：
  - ASCII 文本
  - `\uXXXX` 转义
  - 显式错误类型
- 如果局部补丁频繁被编码噪音阻断，优先整段或整文件重写，不要继续赌字符串匹配。

## 6. 最低验证矩阵

- 只改后端时，至少执行：
  - `go test ./... -count=1`
  - `go vet ./...`
  - `go build ./cmd/server`
- 改前端时，至少执行：
  - `cd frontend/admin && npm.cmd run lint`
  - `cd frontend/admin && npm.cmd run build`
- 只要改动涉及以下任一类，就必须补真实浏览器回归：
  - 认证
  - 会话
  - 路由守卫
  - 导航
  - 弹窗保护
  - 用户主流程
  - `window` 相关防线
  - 影响登录页或后台主导航的改动
  - 命令：`cd frontend/admin && npm.cmd run e2e:full:win`

## 7. 文档同步规则

- 改变真实结论时，必须同步更新：
  - `docs/status/REAL_PROJECT_STATUS.md`
- 沉淀长期工程约束时，优先更新：
  - `docs/team/QUALITY_STANDARD.md`
  - `docs/team/PRODUCTION_CHECKLIST.md`
  - `docs/team/TECHNICAL_GUIDE.md`
- 形成阶段性经验总结时，沉淀到：
  - `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`

## 8. 对外表述规则

- 允许说：
  - “浏览器级真实 E2E 已闭环”
  - “本地可审计的一轮治理证据已形成”
- 不允许夸大成：
  - “完整 OS 级自动化已闭环”
  - “全部企业级生产治理材料都已闭环”
- 若仍缺少真实第三方 OAuth live 验证、外部 Secrets/KMS、多环境交付证据或 schema downgrade 回滚证据，必须明确说明。