89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
# 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 回滚证据，必须明确说明。
|