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

11 KiB

项目协作规范

默认分支与工作目录

  • 新增功能、新增文件、修复问题和重构,默认全部在本项目根目录的 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 或自制折叠控件;修改同类区域时同步统一现有实现。
  • 维持项目现有简洁、扁平的视觉风格。用标题、简短说明、留白和对齐区分普通功能区域,避免无意义的底色、边框和装饰线。
  • 页面文案保持精简,说明应帮助用户理解当前操作;不把大量错误、技术细节和重复提示堆在设置页面。

全屏抽屉与关闭入口

  • 新建剧本、项目全局配置、拆解设置、拆解问题等已确认使用全屏的界面统一复用 AppDrawer。后续同类复杂表单、设置和问题处理界面默认沿用全屏抽屉;简短确认或轻量提示仍可使用 AppDialog。
  • 全屏必须同时覆盖容器与正文:内容使用可用的完整宽度,不能只把外壳放大而保留原弹窗的固定宽度或居中最大宽度。
  • 标题区和底部操作区固定,只有正文独立滚动。长内容不能把关闭或提交按钮挤出视口,也不能产生页面与抽屉重复滚动。
  • 抽屉标题、说明、正文和底栏左右边界统一。复用公共抽屉的桌面、移动端内边距;正文 padding-top 保持为 0,不要额外叠加顶部空白。
  • 所有弹窗和抽屉底部至少保留一个可见的“关闭”或“取消”按钮,不能只有右上角叉号。底部操作使用公共组件的 footer 插槽,避免正文末尾再放一套底栏或重复关闭按钮。
  • 关闭、取消统一为灰色底面和中性文字的普通按钮,不使用绿色主按钮;右上角关闭图标的尺寸、底色与交互反馈也统一复用公共样式。
  • 提交期间按真实业务状态防止重复操作及意外关闭;普通只读加载不能无故阻止用户关闭。关闭、切换或定位后,不回填已失效的异步结果。

布局、说明与间距

  • 页面外边距、模块间距优先复用 --app-content-padding、--app-content-gap;表单与抽屉内部复用对应公共组件的间距,不在各页面随意添加不同数值。
  • 同级模块使用一致的标题、说明、字段间距和上下留白。需要说明时采用“模块标题 + 一句简短说明”,例如画布设置、图片配置、视频配置、动作与物理规则;优先复用 WorkspaceSectionHeading。
  • 新建剧本等长表单默认每个字段单独占一行并铺满内容宽度;不因改成全屏就自动把原来的字段挤成两列。
  • 图片、视频等已有明确分组的并列模块可以保留协调的分栏,窄屏改为单列;同一行的标签、控件及操作必须分别对齐,不能因说明或校验消息出现而上下错位。
  • 行内按钮按输入控件本身的基线对齐,不能按包含标签的整块区域垂直居中。动态例外行中的移除按钮与输入框底部对齐,使用 Trash2 等现有图标,不再显示“移除”文字,并提供可访问名称。
  • 项目生成配置等普通表单分区不铺大块背景色,使用标题、说明和统一间距组织;错误、成功等有明确状态含义的提示区域才使用对应柔和底色。

按钮、图标与状态颜色

  • 绿色背景、白色文字用于保存、提交、开始生成等主要执行操作;关闭、取消和普通辅助操作使用中性样式。
  • 错误、校验未通过、需要修复的区域使用柔和浅红背景,深色主题使用对应柔和深红底面。禁止使用上下两条绿色横线表示错误或待修复状态,也不能借用绿色选中态来标记错误。
  • 错误入口按钮的文字、图标和焦点提示与红色底面保持一致;默认、悬停、按下、聚焦各状态都不能被主题主色覆盖成绿色。保留清晰的键盘焦点提示。
  • 只有执行完成且结果明确通过校验时,成功任务区域才使用柔和浅绿背景。执行结束但校验失败、质量待审或结果未确认时,不能显示成绿色成功状态,也不能用满格绿色进度条暗示业务成功。
  • 工具栏中相邻按钮保持一致的高度、内边距、图标大小和间距。问题入口使用图标加文字;分镜结构校验失败时文案为“分镜校验未通过”,其他问题按真实类型命名。
  • 移动端的工具栏操作优先只显示图标,保留完整的 aria-label、提示文本和足够点击区域;普通表单的底部关闭、取消、提交按钮仍保留文字。
  • 页面左侧汇总状态在运行、成功、失败等状态下均有意义,应保留;右侧操作入口负责打开对应处理界面,避免把状态展示和操作混成重复文案。

设置、问题处理与任务进度

  • 拆解设置与问题处理分开:设置界面负责模块选择、分组预览、启动拆解、候选确认与提交;问题界面负责错误查看、分镜定位、人工修订、读取修复清单及阶段恢复。
  • 不在拆解设置中重复堆放详细错误列表和修复说明;问题按剧集、节拍、镜头分组并去重,保留后端原始问题及可定位位置。
  • 从问题界面定位正文时,先关闭抽屉,等离场和焦点约束释放后再定位,不能同时叠加两个主界面。
  • 后端从其他入口启动或重新执行任务时,前端也应发现任务并显示真实运行阶段、进度、作用范围及更新时间;重新进入页面后能够恢复观察,不能只依赖前端本次点击形成的加载状态。
  • 执行状态与质量校验结果分别表达,不能把“执行完成”直接等同于“校验通过”;没有真实进度或结果时明确显示待确认,不伪造百分比。
  • 拆解执行中暂不显示“查看诊断”等需要稳定结果的入口。问题可以只读查看,但人工修改、候选提交、修复和恢复操作应遵守真实活动任务锁,避免冲突。
  • 拆解任务卡片与相邻模块采用统一边距和状态底色,必要的阶段、范围、进度和时间直接简洁展示;不要把重要信息只藏在“任务详情”折叠中,也不默认展示无助于操作的内部编号或原始数据。

表单校验与交互时机

  • 打开表单、加载已有配置或添加一条空白例外时,不立即展示红色校验错误。
  • 点击保存、提交时再执行完整校验,阻止不完整请求;需要字段交互校验时,只在用户已操作该字段或已尝试提交后显示。
  • 用户修改相关内容后及时清除或更新旧错误,不能让已经失效的提示长期挂在表单上。
  • 必填标记、字段提示和错误信息保持统一位置与间距;删除行、增添行和错误出现时,操作按钮仍应与对应控件对齐。

页面验收

  • 涉及页面或交互的改动,必须在已有本地 Chrome 标签页使用 localhost 验证后才算完成,不能只根据代码、构建或 DOM 测试声称布局通过。
  • 验证本次改动涉及的桌面、移动端、长内容滚动、固定底栏及必要的加载、错误、成功状态;检查普通、悬停和键盘聚焦时的颜色、对齐与可访问名称。
  • 界面验收不得为了制造状态而触发真实付费生成、覆盖正式结果或提交用户数据;使用现有状态、只读操作和合适的自动化测试验证。
  • 测试与检查按改动范围执行;纯文档变更无需启动页面或重复完整构建。报告时区分自动化检查与真实浏览器验证,并明确未完成项,不把尝试操作当作验收通过。

提交规范补充

  • 仅用户明确要求“提交”时才提交,“提交并 push”才同时授权推送;不因界面修改完成而自动提交或推送。
  • 提交前必须查看 git diff --stat 和 git diff,按实际文件与所属包确定提交类型及作用域;不根据用户描述猜测,也不覆盖已有无关改动。
  • 提交类型仅使用 feat、perf、fix;中文描述用动词开头,简洁明确,提交信息不超过 50 个字符。
  • 单包修改优先以 package.json 的 name 作为 scope;多个项目或公共基础设施改动可省略 scope,不用目录名代替包名。
  • 不使用 update、fix bug、修改代码、提交代码、test、wip、temp 等含糊信息。