课务台（Laosu Workbench）

一个把「排课、事务、日历」收进同一界面的 HanaAgent 全屏插件。 界面只读，所有变更交给 AI 执行 —— 这是它最核心的设计取舍。

---

这是什么

课务台是运行在 HanaAgent 内的全屏工作台插件，用来管理课程安排和日常事务。

它的定位比较特别：前端只负责展示，不负责操作。

你在界面上看到课表、待办、冲突提醒，但想调课、取消、加课——不是去点某个「编辑」按钮，而是唤起 AI，让 AI 去执行。所有真实写入统一走 AI 入口。

这样做的好处：

• 界面永远不会因为误点而改坏数据
• 所有变更都有预演（dry-run）和审计记录
• 复杂操作可以直接说人话（「把周三的课挪到周五，冲突就换下周」）

---

核心设计

1. 只读界面 + AI 执行

界面上每张卡片只有两个按钮：

• 确认 / 不确认 —— 处理需要你拍板的事
• 调 —— 点开直接唤起带该课上下文的 AI 对话框

取消、改期、补记这类操作全部收进详情和 AI，不在主界面暴露。

2. 所有写入必须预演

这是硬约束，不是建议：

规则	说明
不直接读写 SQLite	只通过 Python 脚本的 agent 契约
排课只调 schedule.py agent	事务只调 affairs.py agent
调课用 move	不用 cancel + add，避免丢失关联
所有真实写入先 dry-run	预演令牌 15 分钟有效、一次性使用
写入后回读	确认真的写进去了
事务写入带 --request-id	保证幂等
全量审计	预演和提交都记进插件私有审计日志

3. 冲突自动检测

刷新后统一检查三类冲突：课程×课程、课程×事务、事务×事务。

进行中的事务若缺结束时间，会明确提示「校验不完整」，而不是默默算错。

4. 外部改动自动感知

每 45 秒探测一次课表/事务库文件变化，变了就静默全量刷新。 其他 AI 会话的修改会自动带回界面 —— 适合多个 Agent 同时干活的场景。

---

界面结构

主导航三页：

• 总览 —— 三层：下一节课（现在做什么）→ 行动中心（欠什么决定）→ 周/月视图（安排全貌）
• 筹备 —— 试排空档、驾驶舱
• 事务 —— 待处理 / 已安排 / 已完成·已取消，列表与日历双视图

两条队列互斥

• 待处理：只收需要人来决定的事（课程复核、过期未标记、真实冲突），按冲突 → 过期 → 复核排序
• 建议处理：只收系统级优化建议（日历差异等），可折叠

同一事务只出现一次，不会重复打扰。

---

技术栈

• 运行环境：HanaAgent 插件（@hana/plugin-runtime / plugin-sdk / plugin-components）
• 前端：React 19 + Vite
• 后端：Node.js（≥ 22.6.0）
• 数据层：Python 3 脚本（排课 / 事务 / 日历同步）

与后端系统的契约

课务台不直接碰数据库，全部通过 Python 脚本的 agent 接口：

能力	脚本	契约要求
排课	schedule.py agent	schema ≥ 7（contract v2）
事务	affairs.py agent	带 writer 锁校验
飞书日历同步	sync_to_calendar.py	固定使用 --prune

---

安装与配置

前置条件

• HanaAgent ≥ 0.333.0
• Node.js ≥ 22.6.0
• Python 3
• 三个后端脚本（排课 / 事务 / 日历同步）

路径配置

默认路径如下，都可通过环境变量覆盖：

环境变量	默认路径
LAOSU_SCHEDULE_SCRIPT	~/laosu-workspace/库管理与索引/老苏排课系统/schedule.py
LAOSU_AFFAIRS_SCRIPT	~/Shared/Hana主动式事务系统/affairs.py
LAOSU_CALENDAR_SYNC_SCRIPT	~/laosu-workspace/库管理与索引/老苏排课系统/sync_to_calendar.py

数据库路径同样可覆盖：LAOSU_SCHEDULE_DB、LAOSU_AFFAIRS_DB。

首次使用某个能力时会校验脚本路径，找不到就返回明确错误，不会静默失败。

开发

npm install
npm run verify    # 类型检查 + 语法检查 + 测试 + UI 构建
npm run release   # 一条命令发版（校验/备份/打包/部署/commit）

---

关于这个仓库

课务台原本为个人使用而写，有些设计带着强烈的个人习惯：

• 强调「确认/不确认」而非自由编辑
• 冲突和过期提醒很啰嗦
• 与飞书日历深度绑定

如果你要复用，后端那三个 Python 脚本需要你自己实现 —— 课务台只认它们暴露的 agent 契约，不关心你内部怎么存数据。契约要求见上文。

---

版本演进

课务台从 v1.1.1 一路迭代到 v2.12.10，大致可以分成四个阶段。

阶段一：基础与视觉语言（v1.1.1 – v1.8.0）

版本	主要变化
v1.1.1	安全与稳定性修复：renderShell XSS 注入点、快照缓存并发旧回写、部分成功时缓存失效、course_day_complete 提交前当日快照复核、review resolve 重复导出、拒绝 - 开头的 argv 参数
v1.3.0	「留痕轮」：schedule.py events 与 affairs.py timeline 增加 --include-finished；已完成课程用独立石板色（--wb-state-finished: #6e8290），已取消用灰色，周/月/时间轴不再隐藏结束项
v1.4.0	交互统一第一轮：周视图列数随容器宽度连续自适应（每天保底 150px），点日期头原地聚焦单日（Esc 退出）；触屏轻点语义统一——有详情的卡进抽屉，纯操作卡原地展开
v1.5.0	交互统一第二轮：新增 WorkbenchNav 组件，总览 scope 切换与筹备分区同形；四页统一 PageTitle；对象级反馈统一为 InlineResult 小字
v1.5.1	留痕规则修正：画布只保留上过课的（已完成·石板色），过去的已取消/已调课不再上画布；过期未标记课程转琥珀色并标注「（过期）」
v1.6.0	驾驶舱归一：色板 token、字号阶、圆角统一，today 描边从蓝色改为品牌色
v1.7.0	排版归一：清除 panel.css 里 12 处刻意使用衬线体的展示层样式，全部改为继承无衬线栈，展示字号收进统一字阶
v1.8.0	「无线框化」：老苏定调「所有框都是无线的框、小字要加粗」——卡框与按钮发丝线全部改透明，元信息小字统一字重

阶段二：AI 化与自动化（v2.0.0 – v2.9.0）

版本	主要变化
v2.0.0	AI 插口成型。引入 lib/operations.js 操作注册表（AI 提示词列表 / 路由白名单 / 工具枚举三者同源，加能力只需加一条）；AI 追问带可点 chips；支持批量意图（AI 返回多个操作 → 逐条预演 → 「全部执行」逐条提交，首败即停）。北极星：一句话办成事
v2.1.0	主动建议系统：buildSuggestionCards 纯函数生成建议卡（过期课、当天到期预约、限期过期、日历差异、明日速览）；外部改动感知（/api/data-revision 返回两库 mtime，前端 45 秒轮询，变化即静默刷新）
v2.2.0	总览布局改为主列＋边栏两块，解决「顶层堆三个通栏」；按钮体系统一（字重 620、圆角 8px）；残留杂色归入色板
v2.4.0	全站按钮彻底无线化（此前只覆盖了部分按钮类，导致建议卡掉回浏览器默认黑框外观）；事务页固定本月视图，与总览时间范围解耦
v2.5.0	交互铁律落地：老苏明确「一两步的事按钮点一下，两步以上的事调 AI 说一句」。决策类动作全部一键化，新增 /api/courses/overdue-complete、/api/affairs/complete 等快捷路由
v2.6.0	事务页改版：待处理 / 已安排 / 已完成·已取消 三状态 + 列表与日历双视图；日历按状态着色
v2.7.0	建议卡「点了就办」：每个建议卡后台完成预演+提交+回读，成功即消失；建议引擎加入冲突扫描
v2.8.0	全量冲突审计：五大审计全跑并根修（8/31 两个事务缺 end_at 导致假冲突，补上后归零）
v2.9.0	全自动化三件套：① 日历差异自愈（签名去重 + 10 分钟最小间隔）；② fs.watch 即时感知，前端轮询 45s→15s；③ 定时事务缺 end_at 自动检测并一键补齐；④ 发版全自动化（npm run release 完成校验→备份→双槽部署→commit）

阶段三：形态收敛（v2.10.0 – v2.11.0）

版本	主要变化
v2.10.0	两键形态定调：老苏最终确定每张卡只有两个按钮——「确认/不确认」＋「调」（点开直接是带该课上下文的 AI）。课程卡、时间轴、下一节课、详情抽屉全部统一；AI 输入框增加语音按钮
v2.11.0	配色基准统一：--wb-accent 钉死为鼠尾草绿 #547362（此前继承宿主蓝色 accent，是配色不统一的根源）；建议卡按钮统一浅绿章；待处理空面板自动瘦身。同时修复发版脚本的版本号 bug

v2.11.0 的教训：版本号 bump 不能用「替换旧版本号」的写法（旧号对不上会静默 no-op，差点把 v2.11.0 发成 2.10.0），必须 json 赋值 + 回读校验。

阶段四：视图与稳定性打磨（v2.12.0 – v2.12.10）

版本	主要变化
v2.12.0	Visual ID v2.12 全量统一：新增独立 design-system.css 作为最终视觉身份层，统一品牌色、状态色、表面层级、字阶、圆角、控件高度、触屏尺寸；只覆盖表现层，不动业务接口与状态机
v2.12.1	两条队列互斥：待处理只收需要人决定的事（按冲突→过期→复核排序，不可收起），建议处理只收系统优化（可收起）；同一事务只出现一次
v2.12.2	总览收敛为三层：下一节课 → 行动中心 → 周/月视图；删除四个重复指标块；驾驶舱并入筹备页
v2.12.3	过期课在待处理区逐节成卡，超 4 节才提供批量转复核兜底；新增快速路由 /api/reservations/cancel-quick
v2.12.4	打开固定进入周视图，只保留周/月两视图；固定课程与已确定事务进同一张时间表；刷新后统一检查三类冲突；统计排定课程节数、总课时、已完成课时
v2.12.5	月视图当天安排改为高密度卡片，一屏可看约 8–9 人；紧凑模式保留类型、时间、姓名、状态
v2.12.6	顶栏新增页面缩放控件（自动适配 70%–100%）；周视图取消窄屏分页，任何宽度下保持周一至周日七列
v2.12.7	周视图与月视图取消窄窗口强制最小宽度，七列完整铺开；全局收紧间距、圆角与阴影；中窄窗口顶栏改上下两层
v2.12.8	只读接口遇到短暂会话切换或 5xx 自动重试一次（写操作绝不自动重放）；手动刷新失败时保留当前课表并直接显示实际失败原因
v2.12.9	手动刷新改为非阻塞更新：课表保持可看可用，只让刷新按钮进入忙碌态；连续点击只执行一次
v2.12.10	外部 AI 或底层系统写入数据后，自动轮询改为强制重读，不再命中 30 秒旧快照；只有静默刷新成功才消费数据版本号，失败下一轮继续尝试

---

变更日志

展开完整变更历史

## v2.12.10

• 外部 AI 或底层系统写入数据后，自动轮询改为强制重读，不再命中 30 秒旧快照。
• 只有静默刷新成功后才消费数据版本号；失败会在下一轮继续尝试，避免页面长期停在旧数据。

v2.12.9

• 手动刷新改为非阻塞更新：课表保持可看可用，只让刷新按钮进入忙碌态。
• 连续点击只执行一次刷新，自动轮询在手动刷新期间暂停，避免请求互相覆盖。
• 刷新按钮增加明确的“刷新中”状态和轻量旋转反馈。

v2.12.8

• 只读接口遇到短暂页面会话切换或 5xx 错误时自动重试一次；写操作绝不自动重放。
• 手动刷新失败时保留当前课表，不再用红色页面错误覆盖已有数据，并直接显示实际失败原因。

v2.12.7

• 周视图与月视图取消窄窗口强制最小宽度，七列在当前窗口内完整铺开。
• 全局收紧日期列、时间轴、卡片间距、圆角与阴影，减少列宽和空白占用。
• 中窄窗口顶栏改为上下两层，所有控件禁止逐字竖排；手机宽度下刷新按钮收为图标。

v2.12.6

• 顶栏新增页面缩放控件：自动适配 70%–100%，也可手动缩小、放大或恢复自动
• 周视图取消窄屏分页和单日聚焦，任何窗口宽度下都保持周一至周日七列
• 月视图继续固定七列；周/月画布在窄窗口使用紧凑间距与字号，日期详情抽屉不参与主画布缩放
• 修正窄窗口下时间轴、日期列和顶部工具区比例失衡，画布不再依赖横向拖动

v2.12.5

• 月视图点击某一天后的当天安排列表改为高密度卡片，一屏可同时查看约 8–9 人
• 紧凑模式保留类型、时间、姓名和状态；次要备注在当天列表中隐藏，单项详情样式不受影响

v2.12.4

• 打开固定进入周视图；功能范围只保留周视图和月视图
• 固定课程与已确定事务进入同一张时间表，临时预留退出第一展示位置
• 周/月画布与详情抽屉全部只读，顶部保留 AI 操作、系统状态和“刷新本地数据”
• 刷新后统一检查课程×课程、课程×事务、事务×事务冲突；进行中事务缺结束时间时明确提示校验不完整
• 月视图统计排定课程节数、总课时和已完成课时；统计不含取消、调课旧记录
• 画布过滤已取消、已调课、已删除及完全重复记录，保留真实已完成课程
• 正式课务全部落盘确认后，可按固定模板每周幂等生成；照常上课走模板，临时调课走 move，因故不上走单次 cancel

当前能力

• Visual ID v2.12 全量统一：新增独立 design-system.css 作为最终视觉身份层，统一品牌色、状态色、表面层级、字阶、圆角、控件高度、焦点和触屏尺寸；只覆盖表现层，不改业务接口、状态机和操作流程

• 组件身份统一：一级导航、二级导航、状态徽章、标题、抽屉和高频动作补齐稳定 data-ui 语义；所有高频调课按键统一为「调时间」

• 按钮统一为 primary／secondary／danger／quiet／icon 五类，桌面和窄屏共享同一角色色、字重、圆角与禁用反馈

• 配色基准统一：全站强调色钉死为鼠尾草绿；待处理用低浓度琥珀、系统建议用低浓度鼠尾草绿，空行动队列不渲染

• 交互铁律全量落地：每张卡只有两个按钮——「确认/不确认」＋「调」（点开直接是带该课上下文的 AI）；取消等其余操作收进详情与 AI

• AI 调课入口贯穿所有视图：总览卡片、时间轴、下一节课、详情抽屉、筹备试排空档，点开即预填该课信息；AI 输入框支持语音（浏览器支持时显示麦克风）

• 全自动：飞书日历差异自愈只写真实变化项；无变化事件进入 unchanged，不再重复 update/颜色/提醒 patch

• 正式槽与开发槽共享唯一后台租约、日历状态、预演和审计；双槽临时并存时只有一个实例执行自动对账与数据监听

• 飞书健康只比较托管事件，手工日历事件不再误报；对账失败、状态过期和真实差异进入总览健康

• 仅仍在推进的定时事务缺结束时间时生成建议；已完成/已取消的历史留痕不再误报

• 一条命令发版：npm run release（校验/正式槽备份/打包/单槽部署/本地 commit）；热载与开发槽清理由 Hana 插件开发工具完成

• 两条队列互斥：待处理只收需要老苏决定/补记的事项，建议处理只收可选系统优化；同一事务只出现一次

• 待处理不可收起：课程复核、过期未标记、真实时间冲突进入主队列，按冲突→过期→复核排序，状态解决后才退出

• 建议处理可收起：日历差异、活跃事务缺结束时间等系统优化降为行动中心内的折叠次级层；明日课表等纯信息不占处理队列

• 事务页改版：待处理/已安排/已完成·已取消三个状态按键，另配列表/日历双视图——本月事务按状态着色铺进月历（与总览同款），点开任何一天看当天安排与详细交互

• 交互铁律落地：决策类动作全部一键化（本次不上、完成、没约上、取消预留、过期课已上/没上），预演+提交+回读在后台完成；两步以上的事交给 AI

• 过期课在待处理区逐节成卡：看到即决策（老苏即人工），超 4 节才提供批量转复核兜底

• 新增快速路由：/api/courses/overdue-complete（转复核+确认完成合并执行）、/api/affairs/complete、/api/reservations/cancel-quick

• 按钮彻底无线化：全站按钮去边框去系统外观，建议卡按钮补齐底色层级

• 事务页固定本月视图（含已完成/已取消留痕），与总览时间范围解耦——这个月做了什么一眼可见

• 按钮彻底无线化：全站按钮去边框、去系统外观，统一纯底色/文字层级

• 总览收敛为三层：下一节课（现在做什么）→ 行动中心（欠什么决定）→ 周/月视图（安排全貌）；删除课程数、待办数、下一项、系统正常四个重复指标块

• 按钮体系统一：同字重同圆角档，主要/次要/危险角色色全走色板；健康点、事务图标、日历对账等残留杂色归入色板

• 驾驶舱并入筹备页「试排」分区，主导航收敛为总览/筹备/事务三页

• 总览行动中心统一聚合事务 pending 与课程待决策卡；预约/限期事务不再重复生成，整块为空时彻底隐藏；下一节课为空也不占位，今日收课只在当天已结束且仍有课程待记录时出现

• 外部改动自动感知：每 45 秒探测课表/事务库文件变化，变化即静默全量刷新（其他 AI 会话的修改自动带回）

• 事务库每周维护挂入 Hana 定时（周日 23:40 agent prune）

• AI 交互升级：追问带可点选项（点一下继续，不用打字）；一句话出多步批量方案，整批预演、逐条提交、首败即停

• 操作注册表（lib/operations.js）：AI 提示词、路由白名单、Agent 工具枚举同源，新增能力只需加一条定义

• 交互简化第一轮：打开页面秒开（上次数据即显＋后台全量重扫本地课表与事务系统，外部 AI 改动自动带回）；刷新一键扫总览/筹备/驾驶舱/AI 上下文；卡片 hover 只留高频一键（本次不上、完成、没约上），调整时间与取消统一走详情；筹备 5 分区收敛为 3 分区

• 全站无线框化：卡框与按钮去线（输入框保留），以底色和阴影分层；元信息类小字统一加粗，对齐总览参照系

• 全站排版统一：展示层（页标题、指标数字、时刻、阶段数字）全部转无衬线并收进全局字阶，清除残留宋体衬线

• 驾驶舱排版并入全局设计语言：卡色、字号、圆角、today 强调色、每列最小宽度与周视图对齐，不再是突兀的第二套 UI

• 交互语法统一第二轮：总览与筹备共用同一导航组件（workbench-nav），四页统一 PageTitle 标题区，对象级反馈统一为 inline-result 小字

• 留痕规则修正：画布只保留上过课（已完成·石板色）；已取消/已调课不再回到画布；过期未标记课程以琥珀“过期”提示，不再显示为绿色待上课

• 交互语法统一第一轮：轻点即详情、单日聚焦、列数随窗口自适应

• 结束的课程和事务不再从视图消失：周/月/时间轴带留痕展示，已完成用独立石板色，已取消用灰色降低色度

• 对接 schedule events --include-finished 与 timeline --include-finished；冲突检查、简报等链路保持默认过滤

• 新增「修改事务」：改时间、标题、优先级、备注，走 dry-run 预演，带版本与冲突校验，不再需要取消重建

• 「没约上」推进后可在原地一键「撤销推进」（retry-prev，恢复上一候选日），带版本并发保护

• 新建/修改事务支持「办成前每日跟进」（follow_up=daily）：按每日窗口提醒，约上或完成后自动静默

• 对接事务系统 schema 5：follow_up 字段、scan follow_ups 与 agent prune 保留期清理

• 页面启动失败提示使用 textContent 写入，错误消息不再拼接 HTML，消除注入点

• 快照缓存带请求序号门：并发下先发出、后完成的旧读取不会回写新缓存

• 预演提交只要主写入落库就立即失效数据缓存；导出失败时页面同样回读真实状态

• “今日课程已上完”提交前复核当日待上课程快照，预演后课表变化会被拦截并要求重新预演

• 复核处理不再触发重复工作簿导出（底层 review 写入已自动导出）

• 批量调课计划中途失败会写入孤儿计划审计（plan_orphaned），便于定期清理

• 操作文本不允许以“-”开头，避免被底层命令行误认为选项参数

• 事务截止日过期显示“已过 N 天”，不再出现负数天数

• 「课务台」全屏页面，三项主导航保持居中

• AI 操作使用右侧抽屉，保留原页面上下文；系统状态保留为二级入口

• 统一工作台视觉语言：采用无边线模块，以底色、留白和轻阴影区分层级

• 放大顶部三项主导航，强化主要切换入口

• 重新平衡主内容宽度、左右栏比例、卡片高度和模块间距

• 移除顶部重复品牌展示，保留导航与功能入口

• 顶栏左侧留空，主导航保持居中

• 总览、筹备、事务和详情共用同一套无边线颜色语法：绿色表示已确认/已完成，琥珀色表示待确认/待处理，红色表示错误/硬阻塞；临时身份以蓝色小圆点叠加，不覆盖状态色

• 筹备页使用结构化排课数据，按“周视图→资料准备→模板体检→课程预留→正式落课”形成闭环；周视图分临时预留与正式固定两层，窄窗口自动切换为每页三天并提供视图翻页按钮

• 卡片统一遵循“指向谁就原地处理谁”：待落课显示“调整时间｜确认落课”，已落课显示“调整时间｜本次不上”；触屏轻点卡片打开相同操作

• 总表课程、下一节课、普通事务、预约型事务和事务列表共用原地双动作：课程“调整时间｜本次不上”，普通事务“完成｜取消”，预约型事务“完成｜没约上”

• 事务页将“已安排”和“已完成／已取消”分区展示：进行中记录在前，完成历史在后并降低色度

• 系统状态覆盖事务、排课、学生、通勤和后续课程读取链路；写入预演令牌保留失败结果，只有成功提交后才清理

• 筹备确认落课成功或失败后自动刷新筹备数据，提交中的预演不会被内部重复检查误判；提交中保留可提交标记，避免状态机自我阻塞

• 课程主提交与飞书日历同步分层判定：快速连续落课时同步串行重试，日历锁竞争不再把已写入课程误报为失败

• 页面接口对非 2xx、非 JSON 和结构缺失统一报可读错误；渲染异常由 ErrorBoundary 隔离，不再整页白屏

• 兼容 Hana 0.450.0 静态资源鉴权：页面短期 token 仅用于同插件 CSS/JS，业务 XHR 继续走 hana.api.fetch

• 总览、预演和 AI 请求均有最新请求门，旧响应不能覆盖新范围或新表单

• 手动刷新强制绕过快照；快照具备并发合并与 epoch 失效，旧读取不能回写新缓存

• 中断的 committing 预演在启动时恢复为锁定失败记录；审计与令牌收尾故障不再反向误报主写入结果

• 日历同步使用 generation 队列，首次失败也会消费执行中新增的同步请求

• 总览、筹备与 AI 统一使用上海时区 04:00 日界线

• 确认落课只等待预演、写入与本地验证；飞书同步持久化后台执行，全端数据静默刷新并先在当前卡片即时显示已落课

• 已完成或已取消对象不再显示写操作；加载、失败和硬约束在原对象附近反馈，禁用原因不依赖系统黑色 title 提示

• 周视图列数随窗口宽度连续自适应（每天保底 150px，1–7 天），窗口大小决定每页天数，不再是单一断点

• 点击周视图日期头原地聚焦单日大图（更大时间格），Esc 或“返回整周”退出；总览与筹备周视图同款交互

• 触屏轻点语义统一：有详情的卡片轻点即进详情抽屉（操作在详情内完成），筹备纯操作卡保持原地展开；桌面 hover 原地快捷操作不变

• 驾驶舱卡片配色并进全局状态色板；月历条目字号提升到 10px

• 周/月视图只用颜色区分课程与事务，不再设置独立事务栏；同一时刻冲突自动并排

• 学生缺口支持就地设置片区、长期候选时间、预留课程和补录通勤；已有具体单日预留时不再误判为缺时间

• 全局字号、行高和密集信息区域已重新分级；窄窗口会放大正文、控件和时间卡片，避免缩窄后难以阅读

• 顶栏三项主视图是唯一一级导航；统计卡只展示数据，不再重复跳页

• 系统状态、日期详情和条目详情统一使用右侧抽屉及返回键

• 总览待办支持快捷完成与“没约上”，移除重复的跨页入口

• 实时读取 schedule.py agent 和 affairs.py agent

• Agent 工具：读取看板、预演变更、提交一次性预演令牌

• 课程行一键带入调课预演；事务行快捷带入完成/取消/重试推进

• 记住上次标签与时间范围，显示最后更新时间

• 下一节课卡片、课间通勤时长与最晚出发时间；首节课明确提示缺少固定起点数据

• 新建课程、新建事务均走 dry-run 预演

• 今日课程结束后可一键预演“今日课程已上完”，确认后写入本地课表、导出工作簿并同步飞书日历

• AI 抽屉默认是自然语言工作台：直接说学生和目标，系统追问、生成预演，再进入确认链路

• 执行完成后原路返回；抽屉支持统一返回键、浏览器返回、焦点闭环和草稿保持

• 各标签记住独立滚动位置；时间范围切换提供加载反馈和人性化日期

• 精确表单保留为兜底能力，打开型动作统一使用省略号提示后续确认

• AI 支持新建、调课、取消、预留、事务处理与日历同步

• “筹备”视图将采集、预留、片区和可用时间结构化展示，并保留底层文本证据

• 筹备文本解析配有固定样本测试和失败回退提示

• 支持预留新增/确认/取消；出游、重复课程和老师冲突继续硬校验，通勤只在排具体时间时询问并展示提示，不再锁定落课；失败反馈不再覆盖课程卡片

• 多项调课进入 schedule plan，顺序预演、数据库版本校验、备份、原子提交、导出和日历同步

• 调课、事务完成/取消/重试推进、飞书日历同步

• 事务“没约上”一键完成后台预演、提交、回读和刷新，不再跳转二次确认

• 排课与事务操作统一提供点击反馈、处理中状态和原地结果；跳转型操作明确提示尚未执行

• 今日时间轴右上角提供“全部上完”，每节待上课程提供“没上”，均走后台预演、提交、回读与同步

• 聊天 WebView 卡片与全屏页面联动

安全契约

• 不直接读取或写入 SQLite
• 排课只调用 schedule.py agent
• 事务只调用 affairs.py agent
• 调课只使用 move，不使用 cancel + add
• 所有真实写入必须先 dry-run
• 对接 schedule schema >= 7（contract v2）：课程来源、周期范围、预留关联与单次 availability 覆盖均为结构化字段
• 新建/调课只有在具体单次时间已明确时才传 --override-availability，不会修改长期候选时间
• 预演令牌 15 分钟有效、一次性使用
• 正式写入后执行回读；日历同步固定使用 --prune
• 事务写入附带 --request-id 幂等标识
• 写入前校验排课/事务契约版本和事务 writer 锁
• 预演与提交记录到插件私有审计日志

本机依赖

• Python 3
• ~/laosu-workspace/苏据库/库管理与索引/老苏排课系统/schedule.py
• ~/Shared/Hana主动式事务系统/affairs.py
• ~/laosu-workspace/苏据库/库管理与索引/老苏排课系统/sync_to_calendar.py

以上路径可通过环境变量覆盖：LAOSU_SCHEDULE_SCRIPT、LAOSU_AFFAIRS_SCRIPT、LAOSU_CALENDAR_SYNC_SCRIPT；首次使用对应能力时会校验脚本路径并返回明确错误。

开发

npm install
npm run verify

源码在工作区维护，通过 Hana Plugin Dev Loop 加载。页面和工具均走公开插件接口。

---

许可

MIT