双层知识架构
知识库内容需要同时服务两个受众：AI（结构化检索与推理）和人（直觉理解与快速决策）。本文定义双层架构的设计原则与标准操作流程。
为什么需要双层
同一份知识，消费方式完全不同：
| 受众 | 诉求 | 最佳载体 |
|---|---|---|
| AI | 可检索、可引用、可推理 | 结构化 Markdown（.md） |
| 人 | 直观、逻辑清晰、秒懂 | 可视化展示页（.html） |
纯 Markdown 对 AI 友好，但人读起来信息密度低、理解慢。纯 HTML 展示页视觉冲击力强，但 AI 无法有效检索和复用。
因此：两层指向同一份知识，互相链接，缺一不可。
关键原则
HTML → Markdown 容易（提取内容即可），Markdown → HTML 难（无法还原视觉效果）。输入端优先提供 HTML，由知识管理员拆分为双层产出。
架构总览
输入：HTML 可视化展示页
│
▼
┌─────────────┐
│ 知识管理员 │
│ 拆分 & 归档 │
└──────┬──────┘
│
┌──────┴──────┐
▼ ▼
┌────────┐ ┌────────┐
│ 语义层 │ │ 展示层 │
│ .md │◄►│ .html │
└────────┘ └────────┘
docs/cases/ docs/public/
docs/playbook/ showcase/
docs/articles/语义层（Markdown）
| 属性 | 说明 |
|---|---|
| 存放位置 | docs/cases/、docs/playbook/、docs/articles/ |
| 格式要求 | 遵循各分类的标准模板（五维度案例、方法论结构等） |
| 作用 | AI 检索、知识关联、内容复用、sidebar 导航 |
| 访问方式 | VitePress 渲染，融入站点主题和搜索 |
展示层（HTML）
| 属性 | 说明 |
|---|---|
| 存放位置 | docs/public/showcase/ |
| 格式要求 | 纯 HTML + CSS + vanilla JS，不依赖 React/Vue |
| 作用 | 人快速理解、视觉化呈现、外部分享传播 |
| 访问方式 | /showcase/<filename>.html（VitePress public/ 原样托管） |
为什么不嵌入 Markdown
复杂交互页面（含 IntersectionObserver、滚动事件、CSS 动画等）与 VitePress 的 Vue 编译器冲突，必须放在 public/ 目录独立托管。
标准操作流程
Step 1：接收输入
| 来源格式 | 处理方式 |
|---|---|
| HTML | 直接使用，最理想输入 |
| JSX / React | 转为纯 HTML（去掉 React 依赖，改用 vanilla JS） |
| Markdown | 仅产出语义层，展示层按需补充 |
| 纯文本 | 仅产出语义层 |
Step 2：存放展示层
将 HTML 文件复制到展示目录：
docs/public/showcase/<slug>.html文件命名使用英文 kebab-case，与内容主题对应。
Step 3：提取语义层
从 HTML 中提取文本内容，按对应分类的模板结构化为 Markdown：
- 案例拆解 →
docs/cases/<slug>.md（五维度：产品概述 / 技术架构 / 商业模式 / 增长策略 / 关键启示） - 方法论 →
docs/playbook/<topic>.md（标题层级 + 表格 + 清单 + 容器语法） - 文章 →
docs/articles/<slug>.md（YAML frontmatter + 正文）
拆分原则
如果一份 HTML 同时包含产品分析和通用方法论，拆为两个 Markdown 文件分别归档。两个语义层页面都链接到同一个展示页。
Step 4：建立双向链接
在语义层 Markdown 页面顶部添加展示层入口：
markdown
> 📊 [查看可视化版本](/showcase/<slug>.html)Step 5：更新索引
- [ ]
config.mjs对应 sidebar 添加条目 - [ ] 对应分类
index.md添加卡片 - [ ] 确认构建通过（
npm run docs:build）
内容分流决策表
| 内容特征 | 语义层归属 | 示例 |
|---|---|---|
| 围绕某个产品的分析 | docs/cases/ | Gushwork 案例拆解 |
| 可复用的策略框架 | docs/playbook/ | AI 可见性方法论 |
| 观点或资讯类 | docs/articles/ | 行业趋势文章 |
| 知识库自身的管理规范 | docs/ops/ | 本文档 |
展示页导航（规划中）
当 docs/public/showcase/ 积累到 3-5 个展示页后：
- [ ] 建立展示页导航索引（卡片布局，含标题、分类、预览）
- [ ] 从顶部导航或首页提供入口
当前阶段通过语义层页面中的链接跳转即可。
实践案例
Gushwork — 首个双层入库
| 层 | 文件 | 线上路径 |
|---|---|---|
| 语义层 | docs/cases/gushwork.md | /cases/gushwork |
| 展示层 | docs/public/showcase/ai-b2b-revolution.html | /showcase/ai-b2b-revolution.html |
语义层页面顶部 📊 查看可视化版本 → 展示层，形成闭环。