hololake-system-architecture/skills/guanghu-knowledge-ui/outline-sample-analysis/OUTLINE-SAMPLE-COMPONENT-CARDS-20260808.md

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 · 富文本文档编辑器

组件名: 文档编辑器
样本来源: 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 · 文档数据模型

组件名: 文档数据模型
样本来源: 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 · 全文搜索引擎

组件名: 全文搜索
样本来源: 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 · 文档树与导航

组件名: 文档树导航
样本来源: 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 · 版本历史与回滚

组件名: 版本历史
样本来源: 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 · 评论与协作

组件名: 评论协作
样本来源: 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 · 文件附件与存储

组件名: 附件存储
样本来源: 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 · 权限与分享

组件名: 权限分享
样本来源: 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 与事件通知

组件名: 事件通知
样本来源: 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 导入导出

组件名: 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 签字