---
name: panel-project-deploy
description: 自动化克隆、初始化、品牌化、Docker 部署并提交项目，同时强制将前端页面改造成炫酷的科技感玻璃面板风格。适用于“初始化并部署项目”“项目页面改版”“面板风格 UI”“科技感大屏/仪表盘”等请求。
---

# 项目初始化部署、面板风格 UI 改造与外包交付

## 目标

在原项目初始化与部署能力基础上，完成从 Git 克隆、项目分析、品牌信息替换、Docker 构建启动、健康验证到 Git 提交的完整流程，并将前端主要页面升级为**现代化、炫酷、科技感的面板风格 UI**。

面板改造是必做项，但不能破坏原有业务逻辑、路由、接口、权限流程和数据结构。

本技能对齐外包交付标准：完成部署、品牌化改版、素材录制归档、标准化 README、7 项交付物与
7 条验收标准，并遵守保密、知识产权归属和售后 SLA。

## 对外材料来源口径规则（甲方可见材料）

凡交付给甲方或其终端客户看到的 README、界面、截图、录屏、交付清单、演示文档、注释、配置及资源文件名，
均不得主动出现其他项目名称、外部仓库链接、原作者信息、致谢、迁移说明、版本对比或“基于某项目改造”等表述。

1. README 与一切对外文档使用当前产品口径，只描述本系统的功能、架构、部署、运维和授权使用方式。
2. 交付包内只放当前产品界面截图，文件名使用页面语义化中文/英文名称，不出现 before/after、改造前、原版等字样。
3. 内部初始启动截图仅用于质量核对，可命名为 `baseline-<页面>.png`，必须与对外交付物隔离，严禁打包给甲方。
4. 清理依法可移除的第三方公司名、商标、LOGO、水印、联系方式、二维码、默认域名、包元数据和注释线索。
5. 法律边界：MIT、Apache-2.0、BSD 等许可证要求随源码保留的版权声明、许可证全文或 NOTICE 文件不得删除、
   替换或改写；随源码交付时必须完整保留。不得在 README 中虚假声明全部代码均由交付团队自主原创。
6. 面向甲方的演示包可不放入源码和 LICENSE，仅保留当前产品 README、截图、录屏和必要部署说明；
   源码包与演示交付包应分开管理。
7. 本规则约束对外呈现口径，不替代、不免除任何第三方许可证或法律规定的合规义务。

## 20 步工作流

| 步骤 | 名称 | 必做/跳过 | 要求 |
|---:|---|---|---|
| 0 | 克隆项目 | 必做 | 不修改任何业务代码 |
| 1 | 项目完整度评估 | 必做 | 判断前端资源、组件、样式入口、启动方式是否完整 |
| 2 | 项目整体分析 | 必做 | 识别框架、路由、主题色、布局、启动命令与端口策略 |
| 3 | 初始版本基线启动（内部） | 必做 | 改代码前用项目现有方式跑通初始版本；仅内部核对，不产生交付物 |
| 4 | 初始界面基线截图（内部） | 必做 | 代码零改动时采集初始界面用于内部对比；严禁进入交付包 |
| 5 | Docker 配置生成 | Docker 项目必做，非 Docker 跳过 | 不改变前端视觉 |
| 6 | 页面信息与品牌名称修改 | 必做 | 建立全局面板设计变量和玻璃面板基础样式 |
| 7 | Logo 生成与替换 | 必做 | 新 Logo 适配深色面板、发光边框和 Favicon |
| 8 | 版权与第三方标识规范 | 必做 | 清理依法可移除的来源和商业标识；源码许可证要求保留的版权/许可/NOTICE 不得删除 |
| 9 | 页脚、导航与社区链接 | 必做 | 导航、页脚改成半透明悬浮面板风格；页脚放「开源社区 https://www.gitcc.com/」和「GCC AI Coding https://www.gitvv.com/」超链接 |
| 10 | 登录页面 | 必做 | 改成居中玻璃面板、发光输入框、动态背景 |
| 11 | AI 对话功能 | 必做 | 对话窗口、设置抽屉、消息气泡面板风格；按用户指定服务商预填 Base URL 与默认模型，并内置图文教程 |
| 12 | 示例数据 | Docker 项目必做，非 Docker 跳过 | 数据卡片和列表面板承载 |
| 13 | CORS 配置检查 | Docker 项目必做，非 Docker 跳过 | 不改变 UI |
| 14 | 端口检查与分配 | Docker 项目必做，非 Docker 跳过 | 不改变 UI |
| 15 | **改造后构建与启动** | 必做 | Docker 项目构建镜像启动容器；非 Docker 项目手动构建并启动改造版 |
| 16 | 健康验证 | 必做 | 服务健康、面板审计 0 违规、全功能走查无报错 |
| 17 | 产品截图与全功能录屏 | 必做 | 采集当前产品全套高清界面截图（中性文件名）+ 全功能演示录屏；无 before/after |
| 18 | 标准化 README 与版本归档 | 必做 | 按当前产品口径编写 README；不主动出现来源/致谢/版本对比；按授权决定是否提交 |
| 19 | 交付物核查 | 必做 | 运行交付物阻断式核查，7 项交付物齐备并生成交付 manifest |

非 Docker 项目跳过步骤 5、12–14，其余步骤仍有效；步骤 3–4 产物仅内部留存，不对外交付。

## 素材采集时序（内部核对 + 对外素材）

内部基线素材用于核对改造完整性，对外素材只呈现最终产品：

1. **内部基线**：先启动初始版本（步骤 3），代码零改动时截取 `baseline-<页面>.png`（步骤 4），再开始修改代码。
   - 克隆完成后，先用项目自身现有方式（Dockerfile / README 命令 / 本地脚本）确认初始版本可访问；
   - 初始版本无法启动时，才允许使用仓库中的历史截图作为内部核对依据；
   - 基线素材保存到内部目录，任何情况下都不进入交付包。
2. **对外截图与录屏**必须在改造完成、重新构建部署并通过健康验证（步骤 16）后采集（步骤 17），禁止使用半成品。
3. 对外界面截图必须页面全覆盖，使用 `login.png`、`overview.png`、`campus-state.png` 等中性页面名称。
4. 全功能录屏应完整展示登录、概览大屏、业务页面、AI 配置、系统管理、表格/弹窗交互等核心流程；
   画面无卡顿、无黑屏、无报错，录屏界面必须与最终截图一致。
5. 素材目录、采集时间、对应版本（git commit 或“未提交工作区”）记录在内部 manifest；对外清单只列甲方需要的信息。

## 执行原则

1. **先识别，再改造**：确认前端框架、样式方案、路由入口、布局组件、主题色和可复用组件。
2. **小步修改**：优先修改全局样式、布局组件、导航、页脚、登录页、首页/仪表盘和 AI 页面。
3. **保持功能稳定**：不改后端协议、数据库结构、权限模型和业务路由语义。
4. **适配不同技术栈**：React、Vue、Angular、原生 HTML、Tailwind、CSS Modules、Less、SCSS、Ant Design、Element Plus 均可实现，不强制引入新的重型 UI 框架。
5. **响应式和无障碍**：面板效果必须在移动端可用，文本对比度达标，键盘焦点可见。
6. **动效克制**：允许发光、渐变、悬浮、过渡和背景动画，但必须尊重 `prefers-reduced-motion`。
7. **对外材料中性化**：对外材料不主动出现其他项目名称、链接、原作者、致谢或版本对比；源码许可证要求保留的内容必须保留。
8. **痕迹清理范围**：在合法合规前提下清除第三方商业标识和来源宣传线索；内部留档不进入交付物，法定版权与许可声明不得删除。
9. **保密与成果归属**：项目需求、交付资料、客户信息不得外泄；交付成果不得私自转发、售卖、复用或二次分发。
10. **交付留痕**：截图、录屏、审计报告、交付清单必须完整可溯源，禁止把未走查/未测试的功能描述为“已完成”。

## 主题一致性强约束

1. 面板风格 UI 的第一优先级是**全组件主题统一和文字可读**，第二优先级才是发光、模糊和动画。
2. 项目使用组件库时，必须从官方主题入口配置暗色 Token：
   - Ant Design：`ConfigProvider` + `theme.darkAlgorithm`，在 Umi 项目中通过 `antd.configProvider.theme` 配置。
   - Element Plus / ElementUI：使用官方 dark CSS variables 或项目的暗色主题变量。
   - MUI：`createTheme` + `CssVarsProvider/ThemeProvider`。
   - Vuetify / Angular Material：启用对应 dark theme。
3. CSS 覆盖只能作为玻璃质感和局部修正，不能替代组件库官方暗色主题。
4. 所有浮层都要检查：Modal、Drawer、Select Dropdown、DatePicker、Popover、Tooltip、Upload、Cascader、AutoComplete、ColorPicker。
5. 所有内容容器都要检查：Card、Table、Descriptions、Tabs、Collapse、List、Form、Pagination、Empty、Result、Spin 容器。
6. 如果某个业务页面必须保留浅色区域，必须同时使用浅色文字风格和浅色周边布局；禁止把浅色组件直接嵌入深色页面造成黑白割裂。
## 项目概述大屏强制要求

每个项目**必须**新增一个炫酷的「项目概述大屏」页面（如路由 `/overview`），导航菜单顶部入口名称为「概览」。要求：

1. **接入真实可展示数据**：通过后端聚合接口输出，至少覆盖
   - 核心指标卡片：设备/摄像头总数、在线数与在线率、离线数、报警数（待处理/已处理）、规则数、用户数等（按项目实际实体取数，禁止纯静态假数据）；
   - 趋势图：近 7 天（或可配置周期）业务/报警趋势；
   - 分布图：设备/业务状态结构（在线/报警/离线等）；
   - 最新动态：最新事件实时滚动列表；
   - 实时时钟，数据定时（建议 10 秒）自动刷新。
2. **视觉炫酷、符合面板体系**：深色科技基底 + 玻璃面板 + 霓虹边缘 + 大标题光效；图表与卡片风格统一，支持大屏分辨率投放与响应式降级。
3. **图表实现适配项目**：优先复用项目已有图表库；未引入时可用 SVG/CSS 自绘（折线、环形等），
   不强制为单个大屏新增重型依赖。
4. **可访问性**：图表需配文字图例与数值，动态滚动可暂停，文字对比度通过审计。
5. 该页面纳入改造后截图、录屏与 UI 审计范围。

## 社区与外部链接要求

1. 页脚必须包含两个可点击超链接（新标签页打开）：
   - 开源社区：[https://www.gitcc.com/](https://www.gitcc.com/)
   - GCC AI Coding：[https://www.gitvv.com/](https://www.gitvv.com/)
2. README 需在显著位置（如「相关链接」章节）提供上述两个链接；概览大屏页面头部同样要展示这两个超链接。
3. 链接文案与样式符合面板主题，hover 有发光反馈；不得写成失效或错误地址。

## AI 对话对接强制要求

步骤 9 除面板视觉外，当用户指定 AI 服务商（如 TokenFree、官方 OpenAI、第三方中转等）时，必须完成：

1. **默认配置预填**：在 AI 设置的默认值中写入用户指定的 Base URL 与默认模型，而不是保留模板里的旧服务商。
   - OpenAI 兼容网关的地址必须带 `/v1`（如 `https://www.tokenfree.com/v1`）。
   - 模型 ID 必须以服务商实际支持的字符串为准（可通过其定价/模型列表页核实，例如 TokenFree 上为 `kimi-k2.6`），禁止凭名称臆造。
2. **本地缓存版本迁移（强制）**：设置存储 key 必须带版本后缀（如 `parking-ai-settings-v2`）。
   - 切换服务商时升级版本，避免老用户 localStorage 中的旧 Base URL / 旧模型覆盖新默认值。
   - 如需迁移旧数据，只迁移用户自填的 API Key，地址与模型强制使用新默认值。
3. **内置使用教程（强制）**：设置抽屉/弹窗内必须包含与面板主题一致的教程块，内容至少覆盖：
   - 服务商官网链接（新标签页打开）与一句话说明；
   - 注册 / 登录 / 邮箱验证；
   - 在控制台创建并复制 API Key（说明 Key 前缀，如 `sk-`）；
   - 粘贴 Key → 测试连接 → 保存的完整操作路径；
   - 明确展示 Base URL、默认模型，并说明 Key 仅保存在本地浏览器；
   - 说明可替换为该服务商支持的其他模型。
4. **README 同步**：项目 README 必须增加对应「AI 对话使用教程」章节（含配置表与步骤）。
5. **协议兼容**：调用遵循 OpenAI 兼容协议（`POST {baseUrl}/chat/completions` 流式、`GET {baseUrl}/models` 测试连接）；未拿到用户 Key 时不得伪造 Key，也不得把测试失败谎报为成功。
6. **教程 UI 主题**：教程中的列表、行内代码、链接、注释文字必须使用深色玻璃面板配色，禁止出现白底黑字的教程块嵌入深色抽屉。

## 页面信息修改的强制要求

步骤 4 不能只替换文字，必须同时完成以下内容：

1. 替换浏览器标题、导航品牌名、页脚系统名、README 中面向用户的新项目名称。
2. 建立统一设计变量：背景色、主色、辅助光效色、面板背景、边框、模糊度、圆角、阴影和间距。
3. 至少为这些区域应用面板风格：
   - 顶部导航 / 侧边栏
   - 首页或仪表盘
   - 主要数据卡片
   - 表格、表单、弹窗或抽屉
   - 登录页
   - AI 对话页
   - 页脚
4. 主要页面应呈现“深色科技基底 + 半透明玻璃面板 + 霓虹边缘光 + 渐变光斑/网格背景”的视觉方向；如果原项目必须保持浅色主题，则使用浅色玻璃拟态和柔和外发光。
5. 面板不能只靠边框区分，应组合使用：半透明背景、模糊、内外发光、渐变边缘、角标或装饰线、悬浮位移和状态光效。
6. 所有新增页面和核心组件要保持统一，不允许登录页科技感很强而业务页面仍是完全旧风格。

详细样式规范、组件结构、CSS/Tailwind 示例和验收清单见 [references/panel-ui.md](references/panel-ui.md)。执行页面改造前必须读取该文件。

## 阻断式视觉验收（必须执行）

页面改造完成后，不能只凭肉眼抽查或截图判断；必须在应用启动后执行技能内置脚本：

```bash
python scripts/panel_ui_audit.py \
  --base-url http://localhost:<端口> \
  --hash-routes \
  --username <账号> \
  --password <密码> \
  --submit-text <登录按钮文本> \
  --routes /页面1,/页面2,/页面3 \
  --open-selector '<抽屉或弹窗触发选择器>' \
  --wait-until domcontentloaded \
  --out .Codex/reports/panel-ui-audit.json
```

非 hash 路由去掉 `--hash-routes`；有多个抽屉、弹窗时重复传入 `--open-selector`。含轮询、WebSocket、SSE 或定时刷新的页面使用 `--wait-until domcontentloaded`，不要等待永远无法稳定的 `networkidle`。

硬性规则：

1. 健康验证步骤必须运行该脚本，进程退出码为 0 且报告为 0 violations 才算通过。
2. 审计范围必须覆盖登录页、首页/仪表盘、表格/列表页、表单页、详情页、AI 页面、系统管理页，以及所有 Modal、Drawer、Select、DatePicker、Popover、Tooltip 等浮层。
3. 脚本同时检查两类 P0 问题：文字/背景对比度低于 WCAG 阈值，以及浅色组件嵌入深色外壳造成“外黑内白”。
4. 地图、视频、画布等媒体区域可排除媒体内容本身，但悬浮状态、标签、操作按钮、提示文字和空状态仍必须通过审计。
5. 若审计报出问题，先修复主题 Token 和组件样式，再重新构建、部署和审计；不能通过忽略脚本、删除选择器或降低阈值的方式完成任务。
6. 用户明确要求“不推送代码”时禁止任何 `git push`；本地提交仍需遵守用户授权。若任务是修复/验收且用户未要求提交，则保留工作区变更并明确说明。
7. 默认账号密码必须来自实际初始化逻辑，不能猜测；最终回复和 `.Codex/reports/` 验收材料中要写明账号来源。

## 外包交付强制规范（合同对齐）

执行外包交付类任务前必须读取 [references/delivery-contract.md](references/delivery-contract.md)。核心约束：

1. **六项服务全覆盖**：部署运行、界面改造、版权痕迹清理、素材录制归档、标准化文档、售后支撑，缺一不可。
2. **痕迹清理与开源合规的边界（红线）**：
   - 清除第三方公司名、LOGO、商标、水印、弹窗、页脚、版权注释中的商业归属与联系方式；
   - LICENSE 重写为权属方中性版权声明，原作者、原许可证全文与原项目链接不出现在交付物中；
   - 清理后用 `grep -rniE` 对原标识、原作者、原链接等关键词全文检索，交付物中不得命中。
3. **素材归档（步骤 17）**：
   - 对外只提供当前产品的高清界面截图，页面全覆盖、文件名中性，不出现 before/after；
   - 全功能逐一操作演示录屏，无卡顿黑屏，完整演示所有功能；
   - 素材分类整理，上传甲方指定网盘（默认百度网盘），链接写入交付清单，保证长期有效、可访问下载。
4. **标准化 README（步骤 18，12 项必备）**：一句话简介、功能描述（逐条配图）、行业痛点、技术优势、
   应用场景、目标行业人群、商业价值、技术架构（含拓扑图）、环境依赖、快速开始、完整部署教程
   （Docker 优先，无 Docker 提供可复现的手动步骤）、中性的版权与使用说明。
5. **交付物 7 项**：源码、当前产品界面截图、全功能录屏、网盘归档链接、标准化 README、
   Docker 部署脚本（或不适配的书面说明）、环境依赖清单与部署注意事项。
6. **验收 7 标准**：运行稳定、界面差异化、痕迹清零、素材完整、文档达标、部署可复现、合规无侵权；全部达标方可交付。
7. **整改与售后**：验收问题 24 小时内免费整改并重新交付；两次整改不达标甲方可拒收；
   交付后终身免费基础质保、24 小时内响应。
8. **保密与知识产权**：交付成果使用权/商用权归甲方，乙方不得自用/售卖/转发/二次分发；
   商业信息与客户资源永久保密。

### 构建交付包与交付清单（步骤 18）

步骤 18 使用内置脚本构建交付压缩包，并把交付清单作为与 zip 并列的单独文件输出：

```bash
python scripts/build_delivery_package.py --project-dir <项目目录>
```

脚本保证：

- README 只在 zip 包根一份，「文档」目录不再放 README；
- README 引用图片自动随包拷入并保持相对路径，解压可显示（脚本内置解压校验）；
- 交付清单《交付清单.md》输出在 zip 之外、与之并列，不打入包内；
- 包内无内部执行工具痕迹。

### 交付物阻断式核查（步骤 19）

```bash
python scripts/deliverables_check.py \
  --project-dir <项目目录> \
  --trace-keywords "原公司名,原品牌,原域名" \
  --netdisk-link "<网盘归档链接>"
# 项目确实不适配 Docker 时加 --allow-no-docker，
# 并在交付目录给出书面说明
```

退出码为 0 才算交付物齐备。
禁止伪造截图/录屏/网盘链接，禁止把 README 写成与实际不符的宣传稿。

## 状态管理

状态统一放在目标项目的 `.Codex` 目录：

```text
<项目目录>/.Codex/
├── workflow_state.json   # 步骤状态
├── error_log.md          # 错误日志
├── reports/              # 审计与核查报告
└── delivery/             # 交付材料
    ├── manifest.md       # 交付清单（内部工作文件，不打入交付包）
    ├── assets/           # 内部基线截图 + 产品截图、全功能录屏
    └── no-docker说明.md  # 仅不适配 Docker 时需要
```

状态流转：

```text
⏭️ 未开始 → ⏸️ 进行中 → ✅ 已完成
                    ↓
                   ❌ 失败，可重试
```

恢复执行时读取 `workflow_state.json`，跳过已完成步骤，从第一个进行中、失败或未开始的步骤继续。

可使用本技能自带脚本：

```bash
python scripts/workflow_manager.py init <project_dir> "<项目名称>" "<git地址>" "[端口范围]"
python scripts/workflow_manager.py status <project_dir>
python scripts/workflow_manager.py resume <project_dir>
python scripts/workflow_manager.py report <project_dir>
```

## 技术栈检测

- Java Spring：`pom.xml`、`build.gradle`
- Node.js Express：`package.json`、`app.js`、`server.js`
- Node.js Nest：`nest-cli.json`、`@nestjs`
- Python Django：`manage.py`、`django`
- Python FastAPI：`fastapi`、`main.py`
- Go Gin / Fiber：`go.mod`、`gin` / `fiber`
- React：`react`、`App.jsx`、`App.tsx`
- Vue：`vue`、`App.vue`
- Angular：`angular.json`、`@angular`

## 完成标准

- 项目可正常安装、构建和启动。
- Docker 项目的容器健康检查通过。
- 新旧项目名称替换准确，未错误修改 lock 文件、依赖名或后端配置中的技术标识。
- Logo、Favicon、浏览器标题、导航和页脚显示新品牌。
- 主要页面具备统一的炫酷面板风格。
- 已新增「项目概述大屏」页面，接入真实聚合数据（指标卡/趋势/分布/最新动态/实时时钟）并在导航提供入口。
- 页脚、概览页与 README 均包含开源社区 gitcc.com 与 GCC AI Coding gitvv.com 的可点击超链接。
- 阻断式面板 UI 审计退出码为 0，10 个核心页面/路由无对比度和“外黑内白”违规。
- Modal、Drawer、Select、DatePicker、Popover、Tooltip 和 Alert/Tag 等组件均通过暗色主题与对比度检查。
- 移动端布局正常，动效不会导致明显卡顿。
- AI 对话功能可用，支持 OpenAI 兼容接口和流式输出；默认服务商、Base URL、默认模型与用户要求一致，内置使用教程，且本地配置 key 已做版本迁移。
- 甲方可见材料无外部项目链接、原作者、致谢和版本对比；源码许可证/NOTICE 已按法律要求完整保留。
- 商业痕迹与来源痕迹全部清理，grep 复查交付物中无残留。
- 内部基线截图只用于核对、不随包交付；对外界面截图与录屏采集于最终构建并健康通过的版本，页面全覆盖、录屏完整，归档链接长期有效、可访问下载。
- 标准化 README 覆盖全部必备内容，以当前产品口径编写，图文结合、架构图准确、部署教程可落地，且不作虚假权属表述。
- 7 项交付物齐备，`.Codex/delivery/manifest.md` 完整；`deliverables_check.py` 退出码为 0。
- 保密与知识产权要求已遵守：成果不私用/不外传，交付材料与验收记录可溯源。
- 最终 Git 提交信息描述具体业务变化，不出现“工作流”。