先从 项目 README 了解页面和功能，再按下面的任务进入详细文档。这里维护当前项目的用法与设计；框架概念笔记单独放在参考资料中。
| 我想做什么 | 从这里开始 | 继续阅读 |
|---|---|---|
| 本地运行、预览、部署到自己的域名 | 开发与部署指南 | 部署、SEO 与地址 |
| 替换作者、导航、头像、备案或外部账号 | 个性化配置 | 外部服务 |
| 写文章、加拾趣、维护友链或项目 | 内容维护 | 内容发布 skill、正文样式指南文章 |
| 写图片排版、卡片日期、视频或绘图 | 正文与媒体 | 源码与管线、组件验证 |
| 理解一个页面应如何工作 | 站点与页面 | 模块属主 |
| 修改导航、分类筛选、分页或上下篇 | 页面契约 | 上下篇、实现边界 |
| 改样式、目录、主题、搜索或评论 | 架构与模块边界 | 视觉约束、评论 |
| 确认 RSS 会显示什么、换域名有什么影响 | SEO 与全文订阅 | RSS 内容表达、验证 |
| 配置首页屏幕时间与本机每小时同步 | ActivityWatch 屏幕时间 | macOS / Windows 安装、公开数据边界 |
| 接入或排查首页听歌接口 | Last.fm 运行时接口与展示 | 环境变量与部署 |
| 添加或排查拾趣歌单、运行时数据与导出 | 拾趣歌单 | 固定配置、平台适配器与 CDN 暖缓存 |
| 导入圆周旅迹或照片整理的行程、维护日历、调整旅行页或地图 | 旅行与日历 | 导入与照片脚本 |
| 开关像素猫、改皮肤或访客隐藏 | Oneko 像素猫 | 全站功能配置 |
| 跑检查、准备交付 | 检查与验收 | 对应设计文档末尾的验证映射 |
| 学习 Astro 组件、插槽和模板语法 | Astro 学习笔记 | 项目实现以架构文档和源码为准 |
| 文档 | 负责回答 | 不在这里维护 |
|---|---|---|
| 开发与部署指南 | 如何运行、配置、维护内容、部署和验证 | 完整算法及组件状态机 |
| 站点与页面 | 各页面、导航、筛选、上下篇、目录、主题、评论的用户契约；视觉不变量（含链接反馈三族，见 #visuals） | 正文组件和订阅的完整规则；模块属主与调用链路 |
| 架构与模块边界 | 规则由谁定义、调用链路、改功能应落在哪（含 --link-underline／首页次级入口的样式属主） |
链接反馈交互细则与专题重复的媒体契约（细则见 visuals） |
| 正文与媒体 | 图片、卡片、相册、HTML／音视频、绘图与博文卡的写法、设计及资源边界 | 订阅器中的输出策略 |
| SEO 与全文订阅 | canonical、sitemap、RSS 身份、内容降级、安全及失败语义 | 网站视觉布局 |
| Last.fm | 运行时接口、缓存、封面回退、请求上限和页面状态 | 通用卡片与图片查看器实现 |
| 拾趣歌单 | 固定歌单、平台适配、运行时缓存、海报卡片与文本导出 | 播放器、任意 URL 导入 |
| 旅行与日历 | 全屏旅行页、按月日历、中立行程数据、圆周旅迹与照片草稿导入、地图与回放 | 站内编辑、运行时同步圆周旅迹 |
| Oneko | 可选像素猫的托管集成、开关、换页和许可 | 本站内容与搜索 |
| Astro 学习笔记 | 框架概念与教学例子 | 当前项目规范或完整官方 API 文档 |
docs/
README.md 按任务查找文档
guides/
development.md 运行、个性化、内容、部署与验证
design/
site.md 站点与页面
architecture.md 架构与模块边界
content.md 正文与媒体
distribution.md SEO 与全文订阅
listening.md Last.fm
playlists.md 拾趣歌单
trips.md 旅行
screen-time.md ActivityWatch 屏幕时间
oneko.md Oneko
reference/
astro.md Astro 学习笔记
img/ 学习笔记的本地配图
- 先更新功能对应的设计文档及示例，再更新 README 的功能摘要和链接；README 不复制尺寸、状态机和完整参数表。
- 同一规则由一个专题完整解释，其它文档用简短说明和链接；全局模块属主集中在架构文档，专题保留必要的细化职责。
- 当前设计不夹带已经放弃的方案、阶段性报告或某次测试快照。历史变更留在 CHANGELOG 和 Git；“需要验收”不代表当前线上已经验收。
- 跨专题的同一行为变化，检查代码、测试、专题文档和作者示例是否一起更新。移动文件同时更新相对链接、锚点及源码注释中的入口。
- 内容发布 skill 是可独立分发的包，必要规则须在包内可读，不依赖仓库外部文档。