sub2api-cn-relay-manager/AGENTS.md

sub2api-cn-relay-manager — Agent Guidelines

项目关键信息

• Go 1.22.2, 纯 Go (modernc.org/sqlite, 无 CGO)
• 零侵入宿主：不修改 sub2api 源码，不写宿主数据库
• 所有 schema 变更通过 internal/store/sqlite/ 下的 repo + integration test 验证
• docs/ 下有 PRD.md、TDD_PLAN.md、EXECUTION_BOARD.md、solution 文档

质量门禁（每个模块完成前必须执行）

1. 设计对齐 — 重新读取 PRD.md、TDD_PLAN.md、EXECUTION_BOARD.md、docs/plans/ 下的规划设计文档，逐条确认实现已覆盖设计目标。发现漂移先修正，不维持虚假 COMPLETED。
2. 前端门禁 — 任何触及 deploy/tksea-portal/、deploy/*portal*、/portal-admin-api/ 文案或前端验收文档的改动，必须至少执行：
   • bash ./scripts/test/test_tksea_portal_assets.sh
   • bash ./scripts/test/verify_frontend_smoke.sh
   • 若改动 providers.html 页面内显式动作，还必须执行 bash ./scripts/acceptance/verify_provider_admin_actions.sh 或给出不可执行原因。
3. 代码 review — 加载 go-reviewer skill，对新写/修改的全部 Go 文件做系统审查。
4. 测试覆盖 — go test -cover ./internal/... 核心包（provision、access、pack）覆盖率 >= 70%。未达标则补用例。
5. 静态分析 — go vet ./... 零警告。gofmt -l . 显示无未格式化文件。
6. 集成验证 — go test ./tests/integration/... -count=1 必须通过。
7. 板同步 — 更新 EXECUTION_BOARD.md，反映真实完成状态。

Go 编码规范

包结构

internal/
  access/       — 访问闭环（订阅分配、探测、自服务检查）
  app/          — HTTP 控制面（bootstrap, server, API handlers）
  host/sub2api/ — 宿主适配器
  pack/         — pack 装载与校验
  provision/    — 导入编排（import, preview, reconcile, rollback）
  store/sqlite/ — SQLite 数据访问层（repo 模式）
cmd/
  cli/          — CLI 入口
  server/       — HTTP server 入口
tests/integration/ — 集成测试套件

代码风格

• 标准 Go：4-space tabs, 花括号同行, 单 class/struct 文件
• 包名小写，与目录名一致
• 错误处理用 fmt.Errorf("context: %w", err) 包裹
• 常量分组在文件顶部，const ( Name = "value" )
• Repository 模式：type XRepo struct { db execQuerier } + newXRepo(db)
• Context 作为第一个参数传入所有 DB/SQL 操作
• 接口定义在使用方，不在实现方
• 测试用 fake/mock adapter 而非真实 HTTP

测试规范

• 文件名 *_test.go 与源码同包
• 方法名 TestXxxFlow / TestXxxWhenY 格式
• 优先使用 FakeHostAdapter（已在 provision 包中定义）而不是 mock 框架
• 集成测试放在 tests/integration/，使用真实 SQLite 内存库
• 测试函数必须 t.Parallel() 安全（使用独立 SQLite 连接）

重要约束

• 不要运行 go get / go mod tidy — 源码写完后告诉用户手动安装依赖
• 不改动 go.mod 中的依赖版本
• 所有功能必须配套测试，集成测试优先
• 不允许跳过 quality gate 中的任何一步