# 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 签字