MuseDock AGENTS.md

项目协作规则

分支与工作区约束

• 日常开发默认基于 dev 分支进行，包括代码修改、文档修改、依赖调整、配置变更、格式化和提交。
• 可以在 dev 或从 dev 派生的功能分支上开发；禁止直接在 main 上承接日常开发。
• 在修改任何文件前，必须先确认当前 Git 分支。
• 在修改任何文件前，应检查 git status --short，识别已有未提交改动。
• 不得回滚、覆盖、格式化或顺手修改与当前任务无关的用户改动。
• 如果当前分支是 main，且任务不是发布、同步或将 dev 合并到 main，必须立即停止工作，不得编辑文件、生成文件、格式化、提交或推送，并提醒用户先切换到 dev 分支。
• main 分支只用于稳定版本、发布、同步远端状态或从 dev 合并，不直接承接日常开发。
• 当用户明确要求将 dev 合并到 main，可以切换到 main 执行合并和推送；合并完成后应切回 dev 继续开发。
• 如果用户要求在 main 上直接修改业务代码或文档，需要先复述风险并等待用户再次确认。

修改范围与验证

• 修改（Edit/Update/覆盖 Write）任何已存在的文件前，必须先读取（Read）该文件的当前内容再改：工具层会直接拒绝未读先改的操作，且先读才能确认已有未提交改动与最新状态。
• 每次修改应聚焦当前任务，避免无关重构、目录重排、批量格式化或大面积样式迁移。
• 完成代码修改后，应根据改动范围运行最小必要验证，例如前端构建、类型检查、相关单测或手动启动验证。
• 如果验证无法运行，必须在结果说明中写明原因和剩余风险。

用户可见文案

• 默认所有展示给用户看的文案必须使用中文，包括按钮、提示、弹窗、状态、错误信息、空状态、加载文案和操作结果。
• 技术专有名词、接口字段、品牌名、文件名、命令、环境变量、第三方服务名可以保留英文，例如 OpenAI API、ffmpeg、OPENAI_API_KEY。
• 如果必须展示后端或第三方返回的英文错误，应尽量补充中文解释，避免只把英文原样抛给用户。

前端 UI 与样式

• 新增或重构面向用户的前端 UI 时，默认优先使用 Tailwind CSS utility class 与官方 shadcn/ui 组件体系。
• shadcn/ui 接入默认参考 Vite 安装文档：https://www.shadcn-ui.cn/docs/installation/vite 。
• 通用控件应优先复用项目已有 shadcn/ui 组件；确需新增时，使用项目当前依赖和配置通过 CLI/registry 引入或同步官方组件，避免无关升级。
• 按钮、输入框、下拉框、弹窗、标签页、徽标、提示、表格、Tooltip、Checkbox、Switch 等通用控件，应优先来自官方 shadcn/ui 组件；如果确需改造，优先在引入的组件基础上做项目化调整，并保留清晰来源和 API 边界。
• 避免继续向 frontend-react/src/styles.css 追加大段跨页面全局样式；确需新增 CSS 时，应优先限制在小范围组件、复杂布局、媒体编辑器、第三方渲染容器或 Tailwind 难以清晰表达的场景，并保持选择器边界清楚。
• 重构历史页面时采用渐进迁移，不要求一次性把已有手写 CSS 全量改为 Tailwind；每次迁移应同步清理已不再使用的旧样式。
• 复杂工具界面（例如视频编辑器）可以阶段性保留局部 CSS，但新增通用操作控件和状态展示仍应优先走官方 shadcn/ui 组件。

接口加载状态

• 所有会触发接口请求的用户操作，必须在请求期间展示明确的 loading 提示。
• loading 提示应说明正在执行的动作，例如“正在加载评论和二级评论...”“正在准备素材...”“正在请求音频转写...”。
• 请求完成后必须更新为成功、失败、未配置、需登录、需验证等明确状态，不能让 loading 状态悬停。
• 新增接口调用时，需要同时检查对应按钮禁用态或重复点击保护，避免用户连续触发同一请求。
• 新增或修改接口调用时，应尽量区分网络失败、未登录、权限不足、配置缺失、第三方限流和未知错误，并给出中文可操作提示。

依赖与敏感信息

• 不得为少量逻辑轻易新增依赖；新增依赖前应优先检查标准库、浏览器原生能力、现有依赖和项目已有工具。
• 确需新增依赖时，应说明用途，并同步更新对应锁文件。
• 不得提交真实账号、Cookie、Token、API Key、代理密码或其他敏感信息。
• 示例配置只能使用占位值；本地密钥应优先通过 .env、本地配置文件或运行环境读取。