user-system/AGENTS.md

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 回滚证据，必须明确说明。