Jellyfish/AGENTS.md

Jellyfish Agent Guide

代码规范

1. API 变更后，必须运行 pnpm run openapi:update 同步 OpenAPI 接口。
2. 前端调用后端接口时，统一走 OpenAPI generated client，不再新增手写 service 封装。
3. 当前端样式重复度大于 1 次时，应优先抽离为可复用组件或公共样式结构。
4. 后端必须严格区分 api 层与 service 层职责：
   • api 层负责收参、鉴权、响应组织。
   • service 层负责业务逻辑、状态流转、数据编排。
5. 函数、类等代码块必须添加注释：
   • 至少包含功能介绍（说明“做什么”与“为什么存在”）。
   • 复杂函数需补充参数说明、返回值说明（如适用）与关键内部逻辑注释。
   • 注释应与实现保持同步，避免过时或空泛描述。
6. site 文档目录中：
   • site/content/blog 用于存放 release note。
   • 已固化版本的 release note，在未被明确指定时不得修改。
7. site/content/docs 的栏目职责必须严格区分：
   • guide = 开发指南 / how-to，回答“怎么做”。
   • architecture = 当前架构，回答“现在是什么”。
   • plans = 任务计划，回答“接下来做什么”。
   • reference = 稳定参考资料，回答“查什么”。
8. 新增或调整文档时，必须先判断内容归属：
   • 当前真实实现、当前边界、当前状态流转，放 architecture。
   • 正在推进或待推进的改造方案、任务拆解、阶段计划，放 plans。
   • 操作说明、开发流程、接入方式，放 guide。
9. 生成能力相关的通用契约（输入/输出 DTO、供应商配置等）统一放在 app/core/contracts：
   • tasks 仅保留任务封装、分派与执行编排，不定义跨层 DTO。
   • integrations 仅依赖 contracts，不依赖 tasks 类型模块。

前端页面职责

1. 分镜编辑页 = 准备
   • 负责资产/对白提取、候选确认、基础信息修正。
   • 负责将镜头推进到 ready。
2. 分镜工作室 = 生成
   • 负责视频准备度、关键帧、图片、视频参数与视频生成。
   • 不应承担主要的提取确认职责。
3. 任务中心 = 通用任务状态面板
   • 只负责展示通用、轻量的任务信息，如状态、进度、成功失败、取消与回跳入口。
   • 不承载业务专属上下文摘要，不展示提示词调试上下文、图文映射细节等重信息。
   • 业务细节应留在对应业务面板内展示，例如提示词弹窗、生成面板、诊断面板。

状态语义约定

1. shot.status 只表示信息提取确认状态：
   • pending = 当前镜头仍有提取确认工作未完成。
   • ready = 当前镜头已完成提取确认，可进入后续生成准备。
2. shot.status 不用于表达运行时生成状态：
   • generating 不再作为正式 shot.status 使用。
   • 运行中状态统一来自任务系统与 runtime summary。
3. video-readiness 单独表示是否具备视频生成条件：
   • 它与 shot.status 分离。
   • shot.status = ready 不等于一定可以立即生成视频。
4. 页面展示时必须明确区分三类状态：
   • 信息确认状态
   • 运行时任务状态
   • 视频生成准备度
5. 状态语义变更后，必须同步：
   • 后端实现
   • OpenAPI
   • 前端 generated types
   • 开发文档 / 说明文档

分镜主流程约定

1. 标准主流程为：
   • 章节内容提取分镜
   • 分镜编辑页完成资产/对白等基础信息提取与确认
   • 分镜工作室完成关键帧、参考图、视频参数与视频准备度检查
   • 分镜工作室发起视频生成
2. 默认职责边界：
   • 分镜编辑页负责“提取、确认、修正”。
   • 分镜工作室负责“生成准备、执行生成、查看结果”。
3. 若工作室中保留提取相关能力：
   • 仅作为快捷入口或诊断入口存在。
   • 不应重新成为提取确认主入口。
4. 涉及页面交互调整时，优先保证这条流转成立：
   • 编辑页准备完成后，明确引导进入工作室继续生成。
   • 工作室发现镜头未 ready 时，明确引导回编辑页确认。

协作约定

1. 修改 API、类型、状态模型后，优先同步：
   • 后端实现
   • OpenAPI
   • 前端 generated types
   • 对应开发文档
2. 涉及职责边界调整时，优先保持：
   • 分镜编辑页负责“准备”
   • 分镜工作室负责“生成”
3. 未经明确要求，不修改已固化的历史 release note。
4. 涉及系统结构、状态语义、页面职责边界调整时，必须同步更新 site 文档：
   • 当前已生效的规则，更新到 site/content/docs/architecture/
   • 尚在推进中的方案，更新到 site/content/docs/plans/
5. architecture 与 plans 必须保持动态更新，不允许长期滞后于真实代码状态：
   • 架构已落地但文档未更新，视为未完成
   • 计划已变更但文档未更新，视为未完成
6. 涉及任务系统 UI 调整时，优先保持：
   • 任务中心只展示通用任务信息
   • 业务上下文与调试信息留在具体业务界面
   • 不把任务中心演化成新的业务详情页

文档更新约定

1. architecture 文档的更新原则：
   • 只记录当前真实生效的实现
   • 不混入“未来准备怎么改”的内容
   • 当代码行为、状态语义、页面职责发生变化时，必须同步修订
2. plans 文档的更新原则：
   • 记录当前仍在推进中的计划、分阶段任务和方案
   • 当计划范围、优先级、执行路径发生变化时，必须同步修订
   • 某项计划稳定落地后，应沉淀到 architecture 或发布到 blog
3. 若同一主题同时涉及“当前事实”和“未来计划”：
   • 当前事实写入 architecture
   • 未来执行写入 plans
   • 不得混写在同一篇 how-to 中
4. release note（site/content/blog）格式与风格规范：
   • 必须采用稳定章节结构（按需裁剪，但顺序保持一致）：
     • Highlights
     • Added / Changed / Fixed
     • Breaking Changes（如有行为或契约变化必须填写）
     • Deprecations（如有弃用路径必须填写）
     • Security
     • Known Issues
     • Migration Guide
     • Rollback Notes
     • Compatibility Matrix
     • Validation Commands
     • Upgrade Checklist
     • References
     • Notes for Contributors
     • Acknowledgements
   • 必须包含 frontmatter：title、date、description、tags、authors。
   • 文风要求：
     • 使用“维护者发布口径”，优先结论与可执行信息，避免冗长叙事。
     • 术语必须稳定一致（如 shot.status、runtime task status、video-readiness）。
     • 升级步骤、回滚步骤、验证命令必须可直接执行，避免模糊描述。
   • 对外可读性要求：
     • 优先短段落与清单化表达；避免重复解释同一事实。
     • 明确区分“新增能力”“行为变化”“兼容风险”“已知问题”。

标准完成状态

以下场景在默认情况下，满足全部条件才算“完成”：

1. 代码实现完成：
   • 功能代码已落地
   • 无明显遗留占位实现
   • 无无效兼容代码残留
   • 新增或改动的函数、类等代码块已补充必要注释，并与实现一致
2. 接口/类型完成：
   • 若后端 API 有变化，已运行 pnpm run openapi:update
   • 前端 generated types 已同步
   • 前端调用已切到 OpenAPI generated client
3. 文档完成：
   • 若影响当前系统行为，已更新 architecture
   • 若影响后续执行计划，已更新 plans
   • 若为发布说明，按需更新 blog
4. 页面职责完成：
   • 分镜编辑页继续保持“准备”定位
   • 分镜工作室继续保持“生成”定位
   • 未引入新的职责混淆
5. 验证完成：
   • 前端改动后，至少通过 pnpm exec tsc --noEmit
   • 后端改动后，至少通过相关测试或最低限度的语法/导入校验
6. 结果汇报完成：
   • 明确说明改了什么
   • 明确说明验证结果
   • 若有未完成项或后续建议，需单独说明