> For AI agents: the complete documentation index is available at https://www.notionhub.app/llms.txt, the full documentation bundle is available at https://www.notionhub.app/llms-full.txt.

# 古文岛同步到 Notion

NotionHub 可以把古文岛中的诗文详情和个人学习记录同步到 Notion。第一版支持诗文详情、作者、收藏、诗单、笔记、背诵和标签七类数据。

## 使用前准备

- 已安装 NotionHub 浏览器插件，建议先完成 [插件安装](https://www.notionhub.app/docs/install.md)。
- 已登录 Notion，并允许 NotionHub 访问目标工作区。
- 已购买古文岛激活码，或仍有古文岛免费体验次数。
- 已在古文岛 App 中登录，并能查看自己的收藏或背诵数据。

## 配置步骤

### 1. 复制 Notion 模板

在插件服务列表打开「古文岛」，点击「复制 Notion 模板」，按 Notion 页面提示授权。官方模板包含以下七个数据库：

| 数据库  | 内容                        |
| ---- | ------------------------- |
| 诗文   | 诗文详情、作者关系、标签关系、音频文件和字幕文件  |
| 作者   | 作者名称、朝代和简介；作者图片会作为页面 icon |
| 我的收藏 | 古文岛收藏的诗文，并关联「诗文」          |
| 我的诗单 | 一条记录代表一个诗单，并关联该诗单中的多首「诗文」 |
| 我的笔记 | 个人标注和备注，并关联「诗文」           |
| 背诵   | 背诵记录和关联诗文                 |
| 标签   | 独立标签页面，并关联使用该标签的多首「诗文」    |

模板扫描会检查这七个数据库和对应的 data source。旧模板中的「收藏」「诗单」「标注」会按兼容名称识别；「我的诗单」不会把每一首诗拆成一条记录。

### 2. 填写古文岛会话凭证

在古文岛 App 的登录会话信息中取得自己的用户 ID 和短期 `pwdSeed`，填写到插件的古文岛登录页面并点击「保存并验证」。

`pwdSeed` 是用于生成 Android API 动态请求签名的会话凭证，不是 Notion token。NotionHub 不要求填写古文岛明文密码，也不会把密码写入 Notion、GitHub 日志或运行日志。

如果无法取得有效会话信息，请先在古文岛 App 重新登录后再复制会话值。会话过期后需要重新登录，不要把他人的会话值填入自己的账号。

### 3. 开始同步

完成 Notion 模板和古文岛登录后，连接 GitHub 并点击「开始同步」。任务会在你的 `notionhub-runner` 仓库中运行；也可以在 GitHub Actions 页面手动运行 `guwendao.yml`。

同步流程会先拉取收藏、诗单、笔记和背诵列表，再读取诗单元数据，按 `idStr` 获取诗文详情，最后写入诗文、作者、标签和关系数据。重复运行会按古文岛原始 ID 更新已有页面，不会因为标题变化重复创建诗文；同一诗单会始终更新为一条记录并保留多首诗的关系。收藏、笔记、划线、背诵和诗单可用的原始时间会写入日期字段，诗单明细时间会保留在 `诗文添加时间` 中。

诗文页面不会把原文、译文和赏析塞进数据库属性，而是按「原文」「译文」「赏析」建立 Tab；朗诵音频播放器位于 Tab 上方。作者图片会尝试上传为作者页面 icon，已有音频或字幕文件会复用，不会重复上传。

## 同步范围

第一版暂不支持：计划、名句、字词详情、自定义背诵、通知和「修复 Notion 数据」。详情接口偶尔缺失时，会先保留列表中的基础信息，并在 Action 日志中记录 warning，不影响其它列表继续同步。

音频会下载并上传到 Notion 的 `音频文件` 属性，字幕接口响应会保存为 `.json` 文件并写入 `字幕文件` 属性。第三方资源不会经过 NotionHub 服务端长期保存；上传失败时页面仍保留可访问的外部音频地址。

## 常见问题

### 提示登录信息不完整

请确认用户 ID 和 `pwdSeed` 都已填写，并重新从当前古文岛 App 会话复制。不要把加密后的 `pwd`、旧 Cookie 或其它请求的 token 当作 `pwdSeed`。

### 提示 403、非法请求或签名不正确

这是古文岛上游拒绝了动态签名请求，常见原因是会话已过期、字段复制不完整或古文岛更新了 Android API。先在 App 重新登录并重新填写会话值，再重试一次。不要在 GitHub Action 日志中粘贴完整 Cookie、token 或签名参数。

### 诗文同步成功，但收藏、诗单或笔记为空

确认对应数据库已经在模板中存在，并且古文岛账号确实有该类数据。同步不会创建没有上游数据的空页面；诗单如果缺少诗单 ID 和名称，会在 Action 日志中提示并跳过该条，避免把诗文误写成独立诗单。

### 详情失败会不会影响全部同步

不会。详情请求失败时会记录脱敏 warning，并使用列表返回的标题等基础字段继续写入；其它诗文和关系列表仍会继续处理。

### 如何查看失败原因

打开 GitHub 仓库的 Actions，进入 `古文岛` workflow，查看「同步古文岛数据」Job。请保留错误类型、HTTP 状态和失败步骤，隐藏用户 ID 之外的会话凭证；需要帮助时可通过 [技术支持](https://www.notionhub.app/docs/support.md) 联系。

## 敏感信息说明

- 古文岛用户 ID 和 `pwdSeed` 只用于生成请求签名和校验登录状态。
- Notion token、古文岛会话凭证和激活码不会显示在普通日志或 Step Summary 中。
- 不要把 GitHub Secret、Action 原始日志、Cookie 或完整请求复制到公开 issue 或群聊。
- 如果怀疑会话泄露，请立即在古文岛 App 退出其它设备或重新登录，再更新插件中的会话凭证。
