SuperAPI AI 工具集

explain-clearly

写作与研究

查看项目

更新于 10-23 20:54

技能介绍

Explain Clearly 是一个面向技术概念与机制讲解的技能,用于帮助用户看清某个东西如何运作。它把理性讲解作为主体,把类比作为辅助部分,而不是两条对等的讲解线。讲解使用用户的语言,并按用户选择的形式交付。

适用场景:概念和机制类问题,例如某物是什么、为什么存在、两部分能否通信。IPC、内存隔离、事件循环、虚拟 DOM、共识、缓存是典型主题。以下请求应转交其他技能并停止:手把手教程或入门引导(“教我怎么用 X”“带我搭建 X”)转 teach;把现有文档改写成文章转 article-writer;把设计文档转成评审文档转 tech-review-doc。

形式选择:用户已指定形式时沿用该形式;未指定时询问一次,只提供当前会话、HTML、Markdown、纯文本这几个选项,并推荐 HTML。

每次讲解必含四步,按顺序写:一句话定义,用一句精确的话说明它是什么,若问题可由一个事实回答(如“A 能否与 B 通信”),先给出该事实再继续四步;为什么存在,从没有它会怎样出发,再说明机制如何消除这一痛点;在用户世界中的具体形态,用提问者已知的代码或架构来落地机制,引用本次会话中读到的文件、行号和 API,如果概念在当前代码库中没有落点,则使用一个公开的典型示例并明确标注,若没有典型公开示例,则基于定义和存在原因展开并说明没有具体示例可用,编造路径、行号或 API 视为讲解失败;关键设计含义,说明在此情形下由机制推导出的设计决策。

随后附一个辅助部分:日常类比,用一个场景延展并映射各部分的关系,需逐条对照机制的每个定义性约束,若某个约束会丢失或被颠倒,就先调整或替换类比再交付;以及一句记忆锚点,一句话供用户复述。

可视化:概念存在比较、多条目映射、拓扑或流程时加入可视化,只画真实存在的关系。比较或映射用表格,每项一行;拓扑、分层或流程用图示;没有这类结构就不加可视化。HTML 与 Markdown 包含该可视化,纯文本保持散文形式,当前会话使用聊天中的表格或文本图示。

交付方式:需要文件形式时,在工作区根目录创建 .explain-clearly/ 目录。文件命名为 <topic-slug>-<local-YYYYMMDD-HHmm> 加对应形式的扩展名。每次都写新文件,保留已有文件,不修改工作区 gitignore。当前会话:把讲解放在聊天中,概念有结构时包含可视化,不写文件。HTML:在用户语言下写入 .explain-clearly/<name>.html,可参考 assets/explanation-shell.html 的结构(相同分区、内联 CSS、无脚本、文本即文本),该文件中的英文词只是示例,因为此技能以英文撰写;概念无结构时省略可视化块;在浏览器中打开该本地 HTML 文件,在聊天中给出文件路径并请用户查看页面,不粘贴完整讲解;若无法打开浏览器,仍给出文件路径。Markdown:写入 .explain-clearly/<name>.md,分区相同,概念有结构时包含可视化,在聊天中给出文件路径,不粘贴完整讲解。纯文本:写入 .explain-clearly/<name>.txt,仅散文,在聊天中给出文件路径,不粘贴完整讲解。

参考示例:reference.md 中有两个经过校准的示例,可用于对齐讲解深度,以及查看当代码库中没有落点时如何标注通用示例。在这些示例中,类比是辅助部分。