Stev_Wang
75cedbe97b
原 GIT-05 要求 subject 用英文祈使句，与团队实际书写习惯不符（已有提交均为 中文），且缺少中英混排与术语约定，容易写出 Chinglish、自造术语或中英标点混乱。 本次改动： - GIT-05 改为「提交信息一律使用中文」，type / scope 保留英文小写，规定祈使句、 字数（≤50 汉字 / 整行 ≤72 字符）与不加句末标点； - 新增 GIT-21~GIT-23：中英文间加空格、使用全角标点与反引号、术语沿用 PRD 术语表、 禁止 Chinglish 与无信息缩写； - 新增 §2.2 commitlint 配置要点：中文必须关闭 subject-case、拦截中文句号， 否则钩子校验实际无效； - 同步 03（commit-msg 钩子说明）、07（PR-01 标题用中文）与 AGENTS §7 / §9 / 附录。 影响面：仅文档，无代码影响。新规则对后续提交生效，已推送的历史提交不改写 （GIT-15 禁止改写 main 历史）。 回滚方式：git revert 本提交。
216 lines
14 KiB
Markdown
216 lines
14 KiB
Markdown
# AGENTS.md · 灵犀项目整体规范
|
||
|
||
> 本文件是本仓库的**唯一总纲**，面向所有研发与 AI 编程助手（Claude Code / Cursor / Codex / Copilot 等）。
|
||
> 只写**硬约束与索引**，细则一律见 [`docs/工程规范/`](docs/工程规范/README.md)，本文不重复展开。
|
||
|
||
| 项 | 内容 |
|
||
| --- | --- |
|
||
| 适用对象 | 前端 / 后端 / 测试 / 运维 / AI 工程 / 产品（技术边界） |
|
||
| 适用产物 | 代码、配置、脚本、迁移、文档、Prompts |
|
||
| 文档版本 | V1.0（2026-11-02） |
|
||
| 事实基线 | PRD `V1.6`、技术架构 `V0.4` |
|
||
|
||
---
|
||
|
||
## 0 效力与冲突处理
|
||
|
||
1. **优先级（高 → 低）**：现行 PRD → 技术架构 → 工程规范 → 本文示例 → 个人偏好。
|
||
2. 规范与实现冲突时：**先改文档，再改代码**；禁止"代码先行、文档后补"。
|
||
3. 本文与细则冲突：以细则为准；细则未覆盖：以技术架构为准。
|
||
4. 文档未定义且影响面大于单个模块的决策，**必须提 ADR**（`docs/adr/ADR-xxx-标题.md`）评审后再写代码。
|
||
5. 无法确认的业务口径：标 `【待确认 Q-xx】` 并停下，**禁止猜测**（Q 编号见 PRD 第 10 章）。
|
||
|
||
---
|
||
|
||
## 1 项目边界（一句话）
|
||
|
||
灵犀 = 信息流广告素材生产平台：**行业包 → 要素卡 → 脚本 → 素材（图片确定性合成 / 视频逐镜生成）→ 快筛 → 导出即归档**。
|
||
内核不分行业，行业差异用「行业包 + schema」表达，**禁止写成代码分支**。
|
||
|
||
**本期不做**（越界即评审驳回）：通用视频剪辑器、投放执行、效果归因、客户自助登录、计费结算、图片线 AI 生图（M5 前）、通用低代码/审批引擎、模型训练微调。
|
||
|
||
---
|
||
|
||
## 2 文档基线（唯一事实来源）
|
||
|
||
| 文档 | 路径 | 版本 | 作用 |
|
||
| --- | --- | --- | --- |
|
||
| PRD | `docs/PRD/灵犀-信息流广告素材一站式生产平台PRD.md` | V1.6 | 需求、业务规则（R-01~R-30）唯一来源 |
|
||
| 技术架构 | `docs/技术架构/灵犀_信息流素材生产平台_技术架构_V0.1.md` | V0.4 | 技术选型、模块、数据、接口唯一来源 |
|
||
| 立项建议 | `docs/立项建议/灵犀_信息流素材生产平台_立项建议书_V0.1.md` | V0.1 | 论证背景，**不约束实现** |
|
||
| 工程规范 | `docs/工程规范/` | — | 落地细则（本文件的下游） |
|
||
| 参考项目 | `项目参考/`、`sucaigongfang` | — | 仅查阅，**不入库、禁止复制业务代码** |
|
||
|
||
- 新增技术选型 / 架构变更，必须先更新技术架构并评审，**禁止在代码里"先试再说"**。
|
||
- 引用业务规则时写编号（如 `// R-04 客户数据隔离`），便于反查。
|
||
|
||
---
|
||
|
||
## 3 硬红线（违反即打回，不接受"下个版本再改"）
|
||
|
||
1. **包管理只用 pnpm 10**，Node 锁定 `24.15.0`（`.nvmrc`）；禁 npm / yarn / bun，禁 `npm link`，内部包用 `workspace:*`。
|
||
2. **全栈 TypeScript strict**；禁 `any`（用 `unknown` + 收窄），禁用 `as` 绕过类型检查。
|
||
3. **UI 只用 `@douyinfe/semi-ui-19`**；图标只用 Remix Icon 且只能从 `packages/ui/icons.ts` 按语义名导入。禁混装其他组件库/图标库，禁业务代码内联 SVG（品牌 Logo 除外）。
|
||
4. **模块化单体**：模块间只走 Service 接口或领域事件；**禁止跨模块 `prisma.*`**；`identity` / `client` 是被依赖方，不得反向依赖。
|
||
5. 任何数据访问必须携带 **`ScopeContext`**，查询必须带 `customer_id`；**禁止"先查全量再过滤"**。
|
||
6. **出网 AI 调用唯一入口 `platform.ai`**；业务模块不得直连任何模型 SDK。
|
||
7. **图片线只做确定性合成**（PSD 套版 + 抠图 + 合成）；**禁止**在图片线接入文生图 / 图生图（PRD R-29）。
|
||
8. **迁移一律 expand → migrate → contract**；禁止同一次发布内"删字段 + 改代码"。
|
||
9. **密钥 / Token 不入库、不写日志、不进前端 bundle**，只从环境变量读。
|
||
10. **审计表 append-only（仅 INSERT）**；导出全留痕（PRD R-05）。
|
||
11. **阈值 / 上限类数字只存系统配置一处**（PRD R-26）；禁前后端硬编码。
|
||
12. **低质量产出必须显式打标**（`low_quality` + 原因码），不得按成功静默交付（PRD R-30）。
|
||
13. 任务提交必须带 **`Idempotency-Key`**；产物一律短时效签名 URL，**不塞进 JSON**。
|
||
14. **被引用的资产只能停用、不能删除**（PRD R-02）；已入库资产修改须**新版本 + 重新审核**（R-03）。
|
||
|
||
---
|
||
|
||
## 4 技术栈基线（版本以技术架构 §2.10 为准）
|
||
|
||
| 层 | 选型 |
|
||
| --- | --- |
|
||
| 运行时 | Node.js `24.15.0` · pnpm `10.x` · TypeScript `5.7+` |
|
||
| 前端 | React `19` · Vite `6` · React Router `7` · TanStack Query `5` · Zustand `5` · Tiptap · dnd-kit · ECharts `5` · HLS.js（P2） |
|
||
| UI | Semi Design `2.x`（`@douyinfe/semi-ui-19`）· Remix Icon `4.x` |
|
||
| 后端 | NestJS `11` + Fastify · Prisma `6` · Zod（静态 DTO）+ Ajv（动态 schema） |
|
||
| 数据 | PostgreSQL `18` · Redis `7.4` + BullMQ `5` · MinIO（S3 协议） |
|
||
| 媒体 | ffmpeg `7` · sharp `0.33+` · `@napi-rs/canvas` · `ag-psd` · ONNX 抠图 |
|
||
| 质量 | Vitest · Testcontainers · Playwright · k6 · oasdiff |
|
||
| 观测 | Pino · OpenTelemetry |
|
||
|
||
> 版本升级单独 PR + 修订记录，**禁止顺手升级**。新增运行时依赖需在 PR 说明必要性（影响面 + 替代方案）。
|
||
|
||
---
|
||
|
||
## 5 仓库结构（目标态；当前仅 `docs/`）
|
||
|
||
```
|
||
apps/api NestJS HTTP + SSE + AI 回调
|
||
apps/worker 同一镜像，按 QUEUE 环境变量启动
|
||
apps/web React SPA
|
||
packages/shared 领域事件、错误码、权限点常量、Zod schema、ULID、命名工具
|
||
packages/form-engine 受控 schema 表单渲染器（14 类字段白名单）
|
||
packages/render PSD 解析 / 抠图 / 合成 / 编码
|
||
packages/ai-sdk Provider 适配器、路由、限流、记账
|
||
packages/ui Semi 二次封装 + Remix 图标统一出口 + locale
|
||
prisma/ schema.prisma 与 migrations/
|
||
infra/ compose、Nginx、监控、备份
|
||
docs/ PRD / 技术架构 / 立项建议 / 工程规范
|
||
```
|
||
|
||
- **依赖方向**：`apps → packages`；`packages` 单向；`shared` 不依赖任何包；**禁止循环依赖**。
|
||
- 工作区包 scope 统一 `@lingxi/*`（`@lingxi/shared`、`@lingxi/ui`、`@lingxi/render`…），保持私有、不发布公网。
|
||
- 后端 8 模块：`identity` `client` `catalog` `industry` `script` `media` `delivery` `platform`。
|
||
- 新目录 / 新包必须先评审，**禁止在 `apps/web` 内私建"共享"目录**充当包。
|
||
|
||
---
|
||
|
||
## 6 命令契约（建仓后必须与下表一致）
|
||
|
||
| 场景 | 命令 |
|
||
| --- | --- |
|
||
| 依赖启动 | `pnpm compose:up` / `pnpm compose:down` |
|
||
| 开发 | `pnpm dev` |
|
||
| 构建 | `pnpm build` |
|
||
| 质量 | `pnpm lint` · `pnpm lint:fix` · `pnpm format` · `pnpm format:check` · `pnpm typecheck` |
|
||
| 测试 | `pnpm test` · `pnpm test:int` · `pnpm test:e2e` |
|
||
| 数据库 | `pnpm db:migrate` · `pnpm db:reset`（禁止 `docker compose down -v`） |
|
||
| 契约 | `pnpm openapi:diff` |
|
||
|
||
> 文档、脚本、CI 中出现的命令必须与上表一致，禁止自造别名。
|
||
|
||
---
|
||
|
||
## 7 变更流程（提测 / 合并前必须全绿）
|
||
|
||
1. 从 `main` 拉短分支 → 小步提交（**Conventional Commits，提交信息与 PR 标题一律用中文**，`type` / `scope` 保留英文）。
|
||
2. 本地门禁：`pnpm lint && pnpm typecheck && pnpm test`。
|
||
3. PR 描述必含：**背景 / 改动 / 影响面 / 回滚方式 / 验证证据**；迁移、权限、AI、导出类变更须**双人 Review**。
|
||
4. CI 全绿 + Review 通过 → **Squash Merge**；禁止 force push `main`。
|
||
5. 发布：staging 验证 → 生产灰度；**迁移先行、代码后行**。
|
||
|
||
细则：[Git 规范](docs/工程规范/01-Git规范.md) · [Code Review 与 PR](docs/工程规范/07-CodeReview与PR规范.md) · [测试与 CI](docs/工程规范/06-测试与CI规范.md)
|
||
|
||
---
|
||
|
||
## 8 文档规范（摘要）
|
||
|
||
- 文档与代码**同 PR** 更新；只改文档也要走 PR。
|
||
- 新业务规则先进 PRD 并编号（`R-xx`），再进代码。
|
||
- 文档版本 `V<主>.<次>`：主版本 = 业务口径不兼容；次版本 = 增量补充。
|
||
- 索引三处必须同步：根 `README.md`、`docs/工程规范/README.md`、本文件 §9。
|
||
- 命名沿用 `灵犀_<主题>_<类型>_V<版本>.md`；**新建文档**必须遵循，历史文件保持原名并登记。
|
||
|
||
---
|
||
|
||
## 9 细则索引
|
||
|
||
| 主题 | 文档 | 一句话 |
|
||
| --- | --- | --- |
|
||
| Git / 分支 / 提交 | [01-Git规范](docs/工程规范/01-Git规范.md) | 主干 + 短分支，Conventional Commits（**提交信息用中文**），Squash 合并 |
|
||
| 代码风格 | [02-代码风格](docs/工程规范/02-代码风格.md) | 命名、类型、错误处理、异步、React 约定 |
|
||
| 格式化与 Lint | [03-格式化与Lint](docs/工程规范/03-格式化与Lint.md) | Prettier + ESLint 9 flat，钩子与 CI 门禁 |
|
||
| API 与路由 | [04-API与路由规范](docs/工程规范/04-API与路由规范.md) | REST /api/v1、错误码、鉴权链、任务协议 |
|
||
| 数据库 | [05-数据库规范](docs/工程规范/05-数据库规范.md) | ULID、customer_id、游标分页、expand/contract |
|
||
| 测试与 CI | [06-测试与CI规范](docs/工程规范/06-测试与CI规范.md) | 分层测试、权限三态、覆盖率只升不降 |
|
||
| Code Review | [07-CodeReview与PR规范](docs/工程规范/07-CodeReview与PR规范.md) | PR 模板、双人场景、DoD、合并后观察 |
|
||
| 日志与可观测 | [08-日志与可观测性规范](docs/工程规范/08-日志与可观测性规范.md) | Pino 字段、trace_id、审计与日志分离、告警 |
|
||
| 环境变量与密钥 | [09-环境变量与密钥规范](docs/工程规范/09-环境变量与密钥规范.md) | `.env.example` 入库、启动校验、轮换与泄露处置 |
|
||
| 资产命名与图层 | [10-资产命名与PSD图层规范](docs/工程规范/10-资产命名与PSD图层规范.md) | 命名占位符、PSD 图层前缀、规格矩阵、低质量标记 |
|
||
|
||
---
|
||
|
||
## 10 禁止自行决定（须产品 / 技术负责人确认）
|
||
|
||
- 新增第三方运行时依赖、新增外部 AI 供应商、改动 `ai_routes` 路由表。
|
||
- 字段类型白名单之外的新字段类型；权限点新增 / 删除 / 改名。
|
||
- 数据保留期、AI 预算阈值、爆量判定阈值。
|
||
- 公开分享 / 免登录审核链接开关（PRD R-28）。
|
||
- 跨客户资产复用授权（R-02 之外的显式授权流程）。
|
||
- 任何会让客户数据跨客户可见的实现方式。
|
||
|
||
---
|
||
|
||
## 11 AI 助手协作约定
|
||
|
||
1. 读上下文顺序：本文件 → 相关细则 → 技术架构对应章节 → PRD 对应章节，**禁止凭记忆写版本号 / 包名 / 表名 / 路由**。
|
||
2. 产出代码必须能过 `pnpm lint`、`pnpm typecheck`、`pnpm test`；不得新增未声明依赖。
|
||
3. 禁止修改已合并的 `prisma/migrations/`；禁止 `--no-verify` 提交。
|
||
4. 涉及业务口径不确定时，输出 `【待确认 Q-xx】` 并说明影响面，**不要编造**。
|
||
5. 改动跨 >3 个模块或触及 §10 清单时，先给出方案与影响面，等确认后再动手。
|
||
|
||
---
|
||
|
||
## 12 待建设规范（建议，尚未落地）
|
||
|
||
当前已覆盖 Git / 代码 / 格式 / 接口 / 数据库 / 测试 / Review / 日志 / 密钥 / 资产命名。以下规范建议在对应里程碑前补齐，**补齐前不得以"没有规范"为由自行发挥**：
|
||
|
||
| 规范 | 为什么需要 | 建议时点 |
|
||
| --- | --- | --- |
|
||
| **Prompt 工程规范** | 提示词模板是最容易被低估的资产；需约定模板结构、变量槽、版本与评测集 | M1 前 |
|
||
| **AI 成本与预算规范** | 预占 / 结算 / 账本 / 闸门已定，但预算口径与对账流程未文档化 | M2 前 |
|
||
| **安全与合规专项** | 广告法极限词、肖像权授权、AI 生成内容标识（R-09 形式仍待确认） | M1 前 |
|
||
| **运维 Runbook** | 部署、备份恢复、故障处理、告警处置（技术架构待办已列） | T1 前 |
|
||
| **前端交互与 UX 规范** | 快筛快捷键、空态 / 加载态 / 错误态、表格与表单交互统一 | M1 中 |
|
||
| **性能预算规范** | 首屏 ≤ 2s、接口 P95 ≤ 500ms 需拆到包体积 / 请求数 / 渲染预算 | M1 后 |
|
||
| **ADR 目录** | `docs/adr/` 尚未创建；首次架构决策时建立并纳入索引 | 首次 ADR 时 |
|
||
| **文档写作规范** | 术语统一、图表规范、评审流程 | M1 前 |
|
||
|
||
---
|
||
|
||
## 附：待同步事项（2026-11-02）
|
||
|
||
- [x] 根 `README.md` 已与 PRD V1.6 对齐（三主线 + 一底座、文档索引、命令契约）。
|
||
- [x] `docs/技术架构/`、`docs/立项建议/`、PRD V1.6、`docs/工程规范/` 已于 2026-11-02 按 Conventional Commits 拆为 6 个提交入库并推送（`6f644c0`~`c50ee7b`）。
|
||
- [ ] PRD 文件名 `灵犀-信息流广告素材一站式生产平台PRD.md` 不符合 §8 命名；因已被外部引用，暂保留原名，重命名时同步更新全部引用。
|
||
- [ ] 技术架构文档**文件名**为 `_V0.1.md` 但**内部版本**为 V0.4，正文修订记录中 V0.4 / V0.3 顺序倒置，建议下一版修正。
|
||
|
||
## 附：待确认口径（工程侧发现，需产品 / 架构确认）
|
||
|
||
| 编号 | 待确认项 | 本文现行约定 |
|
||
| --- | --- | --- |
|
||
| `C-01` | JSON body 字段命名：架构文档示例为 camelCase，而 query 用 `next_cursor` 等 snake_case | body 用 camelCase，query 用 snake_case（见 [04](docs/工程规范/04-API与路由规范.md) §2） |
|
||
| `C-02` | 列表响应是否统一信封 | 列表 `{ items, next_cursor }`，单资源不套 `data` |
|
||
| `C-03` | 工作区包 scope 命名 | 暂定 `@lingxi/*` |
|
||
| `C-04` | AI 生成内容标识的具体形式与位置（PRD Q-06 / R-09） | 角标 + MP4 元数据（技术架构 §7.4），形式待法务确认 |
|