video-workflow/AGENTS.md

# AI 助手项目说明

本文件是 AI 助手改动本仓库前必读的约定。与代码/真实结果冲突时以代码为准；不确定先问，不要臆造。

开工前必读

• 开始任何任务前，必须依次阅读：
  1. 本文件 AGENTS.md（约定与铁律）
  2. docs/长期规范/AI助手必读规范/系统架构.md（运行边界、数据流、模块依赖、设计决策）
  3. docs/长期规范/AI助手必读规范/IP操盘三大核心路线.md（IP 操盘主线、验收标准和防跑偏规则）
  4. docs/长期规范/AI助手必读规范/项目术语表.md（遇到不懂的专有名词在此查证，不要臆测含义）
  5. docs/长期规范/AI助手必读规范/项目状态.md（当前进度；注意区分“代码已完成”与“线上已验收”）
• 读完后、动手前，必须用几句话向用户复述：项目定位、相关的运行边界与职责、本次任务要遵守的铁律和要避开的坑，以及打算如何改动；经用户确认后再开始写代码。
• 不确定的概念先查 项目术语表.md 或询问用户，禁止臆造。

项目定位

• 公司内部的抖音内容运营与创作工作台。产品重心已由“AI 视频生成”转向“IP 操盘、选题、脚本和辅助运营”；生成能力仍是内容执行层，不是唯一主线。
• IP 操盘目标是证据驱动的半自动闭环：真实账号数据 -> 定位诊断 -> 内容方向/选题 -> 分镜脚本 -> 日历/发布包 -> 数据复盘。中高风险动作由用户确认，不建设批量评论、Cookie 池、代理池或全自动发布。

技术栈与架构

• Angular 21 standalone + Signals；严格 TypeScript/模板检查。Express 仅承接本地代理、媒体处理和 FFmpeg/Whisper 等能力；长期业务数据经 fmode 云函数写入 Parse 项目命名空间 Class，文件本体进入七牛。
• 主产品界面主要由 App 的 currentTab 单壳切换驱动，不是常规 Angular Router 多页面应用；app.routes.ts 只保留少量旧入口/调试入口。
• app.ts 是历史主壳且体积很大。新业务逻辑优先放服务或独立 standalone 页面组件，不继续把流程堆进主壳。
• 登录用户的数据归属只能由服务端根据 Parse sessionToken 解析的用户决定；不得信任前端传入的 userId。
• 长期业务主数据写 Parse 项目命名空间 Class：VideoWorkflowEntity、VideoWorkflowAudit、VideoWorkflowMigration 或后续确认的 VideoWorkflow* 专用 Class；图片/视频/音频写七牛并登记 VideoWorkflowFileAsset。localStorage 仅允许轻量偏好和可重建缓存，短期试用/草稿使用 sessionStorage 或 IndexedDB。
• 数据库清理、迁移、测试数据重置或批量修改只能操作 VideoWorkflowEntity、VideoWorkflowAudit、VideoWorkflowMigration、VideoWorkflowFileAsset 四个项目 Class；_User、APIG、APIGAuth、APIGOrder 以及其他共享/平台 Class 绝对不能动。
• PSQL 不再作为本项目业务主存储；旧 PSQL 数据因尚未正式使用，本阶段不迁移、不删除。Parse Class 和字段结构不得擅自删除、重建或新增，新增字段必须先确认。

目录约定

• 新页面：src/app/pages/<feature>/；页面专属样式和模板与组件同目录。
• 可复用 UI：src/app/components/；跨页面业务逻辑、API、存储适配：src/app/services/；共享业务类型：src/app/models/。
• 新生成模式：放入 src/app/pages/pipelines/<mode>/，并同步登记 pipeline-registry.ts、AppTab/Tab 校验和主壳模板入口。
• Express 新接口：实现于 server/routes/，运行时配置集中在 server/config/runtime-config.js；避免继续膨胀 server.js。
• fmode 云函数源码：cloud-functions/；共用登录态逻辑放 _session.js。cloud-functions/deployable/ 是构建产物，不手改、不提交。
• 工程校验/迁移脚本：scripts/validation/；Playwright 场景：e2e/；单元测试与被测文件同目录，使用 *.spec.ts。
• docs/ 默认仅在本机保留并整体忽略，不作为提交或 CI 输入；AI 助手长期协作文档统一放在 docs/长期规范/AI助手必读规范/，仅作为本地开工读取与协作记录使用。data/、测试结果、本地部署脚本和个人资料不得作为 CI 或运行时输入。

工作流程铁律

• 修改前先读现有调用链和相邻测试；保留现有服务边界，不为单点需求另建一套账号、积分、存储或任务体系。
• 改前端/服务后至少运行相关 *.spec.ts 与 npm run build；改 IP 操盘主流程再运行 npm run e2e:ip-operator。
• 改云函数后运行 npm run build:cloud-functions、npm run validate:cloud-functions、npm run smoke:cloud；真实登录态、扣费或隔离测试需用户明确提供本地临时环境变量。
• 改计费链路额外运行 npm run validate:jimeng-billing；改存储边界额外运行 npm run validate:storage-policy。
• 提交前运行 npm run review:guard 和 git status。提交应原子化，说明改动范围与已运行的验证；仓库没有强制 Conventional Commits 格式。
• 每个任务结束前必须按类型回写文档：约定、目录、命令或已知坑变化更新 AGENTS.md；阶段进度更新 docs/长期规范/AI助手必读规范/项目状态.md；技术决策在 docs/长期规范/AI助手必读规范/架构决策记录/ 新增 ADR；架构变化更新 docs/长期规范/AI助手必读规范/系统架构.md。没有需要更新时，必须显式说明“无需更新”。
• 运行边界、关键数据流、模块依赖方向、数据存储模型或关键设计决策发生变化时，必须在同一任务内同步 docs/长期规范/AI助手必读规范/系统架构.md；不能只更新项目状态或普通说明文档代替架构回写。
• 禁止提交 .env、session token、用户数据、媒体产物、测试结果、deployable/ 或本地方案资料。禁止用真实生成/充值接口做无授权冒烟测试。
• 不直接修改或删除用户已有改动；不使用 git reset --hard、git checkout -- 等破坏性命令。

常用命令

# 首次克隆仓库后启用版本化 pre-commit 提醒钩子；每个工作副本执行一次。
git config core.hooksPath .githooks

# 同时启动 Angular 前端和本地 Express 后端，进行日常联调。
npm run dev

# 一次性运行 Angular/Vitest 单元测试，适合提交前或修改服务后执行。
npm test -- --watch=false

# 执行生产构建，验证严格类型、模板和构建预算。
npm run build

# 修改 IP 操盘主流程或页面交互后运行对应 Playwright 回归。
npm run e2e:ip-operator

# 修改依赖 _session.js 的云函数后，重新生成 fmode 单文件部署包。
npm run build:cloud-functions

# 修改云函数源码、函数清单或部署约定后检查部署就绪状态。
npm run validate:cloud-functions

# 修改余额、预扣、确认、退款或即梦计费逻辑后执行。
npm run validate:jimeng-billing

# 修改浏览器存储、Parse 云端实体、评论/脚本等数据边界后执行。
npm run validate:storage-policy

# 只读预览 IP 操盘测试垃圾清理候选；需要先设置 SMOKE_SESSION_TOKEN，不会删除或 purge。
npm run inspect:ip-operator-cleanup

# 按 dry-run 报告软删除 IP 操盘测试垃圾候选；必须显式传入 --confirm SOFT_DELETE_IP_OPERATOR_CANDIDATES。
npm run cleanup:ip-operator:soft -- --input tmp/<dry-run-report>.json --confirm SOFT_DELETE_IP_OPERATOR_CANDIDATES

# 按清理报告解析/物理删除 IP 操盘测试垃圾；默认只解析 objectId，真正删除必须显式传入 --confirm PHYSICAL_DELETE_IP_OPERATOR_CANDIDATES。
npm run cleanup:ip-operator:physical -- --input tmp/<cleanup-report>.json

# 只读预览当前登录用户在四个 VideoWorkflow 白名单 Class 下的测试数据；必须先设置 SMOKE_SESSION_TOKEN，不会删除。
npm run inspect:videoworkflow-cleanup

# 物理删除当前登录用户在四个 VideoWorkflow 白名单 Class 下的测试数据；必须显式传入 --confirm DELETE_VIDEO_WORKFLOW_TEST_DATA。
npm run cleanup:videoworkflow:parse -- --confirm DELETE_VIDEO_WORKFLOW_TEST_DATA

# 云函数部署或函数 ID 变更后检查线上连通性与权限拦截。
npm run smoke:cloud

# 提交前检查疑似凭证和已知大文件治理阈值。
npm run review:guard

已知坑

• App 使用 ViewEncapsulation.None 让全局 dh-*、pl-*、pipeline-* 样式作用于子组件；改回默认封装会导致多个生成页面失样。
• fmode 运行环境不支持源码中的 require('./_session')。部署依赖它的函数前必须生成并复制 cloud-functions/deployable/*.js。
• cloud-functions.ts 是云函数 ID 的唯一前端登记点；部署说明中的状态可能滞后，以配置和真实 smoke 结果为准。
• fmode 网关偶发 fetch failed 或“必须提供 id”；只对只读/幂等请求做有限重试，充值、扣费、生成提交不得盲目重放。
• Playwright 固定使用 Edge、端口 4300 且串行运行；真实 LLM/E2E 会调用外部服务并可能产生费用。
• 前端生产包仍偏大，initial 预算当前为 warning 2.7MB、error 3.0MB；app.ts、IP 操盘组件和部分服务已很大，新增功能优先拆分，避免继续扩大单文件。
• 开发代理中的 /api 指向 TikHub，/backend 才指向本地 Express；生产环境没有本地 Express 抖音代理，抖音账号采集必须走 CLOUD_FN.douyin 云函数，否则 https://app.fmode.cn/backend/api/douyin/call 会返回 405。