feat(studio+docs): 验收核验状态可视化 + 文档 + compose 提示词注明真核验

jnMetaCode · jnMetaCode · commit 8ae801f6af1c · 2026-07-17T12:57:33.000+08:00
Q1 acceptance 自动核验的第二期（展示与文档）： - Studio 实时运行：步骤行的「验收 ✓/⚠️」拆成彩色徽章（绿=通过/琥珀=未满足）； 核验未满足条目由服务端拦成 step-verify-item 事件，独立卡片展示， 不再混入步骤正文（复制/下载的产出保持干净） - Studio 运行历史：步骤行显示核验徽章（hover 提示是否返工过）， 展开详情时未满足条目在验收标准卡片下方逐条列出（metadata.verification 透传） - 文档站新增「验收与自动核验」页（迭代优化分组）：acceptance 字段写法、 核验+返工机制与设计底线、三级开关；YAML 字段说明补 acceptance/verify 条目 - compose 提示词（中英）注明 acceptance 会被逐条真核验+未过自动返工， 要求每条仅凭产出文本即可客观判定 已实测：真实 claude-code 走 web SSE 全链路——step-done meta 带「验收 ⚠️ 1 条 未满足（已返工 1 轮）」、step-verify-item 事件携带未满足条目、正文无 ⚠️ 混入； 历史 API verification 字段完整透传
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 ### Added（本次新增）
 - **acceptance 自动核验 + 一轮自动返工（默认开）**：写了 `acceptance:` 的步骤产出后，用同一 provider 逐条核对验收标准——未过则把「上一版产出 + 未满足条目」交回同一专家针对性返工一轮再复核。验收从"注入 prompt 的嘱咐"升级为"跑完真的有人对着查"的机制。验收不过是质量信号而非执行错误：步骤不会因此失败，最坏得到带 ⚠️ 标记的返工版照常流向下游；核验器自身故障（网络/解析失败）自动跳过核验不拦产线。核验状态（通过/返工后通过/仍有 N 条未满足）进 CLI 结果行、summary.md、metadata.json 与步骤文件头。三级开关：CLI `--verify`/`--no-verify` > YAML 顶层 `verify:` > 步骤级 `verify: false`（默认开，仅影响写了 acceptance 的步骤）；核验/返工消耗如实计入该步 token 成本。
+- **Studio 验收徽章**：实时运行与历史详情的步骤行显示核验状态徽章（绿 = 验收 ✓ / 琥珀 = ⚠️ N 条未满足，hover 提示是否返工过）；未满足条目在实时视图拦成独立卡片展示，不再混入步骤正文。文档站新增「验收与自动核验」页；自动组队提示词同步注明 acceptance 会被逐条真核验，要求每条仅凭产出文本即可客观判定。
 
 ## [0.10.0] - 2026-07-12
 
diff --git a/src/cli/compose.ts b/src/cli/compose.ts
@@ -228,7 +228,7 @@ ${autoRun ? '      Include specific information from the user\'s description' :
 - **Detailed tasks**: Task descriptions should be specific — tell the role what to do and what format to output
 ${inputsDesignPrinciple}
 - **Use human_input when the user needs to clarify something — don't have a role "ask" in its task**: if the task genuinely can't proceed without more info from the user (personal preference, choosing between options, a specific detail not in inputs — classic case: registration/enrollment-type requests where you must ask the user's specifics partway through), insert a \`type: human_input\` step to ask them, and feed the answer downstream as its output variable. Writing "ask the user X" inside a regular role step's task does NOT work — the engine won't actually pause, the model will just make up an answer
-- **Acceptance criteria**: give key steps — at minimum the FINAL deliverable step — an \`acceptance:\` field with 2-5 verifiable conditions the output must satisfy. Concrete and checkable ("contains X/Y/Z sections", "every recommendation states its risk"), never vague ("high quality"). It is injected into the step's prompt and used as the review yardstick
+- **Acceptance criteria**: give key steps — at minimum the FINAL deliverable step — an \`acceptance:\` field with 2-5 verifiable conditions the output must satisfy. Concrete and checkable ("contains X/Y/Z sections", "every recommendation states its risk"), never vague ("high quality"). It is injected into the step's prompt AND actually enforced: after the step runs, the engine checks the output against each item, and any unmet item triggers one automatic rework round — so every item must be objectively machine-checkable from the output text alone
 - **High-risk tasks need an approval gate**: for finance/investment, medical, legal, or anything spending real money / hard to reverse — insert a \`type: approval\` step before the final recommendation/execution step, so the user signs off before proceeding
 - **Final deliverable**: The last step must output the final deliverable the user wants (e.g., complete article, complete report), not review comments or suggestions. If there's a review step, it should output the revised final version, not a "list of suggestions"
 - **Clean final output (IMPORTANT)**: The LAST step's \`task\` MUST end with an explicit instruction to output ONLY the deliverable itself — no preamble/greeting, no "what I changed"/change-log, no formatting notes, no questions to the user, no suggestions to run \`ao\`/other commands, no "shall I continue?" closers. Append a line like: "⚠️ Output only the final deliverable itself — no preamble, no change-log, no meta-commentary, no questions, no tool/command suggestions." (If you genuinely need to ask the user something, use the human_input step above instead — not in the final step)
@@ -347,7 +347,7 @@ ${autoRun ? '      直接包含用户需求中的具体信息' : '      使用 {
 - **任务详细**：task 描述要具体，告诉角色要做什么、输出什么格式
 ${inputsDesignPrinciple}
 - **需要用户澄清时用 human_input，不要指望角色在 task 里"提问"**：如果任务本质上需要用户提供额外信息才能继续（如个人偏好、多个方案里选一个、inputs 里没给的具体细节——典型例子是报名/选课/选方案类需求，中途必须问用户具体情况），插入一个 \`type: human_input\` 的步骤向用户提问，把回答作为 output 变量给下游用。普通 role 步骤的 task 里写"请问用户 XXX"是无效的——引擎不会暂停等回答，模型只会自己编一个答案
-- **验收标准**：给关键步骤——至少是最终交付步——写 \`acceptance:\` 字段，列 2-5 条产出必须满足的可核对条件。要具体可查（"包含 X/Y/Z 三节""每条建议都标注风险"），不要空话（"高质量"）。它会注入该步 prompt 并作为评审的统一尺子
+- **验收标准**：给关键步骤——至少是最终交付步——写 \`acceptance:\` 字段，列 2-5 条产出必须满足的可核对条件。要具体可查（"包含 X/Y/Z 三节""每条建议都标注风险"），不要空话（"高质量"）。它不只注入该步 prompt——步骤跑完后引擎会**逐条真核验**，未过自动返工一轮。所以每一条都必须是仅凭产出文本就能客观判定的
 - **高风险任务要加签字闸门**：涉及金融/投资、医疗、法律，或花真金白银、难以撤销的操作——在最终建议/执行步骤之前插入 \`type: approval\` 节点，让用户签字放行后才继续（重大决策必须老板拍板）
 - **最终成品**：最后一个步骤必须输出用户想要的最终成品（如完整文章、完整报告），而不是审查意见或修改建议。如果有审校步骤，审校步骤应该直接输出修改后的定稿，而不是"修改建议列表"
 - **干净的最终产出（重要）**：最后一个步骤的 \`task\` 结尾必须显式要求"只输出成品本身"——不要开场白/寒暄、不要"我改了什么/复盘/修改说明"、不要排版备注小节、不要向用户提问或请其拍板、不要建议运行 \`ao\` 或其它命令、不要"要我继续吗"之类收尾。请在该 step 的 task 末尾追加一行类似：「⚠️ 只输出最终成品本身：不要开场白、不要复盘或说明、不要向用户提问、不要建议任何命令或后续动作。」（需要问用户时用上面的 human_input 步骤，不要在最终步骤里问）
diff --git a/web/server.js b/web/server.js
@@ -582,6 +582,9 @@ app.post('/api/run', (req, res) => {
   // Parse CLI output into structured events
   let lineBuffer = '';
   let currentStepId = null;
+  // 验收未过时，"完成 | … | 验收 ⚠️" 行之后紧跟若干 "⚠️ 未满足条目" 行——
+  // 它们是核验详情而非步骤产出，转成 step-verify-item 事件，别混进正文。
+  let inVerifyItems = false;
 
   function parseLine(raw) {
     const clean = raw.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '').replace(/\r/g, '').trim();
@@ -617,10 +620,18 @@ app.post('/api/run', (req, res) => {
     // currentStepId set here — clearing it would drop the whole step body.
     const metaMatch = clean.match(/^完成\s*\|\s*(.+)/);
     if (metaMatch && currentStepId) {
+      inVerifyItems = /验收\s*⚠️/.test(metaMatch[1]);
       send('step-done', { id: currentStepId, meta: metaMatch[1] });
       return;
     }
 
+    // Verification detail lines right after a "完成 | … | 验收 ⚠️" line
+    if (inVerifyItems && currentStepId && /^⚠️\s*/.test(clean)) {
+      send('step-verify-item', { id: currentStepId, text: clean.replace(/^⚠️\s*/, '') });
+      return;
+    }
+    inVerifyItems = false;
+
     // Workflow summary: "完成: 5/5 步 | ..." — end of all step output.
     if (/完成:\s*\d+\/\d+\s*步/.test(clean)) {
       send('workflow-summary', { text: clean });
diff --git a/website/src/components/studio/RunManager.tsx b/website/src/components/studio/RunManager.tsx
@@ -20,6 +20,8 @@ export interface LiveStep {
   total?: number;
   content: string;
   meta?: string;
+  /** 验收核验未满足的条目（来自 step-verify-item 事件），展示为核验详情而非正文 */
+  verifyItems?: string[];
   status: StepStatus;
 }
 
@@ -213,6 +215,12 @@ export function RunProvider({ children }: { children: ReactNode }) {
               upsert(data.id, { meta: data.meta, status: "done" });
             }
             break;
+          case "step-verify-item": {
+            const i = inst.steps.findIndex((s) => s.id === data.id);
+            const prev = i >= 0 ? inst.steps[i].verifyItems ?? [] : [];
+            upsert(data.id, { verifyItems: [...prev, data.text] });
+            break;
+          }
           case "workflow-summary":
             inst.summary = data.text;
             break;
diff --git a/website/src/components/studio/RunsPanel.tsx b/website/src/components/studio/RunsPanel.tsx
@@ -144,6 +144,19 @@ function DetailPane({ id, provider, onRun }: { id: string; provider: string; onR
                   {isFinal && <span className="shrink-0 rounded-full bg-primary/15 px-2 py-0.5 text-[11px] font-semibold text-primary">✦ {t.studio.runs.finalResult}</span>}
                   {s.status === "failed" && <span className="shrink-0 rounded-full bg-red-500/15 px-2 py-0.5 text-[11px] font-semibold text-red-500">{t.studio.runs.stepFailed}</span>}
                   {s.status === "skipped" && <span className="shrink-0 rounded-full bg-muted px-2 py-0.5 text-[11px] text-muted-foreground">{t.studio.runs.stepSkipped}</span>}
+                  {s.verification && (
+                    <span
+                      className={cn(
+                        "shrink-0 rounded-full px-2 py-0.5 text-[11px] font-semibold",
+                        s.verification.pass ? "bg-emerald-500/15 text-emerald-600 dark:text-emerald-400" : "bg-amber-500/15 text-amber-600 dark:text-amber-400",
+                      )}
+                      title={s.verification.reworked ? t.studio.runs.verifyReworkedTitle : undefined}
+                    >
+                      {s.verification.pass
+                        ? `${t.studio.runs.verifyPass}${s.verification.reworked ? t.studio.runs.verifyReworkedSuffix : ""}`
+                        : `${t.studio.runs.verifyFailPrefix}${s.verification.failed.length}${t.studio.runs.verifyFailSuffix}`}
+                    </span>
+                  )}
                   {s.duration && <span className="shrink-0 text-xs text-muted-foreground">{s.duration}</span>}
                 </button>
                 <div className="flex shrink-0 items-center gap-1.5">
@@ -190,6 +203,16 @@ function DetailPane({ id, provider, onRun }: { id: string; provider: string; onR
                       <p className="mt-1 whitespace-pre-wrap leading-relaxed text-muted-foreground">{s.acceptance}</p>
                     </div>
                   )}
+                  {s.verification && !s.verification.pass && s.verification.failed.length > 0 && (
+                    <div className="mb-2.5 rounded-lg border border-amber-500/30 bg-amber-500/[0.06] px-3 py-2 text-xs">
+                      <span className="font-semibold text-amber-600 dark:text-amber-400">{t.studio.runs.verifyUnmetTitle}</span>
+                      <ul className="mt-1 space-y-0.5 leading-relaxed text-muted-foreground">
+                        {s.verification.failed.map((f, fi) => (
+                          <li key={fi}>· {f}</li>
+                        ))}
+                      </ul>
+                    </div>
+                  )}
                   <Markdown>{s.content}</Markdown>
                 </div>
               )}
diff --git a/website/src/components/studio/StepList.tsx b/website/src/components/studio/StepList.tsx
@@ -23,6 +23,11 @@ export function StepList({
       {steps.map((s) => {
         const running = s.status === "running";
         const pending = s.status === "pending";
+        // CLI 结果行形如 "33.1s | 345 tokens | 验收 ✓"——把验收段拆出来做成彩色徽章
+        const verifMatch = s.meta?.match(/^(.*?)(?:\s*\|\s*)?(验收\s*[✓⚠️].*)$/);
+        const baseMeta = verifMatch ? verifMatch[1] : s.meta;
+        const verifText = verifMatch?.[2];
+        const verifPass = verifText?.includes("✓");
         return (
           <div
             key={s.id}
@@ -50,7 +55,17 @@ export function StepList({
                 {s.status === "done" && <Check className="size-3.5 shrink-0 text-emerald-500" />}
               </div>
               <div className="flex shrink-0 items-center gap-1.5">
-                {s.meta && <span className="hidden text-xs text-muted-foreground sm:inline">{s.meta}</span>}
+                {baseMeta && <span className="hidden text-xs text-muted-foreground sm:inline">{baseMeta}</span>}
+                {verifText && (
+                  <span
+                    className={cn(
+                      "shrink-0 rounded-full px-2 py-0.5 text-[11px] font-semibold",
+                      verifPass ? "bg-emerald-500/15 text-emerald-600 dark:text-emerald-400" : "bg-amber-500/15 text-amber-600 dark:text-amber-400",
+                    )}
+                  >
+                    {verifText}
+                  </span>
+                )}
                 {s.content && <CopyButton value={s.content} label={t.studio.shell.copy} copiedLabel={t.studio.shell.copied} />}
                 {s.content && (
                   <button
@@ -65,6 +80,17 @@ export function StepList({
               </div>
             </div>
 
+            {!pending && !!s.verifyItems?.length && (
+              <div className="border-t border-border/60 bg-amber-500/[0.06] px-4 py-2.5 text-xs">
+                <span className="font-semibold text-amber-600 dark:text-amber-400">{t.studio.shell.verifyUnmet}</span>
+                <ul className="mt-1 space-y-0.5 text-muted-foreground">
+                  {s.verifyItems.map((it, i) => (
+                    <li key={i}>· {it}</li>
+                  ))}
+                </ul>
+              </div>
+            )}
+
             {!pending && (
               <div className="max-h-[460px] overflow-auto border-t border-border/60 px-4 py-3">
                 {s.content ? (
diff --git a/website/src/content/docs.ts b/website/src/content/docs.ts
@@ -183,8 +183,8 @@ steps:
           {
             heading: { zh: "字段说明", en: "Field reference" },
             body: {
-              zh: "- `id`：步骤唯一标识，被 `depends_on` 引用\n- `role`：专家，格式 `category/role-name`\n- `task`：任务描述，可用 `{{变量}}` 插值\n- `output`：把本步产出存成变量，供下游引用\n- `depends_on`：依赖的步骤数组，决定 DAG\n- `condition`：条件执行（见「循环与条件」）\n- `loop`：循环块（见「循环与条件」）",
-              en: "- `id`: unique step id, referenced by `depends_on`\n- `role`: an expert, as `category/role-name`\n- `task`: the task, with `{{var}}` interpolation\n- `output`: save this step's output as a variable for downstream\n- `depends_on`: array of step deps, defines the DAG\n- `condition`: conditional execution (see Loops & conditions)\n- `loop`: loop block (see Loops & conditions)",
+              zh: "- `id`：步骤唯一标识，被 `depends_on` 引用\n- `role`：专家，格式 `category/role-name`\n- `task`：任务描述，可用 `{{变量}}` 插值\n- `output`：把本步产出存成变量，供下游引用\n- `depends_on`：依赖的步骤数组，决定 DAG\n- `condition`：条件执行（见「循环与条件」）\n- `loop`：循环块（见「循环与条件」）\n- `acceptance`：验收标准，跑完自动核验（见「验收与自动核验」）\n- `verify: false`：本步关闭自动核验",
+              en: "- `id`: unique step id, referenced by `depends_on`\n- `role`: an expert, as `category/role-name`\n- `task`: the task, with `{{var}}` interpolation\n- `output`: save this step's output as a variable for downstream\n- `depends_on`: array of step deps, defines the DAG\n- `condition`: conditional execution (see Loops & conditions)\n- `loop`: loop block (see Loops & conditions)\n- `acceptance`: acceptance criteria, auto-verified after the step runs (see Acceptance & auto-verify)\n- `verify: false`: opt this step out of auto-verify",
             },
           },
           {
@@ -309,6 +309,42 @@ steps:
           },
         ],
       },
+      {
+        slug: "acceptance",
+        title: { zh: "验收与自动核验", en: "Acceptance & auto-verify" },
+        sections: [
+          {
+            heading: { zh: "acceptance 字段", en: "The acceptance field" },
+            body: {
+              zh: "给关键步骤（至少是最终交付步）写 `acceptance:`，列 2-5 条产出必须满足的**可核对**条件——要具体可查（「包含 X/Y/Z 三节」「每条建议标注风险」），不要空话（「高质量」）。它会注入该步 prompt 末尾，并在 `--compare` 盲评时作为评分锚点。",
+              en: "Give key steps (at minimum the final deliverable step) an `acceptance:` field: 2-5 **checkable** conditions the output must satisfy — concrete ('contains sections X/Y/Z', 'every recommendation states its risk'), never vague ('high quality'). It is injected at the step's prompt tail and anchors the blind judge in `--compare`.",
+            },
+            code: `  - id: write_report
+    role: "product/product-analyst"
+    task: "基于 {{research}} 写投资分析报告"
+    acceptance: |
+      1. 包含「机会 / 风险 / 建议」三节
+      2. 每条建议都标注风险等级
+      3. 结尾给出明确的行动清单
+    output: report`,
+          },
+          {
+            heading: { zh: "自动核验 + 一轮自动返工（默认开）", en: "Auto-verify + one rework round (on by default)" },
+            body: {
+              zh: "写了 `acceptance` 的步骤跑完后，引擎用同一 provider **逐条核对**验收标准；未过则把「上一版产出 + 未满足条目」交回同一专家针对性返工一轮再复核。验收从「注入 prompt 的嘱咐」变成「跑完真的有人对着查」的机制。\n\n验收不过是**质量信号**而非执行错误：步骤不会因此失败，最坏得到带 ⚠️ 标记的返工版照常流向下游；核验器自身故障会自动跳过核验，不拦产线。核验状态显示在 CLI 结果行、`summary.md`、`metadata.json` 与 Studio 的运行/历史面板。",
+              en: "After a step with `acceptance` runs, the engine **checks each item** with the same provider; on failure it hands the previous output + unmet items back to the same expert for one targeted rework round, then re-checks. Acceptance goes from 'a note injected into the prompt' to 'someone actually checks after the run'.\n\nA failed check is a **quality signal**, not an execution error: the step never fails because of it — worst case a ⚠️-flagged reworked version flows downstream as usual; if the verifier itself errors, verification is skipped without blocking the pipeline. Verification status shows in the CLI result line, `summary.md`, `metadata.json`, and the Studio run/history panels.",
+            },
+          },
+          {
+            heading: { zh: "三级开关", en: "Three-level switch" },
+            body: {
+              zh: "优先级从高到低：CLI `--verify` / `--no-verify` > YAML 顶层 `verify:` > 步骤级 `verify: false`。默认开，只影响写了 `acceptance` 的步骤；核验/返工消耗如实计入该步 token 成本（单次核验是 max_tokens 500 的小额调用）。",
+              en: "Priority high to low: CLI `--verify` / `--no-verify` > top-level `verify:` in YAML > per-step `verify: false`. On by default and only affects steps that declare `acceptance`; verify/rework usage counts toward that step's token cost (a single check is a small max_tokens-500 call).",
+            },
+            code: "ao run workflow.yaml --no-verify   # 本次运行关闭自动核验",
+          },
+        ],
+      },
     ],
   },
   {
diff --git a/website/src/i18n/translations.ts b/website/src/i18n/translations.ts
diff --git a/website/src/lib/studio.ts b/website/src/lib/studio.ts
