feat(skills): 登记 Outline 样本组件卡 GH-KB-SAMPLE-001（知识库模块拆解 · 10张组件卡）

铸渊 2026-08-08 拆解 Outline v0.80.2 开源样本： - KB-COMP-001..010 覆盖编辑器/数据模型/搜索/文档树/版本历史/评论/附件/权限/Webhook/导入导出 - 光湖主控：不依赖 Outline 运行，不跟踪其更新，只吸收设计模式 - 依据 GLS-0230 源码安全净化协议：隔离→拆解→审计→组件化 - 落地优先级：数据模型 > 编辑器 > 导航 > 搜索 > 版本历史
2026-08-08 02:55:45 +08:00 · 2026-08-08 02:55:45 +08:00 · 070b11ac54
commit 070b11ac54
parent 058fd3ed15
1 changed files with 415 additions and 0 deletions
--- a/skills/guanghu-knowledge-ui/outline-sample-analysis/OUTLINE-SAMPLE-COMPONENT-CARDS-20260808.md
+++ b/skills/guanghu-knowledge-ui/outline-sample-analysis/OUTLINE-SAMPLE-COMPONENT-CARDS-20260808.md
@ -0,0 +1,415 @@
+# 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 · 光湖主控声明
+
+```
+⊢ Outline v0.80.2 是 BSL 1.1 开源许可，允许参考和学习
+⊢ 光湖不 import Outline 的任何 npm 包
+⊢ 光湖不依赖 Outline 运行
+⊢ 光湖不跟踪 Outline 的更新
+⊢ 光湖按自己的节奏和标准实现知识库模块
+⊢ 所有注册到灯塔的模块由光湖主控
+⊢ 本文档是样本学习记录，不是集成方案
+```
+
+---
+
+## 5 · 时间锚定
+
+```
+文档:    OUTLINE-SAMPLE-COMPONENT-CARDS · 知识库模块样本拆解
+版本:    v1.0
+创建:    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 签字