记一次网站内容改动flash模型成本对比

把Github上仓库，aluvien/yezi-blog 同步到本地

请先完整阅读当前相关代码，再实施修改。
 
不要凭空重建一套平行系统，不要为了“统一”而推倒现有成熟模块，不要做与本需求无关的大规模重构。
 
本次任务目标是：
 
完整升级「小记」系统
 
在保留现有：
 
* 随笔
* 絮语
* 归档
* 关于
 
等现有产品结构的基础上，把当前经典导航中的「小记」升级成一个新的聚合型页面：
 
/life
 
新的「小记」包含：
 
* 全部
* 生活节点
* 作品
* GitHub
* 收藏引用
 
同时新增：
 
* 独立生活节点数据模型
* 从絮语提取生活节点
* GitHub Repository 登记与同步
* 作品与 GitHub 仓库关联
* 收藏引用增强
* 小记统一时间流
* 后台统一管理入口
 
⸻
 
一、必须遵守的产品导航
 
经典版网站导航必须继续保持：
 
随笔 / 絮语 / 小记 / 归档 / 关于
 
不得改成：
 
首页 / 文章 / 生活小记 / 关于
 
不得把现有导航体系重新设计掉。
 
最终导航关系：
 
随笔
→ /posts
絮语
→ /moments
小记
→ /life
归档
→ /archives
关于
→ /about
 
本次只改变「小记」对应的实际页面和内部功能。
 
⸻
 
二、最终产品语义
 
必须彻底统一现有历史命名。
 
1. 随笔
 
技术实体：
 
posts
Post
 
产品名称：
 
随笔
 
规范入口：
 
/posts
 
保持现有功能。
 
⸻
 
2. 絮语
 
技术实体：
 
moments
Moment
 
产品名称必须统一为：
 
絮语
 
规范入口：
 
/moments
 
以后 UI 中不要再把 moments 称为：
 
想法
 
例如：
 
原：
 
想法
发想法
还没有想法
 
应改成：
 
絮语
写絮语
还没有絮语
 
或者使用更自然的：
 
写一条
 
但栏目名称必须统一为：
 
絮语
 
注意：
 
絮语仍然是完全独立的一级栏目。
 
不得把絮语放进 /life。
 
⸻
 
3. 小记
 
新的规范页面：
 
/life
 
对外名称：
 
小记
 
小记是一个聚合型栏目。
 
其内部包括：
 
全部
生活节点
作品
GitHub
收藏引用
 
注意：
 
「小记」现在代表整个 /life 页面。
 
不再等同于 works。
 
⸻
 
4. 作品
 
技术实体继续保持：
 
works
Work
 
产品名称：
 
作品
 
但作品不再作为经典版一级导航。
 
它成为：
 
小记 → 作品
 
的一种内容类型。
 
不要因为页面调整而重命名：
 
works
Work
listWorks()
createWork()
 
等技术实体。
 
⸻
 
5. GitHub
 
新增：
 
github_repositories
 
用于登记和展示用户自己的 GitHub Repository。
 
产品名称：
 
GitHub
 
作为：
 
小记 → GitHub
 
的一种内容类型。
 
⸻
 
6. 收藏引用
 
继续基于现有：
 
reference_library
 
产品名称：
 
收藏引用
 
作为：
 
小记 → 收藏引用
 
的一种内容类型。
 
不要重新创建：
 
bookmarks
favorites
saved_urls
 
之类重复数据表。
 
⸻
 
三、最终信息架构
 
前台必须遵循：
 
随笔
└── posts
絮语
└── moments
小记
├── 全部
├── 生活节点
├── 作品
├── GitHub
└── 收藏引用
归档
关于
 
特别注意：
 
moments ≠ 小记
works ≠ 小记
 
而是：
 
moments = 絮语
works = 小记里的「作品」
/life = 小记
 
⸻
 
四、修改前必须阅读代码
 
修改前至少完整阅读并理解以下文件及调用关系。
 
数据库
 
src/lib/db/schema.ts
src/lib/db/migrations.ts
src/lib/db/types.ts
src/lib/db/moments.ts
src/lib/db/works.ts
src/lib/db/references.ts
src/lib/db/feed.ts
src/lib/db/fts.ts
 
以及实际数据库导出入口。
 
Server Actions / 服务层
 
src/lib/actions/moments.ts
src/lib/actions/works.ts
src/lib/actions/references.ts
src/lib/actions/posts.ts
src/lib/actions/sync.ts
src/lib/admin/deploy.ts
 
后台
 
src/components/admin/AdminNav.tsx
src/app/admin/(protected)/moments/**
src/app/admin/(protected)/works/**
src/app/admin/(protected)/references/**
src/components/admin/MomentForm.tsx
src/components/admin/WorkForm.tsx
src/components/admin/AdminReferenceAddButton.tsx
src/components/admin/ArticleReferenceDialog.tsx
src/components/admin/ArticleReferenceArchiveActions.tsx
 
前台
 
src/app/(site)/moments/page.tsx
src/app/(site)/works/page.tsx
src/app/(site)/references/page.tsx
src/app/(site)/memo/page.tsx
src/lib/site-navigation.ts
src/lib/home-feed.ts
 
以及：
 
* classic theme 相关组件
* MomentEntry
* ReferenceLibraryCard
* works 相关展示组件
 
API
 
检查：
 
src/app/api/v1/moments/**
src/app/api/v1/works/**
src/app/api/v1/references/**
src/lib/api.ts
 
以及实际存在的 API 文件。
 
⸻
 
五、现有功能必须保留
 
moments
 
当前絮语已有能力必须保留：
 
* 文本
* 图片
* 标签
* 城市位置
* 音乐
* 评论
* 点赞
* 浏览量
* 编辑
* 删除
* FTS 搜索
 
不要为了生活节点功能破坏这些能力。
 
⸻
 
reference_library
 
现有引用系统已有：
 
* URL
* canonical URL
* 标题
* 来源
* 作者
* 发布时间
* 封面
* 描述
* 摘要
* key points
* 分类
* 标签
* article references
* reader archive
* archive jobs
* canonical URL 去重
 
这些都必须保留。
 
尤其不得破坏：
 
article_references
reference_library
article_reference_archives
article_reference_archive_jobs
 
之间现有关系。
 
现有文章引用快照机制必须继续存在。
 
⸻
 
六、前台导航修改
 
修改：
 
src/lib/site-navigation.ts
 
经典版导航最终必须变成：
 
随笔 → /posts
絮语 → /moments
小记 → /life
归档 → /archives
关于 → /about
 
其中仅把原来的：
 
小记 → /works
 
改为：
 
小记 → /life
 
不得删除经典导航结构。
 
⸻
 
七、历史路由兼容
 
/memo
 
当前：
 
/memo → /works
 
应修改为：
 
/memo → /life
 
因为 /life 才是新的「小记」页面。
 
⸻
 
/works
 
旧：
 
/works
 
必须保留兼容。
 
建议：
 
/works → /life?type=works
 
使用永久重定向或与项目当前路由策略一致的兼容方式。
 
不得直接造成旧链接 404。
 
⸻
 
/references
 
现有：
 
/references
 
可以继续作为兼容入口。
 
建议可保留现有独立页面，或者后续重定向到：
 
/life?type=references
 
本轮优先保证兼容，不要求强制删除原独立页面。
 
⸻
 
八、后台新的信息架构
 
当前后台已有：
 
仪表盘
文章
想法
数据
页面
设置
 
需要清理。
 
新的主要结构建议：
 
仪表盘
文章
絮语
小记
数据
设置
 
其中：
 
絮语
 
继续保留独立入口：
 
/admin/moments
 
或者迁移到更规范位置，但不要强制合并进小记。
 
对外名称统一：
 
絮语
 
不要再显示：
 
想法
 
⸻
 
小记
 
新增一级后台入口：
 
小记
 
进入：
 
/admin/life
 
其顶部 Tabs：
 
生活节点
作品
GitHub
收藏引用
 
推荐路由：
 
/admin/life/milestones
/admin/life/works
/admin/life/github
/admin/life/references
 
/admin/life
 
默认跳转：
 
/admin/life/milestones
 
抽取共享：
 
LifeAdminTabs
 
或类似组件。
 
要求：
 
* 当前 Tab active 明显
* 移动端可横向滚动或合理适配
* 不重复复制四套顶部结构
* 延续当前后台视觉风格
 
⸻
 
九、生活节点必须使用独立数据模型
 
此前不要使用：
 
moments.kind = milestone
 
方案。
 
生活节点必须新增独立数据表：
 
life_events
 
因为：
 
絮语
 
是当时留下的原始记录，
 
而：
 
生活节点
 
是后来整理的人生时间索引。
 
一条絮语可以被提取成生活节点，但原始絮语必须继续保留。
 
⸻
 
十、life_events 数据表
 
新增：
 
life_events
 
建议字段至少包括：
 
id
title
content
occurred_at
date_precision
cover
images
tags
location
source_type
source_moment_id
created_at
updated_at
 
根据当前数据库现有字段风格调整 SQLite 类型。
 
⸻
 
十一、生活节点日期设计
 
必须区分：
 
created_at
 
和：
 
occurred_at
 
含义：
 
created_at
= 什么时候录入博客
occurred_at
= 事情实际什么时候发生
 
例如：
 
2026 年录入：
 
2002 年第一次做网站
 
时间线应显示到：
 
2002
 
而不是 2026。
 
⸻
 
十二、date_precision
 
支持：
 
day
month
year
 
例如：
 
2002
2025-07
2026-09-03
 
前端不得为了存储方便强制把：
 
2002
 
展示成：
 
2002-01-01
 
数据库可以内部采用统一日期格式，但 UI 必须尊重精度。
 
⸻
 
十三、生活节点来源
 
source_type：
 
manual
moment
 
手动添加
 
source_type = manual
source_moment_id = NULL
 
从絮语提取
 
source_type = moment
source_moment_id = moments.id
 
⸻
 
十四、source_moment_id 外键
 
建议：
 
FOREIGN KEY(source_moment_id)
REFERENCES moments(id)
ON DELETE SET NULL
 
删除原始絮语时：
 
* 不得删除生活节点
* 仅断开来源关系
 
因为生活节点已经是独立整理好的记录。
 
⸻
 
十五、防止重复提取
 
默认：
 
一条絮语只允许直接提取成一个生活节点。
 
建议给非 NULL：
 
source_moment_id
 
建立唯一约束或 partial unique index。
 
如果 SQLite 当前版本和项目结构适合，可使用：
 
UNIQUE INDEX WHERE source_moment_id IS NOT NULL
 
避免重复点击产生多个节点。
 
⸻
 
十六、生活节点后台
 
后台：
 
/admin/life/milestones
 
顶部至少提供：
 
+ 添加生活节点
从絮语提取
 
列表按照：
 
occurred_at DESC
 
排序。
 
不是：
 
created_at DESC
 
建议展示：
 
* 日期
* 日期精度
* 标题
* 内容摘要
* 标签
* 图片数量
* 位置
* 来源
* 编辑
* 删除
 
⸻
 
十七、手动创建生活节点
 
支持填写：
 
标题
内容
发生日期
日期精度
封面
图片
标签
位置
 
如项目已有适合复用的：
 
* 图片上传
* 标签输入
* 位置
* 音乐
* Markdown / textarea
 
优先复用现有组件。
 
不要复制大量 MomentForm 代码。
 
⸻
 
十八、从絮语提取生活节点
 
这是本次核心功能之一。
 
后台提供：
 
从絮语提取
 
点击打开絮语选择器。
 
默认优先显示：
 
尚未提取
 
支持：
 
全部
未提取
已提取
 
以及搜索。
 
每条显示：
 
* 时间
* 内容摘要
* 图片
* 标签
* 是否已提取
 
⸻
 
十九、提取流程
 
选择絮语后：
 
不要直接静默创建生活节点。
 
必须进入整理界面。
 
根据原絮语自动预填：
 
content
occurred_at
images
tags
location
 
标题可以：
 
* 留空让用户填写
* 或通过现有 AI 能力生成建议
 
但不得未经用户确认直接覆盖。
 
用户可以修改：
 
* 标题
* 内容
* 日期
* 日期精度
* 图片
* 标签
* 位置
 
确认后才创建：
 
life_events
 
同时：
 
source_type = moment
source_moment_id = 原 moments.id
 
原絮语保持完全不变。
 
⸻
 
二十、絮语后台增加提取入口
 
现有絮语列表操作：
 
查看
编辑
删除
 
增加：
 
提取节点
 
如果已经提取：
 
已提取节点
 
并可以点击跳转到对应：
 
/admin/life/milestones/{id}/edit
 
或实际编辑路径。
 
⸻
 
二十一、前台生活节点来源展示
 
如果生活节点来自絮语，可以轻量显示：
 
来自一条 2026-09-03 的絮语
 
链接：
 
/moments#moment-{id}
 
如果当前 moment DOM anchor 命名不同，则复用现有规则。
 
不要重复完整展示原絮语正文。
 
⸻
 
二十二、生活节点产品语义
 
代码和 UI 必须遵循：
 
絮语
= 当时留下的原始记录
生活节点
= 对经历整理后的时间索引
 
不得因为提取：
 
* 删除原絮语
* 隐藏原絮语
* 修改原絮语类型
* 将原絮语迁移到 life_events
 
提取是：
 
复制 + 整理 + 建立来源关系
 
不是：
 
移动
 
⸻
 
二十三、数据库 migration
 
当前项目 migration 已有连续版本管理。
 
必须先检查：
 
src/lib/db/migrations.ts
 
确认当前最新版本。
 
然后新增下一版本。
 
不要：
 
* 修改已经发布的旧 migration
* 只改 BASE_SCHEMA_SQL
* 直接假设 migration 版本号
 
新增表和字段必须：
 
1. 修改 base schema
2. 新增 migration
3. 更新 types
4. 更新 DAO
5. 更新 tests
6. 检查 schema version
 
⸻
 
二十四、life_events DAO
 
新增独立 DAO，例如：
 
src/lib/db/life-events.ts
 
或者遵循项目命名规则。
 
至少实现：
 
createLifeEvent()
updateLifeEvent()
deleteLifeEvent()
getLifeEvent()
listLifeEvents()
countLifeEvents()
getLifeEventBySourceMoment()
 
需要分页。
 
避免列表页 N+1。
 
⸻
 
二十五、作品 works 保持独立
 
现有：
 
works
 
不重构成 life_events。
 
作品和人生事件不是一个数据模型。
 
作品继续支持现有：
 
* title
* description
* cover
* link
* sort_order
 
如果未来有必要可以扩展：
 
published_at
tags
featured
 
但本轮不是必须。
 
⸻
 
二十六、新增 GitHub Repository 模型
 
新增：
 
github_repositories
 
建议字段：
 
id
owner
name
full_name
repo_url
description
homepage
primary_language
topics
stars
forks
license
default_branch
archived
visibility
github_created_at
github_updated_at
pushed_at
custom_title
custom_description
cover
tags
featured
registered_at
synced_at
sync_status
sync_error
 
⸻
 
二十七、GitHub 唯一标识
 
使用：
 
full_name
 
例如：
 
aluvien/yezi-blog
 
并：
 
UNIQUE(full_name)
 
避免重复登记。
 
⸻
 
二十八、GitHub 仓库登记
 
后台：
 
/admin/life/github
 
提供：
 
+ 登记 GitHub 仓库
 
允许输入：
 
https://github.com/aluvien/yezi-blog
 
或者：
 
aluvien/yezi-blog
 
规范化：
 
owner = aluvien
name = yezi-blog
full_name = aluvien/yezi-blog
repo_url = https://github.com/aluvien/yezi-blog
 
必须验证：
 
* GitHub owner 合法
* repo name 合法
* 必须是真正 GitHub Repo
* github.com 之外 URL 不得当作 GitHub Repo
* 不允许重复 full_name
 
⸻
 
二十九、GitHub 元数据同步
 
新增专门 Repository metadata service。
 
当前项目已有：
 
syncLatestGithubAction
 
但它属于：
 
服务器部署 / 代码更新
 
不得复用成 Repository 元数据同步。
 
新功能建议命名：
 
syncGithubRepositoryMetadata()
syncAllGithubRepositoryMetadata()
 
明确与 deploy sync 区分。
 
⸻
 
三十、GitHub 同步字段
 
至少同步：
 
name
full_name
description
homepage
stars
forks
primary_language
topics
license
archived
visibility
default_branch
created_at
updated_at
pushed_at
 
同步成功：
 
sync_status = success
synced_at = now
sync_error = null
 
失败：
 
sync_status = error
sync_error = 人类可理解的错误
 
批量同步：
 
* 单个失败不得导致全部中止
* 返回成功 / 失败统计
 
⸻
 
三十一、GitHub Token
 
使用环境变量：
 
GITHUB_TOKEN
 
禁止：
 
* 写死 token
* 打印 token
* 返回 token 到前端
 
没有 Token 时：
 
* 公共仓库可以尝试 GitHub 公共 API
* 正确处理 rate limit
* 后台给出明确错误
 
⸻
 
三十二、GitHub 手动数据优先
 
自动同步字段和手工字段必须分离。
 
自动字段：
 
description
homepage
stars
forks
primary_language
topics
license
...
 
手动字段：
 
custom_title
custom_description
cover
tags
featured
 
展示：
 
custom_title || name
custom_description || description
 
GitHub 同步绝对不得覆盖：
 
custom_title
custom_description
cover
tags
featured
 
⸻
 
三十三、作品与 GitHub 关联
 
新增：
 
work_github_repositories
 
至少包含：
 
work_id
repository_id
created_at
 
推荐：
 
PRIMARY KEY(work_id, repository_id)
 
允许：
 
* 一个作品无仓库
* 一个作品一个仓库
* 一个作品多个仓库
* 一个仓库根据需求关联多个作品
 
不要在：
 
works
 
中增加：
 
github_repo_id
 
这种单关系设计。
 
⸻
 
三十四、作品后台
 
在作品编辑页面增加：
 
关联 GitHub 仓库
 
支持：
 
0 个
1 个
多个
 
优先使用多选控件。
 
不要破坏现有 WorkForm。
 
⸻
 
三十五、收藏引用继续使用 reference_library
 
禁止新增：
 
bookmarks
web_bookmarks
favorites
saved_pages
 
作为平行收藏系统。
 
继续使用：
 
reference_library
 
⸻
 
三十六、reference_library 增强
 
新增字段：
 
note
status
favorite
saved_at
last_checked_at
 
其中：
 
note
 
必须实现。
 
含义：
 
为什么收藏这个资料
准备如何使用
它与什么内容有关
 
示例：
 
博客升级 Next.js 16 缓存体系时重点参考。
 
⸻
 
三十七、收藏状态
 
建议：
 
inbox
read
archived
 
如果为了控制本轮复杂度，也可以：
 
inbox
archived
 
但 schema 设计要易于后续扩展。
 
⸻
 
三十八、发布时间和收藏时间必须分开
 
published_at
 
表示：
 
原网页发布时间
saved_at
 
表示：
 
我什么时候收藏
 
小记时间流中的收藏项目排序：
 
优先使用：
 
saved_at
 
绝对不要使用 published_at 替代收藏时间。
 
⸻
 
三十九、URL canonical normalization 增强
 
保留现有 canonical 逻辑。
 
在此基础上谨慎去除常见 tracking 参数：
 
utm_source
utm_medium
utm_campaign
utm_term
utm_content
fbclid
gclid
 
不要暴力删除所有 query 参数。
 
对于：
 
spm
from
ref
 
等参数需要谨慎。
 
部分网站使用 query 参数确定实际内容。
 
现有：
 
X / Twitter
 
专门 URL normalization 逻辑必须保留。
 
新增测试覆盖：
 
* utm 去除
* hash 去除
* 内容型 query 保留
* X URL
* 同 canonical 去重
 
⸻
 
四十、通用 reference relations
 
现有：
 
article_references
 
继续负责：
 
文章中的引用快照
 
不要删除。
 
另新增：
 
reference_relations
 
用于更广泛关联。
 
建议：
 
id
reference_id
target_type
target_id
context
created_at
 
支持：
 
post
life_event
work
github_repository
 
如果 moment 也有明确需求，可以支持：
 
moment
 
但优先保持实际使用场景。
 
⸻
 
四十一、引用关系语义
 
例如一个 Next.js 官方文档可以关联：
 
文章
作品
GitHub Repository
生活节点
 
其中：
 
article_references
 
仍然是“文章实际发表时引用的稳定快照”。
 
而：
 
reference_relations
 
表示：
 
这个资料与哪个内容有关
 
职责不可混淆。
 
⸻
 
四十二、引用后台增强
 
收藏引用列表可以增加：
 
备注 note
状态
收藏标记
关联内容
收藏时间
 
例如：
 
关联内容
文章 2
作品 1
GitHub 1
生活节点 1
 
点击可以查看具体关系。
 
必须避免明显 N+1。
 
优先：
 
* JOIN 聚合
* 批量查询
* Map hydrate
 
不要每张卡片单独请求数据库。
 
⸻
 
四十三、引用搜索
 
当前如果仍使用：
 
instr(lower(...))
 
可以暂时保留。
 
如果本轮实现 fts_references 成本合理，可复用现有 FTS5 trigram 架构。
 
搜索：
 
title
source_name
author
description
summary
key_points
category
tags
note
 
如果增加 FTS：
 
* 必须版本化
* 必须 triggers
* migration 支持 rebuild
* 不影响 posts / moments FTS
 
如果本轮变更过大：
 
可以将 reference FTS 明确标记为：
 
后续优化
 
不要为了 FTS 阻塞核心功能。
 
⸻
 
四十四、新增前台 /life 页面
 
新增：
 
src/app/(site)/life/page.tsx
 
或按项目真实路由结构实现。
 
页面名称必须：
 
小记
 
不要叫：
 
生活小记
 
作为用户界面主标题。
 
因为经典导航名称已经确定为：
 
小记
 
可以使用类似副标题：
 
记录经历，也留下做过的事。
 
具体文案保持与 classic theme 风格一致。
 
⸻
 
四十五、小记 Tabs
 
/life 包含：
 
全部
生活节点
作品
GitHub
收藏引用
 
建议：
 
/life?type=all
/life?type=milestones
/life?type=works
/life?type=github
/life?type=references
 
如果项目路由风格更适合子路由，也可以采用子路由。
 
优先：
 
* 简单
* 可分享
* 可后退
* SSR 友好
* 与项目现有风格统一
 
⸻
 
四十六、絮语不要放入 /life
 
再次强调：
 
/moments
 
继续独立。
 
/life 中禁止增加：
 
絮语
 
Tab。
 
最终：
 
/life
├── 全部
├── 生活节点
├── 作品
├── GitHub
└── 收藏引用
 
⸻
 
四十七、小记“全部”时间流
 
不要简单：
 
const items = [
  ...allLifeEvents,
  ...allWorks,
  ...allGithubRepos,
  ...allReferences,
].sort(...)
 
然后一次性全部加载。
 
必须参考现有：
 
src/lib/db/feed.ts
src/lib/home-feed.ts
 
现有架构思想：
 
UNION ALL
只查询轻量 type / id / time
数据库排序
LIMIT/OFFSET
批量 hydrate
 
新的 Life Feed 应沿用同样设计。
 
⸻
 
四十八、Life Feed 类型
 
可以定义：
 
type LifeFeedItem =
  | LifeEventFeedItem
  | WorkFeedItem
  | GithubRepositoryFeedItem
  | ReferenceFeedItem
 
每种 item 保留：
 
type
id
sort_time
 
然后根据 type 批量 hydrate。
 
⸻
 
四十九、Life Feed 时间来源
 
必须使用符合产品语义的时间。
 
生活节点
 
occurred_at
 
作品
 
如果当前没有真实发布日期：
 
第一版使用：
 
created_at
 
但不要使用：
 
sort_order
 
作为时间。
 
后续可扩展：
 
published_at
 
GitHub
 
使用：
 
registered_at
 
表示：
 
什么时候登记到自己的小记
 
不要使用：
 
synced_at
 
作为生活时间线时间。
 
收藏引用
 
使用：
 
saved_at
 
不要使用：
 
published_at
 
⸻
 
五十、Life Feed 查询
 
建议新增：
 
src/lib/db/life-feed.ts
 
或遵循当前命名。
 
使用类似：
 
SELECT 'life_event', id, occurred_at AS sort_time
FROM life_events
UNION ALL
SELECT 'work', id, created_at AS sort_time
FROM works
UNION ALL
SELECT 'github_repository', id, registered_at AS sort_time
FROM github_repositories
UNION ALL
SELECT 'reference', id, saved_at AS sort_time
FROM reference_library
ORDER BY sort_time DESC
LIMIT ? OFFSET ?
 
实际 SQL 按当前 SQLite/schema 结构优化。
 
然后分别批量：
 
getLifeEventsByIds
getWorksByIds
getGithubRepositoriesByIds
getReferencesByIds
 
最后恢复统一顺序。
 
⸻
 
五十一、单独 Tab 分页
 
以下所有 Tab：
 
生活节点
作品
GitHub
收藏引用
 
都必须支持合理分页。
 
不要一次性加载无限量数据。
 
复用当前：
 
* pagination
* query params
* page size
 
设计风格。
 
⸻
 
五十二、前台生活节点展示
 
生活节点建议采用：
 
时间轴
 
而不是普通作品 Card。
 
日期精度：
 
2026-09-03
2025-07
2002
 
必须按实际 precision 展示。
 
内容建议：
 
年份 / 日期
标题
内容
图片
标签
位置
来源絮语
 
保持简洁。
 
⸻
 
五十三、前台作品展示
 
继续复用现有作品展示能力。
 
但现在属于：
 
/life?type=works
 
不要大幅重写视觉设计。
 
在“全部”流中可以使用精简版卡片。
 
⸻
 
五十四、GitHub 前台展示
 
Repository 卡片建议展示：
 
名称
描述
语言
stars
forks
topics
最后 pushed 时间
GitHub 链接
homepage
 
但避免变成完整 GitHub Dashboard。
 
用户真正的自定义内容：
 
custom_title
custom_description
cover
tags
featured
 
应优先显示。
 
⸻
 
五十五、收藏引用前台
 
复用现有：
 
ReferenceLibraryCard
 
尽量不要复制第二套。
 
根据 /life 场景适配：
 
note
saved_at
favorite
category
tags
 
公开前端不要泄露：
 
archive private body
archive job
内部同步错误
后台私有字段
 
⸻
 
五十六、API
 
现有 API 必须保持兼容。
 
不要因为新功能破坏：
 
/api/v1/moments
/api/v1/works
/api/v1/references
 
新增：
 
/api/v1/life-events
 
如果现有 API 命名使用别的习惯，则遵循项目约定。
 
新增 GitHub API：
 
/api/v1/github-repositories
 
如有必要新增：
 
/api/v1/life
 
作为统一 feed API。
 
⸻
 
五十七、公开 serializer
 
更新：
 
src/lib/api.ts
 
增加：
 
publicLifeEvent()
publicGithubRepository()
 
如果增加 Life Feed：
 
增加：
 
publicLifeFeedItem()
 
必须明确过滤私有字段。
 
GitHub 不得公开：
 
sync_error
 
如果其内容可能包含内部错误信息。
 
Reference 不得因为 life API 暴露 private archive 数据。
 
⸻
 
五十八、后台 Server Actions
 
新增或扩展：
 
life event actions
github repository actions
reference relation actions
 
所有写操作必须继续使用项目已有：
 
* admin 权限检查
* 输入 validation
* revalidatePath
* 错误处理
 
不要创建绕过现有权限体系的新接口。
 
⸻
 
五十九、安全要求
 
所有后台新增操作：
 
* 必须验证管理员身份
* 不相信客户端传入的 id
* GitHub URL 必须严格解析
* 防止任意 URL 被当 GitHub API 请求
* 不允许 SSRF
* 不允许用户控制服务端 fetch 任意 host
* 不把 GitHub token 返回客户端
* 不把服务器内部异常 stack 暴露给页面
 
引用抓取继续使用当前安全约束。
 
⸻
 
六十、缓存要求
 
检查当前：
 
* revalidate
* no-store
* unstable cache
* API cache
 
策略。
 
管理后台：
 
优先保证实时一致性。
 
公开页面：
 
按现有项目策略处理。
 
新增/编辑/删除后必须正确：
 
revalidate /life
revalidate 对应 Tab
 
同时保持：
 
/moments
/works
/references
 
兼容页面缓存正确。
 
⸻
 
六十一、删除行为
 
删除生活节点
 
不得删除来源絮语。
 
删除来源絮语
 
life_events.source_moment_id
 
应：
 
SET NULL
 
生活节点继续存在。
 
删除 GitHub Repository
 
正确处理：
 
work_github_repositories
reference_relations
 
不要留下脏关系。
 
删除 Work
 
正确处理 work-repository relation。
 
删除 Reference
 
保留当前引用系统原有语义。
 
不要因为新增 relation 改坏：
 
article_references
 
快照机制。
 
⸻
 
六十二、后台 Dashboard
 
当前后台已经有：
 
* Articles
* Moments
* Works
* References
* Comments
* Views
* Likes
* Attachments
 
更新显示名称：
 
Moments → 絮语
 
增加：
 
生活节点
GitHub
 
Works 对外：
 
作品
 
References：
 
收藏引用
 
不要为了小记聚合把各统计全部合成一个数字。
 
可以增加一个：
 
小记
 
聚合统计，但必须保留分项统计可见。
 
⸻
 
六十三、页面 Meta / SEO
 
统一页面 title。
 
/moments
 
絮语
 
不要再：
 
想法
 
/life
 
小记
 
/works 兼容页
 
若 redirect，无需独立重复 SEO。
 
/references
 
保留现有或根据兼容策略处理。
 
⸻
 
六十四、Classic Theme
 
重点检查 classic theme。
 
因为当前：
 
小记
 
历史上实际指向：
 
works
 
本次必须清理。
 
Classic 导航：
 
随笔
絮语
小记
归档
关于
 
其中：
 
小记 → /life
 
Classic 现有：
 
ClassicMemoPage
 
如果它本质上只是 works 页面：
 
不要继续把它当成完整小记页面。
 
可以：
 
* 重构为 /life 的某个作品 Section
* 或保留为作品组件
* 或重新抽取
 
但不得让：
 
works
 
继续拥有：
 
生活小记
 
的页面语义。
 
⸻
 
六十五、现代主题
 
如果 modern theme 当前导航不同，可以在不破坏其设计的情况下适配新 /life。
 
但此次最重要的产品约束是：
 
经典版五项导航必须保持不变。
 
不要为了 modern theme 改坏 classic。
 
⸻
 
六十六、可访问性
 
新增：
 
* Tabs
* Dialog
* GitHub form
* 时间线
* 选择絮语
* 多选 Repository
 
必须检查：
 
* keyboard navigation
* focus
* aria-current
* aria-label
* button type
* form label
* dialog focus trap
* 图片 alt
* 色彩不能是唯一状态表达方式
 
⸻
 
六十七、移动端
 
重点检查：
 
/life
/admin/life/**
 
要求：
 
* Tab 小屏可横向滚动
* 时间线不溢出
* GitHub repo 长 full_name 正确换行
* URL 不撑爆 Card
* Tags 换行
* 后台操作按钮不挤压
* modal 在窄屏可正常使用
* 图片布局正常
 
⸻
 
六十八、性能
 
重点避免：
 
N+1
全量加载
JS 端全量 sort
每张卡片单独查关系
每次 render 请求 GitHub
 
GitHub 数据必须：
 
后台同步到数据库
前台读取数据库快照
 
绝对不要前台访问 /life 时实时调用 GitHub API。
 
⸻
 
六十九、GitHub 同步不进入页面渲染关键路径
 
GitHub API 失败时：
 
/life
 
仍然必须正常打开。
 
前端显示数据库最近一次成功同步结果。
 
管理员可手动：
 
同步
 
GitHub 外部服务不可用不应导致站点不可用。
 
⸻
 
七十、测试
 
必须补充或更新测试。
 
至少覆盖：
 
life_events
 
* create
* update
* delete
* source moment
* source moment delete SET NULL
* duplicate extraction prevention
* date precision
* pagination
 
提取絮语
 
* 原 moment 不变
* life_event 正确创建
* 来源关系正确
* 已提取不能重复创建
 
GitHub parser
 
* full URL
* owner/repo
* invalid host
* invalid repo
* duplicate
 
GitHub sync
 
* success
* 404
* rate limit
* invalid token
* API error
* custom fields 不被覆盖
 
Works ↔ GitHub
 
* 关联
* 多仓库
* 删除关系
* 删除 repo
* 删除 work
 
References
 
* tracking params normalization
* canonical 去重
* note
* relation
 
Life Feed
 
* 混合排序
* pagination
* 时间字段正确
* hydrate 后顺序不乱
 
⸻
 
七十一、迁移兼容
 
部署到已有数据库时必须：
 
自动 migration
 
不能要求用户：
 
* 删除数据库
* 手工重建
* 清空数据
 
当前：
 
* posts
* moments
* works
* references
* comments
* metrics
 
数据必须保留。
 
⸻
 
七十二、禁止事项
 
不要：
 
1. 把 moments 改名成 whispers
2. 把 works 改名成 memos
3. 把 reference_library 重做成 bookmarks
4. 把生活节点做成 moments.kind
5. 把絮语合并进 /life
6. 把经典导航改掉
7. 删除 /moments
8. 直接删除 /works 造成 404
9. 删除文章引用快照机制
10. 把 GitHub deploy sync 和 repo metadata sync 混在一起
11. 每次前端渲染实时请求 GitHub
12. 大规模重构与本需求无关代码
13. 修改历史 migration
14. 为了 UI 命名修改数据库核心技术实体
15. 创建重复的收藏系统
16. 在 JS 内加载全部小记数据再 sort
17. 引入明显 N+1
18. 破坏 Next.js 当前版本兼容性
19. 输出 secret/token
20. 静默吞掉 GitHub 同步错误
 
⸻
 
七十三、推荐实施顺序
 
严格建议按以下顺序实施。
 
Phase 1：命名与路由
 
先完成：
 
moments UI → 絮语
小记导航 → /life
/memo → /life
/works → /life?type=works
 
建立 /life 基础页面。
 
不要先删除旧页面。
 
⸻
 
Phase 2：数据库
 
新增：
 
life_events
github_repositories
work_github_repositories
reference_relations
 
扩展：
 
reference_library
 
新增正式 migration。
 
⸻
 
Phase 3：Types / DAO
 
实现：
 
* life events DAO
* GitHub DAO
* relation DAO
* Work ↔ repo DAO
* reference metadata 更新
* bulk hydrate
 
⸻
 
Phase 4：后台生活节点
 
实现：
 
/admin/life/milestones
 
包括：
 
* 手动添加
* 编辑
* 删除
* 从絮语提取
 
再给絮语后台加入：
 
提取节点
 
⸻
 
Phase 5：GitHub 管理
 
实现：
 
/admin/life/github
 
包括：
 
* 登记
* 编辑自定义字段
* 同步
* 批量同步
* 删除
* 状态展示
 
⸻
 
Phase 6：作品关联 GitHub
 
在现有作品编辑中加入多 Repository 关联。
 
⸻
 
Phase 7：引用增强
 
实现：
 
* note
* status
* favorite
* saved_at
* relations
* URL normalization 增强
 
不要重写现有 article references。
 
⸻
 
Phase 8：前台 /life
 
实现：
 
全部
生活节点
作品
GitHub
收藏引用
 
⸻
 
Phase 9：统一 Life Feed
 
参考现有 feed 架构完成：
 
UNION ALL
数据库排序
分页
批量 hydrate
 
⸻
 
Phase 10：兼容与测试
 
完整检查：
 
* old URLs
* classic theme
* modern theme
* API
* mobile
* accessibility
* migrations
* build
* lint
* typecheck
* tests
 
⸻
 
七十四、验收标准
 
最终必须满足：
 
导航
 
经典导航仍然是：
 
随笔 / 絮语 / 小记 / 归档 / 关于
 
絮语
 
/moments
 
继续独立。
 
UI 不再称：
 
想法
 
小记
 
/life
 
正式成为新的小记首页。
 
包含：
 
全部
生活节点
作品
GitHub
收藏引用
 
生活节点
 
可以：
 
后台手动添加
 
也可以：
 
从絮语提取
 
提取后：
 
原絮语仍存在
 
作品
 
继续使用：
 
works
 
并可关联多个 GitHub Repository。
 
GitHub
 
可以：
 
* 登记
* 同步
* 自定义展示
* 查看同步错误
* 不影响前台可用性
 
收藏引用
 
继续使用：
 
reference_library
 
并支持：
 
note
status
favorite
saved_at
relation
 
全部
 
/life?type=all
 
按照正确业务时间混合展示：
 
生活节点
作品
GitHub
收藏引用
 
并有真正数据库分页。
 
兼容
 
旧：
 
/memo
/works
/references
 
不能无故 404。
 
数据
 
升级后旧数据库全部数据保留。
 
工程
 
必须通过项目实际存在的：
 
typecheck
lint
test
build
 
如果某条命令项目不存在，不要自行假造 package script。
 
⸻
 
七十五、最终交付要求
 
完成代码后，不要只告诉我“已完成”。
 
请输出一份实施报告，包含：
 
1. 修改了哪些文件
2. 新增了哪些文件
3. 新增了哪些 migration
4. 数据库结构变化
5. 路由变化
6. 后台变化
7. 前台变化
8. GitHub 同步实现方式
9. 絮语提取生活节点的完整流程
10. Reference 系统做了哪些增强
11. 旧地址如何兼容
12. 做了哪些测试
13. typecheck / lint / test / build 结果
14. 是否存在需要人工配置的环境变量
15. 是否还有未完成项
16. 是否存在需要我确认的设计选择
 
如果发现当前仓库实际实现和本提示词中的路径、字段或假设不完全一致：
 
优先服从当前 main 分支真实代码架构。
 
不要机械创建重复模块。
 
如果已有能力可以扩展：
 
优先扩展。
 
如果已有组件可以复用：
 
优先复用。
 
如果发现本需求会破坏已有：
 
* 安全
* 数据一致性
* migration
* API
* classic theme
* comments
* metrics
* FTS
 
必须采用兼容方案，而不是强行实现。
 
最终目标不是“代码改得最多”，而是：
 
用尽可能小、清晰、可维护的改动，把「小记」升级成一个真正记录经历、作品、代码和收藏资料的长期个人档案系统。