ClassIsland Prompt Kit
22c1784bab
- 重构版主提示词（14 parts，面向 ClassHelper 灵动岛重构） - ClassIsland 全量规格提示词（20 parts，含分卷与逐章版本） - 投喂指南、分卷、逐节文件 - 调研记录、一致性基线、生成与质检脚本
8.8 KiB
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 部分）。
使用说明（给人类读者，不投喂给模型）
- 投喂方式：全文约 12 万 tokens，建议按
out/投喂指南-重构版.md的五卷/逐章方式投喂；一次性投喂需 ≥ 128k 上下文模型。投喂前请把 ClassHelper 仓库（或至少packages/desktop-client、packages/shared、packages/ui、docs/）提供给 ChatGPT（作为代码上下文或附件）。 - 推荐开场：「请先阅读第 0–2 部分，复述你对现状、目标与 7 条裁决的理解；然后给出文件级重构计划（含迁移与回滚），等我确认后再按 M0–M7 逐阶段实现。」
- 证据约定：
packages/...:行号指 ClassHelper 仓库相对路径；repos/ClassIsland/...:行号是 ClassIsland 基准来源（相对本工作区），只用于理解行为，不是运行时依赖。 - 验收纪律：任何「已完成」的声明都必须附带无头验证输出与第 12 部分的逐项勾选结果；未验证项必须标注。
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 不可协商的技术与工程约束
- 技术栈原样沿用：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。
- 包边界不变：
packages/shared（类型/常量/纯函数/岛 schema）、packages/ui（共享控件/tokens）、packages/desktop-client（Electron 主进程 + preload + 主窗口渲染 + 独立岛渲染island.html）；服务端packages/server与 Web 管理端packages/web-admin不在本次改动范围。 - 岛窗口仍是独立透明 BrowserWindow + 独立
island.html渲染入口 + 独立 island preload；主窗口设置页只作为编辑器入口，编辑预览不创建额外桌面窗口。 - 渲染层零 Node 权限：preload 仅暴露 contextBridge 白名单，不暴露
ipcRenderer；nodeIntegration:false、contextIsolation:true、sandbox:true。 - 禁止
setBackgroundMaterial()/vibrancy/backdrop-filter等会破坏逐像素透明的 API；透明、圆角、阴影全部由 CSS 自绘。 - 数据来源不变：课表/时间点/通知/作业/叫人/课件仍来自 ClassHelper 服务端解析结果（
ScheduleDto、IslandTimePointDto、IslandState、IslandNotification等）；不得引入 ClassIsland 的本地 Profile/ClassPlan 档案体系。 - 配置仍写入
config.json.islandLayout（本机，不同步服务端）；新增字段必须可迁移、可回滚，旧fixed/custom配置无损升级。 - 既有硬约束必须保留：
winisland兼容形态下的连续圆角与投影常驻、触摸输入、失焦宽限、固定窗口几何护栏；所有形态下消息按 id 去重、通知/叫人双播不重复、课件传输优先、默认验证不创建可见岛或托盘、冒烟假执行不真关机。 - 所有自动验证无头执行；不得修改验收标准来「通过」；未验证项必须标注。
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 工作方式
- 先通读本提示词与 ClassHelper 相关源码，输出：①你对现状与目标的理解复述；②文件级重构计划（含每个文件的改动类型、接口变化、迁移与回滚）；③你识别出的歧义点（一次性提问）；④M0 的无头验证方案。
- 严格按第 13 部分的 M0–M7 顺序推进；每个里程碑结束都交付「可无头启动 + 通过该阶段验收 + 不回归既有功能」的状态。
- 每个模块完成后写清：改了什么、证据（文件/行号/行为变化）、未完成/推断项、验证方法与结果。
- 遇到本提示词未覆盖的细节：ClassHelper 既有行为优先（业务语义与既有交互），ClassIsland 规格优先（视觉、像素、动画）；仍不明确时在代码与交付说明中标注【推断】。
- 不得顺手重构无关模块；保持 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 部分给兼容、验收、里程碑。