@zhushanwen/pi-structured-output 6.1.3 → 6.2.1

package/README.md

@@ -74,9 +74,9 @@ structured-output/
     ├── tool-definition.ts  # 双变体工具定义（workflow 单参数 / 日常双参数）
     ├── execute.ts          # 校验编排（workflow 透传 / 日常防御链）+ 根形态判定
     ├── ajv-validator.ts    # Ajv 编译缓存（WeakMap）
-    ├── schema-guards.ts    # 形态守卫纯函数（互换检测 / 关键字识别 / JSON 解析回显）
+    ├── schema-guards.ts    # 形态检查纯函数（互换检测 / 关键字识别 / JSON 解析回显）
     ├── workflow-hook.ts    # turn_end 强制调用 hook + RetryState 状态机
-    ├── loop-gate.ts        # 同签名失败 ×3 有界闸门（abort + shutdown + 硬退兜底）
+    ├── loop-gate.ts        # 同签名失败 ×3 有界门禁（abort + shutdown + 硬退兜底）
     └── text-primitives.ts  # 截断/错误块有界化共享原语
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-structured-output",
-  "version": "6.1.3",
+  "version": "6.2.1",
   "description": "Structured output tool for Pi — workflow schema enforcement via pi's parameter layer; interactive mode validates self-reported schemas with Ajv",
   "type": "module",
   "main": "index.ts",
@@ -26,16 +26,21 @@
   ],
   "dependencies": {
     "ajv": "^8.17.0",
+    "@zhushanwen/extension-protocol": "0.22.0",
     "@zhushanwen/pi-ext-guards": "0.5.0"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "^1.0.0",
     "@earendil-works/pi-coding-agent": "^1.0.0",
-    "typebox": "1.3.27",
-    "@earendil-works/pi-ai": "^1.0.0"
+    "@earendil-works/pi-tui": "^1.0.0",
+    "typebox": "1.3.27"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
       "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
     }
   },
   "devDependencies": {

package/src/index.ts

@@ -4,19 +4,19 @@
  * 装配分岔（D1，U1）：读 PI_WORKFLOW_SCHEMA——
  *   - 有值（workflow 子进程）：注册 workflow 变体（parameters = 权威 schema 本身，
  *     D4 根级 additionalProperties 注入 / P6 非 object 根 {value} 包装 / 注册期
- *     fail-fast 防御都在 createWorkflowToolDefinition 内）+ 双闸门合一 hook
+ *     fail-fast 防御都在 createWorkflowToolDefinition 内）+ 双门禁合一 hook
  *   - 无值（日常 pi）：注册日常变体（双参数自报形态，行为不变，G4）
  *
  * Hook 机制（仅 workflow 模式，D2 单状态机单 listener）：
  *   turn_end 时检查模型是否调用了 structured-output 工具，没调/失败则 steer 注入
- *   重试提醒（软闸门，最多重试 2 次）。同一状态机（WorkflowGate）上的硬杀闸门在
+ *   重试提醒（软门禁，最多重试 2 次）。同一状态机（WorkflowGate）上的硬杀门禁在
  *   同签名校验失败达 3 次时 terminal：写日志（stderr + session JSONL 双通道，含恢复
  *   指引）后 ctx.abort() + ctx.shutdown() 优雅终止子进程（无兜底硬退 timer，ADR-0122）——
- *   terminal 后软闸门不再 steer（同一份 terminal 事实，无跨对象接线；G2 与模型
+ *   terminal 后软门禁不再 steer（同一份 terminal 事实，无跨对象接线；G2 与模型
  *   配合度无关）。装配与 listener 明细见 workflow-hook.setupWorkflowHook。
  *
  * 模块拆分（M4 + D2 合一）：实现体分布于 ajv-validator.ts（编译缓存）/
- * schema-guards.ts（形态守卫）/ execute.ts（校验编排）/ tool-definition.ts（工具定义）/
+ * schema-guards.ts（形态检查）/ execute.ts（校验编排）/ tool-definition.ts（工具定义）/
  * workflow-hook.ts（唯一装配入口 + steer 文案）/ loop-gate.ts（合一状态机 +
  * 错误签名归一化 + terminal 副作用链）。本文件仅剩 entry 装配与 re-export。
  */
@@ -52,7 +52,7 @@ export default function structuredOutputExtension(pi: PiAPI): void {
 	const schemaEnv = process.env[ENV_SCHEMA];
 
 	if (schemaEnv) {
-		// ── Workflow 模式：单参数工具（注册期 fail-fast 防御）+ 双闸门合一 hook ──
+		// ── Workflow 模式：单参数工具（注册期 fail-fast 防御）+ 双门禁合一 hook ──
 		// D2：软 steer 与硬杀由同一 WorkflowGate 状态机承载（单状态机单 listener），
 		// terminal 单字段单写，硬杀不需要向 steer 侧做任何回调同步。
 		pi.registerTool(createWorkflowToolDefinition(schemaEnv));

package/src/loop-gate.ts

@@ -1,9 +1,9 @@
 /**
- * 有界失败闸门 + steer 记账——双闸门合一状态机（D2 单状态机）+ G2「失败必有界」执行体。
+ * 有界失败门禁 + steer 记账——双门禁合一状态机（D2 单状态机）+ G2「失败必有界」执行体。
  *
  * 状态归属（D2 单状态机）：软 steer（workflow-hook 的重试提醒）与硬杀（本文件的
  * 同签名失败 terminal）共用 WorkflowGate 一份状态——terminal 单字段单写，turn_end
- * 守卫链与硬杀幂等短路读同一份事实；若拆成两个状态机，terminal 双写就需要跨对象
+ * 检查链与硬杀幂等短路读同一份事实；若拆成两个状态机，terminal 双写就需要跨对象
  * 回调同步，漏接线即 steer 与硬杀失步（单状态机使失步在结构上不可能）。
  *
  * 通道选型（设计 §6.3；pi 0.84.1 实装，登记 PS-20）：
@@ -51,8 +51,8 @@
  * 一个 listener，同一 tool_execution_end 内先 steer 记账后硬杀计数——与合一前两
  * listener 的注册顺序一致）。
  *
- * 诚实边界（设计 §6.3）：闸门只终止「同签名无进展」这一种循环形态；签名不断
- * 变化的长尾低效不触发闸门，仍由 workflow 层 maxTurns 兜底。
+ * 诚实边界（设计 §6.3）：门禁只终止「同签名无进展」这一种循环形态；签名不断
+ * 变化的长尾低效不触发门禁，仍由 workflow 层 maxTurns 兜底。
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -119,7 +119,7 @@ function requiredBulletPrefix(bulletPath: string, firstField: string): string {
  *   2. 日常模式 ajv（execute.ts instancePath 拼接形态，ajv locale 模板大写 "must
  *      NOT have additional properties"）——模板词组含空格与固定语序，字段名不可能
  *      携带。该形态无 "Received arguments:" 回显段，keys 分桶天然不激活
- *      （hasApError 仅作标记；闸门仅 workflow 模式装配，此形态实为防御性保留）。
+ *      （hasApError 仅作标记；门禁仅 workflow 模式装配，此形态实为防御性保留）。
  */
 const AP_LINE_SUFFIX_RE = /^(.*):\s*must not have additional properties\s*$/;
 const AP_AJV_MESSAGE_RE = /must NOT have additional properties/;
@@ -143,7 +143,7 @@ const AP_BULLET_MESSAGE = "must not have additional properties";
  *
  * 有意决策（披露）：token 集合只含字段/路径、不含错误类型——同一字段换约束试错
  * （"must be string" → "must be number"）折叠为同签名。权衡：换取「集合不变 = 无进展」
- * 的强判定；代价是弱模型对单字段多约束的试错容忍度下降（同字段反复错达阈值即闸门）。
+ * 的强判定；代价是弱模型对单字段多约束的试错容忍度下降（同字段反复错达阈值即门禁）。
  *
  * 同时报告错误行块是否含 AP 错误行（hasApError）——normalizeErrorSignature 据此
  * 门控 echo keys 并入（分桶动机见该函数注释）；并收集 AP 错误行的路径位集合
@@ -344,19 +344,19 @@ export function normalizeErrorSignature(errorText: string): string {
 }
 
 /**
- * structured-output 双闸门合一状态机（D2 单状态机；纯逻辑，可单测）。
+ * structured-output 双门禁合一状态机（D2 单状态机；纯逻辑，可单测）。
  *
  * 状态分区（一个对象、一份 terminal 事实）：
  *   - steer 侧（workflow-hook turn_end 消费）：soCallCount / soSucceededEver /
  *     hookRetryCount / lastSchemaError。
  *   - 硬杀侧：lastSignature / consecutiveFailures / lastErrorText。
  *   - 共享终态：terminal——硬杀触发后置位（不可逆，仅 reset() 可清），turn_end
- *     守卫链据此停 steer，硬杀计数据此幂等短路。
+ *     检查链据此停 steer，硬杀计数据此幂等短路。
  *
  * 转移表（loop-gate.test.ts / retry-state.test.ts 锁定）：
  *   onToolExecEnd(hasError, errorText?)（每事件一次，先记账后计数——与合一前两
  *   listener 的注册顺序一致）：
- *   - steer 记账段（不受 terminal 短路影响：terminal 后迟到的失败仍记录，闸门自身
+ *   - steer 记账段（不受 terminal 短路影响：terminal 后迟到的失败仍记录，门禁自身
  *     幂等，重复事件无害）：
  *     - (!hasError)            → soCallCount++ / soSucceededEver=true
  *     - (hasError, errorText)  → soCallCount++ / lastSchemaError=errorText ?? 通用提示
@@ -380,7 +380,7 @@ export class WorkflowGate {
 	consecutiveFailures = 0;
 	/** 最近一次失败的原始终态文本（截断后），供 terminal 日志引用。 */
 	lastErrorText: string | null = null;
-	// ── 共享终态（单字段单写：硬杀计数段置位，两闸门读同一份）──────
+	// ── 共享终态（单字段单写：硬杀计数段置位，两门禁读同一份）──────
 	terminal = false;
 
 	/**
@@ -510,7 +510,7 @@ export function runTerminalTeardown(pi: PiAPI, gate: WorkflowGate, ctx: Extensio
 	// （PS-30，runner.js createContext）——session 替换窗口触发 terminal 时无人接的
 	// 同步 throw 会经 async handler 变 rejected Promise 杀 pi 进程。stale 静默跳过
 	// 优雅退出（此时进程的存在意义已随 session 替换消失）。非 stale 错误原样上抛
-	//（守卫不吞真实 bug）。
+		//（检查不吞真实 bug）。
 	guardStaleCtx(() => {
 		ctx.abort();
 		ctx.shutdown();

package/src/render-result.ts

@@ -0,0 +1,64 @@
+/**
+ * structured-output 工具的 TUI renderResult（折叠态一行摘要 / 展开态 content 纯文本）。
+ *
+ * 摘要不进 details：本工具的 result.details 是模型的结构化产出本体（workflow 引擎
+ * output-collector 的 extractParsedOutput 原样取走作 agent parsedOutput），混入 summary
+ * 键会污染产出契约（object 形态多出合同外字段、primitive 形态无处挂载）。因此成功路径
+ * 折叠态摘要 = 固定文案，不依赖数据。
+ *
+ * 错误路径（context.isError）不能用成功文案——pi 对失败轮同样调用 renderResult
+ *（tool-execution.js 传 {content, details} 给 renderResult，isError 只在第 4 参 context），
+ * 而 runResult 的 content 是校验失败文案。此时折叠态回退 content 首行，避免把失败显示成
+ *「schema validated」的假成功。判定靠 context.isError 事实，不做 content 文案匹配。
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { firstContentText } from "@zhushanwen/extension-protocol";
+
+/** 成功轮折叠态一行摘要（两种注册变体统一；错误轮走 firstLine(contentText)）。 */
+export const STRUCTURED_OUTPUT_SUMMARY = "Final result reported (schema validated)";
+
+/**
+ * renderResult 的 context（SDK ToolRenderContext 的有意子集——结构兼容只声明本组件
+ * 需要的字段）。SDK 实际传入更完整的 { args, toolCallId, cwd, ..., isError }。
+ */
+export interface StructuredOutputRenderContext {
+	isError?: boolean;
+}
+
+/** content[0] 的 text 纯文本（content 缺失或非 text 类型时兜底空串）。 */
+/** unknown 值按字段名安全取值（index-signature 收窄，替代全可选结构断言）。 */
+function fieldValue(v: unknown, key: string): unknown {
+	if (typeof v !== "object" || v === null) return undefined;
+	return (v as Record<string, unknown>)[key];
+}
+
+function contentText(result: unknown): string {
+	const content = fieldValue(result, "content");
+	if (!Array.isArray(content)) return "";
+	return firstContentText({ content });
+}
+
+/** 折叠态回退：content 文本取首行（保持一行摘要形态）。 */
+function firstLine(text: string): string {
+	const idx = text.indexOf("\n");
+	return idx === -1 ? text : text.slice(0, idx);
+}
+
+/**
+ * 折叠态（expanded=false）：成功 = 固定一行摘要；错误 = content 首行（dim）。
+ * 展开态 = content 纯文本。context 可选——旧的三参调用（测试 / 历史 caller）按成功处理。
+ */
+export function renderStructuredOutputResult(
+	result: unknown,
+	options: { expanded: boolean },
+	theme: Theme,
+	context?: StructuredOutputRenderContext,
+): Text {
+	if (options.expanded) return new Text(contentText(result), 0, 0);
+	const summary = context?.isError === true
+		? firstLine(contentText(result))
+		: STRUCTURED_OUTPUT_SUMMARY;
+	return new Text(theme.fg("dim", summary), 0, 0);
+}

package/src/schema-guards.ts

@@ -1,12 +1,12 @@
 /**
- * Schema 形态守卫 — 纯逻辑叶节点（零业务依赖，全导出）。
+ * Schema 形态检查 — 纯逻辑叶节点（零业务依赖，全导出）。
  *
  * 从 index.ts 拆出：swap 检测 + silent-corruption prevention 的一组纯函数。
  *
  * 核心问题：schema 和 data 参数都用 Type.Unknown()，结构无差别。弱模型常把答案
  * 塞进 schema、把形状塞进 data。因 ajv strict:false 把无 keyword 的对象编译成
  * "接受一切" 的 validator，互换后会校验通过、存垃圾、无报错（静默腐败）。
- * 这组守卫在编译前拦截两类形态：互换（schema 像数据 + data 像 schema）和
+ * 这组检查在编译前拦截两类形态：互换（schema 像数据 + data 像 schema）和
  * keyword-less schema（{} / {a:1} 这种会被 ajv 静默放行）。
  */
 
@@ -80,8 +80,8 @@ export function tryParseJson(raw: unknown): unknown {
 /**
  * 把 authoritative schema 的 unknown 收窄为合法 JSON Schema 根类型（object | boolean）。
  * draft-07 允许 boolean 根 schema（true=接受一切，false=拒绝一切）。
- * 独立守卫使后续 getOrCompileValidator(authoritative) 在类型层面也成立，
- * 避免在守卫块外直接用 unknown。非合法形态抛清晰错误。
+ * 独立检查使后续 getOrCompileValidator(authoritative) 在类型层面也成立，
+ * 避免在检查块外直接用 unknown。非合法形态抛清晰错误。
  */
 export function assertJsonSchemaRoot(value: unknown): asserts value is Record<string, unknown> | boolean {
 	if (!(isRecord(value) || typeof value === "boolean")) {
@@ -94,7 +94,7 @@ export function isTurnEndEvent(e: unknown): e is { message?: { stopReason?: stri
 	return typeof e === "object" && e !== null;
 }
 
-/** tool_execution_end event 结构守卫（替代直接 cast，配合 taste/no-unsafe-cast）。 */
+/** tool_execution_end event 结构检查（替代直接 cast，配合 taste/no-unsafe-cast）。 */
 export function isToolExecutionEndEvent(
 	e: unknown,
 ): e is { toolName: unknown; isError: unknown; result?: unknown } {

package/src/text-primitives.ts

@@ -10,7 +10,7 @@
  */
 
 /**
- * 闸门签名侧截断上限：① normalizeErrorSignature fallback 分支（提取不到字段 token 的
+ * 门禁签名侧截断上限：① normalizeErrorSignature fallback 分支（提取不到字段 token 的
  * 非校验类错误文本降级为裸前缀做等值比较，消费方 loop-gate）；② WorkflowGate.lastErrorText
  * （terminal 日志引用，不进模型上下文，消费方 loop-gate）。与 steer 回灌错误块上限
  * （STEER_ERROR_MAX_CHARS）语义独立（F5 拆分：签名只做比较原料、可随实现演化；steer

package/src/tool-definition.ts

@@ -18,10 +18,13 @@
  * 两变体的描述文本均被 prompt-quality.test.ts 文本断言锁定。
  */
 
+import type { Theme } from "@earendil-works/pi-coding-agent";
 import { isRecord } from "@zhushanwen/pi-ext-guards";
 import { Type } from "typebox";
 
 import { executeStructuredOutput, isObjectRootSchema } from "./execute.js";
+import { renderStructuredOutputResult } from "./render-result.js";
+import type { StructuredOutputRenderContext } from "./render-result.js";
 import {
 	assertJsonSchemaRoot,
 	echo,
@@ -43,7 +46,7 @@ export const ENV_SCHEMA = "PI_WORKFLOW_SCHEMA";
  * 各自保留、跨包契约测试锁字节相等（tests/cross-package-contract.test.ts）。
  * 本侧职责仅可见性：注册时超限 logger.warn（无 logger API，stderr 直出惯例）提示
  * env 通道有上限，建议拆分 schema 或精简——不拒绝注册（子进程能收到 env 说明 SW
- * 侧闸门已放行，此处拒绝只会把可诊断的降级变成无法启动）。
+ * 侧门禁已放行，此处拒绝只会把可诊断的降级变成无法启动）。
  *
  * [跨包契约] 任一端改值必须同步另一端，否则 SW 侧硬拒绝线与 SO 侧提示线漂移。
  */
@@ -163,6 +166,18 @@ export function createWorkflowToolDefinition(envSchema: string) {
 			// 「根是否 object」对称完成（与注册期包装判定同一函数 isObjectRootSchema）。
 			return executeStructuredOutput({ data: params, authoritativeSchema: schema });
 		},
+
+		// 摘要不进 details：details 是模型的结构化产出本体（workflow 引擎 extractParsedOutput
+		// 原样消费），成功轮折叠态摘要 = render-result 的固定文案；失败轮（context.isError）
+		// 回退 content 首行，避免把校验失败显示成「schema validated」。
+		renderResult(
+			result: unknown,
+			options: { expanded: boolean },
+			theme: Theme,
+			context?: StructuredOutputRenderContext,
+		) {
+			return renderStructuredOutputResult(result, options, theme, context);
+		},
 	};
 }
 
@@ -240,5 +255,16 @@ export function createDailyToolDefinition() {
 					: params,
 			);
 		},
+
+		// 摘要不进 details：同 workflow 变体（details = 数据本体，parsedOutput 契约）；
+		// 失败轮折叠态回退 content 首行（context.isError）。
+		renderResult(
+			result: unknown,
+			options: { expanded: boolean },
+			theme: Theme,
+			context?: StructuredOutputRenderContext,
+		) {
+			return renderStructuredOutputResult(result, options, theme, context);
+		},
 	};
 }

package/src/workflow-hook.ts

@@ -6,11 +6,11 @@
  *     steer 记账段 + 硬杀计数段，先记账后计数），newlyTerminal 时触发硬杀副作用链
  *     （runTerminalTeardown：日志 → abort+shutdown 优雅终止）。
  *   - turn_end：唯一 listener——模型未成功产出 structured-output 时以 steer 方式注入
- *     重试提醒（软闸门），提示词不伪装用户气泡，对话流用户内容 100% 来自用户输入；
+ *     重试提醒（软门禁），提示词不伪装用户气泡，对话流用户内容 100% 来自用户输入；
  *     最多重试 MAX_HOOK_RETRIES 次，防止无限循环。
  *
- * 软硬闸门合一语义：terminal 是 WorkflowGate 上的单一事实——硬杀计数段置位后，
- * turn_end 守卫链第 0 条据此停 steer；两闸门间无任何回调接线（terminal 若双写于
+ * 软硬门禁合一语义：terminal 是 WorkflowGate 上的单一事实——硬杀计数段置位后，
+ * turn_end 检查链第 0 条据此停 steer；两门禁间无任何回调接线（terminal 若双写于
  * 两个状态机，就必须跨对象回调同步，漏接线即 steer 与硬杀失步——单状态机单写使
  * 失步在结构上不可能）。
  *
@@ -52,10 +52,10 @@ export const HOOK_ENTRY_TYPE = "structured-output:hook";
 export const RETRY_REMINDER_CUSTOM_TYPE = "structured-output:retry-reminder";
 
 /**
- * steer 守卫链（原 turn_end handler 内联守卫提取，判定顺序与旧实现逐条一致）。
- * 命中任一守卫即跳过 steer，且调用方不调 onTurnEnd（toolUse/error/aborted 保留
+ * steer 检查链（原 turn_end handler 内联检查提取，判定顺序与旧实现逐条一致）。
+ * 命中任一检查即跳过 steer，且调用方不调 onTurnEnd（toolUse/error/aborted 保留
  * soCallCount、超上限保留 lastSchemaError，与合一前逐点一致）：
- *   0. 闸门 terminal（D3/U2）：同签名失败已满 3 次、shutdown 已发——不再 steer，
+ *   0. 门禁 terminal（D3/U2）：同签名失败已满 3 次、shutdown 已发——不再 steer，
  *      让进程终止（防御性保留：shutdown 正常生效时进程已死，到不了这里）
  *   1. 已经成功调用过 structured-output，不再干预
  *   2. 不是合法 turn_end 事件
@@ -154,13 +154,13 @@ function writeSteerFailedLog(pi: PiAPI, hookRetryCount: number, err: unknown): v
 }
 
 /**
- * 装配 workflow 模式的双闸门（D2 唯一装配入口，仅 workflow 模式调用，见 src/index.ts）。
+ * 装配 workflow 模式的双门禁（D2 唯一装配入口，仅 workflow 模式调用，见 src/index.ts）。
  *
  * 每个事件至多一个 listener（单 listener 契约，D2）：
- *   - tool_execution_end：结构守卫 → toolName 过滤 → WorkflowGate.onToolExecEnd
+ *   - tool_execution_end：结构检查 → toolName 过滤 → WorkflowGate.onToolExecEnd
  *     （合一状态机：先 steer 记账后硬杀计数）→ newlyTerminal 时 runTerminalTeardown
  *     （terminal 时序与副作用明细见该函数注释）。
- *   - turn_end：守卫链 shouldSkipSteer → 两种失败形态都 steer：
+ *   - turn_end：检查链 shouldSkipSteer → 两种失败形态都 steer：
  *     1. 完全没调用（soCallCount === 0）→ 注入"必须调用"提示 + 正确 schema
  *     2. 调了但全是 isError（soCallCount > 0 && !soSucceededEver）→ 注入具体校验错误
  *        + 正确 schema。旧实现在此处撒手交给 Pi 自然修正，但模型遇到 "Invalid JSON Schema"
@@ -193,7 +193,7 @@ export function setupWorkflowHook(pi: PiAPI, schemaJson: string): void {
 	});
 
 	pi.on("turn_end", async (event: unknown) => {
-		// 守卫链（判定明细见 shouldSkipSteer 注释）：命中即直接 return，不调
+		// 检查链（判定明细见 shouldSkipSteer 注释）：命中即直接 return，不调
 		// onTurnEnd——预算不扣减，状态保留到下一个正常收尾的轮再判定 steer。
 		if (shouldSkipSteer(state, event)) return;