Imported from ater-lzp/clip_agent (AGENTS.md). Install upstream with npx skills add ater-lzp/clip_agent. Copyright stays with the author.

Clip Agent 项目协作规范

1. 项目目标

本项目是一个由 LangGraph 编排的短视频生成智能体应用。系统接收主题描述、目标时长和画面比例，经过剧本生成与人工审核、分镜生成与人工审核、配音、素材检索、字幕与时间轴对齐、预览渲染和可选 BGM 混音，最终输出可预览、导出和追溯的短视频。

所有实现都应优先保证：流程可恢复、产物可追溯、人工审核可靠、音画时间轴准确、外部服务可替换，以及用户数据和凭据安全。

2. 指令作用域与优先级

• 本文件适用于整个仓库；子目录中的 AGENTS.md 或 agents/*.md 只补充其专项规则。
• 当前用户任务的明确要求高于本文件；遇到冲突时先指出冲突，再采用风险最低且最符合用户目标的方案。
• 修改前先阅读相关代码、配置和测试，不猜测尚未查看的实现。
• 保留用户已有改动。不得为了方便而回滚、覆盖或格式化与当前任务无关的内容。
• 只修改完成当前任务所需的文件；如果发现旁支问题，在交付说明中列出，不擅自扩大范围。

3. 技术基线

• 后端：Python 3.10.9、LangChain 1.x、LangGraph 1.x、Pydantic 2.x。
• 前端：Node.js 24.18.1、npm 11.16.0、Vue 3、TypeScript。
• 持久化：SQLite；LangGraph 使用 SQLite Checkpointer 保存工作流检查点。
• 依赖版本以 pyproject.toml、uv.lock、package.json 和前端锁文件为准。不得仅以 latest 作为可复现的依赖版本。
• LLM、TTS 和素材服务必须通过适配器调用；模型名、服务地址和凭据从服务端环境配置读取，不得散落在业务代码中。

4. 按任务读取规范

开始工作前，只读取与任务相关的专项文件：

接口实现与 agents/api.md 必须在同一次变更中保持一致。若接口文档尚未定义所需契约，先补充契约，再实现调用方和服务端。

5. 目标项目结构

以下是项目的目标布局。实际新增、移动或删除顶层目录时，应同步更新本节；不要保留与仓库不符的结构说明。

clip_agent/
├── .env                  # 本地服务端环境变量；不得提交真实凭据
├── AGENTS.md             # 全局协作与安全约束
├── README.md             # 面向使用者的安装、运行与架构说明
├── pyproject.toml        # Python 与后端依赖配置
├── uv.lock               # Python 锁文件
├── backend/              # API、工作流、领域服务和基础设施适配器
├── frontend/             # Vue + TypeScript 客户端
├── admin/                # 独立 Vue + TypeScript 管理员控制台
├── agents/               # 前端、后端和 API 专项规范
└── tests/                # 跨模块或端到端测试

模块应按职责组织，避免把路由、LangGraph 节点、供应商 SDK 调用和媒体处理堆叠在同一个文件中。

6. 通用工程规则

6.1 实施流程

1. 明确需求、受影响模块、数据流和验收条件。
2. 检查现有实现、接口契约、依赖和工作区改动。
3. 采用最小且完整的改动，复用现有抽象，不创建重复实现。
4. 为新增逻辑补充与风险相称的测试；外部 LLM、TTS、素材和渲染服务应使用 mock 或 fake。
5. 运行受影响范围的检查和测试；无法运行时说明具体原因，不宣称已经验证。
6. 检查 README.md 是否因安装方式、环境变量、命令、目录结构、接口或用户流程变化而需要更新。

6.2 代码质量

• 命名应表达领域含义，避免 data、result、temp 等在跨层传递中失去语义的名称。
• 公共边界必须有明确类型；不得用无约束字典长期代替 Pydantic 模型或 TypeScript 类型。
• 错误处理应保留原因、阶段和可重试性，并向用户返回安全、可行动的信息。
• 时间统一以 UTC 存储，API 使用带时区的 ISO 8601；面向用户时再按本地时区展示。
• 持久化实体使用稳定且不可猜测的 ID。所有资源访问都必须校验当前用户的所有权。
• 不在图状态、数据库记录和 API 响应中存放大型二进制数据；仅保存受控路径、对象存储键、URL 和必要元数据。

6.3 安全红线

• 禁止在代码、提示词、图状态、日志、测试夹具、前端包或版本库中硬编码 API 密钥、令牌和用户密码。
• 禁止使用 eval、exec、不受限动态导入，或把用户输入直接拼接为系统命令、SQL、URL 或文件路径。
• 所有数据库查询使用参数化语句或安全 ORM；所有文件访问先做规范化并限制在专用工作目录内。
• 日志必须脱敏。不得记录密码、完整令牌、Cookie、Authorization 头、供应商密钥、完整用户提示词中的敏感内容或媒体二进制。
• 服务端 .env 是部署级配置，不是普通用户偏好存储。普通用户请求不得直接读取、回传或修改 .env。
• 浏览器端不得接收供应商密钥。用户设置只保存非敏感偏好；如需在线管理部署凭据，必须另设管理员授权、审计和加密存储方案。
• 外部 URL、上传文件和媒体元数据都视为不可信输入，必须限制协议、来源、大小、类型、时长和解析资源消耗。

7. 文档与运行命令

命令必须注明工作目录，并以仓库实际入口为准。入口尚未创建时，不得在文档中声称可运行。

# 后端（在仓库根目录；入口存在后使用）
.\.venv\Scripts\python.exe -m uvicorn backend.main:app --reload

# 前端（在 frontend 目录）
npm run dev

新增环境变量时，同时提供安全的示例名称、用途和是否必填，不填写真实值。涉及用户可见安装、配置或使用方式的变化时同步更新 README.md。

8. 完成标准

只有同时满足以下条件，任务才算完成：

• 行为符合需求，关键失败路径有处理，且没有破坏已有流程。
• 前后端契约、类型、状态枚举和字段命名一致。
• 人工审核、重试、恢复和并行汇合不会重复产生不可控副作用。
• 新增或变更逻辑有必要的测试，已执行的检查结果明确。
• 无密钥泄露、越权访问、路径穿越、命令注入或不受控远程资源访问风险。
• 已检查并按需更新 agents/api.md、README.md 和本文件中的项目结构。