d6a42d53a1
按视觉层重设计 z-index（12→14 档），新增节点层/激活节点层/节点工具栏层等 语义 token，并下沉节点内部 stacking context（--node-z-content/overlay/handle） 与 dock 子面板（--dock-z-popover），消除硬编码 z 值。 新增专注模式（避让分屏可切换）：use-focus-mode 管理 localStorage 偏好与小屏 （<1024px）强制避让；助手面板从 flex 改为 absolute + 垂直分槽（顶部 288px 让位活动任务面板），画布区按面板宽度动态 padding；顶栏新增 PanelRight 切换按钮并带强制态反馈。 节点工具栏由 hover+select 触发放为 click-only（选中即显），组件由 canvas-node-hover-toolbar 重命名为 canvas-node-toolbar；移除 project 与 render-model 中冗余的 toolbarNodeId 状态。 活动任务面板 z-index 由 --z-modal-overlay(110) 降至 --z-panel-floating(80)， 归位浮动面板层；AGENTS.md Elevation 同步至 14 档。 Co-authored-by: sikongyue <3155157671@qq.com>
10 KiB
10 KiB
AGENTS.md
本文件约束本项目中的 AI 和自动化开发行为。先遵循用户当前任务，再遵循本文件。
工作方式
- 先读代码、配置和文档，再判断和修改；结论必须有代码或命令输出依据。
- 默认推进到可交付状态，但只改任务相关文件，不回滚或覆盖已有用户修改。
- 优先小而完整的实现，不为假想兼容场景增加分支，不引入无实际收益的抽象。
- 项目尚未上线；除非用户要求，不为旧字段和旧数据编写迁移兼容层。
- 本工作区本地启动后端时必须复用
.local/project-workbench-debug，通过CANVAS_BACKEND_DATA_DIR显式指定；启动前先确认该目录中的现有数据库，禁止直接使用backend/data创建或切换到另一套本地账号数据。 - 按用户要求，写完代码不执行语法检查、测试或构建；交付时明确说明未运行验证。
- 反复出现的项目约束应补充到本文件，规则要具体、可执行。
代码质量
- 页面或服务只保留本层职责。纯算法、协议转换和可独立测试的业务规则放到对应
lib或 service 文件。 - 不新增只改名或透传 props 的组件，不用 helper 掩盖超长主流程；先拆清职责边界。
- 核心业务入口、非直观算法、安全边界和降级策略必须有简短中文注释，说明“为什么”和关键约束；显而易见的赋值不写注释。
- 新文件建议控制在 500 行以内；文件超过 800 行时，新增功能前应优先拆出明确职责。历史超长文件按功能逐步治理，不做无关的大爆炸重构。
- 错误不可静默吞掉。读展示路径允许降级并提示，保存、生成、权限、删除等写路径必须明确失败。
- 通用格式、解析、压缩、加密、日期等能力使用成熟库，不手写底层实现。
后端
- 技术栈：Go、Gin、GORM、SQLite。
handler/只处理 HTTP 入参、调用 service、返回OK/Fail。service/负责业务逻辑、校验、鉴权、默认值、时间和 ID。repository/只负责数据库访问和 GORM 查询；model/只定义结构、枚举和简单模型方法。- 列表接口沿用
model.Query、Normalize、分页和标签筛选；响应保持{ code, data, msg }。 - 新增或调整数据表时同步更新
docs/content/docs/backend/backend-database.mdx。 - 生成、激活、权限、删除和密钥处理属于强校验写路径，不允许用默认值掩盖失败。
前端
- 技术栈：Vite、React、React Router、TypeScript、Ant Design、Tailwind、Zustand、TanStack Query。
- Ant Design 以当前安装版本和官方
llms-full.txt为准；共性主题、按钮、下拉框、弹窗和反馈配置集中在app-theme.ts或AppProviders。 - API 放在
web/src/services/api/；跨页面状态放在web/src/stores/；路由页面、布局和路由配置分别放在pages/、layouts/、router.tsx。 - 画布组件、状态和工具分别放在
components/canvas/、stores/canvas/、lib/canvas/。 - 页面私有组件和 hook 放在页面目录内；只有真实跨页面复用的能力才上移到全局目录。
- 已在全局 store 或 hook 中的状态直接读取，不通过多层 props 透传。复制、下载、确认等跨页面 UI 副作用优先收敛为全局 hook。
- UI 图标优先使用
lucide-react或项目已有 Ant Design 图标；页面文案使用中文。 - 页面身份图标统一使用
WorkspaceSignalIcon，导航与操作图标统一使用lucide-react；同一角色不得并行创造另一套图标容器或视觉语言。 - 页面级分类导航统一使用至少 44px 高的“图标 + 明确文字”入口和一致选中态；项目设置等重要入口不得只藏在无文字图标中。
- 可编辑的工作区、画布和对象名称必须常显铅笔图标并支持单击编辑；双击和右键只能作为快捷方式，不能作为唯一发现路径。画布顶栏名称采用纯文字原位编辑，只显示文本光标，不使用大面积输入框、下划线或自动焦点框破坏标题层级。
- 私有样式优先用 Tailwind 或少量内联样式；
globals.css只放变量、重置、通用样式和必要的第三方覆盖。 - 业务列表、生成记录、媒体和大 JSON 使用
localforage；localStorage只保存极小配置。
画布 UI
- 画布与核心产品界面的视觉交互以 Aceternity UI 的空间层次和组件语言为主基线；优先适配其组件源码并结合当前业务重构，不以旧平面组件外加少量动画作为完成标准。
- Aceternity 组件必须改造成当前项目的命令、状态和主题契约，使用
lucide-react与现有业务 hook；不得为同一入口长期并行维护新旧两套视觉实现。 - 遵循现有画布主题，优先使用
canvasThemes、useThemeStore和 Ant Design token，不硬编码导致明暗主题失配的颜色。 - 工具 Dock、节点表面、弹窗和浮层应具有清晰空间层级；高频创作操作保持紧凑，动效强度按使用频率和画布性能调整，但不退回静态平面方案。
- 图片节点默认保持原始比例；批量生成、多图和助手面板不得长期遮挡主要画布空间。
- 动效服务于状态变化和空间关系，并尊重
prefers-reduced-motion；不要添加持续干扰创作的装饰动画。
Design Token 系统
画布页面使用三层设计 token 架构（Primitive → Semantic → Component），详见 globals.css 和 Wayfinder #96。
三层结构
- Primitive 层：纯值，无语义，不随主题变。包含 9 个维度：色彩（neutral 色板 + 节点类型色板 + 状态色）、间距（4px 栅格
--space-0.5~--space-24）、字号（10 档--fs-micro~--fs-display）、圆角（10 档--r-xs~--r-full）、阴影（--shadow-xs~--shadow-2xl+ glow）、Elevation（14 档--z-canvas~--z-max）、动效（duration 5 档 + easing 5 曲线 + delay 5 档 + motion-scale）、描边（4 档）、不透明度（6 档）。 - Semantic 层：引用 Primitive，随主题切换。包含通用语义色（
--bg/--fg/--border-semantic）、Canvas 语义（--cn-text/--cn-muted/--cn-stroke等）、Aceternity spatial 语义（--cn-spatial-*）、节点类型语义（--cn-type-*）、状态语义（--status-*）。 - Component 层：引用 Semantic，某组件专属。包含 Dock（
--dock-*）、Node（--node-*）、Modal（--modal-*）、Panel（--panel-*）、Prompt 面板（--prompt-panel-*）、进度条（--progress-bar-*）、缩放控制（--zoom-control-*）。
使用规则
- 禁止新增裸值：组件中不得新增
text-[Npx]、rounded-[Npx]、z-[N]、p-[Npx]、gap-[Npx]等硬编码 Tailwind 任意值。必须使用对应 token。- 反例：
className="text-[10px] rounded-[12px] z-[1500]" - 正例：
className="text-tiny rounded-[var(--r-lg)] z-[var(--z-modal)]"
- 反例：
- CSS 变量优先：在 inline style 中使用
var(--token-name)引用 token，不写字面值。 - Ant Design 同步：AntD ConfigProvider 从 CSS 变量反序列化初始化，改 token 则 AntD + shadcn 同步变化。
- Aceternity 风格：
canvas-theme.ts和aceternity-motion.ts从 CSS 变量读取，CSS 是单一信源。 - 新增 token：如需新增 token，先加到 Primitive 层（纯值），再在 Semantic 层引用，最后在 Component 层定义组件专属值。
文档
- README 只保留项目定位、核心功能、快速开始、数据说明和文档入口。
docs/index.md是面向 AI 的短索引；详细内容只写入docs/content/docs/对应页面。- 功能说明、代码地图、待办和待测试分别维护在
features.mdx、code-map.mdx、todo.mdx、pending-test.mdx。 - 已实现但未由用户确认的变化写入
pending-test.mdx；确认后再更新正式功能说明。 - 完成 todo 后先移入
pending-test.mdx，不要直接写入正式功能说明。 CHANGELOG.md的Unreleased只做版本级归纳，不逐条复制待测试内容。- 每次任务结束前检查 todo 和 pending-test；没有功能变化时无需机械修改。
- 文档默认中文，不写过期日期，不暴露密钥、Token 或机器敏感信息。
Git Commit 文案
提交说明必须使用统一格式（不要模仿仓库里旧的纯英文 subject）：
<type>(<scope>): <业务模块> - <变更摘要>
type：feat|fix|refactor|perf|docs|test|build|ci|chore|revertscope：技术域英文；跨模块用*。常用：canvas、platform、auth、api、database、deploy、release、dependencies、security、media、admin业务模块：中文可检索名（如「模型选择」「登录态」），不用纯文件名变更摘要：中文写业务结果；不堆文件列表；不加句末句号；专有名词可英文- 默认不写 body；breaking / 复杂原因 / issue 再写
- 正例：
fix(canvas): 模型选择 - 清空可选项后仍残留已删除模型显示为 undefined - 正例：
chore(release): 版本发布 - publish v0.16.4 - 反例：
fix(canvas): use supported modal style slot（纯英文）、fix: 修了 bug（缺 scope 与模块）
发布
- 发布时将
Unreleased整理为新版本并保留空标题，更新VERSION，提交全部当前改动，再创建对应vX.Y.Ztag。 - 发布 commit 使用：
chore(release): 版本发布 - publish vX.Y.Z - 发布流程不执行编译、测试或构建，除非用户明确要求。
当前边界
- 画布和素材支持登录后端同步；
localForage仍是缓存及后端/OSS 不可用时的降级存储。 - 用户 AI API Key 保存在浏览器本地，任务创建时可能提交到自部署后端；安全说明必须强调 HTTPS 和可信部署。
- 媒体资源支持私有 OSS 或后端文件存储；删除节点或素材不会自动清理 OSS 远端对象。
- Docker 静态资源和生产部署仍需按待测试清单验证，不得写成已全面生产验证。