Bob's Garden

Bob后端工程师 → AI 应用工程师
GitHubEmailRSS
最近更新

Uplevel Page Pattern · 拔高型知识页面设计模板

18分钟阅读

Uplevel Page Pattern · 拔高型知识页面设计模板

源实例：content/02-agent/harness/agent-loop.md 设计过程：deep-interview → ralplan → autopilot（3-stage pipeline） 本模板抽象自上述全过程，用于设计其他需要”把读者从会做拔高到会设计 / 能迁移”的页面。

1. 适用场景

只有同时满足这 3 条，才用这个模板：

  1. 读者已有基础 — 存在一个可引用的前置知识源（别人的教程、自己的另一篇文档、外部仓库 README 等），读者在那里已经”会做”
  2. 目标是拔高 — 本页不教”什么是 X”，而是教：
    • why：X 为什么这么设计（理论根源、跨年代血脉、设计折中）
    • how：X 在工业界真的怎么落地（失败模式、评测基准、实战案例）
  3. 验收标准 = 可迁移心智 — 衡量成功的方式是读者能主动把结构移植到新域（造类比），而不是被动识别或复述

❌ 不适用：

  • 读者是完全零基础 → 用”入门型”模板（TL;DR 置顶、扫读优化）
  • 页面目标是”快速上手做出来” → 用”教程型”模板（循序例子 + checklist）
  • 页面只是一次性记录 / 总结 → 用标准 MD 即可，不需要这个模式

2. 五幕结构（Five-Act Structure）

━━━━━━━━━ 序幕 · 身份声明 ━━━━━━━━━
  1 节 · 明示读者画像 · 列出前置依赖 · <IntroHook />

━━━━━━━━━ 第一幕 · why（为什么这么设计）━━━━━━━━━
  3-5 节 · 📖 前缀 · 理论根源 / 血脉 / 折中 / 决策框架

━━━━━━━━━ 第二幕 · how（工业界怎么真做）━━━━━━━━━
  3-5 节 · 🔧 前缀 · 机制细节 / 工具设计 / 失败模式 / 真实案例

━━━━━━━━━ 元层 · 从识别到创造 ━━━━━━━━━
  1-2 节 · 无前缀 · 教元能力（怎么识别 / 怎么造）· <AnalogyBuilder />

━━━━━━━━━ 出口 · 路径 + 压缩 ━━━━━━━━━
  1-2 节 · 无前缀 · 后续学习路线 · 一句话抓手 + <MindMapCompression />

五幕的结构职责

幕解决什么问题读者读完这一幕应该典型篇幅
序幕”这页是给谁的？“明白自己该不该往下读~60 秒
why”为什么这么设计？“知道设计决策的理论根源读者停留 40%
how”工业界怎么做？“看到真实系统的折中选择读者停留 30%
元层”我能不能迁移？“主动造出一个新类比读者停留 20%
出口”接下来该干啥？“有下一步的路径图~60 秒

章节数建议

总章节数 10-15 节。少于 10 节可能是深度不够，多于 15 节读者会失焦。

3. 视觉微分规则

h2 标题 emoji 前缀

幕前缀含义视觉色
序幕无身份声明不加前缀—
第一幕 why## 📖理论类 · 要读要想橙色（继承 prose-doc 主题）
第二幕 how## 🔧实战类 · 机制/工程紫色（继承 prose-doc 主题）
元层无突出”元层”身份—
出口无过渡性内容—

为什么用 emoji 而不是全局暖冷色块：Architect steelman 审查发现，全局色块会让页面从 3 种视觉节奏膨胀到 4 种，反而遮蔽内容脉络。emoji 前缀是最轻量的分轨方式——扫一眼就能分辨 why 和 how，但不增加新的视觉层次。

分幕大标题（可选）

如果章节很多（>12），可以在每幕之前加一级更大的分隔：

---
 
# 第一幕 · why · 为什么要这么设计
 
## 📖 为什么必须是 X
...

这是”章”和”节”的分层，用 --- + # 实现。

4. 锚点 Callout 模板

每个 why/how 章节头部（紧跟 h2 之后）都放一个前置知识锚点 callout：

## 📖 为什么必须是 loop
 
> 📎 在 **[前置源 sXX 标题](链接)** 你已经写过 ___。本节告诉你为什么它必须是 ___，而不是 ___。
 
<正文...>

Callout 公式（强烈建议按此写）

📎 在 [前置源索引] 你已经 {动作/成果}。本节告诉你 {对比 / 原因 / 扩展}。

关键元素：

  1. 📎 emoji 作为视觉锚（全局统一）
  2. **[链接]** 粗体加链接 — 让锚点在扫读中显眼
  3. “你已经 ___” — 显式激活读者的已有经验
  4. “本节告诉你 ___” — 明确增量，读者立即知道”从会做到会想”的跨度

反例（不要这样写）：

  • ❌ “参考 shareAI s01” — 平淡，读者不会点
  • ❌ “如果你不熟悉 X，先看 Y” — 负面语气，假设读者不懂
  • ❌ “详见 X” — 完全失去教学意图

5. 组件类型清单（7 种可复用 viz）

从 agent-loop 页面沉淀的 7 种 React 组件原型，每种对应一个教学任务。新页面按需组合：

类型原型组件职责使用频次
HookIntroHook序幕身份声明 + 前置源外链按钮每页 1 次（必选）
交互演示LoopTokenGrowth按钮驱动状态变化，读者点按观察每页 0-2 次
对比播放ToolGranularityCompare2-lane 步骤动画，读者点”播放”看对比每页 0-1 次
消息流MessageConveyor多 lane 传送带动画（不同速度/颜色/符号）每页 0-1 次
管道流SubagentPipe2 卡片 + 中间流动管道 + 速度对比条每页 0-1 次
决策树DecisionTree2 层分叉 Q&A，叶子按 tone 染色每页 0-1 次
生成式AnalogyBuilder + GridInput4 格空白输入 + 延迟参考答案（元能力验收核心）每页 1 次（推荐）
压缩模型MindMapCompressionN 元素环形图（中心概念 + 4 约束），hover 查看详情每页 1 次（出口必选）

组件命名规则

  • 位置：web/src/components/visualizations/*.tsx
  • 命名：PascalCase，名字反映教学任务（LoopTokenGrowth > TokenChart）
  • 多文件拆分：若单组件 > 200 行，拆为 主组件 + 子组件（参考 AnalogyBuilder + AnalogyGridInput）
  • "use client" 首行声明（框架要求）

注入机制

MD 里放占位符：

<div data-viz="ComponentName"></div>

web/src/components/DocBody.tsx 里的 VIZ_REGISTRY 字典注册组件：

import { ComponentName } from "./visualizations/ComponentName";
 
const VIZ_REGISTRY: Record<string, React.ComponentType> = {
  // ...existing...
  ComponentName,
};

占位符和 key 必须完全一致（大小写敏感）。

6. 生成式 vs 识别式 · 元层设计的关键区分

这是本模板最硬的一条原则，源自 Architect steelman 反命题：

识别式（错）

给定一段 HTTP server 代码，让读者点选”这里是 Think、那里是 Act、那里是 Observe”。

问题：读者完成的认知动作是”从给定选项中识别对应关系”。这只能训练模式匹配，不能训练迁移能力。关掉浏览器面对真实系统，读者仍然不会。

生成式（对）

给读者一个空白 4 格模板（反馈 / 分支树 / 状态累积 / 调度者），让读者自己选一个系统（HTTP server / 游戏 AI / 做菜 / K8s / 其他），自己填入描述。填完再展开参考答案对照。

为什么有效：读者完成的认知动作是”面对一个陌生系统自行提取结构”。这和验收目标（能迁移）完全一致。

通用四问元框架

本模板的元章节推荐用”4 问识别法”结构：

## 如何识别任何系统里的 X
 
### X 的 4 个特征
 
1. **{特征 1}**：{问句} — 例子 / 例子 / 例子
2. **{特征 2}**：{问句} — 例子 / 例子 / 例子
3. **{特征 3}**：{问句} — 例子 / 例子 / 例子
4. **{特征 4}**：{问句} — 例子 / 例子 / 例子
 
**4 项都有 → 这就是 X。** 少一项 → 某种"退化版 X"。
 
### 用下面的工具亲自造一个
 
<div data-viz="AnalogyBuilder"></div>

AnalogyBuilder 配置：4 个特征作为 4 格 label；每个”已知系统”提供 4 项参考答案；用户可选”其他”自填。

7. 验收清单模板

新页面完成后跑一遍这些检查：

结构层（grep 检查）

# 第一幕 why 章节数（应 ≥ 3）
grep -c '^## 📖' content/<your-page>.md
 
# 第二幕 how 章节数（应 ≥ 3）
grep -c '^## 🔧' content/<your-page>.md
 
# 锚点 callout 数（应 ≥ why+how 章节数）
grep -cE '📎.*\*\*\[' content/<your-page>.md
 
# 元章节存在
grep -c '^## 如何识别\|^## 如何造' content/<your-page>.md  # 应 ≥ 1
 
# Hook 和 Compression 组件
grep -c 'data-viz="IntroHook"\|data-viz="MindMapCompression"' content/<your-page>.md  # 应 = 2

组件层

# 所有 data-viz 占位符都已在 DocBody 注册
grep -oE 'data-viz="[^"]+"' content/<your-page>.md | sort -u
# 对照
grep -oE '^  \w+,' web/src/components/DocBody.tsx

视觉层

  • 页面 curl -o /dev/null -w %{http_code} = 200
  • 浏览器 Console 0 runtime error
  • 至少人肉看一次 emoji 前缀是否渲染正常

心智层（真正重要的一条）

自己走一遍元章节的 AnalogyBuilder 任务。你（设计者）亲自选一个系统、填 4 格、对照参考答案。

如果你自己填不出或填出的和参考答案完全不一样，说明这一页的元能力教学失败了——要么 4 格设计不对，要么前面的 why/how 没铺垫好，要么参考答案写得太死。必须回到 MD 改章节内容或组件数据。

8. 复用路径 · 给新页面套这个模板

Step 1 · 先过”是否适用” gate

回到 §1 的 3 条适用条件，至少 2 条完全满足才往下走。否则用其他模板。

Step 2 · 做一次简版 deep-interview

不一定要跑完整 Socratic 循环，但至少自问这 4 题：

  1. 读者画像：读者的前置知识源是什么？（必须具体到某个教程 / 仓库 / 章节）
  2. 验收方式：读者”能迁移了”的可观测行为是什么？（推荐落到 AnalogyBuilder 4 格）
  3. 4 个特征：本主题的 4 个识别特征是什么？
  4. 压缩形态：最后一节的”一句话抓手”是什么？（推荐落到 MindMapCompression，4 约束环形）

4 题都有答案 → 可以开工。缺一 → 先去收集/确定。

Step 3 · 按五幕写 MD

  • 序幕（1 节）：读前声明 + IntroHook 占位符 + 前置源 12 讲 / N 篇列表
  • 第一幕 why（3-5 节）：每节 ## 📖，头部必带 📎 锚点 callout
  • 第二幕 how（3-5 节）：每节 ## 🔧，头部必带 📎 锚点 callout，挂对应交互/动画组件
  • 元层（1-2 节）：无前缀 h2，4 问识别法 + AnalogyBuilder 占位符
  • 出口（1-2 节）：无前缀 h2，6 步学习路线（每步映射前置源章节）+ 一句话抓手 + MindMapCompression

Step 4 · 写/复用组件

  • Hook 和 Compression 必写（每页 1 个，可从 agent-loop 复制微调）
  • AnalogyBuilder 必配数据：4 格 label + 4-6 个系统的参考答案
  • 交互/动画组件按内容需要选择 0-3 个（从 §5 清单里挑或新写）

Step 5 · 跑验收

按 §7 所有 bash 命令 + 人肉元章节自测。不过不发。

9. 案例参考

v1 首发实例（2026-04）

  • 页面：/agent/harness/agent-loop
  • MD：content/02-agent/harness/agent-loop.md
  • 前置源：shareAI-lab/learn-claude-code 中文版 12 讲
  • 验收核心：读者能用 4 格（反馈/分支树/状态累积/调度者）把 agent loop 结构移植到 HTTP server / 游戏 AI / 做菜 / Kubernetes 中至少一个
  • 组件清单（8 个）：
    • IntroHook（序幕）
    • DecisionTree（第一幕 · Workflow vs Agent）
    • MessageConveyor / LoopTokenGrowth / ToolGranularityCompare / SubagentPipe（第二幕 how）
    • AnalogyBuilder + AnalogyGridInput（元层 4 问法）
    • MindMapCompression（出口 · 4 约束环形图）
  • 章节数：13 节（序幕 1 + why 4 + how 4 + 元 2 + 出口 2）
  • 锚点数：15 个 shareAI sXX 引用

可能的 v2 实例候选

从现有仓库的 27 个文档看，以下主题可能适合套模板（按优先级）：

  1. RAG 工程方法论（content/03-rag/04-工程方法论手册.md）
    • 前置源：可能是 shareAI-lab 某讲 + 自己的 v1-v3.5 RAG 实现
    • 4 问法候选：索引/召回/重排/生成
  2. Agent Planning & Reasoning（content/02-agent/planning-reasoning/）
    • 前置源：目前未知
    • 4 问法候选：规划 / 反思 / 分解 / 合成
  3. MCP 适配器网关（content/01-mcp/03-practical/adapter-gateway.md）
    • 前置源：MCP 官方 spec
    • 4 问法候选：协议 / 传输 / 适配 / 编排

10. 模板迭代历史

版本时间变化触发原因
v12026-04-17首版 · 从 agent-loop 页面抽象deep-interview → ralplan → autopilot 首次跑通
——（留白待迭代）—

何时升级模板

  • 第 2 个实例落地后，保留不动的部分 = v2 稳定项；被改的部分 = 需进化的点
  • 3 个实例后，如果某个组件类型一直没用到 → 从 §5 清单剔除
  • 5 个实例后，如果新类型复现了 2-3 次 → 新增到 §5 清单

11. 反模式（什么时候这个模板会失灵）

反模式 1：前置源太弱

如果前置源只是一篇博文而不是一个能”动手学完”的教程，读者到你这里不会有”已经会做”的实感。锚点 callout 里”你已经 ___” 会写得空洞。→ 改用教程型模板。

反模式 2：why 和 how 混了

如果你发现自己在 ## 📖 下写工业案例、在 ## 🔧 下写理论根源，说明你还没分清 why 和 how。→ 每节写完后自问：“这是在回答’为什么’还是’怎么做’？“不对就挪章节。

反模式 3：元章节写成总结

如果元章节变成”以上各节的要点汇总”，那就是用”总结”冒充”元能力教学”。→ 强制自问”我在教读者什么他能带走的方法？“没答案就重写。

反模式 4：AnalogyBuilder 参考答案太死

如果你给的参考答案像”标准答案”（读者填的任何其他东西都显得不对），就又退回到识别式了。→ 参考答案应该是”好例子”，并在组件里明确告诉读者”你的答案没有正确只有更深更浅”。

反模式 5：MindMapCompression 变成思维导图索引

如果出口的环形图只是把本页章节罗列一遍，那就失去了”压缩”的意义。→ 环形图应该是新的压缩模型（比如 agent-loop 的 “loop + 4 约束”），读者记住这个就记住了本页，而不是记住 13 个章节标题。

关系图谱