@mokuyoaxis/dsh-iris 0.1.4 → 0.2.1

package/docs/HOST_ADAPTER_CONTRACT.md

@@ -1,12 +1,12 @@
 # Host Adapter v0 契约
 
-状态：**v0.1.4 内部契约与渐进迁移已完成，并通过真实 DSH 隔离 canary。** 本文固定真实消费者所需的最小边界；不宣称已经提供独立 Core、公开 Host SDK 或完整 Local Host。
+状态：**v0.1.4 内部契约与渐进迁移已完成，并通过真实 DSH 隔离 canary。** 本文固定真实消费者所需的最小边界；0.2.1 已提供独立 Core/CLI，但未冻结公开 Host SDK，也未实现完整 Local Host。
 
 ## 目标
 
 Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、会话、浏览器和模型能力映射为 Iris 端口。Command 接收 Iris 输入、`AbortSignal` 和所声明的 Host Port，**不得接收原始 `ctx`**。Task、Provider、文件持久化和成本语义不属于宿主。
 
-契约版本固定为 `0`。它在 0.1.x 内仍是内部接口；只有经过 DSH 与 Local Host 两个真实消费者验证后，才考虑成为公开 SDK。
+契约版本固定为 `0`。它仍是内部接口；只有经过 DSH 与 Local Host 两个真实消费者验证后，才考虑成为公开 SDK。
 
 ## 端口清单
 
@@ -29,7 +29,7 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 | Command/入口 | 必需端口 | 可选端口 | 说明 |
 |---|---|---|---|
 | `image` | 无 | `visionModel` | 生成与 Task 不依赖宿主；成功后的简短视觉描述可以降级 |
-| `video`、`tts`、`transcribe` | 无 | 无 | Provider、Task 与产物落盘属于 Iris Core 候选 |
+| `video`、`tts`、`transcribe` | 无 | 无 | Provider、Task 与产物落盘属于 Iris Core |
 | `look`、`locate`、`ocr` | 无 | `visionModel` | 优先使用 Iris Provider；没有任何视觉后端才失败 |
 | `crop`、`diff`、`video_frames` | 无 | 无 | 确定性本地动作 |
 | `media_summarize` | 无 | `visionModel` | 帧提取是本地动作，理解阶段允许宿主视觉降级 |
@@ -45,9 +45,9 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 
 ## 不可违反规则
 
-1. Core 候选、Command、Task 和 Provider 模块不得导入 DSH/Cordis 运行时，也不得通过任意字段重新取得原始 `ctx`。
+1. Core、Command、Task 和 Provider 模块不得导入 DSH/Cordis 运行时，也不得通过任意字段重新取得原始 `ctx`。
 2. Host Adapter 只能映射宿主能力；不得复制业务校验、Provider 路由、Task 状态机、failover 或产物持久化。
-3. 宿主会话 ID 只能作为来源上下文，不能成为 Iris Task、Attempt 或未来 Artifact 的主键。
+3. 宿主会话 ID 只能作为来源上下文，不能成为 Iris Task、Attempt 或 Artifact 的主键。
 4. Command 输入和结果只能包含 JSON、字节、稳定引用与受控错误；不得持久化 page、session、service 等 live Host 对象。
 5. 能力探测必须显式、可序列化且零计费。缺能力返回稳定分类和可执行说明，不得用异常吞噬后继续猜测私有 API。
 6. 调用方的 `AbortSignal` 必须传播到 Host 操作；断开、取消和超时不得被 Adapter 转换为自动重试。
@@ -68,19 +68,38 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 
 `lib/host-runtime.js` 另记 Iris 自身成功完成的工具、Skill 和路由注册，以及客户端版本/Slot 握手；它不保存 `ctx`、service、会话、附件或密钥。
 
-## 0.1.4 实现顺序
+## DSH 装载与版本变化
 
-1. 以本契约和测试冻结名称、依赖方向与错误分类。
-2. 提供 test-only Local Host fixture，先运行本地确定性动作、任务查询与确认流程。（已完成；不等同于 standalone Host。）
-3. 从 `actions.js` 的真实消费者逐项替换 `ctx.get()`，不一次性搬迁全部目录。（已完成服务端消费者迁移；lint 禁止重新扩散。）
-4. 将 DSH 工具、路由、附件、会话、Browser、模型和 Skill 映射集中进 DSH Adapter。（已完成；客户端 Slot 使用 client bundle 内的最小 adapter。）
-5. Host Doctor 消费同一能力快照、成功注册账本与受限客户端握手，验证真实 DSH profile 的服务端与客户端装载。（已完成；见 [Host Doctor](HOST_DOCTOR.md)。）
+Iris 继续作为普通 DSH/Cordis 插件装载：`cordis.patch.yml` 只把 npm 包入口 `lib/index.js` 挂入宿主。该入口可以依赖 Core，但 Core Runtime 必须能在 DSH/Cordis 完全不可解析时独立装载。拆 Core 不会要求用户在 DSH 外另起守护进程，也不会取消工作台、Agent 工具或 🫧 入口。
 
-Local Host fixture 不能假装拥有 Browser、会话或附件能力；需要什么就显式注入什么，缺失路径也必须纳入测试。
+兼容规则：
 
-## 非目标
+1. DSH 原始 `ctx` 只允许存在于 `lib/index.js`、`lib/dsh-host-adapter.js` 和客户端 Slot 边界；任务、Provider、Artifact 与 Command 不感知其形状。
+2. 工具、Skill、路由、附件、Browser、模型和客户端 Slot 分别探测、分别注册、分别诊断。单个端口失败只能降级对应体验，不能改变 Core Task/Artifact 事实。
+3. 不把所有功能押在单个便利 RPC 或私有服务上。当前 Iris Web 数据通路使用宿主公开的 prefix route + 普通 `fetch`，不调用 `connection.rpc.handle()`；这只是当前适配实现，不是永久绑定承诺。
+4. DSH Doctor 必须区分 loader、服务端端口、路由、工具/Skill 账本、客户端 bundle 与 Slot 握手；“Core 可运行但 DSH 投影失败”必须成为可识别结果。
+5. 兼容范围只按真实版本/commit canary 声明，不使用宽泛 semver 猜测未来预览版。上游破坏时先修改 DSH Adapter 与 fixture，不迁移或重写 Core 数据。
+6. 若 DSH 原生吸收某项同类功能，不自动删除 Iris 能力。只有公开契约在语义、安全和生命周期上等价并有版本化测试时，Adapter 才可选择委托；否则继续使用 Iris Core 实现。
 
-- 0.1.4 不拆分 npm 多包，不发布第三方 Host SDK。
-- 不启动 standalone 服务，不复制 DSH 聊天界面。
-- 不实现 Artifact Manifest、Recipe/Flow 或完整 headless 命令集。
-- 不新增 Gemini、Fal、Replicate，也不为尚无消费者的能力预建端口。
+## 当前覆盖
+
+- `lib/index.js` 负责 DSH 插件入口、生命周期和工具注册；
+- `lib/dsh-host-adapter.js` 映射九类命名端口；
+- Local Host fixture 覆盖 crop/diff、Task 查询与提醒操作，并验证缺失能力的错误；
+- Host Doctor 对服务端注册账本、客户端版本和 Slot 握手分别给出结果；
+- 已发布 Iris `0.1.4` 在 DSH `0.1.2-rc.1` 与 `0.1.5-rc.1` 上有历史宿主验证记录，不继承为当前版本的支持声明。
+- Iris `0.2.1` 只声明 DSH `0.2.0-rc.2`，已通过真实安装服务隔离验收，保留附件完整引用、绑定明确图片模型路由并适配客户端主视图选择；边界与尚未完成的浏览器实机检查见 [rc.2 适配说明](DSH_RC2_ADAPTATION.md)。
+
+Local Host 不模拟 Browser、会话或附件。测试需要这些能力时必须显式注入，缺失行为也属于契约。
+
+## Text/Vision 共享契约
+
+[Text/Vision Model Port v0](MODEL_PORT_CONTRACT.md) 已实现独立纯契约、调用控制与 test-only Fake Port，不替换本契约已有的 `textModel.stream()` / `visionModel.analyze()` 方法。0.2.1 已由 DSH 模型适配器把 Host 能力映射为共享 `complete()`：解析原始流和正常终态、传递取消、桥接同一张图片，并隔离 Host 引用与会话上下文。
+
+普通能力快照仍为零模型调用。显式视觉实测属于可能计费的模型操作，不能用于 `describe()` 或自动 Doctor；缺图片桥接时必须在模型调用前失败。共享端口已被视觉、OCR、定位、摘要与提示词预览消费；它不代表 Host Adapter v0 已升级或公开 SDK 已冻结。
+
+## 范围
+
+- Host Adapter v0 仍是内部接口，不是第三方 SDK；
+- DSH 插件不启动 standalone 服务，也不复制聊天界面；
+- Artifact Manifest、Recipe/Flow 和新 Provider 不属于本契约。

package/docs/HOST_DOCTOR.md

@@ -5,7 +5,7 @@ Host Doctor 是 Iris 在运行中的 DSH 实例内提供的兼容性诊断。它
 | 模式 | 入口 | 观察范围 |
 |---|---|---|
 | `offline` | `dsh-iris doctor [--json]` | Node、依赖、私有存储、配置、Task 与产物；不要求 DSH |
-| `host` | 已认证 DSH 中的 `GET /iris/api/doctor` | DSH 版本和 Host Port、插件装载、14 个工具、2 项 Skill、4 组路由、Browser/附件/模型能力、客户端版本与 4 个 UI Slot |
+| `host` | 已认证 DSH 中的 `GET /iris/api/doctor` | DSH 版本和 Host Port、插件装载、当前工具（0.2.1为 15 个）、2 项 Skill、4 组路由、Browser/附件/模型能力、客户端版本与 4 个 UI Slot |
 
 两种模式都默认零网络、零计费。Host Doctor 不调用任何 Host Port，不打开 Browser，不读取附件或会话，不调用文本/视觉模型，也不向 Provider 发送请求。它只读取：
 
@@ -29,12 +29,14 @@ Host Doctor 是 Iris 在运行中的 DSH 实例内提供的兼容性诊断。它
 
 如果刚安装、热更新或强制刷新，先等 Web 页面完成装载，再刷新诊断。未收到客户端握手时，Host Doctor 只报告警告，不会把“服务端已装载”冒充成“UI 已装载”。
 
+Iris `0.2.x` 仅支持 DSH `0.2.0-rc.2`，版本检查与 package 的 DSH engines 一致。旧 DSH `0.1.2` 线或 `0.1.5-rc.1` 返回版本错误，并提示使用历史稳定包 `@mokuyoaxis/dsh-iris@0.1.4`；旧版 Doctor 的支持范围不继承到当前版本。无 DSH 的 CLI/离线诊断不受此宿主限制。
+
 ## 运行时证据
 
 服务端只登记成功完成的注册：
 
 - 插件身份与 npm 版本；
-- 14 个 Iris Agent 工具名；
+- Iris Agent 工具名（0.2.1包含 `iris_edit_image`，共 15 个）；
 - `iris-verify-ui`、`iris-compose-media`；
 - `/iris/media`、`/iris/api`、`/iris/api/actions`、`/iris/render` 四组逻辑路由。
 

package/docs/MODEL_PORT_CONTRACT.md

@@ -0,0 +1,305 @@
+# Text/Vision Model Port v0 契约设计
+
+状态：**Iris 0.2.1。** 0.2.0 已包含 M1 契约；0.2.1 接入 DSH 文本适配器与共享优化消费者、HTTP/DSH Vision Port，以及 look/relook、OCR、定位、拼图摘要和图片自述。端口仍为内部契约，不增加公开 export 或生产依赖，不改变 [Host Adapter v0](HOST_ADAPTER_CONTRACT.md) 的现有方法。新增按次规则与 UI 见 [提示词优化系统](PROMPT_OPTIMIZER.md)，单图预算与宿主附件副作用见 [单图视觉调用](VISION_MODEL.md)，复合操作见 [长图 OCR](OCR_MODEL.md) 和 [定位与摘要](COMPOSITE_VISION.md)。
+
+0.2.1 还提供 [视觉 CLI](VISION_CLI.md)、可选账号/模型 `visionInput` 和设置命令，见 [看图输入预算](CLI_MANAGEMENT.md#看图输入预算)；不改变请求/完成 DTO、契约版本或公开 exports。该设置用于看图、OCR 分块、定位和聊天改图的发送副本，不是供应商能力上限声明；聊天改图的媒体任务语义仍由 Core Runner 管理。
+
+## 目标与范围
+
+共享层负责一次文本或视觉调用的输入校验、预算、取消、完整结果与安全错误。DSH 与自持 Provider 只适配协议；提示词优化、看图、定位、OCR 和媒体摘要消费同一调用语义。
+
+v0 只支持单轮、无工具的完整文本结果。视觉请求携带一张图片；多帧摘要先由业务层制作一张 contact sheet。会话历史、工具调用、音频、视频、实时流式 UI 与结构化输出协议留到后续单独设计。定位的 bbox JSON 和 OCR 的分块结果仍由对应业务模块解析，不成为通用模型端口的数据结构。
+
+这些操作不属于媒体生成 Task：端口不创建 Task/Attempt/Artifact，不占 Core writer 租约，不接入 Provider Task Runner。后续若需要保存文字结果，应另行通过显式 Command 设计产物交付。
+
+```mermaid
+flowchart TD
+  DSH[DSH 工具 / 工作台] --> DB[DSH 边界：模型选择与附件解析]
+  LOCAL[后续独立入口 / 离线 fixture] --> LB[显式配置与图片字节]
+  DB --> OPS[共享业务：优化 / 看图 / 定位 / OCR / 摘要]
+  LB --> OPS
+  OPS --> INV[调用控制：预算 / 取消 / 完整结果 / 错误]
+  INV --> TEXT[TextModelPort v0]
+  INV --> VISION[VisionModelPort v0]
+  TEXT --> DA[DSH 模型适配器]
+  VISION --> DA
+  VISION --> PA[自持 Provider 模型适配器]
+  TEXT --> FA[Fake Model Port]
+  VISION --> FA
+```
+
+图中是目标结构。独立文本 Provider 与新 Headless 命令不在本轮范围；当前自持 Provider 目录尚无 `text` 能力。
+
+## 职责归属
+
+| 层 | 拥有的职责 | 交给下一层的输入 |
+|---|---|---|
+| 入口 / Host 边界 | 读取配置、固定或会话/默认模型选择、解析附件与文件、预览和写回草稿 | 已绑定端口、文字、图片字节、预算、取消信号 |
+| 共享业务 | 模板、目标类型、bbox 解析、OCR 分块、contact sheet、操作整体调用预算 | 单轮请求与单次调用预算 |
+| 共享调用控制 | 通用校验、deadline、结果验证、安全错误、显式候选策略 | 已验证请求与合成信号 |
+| 模型适配器 | 凭据和端点闭包、请求映射、底层流聚合、终态识别、资源清理 | 完整文本或稳定错误 |
+| Host 投影 | 附件、工具输出、健康反馈、UI 文案 | 对用户有用的结果 |
+
+共享模块不得导入 DSH/Cordis、`config-store.js`、Host Runtime 或 Store，不读取环境配置，不取得原始 `ctx`。DSH 模型适配器只接收已探测的 Host Port；原始 DSH 对象仍封闭在已有 Host Adapter 与插件装配边界。
+
+## 端口与版本
+
+两种端口均提供同步、纯读取的 `describe()` 与异步 `complete(request, options)`。v0 不向消费者暴露原始事件流；适配器可以在内部使用流，并在收到正常终态后返回完整结果。
+
+以下 TypeScript 描述内部契约形状，不是已发布类型声明：
+
+```ts
+type Support = 'supported' | 'unsupported' | 'unknown';
+
+type ModelIdentity =
+  | { origin: 'provider'; backendId: string; providerId: string; modelId: string }
+  | { origin: 'host'; backendId: string; providerId?: string; modelId?: string };
+
+type ModelDescriptor = {
+  contractVersion: 0;
+  kind: 'text' | 'vision';
+  identity: ModelIdentity;
+  availability: 'available' | 'unavailable' | 'incompatible';
+  reasonCode?: string;
+  features: {
+    system: Support;
+    temperature: Support;
+    maxOutputTokens: Support;
+    reasoning: Support;
+  };
+  reasoning?: { off: Support; effortIds?: string[] };
+  image?: { mediaTypes?: string[]; maxBytes?: number };
+};
+
+type Reasoning =
+  | { mode: 'provider-default' }
+  | { mode: 'off' }
+  | { mode: 'effort'; effortId: string };
+
+type TextRequest = {
+  prompt: string;
+  system?: string;
+  generation?: {
+    temperature?: number;
+    maxOutputTokens?: number;
+    reasoning?: Reasoning;
+  };
+};
+
+type VisionRequest = TextRequest & {
+  image: { bytes: Uint8Array; mediaType: string };
+};
+
+type TextCallOptions = {
+  signal?: AbortSignal;
+  budget: {
+    timeoutMs: number;
+    maxInputTextBytes: number;
+    maxOutputChars: number;
+  };
+};
+
+type VisionCallOptions = {
+  signal?: AbortSignal;
+  budget: TextCallOptions['budget'] & { maxImageBytes: number };
+};
+
+type ModelCompletion = {
+  contractVersion: 0;
+  text: string;
+  finishReason: 'stop';
+  identity: ModelIdentity;
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    reasoningTokens?: number;
+  };
+};
+
+interface TextModelPort {
+  describe(): ModelDescriptor & { kind: 'text' };
+  complete(request: TextRequest, options: TextCallOptions): Promise<ModelCompletion>;
+}
+
+interface VisionModelPort {
+  describe(): ModelDescriptor & { kind: 'vision' };
+  complete(request: VisionRequest, options: VisionCallOptions): Promise<ModelCompletion>;
+}
+```
+
+契约版本独立于 Host Adapter 版本。`lib/model-port-contract.js` 验证端口、请求、描述与结果；未知字段、错误类型或不兼容版本应明确拒绝。端口是只包含 `describe` / `complete` 的方法对象；DTO 拒绝额外字段、accessor 和非普通对象原型。能力列表只接受密集的自有数据元素，不读取元素 getter、不调用自定义 iterator。标识长度最多 256 code units，命名空间化 `backendId` 最多 512，组件需使用安全字符或百分号编码。描述与结果中的对象只包含安全 DTO；端口方法与 `AbortSignal` 不可序列化，也不进入任何记录。
+
+`describe()` 只读取已绑定或缓存的事实，返回独立、可序列化的快照；不得联网、调用模型、保存附件、探测账号或写健康状态。未知能力保留 `unknown`，不能猜测为 supported 或 unsupported。`reasonCode` 是受控诊断码，不透传供应商异常原文。
+
+## 模型绑定与能力
+
+端口在一次业务操作开始时绑定后端。`backendId` 使用命名空间，例如 `iris-provider:<id>`、`dsh-text:<id>`、`dsh-vision:default`；DSH 的 provider/model ID 与 Iris 的 `providerId::modelId` 是不同命名空间，不能互相猜测转换。
+
+自持 Provider 必须有明确的 Provider 与模型身份。DSH 固定选择或可解析的当前选择应记录已知身份；全局视觉默认模型若无法解析，只声明 Host 后端，省略未知 `providerId`/`modelId`。不得用文本默认模型冒充视觉模型，也不得承诺宿主内部动态路由每次选到相同物理模型。
+
+`availability=available` 表示本地依赖与协议形状可调用，不表示凭据有效、模型具备看图能力或远端一定成功。真实视觉实测仍是显式模型调用，可能产生费用；它使用同一预算与取消机制。普通 describe/Doctor 不做该实测。
+
+`kind='text'|'vision'` 是共享端口的调用类型，不是新增持久 Provider 能力标签。当前目录只声明媒体生成、转写和视觉能力；不能从模型名或 `vision` 标签推导 `text`。首个文本消费者使用 DSH 或显式注入的 Fake Text Port。增加自持文本目录、配置或 CLI 选择能力应另行审查，不在迁移中顺带改写现有配置。
+
+## 输入与生成控制
+
+- `prompt` 必须是非空字符串，`system` 若提供也必须非空；用 trim 判断空白，但端口不改写原文。业务层负责当前功能已有的修剪、JSON 数据包装与模板选择。
+- 文本大小按 `prompt` 与 `system` 的 UTF-8 字节总和检查。`maxOutputChars` 按 JS 字符串长度（UTF-16 code unit）计算，与当前提示词优化器一致；不能按 token 数替代。
+- 视觉输入必须是非空字节和规范化 MIME，不接受路径、URL、data URL、Artifact ID 或 DSH attachment/session 对象。入口解引用并解码；业务层制作的 OCR 分块或 contact sheet 也以字节传入。
+- v0 图片 MIME 范围为 `image/png`、`image/jpeg`、`image/webp`、`image/gif`；适配器可以声明更小范围。声明限制与调用预算取更严格者。未知远端限制不伪造数值；格式不支持要返回稳定错误，不能丢掉图片继续纯文本调用。
+- 字节在调用期间只读，消费者不得复用后修改；适配器若异步保留或转码，需持有安全副本。图片来源和宿主引用留在入口，不进入通用错误或结果。
+- 预算必须显式传入；时间、文本、图片和输出上限均为正的有限安全整数。超限在模型调用前拒绝，输出超限在读取过程中中止；不能截取前若干字再返回成功。
+- `temperature` 为有限非负数，具体范围由绑定协议校验；`maxOutputTokens` 为正安全整数。不支持的显式参数在调用前拒绝；未知能力不能静默丢弃参数，必须由已验证协议映射，否则返回 unsupported。
+- `reasoning` 缺省等于 `provider-default`；`off` 必须有明确的关闭能力，`effort` 必须在已声明 effort 列表中。适配器不推测厂商字段，也不把思考正文作为结果文本。
+
+提示词优化的 `off-if-supported` 与 `inherit` 是业务策略，不成为通用请求字段：前者在已知支持关闭时映射为 `off`，否则 `provider-default`；后者只继承入口明确选择的 effort。当前 `off/none/disabled/disable/no-thinking` 等供应商元数据只在 DSH 适配边界归一化。模型元数据解析使用操作信号与总 deadline，不在 `describe()` 中触发网络查询。
+
+迁移保留已有业务预算：提示词草稿 32 KiB、输出 16,000 code units、默认 45 秒与 1,200 输出 token，原配置范围不变。草稿上限仍在业务层校验；端口的总文本上限需按草稿上限、JSON 转义的最坏增长与已验证模板上限计算，不能把带模板的整个请求限制为 32 KiB，导致原本合法的草稿被拒绝。
+
+视觉 M3 沿用 120 秒默认档，原 6,000 字限制改为超限失败；输入文字 32 KiB UTF-8，图片 20 MiB。其他入口需明确其文字/图片上限，不直接套用生成任务参数校验。v0 不为预算增加持久配置格式。0.2.1 的 M2 已将元数据未知时的显式 effort 从直接透传收紧为生成前拒绝，覆盖配置与 inherit；默认 off-if-supported 保留供应商默认回退，不能声称所有行为完全未变。
+
+## 完整结果与底层流
+
+成功只返回 `finishReason='stop'` 且 trim 后非空的完整正文。端口保留正文原样，业务层决定展示或解析时是否 trim；结果身份来自本次真实绑定或明确的 Host 不透明后端。
+
+正文按本次请求返回调用方，可能复述用户输入，例如优化后的提示词或 OCR 文字；这是显式结果，不是诊断字段。共享层不自动记录输入/正文，也不把它们复制到能力快照、错误、健康元数据或 Core 记录。
+
+适配器必须处理底层完整性：
+
+1. 正常结束原因需有已验证语义。SSE `[DONE]`、EOF、退出迭代或已经读到文字均不能单独证明正常完成；非流式协议需确认完整响应与终态。
+2. DSH `text-delta` 聚合为正文；`block-end` 的完整文本替换同一块的累积值，不能再追加导致重复。旧 `delta` 只有在同一协议存在可验证终态时才兼容。
+3. `length/max-tokens`、本地输出上限、工具调用、内容阻断、未知终态、解析失败、流中断和流错误均拒绝成功，即使已读到部分正文。不得把 partial text 伪装成完成结果。
+4. 不返回原始块、事件、thinking、工具参数、HTTP headers/body 或 Host live object。底层 cleanup 后才能完成正常调用；取消路径按下一节处理。
+5. usage 只填供应商实际提供且语义已知的非负安全整数；未知字段省略，不能补零、推算 token 或把思考 token 重复加到总数。
+
+现有 `adapters.visionStream()` 与 Host `visionModel.analyze()` 只返回字符串，不足以证明正常结束；实现时必须增强协议读取，不能仅套一层 wrapper 就宣称符合 v0。缺少终态的既有 SSE fixture 也需要改为真实协议形状。
+
+## 取消、超时与调用次数
+
+一次 `complete()` 最多调用一次上游模型生成入口，不自动重试或切换后端。DSH 内部的调度/重试事实未知时应如实说明；“调用 Host 一次”不等于已证明远端绝对只执行一次。
+
+调用前先检查取消；已取消时零图片准备、零模型调用。调用期间的合成信号覆盖图片桥接、HTTP/Host 请求与流读取，deadline 从调用开始计时。成功返回前再次检查信号；已经取消或超时的晚到结果不能覆盖错误。
+
+取消时向底层传递 abort，结束流迭代、释放 reader，移除监听器并清理 timer。超时也必须触发 abort；不能只用 `Promise.race` 返回超时而放任底层继续。本地应在 deadline 后有界退出；若第三方不响应信号，则丢弃晚到结果、处理晚到拒绝并报告本地取消，不宣称远端执行或计费已经停止。没有可验证信号传递/流清理路径的适配器不能标为符合 v0。
+
+业务操作另有整体预算 `{ timeoutMs, maxInvocations }`，两者均为正的有限安全整数；该预算属于共享调用控制，不作为额外字段传给模型端口。整体 deadline 覆盖路由解析、图片处理、OCR 所有块及候选切换。每次调用只能消费剩余时间与次数，不能为每一块重置总预算。取消/超时立即停止整次操作；OCR 不得把它记录成普通失败块后继续请求后续图片。
+
+看图或提示词优化等单次业务默认 `maxInvocations=1`；OCR 应按已规划的块数设置有限基础预算，若允许候选切换，再显式给出总调用上限与整体 deadline，不沿用单次调用的默认次数。保留视觉有序候选时，由共享调用策略显式给出候选、总次数和允许的错误条件：
+
+| 上次结果 | 可否进入下一候选 |
+|---|---|
+| 本地校验错误、取消、超时 | 停止；不能通过换模型掩盖请求问题或取消 |
+| 能力缺失/不兼容/不支持且 `not_invoked` | 显式策略可跳过，无模型调用 |
+| 明确认证、限额或速率拒绝且 `rejected` | 显式策略可继续；仍计入调用次数 |
+| 正常结束但正文为空且 `responded` | 仅策略明确允许时继续；前次可能已计费 |
+| 已读部分正文、截断、工具调用、内容阻断、协议错误或调用事实未知 | 停止，不自动重提 |
+
+`maxInvocations` 统计实际进入上游生成入口的次数；跳过不可用候选不消耗次数，但候选表必须有限。适配器没有自己的候选列表。此处是文本/视觉调用策略，不借用媒体 Task 的 `accepted/not_accepted`，也不把错误分类当作免费调用证明。
+
+整体调用次数用尽后不得进入下一次生成，返回 `IRIS_MODEL_CALL_LIMIT`；OCR 可以在业务层将此前成功块投影为明确的 partial 结果，但不能宣称全部完成。取消或超时仍立即终止操作，不通过 partial 结果隐藏。
+
+## 错误契约
+
+错误使用 `ModelPortError`，只暴露受控字段：
+
+```ts
+type ModelPortErrorRecord = {
+  code: string;
+  message: string;  // 固定或经过白名单映射的安全说明
+  stage: 'validate' | 'prepare' | 'invoke' | 'read' | 'normalize';
+  invocation: 'not_invoked' | 'rejected' | 'responded' | 'unknown';
+  backendId?: string;
+  status?: number;  // 已验证的 HTTP 状态码；未知时省略
+  imageBytes?: number;  // 看图大小拒绝：实际发送图片字节数
+  imageMaxBytes?: number;  // 已验证的上限；未知时省略
+};
+```
+
+| code | 含义 |
+|---|---|
+| `IRIS_MODEL_INPUT_INVALID` | 字段、类型、预算或输入大小非法 |
+| `IRIS_MODEL_IMAGE_TOO_LARGE` | 看图副本无法满足预算，或上游明确拒绝图片大小；安全数值生成说明，不返回原文 |
+| `IRIS_MODEL_UNAVAILABLE` | 未配置或缺失依赖/Host 图片桥接能力 |
+| `IRIS_MODEL_INCOMPATIBLE` | 端口版本或底层协议形状不兼容 |
+| `IRIS_MODEL_UNSUPPORTED` | 当前模型/协议不支持显式输入或生成参数 |
+| `IRIS_MODEL_AUTH_FAILED` | 明确认证或权限拒绝 |
+| `IRIS_MODEL_RATE_LIMITED` | 明确速率或额度限制 |
+| `IRIS_MODEL_REQUEST_FAILED` | 其他请求失败；网络异常不推定未调用 |
+| `IRIS_MODEL_PROTOCOL_INVALID` | 无法解释的响应/事件/终态 |
+| `IRIS_MODEL_INCOMPLETE` | 流结束但缺少可验证的正常终态 |
+| `IRIS_MODEL_OUTPUT_LIMIT` | 本地输出超限或远端 token 截断 |
+| `IRIS_MODEL_CALL_LIMIT` | 操作整体生成调用次数已用尽 |
+| `IRIS_MODEL_EMPTY_RESULT` | 正常结束但正文为空 |
+| `IRIS_MODEL_UNEXPECTED_TOOL` | 收到工具调用或工具结束原因 |
+| `IRIS_MODEL_CONTENT_BLOCKED` | 明确内容阻断/拒答终态 |
+| `IRIS_MODEL_ABORTED` | 调用方或上层操作取消 |
+| `IRIS_MODEL_TIMEOUT` | 单次或整体 deadline 到期 |
+
+`invocation` 只描述本地可确认的调用事实：未进入生成入口为 `not_invoked`；上游明确拒绝为 `rejected`；收到有效生成内容/终态为 `responded`；进入入口但无法确认结果为 `unknown`。网络失败、在途取消和超时不能回写为 `not_invoked`。收到部分正文后中断仍为 `responded`，但调用失败。它不是账单事实或持久 Task 状态。
+
+不提供通用 `retryable` 布尔值。是否切换候选由上述策略同时检查 code 与 invocation；同一个错误码可发生于不同调用阶段。
+
+安全错误不包含 Prompt、图片、凭据、端点、签名 URL、会话/附件标识、绝对路径或原始异常 cause。上层可给出预算数值等安全上下文，但不能直接拼接供应商错误原文。`ModelPortError` 不复用依赖 Task 受理/持久化语义的 Provider Error Record。
+
+## DSH 图片与结果桥接
+
+DSH 视觉适配器通过 Attachments Port 桥接共享请求中的图片，模型必须收到同一张图或经核验的宿主规范化副本：
+
+1. 已验证 DSH 支持内联图片时，在适配边界转换字节；
+2. 否则使用 Attachments Port 保存输入字节，取得 Host 引用，再调用 Host 模型；若宿主规范化图片，须核验实际 MIME、尺寸、字节数和来源引用，该步骤受同一信号、deadline 与图片预算约束；
+3. 若两者都不可用，调用模型前返回 `IRIS_MODEL_UNAVAILABLE`，禁止退化成只有问题的纯文本请求。
+
+Host 引用、session ID 与 source metadata 可存在于 DSH 适配器闭包，但不能进入共享请求、结果或诊断快照。桥接不得创建 Core Artifact；宿主是否持久保存附件需在实现与 canary 中明确记录，不能把这条路径称为完全零副作用。
+
+提示词优化仍由 DSH 边界读取 v1 配置、解析固定/会话/默认模型，返回选择来源供 UI 展示。共享核心只接收选定端口与模板；保留原草稿、预览后写回和不携带会话历史的行为。Provider 健康反馈由入口消费安全结果/错误，模型端口不导入健康 Store。
+
+## 实现切片与退出条件
+
+0.2.0 包含 M1；0.2.1 包含 M2/M3/M4 和 M5 独立视觉 CLI，详见 [视觉 CLI](VISION_CLI.md)；提示词优化后续由用户另行安排。
+
+| 切片 | 范围 | 退出条件 |
+|---|---|---|
+| M1：纯契约与调用控制（已实现） | `model-port-contract.js`、`model-invoker.js`、test-only Fake Text/Vision Port | 无 Host/配置/Store 依赖；请求、错误、预算与取消 conformance 通过 |
+| M2：首个文本消费者（0.2.1 已实现） | `dsh-text-model-adapter.js` 与纯 `prompt-optimizer-core.js`；原入口保留配置/选择/投影，泡泡加入按次规则/组装/预览 | DSH/Fake 共用 conformance、reasoning、点击/写回、取消和零 Task 写入回归，以及已安装 rc.2 Runtime 隔离验收通过；真实模型/浏览器另验 |
+| M3：视觉单次调用（0.2.1 已实现） | `http-vision-model-adapter.js`、`dsh-vision-model-adapter.js`、`vision-core.js`，Agent/工作台 look/relook 与显式视觉实测 | HTTP/DSH 共用 conformance；同图字节、准备/整体预算、严格终态、取消后零下一候选；真实 rc.2 与阿里云隔离验收已通过；浏览器另验 |
+| M4：复合视觉业务（0.2.1 已实现） | OCR、locate、contact-sheet summarize 和生成后自述接入共享端口 | 有限分块与明确 partial；总预算/次数；取消停止后续块/候选；bbox 解析；同一张拼图一次候选生成；Core 转写正文；真实 DSH CLI 与独立安装逐项验收 |
+| M5：独立视觉入口（0.2.1 已实现） | CLI look/locate/ocr/summarize、严格显式选型和文件输出；主动转写才使用 Core | 实际 CLI 子进程、无 DSH tarball 安装副本与真实廉价 Provider 分别验收；文本目录与独立优化另行安排 |
+
+实际协议实现为 `http-vision-model-adapter.js`、`dsh-vision-model-adapter.js` 和 `dsh-text-model-adapter.js`。视觉候选通过共享调用策略执行，业务入口不再调用 legacy `vision.js` 的模型链；共享代码不反向导入旧 Host 实现。0.2.1 的 S2V/Browser 已迁移至共享 Core，见 [CLI 管理与补齐](CLI_MANAGEMENT.md)；媒体摘要已支持复用 Core 抽帧 Artifact，无需原视频或 ffmpeg。
+
+## M1 内部调用方式
+
+- `modelPortSnapshot()` 取得严格描述；`normalizeModelCall()` / `normalizeModelCompletion()` 校验输入和完整结果；`modelErrorRecord()` 只输出受控字段，不信任普通 Error 的原始 code、message 或 status。
+- `invokeModel(port, request, options)` 用于单次调用，自动释放 deadline 和监听器，没有候选切换。
+- `createModelOperation({ signal?, budget: { timeoutMs, maxInvocations? } })` 用于有总预算的复合操作；次数缺省 1。`operation.signal` 可覆盖入口解析与图片准备；`invoke()` 共用总额度，取消或任一调用超时后整个操作停止。
+- `operation.runCandidates(ports, request, options, policy)` 只消费有限的端口数组；`skipUnavailable`、`allowRejected`、`allowEmptyResult` 均缺省 false。策略只允许前文矩阵中的错误组合，不能通过放宽策略重试未知结果、截断、工具调用或取消。
+- 复合操作在 `finally` 中调用 `operation.dispose()`；`snapshot()` 只返回次数、在途数和本地生命周期，不包含请求或结果。并发调用先预留次数，只有可信契约错误明确 `not_invoked` 才返还，普通 Error 不能伪造未调用。
+- `createModelTextCollector()` 是协议无关的正文辅助工具，支持 append/replace、读取时输出上限和正常终态；`fail(error)` 在流错误后保留已收到正文的事实，错误进入终态后不再接受新的 stop。具体适配器先映射自身事件；该辅助工具不理解 DSH 或 SSE 协议，也不提供公共流接口。
+
+`tests/fixtures/fake-model-port.mjs` 可复现正常正文、规范化流、准备失败、在途错误、等待取消与迟到结果；`model-conformance.mjs` 的同一组 17 项检查分别消费 Text/Vision。fixture 和输入记录只在测试进程存在，不进入 npm 包。
+
+所有共享调用通过调用控制执行；协议适配器负责向真实源传递 abort 和清理资源。M2 的 DSH 文本与 M3 的 HTTP/DSH 视觉 fixture 复用同组 conformance，已安装 Runtime 使用离线源适配器单独举证。M4 另验 OCR 多块、定位 bbox、摘要一张拼图、可选 Core 转写、自述及这些操作的取消，不能仅凭协议测试推断业务正确。
+
+现有配置版本、公开接口和全部消费者不应在一个提交中同时切换。M1 不提供对提示词内容的语义过滤或注入防护证明；优化系统的主动模板/约束加入和不可信输入隔离，需在后续业务设计中分别验证。
+
+## 必须补齐的 conformance
+
+M1 已执行纯契约、调用控制与 Fake Port；0.2.1 的 M2 执行 DSH 文本协议、业务/HTTP、实际组件点击及已安装 Runtime 隔离验收；0.2.1 的 M3 执行 HTTP/DSH Vision Port、单图入口与图片桥接。M4 在同一端口上逐项验证多块 OCR、定位、摘要与自述的整体 operation，并有实际 DSH CLI 和无 DSH 安装副本证据。
+
+| 场景 | 必须证明的结果 |
+|---|---|
+| describe、能力快照与 Doctor | 零模型/网络调用、零配置/Task/Artifact 写入；未知能力不猜测 |
+| 非法输入、格式、预算、reasoning | 在生成入口前拒绝；显式参数不静默丢弃 |
+| 预先取消 | 零附件桥接、零生成调用 |
+| 在途取消、超时与晚到结果 | 底层收到 abort，资源清理，本地有界退出，无下一候选/下一 OCR 块 |
+| delta 与 block-end | 不重复文字；只有可验证正常终态才返回完整正文 |
+| EOF、`[DONE]` 但无终态、坏 JSON、未知终态 | 稳定失败，部分正文不返回为成功 |
+| 空结果、token 截断、输出超限、工具调用、内容阻断 | 独立错误；切换行为符合显式策略与总次数 |
+| OCR 与候选组合 | 有限总调用数与整体 deadline；普通块失败可形成明确 partial 业务结果，取消/超时终止操作 |
+| DSH 图片桥接 | 保存/内联输入图片，允许经核验的宿主规范化；损坏或不匹配引用在生成前拒绝；缺桥接时零模型调用，无引用泄漏 |
+| 模型身份与 usage | DSH 与 Iris 命名空间不混用；未知默认身份和 usage 字段省略 |
+| 错误、快照与自动记录 | 不包含输入、Key、端点、路径或 Host 对象；正文只作为显式结果返回，无隐式 Task/Artifact 写入 |
+| 两类适配器与业务入口 | Fake Port、HTTP 协议 fixture、DSH 流 fixture 消费同一组结果/错误规则 |
+
+legacy `tests/vision-backend.mjs` 仍验证旧兼容实现允许预先取消后继续 Host fallback。M3/M4 的现有业务入口已切换到新模块；旧 fixture 不代表新契约。OCR 额外证明取消/超时终止所有后续块、总次数有界和部分结果语义；定位、拼图摘要与自述另有完整终态、业务解析和取消验收。

package/docs/OCR_MODEL.md

@@ -0,0 +1,39 @@
+# 长图 OCR
+
+状态：**Iris 0.2.1**。定位、拼图摘要及自述见 [复合视觉调用](COMPOSITE_VISION.md)。
+
+Agent 的 `iris_long_ocr` 与工作台 OCR 使用相同分块业务和共享 Vision Ports。工具接受 `image_path`、`artifact_id` 或 `attachment_id` 三选一；工作台动作接受 `image_path` 或 `artifact_id` 二选一，现有表单继续输入文件路径。Core ID 读取当前 profile 的既有图片，核验内容哈希和 MIME，不依赖原文件、不导出临时图片、不写入 Core。工具文字保留 Core ID，动作 JSON 带 `artifactId`；CLI `vision ocr` 同样支持，详见 [视觉 CLI](VISION_CLI.md)。复用可选的账号/模型输入预算，不新增公开 SDK export 或生产依赖。
+
+## 分块与结果
+
+默认块高 1200 像素、重叠 120 像素，纵向步长为块高减重叠。显式 `overlap: 0` 会关闭重叠。保留原有块高至少 100、重叠钳制到 `[0, 块高−1]` 的规则；非有限数值在读取图片前拒绝。
+
+图片先按 EXIF 转正；宽图再按比例缩到默认最多 2048 像素宽，从上到下分块。输出中的宽高与 `y` 都是处理后图片的坐标，`sourceWidth/sourceHeight` 为转正后的源尺寸。每块提供相同源 PNG 切片，各候选在提交前按自己的账号/模型 `visionInput` 准备发送副本，不把整张长图先缩到模型最长边。重叠区域的重复文字仍保留，不做可能误删内容的自动去重。
+
+CLI/共享结果的成功块附 `input.source/sent`：切片与实际发送图的宽高、字节数、MIME，以及是否缩小。候选切换使用成功模型的记录；DSH 记录宿主保存后实际附件，而不是保存前估计。文本结果在整体宽度或某块缩小时明确提示细字可能丢失，并列出缩小块的发送尺寸。可以提高 CLI `max_dimension`（最高 4096）或模型预算以保留更多细节；缩放不会保证识别质量。
+
+| 结果 | 含义 |
+|---|---|
+| 完成 | 全部分块得到有正常终态的非空正文 |
+| 部分完成 | 至少一块成功，其他块失败或因次数上限未处理 |
+| 失败 | 没有任何完整成功块；工作台 `ok` 为 false |
+
+普通块失败允许继续处理后续块，失败块不会把半截正文拼入结果。成功段保留原始段号，例如第二块失败后第三块仍标记为 `[第3段 y=…]`。未处理块与失败块分别计数；部分结果不称为完整全文。块级诊断只有稳定模型错误，不能含原始异常、Key 或图片路径。
+
+取消或超时会立即终止整次操作并返回错误，**不以部分结果隐藏取消/超时**，也不会生成下一块或继续切换候选。
+
+## 整体预算
+
+| 限制 | 默认值 |
+|---|---|
+| 整体时间 | 120 秒，覆盖文件/Artifact/附件读取、图片处理、模型元数据、所有块与候选 |
+| 最大分块数 | 32，超出时生成前拒绝 |
+| 总生成次数 | 64，候选切换也占用次数；本地确认未调用不占次数 |
+| 源图片 | 20 MiB 编码字节，最多 4000 万像素；单帧 PNG/JPEG/WebP/GIF，工具/工作台本地路径接受 PNG/JPEG/WebP |
+| 每块正文 | 6000 个 UTF-16 code units，超限或 token 截断不返回成功 |
+
+次数用尽后不再准备/生成后续块，已完成块形成明确部分结果；一块也未完成则失败。整体 deadline 不会因下一块或下一候选重置。输入损坏、MIME 不符或多帧图片在生成前拒绝。
+
+DSH 默认视觉路由在本轮首次使用时绑定，操作期间的默认模型变更在下次 OCR 才生效。每块通过宿主保存并读回，允许核验过的合法规范化，检查内容哈希、字节数、MIME 和尺寸；不可取消保存与远端预处理的边界沿用 [单图视觉调用](VISION_MODEL.md)。Sharp 的原生图片处理不能被 AbortSignal 强制中止，本地等待有界退出后晚到结果会被忽略，不会启动模型或保存 Core 产物。
+
+OCR 不创建 Core/legacy Task、Attempt 或 Artifact，也不自动保存识别正文。验证使用共享 Fake/HTTP/DSH 端口、真实安装的 DSH 服务和无 DSH 的包外安装副本；真实模型验收单独记录，不把协议 fixture 当成识别质量证明。

package/docs/PROMPT_OPTIMIZER.md

@@ -0,0 +1,47 @@
+# 提示词优化与规则组装
+
+状态：**Iris 0.2.1**。本版提供按次规则、只组装和可编辑预览；后续独立提示词优化系统另行安排。
+
+## 使用
+
+在 DSH 输入框写入未发送的纯文本草稿，打开 🫧，选择通用、图片、视频或首尾帧视频目标。
+
+“本次规则”可填写以下内容；留空表示不选择。规则只在当前组件中保留，刷新后重置，不改写已有 `prompt-optimizer.json`。
+
+| 内容 | 智能优化 | 只组装 |
+|---|---|---|
+| 改写规则 | 指导模型如何编辑草稿，不要求将规则原文抄入结果 | 不使用 |
+| 输出前缀 | 模型改写完成后，程序原样加入开头 | 原样加入原稿开头 |
+| 输出后缀 | 模型改写完成后，程序原样加入末尾 | 原样加入原稿末尾 |
+
+智能优化进行一次文本模型生成；只组装不读取模型路由或优化配置、不调用模型，在 Host 文本服务不可用时仍可使用。只组装不会套用目标模板或自动润色原稿。规则之间与正文之间用两个 LF 分隔；输出规则原文与只组装的草稿空白保持不变。
+
+结果先进入可编辑预览。可以查看原文、本次参与规则、实际模型与思考策略，以及折叠相同首尾后的中间替换区。这是文本改动对照，不代表模型解释了每处改动的原因。手动编辑也会更新对照；复制和写回使用编辑后的文字。
+
+写回不会自动发送。出现新草稿时先确认替换；出现结构化 `@`、`/` 引用或忙碌状态时拒绝写回。切换会话清除旧预览并取消在途操作，即便两边草稿文本相同。取消、关闭或卸载会传递 abort，迟到结果不能恢复旧预览或覆盖新操作。恢复原文只恢复本次操作前的文字，不自动恢复附件/结构化引用。
+
+## 规则来源与限制
+
+优化处理规则、用户选择的改写规则、待处理草稿和程序拼接的输出规则分别处理。Iris 不从草稿解析额外规则，不读取会话历史、附件、工具或工作区。JSON 包装及 system 字段用于区分指令和素材，不能证明模型永远抵御提示词注入；事实保留、规则冲突和优化质量仍需真实模型评估与预览。
+
+输出前后缀不交给模型改写，也不自动转换为生成 API 参数。例如文字中的画幅要求不等同于图片工具的实际尺寸参数。Iris 不对任意自然语言规则做完整冲突检测。
+
+- 草稿：沿用修剪后 32 KiB UTF-8 上限；返回原文保留空白。
+- 规则：单条最多 4,000 个 UTF-16 code units；最多 12 条，正文总计 16 KiB UTF-8。
+- 最终结果：最多 16,000 个 UTF-16 code units；智能优化先为输出规则与分隔符预留空间，超限或截断失败。
+- 默认预算：45 秒、1,200 输出 token；元数据查询和生成共用 deadline，不自动重试或切换模型。
+- 配置仍为 v1，模型路由、JSON 导入/导出、恢复默认和开关保持原有方式。`off-if-supported` 在关闭能力未知时使用供应商默认；显式 effort 和 `inherit` 的具体档位必须有元数据声明，否则在生成前拒绝。该拒绝是与 npm 0.2.0 的行为差异。
+
+取消表示本地停止等待并向底层传递信号，不保证第三方远端执行或计费已停止。失败、工具调用、未知终态和部分正文不会作为完整结果交付。
+
+## 开发边界
+
+`prompt-optimizer-core.js` 只接收显式文字、模板快照及 TextModel Port；DSH 入口负责 v1 配置、模型绑定、预览与写回。DSH 适配器聚合 `text-delta` / `block-end`、忽略思考正文、检查终态和清理源迭代器。rc.2 的缓存与未缓存输入计数相加后成为共享输入 token 数，未知 usage 字段省略。
+
+优化和组装不创建 Core Task/Attempt/Artifact，不取得 writer 租约。纯核心可在无 DSH 的安装树中执行，但本轮未增加 CLI 命令、自持文本目录、公共 SDK export 或规则持久化格式。
+
+现有 `POST /iris/api/prompt-optimizer/optimize` 增加可选 `mode`（`optimize` / `assemble`）与 `rules`；省略时沿用原优化行为。规则形状为 `{ id, label, kind, text, position? }`：kind 是 `optimization` 或 `output`，只有 output 设置 `prefix` / `suffix`。调用者不能伪造 source；响应由程序标记为 `user-selected`。直接 API 在 assemble 模式携带 optimization 规则会拒绝；UI 只组装只提交输出规则。
+
+配置 API 在配置对象外返回 `capabilities: { rules: true, assemble: true }`。新客户端读到明确能力才启用规则和只组装按钮，防止旧后端忽略 mode 并意外调用模型。能力字段不进入配置导出文件。
+
+参见 [Model Port 契约](MODEL_PORT_CONTRACT.md) 与 [架构边界](ARCHITECTURE.md)。浏览器/Android 交互和真实模型质量需各自验收。