用交互让读者“玩会“概念：Beautiful Article 的 interactive-explainer 文章类型实战指南

人工智能AI 技能/插件提示工程【免费下载链接】garden-skillsConardLis open-source Skills collection, featuring web design, knowledge retrieval, image generation, and more.项目地址https://gitcode.com/GitHub_Trending/we/garden-skills点击查看免费下载把一篇长技术文章、论文或系统设计稿重构成以交互动画为主载体的会用了再走式学习页是 beautiful-article 技能提供的十种文章类型中最特别的一种。它参考 3blue1brown 的视觉化、distill.pub 的可调参数式机器学习解释、Bartosz Ciechanowskiciechanow.ski的硬件原理可玩页这三条成熟路径核心思路是正文是简短引导和定义Raw 交互层才是主体——读者不是看完而是操作完从知道了升级到会用了。本文基于 interactive-explainer.md结合仓库内的工作流与组件协议完整拆解这个类型的结构骨架、Raw 边界、自检清单与主题选择帮助你用它把抽象概念变成可动手验证的学习页。一、这个类型到底在解决什么问题在 article-types.md 的类型路由表中interactive-explainer被定位为Raw 交互为主载体的会用了再走式学习页选型提示只有一句但很关键要让读者玩明白一个概念Raw 交互为主正文为辅每知识点配交互演示→interactive-explainer。它的典型输入是信息密度极高、但线性阅读很难消化的材料一篇长技术文章、一篇论文、一份系统设计稿。输出则是一张让读者通过操作来建立直觉的网页。参考路径三选一3blue1brown 视觉化用动画把数学直觉讲透distill.pub 可调参数式解释让读者拖动参数、实时观察机器学习机制变化ciechanow.ski 硬件原理可玩页把硬件内部结构做成可操作的演示。这三者共同点是理解建立在亲手操作之上而不是建立在读完一段文字之上。与 explainer 的关键区别仓库原文用一个对照把两个最容易混淆的类型切开维度explainerinteractive-explainer主体正文是主体Raw 是辅助插图Raw 是主体正文是简短引导和定义读者状态读完知道了操作完会用了信息保留80%~25%原文摘录占比见下节本质解释机制内容重构判据很朴素如果你发现 Raw 承载了主要信息、正文变成了图注那么 explainer.md 的自检会提示你应该考虑改用interactive-explainer——这正是两个类型分界线在代码结构层面的体现。二、~25% 信息保留不是删 75%是重构 75%这是本类型最容易误解、也最容易做走样的数字。仓库原文明确警告这里的百分比不是原文删了 75%而是成品里直接来自原文的句子 / 段落只占约 25%。本类型的本质是内容重构。具体操作是只摘核心知识点的关键定义、公式、数据、约束、易错点其余 75% 由 AI 围绕这些知识点全新创作引导文字、直觉解释、交互演示、自己试、验证理解全部舍弃原文的叙事铺垫、历史背景、案例展开、扩展讨论——由交互替代。information-density.md 在信息密度等级表中单列为特例专门强调百分比含义不同plan-template.md 的 Brief 段模板也内置了一行interactive-explainer 特例说明要求写入 plan.md 的必须是成品里直接来自原文的句子 / 段落约占 25%这个准确表述。为什么不能当删 50% 的 explainer做仓库原文给了两个后果既学不透核心知识点没被交互撑起来也失去本类型存在的意义那不如直接用 explainer。重构的标准是——成品里直接来自原文的句子 / 段落比例确实在 ~25% 这个量级太高40%说明你在删 explainer而不是重构太低10%说明核心知识点没说清。三、典型结构每个概念一节一节三段式interactive-explainer的结构骨架在仓库原文中给定如下Hero一句话定位——这页让你学懂什么 / 玩什么Lead前置——1-2 句话提示你需要哪些基础、玩完能做到什么可选Summary列出 N 个核心知识点作为路线图多个Concept Section每个一个核心知识点节内三段式定义 / 直觉1-3 段正文 一个Aside toneprinciple抬出一句话直觉交互演示Raw 主体动画 / 滑块 / 拖拽 / 状态切换 / 参数变化的实时可视化自己试 / 验证理解Raw 交互让读者动手试一个边界 / 反例 / 应用场景可选一个答案揭晓的折叠Conclusion知识点串联回顾 何时用 / 不用 延伸阅读。组件选择这一类型对组件使用的约束非常具体正文要短每节正文加起来通常不超过 200-400 字Aside toneprinciple标定义、关键直觉、易错点这是每节三段式中定义 / 直觉的主力组件Detail/Tabs折叠次要细节、答案、推导三段式中答案揭晓的折叠就用它Quote引原文 / 论文金句少用Table/CodeBlock——如有必须服务一个具体交互演示不放整页代码Raw是主角。对照 component-policy.md 的 reacticle 组件协议正文仍是Section的 children语义组件Aside/Quote/Detail/Tabs只在内容确实是那个结构时使用而Raw与其余类型相反鼓励多用。本类型的特殊性在于把这条原则推到极致——Raw从点亮升级为主体。四、Raw 边界本类型的核心 · 必读既然 Raw 是主角它的边界就是本类型质量的生命线。仓库原文用核心 · 必读标注了这一节六条边界逐条拆解1. 每个 Raw 必须服务一个具体知识点不允许装饰性炫技。一条判断标准可以复用 raw-policy.md 的自检这块 Raw 删掉后文章理解是否会变差在 interactive-explainer 里这条标准要更严删掉它读者是否就学不会这个知识点2. 操作性优先滑块 / 拖拽 / 切换 / 输入框 / 步进按钮——让用户改变某个量并实时看到结果。这比看一段动画更深。注意方向动画是单向的看操作是双向的改 → 看结果 → 再改。raw-policy.md 里给出的示例正是这个思路——一个useState驱动的input typerange滑块拖动即见数值变化function TokenScale() { const [n, setN] useState(50); return ( div input typerange value{n} onChange{(e) setN(e.target.value)} / span style{{ color: var(--ra-color-accent) }}{n}%/span /div ); } Raw title拖动感受差距TokenScale //Raw3. 状态可见当前参数、当前数值、当前阶段都要显式可见不要藏在动画里。交互的每一步反馈必须能被读者读出来——这是可学习性而不是炫技的分水岭。4. 可重置每个交互配reset或恢复初值鼓励反复试。反复试错是会用了再走的机制保障读者可以放心把参数拖到任何位置一键回到起点重新来。5. 样式走 token颜色 / 字体 / 间距用--ra-*不写野生 CSS。这与 raw-policy.md 的自由但一致用 token完全一致——Raw 内部任意 HTML / CSS / JS / React 都可以写但颜色 / 字体 / 间距必须取自主题变量var(--ra-color-accent)、var(--ra-font-body)、var(--ra-space-4)…这样每块 Raw 独一无二却又随主题切换。6. 错误示例同样有价值让用户拖到会出错的位置配一行说明为什么这里崩。这是 interactive-explainer 特有的教学策略边界条件不是靠文字陈述而是靠读者亲手触达。它是自己试环节的标准素材。五、配图倾向与主题倾向配图倾向none优先交互比图片更有信息量少量placeholders理论图 / 截图避免ai-generated氛围图打断学习节奏。这与 SKILL.md 的默认策略呼应——配图模式与 Raw 正交选none不影响 Raw而在本类型里Raw 恰恰是主角所以none是最自然的搭配。主题倾向仓库原文给出一组明确的推荐与禁忌主题适合理由tufte克制 数据感适合 ML / 算法可视化shannon暗底工程感适合系统 / 硬件交互演示knuth学术克制适合论文重构避免freddie/sottsass活泼配色会让交互显得像游戏而非学习对照 theme-profiles/index.json 与 tufte.mdtufte 的 Raw 风格正是细线折线 / 可拖动阈值线 / 微型 sparkline / 轻量可调参数控件这类数据密集、低装饰的交互——与 interactive-explainer 的操作式学习完全同频shannon.md 则是暗底工程现场的仪表信号气质契合系统 / 硬件演示。主题决定的是审美气质与是否可交互无关——但主题选错会直接动摇读者对这是学习页的认知。六、自检清单判断本类型是否走样的关键仓库原文给出一组自检项其中两条标注了这是判断本类型是否走样的关键问题。完整列出读者玩完是否真正会用这个概念而不只是听过 / 看过——最终验收标准每个交互是否服务一个具体知识点有没有炫技但学不到东西的 Raw没有交互的章节是真的不需要交互还是偷懒了★关键问题移动端能不能操作很多滑块 / 拖拽 / 复杂 SVG 在 mobile 上不能用——必须在Plan 阶段就决定是否放弃 mobile 交互还是提供 mobile 替代展示删掉所有 Raw 后剩下的正文是不是太薄太薄说明 Raw 没把信息装进去——应该在 Raw 内或紧邻位置补足成品里直接来自原文的句子 / 段落比例确实在 ~25% 这个量级吗40% 是在删 explainer10% 是核心知识点没说清核心知识点筛选有据能否一句话说出这页保留的 N 个知识点为什么是这 N 个随便挑几个是这个类型走样的开端。其中第 3 条和第 7 条最值得反复对照没有交互的章节是真不需要还是偷懒以及知识点筛选能否一句话说出理由——这两条直接决定了文章是重构后的学习页还是没删干净的 explainer。七、何时不要用 interactive-explainer仓库原文在结尾给出了反向边界同样重要源材料是叙事 / 观点 / 评论→essay源材料是步骤型操作→tutorial步骤之间有先后依赖不是知识点的并列源材料是数据报告→full-report结论比交互重要你不打算写真正可操作的 Raw→explainer即可别假装 interactive。这个不要用清单与 article-types.md 的选型提示形成闭环interactive-explainer 只服务知识点并列、可独立操作验证的源材料。任何有强先后依赖tutorial、强结论导向full-report或强叙事结构essay的材料硬套进来都会变形。八、在 beautiful-article 工作流中的落地位置本类型不是孤立的写作技巧而是 SKILL.md 八阶段工作流中一个结构决策。几个关键衔接点Phase 2 规划选定类型后读article-types/type.md拿结构 / 组件 / Raw 边界 / 配图倾向 / 自检把大纲、必须保留的知识点写进plan/plan.md的 Outline 段Phase 3 Checkpoint 1文章类型含标配保留比例 ~25%作为 5 项必确认决策之一由用户独立确认禁止静默替选比例已绑进类型选项避免longform 20%这类伪组合Phase 4/5 生成每个 Section 是独立组件文件article/sections/NN-*.tsxcomponent-policy.md 的一节一文件铁律Article.tsx只做组装大型 Raw 隔离到article/raw-blocks/NN-*.tsx移动端问题必须在 Plan 阶段决策这正是自检清单第 4 条指向的硬约束终审Editorial / Visual / Technical 三视角验收中删掉所有 Raw 后正文是否太薄是判断本类型是否走样的直接抓手。工作区脚手架通过bash path-to-beautiful-article/scripts/scaffold.sh ./my-article --themeid创建 Vite React TS 工作区从 npm 安装reacticle最新发布版含source/ plan/ review/记忆目录与 assemblerarticle/Article.tsx——interactive-explainer 的 Raw 主体正是依托这套语义组件 受主题约束的 Raw 自由层的协议来实现的。结语interactive-explainer是 beautiful-article 十种文章类型中信息保留含义最特殊、对 Raw 要求最高的一种约 25% 的原文摘录是种子75% 的 AI 重构引导文字 交互演示 自己试 验证理解是果实。它的成败不取决于文字写得是否漂亮而取决于三个问题每个知识点是否都有一个可操作、状态可见、可重置的交互演示删掉所有 Raw 后正文是否仍然完整核心知识点筛选是否说得清理由抓住这三条你就掌握了从读完知道了到玩完会用了的转换开关。赞分享人工智能AI 技能/插件提示工程【免费下载链接】garden-skillsConardLis open-source Skills collection, featuring web design, knowledge retrieval, image generation, and more.项目地址https://gitcode.com/GitHub_Trending/we/garden-skills点击查看免费下载相关推荐Klavis 仓库中的 Notion MCP Server从 Integration 配置到双传输模式的完整接入指南Klavis 仓库中的 Notion MCP Server从 Integration 配置到双传输模式的完整接入指南 本指南以 mcp_servers/not人工智能AI 技能/插件提示工程Lefthook 的 interactive 配置让 Git Hook 与开发者实时交互Lefthook 的 interactive 配置让 Git Hook 与开发者实时交互 导读 当 Git Hook 中的命令需要向开发者提问、要求确认或接收开发工具Figma MCP Server教育应用设计创造互动学习体验Figma MCP Server教育应用设计创造互动学习体验 Figma MCP Server是一款将Figma设计直接集成到工作流中的工具它能为AI代理提AI 技能AI 插件上一篇Driver Store ExplorerWindows驱动仓库清理与管理的终极解决方案下一篇突破物理限制用ParsecVDisplay在Windows上创建完美虚拟显示器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考