用途
当任务中包含暂时无法确定的事实(例如未公开的字节布局、未确认的端口或字节序、当前还无法调用的外部 API、只有真实硬件或生产环境才能揭示的取值),而大部分工作并不真正依赖这些事实时,使用本技能。不要因此让整个项目停滞,也不要把猜测值散落到代码库各处;而是划定一条边界。
不适用的情况:未知本身就是整个任务(例如“还不知道要构建什么”),或者未知现在就能廉价解决(那就直接解决)。此外,不猜测并把它当作已确认来呈现;也不对已经确定的东西“为了保险”而抽象化(过度工程)。
心智模型
所有依赖稳定领域契约的部分现在就构建并测试。所有依赖未知的部分存在于一个适配器之后,默认采用有文档记录的最佳猜测,标记 verified:false,且可通过单次编辑替换。
流程:unknowns(⚠️ + 事实来源)→ 稳定契约(不含 ⚠️)→ 隔离(1 个配置 + 1 个适配器,verified:false)→ 在契约上完整构建核心 → 与契约一致的 mock → Adapt-kit(清单 + 一致性校验)→ 守护边界。
输入与输出契约
输入:任务与规格中带有 ⚠️“待验证”条目,且大部分工作不依赖未知;可选地为每个未知提供最佳猜测的文档(缺失时默认值仍须记录来源并 fail-safe)。
输出:契约(领域类型/接口),不含任何 ⚠️ 值;隔离配置与适配器,容纳所有未知,verified: false,每个 ASSUMPTION 值均有来源;核心与 mock 当天即可端到端运行(基于契约构建与测试);ADAPT-CHECKLIST 与一致性测试/向量,作为翻转 verified:true 前的门禁;交接说明,列明已构建并验证的部分、正在猜测的部分,以及每个 ⚠️ 的单文件收尾路径。
规则与能力
RULE-01(必须):适配器及其配置是未知存在的唯一位置。同一猜测出现在两个文件即为泄漏。
RULE-02(必须):每个猜测都要标记并注明来源。无论代码还是文字中,绝不把猜测呈现为已确认。
RULE-03(必须):verified:false 下的默认行为必须 fail-safe 而非乐观——在一致性验证证明之前假定猜测是错的(尤其涉及物理、金融或破坏性操作)。
RULE-04(必须):只隔离真正未知的部分。不要对确定的东西“以防万一”而抽象——那是过度工程,不是隔离。
RULE-05(必须):契约是下游工作依赖的交付物。保持稳定;有意识地扩展,而不是按猜测逐个扩展。
RULE-06(必须):在交接中明确说明:已构建并验证了什么、正在猜测并待定什么,以及收尾每个 ⚠️ 的单文件路径。
能力:读取已有规格/文档;编写项目代码(契约、核心、适配器、mock、测试);无需访问真实硬件或生产环境。
失效边界:未知就是整个任务(“还不知道要构建什么”)→ 不适用本技能,向用户澄清;未知现在就能廉价解决 → 直接查证,不隔离;同一猜测值出现在两处 → 隔离已破裂 → 在修复前阻塞(第 7 步);一致性未通过 → 保持 verified:false,默认行为 fail-safe(部分完成,并在交接中说明)。
使用方式(主工作流)
W01 判断:枚举未知,标记 ⚠️ 与事实来源。能廉价查到的就不是未知。
W02 判断:定义稳定边界(契约),契约不得包含任何 ⚠️ 值,否则重做。
W03 执行:隔离——1 个配置 + 1 个适配器,最佳猜测 + verified: false。
W04 执行:在边界之上完整构建一切(UI、业务逻辑、传输、安全/错误处理、校验),全部基于契约编写并测试,绝不导入被隔离的值。
W05 执行:构建与契约一致的 mock/stub,使整个系统今天即可端到端运行;让 mock 遵循同一适配器/配置,从而兼作后续的一致性测试装置。
W06 执行:交付 Adapt-kit——(a)简短的 ADAPT-CHECKLIST,即未知确认后的确切收尾步骤(改配置 → 改适配器 → 运行一致性 → 翻转 verified:true);(b)在猜测值被信任用于生产或真实硬件之前必须通过的一致性测试/向量。
W07 确定性:守护边界——添加 lint 规则或审查备注,确保被隔离的值不会越过适配器。如果猜测常量出现在两处,说明隔离已破裂,在继续前先修复。
分支:B01 恢复——W07 发现同一猜测值出现在两处时,将其移回适配器/配置并删除第二处,随后回到 W07;B02 条件必需——若项目存在 llmwiki/,撰写草稿报告(见 Delivery 部分),否则跳过并结束。
验证与停止:确定性——核心 + mock 的端到端测试在契约上全部通过;一致性测试/向量是翻转 verified:true 的唯一门禁。需人工审查——契约不含 ⚠️,边界不泄漏(lint 规则或审查备注)。当交接中完整列出“已构建/已验证”与“猜测/待定”时停止。
适用场景
正面示例:lite3-controller-ui——协议 MotionSDK(命令码、字节偏移、字节序、端口)尚未与真实硬件核实 → 契约采用 SemanticCommand/Telemetry,隔离 protocol.config + motionsdk-codec,UI/WS/桥接/安全全部构建完成,使用 UDP mock 主机实现离线端到端,Adapt-kit 使协议收尾变成修改一个文件。
边界/失败示例:用户说“还不知道这个应用做什么,先构建再说” → 未知即整个任务 → 不适用本技能,先澄清需求。支付网关的线格式未知时,默认 verified:false 必须拒绝真实交易(fail-safe),不能假定成功。
参考模板与交付
快速模板(按技术栈调整):contract/ 为稳定领域类型(不含未知值,现在构建并测试);core/ 基于契约的 UI/逻辑/传输/安全(现在构建并测试);adapter/ 下 config.* 存放全部未知常量与 verified:false,codec.* 针对未知进行编解码(隔离,单文件替换);mock/ 使用同一适配器实现离线端到端与一致性测试装置;ADAPT-CHECKLIST.* 为 5 步收尾流程;conformance.* 为门禁 verified:true 的向量。
Delivery(输出报告,仅当项目存在 llmwiki/ 时):工作完成后撰写草稿报告以便决策可追溯。文件名 llmwiki/wiki/draft/orca/DDMMYY-<ten>.md(DDMMYY 为当天日期,<ten> 为 2–4 个 kebab 词),写入包含 type、title、status、tags、timestamp 的 front matter 与标题区,并分节记录 What(一句话说明本次构建了什么与隔离了什么)、Boundary(契约与被隔离的配置+适配器文件)、Unknowns(⚠️ 待验证表格:未知项、最佳猜测来源、收尾方式)、Files(文件与操作表格)、Notes(注明通过 /build-now-adapt-later 技能调用)、Origin(草稿路径、commit、提升日期,由 verify-before-commit 填写)。最后在 llmwiki/wiki/index.md 追加一行,并在 llmwiki/wiki/log.md 追加一条。
限制
资料未提供该技能的具体收费、价格、平台支持范围或效果保证;不猜测并呈现为已确认是该技能的核心约束,任何猜测值在生产/真实硬件使用前必须通过一致性门禁。除上述模板与示例外,未提供其他实现细节。