100 lines
4.6 KiB
Markdown
100 lines
4.6 KiB
Markdown
# Airshelf · 电商 AI 平台 · Codex 工程约定
|
|
|
|
> **本文件由 Codex 启动时自动加载。所有 AI 协作必须遵循以下规则。**
|
|
|
|
---
|
|
|
|
## 项目简介
|
|
|
|
**Airshelf** · AI 短视频带货生成平台 · 5 阶段流水线(商品 → 故事板 → 镜头 → 生成 → 投放)
|
|
|
|
- **设计代号:** Restraint · V2.1 · Firecrawl-aligned
|
|
- **主要工作目录:** [电商AI平台/](电商AI平台/)
|
|
- **Next.js 工程(独立):** [app/](app/)
|
|
- **V1 历史归档:** [v1/](v1/)
|
|
- **V2.1 归档(原 v2.1/):** [v2/](v2/)
|
|
|
|
---
|
|
|
|
## ★ 设计规范铁律(每次涉及页面 / CSS / UI 必读)
|
|
|
|
### 触发条件
|
|
**只要任务涉及以下任一种,必须先 Read [电商AI平台/design.md](电商AI平台/design.md):**
|
|
- 修改 `.html` 文件
|
|
- 修改 `assets/restraint.css` 或任何 `.css`
|
|
- 修改 inline `<style>` 块
|
|
- 添加新页面 / 新组件
|
|
- 调整布局 / 间距 / 颜色 / 字号
|
|
- 用户提到"页面" "样式" "视觉" "组件" "色" "字" "圆角" "间距" 等关键词
|
|
|
|
### 必读章节
|
|
- [design.md §0 AI 协作铁律](电商AI平台/design.md#0--ai-协作铁律每次启动必读) — 必读
|
|
- [design.md §1 设计哲学](电商AI平台/design.md#1--设计哲学) — 价值观
|
|
- [design.md §3 组件清单](电商AI平台/design.md#4--组件清单restraintcss-已实现--不要重发明) — 用现成组件
|
|
- [design.md §8 Don't List](电商AI平台/design.md#8--dont-list绝对禁止--每次自检) — 自检
|
|
|
|
### 7 条铁律
|
|
|
|
1. **任何页面 / CSS 调整前必须 Read [电商AI平台/design.md](电商AI平台/design.md)** — 不读不动手
|
|
2. **检查 [电商AI平台/assets/restraint.css](电商AI平台/assets/restraint.css) 已有组件** — `Grep ".btn|.pill|.input"` 等
|
|
3. **禁止在页面 inline `<style>` 重写共享类**(`.btn` `.pill` `.input` `.modal` `.drawer` `.toast` `.field` `.tabs` `.chip` `.stats` `.list-row` 等)— 要变体回 restraint.css 加
|
|
4. **禁止创建新色值** — 必须用 design.md §2.1 的 token,不写裸 hex
|
|
5. **禁止改动基础 token**(`--heat` `--background-base` `--border-faint` 等)— 改了破坏全站
|
|
6. **完成后对照 [design.md §8 Don't List](电商AI平台/design.md#8--dont-list绝对禁止--每次自检) 逐条自检**
|
|
7. **不确定就问用户**,不要凭感觉发挥 — 用户原话:"我都希望你能遵循我们的设计规范,而不是乱做"
|
|
|
|
---
|
|
|
|
## 设计核心速记(详见 design.md)
|
|
|
|
- **冷灰底** `#f9f9f9` · 主橙 `#fa5d19` · 主前景 `#262626`
|
|
- **全场 8 px 圆角**(Pill / dot 999 例外)· `>12 px` 直接判错
|
|
- **inside-border** 而非真 `border`(hover 不抖动)
|
|
- **单橙锚点** · 全场只有一个 accent · hover 用 alpha 不用换 hue
|
|
- **Mono 装饰必有** · `[ 200 OK ]` `// 05.14` `[ /v2 ]`(品牌签名)
|
|
- **主 CTA 唯一允许阴影** · 4 层橙色发光 · 其他场景禁阴影
|
|
- **Inter(英/数字/装饰)+ Alibaba PuHuiTi(中)** · 字符级 fallthrough
|
|
- **字重仅 3 档** · 400 / 500 / 600 · 700 仅给 Ctrl K 徽标
|
|
|
|
---
|
|
|
|
## Git 工作流
|
|
|
|
- **当前开发分支:** `dev`
|
|
- **主分支:** `main` (生产)
|
|
- **严禁直推 master/main** — 走 dev 分支 → PR → 合并触发 CI/CD
|
|
- **严禁 `--no-verify` 跳过 hook**
|
|
- **Push 规则:** 默认不 push,改完即停 · 用户明确说"push / 推一下"才执行
|
|
- **commit 前不要 amend** — 创建新 commit,避免破坏历史
|
|
|
|
## 文件操作
|
|
|
|
- **三视图 = 单张 16:9 图** · 不要拆成 3 张缩略 · 用 `aspect-ratio: 16/9` 单容器
|
|
- **设计稿优先** · 写代码前必须先读 [电商AI平台/_design_src/](电商AI平台/_design_src/) 设计稿(如果有)
|
|
- **`.pen` 文件加密** · 只能用 pencil MCP 工具,不能 Read/Grep
|
|
|
|
---
|
|
|
|
## 用户偏好
|
|
|
|
- **角色:** UI 设计师 · 不读代码报错,只看最终视觉结果
|
|
- **不需要的:** 终端报错截图、深奥的代码解释、过度的实施细节
|
|
- **需要的:** 简短状态更新、视觉结果对照、清晰的"对/错"反馈
|
|
|
|
---
|
|
|
|
## 关键路径速查
|
|
|
|
| 资产 | 路径 |
|
|
| ---- | ---- |
|
|
| **设计规范(SSoT)** | [电商AI平台/design.md](电商AI平台/design.md) |
|
|
| **共享 CSS** | [电商AI平台/assets/restraint.css](电商AI平台/assets/restraint.css) |
|
|
| **Shell 注入** | [电商AI平台/assets/shell.js](电商AI平台/assets/shell.js) |
|
|
| **视觉样板间(归档)** | [电商AI平台/_archive/design-system.html](电商AI平台/_archive/design-system.html) |
|
|
| **规范理论(归档)** | [电商AI平台/_archive/DESIGN_SPEC_V2.md](电商AI平台/_archive/DESIGN_SPEC_V2.md) |
|
|
| **设计稿源** | [电商AI平台/_design_src/](电商AI平台/_design_src/) |
|
|
|
|
---
|
|
|
|
**违反任何规范规则,用户有权要求重做,无需解释。**
|