雨舍：个人数字花园的设计与实现
雨舍：个人数字花园的设计与实现
雨舍（Yushe）是个人门户站点 yushe.ai 的项目代号。它的目标是构建一个完全属于个人的数字大本营，把高频使用的门户入口、知识输出和生产力工具聚合在同一个地方。目前已经落地并对外提供服务的，是其中的第一个模块：一个零后端的知识库博客系统。
愿景
雨舍设想的不只是一个博客，而是四个长期共存的模块：
| 模块 | 定位 |
|---|---|
| 浏览器门户 / Dashboard | 个性化首页，聚合搜索入口与日常关注的信息源 |
| 知识库博客（Digital Garden） | 基于 Obsidian 笔记直接发布的内容站点 |
| 个人工具站 | 收纳格式化、编解码等高频使用的小工具 |
| 个人 AI 应用 | 接入自有模型管线的对话与文本处理能力 |
四个模块之间共享同一套视觉语言和底层基础设施，但开发顺序上不追求齐头并进——优先把价值最确定的一块做扎实，再逐步扩展边界。
已实现：知识库博客
这是目前唯一交付并上线的模块，核心思路是取消"笔记"和"博文"之间的转换步骤。日常使用 Obsidian 记录的笔记本身就是发布的源文件，是否公开完全由 frontmatter 决定：
publish: true # 是否发布
type: post # 内容类型
visibility: public # 公开范围（亦支持密码保护等更细粒度控制）
draft: false # 是否为草稿站点在构建时遍历整个知识库，依据上述字段筛出可公开的笔记，解析后生成静态页面。这意味着内容创作和内容发布共用同一个工作流，不存在"整理笔记成博文"的额外环节。
针对 Obsidian 语法的适配
Obsidian 笔记里大量使用的是其专属语法，直接渲染为标准 Markdown 会丢失语义，因此内容管线在 remark/rehype 渲染流程之上做了一层定制转换：
- 双向链接
笔记、别名、笔记 > 标题：转换为站内文章链接，并对断链给出构建期告警 - 图片嵌入
、：转换为标准<img>并处理路径映射 - Callout（
> [!note]等高亮提示块）：转换为带左侧色条的语义化卡片，支持多种类型 - 高亮语法
<mark>文本</mark>：转换为<mark>标签 - Obsidian 专属注释 ``：在渲染时整段移除，不出现在公开页面
发布边界与构建期校验
内容是否公开，不只取决于 publish 一个字段，还要综合 draft、visibility、type，以及是否设置了密码或额外鉴权要求；这一套判断逻辑在构建期统一执行一次，线上不再做任何动态判断。同样在构建期完成的还有 frontmatter 字段校验、slug 唯一性检查（冲突直接中断构建，而不是悄悄覆盖）、以及断链与解析异常的诊断汇总——这些都属于"宁可构建失败，也不让坏内容上线"的设计取向。
检索与呈现
- 全文搜索：构建期生成索引，客户端纯前端检索，不依赖外部搜索服务
- 代码高亮：基于 Shiki 渲染，附带一键复制
- 标准博客能力：RSS、sitemap、robots.txt 一并提供
UI 设计思路
视觉设计的出发点是放弃传统博客"居中窄栏、大量留白"的排版方式，采用更高空间利用率的沉浸式布局，并围绕"层"的概念组织界面：
- 配色：暖色调暗黑主题，避免纯黑背景，整体基调更接近深灰、暖棕灰
- 分层结构：背景层承载缓慢呼吸的渐变光斑动画，导航层使用毛玻璃（
backdrop-filter）效果与内容区分隔，交互弹层（如搜索面板）按需注册到最上层 - 层级管理：上述分层关系由一个统一的
LayerManager组件管理 z-index 注册与释放，而不是在各处手写、相互冲突的z-index数值 - 微交互：卡片组件带有鼠标位置追踪的光效与轻微的 3D 倾斜反馈，强化沉浸感而不喧宾夺主
这套分层设计目前只落地了背景层与导航层两层，是早期更复杂的多层 UI 构想中最先做实的部分，后续模块会在此基础上继续扩展。
技术栈
Next.js（App Router）+ TypeScript（严格模式）+ Tailwind CSS，构建时直接读取文件、不连接数据库；部署在自托管服务器上，由 Gitea Actions 负责持续集成与部署。
尚未实现：规划中的方向
除了博客模块之外，以下设想已经成型但尚未开始开发：
- 门户 / Dashboard、工具站、AI 应用：见上文"愿景"表格，目前均处于构想阶段
- WebOS 化的界面重构：把当前简单的两层结构扩展为类似桌面操作系统的多窗口交互模式（任务栏、开始面板、窗口管理），其中包含一个可以在不同界面层之间"穿梭"的 3D 虚拟形象构想，技术上最大的难点在于跨层时鼠标事件的捕获与转发，目前仍停留在方案讨论阶段
这些方向一旦真正进入开发，会有专门的文章记录具体的实现过程，而不会只是更新这里的一条清单。
后续：技术细节文章
构建这套内容管线的过程中遇到过若干值得单独展开的技术问题——例如代码块行号渲染的兼容性问题、搜索弹层从 createPortal 迁移到自建 LayerManager 的取舍考量等。这类内容信息密度较高，不适合塞进项目概述，会在后续以独立文章的形式展开。
关于本文与其他文档的关系
雨舍项目的正式开发文档——需求、架构现状、迭代记录——维护在代码仓库的 docs/ 目录中，是指导开发的权威来源。本文是面向读者的项目介绍，会随项目实际进展更新，但不承担工程规格说明的职责。