v2.1.0 · 登录联动与体验优化版

Full Changelog: v2.0.0...v2.1.0

v2.0.0 · 架构重构版

发布概览

发布日期：2026-04-15
发布定位：架构重构版 / main 分支正式发布

v2.0.0 不是一次常规的小版本迭代，而是围绕 KeepPage 的 archive-first 主链路完成的一轮系统性重构。相较 v1.0.0，这次版本的重点不只是补功能，而是把 API、Web 和浏览器扩展内部已经逐渐膨胀的实现重新收口，为后续继续迭代导入、归档、同步和站点适配能力建立更稳定的结构基础。

为什么升级到 2.0.0

这次发布对应的是一次明显的“结构代际切换”：

• API 从“胖 Route + 超级 Repository”的模式，继续推进到更明确的 Route / Service / Repository 三层分工。
• Web 从以 App.tsx 为中心的单文件主流程，拆成 app shell、数据源适配层和 route-level feature 模块。
• Extension 从集中式站点归档逻辑，重构为 registry + site modules 的组合式结构，后续接入和维护站点规则的成本更低。
• 架构评审文档同步补齐，把已经落地的拆解、剩余任务和治理规则明确下来，避免后续重构继续靠“感觉推进”。

如果说 v1.0.0 标志着 archive-first MVP 主链路可运行，那么 v2.0.0 更像是这条链路从“能跑”走向“可持续演进”的第一个版本。

本次重点变更

1. API 架构分层正式落地一轮

后端这次的核心不是新增很多公开接口，而是把已有能力从耦合过深的实现里拆出来：

• 收窄 Repository 接口，减少 Route 直接承担业务编排的情况。
• 新增并落地 services/bookmarks、services/imports、services/uploads，让书签、导入、上传等用例有了明确归属。
• auth、api-tokens、cloud-archive 相关能力继续收口到 services/ 目录，边界比之前清晰很多。
• memory 与 postgres 两套仓储实现从超大文件中拆分为 core、bookmarks、imports、objects、taxonomy、auth、api-tokens 等能力模块，后续维护时不再需要反复进入同一个超级文件修改。
• routes/imports.ts、routes/uploads.ts 等原本承担大量业务编排的入口显著瘦身，服务端整体结构更接近可持续扩展的后端骨架。

这一轮调整的意义在于：以后无论继续做 imports、cloud archive、对象上传，还是补 Postgres 能力，都能在更明确的职责边界内推进，而不是继续把复杂度堆回路由和仓储入口。

2. Web 管理端完成第一轮去单体化

Web 端这次重构的重点是把不断膨胀的 App.tsx 拆开，并把数据获取和页面特性模块分离：

• 新增 app 级数据源适配层 use-app-data-source，统一 Web 的数据来源接入方式。
• App.tsx 继续收口，减少 demo / mock / live 逻辑彼此侵入的情况。
• 书签列表页和详情页拆为独立 feature 模块，页面结构更清楚，后续继续抽路由或扩展页面能力时阻力更小。
• 站点图标能力抽成共享组件，避免列表和详情视图重复实现。
• 相关 demo 入口和 feature 出口同步整理，为后续把前端收成真正的 app shell + feature routes 奠定基础。

这意味着 Web 端后面继续做筛选、详情扩展、导入视图、更多交互时，不必再优先修改一个超大主组件。

3. 浏览器扩展站点归档能力重组

扩展端是这次重构另一个很大的受益方：

• 内容脚本入口职责进一步收口，状态解析逻辑更集中，入口文件负担降低。
• 原本非常集中的 site-archive.ts 按职责继续拆分，形成更明确的站点 registry、generic reader、legacy reader 和站点专属模块。
• 新增或细化 X、小红书、少数派等站点模块，让站点适配从“堆规则”转向“模块化接入”。
• X 站点增加独立优化逻辑，小红书增加状态解析模块，站点兼容层的维护方式明显更健康。
• 扩展版本同步提升到 0.1.34，并继续保证 package.json 与 manifest 版本一致。

这轮调整最大的价值，是为后续继续补站点规则、做站点回归或拆 capture pipeline 时，保留了更高的可维护性。

4. 书签仓储与站点 / 页面职责继续拆细

围绕书签主链路，这次还做了一轮更底层的结构梳理：

• 书签仓储逻辑继续从“大而全”的实现里剥离出来。
• 站点与页面相关职责被进一步物理拆分，模型边界更清晰。
• 导入、上传、对象访问、分类与标签等相关能力开始围绕统一的结构整理，而不是散落在同一批实现文件里。

这部分虽然对终端用户不是显性 UI 变化，但对后续继续扩展 archive-first 数据链路非常关键。

5. 架构文档同步升级

本次发布不是“代码改了，文档以后再补”。相反，docs/architecture-review.md 也完成了同步更新：

• 补充了截至 2026-04-15 的首轮落地进展。
• 标明了 API、Web、Extension 目前已经完成的拆解工作。
• 保留了后续剩余任务、目标蓝图和治理规则，方便下一轮演进继续接着做，而不是重新评估一遍。

这让 v2.0.0 不只是代码结构调整，也是一版有明确演进上下文的发布。

变更规模

自 v1.0.0 以来，本次发布共包含：

• 2 次提交
• 67 个文件变更
• 10,862 行新增
• 8,540 行删除

对应提交如下：

• f053c60 重构架构分层并收口 Web 数据源与扩展状态解析
• a0697df 重构书签仓储并拆分站点与页面模块

升级与回归建议

从本次 diff 看，这一版主要是内部结构重构，不是部署模型重写；现有的开发与部署文档仍然适用。为了稳妥起见，仍建议在升级到 v2.0.0 后至少完成一轮人工回归：

• API：验证 GET /health、书签列表 / 详情、导入与上传相关主链路。
• Web：验证书签列表、详情页、iframe 预览、筛选与统计视图。
• Extension：验证本地归档、Side Panel 预览、同步上传，以及常用站点的内容提取结果。
• Postgres 模式：按既有流程执行 npm run db:init -w @keeppage/api 并检查对象访问链路。

已知定位

v2.0.0 的重点是“完成首轮重构落地”，而不是宣布所有拆解工作已经结束。根据当前文档与代码状态，后续仍值得继续推进：

• Web 进一步收口为更清晰的 app shell 和 route-level 架构。
• API 继续完成 imports / cloud archive 等边界收敛。
• Extension 第二阶段大拆仍有空间，尤其是 capture pipeline、共享状态和多入口 UI。
• Domain 与根目录结构仍可以进一步细化。

因此，这个版本的意义不是“重构结束”，而是“重构已经进入可持续推进的正轨”。

对比链接

Full Changelog: v1.0.0...v2.0.0

v1.0.0

What's Changed

• Fix archived page previews by injecting base href for relative assets by @iwascy in #1
• Fix archive detail view to use a full-page preview layout by @iwascy in #2
• Update archive homepage cards to match the new reference layout by @iwascy in #3
• Fix extension login flow and add version visibility by @iwascy in #4
• Add AI instructions for extension version bumps and build requirements by @iwascy in #5
• Codex/add in ai md by @iwascy in #6
• Add hierarchical folders and tag management for bookmarks by @iwascy in #7
• Remove invalid Contextweaver MCP permission and rename PRD progress doc by @iwascy in #8
• Add batch import product requirements document by @iwascy in #9
• Add private mode PRD and link it from README by @iwascy in #10
• Add bookmark views and favorites support and remove main push CI by @iwascy in #13
• Add Xiaohongshu video and animated media capture support by @iwascy in #16
• Update extension to use only the complete capture profile by @iwascy in #15

Full Changelog: https://github.com/iwascy/KeepPage/commits/v1.0.0