long-agent
2ae146a0b9
新增第14节：项目目录规范 - 目录结构速查表 - 禁止在根目录放置的文件类型 - 新增目录检查清单 - 文件命名规范 配合 docs/PROJECT_STRUCTURE.md 使用
281 lines
10 KiB
Markdown
281 lines
10 KiB
Markdown
# 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`
|