安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install no-black-box
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 no-black-box。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

No Black Box 是 Openclaw Skills 工作流，用于说明已完成的代理工作，不隐藏推理、证据、决策、限制或未解决事项。它帮助代理将源材料、实现变更、数据更新、部署和验证结果转化为便于读者理解的交接文档。
此技能优先采用结论先行的写法、一致的说明顺序、真实数据、来源位置、截图、清晰可见的状态标签，以及诚实说明验证边界。它可以生成独立 HTML 文档或在线文档；当外部相关方必须批准或决定具体事项时，还可以另外生成确认清单。

应用场景

用户表示自己尚未审阅源材料，需要逐步了解需求。
代理已完成一项耗时较长、涉及多个文件或步骤的任务，必须说明变更内容。
客户、同事、专家或决策者需要一份可阅读或演示的文档。
项目包含大量数据变更、意见、需求或需要跟踪状态的审阅事项。
部署或数据更新需要记录验证结果、版本、日期和已知缺口。
需要外部批准，且必须逐项回答每个问题。
演示或转发时需要一份嵌入截图、可独立使用且便于携带的 HTML 简报。
团队需要透明的交接文档，将面向公众的信息与内部实现细节分开。

工作原理

判断工作是否需要文档：对大量且已独立完成的工作或相关方沟通使用此技能；对于几句话即可说明的小改动则不使用。
确定受众，包括用户、同事、客户、专家以及所有负责批准的人。
清点每项源材料，记录作者、类型、与工作的关系，以及由其得出的具体事项。
收集真实数据中的证据，包括变更前后的数值、比较结果、测试结果、来源位置、版本、日期和截图。将无法获得的证据标记为未经验证，而不是凭空编造。
使用稳定结构编写一份说明文档：结论、快速概览、背景、源材料概览、逐项说明、发布与验证、外部确认、补充事实、未解决事项和附录。
按一致顺序说明每个事项：内容、原始状态、变更内容、演算示例、边界、实现细节、影响以及与其他事项的关系。
事项数量较多时，使用代表性示例和状态摘要；将完整跟踪表放入附录或链接文档。
只有在外部人员必须批准或作出决定时，才创建单独的确认清单。将其分为已处理事项、问题和待决事项，并提供清晰编号和回复说明。
从可能分享的文档中删除机密、凭据、私人联系人、不必要的内部架构和敏感信息。
独立审查事实、截图、一致性和读者适用性。重新检查所有变更部分，验证已发布版本，并披露未执行的审查或测试。
随文档链接或文件一并提供简明的对话说明，指出关键风险、例外、缺口和建议阅读顺序。

配置指南

安装与配置
No Black Box 是一项文档与交接技能，而非独立运行时应用程序。请将技能目录及其参考文件添加到 Openclaw Skills 兼容代理环境所使用的技能位置，以完成安装。请保留随附的 references/ 目录，因为该工作流依赖其中的写作、证据和 HTML 模板。

示例：将技能目录复制到代理配置的技能目录中

cp -R no-black-box /path/to/your/skills/
如果代理宿主使用不同的技能目录，请按照该宿主的安装约定将 no-black-box/ 放入其中。此技能未指定包管理器、API 密钥、外部脚本或运行时依赖。
生成文档前，请阅读适用的参考文件：
references/rhythm.md：说明顺序、代表性示例、沟通措辞和大量事项的处理方式。
references/evidence.md：来源引用、截图准备、说明文字和证据检查。
references/page-template.html：独立 HTML 布局、主题变量、响应式组件和确认清单结构。
references/example-briefing.html：完整的简报示例。
对于在线文档，请使用团队现有平台和默认权限。不要自动启用基于链接的编辑权限或广泛访问权限。对于独立 HTML，请确保文件自包含，并将截图嵌入为 data: URI，而不要依赖相对图像路径。

数据架构

文档输出
输出 受众 用途
说明文档 用户、同事、专家、客户 说明工作、证据、影响、验证、限制和未解决事项
确认清单 外部审批者或决策者 收集针对问题和待决事项的逐项回复
跟踪表 内部或共享项目的读者 记录事项状态、编号、证据、负责人和后续工作
附录 需要详细信息的读者 存放截图、来源列表、术语以及完整数据集或事项清单
建议的元数据分类
受众：用户、同事、专家、客户、审批者。
源材料：文件名、作者、类型、页码、行号、单元格或系统位置。
事项：正在说明的需求、变更、数据更新或决策。
状态：已完成、待确认、未完成、已处理、问题或待决事项。
证据：原始值、更新值、比较结果、公式、测试结果、截图和验证范围。
验证：测试名称、版本、执行日期、环境、结果和未测试区域。
影响：受影响的结果、外部相关方、不受影响的区域和后续工作。
决策负责人：负责确认未解决事项的个人或群体。
保密性：可分享内容、仅供内部使用的细节、已删减内容和截图审查状态。
对于大型事项集合，请在概览页按状态汇总数量，并为每种状态列出一至四个代表性示例。将完整跟踪数据放入附录或链接的在线文档中。确认事项应使用明确的前缀，例如 Question 1 和 Pending 1，并确保这些标识在简报、清单和跟踪表中保持一致。

高级特性

结论先行的简报设计，让读者在查看支持证据前先了解结果。
固定的逐项说明节奏，涵盖背景、原文、变更、示例、边界、实现、影响和关联。
以证据为依据的写作，要求使用真实来源数值以及精确的文件、页码、行号或单元格引用。
提供演算过程的变更前后比较，并明确列出不受影响的示例。
通过状态数量、代表性标记示例和完整附录处理大量事项。
独立的确认工作流，分为已处理事项、问题和待决事项。
独立 HTML 输出，包含响应式布局、浅色和深色主题、CSS 变量、状态标签、原文与解读并列视图、说明文字和嵌入式截图。
截图安全检查，涵盖地址、账户标识、客户名称、隐藏单元格、说明文字以及编辑后的重新截图。
保密控制，排除密码、令牌、密钥、服务器地址、私人联系人、不必要的架构信息和内部评估。
从事实、截图、一致性和读者角度进行独立审查；条件允许时支持多个审查代理。
如实披露未经测试的环境、无法获得的证据、缺失的独立审查，以及新发现但未经验证的问题。
提供对话中的交付指导，避免将内部实现细节放入面向外部读者的文档中。

name: no-black-box description: 不留黑箱的交接讲解：Agent 自主完成一段较长的工作（理解需求材料、写代码、改数据、部署、验证）之后，把需求背景、落地方案、验证结果和未决事项讲给使用人，让他能先自己吃透、再去和客户、同事、专家沟通。产出一份讲解文档（自己读，也能投屏、转给别人），有需要外部确认或拍板的事项时再加一份确认单（给对方逐条回复），单文件 HTML 或在线文档；结论写明出处，源文件配截图，条目多时用标杆例子讲。当有人说“我得先理解你做了什么”“给我讲讲背景”“对照原材料讲一下”“做个需求导读”“我要拿去和客户/同事沟通”“这些我都没看过”“做个 html 方便我理解”“写份汇报材料，我要投屏讲”“附上源文件截图”，或 Agent 刚独立做完一大段工作需要交接时使用。 license: MIT

不留黑箱

Know your own shit —— AI 做完的活，你得能讲给别人听。

Agent 一个人把活干完了，使用人却没看过材料、没跟过过程。他接下来要去和客户、同事、专家 沟通，必须先听懂：需求从哪来、改了什么、为什么这么改、改了以后会怎样、还剩什么没定。

本 skill 规定怎么讲：每个事项都按同一个顺序讲，用真实数据举例，原文和解读并排放，每个结论 写明出处。它不管活怎么干，只管活干完以后怎么讲清楚。

参考文件：

文件 何时读
references/rhythm.md 动笔前读：单个事项的讲解顺序、条目很多时怎么挑例子、沟通口径、反例
references/evidence.md 要写出处、截源文件或系统页面时：出处写法、截图方法、图注规则
references/page-template.html 写 HTML 时：版式、颜色令牌、组件（原文/解读并排、讲解卡、状态标签、截图与图注）；末尾有确认单骨架
references/example-briefing.html 想看成品长什么样时：一个虚构项目的完整讲解文档

1. 什么时候用，什么时候不用

用：

使用人明确说自己没看过材料、要先理解，或者要拿去和别人沟通、当面讲。
Agent 独立完成了跨多份材料、多个改动的工作，使用人只看到了结果。
改动会影响外部的人（客户的数据、专家的方法、同事的模块），需要有人去解释。

不用：

小改动、一问一答能说清的，直接在对话里讲。
使用人一直全程参与，只需要一个结论。
使用人只要一份正式交付的对外文档（报告、发布说明），自己不需要先吃透、也不拿去当面讲，那用对应的写作规范。

拿不准时，先在对话里用三五句话讲结论，问使用人要不要展开成文档。

2. 动笔前准备

逐项确认，缺的就补，补不到的写进文档的「未决与待商量」：

项 要确认什么
读者 讲解文档除了使用人，还会转给或投屏给谁（客户、同事、专家）；确认单给谁拍板
原材料 使用人给过的每一份材料：文件名、谁写的、是什么性质（标准、意见、需求、笔记）
事项清单 这一轮做了哪几件事，每件事对应哪份材料
证据 每个结论背后的实际数据：改前改后的值、比对结果、测试结果。要从真实数据里取，不能凭印象写
出处 每个结论落在哪份源文件的哪一页、哪一行、哪一格；要配图的源文件和系统页面先截好（见 references/evidence.md）
验证 做了哪些验证、在哪个版本上、什么时候做的、结果如何、哪些没验证（比如本机缺环境）
未决 哪些需要外部的人拍板、哪些是自己后续要做的
保密 哪些信息不能出现在会被转发的文档里（见第 6 节） 3. 文档组合

最多两份文档，按读者分（确认单只在有需要外部确认或拍板的事项时做）：

文档 读者 作用
讲解文档 使用人，以及他要转给或投屏给的同事、专家、客户 把整件事讲清楚：使用人先吃透，再直接拿去讲
确认单 需要拍板的外部专家或决策人 逐条答复

默认用单文件 HTML（浏览器直接打开，不依赖外部资源，见第 5 节）；使用人的团队在在线文档里协作时， 直接写进在线文档。

讲解文档只写一份。 使用人自己读的和拿去给别人看的是同一份，所以它从一开始就按「会被别人看到」 来写：只放内容（见第 5 节「文档里只放内容」）。只给使用人一个人的东西（沟通口径、讲解提示）在对话里 交付（见第 8 节）；文档会到外部的人手里时，内部细节也放进对话（见第 4、6 节）。

讲解文档的章节顺序固定，没有的内容就省掉那一节：

结论：三五句。做完了什么、影响多大、需要谁做什么。
一页速览：每个事项一行（来源原话、结果、状态）；条目很多时再加按处理状态的条数表。
先理解背景：被改的东西本身是什么、怎么运转。事项卡里的「它是什么」已经讲清的可以省。
源文件一览：每份材料是什么、谁写的、对应哪个事项；材料之间是什么关系。
每个事项：先一个结论框，再按第 4 节的顺序讲；原文和解读并排。事项可以按材料组织，一份材料一节。
上线与验证：在哪个版本、什么时候、验证了什么、结果如何。
需要外部确认的事项：确认单有几条、请谁回复、怎么回复（在线文档：在条目后填写或评论；单文件 HTML 不能批注， 请对方按编号在邮件或消息里回复，如「待定 1：……」；要对方直接在文件上填的，确认单改用在线文档或表格）； 在线文档附确认单链接，单文件 HTML 写确认单的文件名和位置（列进附录文件清单）。
补充说明：容易被问到的点，写成中性的事实。
未决与待商量：每条写明需要谁。
附录：放不进事项卡的源文件截图、名词解释、文件清单（源文件、跟踪表的位置）。

确认单单独成文，因为读者要逐条回复。开头一段写清：致谁、依据哪几份材料、请回复哪几部分、怎么回复、 希望什么时候前回复。正文分三部分，顺序固定，某部分没有条目就省掉：「已处理」（已改好的，以及不用改、排进下一版的，每条写怎么处理的、没改的写为什么，供知悉，不用回复，不编号）、「疑问」（疑似 问题，每条写出处、现状、建议）、「待定」（需要拍板的，每条写出处和一个明确的问题，并写回复前暂按什么做）。 要回复的条目按部分各自编号，写成「疑问 1」「待定 1」；回复和讲解文档、跟踪表引用时都带前缀。版式见 references/page-template.html 末尾的确认单骨架。没有需要外部确认的事项，就不做确认单。

条目很多时（几十上百条意见），不逐条讲：一页速览给按处理状态的条数表，对应事项里每个状态挑 一到四个标杆例子，挑法、例子一览表和例卡格式见 references/rhythm.md；全量放跟踪表， 文档里写明它在哪（在线文档给链接，HTML 列进附录文件清单）。

4. 核心：每个事项按同一个顺序讲

这是本 skill 最重要的一条。使用人觉得「好懂」，主要靠这个顺序，所有事项都按它写：

它是什么：先用一两句白话解释被改的东西本身。读者不知道「暗访」「培训完成率」是什么，后面的改动他看不懂。
原文 / 改前：材料原话怎么写的，或者改之前是什么样。原文照录，不要转述。
改成了什么：用改前改后对照表，配真实数字的例子。一条规则配一两个最典型的例子，不要列全量。
一个算给你看的例子：挑一个具体对象，把改前改后各算一遍，让读者看到差在哪里。
边界：哪些没动、为什么没动；哪些是例外。
怎么落地的：规模（改了多少处）和核对结果；方法和碰到的坑看读者（见下面「会到外部的人手里时」）。
影响：对结果、对外部的人有什么影响；什么不受影响。
和其他事项的关系：它和哪份材料、哪个待确认事项、哪个后续工作有关。

不是每一步都必须有，但顺序不要乱。详细写法、措辞和反例见 references/rhythm.md。

几条容易卡住的规则：

结论放在卡片前面：每个事项先用一个结论框说一句话（改了什么、影响多大、状态），下面才是八步讲解卡。
原文不重复：页面上方已经有原文并排的，讲解卡里第 2 步只写「改前是什么状态」，不再照录原文。
可以用假设的例子：真实数据里找不到能说明问题的对象时，可以假设一个输入，但分界值、公式、 权重这些规则本身必须是真的，并在例子旁标「假设」。能找到真实对象（样例数据、实际记录）时优先用真的。
再算一个不变的例子：讲「什么不受影响」时，最好算一个改前改后结果相同的例子，比一句话有说服力。
规模数字写清口径：「改了多少处」可能有两种数法（业务上的条目数、系统里的副本数），两个都写并注明。
会到外部的人手里时：第 6 步只写对方用得上的部分（业务条目数和核对结果，用业务说法）；副本数、改法、 系统结构、改的过程中出过又已补上的错、提交号，在对话里讲给使用人（见第 8 节）。
使用人自己拍过板的事：写成「按 X 月 X 日定的口径」，讲清内容；是谁定的在对话里提醒使用人。
讲解中发现的新问题：写在对应讲解卡末尾的提示框里，同时列进「未决与待商量」，标明「新发现，未核实」。 5. 写法规则 结论先行：每节第一段就是结论，依据放后面。读者只看第一段也该知道发生了什么。
白话：术语第一次出现就解释；不用内部代号、提交号、函数名当主语，需要时放括号或附录（会到外部时省掉）。
真实数据：例子里的数字从实际数据里取，写之前先查一遍。查不到就写「未核实」，不要编。
出处写到格：每个结论写明源文件、页、行或单元格，原话逐字照录。写法见 references/evidence.md。
原文和解读并排：左边是材料原话，右边是理解和处理结果。读者能自己判断你理解得对不对。 关键源文件配截图，截图和图注的规则见 references/evidence.md。
结论只说到证据覆盖的范围：「说到分数的 40 条逐条重算，36 条一致，另 4 条都是系统舍入早了一步（已改）」比「全部没问题」可信。 别的条目里只要有一处中间值对不上，结论就不能扩到全部。
界面和系统行为对照实物再写：写「页面不显示 X」「系统会 Y」之前，看一次代码和实际页面 （反例见 references/rhythm.md）。
测试结果写清版本和时间：和「最终版本」放在一起的测试结果，读者会以为是在最终版本上跑的； 不是的话写明在哪个版本、什么时候跑的，此后又改了什么。
同一个记号只表示一样东西：同一页里只写「3」，读者分不清是例子一览的例 3 还是确认单的待定 3； 写明「例 3」「待定 3」。
各处说法一致：同一事实、同一数字、同一说法在讲解文档、确认单、跟踪表里一致。改一处说法时， 把每份文档里同样的话都找出来一起改，包括跟踪表的备注列。
状态一眼可见：用「已完成 / 待确认 / 未做」这类标签，不要让读者从段落里找状态。
诚实：没验证的写没验证，影响到读者的问题照写，被推翻的结论要更正。上线前就发现并改好、没影响到 读者的失误，文档会到外部的人手里时在对话里讲。
长度：讲透为止，但不要把材料整段搬过来。表格只放有代表性的行，全量放附录或另给文件。
载体要求：HTML 用单文件，颜色走 CSS 变量并做深浅两套主题，窄屏能看，不引外部脚本；截图用 data: URI 内嵌进 ，不写 src="shot1.png" 这类相对路径（转发或换台机器投屏就丢图，见 references/evidence.md）。版式和组件照 references/page-template.html。写进在线文档时用平台自带的组件对应： 结论框用高亮块，原文/解读并排用两栏，状态标签用表格底色，截图用图片块并写图注。

文档里只放内容。 讲解文档会被投屏、转发，确认单会发给外部的人：

不写「用途：本人使用」「信息截至」这类元信息，不写讲解顺序、时间安排、措辞建议、沟通口径、 「现场可能被问到」，也不写「今天改了哪几处」这类改动记录。这些在对话里交给使用人。
可能被问到的问题改写成中性的「补充说明」：只陈述事实，不用问句，不用质问的口气。
结论要经得起被涉及的人当面看：不写读起来像在说对方错的句子，待对方确认的事写成「疑似」「请您确认」 （正反例见 references/rhythm.md「反例」）。
交付前把文档通读一遍，找「本人」「讲解顺序」「先讲」「时间安排」「措辞」「沟通口径」「现场」「今天」这类字眼。 6. 保密与脱敏

讲解文档会被转发。动笔前先想清楚它会到谁手里：

任何文档都不写密码、令牌、密钥、服务器地址、个人联系方式。
会到外部的人手里时（客户、专家），只写对方需要知道的：不写内部系统结构、其他客户的信息、 实现细节、内部人员的评价。内部细节在对话里讲给使用人。
引用材料原文时，只摘和事项有关的几行。
截图同样要查：系统截图里可能带地址栏、账号、其他客户的名字；放进文档前逐张看一遍。
在线文档按团队默认权限创建，不擅自打开「有链接即可查看/编辑」；要开放时让使用人自己设。
文档要放进共享仓库或作为示例复用时，整体脱敏：项目名、客户名、人名、行业术语、编号体系、 真实数值、单元格位置、原文里有特点的笔误、地址、提交号全部替换成虚构的，替换后通读一遍，再按名单检索 一遍有没有漏网的。只把真实记录换个名词不算脱敏。 7. 交付前独立核对

文档发出去之前，按下面四个角度各找一个复核者从头查，复核者之间互不知情（宿主能开子 Agent 就每个 角度开一个）。查出的问题再找另一个人试着推翻，推不翻才改。四个角度：

事实：每句话对源文件、对系统、对数据查一遍（原话、行号、单元格、公式、数值、状态、编号）。
截图：逐张打开图片，看图注说的和图里能看到的是否一致；文档里截了另一份文档的，那份文档 改过之后要重截。
一致：讲解文档、确认单、跟踪表和线上版本互相比对：条数、编号、同一件事的说法。
读者：文档里有没有元语句、讲解提示；结论在被涉及的人面前读起来是否得体。

开不了子 Agent 时，自己按这四个角度各从头过一遍，每个问题先试着自己推翻再改；在交付说明（见第 8 节） 里写明「未做独立复核」，不要声称已独立核对。

每改一轮，就对改过的地方再查一轮，直到没有新问题。文档放在共享位置时：覆盖前先看有没有新评论、 版本号有没有变（别人可能正在改）；发布后回读线上版本，确认和源稿逐字一致、图片一张不少。

8. 交付以后

在对话里交给使用人：

文档链接，以及几句话的交付说明：先看哪一节、哪几件事值得先提（风险、例外、遗漏），哪些检查没做 （如「未做独立复核」「未实测」）。
沟通口径：每类读者一段可以直接说出口的话，三到五句：先说结论，再说对他有什么影响，最后说 需要他做什么。写法和例子见 references/rhythm.md。
讲解提示：讲的顺序、哪些说法当着谁的面要注意、容易被问到的问题和答法。
内部细节（文档会到外部的人手里时）：第 6 步的改法、系统结构和副本数、改的过程中出过又补上的错、提交号。
哪些事是使用人自己拍的板：文档里只写「按 X 月 X 日定的口径」，是谁定的在这里提醒（见第 4 节）。
使用人说「这个没看懂」，就单独把那一项按第 4 节的顺序在对话里讲一遍；他认可了，再把这段讲解 补回文档对应位置。使用人说「这个节奏好」，后面的事项都照这个节奏补齐。 9. 自查清单

交付前逐条过一遍：

讲解文档按第 3 节的章节顺序；每节第一段就是结论
每个事项都按第 4 节的顺序讲，没有跳过「它是什么」
每个例子的数字都从真实数据里查过；假设的例子标了「假设」，规则数值都是真的
原文是照录的，不是转述；每个结论写了出处（文件、页、行或格）
关键源文件有截图，每张按 references/evidence.md「截图清单」过了一遍（图注和图一致、后加标注/拼接/略去写明、看不见的格有说明、改稿后重截、投屏看得清）
条目很多时，给了按状态的条数和每类的标杆例子
结论的范围没有超出证据；界面和系统的说法对照过代码和实际页面；测试结果写明了版本和时间
状态标签和正文一致；讲解文档、确认单、跟踪表的数字和说法一致；同一记号只表示一样东西
确认单（有的话）开头写明致谁、依据哪几份材料、请回复哪几部分、怎么回复、何时前回复；分成「已处理」「疑问」「待定」 三部分（没有条目的省掉）；要回复的按「疑问 N」「待定 N」编号，和讲解文档、跟踪表一致；每条有出处，「疑问」每条写了 现状和建议，「待定」每条一个明确的问题，并写了回复前暂按什么做；没有需要外部确认的事项就没做确认单
未决与待商量写明了需要谁；讲解中新发现的问题已列进去并标「新发现，未核实」
文档里没有元语句、讲解提示、沟通口径和改动记录；结论在被涉及的人面前读得过去；这些提示已在对话里交给使用人
不该出现的内部信息没有出现，截图也查过；在线文档没有擅自打开链接分享
做过独立核对（开不了子 Agent 的，按四个角度自查过，并在交付说明里写明「未做独立复核」），改动后又 复核过；放在共享位置的，线上版本和源稿一致
HTML：文件能单独打开（截图已内嵌），深色主题下看得清，手机宽度下页面不横向滚动（宽表只在表格框内滚动）， 浏览器放大到 150% 投屏时版式不乱、出处看得清。宿主有预览或截图工具就实际看一次；没有就在交付说明里写明 「未实测」，不要声称已检查
新用户产品审计

Prose & Gap Polish