冰朔
920b6bf690
冰朔 2026-08-08 架构决策：Git 是知识库模块的底层存储与版本引擎。 - Outline 用 PostgreSQL + Redis + ORM，光湖不需要 - Git commit = 版本历史，git diff = 版本对比，branch = 协作 - 不需要数据库、不需要缓存层、Markdown 文件即文档 - 与 HoloLake 代码频道天然同构
453 lines
17 KiB
Markdown
453 lines
17 KiB
Markdown
# Outline 样本组件卡 · 光湖知识库模块拆解
|
||
|
||
> 文档编号：`GH-KB-SAMPLE-001`
|
||
>
|
||
> 产品编号：`GH-AIOS-LIGHTHOUSE-020`
|
||
>
|
||
> 上位基线：`HLP-INTENT-REASONING-MAP-001`（意图二：频道DIY与跨行业搬模块）
|
||
>
|
||
> 来源：2026-08-08 铸渊（`ICE-P-ZY001`）拆解 Outline v0.80.2 开源样本
|
||
>
|
||
> 主权者：冰朔 `ICE-GL∞`
|
||
>
|
||
> 性质：样本学习 · 非运行时依赖 · 光湖主控
|
||
>
|
||
> 可见性：public-safe
|
||
|
||
---
|
||
|
||
## 0 · 本文档为什么存在
|
||
|
||
Outline v0.80.2（BSL 1.1 开源）运行在 BS-SG-001 新加坡大脑上，
|
||
其知识库 UI 组件质量高、功能全，值得光湖吸收。
|
||
|
||
**但光湖不是 Outline 的下游。** 本文档的职责是：
|
||
|
||
- 把 Outline 拆成独立的组件卡，每张卡记录"它做了什么、怎么做的、光湖可以吸收什么"
|
||
- 光湖按自己的模块标准重新实现，不 import Outline 的任何包
|
||
- Outline 只是参考样本，更新节奏完全由光湖决定
|
||
|
||
⊢ 依据：`GLS-0230`（源码安全净化协议）——外部代码进入光湖前先隔离、拆解、审计、组件化。
|
||
|
||
---
|
||
|
||
## 1 · Outline 整体架构速览
|
||
|
||
```
|
||
Outline v0.80.2
|
||
├── 前端：React + ProseMirror 编辑器 + Hocuspocus 实时协作
|
||
├── 后端：Node.js + Koa + Sequelize ORM
|
||
├── 数据库：PostgreSQL 16
|
||
├── 缓存：Redis 7
|
||
├── 认证：Dex OIDC / Google / GitHub / Slack / Azure / Email
|
||
├── 存储：本地文件 / S3 可选
|
||
├── 协作：Y.js + Hocuspocus WebSocket
|
||
└── 插件：Slack / Webhooks / Google Analytics / Umami / Matomo / Iframely
|
||
```
|
||
|
||
### 核心依赖（200个 npm 包，以下为知识库相关）
|
||
|
||
| 包名 | 用途 | 光湖吸收策略 |
|
||
|------|------|------------|
|
||
| `prosemirror-*` 系列 | 富文本编辑器引擎 | 吸收编辑模式，自实现编辑器 |
|
||
| `@hocuspocus/server` + `provider` | 实时协作（Y.js） | 吸收协作协议，自实现同步层 |
|
||
| `@dnd-kit/*` | 拖拽排序 | 吸收交互模式 |
|
||
| `turndown` + `@joplin/turndown-plugin-gfm` | HTML→Markdown | 吸收转换逻辑 |
|
||
| `sequelize` | ORM | 参考数据模型设计 |
|
||
|
||
---
|
||
|
||
## 2 · 组件卡清单
|
||
|
||
### KB-COMP-001 · 富文本文档编辑器
|
||
|
||
```yaml
|
||
组件名: 文档编辑器
|
||
样本来源: Outline server/editor/ + 前端 ProseMirror 组件
|
||
Outline 实现:
|
||
引擎: ProseMirror（模块化富文本编辑框架）
|
||
数学公式: @benrbray/prosemirror-math
|
||
协同: @getoutline/y-prosemirror + Hocuspocus
|
||
特性:
|
||
- Markdown 原生支持（写 Markdown 自动渲染）
|
||
- 斜杠命令（/command 快速插入）
|
||
- 交互式嵌入（嵌入其他文档/外部内容）
|
||
- 表格编辑
|
||
- 代码块（语法高亮）
|
||
- 任务列表 / 待办清单
|
||
- 图片拖拽上传
|
||
- @提及用户
|
||
- 文档内链接
|
||
光湖吸收要点:
|
||
- ProseMirror 的模块化编辑思路值得参考（编辑器=插件组合）
|
||
- Markdown 输入→实时渲染的交互模式是知识库刚需
|
||
- 斜杠命令是知识库高效操作的核心 UX
|
||
- 协同编辑用 CRDT（Y.js）是成熟方案
|
||
光湖自实现方向:
|
||
- 编辑器组件化为可热插拔插件
|
||
- Markdown 解析与渲染分离（HLDP 友好）
|
||
- 协同层走 HoloLake 频道协议，不走第三方 WebSocket
|
||
吸收优先级: ⭐⭐⭐⭐⭐（知识库核心组件）
|
||
```
|
||
|
||
### KB-COMP-002 · 文档数据模型
|
||
|
||
```yaml
|
||
组件名: 文档数据模型
|
||
样本来源: Outline server/models/
|
||
Outline 实现:
|
||
核心模型:
|
||
Document:
|
||
字段: id, title, text, emoji, collectionId, parentDocumentId,
|
||
createdById, publishedAt, archivedAt, deletedAt,
|
||
templateId, template, fullWidth, collaboratorIds
|
||
关系: 属于 Collection, 可嵌套（parentDocumentId 自引用）
|
||
特性: 软删除, 模板支持, 全文索引
|
||
Collection:
|
||
字段: id, name, description, color, icon, type, permission,
|
||
sort, sharing, index
|
||
关系: 包含多个 Document, 支持权限控制
|
||
特性: 集合=知识库分区, 支持公开/私密/团队可见
|
||
Revision:
|
||
字段: id, documentId, title, text, createdById
|
||
特性: 每次编辑自动快照, 可回滚到任意版本
|
||
Comment:
|
||
字段: id, documentId, parentCommentId, createdById, body
|
||
特性: 评论可嵌套（回复链）, 锚定到文档段落
|
||
Attachment:
|
||
字段: id, documentId, teamId, userId, key, url, size, type
|
||
特性: 文件上传, 支持 S3/本地存储
|
||
Share:
|
||
字段: id, documentId/collectionId, userId, teamId, published
|
||
特性: 文档/集合级公开分享链接
|
||
Star / Pin / View:
|
||
特性: 收藏/置顶/浏览记录, 辅助导航
|
||
光湖吸收要点:
|
||
- Document + Collection 的二层结构清晰（集合→文档→子文档）
|
||
- Revision 自动快照是版本历史的工程基线
|
||
- Comment 锚定到段落（不是页面级评论）是高质量协作 UX
|
||
- 软删除 + 回收站是知识库安全基线
|
||
光湖自实现方向:
|
||
- 数据模型走 HLDP 树形结构（与 HoloLake 原生兼容）
|
||
- Document 对应 HoloLake 的"文档模块"，Collection 对应"知识库频道"
|
||
- Revision 与 HLDP 的历史寻址系统合并设计
|
||
吸收优先级: ⭐⭐⭐⭐⭐（所有知识库功能的地基）
|
||
```
|
||
|
||
### KB-COMP-003 · 全文搜索引擎
|
||
|
||
```yaml
|
||
组件名: 全文搜索
|
||
样本来源: Outline server/routes/api/searches/ + models/SearchQuery
|
||
Outline 实现:
|
||
引擎: PostgreSQL 全文索引（tsvector + tsquery）
|
||
API:
|
||
POST /api/documents.search
|
||
参数: query, collectionId, userId, dateFilter, statusFilter
|
||
返回: 匹配文档列表 + 高亮片段 + 相关度评分
|
||
特性:
|
||
- 标题 + 正文联合搜索
|
||
- 按集合/用户/日期/状态过滤
|
||
- 搜索结果高亮（匹配词前后上下文）
|
||
- 搜索历史记录（SearchQuery 模型）
|
||
- 拼音/部分匹配支持
|
||
光湖吸收要点:
|
||
- PG 全文索引够用于中等规模知识库（百万级文档）
|
||
- 搜索 API 的过滤维度设计完整
|
||
- 搜索历史记录可以做"最近搜索"和"热门搜索"
|
||
光湖自实现方向:
|
||
- 搜索接口走 HoloLake 模块协议（统一搜索入口）
|
||
- 可扩展到向量搜索（嵌入模型 + pgvector）做语义搜索
|
||
- 搜索结果投影为光湖 UI 格式（不是 Outline 的列表样式）
|
||
吸收优先级: ⭐⭐⭐⭐（知识库核心能力）
|
||
```
|
||
|
||
### KB-COMP-004 · 文档树与导航
|
||
|
||
```yaml
|
||
组件名: 文档树导航
|
||
样本来源: Outline 前端 sidebar + 拖拽排序
|
||
Outline 实现:
|
||
结构: Collection → Document → 子 Document（无限嵌套）
|
||
UI 特性:
|
||
- 左侧边栏文档树（可折叠/展开）
|
||
- 拖拽排序（@dnd-kit/core + sortable）
|
||
- 拖拽移动文档（跨集合/跨层级）
|
||
- emoji 图标前缀
|
||
- 拖拽创建子文档
|
||
- 自动缩进显示层级
|
||
后端:
|
||
- Document.parentDocumentId 自引用形成树
|
||
- Collection.sort 控制集合内排序
|
||
- 移动文档只更新 parentDocumentId + index
|
||
光湖吸收要点:
|
||
- 拖拽排序 + 无限嵌套是知识库导航标配
|
||
- emoji 前缀提升视觉辨识度
|
||
- 移动文档只改指针不动内容（轻量操作）
|
||
光湖自实现方向:
|
||
- 文档树走 HoloLake 频道树形结构
|
||
- 导航组件可独立挂载（不依赖编辑器）
|
||
- 拖拽交互参考 @dnd-kit 模式但自实现
|
||
吸收优先级: ⭐⭐⭐⭐（知识库导航核心）
|
||
```
|
||
|
||
### KB-COMP-005 · 版本历史与回滚
|
||
|
||
```yaml
|
||
组件名: 版本历史
|
||
样本来源: Outline server/models/Revision + routes/api/revisions/
|
||
Outline 实现:
|
||
模型: Revision（每次编辑保存自动创建快照）
|
||
API:
|
||
POST /api/revisions.list → 列出某文档的所有版本
|
||
POST /api/revisions.info → 查看某版本详情
|
||
POST /api/documents.restore → 回滚到指定版本
|
||
特性:
|
||
- 每次保存自动生成版本快照（标题+正文完整副本）
|
||
- 版本列表显示：谁改的、什么时候改的
|
||
- 一键回滚到任意历史版本
|
||
- 版本对比（diff）
|
||
- 版本不影响当前文档（只读快照）
|
||
光湖吸收要点:
|
||
- "每次保存=一次快照"是简单可靠的版本策略
|
||
- 快照存完整副本（不是增量 diff），回滚简单直接
|
||
- 版本元数据（谁/何时/改了什么）是审计基线
|
||
光湖自实现方向:
|
||
- 与 HLDP 持久记忆系统对齐（Revision ≈ HLDP 检查点）
|
||
- 版本数据可走 Git 存储（与 HoloLake 代码频道天然兼容）
|
||
- 回滚走工单授权（不是无限制回滚）
|
||
吸收优先级: ⭐⭐⭐⭐（知识库安全基线）
|
||
```
|
||
|
||
### KB-COMP-006 · 评论与协作
|
||
|
||
```yaml
|
||
组件名: 评论协作
|
||
样本来源: Outline server/models/Comment + routes/api/comments/
|
||
Outline 实现:
|
||
模型: Comment（可嵌套回复）
|
||
API:
|
||
POST /api/comments.create → 创建评论
|
||
POST /api/comments.list → 列出文档评论
|
||
POST /api/comments.update → 编辑评论
|
||
POST /api/comments.delete → 删除评论
|
||
特性:
|
||
- 评论锚定到文档段落（不是页面级）
|
||
- 回复链（parentCommentId 嵌套）
|
||
- @提及触发通知
|
||
- 评论解决/未解决状态
|
||
光湖吸收要点:
|
||
- 段落级评论比页面级评论精确得多
|
||
- 回复链让讨论有上下文
|
||
- "解决"状态适合团队协作审阅
|
||
光湖自实现方向:
|
||
- 评论走 HoloLake 频道内的协作协议
|
||
- 评论数据与文档数据分离存储（模块独立性）
|
||
- 通知走 HoloLake 统一通知系统
|
||
吸收优先级: ⭐⭐⭐（协作增强，非核心必需）
|
||
```
|
||
|
||
### KB-COMP-007 · 文件附件与存储
|
||
|
||
```yaml
|
||
组件名: 附件存储
|
||
样本来源: Outline server/storage/ + models/Attachment + commands/attachmentCreator
|
||
Outline 实现:
|
||
存储后端:
|
||
- 本地文件存储（server/storage/files/）
|
||
- S3 兼容存储（@aws-sdk/client-s3）
|
||
- 可配置切换（FILE_STORAGE 环境变量）
|
||
特性:
|
||
- 拖拽上传到文档
|
||
- 图片自动内联显示
|
||
- 文件大小限制
|
||
- 预签名 URL（S3 安全访问）
|
||
- 附件与文档/团队绑定
|
||
光湖吸收要点:
|
||
- 存储后端可插拔（本地/S3/其他）是好设计
|
||
- 预签名 URL 避免直接暴露存储地址
|
||
- 附件元数据（大小/类型/归属）必须记录
|
||
光湖自实现方向:
|
||
- 存储层走 HoloLake 文件存储协议
|
||
- 附件与 HoloLake 资产系统对齐（资产锁定含参数）
|
||
- 文件存 JZAO 移动硬盘或光湖自有存储节点
|
||
吸收优先级: ⭐⭐⭐（知识库必需但优先级低于编辑器）
|
||
```
|
||
|
||
### KB-COMP-008 · 权限与分享
|
||
|
||
```yaml
|
||
组件名: 权限分享
|
||
样本来源: Outline server/policies/ + models/Share + routes/api/shares/
|
||
Outline 实现:
|
||
权限模型:
|
||
- Collection 级：公开/私密/团队可见
|
||
- Document 级：继承集合权限 + 单独分享
|
||
- Share：生成公开链接（可设密码/过期）
|
||
- Group/GroupMembership：用户分组管理
|
||
特性:
|
||
- 精细权限（只读/读写/管理）
|
||
- 公开分享链接（可选密码保护）
|
||
- 团队级/集合级/文档级三层权限
|
||
- API Key 支持（程序化访问）
|
||
光湖吸收要点:
|
||
- 三层权限（团队→集合→文档）是标准模式
|
||
- 公开分享链接是知识库对外输出的刚需
|
||
- API Key 让程序化接入成为可能
|
||
光湖自实现方向:
|
||
- 权限走 HoloLake 灯塔授权体系（GLSV）
|
||
- 分享链接走光湖域名（不是 Outline 的链接）
|
||
- API Key 与 HoloLake 能力令牌对齐
|
||
吸收优先级: ⭐⭐⭐（安全基线，但可后续迭代）
|
||
```
|
||
|
||
### KB-COMP-009 · Webhook 与事件通知
|
||
|
||
```yaml
|
||
组件名: 事件通知
|
||
样本来源: Outline server/models/WebhookSubscription + WebhookDelivery
|
||
Outline 实现:
|
||
模型:
|
||
WebhookSubscription: 注册监听（URL + 事件类型 + 密钥）
|
||
WebhookDelivery: 投递记录（状态码 + 响应 + 重试）
|
||
支持事件:
|
||
- documents.create / update / delete / publish / archive
|
||
- collections.create / update / delete
|
||
- users.create / update / delete
|
||
- revisions.create
|
||
- comments.create / update
|
||
- groups.* / integrations.*
|
||
特性:
|
||
- 签名验证（HMAC-SHA256）
|
||
- 自动重试失败投递
|
||
- 投递历史记录
|
||
光湖吸收要点:
|
||
- Webhook 是知识库与其他系统联动的桥梁
|
||
- 签名验证防篡改
|
||
- 投递记录可审计
|
||
光湖自实现方向:
|
||
- 事件系统走 HoloLake 频道事件协议
|
||
- Webhook 与 HoloLake 广播塔对齐
|
||
- 事件类型与 HLDP 四字段（trigger/emergence/lock/why）对齐
|
||
吸收优先级: ⭐⭐（集成能力，后期迭代）
|
||
```
|
||
|
||
### KB-COMP-010 · Markdown 导入导出
|
||
|
||
```yaml
|
||
组件名: Markdown 导入导出
|
||
样本来源: Outline server/commands/documentImporter + collectionExporter
|
||
Outline 实现:
|
||
导入:
|
||
- Markdown (.md) → Outline 文档
|
||
- HTML → Outline 文档（turndown 转换）
|
||
- 批量导入（zip 包）
|
||
- 保留图片/附件引用
|
||
导出:
|
||
- 文档 → Markdown
|
||
- 集合 → zip 包（含所有文档 + 图片 + 附件）
|
||
- HTML 导出
|
||
转换引擎:
|
||
- turndown: HTML → Markdown
|
||
- @joplin/turndown-plugin-gfm: GFM 扩展支持
|
||
光湖吸收要点:
|
||
- Markdown 是知识库通用交换格式
|
||
- HTML↔Markdown 双向转换是必需能力
|
||
- 批量导入导出是知识库迁移的刚需
|
||
光湖自实现方向:
|
||
- 导入导出与 HLDP 格式对齐（Markdown ↔ HLDP 双向）
|
||
- 批量操作走 HoloLake 工单系统（有授权、有回执）
|
||
- 图片/附件引用走光湖资产系统
|
||
吸收优先级: ⭐⭐⭐（知识库互操作性）
|
||
```
|
||
|
||
---
|
||
|
||
## 3 · 组件优先级与落地顺序
|
||
|
||
| 顺序 | 组件卡 | 优先级 | 理由 |
|
||
|:---:|--------|:---:|------|
|
||
| 1 | KB-COMP-002 文档数据模型 | ⭐⭐⭐⭐⭐ | 所有功能的地基，先定义数据结构 |
|
||
| 2 | KB-COMP-001 富文本编辑器 | ⭐⭐⭐⭐⭐ | 知识库核心交互，人类每天面对 |
|
||
| 3 | KB-COMP-004 文档树导航 | ⭐⭐⭐⭐ | 没有导航=没有知识库 |
|
||
| 4 | KB-COMP-003 全文搜索 | ⭐⭐⭐⭐ | 找不到=不存在 |
|
||
| 5 | KB-COMP-005 版本历史 | ⭐⭐⭐⭐ | 安全基线，不可逆操作必须有后悔药 |
|
||
| 6 | KB-COMP-010 导入导出 | ⭐⭐⭐ | 从现有系统迁移过来 |
|
||
| 7 | KB-COMP-007 附件存储 | ⭐⭐⭐ | 图片/文件上传 |
|
||
| 8 | KB-COMP-006 评论协作 | ⭐⭐⭐ | 团队协作增强 |
|
||
| 9 | KB-COMP-008 权限分享 | ⭐⭐⭐ | 安全基线但可迭代 |
|
||
| 10 | KB-COMP-009 Webhook | ⭐⭐ | 集成能力，后期 |
|
||
|
||
---
|
||
|
||
## 4 · 架构决策：Git 是知识库的底层引擎
|
||
|
||
> 冰朔 2026-08-08 原话："git要能做这些模块的底层引擎，因为它轻量也不占地方"
|
||
|
||
```
|
||
Outline 的存储方案 光湖的存储方案
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
PostgreSQL（数据库） Git 仓库（文件系统 + 版本控制）
|
||
Redis（缓存） 不需要（Git 本地操作极快）
|
||
Sequelize ORM 不需要（Markdown 文件 + Git API）
|
||
S3 / 本地文件存储 Git LFS 或 Git 原生（附件另走资产系统）
|
||
```
|
||
|
||
Git 原生能力 → 知识库需求映射：
|
||
|
||
| Git 能力 | 知识库需求 | 对应组件卡 |
|
||
|---|---|---|
|
||
| commit 历史 | 版本历史 / 谁改了什么 / 何时改的 | KB-COMP-005 |
|
||
| git diff | 版本对比 / 变更高亮 | KB-COMP-005 |
|
||
| branch / merge | 草稿分支 / 审阅合并 / 发布 | KB-COMP-001/006 |
|
||
| git log --author | 按人过滤变更 | KB-COMP-002 |
|
||
| 目录结构 | 文档树 / 集合层级 | KB-COMP-004 |
|
||
| Markdown 文件 | 文档原生格式 / 导入导出 | KB-COMP-010 |
|
||
| 分布式 clone | 每个频道本地有完整副本 | 全局 |
|
||
| .git / HEAD | 轻量元数据 / 不占地方 | 全局 |
|
||
| tag / release | 里程碑版本 / 正式发布 | KB-COMP-005 |
|
||
| git grep | 全文搜索基础 | KB-COMP-003 |
|
||
|
||
⊢ 知识库文档 = Markdown 文件存在 Git 仓库里
|
||
⊢ 版本历史 = Git commit 历史（免费获得，不用自己实现）
|
||
⊢ 协作 = Git branch + merge（天然多人协作）
|
||
⊢ 搜索 = git grep + 可选全文索引层
|
||
⊢ 不需要数据库 · 不需要 Redis · 不需要 ORM
|
||
⊢ 与 HoloLake 代码频道天然同构（代码和文档走同一条路）
|
||
|
||
---
|
||
|
||
## 5 · 光湖主控声明（含架构决策）
|
||
|
||
```
|
||
⊢ Outline v0.80.2 是 BSL 1.1 开源许可，允许参考和学习
|
||
⊢ 光湖不 import Outline 的任何 npm 包
|
||
⊢ 光湖不依赖 Outline 运行
|
||
⊢ 光湖不跟踪 Outline 的更新
|
||
⊢ 光湖按自己的节奏和标准实现知识库模块
|
||
⊢ 所有注册到灯塔的模块由光湖主控
|
||
⊢ Git 是知识库模块的底层存储与版本引擎
|
||
⊢ 本文档是样本学习记录，不是集成方案
|
||
```
|
||
|
||
---
|
||
|
||
## 6 · 时间锚定
|
||
|
||
```
|
||
文档: OUTLINE-SAMPLE-COMPONENT-CARDS · 知识库模块样本拆解
|
||
版本: v1.1（增补 §4 Git 引擎架构决策）
|
||
创建: 2026-08-08 · 铸渊 ICE-P-ZY001
|
||
主权者: 冰朔 ICE-GL∞
|
||
样本源: Outline v0.80.2 · BS-SG-001 新加坡大脑
|
||
组件数: 10 张组件卡
|
||
平台: TCS 通感语言核系统（国作登字-2026-A-00037559）
|
||
```
|
||
|
||
---
|
||
|
||
> ⊢ 拆解样本 · 吸收精华 · 光湖主控 · 不做下游
|
||
> ⊢ 10 张组件卡 · 知识库全功能覆盖 · 按优先级落地
|
||
> ⊢ 语言等于现实 · 语言不可撤销
|
||
|
||
铸渊 `ICE-P-ZY001` · 2026-08-08 · 组件卡 v1.0 签字
|