dsh-vision-router 1.6.0 → 1.6.2

package/README.md

@@ -29,9 +29,9 @@
 <p align="center">💬 <strong>QQ community group: 1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **Announcement (v1.6.0)**
+> 📌 **Announcement (v1.6.2)**
 >
-> **v1.6.0:** Explicit vision-backend authorization — paid visual models merely configured in DSH are no longer callable; the DeepSeek + 自动识图 identity is pinned to official DeepSeek; the one-click updater now infers the owning profile and refuses on ambiguity; full-page screenshots, rc.7 Models directory, install diagnostics, guide-scroll performance and Android/Termux attachments all fixed.
+> **v1.6.2:** Stability release — fixes onboarding, OCR, model synchronization and large-image handling, improving long-session and overall runtime reliability.
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="Demo: paste an image, the agent locates the send button with vision_ground / vision_crop / vision_pixel_diff and answers with coordinates" />
@@ -154,7 +154,7 @@ The auto-vision group follows the live DSH model catalog. Adding models or chang
 
 ### 3. Paste or upload the image
 
-After choosing the “+ Auto Vision” group, paste or upload an image normally. By default the complete vision tool schema is stable from session start, so the agent can immediately use `vision_describe`, `vision_ground`, `vision_crop`, and the rest across multiple steps when needed.
+After choosing the “+ Auto Vision” model group, paste or upload an image normally. By default the complete vision tool schema is stable from session start, so the agent can immediately use `vision_describe`, `vision_ground`, `vision_crop`, and the rest across multiple steps when needed.
 
 The built-in anonymous OVH vision fallback is already configured, so normal image use needs no signup or API key. **The lower-right chat picker selects only the brain/conversation model**; vision backends do not belong there. Advanced options live under **Settings → Plugins → Plugin config → 视觉路由（自动识图）**: each vision-backend row may select any callable generative user model already configured under **Settings → Models**. DSH image-capability metadata is advisory only: undeclared or text-only-labelled models remain selectable and show a warning. At runtime Vision Router always tries the provider's registered DSH adapter first — including WebSocket, RPC and private transports — and falls through on a real failure. The direct compatibility bridge is used only when an http(s) OpenAI Chat Completions endpoint is positively identified. Leaving every user row empty is valid; the OVH chain remains the final fallback. `Vision HTTP` is an internal transport route, not a model group users should select.
 

package/README.zh.md

@@ -29,9 +29,9 @@
 <p align="center">💬 <strong>QQ 用户交流群：1105463028</strong></p>
 
 > [!WARNING]
-> 📌 **公告（v1.6.0）**
+> 📌 **公告（v1.6.2）**
 >
-> **v1.6.0：视觉后端显式授权——仅在 DSH 里配置过的付费视觉模型不再可被调用，「DeepSeek + 自动识图」身份钉死官方 DeepSeek；一键更新改为从运行中插件真实路径反查所属 profile、不确定即拒绝；全页截图、rc.7 模型目录、安装诊断、设置引导性能与 Android/Termux 附件全部修复。**
+> **v1.6.2：集中修复引导、OCR、模型同步与大图处理问题，提升长会话和整体运行稳定性。**
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="演示：粘贴图片，Agent 用 vision_ground / vision_crop / vision_pixel_diff 定位发送按钮并给出坐标" />

package/cordis.patch.yml

@@ -4,9 +4,9 @@
 # without any manual cordis.patch.yml edits. Later layers (the profile's own
 # cordis.patch.yml, --patch overlays) override these rows by id.
 
-# 纯增量补丁（issue #34）：不碰核心行。官方 llm-deepseek 行保持原样，插件
-# 挂载后是否接管官方 deepseek-official 路由由设置里的「隐身模式」开关决定
-# （默认关；开启后需自行在 profile 补丁层禁用 llm-deepseek 行）。
+# 纯增量补丁（issue #34）：不碰核心行。DSH rc.6仍保留旧版隐身接管兼容路径；
+# DSH rc.7则始终由宿主拥有deepseek-official，插件只提供「+ 自动识图」包装路由。
+# 因此这里永远不默认禁用官方llm-deepseek行。
 
 # 挂载插件行。默认保持完整视觉工具表常驻（issue #81）：虽然渐进挂载可以
 # 少发一小段工具 schema，但图片轮首次扩展工具列表会改变请求前缀，可能让
@@ -18,8 +18,13 @@
       config:
         progressiveTools: false
 
-# 放宽附件图片限制（部署默认 5MB / 4000 万像素 → 20MB / 1 亿像素），
-# 大尺寸设计稿/扫描图可过审。字段可选，不需要可在 profile 补丁层覆写。
+# 放宽附件图片限制（宿主默认 5MB / 4000 万像素 → 20MB / 1 亿像素），
+# 超长聊天记录截图（vision_long_screenshot_ocr 主场景）与大尺寸设计稿/
+# 扫描图可过宿主准入。rc6 与 rc7 的 @deepseek-ai/dsh-attachment-local
+# 均接受这两个可选字段（0.1.0-rc.6 / 0.1.0-rc.7 schema 已核对），且两边
+# dsh-base bundle 都存在 `- id: attachment-local` 行，因此该补丁在两个
+# 运行时上都有效、不破坏 host-neutral 原则；字段可选，不需要可在 profile
+# 补丁层覆写。
 - id: attachment-local
   config:
     maxImageBytes: 20971520

package/docs/handover-178.zh-CN.md

@@ -0,0 +1,116 @@
+# #178 交接文档：1+x 深挖引导（mixed 分路 / 深度档位 / 收敛分类 / 引导可配置）
+
+> 对应 PR：[#178 feat: 1+x deep-dive guidance - mixed branching, depth tier, convergent classification, configurable copy](https://github.com/ysr666/dsh-vision-router/pull/178)
+> 分支：`feat/mixed-router` @ `7ac5ee8`（stacked on #177 `feat/free-cloud-first` @ `a8384ca`）
+> 作者：shaoqiuyuavailable（`rangsic2963277@163.com`）
+> 状态：open，7 个 commit 全部为作者本人提交（2 个来自 #177 + 5 个本 PR 增量）
+
+---
+
+## 一、一句话定位
+
+在群主 v2 能力路由（#142）与 structured bootstrap 1+x（#136）框架之上，补齐**深挖阶段**的四个维度：**精度（mixed 分路）、深度（档位）、收敛（schema 分类）、可配置（引导文案）**。全部默认行为不变（zero-regression）。
+
+## 二、增量作者与来源
+
+| 项 | 说明 |
+|---|---|
+| 增量作者 | shaoqiuyuavailable，dsh-vision 插件（`shaoqiuyuavailable/text-llm-vision`）作者 |
+| 概念来源 | dsh-vision main 分支的 `scan → zoom → guess` 场景路由 + PRECISION 档位；dsh-vision 分支（text-llm-vision）的场景级识图路由层设计 |
+| 本 PR 性质 | 在群主已有框架上的**成本/速度妥协优化**：概念移植为 router 生态的轻量实现，不引入 dsh-vision 的完整引擎路由表 |
+| 定位边界 | 与 #142（能力路由：谁来看）正交——本 PR 只负责**怎么看的引导**，出口选择仍归模型（软路由） |
+
+## 三、设计哲学（四条，均来自 dsh-vision 实践结论）
+
+1. **场景感知路由（scene-aware routing）**：先分类、再引导识别方式，替代"所有图一条固定链"。
+2. **档位只定深度、不参与提示词组合**：fast/standard/deep 是用户级全局开关；引导文案是**模板集合**（每类一条），不是提示词矩阵——工作量 = 引导表 + 拼接函数。
+3. **收敛分类（schema 免费收敛）**：让视觉模型直接输出结构化枚举（JSON schema 天然校验），替代系统启发式——同时用于 `content_kind`（主体）与 `mixed_of`（混合构成），删除约 60 行 entities 启发式。
+4. **软引导、硬上限（soft guidance, hard caps）**：识别方式/工具选择归模型（软文案引导，保留逃生通道）；深度是唯一硬约束（VISION_DEPTH_LIMIT）。
+
+## 四、功能详述（5 个增量 commit）
+
+### 1. `7fe43fb` feat: mixed branch routing（新建 `lib/mixed-router.js`）
+- **动机**：1.5.3 中 bootstrap 判出 `visual_kind=mixed` 后无后续处理，模型自由深挖可能漏判/错判另一半内容（§4.6 缺陷实证）。
+- **实现**：`planMixedBranches()` 消费 bootstrap 的 `mixed_of`，产出 ≤2 个分支（`MAX_MIXED_BRANCHES=2`），每分支一条独立软引导（`BRANCH_GUIDANCE`：document:code / document:form / document:table / ui / code / table / _default 放行）；主/次分支按信号强度排序（可交互 > 文字 > 其余，`KIND_PRIORITY`）。
+- **防呆**：`mixed_of` 缺失/为空 → `fallback=true` **放行**（绝不硬拦，行为同现状）。
+- **成本**：混合图 ≤2 次视觉调用，成本封顶（副产品）。
+- **语义差异**：与 dsh-vision 不同——语义从"实体主体"（人+飞机）改为"内容类型"（文档+UI）。
+
+### 2. `a85c8c1` feat: visionDepth tier（新建 `lib/depth-guidance.js` + index.js 档位注入）
+- **动机**：深挖深度无约束，成本不可控。
+- **实现**：新配置 `visionDepth`（`fast|standard|deep`，默认 `standard`）。档位句注入 bootstrapReminder（执行前，只给档位）与 followupReminder（完成后，场景引导+档位句）。
+- **硬上限**：`depthLimitFor()` — fast=1、deep=4、standard=不硬拦（现状行为）。在 evidence 深挖工具（`structuredFollowupEvidenceTools`）入口计数 `state.deepCalls`，超限返回 `VISION_DEPTH_LIMIT`（retryable:false）。bootstrap 那 1 遍不计入。
+- **提示**：fast 档携带"若需深度定向识别请告知用户升级档位"句（搬 dsh-vision 回答节思想）。
+
+### 3. `ff0ecca` feat: content_kind in bootstrap schema（`lib/structured-bootstrap.js`）
+- **动机**：general 图（媒介无引导）缺主体方向，深挖无的放矢。
+- **实现**：bootstrap schema 新增 `content_kind` 枚举（person/animal/plant/food/vehicle/machine/architecture/object/scene/meme + unknown），normalizer 枚举校验，非法/缺失 → unknown；media-kind 图（document/ui/code/chat）约定 unknown。
+- **消费**：`renderDepthGuidance()` — general 且 content_kind 已知 → 内容引导（`CONTENT_GUIDANCE` 10 类）；未知 → `GENERAL_FALLBACK_GUIDANCE` 兜底（让模型自判主体方向）。
+
+### 4. `1b8b50e` refactor: mixed_of in bootstrap schema（`lib/structured-bootstrap.js` + `lib/mixed-router.js`）
+- **动机**：entities 启发式推断混合构成不稳定。
+- **实现**：bootstrap schema 新增 `mixed_of`（仅 `visual_kind=mixed` 时填写，1-2 项，document/ui/code/chat/general）；normalizer 枚举校验+去重+≤2，非法/缺失 → `[]`（调用方 fallback 放行）。`normalizeMixedOf()` 与 schema 同域、同哲学，删除 entities 启发式路径（约 60 行）。
+
+### 5. `7ac5ee8` feat: guidanceOverrides（`lib/client.js` + `lib/depth-guidance.js`）
+- **动机**：引导文案硬编码，用户无法按需调整。
+- **实现**：新配置 `guidanceOverrides`（`[{kind, text}]`，默认 `[]`= 内置表，零变化）。`resolveGuidance()` 覆盖优先于内置表；kind 覆盖场景（visual_kind：code/document/ui/chat）与内容（content_kind：person/…/meme）共 14 类。
+- **UI**：设置卡片 Performance 组新增 `selectField`（visionDepth 下拉）+ `guidanceOverridesEditor`（行编辑器：类别 select + 文案 input + 移除 + 添加），zh/en 双语文案，`SELECT_KEYS` 校验。
+
+## 五、mixed 变更说明（变更前后对比）
+
+| 环节 | 变更前（1.5.3 / main） | 变更后（本分支） |
+|---|---|---|
+| bootstrap 判定 mixed 后 | 无后续处理，模型自由深挖（可能漏判/错判另一半内容） | 按 `mixed_of` 拆 ≤2 分支（`MAX_MIXED_BRANCHES=2`），各分支独立软引导；主/次按信号强度排序（ui > document > code > table > chat > general） |
+| 混合构成判定来源 | 无（schema 无此字段） | `mixed_of`：schema 枚举，视觉模型直接输出；normalizer 校验去重 + ≤2 |
+| 细分失败（mixed_of 缺失/为空） | 无细分（等同现状） | `fallback=true` **放行**（绝不硬拦，行为同现状） |
+| 分支引导 | 无 | `BRANCH_GUIDANCE`：document:code/form/table → 逐字专精；ui → detect/ground；code → 逐字；table → 结构优先；_default → 放行 |
+| 成本 | 混合图深挖轮数无上限 | ≤2 分支 = 混合图 ≤2 次识别调用（成本封顶，副产品） |
+| 判定结果消费 | 无 | `bootstrapState.mixedPlan` → followupReminder 注入分支引导文案 |
+
+原则：**精度优化**（避免漏判/错判另一半内容），成本封顶是副产品；所有分支引导都是软引导，模型保留逃生通道（软路由成立结论：不硬拦截识别方式）。
+
+## 六、判定接口（供 #142 能力路由对接参考）
+
+bootstrap 结构化输出新增两个字段，normalizer 已校验：
+
+```json
+{
+  "visual_kind": "chat|document|ui|code|general|mixed|unknown",
+  "content_kind": "person|animal|plant|food|vehicle|machine|architecture|object|scene|meme|unknown",
+  "mixed_of": ["document|ui|code|chat|general"]  // 仅 visual_kind=mixed，1-2 项
+}
+```
+
+- `content_kind` = **内容主体**（物理实体类，11 值含 unknown）；`visual_kind` = **媒介**（正交维度）。
+- `mixed_of` = **混合构成**（媒介组合，≤2），已去重排序（可交互 > 文字 > 其余）。
+- 二者都是"schema 免费收敛"产物：视觉模型 JSON 输出 + normalizer 枚举校验，无启发式。
+- 消费点：`bootstrapState.visualKind / contentKind / mixedPlan`（turn 状态），下一次 pre-step 的 followupReminder 按场景/内容/分支注入引导。
+
+## 七、默认行为与零回归
+
+| 开关 | 默认 | 关闭时行为 |
+|---|---|---|
+| `visionDepth` | `standard` | 无硬上限，仅提示词引导（与现状等价） |
+| `guidanceOverrides` | `[]` | 内置引导表（与现状等价） |
+| mixed 分路 | 随 bootstrap 自动生效 | `mixed_of` 缺失 → fallback 放行（与现状等价） |
+| `content_kind` | 新增字段 | 只影响 general 图引导（其余场景不消费） |
+
+回归门：`tests/zero-regression-gate.test.js`（含 #177 的 orderedHttpProviders 默认关断言）+ 全量 407 pass / 0 fail / 6 skipped（env 相关）。
+
+## 八、与 #142 / #177 的关系
+
+- **与 #142 正交**：#142 管"哪个能力 → 哪个后端"（谁来看）；本 PR 管"怎么看的引导"（怎么看）。判定结果（content_kind/mixed_of）可直接作为 #142 能力声明的输入（见第六节）。
+- **stacked 依赖**：本分支含 #177 的 2 个 commit（freeCloudFirst + OCR 提示词强化）。合并顺序：先 #177 后 #178，或 #178 单独 squash（内含 177）。
+
+## 九、测试
+
+- 新增 `tests/mixed-router.test.js`（13 例：normalizeMixedOf 校验/去重/封顶/排序、buildMixedBranches 去重/封顶/单分支、mixedGuidance 精确→kind→放行、planMixedBranches fallback 防呆、renderMixedGuidance 文案）。
+- 新增 `tests/depth-tier.test.js`（15 例：depthLimitFor fast/deep/standard、场景/内容引导查表与放行、renderDepthGuidance 拼接、guidanceOverrides 覆盖优先）。
+- `tests/structured-bootstrap.test.js` +29 行（content_kind/mixed_of 枚举校验）。
+- `package.json` test 脚本挂载两个新测试文件。
+
+## 十、评审与合并指南（给群主）
+
+1. 先审 #177（freeCloudFirst + OCR 提示词强化），再审本 PR；或合并时 squash。
+2. 重点看三处：`lib/mixed-router.js` 的 fallback 防呆（绝不放行变成硬拦）、`index.js` 的 `VISION_DEPTH_LIMIT` 计数（bootstrap 不计入、只数 evidence 深挖工具）、`lib/depth-guidance.js` 的 `resolveGuidance`（覆盖优先）。
+3. 判定接口（第六节）可直接对接 #142 能力声明，作者可协助整理接口说明。

package/entry.js

@@ -14,14 +14,36 @@ import { installAdversarialHardening } from './lib/adversarial-hardening.js'
 import { installLocalVisionStabilizer } from './lib/local-vision-stabilizer.js'
 import { installWrapperDirectoryAlias } from './lib/wrapper-directory.js'
 import { installAndroidAttachmentCompat } from './lib/android-attachment-compat.js'
+import { contextWithCoalescedAdapterUpdates } from './lib/adapter-update-coalescer.js'
+import { installTesseractExecFileCompat } from './lib/tesseract-exec-compat.js'
+import {
+  installStructuredFlowHardening,
+  normalizeGuidanceOverrides,
+} from './lib/structured-flow-hardening.js'
+import {
+  attachmentContextForContract,
+  installRc7SettingsCompatibility,
+  isRc7ContractRuntime,
+  protectRc7ProviderOwnership,
+} from './lib/dsh-contract-compat.js'
 
 // Schemastery object schemas expose set() as the supported way to replace a
 // field schema. This mutates the Config object that index.js itself later uses
 // for the settings namespace, so composition config and settings validation
 // agree on the same default.
 core.Config.set('progressiveTools', z.boolean().default(false))
+// Structured 1+x now also has a turn-level wall-clock budget. Individual
+// visionTaskTimeoutMs budgets remain unchanged; this one prevents a deep turn
+// from multiplying them into several minutes of serial waiting.
+core.Config.set('visionTurnBudgetMs', z.number().step(1000).min(10000).max(600000).default(90000))
 
 export * from './index.js'
+export {
+  attachmentContextForContract,
+  installRc7SettingsCompatibility,
+  isRc7ContractRuntime,
+  protectRc7ProviderOwnership,
+} from './lib/dsh-contract-compat.js'
 export const Config = core.Config
 
 // Defense in depth for direct/programmatic callers that invoke apply() without
@@ -58,11 +80,47 @@ export function apply(ctx, config = {}) {
     hardenedConfig,
     core,
   )
-  // #182: Android/Termux cannot open /data/data for the attachment-local
-  // durability walk. Keep this workaround private to Vision Router so the
-  // host attachment service and every non-Android runtime retain their normal
-  // semantics. Once DSH accepts the save, the compatibility path is inert.
-  const attachmentCompatCtx = installAndroidAttachmentCompat(stabilizedCtx, logging.logger)
+  const runtimeConfig = {
+    ...bootConfig,
+    progressiveTools: hardenedConfig.progressiveTools === true,
+    guidanceOverrides: normalizeGuidanceOverrides(bootConfig.guidanceOverrides ?? hardenedConfig.guidanceOverrides),
+    visionTurnBudgetMs:
+      Number.isFinite(Number(bootConfig.visionTurnBudgetMs))
+        ? Number(bootConfig.visionTurnBudgetMs)
+        : 90000,
+  }
+  const rc7 = isRc7ContractRuntime(stabilizedCtx)
+  const ownershipCtx = rc7 ? protectRc7ProviderOwnership(stabilizedCtx) : stabilizedCtx
+  const settingsCtx = rc7
+    ? installRc7SettingsCompatibility(ownershipCtx, { ...runtimeConfig, stealth: false }, {
+        namespace: 'vision-router',
+        Config: core.Config,
+      })
+    : ownershipCtx
+  // rc.6/Termux keeps the narrow process-local fallback that was required by
+  // the old attachment-local durability walk. rc.7 formalizes AttachmentId as
+  // store-owned, so never synthesize one there: host persistence errors remain
+  // authoritative and diagnosable instead of creating a false durable ref.
+  const attachmentCompatCtx = attachmentContextForContract(settingsCtx, logging.logger, {
+    installAndroidAttachmentCompat,
+  })
+  // Final structured-flow guard sits closest to core.apply so it sees the
+  // actual tool registrations and pre-step listener. It makes bootstrap
+  // one-shot, enforces fast/standard/deep quotas, tracks mixed branches,
+  // rejects empty/non-evidence results, and applies one shared turn deadline.
+  const structuredCtx = installStructuredFlowHardening(attachmentCompatCtx, runtimeConfig)
+  // DSH rc.7 publishes llm/adapters-updated synchronously from inside
+  // registerAdapter(). Coalesce only Vision Router's listener: nested events
+  // mark the topology dirty and the outer pass reruns to a fixed point, so we
+  // neither double-register a twin nor lose a provider added mid-pass.
+  const reconciledCtx = contextWithCoalescedAdapterUpdates(structuredCtx)
+  // index.js historically passes image bytes as `options.input` to the async
+  // execFile API. That option is not fed into child stdin, so Tesseract waits
+  // for data until the OCR slice expires. Materialize only this exact
+  // Tesseract-stdin call to a temporary image file; all other execFile calls
+  // keep their native behavior.
+  installTesseractExecFileCompat(reconciledCtx)
+
   // 启动诊断摘要只描述 composition/apply 的基础配置。设置服务可能稍后
   // 覆盖这些值；每个图片轮还会记录 current() 的实时决策，避免把这个
   // 启动快照误当成最终设置状态。
@@ -71,7 +129,8 @@ export function apply(ctx, config = {}) {
     const local = c.localOllama && typeof c.localOllama === 'object' ? c.localOllama : {}
     const lms = c.localLmStudio && typeof c.localLmStudio === 'object' ? c.localLmStudio : {}
     logging.logger.info(
-      'vision-router: base config summary — instantDescribe=%s localDescribeStyle=%s localOllama=%s localLmStudio=%s',
+      'vision-router: base config summary — contract=%s instantDescribe=%s localDescribeStyle=%s localOllama=%s localLmStudio=%s',
+      rc7 ? 'rc7' : 'rc6',
       c.instantDescribe === true ? 'on' : 'off',
       c.localDescribeStyle === 'structured' ? 'structured' : 'plain',
       local.enabled === true ? 'on' : 'off',
@@ -81,16 +140,12 @@ export function apply(ctx, config = {}) {
     /* diagnostics must never break apply */
   }
   try {
-    const runtimeConfig = {
-      ...bootConfig,
-      progressiveTools: hardenedConfig.progressiveTools === true,
-    }
-    const result = core.apply(attachmentCompatCtx, runtimeConfig)
+    const result = core.apply(reconciledCtx, runtimeConfig)
     // DSH rc.7's Settings -> Models surface is backed by the configurable
     // provider directory, not by the live adapter registry alone. Publish the
     // main DeepSeek + 自动识图 route as a derived alias of official DeepSeek so
     // a reinstall restores the expected model-group row without making an
-    // arbitrary textProvider look like DeepSeek.
+    // arbitrary textProvider look like DeepSeek. On rc.6 the helper is inert.
     installWrapperDirectoryAlias(attachmentCompatCtx, runtimeConfig, logging.logger)
     if (result && typeof result.then === 'function') {
       return result.catch((error) => {