@dsh-workbench/shared 0.3.6 → 0.3.7

package/dist/index.js

@@ -7,7 +7,6 @@ export * from './api/facts.js';
 export * from './api/host-write.js';
 export * from './api/long-task.js';
 export * from './api/unit-board.js';
-export * from './api/unit-declaration.js';
 export * from './api/unit.js';
 export * from './api/workbench-client.js';
 export * from './api/workbench-contract.js';
@@ -19,6 +18,7 @@ export * from './components/CardAnchor.js';
 export * from './components/CardBoundary.js';
 export * from './components/CardHead.js';
 export * from './components/ChoiceGroup.js';
+export * from './components/ConfirmBar.js';
 export * from './components/Field.js';
 export * from './components/Form.js';
 export * from './components/FormActions.js';
@@ -49,10 +49,7 @@ export * from './i18n/zh.js';
 export * from './lib/blocker-action.js';
 export * from './lib/board-fact.js';
 export * from './lib/busy.js';
-export * from './lib/diy-debug.js';
-export * from './lib/diy-record.js';
 export * from './lib/form-problem.js';
-export * from './lib/panel-state.js';
 export * from './lib/react.js';
 export * from './lib/text.js';
 export * from './lib/ui.js';

package/dist/lib/board-fact.d.ts

@@ -24,13 +24,6 @@ export interface BoardProbe {
  * @returns 同一个路径或在其下给 `true`；`root` 末尾带不带斜杠都认（`/a` 不匹配 `/ab`）。
  */
 export declare function insideWorkshop(root: string, target: string): boolean;
-/**
- * 把一次探针读数归成椅面归属。
- * @param probe - 探针读数。
- * @param workshop - 当前工作区根路径；`null` 表示还不知道当前是哪个工作区。
- * @returns 外壳不在、或板路径与工作区缺一 → `unknown`；右栏没开或没画出来 → `hidden`；板在本工作区 → `workshop`，否则 `other`。
- */
-export declare function boardFactOf(probe: BoardProbe, workshop: string | null): BoardFactState;
 /**
  * 把探针读数归成左栏那句人话的档位。
  * @param probe - 探针读数。

package/dist/lib/board-fact.js

@@ -10,21 +10,6 @@ export function insideWorkshop(root, target) {
     const base = root.endsWith('/') ? root : `${root}/`;
     return target.startsWith(base);
 }
-/**
- * 把一次探针读数归成椅面归属。
- * @param probe - 探针读数。
- * @param workshop - 当前工作区根路径；`null` 表示还不知道当前是哪个工作区。
- * @returns 外壳不在、或板路径与工作区缺一 → `unknown`；右栏没开或没画出来 → `hidden`；板在本工作区 → `workshop`，否则 `other`。
- */
-export function boardFactOf(probe, workshop) {
-    if (!probe.workbench)
-        return 'unknown';
-    if (!probe.bar || !probe.open || !probe.drawn)
-        return 'hidden';
-    if (probe.board === '' || workshop === null)
-        return 'unknown';
-    return insideWorkshop(workshop, probe.board) ? 'workshop' : 'other';
-}
 /**
  * 把探针读数归成左栏那句人话的档位。
  * @param probe - 探针读数。

package/dist/lib/diy-record.d.ts

@@ -14,7 +14,29 @@ export interface RecordExpect {
     readonly urlContains: string;
 }
 /**
- * 一份活着的录制约定：相位 + 谁的会话 + 哪个工作区 / 单元 + 页面 URL 与标题 + 要找的那一次写 + 落盘文件 + 三个时间戳。
+ * 一次「截图」在宿主台账里的那一行：页面上的计数、落图那一刻、落盘路径；没落下来时带 `error` 原文（落成的那条没有它）。
+ */
+export interface RecordShot {
+    readonly n: number;
+    readonly at: number;
+    readonly path: string;
+    readonly error?: string;
+}
+/**
+ * 某个页面计数已经试过几次：初拍算一次，失败再试一次；计数一换就从头数。
+ */
+export interface RecordShotTries {
+    readonly n: number;
+    readonly tries: number;
+}
+/**
+ * 一张图最多试几次（初拍 + 一次重试）：失败如实报过就停，不每拍重试到底。
+ */
+export declare const RECORD_SHOT_TRIES = 2;
+/**
+ * 一份活着的录制约定：相位 + 谁的会话 + 哪个工作区 / 单元 + 页面 URL 与标题 + 要找的那一次写 +
+ * 落盘文件 + 三个时间戳，以及两份台账：按计数落图的 `shots`（`shotsSeen` 只记落成的那个计数）
+ * 与门铃的 `beats` / `beatMs`（命中几次、最近一次等了多久）。
  */
 export interface RecordState {
     readonly phase: RecordPhase;
@@ -30,6 +52,11 @@ export interface RecordState {
     readonly startedAt: number;
     readonly t0: number | null;
     readonly t1: number | null;
+    readonly shots: readonly RecordShot[];
+    readonly shotsSeen: number;
+    readonly shotTries: RecordShotTries | null;
+    readonly beats: number;
+    readonly beatMs: number;
     readonly at: number;
 }
 /**
@@ -83,8 +110,18 @@ export interface RecordStore {
     begin(pact: RecordPact): RecordMove;
     started(sessionId: string, at: number, now: number): RecordMove;
     finished(sessionId: string, at: number, now: number): RecordMove;
+    shotTaken(sessionId: string, shot: RecordShot, now: number): RecordMove;
+    shotFailed(sessionId: string, shot: RecordShot, now: number): RecordMove;
+    beat(sessionId: string, ms: number, now: number): RecordMove;
     stop(sessionId: string, now: number): RecordMove;
 }
+/**
+ * 这一拍该不该落图：页面计数涨过 `shotsSeen` 才算；同一个计数已经试满就先放下，等他自己再按。
+ * @param state - 当前有效的那份约定。
+ * @param pageShots - 页面浮条上那个「已拍」计数。
+ * @returns 该落的那个计数；不该落给 `null`（没涨 / 试满了 / 不是个正经数）。
+ */
+export declare function shotDueOf(state: RecordState, pageShots: number): number | null;
 /**
  * 造一份新的录制约定存储（进程内存，同一时刻只可能有一份有效约定）。
  * @returns 存取口；动作成不成都在返回的 `RecordMove` 里，不抛异常。

package/dist/lib/diy-record.js

@@ -2,6 +2,10 @@
  * 录制约定的有效期（15 分钟，毫秒）：超过它没动静的约定算过期、当场让人。
  */
 export const RECORD_STALE_MS = 15 * 60 * 1000;
+/**
+ * 一张图最多试几次（初拍 + 一次重试）：失败如实报过就停，不每拍重试到底。
+ */
+export const RECORD_SHOT_TRIES = 2;
 /**
  * 把工具入参收成人话动作。
  * @param raw - 任意入参值。
@@ -10,6 +14,22 @@ export const RECORD_STALE_MS = 15 * 60 * 1000;
 export function parseRecordIntent(raw) {
     return raw === 'peek' || raw === 'halt' || raw === 'stop' ? raw : null;
 }
+/**
+ * 这一拍该不该落图：页面计数涨过 `shotsSeen` 才算；同一个计数已经试满就先放下，等他自己再按。
+ * @param state - 当前有效的那份约定。
+ * @param pageShots - 页面浮条上那个「已拍」计数。
+ * @returns 该落的那个计数；不该落给 `null`（没涨 / 试满了 / 不是个正经数）。
+ */
+export function shotDueOf(state, pageShots) {
+    if (!Number.isFinite(pageShots))
+        return null;
+    const n = Math.floor(pageShots);
+    if (n <= state.shotsSeen)
+        return null;
+    if (state.shotTries !== null && state.shotTries.n === n && state.shotTries.tries >= RECORD_SHOT_TRIES)
+        return null;
+    return n;
+}
 function alive(state, now) {
     if (state === null)
         return null;
@@ -28,6 +48,18 @@ function ownerOf(state, sessionId, now) {
 export function createRecordStore() {
     let held = null;
     const live = (now) => alive(held, now);
+    const withShot = (found, shot, now, error) => {
+        const row = error === undefined ? shot : { n: shot.n, at: shot.at, path: shot.path, error };
+        const kept = found.shots.filter((one) => one.n !== shot.n);
+        const tries = found.shotTries !== null && found.shotTries.n === shot.n ? found.shotTries.tries : 0;
+        return {
+            ...found,
+            shots: [...kept, row].sort((one, two) => one.n - two.n),
+            shotsSeen: error === undefined ? Math.max(found.shotsSeen, shot.n) : found.shotsSeen,
+            shotTries: error === undefined ? null : { n: shot.n, tries: tries + 1 },
+            at: now,
+        };
+    };
     return {
         live,
         begin(pact) {
@@ -49,6 +81,11 @@ export function createRecordStore() {
                 startedAt: pact.now,
                 t0: null,
                 t1: null,
+                shots: [],
+                shotsSeen: 0,
+                shotTries: null,
+                beats: 0,
+                beatMs: 0,
                 at: pact.now,
             };
             held = state;
@@ -76,6 +113,35 @@ export function createRecordStore() {
             held = state;
             return { ok: true, state };
         },
+        shotTaken(sessionId, shot, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            const state = withShot(found, shot, now, undefined);
+            held = state;
+            return { ok: true, state };
+        },
+        shotFailed(sessionId, shot, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            const state = withShot(found, shot, now, shot.error === undefined ? '落图失败' : shot.error);
+            held = state;
+            return { ok: true, state };
+        },
+        beat(sessionId, ms, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            const state = {
+                ...found,
+                beats: found.beats + 1,
+                beatMs: Math.max(0, Math.floor(ms)),
+                at: now,
+            };
+            held = state;
+            return { ok: true, state };
+        },
         stop(sessionId, now) {
             const found = ownerOf(held, sessionId, now);
             if (typeof found === 'string')

package/dist/lib/text.d.ts

@@ -1,16 +1,3 @@
-/**
- * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
- * @param value - 任意值；不是字符串的先 `String()`。
- * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
- */
-export declare function quoteShellArg(value: unknown): string;
-/**
- * 取一段文本的末尾若干行（如命令输出），顺带去掉首尾空白。
- * @param text - 原文；`null` / `undefined` 当空串。
- * @param lines - 最多留几行，默认 6；0 给全篇、负数从开头砍掉那么多行（都是 `slice` 语义），调用方传正数。
- * @returns 末尾若干行、去首尾空行后的文本；原文行数不够就全给，空输入给空串。
- */
-export declare function tailLines(text: string | null | undefined, lines?: number): string;
 /**
  * 宽松解析一段前后可能夹着人话的 JSON：整段不通就从行首的 `[` / `{` 起、截到最后一个闭合符再试。
  * @param text - 原文；`null` / `undefined` 当空串。

package/dist/lib/text.js

@@ -1,23 +1,3 @@
-/**
- * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
- * @param value - 任意值；不是字符串的先 `String()`。
- * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
- */
-export function quoteShellArg(value) {
-    return `'${String(value).replace(/'/g, `'\\''`)}'`;
-}
-/**
- * 取一段文本的末尾若干行（如命令输出），顺带去掉首尾空白。
- * @param text - 原文；`null` / `undefined` 当空串。
- * @param lines - 最多留几行，默认 6；0 给全篇、负数从开头砍掉那么多行（都是 `slice` 语义），调用方传正数。
- * @returns 末尾若干行、去首尾空行后的文本；原文行数不够就全给，空输入给空串。
- */
-export function tailLines(text, lines = 6) {
-    const all = String(text ?? '')
-        .trim()
-        .split('\n');
-    return all.slice(-lines).join('\n');
-}
 function candidateStarts(raw) {
     const starts = [];
     for (let index = 0; index < raw.length; index += 1) {

package/dist/testing/declaration.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { readDeclaration } from '../api/unit-declaration.js';
+import { readDeclaration } from '../host/unit-declaration.js';
 export function declarationOfPackage(pkg, packageJson) {
     const at = typeof packageJson === 'string' ? packageJson : fileURLToPath(packageJson);
     let parsed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/shared",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "工作台与模块共享的纯代码与契约类型：类型、纯逻辑、哑组件、平台解析。宿主侧的东西从 /host 进（不影响浏览器产物）。",
   "license": "MIT",
   "type": "module",

package/src/api/__tests__/facts.test.ts

@@ -2,10 +2,7 @@ import { describe, expect, it, vi } from 'vitest';
 import {
   createFactChannel,
   factOfRoute,
-  isFactScope,
   parseFactFrame,
-  scopePrefixOf,
-  unitFactScope,
   type FactFrame,
   type FactTransport,
 } from '../facts.js';
@@ -262,13 +259,3 @@ describe('factOfRoute', () => {
     expect(factOfRoute('capability')).toBe('capability');
   });
 });
-
-describe('unitFactScope', () => {
-  it('命名空间 = 模块 id + `*`（"这个模块的数据全作废"只写一个字符串）', () => {
-    expect(unitFactScope('cmdb')).toBe('cmdb*');
-    expect(isFactScope('cmdb*')).toBe(true);
-    expect(isFactScope('*')).toBe(false);
-    expect(isFactScope('cmdb/summary')).toBe(false);
-    expect(scopePrefixOf('cmdb*')).toBe('cmdb');
-  });
-});

package/src/api/context-ref.ts

@@ -11,10 +11,6 @@ export interface ContextRef {
   readonly parts: readonly string[];
 }
 
-const MARKER = new RegExp(`@${CONTEXT_MARKER_NAME}:([a-z][a-z0-9-]*:[A-Za-z0-9._~%#/-]+)`, 'g');
-
-const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
-
 /**
  * 把引用拼回标记体里的那一段文本（不含 @ 与标记名）。
  * @param ref 要拼的引用。
@@ -24,21 +20,6 @@ export function encodeRef(ref: ContextRef): string {
   return `${ref.kind}:${ref.parts.join('/')}`;
 }
 
-/**
- * 把 kind:part/part 文本读回引用。
- * @param text 待解析文本。
- * @returns 没冒号、冒号在首尾、种类不是小写字母开头、或冒号后为空时给 undefined；不抛异常。
- */
-export function decodeRef(text: string): ContextRef | undefined {
-  const at = text.indexOf(':');
-  if (at <= 0 || at === text.length - 1) return undefined;
-  const kind = text.slice(0, at);
-  if (!/^[a-z][a-z0-9-]*$/.test(kind)) return undefined;
-  const parts = text.slice(at + 1).split('/').filter((part) => part !== '');
-  if (parts.length === 0) return undefined;
-  return { kind, parts };
-}
-
 /**
  * 拼出 @ 后面那半截（标记名加已编码文本），比较与拼接都用它。
  * @param encoded encodeRef 的结果。
@@ -56,23 +37,3 @@ export function markerBody(encoded: string): string {
 export function buildMarker(ref: ContextRef): string {
   return `@${markerBody(encodeRef(ref))}`;
 }
-
-/**
- * 从一段文本里按出现顺序捞出所有标记引用，同一个引用只留第一次。
- * @param text 任意文本；null / undefined 当空串。
- * @returns 解析不出来的标记会被丢掉，所以结果只含合法引用，可能为空数组。
- */
-export function parseMarkers(text: string): ContextRef[] {
-  const seen = new Set<string>();
-  const refs: ContextRef[] = [];
-  for (const match of String(text ?? '').matchAll(MARKER)) {
-    const raw = match[1].replace(TRAILING_PUNCTUATION, '');
-    const ref = decodeRef(raw);
-    if (ref === undefined) continue;
-    const key = encodeRef(ref);
-    if (seen.has(key)) continue;
-    seen.add(key);
-    refs.push(ref);
-  }
-  return refs;
-}

package/src/api/facts.ts

@@ -12,15 +12,6 @@ export interface FactFrame {
  */
 export const FACT_SCOPE_SUFFIX = '*';
 
-/**
- * 由单元 id 拼出它那一族事实的范围名。
- * @param unit 单元 id，不带后缀。
- * @returns <unit>* —— 永远是范围名，不是某一条事实。
- */
-export function unitFactScope(unit: string): string {
-  return `${unit}${FACT_SCOPE_SUFFIX}`;
-}
-
 /**
  * 判一个名字是不是范围查法，不是问这条事实存不存在。
  * @param name 事实名或范围名。

package/src/components/ConfirmBar.css

@@ -0,0 +1,26 @@
+.wb-confirmBar {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wb-len-8);
+  width: 100%;
+  box-sizing: border-box;
+  padding: var(--wb-len-10) var(--wb-len-12);
+  border: 0.5px solid var(--dsw-alias-border-l3);
+  border-radius: var(--dsw-radius-md);
+  background: var(--dsw-alias-bg-layer-1);
+}
+.wb-confirmBarTitle {
+  margin: 0;
+  font-size: var(--dsw-font-xxs-12-font-size);
+  font-weight: 600;
+  line-height: var(--wb-line-18);
+  color: var(--dsw-alias-label-primary);
+  overflow-wrap: anywhere;
+}
+.wb-confirmBarHint {
+  margin: 0;
+  font-size: var(--dsw-font-xxxs-11-font-size);
+  line-height: var(--wb-line-16);
+  color: var(--dsw-alias-label-secondary);
+  overflow-wrap: anywhere;
+}

package/src/components/ConfirmBar.test.tsx

@@ -0,0 +1,130 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { ConfirmBar, type ConfirmRow } from './ConfirmBar.js';
+import { FormActions, type FormAction } from './FormActions.js';
+import { Note } from './Note.js';
+import { Rows } from './Rows.js';
+
+interface AnyElement {
+  readonly type: unknown;
+  readonly props: Record<string, unknown>;
+  readonly key?: unknown;
+}
+
+function action(key: string, kind?: FormAction['kind']): FormAction {
+  return { key, label: key, kind, onClick: () => {} };
+}
+
+function row(key: string): ConfirmRow {
+  return { key, label: `名字-${key}`, value: `值-${key}` };
+}
+
+function bar(extra: Record<string, unknown> = {}): AnyElement {
+  return ConfirmBar({
+    title: '发布到 prod？',
+    actions: [action('publish', 'primary')],
+    ...extra,
+  }) as unknown as AnyElement;
+}
+
+function childrenOf(node: AnyElement): AnyElement[] {
+  return ((node.props['children'] as unknown[]) ?? []).filter(
+    (one): one is AnyElement => typeof one === 'object' && one !== null,
+  );
+}
+
+describe('确认条（契约类 wb-confirmBar）', () => {
+  it('★ 是一个 role="group" 的条，读屏名默认取字符串标题', () => {
+    const root = bar();
+
+    expect(root.props['role']).toBe('group');
+    expect(root.props['aria-label']).toBe('发布到 prod？');
+    expect(childrenOf(root)[0]?.props['className']).toBe('wb-confirmBarTitle');
+  });
+
+  it('显式给了 label 就用它；标题不是字符串又没给 label 就不设读屏名', () => {
+    expect(bar({ label: '发布确认' }).props['aria-label']).toBe('发布确认');
+    expect(bar({ title: 42 }).props['aria-label']).toBeUndefined();
+  });
+
+  it('busy 只喂 aria-busy，不改动作那一块', () => {
+    const root = bar({ busy: true, actions: [action('publish', 'primary'), action('cancel')] });
+
+    expect(root.props['aria-busy']).toBe(true);
+    expect(childrenOf(root)[1]?.props['actions']).toHaveLength(2);
+  });
+
+  it('★ 三件都借现成的：键值走 Rows、失败那句走 Note(tone=problem, role=alert)、动作走 FormActions', () => {
+    const actions = [action('publish', 'primary'), action('cancel')];
+    const root = bar({ rows: [row('env')], problem: '源上没有这个包', actions });
+    const children = childrenOf(root);
+
+    expect(children[0]?.props['className']).toBe('wb-confirmBarTitle');
+    expect(children[1]?.type).toBe(Rows);
+    expect(children[2]?.type).toBe(Note);
+    expect(children[2]?.props['tone']).toBe('problem');
+    expect(children[2]?.props['role']).toBe('alert');
+    expect(children[3]?.type).toBe(FormActions);
+    expect(children[3]?.props['actions']).toBe(actions);
+  });
+
+  it('★ 没给的那几块不占位：只要标题与动作区', () => {
+    expect(childrenOf(bar())).toHaveLength(2);
+    expect(childrenOf(bar({ rows: [] }))).toHaveLength(2);
+    expect(childrenOf(bar({ hint: '这一趟会重启一次' }))).toHaveLength(3);
+  });
+
+  it('★ 键值那几格走 Row 的 label / value 两格（key 交给 React 认列表），不是自己画两栏', () => {
+    const root = bar({ rows: [row('env'), row('branch')] });
+    const rowNodes = childrenOf(childrenOf(root)[1] as AnyElement);
+
+    expect(rowNodes.map((one) => one.props['label'])).toEqual(['名字-env', '名字-branch']);
+    expect(rowNodes.map((one) => one.props['value'])).toEqual(['值-env', '值-branch']);
+    expect(rowNodes.map((one) => one.key)).toEqual(['env', 'branch']);
+  });
+});
+
+const CSS = readFileSync(new URL('./ConfirmBar.css', import.meta.url), 'utf8');
+
+function declarations(selector: string): string[] {
+  for (const block of CSS.split('}')) {
+    const [head, ...rest] = block.split('{');
+    if (rest.length === 0 || head === undefined) continue;
+    if (head.trim() !== selector) continue;
+    return rest
+      .join('{')
+      .split(';')
+      .map((one) => one.replace(/\s+/g, ' ').trim())
+      .filter((one) => one !== '');
+  }
+  throw new Error(`ConfirmBar.css 里没有这条规则：${selector}`);
+}
+
+describe('确认条的版式（ADR-0073 §2.2）', () => {
+  it('★ 占满自己那一格（有内边距与描边 ⇒ 配 border-box），别在横向父容器里退回内容宽', () => {
+    const rule = declarations('.wb-confirmBar');
+
+    expect(rule).toContain('width: 100%');
+    expect(rule).toContain('box-sizing: border-box');
+  });
+
+  it('★ 一档间距、描边与圆角都走令牌', () => {
+    const rule = declarations('.wb-confirmBar');
+
+    expect(rule).toContain('gap: var(--wb-len-8)');
+    expect(rule).toContain('padding: var(--wb-len-10) var(--wb-len-12)');
+    expect(rule).toContain('border: 0.5px solid var(--dsw-alias-border-l3)');
+    expect(rule).toContain('border-radius: var(--dsw-radius-md)');
+  });
+
+  it('★ 标题与说明的大小走令牌，标题比说明重一档', () => {
+    const title = declarations('.wb-confirmBarTitle');
+    const hint = declarations('.wb-confirmBarHint');
+
+    expect(title).toContain('font-size: var(--dsw-font-xxs-12-font-size)');
+    expect(title).toContain('line-height: var(--wb-line-18)');
+    expect(title).toContain('font-weight: 600');
+    expect(hint).toContain('font-size: var(--dsw-font-xxxs-11-font-size)');
+    expect(hint).toContain('line-height: var(--wb-line-16)');
+  });
+});

package/src/components/ConfirmBar.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from '../lib/react.js';
+import { h } from '../lib/react.js';
+import { FormActions, type FormAction } from './FormActions.js';
+import { Note } from './Note.js';
+import { Row, Rows } from './Rows.js';
+import './ConfirmBar.css';
+
+/**
+ * `ConfirmBar` 的一格键值：`label` 在左、`value` 在右（走 `Rows` 的标签列）。
+ */
+export interface ConfirmRow {
+  readonly key: string;
+  readonly label: ReactNode;
+  readonly value: ReactNode;
+}
+
+/**
+ * `ConfirmBar` 的契约：标题、说明、键值、失败那句与动作。
+ */
+export interface ConfirmBarProps {
+  readonly title: ReactNode;
+  readonly hint?: ReactNode | undefined;
+  readonly rows?: readonly ConfirmRow[] | undefined;
+  readonly actions: readonly FormAction[];
+  readonly problem?: ReactNode | undefined;
+  readonly busy?: boolean | undefined;
+  readonly label?: string | undefined;
+}
+
+/**
+ * 「先问一句再动手」那一条：标题 + 说明 + 键值 + 失败那句 + 动作区，形状一次收口。
+ * **要不要问**归调用点（ADR-0054 §2 规则三），这一件只回答"问的时候长什么样"。
+ * @param props.title - 那一句问话（"发布到 prod？"）。
+ * @param props.hint - 标题下面那句说明或正文；不给不占位。
+ * @param props.rows - 键值两格（键值列宽与分隔线归 `Rows` / `Row`）；不给或空数组不渲染。值那一格可以放控件。
+ * @param props.actions - 动作清单（归 `FormActions`：一个区一颗 `primary`、永远在右、窄了折行）。
+ * @param props.problem - 失败那句（走 `Note tone="problem"`，读屏是 `alert`）；不给不占位。
+ * @param props.busy - 整条在忙（只喂 `aria-busy`；按钮自己的转圈与禁用归 `actions` 里那一颗）。
+ * @param props.label - 读屏的组名；不给时 `title` 是字符串就拿它顶上，两者都没有就不设。
+ * @returns 一个 `role="group"` 的条；`actions` 空数组时最后那一块不渲染。
+ */
+export function ConfirmBar({ title, hint, rows, actions, problem, busy, label }: ConfirmBarProps) {
+  const name = label ?? (typeof title === 'string' ? title : undefined);
+  return (
+    <div className="wb-confirmBar" role="group" aria-label={name} aria-busy={busy}>
+      <p className="wb-confirmBarTitle">{title}</p>
+      {hint === undefined ? null : <p className="wb-confirmBarHint">{hint}</p>}
+      {rows === undefined || rows.length === 0 ? null : (
+        <Rows>
+          {rows.map((row) => (
+            <Row key={row.key} label={row.label} value={row.value} />
+          ))}
+        </Rows>
+      )}
+      {problem === undefined ? null : (
+        <Note tone="problem" role="alert">
+          {problem}
+        </Note>
+      )}
+      <FormActions actions={actions} />
+    </div>
+  );
+}

package/src/components/Form.test.tsx

@@ -20,6 +20,7 @@ function field(key: string, value: FormValue, validate?: FormField['validate']):
     key,
     label: key,
     value,
+    onChange: () => {},
     control: (binding) => `${key}:${binding.id}:${String(binding.invalid)}:${String(binding.disabled)}`,
     ...(validate === undefined ? {} : { validate }),
   };
@@ -402,6 +403,20 @@ describe('formRowsOf', () => {
     expect(propsOf(rows[0])['children']).toBe('env:wb-form-env:true:false');
   });
 
+  it('★ 这一格的 value / onChange 从字段配置原样进绑定（值只写一处）', () => {
+    const onChange = (): void => {};
+    const probe: FormField = {
+      key: 'env',
+      label: 'env',
+      value: 'prod',
+      onChange,
+      control: (binding) => `${String(binding.value)}:${String(binding.onChange === onChange)}`,
+    };
+    const rows = formRowsOf({ fields: [probe], problems: {}, showProblem: false, busy: false });
+
+    expect(propsOf(rows[0])['children']).toBe('prod:true');
+  });
+
   it('★ 还没提交过（showProblem: false）：文案不画、invalid 也不给（done 之前一律 false）', () => {
     const rows = formRowsOf({ fields: [field('env', 'prod')], problems, showProblem: false, busy: false });