@zhushanwen/pi-structured-output 5.1.7 → 5.1.9

package/README.md

@@ -0,0 +1,85 @@
+# @zhushanwen/pi-structured-output
+
+结构化输出 pi extension：让模型用经过 JSON Schema 校验的工具调用代替自由文本交付结果。按 `PI_WORKFLOW_SCHEMA` 环境变量装配两种变体——workflow 模式以引擎注入的权威 schema 强制约束产出，日常模式校验模型自报 schema 的数据。
+
+## 两种模式
+
+启动时读取 `PI_WORKFLOW_SCHEMA`（该 env 由 subagent workflow 引擎注入子进程）：
+
+| | workflow 模式（env 有值） | 日常模式（env 无值） |
+|---|---|---|
+| 工具参数 | 单参数——parameters 即权威 schema 本身 | 双参数 `{schema, data}` 自报形态 |
+| 校验权威 | pi 参数层直接按权威 schema 校验模型 arguments，execute 透传不二次校验 | Ajv 校验自报 data（防御链见下） |
+| 强制手段 | turn_end 未成功调用工具（完全未调用，或调用了但全部校验失败）→ steer 注入重试（整个子进程生命周期最多 2 次）；同签名失败连续 3 次 → 写日志后 abort 当前 turn + shutdown 子进程，15s 内未退出则进程硬退兜底 | 无（普通工具，失败抛错由模型自修） |
+
+## 提供的工具
+
+### `structured-output`
+
+**workflow 模式**（`PI_WORKFLOW_SCHEMA` 有值时注册）：
+
+- object 根 schema：arguments 即数据本身，如 `structured-output({ score: 8 })`
+- 非 object 根 schema（array/string/number/boolean/组合根等）：包装为 `{ value: <data> }`（tool call arguments 协议上必须是 object），错误路径带 `value.` 前缀
+- 根级 `additionalProperties` 未声明时注入 `false`：模型多传的字段被参数层显式拒绝（作者显式声明则尊重不动）
+- 注册期 fail-fast：非法 schema（非 object/boolean 根、boolean true、无任何关键字的 object）在子进程加载期即终止并指回 workflow 脚本的 schema 定义；schema 超 256KiB 时 stderr 提示精简/拆分（硬拒绝在引擎注入侧）
+
+**日常模式**（交互式 pi 注册）：
+
+- `schema`：JSON Schema draft-07 对象
+- `data`：待校验的值（原始类型/object/array 均可）
+
+日常模式防御链（编译前拦截，全部抛错并带回显与纠错提示）：
+
+1. 互换检测——schema 像数据且 data 像 schema → 判定为参数装反，拒绝
+2. 无关键字 schema 拒绝——`{}` / `{a:1}` 会被 Ajv（`strict:false`）编译成"接受一切"，静默放行垃圾数据
+3. Ajv 编译失败 → 报 Invalid JSON Schema
+4. 校验失败 → 报告失败字段路径
+
+## 安装
+
+```bash
+# npm 方式（正式）
+pi install npm:@zhushanwen/pi-structured-output
+
+# 本地路径加载（开发调试；-e 为 --extension 简写，可多次传入）
+pi -e /path/to/extensions/universal/structured-output
+pi --extension /path/to/extensions/universal/structured-output
+```
+
+## 示例
+
+日常模式（模型自报 schema + data）：
+
+```
+structured-output({
+  schema: { type: "object", properties: { score: { type: "number" } }, required: ["score"] },
+  data: { score: 8 }
+})
+```
+
+workflow 模式（schema 由引擎注入，模型只提交数据）：
+
+```
+structured-output({ score: 8 })            # object 根：arguments 即数据
+structured-output({ value: [1, 2, 3] })    # array 根：包装在 value 字段
+```
+
+## 文件结构
+
+```
+structured-output/
+├── index.ts            # 入口 — re-export src/index.ts
+└── src/
+    ├── index.ts            # 装配分岔：读 PI_WORKFLOW_SCHEMA 选择变体 + re-export
+    ├── tool-definition.ts  # 双变体工具定义（workflow 单参数 / 日常双参数）
+    ├── execute.ts          # 校验编排（workflow 透传 / 日常防御链）+ 根形态判定
+    ├── ajv-validator.ts    # Ajv 编译缓存（WeakMap）
+    ├── schema-guards.ts    # 形态守卫纯函数（互换检测 / 关键字识别 / JSON 解析回显）
+    ├── workflow-hook.ts    # turn_end 强制调用 hook + RetryState 状态机
+    ├── loop-gate.ts        # 同签名失败 ×3 有界闸门（abort + shutdown + 硬退兜底）
+    └── text-primitives.ts  # 截断/错误块有界化共享原语
+```
+
+## License
+
+MIT

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zhushanwen/pi-structured-output",
-  "version": "5.1.7",
+  "version": "5.1.9",
   "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",
-  "xyz-agent": {
+  "taiji": {
     "role": "universal"
   },
   "pi": {
@@ -25,7 +25,7 @@
   ],
   "dependencies": {
     "ajv": "^8.17.0",
-    "@zhushanwen/pi-ext-guards": "0.4.0"
+    "@zhushanwen/pi-ext-guards": "0.4.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",

package/src/index.ts

@@ -9,7 +9,7 @@
  *
  * Hook 机制（仅 workflow 模式）：
  *   turn_end 时检查模型是否调用了 structured-output 工具。
- *   如果没调 → 通过 pi.sendUserMessage() 注入 steering message 强制调用。
+ *   如果没调 → 通过 pi.sendMessage()（custom message）注入 steering message 强制调用。
  *   最多重试 2 次，防止无限循环。
  *
  * 失败闸门（仅 workflow 模式，D3/U2）：

package/src/loop-gate.ts

@@ -458,7 +458,7 @@ export function armForceExitTeardown(): void {
 
 /**
  * terminal 态日志（§5.2 形态 b）：
- *   - stderr：子进程 stderr 直出（xyz-agent runtime 的 pi-*.jsonl tee / 本地探针可见）
+ *   - stderr：子进程 stderr 直出（taiji runtime 的 pi-*.jsonl tee / 本地探针可见）
  *   - appendEntry：session JSONL 持久化记录（事后排查通道，不进 LLM 上下文）
  * 两者内容同源，指引文案逐字对齐设计 §5.2。
  */

package/src/workflow-hook.ts

@@ -1,6 +1,7 @@
 /**
  * Workflow hook：turn_end 时检查模型是否成功调用 structured-output 工具。
- * 未成功时通过 pi.sendUserMessage({deliverAs:"steer"}) 注入 steering message 重试。
+ * 未成功时通过 pi.sendMessage（custom message，display:false）以 steer 方式注入
+ * steering message 重试——提示词不伪装用户气泡，对话流用户内容 100% 来自用户输入。
  * 最多重试 MAX_HOOK_RETRIES 次，防止无限循环。
  *
  * RetryState：从旧 4 个 mutable 闭包（soCallCount/soSucceededEver/hookRetryCount/
@@ -90,6 +91,14 @@ export class RetryState {
 /** steer 发送失败告警的 appendEntry customType（session JSONL 持久化，不进 LLM 上下文）。 */
 export const HOOK_ENTRY_TYPE = "structured-output:hook";
 
+/**
+ * steer reminder 的 sendMessage customType（role:"custom" 消息，pi convertToLlm 对其
+ * 无条件转 LLM user 消息——LLM 可见性与 user message 无差别；display:false 不渲染
+ * 用户气泡，对话流归属语义结构性正确。锚点登记 docs/pi-semantics.json PS-43：
+ * pi dist/core/messages.js:89-96 case "custom" 无条件 role:"user"）。
+ */
+export const RETRY_REMINDER_CUSTOM_TYPE = "structured-output:retry-reminder";
+
 /**
  * steer 发送失败告警（审查项#8 失败路径）：双通道落盘（同 loop-gate writeTerminatedLog
  * 惯例）——stderr 直出 + appendEntry 持久化。预算未扣减由「不调 onTurnEnd」结构保证，
@@ -194,7 +203,8 @@ function buildSteerReminder(
 
 /**
  * 注册 turn_end hook，检查模型是否成功调用 structured-output 工具。
- * 未成功时通过 pi.sendUserMessage({deliverAs:"steer"}) 注入 steering message 重试。
+ * 未成功时通过 pi.sendMessage（custom message，display:false）以 steer 方式注入
+ * steering message 重试。
  * 最多重试 MAX_HOOK_RETRIES 次，防止无限循环。
  *
  * @returns 共享的 RetryState（U2：index.ts 拿它接线 loop-gate 的 onTerminal 回调）。
@@ -240,14 +250,18 @@ export function setupWorkflowHook(pi: PiAPI, schemaJson: string): RetryState {
 		// 故 onTurnEnd()（清空 lastSchemaError）必须在发送成功之后调用。
 		const reminder = buildSteerReminder(calledButFailed, state.lastSchemaError, schemaJson, isObjectRoot);
 
-		// 审查项#8：await 发送结果——发送失败（如 compaction 中 prompt() 抛错 / 扩展已
+		// 审查项#8：await 发送结果——发送失败（如 compaction 中开轮抛错 / 扩展已
 		// 被 assertActive 拒绝）不扣减重试预算（不调 onTurnEnd），否则 fire-and-forget
 		// 丢一份 steer + 白扣一次预算，两次即永久哑火。
-		// pi 0.84.1 实装（loader.js）：extension 侧 sendUserMessage 同步转发且吞掉异步
-		// rejection（转 emitError）返回 void——await 对 undefined 立即解析；此处的
-		// try/catch 兜住同步 throw（assertActive）与未来 pi 返回真 Promise 的形态。
+		// pi 0.84.4 实装（loader.js）：extension 侧 sendMessage 同步转发且吞掉异步
+		// rejection（bindCore .catch(emitError) 转事件）返回 void——await 对 undefined
+		// 立即解析；此处的 try/catch 兜住同步 throw（assertActive）与未来 pi 返回真
+		// Promise 的形态。
 		try {
-			await pi.sendUserMessage(reminder, { deliverAs: "steer" });
+			await pi.sendMessage(
+				{ customType: RETRY_REMINDER_CUSTOM_TYPE, content: reminder, display: false },
+				{ deliverAs: "steer", triggerTurn: true },
+			);
 		} catch (err) {
 			writeSteerFailedLog(pi, state.hookRetryCount, err);
 			return;