Files
short-drama-agent-front/AGENTS.md
T

125 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 项目协作规范
## 默认分支与工作目录
- 新增功能、新增文件、修复问题和重构,默认全部在本项目根目录的 `dev` 分支进行。
- 开始修改前先确认当前分支。若不在 `dev`,应保留现有修改并安全切换到 `dev`,不得丢弃或覆盖用户已有工作。
- 不创建新的 Git worktree,不在 `worktree`、`worktrees`、`.worktree` 或 `.worktrees` 目录中新增或修改文件。
- 不因技能、模板或默认隔离流程而创建工作树;本规则覆盖此前“新功能在 worktree 中开发”的项目约定。
- 已有工作树仅在用户要求迁回改动时作为只读来源;迁回后在项目根目录的 `dev` 分支继续修改和验证。
- 未经用户明确要求,不提交代码、不推送、不切换或合并到其他发布分支。
## 开发与验证
- 尽量使用中文沟通,沿用项目现有的 Vue 3、TypeScript、Tailwind CSS 和 pnpm 约定。
- 新增或修改的函数、类型、响应式状态及页面模块需要中文注释;函数有参数或返回值时补充 `@param`、`@returns`。
- 无参数、无返回值的函数使用 `/** 描述 */`;类型及其字段分别注释,`ref`、`computed`、`defineProps`、`defineEmits` 等也要说明用途;Vue 模板中的功能模块之间换行并添加中文模块注释。
- 超过两个位置使用的相同功能或组件,应抽成公共方法或组件。
- 页面和交互验证使用本地 Chrome,地址使用 `localhost`,禁止使用 Playwright;已有对应测试标签页时复用它。
- 以真实接口和后端契约为准,不用占位数据或其他功能代替缺失能力。
- 根据后端新增或重构前端功能前,先核对真实路由、请求参数、返回结果、服务逻辑和接口文档;不能只补类型而遗漏页面流程。缺少契约且无法确认时明确说明,不猜测或用其他功能代替。
- 提交代码时遵循项目的 Conventional Commits 规范,使用中文描述;提交前先检查实际差异。
## 全局页面与交互规范
以下规则是用户长期确认的项目要求,适用于后续所有新增、修改和重构的页面、弹窗及抽屉。换窗口后也应直接沿用,不等待用户再次指出同类问题。
### 整体协调与公共实现
- 修改前先查看所在完整页面、相邻模块及已有公共组件,同时考虑整体协调、元素间距和功能一致性,不能只修改截图中的一个局部而忽略其他状态。
- 同类布局、按钮、状态色、关闭入口和交互流程保持一致;发现本次改动涉及的同类问题时,一并修正相关公共组件或当前功能中的使用位置。
- 优先复用 `src/components/ui` 中的公共组件、`src/styles/admin.css` 中的设计变量和现有主题配置;公共问题在公共层解决,避免各页面重复覆盖或硬编码颜色、尺寸。
- 所有折叠、展开和历史详情区域统一使用 Naive UI 的 `NCollapse`、`NCollapseItem` 等组件,不再使用原生 `details`、`summary` 或自制折叠控件;修改同类区域时同步统一现有实现。
- 维持项目现有简洁、扁平的视觉风格。用标题、简短说明、留白和对齐区分普通功能区域,避免无意义的底色、边框和装饰线。
- 页面文案保持精简,说明应帮助用户理解当前操作;不把大量错误、技术细节和重复提示堆在设置页面。
### 面向普通用户的文案
- 默认使用者不了解软件开发。页面、弹窗、按钮、说明、校验、空状态和错误提示不得直接描述“前端做什么”“后端做什么”,应说明当前结果、影响和下一步操作。
- 英文技术术语优先改成易懂的中文,例如 `Checkpoint` 用“保存记录”、`Storyboard` 用“分镜”、`Prompt` 用“画面描述”或“提示词”、`Thinking` 用“深度思考”。不要把内部字段名、错误码、任务标识直接作为主要说明。
- 接口返回的系统提示也需要在展示层转换为可读中文;错误详情只提取有助于操作的业务原因,不把调试对象、堆栈或整段原始数据直接输出给用户。原始错误和错误码保留在数据层,不改动业务判断依据。
- 只调整展示文案,不翻译或改写请求字段、枚举值、接口地址、用户创作的剧本与提示词正文、文件名、自定义名称或模型品牌。分类等内部值使用中文选项展示,提交仍保留真实取值。
- 用短句直说结果和下一步。同一个意思只写一次;标题和按钮已说明用途时,删掉重复说明。提示一行能说清就不写成段落,必需的限制和费用信息要保留。
- 导航只显示名称。禁用原因放到可通过悬停和键盘聚焦查看的提示里,菜单行高保持一致。
- 问题提示放在能直接处理它的页面。素材图库不常驻展示下游镜头的生产警告和列表;从镜头主动定位素材时,只保留定位所需的信息与返回入口。普通浏览不发仅供该定位使用的全项目检查请求。
- 费用、覆盖、删除、适用范围与待审核限制必须保留并说清楚,不能为了简化文字改变功能含义。无法确认的能力不要用容易误解的描述代替。
- 必要的原始技术数据放在默认收起的“高级详情”或导出结果中,日常操作先展示中文摘要。同一弹窗的操作统一放入公共 `footer`,避免正文操作与默认关闭按钮重复。
### 全屏抽屉与关闭入口
- 新建剧本、项目全局配置、拆解设置、拆解问题等已确认使用全屏的界面统一复用 `AppDrawer`。后续同类复杂表单、设置和问题处理界面默认沿用全屏抽屉;简短确认或轻量提示仍可使用 `AppDialog`。
- 全屏必须同时覆盖容器与正文:内容使用可用的完整宽度,不能只把外壳放大而保留原弹窗的固定宽度或居中最大宽度。
- 标题区和底部操作区固定,只有正文独立滚动。长内容不能把关闭或提交按钮挤出视口,也不能产生页面与抽屉重复滚动。
- 抽屉标题、说明、正文和底栏左右边界统一。复用公共抽屉的桌面、移动端内边距;正文 `padding-top` 保持为 `0`,不要额外叠加顶部空白。
- 所有弹窗和抽屉底部至少保留一个可见的“关闭”或“取消”按钮,不能只有右上角叉号。底部操作使用公共组件的 `footer` 插槽,避免正文末尾再放一套底栏或重复关闭按钮。
- 关闭、取消统一为灰色底面和中性文字的普通按钮,不使用绿色主按钮;右上角关闭图标的尺寸、底色与交互反馈也统一复用公共样式。
- 提交期间按真实业务状态防止重复操作及意外关闭;普通只读加载不能无故阻止用户关闭。关闭、切换或定位后,不回填已失效的异步结果。
### 布局、说明与间距
- 页面外边距、模块间距优先复用 `--app-content-padding`、`--app-content-gap`;表单与抽屉内部复用对应公共组件的间距,不在各页面随意添加不同数值。
- **表单字段间距为强制要求**:页面、弹窗、抽屉中的标签不能紧贴输入框、下拉框或选择组;自定义字段默认使用 `--app-field-label-gap`(8px),相邻字段默认使用 `--app-field-gap`(16px)。紧凑布局和移动端也不得取消这些必要间距,除非用户明确要求调整。
- 自定义的“标签 + 控件”优先复用 `src/styles/admin.css` 中的 `workspace-form-field`,使用真实的纵向 Flex/Grid `gap`;成熟表单继续复用 `AppForm` / `NFormItem` 的公共排版。禁止仅给行内 `span` 套 `space-y-*` 或垂直 margin 后,就认定标签间距已经生效。
- 修改表单布局时必须核对同模块的全部同类字段,保证同排标签、控件分别对齐;图片与表单并排时,图片标题和字段标签必须复用同一纵向间距值,图片与首排控件的上沿必须对齐;在本地 Chrome 检查桌面、窄屏及必要的加载/校验状态,确认实际留白生效后才算完成。
- 同级模块使用一致的标题、说明、字段间距和上下留白。需要说明时采用“模块标题 + 一句简短说明”,例如画布设置、图片配置、视频配置、动作与物理规则;优先复用 `WorkspaceSectionHeading`。
- 页面、弹窗和抽屉中的同级模块共用左右边界。普通分区直接对齐;需要突出一组内容时,优先用已有的中性背景包住整组内容。背景外沿与相邻模块对齐,组内使用统一内边距,避免透明容器单独缩进。
- 新建剧本等长表单默认每个字段单独占一行并铺满内容宽度;不因改成全屏就自动把原来的字段挤成两列。
- 图片、视频等已有明确分组的并列模块可以保留协调的分栏,窄屏改为单列;同一行的标签、控件及操作必须分别对齐,不能因说明或校验消息出现而上下错位。
- 行内按钮按输入控件本身的基线对齐,不能按包含标签的整块区域垂直居中。动态例外行中的移除按钮与输入框底部对齐,使用 `Trash2` 等现有图标,不再显示“移除”文字,并提供可访问名称。
- 项目生成配置等普通表单分区不铺大块背景色,使用标题、说明和统一间距组织;常规错误沿用中性底色,只有明确的严重错误或通过检查的成功状态才使用对应状态底色。
### 按钮、图标与状态颜色
- 绿色背景、白色文字用于保存、提交、开始生成等主要执行操作;关闭、取消和普通辅助操作使用中性样式。
- 普通请求失败、表单校验、审核未通过和可修复问题默认使用中性底面,配合短文字、图标或细线提示。红色底面只用于明确需要立即关注的严重错误,例如任务中断且可能重复计费。保留深浅主题对应的柔和状态色。
- 普通镜头定位使用中性提示。从明确问题定位时,可加细线标记;正文刷新后清除旧标记。
- 错误入口按钮使用中性底面,文字、图标和焦点保留错误语义。默认、悬停、按下和聚焦时保持清晰的键盘焦点与状态反馈。
- 只有执行完成且结果明确通过校验时,成功任务区域才使用柔和浅绿背景。执行结束但校验失败、质量待审或结果未确认时,不能显示成绿色成功状态,也不能用满格绿色进度条暗示业务成功。
- 卡片内的定位、复查、修订和历史入口使用带图标、独立中性底面的按钮,不添加边框,不能与说明文字混在一起;复用 `workspace-action-button` / `workspace-action-group`,不把辅助操作改成绿色主按钮。
- 工具栏中相邻按钮保持一致的高度、内边距、图标大小和间距。问题入口使用图标加文字;分镜结构校验失败时文案为“分镜校验未通过”,其他问题按真实类型命名。
- 移动端的工具栏操作优先只显示图标,保留完整的 `aria-label`、提示文本和足够点击区域;普通表单的底部关闭、取消、提交按钮仍保留文字。
- 仅显示单个图标的操作按钮统一使用正方形,图标居中,并使用 Naive UI `NPopover` 展示完整操作名称;优先复用 `WorkspaceActionTooltip`,保留对应 `aria-label`,相邻按钮尺寸和间距一致。
- 按钮已显示完整文字时,不再重复添加同名悬浮提示;桌面有文字、移动端仅图标的响应式按钮,仅在隐藏文字的屏幕尺寸下启用 `NPopover`。桌面仍为纯图标的按钮继续保留提示。
- 诊断结果卡片的定位、可选 AI 复查、修订及历史按钮在移动端也保留图标和完整文字,宽度不足时自动换行,不套用顶部工具栏仅显示图标的规则。
- 页面左侧汇总状态在运行、成功、失败等状态下均有意义,应保留;右侧操作入口负责打开对应处理界面,避免把状态展示和操作混成重复文案。
### 设置、问题处理与任务进度
- 拆解设置与问题处理分开:设置界面负责模块选择、分组预览、启动拆解、候选确认与提交;问题界面负责错误查看、分镜定位、人工修订、读取修复清单及阶段恢复。
- 质量规则确认以服务端 revision、fingerprint、confirmed 和独立 confirm 接口为准,不能用 LocalStorage 或格式版本 policy.version 代替。规则保存携带 expectedRevision,拆解启动携带本次已确认修订;候选提交预检查必须包含 qualityPolicyMatches。
- 首次拆解前只确认表现方式、动作许可和自定义规则,不显示精确动作例外的空白编辑行。已有例外可只读核对,隐藏输入不能清空已有规则或在保存时覆盖后来新增的例外。
- 新增精确动作例外统一放在拆解后的问题修订中,从当前版本的真实冲突证据自动带入角色、部位或物品及动作,用户填写允许原因。证据缺失时不能猜测或用其他镜头代替;按后端实际范围说明影响,保存例外不能直接标记质量通过。
- 不在拆解设置中重复堆放详细错误列表和修复说明;问题按剧集、节拍、镜头分组并去重,保留后端原始问题及可定位位置。
- 从问题界面定位正文时,先关闭抽屉,等离场和焦点约束释放后再定位,不能同时叠加两个主界面。
- 后端从其他入口启动或重新执行任务时,前端也应发现任务并显示真实运行阶段、进度、作用范围及更新时间;重新进入页面后能够恢复观察,不能只依赖前端本次点击形成的加载状态。
- 执行状态与质量校验结果分别表达,不能把“执行完成”直接等同于“校验通过”;没有真实进度或结果时明确显示待确认,不伪造百分比。
- 已修订且当前审核通过的镜头,不因未运行或过期的独立 AI 诊断再次列为“需处理”。AI 复查单独作为可选项,只有当前明确冲突或实时结构化问题才提示修复;复查入口受限不能直接解释为正式分镜需要重拆。
- 默认收起的“高级检查详情”只保留必要的检查记录和当前复查范围,不再单独展示旧手部覆盖率或未填写手部记录;缺少记录使用中性说明,不作为错误,实际检出的动作冲突仍在普通问题区域展示。
- 拆解执行中暂不显示“查看诊断”等需要稳定结果的入口。问题可以只读查看,但人工修改、候选提交、修复和恢复操作应遵守真实活动任务锁,避免冲突。
- 拆解任务卡片与相邻模块采用统一边距和状态底色,必要的阶段、范围、进度和时间直接简洁展示;不要把重要信息只藏在“任务详情”折叠中,也不默认展示无助于操作的内部编号或原始数据。
### 表单校验与交互时机
- 打开表单、加载已有配置或添加一条空白例外时,不立即展示红色校验错误。
- 点击保存、提交时再执行完整校验,阻止不完整请求;需要字段交互校验时,只在用户已操作该字段或已尝试提交后显示。
- 用户修改相关内容后及时清除或更新旧错误,不能让已经失效的提示长期挂在表单上。
- 必填标记、字段提示和错误信息保持统一位置与间距;删除行、增添行和错误出现时,操作按钮仍应与对应控件对齐。
### 页面验收
- 涉及页面或交互的改动,必须在已有本地 Chrome 标签页使用 `localhost` 验证后才算完成,不能只根据代码、构建或 DOM 测试声称布局通过。
- 验证本次改动涉及的桌面、移动端、长内容滚动、固定底栏及必要的加载、错误、成功状态;检查普通、悬停和键盘聚焦时的颜色、对齐与可访问名称。
- 页面模块之间复用公共间距;按钮、标题和辅助说明须有清晰留白。已有相邻页面使用骨架屏时,同类入口也应在项目加载和正文加载阶段预留相同结构。
- 骨架与图片占位默认静态显示,避免闪动。图库按真实卡片结构分别预留图片、文字和操作位置。
- 图片卡片在请求图片前就预留画面区域,优先用已有宽高,缺少宽高时使用稳定比例。检查慢速、加载失败和无图时卡片都不会塌陷。
- 界面验收不得为了制造状态而触发真实付费生成、覆盖正式结果或提交用户数据;使用现有状态、只读操作和合适的自动化测试验证。
- 测试与检查按改动范围执行;纯文档变更无需启动页面或重复完整构建。报告时区分自动化检查与真实浏览器验证,并明确未完成项,不把尝试操作当作验收通过。
## 提交规范补充
- 仅用户明确要求“提交”时才提交,“提交并 push”才同时授权推送;不因界面修改完成而自动提交或推送。
- 提交前必须查看 `git diff --stat` 和 `git diff`,按实际文件与所属包确定提交类型及作用域;不根据用户描述猜测,也不覆盖已有无关改动。
- 提交类型仅使用 `feat`、`perf`、`fix`;中文描述用动词开头,简洁明确,提交信息不超过 50 个字符。
- 单包修改优先以 `package.json` 的 `name` 作为 scope;多个项目或公共基础设施改动可省略 scope,不用目录名代替包名。
- 不使用 `update`、`fix bug`、`修改代码`、`提交代码`、`test`、`wip`、`temp` 等含糊信息。