# 本地批注工作区

aibookbar.cn 的批注 / 高亮 / 修订 / 笔记**全部保存在用户本地**：浏览器 localStorage 只是工作缓冲，
导出的 `.jsonl` 文件（本地文件夹）是唯一数据源，站服务器不存储任何用户批注数据。

## 数据格式（JSONL，每行一条）

```jsonl
{"type":"highlight","book_id":"shang-han-lun","section_n":1,"para":2,"quote":"脉浮","color":"y","created_at":"2026-08-20T00:00:00Z"}
{"type":"annotation","book_id":"shang-han-lun","section_n":1,"para":0,"quote":"太阳之为病","text":"六经总纲，参见 [[s:shang-han-lun:5]]","created_at":"2026-08-20T00:00:00Z"}
{"type":"edit","book_id":"shang-han-lun","section_n":1,"para":0,"quote":"桂枝","replacement":"桂（桂枝）","note":"别名注","created_at":"2026-08-20T00:00:00Z"}
{"type":"note","book_id":"shang-han-lun","title":"太阳病纲要","body":"参见 [[s:shang-han-lun:1]] 与 [[a:批注id]]","created_at":"2026-08-20T00:00:00Z"}
```

- `type`：highlight（高亮）/ annotation（批注）/ edit（修订）/ **note（笔记）**
- `section_n`：篇目序号（阅读页 URL 中的数字）；`para`：该篇内段落序号（0 起）
- `quote`：锚定原文（站上定位靠 quote 匹配段落原文，比字符偏移更稳）
- edit 的 `replacement` 留空表示删除；**站上原文永不被修改**，修订以覆盖层显示

## 双向引用（[[...]]）

批注、修订说明与笔记正文中均可书写：

- `[[s:shang-han-lun:1]]` → 链接站内篇章（书 id + 篇号）
- `[[herb:人参]]` → 链接中药页
- `[[a:批注id]]` / `[[n:笔记标题]]` → 链接本地批注 / 本地笔记（面板内跳转）
- 其他任意文本 → 链接全文搜索页

面板「引用」标签自动列出引用当前篇的全部批注与笔记（反向引用）。

## 自动保存 / 自动加载

- **浏览器缓冲**：每次操作立即写入浏览器本地存储，刷新不丢
- **「保存」按钮**：已连接本地文件时 = 原地写入该文件（自动保存 0.6s 防抖同样生效），
  **不会产生新副本**；未连接时 = 下载兜底（浏览器安全模型不允许网页静默覆盖磁盘文件，
  下载会被重命名为副本）
- **文件自动同步**（支持 File System Access 的浏览器，如 Chrome/Edge）：
  点「连接本地文件」选择你的 `{book_id}.notes.jsonl` 一次 → 此后每次修改自动写入、
  每次打开自动加载（与浏览器缓冲按 id 合并，文件为主）；面板底部显示连接状态
- 其他浏览器：用「保存 / 导入」手动管理 `.jsonl`

## 交互说明

- **高亮**：选中文字 → 工具条「高亮」→ 按钮上方展开调色板选色（黄/绿/蓝/红）；面板卡片上的圆点可随时换色
- **批注**：选中文字 → 工具条「批注」→ **选中文字上方弹出输入框** → 填写 → 保存后
  批注显示在**右侧面板**（卡片可编辑/删除/回跳原文），正文显示橙色标记
- **修订**：选中文字 → 工具条「修订」→ 上方输入框（**预填原文**，直接改写）→ 保存后
  **修订内容直接显示在原文位置**（红色样式，悬停可见原文；留空 = 待修订虚线标记）
- **编辑**：批注/修订卡片上的「编辑」按钮 → 回到原文标记处再次弹出输入框修改；笔记点卡片进面板编辑器

## 工作流

1. **浏览器工作**：阅读页选中文字 → 高亮 / 批注 / 修订；「笔记」标签记录跨书理解
2. **AI 工具直读**：Trae/ZCode 等直接读写该 JSONL（原生文件工具，不经服务器）
3. **站上查看**：阅读页「导入」或「连接本地文件」恢复显示
4. **建工作区**：`friendlyai notes new <book_id> --dir ./notes` 生成
   `{book_id}/{book_id}.md`（全书 Markdown）+ `{book_id}.notes.jsonl`（空模板）+ README

## 相关

- [AI 概览](https://aibookbar.cn/llms.txt) · [Skills 库](https://aibookbar.cn/skills) · [分享层](https://aibookbar.cn/gallery)