d22526506d
* feat(canvas): 设计token系统 - 建立三层架构骨架 #94 #96 建立 Primitive→Semantic→Component 三层设计 token 体系，覆盖 9 个维度： 色彩/间距/字号/圆角/阴影/Elevation/动效/描边/不透明度。 - Primitive 层：纯值无语义，含 neutral 色板+节点类型色板+状态色、 4px 栅格间距、10档字号、10档圆角、阴影+glow、12档 z-index、 动效(duration+easing+delay+motion-scale)、描边、不透明度 - Semantic 层：引用 Primitive，随主题切换，含通用语义色、 Canvas 语义(--cn-*)、Aceternity spatial 语义、节点类型语义、状态语义 - Component 层：引用 Semantic，含 Dock/Node/Modal/Panel/Prompt面板/ 进度条/缩放控制专属 token - @theme inline 映射：节点类型色、状态色、Canvas 语义色、字号映射到 Tailwind utility - prefers-reduced-motion 三级降级(L0正常/L1简化/L2禁用) - AGENTS.md 新增 Design Token 使用规范，禁止新增裸 px 值 - 附带修复 canvas-drawing-excalidraw-editor.tsx TS7006 类型注解 - 附带修复 canvas-drawing-editor-modal.tsx TS2339 engine 字段缺失 Wayfinder 决策来源：#95 #96 #97 #98 #99 * fix(canvas): 设计token系统 - 修复CSS变量循环引用和命名兼容性 #94 #96 修复两个问题： 1. CSS变量循环引用：Primitive层 --color-node-*/--color-status-* 与 @theme inline 中的 --color-node-*/--color-status-* 同名，经 Semantic 层中转后形成循环（A→B→A）。改用 --palette- 前缀隔离 Primitive 色板， 打断循环链路。 2. 变量名小数点兼容性：--space-0.5/1.5/2.5/3.5 中的小数点被部分 CSS linter 误判为类选择器。改为 --space-half/-1-half/-2-half/-3-half， 保持语义清晰的同时提升工具链兼容性。 * refactor(canvas): 画布核心组件 - 迁移硬编码值到设计token #94 批次1：5个画布核心组件的裸 text-[Npx]/rounded-[Npx]/z-[N] 替换为 对应设计token，统一视觉语言： - canvas-node.tsx：text-[10/11/9/17px]→fs-tiny/label/micro/heading-lg， rounded-[18px]→node-radius - canvas-node-hover-toolbar.tsx：text-[11/17/10/9px]→fs-*， rounded-[14/9px]→dock-radius/dock-item-radius，z-[70]→z-panel-floating - canvas-toolbar.tsx：text-[9/10/11px]→fs-*， rounded-[17/16/11/10px]→panel-radius/dock-item-radius-*， z-[30/40]→z-toolbar/z-toolbar-floating - canvas-assistant-panel.tsx：text-[8/9/10/11px]→fs-* - canvas-script-node.tsx：text-[9/10/11px]→fs-* 视觉零回归（token值与原硬编码值一致），代码可维护性提升。 * refactor(canvas): 画布辅助组件 - 迁移硬编码值到设计token #94 批次2：6个画布辅助组件的裸 text-[Npx]/rounded-[Npx]/z-[N] 替换为 对应设计token： - canvas-style-picker-modal.tsx：text-[10/11px]→fs-tiny/label - canvas-file-drop-overlay.tsx：z-[110]→z-modal-overlay， rounded-[28/20px]→r-5xl/r-3xl - canvas-character-reference-node.tsx：text-[10px]→fs-tiny - canvas-drawing-editor-modal.tsx：text-[11px]→fs-label - canvas-video-prompt-tools.tsx：z-[1500]→z-toast， rounded-[12/10px]→r-lg/dock-item-radius - asset-picker-modal.tsx：text-[10px]→fs-tiny 视觉零回归（token值与原硬编码值一致）。 * refactor(*): 全项目硬编码值 - 批量迁移到设计token #94 批次3：全项目 .tsx 文件中 372 处裸 text-[Npx]/rounded-[Npx] 批量 替换为对应设计token，剩余 25 处无直接 token 对应的低频值保留。 替换覆盖（按频率）： - text-[10px]→fs-tiny (132处) - text-[11px]→fs-label (100处) - text-[9px]→fs-micro (45处) - text-[12px]→fs-caption, text-[13/14px]→fs-body, text-[15px]→fs-body-lg - text-[18px]→fs-heading-lg, text-[22px]→fs-title, text-[8px]→fs-micro - rounded-[9/10px]→dock-item-radius, rounded-[12px]→r-lg - rounded-[14px]→dock-radius, rounded-[16px]→r-2xl - rounded-[17px]→panel-radius, rounded-[8px]→r-md 涉及 components/ 和 pages/ 下所有 .tsx 文件。 视觉零回归（token值与原硬编码值一致）。 * feat(canvas): 节点视觉层次规范 - 色带+状态徽章+四态递进 #97 #94 基于 Wayfinder 地图 #97 决议执行节点视觉重设计： 1. 节点类型色带（决策1） - 新增 nodeTypeColorVar() 函数，10种节点类型对应色带色 - 节点左侧3px色条，引用 --cn-type-* token - 远距离最强信号，用户扫视画布即可识别节点类型 2. 节点状态徽章（决策2） - 新增 NodeStatusBadge 组件，loading/success/error 三态 - 左上角圆角徽章，backdrop-blur 玻璃质感 - success 态 2s 后自动淡出（canvas-status-success-fade 动画） 3. 四态递进视觉权重（决策3） - idle：无额外阴影 - hover：轻微抬升阴影（16px 48px） - selected：2px 边框环（accent.primary 40% 透明度） - selected-primary：4px 软色环 + resize handle - active：6px 外发光环 + inner glow（最强强调） - 120-150ms ease-out 过渡 4. 阴影迁移 - boxShadow 从硬编码改为分层语义化表达 - 边框色 hover 态使用 color-mix 动态加深 Closes #97 --------- Co-authored-by: sikongyue <3155157671@qq.com>
118 lines
10 KiB
Markdown
118 lines
10 KiB
Markdown
# 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（12 档 `--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）：
|
||
|
||
```text
|
||
<type>(<scope>): <业务模块> - <变更摘要>
|
||
```
|
||
|
||
- `type`：`feat` | `fix` | `refactor` | `perf` | `docs` | `test` | `build` | `ci` | `chore` | `revert`
|
||
- `scope`：技术域英文；跨模块用 `*`。常用：`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.Z` tag。
|
||
- 发布 commit 使用：`chore(release): 版本发布 - publish vX.Y.Z`
|
||
- 发布流程不执行编译、测试或构建，除非用户明确要求。
|
||
|
||
## 当前边界
|
||
|
||
- 画布和素材支持登录后端同步；`localForage` 仍是缓存及后端/OSS 不可用时的降级存储。
|
||
- 用户 AI API Key 保存在浏览器本地，任务创建时可能提交到自部署后端；安全说明必须强调 HTTPS 和可信部署。
|
||
- 媒体资源支持私有 OSS 或后端文件存储；删除节点或素材不会自动清理 OSS 远端对象。
|
||
- Docker 静态资源和生产部署仍需按待测试清单验证，不得写成已全面生产验证。
|