汇报流:活动按步序位置推视图,容器沙箱渲染

「flow:按**步序位置**推送声明的模版」(AM 07)。原先这条链只有写面没有读面,
活动的 viewTemplates 是一行占位字符串,工作台视图区永远只显示一份硬编码概览。

补齐整条链:
  · 步声明新增 `view`:这一步呈现哪张模版 —— 推什么由声明给定,不由临场决定。
  · 新增模版填数的纯函数(interaction/domain):`data-slot` 取值、`data-rows` 逐条展开。
    **填数只做取值与转义**,没有表达式、没有分支、没有循环 —— 一旦模版能算,
    它就成了代码,容器的「无脚本执行权」也就形同虚设。填充**消费槽位**,
    交出去的是干净 HTML,不是带模板属性的半成品。
  · interaction 补读面 `viewOf`;desk 路由把推送的 HTML 交给前端;
    ViewRegion 经 `@ui` 的 ViewContainer(sandbox="" 的 iframe)渲染 —— feature 不碰 innerHTML。
  · A1 写了三张真模版(事态全景 / 打标判据 / 成果预览),内联自带样式
    (沙箱页面不继承工作台 CSS),按步序位置挂在 S3 / S5 / S6 上。

沿路两处修:
① 取值路径遇到**本身带点号的键**(台账地址 `域.对象`)会被拆成两级、永远取不到。
   改为整键优先、找不到再下行;`view-render` 与 `step-sequence` 两处同修。
② 「本单交付」不能画成台账全表:任务视图是正式版 + 我的草稿的合并结果,
   直接拿来列会把**别单**放行过的记录一并列出。本单自己写下的行单独放在
   `mine:域.对象` 下(整键,取值不歧义)。

另:视图推送失败原先静默吞掉 —— 会让「视图区一直空着」变成查不出原因的怪事;
改为留痕(仍不影响步序推进,呈现是投影)。

实测:一封 RFQ 入站 → 放行前那一屏列出本单交付 LM358DR / TI / 12000 / 8.2 / 10周,
以及 Type A「直接快答」的分类结论与四项打标判据。

gates: tsc / eslint / depcruise(321 模块)/ api-report / 423 测试 全绿

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KeDBx2PHLavbURXB8LJJ7m

apps/api/src/app/routes/desk.ts

@@ -82,17 +82,19 @@ export function registerDeskRoutes(app: Hono<AppEnv>, container: Container): voi
     const taskId = taskIdSchema.parse(c.req.param('taskId'));
     const task = await container.task.get(taskId);
 
-    const [workOrders, chat, lines] = await Promise.all([
+    const [workOrders, chat, lines, pushed] = await Promise.all([
       container.humanTool.openWorkOrders(taskId),
       container.interaction.timeline(taskId),
       container.memory.taskLog(taskId),
+      container.interaction.viewOf(taskId),
     ]);
     const cards = await container.humanTool.chatCards(taskId);
 
     // 对话流 = 时间线 + 对话卡族,按时间全序 —— 与任务记忆同源、不同筛选
     const merged: ChatMessage[] = [...chat, ...cards].sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
 
-    // 视图区:活动推送的结构化块(尚无推送时给一份进度概览,不留空屏)
+    // 视图区:活动推的 HTML 优先(它是活动按局面组织的完整一屏);
+    // 尚无推送时给一份进度概览,不留空屏
     const view: ViewBlock[] = [
       {
         t: 'kv',
@@ -119,7 +121,8 @@ export function registerDeskRoutes(app: Hono<AppEnv>, container: Container): voi
       deliverables: [],
       workOrders,
       chat: merged,
-      view,
+      view: pushed?.blocks !== undefined ? [...pushed.blocks] : view,
+      ...(pushed?.html === undefined ? {} : { viewHtml: pushed.html }),
       log: lines.map((l) => ({
         id: l.id,
         at: l.at,

apps/api/src/app/wiring/engines.ts

@@ -10,6 +10,7 @@ import type { LedgerService } from '@modules/ledger';
 import type { MemoryService } from '@modules/memory';
 import type { ToolboxService, ToolInvoker } from '@modules/toolbox';
 import type { HumanToolService } from '@modules/human-tool';
+import { renderView } from '@modules/interaction';
 import type { InteractionService } from '@modules/interaction';
 import type { MessageService } from '@modules/message';
 import type { OrgService } from '@modules/org';
@@ -285,6 +286,31 @@ export function wireEngines(deps: EngineWiringDeps): EngineWiring {
     data: taskData,
     tools: { ...toolGateway, invoke: (i) => toolGateway.invoke(i) },
     schemas: deps.schemas,
+    views: {
+      /*
+       * 按名取模版 → 填数 → 推给前端。
+       * 模版取自**该任务装载时的资产版本**(经 registry),不是「当前最新」——
+       * 在途任务按其启动时版本跑完,呈现也该跟着那一版。
+       */
+      async push({ taskId, activityId, template, scope }) {
+        const manifest = await deps.registry.manifestOf(activityId);
+        const found = manifest.assets.viewTemplates.find((t) => t.name === template);
+        if (found === undefined) return;
+
+        /*
+         * 视图作用域 = 任务视图 + **本单自己写下的行**。
+         * 两者要分得开:任务视图里的 `域.对象` 是正式版 + 我的草稿的合并结果,
+         * 拿它画「本单交付」会把别单放行过的记录一并列出来。
+         * 本单的行放在 `mine:域.对象` 下 —— 整键,取值不歧义。
+         */
+        const own: Record<string, unknown[]> = {};
+        for (const draft of await deps.ledger.taskDrafts(taskId)) {
+          const key = `mine:${draft.domain}.${draft.object}`;
+          (own[key] ??= []).push({ ...draft.key, ...draft.patch });
+        }
+        await deps.interaction.pushViewHtml(taskId, renderView(found.html, { ...scope, ...own }));
+      },
+    },
     llm: {
       async generate(input) {
         // LLM 在 flow 里只以「被调用的工具」出现,不是调度者

apps/api/src/modules/flow-engine/internal/domain/step-sequence.ts

@@ -165,6 +165,14 @@ export function lastSelectedPorts(position: FlowPosition): Record<string, string
  * 悄悄写出一条空记录。
  */
 export function resolvePath(source: unknown, path: string): unknown {
+  /*
+   * 整键优先:作用域里有些键**本身带点号**(台账地址 `域.对象`)。
+   * 先按字面整键找,找不到再按点号下行 —— 反过来会把地址键拆成两级、永远找不到。
+   */
+  if (typeof source === 'object' && source !== null && !Array.isArray(source)) {
+    const direct = (source as Record<string, unknown>)[path];
+    if (direct !== undefined) return direct;
+  }
   return path.split('.').reduce<unknown>((acc, seg) => {
     if (acc === null || acc === undefined || typeof acc !== 'object') return undefined;
     if (Array.isArray(acc)) {

apps/api/src/modules/flow-engine/internal/usecase/flow-runner.ts

@@ -11,6 +11,7 @@ import type {
   ListenerRegistrar,
   LlmStepGateway,
   SchemaValidator,
+  ViewGateway,
   MemoryRecorder,
   PredicateEvaluator,
   TaskContext,
@@ -38,6 +39,7 @@ export type FlowRunnerDeps = {
   readonly tools: ToolStepInvoker;
   readonly llm: LlmStepGateway;
   readonly schemas: SchemaValidator;
+  readonly views: ViewGateway;
   readonly cards: CardGateway;
   readonly listeners: ListenerRegistrar;
   readonly memory: MemoryRecorder;
@@ -77,6 +79,28 @@ export function createFlowRunner(deps: FlowRunnerDeps): FlowEngineService {
     });
   }
 
+  /**
+   * 按步序位置推视图 —— 声明了 `view` 才推,推的是这一步跑完后的**任务视图**。
+   * 推送失败不该把步拖垮:呈现是投影,投影出问题不改变已经发生的事实。
+   */
+  async function pushStepView(taskId: TaskId, step: FlowStep, activityId: string): Promise<void> {
+    if (step.view === undefined) return;
+    try {
+      await deps.views.push({ taskId, activityId, template: step.view, scope: await deps.data.view(taskId) });
+    } catch (error) {
+      /*
+       * 呈现失败只丢这一帧画面,不影响步序推进 —— 但**必须留痕**:
+       * 静默吞掉会让「视图区一直空着」变成一桩查不出原因的怪事。
+       */
+      await deps.memory.append({
+        taskId,
+        kind: 'engine-transition',
+        title: `视图推送失败(不影响推进):${error instanceof Error ? error.message : String(error)}`,
+        detail: { step: step.name, template: step.view },
+      });
+    }
+  }
+
   /** 回传协议 → 出参:取 `values`;非回传形状的人事件按原样当出参 */
   function replyValuesOf(payload: Record<string, unknown>): Record<string, unknown> {
     const values = payload['values'];
@@ -126,6 +150,7 @@ export function createFlowRunner(deps: FlowRunnerDeps): FlowEngineService {
         });
         if (!result.ok) return handleFailure(taskId, step, index, position, attempt, result.error?.message ?? '工具失败');
         if (result.output !== undefined) await writeOutput(taskId, step, result.output);
+        await pushStepView(taskId, step, context.activityId);
         const next = markStep(position, index, { state: 'done', attempt, ...(result.output === undefined ? {} : { output: result.output }) });
         await deps.state.save(taskId, (await loaded(taskId)).model, next);
         return { position: next, status: 'running' };
@@ -164,6 +189,7 @@ export function createFlowRunner(deps: FlowRunnerDeps): FlowEngineService {
 
         const output = parsed as Record<string, unknown>;
         await writeOutput(taskId, step, output);
+        await pushStepView(taskId, step, context.activityId);
         const next = markStep(position, index, { state: 'done', attempt, output });
         await deps.state.save(taskId, (await loaded(taskId)).model, next);
         return { position: next, status: 'running' };
@@ -198,6 +224,8 @@ export function createFlowRunner(deps: FlowRunnerDeps): FlowEngineService {
           keyFilter: { cardId: card.id },
           deadline: step.deadline,
         });
+        // 发卡的同时把全景推上去:人要在数据上作判断,数据就得摆在卡旁边
+        await pushStepView(taskId, step, context.activityId);
         const next = markStep(position, index, { state: 'awaiting', attempt });
         await deps.state.save(taskId, (await loaded(taskId)).model, next);
         return {

apps/api/src/modules/flow-engine/port.ts

@@ -64,6 +64,15 @@ export type SchemaValidator = {
   validate(schema: Record<string, unknown>, value: unknown): { ok: boolean; errors: string[] };
 };
 
+/**
+ * 视图流控 —— app 注入 `interaction`(L3)。
+ * flow 按步序位置推声明的模版;推的是**填好数的 HTML**,容器只渲染不执行。
+ */
+export type ViewGateway = {
+  /** 按模版名取模版、以任务视图填数、推给前端;模版不存在就什么都不做 */
+  push(input: { taskId: TaskId; activityId: string; template: string; scope: Record<string, unknown> }): Promise<void>;
+};
+
 /** 人类工具步 —— app 注入 `human-tool`(L3) */
 export type CardGateway = {
   issue(input: {

apps/api/src/modules/interaction/__tests__/view-render.test.ts

@@ -0,0 +1,110 @@
+/** 视图模版填数 —— domain 测试零 mock(AM 07:模版是内容不是代码) */
+import { describe, expect, it } from 'vitest';
+import { displayValue, escapeHtml, renderView, resolveSlot } from '../internal/domain/view-render.ts';
+import { templateIsSafe } from '../internal/domain/control-handover.ts';
+
+describe('取值与展示', () => {
+  it('点号下行 + 数组下标 —— 与步声明的写法一致', () => {
+    const scope = { records: [{ pn: 'LM358DR' }], n: 3 };
+    expect(resolveSlot(scope, 'records.0.pn')).toBe('LM358DR');
+    expect(resolveSlot(scope, 'n')).toBe(3);
+    expect(resolveSlot(scope, 'nope.deep')).toBeUndefined();
+  });
+
+  it('空值显示为「—」,免得画面留空洞', () => {
+    expect(displayValue(undefined)).toBe('—');
+    expect(displayValue('')).toBe('—');
+    expect(displayValue(null)).toBe('—');
+  });
+
+  it('数组显示条数,布尔显示是/否,小数收敛', () => {
+    expect(displayValue([1, 2, 3])).toBe('3');
+    expect(displayValue(true)).toBe('是');
+    expect(displayValue(0.123456789)).toBe('0.1235');
+  });
+});
+
+describe('填数只做取值与转义 —— 模版不得成为代码', () => {
+  it('填入的值被转义,注不进标签', () => {
+    const html = '<b data-slot="x"></b>';
+    const out = renderView(html, { x: '<img src=x onerror=alert(1)>' });
+    // 标签没能成型:尖括号全被转义,留下的是惰性文本
+    expect(out).not.toContain('<img');
+    expect(out).toBe('<b>&lt;img src=x onerror=alert(1)&gt;</b>');
+  });
+
+  it('净化门查的是**作者写的模版**,不是填完数据的成品', () => {
+    // 模版本身必须无脚本、无事件处理器、无外链
+    expect(templateIsSafe('<b data-slot="x"></b>')).toBe(true);
+    expect(templateIsSafe('<b onclick="x()"></b>')).toBe(false);
+    // 成品里出现「onerror=」这串字面文本是转义后的惰性文本,不该再拿模版规则去卡它 ——
+    // 否则任何正文提到事件处理器的业务数据都会被误伤。安全由「模版过门 + 沙箱容器」两道保证。
+    expect(renderView('<b data-slot="x"></b>', { x: 'onclick=1' })).toBe('<b>onclick=1</b>');
+  });
+
+  it('未命中的槽位填「—」,不把占位文字漏到成品上', () => {
+    expect(renderView('<b data-slot="missing">占位</b>', {})).toBe('<b>—</b>');
+  });
+
+  it('填充消费槽位 —— 交出去的是干净 HTML,不带模板属性', () => {
+    expect(renderView('<b class="k" data-slot="x"></b>', { x: 1 })).toBe('<b class="k">1</b>');
+  });
+});
+
+describe('行模版 —— 逐条清单不写死条数', () => {
+  const html = '<table data-rows="records"><tr><td data-slot="pn"></td><td data-slot="eau"></td></tr></table>';
+
+  it('按数组逐项复制,行内槽位相对该行取值', () => {
+    const out = renderView(html, {
+      records: [
+        { pn: 'A1', eau: 100 },
+        { pn: 'B2', eau: 200 },
+      ],
+    });
+    expect(out).toContain('<td>A1</td>');
+    expect(out).toContain('<td>B2</td>');
+    expect(out).toContain('<td>200</td>');
+  });
+
+  it('空数组渲染成空容器,不留一行占位', () => {
+    const out = renderView(html, { records: [] });
+    expect(out).toBe('<table></table>');
+  });
+
+  it('行先展开再填标量槽 —— 顺序反了行内会被外层作用域填掉', () => {
+    const out = renderView('<ul data-rows="rs"><li data-slot="v"></li></ul><b data-slot="v"></b>', {
+      rs: [{ v: '行内' }],
+      v: '外层',
+    });
+    expect(out).toContain('<li>行内</li>');
+    expect(out).toContain('<b>外层</b>');
+  });
+});
+
+describe('转义', () => {
+  it('四个字符各归其位', () => {
+    expect(escapeHtml('<a href="x">&</a>')).toBe('&lt;a href=&quot;x&quot;&gt;&amp;&lt;/a&gt;');
+  });
+});
+
+describe('整键优先 —— 台账地址本身带点号', () => {
+  const scope = {
+    'quote_intake.record': [{ pn: 'LM358DR', eau: 12000 }],
+    quote_intake: { record: [{ pn: '不该取到这个' }] },
+    a: { b: 'nested' },
+  };
+
+  it('字面整键存在时取它,不拆成两级', () => {
+    const rows = resolveSlot(scope, 'quote_intake.record');
+    expect(Array.isArray(rows) && (rows[0] as { pn: string }).pn).toBe('LM358DR');
+  });
+
+  it('没有整键才按点号下行', () => {
+    expect(resolveSlot(scope, 'a.b')).toBe('nested');
+  });
+
+  it('行模版用地址键取表', () => {
+    const out = renderView('<tbody data-rows="quote_intake.record"><tr><td data-slot="pn"></td></tr></tbody>', scope);
+    expect(out).toContain('<td>LM358DR</td>');
+  });
+});

apps/api/src/modules/interaction/contract.ts

@@ -41,6 +41,8 @@ export type InteractionService = {
   pushView(taskId: TaskId, blocks: readonly ViewBlock[]): Promise<void>;
   /** 视图流控:活动推 HTML 模版 —— 过净化门,不过即抛 */
   pushViewHtml(taskId: TaskId, html: string): Promise<void>;
+  /** 视图区当前呈现什么 —— 只读投影,刷新即重建(前端零过程状态) */
+  viewOf(taskId: TaskId): Promise<{ blocks?: readonly ViewBlock[]; html?: string } | undefined>;
 
   /** 控制权转交 —— 随引擎的激活 / 完成事件自动发生 */
   setPhase(taskId: TaskId, phase: InteractionPhase): Promise<ControlHolder>;

apps/api/src/modules/interaction/index.ts

@@ -27,6 +27,7 @@ export {
   outputControl,
   templateIsSafe,
 } from './internal/domain/control-handover.ts';
+export { renderView, renderTemplate, renderRows, escapeHtml, displayValue } from './internal/domain/view-render.ts';
 
 export { createInteractionStore } from './internal/adapter/interaction-store.ts';
 export { chatMessageTable, taskViewTable } from './internal/adapter/interaction-schema.ts';

apps/api/src/modules/interaction/internal/adapter/interaction-store.ts

@@ -43,6 +43,14 @@ export function createInteractionStore(db: Db): InteractionStore {
           set: { blocks: values.blocks, html: values.html, updatedAt: values.updatedAt },
         });
     },
+    async getView(taskId: TaskId) {
+      const [row] = await db.select().from(taskViewTable).where(eq(taskViewTable.taskId, taskId)).limit(1);
+      if (row === undefined) return undefined;
+      return {
+        ...(row.blocks === null ? {} : { blocks: row.blocks as ViewBlock[] }),
+        ...(row.html === null ? {} : { html: row.html }),
+      };
+    },
     async setPhase(taskId: TaskId, phase: InteractionPhase) {
       await db
         .insert(taskViewTable)

apps/api/src/modules/interaction/internal/domain/view-render.ts

@@ -0,0 +1,91 @@
+/**
+ * 视图模版填数 —— 纯函数、零 IO(编码规范 §10.2;语义出处 AM 07)。
+ *
+ * 「**模版是内容不是代码**:AI 按局面选模版、填数据、决定下一屏呈现什么。」
+ * 所以填数只做**取值与转义**两件事:没有表达式、没有分支、没有循环 ——
+ * 一旦模版能算,它就成了代码,容器的「无脚本执行权」也就形同虚设。
+ *
+ * 约定:`data-slot="路径"` 的元素,内容替换为作用域上该路径的值。
+ * 路径按点号下行、数组下标按数字段(`records.0.pn`),与步声明的取值写法一致。
+ */
+
+/** 只在**文本位置**插值,故只需转义这四个字符;属性位不开放插值 */
+export function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+export function resolveSlot(scope: unknown, path: string): unknown {
+  /*
+   * 整键优先:作用域里有些键**本身带点号**(台账地址 `域.对象`)。
+   * 先按字面整键找,找不到再按点号下行 —— 反过来会把地址键拆成两级、永远找不到。
+   */
+  if (typeof scope === 'object' && scope !== null && !Array.isArray(scope)) {
+    const direct = (scope as Record<string, unknown>)[path];
+    if (direct !== undefined) return direct;
+  }
+  return path.split('.').reduce<unknown>((acc, seg) => {
+    if (acc === null || acc === undefined || typeof acc !== 'object') return undefined;
+    if (Array.isArray(acc)) {
+      const index = Number(seg);
+      return Number.isInteger(index) ? acc[index] : undefined;
+    }
+    return (acc as Record<string, unknown>)[seg];
+  }, scope);
+}
+
+/** 值 → 展示文本:空值显示为「—」,免得画面上留一串空洞 */
+export function displayValue(value: unknown): string {
+  if (value === undefined || value === null || value === '') return '—';
+  if (typeof value === 'number') return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)));
+  if (typeof value === 'boolean') return value ? '是' : '否';
+  if (Array.isArray(value)) return String(value.length);
+  if (typeof value === 'object') return JSON.stringify(value);
+  return String(value);
+}
+
+const SLOT = /<([a-zA-Z][\w-]*)\b([^>]*?)\bdata-slot\s*=\s*"([^"]+)"([^>]*)>([\s\S]*?)<\/\1>/g;
+
+/**
+ * 把作用域填进模版的槽位。
+ *
+ * 填充**消费槽位**:填完就把 `data-slot` 摘掉 —— 一来第二遍不会再拿外层作用域
+ * 把行内已填好的值冲掉,二来交出去的是干净 HTML,不是带模板属性的半成品。
+ * 未命中的槽位填「—」而不是留原样:模版里的占位文字漏到成品上比空着更糟。
+ */
+export function renderTemplate(html: string, scope: Readonly<Record<string, unknown>>): string {
+  return html.replace(SLOT, (_all, tag: string, before: string, path: string, after: string) => {
+    const attrs = `${before}${after}`.replace(/\s+/g, ' ').trimEnd();
+    const text = escapeHtml(displayValue(resolveSlot(scope, path)));
+    return `<${tag}${attrs === '' ? '' : ` ${attrs.trim()}`}>${text}</${tag}>`;
+  });
+}
+
+/**
+ * 行模版:`data-rows="路径"` 的元素,按数组逐项复制其内部结构。
+ * 每行内部的 `data-slot` 相对**该行对象**取值 —— 这样「逐条清单」不必写死条数。
+ */
+const ROWS = /<([a-zA-Z][\w-]*)\b([^>]*?)\bdata-rows\s*=\s*"([^"]+)"([^>]*)>([\s\S]*?)<\/\1>/g;
+
+export function renderRows(html: string, scope: Readonly<Record<string, unknown>>): string {
+  return html.replace(ROWS, (_all, tag: string, before: string, path: string, after: string, inner: string) => {
+    const attrs = `${before}${after}`.replace(/\s+/g, ' ').trim();
+    const open = `<${tag}${attrs === '' ? '' : ` ${attrs}`}>`;
+    const value = resolveSlot(scope, path);
+    const rows = Array.isArray(value) ? value : [];
+    const body = rows
+      .map((row) =>
+        renderTemplate(inner, (typeof row === 'object' && row !== null ? row : { value: row }) as Record<string, unknown>),
+      )
+      .join('');
+    return `${open}${body}</${tag}>`;
+  });
+}
+
+/** 先展开行,再填标量槽 —— 顺序不能反,否则行内槽位会被外层作用域填掉 */
+export function renderView(html: string, scope: Readonly<Record<string, unknown>>): string {
+  return renderTemplate(renderRows(html, scope), scope);
+}

apps/api/src/modules/interaction/internal/usecase/interaction-service.ts

@@ -68,6 +68,10 @@ export function createInteractionService(deps: InteractionServiceDeps): Interact
       broadcast({ kind: 'view-html', taskId, html });
     },
 
+    async viewOf(taskId) {
+      return deps.store.getView(taskId);
+    },
+
     async setPhase(taskId: TaskId, phase: InteractionPhase) {
       await deps.store.setPhase(taskId, phase);
       const output = outputControl(phase);

apps/api/src/modules/interaction/port.ts

@@ -11,6 +11,7 @@ export type InteractionStore = {
   appendMessage(taskId: TaskId, message: ChatMessage): Promise<void>;
   listMessages(taskId: TaskId): Promise<ChatMessage[]>;
   putView(taskId: TaskId, view: { blocks?: readonly ViewBlock[]; html?: string }): Promise<void>;
+  getView(taskId: TaskId): Promise<{ blocks?: readonly ViewBlock[]; html?: string } | undefined>;
   setPhase(taskId: TaskId, phase: InteractionPhase): Promise<void>;
   phaseOf(taskId: TaskId): Promise<InteractionPhase | undefined>;
 };