提案与证据

第 4 课 · 共 6 课 约 8 分钟

触发原因、改动、验证、影响面、是否破坏性：谁写哪一部分；提案要小；开完提案之后做什么。

本课目标

读完这一课，你将能够

  • 说出提案证据的五个部分，以及哪些由智能体写、哪些由平台算
  • 写出一条带触发原因和自测结果的 aidc semantic branch propose 命令
  • 判断一份提案该不该拆小，并知道开完提案之后智能体该做什么

提案是一份让人审得动的论据

分支写好、自测过了，下一步是开提案。本课按默认 review 策略演示，由人审核。提案（Proposal）像一次代码评审：审核的人只看得到提案里摆出的证据，所以每份提案带五样证据。

TRIGGER

触发原因

智能体写。哪个问题答不出，接了哪个新数据源。

CHANGES

改动

平台算。按资源列出新建、修改、删除了什么，每个资源是一项审核。

VALIDATION

验证

合并检查的结果，加上智能体自己写的自测结果。

IMPACT

影响面

平台算。最近 30 天这些类型被读写了多少次、有多少活跃用户，哪些应用登记了它们。

BREAKING

是否破坏性

平台算。破坏性改动单独标出，连同受影响的下游应用。

分工是有意的：智能体写「为什么」和「我测了什么」，平台算「改了什么」「影响谁」「破不破坏」。智能体不给自己的作业打分。

影响面这一项，要会读。一个类型 30 天里没人读写，改它的风险小。有几个应用在自己的清单里登记了它，改它就得先想到这几个应用。审核的人看的正是这个：改的东西有多少人在用。

写触发原因和自测结果

采购智能体把上一节的分支交出去。触发原因沿用发现那一节写好的那句，再补上自测结果。触发原因要能单独读懂，因为审核的人可能是第一次听说这件事：

aidc semantic branch propose delivery-promise \
  --title "加交期承诺对象类型" \
  --trigger "采购员本周三次问「哪些供应商在哪些物料上晚了」，答不出：说明书里没有交期承诺；po-promises 流在送数据，但没有对象类型接它" \
  --self-test "分支上 validate 为 VALID；object-types DeliveryPromise、links purchaseOrder promises 都能读到；数据尚未绑定，对象数为 0，合并后用 SQL 复核" \
  --json

自测结果有一条硬规矩：写清楚没验证的。上面这条明说「数据尚未绑定」，审核的人就知道合并后该看哪里。一份写满「全部通过」的自测，反而让人不放心。

更好的自测是一份问题清单：每个问题写「答出来了没有」和「走的哪条路径」。SDK 的提案证据里有专门的 questions 字段；命令行目前只有 --self-test 一段文字，就把问题清单写进这段文字里。

提案要小

一份提案只解决一个问题。原因很实际：提案里每个资源是一项审核，任何一项被拒绝就挡住整份合并。把三件不相干的事捆在一起，最弱的一项会拖住另外两项。

大而杂的提案小而准的提案
审核人要同时想清楚三个问题一个问题，一次看完
被拒绝时整份等着重做只重做这一件事
出问题时不知道该查哪一部分一份提案对应一个语义版本，一目了然

还有一条顺序上的规矩：先把分支改到位、validate 通过，再开提案。提案打开之后，如果智能体又改了分支，被改到的那一项要重新审。一个分支同一时间只有一个打开的提案。

开完提案之后

命令的输出里有 reviewUrl，这是给人的审核地址。智能体的下一步是把地址交给人，然后去做别的事，不要在终端里循环等待。交给人的话写三样：提案标题、一句话说明它解决什么、审核地址。

过一会儿，用下面的命令看一眼进度。审核意见要改的话，回分支上改；想撤回，就关掉这份提案。

aidc semantic proposals --status OPEN
aidc semantic proposal <提案 id>
aidc semantic proposal close <提案 id> --note "改用另一个方案"

要点

  • 提案带五样证据：触发原因、改动、验证、影响面、是否破坏性。
  • 智能体写触发原因和自测结果，平台算改动、影响面（30 天）和破坏性；智能体不给自己打分。
  • 自测要写清没验证的部分；更好的自测是一份问题清单。
  • 一份提案只解决一个问题：任何一项被拒绝就挡住整份合并。
  • 开完提案，把审核地址交给人再去做别的事，不在终端里循环等。

练一练

替智能体写一份提案

沿用上一节的分支，或者你自己的分支。

写出完整的 aidc semantic branch propose：标题、触发原因、自测结果。自测里至少有一句「没验证什么」。

小测

选一个答案，马上看解析。

Q1提案证据里，哪一部分是智能体自己写的？

Q2为什么一份提案最好只解决一个问题？

Q3自测时新类型还没有数据，自测结果该怎么写？

延伸阅读