Izayoi

一个既不完美，也不潇洒的 AI 日程与提醒工具

Task / Todo / Habit / Assistant / Sync / Backup

00. 一些东西

这是一个用来应付学校新生引导课大作业的产物，代码绝大部分由 AI 编写，因为我很懒。

截至目前，服务端还没有完成，请不要使用服务端；部分地方的 UI 风格还没有统一，因为我很懒。

本来计划兼容PC端和移动端的，但目前只适配了 Android 端，因为我很懒。

其实 Android 端也没有完全完成，因为我画的饼太大了，也因为我很懒。

End of Bullshit

01. 功能

模块	你能做什么	当前实现要点
日历页 Calendar	查看日程时间线	横向滑动日期、月份下拉跳转、今日快捷返回、重叠日程并排布局、全天事件区、当前时间线
今天页 Today	专注处理今日待办	未完成/已完成双泳道、滑动完成、移出今天、完成动画、今日汇总
Today 选择页	从待办池挑项目进今天	只显示未完成的手动待办，支持一键加入 Today
Today 历史页	回看完成或过期项目	按最近更新时间排序，支持删除模式
Smart Add	快速录入新内容	日程 / 待办 / 习惯三种入口，自定义时间轮盘，支持 AI 预填表单
Habit	长期行为追踪	周期进度、打卡、连续轮数、完成轮数、84 天热力图、编辑与删除
Izayoi 助手	对话式整理事项	支持回答问题、澄清选项、生成待确认操作包、执行后可跳转结果详情
Settings	管理连接、模型与数据	同步地址、OpenAI / Gemini 模板、API Key / Base URL / Model、画像编辑、备份导入导出
Sync Server	作为 NAS 端同步层	tasks / todos / habits / habit-checkins 的 CRUD 与增量同步

02. 页面与功能明细

Calendar / 日程

• 以时间轴形式查看单日任务，默认可以左右翻看前后约 2 年日期。
• 顶部月份选择器可展开日历面板并跳转到指定日期。
• 顶部提供“回到今天”按钮。
• 支持全天日程与定时日程分区展示。
• 多个时间重叠的日程会自动分列排布。
• 当天页面会显示当前时间线。
• 可在详情弹窗里查看标题、时间、状态、备注，并继续编辑或删除。
• 可调整时间轴密度，压缩或拉伸每小时高度。

Today / 待办工作台

• 只聚焦 today_bucket_date 命中的今日待办。
• 页面拆成“未完成 / 已完成”两条泳道。
• 手动待办可左滑快速完成。
• 手动待办可右滑露出移除操作，把项目移出 Today。
• 完成一个待办时会有条目入列动画。
• 顶部 + 可打开待办选择页，把待办池里的事项加入今天。
• 历史页会汇总已完成和已过期的待办，并支持删除模式。

Smart Add / 智能录入

• 一个入口同时支持新建日程、待办、习惯。
• 日程支持“全天”切换，以及开始/结束日期与时间轮盘输入。
• 待办支持截止时间输入。
• 习惯支持设置开始时间与周期单位。
• 周期单位支持 day、workday、week、month、year。
• 可粘贴自然语言文本，调用 AI 解析后预填标题、描述、开始时间、结束时间。
• AI 解析只负责预填表单，最终仍由用户确认后保存。

Habit / 习惯

• 习惯列表会展示当前周期进度与完成状态。
• 详情页支持当天打卡，重复点击同一天是幂等的。
• 每个习惯都会根据周期生成摘要，包括当前周期完成数、连续轮数、已完成轮数。
• 提供最近 84 天打卡热力图。
• 支持编辑开始时间、周期、持续周期数和中断策略。
• 中断策略支持 continue 与 reset。
• 周期推进和打卡结果会反向更新习惯派生待办。

Izayoi Assistant / AI 助手

• 会读取当前本地任务、Today 待办、待办池、习惯状态与最近对话，构造上下文。
• 可直接回答问题。
• 当用户意图不清晰时，会返回澄清问题和快捷选项。
• 当用户意图足够明确时，会生成“待确认操作包”而不是直接修改数据。
• 操作包支持的动作包括：
  • Task：创建、更新、删除、完成。
  • Todo：创建、更新、删除、完成、加入今天、移出今天。
  • Habit：创建、更新、删除、打卡。
• 用户确认后才真正执行写操作。
• 执行结果支持跳转到对应的日程、待办或习惯详情页。

Settings / 设置与数据管理

• 配置同步服务器地址；如果留空，应用继续以本地模式运行。
• 配置 AI 提供商模板，目前内置 OpenAI 与 Gemini。
• 支持自定义 API Key、Base URL、Model Name，因此也可接 OpenAI 兼容接口。
• 用户画像支持启用/停用、查看统计、手动编辑、清空数据。
• 画像来源包括 Smart Add 原文、任务快照和聊天消息。
• 可导出完整 JSON 备份。
• 可将备份文件写入应用文稿目录并调用系统分享。
• 可复制备份到剪贴板。
• 可从剪贴板粘贴或从文件导入备份。
• 导入会整体替换当前设备上的本地数据。

Sync Server / 同步后端

• 提供 tasks、todos、habits、habit-checkins 四类资源。
• 每类资源都支持列表、单条读取、创建、更新、软删除、/sync 增量同步。
• 删除采用软删除，依赖 deleted_at 传播。
• 同步冲突依赖 updated_at 与 version。
• OpenAPI 文档默认可在 /docs、/redoc、/openapi.json 查看。

03. 数据模型

对象	作用	关键字段
Task	有明确开始/结束时间的日程	title start_time end_time is_all_day priority is_completed
Todo	无开始时间、以截止时间驱动的待办	due_at status today_bucket_date source_type habit_id cycle_key
Habit	长期周期性行为	cycle_unit target_count duration_cycles streak_count completed_cycles break_policy
HabitCheckin	具体某天的一次打卡记录	habit_id checkin_date cycle_key
Profile	AI 用的结构化软提示	common_projects common_contacts common_locations time_preferences 等

其中：

• Todo.status 当前支持 todo | done | expired。
• Todo.source_type 当前支持 manual | habit。
• Habit.cycle_unit 当前支持 day | workday | week | month | year。
• 习惯派生待办、待办过期、连续轮数等规则全部在客户端结算，不在服务端结算。

04. 架构图

flowchart LR
  A["Calendar / Today / Smart Add / Habit / Assistant"] --> B["Zustand Stores"]
  B --> C["Expo SQLite<br/>本地真相层"]
  C --> D["业务服务<br/>habitTodo / profile / assistant / dataTransfer"]
  D --> E{"是否配置 serverAddress"}
  E -- "否" --> F["本地优先模式"]
  E -- "是" --> G["FastAPI Sync API"]
  G --> H["SQLite<br/>server/data/reminder.db"]

Loading

架构原则

• 客户端是业务真相层，先写本地 SQLite，再决定是否同步。
• 服务端只负责存储和多设备同步，不负责 AI、画像推理、习惯周期结算、待办过期判定。
• 应用进入前台时会触发一次同步与本地状态刷新。
• 即使没有配置同步服务器，应用也能正常以单机模式使用。

05. 技术栈

Client

• Expo 55
• React Native 0.83
• React 19
• React Navigation
• React Native Paper
• Zustand
• Expo SQLite
• Expo Clipboard / Document Picker / Sharing / Font

Server

• FastAPI
• SQLAlchemy 2
• Pydantic 2
• Uvicorn
• SQLite

06. 快速启动

1) 启动客户端

cd client
npm install
npm run start

可选命令：

• npm run android
• npm run ios
• npm run web

2) 启动同步服务

本地 Python 方式：

cd server
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Docker 方式：

cd server
docker compose up --build -d

默认地址：

• API: http://127.0.0.1:8000

3) 首次配置建议

进入客户端 Settings 后建议按这个顺序设置：

1. 如需多设备同步，填写 serverAddress。
2. 填写 AI 的 API Key、Base URL、Model Name。
3. 按需要开启“用户画像生成”。

如果你只想单机使用：

• 可以不填 serverAddress。
• 只有使用 Smart Add AI 解析和 Izayoi 助手时，才需要配置模型服务。

07. 同步、备份与恢复

本地优先同步

• 所有对象先写本地库，再标记 sync_status。
• 同步时先 push 本地脏数据，再 pull 远端增量更新。
• Habit 会优先同步，随后才是依赖它的 Todo 与 HabitCheckin。
• 同步前后都会运行一次本地刷新逻辑，保证习惯派生待办、过期状态和统计信息正确。

备份与恢复

导出内容包括：

• 日程
• 待办
• 习惯
• 习惯打卡
• 画像事件
• 结构化用户画像

恢复时请注意：

• 导入会替换当前设备上的本地数据。
• 恢复完成后会重新计算习惯与待办的派生状态。

08. API 概览

资源	增量同步	CRUD
tasks	GET /api/v1/tasks/sync	GET/POST/PUT/DELETE /api/v1/tasks
todos	GET /api/v1/todos/sync	GET/POST/PUT/DELETE /api/v1/todos
habits	GET /api/v1/habits/sync	GET/POST/PUT/DELETE /api/v1/habits
habit-checkins	GET /api/v1/habit-checkins/sync	GET/POST/PUT/DELETE /api/v1/habit-checkins

09. 仓库结构

./
├─ client/                     Expo + React Native 客户端
│  ├─ App.tsx                  应用入口与导航装配
│  ├─ src/screens/             页面层
│  ├─ src/store/               Zustand 状态层
│  ├─ src/services/            业务规则、AI、同步、备份
│  ├─ src/db/                  本地 SQLite 真相层
│  └─ src/api/                 服务端 API 封装
└─ server/                     FastAPI 同步服务
   ├─ main.py                  API 入口
   ├─ routers/                 按资源拆分的路由
   ├─ models.py                SQLAlchemy 模型
   ├─ schemas.py               Pydantic Schema
   ├─ crud.py                  CRUD 与增量同步查询
   └─ data/reminder.db         服务端 SQLite 数据文件

---