# ClassIsland 复刻工程：给 ChatGPT 的完整实现提示词（ClassHelper 技术栈版）

> **文档性质**：这是一份「提示词」而非分析报告。请把本文件（或按章节分卷）直接投喂给 ChatGPT，要求它按第 17 部分的里程碑从零实现一个 ClassIsland 等价应用；实现技术栈采用 ClassHelper 桌面端（Electron 44 + Vue 3.5 + Element Plus + Pinia + Vite 8 + TypeScript 5.9 + pnpm monorepo），以等价替换 ClassIsland 原项目的 C# / .NET 8 / Avalonia / FluentAvalonia / XAML。
>
> **信息来源**：ClassIsland v2.1 源码（`repos/ClassIsland`，C#/Avalonia）与 ClassHelper 源码（`repos/ClassHelper-master`，TypeScript/Electron）。文中所有确切数值、资源名、行为均尽量标注 `文件:行号` 证据；无源码依据处标注【推断】。ClassIsland 的截图与文档仅用于校对视觉语义，不复制其代码。
>
> **重要说明**：本提示词要求实现者的一切自动验证（构建、冒烟、截图、动画检查）必须**无头/离屏运行，禁止弹出可见窗口、禁止播放声音、禁止干扰用户桌面**。这是本项目的强制纪律，也是验收的一部分（见第 18 部分）。

## 使用说明（给人类读者，不投喂给模型）

1. **整体投喂**：全文约 200k tokens，需使用上下文 ≥ 200k 的模型（如 GPT-5 级长上下文 / Gemini 2.5 Pro）才能一次粘贴；将本文件从「## 0.」到结尾整体粘贴，尾附一句：「请严格按此提示词实现，先给出实施计划与文件树，再按里程碑推进。」
2. **分卷投喂**：按 `## 0` + `## 1` + `## 2`（基础）→ `## 3`~`## 5`（视觉与组件）→ `## 6`~`## 8`（业务）→ `## 9`~`## 13`（系统与数据）→ `## 14`~`## 19`（动画、资源、验收）的顺序分批发送；每批发完后要求模型复述关键参数，避免长上下文丢失。
3. **推荐追问**：「请先输出 20 个你认为最可能歧义的点」「请给出 packages/desktop-client 的完整文件树与每个文件的职责」「请先实现 M0/M1 并给出无头验证脚本」。
4. **证据约定**：文中 `repos/ClassIsland/...` 与 `repos/ClassHelper-master/...` 是规格来源路径，不是让你照抄的运行时依赖；实现时应把这些规格转写为 TypeScript/CSS。

<!-- TOC -->

## 0. 给 ChatGPT 的任务声明（从本节开始执行）

### 0.1 你的任务

从零实现一个名为 **ClassIsland**（实现代号 `classisland-ts`）的跨平台桌面应用：它常驻班级多媒体屏幕，以悬浮「岛」显示当天课表、当前课程、倒计时、日期时间、天气等信息；在上下课等重要时间点发出包含音效、语音与全屏特效的提醒；并提供课表编辑、档案管理、组件系统、主题、自动化、插件、自动更新等完整能力。灵感来源是 iOS 灵动岛（Dynamic Island），但它是为教室大屏与「不打扰授课」场景重新设计的桌面工具。

你必须交付**可安装、可离线运行、可长时间无人值守运行**的 Electron 应用，而不是网页 Demo 或原型。视觉与交互规格必须严格按本提示词执行，尤其是第 3（设计 tokens）、4（主界面）、5（组件）、14（动画）部分中的数值。

### 0.2 不可协商的技术栈

- pnpm@11.8.0 monorepo；Node.js >= 20.19；TypeScript ~5.9.3（strict）。
- Electron ^44.3.0 + electron-builder ^26.15.3；主进程/preload 用 esbuild 打包，渲染层用 Vite ^8.3.0 多入口（`index.html` 应用窗口、`island.html` 岛）。
- Vue ^3.5.42 + Vue Router ^5.3.1 + Pinia ^4.0.3；Element Plus ^2.14.5 仅用于设置/管理类界面，**不得进入岛的渲染进程**。
- 三个进程角色：主进程（窗口/调度/配置/更新/IPC）、岛渲染进程（常驻、透明、逐像素自绘）、应用窗口渲染进程（按需创建）。
- 复用 ClassHelper 已验证的实现模式：独立 `island.html` + 独立透明 BrowserWindow、连续圆角 `squircle.ts`、弹簧动画 `spring.ts`、`config.json` 原子读写、contextBridge 白名单、`tokens.css` 设计变量、自研 `auto-update.ts`（禁止 electron-updater）、崩溃守卫 `crash-guard.ts`。
- 不引入服务端依赖；所有业务数据本地存储；可选管理端联动只能作为 P2 可裁剪子包。

### 0.3 硬性纪律（违反即不合格）

1. 所有自动验证必须无头/离屏执行；不得显示可见窗口、托盘气泡、系统通知或声音；需要人工观察的验证用显式 `--visual` 参数开启且不得作为默认。
2. 渲染层零 Node 权限：preload 只暴露 contextBridge 白名单，不暴露 `ipcRenderer`；`nodeIntegration=false`、`contextIsolation=true`、`sandbox=true`。
3. 主窗口（岛）不得抢焦点、默认不进入任务栏；不得使用 `setBackgroundMaterial()` 等破坏逐像素透明的 API。
4. 动画必须 60fps：优先 transform/opacity，禁止 `setInterval` 逐帧驱动、禁止逐帧改布局属性。
5. 核心功能离线可用；数据写入原子化并自动备份；迁移前先备份。
6. 不得伪造验收结果；未验证项必须显式标注。

### 0.4 交付物

- 完整源码 + `pnpm-lock.yaml` + 构建/打包脚本；`README.md` 含运行、构建、打包、数据目录说明。
- `docs/architecture.md`、`docs/data-schema.md`、`docs/plugin-api.md`、`docs/theme-api.md`。
- 至少 1 个示例课表档案、1 个示例主题、1 个示例插件（P1）。
- 无头测试（单元 + 组件 + 端到端）与第 16 部分的验收报告。

### 0.5 工作方式

1. 通读本提示词后，先输出：实施计划、完整文件树、你识别出的歧义点（一次性提问）。
2. 按第 17 部分的 M0→M8 顺序实现；每个里程碑结束都交付「可无头启动 + 通过该阶段验收」的状态。
3. 每完成一个模块，写清楚：实现了什么、证据（文件与行号）、未实现/推断项、如何验证。
4. 遇到本提示词未覆盖的细节：按第 18.5 节的优先级裁决，并在代码注释标注「推断」。
5. 不得把不同模块混在一起「顺手重构」；保持提交/变更范围单一、可回滚。

### 0.6 术语与阅读顺序

- **岛（Island / MainWindow）**：常驻悬浮主界面；由一行或多行「行（Line）」组成。
- **行（MainWindowLine）**：承载组件的横向容器，拥有自己的背景、进度条、遮罩与提醒气泡。
- **组件（Component）**：最小显示单元（日期、时钟、倒计时、课程表、天气等），可嵌套。
- **档案（Profile）**：一套课表/时间表/科目的配置集合，对应一个 JSON 文件。
- **课表（ClassPlan）** 与 **时间表（TimeLayout）**：见第 6 部分。
- **提醒（Notification）**、**自动化（Automation）**、**规则集（Ruleset）**、**主题（XamlTheme→CSS 主题包）**、**插件（Plugin）**：见对应章节。
- 阅读顺序：0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 15 → 16 → 17 → 18 → 19。