# AGENTS.md · 灵犀项目整体规范

> 本文件是本仓库的**唯一总纲**，面向所有研发与 AI 编程助手（Claude Code / Cursor / Codex / Copilot 等）。
> 只写**硬约束与索引**，细则一律见 [`docs/工程规范/`](docs/工程规范/README.md)，本文不重复展开。

| 项 | 内容 |
| --- | --- |
| 适用对象 | 前端 / 后端 / 测试 / 运维 / AI 工程 / 产品（技术边界） |
| 适用产物 | 代码、配置、脚本、迁移、文档、Prompts |
| 文档版本 | V1.1（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 | 全项目 M0–M4 里程碑、批次、WBS、门禁与验收口径（派生文档，**不得改变需求与技术边界**） |
| 立项建议 | `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 |

> 版本升级单独提交 + 修订记录，**禁止顺手升级**。新增运行时依赖需在提交说明必要性（影响面 + 替代方案）。

---

## 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 ci:local` |
| 数据库 | `pnpm db:migrate` · `pnpm db:reset`（禁止 `docker compose down -v`） |
| 契约 | `pnpm openapi:diff` |

> 文档、脚本、CI 中出现的命令必须与上表一致，禁止自造别名。

---

## 7　变更流程（推送前必须全绿）

1. 基于最新 `main` 直接提交，小步 commit（**Conventional Commits，提交信息一律用中文**，`type` / `scope` 保留英文）。
2. 本地门禁：`pnpm format:check && pnpm lint && pnpm typecheck && pnpm test`。
3. 提交说明必含：**背景 / 改动 / 影响面 / 回滚方式 / 验证证据**；迁移、权限、AI、导出类变更须在推送前完成双人走查。
4. 直接 `git push origin main`；禁止 force push `main`，禁止 Merge commit；推送后立即确认 CI，失败按前向修复处理。
5. 发布：staging 验证 → 生产灰度；**迁移先行、代码后行**。

细则：[Git 规范](docs/工程规范/01-Git规范.md) · [Code Review](docs/工程规范/07-CodeReview与PR规范.md) · [测试与 CI](docs/工程规范/06-测试与CI规范.md)

---

## 8　文档规范（摘要）

- 文档与代码**同一次提交或相邻提交**更新；只改文档也直接提交到 `main`。
- 新业务规则先进 PRD 并编号（`R-xx`），再进代码。
- 文档版本 `V<主>.<次>`：主版本 = 业务口径不兼容；次版本 = 增量补充。
- 索引三处必须同步：根 `README.md`、`docs/工程规范/README.md`、本文件 §9。
- 命名沿用 `灵犀_<主题>_<类型>_V<版本>.md`；**新建文档**必须遵循，历史文件保持原名并登记。

---

## 9　细则索引

| 主题 | 文档 | 一句话 |
| --- | --- | --- |
| Git / 分支 / 提交 | [01-Git规范](docs/工程规范/01-Git规范.md) | 仅 `main` 直推，Conventional Commits（**提交信息用中文**），禁止 Merge commit |
| 代码风格 | [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) | 提交说明、双人场景、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），形式待法务确认 |