agentworkshop 0.7.70 → 0.7.71

package/server/services/workshop/agents/adapters/omp-rpc-client/types.ts

@@ -1,115 +1,121 @@
-/**
- * OmpRpcClient 的依赖类型与对外 DTO(原 server/services/workshop/agents/adapters/omp-rpc-client.ts 顶部模块级类型声明)。纯类型。
- */
-
-export type RpcCommand
-  = | { id?: string, type: 'prompt', message: string, streamingBehavior?: 'steer' | 'followUp' }
-    | { id?: string, type: 'steer', message: string }
-    | { id?: string, type: 'follow_up', message: string }
-    | { id?: string, type: 'abort' }
-    | { id?: string, type: 'set_host_tools', tools: RpcHostToolDefinition[] }
-    | { id?: string, type: 'set_todos', phases: unknown[] }
-    | { id?: string, type: 'negotiate_protocol', protocolVersion: number }
-    | { id?: string, type: 'set_model', provider: string, modelId: string }
-    | { id?: string, type: 'get_state' }
-    | { id?: string, type: 'new_session' }
-    // ===== 上下文治理(70% 压缩环;协议权威 omp://rpc.md)=====
-    | { id?: string, type: 'get_session_stats' }
-    | { id?: string, type: 'compact', customInstructions?: string }
-    | { id?: string, type: 'set_auto_compaction', enabled: boolean }
-
-/** compaction 结果(compaction_end 事件 / compact 响应 data.result 共用形状) */
-export interface CompactionResult {
-  summary?: string
-  tokensBefore?: number
-  tokensAfter?: number
-  estimatedTokensAfter?: number
-}
-
-/** provider 用量(被动上下文跟踪源;message_update 等帧携带的累计值) */
-export interface RpcUsage {
-  /** input tokens ≈ 当前上下文长度(本回合 LLM 调用的 prompt 规模) */
-  input: number
-  output?: number
-  cacheRead?: number
-  at: number
-}
-/** host 工具定义(omp 端可见的工具 schema) */
-export interface RpcHostToolDefinition {
-  name: string
-  label?: string
-  description: string
-  parameters: Record<string, unknown>
-  hidden?: boolean
-}
-
-/** RPC 响应(命令执行结果) */
-export interface RpcResponse {
-  id?: string
-  type: 'response'
-  command: string
-  success: boolean
-  data?: unknown
-  error?: string
-  code?: string
-}
-
-/** omp AgentSession 事件(本项目消费的子集) */
-export interface AgentSessionEvent {
-  type: string
-  // message_update
-  assistantMessageEvent?: {
-    type: 'text_delta' | 'text_start' | 'text_end' | 'thinking_delta' | 'tool_call' | 'tool_result' | string
-    delta?: string
-    text?: string
-    toolName?: string
-    toolCallId?: string
-    [k: string]: unknown
-  }
-  message?: { role: string, content: unknown[] }
-  // agent_end
-  messages?: Array<{ role: string, content: Array<{ type: string, text?: string }> }>
-  isTerminal?: boolean
-  // tool_execution
-  toolName?: string
-  toolCallId?: string
-  [k: string]: unknown
-}
-
-/** omp 向宿主发起的 host_tool_call 请求 */
-export interface HostToolCallRequest {
-  id: string
-  toolCallId: string
-  toolName: string
-  arguments: Record<string, unknown>
-}
-
-/** 宿主工具 handler:接收 omp 的工具调用,返回结果 */
-export type HostToolHandler = (req: HostToolCallRequest) => Promise<{ text: string, isError?: boolean }>
-
-/** RPC 客户端配置 */
-export interface OmpRpcClientOptions {
-  /** omp 可执行文件路径(默认 'omp') */
-  command?: string
-  /**
-   * 输出模式:'rpc' = 纯协议(无 UI);'rpc-ui' = 协议 + UI 上下文
-   * (ask 工具 / extension_ui_request 对话框可用 —— HITL 通道;强制 noPty)。默认 'rpc'。
-   */
-  mode?: 'rpc' | 'rpc-ui'
-  /** 额外 CLI 参数 */
-  args?: string[]
-  /** 工作目录 */
-  cwd?: string
-  /** 环境变量 */
-  env?: Record<string, string>
-  /** 进程退出回调(运行时资源监控登记/标记用;pid 为 -1 表示无法取得) */
-  onExit?: (pid: number, code: number | null) => void
-}
-
-export interface PendingRequest {
-  resolve: (response: RpcResponse) => void
-  reject: (error: Error) => void
-  timer?: ReturnType<typeof setTimeout>
-}
-
-/** 流式缓冲上限(超限截断并计数,防大输出/异常流拖爆内存) */
+/**
+ * OmpRpcClient 的依赖类型与对外 DTO(原 server/services/workshop/agents/adapters/omp-rpc-client.ts 顶部模块级类型声明)。纯类型。
+ */
+
+export type RpcCommand
+  = | { id?: string, type: 'prompt', message: string, streamingBehavior?: 'steer' | 'followUp' }
+    | { id?: string, type: 'steer', message: string }
+    | { id?: string, type: 'follow_up', message: string }
+    | { id?: string, type: 'abort' }
+    | { id?: string, type: 'set_host_tools', tools: RpcHostToolDefinition[] }
+    | { id?: string, type: 'set_todos', phases: unknown[] }
+    | { id?: string, type: 'negotiate_protocol', protocolVersion: number }
+    | { id?: string, type: 'set_model', provider: string, modelId: string }
+    | { id?: string, type: 'get_state' }
+    | { id?: string, type: 'new_session' }
+    // ===== 上下文治理(70% 压缩环;协议权威 omp://rpc.md)=====
+    | { id?: string, type: 'get_session_stats' }
+    | { id?: string, type: 'compact', customInstructions?: string }
+    | { id?: string, type: 'set_auto_compaction', enabled: boolean }
+
+/** compaction 结果(compaction_end 事件 / compact 响应 data.result 共用形状) */
+export interface CompactionResult {
+  summary?: string
+  tokensBefore?: number
+  tokensAfter?: number
+  estimatedTokensAfter?: number
+}
+
+/** provider 用量(被动上下文跟踪源;message_update 等帧携带的累计值) */
+export interface RpcUsage {
+  /** input tokens ≈ 当前上下文长度(本回合 LLM 调用的 prompt 规模) */
+  input: number
+  output?: number
+  cacheRead?: number
+  at: number
+}
+/** host 工具定义(omp 端可见的工具 schema) */
+export interface RpcHostToolDefinition {
+  name: string
+  label?: string
+  description: string
+  parameters: Record<string, unknown>
+  hidden?: boolean
+  /** WP5:引用面声明(与 host-tools.json 同源;执行期由 tool-verify 实时校验) */
+  references?: import('../../tool-reference-spec').ToolVerifySpec
+  /** WP5:显式无引用声明(登记制) */
+  noRefs?: boolean
+  /** WP5:风险类别(read/write/admin) */
+  riskClass?: import('../../tool-reference-spec').ToolRiskClass
+}
+
+/** RPC 响应(命令执行结果) */
+export interface RpcResponse {
+  id?: string
+  type: 'response'
+  command: string
+  success: boolean
+  data?: unknown
+  error?: string
+  code?: string
+}
+
+/** omp AgentSession 事件(本项目消费的子集) */
+export interface AgentSessionEvent {
+  type: string
+  // message_update
+  assistantMessageEvent?: {
+    type: 'text_delta' | 'text_start' | 'text_end' | 'thinking_delta' | 'tool_call' | 'tool_result' | string
+    delta?: string
+    text?: string
+    toolName?: string
+    toolCallId?: string
+    [k: string]: unknown
+  }
+  message?: { role: string, content: unknown[] }
+  // agent_end
+  messages?: Array<{ role: string, content: Array<{ type: string, text?: string }> }>
+  isTerminal?: boolean
+  // tool_execution
+  toolName?: string
+  toolCallId?: string
+  [k: string]: unknown
+}
+
+/** omp 向宿主发起的 host_tool_call 请求 */
+export interface HostToolCallRequest {
+  id: string
+  toolCallId: string
+  toolName: string
+  arguments: Record<string, unknown>
+}
+
+/** 宿主工具 handler:接收 omp 的工具调用,返回结果 */
+export type HostToolHandler = (req: HostToolCallRequest) => Promise<{ text: string, isError?: boolean }>
+
+/** RPC 客户端配置 */
+export interface OmpRpcClientOptions {
+  /** omp 可执行文件路径(默认 'omp') */
+  command?: string
+  /**
+   * 输出模式:'rpc' = 纯协议(无 UI);'rpc-ui' = 协议 + UI 上下文
+   * (ask 工具 / extension_ui_request 对话框可用 —— HITL 通道;强制 noPty)。默认 'rpc'。
+   */
+  mode?: 'rpc' | 'rpc-ui'
+  /** 额外 CLI 参数 */
+  args?: string[]
+  /** 工作目录 */
+  cwd?: string
+  /** 环境变量 */
+  env?: Record<string, string>
+  /** 进程退出回调(运行时资源监控登记/标记用;pid 为 -1 表示无法取得) */
+  onExit?: (pid: number, code: number | null) => void
+}
+
+export interface PendingRequest {
+  resolve: (response: RpcResponse) => void
+  reject: (error: Error) => void
+  timer?: ReturnType<typeof setTimeout>
+}
+
+/** 流式缓冲上限(超限截断并计数,防大输出/异常流拖爆内存) */

package/server/services/workshop/agents/hitl-decision/dispatcher.ts

@@ -1,96 +1,112 @@
-/**
- * 原生派发器注册与默认派发
- * (由 server/services/workshop/agents/hitl-decision.ts 按职责拆出;内容逐行原文搬运)
- */
-import type { AepHitlQuestion } from '../../../../../shared/workshop-protocol'
-import type { HitlActingUser, HitlDecisionPayload } from './shared'
-import { AppError } from '@/server/utils/errors'
-import { encodeHitlAnswers, resolveHitlRuntime } from '../hitl-registry'
-import { getToolApprovals, normalizeRecipeProposeDecision } from '../tool-approvals'
-import { resolveAnswers } from './answers'
-import { respondTerminalUi } from '../harness-terminal'
-
-// ============================================================================
-// 原生应答传导(可插拔:测试/嵌入场景替换;缺省走真实 adapter 面)
-// ============================================================================
-
-export interface HitlNativeDispatchContext {
-  kind: string
-  id: string
-  requestType: 'question' | 'approval'
-  channelId: string
-  agentId: string
-  /** 内存快照里的 pid(omp-dialog 终止对话框用) */
-  pid?: number
-  /** 问题列表(多问题答案按问题 id 对齐回传;来自持久化行,回落到内存快照) */
-  questions: AepHitlQuestion[]
-  decision: HitlDecisionPayload
-  user: HitlActingUser
-}
-
-export type HitlNativeDispatcher = (ctx: HitlNativeDispatchContext) => Promise<unknown> | unknown
-
-export const nativeDispatchers = new Map<string, HitlNativeDispatcher>()
-
-/** 注册/覆盖某 providerKind 的原生应答传导(测试与嵌入装配用) */
-export function registerHitlNativeDispatcher(kind: string, fn: HitlNativeDispatcher | null): void {
-  if (fn) nativeDispatchers.set(kind, fn)
-  else nativeDispatchers.delete(kind)
-}
-
-/** 默认传导:omp 对话框写 stdin;dcw 走工具审批服务;其余走 manager→adapter */
-export async function defaultDispatch(ctx: HitlNativeDispatchContext): Promise<unknown> {
-  const manager = resolveHitlRuntime()
-  const { decision } = ctx
-  if (ctx.kind === 'omp-dialog') {
-    // 保持既有 410 SESSION_GONE 语义:pid 缺失/进程已退出 = 会话不可用(确定性失败)
-    if (!ctx.pid) throw new AppError(410, 'SESSION_GONE', '对话框缺少 pid(进程已退出?)')
-    try {
-      respondTerminalUi(ctx.pid, {
-        id: ctx.id,
-        // 提问型 UI 提交的是 answers[];omp terminal 只认 value。
-        // 与 harness 路径同源编码:单答案 → 纯文本,多答案 → 信封。
-        value: encodeHitlAnswers(resolveAnswers(ctx.questions, decision), decision.value ?? ''),
-        confirmed: typeof decision.confirmed === 'boolean' ? decision.confirmed : undefined,
-        cancelled: decision.cancelled === true,
-      })
-    }
-    catch (err) {
-      throw new AppError(410, 'SESSION_GONE', `omp 会话不可用: ${err instanceof Error ? err.message : String(err)}`)
-    }
-    return { via: 'omp-terminal' }
-  }
-  if (ctx.kind === 'dcw-approval') {
-    // dcw 工具审批:与 hitl/respond 同语义(缺省视为拒绝,approved 必须显式 confirmed===true)。
-    // 产线 Co-Pilot P2:结构化审批单(recipe-propose,payload.schemaVersion=1)先经 fail-closed
-    // 归一 —— 无有效 choice 的「批准」一律按拒绝收敛;legacy 审批单(无 payload)完全不干预。
-    const pending = getToolApprovals().listPending().find(a => a.id === ctx.id)
-    const normalized = normalizeRecipeProposeDecision(pending, {
-      approved: decision.confirmed === true,
-      choice: decision.choice,
-    })
-    if (decision.confirmed === true && !normalized.approved) {
-      // fail-closed 降级:把有效裁决回写进决策载荷,使 hitl 行终态/审计/落定通知
-      // 与实际裁决(拒绝)一致,不留「已批准但未执行」的假态
-      decision.confirmed = false
-    }
-    const approval = getToolApprovals().decide(
-      ctx.id,
-      normalized.approved,
-      String(decision.comment ?? ''),
-      ctx.user.id,
-      ctx.user.name ?? '',
-      normalized.choice,
-    )
-    return { via: 'tool-approvals', approval }
-  }
-  if (!manager) throw new AppError(409, 'NOT_RESPONDABLE', 'Workshop 运行时未装配,无法应答该 harness 请求')
-  await manager.respondHarnessHitl(ctx.agentId, ctx.kind, ctx.id, {
-    confirmed: typeof decision.confirmed === 'boolean' ? decision.confirmed : undefined,
-    cancelled: decision.cancelled === true,
-    value: encodeHitlAnswers(resolveAnswers(ctx.questions, decision), decision.value),
-    response: typeof decision.response === 'string' ? decision.response : undefined,
-    comment: typeof decision.comment === 'string' ? decision.comment : undefined,
-  })
-  return { via: 'harness', harness: ctx.kind }
-}
+/**
+ * 原生派发器注册与默认派发
+ * (由 server/services/workshop/agents/hitl-decision.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { AepHitlQuestion } from '../../../../../shared/workshop-protocol'
+import type { HitlActingUser, HitlDecisionPayload } from './shared'
+import { AppError } from '@/server/utils/errors'
+import { encodeHitlAnswers, resolveHitlRuntime } from '../hitl-registry'
+import { getToolApprovals, normalizeRecipeProposeDecision } from '../tool-approvals'
+import { decideOptimizerDispatch, isOptimizerDispatchCard } from '../../optimization/dispatch.service'
+import { resolveAnswers } from './answers'
+import { respondTerminalUi } from '../harness-terminal'
+
+// ============================================================================
+// 原生应答传导(可插拔:测试/嵌入场景替换;缺省走真实 adapter 面)
+// ============================================================================
+
+export interface HitlNativeDispatchContext {
+  kind: string
+  id: string
+  requestType: 'question' | 'approval'
+  channelId: string
+  agentId: string
+  /** 内存快照里的 pid(omp-dialog 终止对话框用) */
+  pid?: number
+  /** 问题列表(多问题答案按问题 id 对齐回传;来自持久化行,回落到内存快照) */
+  questions: AepHitlQuestion[]
+  decision: HitlDecisionPayload
+  user: HitlActingUser
+}
+
+export type HitlNativeDispatcher = (ctx: HitlNativeDispatchContext) => Promise<unknown> | unknown
+
+export const nativeDispatchers = new Map<string, HitlNativeDispatcher>()
+
+/** 注册/覆盖某 providerKind 的原生应答传导(测试与嵌入装配用) */
+export function registerHitlNativeDispatcher(kind: string, fn: HitlNativeDispatcher | null): void {
+  if (fn) nativeDispatchers.set(kind, fn)
+  else nativeDispatchers.delete(kind)
+}
+
+/** 默认传导:omp 对话框写 stdin;dcw 走工具审批服务;其余走 manager→adapter */
+export async function defaultDispatch(ctx: HitlNativeDispatchContext): Promise<unknown> {
+  const manager = resolveHitlRuntime()
+  const { decision } = ctx
+  if (ctx.kind === 'omp-dialog') {
+    // 保持既有 410 SESSION_GONE 语义:pid 缺失/进程已退出 = 会话不可用(确定性失败)
+    if (!ctx.pid) throw new AppError(410, 'SESSION_GONE', '对话框缺少 pid(进程已退出?)')
+    try {
+      respondTerminalUi(ctx.pid, {
+        id: ctx.id,
+        // 提问型 UI 提交的是 answers[];omp terminal 只认 value。
+        // 与 harness 路径同源编码:单答案 → 纯文本,多答案 → 信封。
+        value: encodeHitlAnswers(resolveAnswers(ctx.questions, decision), decision.value ?? ''),
+        confirmed: typeof decision.confirmed === 'boolean' ? decision.confirmed : undefined,
+        cancelled: decision.cancelled === true,
+      })
+    }
+    catch (err) {
+      throw new AppError(410, 'SESSION_GONE', `omp 会话不可用: ${err instanceof Error ? err.message : String(err)}`)
+    }
+    return { via: 'omp-terminal' }
+  }
+  if (ctx.kind === 'dcw-approval') {
+    // dcw 工具审批:与 hitl/respond 同语义(缺省视为拒绝,approved 必须显式 confirmed===true)。
+    // 产线 Co-Pilot P2:结构化审批单(recipe-propose,payload.schemaVersion=1)先经 fail-closed
+    // 归一 —— 无有效 choice 的「批准」一律按拒绝收敛;legacy 审批单(无 payload)完全不干预。
+    const pending = getToolApprovals().listPending().find(a => a.id === ctx.id)
+    const normalized = normalizeRecipeProposeDecision(pending, {
+      approved: decision.confirmed === true,
+      choice: decision.choice,
+    })
+    if (decision.confirmed === true && !normalized.approved) {
+      // fail-closed 降级:把有效裁决回写进决策载荷,使 hitl 行终态/审计/落定通知
+      // 与实际裁决(拒绝)一致,不留「已批准但未执行」的假态
+      decision.confirmed = false
+    }
+    // SW5/D13 单一咽喉:optimizer-recipe:* 卡一律走 dispatch 链(八项重验→抢占→写→回读→审计);
+    // 业务拒绝在咽喉内 decide() 落定,hitl 行终态与实际裁决一致
+    if (pending && isOptimizerDispatchCard(pending.nodeId)) {
+      const result = await decideOptimizerDispatch({
+        cardId: ctx.id,
+        approved: normalized.approved,
+        comment: String(decision.comment ?? ''),
+        choice: normalized.choice,
+        actingUser: { id: ctx.user.id, name: ctx.user.name ?? ctx.user.id },
+        via: 'hitl/respond',
+      })
+      if (result.handled) {
+        return { via: 'optimizer-dispatch', result: { approved: result.approved, comment: result.comment, code: result.code, execution: result.execution } }
+      }
+    }
+    const approval = getToolApprovals().decide(
+      ctx.id,
+      normalized.approved,
+      String(decision.comment ?? ''),
+      ctx.user.id,
+      ctx.user.name ?? '',
+      normalized.choice,
+    )
+    return { via: 'tool-approvals', approval }
+  }
+  if (!manager) throw new AppError(409, 'NOT_RESPONDABLE', 'Workshop 运行时未装配,无法应答该 harness 请求')
+  await manager.respondHarnessHitl(ctx.agentId, ctx.kind, ctx.id, {
+    confirmed: typeof decision.confirmed === 'boolean' ? decision.confirmed : undefined,
+    cancelled: decision.cancelled === true,
+    value: encodeHitlAnswers(resolveAnswers(ctx.questions, decision), decision.value),
+    response: typeof decision.response === 'string' ? decision.response : undefined,
+    comment: typeof decision.comment === 'string' ? decision.comment : undefined,
+  })
+  return { via: 'harness', harness: ctx.kind }
+}

package/server/services/workshop/agents/host-tool-bridge/catalog.ts

@@ -12,10 +12,14 @@ import { getChannelTwinProfile } from '../../aml/twin/channel-profile'
 import { amlTwinFeatureFlags } from '../../aml/twin/feature-flags'
 import { applyChannelToolPolicy } from '../../tools/policy'
 import type { ToolExclusion } from '../../tools/types'
+import { registerToolReferenceDeclarations } from '../tool-reference-spec'
 
 /** host tool 定义(外置 .AgentWorkShop/prompts/host-tools.json;加载器缓存) */
 export const HOST_TOOLS: RpcHostToolDefinition[] = loadHostToolDefs()
 
+// WP5:定义自带的引用面声明装配进单一声明表(tool-verify 执行期查表;声明在注册时生效)
+registerToolReferenceDeclarations(HOST_TOOLS)
+
 // 工具分类常量已上收零依赖叶子模块 agents/tool-classes(权限面/测试在 nitro 之外可用);此处 re-export 保持导入路径兼容
 export { LEAD_ONLY_TOOL_NAMES, HYBRID_TWIN_DIRECT_WRITE_TOOL_NAMES } from '../tool-classes'
 
@@ -38,6 +42,14 @@ export const AML_OPTIMIZATION_TOOL_NAMES = new Set([
   'twin_snapshot_create', 'twin_trial_run', 'mpc_optimize', 'twin_gate_evaluate', 'optimization_explore', 'twin_bayes_optimize',
 ])
 
+/**
+ * 优化器工具族(G4):零写设备;仅 aml_optimization / hybrid_twin 注入,
+ * 且 solve/status/cancel/plan_get 还要求该 Agent 有有效绑定(per-agent 再裁一次)。
+ */
+export const OPTIMIZER_TOOL_NAMES = new Set([
+  'optimizer_capabilities', 'optimizer_solve', 'optimizer_status', 'optimizer_cancel', 'optimizer_plan_get',
+])
+
 /** 仅 aml 模式(已绑定模型)可执行的工具;探索模式下 dispatch 层 fail-closed 拒绝。 */
 export const AML_MODEL_BACKED_TOOL_NAMES = new Set([
   'twin_trial_run', 'mpc_optimize', 'twin_bayes_optimize',
@@ -183,16 +195,16 @@ export function scopeHostToolsForRole(role: 'lead' | 'worker', channelId?: strin
   const flags = amlTwinFeatureFlags()
   let scoped: RpcHostToolDefinition[]
   if (kind === 'aml_training') {
-    // 训练面:剔除优化族(gate 保留 —— 模型晋升前需门禁评估);训练族显式补齐(host-tools.json 全量已含)
+    // 训练面:剔除优化族与优化器族(gate 保留 —— 模型晋升前需门禁评估)
     scoped = narrow(
       base,
-      t => !AML_OPTIMIZATION_TOOL_NAMES.has(t.name) || t.name === 'twin_gate_evaluate',
+      t => (!AML_OPTIMIZATION_TOOL_NAMES.has(t.name) || t.name === 'twin_gate_evaluate') && !OPTIMIZER_TOOL_NAMES.has(t.name),
       'PROFILE_DENIED',
-      `当前 Channel 档位(${kind})不开放该工具(训练面与优化执行面互斥)`,
+      `当前 Channel 档位(${kind})不开放该工具(训练面不求解)`,
     )
   }
   else if (kind === 'aml_optimization') {
-    // 优化面:剔除训练族(gate 保留 —— 绑定校验需门禁);优化族显式补齐(含新工具)
+    // 优化面:剔除训练族(gate 保留);优化器族保留(per-agent 再按绑定裁剪)
     scoped = narrow(
       base,
       t => !AML_TRAINING_TOOL_NAMES.has(t.name) || t.name === 'twin_gate_evaluate',
@@ -222,9 +234,10 @@ export function scopeHostToolsForRole(role: 'lead' | 'worker', channelId?: strin
           base,
           t => !HYBRID_TWIN_TOOL_NAMES.has(t.name)
             && !AML_TRAINING_TOOL_NAMES.has(t.name)
-            && !AML_OPTIMIZATION_TOOL_NAMES.has(t.name),
+            && !AML_OPTIMIZATION_TOOL_NAMES.has(t.name)
+            && !OPTIMIZER_TOOL_NAMES.has(t.name),
           'PROFILE_DENIED',
-          '当前 Channel 为 legacy 档位,不开放孪生/训练/优化族工具',
+          '当前 Channel 为 legacy 档位,不开放孪生/训练/优化/优化器族工具',
         )
   }
 

package/server/services/workshop/agents/host-tool-bridge/description-budget.ts

@@ -0,0 +1,34 @@
+/**
+ * 工具描述预算折叠(WP6)—— 零依赖叶子模块,便于单测。
+ *
+ * 折叠必须确定性:调用方先按 id 排序,本模块按顺序稳定截断,同一绑定面两次编译
+ * 输出逐字节相同(否则 tools/list_changed 会因截断边界抖动持续刷屏)。
+ * env AW_DESC_BUDGET=0 关闭折叠(回退全量拼接)。
+ */
+export const RESOURCES_GUIDE = ';完整清单用 industrial_resources 分页查询'
+
+export function descBudget(env: Record<string, string | undefined> = process.env): number {
+  const n = Number(env.AW_DESC_BUDGET ?? 400)
+  return Number.isFinite(n) && n >= 0 ? n : 400
+}
+
+export function sortedById<T extends { id: string }>(items: T[]): T[] {
+  return [...items].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+}
+
+export function foldList(prefix: string, items: string[], guide = RESOURCES_GUIDE, budget = descBudget()): string {
+  const full = `${prefix}${items.join('、')}`
+  if (budget === 0 || full.length <= budget) return full
+  const head: string[] = []
+  let used = prefix.length + guide.length + 16
+  for (const it of items) {
+    // 首项必须保留:配方条目携带完整参数面,单条即可超预算——空折叠(「等 N 项」
+    // 前无任何条目)会把绑定面整体隐藏,模型连绑了哪个配方/节点都看不到,
+    // per-agent 描述增强("不必先探测绑定面")失效。预算只对第 2 项起收紧。
+    if (head.length > 0 && used + it.length + 1 > budget) break
+    head.push(it)
+    used += it.length + 1
+  }
+  const more = head.length < items.length ? ` 等 ${items.length} 项` : ''
+  return `${prefix}${head.join('、')}${more}${guide}`
+}