ClassIsland Prompt Kit
22c1784bab
- 重构版主提示词（14 parts，面向 ClassHelper 灵动岛重构） - ClassIsland 全量规格提示词（20 parts，含分卷与逐章版本） - 投喂指南、分卷、逐节文件 - 调研记录、一致性基线、生成与质检脚本
11 KiB
11 KiB
1. 重构目标与范围
1.1 为什么重构、以什么为基准
ClassHelper 的灵动岛已经具备完整的工程骨架：独立透明窗口、fixed/custom 两种布局、多方案组件编辑器、消息队列、课程提醒、天气、课件覆盖。但它的视觉语言来自 WinIsland（连续圆角、小胶囊、弹簧形变、纯黑/毛玻璃），与 ClassIsland 的「Fluent 信息行 + 组件化 + 提醒气泡 + 强提醒特效 + 精细过渡」存在系统性差距。本次重构以 ClassIsland v2.1 的灵动岛（MainWindow / MainWindowLine / Components / Notification / TopmostEffect）为行为与视觉基准，把 ClassHelper 的岛升级为同等精细度，同时保留 ClassHelper 的工程结构、数据来源与业务规则。
你必须记住三条基准优先级：
- ClassHelper 业务语义优先：消息去重、优先级、上课暂存、紧急展开、叫人胶囊、已读回执、班级设备、课件传输优先等规则不得改变；
- ClassIsland 视觉与动画优先：像素、字号、圆角、间距、颜色、动画时长与曲线以本提示词第 6、7、10 部分为准；
- ClassHelper 既有工程与配置不得推翻：pnpm monorepo、独立岛渲染进程、
config.json.islandLayout、IslandComponentNode/IslandLayoutScheme数据模型、编辑器入口、无头验证纪律继续有效。
1.2 目标状态（重构完成后用户看到什么）
- fixed（经典）默认变成 ClassIsland 风格的课表信息行：屏幕顶部/底部悬浮一条或多条信息行（默认 1 行：日期 + 课程表；行高 40、圆角 8、背景不透明度 0.5、字号 14/16/18/20、底部 3px 进度条），显示当天课程、当前课程、剩余分钟/倒计时；不再是 268×44 的小胶囊。
- 消息到来时的表现：普通通知/作业在岛内展开为 ClassIsland 风格的气泡（行内遮罩 + 内容两阶段：遮罩扫入 360ms + 错峰 120ms，文字延迟 260ms 淡入并 1.1→1.0 缩放 750ms），紧急消息立即展开；保留 ClassHelper 的上课暂存、普通叫人可点胶囊、紧急立即展开等规则。
- 强提醒：可配置的 ClassIsland 强提醒（Topmost 特效）在岛所在显示器全屏/大区域显示，超时自动关闭，不抢焦点、不阻塞操作；默认仅对"强调提醒"启用。
- custom（自定义常驻）：保留现有方案/行/组件/编辑器，但渲染与交互升级为 ClassIsland 规格：行高 40、行间距 5、组件外边距 6/6、行设置抽屉、选中框 1.5px 虚线、拖拽把手、隐藏规则、行/组件外观覆盖、进入编辑模式（实际内容预览）、退出保存。
- winisland 兼容风格（只作用于 fixed）：
appearance.family = 'winisland'时保留现有经典 fixed 观感（连续圆角、胶囊 268×44、纯黑/毛玻璃/主题色渐变、弹簧形变）；custom不随 family 变化，始终使用 ClassIsland 规格（其编辑器/行/组件结构保持不变，只按 07 细化像素）。默认新装classisland，老用户升级迁移为winisland。 - 设置与编辑器：灵动岛设置页新增风格选择、ClassIsland 外观参数（字号阶梯、行间距、进度条、强提醒开关、主题 Fluent/Classic 选择）；自定义方案编辑器增加"编辑模式"与行设置抽屉；所有改动即时保存、失败可重试、退出不丢改动。
- 数据与兼容：旧
config.json.islandLayout无损迁移；用户的 schemes/rows/nodes、外观值、编辑器习惯全部保留；迁移失败可回滚；旧版本客户端读到新配置时按"忽略未知字段 + 默认值"处理（或明确拒绝并提示升级）。
1.3 范围（In / Out）
必须做（In）：
- 岛窗口与渲染层：
island.html、LayoutIslandApp.vue、IslandApp.vue、CustomIslandRuntime.vue、ComponentNode.vue、ClassicNotifications.vue、LessonReminderContent.vue、CoursewareTransfer.vue、spring.ts、squircle.ts、各 CSS。 - 主进程岛控制器：
src/main/island.ts（窗口几何、命中、触摸、消息队列、课程提醒、天气、课件、编辑预览、保存配置、预览/应用）。 - preload 与 bridge：
src/preload/island.ts、src/renderer/island/bridge.ts、src/types/desktop.d.ts的岛契约。 - 共享层：
packages/shared/src/{island-layout,constants,motion}.ts的 schema、常量、归一化、迁移。 - 设置/编辑器：
IslandSettingsView.vue、IslandEditorView.vue、IslandComponentSettings.vue、IslandEditorNode.vue、island-editor.css，以及router中岛编辑路由的入口。 - 配置：
config.json.islandLayout版本化迁移、原子写、回滚。 - 文档与无头测试。
不做（Out，最多在交付说明中标注为后续）：
- 不重写服务端/数据库/Web 管理端；不改变服务端接口字段与权限。
- 不引入 ClassIsland 的 Profile/TimeLayout 本地档案、插件系统、自动化系统、管理端、主题市场、Excel 导入、更新器。
- 不引入新框架/新 UI 库/新状态库；不更换构建管线。
- 不把岛改成多窗口；仍只有一个原生岛窗口 + 一个可选的强提醒特效窗口。
- 不改动主窗口（设置/作业/成绩/通知中心）布局，除编辑器入口与预览联动外。
1.4 模块级 Keep / Change / Add / Remove
| 模块 | 处理 | 说明 |
|---|---|---|
| 岛窗口创建/几何/命中/触摸/失焦宽限 | Keep + Change | 保留固定包围盒与透明窗口护栏；按 ClassIsland 行高/宽度/停靠语义重算几何；fixed 从胶囊尺寸改为信息行尺寸；custom 保持测量适配但按 ClassIsland 行模型约束 |
IslandApp.vue（经典） |
Change（大改） | 从"胶囊+详情卡"重构为"ClassIsland 信息行 + 通知气泡 + 进度条"；保留消息状态机与紧急/上课规则 |
CustomIslandRuntime.vue（自定义） |
Change | 保留测量/缩放/行渲染；行高、行距、组件边距、背景、圆角、进度条、选中框、拖拽按 ClassIsland 规格；编辑模式重做 |
ComponentNode.vue / 组件库 |
Change + Add | 11 类组件的默认样式/尺寸/字号/空数据按 ClassIsland 规格；新增进度条/倒计时徽标/课程时间点展开等子结构 |
ClassicNotifications.vue |
Change | 气泡两阶段（斜切遮罩/文字/缩放）与 ClassIsland 参数对齐；保留 ClassHelper 消息类型/排序/回执 |
LessonReminderContent.vue |
Change | 课程提醒条/倒计时徽标按 ClassIsland 布局与字号；下课前蓝色圆形秒数徽标（含 -1） |
CoursewareTransfer.vue |
Keep | 覆盖优先逻辑不变，只按新视觉加外壳/动画 |
spring.ts / squircle.ts |
Keep（条件使用） | ClassIsland 风格默认用 CSS transition + 标准圆角；winisland 风格继续用弹簧/连续圆角；不得把弹簧用于 ClassIsland 规格动画 |
main/island.ts |
Change | 窗口几何、状态模式、消息队列、课程提醒、天气、编辑预览按新交互调整；新增强提醒窗口控制、编辑模式、迁移调用；保留单实例/恢复/限流 |
shared/island-layout.ts |
Change（v2） | 新增 version、风格/主题/强提醒/进度条等字段；新增 ClassIsland 组件设置字段；normalize/migrate；旧配置无损升级 |
| 设置页/编辑器 | Change + Add | 新增风格切换、ClassIsland 外观项、编辑模式、行设置抽屉；保留方案/行/组件/导入导出 |
| 文档/测试 | Change + Add | 更新 docs；新增无头测试；--visual 保持可选 |
1.5 关键设计裁决（必须逐条执行）
- 固定形态风格双轨、默认 ClassIsland：
appearance.family: 'classisland' | 'winisland'只决定 fixed 的形态（信息行 vs 旧胶囊）；custom始终 ClassIsland 规格。新装默认classisland；旧用户升级保持winisland（避免 fixed 观感突变）；设置页在 fixed 下提供切换并即时预览。 - fixed 重定义：fixed 不再是"小胶囊消息岛"，而是 ClassIsland 风格信息行（默认 1 行，日期+课程表；消息时行内气泡）。原胶囊形态只在
winisland风格下保留。 - custom 保留数据模型：schemes/rows/nodes/expandedRows 不变，只扩展字段与渲染；已有用户方案无需重做即可获得新视觉。
- 数据不迁移：继续消费 ClassHelper 的课表/通知/作业/叫人/课件数据；ClassIsland 的 Lesson/Notification 语义只作为行为参考。
- 强提醒是新增窗口而非替换岛：ClassIsland 的 TopmostEffect 以独立透明窗口实现（无边框、置顶、不抢焦点、超时关闭）；只在消息的"强调提醒"开关开启时出现；编辑/预览模式不创建。
- 配置版本化：
islandLayout.version（整数，当前 2）；normalizeIslandLayouts()先迁移再归一化；迁移前备份config.json，失败回滚并提示。 - 验证无头：所有自动验证必须后台执行；
--visual才允许可见岛、动画、截图验收；不得为验收创建真实班级/发送测试通知/重置密码。
1.6 成功标准（重构完成的定义）
- 视觉：第 6/7 部分的像素值在 1920×1080@100%、1080p@125%/150%、深/浅色、ClassIsland Fluent/Classic 两套主题、ClassHelper winisland 风格下逐项对齐（容差：颜色 ±2/255，尺寸/位置 ±1px，透明度 ±1%）。
- 动画：第 10 部分动画表逐项实现（时长误差 ≤ 16ms、曲线一致）；60fps；减少动画/失焦/隐藏页暂停生效。
- 功能：消息/课程提醒/天气/课件/编辑器/设置/迁移全部可用；无回归（见第 12 部分）。
- 兼容：旧配置升级成功率 100%（本仓库 fixtures 内）；回滚可用；旧字段
residentEnabled继续兼容。 - 性能：岛渲染进程启动 ≤ 500ms；空闲 CPU ≤ 1%；主+岛进程内存 ≤ 250MB；消息风暴 20 条/分钟无卡顿/丢失/重复。
- 纪律：
verify:desktop默认不创建可见岛/托盘；无 GUI 打扰。
1.7 主要风险与对策
| 风险 | 对策 |
|---|---|
| 透明窗口改尺寸导致闪烁 | 固定包围盒 + 窗内形变（保留现有策略）；setBounds 仅模式/设置/显示器变化且节流 ≥100ms |
| fixed 重定义导致老用户不习惯 | winisland 风格保留 + 升级默认沿用旧风格 + 设置页可切换 |
| 消息状态机重构引入竞态 | 先写状态机单测（去重/优先级/暂存/紧急/回执），再改 UI；所有状态变更走单一入口 |
| 编辑模式拖拽与触摸冲突 | 编辑模式暂停指针避让/消息展开；触摸与鼠标分别走命中/宽限路径 |
| 配置迁移破坏用户方案 | 迁移前备份；schema 校验 + 归一化；失败回滚；fixtures 覆盖 fixed/custom/旧版字段 |
| 多显示器/DPI 偏差 | 全部使用 DIP；屏幕变化事件驱动重算；截图验收用 devicePixelRatio 换算 |
| 动画掉帧 | 只用 transform/opacity；弹簧仅限 winisland；长任务移出主线程；帧率监控 |
1.8 阅读顺序提示
- 先读第 2 部分（ClassHelper 现状）与第 3 部分（ClassIsland 行为基准），确认"保留什么、改什么"。
- 第 4/5 部分是施工图与数据迁移，必须在写代码前读完。
- 第 6/7/10 部分是像素与动画的硬规格，逐条落实。
- 第 8/9 部分处理消息、课程、强提醒与编辑器。
- 第 11/12/13 部分是兼容、验收与里程碑，按顺序执行。