# AGENTS.md

本文件适用于整个仓库。

## 1. 项目目标

- 目标不是"看起来完成"，而是形成可验证、可审计、可上线的真实闭环。
- 任何"已完成""已收口""可上线"的表述，都必须以本地实际执行过的命令和证据为依据。
- 迭代速度优先，但速度不牺牲质量：快速验证、快速反馈、快速修正。

## 2. Gitea 协作规则

### 2.1 分支策略

- `main` 分支：始终可构建、可测试通过，是唯一的发布基线。
- `feature/<简短描述>`：功能分支，每个独立功能一个分支。
- `fix/<简短描述>`：修复分支，每个独立修复一个分支。
- 禁止直接推送到 `main`，所有变更必须通过 PR 合并。

### 2.2 PR 规范

- 每个 PR 只包含一个逻辑变更。
- PR 描述必须包含：
  - 变更目的（1-2 句）
  - 验证命令及结果
  - 影响范围（后端/前端/文档）
- PR 合并前必须通过最低验证矩阵（见第 6 节）。

### 2.3 提交规范

- 提交信息格式：`类型: 简短描述`
  - 类型：`feat`、`fix`、`test`、`docs`、`refactor`、`chore`
- 每次提交应该是可独立验证的最小单元。

## 3. 多智能体并行工作流

### 3.1 任务拆分原则

- 每个任务必须是独立的、可并行执行的单元。
- 任务之间如果有依赖，必须明确标注依赖关系和执行顺序。
- 前后端分离的任务优先并行执行。

### 3.2 并行执行模式

- **方案对比阶段**：多个智能体并行输出不同方案，由决策者选择最优解。
- **实现阶段**：无依赖的任务并行执行，有依赖的任务按拓扑序执行。
- **验证阶段**：后端测试、前端 lint/build、E2E 测试并行执行。

### 3.3 智能体分工

- **规划智能体**：负责任务拆分、依赖分析、方案对比。
- **实现智能体**：负责编码，每个智能体负责一个独立任务。
- **验证智能体**：负责测试执行、结果验证、报告生成。
- **审查智能体**：负责代码审查、安全审查、性能审查。

### 3.4 冲突解决

- 多个智能体修改同一文件时，必须在任务拆分阶段识别并协调。
- 如果发生合并冲突，优先保留功能完整的版本，手动合并差异。

## 4. 方案对比机制

### 4.1 何时需要方案对比

- 新增核心功能或架构变更时。
- 存在多种可行实现路径时。
- 性能优化涉及重大权衡时。

### 4.2 对比维度

- 实现复杂度（人天/智能体时）
- 性能影响
- 可维护性
- 与现有架构的兼容性
- 测试难度

### 4.3 决策记录

- 选定的方案必须记录决策原因。
- 被否决的方案必须记录否决原因。
- 决策记录写入 PR 描述或 `docs/decisions/` 目录。

## 5. 测试全面性要求

### 5.1 测试层级

- **单元测试**：每个函数/方法必须有对应的单元测试。
- **集成测试**：跨模块交互必须有集成测试。
- **E2E 测试**：用户主流程必须有真实浏览器 E2E 测试。

### 5.2 测试覆盖要求

- 新增代码必须有对应测试。
- 修复 bug 必须有回归测试。
- 安全敏感代码必须有边界条件测试。

### 5.3 测试执行策略

- 本地开发：运行受影响的最小测试集。
- PR 提交前：运行完整测试矩阵。
- 合并后：运行完整 E2E 验证。

### 5.4 防虚假测试规则

- 禁止使用 mock 响应替代真实 API 调用进行 E2E 验证。
- 禁止在测试中硬编码预期结果而不走真实业务链路。
- 禁止跳过认证、权限校验等安全环节直接断言页面状态。
- 禁止在测试中使用 `context.Background()` 绕过上下文治理。
- E2E 测试必须：
  - 启动真实后端进程（隔离测试数据库）
  - 启动真实前端开发服务器
  - 通过真实浏览器（CDP 协议）执行用户操作
  - 验证真实 API 响应（非 mock）
  - 验证真实数据库状态变化
- 当前项目的真实 E2E 路径：
  - Playwright CDP E2E：`cd frontend/admin && npm.cmd run e2e:full:win`
  - 覆盖场景：管理员引导、注册、邮箱激活、登录、认证工作流、响应式布局、桌面/移动端导航
- 未来增强方向：
  - 引入 `agent-browser`（bb browse）等浏览器自动化工具，补充 Playwright 未覆盖的交互场景
  - 增加复杂业务流程的端到端验证（如设备信任、批量操作、系统设置等）

## 6. 真实边界

- 当前受支持的真实浏览器主验收路径是：
  - `cd frontend/admin && npm.cmd run e2e:full:win`
- 当前可诚实宣称的是"浏览器级真实 E2E 已闭环"，不是"完整 OS 级自动化已闭环"。
- `smoke` 脚本仅用于补充诊断，不能被当成产品运行时依赖，也不能被当成主验收结论。
- `agent-browser` 目前只能辅助观察和诊断，不能替代受支持的项目 E2E 主链路。
- 当前 E2E 覆盖场景：
  - 管理员引导（admin-bootstrap）
  - 公开注册（public-registration）
  - 邮箱激活（email-activation）
  - 登录表面验证（login-surface）
  - 认证工作流（auth-workflow）
  - 响应式登录（responsive-login）
  - 桌面/移动端导航（desktop-mobile-navigation）
- E2E 测试架构：
  - Playwright CDP 协议连接真实浏览器
  - 隔离测试数据库（临时 SQLite 文件）
  - 本地 SMTP 捕获服务（验证邮件发送）
  - 信号收集器（console errors、dialogs、popups、request failures、401 responses）
  - 多视口验证（desktop 1440x960、tablet 820x1180、mobile 390x844）

## 7. 运行时规则

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

## 8. 设计规则

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

## 9. 编码与编码问题

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

## 10. 最低验证矩阵

- 只改后端时，至少执行：
  - `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`

## 11. 文档同步规则

- 改变真实结论时，必须同步更新：
  - `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`
- 新增架构决策时，写入：
  - `docs/decisions/` 目录

## 12. 对外表述规则

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

## 13. 快速迭代规则

### 13.1 迭代节奏

- 小步快跑：每个迭代周期不超过 2 小时。
- 持续验证：每个迭代完成后立即执行验证矩阵。
- 快速回滚：如果验证失败，立即回滚到上一个可用状态。

### 13.2 阻塞处理

- 遇到阻塞时，立即记录阻塞原因和影响范围。
- 优先寻找替代方案，而不是等待阻塞解除。
- 阻塞超过 30 分钟必须上报并寻求协助。

### 13.3 知识沉淀

- 每次解决的问题必须记录解决方案。
- 每次踩过的坑必须记录避免方法。
- 每次验证通过的命令必须记录执行结果。

## 14. 项目目录规范

### 14.1 目录结构

详见 `docs/PROJECT_STRUCTURE.md`，核心规范：

| 目录 | 用途 | 注意事项 |
|------|------|----------|
| `bin/` | 编译产物（二进制） | 禁止提交 |
| `cmd/` | 应用入口 | 每个应用一个子目录 |
| `internal/` | 私有内部包 | 不可被外部导入 |
| `pkg/` | 公共外部包 | 仅当需要作为独立库发布时使用 |
| `scripts/` | 脚本 | 按 dev/deploy/ops/test 分类 |
| `tools/` | 工具脚本 | Python/Shell 工具 |
| `configs/` | 配置文件 | JSON/YAML/TOML |
| `deployment/` | 部署配置 | Docker/K8s/Compose |
| `docs/` | 项目文档 | 分类管理 |
| `data/` | 运行时数据 | SQLite数据库等 |
| `logs/` | 日志输出 | |
| `uploads/` | 用户上传 | |

### 14.2 禁止在根目录放置

- ❌ 编译产物（*.exe, *.dll → bin/）
- ❌ 临时测试输出（*_result.txt, *_test.txt → 删除）
- ❌ 运行时日志（*.log → logs/）
- ❌ 环境配置文件（.env → 不提交）

### 14.3 新增目录检查

添加新目录前，确认：
1. 是否有必要？能用现有目录表达吗？
2. 符合命名规范？小写字母、中划线分隔
3. 放置位置正确？对应到规范中的位置
4. 是否需要版本控制？data/logs/uploads 通常不提交

### 14.4 文件命名规范

- Go源文件：`snake_case.go`
- 测试文件：`*_test.go`
- 配置文件：`snake_case.json/yaml/toml`
- 脚本文件：`snake_case.sh/ps1/py`
- Markdown：`kebab-case.md` 或 `snake_case.md`