long-agent/user-system
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6b2b450e917d430115792dc26232ca0203baae8b
user-system/AGENTS.md
long-agent 5b6bd93179 refactor: 整理项目根目录结构 
整理内容:
- 删除 60+ 临时测试输出文件 (*.txt)
- 移动二进制文件到 bin/ 目录
- 移动 Shell 脚本到 scripts/ 目录
  - scripts/dev/: check_gitea.sh, check_sub2api.sh, run_tests.sh
  - scripts/deploy/: deploy_*.sh, simple_deploy.sh
  - scripts/ops/: fix_nginx.sh, fix_ssl.sh, install_docker.sh
  - scripts/test/: test_*.sh, test_*.bat
- 移动批处理文件到 scripts/
- 移动 Python 脚本到 tools/
- 清理临时日志文件

保留根目录必要文件:
- go.mod, go.sum, go.work
- Makefile, docker-compose.yml
- .env.example, .gitignore
- README.md, AGENTS.md, DEPLOY_GUIDE.md

验证: go build ./... && go test ./... 通过
2026-04-07 18:10:36 +08:00

8.8 KiB
Raw Blame History

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 知识沉淀

  • 每次解决的问题必须记录解决方案。
  • 每次踩过的坑必须记录避免方法。
  • 每次验证通过的命令必须记录执行结果。
Reference in New Issue View Git Blame Copy Permalink