A2-A7 全部补齐到验收线;顺手把几处「门拦住却不给路」的坑填了

活动:A2 选型 / A3 寻源 / A4 定价 / A6 议价 / A7 归档五件各补成真活动包 ——
契约宽进(input.required 空,归一在活动内)、台账必填声明(含行级 requiredWhen)、
入场哨兵与 L1/L2 判据一律读基座数、两份件(在办可编辑 + 办结静态快照)、
三案例常备、包内自测。e2e 各三案例 released、行动被拒 0、发口正确、提交闸每单真拦。

基座(共享面,改一处影响所有活动,故每处都带回归):
· 重发判断走在站上场之前 —— 人答完那步常已收掉,readyToWork 先抛「不能再往它上面挂活」,
  于是「重发已答过的卡 = 无事发生」这条唯一活路在最需要时够不着,A1 基线当场熔断;
· 决策卡补幂等兜底(与执行工单同一把尺):头两次无事发生,第三次起才算被拒;
· 输出没成形先就地重问一次,原话进工作日志、不再摆上卡面;
· 工具调用读数 tool_<名>_calls —— 「机检只读基座数」这条纪律第一次覆盖到工具;
· 执行卡 steps/standard 补进出参 schema(从前能到卡面全靠厂商 JSON 模式宽松);
· 件的就地更新改逐节点 morph,保存先把新值镜像进只读那份 —— 不闪、不等回声。

A1(基线,全程守住):措辞三档对齐(必填/建议/选填)、禁止拿历史价当客户目标价、
卡骨架从步骤剧本搬进说明书(压成一拍连做时剧本没摊开,会发出没有指导书的裸卡)。

契约两处**新增可选字段**(非破坏):FieldDeclaration.requiredWhen、工单 finalHtml;
api-report 同批更新。docs/adr 与 docs/archive 的 13 份文件在工作树里不见了,
本次予以恢复而非提交删除。

门禁:typecheck / lint / depcruise / test(1366)全绿。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

apps/api/src/app/__tests__/agent-action-normalize.test.ts

@@ -81,13 +81,13 @@ describe('写行的形状', () => {
 });
 
 describe('看不懂就转人,不猜着动手', () => {
-  it('行动型不认识 → 发执行卡,并把**模型原话**摆上去', () => {
-    const action = normalizeAction({ kind: '我自己想的行动' }, ENABLED, '{"kind":"我自己想的行动"}');
+  it('行动型不认识 → 发执行卡,卡面只说人话 —— JSON 原话归工作日志,不上卡', () => {
+    const action = normalizeAction({ kind: '我自己想的行动' }, ENABLED);
     expect(action.kind).toBe('human');
     if (action.kind !== 'human') return;
-    expect(action.card['reason']).toBe('模型未给出合规的行动');
-    // 只写「不合规」的话,收卡的人分不清是模型跑偏、行动型少了一种、还是提示词没交代清楚
-    expect(String(action.card['modelReply'])).toContain('我自己想的行动');
+    // 2026-08-03 实测:原话上卡,人看到的是一坨代码(「卡片里又是乱七八糟的东西」)
+    expect(action.card['modelReply']).toBeUndefined();
+    expect(String(action.card['reason'])).toContain('工作日志');
     expect(action.card['kindSeen']).toBe('我自己想的行动');
   });
 
@@ -98,44 +98,38 @@ describe('看不懂就转人,不猜着动手', () => {
 });
 
 /**
- * 补全卡的格子在哪儿 —— **两处都认**。
- *
- * 提示词里执行工单的写法是 `card.fields`,模型很自然把补全卡也那么写(实测就是),
- * 于是每一拍都被「fields 为空」拒回来。空不空由引擎验,这里只负责不让一个位置差异吃掉一整拍。
+ * **补全卡已全局退役**(2026-08-02 用户定:「彻底全局退役补全卡,执行卡完全就是
+ * 包含补全语义的人类工具」)—— 归一层把旧输出里的 `ask` 原地转成零输入执行工单:
+ * 问句上卡,字段名并进指导书(人补在工作区的件上),`fields` 不上卡。
+ * 拒回只会让模型换着花样再发,归一才是把路铺平。
  */
-describe('补全卡的格子', () => {
-  const fieldsOf = (raw: Record<string, unknown>) => {
-    const a = normalizeAction({ kind: 'ask', itemId: 'T1', ...raw }, ENABLED);
-    return a.kind === 'ask' ? a.fields : [];
-  };
+describe('补全卡退役:ask 原地转成零输入执行工单', () => {
+  const norm = (raw: Record<string, unknown>) => normalizeAction({ kind: 'ask', itemId: 'T1', ...raw }, ENABLED);
 
-  it('顶层 fields', () => {
-    expect(fieldsOf({ ask: '补一下', fields: [{ key: 'lead_time', label: '交期' }] })).toEqual([
-      { key: 'lead_time', label: '交期' },
-    ]);
+  it('转成 human + execution,问句在 ask,字段名进指导书', () => {
+    const a = norm({ ask: '缺交期,补一下', fields: [{ key: 'lead_time', label: '交期' }] });
+    expect(a.kind).toBe('human');
+    if (a.kind !== 'human') return;
+    expect(a.workOrder).toBe('execution');
+    const card = a.card as Record<string, unknown>;
+    expect(card['ask']).toBe('缺交期,补一下');
+    expect(JSON.stringify(card['steps'])).toContain('交期');
+    // 零输入:fields 不上卡
+    expect(card['fields']).toBeUndefined();
   });
 
-  it('落在 card 里也认(实测模型这么写过)', () => {
-    expect(fieldsOf({ card: { ask: '补一下', fields: [{ key: 'eau', label: '年用量' }] } })).toEqual([
-      { key: 'eau', label: '年用量' },
-    ]);
+  it('fields 落在 card 里也认(旧模型这么写过)—— 一样进指导书', () => {
+    const a = norm({ card: { ask: '补一下', fields: [{ key: 'eau', label: '年用量' }] } });
+    expect(a.kind).toBe('human');
+    if (a.kind !== 'human') return;
+    expect(JSON.stringify((a.card as Record<string, unknown>)['steps'])).toContain('年用量');
   });
 
-  it('写成一串字段名也认 —— label 用 key 顶上,宁可显示字段名不显示空白', () => {
-    expect(fieldsOf({ ask: 'x', fields: ['eau', 'lead_time'] })).toEqual([
-      { key: 'eau', label: 'eau' },
-      { key: 'lead_time', label: 'lead_time' },
-    ]);
-  });
-
-  it('没有 key 的格子丢掉 —— 没有 key 就没法回填', () => {
-    expect(fieldsOf({ ask: 'x', fields: [{ label: '只有标签' }, { key: 'ok', label: '行' }] })).toEqual([
-      { key: 'ok', label: '行' },
-    ]);
-  });
-
-  it('一个都收不到就是空数组,交引擎拒(不替它编格子)', () => {
-    expect(fieldsOf({ ask: 'x' })).toEqual([]);
+  it('连问句都没有:兜一个标题,不吃掉整拍', () => {
+    const a = norm({});
+    expect(a.kind).toBe('human');
+    if (a.kind !== 'human') return;
+    expect(String((a.card as Record<string, unknown>)['title'])).not.toBe('');
   });
 });
 
@@ -209,10 +203,16 @@ describe('一拍一串行动的归一', () => {
     expect(turn.actions.map((a) => a.kind)).toEqual(['finish']);
   });
 
-  it('整串一个都不认识 → 单张转人卡,模型原话摆上去', () => {
-    const turn = normalizeTurn({ actions: [{ kind: '胡编的' }] }, ENABLED, '{"kind":"胡编的"}');
+  it('整串一个都不认识 → 标 unrecognized(decide 先就地重问)+ 单张转人卡兜底', () => {
+    const turn = normalizeTurn({ actions: [{ kind: '胡编的' }] }, ENABLED);
     expect(turn.actions).toHaveLength(1);
     expect(turn.actions[0]?.kind).toBe('human');
+    expect(turn.unrecognized).toBe(true);
+  });
+
+  it('认出了行动就不标 unrecognized —— 别把好拍拿去白重问一遍', () => {
+    const turn = normalizeTurn({ actions: [{ kind: 'finish', itemId: 'T1' }] }, ENABLED);
+    expect(turn.unrecognized).toBeUndefined();
   });
 
   it('超出封顶截到 6 个 —— 引擎侧还会再守一道', () => {

apps/api/src/app/__tests__/agent-runner-retry.test.ts

@@ -0,0 +1,108 @@
+/**
+ * 输出不成形的就地重问(2026-08-03 用户实测送来的单逼出来的)。
+ *
+ * 病:关思考的模型偶发把一拍输出写坏(整串行动一个都不认识),从前一次没认出
+ * 就直接发「需要你判断下一步」的兜底卡,还把 JSON 原话整段摆在卡面上 ——
+ * 人打开工单看到的是一坨代码(用户原话:「卡片里又是乱七八糟的东西」)。
+ *
+ * 法:第一次没认出 → 原文经 `note` 存进工作日志(内部痕),附「只输出 JSON」
+ * 就地再问一次;第二次仍不成形才交人,卡面只说人话、不摆原话。
+ * 这里用假网关钉死三件事:重问只有一次、原文进痕、好输出不白重问。
+ * (ModelGateway 是外界 —— LLM 厂商 —— 的缝,录制回放替身合规。)
+ */
+import { describe, expect, it } from 'vitest';
+import type { EnabledSet } from '@modules/loop-engine';
+import type { ModelCall, ModelGateway, ModelResult } from '@modules/llm';
+import type { TaskId } from '@contracts';
+import { createAgentRunner } from '../agent-runner.ts';
+
+const ENABLED: EnabledSet = {
+  entries: [{ id: 'T1', name: '干活', type: 'humanTask', requiresManualStart: false, discretionary: false }],
+  inProgress: [],
+  judgements: [],
+  gaps: ['缺记录'],
+  activeStages: [],
+};
+
+/** 按序回放给定出参的假网关 —— 超出名单就重复最后一个 */
+function gatewayOf(outputs: Array<{ object: unknown; text: string }>): { gateway: ModelGateway; calls: ModelCall[] } {
+  const calls: ModelCall[] = [];
+  const gateway: ModelGateway = {
+    mode: 'replay',
+    resolve: () => Promise.reject(new Error('测试里用不到 resolve')),
+    generate: (call) => {
+      calls.push(call);
+      const next = outputs[Math.min(calls.length - 1, outputs.length - 1)];
+      if (next === undefined) return Promise.reject(new Error('名单空着'));
+      const result: ModelResult = {
+        text: next.text,
+        object: next.object,
+        usage: { inputTokens: 10, outputTokens: 5, latencyMs: 1 },
+        binding: { name: 'fake', provider: 'deepseek', model: 'fake' },
+        mode: 'replay',
+      };
+      return Promise.resolve(result);
+    },
+    withMode: () => gateway,
+  };
+  return { gateway, calls };
+}
+
+function runnerOf(outputs: Array<{ object: unknown; text: string }>) {
+  const { gateway, calls } = gatewayOf(outputs);
+  const notes: Array<{ title: string; raw: string }> = [];
+  const runner = createAgentRunner({
+    gateway,
+    modelOf: () => Promise.resolve('fake'),
+    onUsage: () => Promise.resolve(),
+    note: (_taskId, title, raw) => {
+      notes.push({ title, raw });
+      return Promise.resolve();
+    },
+  });
+  const decide = () =>
+    runner.decide({
+      taskId: 'task-1' as TaskId,
+      narrative: '(空)',
+      enabled: ENABLED,
+      scope: {},
+      writable: [],
+      tools: [],
+    });
+  return { decide, calls, notes };
+}
+
+const GOOD = { object: { say: '收工', actions: [{ kind: 'finish', itemId: 'T1' }] }, text: '{"say":"收工"}' };
+const BAD = { object: { say: '', actions: [{ kind: '胡编的' }] }, text: '再连贯的散文也不是行动串' };
+
+describe('输出不成形先就地重问,别一抖就叫人', () => {
+  it('第一拍坏、重问好 → 两次调用、原文进痕一条、返回的是好行动', async () => {
+    const { decide, calls, notes } = runnerOf([BAD, GOOD]);
+    const turn = await decide();
+    expect(calls).toHaveLength(2);
+    // 重问那一次要把「只输出 JSON」的硬提示带上 —— 不带等于原样再撞一次
+    expect(calls[1]?.prompt).toContain('不是合法的行动 JSON');
+    expect(notes).toHaveLength(1);
+    expect(notes[0]?.raw).toContain('散文');
+    expect(turn.actions[0]?.kind).toBe('finish');
+  });
+
+  it('两拍都坏 → 就收手交人,不无限重问;卡面不摆模型原话', async () => {
+    const { decide, calls } = runnerOf([BAD, BAD]);
+    const turn = await decide();
+    expect(calls).toHaveLength(2);
+    const action = turn.actions[0];
+    expect(action?.kind).toBe('human');
+    if (action?.kind !== 'human') return;
+    expect(action.card['modelReply']).toBeUndefined();
+    expect(String(action.card['reason'])).toContain('工作日志');
+  });
+
+  it('第一拍就是好的 → 只调一次,不白烧重问', async () => {
+    const { decide, calls, notes } = runnerOf([GOOD]);
+    const turn = await decide();
+    expect(calls).toHaveLength(1);
+    expect(notes).toHaveLength(0);
+    expect(turn.actions[0]?.kind).toBe('finish');
+  });
+});

apps/api/src/app/__tests__/ledger-coerce.test.ts

@@ -9,7 +9,7 @@
  * 所以归型放在写进草稿那一刻:归得了就归,归不了当场拒(理由喂回下一拍)。
  */
 import { describe, expect, it } from 'vitest';
-import { coerceToColumn, localStamp, missingReadings, rowReadings, rowKeyList, tallyReadings } from '../wiring/engines.ts';
+import { coerceToColumn, localStamp, missingReadings, rowReadings, rowKeyList, tallyReadings, toolCallReadings } from '../wiring/engines.ts';
 
 describe('空值 = 这一列没有值(不写)', () => {
   it('空串 / 全空白 / null / undefined 一律不写 —— 「原文没写的不要补」的数据面落点', () => {
@@ -342,3 +342,42 @@ describe('按值现数:域_对象_列_值', () => {
     ).toBe(1);
   });
 });
+
+/**
+ * **工具调用读数** —— 「机检只读基座数」这条纪律第一次覆盖到工具(2026-08-03)。
+ *
+ * 起因:A2 判稳偶发压根不调行情工具就把料判成「稳」转 A,而自报的那一列写得漂亮,
+ * 去向就此走岔(约十次一次)。工具出参本来就入痕,「调没调」是基座数得出来的事实。
+ */
+describe('工具调用读数', () => {
+  const declared = [{ name: 'crm.history-price-read' }, { name: 'mail.send' }];
+
+  it('声明过的工具一律先铺 0 —— 没调过与调了 0 次在业务上是同一件事', () => {
+    expect(toolCallReadings([], declared)).toEqual({
+      tool_crm_history_price_read_calls: 0,
+      tool_mail_send_calls: 0,
+    });
+  });
+
+  it('数成功返回的那几次,名字里的点号横杠一律换成下划线(S-FEEL 不认)', () => {
+    const trail = [
+      { kind: 'result', title: 'crm.history-price-read 返回' },
+      { kind: 'result', title: 'crm.history-price-read 返回(3 行)' },
+      { kind: 'thought', title: 'crm.history-price-read 返回' },
+    ];
+    expect(toolCallReadings(trail, declared).tool_crm_history_price_read_calls).toBe(2);
+  });
+
+  it('**调失败不算查过** —— 调不通等于没拿到行情,不该拿来当依据', () => {
+    const trail = [{ kind: 'result', title: 'crm.history-price-read 失败:端点不可达' }];
+    expect(toolCallReadings(trail, declared).tool_crm_history_price_read_calls).toBe(0);
+  });
+
+  it('没声明的工具不数 —— 声明面就是授权面,不在名单里的本来也数不着', () => {
+    const trail = [{ kind: 'result', title: 'erp.write 返回' }];
+    expect(Object.keys(toolCallReadings(trail, declared))).toEqual([
+      'tool_crm_history_price_read_calls',
+      'tool_mail_send_calls',
+    ]);
+  });
+});

apps/api/src/app/__tests__/view-table-edit.test.ts

@@ -19,7 +19,7 @@
  * 抄一份的下场踩过 —— 生产改了、测没跟着改,测全绿而线上照旧。
  */
 import { describe, expect, it } from 'vitest';
-import { gateOf, rowChanged, writesOf } from '../routes/desk.ts';
+import { gateAddressesOf, gateOf, rowChanged, writesOf } from '../routes/desk.ts';
 import { missingReadings } from '../wiring/engines.ts';
 
 /** A1 受理记录的声明(裁到这一段用得着的几列):PN 与年用量必填 */
@@ -103,6 +103,100 @@ describe('提交闸:必填没填就交不了', () => {
   });
 });
 
+/*
+ * **行级必填 `requiredWhen`:必填钉在该轮到的那一行**(2026-08-02 用户:
+ * 「工作区的 HTML 必填项必须填写了才能提交啊,不填写能算任务完成了吗?」)。
+ *
+ * 逐颗按序派单(A2 的 sel_stage 队列)撞上表级 required 的死结:定案三格整列必填,
+ * 第一颗的卡会被第二颗(还没轮到、件上不可见)的空格拦死;整列不标,闸又没牙,
+ * 空手就能交卷(用户实测点名)。requiredWhen 只在行上指定列等于指定值时才算必填。
+ */
+describe('行级必填:requiredWhen 只数该轮到的那一行', () => {
+  const LIST = {
+    domain: 'quote_alternative',
+    object: 'list',
+    fields: [
+      { name: 'rfq_ref', type: 'text', primaryKey: true },
+      { name: 'pn', type: 'text', primaryKey: true },
+      { name: 'alt_pn', type: 'text', primaryKey: false, label: '替代料 PN', requiredWhen: { column: 'sel_stage', value: 'NOW' } },
+      { name: 'alt_grade', type: 'text', primaryKey: false, label: '替代等级', requiredWhen: { column: 'sel_stage', value: 'NOW' } },
+    ],
+  };
+  const read = (rows: Array<Record<string, unknown>>) =>
+    missingReadings({ 'mine:quote_alternative.list': rows }, [LIST]);
+
+  it('**排队(WAIT)的颗不拦当前的卡** —— 只有 NOW 行的空格算缺', () => {
+    const got = read([
+      { rfq_ref: 'R1', pn: 'A', sel_stage: 'NOW', alt_pn: '', alt_grade: '' },
+      { rfq_ref: 'R1', pn: 'B', sel_stage: 'WAIT', alt_pn: '', alt_grade: '' },
+    ]);
+    expect(got['quote_alternative_list_missing']).toBe(1);
+    expect(got['quote_alternative_list_missing_keys']).toBe('R1/A 缺替代料 PN、替代等级');
+  });
+
+  it('NOW 行定案齐了 → 缺 0,闸开;办结(DONE)的行不再数', () => {
+    const got = read([
+      { rfq_ref: 'R1', pn: 'A', sel_stage: 'DONE', alt_pn: 'X', alt_grade: 'P2P' },
+      { rfq_ref: 'R1', pn: 'B', sel_stage: 'NOW', alt_pn: 'Y', alt_grade: 'FUNC' },
+    ]);
+    expect(got['quote_alternative_list_missing']).toBe(0);
+  });
+
+  it('**未果撤行之后 NOW 行不存在 → 缺 0** —— 撤行也是一个答案', () => {
+    expect(read([{ rfq_ref: 'R1', pn: 'B', sel_stage: 'WAIT', alt_pn: '', alt_grade: '' }])['quote_alternative_list_missing']).toBe(0);
+  });
+
+  it('不带 requiredWhen 的 required 照旧整列必填 —— 老声明一个字不用改', () => {
+    const plain = {
+      domain: 'd',
+      object: 'o',
+      fields: [
+        { name: 'k', type: 'text', primaryKey: true },
+        { name: 'v', type: 'text', primaryKey: false, label: '值', required: true },
+      ],
+    };
+    expect(missingReadings({ 'mine:d.o': [{ k: '1', v: '' }] }, [plain])['d_o_missing']).toBe(1);
+  });
+});
+
+/*
+ * **执行卡零输入之后,闸看哪几张表**(2026-08-02 用户定:填写全去工作区)。
+ *
+ * 卡面不再绑 blocks,闸若只认卡上的表就整个失效 —— 缺着必填照样交得回来,
+ * 一路走到放行门才被 L1 拦住,那正是当初立这道闸要治的病。
+ * 回落断了页面上看不出来(按钮照常绿着),所以钉在这儿。
+ */
+describe('闸看哪几张表:卡上绑的优先,没绑回落到必交付物声明', () => {
+  const table = (ledger: string) => ({ t: 'table' as const, ledger, cols: [], rows: [], fields: [] });
+
+  it('卡上绑了表 → 看绑的那几张,交付物声明不掺和', () => {
+    expect(
+      gateAddressesOf([table('quote_intake.record')], [{ ledgers: ['a.b', 'c.d'] }]),
+    ).toEqual(['quote_intake.record']);
+  });
+
+  it('**卡上没绑表(零输入执行卡)→ 回落到必交付物的 ledgers 全表**', () => {
+    expect(
+      gateAddressesOf(undefined, [{ ledger: 'quote_intake.record', ledgers: ['quote_intake.record', 'quote_intake.verdict'] }]),
+    ).toEqual(['quote_intake.record', 'quote_intake.verdict']);
+  });
+
+  it('老清单只给 ledger 单张 → 退它那一张;两边都空才真的没有依据', () => {
+    expect(gateAddressesOf([], [{ ledger: 'quote_sourcing.quote_list' }])).toEqual(['quote_sourcing.quote_list']);
+    expect(gateAddressesOf([], [{}])).toEqual([]);
+    expect(gateAddressesOf(undefined, [])).toEqual([]);
+  });
+
+  it('非表块(文本段)不算绑表 —— 熔断卡带 basis 不带表,照样回落', () => {
+    expect(
+      gateAddressesOf(
+        [{ t: 'p', text: '拒绝理由' } as never],
+        [{ ledgers: ['quote_alternative.list', 'quote_alternative.verdict'] }],
+      ),
+    ).toEqual(['quote_alternative.list', 'quote_alternative.verdict']);
+  });
+});
+
 describe('只写真改了的那几行', () => {
   const row = { rfq_ref: 'R1', pn: 'NE555P', eau: 30000, brand: 'TI' };