dsh-vision-router 2.0.0 → 2.0.1

package/docs/releases/v2.0.1.md

@@ -0,0 +1,17 @@
+# v2.0.1
+
+这是一个针对长任务识图设置与诊断的补丁版本。
+
+## 修复
+
+- 修复 `visionTaskTimeoutMs` 在浏览器设置页与 Host schema 之间的校验漂移：客户端现在会在写入前正确检查范围和步进，避免 Host 拒绝后只留下 `readback-mismatch`。
+- 明确区分“单次识图任务超时”和“首次识图后的整轮时间上限”；整轮限制继续沿用既有 wall-clock 语义。
+- 保持 v2 默认 `visionTurnBudgetMs=0`（不限制）；不会自动迁移或清除用户已有的显式正数配置。
+- 当整轮视觉时间上限耗尽时，guard 与日志会显示实际生效的限制；Diagnostics 与 Doctor 也会显示有效值及其来源，便于定位旧 profile / composition 覆盖。
+- 增加针对设置边界、预算诊断、Doctor 输出和运行时结构不变量的回归测试。
+
+## Compatibility
+
+- No change to #220/#295 lazy activation or wall-clock accounting.
+- No change to the v2 default: `visionTurnBudgetMs=0` remains unlimited.
+- Existing explicit positive whole-turn limits remain honored.

package/entry.js

@@ -34,6 +34,7 @@ import { installLocalMutationRouteBoundary } from './lib/web-capability-boundary
 import { installScreenshotSourceBoundary } from './lib/screenshot-source-boundary.js'
 import { installVisionToolRuntimeBoundary } from './lib/vision-tool-runtime-boundary.js'
 import { installVisionRouterRemoteSettingsBridge } from './lib/remote-settings-bridge.js'
+import { installSettingsLimitClientPrelude } from './lib/settings-limit-client-prelude.js'
 import { installSettingsRc8ClientLifecycle } from './lib/settings-client-rc8-lifecycle.js'
 import { installCapabilityShadowRuntime } from './lib/vision-capability-shadow.js'
 import { createCapabilityProfileStore } from './lib/vision-capability-probe.js'
@@ -56,6 +57,7 @@ import {
   installStructuredFlowHardening,
   normalizeGuidanceOverrides,
 } from './lib/structured-flow-hardening.js'
+import { installVisionLimitDiagnostics } from './lib/vision-limit-diagnostics.js'
 import {
   attachmentContextForContract,
   hasBatchAttachmentContract,
@@ -205,6 +207,9 @@ export function apply(ctx, config = {}) {
   }
   const batchAttachmentHost = hasBatchAttachmentContract(stabilizedCtx)
   if (batchAttachmentHost) installVisionAttachmentAdmissionPolicy(stabilizedCtx, logging.logger)
+  // Install this before the consolidated Settings IA transform registered by
+  // the remote-settings bridge so the numeric fence remains the outer wrapper.
+  installSettingsLimitClientPrelude(stabilizedCtx)
   installVisionRouterRemoteSettingsBridge(stabilizedCtx, logging.logger)
   installSettingsRc8ClientLifecycle(stabilizedCtx)
   const ownershipCtx = batchAttachmentHost ? protectHostProviderOwnership(stabilizedCtx) : stabilizedCtx
@@ -230,8 +235,15 @@ export function apply(ctx, config = {}) {
   // actual tool registrations and pre-step listener. It makes bootstrap
   // one-shot, enforces fast/standard/deep/custom quotas, tracks mixed branches,
   // rejects empty/non-evidence results, and applies the optional turn deadline
-  // only when the user explicitly configures one.
-  const structuredCtx = installStructuredFlowHardening(legacyCoreCompat.ctx, legacyCoreCompat.config)
+  // only when the user explicitly configures one. The diagnostic observer sits
+  // immediately inside it so it can inspect the final budget result/guard while
+  // leaving #220/#295 wall-clock semantics untouched.
+  const limitDiagnosticCtx = installVisionLimitDiagnostics(
+    legacyCoreCompat.ctx,
+    legacyCoreCompat.config,
+    logging.logger,
+  )
+  const structuredCtx = installStructuredFlowHardening(limitDiagnosticCtx, legacyCoreCompat.config)
   const backgroundProfiling = installBackgroundCapabilityProfiling(
     structuredCtx,
     runtimeConfig,
@@ -369,4 +381,4 @@ export function apply(ctx, config = {}) {
     )
     throw error
   }
-}
+}

package/lib/doctor-cli.js

@@ -4,6 +4,7 @@ import { realpathSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { doctorProfiles, resolveDshHome } from './doctor.js'
 import { inspectPlatform, probeRuntime, supportReport } from './doctor-runtime.js'
+import { inspectDoctorVisionLimits, formatDoctorVisionLimits } from './doctor-vision-limits.js'
 import { repairLegacySessionLogs } from './legacy-session-repair.js'
 
 function usage() {
@@ -206,6 +207,7 @@ export async function run(argv = process.argv.slice(2), io = console, env = proc
     .filter((item) => item.installation?.applicable && item.profileDir)
     .map((item) => item.profileDir)
   const platform = inspectPlatform({ profileDirs: applicableDirs })
+  const visionLimits = inspectDoctorVisionLimits(profileReport.log?.file)
   let sessions
   if (options.sessions) sessions = repairLegacySessionLogs({ dshHome, fix: false })
 
@@ -215,6 +217,7 @@ export async function run(argv = process.argv.slice(2), io = console, env = proc
 
   if (options.json) {
     const report = supportReport({ profileReport, runtime, platform, sessions })
+    report.visionLimits = visionLimits
     report.ok = overallOk
     io.log(JSON.stringify(report, null, 2))
     return overallOk ? 0 : 1
@@ -231,6 +234,10 @@ export async function run(argv = process.argv.slice(2), io = console, env = proc
   if (profileReport.log?.historicalSettingsSaveFailures?.length > 0) {
     io.log(`! Historical settings save failures exist (${profileReport.log.historicalSettingsSaveFailures.length}); none are attributed to the latest plugin start.`)
   }
+  for (const line of formatDoctorVisionLimits(visionLimits)) {
+    if (line.startsWith('WARN:')) io.log(`! ${line.slice('WARN:'.length).trim()}`)
+    else io.log(`✓ ${line}`)
+  }
 
   if (runtime) {
     if (!runtime.reachable) io.log(`– Runtime probe: DSH not reachable at ${runtime.baseUrl}; offline checks still completed.`)

package/lib/doctor-vision-limits.js

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync, statSync, openSync, readSync, closeSync } from 'node:fs'
+
+const LIMIT_LINE = /vision-router: effective vision limits\s+taskTimeoutMs=(\d+)\s+taskSource=([^\s]+)\s+turnBudgetMs=(\d+)\s+turnSource=([^\s]+)/i
+const EXHAUSTED_LINE = /vision-router: vision turn deadline exhausted\s+turn=([^\s]+)\s+budgetMs=(\d+)\s+elapsedMs=([^\s]+)/i
+
+function readTail(file, maxBytes = 2 * 1024 * 1024) {
+  if (!file || !existsSync(file)) return ''
+  let fd
+  try {
+    const stat = statSync(file)
+    const size = Math.min(stat.size, maxBytes)
+    if (size <= 0) return ''
+    const buffer = Buffer.alloc(size)
+    fd = openSync(file, 'r')
+    readSync(fd, buffer, 0, size, Math.max(0, stat.size - size))
+    return buffer.toString('utf8')
+  } catch {
+    try { return readFileSync(file, 'utf8') } catch { return '' }
+  } finally {
+    if (fd !== undefined) closeSync(fd)
+  }
+}
+
+export function parseVisionLimitLog(text) {
+  let latest
+  let latestExhaustion
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const limit = LIMIT_LINE.exec(line)
+    if (limit) {
+      latest = {
+        taskTimeoutMs: Number(limit[1]),
+        taskSource: limit[2],
+        turnBudgetMs: Number(limit[3]),
+        turnSource: limit[4],
+      }
+    }
+    const exhausted = EXHAUSTED_LINE.exec(line)
+    if (exhausted) {
+      latestExhaustion = {
+        turn: exhausted[1],
+        budgetMs: Number(exhausted[2]),
+        elapsedMs: exhausted[3] === 'unknown' ? undefined : Number(exhausted[3]),
+      }
+    }
+  }
+  if (!latest && !latestExhaustion) return undefined
+  return {
+    ...latest,
+    latestExhaustion,
+    explicitTurnLimit: Number(latest?.turnBudgetMs) > 0,
+  }
+}
+
+export function inspectDoctorVisionLimits(logFile) {
+  return parseVisionLimitLog(readTail(logFile))
+}
+
+export function formatDoctorVisionLimits(limits) {
+  if (!limits) return []
+  const task = Number.isFinite(limits.taskTimeoutMs) ? `${limits.taskTimeoutMs / 1000}s` : 'unknown'
+  const turn = Number.isFinite(limits.turnBudgetMs)
+    ? limits.turnBudgetMs === 0 ? 'unlimited' : `${limits.turnBudgetMs / 1000}s`
+    : 'unknown'
+  const lines = [
+    `Vision task timeout: ${task}${limits.taskSource ? ` (${limits.taskSource})` : ''}`,
+    `Vision turn deadline: ${turn}${limits.turnSource ? ` (${limits.turnSource})` : ''}`,
+  ]
+  if (limits.explicitTurnLimit) {
+    lines.push('WARN: an explicit whole-turn vision deadline is active; v2 defaults to unlimited and long multi-image tasks may stop after this deadline.')
+  }
+  return lines
+}

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

@@ -0,0 +1,110 @@
+import { SETTINGS_NUMBER_META } from './settings-number-contract.js'
+
+const CLIENT_MARK = 'data-vision-router-settings-limit-hardening'
+const META = JSON.stringify(SETTINGS_NUMBER_META)
+
+export const SETTINGS_LIMIT_CLIENT_PRELUDE = String.raw`(function(){
+  'use strict';
+  var TARGET='dsh-vision-router';
+  var SECTION_ID='vision-router';
+  var META=${META};
+
+  function obj(value){return value&&typeof value==='object'&&!Array.isArray(value)?value:{};}
+  function own(value,key){return !!value&&typeof value==='object'&&Object.prototype.hasOwnProperty.call(value,key);}
+  function validNumber(key,raw){var meta=META[key];if(!meta)return true;var n=Number(raw);if(!Number.isFinite(n)||!Number.isInteger(n)||n<meta.min||n>meta.max)return false;return (n-meta.min)%meta.step===0;}
+  function source(snapshot,key){var user=obj(snapshot&&snapshot.user),base=obj(snapshot&&snapshot.base);if(own(user,key))return ['用户设置','User override'];if(own(base,key))return ['Profile / Composition','Profile / Composition'];return ['默认','Default'];}
+  function seconds(value,unlimited){var n=Number(value);if(unlimited&&n===0)return ['不限制','Unlimited'];if(!Number.isFinite(n))return ['未知','Unknown'];return [String(n/1000)+' 秒',String(n/1000)+'s'];}
+  function zh(){try{return String(document.documentElement.lang||'').toLowerCase().startsWith('zh');}catch(_){return true;}}
+  function tx(pair){return zh()?pair[0]:pair[1];}
+
+  function wrapScope(scope){
+    if(!scope||typeof scope!=='object')return scope;
+    return new Proxy(scope,{get:function(target,property){
+      if(property==='set'){
+        var set=Reflect.get(target,property,target);if(typeof set!=='function')return set;
+        return function(key,value){
+          if(META[key]&&!validNumber(key,value)){
+            var meta=META[key],error=new Error('value must be an integer between '+meta.min+' and '+meta.max+' in steps of '+meta.step);
+            error.code='settings-client-validation';
+            return Promise.reject(error);
+          }
+          return set.call(target,key,value);
+        };
+      }
+      var value=Reflect.get(target,property,target);return typeof value==='function'?value.bind(target):value;
+    }});
+  }
+
+  function textOf(React,node){
+    if(node===null||node===undefined||node===false)return '';
+    if(typeof node==='string'||typeof node==='number')return String(node);
+    if(!React.isValidElement||!React.isValidElement(node))return '';
+    var out='';React.Children.forEach(node.props&&node.props.children,function(child){out+=textOf(React,child)+' ';});return out;
+  }
+
+  function replacement(text){
+    var map={
+      '单个视觉任务':'单次识图任务超时',
+      'Single visual task':'Single vision-task timeout',
+      '包含该任务内部的重试和备用模型；不是每个后端各自一份。':'包含本次识图内部的重试和备用模型；最长 180 秒。它不会增加本轮视觉时间上限。',
+      'Includes retries and fallbacks inside the task; it is not a fresh budget per backend.':'Includes retries and fallbacks for this vision task; maximum 180s. It does not extend the whole-turn vision deadline.',
+      '整轮视觉工具上限':'首次识图后的整轮时间上限',
+      'Whole-turn vision-tool limit':'Whole-turn limit after first vision call',
+      '部分配置没有写入，未写入的修改已保留。':'Host 未接受或未持久化这项设置，修改已保留。请检查允许范围/步进，或确认 DSH 与 Vision Router 版本匹配。',
+      'Some settings were not written; unwritten changes were kept.':'The Host did not accept or persist this setting. The edit was kept; check the allowed range/step and DSH/Vision Router version compatibility.'
+    };
+    return Object.prototype.hasOwnProperty.call(map,text)?map[text]:text;
+  }
+
+  function transformTree(React,node){
+    if(typeof node==='string')return replacement(node);
+    if(node===null||node===undefined||node===false||!React.isValidElement||!React.isValidElement(node))return node;
+    var originalText=textOf(React,node),props={};
+    if(node.props&&node.props.children!==undefined){props.children=React.Children.map(node.props.children,function(child){return transformTree(React,child);});}
+    if(node.type==='input'&&node.props&&node.props.type==='number'){
+      var min=Number(node.props.min),max=Number(node.props.max),match;
+      Object.keys(META).some(function(key){var meta=META[key];if(meta.min===min&&meta.max===max){match=meta;return true;}return false;});
+      if(match)props.step=match.step;
+    }
+    var next=React.cloneElement(node,props);
+    if(node.type==='div'&&node.props&&String(node.props.className||'').includes('vr-field')&&originalText.includes('整轮视觉工具上限')){
+      var hint=React.createElement('p',{className:'vr-hint',key:'issue307-budget-hint'},zh()
+        ?'从本轮第一次实际 Vision Router 识图调用开始按墙钟计时；模型思考和两次识图之间的等待也计入。长任务建议保持“不限制”。'
+        :'Wall-clock time starts at the first actual Vision Router vision call; model reasoning and waits between calls also count. Keep Unlimited for long tasks.');
+      var children=React.Children.toArray(next.props.children);return React.cloneElement(next,{children:children.concat([hint])});
+    }
+    return next;
+  }
+
+  function diagnosticsCard(React,snapshot){
+    var value=obj(snapshot&&snapshot.value),task=seconds(value.visionTaskTimeoutMs===undefined?120000:value.visionTaskTimeoutMs,false),budget=seconds(value.visionTurnBudgetMs===undefined?0:value.visionTurnBudgetMs,true),taskSource=source(snapshot,'visionTaskTimeoutMs'),budgetSource=source(snapshot,'visionTurnBudgetMs');
+    function row(label,valueText){return React.createElement('div',{className:'vr-ia-diag-row'},React.createElement('span',null,label),React.createElement('strong',null,valueText));}
+    return React.createElement('div',{className:'vr-card vr-card-open vr-ia-card','data-vr-limit-diagnostics':'1'},React.createElement('div',{className:'vr-body',style:{borderTop:0}},[
+      row(zh()?'单次识图任务超时':'Single vision-task timeout',tx(task)+' · '+tx(taskSource)),
+      row(zh()?'首次识图后的整轮时间上限':'Whole-turn limit after first vision call',tx(budget)+' · '+tx(budgetSource)),
+      Number(value.visionTurnBudgetMs)>0?React.createElement('p',{className:'vr-hint',key:'warning'},zh()?'当前启用了显式整轮视觉时间上限；v2 默认是不限制，长任务可能在该时间后停止继续识图。':'An explicit whole-turn vision limit is active. v2 defaults to Unlimited; long tasks may stop making vision calls after this time.'):null
+    ]));
+  }
+
+  function wrapSlots(slots,React){if(!slots||(typeof slots!=='object'&&typeof slots!=='function'))return slots;return new Proxy(slots,{get:function(target,property){if(property==='register'){var register=Reflect.get(target,property,target);if(typeof register!=='function')return register;return function(options,component){var args=Array.prototype.slice.call(arguments);if(options&&options.name==='settings.section'&&options.id===SECTION_ID&&typeof component==='function'){var Original=component;args[1]=function VisionRouterIssue307SettingsBoundary(props){var scope=wrapScope(props&&props.scope),nextProps=Object.assign({},props,{scope:scope}),tree=transformTree(React,Original(nextProps)),text=textOf(React,tree),snapshot;try{snapshot=scope&&scope.getSnapshot?scope.getSnapshot():undefined;}catch(_){snapshot=undefined;}if(text.includes('设置协议')||text.includes('Settings contract'))return React.createElement(React.Fragment,null,tree,diagnosticsCard(React,snapshot));return tree;};}return register.apply(target,args);};}var value=Reflect.get(target,property,target);return typeof value==='function'?value.bind(target):value;}});}
+  function wrapContext(ctx,React){if(!ctx||typeof ctx!=='object')return ctx;var slots=wrapSlots(ctx.slots,React);return new Proxy(ctx,{get:function(target,property){if(property==='slots')return slots;var value=Reflect.get(target,property,target);return typeof value==='function'?value.bind(target):value;}});}
+  function patchLoader(loader){if(!loader||(typeof loader!=='object'&&typeof loader!=='function'))return;if(typeof loader.load==='function'&&!loader.load.__visionRouterLimitHardening){var original=loader.load;function load(spec){if(spec&&spec.id===TARGET&&typeof spec.factory==='function'){var factory=spec.factory;spec=Object.assign({},spec,{factory:function(require){var exports=factory(require),React;try{React=require('react');}catch(_){React=undefined;}if(React&&exports&&typeof exports.apply==='function'&&!exports.apply.__visionRouterLimitHardening){var apply=exports.apply;var wrappedApply=function(ctx){var rest=Array.prototype.slice.call(arguments,1);return apply.apply(exports,[wrapContext(ctx,React)].concat(rest));};Object.defineProperty(wrappedApply,'__visionRouterLimitHardening',{value:true});exports.apply=wrappedApply;}return exports;}});}return original.call(loader,spec);}Object.defineProperty(load,'__visionRouterLimitHardening',{value:true});loader.load=load;}}
+  function install(){if(window.__ModuleLoader__){patchLoader(window.__ModuleLoader__);return;}var descriptor=Object.getOwnPropertyDescriptor(window,'__ModuleLoader__');if(descriptor&&descriptor.configurable===false)return;var stored;Object.defineProperty(window,'__ModuleLoader__',{configurable:true,enumerable:true,get:function(){return stored;},set:function(value){stored=value;patchLoader(value);Object.defineProperty(window,'__ModuleLoader__',{configurable:true,enumerable:true,writable:true,value:stored});}});}
+  try{install();}catch(_){}
+})();`
+
+export function injectSettingsLimitClientPrelude(html) {
+  if (typeof html !== 'string' || html.includes(CLIENT_MARK)) return html
+  const script = `<script ${CLIENT_MARK}>${SETTINGS_LIMIT_CLIENT_PRELUDE.replace(/<\/script/gi, '<\\/script')}</script>`
+  const closeHead = html.indexOf('</head>')
+  return closeHead === -1 ? `${html}${script}` : `${html.slice(0, closeHead)}${script}${html.slice(closeHead)}`
+}
+
+export function installSettingsLimitClientPrelude(ctx) {
+  ctx?.inject?.(['webServer'], (webCtx) => {
+    webCtx.effect(
+      () => webCtx.webServer.tapIndex(injectSettingsLimitClientPrelude),
+      'vision-router: settings numeric contract and limit diagnostics prelude',
+    )
+  })
+}

package/lib/settings-number-contract.js

@@ -0,0 +1,29 @@
+export const SETTINGS_NUMBER_META = Object.freeze({
+  timeoutMs: Object.freeze({ min: 1000, max: 600000, step: 1 }),
+  visionTaskTimeoutMs: Object.freeze({ min: 1000, max: 180000, step: 1000 }),
+  ocrTimeoutMs: Object.freeze({ min: 1000, max: 120000, step: 1 }),
+  downscaleMaxPixels: Object.freeze({ min: 1000, max: 100000000, step: 1 }),
+  cacheTtlSeconds: Object.freeze({ min: 0, max: 31536000, step: 1 }),
+  cacheMaxEntries: Object.freeze({ min: 1, max: 100000, step: 1 }),
+  visionDepthMaxCalls: Object.freeze({ min: 0, max: 100, step: 1 }),
+  visionTurnBudgetMs: Object.freeze({ min: 0, max: 600000, step: 1000 }),
+})
+
+export function parseSettingsNumber(key, raw, { allowClear = false } = {}) {
+  const meta = SETTINGS_NUMBER_META[key]
+  if (!meta) return undefined
+  if (raw === '' || raw === null || raw === undefined) return allowClear ? { clear: true } : undefined
+  const value = Number(raw)
+  if (!Number.isFinite(value) || !Number.isInteger(value)) return undefined
+  if (value < meta.min || value > meta.max) return undefined
+  if ((value - meta.min) % meta.step !== 0) return undefined
+  return { value }
+}
+
+export function formatDurationMs(value, { unlimitedZero = false } = {}) {
+  const number = Number(value)
+  if (!Number.isFinite(number)) return undefined
+  if (unlimitedZero && number === 0) return 'unlimited'
+  if (number % 1000 === 0) return `${number / 1000}s`
+  return `${number}ms`
+}

package/lib/vision-limit-diagnostics.js

@@ -0,0 +1,202 @@
+const SETTINGS_NS = 'vision-router'
+const TURN_BUDGET_CODE = 'VISION_TURN_BUDGET_EXCEEDED'
+const GUARD_PREFIX = 'vision-router-structured-guard-stop-'
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function hasOwn(value, key) {
+  return isObject(value) && Object.prototype.hasOwnProperty.call(value, key)
+}
+
+function parseResult(value) {
+  if (isObject(value)) return value
+  if (typeof value !== 'string' || value.trim() === '') return undefined
+  try { return JSON.parse(value) } catch { return undefined }
+}
+
+function settingsService(ctx) {
+  try {
+    const settings = ctx?.get?.('settings')
+    return settings && typeof settings === 'object' ? settings : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function sourceFor(descriptor, key) {
+  if (hasOwn(descriptor?.user, key)) return 'user'
+  if (hasOwn(descriptor?.base, key)) return 'composition'
+  return 'default'
+}
+
+export function resolveVisionLimitDiagnostics(ctx, fallbackConfig = {}) {
+  const settings = settingsService(ctx)
+  let value
+  let descriptor
+  try { value = settings?.get?.(SETTINGS_NS) } catch { value = undefined }
+  try {
+    const described = settings?.describe?.({ redactSecrets: true })
+    descriptor = Array.isArray(described)
+      ? described.find((entry) => entry?.ns === SETTINGS_NS)
+      : undefined
+  } catch {
+    descriptor = undefined
+  }
+  const effective = isObject(value) ? value : isObject(descriptor?.value) ? descriptor.value : fallbackConfig
+  const taskTimeoutMs = Number.isFinite(Number(effective?.visionTaskTimeoutMs))
+    ? Number(effective.visionTaskTimeoutMs)
+    : 120000
+  const turnBudgetMs = Number.isFinite(Number(effective?.visionTurnBudgetMs))
+    ? Number(effective.visionTurnBudgetMs)
+    : 0
+  return {
+    taskTimeoutMs,
+    turnBudgetMs,
+    taskSource: descriptor ? sourceFor(descriptor, 'visionTaskTimeoutMs') : 'unknown',
+    turnSource: descriptor ? sourceFor(descriptor, 'visionTurnBudgetMs') : 'unknown',
+  }
+}
+
+export function formatVisionTurnGuard(turnBudgetMs) {
+  const ms = Number(turnBudgetMs)
+  const seconds = Number.isFinite(ms) && ms > 0 ? Math.round(ms / 1000) : undefined
+  const limit = seconds === undefined ? '' : `（${seconds} 秒）`
+  return `Vision Router 本轮视觉时间上限${limit}已耗尽。不要再调用视觉工具；请基于已经获得的证据作答，并明确仍存在的不确定性。默认配置为“不限制”；长任务如需继续识图，请检查“设置 → Vision Router → 高级 → 首次识图后的整轮时间上限”。`
+}
+
+function replaceGuardText(decision, turnBudgetMs) {
+  if (!isObject(decision) || !Array.isArray(decision.messages)) return decision
+  let anyChanged = false
+  const messages = decision.messages.map((message) => {
+    if (!isObject(message) || typeof message.id !== 'string' || !message.id.startsWith(GUARD_PREFIX)) return message
+    if (!Array.isArray(message.content)) return message
+    let messageChanged = false
+    const content = message.content.map((block) => {
+      if (!isObject(block) || block.type !== 'text' || typeof block.text !== 'string') return block
+      if (!block.text.includes('本轮视觉总时间预算已耗尽')) return block
+      messageChanged = true
+      anyChanged = true
+      return { ...block, text: formatVisionTurnGuard(turnBudgetMs) }
+    })
+    return messageChanged ? { ...message, content } : message
+  })
+  return anyChanged ? { ...decision, messages } : decision
+}
+
+export function installVisionLimitDiagnostics(ctx, fallbackConfig = {}, logger) {
+  if (!ctx || typeof ctx !== 'object') return ctx
+  const turnState = new WeakMap()
+  let startupLogged = false
+
+  const snapshot = () => resolveVisionLimitDiagnostics(ctx, fallbackConfig)
+  const logStartup = () => {
+    if (startupLogged) return
+    const limits = snapshot()
+    startupLogged = true
+    logger?.info?.(
+      'vision-router: effective vision limits taskTimeoutMs=%d taskSource=%s turnBudgetMs=%d turnSource=%s',
+      limits.taskTimeoutMs,
+      limits.taskSource,
+      limits.turnBudgetMs,
+      limits.turnSource,
+    )
+  }
+
+  try {
+    ctx.inject?.(['settings'], (settingsCtx) => {
+      settingsCtx.effect?.(() => {
+        queueMicrotask(logStartup)
+        return () => {}
+      }, 'vision-router: report effective vision limits')
+    })
+  } catch {
+    // Diagnostics are best-effort and must never block plugin startup.
+  }
+
+  const stateForVisualCall = (session, turnHint) => {
+    if (!session) return undefined
+    let state = turnState.get(session)
+    if (!state || (turnHint !== undefined && state.turn !== turnHint)) {
+      state = { turn: turnHint, startedAt: undefined, exhaustionLogged: false }
+      turnState.set(session, state)
+    }
+    if (state.startedAt === undefined) state.startedAt = Date.now()
+    return state
+  }
+
+  const wrapTool = (def) => {
+    if (!def || typeof def.execute !== 'function') return def
+    if (def.name !== 'vision_bootstrap' && !String(def.name || '').startsWith('vision_')) return def
+    return {
+      ...def,
+      async execute(args, exec) {
+        const session = exec?.agent?.session
+        const state = stateForVisualCall(session, exec?.agent?.turn ?? exec?.turn)
+        const result = await def.execute(args, exec)
+        const parsed = parseResult(result)
+        if (parsed?.code !== TURN_BUDGET_CODE) return result
+        if (state?.exhaustionLogged) return result
+        if (state) state.exhaustionLogged = true
+        const limits = snapshot()
+        const elapsedMs = state?.startedAt === undefined
+          ? undefined
+          : Math.max(0, Date.now() - state.startedAt)
+        logger?.warn?.(
+          'vision-router: vision turn deadline exhausted turn=%s budgetMs=%d elapsedMs=%s',
+          state?.turn === undefined ? 'unknown' : String(state.turn),
+          limits.turnBudgetMs,
+          elapsedMs === undefined ? 'unknown' : String(elapsedMs),
+        )
+        return result
+      },
+    }
+  }
+
+  return new Proxy(ctx, {
+    get(target, property) {
+      if (property === 'tools') {
+        const tools = target.tools
+        if (!tools || typeof tools !== 'object') return tools
+        return new Proxy(tools, {
+          get(toolTarget, toolProperty) {
+            if (toolProperty !== 'register') {
+              const value = Reflect.get(toolTarget, toolProperty, toolTarget)
+              return typeof value === 'function' ? value.bind(toolTarget) : value
+            }
+            const register = Reflect.get(toolTarget, toolProperty, toolTarget)
+            return (def) => register.call(toolTarget, wrapTool(def))
+          },
+        })
+      }
+      if (property === 'on') {
+        const on = Reflect.get(target, property, target)
+        if (typeof on !== 'function') return on
+        return (event, handler, ...rest) => {
+          if (event !== 'agent/pre-step' || typeof handler !== 'function') {
+            return on.call(target, event, handler, ...rest)
+          }
+          return on.call(target, event, async function issue307GuardDiagnostics(payload, next) {
+            const session = payload?.agent?.session
+            if (session) {
+              const current = turnState.get(session)
+              if (!current || current.turn !== payload?.turn) {
+                turnState.set(session, {
+                  turn: payload?.turn,
+                  startedAt: undefined,
+                  exhaustionLogged: false,
+                })
+              }
+            }
+            const decision = await handler.call(this, payload, next)
+            const limits = snapshot()
+            return replaceGuardText(decision, limits.turnBudgetMs)
+          }, ...rest)
+        }
+      }
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vision-router",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Eyes for text-only DeepSeek Harness agents: built-in free vision chain (no key) + pixel-level vision tools (Q&A, grounding, crop, pixel diff, colors, OCR, SVG trace, cutout, screenshots). One-command install, no Python, image turns work like ordinary tool-calling turns.",
   "license": "MIT",
   "repository": {
@@ -69,7 +69,7 @@
     "sharp": "^0.35.3"
   },
   "scripts": {
-    "test": "node --test tests/adapter-prepare-call-compat.test.js tests/core.test.js tests/capability-advisory.test.js tests/vision-execution-policy.test.js tests/vision-backend-diagnostics.test.js tests/live-model-discovery.test.js tests/live-model-credential-resolution.test.js tests/vision-model-registry.test.js tests/live-model-client-stability.test.js tests/providers-persistence.test.js tests/provider-directory-fallback.test.js tests/model-catalog-policy.test.js tests/settings-ia-client-prelude.test.js tests/settings-ia-fj.test.js tests/settings-ia-acceptance-regression.test.js tests/settings-migration.test.js tests/settings-section-order.test.js tests/attachment-admission-policy.test.js tests/vision-resilience.test.js tests/vision-breaker-readonly.test.js tests/client.test.js tests/issue-284-vision-mode-toggle.test.js tests/issue-284-vision-mode-hardening.test.js tests/issue-284-attachment-id-hint.test.js tests/issue-284-model-visibility.test.js tests/issue-284-vision-selection-effort.test.js tests/client-presentation-boundary.test.js tests/remote-settings-bridge.test.js tests/remote-settings-v2-contract.test.js tests/remote-settings-risk-confirmation.test.js tests/local-remote-settings-permission.test.js tests/rc6-real-settings-persistence.test.js tests/artifact-path-security.test.js tests/http-compat.test.js tests/catalog-corrections.test.js tests/update-check.test.js tests/self-update.test.js tests/doctor.test.js tests/doctor-cli.test.js tests/legacy-session-repair.test.js tests/profile-pnpm-diagnostics.test.js tests/doctor-v2.test.js tests/doctor-cli-v2.test.js tests/doctor-runtime.test.js tests/session-repair-v2.test.js tests/bundle-defaults.test.js tests/file-logger.test.js tests/replay-delegation.test.js tests/adversarial-hardening.test.js tests/vision-adversarial-hardening-v2.test.js tests/vision-capability-benchmark-visual-proof.test.js tests/wrapper-directory.test.js tests/logging-ui.test.js tests/manifest-dependencies.test.js tests/structured-bootstrap.test.js tests/structured-bootstrap-gate.test.js tests/local-ollama.test.js tests/ollama-cold-start.test.js tests/ollama-cold-start-loaded.test.js tests/zero-regression-gate.test.js tests/runtime-e2e.test.js tests/local-vision-stabilizer.test.js tests/local-connection-probe.test.js tests/repetition-guard.test.js tests/guide-scroll-gate.test.js tests/settings-scroll-jank-regression.test.js tests/android-attachment-compat.test.js tests/free-cloud-first.test.js tests/rc6-rc7-compat.test.js tests/native-image-coexistence.test.js tests/issue-276-session-image-ownership.test.js tests/issue-276-entry-policy-bridge.test.js tests/issue-276-policy-hardening.test.js tests/issue-289-native-nonintervention.test.js tests/pi-ai-bridge-wire-compat.test.js tests/mixed-router.test.js tests/depth-tier.test.js tests/depth-quota-behavior.test.js tests/structured-flow-hardening.test.js tests/vision-budget-activation.test.js tests/runtime-boundary-fixes.test.js tests/tesseract-node24-boot.test.js tests/session-vision-state.test.js tests/session-vision-state-integration.test.js tests/image-resource-governor.test.js tests/pixel-diff-stream.test.js tests/large-image-resource-integration.test.js tests/structured-guard-idempotency.test.js tests/vision-routing-product.test.js tests/vision-runtime-performance.test.js tests/vision-routing-settings-prelude.test.js tests/v2-settings-ia-integration.test.js tests/vision-capability-router.test.js tests/vision-capability-reference.test.js tests/vision-capability-benchmark.test.js tests/vision-capability-grounding-proof-contract.test.js tests/vision-capability-probe.test.js tests/vision-capability-shadow.test.js tests/vision-capability-axis-freshness.test.js tests/vision-capability-shadow-health.test.js tests/vision-capability-benchmark-service.test.js tests/vision-capability-preflight-hardening.test.js tests/vision-capability-benchmark-contract.test.js tests/vision-capability-benchmark-client.test.js tests/vision-capability-benchmark-client-productization.test.js tests/vision-capability-adapter-route.test.js tests/vision-background-benchmark.test.js tests/vision-background-benchmark-productization.test.js tests/vision-capability-benchmark-budget.test.js tests/vision-image-input-verdict.test.js tests/vision-capability-failure-classification.test.js tests/vision-capability-gate-client.test.js tests/v2-product-review-fixes.test.js tests/qa-top5-reliability.test.js tests/qa-screenshot-runtime.test.js tests/qa-runtime-identity.test.js tests/qa-turn-budget-cancellation.test.js tests/qa-cancellation-publication.test.js tests/qa-reliability-tail.test.js tests/qa-endpoint-route-alias.test.js tests/vision-toggle-root-hardening.test.js && node --test tests/vision-backend-runtime-policy.test.js"
+    "test": "node --test tests/adapter-prepare-call-compat.test.js tests/core.test.js tests/capability-advisory.test.js tests/vision-execution-policy.test.js tests/vision-backend-diagnostics.test.js tests/live-model-discovery.test.js tests/live-model-credential-resolution.test.js tests/vision-model-registry.test.js tests/live-model-client-stability.test.js tests/providers-persistence.test.js tests/provider-directory-fallback.test.js tests/model-catalog-policy.test.js tests/settings-ia-client-prelude.test.js tests/settings-ia-fj.test.js tests/settings-ia-acceptance-regression.test.js tests/settings-migration.test.js tests/settings-section-order.test.js tests/attachment-admission-policy.test.js tests/vision-resilience.test.js tests/vision-breaker-readonly.test.js tests/client.test.js tests/issue-307-regression.test.js tests/issue-284-vision-mode-toggle.test.js tests/issue-284-vision-mode-hardening.test.js tests/issue-284-attachment-id-hint.test.js tests/issue-284-model-visibility.test.js tests/issue-284-vision-selection-effort.test.js tests/client-presentation-boundary.test.js tests/remote-settings-bridge.test.js tests/remote-settings-v2-contract.test.js tests/remote-settings-risk-confirmation.test.js tests/local-remote-settings-permission.test.js tests/rc6-real-settings-persistence.test.js tests/artifact-path-security.test.js tests/http-compat.test.js tests/catalog-corrections.test.js tests/update-check.test.js tests/self-update.test.js tests/doctor.test.js tests/doctor-cli.test.js tests/legacy-session-repair.test.js tests/profile-pnpm-diagnostics.test.js tests/doctor-v2.test.js tests/doctor-cli-v2.test.js tests/doctor-runtime.test.js tests/session-repair-v2.test.js tests/bundle-defaults.test.js tests/file-logger.test.js tests/replay-delegation.test.js tests/adversarial-hardening.test.js tests/vision-adversarial-hardening-v2.test.js tests/vision-capability-benchmark-visual-proof.test.js tests/wrapper-directory.test.js tests/logging-ui.test.js tests/manifest-dependencies.test.js tests/structured-bootstrap.test.js tests/structured-bootstrap-gate.test.js tests/local-ollama.test.js tests/ollama-cold-start.test.js tests/ollama-cold-start-loaded.test.js tests/zero-regression-gate.test.js tests/runtime-e2e.test.js tests/local-vision-stabilizer.test.js tests/local-connection-probe.test.js tests/repetition-guard.test.js tests/guide-scroll-gate.test.js tests/settings-scroll-jank-regression.test.js tests/android-attachment-compat.test.js tests/free-cloud-first.test.js tests/rc6-rc7-compat.test.js tests/native-image-coexistence.test.js tests/issue-276-session-image-ownership.test.js tests/issue-276-entry-policy-bridge.test.js tests/issue-276-policy-hardening.test.js tests/issue-289-native-nonintervention.test.js tests/pi-ai-bridge-wire-compat.test.js tests/mixed-router.test.js tests/depth-tier.test.js tests/depth-quota-behavior.test.js tests/structured-flow-hardening.test.js tests/vision-budget-activation.test.js tests/runtime-boundary-fixes.test.js tests/tesseract-node24-boot.test.js tests/session-vision-state.test.js tests/session-vision-state-integration.test.js tests/image-resource-governor.test.js tests/pixel-diff-stream.test.js tests/large-image-resource-integration.test.js tests/structured-guard-idempotency.test.js tests/vision-routing-product.test.js tests/vision-runtime-performance.test.js tests/vision-routing-settings-prelude.test.js tests/v2-settings-ia-integration.test.js tests/vision-capability-router.test.js tests/vision-capability-reference.test.js tests/vision-capability-benchmark.test.js tests/vision-capability-grounding-proof-contract.test.js tests/vision-capability-probe.test.js tests/vision-capability-shadow.test.js tests/vision-capability-axis-freshness.test.js tests/vision-capability-shadow-health.test.js tests/vision-capability-benchmark-service.test.js tests/vision-capability-preflight-hardening.test.js tests/vision-capability-benchmark-contract.test.js tests/vision-capability-benchmark-client.test.js tests/vision-capability-benchmark-client-productization.test.js tests/vision-capability-adapter-route.test.js tests/vision-background-benchmark.test.js tests/vision-background-benchmark-productization.test.js tests/vision-capability-benchmark-budget.test.js tests/vision-image-input-verdict.test.js tests/vision-capability-failure-classification.test.js tests/vision-capability-gate-client.test.js tests/v2-product-review-fixes.test.js tests/qa-top5-reliability.test.js tests/qa-screenshot-runtime.test.js tests/qa-runtime-identity.test.js tests/qa-turn-budget-cancellation.test.js tests/qa-cancellation-publication.test.js tests/qa-reliability-tail.test.js tests/qa-endpoint-route-alias.test.js tests/vision-toggle-root-hardening.test.js && node --test tests/vision-backend-runtime-policy.test.js"
   },
   "pnpm": {
     "onlyBuiltDependencies": ["sharp"]