个人知识中枢与数字花园系统 需求与技术规格说明书 (PRD v2.1)
# 个人知识中枢与数字花园系统 需求与技术规格说明书 (PRD v2.1)
---
## 1. 系统定位与核心愿景
本系统定位为轻量级、自托管、多租户的**个人数字花园、碎片日记与现代专栏小册出版中枢**。
系统坚持以**“真实 Markdown 文件为单一真实数据源（Single Source of Truth, SSOT）”**，辅以 **“SQLite 元数据、FTS5 全文索引与反向双链索引引擎”**，利用 **Uni-app** 实现 Web、iOS、Android 全平台适配，并无缝集成 **n8n** 自动化工作流与 AI Agent。
针对传统知识库“分类层级过深产生维护疲劳”和“单一样式死板缺乏温度”的痛点，系统确立：
1. **收敛栏目层级**：统一四大一级根入口，单层扁平加深层双链，同时保留未来动态扩展余地；
2. **多形态模版化（Layout Templating）**：解耦小册、博客长文、碎片时间流三种独立视图模版；
3. **极速捕获与批处理合流**：移动端投递即走（2秒原则），支持单条即时处理，亦支持手动多选或每日定时合并汇总（Daily Digest）。
---
## 2. 存储与数据架构设计
### 2.1 物理目录结构规范（收敛与扩展性）
整个系统部署于家庭 NAS 或轻量云服务器，根目录命名为 `my_vault/`。用户内容遵循“物理租户隔离”与“两层半扁平化”原则：
```text
my_vault/
├── .system/ # 系统保留目录（不对用户暴露）
│ ├── app.db # SQLite 数据库（存账号、全文索引、双链关系、系统配置）
│ ├── backups/ # 每日快照与 SQLite dump
│ └── cache/ # 静态公开博客预渲染缓存
│
└── users/ # 多用户数据区
├── {user_id}/ # 用户空间（租户隔离）
│ ├── 00_Inbox/ # 1. 动态流：收集箱与暂存区（单层）
│ │ ├── Raw/ # 移动端捕获的原始文字/图片/语音
│ │ └── Drafts/ # AI / n8n 处理生成的待审阅 Markdown
│ ├── 01_Journal/ # 2. 时间流：日记随笔（按年月自动归档，无分类负担）
│ │ └── {YYYY}/{MM}/{YYYY-MM-DD}.md
│ ├── 02_Booklets/ # 3. 结构流：类似《更好生活手册》的专栏小册（限制2层）
│ │ └── {booklet-slug}/ # 单个专栏文件夹
│ │ ├── _book.yaml # 专栏全局元配置
│ │ ├── 01-认知篇/
│ │ │ ├── 01-心智模型.md
│ │ │ └── 02-反馈循环.md
│ │ └── 02-健康篇/
│ ├── 03_Articles/ # 4. 扁平库：独立散篇思考与深度长文（单层，靠标签/双链聚合）
│ │ └── {slug-or-title}.md
│ ├── 04_Extensions/ # 5. 扩展插槽：预留未来用户自定义独立分类目录
│ │ └── {custom_category}/
│ └── Assets/ # 6. 静态资源附件（按年月归档）
│ └── {YYYY}/{MM}/{hash}.(png|jpg|webp)
```
---
### 2.2 Markdown 标准 Front-matter 规范（含模版定义）
所有文章头部包含规范 YAML Front-matter，新增 `template`、`theme_accent` 字段以驱动前端排版。
```yaml
---
id: "doc-550e8400-e29b-41d4-a716-446655440000" # 唯一 UUID，文件重命名或移动时不丢失双链
title: "心智模型的建立与重构"
slug: "mental-models-and-refactoring" # URL 友好别名，用于对外公开博客路由
template: "booklet" # 核心模版：booklet (专栏小册) | post (博客长文) | stream (日记流)
theme_accent: "warm" # 视觉色调：warm(暖调人文) | tech(极客冷色) | mono(黑白素雅)
created_at: "2026-10-21 21:50:00"
updated_at: "2026-10-21 22:10:00"
tags: ["心智模型", "长期主义", "认知迭代"]
status: "draft" # draft (草稿待审), reviewed (已确认), published (发布)
visibility: "private" # private (私有), member (租户共享), public (免登公开)
author: "n8n_agent" # 来源标记: user | n8n_agent | agent_{name}
lang: "zh-CN" # 内容主体语言: zh-CN | en-US
target_booklet: "how-to-live-better" # 可选：归属专栏小册标识
target_chapter: "01-认知篇" # 可选：归属专栏章节
source_url: "https://x.com/..." # 可选：原始引用来源链接
---
正文内容从这里开始，支持原生 WikiLink 双向引用...
```
---
### 2.3 专栏小册配置规范 (`_book.yaml`)
用于定义类似《更好生活手册》的专栏级元信息：
```yaml
id: "book-how-to-live-better"
title: "更好生活手册"
subtitle: "给现代人的生活自救指南与心智模型"
author: "Admin"
cover_image: "/assets/covers/live-better.webp"
visibility: "public" # 支持整本小册一键公开为在线出版物
default_lang: "zh-CN"
default_template: "booklet"
order:
- name: "01-认知篇"
items:
- "01-心智模型.md"
- "02-反馈循环.md"
- name: "02-健康篇"
items:
- "01-精力管理.md"
```
---
### 2.4 SQLite 数据库表设计（元数据索引中心）
```sql
-- 1. 用户与租户表
CREATE TABLE users (
id TEXT PRIMARY KEY, -- 如 admin_01
username TEXT UNIQUE NOT NULL,
password_hash TEXT NOT NULL,
role TEXT NOT NULL DEFAULT 'member', -- admin | member
preferred_lang TEXT DEFAULT 'zh-CN', -- zh-CN | en-US
theme_preference TEXT DEFAULT 'system', -- light | dark | system
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- 2. 文档索引与缓存表
CREATE TABLE documents (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL,
file_path TEXT NOT NULL, -- 相对于 users/{id}/ 的物理路径
title TEXT NOT NULL,
slug TEXT,
doc_type TEXT NOT NULL, -- inbox | journal | article | booklet | custom
template TEXT NOT NULL DEFAULT 'post', -- booklet | post | stream
status TEXT NOT NULL DEFAULT 'draft', -- draft | reviewed | published
visibility TEXT NOT NULL DEFAULT 'private',-- private | member | public
lang TEXT DEFAULT 'zh-CN',
created_at DATETIME,
updated_at DATETIME,
file_mtime INTEGER NOT NULL, -- 文件物理修改时间戳，用于增量对比更新
FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE CASCADE
);
-- 3. 全文检索虚拟表 (SQLite FTS5)
CREATE VIRTUAL TABLE documents_fts USING fts5(
doc_id UNINDEXED,
user_id UNINDEXED,
title,
content,
tags,
tokenize = 'unicode61' -- 支持中英文混合分词
);
-- 4. 双向链接关系表
CREATE TABLE backlinks (
id INTEGER PRIMARY KEY AUTOINCREMENT,
source_doc_id TEXT NOT NULL, -- 引用方文档 ID
target_doc_id TEXT, -- 被引用方文档 ID（消歧未成时允许为空）
target_title TEXT NOT NULL, -- 原始引用的标题，如 [心智模型](/p/%E5%BF%83%E6%99%BA%E6%A8%A1%E5%9E%8B)
raw_context TEXT, -- 引用处的上下文摘录
FOREIGN KEY(source_doc_id) REFERENCES documents(id) ON DELETE CASCADE
);
-- 5. 待审阅草稿与批处理任务表
CREATE TABLE inbox_items (
id TEXT PRIMARY KEY, -- 如 item_20261021_001
user_id TEXT NOT NULL,
raw_content TEXT NOT NULL,
source_meta TEXT, -- JSON: { url, platform, capture_time }
status TEXT NOT NULL DEFAULT 'captured', -- captured (未处理) | queued | processed | merged | archived
digest_batch_id TEXT, -- 若参与了合流汇总，则记录批次 ID
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY(user_id) REFERENCES users(id) ON DELETE CASCADE
);
```
---
## 3. 前端 UI 模版化体系与多端交互规范
### 3.1 前端三大模版（Page Templates）解耦设计
系统抛弃固化的统一排版，针对不同场景动态挂载专有模版组件：
```text
┌── template === 'booklet' ─► BookletTemplate (小册模版)
│ • 左侧抽屉/悬浮章节导航
│ • 720px 黄金阅读宽度 + 翻页条
│ • 温暖的人文排版与行间距
│
Markdown 正文 ──┼── template === 'post' ────► PostTemplate (博客长文模版)
渲染引擎 │ • 顶部封面大图 + 作者/阅读时间
│ • 右侧悬浮目录 (TOC) + 代码行号
│ • 底部展开反向链接与相关推荐
│
└── template === 'stream' ──► StreamTemplate (动态流模版)
• 无标题碎片卡片瀑布流
• 时间戳折叠 + 快捷标签筛选
• 类似微博/Flomo 的敏捷展示
```
### 3.2 明暗色彩系统（Design Tokens）
```css
:root {
--bg-primary: #FFFFFF;
--bg-secondary: #F8F9FA;
--bg-card: #FFFFFF;
--border-subtle: #E9ECEF;
--text-main: #1F2328;
--text-muted: #6C757D;
--accent-color: #2D6A4F; /* 沉稳森林绿 */
--accent-hover: #1B4332;
--callout-bg: #E8F5E9;
--code-bg: #F1F3F5;
--reading-max-width: 760px;
}
[data-theme="dark"] {
--bg-primary: #0D1117; /* 避免死黑，防眼疲劳 */
--bg-secondary: #161B22;
--bg-card: #21262D;
--border-subtle: #30363D;
--text-main: #C9D1D9;
--text-muted: #8B949E;
--accent-color: #52B788; /* 柔和绿 */
--accent-hover: #74C69D;
--callout-bg: #1B2E24;
--code-bg: #161B22;
--reading-max-width: 760px;
}
```
### 3.3 移动端原生“极速捕获（Share Extension）”逻辑优化
1. **2秒投递即走原则**：
* 在 X、微信或浏览器中点击系统“分享”，唤出底栏后，带入选中文本；
* 用户选填一句补充语音或直接点击“投递”；
* 客户端在本地 SQLite/Storage 写入队列后**立即关闭弹窗**，不阻塞手机操作；
2. **后台静默同步**：
* 客户端后台服务检测网络就绪后，静默推送至后端的 `/api/v1/inbox/capture`；
* 后端处理完毕后，发送本地系统通知：“*刚刚捕获的灵感已由 AI 整理就绪*”。
---
## 4. 灵感捕获与 AI 批处理合流机制（单条 vs 多条汇总）
为了防止零散草稿泛滥造成“审阅焦虑”，系统支持两种处理流向：
```text
┌── [ 模式 A: 单条即时清洗 ]
│ • 适用：较完整的随感、深度长文链接
│ • 行为：立即触发 n8n/Agent，生成独立 .md 草稿待审
用户捕获碎片 ──┤
└── [ 模式 B: 多条合并汇总 (Daily Digest) ]
• 适用：零散金句、短推文、随手吐槽
• 行为 1（手动）：在移动端 Inbox 勾选 3~5 条碎片，点击「一键合并成简报」
• 行为 2（定时）：每日固定时间（如 21:00）n8n 轮询当天未处理碎片，
自动聚合输出《YYYY-MM-DD 每日灵感收纳简报》
```
---
## 5. n8n 自动化工作流与数据契约规范
### 5.1 FastAPI $\to$ n8n 外派契约（支持批量汇总与单条）
* **URL**: `POST https://{n8n_host}/webhook/garden-capture`
* **请求头**: `X-Garden-Signature: sha256={HMAC-SHA256}`
* **Payload 结构**:
```json
{
"event_id": "evt_20261021_9918",
"task_type": "batch_digest", // single_capture (单条) | batch_digest (多条合并)
"user_id": "admin_01",
"items": [
{
"item_id": "item_001",
"raw_text": "很多人把懒和不愿改变当长期主义...",
"source_url": "https://x.com/...",
"capture_time": "2026-10-21 14:10:00"
},
{
"item_id": "item_002",
"raw_text": "注意力才是真正不可再生的资产...",
"source_url": "",
"capture_time": "2026-10-21 18:20:00"
}
],
"context_hints": {
"preferred_booklet": "how-to-live-better",
"prompt_override": "提炼出统一的主题，整理为带金句对比的收纳简报"
}
}
```
### 5.2 n8n $\to$ FastAPI 结果回流契约
* **URL**: `POST https://{api_host}/api/v1/workflow/callback`
* **请求头**: `Authorization: Bearer {WORKFLOW_SYSTEM_TOKEN}`
* **Payload 结构**:
```json
{
"event_id": "evt_20261021_9918",
"user_id": "admin_01",
"status": "success",
"consumed_item_ids": ["item_001", "item_002"],
"data": {
"title": "2026-10-21 灵感收纳：关于长期主义与注意力",
"template": "booklet",
"target_dir": "00_Inbox/Drafts",
"filename": "2026-10-21-inspiration-digest.md",
"markdown_content": "---\nid: \"doc-20261021-batch01\"\ntitle: \"2026-10-21 灵感收纳：关于长期主义与注意力\"\ntemplate: \"booklet\"\nstatus: \"draft\"\nauthor: \"n8n_agent\"\ntags: [\"认知\", \"注意力\", \"每日简报\"]\n---\n\n### 今日灵感聚合...",
"inferred_backlinks": ["心智模型的建立"]
}
}
```
---
## 6. 双端多语言体系 (i18n 规范)
### 6.1 前端词条规范 (`vue-i18n@9`)
```json
// locales/zh-CN.json
{
"common": {
"save": "保存",
"cancel": "取消",
"confirm": "确认",
"theme_light": "明亮模式",
"theme_dark": "暗黑模式",
"theme_system": "跟随系统"
},
"inbox": {
"quick_capture": "极速捕获",
"captured_success": "已暂存后台",
"batch_merge": "合并为今日简报",
"select_items": "已选择 {count} 项碎片",
"confirm_archive": "确认入册"
},
"booklet": {
"chapters": "章节目录",
"backlinks": "反向链接",
"prev_section": "上一节",
"next_section": "下一节"
}
}
```
```json
// locales/en-US.json
{
"common": {
"save": "Save",
"cancel": "Cancel",
"confirm": "Confirm",
"theme_light": "Light",
"theme_dark": "Dark",
"theme_system": "System"
},
"inbox": {
"quick_capture": "Quick Capture",
"captured_success": "Saved in Background",
"batch_merge": "Merge into Daily Digest",
"select_items": "{count} fragments selected",
"confirm_archive": "Approve & Archive"
},
"booklet": {
"chapters": "Chapters",
"backlinks": "Linked Mentions",
"prev_section": "Previous",
"next_section": "Next"
}
}
```
---
## 7. 核心 API 接口清单
| 方法 | 路径 | 鉴权级别 | 业务说明 |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/public/booklets/{slug}` | 免登访客 | 获取公开专栏小册元数据及已发布的章节正文 |
| `GET` | `/api/v1/public/articles/{slug}` | 免登访客 | 获取公开单篇博客排版数据 |
| `POST`| `/api/v1/auth/login` | 公开 | 账号密码登录换取 JWT |
| `GET` | `/api/v1/notes/tree` | Member/Admin | 获取用户根目录层级（Inbox/Journal/Booklets/Articles/Extensions） |
| `GET` | `/api/v1/notes/doc` | Member/Admin | 读取指定 Markdown 正文、解析好的 Front-matter 及反链 |
| `POST`| `/api/v1/notes/doc` | Member/Admin | 原子保存 `.md` 文件并增量更新 SQLite 索引与双链关系 |
| `POST`| `/api/v1/inbox/capture` | Member/Admin | 客户端分享秒级投递入口，写入 Raw 队列 |
| `POST`| `/api/v1/inbox/batch-digest` | Member/Admin | 手动触发选中的多条 Raw 碎片合并为一份 Markdown 任务 |
| `POST`| `/api/v1/inbox/archive` | Member/Admin | 审阅确认：将 Draft 移动到指定 Booklets 或 Articles 目录 |
| `POST`| `/api/v1/workflow/callback` | 系统 Token | n8n 任务完成回传 Markdown 的回调接收端 |