SuperAPI AI 工具集

clarification-protocol

智能体与模型

查看项目

更新于 10-20 00:07

技能介绍

澄清规程(Clarification Protocol)是一套面向需求澄清阶段的方法论与配套工具集,用于在制定计划或编写代码之前与用户对齐需求,避免两种典型失控:问得太少,把未确认的假设当作结论落地;问得太多,用穷尽边界替代收敛,把用户变成问答机器。该规程把澄清过程设计为有前置项、有分级、有台账、有预算、有出口的收敛过程。

用途与定位

该规程的核心目标是将需求澄清从开放式问答转变为可管理、可验证的收敛流程。它明确了单一事实来源(SSOT)边界:全局提示词只保留一行指针以维持每轮在场,完整规程以本技能文件为准,不在全局层复制细则。

主要能力

  1. 术语先行:作为全局前置项,先逐一定义核心术语、范围与易歧义处,登记至需求确认文档(RFC)的术语表段落或计划文件,再用统一术语澄清需求与边界。术语问题豁免后续的「依赖强度 × 实现影响」分级,不得因判定为局部低影响而转为默认假设。范围以「易产生歧义」为界,禁止扩张为全量词表。次序门禁要求术语未对齐则不进入需求与边界澄清。

  2. 提问排序:澄清性提问以「依赖强度 × 实现影响」排序。高影响(影响实现)进入本轮问题清单;低影响(仅影响实现细节)直接转为默认假设并登记,不占用用户注意力。需要用户决策时,优先给出 2–3 个具备可行性的方案(优缺点对比与推荐理由),引导用户做选择题而非开放式提问。

  3. 决策台账:已决项、已排除边界与默认假设即时登记于计划文件或检查点,禁止只留在对话里。已决项须写明结论本身与出处(用户裁决或证据);已排除边界须写明被排除的方案或范围与排除依据;默认假设须写明未提问即采用的取值、影响级别与可否决性。去重纪律禁止换一种说法重开已被排除的边界。提前收敛时必须登记被判定为低影响而转为默认假设的分支,未登记即视为未收敛。

  4. 提问收敛律与三项收敛自检:每个里程碑(默认每轮提问结束)执行一次不带新问题的自检,只回答三项:核心业务目标与流程是否仍有未明确;关键边界与异常情况是否仍有未确认;已决项之间是否存在相互矛盾的描述。三项皆否定(无新增信息增量)即收敛,闭合主干、把剩余边界登记为显式默认假设并输出需求确认文档,不以穷尽问题为出口。任一为是则继续,且下一轮问题必须落在该项上。不得用「没问题了」自证收敛,收敛必须有台账作为证据。

  5. 熔断预算与升级:错误层同一错误连续尝试 3 次即 STOP 并 RECORD,Heavy Track 经证据门控可有限重入(不超过 2 轮、每轮不超过 2 次),其余通道直接 ASK & ESCALATE;审查层 Delta Re-Loop 不超过 5 轮,停止追加轮次并携既有证据上报;提问层预算耗尽仍不收敛则升级人类裁决。重入门控四条判据(新假设、新外部证据、非措辞改写、预算未耗尽)与成本上限 min(任务总预算 × 25%, 剩余预算 ÷ 3) 见 goal-loop 技能的 failure-recovery-protocol。升级时向用户客观陈述四项:现状、已验证信息、当前瓶颈、需要裁决的具体分叉。

  6. 显式化思考:在执行关键架构决策、复杂重构或多步骤任务前,在输出中用思考块梳理推演(约束 → 候选 → 取舍 → 结论),确保逻辑自洽后再落笔。

使用方式

该规程正文为单份文件,配套交付物包括:references/decision-ledger.md 将台账纪律细化为三类登记的必填字段、去重判定式与低影响分支转默认假设的判据;references/convergence-checklist.md 将三项自检细化为逐问判定标准与「不算收敛」的反例对照;templates/decision-ledger-template.md 可直接落进计划文件;templates/requirement-confirmation-template.md 是需求确认文档骨架(术语表、已决项、已排除边界、默认假设、收敛结论、待裁决分叉);scripts/check-decision-ledger.sh 用于机械校验台账结构(离线、只读;退出码 0 合规、1 不合规、2 用法错误),在自检前运行一次:bash scripts/check-decision-ledger.sh <台账文件>。回归测试通过 python3 -m pytest skills/clarification-protocol/tests -q 运行。

适用场景与限制

适用场景包括:目标宏观或含糊;存在多种技术路径;处于多轮问答中;已决项被换一种说法重开;需要在「问用户」与「登记默认假设」之间取舍;澄清轮次有失控迹象。不适用场景包括:单文件微调、指令明确的直接执行、只读检索类问答,这些情况直接执行即可。该规程未提供关于收费、价格或具体平台支持的信息。