user-system/AGENTS.md

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