# magic_note

**Repository Path**: dingslord/magic_note

## Basic Information

- **Project Name**: magic_note
- **Description**: magic note
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 里德尔的日记 · Magic Note

一本以墨水浮现的方式与 LLM 对话的「魔法日记本」Web 应用，灵感来自《哈利波特》中的里德尔日记。
支持**全屏手写**或**键盘**输入；提交后墨迹逐渐淡出，LLM 的回复逐字如墨水般浮现。

- **纯静态 / 零后端**：以 PWA（渐进式 Web 应用）形式交付，手机端浏览器直接打开即可，**无需安装、无需租用服务器**。
- **BYO Key**：用户自行填入自己的 LLM API Key，仅存于本机设备，应用直连 LLM 供应商。
- **跨平台**：电脑、手机（iOS Safari / Android Chrome）一致体验，不依赖任何 Android/iOS 专属框架。
- **电子墨水屏适配**：内置墨水屏主题，利用 E-ink 残影做"魔法消散"、分批置换式浮现。

> 设计细节见 [`design.md`](./design.md)，开发步骤见 [`implementation-plan.md`](./implementation-plan.md)。

---

## 1. 功能特性

| 功能 | 说明 |
|---|---|
| 输入模式 | 全屏手写（Canvas + `perfect-freehand`）/ 键盘，一键切换 |
| 手写识别 | 可选第三方识别服务（HR-1 方案 B），或系统手写键盘（方案 A） |
| 墨迹淡出 | 提交后用户输入逐渐淡出（E-ink 模式利用硬件残影） |
| 逐字浮现 | LLM 回复以墨晕效果逐字/分批浮现，支持「跳过动画」 |
| 多轮对话 | 本地维护上下文，可配置保留轮数 |
| 流式响应 | 直连 LLM SSE 流式接口，低首字延迟 |
| 会话管理 | 新建 / 切换 / 删除 / 本地持久化 |
| 配置中心 | LLM、视觉动效、输入、会话、安全 6 类子页，实时预览 |
| 首次引导 | 首次启动分步填入 Key 并进入 |
| E-ink 适配 | 残影式淡出 + 分批浮现 + 静态背景 |
| 可访问性 | `prefers-reduced-motion`、CSP、弱网兜底 |

---

## 2. 编译与运行依赖

### 2.1 环境要求
- **Node.js** ≥ 18（推荐 20 LTS）
- **npm**（随 Node 安装）

### 2.2 运行时/构建依赖
生产依赖（打包进前端）：
- `react` / `react-dom` — UI
- `zustand` — 状态管理
- `perfect-freehand` — 手写笔触渲染

开发依赖（仅构建/测试用）：
- `vite` + `@vitejs/plugin-react` — 构建与开发服务器
- `vite-plugin-pwa` — PWA / Service Worker
- `typescript` — 类型检查
- `vitest` + `@testing-library/react` + `@testing-library/user-event` + `jsdom` — 单元测试
- `fake-indexeddb` — 测试环境用（可选）

> 无需任何后端运行时、数据库或云服务。所有逻辑在浏览器执行。

---

## 3. 安装与配置

```bash
git clone <repo> && cd magic_note
npm install
```

### 3.1 环境变量（可选）

复制并按需填写：

```bash
cp .env.example .env
```

| 变量 | 说明 |
|---|---|
| `VITE_RECOGNIZE_URL` | 手写识别服务地址（可选）。留空则走系统手写键盘。 |
| `VITE_RECOGNIZE_KEY` | 识别服务 Key（可选）。 |

> LLM 的 API Key **不**在此配置，而是在应用内「设置 → LLM 连接」填入（仅存本机）。

---

## 4. 本地运行

开发模式（热更新）：

```bash
npm run dev
```

浏览器打开终端输出的本地地址即可。

---

## 5. 测试

采用 **TDD** 模式，测试覆盖配置、Key 管理、SSE 解析、流式对话、会话、设置页、手写识别等：

```bash
npm test            # 单次运行
npm run test:watch  # 监听模式
```

---

## 6. 构建与部署

### 6.1 构建

```bash
npm run build
```

产物输出到 `dist/`，含：
- 相对路径的静态资源（`base: './'`，可本地双击打开，也可任意静态托管）
- PWA 资源：`manifest.webmanifest`、`sw.js`（离线缓存、可"添加到主屏幕"）

### 6.2 部署（纯静态，无需服务器）

任选其一，将 `dist/` 内容上传即可：

- **GitHub Pages**：仓库 Settings → Pages，选择 `dist` 目录或 CI 发布。
- **Vercel / Netlify / Cloudflare Pages**：连接仓库，构建命令 `npm run build`，输出目录 `dist`。
- **任意静态服务器 / 对象存储**：Nginx、OSS、S3 等，根目录指向 `dist`。

部署要求：
- **必须 HTTPS**（PWA 与 SSE 的强制要求）。
- 不需要配置反向代理或后端；应用直接以用户 Key 请求 LLM 供应商。

### 6.3 首次使用

1. 打开部署地址（或本地 `dist/index.html`）。
2. 首次启动引导：填入你的 LLM API Key（如 OpenAI `sk-...`），选择设备类型。
3. 进入日记，开始书写/键入，等待墨水回应。

---

## 7. 目录结构

```
src/
  config/        配置类型与默认值（design.md §7.2）
  store/         zustand 全局状态 + 会话持久化
  modules/
    key/         API Key 本地管理
    stream/      LLM SSE 流式消费 + 多轮上下文
    input/       手写 Canvas / 键盘输入
    ink/         逐字浮现渲染
    recognition/ 可选手写识别服务接口
  pages/         主页面 / 设置（6 子页）/ 首次引导
  styles/        全局样式（羊皮纸主题）
  test/          测试 setup（canvas / matchMedia / mock fetch 等）
```

---

## 8. 配置项速览

在应用「设置」中可调整（详见 `design.md` §7.2）：

- **LLM**：供应商 / Base URL / 模型 / 温度 / 上限 / 人设提示词
- **视觉与动效**：墨色、字体、淡出时长、浮现间隔、墨晕强度、纸张主题（含墨水屏）、浮现批大小
- **输入**：默认模式、笔触宽度、压感、识别语言、识别服务地址
- **会话与存储**：上下文轮数、自动保存
- **安全与隐私**：显示/清除本机 Key

---

## 9. 手写识别（可选）

- **方案 A（默认，零依赖）**：移动端使用系统原生手写输入法（iOS 随手写 / Android 手写键盘）直接产出文本。
- **方案 B（可选）**：在「设置 → 输入」或 `.env` 配置识别服务地址。纯涂画（无文本）提交时，应用将墨迹坐标 `strokes` POST 到该服务，期望返回 `{ text: string }`。服务由你自备（如自建 OCR 接口），应用不内置。

---

## 10. 电子墨水屏（E-ink）

选择「视觉与动效 → 纸张主题 = 墨水屏」（或首次引导选"电子墨水屏"）即启用 NFR-8：
- 淡出阶段**不**做软件渐变，转而利用 E-ink 天然残影让墨迹缓慢褪去（魔法消散感）；
- 浮现改为每 ~100ms 整批（默认 4 字）置换，关闭墨晕与逐字闪烁；
- 背景静态、低对比，减少全屏刷新。

---

## 11. 安全说明

- 本项目无后端，**不收集、不上传任何数据**。
- LLM API Key 仅存于本机 `localStorage`，用于浏览器直连供应商；建议使用**自有、可随时吊销**的 Key。
- 页面设置了 CSP（内容安全策略）以降低 XSS 风险；请勿引入不可信第三方脚本。
- 识别服务地址与 Key 同样仅存本机。

---

## 12. 许可证

MIT（示例项目，可自由修改与再分发）。