dsh-vision-router 2.1.2 → 2.1.4

package/lib/session-affinity.js

@@ -0,0 +1,93 @@
+const MAX_SESSION_AFFINITY_ID_LENGTH = 512
+
+/** Preserve DSH's in-process session identity exactly; no wire rules belong here. */
+export function rawSessionIdentity(value) {
+  if (value === undefined || value === null) return undefined
+  try {
+    return String(value)
+  } catch {
+    return undefined
+  }
+}
+
+/** Read the live DSH session id across released/alpha session shapes without rewriting it. */
+export function sessionIdentityOf(session) {
+  if (!session) return undefined
+  try {
+    const direct = rawSessionIdentity(session.id)
+    if (direct !== undefined) return direct
+  } catch {
+    /* continue to persisted/header shapes */
+  }
+  try {
+    const header = rawSessionIdentity(session.header?.id)
+    if (header !== undefined) return header
+  } catch {
+    /* continue to requestHeader() */
+  }
+  try {
+    if (typeof session.requestHeader === 'function') {
+      return rawSessionIdentity(session.requestHeader()?.id)
+    }
+  } catch {
+    /* no usable session identity */
+  }
+  return undefined
+}
+
+/**
+ * Admit an opaque identity to an HTTP header without changing it. Fetch/undici
+ * requires ByteString-compatible header values; use visible ASCII so behavior
+ * is identical across Node 22/24 and HTTP implementations. Leading/trailing
+ * whitespace is rejected because Headers would normalize it, violating the
+ * requirement to preserve the DSH identity unchanged.
+ */
+export function wireSessionAffinityId(value) {
+  const text = rawSessionIdentity(value)
+  if (text === undefined || text === '' || text.length > MAX_SESSION_AFFINITY_ID_LENGTH) return undefined
+  if (text.trim() !== text) return undefined
+  if (!/^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/.test(text)) return undefined
+  return text
+}
+
+export function isOfficialOpenCodeGoUrl(value) {
+  try {
+    const url = new URL(String(value))
+    return (
+      url.protocol === 'https:' &&
+      url.hostname.toLowerCase() === 'opencode.ai' &&
+      /^\/zen\/go(?:\/|$)/i.test(url.pathname)
+    )
+  } catch {
+    return false
+  }
+}
+
+export function isOpenCodeGoProvider(provider) {
+  return isOfficialOpenCodeGoUrl(provider?.baseURL ?? provider?.baseUrl ?? '')
+}
+
+function invalidAffinityError(sessionId) {
+  const raw = rawSessionIdentity(sessionId)
+  const error = new Error(
+    raw === undefined || raw === ''
+      ? 'OpenCode Go requires a stable session identity; refusing a direct request without one'
+      : 'OpenCode Go session identity is not safe for an HTTP header; refusing to rewrite or truncate it',
+  )
+  error.code = raw === undefined || raw === '' ? 'OPENCODE_SESSION_REQUIRED' : 'OPENCODE_SESSION_INVALID'
+  return error
+}
+
+export function directSessionAffinityHeaders(provider, sessionId) {
+  if (!isOpenCodeGoProvider(provider)) return {}
+  const wire = wireSessionAffinityId(sessionId)
+  if (wire === undefined) throw invalidAffinityError(sessionId)
+  return { 'x-opencode-session': wire }
+}
+
+export function openCodeSessionAffinityHeaderForUrl(url, sessionId) {
+  if (!isOfficialOpenCodeGoUrl(url)) return undefined
+  const wire = wireSessionAffinityId(sessionId)
+  if (wire === undefined) throw invalidAffinityError(sessionId)
+  return wire
+}

package/lib/settings-ia-client-prelude.js

@@ -258,7 +258,7 @@ export const SETTINGS_IA_CLIENT_PRELUDE = String.raw`(function(){
       function localPageContent(){if(!local)return h(React.Fragment,null,title(tx('本地与设备','Local & device')),card([h('p',{className:'vr-hint',key:'remote'},tx('本地视觉后端和桌面截图只能在运行 DSH 的机器上配置。','Local vision backends and desktop capture can only be configured on the DSH machine.'))]));return h(React.Fragment,null,title(tx('本地与设备','Local & device'),tx('本地运行视觉模型可减少 API 费用和图片上传。','Run vision locally to reduce API cost and image uploads.')),localProviderCard('localOllama','Ollama',{enabled:false,baseURL:'http://127.0.0.1:11434/v1',model:'qwen2.5vl',format:'openai'},'ollama'),localProviderCard('localLmStudio','LM Studio',{enabled:false,baseURL:'http://localhost:1234/v1',model:'',format:'openai'},'lmstudio'),card([toggle('desktopScreenshot',tx('允许 Agent 读取桌面截图','Allow the agent to capture the desktop'),tx('这是独立的隐私权限；macOS 上保存为开启后会立即触发屏幕录制权限检查。','This is a separate privacy permission; on macOS saving it enabled immediately triggers the screen-recording permission check.'))]));}
       function wrappersEditor(){var rows=wrapperRows();return h('div',{className:'vr-field'},fieldHead('wrappedProviders',tx('哪些聊天模型可以开启识图','Which chat models can use Vision mode')),h('p',{className:'vr-hint'},tx('通常无需修改；模型留空表示整个 Provider。','Usually leave this alone; an empty model means the whole provider.')),rows.map(function(row,index){return modelRow(row,index,rows,setWrapperDraft,true);}),h('button',{type:'button',className:'vr-btn',disabled:!writable||saving,onClick:function(){setWrapperDraft(rows.concat([{provider:'',model:''}]))}},tx('+ 添加范围','+ Add scope')));}
       function textProviderEditor(){var current=Object.assign({provider:'',model:''},obj(value('textProvider',{}))),ready=groups.length>0;return h('div',{className:'vr-field'},fieldHead('textProvider',tx('文字回退模型','Text fallback model')),h('div',{className:'vr-chain-row'},ready?h('select',{className:'vr-input',value:current.provider||'',disabled:!writable||saving,onChange:function(event){setValue('textProvider',{provider:event.target.value,model:''});}},providerOptions(current.provider||'')):h('input',{className:'vr-input',value:current.provider||'',disabled:!writable||saving,onChange:function(event){setValue('textProvider',{provider:event.target.value,model:current.model||''});}}),ready?h('select',{className:'vr-input',value:current.model||'',disabled:!writable||saving||!current.provider,onChange:function(event){setValue('textProvider',{provider:current.provider||'',model:event.target.value});}},modelOptions(current.provider||'',current.model||'',false)):h('input',{className:'vr-input',value:current.model||'',disabled:!writable||saving,onChange:function(event){setValue('textProvider',{provider:current.provider||'',model:event.target.value});}})),invalidKeys.includes('textProvider')?h('p',{className:'vr-failed'},tx('Provider 和 model 必须同时填写，或同时留空恢复默认。','Provider and model must both be filled, or both left empty to restore the default.')):null);}
-      function advancedPage(){var routing=toggleValue('routing',false),turnBudget=Number(value('visionTurnBudgetMs',0))||0,customBudget=turnBudget>0;return h(React.Fragment,null,title(tx('高级','Advanced'),tx('这些默认值对大多数用户已经合适。','Defaults are suitable for most users.')),card([h('h4',{className:'vr-ia-subtitle',key:'p'},tx('性能与稳定性','Performance & stability')),toggle('downscale',tx('自动缩放','Auto downscale')),numberField('downscaleMaxPixels',tx('图片像素上限','Image pixel limit'),null,1000,100000000),toggle('cache',tx('识图缓存','Vision answer cache')),numberField('cacheTtlSeconds',tx('缓存有效期（秒）','Cache TTL (seconds)'),null,0,31536000),numberField('cacheMaxEntries',tx('最大缓存数量','Maximum cached answers'),null,1,100000),h('h4',{className:'vr-ia-subtitle',key:'t'},tx('超时','Timeouts')),numberField('timeoutMs',tx('单次模型请求','Single model request'),tx('毫秒。','Milliseconds.'),1000,600000),numberField('visionTaskTimeoutMs',tx('单个视觉任务','Single visual task'),tx('包含该任务内部的重试和备用模型；不是每个后端各自一份。','Includes retries and fallbacks inside the task; it is not a fresh budget per backend.'),1000,180000),numberField('ocrTimeoutMs',tx('OCR 任务','OCR task'),null,1000,120000),h('div',{className:'vr-field',key:'budget'},fieldHead('visionTurnBudgetMs',tx('整轮视觉工具上限','Whole-turn vision-tool limit')),h('select',{className:'vr-input',value:customBudget?'custom':'unlimited',disabled:!writable||saving,onChange:function(event){setValue('visionTurnBudgetMs',event.target.value==='unlimited'?0:(turnBudget>0?turnBudget:180000));}},h('option',{value:'unlimited'},tx('不限制（推荐）','Unlimited (recommended)')),h('option',{value:'custom'},tx('自定义','Custom'))),customBudget?numberField('visionTurnBudgetMs',tx('上限（毫秒）','Limit (ms)'),null,10000,600000):null)]),card([h('h4',{className:'vr-ia-subtitle',key:'cost'},tx('模型顺序与成本','Model order & cost')),toggle('freeCloudFirst',tx('免费云模型优先','Try free cloud models first'))]),card([h('h4',{className:'vr-ia-subtitle',key:'scope'},tx('识图模式范围','Vision mode scope')),toggle('autoWrapProviders',tx('自动允许已启用模型使用识图','Automatically allow enabled models to use Vision mode')),wrappersEditor()]),local?card([h('h4',{className:'vr-ia-subtitle',key:'network'},tx('网络与远程','Network & remote')),toggle('allowRemoteSettings',tx('允许可信 Host 远程修改设置','Allow trusted-host remote settings'),tx('默认关闭；trustedHosts 不是身份认证。','Off by default; trustedHosts is not authentication.')),textField('proxy',tx('代理地址','Proxy URL'),tx('留空关闭代理。','Leave empty to disable.')),textareaArray('proxyHosts',tx('走代理的域名','Proxied hosts'),tx('每行一个。','One per line.'))]):null,card([h('h4',{className:'vr-ia-subtitle',key:'compat'},tx('兼容模式','Compatibility')),toggle('rewriteImages',tx('保护纯文本模型','Protect text-only models')),toggle('routing',tx('整轮视觉路由（旧工作流）','Whole-turn vision routing (legacy workflow)')),routing?toggle('reverseRouting',tx('纯文字消息继续使用聊天模型','Keep text-only messages on the chat model')):null,routing?textProviderEditor():null]),card([h('button',{type:'button',className:'vr-btn',key:'dev',onClick:function(){setOpen(Object.assign({},open,{developer:!open.developer}));}},open.developer?tx('隐藏开发者设置','Hide developer settings'):tx('显示开发者设置','Show developer settings')),open.developer?h('div',{className:'vr-ia-dev',key:'body'},toggle('progressiveTools',tx('渐进式工具暴露','Progressive tool exposure')),local?toggle('stealth','Stealth'):null,local?textField('wrapperRoute',tx('包装路由名','Wrapper route name')):null,local?textField('chainRoute',tx('视觉链路由名','Vision chain route name')):null,textareaArray('extraVisionModels',tx('额外视觉能力标记','Extra vision capability labels'),tx('只有诊断发现模型未声明图片能力时才需要。','Needed only when diagnostics show missing image-capability metadata.'))):null]));}
+      function advancedPage(){var routing=toggleValue('routing',false),turnBudget=Number(value('visionTurnBudgetMs',0))||0,customBudget=turnBudget>0;return h(React.Fragment,null,title(tx('高级','Advanced'),tx('这些默认值对大多数用户已经合适。','Defaults are suitable for most users.')),card([h('h4',{className:'vr-ia-subtitle',key:'p'},tx('性能与稳定性','Performance & stability')),toggle('downscale',tx('自动缩放','Auto downscale')),numberField('downscaleMaxPixels',tx('图片像素上限','Image pixel limit'),null,1000,100000000),toggle('cache',tx('识图缓存','Vision answer cache')),numberField('cacheTtlSeconds',tx('缓存有效期（秒）','Cache TTL (seconds)'),null,0,31536000),numberField('cacheMaxEntries',tx('最大缓存数量','Maximum cached answers'),null,1,100000),h('h4',{className:'vr-ia-subtitle',key:'t'},tx('超时','Timeouts')),numberField('timeoutMs',tx('单次模型请求','Single model request'),tx('毫秒。','Milliseconds.'),1000,600000),numberField('visionTaskTimeoutMs',tx('单个视觉任务','Single visual task'),tx('包含该任务内部的重试和备用模型；不是每个后端各自一份。','Includes retries and fallbacks inside the task; it is not a fresh budget per backend.'),1000,180000),numberField('ocrTimeoutMs',tx('OCR 任务','OCR task'),null,1000,120000),h('div',{className:'vr-field',key:'budget'},fieldHead('visionTurnBudgetMs',tx('整轮视觉工具上限','Whole-turn vision-tool limit')),h('select',{className:'vr-input',value:customBudget?'custom':'unlimited',disabled:!writable||saving,onChange:function(event){setValue('visionTurnBudgetMs',event.target.value==='unlimited'?0:(turnBudget>0?turnBudget:180000));}},h('option',{value:'unlimited'},tx('不限制（推荐）','Unlimited (recommended)')),h('option',{value:'custom'},tx('自定义','Custom'))),customBudget?numberField('visionTurnBudgetMs',tx('上限（毫秒）','Limit (ms)'),null,10000,600000):null)]),card([h('h4',{className:'vr-ia-subtitle',key:'cost'},tx('模型顺序与成本','Model order & cost')),toggle('freeCloudFirst',tx('免费云模型优先','Try free cloud models first'))]),card([h('h4',{className:'vr-ia-subtitle',key:'scope'},tx('识图模式范围','Vision mode scope')),toggle('autoWrapProviders',tx('自动允许已启用模型使用识图','Automatically allow enabled models to use Vision mode')),wrappersEditor()]),local?card([h('h4',{className:'vr-ia-subtitle',key:'network'},tx('网络与远程','Network & remote')),toggle('allowRemoteSettings',tx('允许可信 Host 远程修改设置','Allow trusted-host remote settings'),tx('默认关闭；trustedHosts 不是身份认证。','Off by default; trustedHosts is not authentication.')),textField('proxy',tx('代理地址','Proxy URL'),tx('留空关闭代理。','Leave empty to disable.')),textareaArray('proxyHosts',tx('走代理的域名','Proxied hosts'),tx('每行一个。','One per line.'))]):null,card([h('h4',{className:'vr-ia-subtitle',key:'compat'},tx('兼容模式','Compatibility')),toggle('rewriteImages',tx('保护纯文本模型','Protect text-only models')),toggle('routing',tx('整轮视觉路由（旧工作流）','Whole-turn vision routing (legacy workflow)')),routing?toggle('reverseRouting',tx('纯文字消息继续使用聊天模型','Keep text-only messages on the chat model')):null,routing?textProviderEditor():null]),card([h('button',{type:'button',className:'vr-btn',key:'dev',onClick:function(){setOpen(Object.assign({},open,{developer:!open.developer}));}},open.developer?tx('隐藏开发者设置','Hide developer settings'):tx('显示开发者设置','Show developer settings')),open.developer?h('div',{className:'vr-ia-dev',key:'body'},toggle('progressiveTools',tx('渐进式工具暴露','Progressive tool exposure')),h('p',{className:'vr-hint',key:'progressive-restart'},tx('保存后需重启 DSH 才生效。','Restart DSH after saving for this change to take effect.')),local?toggle('stealth','Stealth'):null,local?textField('wrapperRoute',tx('包装路由名','Wrapper route name')):null,local?textField('chainRoute',tx('视觉链路由名','Vision chain route name')):null,textareaArray('extraVisionModels',tx('额外视觉能力标记','Extra vision capability labels'),tx('只有诊断发现模型未声明图片能力时才需要。','Needed only when diagnostics show missing image-capability metadata.'))):null]));}
       function diagnosticValue(label,valueText){return h('div',{className:'vr-ia-diag-row',key:label},h('span',null,label),h('strong',null,valueText));}
       function updatePanel(){if(!local)return null;var result=updateState.result,auto=result&&result.autoUpdate,current=result&&result.currentVersion?result.currentVersion:tx('检测中','Checking'),latest=result&&result.latestVersion?result.latestVersion:'—',available=result&&result.ok===true&&result.updateAvailable===true,profile=auto&&auto.profile?auto.profile:'web',manualVersion=result&&result.latestVersion?result.latestVersion:'<version>',spec='dsh-vision-router@'+manualVersion,pnpm='pnpm dsh plugin --profile '+profile+' add '+spec,npx='npx @deepseek-ai/dsh plugin --profile '+profile+' add '+spec;return card([h('h4',{className:'vr-ia-subtitle',key:'title'},tx('版本更新','Updates')),h('p',{className:'vr-hint',key:'status'},updateState.status==='running'?tx('正在检查更新…','Checking for updates…'):result&&result.ok===false?tx('更新检查失败：','Update check failed: ')+String(result.error||'unknown'):available?tx('发现新版本：v','Update available: v')+latest+tx('（当前 v',' (current v')+current+')':result&&result.ok===true?tx('已是最新版本 v','Up to date: v')+current:tx('尚未检查','Not checked yet')),h('div',{className:'vr-ia-actions',key:'actions'},h('button',{type:'button',className:'vr-btn',disabled:updateState.status==='running',onClick:function(){void runUpdateCheck(true);}},tx('检查更新','Check for updates')),available&&auto&&auto.supported===true&&auto.token?h('button',{type:'button',className:'vr-btn vr-btn-save',disabled:selfUpdateState.status==='running',onClick:function(){void runSelfUpdate();}},selfUpdateState.status==='running'?tx('更新中…','Updating…'):tx('一键更新','Update now')):null),selfUpdateState.status==='done'&&selfUpdateState.result?h('p',{className:'vr-hint',key:'updated'},tx('更新完成，请重启 DSH。','Update complete. Restart DSH.')):selfUpdateState.error?h('p',{className:'vr-failed',key:'uerr'},String(selfUpdateState.error)):null,available&&(!auto||auto.supported!==true)?h('div',{className:'vr-ia-manual',key:'manual'},h('p',{className:'vr-hint'},tx('当前安装方式不支持安全的一键更新，请使用与你当前 DSH 安装方式一致的命令：','This install method cannot be safely auto-updated. Use the command matching your DSH installation:')),h('code',{className:'vr-ia-code'},pnpm),h('code',{className:'vr-ia-code'},npx)):null]);}
       function diagnosticsPage(){var providerCount=groups.length,modelCount=groups.reduce(function(total,group){return total+arr(group&&group.models).length;},0),configured=chainRows().filter(function(row){return row&&row.provider&&row.model;}).length,ollama=obj(value('localOllama',{})),lm=obj(value('localLmStudio',{})),testText=!local?tx('仅本机可见','Local only'):testState.status==='running'?tx('检测中','Checking'):testState.status==='done'&&testState.result&&testState.result.ok===true?tx('连接正常','Connected'):testState.status==='done'?tx('连接失败','Failed'):tx('未检测','Not checked'),capsText=caps.status==='ready'?tx('正常','Ready'):caps.status==='loading'?tx('检测中','Checking'):caps.status==='error'?tx('不可用','Unavailable'):tx('未检测','Not checked');var rows=[[tx('设置协议','Settings contract'),String(value('settingsContractRevision','—'))],[tx('模型目录','Model catalog'),catalog.status==='ready'?tx('正常','Ready'):catalog.status==='loading'?tx('检测中','Checking'):tx('不可用','Unavailable')],[tx('图片能力元数据','Image capability metadata'),capsText],[tx('可选 Provider','Selectable providers'),String(providerCount)],[tx('可选模型','Selectable models'),String(modelCount)],[tx('已配置识图模型','Configured vision models'),String(configured)],[tx('内置免费兜底','Built-in free fallback'),toggleValue('freeFallback',true)?(caps.builtinFallback.length?tx('已启用，','Enabled, ')+caps.builtinFallback.length+tx(' 个模型',' models'):tx('已启用','Enabled')):tx('已关闭','Disabled')],[tx('后端连接','Backend connection'),testText],[tx('Ollama','Ollama'),local?(ollama.enabled===true?tx('已启用','Enabled'):tx('未启用','Disabled')):tx('仅本机可见','Local only')],[tx('LM Studio','LM Studio'),local?(lm.enabled===true?tx('已启用','Enabled'):tx('未启用','Disabled')):tx('仅本机可见','Local only')],[tx('桌面截图','Desktop capture'),local?(toggleValue('desktopScreenshot',false)?tx('已启用','Enabled'):tx('未启用','Disabled')):tx('仅本机可见','Local only')],[tx('代理','Proxy'),local?(String(value('proxy','')).trim()?tx('已配置','Configured'):tx('未配置','Not configured')):tx('仅本机可见','Local only')],[tx('远程设置','Remote settings'),local?(toggleValue('allowRemoteSettings',false)?tx('已启用','Enabled'):tx('未启用','Disabled')):tx('当前为远程安全视图','Remote safe view')]];function reportText(){return ['Vision Router diagnostics'].concat(rows.map(function(row){return row[0]+': '+row[1];}),['doctor: dsh-vision-router doctor']).join('\n');}async function copyReport(){try{if(typeof navigator!=='undefined'&&navigator.clipboard&&typeof navigator.clipboard.writeText==='function')await navigator.clipboard.writeText(reportText());setActionState({status:'copied'});}catch(error){setActionState({status:'error',error:error&&error.message?error.message:String(error)});}}return h(React.Fragment,null,title(tx('诊断','Diagnostics'),tx('状态页不会修改你的模型/路由设置；连接测试和更新操作会明确由按钮触发。','The status page does not change model or routing settings; connection tests and updates are explicit actions.')),card(rows.map(function(row){return diagnosticValue(row[0],row[1]);})),card([h('div',{className:'vr-ia-actions',key:'actions'},local?h('button',{type:'button',className:'vr-btn',disabled:testState.status==='running',onClick:function(){void runTestConnection();}},tx('测试连接','Test connection')):null,h('button',{type:'button',className:'vr-btn',onClick:function(){invalidateCatalog();}},tx('重新检测模型','Re-detect models')),local?h('button',{type:'button',className:'vr-btn',onClick:function(){void openLogs();}},tx('打开日志文件夹','Open logs folder')):null,h('button',{type:'button',className:'vr-btn',onClick:function(){void copyReport();}},tx('复制诊断信息','Copy diagnostics'))),h('p',{className:'vr-hint',key:'doctor'},tx('需要完整 DSH 版本、安装、Profile、运行时路由和会话诊断时执行：dsh-vision-router doctor','For the full DSH version, installation, profile, runtime-route, and session report, run: dsh-vision-router doctor')),testState.status==='done'&&testState.result&&testState.result.ok!==true?h('p',{className:'vr-failed',key:'testerr'},String(testState.result.error||tx('连接测试失败','Connection test failed'))):null,actionState.status==='error'?h('p',{className:'vr-failed',key:'aerr'},String(actionState.error||'unknown')):null]),updatePanel());}

package/lib/structured-bootstrap.js

@@ -32,7 +32,7 @@ export function structuredBootstrapQuestion() {
     'The example above must remain valid JSON. For mixed_of: ONLY when visual_kind is "mixed", put 1-2 distinct values chosen from document, ui, code, chat, general; otherwise return an empty array. ' +
     'Preserve high-information evidence for downstream reasoning: layout, reading order, objects/controls, relationships, visible state, and uncertainty. ' +
     'Do not prematurely answer any possible user task and do not invent hidden details. ' +
-    'Recommend at least one concrete follow-up evidence call. Do NOT recommend vision_ocr merely because text is visible: use OCR only when exact verbatim transcription is genuinely uncertain or would materially add evidence; for UI/screenshots prefer vision_detect or a focused vision_describe when semantic verification is enough. ' +
+    'Recommend at least one concrete task-independent follow-up evidence candidate; downstream agents must treat these as optional suggestions, not a task plan. Do NOT recommend vision_ocr merely because text is visible: use OCR only when exact verbatim transcription is genuinely uncertain or would materially add evidence; for UI/screenshots prefer vision_detect or a focused vision_describe when semantic verification is enough. ' +
     'OCR is a verbatim transcriber, not a semantic reader: it is systematically unreliable for confusable glyphs (1/l, 0/O), spacing and line breaks, so context-aware semantic reading (vision_describe / vision_detect) usually recovers meaning that raw OCR corrupts. ' +
     'Use vision_ocr ONLY when verbatim fidelity is genuinely required and cannot be recovered from context: executable code, long-form documents needing exact quotation, forms/contracts, table digits, CAPTCHAs, or glyphs with no semantic anchor. ' +
     'When you do call vision_ocr, treat its output as evidence to verify against other tools, never as ground truth. ' +
@@ -107,7 +107,7 @@ export function normalizeStructuredBootstrapResult(parsed, raw = '') {
     recommendedFollowups.push({
       tool: visualKind === 'ui' ? 'vision_detect' : 'vision_describe',
       target: 'the most uncertain or information-dense region from the structured baseline',
-      reason: 'Required x>=1 verification/deepening call after the bootstrap pass; do not default to OCR without a verbatim-text need.',
+      reason: 'Task-independent candidate for the required x>=1 verification/deepening step; the downstream agent must still choose based on the user question and must not default to OCR without a verbatim-text need.',
     })
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {

package/lib/structured-flow-hardening.js

@@ -20,9 +20,7 @@ const MAX_TURN_BUDGET_MS = 600_000
 const MAX_GUIDANCE_OVERRIDES = 14
 const MAX_GUIDANCE_CHARS = 2_000
 const MAX_NON_PROGRESS_ATTEMPTS = 3
-const MAX_EVIDENCE_SIGNATURE_CHARS = 4_096
 const BUDGETED_TIMEOUT_FIELDS = ['timeoutMs', 'visionTaskTimeoutMs', 'ocrTimeoutMs']
-const EVIDENCE_META_KEYS = new Set(['ok', 'code', 'retryable', 'reason', 'phase', 'next'])
 const GUIDANCE_KINDS = new Set([
   'code',
   'document',
@@ -40,25 +38,6 @@ const GUIDANCE_KINDS = new Set([
   'meme',
 ])
 
-const BUILTIN_MIXED_GUIDANCE = {
-  zh: {
-    document: '语义优先；只有逐字引用、合同/表单字段或表格数字确需保真时才使用 OCR。',
-    ui: '优先用 vision_detect / vision_ground 验证元素、状态与位置。',
-    code: '逐字核对代码；对可执行字符、缩进和符号做交叉验证。',
-    chat: '按气泡顺序核对发言者、消息内容与时间/状态信息。',
-    general: '聚焦尚未归类的另一部分可见内容，自行选择最能新增证据的视觉工具。',
-    fallback: '聚焦这个分支新增或验证可见证据。',
-  },
-  en: {
-    document: 'Prioritize semantics; use OCR only when verbatim quotes, contract/form fields, or table numbers require exact transcription.',
-    ui: 'Prefer vision_detect / vision_ground to verify elements, states, and positions.',
-    code: 'Verify code verbatim; cross-check executable characters, indentation, and symbols.',
-    chat: 'Verify speakers, message text, and time/status information in bubble order.',
-    general: 'Focus on the remaining unclassified visible content and choose the vision tool that adds the most useful evidence.',
-    fallback: 'Add or verify visible evidence for this branch.',
-  },
-}
-
 function isObject(value) {
   return value !== null && typeof value === 'object'
 }
@@ -98,36 +77,143 @@ export function producedStructuredEvidence(value) {
   return true
 }
 
-function meaningfulEvidenceValue(value) {
-  if (value === undefined || value === null) return false
-  if (typeof value === 'string') return value.trim() !== ''
-  if (typeof value === 'number') return Number.isFinite(value)
-  if (typeof value === 'boolean') return true
-  if (Array.isArray(value)) return value.length > 0 && value.some(meaningfulEvidenceValue)
-  if (!isObject(value) || value.ok === false) return false
-  return Object.entries(value).some(([key, child]) => (
-    !EVIDENCE_META_KEYS.has(key) && meaningfulEvidenceValue(child)
+function finiteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+function positiveInteger(value) {
+  return Number.isInteger(value) && value > 0
+}
+
+function nonEmptyText(value) {
+  return typeof value === 'string' && value.trim() !== ''
+}
+
+function canonicalBox(value, width, height) {
+  if (!isObject(value) || Array.isArray(value)) return false
+  const { x1, y1, x2, y2 } = value
+  if (![x1, y1, x2, y2].every(Number.isInteger)) return false
+  if (x1 < 0 || y1 < 0 || x2 <= x1 || y2 <= y1) return false
+  if (positiveInteger(width) && x2 > width) return false
+  if (positiveInteger(height) && y2 > height) return false
+  return true
+}
+
+function structuredDescribeEvidence(value) {
+  if (!isObject(value) || Array.isArray(value)) return false
+  if (nonEmptyText(value.summary) || nonEmptyText(value.text)) return true
+  if (Array.isArray(value.layout) && value.layout.some((row) => (
+    isObject(row) && nonEmptyText(row.region) && nonEmptyText(row.content)
+  ))) return true
+  return Array.isArray(value.entities) && value.entities.some((entity) => (
+    isObject(entity) && nonEmptyText(entity.type) && nonEmptyText(entity.label)
+  ))
+}
+
+function groundEvidence(value) {
+  if (!isObject(value) || Array.isArray(value)) return false
+  const { width, height } = value
+  return positiveInteger(width) && positiveInteger(height) && canonicalBox(value, width, height)
+}
+
+function detectEvidence(value) {
+  if (!isObject(value) || Array.isArray(value)) return false
+  const { width, height, elements } = value
+  if (!positiveInteger(width) || !positiveInteger(height) || !Array.isArray(elements)) return false
+  return elements.every((element, index) => (
+    isObject(element) &&
+    element.number === index + 1 &&
+    nonEmptyText(element.label) &&
+    canonicalBox(element.box, width, height)
   ))
 }
 
+function ocrEvidence(value) {
+  if (!isObject(value) || Array.isArray(value)) return false
+  if (value.engine !== 'tesseract' && value.engine !== 'vision') return false
+  return typeof value.text === 'string'
+}
+
+function colorEvidence(value) {
+  if (!Array.isArray(value)) return false
+  return value.every((entry) => (
+    isObject(entry) &&
+    typeof entry.hex === 'string' && /^#[0-9a-f]{6}$/i.test(entry.hex) &&
+    positiveInteger(entry.count) &&
+    finiteNumber(entry.share) && entry.share > 0 && entry.share <= 1
+  ))
+}
+
+function pixelDiffEvidence(value) {
+  if (!isObject(value) || Array.isArray(value)) return false
+  const { width, height, differingPixels, totalPixels, diffRatio, worstRegions } = value
+  if (!positiveInteger(width) || !positiveInteger(height) || totalPixels !== width * height) return false
+  if (!Number.isInteger(differingPixels) || differingPixels < 0 || differingPixels > totalPixels) return false
+  if (!finiteNumber(diffRatio) || diffRatio < 0 || diffRatio > 1) return false
+  if (Math.abs(diffRatio - differingPixels / totalPixels) > 0.000051) return false
+  if (!Array.isArray(worstRegions)) return false
+  return worstRegions.every((region) => (
+    isObject(region) &&
+    canonicalBox(region, width, height) &&
+    Number.isInteger(region.differing) && region.differing > 0 &&
+    positiveInteger(region.total) && region.differing <= region.total &&
+    finiteNumber(region.ratio) && region.ratio > 0 && region.ratio <= 1
+  ))
+}
+
+function longOcrEvidence(value) {
+  if (!isObject(value) || Array.isArray(value)) return false
+  if (typeof value.text !== 'string' || !positiveInteger(value.chunks)) return false
+  if (!isObject(value.engines) || Array.isArray(value.engines)) return false
+  if (![value.markdownPath, value.manifestPath, value.artifactsDir].every(nonEmptyText)) return false
+  const engineCounts = Object.values(value.engines)
+  if (engineCounts.length === 0 || !engineCounts.every((count) => Number.isInteger(count) && count >= 0)) return false
+  if (engineCounts.reduce((sum, count) => sum + count, 0) !== value.chunks) return false
+  if (nonEmptyText(value.text)) return true
+  const completed = (value.engines.tesseract ?? 0) + (value.engines.vision ?? 0)
+  return completed > 0
+}
+
 /**
- * Evidence that is strong enough to advance the 1+x flow and consume an
- * explicit deep-dive call cap. Empty arrays/objects and metadata-only success
- * envelopes do not count. Negative facts such as { match: false } or
- * { count: 0 } still count because they are real observations, not emptiness.
+ * Decide whether one registered evidence tool completed a real observation.
+ *
+ * This deliberately follows each tool's output contract instead of treating
+ * arbitrary non-empty containers as evidence. Valid negative observations
+ * (for example zero detections, empty OCR text, or a 0 pixel diff) still count;
+ * transport failures, malformed envelopes, and describe's empty-content
+ * sentinel do not.
  */
-export function producedUsableStructuredEvidence(value) {
-  if (value === undefined || value === null) return false
-  if (typeof value === 'string') {
-    const text = value.trim()
-    if (text === '') return false
-    const parsed = parseJson(text)
-    if (parsed === undefined) return true
-    return producedUsableStructuredEvidence(parsed)
+export function producedUsableToolEvidence(toolName, value, args = {}) {
+  if (!STRUCTURED_EVIDENCE_TOOLS.has(toolName) || value === undefined || value === null) return false
+  const parsed = parseJson(value)
+  if (isObject(parsed) && !Array.isArray(parsed) && parsed.ok === false) return false
+
+  switch (toolName) {
+    case 'vision_describe': {
+      if (typeof value !== 'string') return false
+      const text = value.trim()
+      if (text === '' || text === '(the vision model returned empty content)') return false
+      if (args?.json === true) {
+        if (text.startsWith('vision_describe: the model did not produce valid JSON.')) return false
+        return structuredDescribeEvidence(parsed)
+      }
+      return true
+    }
+    case 'vision_ground':
+      return groundEvidence(parsed)
+    case 'vision_detect':
+      return detectEvidence(parsed)
+    case 'vision_ocr':
+      return ocrEvidence(parsed)
+    case 'vision_colors':
+      return colorEvidence(parsed)
+    case 'vision_pixel_diff':
+      return pixelDiffEvidence(parsed)
+    case 'vision_long_screenshot_ocr':
+      return longOcrEvidence(parsed)
+    default:
+      return false
   }
-  if (Array.isArray(value)) return value.length > 0 && value.some(meaningfulEvidenceValue)
-  if (!isObject(value) || value.ok === false) return false
-  return meaningfulEvidenceValue(value)
 }
 
 /**
@@ -176,15 +262,6 @@ function languageOf(config) {
   return runtimeLanguageFor(config?.__visionRouterLocale, 'zh')
 }
 
-function guidanceFor(kind, overrides, language = 'zh') {
-  for (let i = overrides.length - 1; i >= 0; i--) {
-    const entry = overrides[i]
-    if (entry.kind === kind) return entry.text
-  }
-  const copy = BUILTIN_MIXED_GUIDANCE[language] ?? BUILTIN_MIXED_GUIDANCE.zh
-  return copy[kind] ?? copy.fallback
-}
-
 function turnBudgetMs(config) {
   const value = Number(config?.visionTurnBudgetMs)
   if (!Number.isFinite(value) || value <= 0) return DEFAULT_TURN_BUDGET_MS
@@ -234,9 +311,7 @@ function freshState(turn, _config) {
     bootstrapDone: false,
     bootstrapResult: undefined,
     successfulEvidenceCalls: 0,
-    mixedBranches: [],
-    completedBranches: new Set(),
-    mixedAttemptSignatures: new Set(),
+    postBootstrapEvidenceCalls: 0,
     consecutiveNonProgressAttempts: 0,
     budgetExhausted: false,
     depthExhausted: false,
@@ -284,56 +359,13 @@ function bootstrapEvidence(raw) {
   return parsed.evidence
 }
 
-function normalizeMixedBranches(evidence, _depth) {
-  if (!isObject(evidence) || evidence.visual_kind !== 'mixed' || !Array.isArray(evidence.mixed_of)) return []
-  const allowed = ['ui', 'document', 'code', 'chat', 'general']
-  const unique = []
-  for (const kind of allowed) {
-    if (evidence.mixed_of.includes(kind)) unique.push(kind)
-  }
-  return unique.slice(0, 2)
-}
-
-function evidenceAttemptSignature(name, args) {
-  let encoded
-  try {
-    encoded = JSON.stringify(args ?? null)
-  } catch {
-    encoded = String(args ?? '')
-  }
-  if (encoded.length <= MAX_EVIDENCE_SIGNATURE_CHARS) return `${name}:${encoded}`
-  const half = Math.floor(MAX_EVIDENCE_SIGNATURE_CHARS / 2)
-  return `${name}:${encoded.length}:${encoded.slice(0, half)}:${encoded.slice(-half)}`
-}
-
-function inferBranchForTool(name, pending) {
-  const prefer = (kinds) => kinds.find((kind) => pending.includes(kind))
-  if (name === 'vision_detect' || name === 'vision_ground') return prefer(['ui', 'general'])
-  if (name === 'vision_long_screenshot_ocr') return prefer(['document', 'chat', 'code', 'general'])
-  if (name === 'vision_ocr') return prefer(['document', 'code', 'chat', 'general'])
-  if (name === 'vision_colors' || name === 'vision_pixel_diff') return prefer(['general', 'ui'])
-  return pending.length === 1 ? pending[0] : undefined
-}
-
-function recordEvidenceSuccess(state, name, args) {
-  state.successfulEvidenceCalls += 1
-  if (state.mixedBranches.length === 0) return true
-  const pending = state.mixedBranches.filter((kind) => !state.completedBranches.has(kind))
-  if (pending.length === 0) return true
-  const signature = evidenceAttemptSignature(name, args)
-  if (state.mixedAttemptSignatures.has(signature)) return false
-  state.mixedAttemptSignatures.add(signature)
-  const branch = inferBranchForTool(name, pending)
-  if (!branch) return false
-  state.completedBranches.add(branch)
-  return true
-}
-
+/**
+ * Structured 1+x has exactly one hard completion condition after bootstrap:
+ * at least one usable task-directed evidence observation. Mixed classifications
+ * remain model-visible advisory evidence; they do not create branch quotas.
+ */
 function missingEvidence(state) {
-  if (state.mixedBranches.length > 0) {
-    return state.mixedBranches.filter((kind) => !state.completedBranches.has(kind)).length
-  }
-  return state.successfulEvidenceCalls >= 1 ? 0 : 1
+  return state.postBootstrapEvidenceCalls >= 1 ? 0 : 1
 }
 
 function hasCoreFollowup(messages) {
@@ -347,6 +379,8 @@ function withoutEvidenceFollowups(messages) {
     const id = message && typeof message.id === 'string' ? message.id : ''
     return !(
       id.includes('vision-router-structured-followup-') ||
+      // Strip historical Round-0 mixed hard guards if one is still present in
+      // a persisted/compatibility message surface. Round 1 never emits them.
       id.includes('vision-router-structured-mixed-guard-') ||
       id.includes('vision-router-structured-evidence-guard-')
     )
@@ -374,30 +408,8 @@ function appendSyntheticGuardOnce(decision, baseMessages, state, message, stripE
 }
 
 function rearmEvidenceGuardAfterAttempt(state) {
-  const mixedPrefix = `vision-router-structured-mixed-guard-${state.turn}-`
   const evidenceId = `vision-router-structured-evidence-guard-${state.turn}`
-  for (const id of state.emittedGuardIds) {
-    if (id === evidenceId || id.startsWith(mixedPrefix)) state.emittedGuardIds.delete(id)
-  }
-}
-
-function mixedReminder(state, config) {
-  const language = languageOf(config)
-  const overrides = normalizeGuidanceOverrides(config?.guidanceOverrides)
-  const pending = state.mixedBranches.filter((kind) => !state.completedBranches.has(kind))
-  const done = state.mixedBranches.filter((kind) => state.completedBranches.has(kind))
-  const separator = language === 'en' ? ': ' : '：'
-  const lines = pending.map((kind) => `- ${kind}${separator}${guidanceFor(kind, overrides, language)}`)
-  if (language === 'en') {
-    const doneText = done.length > 0 ? `Verified branches: ${done.join(' + ')}. ` : ''
-    return `${doneText}This mixed image still has unverified branches: ${pending.join(' + ')}. ` +
-      'Focus each vision call on one unfinished branch; answer only after each branch has produced at least one useful piece of evidence.\n' +
-      lines.join('\n')
-  }
-  const doneText = done.length > 0 ? `已验证分支：${done.join(' + ')}。` : ''
-  return `${doneText}混合图片仍有未验证分支：${pending.join(' + ')}。` +
-    '每次视觉调用只聚焦一个尚未完成的分支；这些分支分别产生至少一次有效证据后再作答。\n' +
-    lines.join('\n')
+  state.emittedGuardIds.delete(evidenceId)
 }
 
 function appendGuardMessage(decision, payload, state, config) {
@@ -421,12 +433,12 @@ function appendGuardMessage(decision, payload, state, config) {
             ? 'The visual turn time budget is exhausted. Do not call more vision tools; answer from the evidence already collected and state any remaining uncertainty.'
             : state.depthExhausted
               ? 'The configured deep-dive call cap has been reached. Do not call more vision tools; answer from the evidence already collected and state any remaining uncertainty.'
-              : 'Repeated follow-up vision attempts did not produce or advance usable evidence. Do not keep retrying vision tools; answer from the evidence already collected and state the remaining uncertainty.'
+              : 'Repeated follow-up vision attempts did not produce usable evidence. Do not keep retrying vision tools; answer from the evidence already collected and state the remaining uncertainty.'
           : state.budgetExhausted
             ? '本轮视觉总时间预算已耗尽。不要再调用视觉工具；请基于已经获得的证据作答，并明确仍存在的不确定性。'
             : state.depthExhausted
               ? '已达到本轮设置的深挖次数上限。不要再调用视觉工具；请基于已经获得的证据作答，并明确仍存在的不确定性。'
-              : '连续多次后续视觉调用都没有产出或推进可用证据。不要继续重复调用视觉工具；请基于已经获得的证据作答，并明确仍存在的不确定性。',
+              : '连续多次后续视觉调用都没有产出可用证据。不要继续重复调用视觉工具；请基于已经获得的证据作答，并明确仍存在的不确定性。',
       }],
       source: { kind: 'plugin', plugin: 'dsh-vision-router' },
     }
@@ -435,16 +447,10 @@ function appendGuardMessage(decision, payload, state, config) {
 
   if (!state.bootstrapDone || missingEvidence(state) === 0) return decision
 
-  if (state.mixedBranches.length > 0) {
-    const message = {
-      role: 'user',
-      id: `vision-router-structured-mixed-guard-${state.turn}-${state.successfulEvidenceCalls}`,
-      content: [{ type: 'text', text: mixedReminder(state, config) }],
-      source: { kind: 'plugin', plugin: 'dsh-vision-router' },
-    }
-    return appendSyntheticGuardOnce(decision, baseMessages, state, message, true)
-  }
-
+  // Core owns bootstrap ordering and its one-shot follow-up guidance. This
+  // outer boundary owns the hard x>=1 completion rule. If Core's guidance is
+  // already present, do not duplicate it; if Core's legacy presentation latch
+  // stopped emitting it after an empty/failed attempt, re-assert the hard guard.
   if (hasCoreFollowup(baseMessages)) return decision
   const message = {
     role: 'user',
@@ -452,8 +458,8 @@ function appendGuardMessage(decision, payload, state, config) {
     content: [{
       type: 'text',
       text: language === 'en'
-        ? 'The structured bootstrap is complete, but the previous follow-up tool did not produce usable evidence. Call at least one more vision tool that can add or verify evidence, then answer after it succeeds.'
-        : '结构化预识别已经完成，但上一条后续工具没有产出可用证据。请再调用至少一个能新增或验证证据的视觉工具，成功后再作答。',
+        ? 'The structured bootstrap is complete, but no usable task-directed visual evidence has been produced yet. Call at least one vision tool that can add or verify evidence, then answer after it succeeds.'
+        : '结构化预识别已经完成，但目前还没有产出可用的任务定向视觉证据。请至少调用一个能新增或验证证据的视觉工具，成功后再作答。',
     }],
     source: { kind: 'plugin', plugin: 'dsh-vision-router' },
   }
@@ -542,9 +548,11 @@ function wrapRegisteredTool(def, states, getConfig) {
           if (evidence !== undefined) {
             state.bootstrapDone = true
             state.bootstrapResult = result
-            state.mixedBranches = normalizeMixedBranches(evidence, depthOf(getConfig()))
-            state.completedBranches.clear()
-            state.mixedAttemptSignatures.clear()
+            // Structured 1+x is explicitly ordered: x starts only after the
+            // bootstrap succeeds. Keep the all-turn successful-evidence count
+            // intact for the user's explicit call cap; post-bootstrap progress
+            // has its own counter so an early model call cannot satisfy x>=1.
+            state.postBootstrapEvidenceCalls = 0
             resetNonProgress(state)
             state.budgetExhausted = false
             refreshDepthExhaustion(state, getConfig())
@@ -565,7 +573,7 @@ function wrapRegisteredTool(def, states, getConfig) {
         if (state.bootstrapDone && missingEvidence(state) > 0 && state.nonProgressExhausted) {
           return failure(
             'VISION_NO_PROGRESS_LIMIT',
-            `the structured follow-up stopped after ${MAX_NON_PROGRESS_ATTEMPTS} consecutive attempts without usable evidence progress`,
+            `the structured follow-up stopped after ${MAX_NON_PROGRESS_ATTEMPTS} consecutive attempts without usable evidence`,
           )
         }
 
@@ -577,18 +585,11 @@ function wrapRegisteredTool(def, states, getConfig) {
         )
         const code = resultCode(result)
         if (code === 'VISION_TURN_BUDGET_EXCEEDED') state.budgetExhausted = true
-        if (producedUsableStructuredEvidence(result)) {
-          const progressed = recordEvidenceSuccess(state, def.name, args)
+        if (producedUsableToolEvidence(def.name, result, args)) {
+          state.successfulEvidenceCalls += 1
+          if (state.bootstrapDone) state.postBootstrapEvidenceCalls += 1
           refreshDepthExhaustion(state, active)
-          if (state.bootstrapDone && missingEvidence(state) > 0) {
-            if (progressed) resetNonProgress(state)
-            else {
-              recordNonProgress(state)
-              if (!state.nonProgressExhausted) rearmEvidenceGuardAfterAttempt(state)
-            }
-          } else {
-            resetNonProgress(state)
-          }
+          resetNonProgress(state)
         } else if (code !== 'VISION_TURN_BUDGET_EXCEEDED' && state.bootstrapDone && missingEvidence(state) > 0) {
           recordNonProgress(state)
           if (!state.nonProgressExhausted) rearmEvidenceGuardAfterAttempt(state)