bug-receipt 技能实战指南用 BUG RECEIPT 收据格式闭环缺陷修复与事故复盘【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot导读bug-receipt 是 awesome-copilot 仓库中一套面向 GitHub Copilot Agents 的收尾技能SKILL当 Agent 完成一次缺陷诊断、修复或事故恢复后必须输出一张结构化的BUG RECEIPTBug 收据并给出VERIFIED、PARTIAL或BLOCKED三种明确状态。它的核心价值在于把看似修好了升级为有证据地修好了——通过强制记录问题、基线、根因、变更、证明与缺口六个字段杜绝把陈旧日志、顺带的构建通过或未经运行的检查当作用户可见行为的证据。读完本文你将掌握收据模板的完整字段语义、证据边界如何建立、追踪与最小修复的纪律、按决定性边界闭合证明循环的方法、三态判定的精确规则以及如何用 JSON 契约 校验脚本实现机器可读收据与 CI 集成。强制收尾输出BUG RECEIPT 模板模板全文与字段语义SKILL 的首要规则是强制输出对于每一个 bug 或事故的收尾决策Agent 必须把下面这份完整收据作为对用户的全部可见结果返回——即使被要求简短回复或未点名该格式。简洁只能缩短字段取值绝不能删除或重命名任何一行也不得用散文替换收据BUG RECEIPT · VERIFIED | PARTIAL | BLOCKED Problem observed defect and intended behavior Baseline failing interaction or command and decisive result; or not run Root cause proven mechanism; or unproven hypothesis Change responsible change; or none Proof supplied or executed check: result; include every decisive layer Gaps none; or exact missing proof and single next experiment/package Source executed now | supplied | mixed逐行语义如下字段含义允许的诚实取值Problem观察到的缺陷与期望行为必须具体描述缺陷现象 预期行为Baseline失败的交互/命令及其决定性结果具体命令与结果或not runRoot cause根因机制有证据的机制或unproven hypothesisChange负责修复的变更具体变更或noneProof已提供或已执行的检查及结果须包含每一层决定性证明检查 结果Gaps缺失的证明none或精确的缺失证明与下一个实验/补丁包Source证据来源executed now本次运行实际执行|supplied用户/其他来源提供|mixed混合关键纪律是必须显式使用not run、unproven、none。永远不要为了让收据看起来完整而省略某一行——留白是诚实的而补齐是误导。为什么模板即强制从技能定义看skills/bug-receipt/SKILL.md这份模板不是建议而是契约。它把 LLM 最常见的两类失败做了结构性拦截过度自信没有基线、没有证明的我修好了在模板里无处安放因为Baseline、Root cause、Proof行会逼迫 Agent 承认证据缺失模糊归因Change一行要求负责的变更杜绝把无关清理、重试、静默兜底或测试特例混入修复。建立证据边界修复之前先划定证据三类证据来源在任何编辑动作之前Agent 必须先记录四件事并形成证据边界观察到的问题observed problem期望行为intended behavior最强的直接检查strongest direct check证据来源executed now本次运行中实际执行的证据、supplied由用户或其他渠道提供的证据、mixed混合来源。严禁把提供的证据暗示为本次运行中执行的证据。例如用户贴来一段日志Agent 引用了它并声称复现成功这是典型的来源混淆正确做法是标记Source: supplied或补一次真实执行后标记mixed。隐私最小化与不可复现时的降级证据应保持隐私最小化对凭据、令牌、Cookie、个人数据、私有 URL 和敏感载荷做脱敏处理只保留复现或关联失败所需的标识符与片段。复现策略遵循最窄安全检查原则尽可能用最窄、最安全的检查复现失败。如果复现不可行例如环境被锁定、依赖不可用则保留已获得的证据并把结果封顶为PARTIAL或BLOCKED——而不是在证据缺失时虚构VERIFIED。追踪与修复从输入到症状的纪律四步追踪流程SKILL 给出了严格的四步修复流程沿实时属主路径追踪follow the live owner path从输入一路追踪到症状而不是在代码里随机打转分离三类信息观察事实observed facts、有界推断bounded inferences、缺口gaps三者必须清晰分开根因必须落点在命名根因之前必须给出一个具体的位置location或运行时转换runtime transition作为证据最小责任变更只做最小的、对症状负责的变更避免无关清理、重试、静默兜底和针对测试夹具的特例。什么不算证明这条规则的针对性非常强不要把一个合理的补丁、陈旧的日志、源码阅读或一次构建通过当作用户可见行为的证明。也就是说Root cause行里若只写我读了源码看起来是这里的问题那只是unproven hypothesisProof行里若写构建通过了也不等于用户可见行为被修复。构建通过只能证明编译层无错不能证明逻辑层正确——这正是下一节证明闭环要解决的。闭合证明循环按决定性边界逐层取证只运行受影响的契约所要求的检查修复完成后Agent 只运行受影响契约要求的检查典型层级如下原始复现或直接验收检查original reproduction / direct acceptance check最近的负向或回归检查nearest negative / regression check受影响的构建或集成门禁affected build / integration gate当声明跨过真实 UI、API、持久化、并发或运行时边界时必须走真实路径验证。决定性边界对照表SKILL 针对不同表面Surface给出了必须提供的直接证明要求这是证明闭环的核心表逐行继承如下表面Surface要求的直接证明Required direct proof逻辑或失败测试Logic or failing test原始失败输入或聚焦测试现在通过UI 行为UI behavior真实交互 相关的控制台与网络观察API 或集成API or integration请求、响应以及负责该行为的服务行为持久化Persistence经由真实属主路径的写/读或重载往返竞态或生命周期Race or lifecycle重复并发触发零或一次成功受影响行与事务证据最终不变量跨系统阻塞Cross-system blocker一条带时间戳或请求 ID 的脱敏失败请求/响应、边缘与应用日志以及当追踪到达该属主时的身份提供方日志这张表回答了为什么构建通过不算证明如果声明跨的是 UI 边界就必须给出真实交互与控制台/网络观察如果声明跨的是持久化边界就必须给出通过真实属主路径的写读往返。每一层缺失都会成为Gaps行的内容。状态判定VERIFIED / PARTIAL / BLOCKED三态定义VERIFIED存在观察到的基线observed baseline、具体的根因concrete cause、负责的变更responsible change所有声明的检查均通过且无实质性缺口PARTIAL存在有用证据但某一必需的证明层缺失或不具结论性BLOCKED存在特定的外部条件阻止了复现、修复或证明。缺口处理规则对于PARTIAL或BLOCKED必须点名唯一的最小实验或相关证据包用于闭合那个决定性缺口并禁止发明命令、观察结果、计数、位置或结果。机器可读收据JSON 契约与 CI 集成当用户、CI 或其他工具需要结构化工件时才使用 JSON正常最终答复保持人类可读。契约与必需字段references/receipt-contract.md 定义了机器可读契约version新收据为整数21仍被接受以保持兼容statusverified、partial或blockedevidenceSourceexecuted-now、supplied或mixedversion 2 必填problem简洁的缺陷与期望行为描述baseline包含command、result、evidence的对象rootCause包含summary与至少一条证据项的对象verified必填changes{ file, summary }对象数组verification{ command, result, evidence }对象数组gaps显式缺失证明的字符串数组。取值枚举基线结果baseline results为failed、observed或not-run验证结果verification results为passed、failed或not-run。状态不变量契约规定了三种状态各自必须满足的不变量verified要求必须有观察到的基线failed或observed绝不能是not-run至少一条具体的根因证据项含location与observation至少一个变更的文件或工件至少一条验证项每条验证结果必须为passedgaps必须为空。partial要求保留所有已获得的证据把每个缺失或不具结论性的证明层放入gaps绝不把未运行的检查改写为passed。blocked要求至少一条点名外部阻塞条件的gaps未执行的工作留空或标记not-run不得臆测结果。从模板起步并校验生成 JSON 工件时从 assets/receipt.template.json 起步写入任务专属路径然后用校验脚本验证。模板默认是诚实保守的status: partial、evidenceSource: supplied、baseline.result: not-run、空changes与verificationgaps内要求填写精确的缺失证明层——它天然引导 Agent 先承认缺口再逐层补证。校验脚本与 Schemascripts/validate-receipt.mjs 是配套的 Node.js 校验器提供三种调用方式# 校验文件 node scripts/validate-receipt.mjs receipt.json # 通过 stdin 管道传入 JSON cat receipt.json | node scripts/validate-receipt.mjs - --json # 安装包 CLI 后的等价命令 bug-receipt check file从源码实现看scripts/validate-receipt.mjs校验器把契约中的枚举与不变量逐条落地用Set限定合法取值statusesverified/partial/blocked、evidenceSourcesexecuted-now/supplied/mixed、baselineResultsfailed/observed/not-run、verificationResultspassed/failed/not-run对每个嵌套对象做未知字段拒绝rejectUnknown保证收据严格符合契约字段集对verified状态强制全部六项不变量基线不得为not-run、必须有根因证据、必须有变更、必须有验证项、每条验证必须passed、gaps必须为空对partial与blocked强制gaps至少一条分别对应缺失证明层与外部阻塞条件输出约定合法时打印✓ path is a valid STATUS bug receipt.并退出码 0非法时逐条列出字段路径: 原因并退出码 1--json模式输出结构化 JSON 便于 CI 消费。配套的 references/receipt.schema.json 提供 JSON Schemadraft 2020-12双重保障version 2必填evidenceSourceverified状态下基线result仅允许failed/observed、根因证据minItems: 1、变更与验证minItems: 1、验证结果const: passed、gapsmaxItems: 0partial/blocked则要求gapsminItems: 1。校验脚本与 Schema 形成双保险脚本适合在 Node 环境中直接执行断言Schema 适合任何支持 JSON Schema 的工具链编辑器、CI 校验器、代码生成复用同一套约束。将两者结合即可把人类可读收据无缝升级为CI 可断言、可入库、可追溯的机器可读收据。使用场景与工作流建议将 bug-receipt 集成进 Agent 工作流时建议遵循以下节奏接手缺陷先记录 Problem、期望行为、最强直接检查与证据来源划定证据边界追踪修复沿属主路径追踪分离事实/推断/缺口确认具体位置后才命名根因做最小责任变更闭合证明按决定性边界表逐层运行检查只运行受影响契约要求的检查输出收据无论用户是否要求都以完整 BUG RECEIPT 作为收尾结果显式使用not run/unproven/none机器集成需要结构化工件时从 assets/receipt.template.json 起步填写后经 scripts/validate-receipt.mjs 校验满足 references/receipt.schema.json 约束即可挂入 CI 或下游工具。该技能在仓库中位于 skills/bug-receipt/其完整工作产物还包括 references/receipt-contract.md契约规范、assets/receipt.template.json起始模板、references/receipt.schema.jsonSchema与 scripts/validate-receipt.mjs校验器。技能最初发布在外部 GitHub 仓库MIT 许可在本仓库以 SKILL 形式收录当前元数据版本 1.4.1可直接为 GitHub Copilot 的 Agent 模式所用。常见误区自查清单误区正确做法用散文代替收据无论用户如何要求都返回完整收据仅压缩字段取值引用用户提供的证据却标记为已执行区分executed now/supplied/mixed绝不混用复现失败或不可复现却报 VERIFIED无观察基线时封顶PARTIAL/BLOCKED构建通过当作修复证明按决定性边界表跨哪层边界就补哪层直接证明为显得完整而省略Gaps行显式使用not run/unproven/none留白即诚实PARTIAL/BLOCKED 不写下一步点名唯一最小实验或相关证据包闭合缺口JSON 收据跳过硬校验从模板起步经校验脚本 Schema 双重验证后再提交【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考