道可道，非常道；名可名，非常名。
ReadTao 是一个专注、可靠、适合长期维护的古籍阅读网站。它首先把典籍的来源、底本、原文、译文、注文和发布版本整理清楚，再为桌面与移动端提供安静、稳定的在线阅读体验。
ReadTao 不再定位为课程或“教会用户读懂古籍”的学习产品，也不规划学习路径、阶段考核、徽章或证书。内容按维护者的时间和兴趣逐部录入；数量和更新频率不设硬指标，来源可信、文本完整、版本可追溯和长期可恢复比快速扩张更重要。
M1 Studio 与 Reader 产品基线、M2“问道”初版均已完成。登录后的桌面 Studio 可以完成典籍、底本、来源、导入、分段、生成、审校、整部不可变发布和显式向量化；Reader 已有首页、书库、动态阅读器、桌面/移动双端排版、阅读设置和导出。“问道”继续作为独立辅助模块保留，但当前主线已经回到典籍整理、书库积累、阅读体验、搜索发现和运维可靠性，不再继续扩张问答能力。
Reader 支持原文、拼音、来源注文和译文彼此独立显示，也可以按阅读习惯切换左右或上下对照。
| 左右对照阅读 | 上下对照阅读 |
|---|---|
 |
 |
Studio 从整部典籍管理进入单卷工作台，并将原文件来源单元、语义切片和内容审校保持在同一条可追溯链路中。
| 典籍与发布总览 | 来源单元、语义切片与内容审校 |
|---|---|
 |
 |
截图中的现代汉语和英文内容是本地演示占位初稿，不代表正式译注；原文与王弼注来自仓库内置的 KR5c0073 来源文件。
当前长期方向：
- 有空时逐部整理和上传值得保存、阅读的古籍，不追求一次搬完大型典籍库。
- 公开内容保留来源、版本、许可或公版依据、修订和发布记录。
- Reader 优先解决找书、连续阅读、对照阅读、稳定链接、导出与移动端体验。
- Studio 优先降低个人长期维护的负担，自动化只辅助整理，最终发布仍由人工确认。
- 已实现的 AI 与 RAG 能力按可靠性和成本需要维护，不作为产品价值成立的前提。
- Reader Web：面向读者的响应式 Web/PWA，桌面和移动端均作为正式使用场景。
- Content Studio：面向编辑、校对和发布人员的桌面管理端。
- Application API：内容、检索、用户设置和问答等业务接口。
- Content Pipeline：导入、清洗、分段、翻译、拼音、向量化和发布任务。
- Data Layer：PostgreSQL 业务数据与 pgvector 向量检索。
项目文档索引、状态及维护规则见 docs/README.md。
环境要求：Node.js 22、pnpm 11、uv、Docker。
pnpm install
uv sync --project apps/backend
pnpm infra:up先创建本地环境文件并执行迁移：
cp .env.example .env
pnpm db:upgrade.env 已被 Git 忽略。真实模型 Key 只填写在本地 .env，不得写入 .env.example 或提交到仓库。
仓库内置 Kanseki Repository KR5c0073 四卷来源文件。全新空数据库可以用一条命令完成来源分层、语义切片、本地占位内容生成、演示审校和不可变 v1 发布；该流程不调用外部模型，也不需要配置模型 Key。
首次准备：
pnpm install
uv sync --project apps/backend
# Windows PowerShell：Copy-Item .env.example .env
# macOS / Linux：cp .env.example .env
pnpm infra:up
pnpm db:upgrade
pnpm demo:seeddemo:seed 只会写入空数据库；如果数据库中已有其他作品或未完成的同名作品，会主动停止，避免覆盖现有内容。已经完整发布过该演示样例时，重复执行会安全退出。
随后分别启动三个进程：
pnpm dev:backend
pnpm dev:reader
pnpm dev:studio- Reader：http://localhost:3000/library
- Studio：http://localhost:3001
- 本地演示账号：
demo@readtao.local - 本地演示密码：
readtao-demo
预置样例已经在初始化脚本内完成本地任务，不必启动 Worker。需要继续编辑、重新生成或验证完整异步流程时，再运行 pnpm dev:worker。
首次打开空数据库的 Studio 时，需要同时填写日常管理员和备用恢复管理员的不同邮箱；Backend 会生成备用密码，并只在无缓存的确认页显示一次。已有单管理员实例应由当前管理员在“账户 → 安全与恢复”补建备用账号。上线与日常恢复步骤见 Studio 管理员恢复操作手册。
分别启动四个开发进程：
pnpm dev:reader
pnpm dev:studio
pnpm dev:backend
pnpm dev:worker- Reader Web：http://localhost:3000
- Content Studio：http://localhost:3001
- API 文档：http://localhost:8000/docs
Reader v2 的设计审阅使用独立 Nuxt 原型，不请求现有 API、不会改动正式 Reader：
pnpm dev:reader-prototype- Reader v2 Prototype：http://localhost:3002
- 内部审阅面板：http://localhost:3002/__review
原型的体验目标、页面清单、响应式规则和后续迁移门禁见 Reader v2 原型设计 Brief。它是设计决策来源，不是正式 Reader 的运行入口。
Reader 问答真实 Provider 需要在本地 .env 配置 READTAO_EMBEDDING_API_KEY、READTAO_WEB_SEARCH_API_KEY 和 READTAO_RAG_LLM_API_KEY。三项服务均通过腾讯 TokenHub 调用，但保留独立 Key，便于轮换、限额和费用审计；Hy3 联网搜索还需在 TokenHub“平台管理 → 工具管理”领取免费资源包或启用后付费。自动测试使用 Fake Provider，不会产生外部费用。
问答默认使用 READTAO_QA_ORCHESTRATOR=langgraph；验收期可切换为 legacy 回滚到旧路由。编排改造不改变已经就绪的向量内容。
向量化统一通过 Studio 典籍详情显式执行：发布整部典籍后只生成不可变发布版和“未开始”索引记录；发布者点击“向量化当前版本”后才会调用 Embedding 并投递 Worker。启动 Backend 或 Worker 不会自动向量化。
首次打开 Studio 时创建管理员账号。该账号同时具有管理员、编辑、审校和发布角色；之后直接登录即可，不需要切换身份。Studio 使用同源 /api，开发服务器会代理到本地 Backend。
pnpm typecheck
pnpm test
pnpm build
pnpm api:check
pnpm check:backend
pnpm test:backend:integration
pnpm db:verify-migrations
pnpm test:e2e
docker compose config --quiet集成测试使用 readtao-test MinIO 桶和假 Provider，不会调用真实模型。当前本地对象存储使用 MinIO；腾讯云 COS 只预留统一配置契约，生产启用前再使用专用 CAM 凭证执行独立冒烟，不在仓库中保存任何真实 COS 密钥。
首次运行浏览器冒烟前执行 pnpm exec playwright install chromium。本仓库不配置托管 CI；维护者在发布前本地执行上述类型、测试、构建、契约、迁移和浏览器门禁。
ReadTao 原创代码、项目文档和视觉素材采用 MIT License。仓库内置的 Kanseki Repository 转录、Chinese Wikisource 固定修订，以及截图和演示媒体中包含的第三方古籍内容不在 MIT 授权范围内，仍适用各自来源条款；完整归属和许可边界见 THIRD_PARTY_NOTICES.md。