lingxi/AGENTS.md

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

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

项	内容
适用对象	前端 / 后端 / 测试 / 运维 / 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 规范 · Code Review 与 PR · 测试与 CI

---

8　文档规范（摘要）

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

---

9　细则索引

主题	文档	一句话
Git / 分支 / 提交	01-Git规范	主干 + 短分支，Conventional Commits（提交信息用中文），Squash 合并
代码风格	02-代码风格	命名、类型、错误处理、异步、React 约定
格式化与 Lint	03-格式化与Lint	Prettier + ESLint 9 flat，钩子与 CI 门禁
API 与路由	04-API与路由规范	REST /api/v1、错误码、鉴权链、任务协议
数据库	05-数据库规范	ULID、customer_id、游标分页、expand/contract
测试与 CI	06-测试与CI规范	分层测试、权限三态、覆盖率只升不降
Code Review	07-CodeReview与PR规范	PR 模板、双人场景、DoD、合并后观察
日志与可观测	08-日志与可观测性规范	Pino 字段、trace_id、审计与日志分离、告警
环境变量与密钥	09-环境变量与密钥规范	.env.example 入库、启动校验、轮换与泄露处置
资产命名与图层	10-资产命名与PSD图层规范	命名占位符、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）

• 根 README.md 已与 PRD V1.6 对齐（三主线 + 一底座、文档索引、命令契约）。
• 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 §2）
C-02	列表响应是否统一信封	列表 { items, next_cursor }，单资源不套 data
C-03	工作区包 scope 命名	暂定 @lingxi/*
C-04	AI 生成内容标识的具体形式与位置（PRD Q-06 / R-09）	角标 + MP4 元数据（技术架构 §7.4），形式待法务确认