dsh-modellix 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,38 @@ The format follows Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-15
+
+### Changed
+
+- Replaced repeated immediate task reads with bounded server waits and an overall cancellation deadline.
+- Moved remote waits outside the shared Design write queue; observations remain serialized and credential-epoch guarded.
+- Added deterministic image, video, and audio upload validation up to 16 MiB and explicit file-quota recovery guidance.
+- Updated real API acceptance to exercise server waits without replaying media submissions.
+
+### Fixed
+
+- Keep API Key validation errors visible while a credential editor is open; background configuration refresh resumes after it closes.
+- Restore keyboard focus to the credential editor's opener when a host Modal applies its own autofocus.
+- Keep settings controls enabled during background refresh and discard stale replies after a newer settings change.
+
+## [0.2.1] - 2026-09-02
+
+### Changed
+
+- Limited the Web switch to the explicit `modellix_web_search` and `modellix_web_fetch` capability and its Agent routing context. The plugin no longer overrides, enables, disables, or selects Harness native `web_search` / `web_fetch` tools and providers.
+- Updated the authoring baseline and public Client/Host integration to DeepSeek Harness `0.1.2-alpha.4`, including the current Connection RPC, Settings namespace, Client renderer, and Tool JSON type surfaces, while retaining `0.1.1-rc.2` runtime compatibility.
+
+### Fixed
+
+- Disabling Web now unregisters both explicit Modellix Web tools immediately, so a new Agent session falls back to the Harness-native Web capabilities configured by the active profile instead of spending a turn on a disabled Modellix tool.
+- Re-enabling Web restores both explicit tools and their Modellix-first routing without changing the independent Design or LLM service state.
+
+### Verification
+
+- Added Host lifecycle regression coverage for enabled → disabled → enabled Web transitions, including preservation of native Search/Fetch tools and providers, continued Design registration, unchanged LLM materialization, and omission of Modellix Web routing while disabled.
+- Added tarball cold-install and declaration-consumer verification against both Harness `0.1.2-alpha.4` and `0.1.1-rc.2`.
+
 ## [0.2.0] - 2026-08-31
 
 ### Added

package/README.md

@@ -8,6 +8,18 @@
 
 ![A real English Harness conversation showing a completed Modellix image result](docs/assets/chat-media-generation-en.webp)
 
+## What changed in 0.3.0
+
+- Task monitoring uses bounded server waits. Only a known task ID is observed, and stopping a wait never resubmits the paid generation.
+- Chat and result history stay responsive during a wait. Disabling Design, changing credentials, or closing the plugin cancels outstanding reads and prevents stale results from being saved.
+- Workspace uploads support the File API's image, video, and audio formats up to 16 MiB, with local file/container checks. Harness attachment uploads still use its image attachment reader. On quota errors, list files and explicitly delete only selected IDs through the File API or CLI; the plugin never deletes files automatically.
+- The server must support `wait=true`; an unsupported server produces a compatibility error instead of repeated short polling.
+
+## What changed in 0.2.1
+
+- The Web switch now unregisters only `modellix_web_search` and `modellix_web_fetch`. Harness-native Web tools and providers remain available, so turning Modellix Web off falls back to the active profile's defaults.
+- Updated the authoring and runtime integration for Harness `0.1.2-alpha.4`, while retaining `0.1.1-rc.2` compatibility.
+
 ## What changed in 0.2.0
 
 - Removed the standalone Design tab. Chat is now the primary media workflow.
@@ -30,7 +42,7 @@
 
 ## Requirements
 
-- DeepSeek Harness `0.1.1-rc.2`
+- DeepSeek Harness `0.1.2-alpha.4` (latest supported); `0.1.1-rc.2` remains supported
 - Published-package runtime: Node.js `^22.19.0 || >=24.0.0`
 - Source development and release verification: Node.js `24.18.1`, pnpm `11.24.0`
 - A valid [Modellix API Key](https://docs.modellix.ai/get-started)
@@ -55,7 +67,7 @@ To install a trusted local build:
 pnpm install --frozen-lockfile
 pnpm run verify:release:static
 pnpm pack
-dsh plugin --profile web add ./dsh-modellix-0.2.0.tgz
+dsh plugin --profile web add ./dsh-modellix-0.3.0.tgz
 ```
 
 See [local usage](docs/en-US/LOCAL_USAGE.md) for the complete Windows-first workflow.
@@ -105,7 +117,7 @@ The **Modellix Design** button sits at the far right of the conversation header,
 - The entire Results list is expanded by default and can be collapsed.
 - Every result card is expanded by default and can be collapsed by selecting its header.
 - The close button returns focus to the launcher.
-- The advanced exact-parameter editor remains implemented but its entry is hidden in `0.2.0`; ordinary users work through chat.
+- The advanced exact-parameter editor remains implemented but its entry is hidden in `0.3.0`; ordinary users work through chat.
 - At 560 px and below, the panel uses the available viewport width. At 360 px and below, the launcher becomes a reachable compact control.
 
 ## LLM models
@@ -118,7 +130,7 @@ When LLM is enabled, the plugin reads the live Modellix catalog and adds those m
 
 Users do not need to name a tool. For current, changing, external, or source-verification questions, the Agent is instructed to use `modellix_web_search`. When the user provides a public URL or a search result needs full-page reading, it uses `modellix_web_fetch`.
 
-The explicit Modellix tools and the native Harness providers share the same underlying service, but the routing instruction prevents both tool families from being called for the same operation. Failed or unknown Web requests are not repeated automatically.
+While Web is enabled, the plugin registers only the two explicit Modellix tools and asks the Agent to prefer them for matching work. Disabling Web unregisters those tools and removes the Modellix Web routing context; Harness-native `web_search` / `web_fetch` tools and their configured providers remain untouched and can be selected automatically. Failed or unknown Modellix Web requests are not repeated automatically.
 
 ![A real English Agent turn automatically using Modellix Search and Fetch](docs/assets/web-tools-auto-en.webp)
 
@@ -128,7 +140,7 @@ The Modellix settings section shows:
 
 - Credential configured/verification status and source;
 - replacement and removal actions for a writable local Credential;
-- independent Design, LLM, and Web switches;
+- independent Design, LLM, and Web switches; each switch changes only its own Modellix capability;
 - live LLM catalog health, count, refresh time, and manual refresh.
 
 Only HTTP 401 marks a Credential invalid. HTTP 402, 429, network failures, and 5xx retain their own recovery states. Concurrent 401 responses are coalesced into one Credential dialog.

package/README.zh-CN.md

@@ -8,6 +8,18 @@
 
 ![真实中文 Harness 会话中已完成的 Modellix 图片结果](docs/assets/chat-media-generation-zh.webp)
 
+## 0.3.0 的主要变化
+
+- 任务监控改为有界服务端等待，只观察已知任务 ID；停止等待不会重新提交计费生成。
+- 等待期间 Chat 与结果历史保持响应。关闭 Design、更换凭据或关闭插件时会取消未完成的读取，并阻止旧结果写入。
+- 工作区上传支持 File API 的图片、视频和音频格式，单文件上限 16 MiB，并校验本地文件与容器。Harness 附件仍使用其图片读取接口。配额不足时，通过 File API 或 CLI 列出文件并明确删除选中的 ID；插件不会自动清理文件。
+- 服务端需要支持 `wait=true`；不支持时会明确提示兼容性错误，不会回退为反复短轮询。
+
+## 0.2.1 的主要变化
+
+- Web 开关现在只注销 `modellix_web_search` 与 `modellix_web_fetch`。Harness 原生 Web 工具和 Provider 保持可用，关闭 Modellix Web 后会回退到当前 Profile 的默认能力。
+- 开发与运行时集成已适配 Harness `0.1.2-alpha.4`，并继续兼容 `0.1.1-rc.2`。
+
 ## 0.2.0 的主要变化
 
 - 删除独立 Design Tab，对话成为媒体创作主界面。
@@ -30,7 +42,7 @@
 
 ## 环境要求
 
-- DeepSeek Harness `0.1.1-rc.2`
+- DeepSeek Harness `0.1.2-alpha.4`（最新支持版本）；继续兼容 `0.1.1-rc.2`
 - 已发布包运行时：Node.js `^22.19.0 || >=24.0.0`
 - 源码开发与发布校验：Node.js `24.18.1`、pnpm `11.24.0`
 - 有效的 [Modellix API Key](https://docs.modellix.ai/get-started)
@@ -55,7 +67,7 @@ dsh --profile web
 pnpm install --frozen-lockfile
 pnpm run verify:release:static
 pnpm pack
-dsh plugin --profile web add ./dsh-modellix-0.2.0.tgz
+dsh plugin --profile web add ./dsh-modellix-0.3.0.tgz
 ```
 
 完整 Windows 本地流程见[本地使用指南](docs/zh-CN/LOCAL_USAGE.md)。
@@ -105,7 +117,7 @@ Agent 会按实际情况：
 - 整个结果列表默认展开，可点击收起。
 - 每张结果卡默认展开，可点击卡片头部收起。
 - 点击 X 关闭后，焦点会回到入口按钮。
-- 高级精准参数编辑器已保留，但 `0.2.0` 暂不显示入口；普通用户通过 Chat 使用。
+- 高级精准参数编辑器已保留，但 `0.3.0` 暂不显示入口；普通用户通过 Chat 使用。
 - 560px 及以下使用可用视口全宽；360px 及以下入口变为可触达的紧凑按钮。
 
 ## LLM 模型
@@ -118,7 +130,7 @@ Agent 会按实际情况：
 
 用户不需要说出工具名。遇到实时、变化中、外部或需要来源核验的问题，Agent 会使用 `modellix_web_search`；用户提供公开 URL，或搜索结果需要阅读全文时，会使用 `modellix_web_fetch`。
 
-明确的 Modellix 工具与 Harness 原生 Provider 共用底层服务，但路由规则会阻止同一操作同时调用两套工具。失败或结果未知的 Web 请求不会自动重复。
+Web 开启时，插件只注册两个明确的 Modellix 工具，并要求 Agent 在适用任务中优先使用它们。关闭 Web 会注销这两个工具并移除 Modellix Web 路由上下文；Harness 原生 `web_search` / `web_fetch` 及其已配置 Provider 不受影响，仍可被 Agent 自动选择。失败或结果未知的 Modellix Web 请求不会自动重复。
 
 ![真实中文 Agent 回合自动使用 Modellix Search 与 Fetch](docs/assets/web-tools-auto-zh.webp)
 
@@ -128,7 +140,7 @@ Modellix 设置页包括：
 
 - Credential 是否已配置、验证状态和来源；
 - 本地可写 Credential 的更换与移除；
-- Design、LLM、Web 独立开关；
+- Design、LLM、Web 独立开关，每个开关只改变自身的 Modellix 能力；
 - LLM 实时目录健康、数量、刷新时间和手动刷新。
 
 只有 HTTP 401 会把 Credential 标记为无效。HTTP 402、429、网络错误和 5xx 使用各自恢复状态。并发 401 会合并为一个 Credential 弹窗。

package/cordis.patch.yml

@@ -1,16 +1,3 @@
-- id: web
-  config:
-    searchProvider: modellix
-    fetchProvider: modellix
-
-- id: tool-web
-  config:
-    search: true
-    fetch: true
-    searchTimeoutMs: 60000
-    fetchTimeoutMs: 60000
-  disabled: false
-
 - insert:
     - id: modellix
       name: dsh-modellix

package/docs/en-US/LOCAL_USAGE.md

@@ -8,7 +8,7 @@ This guide shows how to build `dsh-modellix` from the current source checkout on
 
 You need:
 
-- DeepSeek Harness `0.1.1-rc.2`
+- DeepSeek Harness `0.1.2-alpha.4` (latest supported); `0.1.1-rc.2` remains supported
 - Node.js `24.18.1`; the published runtime also supports `^22.19.0`
 - pnpm `11.24.0`
 - A valid Modellix API Key
@@ -42,7 +42,7 @@ pnpm run verify:pack
 pnpm pack
 ```
 
-The repository root will contain a file such as `dsh-modellix-0.2.0.tgz`. Do not ask DSH to install the unbuilt TypeScript checkout directly.
+The repository root will contain a file such as `dsh-modellix-0.3.0.tgz`. Do not ask DSH to install the unbuilt TypeScript checkout directly.
 
 ## 3. Create an isolated local Harness environment
 
@@ -60,7 +60,7 @@ This affects only the current PowerShell process and its children. Omit this ste
 Install the tarball into the `web` profile and inspect the merged configuration:
 
 ```powershell
-dsh plugin --profile web add .\dsh-modellix-0.2.0.tgz
+dsh plugin --profile web add .\dsh-modellix-0.3.0.tgz
 dsh --profile web --dump-config
 ```
 
@@ -88,10 +88,12 @@ An environment-sourced Modellix Key is read-only in the UI. Stop and restart Har
 ## 6. Start the local Web UI
 
 ```powershell
-dsh --profile web --no-open
+dsh --profile web --no-open --port 3080 --trusted-host localhost:3080
 ```
 
-The terminal prints the actual address, such as `http://127.0.0.1:3080`. Open the printed address; do not assume the port is fixed.
+The supported Harness currently accepts only its loopback IP or all interfaces as a bind value. Keep the default loopback binding, allow `localhost:3080` through its trust fence, and open `http://localhost:3080/`. Do not use an all-interface bind for local acceptance.
+
+The terminal prints the actual address, such as `http://localhost:3080`. Open the printed address; do not assume the port is fixed.
 
 A fresh profile may first show Harness's own DeepSeek initialization dialog. Complete or otherwise handle that step before the plugin presents “Connect Modellix”:
 
@@ -109,7 +111,7 @@ A fresh profile may first show Harness's own DeepSeek initialization dialog. Com
 6. Select **Modellix Design** at the far right of the session header to see all current-session results.
 7. Use Preview/JSON on successful cards, image enlargement, native video/audio players, **Add URL to chat**, and **Download**.
 
-The advanced exact-parameter editor remains internal but its entry is hidden in `0.2.0`. Routine UI flows do not display payment prompts; usage and details remain available in Modellix.
+The advanced exact-parameter editor remains internal but its entry is hidden in `0.3.0`. Routine UI flows do not display payment prompts; usage and details remain available in Modellix.
 
 ## 8. Use Modellix LLM models
 
@@ -123,6 +125,8 @@ The catalog is live. The plugin does not invent fallback models when it cannot l
 
 With Web enabled, ask a current, external, URL, or source-verification question normally. The Agent automatically uses explicit `modellix_web_search` and `modellix_web_fetch` tools when needed; users do not need to name either tool.
 
+With Web disabled, those two explicit tools are unregistered. The plugin does not alter the profile's native `web_search` / `web_fetch` tools or provider selection, so native automatic Web behavior remains available.
+
 ## 10. Update the local plugin
 
 After source changes:
@@ -135,9 +139,9 @@ After source changes:
 Set-Location 'D:\work\maas\githup\dsh-modellix'
 pnpm run verify:pack
 pnpm pack
-dsh plugin --profile web add .\dsh-modellix-0.2.0.tgz
+dsh plugin --profile web add .\dsh-modellix-0.3.0.tgz
 dsh --profile web --dump-config
-dsh --profile web --no-open
+dsh --profile web --no-open --port 3080 --trusted-host localhost:3080
 ```
 
 ## 11. Troubleshooting
@@ -147,8 +151,8 @@ dsh --profile web --no-open
 | A DeepSeek API Key dialog appears first | This is the fresh Harness profile's base initialization, not the Modellix dialog; complete it before configuring Modellix |
 | The CLI is logged in but the plugin still requests a Key | The CLI Keychain and Harness Credential service are separate; save it in the plugin UI or inject `MODELLIX_API_KEY` into the Harness process |
 | Modellix Design is missing | Inspect `--dump-config`, confirm Design is enabled, and fully restart the running profile after an update |
-| A task remains stale in assistant prose | Current status belongs to the live card and right panel; `0.2.0` updates the card in the background and avoids nonterminal status wording in ordinary prose |
-| One task shows two cards | This is not expected in `0.2.0`; record the job/tool call ids without Secrets and report a duplicate-card defect |
+| A task remains stale in assistant prose | Current status belongs to the live card and right panel; `0.3.0` updates the card in the background and avoids nonterminal status wording in ordinary prose |
+| One task shows two cards | This is not expected in `0.3.0`; record the job/tool call ids without Secrets and report a duplicate-card defect |
 | The UI reports an invalid Key | Only an explicit Modellix 401 enters this state; replace a local Credential in settings, or update an environment source and restart |
 | Balance is insufficient | A 402 is not treated as an invalid Key; fund the account or change the task before retrying manually |
 | Requests are rate-limited | Wait for the 429 window to end before retrying manually |

package/docs/en-US/RELEASE_CHECKLIST.md

@@ -1,6 +1,6 @@
 [English](RELEASE_CHECKLIST.md) | [简体中文](../zh-CN/RELEASE_CHECKLIST.md)
 
-# dsh-modellix 0.2.0 Release and Acceptance Checklist
+# dsh-modellix 0.3.0 Release and Acceptance Checklist
 
 Use this document for manual product acceptance and for the final release gate. Check each item against the exact package/commit being released.
 
@@ -23,8 +23,8 @@ Record before testing:
 
 | Item | Expected |
 | --- | --- |
-| Package | `dsh-modellix@0.2.0` |
-| Harness | `0.1.1-rc.2` |
+| Package | `dsh-modellix@0.3.0` |
+| Harness | `0.1.2-alpha.4` latest matrix plus `0.1.1-rc.2` compatibility matrix |
 | Development Node | `24.18.1` |
 | pnpm | `11.24.0` |
 | Browser capture viewport | `1920×1080`, DPR 1 |
@@ -219,7 +219,7 @@ Create Secret-free files outside the repository:
 
 Both files must:
 
-- target `dsh-modellix@0.2.0`;
+- target `dsh-modellix@0.3.0`;
 - contain the exact lowercase 40-character Git HEAD;
 - use a canonical UTC ISO-8601 completion time no older than 72 hours;
 - have status `passed` for every required check;
@@ -244,16 +244,16 @@ After all checks pass:
 5. Read back:
 
 ```sh
-npm view dsh-modellix@0.2.0 version dist.integrity dist.shasum --json --registry=https://registry.npmjs.org/ --prefer-online
+npm view dsh-modellix@0.3.0 version dist.integrity dist.shasum --json --registry=https://registry.npmjs.org/ --prefer-online
 ```
 
-6. From an empty external directory and fresh npm cache, install `dsh-modellix@0.2.0`.
+6. From an empty external directory and fresh npm cache, install `dsh-modellix@0.3.0`.
 7. Verify the installed version and `dsh --profile <isolated> --dump-config`.
 8. Remove temporary npm config, cache, tarball, profile, evidence intermediates, and process variables.
 
 Do not create a Git tag or GitHub Release unless explicitly requested.
 
-## 17. 0.2.0 verification record
+## 17. 0.2.1 verification record
 
 The release candidate was exercised on 2026-08-31 with:
 

package/docs/en-US/USER_GUIDE.md

@@ -2,13 +2,22 @@
 
 # dsh-modellix User Guide
 
-This guide describes the current `0.2.0` experience. Media creation is chat-first; there is no standalone Design tab. The right-side **Modellix Design** panel is a session-scoped result workspace.
+This guide describes the current `0.3.0` experience. Media creation is chat-first; there is no standalone Design tab. The right-side **Modellix Design** panel is a session-scoped result workspace.
+
+
+## What changed in 0.3.0
+
+- Task monitoring uses bounded server waits. Only a known task ID is observed, and stopping a wait never resubmits the paid generation.
+- Chat and result history stay responsive during a wait. Disabling Design, changing credentials, or closing the plugin cancels outstanding reads and prevents stale results from being saved.
+- Workspace uploads support the File API's image, video, and audio formats up to 16 MiB, with local file/container checks. Harness attachment uploads still use its image attachment reader. On quota errors, list files and explicitly delete only selected IDs through the File API or CLI; the plugin never deletes files automatically.
+- The server must support `wait=true`; an unsupported server produces a compatibility error instead of repeated short polling.
+
 
 ## 1. Install and verify
 
 ### Requirements
 
-- DeepSeek Harness `0.1.1-rc.2`
+- DeepSeek Harness `0.1.2-alpha.4` (latest supported); `0.1.1-rc.2` remains supported
 - Node.js `^22.19.0 || >=24.0.0`
 - A valid Modellix API Key
 
@@ -28,7 +37,7 @@ To use a local package artifact:
 pnpm install --frozen-lockfile
 pnpm run verify:release:static
 pnpm pack
-dsh plugin --profile web add ./dsh-modellix-0.2.0.tgz
+dsh plugin --profile web add ./dsh-modellix-0.3.0.tgz
 ```
 
 See [LOCAL_USAGE.md](LOCAL_USAGE.md) for isolated-profile setup and update commands.
@@ -80,7 +89,7 @@ It does not add a standalone Design tab.
 - Results and every card are expanded by default.
 - Select **Results** to collapse the whole list; select a card header to collapse only that card.
 - Select X to close. Keyboard focus returns to the launcher.
-- The advanced exact-parameter editor remains in the implementation but its entry is hidden for `0.2.0`.
+- The advanced exact-parameter editor remains in the implementation but its entry is hidden for `0.3.0`.
 
 ## 4. Create media by chatting
 
@@ -223,7 +232,7 @@ Expected flow:
 2. When full-page content is needed, Agent calls `modellix_web_fetch`.
 3. The answer cites the fetched/source pages.
 
-The user should not need to say “use search” or “use fetch.” If the user explicitly says not to browse, the Agent does not call them. The routing context also prevents duplicate calls to both the explicit tools and native provider tools for the same operation.
+The user should not need to say “use search” or “use fetch.” If the user explicitly says not to browse, the Agent does not call them. When Modellix Web is enabled, its routing context prevents duplicate calls to both tool families for the same operation. When it is disabled, the two explicit Modellix tools and that routing context are removed; the profile's native `web_search` / `web_fetch` tools and providers remain available for automatic fallback.
 
 ## 11. Settings and errors
 
@@ -231,7 +240,9 @@ The user should not need to say “use search” or “use fetch.” If the user
 
 - **Design:** controls media tools, chat result views, and the result panel.
 - **LLM:** controls live Modellix model materialization.
-- **Web:** controls Modellix Search/Fetch providers and explicit tools.
+- **Web:** controls only the explicit Modellix Search/Fetch tools and Modellix-first routing. It does not change Harness-native Web tools or providers.
+
+The three switches are independent. Saving one service change does not register, unregister, or reconfigure either of the other two services.
 
 ### Credential status
 
@@ -269,6 +280,8 @@ Confirm Design is enabled, inspect `dsh --profile web --dump-config`, and fully
 
 Confirm Web is enabled and the current Agent session contains the `Web routing` context. The explicit tools should appear as `modellix_web_search` and `modellix_web_fetch`.
 
+If Web is intentionally disabled, neither explicit tool should appear and the session should not contain Modellix `Web routing`; native `web_search` / `web_fetch` behavior continues according to the active Harness profile.
+
 ### A model Schema is reported as unavailable
 
 Refresh the live media catalog, verify the exact model slug returned by `modellix_media_list`, and read `modellix_media_schema` again. The parser supports documented OpenAPI layouts and bounded shared references; it blocks unsafe or unsupported contracts instead of guessing.
@@ -279,11 +292,11 @@ Keep the conversation open long enough for the Client watcher, verify the Creden
 
 ### Two cards represent one task
 
-This is not expected in `0.2.0`. Capture the two job ids and tool call ids without Secrets. The generation card should win the per-session task claim, and the matching result-query card should be suppressed.
+This is not expected in `0.3.0`. Capture the two job ids and tool call ids without Secrets. The generation card should win the per-session task claim, and the matching result-query card should be suppressed.
 
 ### Results from another conversation appear
 
-This is not expected for new `0.2.0` tasks. Record the affected session/task ids and report it as a session-isolation defect.
+This is not expected for new `0.3.0` tasks. Record the affected session/task ids and report it as a session-isolation defect.
 
 ### Media cannot play
 

package/docs/zh-CN/LOCAL_USAGE.md

@@ -8,7 +8,7 @@
 
 需要：
 
-- DeepSeek Harness `0.1.1-rc.2`
+- DeepSeek Harness `0.1.2-alpha.4`（最新支持版本）；继续兼容 `0.1.1-rc.2`
 - Node.js `24.18.1`；运行已发布包也支持 `^22.19.0`
 - pnpm `11.24.0`
 - 有效的 Modellix API Key
@@ -42,7 +42,7 @@ pnpm run verify:pack
 pnpm pack
 ```
 
-完成后，仓库根目录会生成类似 `dsh-modellix-0.2.0.tgz` 的文件。不要直接把未构建的 TypeScript 源码交给 DSH 安装。
+完成后，仓库根目录会生成类似 `dsh-modellix-0.3.0.tgz` 的文件。不要直接把未构建的 TypeScript 源码交给 DSH 安装。
 
 ## 3. 创建独立的本地 Harness 环境
 
@@ -60,7 +60,7 @@ New-Item -ItemType Directory -Force -Path $env:DSH_HOME | Out-Null
 把刚生成的 tarball 安装到 `web` Profile：
 
 ```powershell
-dsh plugin --profile web add .\dsh-modellix-0.2.0.tgz
+dsh plugin --profile web add .\dsh-modellix-0.3.0.tgz
 dsh --profile web --dump-config
 ```
 
@@ -88,10 +88,12 @@ $env:MODELLIX_API_KEY = (Get-Content -LiteralPath 'D:\secrets\modellix-key.txt'
 ## 6. 启动本地 Web UI
 
 ```powershell
-dsh --profile web --no-open
+dsh --profile web --no-open --port 3080 --trusted-host localhost:3080
 ```
 
-终端会打印实际地址，例如 `http://127.0.0.1:3080`。用浏览器打开终端显示的地址，不要假定端口固定。
+当前受支持的 Harness 绑定值仅接受回环 IP 或全部网卡。保留默认的回环绑定，通过信任边界显式允许 `localhost:3080`，并打开 `http://localhost:3080/`；本地验收不要绑定全部网卡。
+
+终端会打印实际地址，例如 `http://localhost:3080`。用浏览器打开终端显示的地址，不要假定端口固定。
 
 全新 Profile 可能先显示 Harness 自带的 DeepSeek 初始化弹窗。完成或按需处理该步骤后，插件会显示“连接 Modellix”弹窗：
 
@@ -109,7 +111,7 @@ dsh --profile web --no-open
 6. 点击会话头部最右侧 **Modellix Design**，查看当前会话全部结果。
 7. 成功卡可用预览/JSON、图片放大、原生视频/音频播放器、**添加 URL 到对话框** 和 **下载**。
 
-高级精准参数编辑器继续保留，但 `0.2.0` 暂不显示入口。常规 UI 不显示付费提示；消耗与明细在 Modellix 查看。
+高级精准参数编辑器继续保留，但 `0.3.0` 暂不显示入口。常规 UI 不显示付费提示；消耗与明细在 Modellix 查看。
 
 ## 8. 使用 Modellix LLM
 
@@ -123,6 +125,8 @@ dsh --profile web --no-open
 
 确认 Web 开关开启后，正常提出实时、外部、URL 或来源核验问题。Agent 会按需自动使用明确的 `modellix_web_search` 与 `modellix_web_fetch`，用户不需要说出工具名。
 
+关闭 Web 后，这两个明确工具会被注销。插件不会更改当前 Profile 的原生 `web_search` / `web_fetch` 或 Provider 选择，因此原生自动联网能力仍可使用。
+
 ## 10. 更新本地插件
 
 源码变化后：
@@ -135,9 +139,9 @@ dsh --profile web --no-open
 Set-Location 'D:\work\maas\githup\dsh-modellix'
 pnpm run verify:pack
 pnpm pack
-dsh plugin --profile web add .\dsh-modellix-0.2.0.tgz
+dsh plugin --profile web add .\dsh-modellix-0.3.0.tgz
 dsh --profile web --dump-config
-dsh --profile web --no-open
+dsh --profile web --no-open --port 3080 --trusted-host localhost:3080
 ```
 
 ## 11. 常见问题
@@ -147,8 +151,8 @@ dsh --profile web --no-open
 | 先出现 DeepSeek API Key 弹窗 | 这是全新 Harness Profile 的基础初始化，不是 Modellix 弹窗；完成后继续配置 Modellix |
 | `modellix-cli` 已登录但插件仍要求 Key | CLI Keychain 与 Harness Credential 相互独立；在插件 UI 保存，或给 Harness 启动进程设置 `MODELLIX_API_KEY` |
 | 看不到 Modellix Design | 检查 `--dump-config`、确认 Design 已开启，并在更新后完整重启运行中的 Profile |
-| 助手正文里的状态看起来旧 | 当前状态属于实时卡片与右侧面板；`0.2.0` 后台更新卡片，并避免在普通正文写非终态 |
-| 一个任务显示两张卡 | `0.2.0` 不应出现；在不包含 Secret 的情况下记录 job/tool call id 并报告重复卡缺陷 |
+| 助手正文里的状态看起来旧 | 当前状态属于实时卡片与右侧面板；`0.3.0` 后台更新卡片，并避免在普通正文写非终态 |
+| 一个任务显示两张卡 | `0.3.0` 不应出现；在不包含 Secret 的情况下记录 job/tool call id 并报告重复卡缺陷 |
 | 页面提示 Key 无效 | 只有 Modellix 明确返回 401 才会进入该状态；本地 Credential 可在设置中更换，环境来源需在外部更新并重启 |
 | 余额不足 | 402 不会被误报为 Key 无效；充值或调整任务后手动重试 |
 | 请求过多 | 等待 429 限流窗口结束后再手动重试 |

package/docs/zh-CN/RELEASE_CHECKLIST.md

@@ -1,6 +1,6 @@
 [English](../en-US/RELEASE_CHECKLIST.md) | [简体中文](RELEASE_CHECKLIST.md)
 
-# dsh-modellix 0.2.0 发布与验收清单
+# dsh-modellix 0.3.0 发布与验收清单
 
 本文用于人工产品验收和最终发布门禁。每一项都必须针对即将发布的准确包版本与 commit 检查。
 
@@ -23,8 +23,8 @@
 
 | 项目 | 预期 |
 | --- | --- |
-| 包 | `dsh-modellix@0.2.0` |
-| Harness | `0.1.1-rc.2` |
+| 包 | `dsh-modellix@0.3.0` |
+| Harness | `0.1.2-alpha.4` 最新矩阵，并兼容验证 `0.1.1-rc.2` |
 | 开发 Node | `24.18.1` |
 | pnpm | `11.24.0` |
 | 浏览器截图视口 | `1920×1080`、DPR 1 |
@@ -219,7 +219,7 @@ pnpm run test:real:modellix
 
 两个文件必须：
 
-- 指向 `dsh-modellix@0.2.0`；
+- 指向 `dsh-modellix@0.3.0`；
 - 包含准确的 40 位小写 Git HEAD；
 - 使用不早于 72 小时的规范 UTC ISO-8601 时间；
 - 所有必填 check 均为 `passed`；
@@ -244,16 +244,16 @@ pnpm run verify:release
 5. 回读：
 
 ```sh
-npm view dsh-modellix@0.2.0 version dist.integrity dist.shasum --json --registry=https://registry.npmjs.org/ --prefer-online
+npm view dsh-modellix@0.3.0 version dist.integrity dist.shasum --json --registry=https://registry.npmjs.org/ --prefer-online
 ```
 
-6. 在仓库外空目录和全新 npm cache 中安装 `dsh-modellix@0.2.0`。
+6. 在仓库外空目录和全新 npm cache 中安装 `dsh-modellix@0.3.0`。
 7. 检查实际落盘版本和 `dsh --profile <isolated> --dump-config`。
 8. 删除临时 npm 配置、cache、tarball、profile、Evidence 中间文件和进程变量。
 
 未经明确要求，不创建 Git Tag 或 GitHub Release。
 
-## 17. 0.2.0 验证记录
+## 17. 0.2.1 验证记录
 
 2026-08-31 对候选版本执行了：
 

package/docs/zh-CN/USER_GUIDE.md

@@ -2,13 +2,22 @@
 
 # dsh-modellix 用户指南
 
-本文说明 `0.2.0` 的当前体验。媒体创作以对话为主，不再存在独立 Design Tab；右侧 **Modellix Design** 是按会话隔离的结果工作区。
+本文说明 `0.3.0` 的当前体验。媒体创作以对话为主，不再存在独立 Design Tab；右侧 **Modellix Design** 是按会话隔离的结果工作区。
+
+
+## 0.3.0 的主要变化
+
+- 任务监控改为有界服务端等待，只观察已知任务 ID；停止等待不会重新提交计费生成。
+- 等待期间 Chat 与结果历史保持响应。关闭 Design、更换凭据或关闭插件时会取消未完成的读取，并阻止旧结果写入。
+- 工作区上传支持 File API 的图片、视频和音频格式，单文件上限 16 MiB，并校验本地文件与容器。Harness 附件仍使用其图片读取接口。配额不足时，通过 File API 或 CLI 列出文件并明确删除选中的 ID；插件不会自动清理文件。
+- 服务端需要支持 `wait=true`；不支持时会明确提示兼容性错误，不会回退为反复短轮询。
+
 
 ## 1. 安装与检查
 
 ### 环境要求
 
-- DeepSeek Harness `0.1.1-rc.2`
+- DeepSeek Harness `0.1.2-alpha.4`（最新支持版本）；继续兼容 `0.1.1-rc.2`
 - Node.js `^22.19.0 || >=24.0.0`
 - 有效的 Modellix API Key
 
@@ -28,7 +37,7 @@ dsh --profile web
 pnpm install --frozen-lockfile
 pnpm run verify:release:static
 pnpm pack
-dsh plugin --profile web add ./dsh-modellix-0.2.0.tgz
+dsh plugin --profile web add ./dsh-modellix-0.3.0.tgz
 ```
 
 独立 Profile 与更新命令见 [LOCAL_USAGE.md](LOCAL_USAGE.md)。
@@ -80,7 +89,7 @@ dsh plugin --profile web add ./dsh-modellix-0.2.0.tgz
 - 结果列表和每张卡片默认展开。
 - 点击 **结果** 收起整个列表；点击卡片头部只收起该卡片。
 - 点击 X 关闭，键盘焦点回到入口。
-- 高级精准参数编辑器保留在实现中，但 `0.2.0` 隐藏入口。
+- 高级精准参数编辑器保留在实现中，但 `0.3.0` 隐藏入口。
 
 ## 4. 通过对话创建媒体
 
@@ -223,7 +232,7 @@ Provider 使用 OpenAI 兼容接口，重试次数为 `0`；目录不可用时
 2. 需要页面全文时自动调用 `modellix_web_fetch`。
 3. 回答引用搜索/抓取来源。
 
-用户不需要说“使用 search/fetch”。若用户明确说不要浏览，Agent 不调用。路由上下文也会避免同一操作同时调用明确工具和原生 Provider 工具。
+用户不需要说“使用 search/fetch”。若用户明确说不要浏览，Agent 不调用。Modellix Web 开启时，路由上下文会避免同一操作同时调用两套工具；关闭时会移除两个明确工具及该路由上下文，当前 Profile 的原生 `web_search` / `web_fetch` 与 Provider 保持可用，Agent 可自动回退。
 
 ## 11. 设置与错误
 
@@ -231,7 +240,9 @@ Provider 使用 OpenAI 兼容接口，重试次数为 `0`；目录不可用时
 
 - **Design：** 控制媒体工具、对话结果卡和结果面板。
 - **LLM：** 控制 Modellix 实时模型物化。
-- **Web：** 控制 Modellix Search/Fetch Provider 与明确工具。
+- **Web：** 只控制明确的 Modellix Search/Fetch 工具及 Modellix 优先路由，不改变 Harness 原生 Web 工具或 Provider。
+
+三个开关彼此独立。保存一个服务的变化，不会注册、注销或重配另外两个服务。
 
 ### Credential 状态
 
@@ -269,6 +280,8 @@ Provider 使用 OpenAI 兼容接口，重试次数为 `0`；目录不可用时
 
 确认 Web 已开启，并检查当前 Agent 会话包含 `Web routing` 上下文。明确工具应显示为 `modellix_web_search` 与 `modellix_web_fetch`。
 
+若 Web 是有意关闭，两个明确工具与 Modellix `Web routing` 都不应出现；原生 `web_search` / `web_fetch` 按当前 Harness Profile 的配置继续工作。
+
 ### 提示模型 Schema 不可用
 
 刷新实时媒体目录，确认 `modellix_media_list` 返回的准确 slug，再调用 `modellix_media_schema`。解析器支持公开 OpenAPI 布局和受限共享引用；遇到不安全或不支持的结构时会阻止使用，而不是猜测。
@@ -279,11 +292,11 @@ Provider 使用 OpenAI 兼容接口，重试次数为 `0`；目录不可用时
 
 ### 同一任务出现两张卡
 
-`0.2.0` 不应出现。请在不包含 Secret 的情况下记录两张卡的 job id 和 tool call id。生成卡应赢得当前会话的任务展示权，匹配的结果查询卡应被抑制。
+`0.3.0` 不应出现。请在不包含 Secret 的情况下记录两张卡的 job id 和 tool call id。生成卡应赢得当前会话的任务展示权，匹配的结果查询卡应被抑制。
 
 ### 显示其他会话结果
 
-新建 `0.2.0` 任务不应出现。请记录受影响的 session/task id，并按会话隔离缺陷报告。
+新建 `0.3.0` 任务不应出现。请记录受影响的 session/task id，并按会话隔离缺陷报告。
 
 ### 媒体不能播放
 

package/lib/client.d.ts

@@ -1,5 +1,5 @@
 
-import { ClientContext } from "@deepseek-ai/dsh-client-runtime/client";
+import { Context } from "@deepseek-ai/cordis";
 
 //#region src/shared/design-presentation-codes.d.ts
 declare const DESIGN_NOTICE_CODES: readonly ["schema-unavailable", "schema-invalid", "catalog-stale", "catalog-unavailable", "credential-reloaded"];
@@ -221,7 +221,7 @@ type ModellixClientSlotDefinition = (typeof MODELLIX_CLIENT_SLOTS)[number];
 //#endregion
 //#region src/client/index.d.ts
 declare const inject: string[];
-declare function apply(ctx: ClientContext): void;
+declare function apply(ctx: Context): void;
 //#endregion
 export { AckWire, ClientJsonValue, CredentialDescriptorWire, CredentialVerificationWire, DesignDiagnosticWire, DesignDraftWire, DesignEnumOptionWire, DesignFieldWire, DesignJobWire, DesignModelWire, DesignMutationWire, DesignProposalChangeWire, DesignProposalWire, DesignResourceWire, DesignSnapshotWire, MODELLIX_CLIENT_SLOTS, MODELLIX_CLIENT_WIRE_VERSION, MODELLIX_RPC_CHANNEL, MODELLIX_RPC_ENDPOINTS, ModellixClientContractError, ModellixClientSlotDefinition, ModellixRpcEndpoint, ServiceTogglesWire, SettingsMutationWire, SettingsSnapshotWire, apply, inject, parseAck, parseDesignMutation, parseDesignSnapshot, parseSettingsMutation, parseSettingsSnapshot, safeResourceHref, sanitizeParameters };