ClassIsland Prompt Kit
22c1784bab
- 重构版主提示词（14 parts，面向 ClassHelper 灵动岛重构） - ClassIsland 全量规格提示词（20 parts，含分卷与逐章版本） - 投喂指南、分卷、逐节文件 - 调研记录、一致性基线、生成与质检脚本
76 lines
8.8 KiB
Markdown
76 lines
8.8 KiB
Markdown
# ClassHelper 灵动岛重构：给 ChatGPT 的完整实现提示词
|
||
|
||
> **文档性质**：这是一份「提示词」而非分析报告。请把本文件（或按章节分卷）投喂给 ChatGPT，要求它在 **ClassHelper 现有仓库**（`LoveChengke/ClassHelper`，pnpm monorepo，Electron + Vue 3）中，以 ClassIsland（`ClassIsland/ClassIsland`，C#/Avalonia）的灵动岛（主界面）为基准，**重构 ClassHelper 的灵动岛子系统**。不是从零新建项目，不重写服务端与管理端，不更换技术栈。
|
||
>
|
||
> **信息来源**：ClassHelper 工作区源码（`repos/ClassHelper-master`）与 ClassIsland v2.1 源码（`repos/ClassIsland`）。文中所有确切数值、文件名、行为均尽量标注 `packages/...:行号` 或 `repos/ClassIsland/...:行号`；无源码依据处标注【推断】。ClassIsland 的源码只作为行为与视觉基准，**不得**把其 C#/Avalonia 代码、XAML、本地档案体系引入 ClassHelper。
|
||
>
|
||
> **重要纪律**：本重构的一切自动验证（构建、冒烟、截图、动画检查）必须**无头/离屏运行，禁止弹出可见窗口、禁止播放声音、禁止干扰用户桌面**。ClassHelper 仓库默认的 `verify:desktop` / `verify:packaged` 就是后台快速检查，只有显式 `--visual` 才允许可见验收——重构后必须保持这一约定（见第 11、12 部分）。
|
||
|
||
## 使用说明（给人类读者，不投喂给模型）
|
||
|
||
1. **投喂方式**：全文约 12 万 tokens，建议按 `out/投喂指南-重构版.md` 的五卷/逐章方式投喂；一次性投喂需 ≥ 128k 上下文模型。投喂前请把 ClassHelper 仓库（或至少 `packages/desktop-client`、`packages/shared`、`packages/ui`、`docs/`）提供给 ChatGPT（作为代码上下文或附件）。
|
||
2. **推荐开场**：「请先阅读第 0–2 部分，复述你对现状、目标与 7 条裁决的理解；然后给出文件级重构计划（含迁移与回滚），等我确认后再按 M0–M7 逐阶段实现。」
|
||
3. **证据约定**：`packages/...:行号` 指 ClassHelper 仓库相对路径；`repos/ClassIsland/...:行号` 是 ClassIsland 基准来源（相对本工作区），只用于理解行为，不是运行时依赖。
|
||
4. **验收纪律**：任何「已完成」的声明都必须附带无头验证输出与第 12 部分的逐项勾选结果；未验证项必须标注。
|
||
|
||
<!-- TOC -->
|
||
|
||
## 0. 给 ChatGPT 的任务声明（从本节开始执行）
|
||
|
||
### 0.1 你的任务
|
||
|
||
你是一名资深 Electron + Vue 3 + TypeScript 桌面工程师，熟悉透明置顶窗口、逐像素自绘 UI、CSS 动画与主进程/渲染进程协作。你的任务是在 **ClassHelper 现有 monorepo** 中重构灵动岛（island）子系统：
|
||
|
||
- 保留 ClassHelper 的工程结构、技术栈、服务端数据来源、既有业务规则与配置体系；
|
||
- 以 ClassIsland 的灵动岛为**视觉与行为基准**，重构 ClassHelper 的 `fixed`（经典）与 `custom`（自定义常驻）两套布局的渲染、交互、动画、设置与编辑器；
|
||
- 新增 `winisland` 兼容风格开关，使老用户可保留现有观感；默认使用 ClassIsland 风格；
|
||
- 不新建应用、不重写服务端/数据库/Web 管理端、不引入新的 UI 框架。
|
||
|
||
最终交付是**可合并进 ClassHelper 的代码改动 + 数据迁移 + 文档 + 无头测试 + 验收报告**，而不是示例代码或原型。
|
||
|
||
### 0.2 不可协商的技术与工程约束
|
||
|
||
1. 技术栈原样沿用：pnpm@11.8.0 monorepo；Electron ^44.3.0；Vue ^3.5.42；Element Plus ^2.14.5（仅设置/编辑器界面）；Pinia ^4.0.3；Vue Router ^5.3.1；Vite ^8.3.0；TypeScript ~5.9.3；主进程/preload 用 esbuild，渲染层用 Vite。
|
||
2. 包边界不变：`packages/shared`（类型/常量/纯函数/岛 schema）、`packages/ui`（共享控件/tokens）、`packages/desktop-client`（Electron 主进程 + preload + 主窗口渲染 + 独立岛渲染 `island.html`）；服务端 `packages/server` 与 Web 管理端 `packages/web-admin` **不在本次改动范围**。
|
||
3. 岛窗口仍是**独立透明 BrowserWindow + 独立 `island.html` 渲染入口 + 独立 island preload**；主窗口设置页只作为编辑器入口，编辑预览不创建额外桌面窗口。
|
||
4. 渲染层零 Node 权限：preload 仅暴露 contextBridge 白名单，不暴露 `ipcRenderer`；`nodeIntegration:false`、`contextIsolation:true`、`sandbox:true`。
|
||
5. 禁止 `setBackgroundMaterial()` / `vibrancy` / `backdrop-filter` 等会破坏逐像素透明的 API；透明、圆角、阴影全部由 CSS 自绘。
|
||
6. 数据来源不变：课表/时间点/通知/作业/叫人/课件仍来自 ClassHelper 服务端解析结果（`ScheduleDto`、`IslandTimePointDto`、`IslandState`、`IslandNotification` 等）；不得引入 ClassIsland 的本地 Profile/ClassPlan 档案体系。
|
||
7. 配置仍写入 `config.json.islandLayout`（本机，不同步服务端）；新增字段必须可迁移、可回滚，旧 `fixed`/`custom` 配置无损升级。
|
||
8. 既有硬约束必须保留：`winisland` 兼容形态下的连续圆角与投影常驻、触摸输入、失焦宽限、固定窗口几何护栏；所有形态下消息按 id 去重、通知/叫人双播不重复、课件传输优先、默认验证不创建可见岛或托盘、冒烟假执行不真关机。
|
||
9. 所有自动验证无头执行；不得修改验收标准来「通过」；未验证项必须标注。
|
||
|
||
### 0.3 交付物
|
||
|
||
- 代码：`packages/shared`、`packages/desktop-client`（main/preload/island/renderer）的改动；如涉及 `packages/ui` 的 token 复用也需提交。
|
||
- 数据迁移：`config.json.islandLayout` 的版本化迁移函数、旧配置升级、失败回滚路径；不得丢失用户的 schemes/rows/nodes/外观设置。
|
||
- 文档：更新 `docs/app/island.md` 与 `docs/dev/implementation.md` 的岛章节；新增本次重构的 `docs/dev/island-refactor.md`（架构、数据契约、动画表、迁移说明）。
|
||
- 测试：无头单元测试（schema 迁移、normalize、消息队列、课程状态机）+ 组件测试（岛渲染快照）+ 既有无头 `verify:desktop` 的适配；视觉验收仅在 `--visual` 下执行。
|
||
- 报告：第 12 部分验收清单逐项勾选；与 ClassIsland 的差异说明；未实现项与原因；性能数据（启动、空闲 CPU、内存、动画帧率）。
|
||
|
||
### 0.4 工作方式
|
||
|
||
1. 先通读本提示词与 ClassHelper 相关源码，输出：①你对现状与目标的理解复述；②文件级重构计划（含每个文件的改动类型、接口变化、迁移与回滚）；③你识别出的歧义点（一次性提问）；④M0 的无头验证方案。
|
||
2. 严格按第 13 部分的 M0–M7 顺序推进；每个里程碑结束都交付「可无头启动 + 通过该阶段验收 + 不回归既有功能」的状态。
|
||
3. 每个模块完成后写清：改了什么、证据（文件/行号/行为变化）、未完成/推断项、验证方法与结果。
|
||
4. 遇到本提示词未覆盖的细节：ClassHelper 既有行为优先（业务语义与既有交互），ClassIsland 规格优先（视觉、像素、动画）；仍不明确时在代码与交付说明中标注【推断】。
|
||
5. 不得顺手重构无关模块；保持 diff 可审阅、可回滚。
|
||
|
||
### 0.5 术语表
|
||
|
||
- **灵动岛 / 岛（island）**：ClassHelper 的独立透明窗口与 `island.html` 渲染的悬浮界面。
|
||
- **fixed（经典）**：ClassHelper 现有「胶囊 + 详情卡」消息型布局。
|
||
- **custom（自定义常驻）**：ClassHelper 现有「多行 + 组件 + 组件方案」布局，常驻显示。
|
||
- **winisland**：ClassHelper 现有观感（WinIsland 风格：连续圆角、胶囊 268×44、纯黑/毛玻璃/主题色渐变）；作为兼容风格保留。
|
||
- **ClassIsland 风格**：本重构的默认观感，按 ClassIsland 主界面的行/组件/像素/动画规格实现。
|
||
- **行（row / line）**：承载组件的横向容器（对应 ClassIsland `MainWindowLine`）。
|
||
- **组件（component / node）**：`IslandComponentNode`，最小显示单元（日期/时钟/天气/倒计时/课程表/文本/容器等）。
|
||
- **方案（scheme）**：`IslandLayoutScheme`，一套常态 `rows` 与无消息展开 `expandedRows` 的组件布局。
|
||
- **消息（message）**：通知/作业/叫人的统称（`IslandNotification`）。
|
||
- **强提醒（Topmost effect）**：ClassIsland 的全屏强调特效窗口；本次以 Electron 独立窗口实现，不抢焦点、不阻塞。
|
||
- **无头验证**：不创建可见窗口/托盘/声音的自动化检查（ClassHelper 的 `verify:desktop` 默认模式）。
|
||
|
||
### 0.6 阅读顺序
|
||
|
||
0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13。第 2 部分先建立现状地图，第 3 部分给出行为基准，第 4/5 部分给改造清单与数据迁移，第 6/7/10 部分给视觉、组件、动画规格，第 8/9 部分给消息与编辑器，第 11/12/13 部分给兼容、验收、里程碑。
|