wang259797/lingxi
1
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
68b5ca20f47f62b34b6ead5f6a9570be7f345987
lingxi/AGENTS.md
T
Stev_Wang 68b5ca20f4
ci / 质量门禁 (push) Canceled after 0s
Details
ci(ci): 支持本地 CI 并调整开发库凭据 
背景：Gitea 暂未部署 Actions runner，远程 CI 会停留在 queued；本地开发库按约定改用 lingxi / postgres / postgres。

改动：
- 新增 pnpm ci:local，按 CI 工作流顺序执行 compose、格式、Lint、类型、单测、构建、迁移种子、集成、OpenAPI 与 e2e；
- 新增 scripts/e2e.mjs 管理 vite preview 生命周期，e2e 改为单 worker 避免退出挂起；
- openapi:export 生成后自动 Prettier，保持工作区干净；
- compose、.env.example、CI services 数据库凭据统一为 postgres/postgres，库名 lingxi；
- README、AGENTS、A0 报告同步本地 CI 与数据库说明。

影响面：仅本地开发与 CI 执行方式，无业务代码/接口/数据模型变更；本地库已重建为 lingxi/postgres。
回滚方式：git revert 本提交；数据库需按回滚后的 compose 凭据重新初始化。
验证：pnpm ci:local 全绿（158s），format:check、lint、typecheck、openapi:diff 通过。
2026-11-02 18:14:08 +08:00

14 KiB
Raw Blame History

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

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

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

8　文档规范（摘要）

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

9　细则索引

主题 文档 一句话
Git / 分支 / 提交 01-Git规范 仅 main 直推，Conventional Commits（提交信息用中文），禁止 Merge commit
代码风格 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规范 提交说明、双人场景、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），形式待法务确认
Reference in new issue View Git Blame Copy Permalink