Love_Chengke/classhelper-island-refactor-prompt
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
classhelper-island-refactor…/analysis/refactor-current-state.md
T
ClassIsland Prompt Kit 22c1784bab feat: ClassIsland / ClassHelper 灵动岛提示词套件 
- 重构版主提示词（14 parts，面向 ClassHelper 灵动岛重构）
- ClassIsland 全量规格提示词（20 parts，含分卷与逐章版本）
- 投喂指南、分卷、逐节文件
- 调研记录、一致性基线、生成与质检脚本
2026-11-12 21:59:58 +08:00

14 KiB
Raw Permalink Blame History

ClassHelper 灵动岛重构调研笔记（Part 02/04/05 支撑）

本文件是队友 stack 在 Round 2 的静态分析记录，供 Lead 汇总审校时核对"读了什么、依据哪一行、还剩什么没定"。 全程只用 read/grep/glob 与纯文本统计命令；未构建、未安装、未运行 Electron、未截图、未冒烟/verify；未修改 repos/ 下任何文件。

1. 已读文件清单（Round 2）

1.1 ClassHelper（repos/ClassHelper-master，全部为只读）

文件 行数 本轮用途
docs/app/island.md 79 产品口径：fixed/custom、消息展示矩阵、编辑器、课程与课件、验证纪律
docs/dev/implementation.md 54 实现契约：方案存 config.json.islandLayout、单窗口、编辑页子路由
docs/dev/winisland-design-tokens.md 59 几何/度量/动画入口（已在上一轮读过，本轮复核）
docs/dev/testing.md 79 验证命令与"默认无头、--visual 才做桌面验收"纪律
packages/shared/src/types.ts（1050-1230 等片段） 1874 总 IslandMode/IslandNotificationKind/IslandLessonReminder/IslandNotification/IslandAppearance/IslandState、ScheduleDto、WeekParity
packages/shared/src/island-layout.ts 404 组件枚举、CLASSISLAND_ISLAND_METRICS、方案/行/节点 schema、默认值、normalizeIslandLayouts
packages/shared/src/constants.ts（多段） 680 总 DEFAULT_ISLAND_APPEARANCE、范围、停靠、风格、ISLAND_SIZE_DELTA、SHADOW_PAD、ISLAND_TYPE_SCALE、ISLAND_LIST_METRICS、PRIORITY_RANK/LABELS、CLIENT_UPDATE_IDLE_MS
packages/shared/src/class-plan.ts（1-100） 119 TIME_POINT_TYPES、IslandTimePointDto、ActiveClassPlanWeekDto
packages/shared/src/courseware.ts（grep） — COURSEWARE_ISLAND_SIZE={424,132}
src/core?: packages/desktop-client/src/island/main.ts 30 岛渲染入口、二次注入动效令牌
src/island/LayoutIslandApp.vue 76 布局选择/课件覆盖/订阅初始化
src/island/IslandApp.vue 683 经典岛全部逻辑（弹簧、圆角、胶囊、展开、命中、停靠、内容淡入）
src/island/CustomIslandRuntime.vue 528 自定义常驻：测量/三页淡入/铃铛/行渲染/命中
src/island/ComponentNode.vue 456 14 类组件渲染、课程表折叠、进度/徽标、编辑手柄、样式
src/island/IslandEditorNode.vue 124 编辑器标签节点 + 拖拽落点样式（属 renderer/components）
src/island/ClassicNotifications.vue 234 单条详情卡/多条列表卡/按钮行
src/island/LessonReminderContent.vue 318 课程提醒条、5 区斜切遮罩、进度条、徽标
src/island/CoursewareTransfer.vue 132 课件传输覆盖卡（尺寸/样式/进度）
src/island/WeatherBrief.vue 91 天气简报组件与码表映射
src/island/spring.ts / squircle.ts 115 / 81 弹簧参数、连续圆角路径
src/island/classic-island.css 757 经典岛根变量、形状/投影、胶囊/展开/列表/按钮/状态色
src/island/custom-island.css / custom-runtime.css / lesson-ending.css 205 / 255 / 16 自定义组件样式、常驻三页样式、秒数徽标
src/main/island.ts 2445 主进程岛控制器全文（分区间阅读 + 末段 IPC/尺寸函数）
src/main/lesson-reminder.ts 110 五类课程提醒计算
src/main/island-weather.ts 73 Open-Meteo 抓取/缓存/退避
src/main/index.ts（岛相关） 347 总 启动装配、岛初始化、打开应用/编辑器/已读回调、退出清理
src/main/tray.ts（岛相关） 78 托盘"编辑灵动岛布局"入口
src/main/courseware.ts（grep） — island.setCoursewareTransfer(value)
src/preload/island.ts 123 岛窗口 contextBridge 白名单
src/preload/index.ts 101 主窗口桥（含 island push/class state/mark-read 订阅）
src/renderer/island/bridge.ts 473 课表/上课状态/通知/作业/叫人/补弹/已读/生命周期
src/renderer/views/settings/IslandSettingsView.vue 512 设置页脚本 + 模板结构（family 入口需新增）
src/renderer/views/settings/IslandEditorView.vue（多段） 861 编辑器：保存队列/上限/方案/拖拽/应用/加载
src/renderer/components/IslandComponentSettings.vue 307 内容/外观/高级三页字段
src/renderer/components/IslandEditorNode.vue 124 编辑器节点 chip/容器/落点
src/renderer/styles/island-editor.css（选择器） 417 编辑器布局/预览画布/组件库/检查器样式
src/renderer/styles/index.css（grep 关键字） 892 总 与岛相关的全局 token（未逐行引用）
src/types/desktop.d.ts 294 桥接契约与配置形状（上一轮已读，本轮复核 island 部分）
src/main/config.ts 555 islandLayout/island 归一化、合并写、退出 flush（迁移接入点）
src/renderer/App.vue / layouts/ClientLayout.vue（岛相关） — 桥接生命周期、编辑页路由入口
AGENTS.md（自动注入） — §4 灵动岛硬约束、验证纪律

1.2 ClassIsland（本轮仅少量回查，复用上一轮 parts）

  • 上一轮产出的 parts/03,04,05,07,10,11,14 与 analysis/40-baseline.md（Lead 已整理），本轮引用其行高 40/行距 5/圆角 8/字号 14/16/18/20/进度条 3px/斜切遮罩权重等规格。
  • 直接回查：repos/ClassIsland/ClassIsland.Core/Models/Components/MainWindowLineSettings.cs（行隐藏规则语义）、ClassIsland.Shared/Models/Profile/TimeLayoutItem.cs:119-138（TimeType 0-3）、ClassIsland.Core/Models/Notification/NotificationRequest.cs:14-20（Mask/Overlay 5s 默认）。

1.3 团队上下文

  • analysis/50-refactor-brief.md（Round 2 总简报，含 8 条裁决与 §2.3 的 family/fixed 补充口径）
  • 共享任务 task-6（已认领/完成）
  • 上一轮本人产出：parts/02-tech-stack.md、parts/12-plugins-ipc.md、parts/13-data-storage.md、analysis/classhelper-stack.md（仅作技术栈与工程约定参考）

2. 关键行号表（本轮引用最频繁，供 Lead 复核）

主题 文件:行 事实
岛窗口创建 src/main/island.ts:480-512 透明/无边框/置顶/不占任务栏/独立 preload/sandbox
窗口导航白名单 src/main/island.ts:32-50,516-522 生产按精确 file URL、拒绝新开窗口
默认鼠标穿透 src/main/island.ts:527 setIgnoreMouseEvents(true,{forward:true})
固定包围盒 src/main/island.ts:1514-1648 windowBox/windowBounds，触摸贴合、自定义夹取
尺寸基线/增量 src/main/island.ts:72-112、packages/shared/src/constants.ts:344-351 胶囊 216×34；展开/紧急/叫人增量
收回动画 src/main/island.ts:1106-1164 CLOSE_ANIMATION_MS=360，先切胶囊再淡出
超时表 src/main/island.ts:121-132 pill 15s/展开 20s/紧急 45s/叫人 90s 等
消息分流 src/main/island.ts:794-867 紧急立即、上课暂存、普通叫人可点、预览展开
上课态迁移/课后补弹 src/main/island.ts:870-927 进入上课隐藏、下课恢复/补弹
动作状态机 src/main/island.ts:929-1077 expand/collapse/expand-list/dismiss(-all)/mark-read(-all)/open-app
双播合并 src/main/island.ts:704-724 同 id 合并，call/URGENT 不被降级
列表布局 src/main/island.ts:755-765、packages/shared/src/constants.ts:379-471 默认 3 行、hint more/app、safetyPad 6
命中轮询 src/main/island.ts:2049-2078 60ms 读光标，先换屏再命中
命中开关 src/main/island.ts:1795-1822 只由主进程关闭；触摸/编辑/自定义强制 true
岛体矩形 src/main/island.ts:1825-1836,1973-1997 渲染上报 50ms 限流；兜底 expectedHitRect
失焦宽限 src/main/island.ts:557-578,2287-2297 指针在岛上不收起；鼠标 500ms/触摸 1200ms
触摸模式 src/main/island.ts:245-316,1891-1902 贴合岛体+始终接收输入；setShape 仅 win32
窗口自愈 src/main/island.ts:2106-2152 心跳 20s 超时、10 分钟最多 3 次
外观归一化 src/main/island.ts:2225-2264 夹取+NaN fallback；范围与 shared 一致
IPC 注册 src/main/island.ts:2338-2438 全部 island:* handler 与发送方校验
渲染桥 src/preload/island.ts:14-121 window.island 白名单
数据桥 src/renderer/island/bridge.ts:148-172,416-473 每秒复算上课态、课表刷新、生命周期
经典渲染 src/island/IslandApp.vue:188-212,266-332,346-383,420-516 目标尺寸/圆角、弹簧帧循环、透明度、命中上报
自定义渲染 src/island/CustomIslandRuntime.vue:52-124,238-323 测量/适配/三页淡入/命中
组件渲染 src/island/ComponentNode.vue:29-210,212-293,294-454 折叠规则/条件渲染/组件样式
消息面板 src/island/ClassicNotifications.vue:104-233 列表/详情/按钮语义
课程提醒条 src/island/LessonReminderContent.vue:59-123,195-317 5 区遮罩 360ms/错峰、文字 260/250/750ms
课程提醒算法 src/main/lesson-reminder.ts:14-110 五类提醒窗口与 mask/ends 计算
天气 src/main/island-weather.ts:1-73 Open-Meteo、8s、64KB、15min 缓存、退避
课件覆盖 src/main/island.ts:661-676,1420-1429、CoursewareTransfer.vue:12-65 最高优先级覆盖；424×132
配置读写 src/main/config.ts:26-84,198-233,235-346 默认值/归一化/合并写/flush
布局 schema packages/shared/src/island-layout.ts:3-158,256-403 组件枚举/方案/行/节点/归一化上限
度量常量 packages/shared/src/island-layout.ts:19-36 ClassIsland：40/12/8/0.5/14-20/5/0.05
消息常量 packages/shared/src/constants.ts:183-209,344-402 优先级、尺寸增量、排版系数、列表度量
设置页 src/renderer/views/settings/IslandSettingsView.vue:26-160 外观/布局/预览逻辑
编辑器 src/renderer/views/settings/IslandEditorView.vue:81-105,290-337,338-540 保存队列/应用/拖拽/上限
组件设置 src/renderer/components/IslandComponentSettings.vue:26-307 内容/外观/高级字段与范围

3. 与 Lead 口径的对齐（family / fixed 重新定义）

Lead 补充口径已并入 04/05：

  1. appearance.family: 'classisland' | 'winisland' 新增，新装默认 classisland；老用户升级默认 winisland。落点：04 §4.0 第 5-6 条、§4.2 表、§4.3.1/4.3.2/4.3.3/4.3.4；05 §5.2/§5.4。
  2. fixed 重新定义：classisland 下 fixed = ClassIsland 风格信息行（默认 1 行 = 日期 + 课程表、行高 40、圆角 8、不透明度 0.5、3px 进度条、消息行内气泡）；原胶囊+详情卡只在 winisland 保留。落点：04 §4.3.2/4.3.3/4.3.4、05 §5.3 FixedSchemeV2。
  3. 文件级改造已覆盖 IslandApp.vue 的大改：迁为 family/winisland/ClassicIsland.vue（winisland 行为不变），新增 family/classisland/FixedInfoRow.vue + InlineMessageBubble.vue，LayoutIslandApp.vue 四象限分发；ClassicNotifications.vue → shell/MessagePanel.vue（detail/list/inline 三形态），LessonReminderContent.vue → shell/LessonBar.vue。
  4. 老 style(black/glass/tinted) 处理为兼容字段：新 canonical 字段 appearance.winislandStyle，读入优先新字段、回退旧字段，写出保留旧字段一个版本周期（05 §5.2/§5.10），避免旧配置文件解析断裂。

4. 未决项（需 Lead 或对应 part 拍板）

  1. fixed 信息行的默认行数与内容：我按"1 行 = 日期 + 课程表"写入 05；03/07 若无异议需保持一致。是否允许默认再加"当前课程进度/倒计时"由 07 定。
  2. 消息行内气泡的交互细节：行内气泡点击后是"展开行内详情"还是"打开应用通知中心"，以及多条气泡叠放/横向滚动规则，属 07/08 范围；04 只规定"业务状态机不变，只换表现"。
  3. classisland 的 Fluent/Classic 主题映射：04 用 appearance.theme: 'fluent'|'classic' 占位；具体颜色/圆角/阴影 token 归 06/03，需确认是否与 ClassIsland XAML 资源字典逐值对应。
  4. 行设置抽屉字段清单：04/05 定义了行级 appearance/hideRules/progress 的最小集；抽屉的完整分组与控件归 09，需与 05 schema 对齐后再定稿。
  5. style 字段的移除时间：建议 v3 移除；若 Lead 要求长期保留则改为永久兼容字段。
  6. smoke 断言改造归属：现状大量断言依赖旧 DOM/几何（如"固定包围盒全程不变"）；本轮未改 smoke，改造清单只列"需按 family 分套"，具体断言列表需 Lead 安排给验收负责人或在 11 部分细化。
  7. 自定义方案在 winisland family 下的视觉：04 §4.3.1 规定 custom 共用一套运行时、由 family 切样式变量；若希望 winisland 下有独立 custom 外观，需要再拆一套 CSS（当前判断为不必要）。
  8. classisland 信息行与"课程提醒"的叠加方式：我规定提醒条作为行覆盖层出现、不替换常态行（02 §2.8 现状语义）；07/08 若希望"提醒整行替换"需同步 05 的 fixed metrics。
  9. 天气组件是否保留 Open-Meteo：本轮只做岛重构，天气继续用现状实现（02 §2.9）；ClassIsland 天气服务仅作语义参考，不引入其服务端数据模型。
  10. schemaVersion 与 islandLayout.version 的关系：我定义为文件级 + 子结构级双版本；若 Lead 希望只保留一个版本号，需同步修改 05 §5.1 与 04 §4.3.12。
  11. 编辑器 855 行拆分节奏：04 要求先抽 composables 再改逻辑；若本轮排期紧，允许先抽 useIslandDraft，其余留到 M7。
  12. family 切换是否自动写 winislandStyle：当前迁移会写；新装用户从 classisland 切到 winisland 时是否保留 black 默认由 09 的 UI 决定。

5. 静态分析纪律声明

  • 全程只读：read 读文本、grep/glob 找文件、Select-String/Get-Content 做文本统计与结构梳理、[regex] 统计中文字符数。
  • 未执行 pnpm install/dev/build、electron、npm、verify:*、截图、冒烟或任何会弹窗/占用屏幕的命令。
  • 未修改 repos/ClassIsland 与 repos/ClassHelper-master 下任何文件；只写入了 parts-r/02-current-state.md、parts-r/04-file-plan.md、parts-r/05-data-migration.md、analysis/refactor-current-state.md。
  • 证据标注口径：packages/...:行号（ClassHelper）与 repos/ClassIsland/...:行号；无法从源码直接确认的工程设计一律标【推断】。
Reference in new issue View Git Blame Copy Permalink