Mikansei · iPhone 原生首版

把课堂作业、社团工作和日常琐事放在一张随时可见的待办清单里。先用一句话记下，再补充截止时间、提交平台、处理地点和耗时。

项目目录、App 显示名、Xcode target / scheme 和 Swift 模块已统一为 Mikansei。工程保留你在 Xcode 中选择的 Team 和 Bundle Identifier；手机数据目录和通知内部编号继续使用原值，保留已安装版本的数据和提醒。

当前版本 0.3.0 (4)：新增 iCloud Drive 文件夹同步和原生 macOS 版本，两端共享待办、日程、笔记、Checklist、完成状态、计时与课表。沿用免费团队，首次在两端选择同一个 iCloud Drive 文件夹即可，见 同步步骤 和 Mac 安装与使用。

另有独立的 Mikanseta Flutter 测试版，当前为 0.2.0 (4)，使用牛皮浅棕主题。日 / 周日历拖动选时段、课表与消息解析、提醒、小组件、实时活动、Apple 日历及 Android 系统服务的迁移源码已接入；Dart 静态检查与 44 项测试通过，Android Release APK 与 iOS 模拟器构建通过。原生服务尚未在设备上验收，Android 系统日历编辑结果即时回流仍未实现。iCloud Drive 云同步继续未迁移。两个 App 可并存，本机数据分别保存。新版 Android 安装包及验证范围见 安卓安装与打包 和 验证记录。

已实现

• 待办首页：“已超时”在最前，其次正在做、待完成；每个栏目内按紧急 → 重要 → 普通，再按截止时间由近到远排序，同优先级无日期事项在后。
• 完成与历史：勾选立即反馈，以短淡入淡出更新“今日已完成”；清单按需渲染，文件与小组件写入在后台串行执行；按手机当地日期跨天后归入历史记录，可重新打开。启用系统“减弱动态效果”时减少动画。
• 主屏幕小组件：今日清单（小 / 中 / 大）、快速添加（小 / 中）、今日进度（小尺寸及锁屏）。点事项打开详情，点快速添加直接填写待办、作业或笔记。今日清单包括已超时、今天截止、无日期和今日完成的事项。
• 正在做 · 计时：小 / 中尺寸和锁屏矩形小组件，显示当前事项与累计用时。在清单点“开始做”启动，暂停保留用时，继续累加；开始另一件事会自动暂停前一件，完成时停止。小组件的暂停 / 继续按钮会打开 App 并执行动作。
• 清晰选项：类型、视图切换使用实色选中态；可点击选项使用更清楚的文字与自适应深浅色强调色。
• 低成本录入：点击 +，输入一句话就能保存；今天、明天快捷截止时间；详细字段按需展开。
• Checklist：事项与笔记都能拆成小步骤，首页直接勾选，保留进度。
• 日程：以开始时间为核心，输入持续分钟数或全天的天数，自动计算结束时间；默认闹钟、按开始时间提醒，不作为逾期 DDL。
• 具体信息：作业科目、优先级、DDL、平台、地点、预计耗时、消息原文。
• 一次性 / routine 提醒：按设定时间提醒；常态是独立标签，可加在待办和日程上；支持每天、每周多选星期、每两周、每月（缺日取月末）、自定义间隔，以及跨月点选不规律日期。完成后生成下一次，未完成的 routine 也会按后续周期提醒。
• 可选催办：单次、分阶段、截止后每两小时提醒至 24 小时；默认单次，可在每件事项的详情中调整。
• 课后登记：按课表的下课时间通知，询问作业、DDL、平台、耗时；点击通知直接新建该课作业，课程名和平台已预填。
• 课表导入：CSV 和受限的 ICS；先预览确认，再保存与申请通知权限。
• 系统日历自动导入：首次允许读取后，每次打开或回到 App 都导入选定日历中未来 30 天（含今天）的事件；按开始时间安排，带入地点、备注、链接。重复事件逐次导入，不重复添加；保留勾选、计时与手动修改。设置里按名称 / 颜色勾选来源、改为结束时间或关闭同步；首次不默认勾选节假日等任何来源。
• 群消息辅助录入：从 QQ 等渠道复制一件事相关的文字，在 App 粘贴；本地规则给出日期、平台和耗时建议，核对后才保存。
• 笔记与备份：本机 JSON 持久化、原子保存、合并导入 / 导出，浅色与深色界面。

安装到你的 iPhone

更短的安装流程见 三步准备与双击安装。完成首次签名和手机确认后，双击项目根目录的 安装到iPhone.command，自动编译、安装并尝试启动。

1. 用 Xcode 打开 Mikansei.xcodeproj，选择 Mikansei scheme。
2. 在 target 的 Signing & Capabilities 中选择你的 Team；将 Bundle Identifier 改为你自己的唯一标识，例如 com.yourname.mikansei。
3. 连接并信任 iPhone，选择它作为运行设备。需要 iOS 17 或更新版本。
4. 如果 Xcode 提示缺少平台，到 Xcode → Settings → Components 安装对应的 iOS 支持组件。
5. 按 Xcode 的提示在手机上开启开发者模式并信任开发签名，点击 Run。
6. 首次设置提醒时允许通知；在 App 左上角设置中添加课表或导入文件。

这是用于个人试用的开发工程。此前版本通过 Personal Team 签名验证；本轮改动已在 Xcode 编译、签名并安装到 iPhone，界面与真机交互仍需验证。后续分发可在完成真机验证后考虑 TestFlight。

App 图标

0.2.1 (3) 使用选定的第二版绿色角色图标，保留长发、环状呆毛和简化神态。原稿在 App/Artwork/AppIconSource.png；执行 swift Scripts/make_icon.swift 可重新导出 Assets 与独立 PNG 的所有尺寸。图标由 iOS 裁切圆角，看板娘立绘仍为候选设计。

课表与 HUSToday

当前没有直连 HUSToday 的接口，也没有验证其未来的实际 ICS 输出。导入入口已准备好；有真实导出文件后，需要对照日期、单双周、调课与时区做适配验证。

可切换的日程视图

在 日程 → 日历 切换为苹果日历风格的日期浏览，支持 月历 / 日视图，同时保留 今日聚焦 / 列表。App 会记住视图选择。

• 月历支持翻月、回到今天、日期选择与事项标记，点击日期显示当天日程和 DDL。
• 日视图按小时显示实际执行时段；重叠时段并排显示，跨午夜时段在相应日期截取显示，当前时间有红线。全天事项和 DDL 单独显示，DDL 不占据执行时段。
• 点击日程打开原事项与 Checklist；日期旁的加号可以添加当天 DDL 或日程；长按月历日期添加当天日程，长按日时间轴空白处按位置预填开始时间（15 分钟对齐）。无日期事项继续在清单中查看。
• 可在日历显示选项中隐藏已完成；默认保留已完成并显示划线。日历视图显示 App 已记录 / 导入的数据，自动导入仍为今天起 30 天。

日程与常态（Routine）

新建事项选择 日程，或在日历模式长按空白日期 / 时段。填写开始时间和持续时间，结束时间自动计算；全天日程只需填写天数。日程默认按开始时间用闹钟提醒，iOS 26 以下可改用弹窗。

在事项详情 标签 → 常态（Routine） 开启规律。常态可以加在待办、作业或日程上，并可通过清单的“常态”筛选查看：

• 每天、自定义天数；每周可以选择多个星期，未选择时沿用首次发生的星期。
• 每月或每隔数月，沿用首次发生的日号；比如 1 月 31 日 → 2 月末 → 3 月 31 日。
• “日历选日”支持翻月、多选不连续日期；沿用首次发生的时刻，选完的最后一次之后不再生成。
• 完成当前事项后生成下一次，跳过已错过的周期；Checklist 和计时从零开始。未完成时仍会安排后续提醒，日历展示未来发生日期，点选可编辑整条常态规则。
• 苹果日历重复事件按每次分别导入，重复规律由来源日历管理，避免在两边重复生成。

DDL 实时活动 · 锁屏与灵动岛

在 设置 → 锁屏与灵动岛 · 实时活动 → 自动显示今日 DDL 开启，无需添加锁屏小组件。打开 App 时展示今日、超时及无日期的未完成事项，按重要级，再按 DDL / 日程开始时间排序；最重要的一件作为标题，下面列出另外两件及剩余数量。点击活动或事项进入清单 / 详情。

• 使用 ActivityKit，支持 iOS 17+；锁屏展示卡片，支持灵动岛的机型展示紧凑、最小与展开布局。与 AlarmKit 闹钟的实时活动独立。
• 倒计时使用系统动态时间文字，App 退出或挂起后继续显示，到零停止而不反向计时。日程计到开始时间，无日期显示“无时限”。已超时事项在下一次 App 更新时显示超时；不依赖每秒运行 App。
• 保存、完成、删除和改期后更新同一条活动；没有今日待办时结束。系统收起或超时结束后，回到 App 可恢复；手动收起的当日活动可通过“重新显示 / 更新”恢复。关闭开关会结束活动。
• 使用本地摘要，不发送任务到服务器，不包含备注、平台、群消息或 Checklist 正文。锁屏只显示前三件，完整列表在 App 内。
• 苹果限制单次实时活动最长 8 小时；本版没有服务器推送来重启活动或在 App 未运行时刷新任务列表。日期跨天后旧卡片提示更新，回到 App 更新今日内容。系统实时活动权限需开启。

设置页版本从安装包读取；此版为 0.3.0 (4)，iPhone、Mac 与 iPhone 扩展保持一致。

清单和日历的分工

• 先记下来：一句话即可成为待办；无需日期。DDL 只代表最晚何时完成，也不自动创建日历事件。
• 实际安排：确定执行时段后，在事项详情中点“保存并安排到苹果日历”，通过系统编辑页选择日历、时间或重复规则并保存。系统编辑页取消时，已保存的本地待办仍保留。
• 同一件事的两种视图：苹果日历展示事件时段；Mikansei 保留同一事项的 Checklist、平台、估时、计时、DDL 和完成状态。日历改期在下次打开或手动同步时更新关联事项，不复制清单。
• 编辑回日历：事项中点“保存并编辑日历日程”，在系统编辑页确认后回写。普通保存与勾选完成不自动覆盖或删除日历事件；Calendar 没有任务完成状态字段。订阅或只读日历不可回写。
• 同时有时段和 DDL：今日清单会考虑当天执行时段；日程视图分别展示执行与截止日期。提醒中可选择按执行开始还是按 DDL。

系统日历自动导入

更新后首次打开，允许系统日历读取权限。iOS 将读取权限称为“完全访问”；自动同步只读取日历；只有在事项内点击“保存并安排到苹果日历”或“保存并编辑日历日程”，并在系统编辑页确认保存，才写入对应事件。Apple EventKit 权限说明。

在 设置 → 日历自动导入 选择日历、关闭自动同步或点击“立即同步”。首次不勾选任何来源，需要手动选择日历标签 / 来源。旧版默认导入的节假日、生日来源升级后会取消勾选一次，仍可重新手动开启。保存到苹果日历不会自动勾选整个来源。读取范围是从今天本地零点起 30 个日历日，包括与这段时间重叠的事件。若正在编辑事项，会在关闭编辑页后同步，避免覆盖草稿。

• 默认按开始时间导入为“日程”，日历名作为默认分类，地点、备注、链接和事件时长一并导入。系统原来的提醒仍由日历管理；Mikansei 不默认增加第二份提醒，可在事项详情中自行开启。
• 默认把日历开始、结束作为独立执行时段，不把开始时间当作截止时间。需要 DDL 时可选“按结束时间截止”，导入为待办并附加截止日期（全天取排他结束前一秒）。旧版自动写入的开始时间 DDL 会迁移成执行时段，手动修改的 DDL 保留。
• 再次读取更新仍与原导入值相同的字段；手动改过的标题、时间、说明等保留。完成状态、Checklist、优先级、催办与累计计时由你管理。
• 使用日历 / 事件身份和原始重复发生日期去重；单次事件改期更新原事项，重复事件的每一次分别进入清单。Apple 事件标识说明、重复发生日期。
• 在 Mikansei 删除某次导入事项会保存排除记录，下次打开不会重新添加。原日历取消或本次读取未找到的事件保留并提示核对；取消选择日历也不会清除已有事项。可使用“清理未选日历的导入事项”确认清理未修改、未完成的误导入内容；完成记录、Checklist、计时、手动安排或修改的事项保留，苹果日历事件不会删除。

仅读取手机系统日历已加载的事件；远端账号的下载由 iOS 日历负责。界面测试只使用合成事件，不读取个人日历。本轮 Linux 核心测试通过；iOS 编译、界面测试与真实授权、账号、长按和勾选流畅度仍需在 Mac / iPhone 验证，见 VALIDATION.md。

CSV

模板和例子在 Examples/，App 设置 → 课表与登记也能导出模板。表头固定为：

课程,星期,开始时间,结束时间,地点,提交平台,开始日期,结束日期
高等数学,1,08:00,09:40,教学楼,学习通,2026-10-12,2027-01-31

星期 1 表示周一，7 表示周日；时间 HH:mm，日期 yyyy-MM-dd。每行是一节在指定日期范围内每周重复的课。文件须使用 UTF-8，文本中包含逗号时使用标准 CSV 引号。

ICS

支持带具体时刻的 VEVENT，UTC 和系统可识别的 TZID；按日或按周、INTERVAL（可用于单双周）、BYDAY、COUNT / UNTIL、RDATE 和 EXDATE。导入会展开成实际日期，避免凭空补出课程。

不支持全天课、月度复杂循环、自定义 VTIMEZONE 标识、跨天课程和 RECURRENCE-ID 调课覆盖。遇到这些格式会明确报错，并保留原课表；请使用逐次事件导出或手动添加。限制最多两年、2048 次课程、5 MB 文件。

弹窗和闹钟提醒

在事项详情或课程设置中开启提醒，选择 弹窗提醒 / 闹钟提醒 → 铃声 → 稍后提醒（5 / 10 / 15 分钟）。支持系统默认与 Mikansei 原创晨光、清脆、节拍铃声，点选试听；没有复制苹果时钟的专有铃声库。

闹钟使用 AlarmKit，要求 iOS 26+，提供系统停止、稍后提醒，以及锁屏 / 灵动岛的稍后倒计时、暂停与继续。iOS 17/18 保留弹窗通知；选择不支持的闹钟会明确提示，不会悄悄换成普通通知。系统闹钟可穿透静音与专注模式；需要用户给予独立闹钟授权。Apple AlarmKit 说明。停止铃声不等于完成任务。已经响铃或处于稍后倒计时的闹钟不会因为打开 App 而被重建；完成、删除或更改提醒配置会取消旧闹钟。

铃声为 4 秒单声道 PCM WAV，通知声音小于 30 秒，系统默认试听仅使用系统提示音，实际闹钟默认铃声由 iOS 决定。Apple 通知铃声说明。

提醒的实际范围

弹窗提醒使用系统本地通知，不需要服务器；App 前台显示事项弹窗（查看、完成、稍后提醒），后台与锁屏由系统显示通知。Apple 本地通知说明。

• routine 与课后提醒预排未来 28 天，每次打开 App 更新；弹窗与闹钟合计优先安排最近 60 条提醒，稍后提醒也占用名额。AlarmKit 达到系统容量上限时显示未安排原因，下次打开继续补充。
• 如果很久不打开 App，或课表非常密集，后续通知需要再次打开 App 才能补充。
• 普通通知受系统通知设置、声音、专注模式影响；弹窗形式不会强制响铃。iOS 26 起可另选 AlarmKit 系统闹钟并单独授权，闹钟由系统管理。
• 完成、删除或改变时间后，会重新安排并取消不再需要的后续通知。通知长按可使用“标为完成”。
• 分阶段催办 是截止前一天、两小时、到点、截止后两小时；逾期持续催办 再延续至截止后 24 小时，并非无限重复。
• 手机时区改变后，请核对课表时间。本版课表导入展示和排程按手机当前时区处理。

QQ 信息

本版不自动读取 QQ 群。辅助解析仅处理你主动粘贴的文本，不上传原文，不需要 QQ 密码。

日期规则只覆盖常见绝对日期、今天 / 明天 / 后天，以及 HH:mm 时刻。缺少年份或时刻会提示假设；多个日期或不能可靠识别时，要求手动指定。旧消息中的“明天”按解析当天计算，必须核对。一次粘贴只创建一个事项。

未来的自动化需要一个经授权、可稳定导出的消息入口，再接入“提取 → 待确认 → 保存”的流程。

数据

手机数据位于 App 沙盒 Application Support/QingdanJi/entries.json，Mac 为 Application Support/MikanseiMac/entries.json。先保存本机，用户选择 iCloud Drive 文件夹后跨设备合并；没有自建服务器或额外账户登录。卸载 App 会删除本地数据，请定期在设置中导出备份到“文件”。完整同步范围、离线与冲突规则见 SYNC.md。

小组件只读取任务摘要，通过 App 与扩展的同名 Keychain Access Group 共享；不申请 App Groups，不共享笔记正文、消息原文、提交平台或 Checklist 内容。Apple 钥匙串共享说明。本机 Personal Team 现有描述文件允许相应钥匙串组；完整共享读取与小组件显示仍需真机确认。

专注计时将已累计秒数与本次开始时间保存到本机，退出 App 后按时间继续计算；暂停、完成和备份都会保留累计时间，routine 的下一次从零开始。小组件使用系统动态计时文字显示经过时间，避免依赖每秒重新读取清单。Apple 动态计时文字。

保存采用串行后台原子写入，失败时保留内存中的修改并显示“重试保存”。成功写入后合并短时间内的小组件刷新请求；实际刷新时机由 iOS 控制。时间线包含本地午夜与当日截止时刻，供系统更新显示；小组件不是实时倒计时。手机重启后须先解锁，首次安装后先打开 App。同步失败会在设置页显示重试入口，小组件不会用示例任务代替真实清单。

备份导入会合并事项，相同编号保留较新的版本；课程相同编号保留本机设置。课表文件重复导入会按课程、时间与日期范围去重。损坏的数据不会被静默覆盖，App 会停止写入以保留原文件。

开发与验证

没有第三方运行依赖。Sources/MikanseiCore 是共享的 Foundation 数据、排程和同步合并逻辑，App 是 iPhone 界面，Mac 是原生桌面界面，Sync 提供两端的文件夹授权与同步设置，Widgets 使用 WidgetKit，Shared 提供 iPhone 只读摘要的钥匙串共享存储。Mac 使用独立 Xcode 工程和本地签名，保留 iPhone 现有 Team。

核心测试：

swift test

不依赖模拟器的 iPhone 编译：

xcodebuild -project Mikansei.xcodeproj -target Mikansei \
  -configuration Debug -sdk iphoneos ARCHS=arm64 CODE_SIGNING_ALLOWED=NO \
  SYMROOT=/tmp/mikansei-build OBJROOT=/tmp/mikansei-objects build

有 iOS 模拟器运行时后，在 Xcode 选择模拟器并执行 Product → Test 运行 UITests。界面测试使用独立测试目录和启动参数，不读取个人数据；本地开发示例不会默认出现在用户清单里。

新增 Swift 或资源文件后，可运行 python3 Scripts/generate_project.py 重建项目；会保留现有 target 的签名与编译设置，并让扩展使用与主 App 相同的 Team、版本和摘要共享组。更改主 App Bundle Identifier 后请重建工程，以同步扩展的标识前缀和共享组。

Mac 工程由 python3 Scripts/generate_macos_project.py 生成，python3 Scripts/install_mac.py 构建并打开通用 Mac App。python3 Scripts/make_mac_icon.py 将现有批准图标导出为 macOS ICNS。Mac 界面测试运行 MikanseiMac.xcodeproj 的 MikanseiMac scheme；合成示例使用 --ui-testing --demo，不会读取个人清单或日历。

目前验证结果与环境限制见 VALIDATION.md。