dsh-primer 0.4.3 → 0.4.5

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/web-search-billing/guide.zh.md

@@ -0,0 +1,41 @@
+---
+kind: upgrade-guide
+description: "DeepSeek Search 与 Fetch 新增按能力选择的计费方式，并将提供方认证字段替换为有序凭据来源。"
+---
+
+# DeepSeek 网页搜索与获取按计费方式选择凭据
+
+[English](guide.md) | 中文
+
+## 变更
+
+DeepSeek Search 与 Fetch API（`web-deepseek-api`）过去只在 `deepseek-account` 会话中使用已登录账号；其他会话需要 API 密钥。新增的 `searchBilling` 与 `fetchBilling` 设置接受 `auto`（默认）、`account` 或 `api-key`。在 `auto` 下，DeepSeek 模型路由的行为不变；其他会话与会话之外的操作在没有密钥时改用已登录账号。`account` 只使用账号，`api-key` 只使用密钥。非空的 `*BaseURL` 或 `*ApiKeyEnv` 设置仍然优先。其他提供方（包括本地 HTTP 抓取）不受影响。
+
+在 TypeScript 中，`DeepSeekSearchApiOptions` 与 `DeepSeekFetchApiOptions` 移除了顶层 `baseURL`。其 `auth` 改为 `{ sources, missingCredentialMessage? }`。每个账号或 API 密钥来源携带自己的地址；列表顺序替代隐式的账号优先顺序。直接调用提供方构造函数的代码需要迁移。
+
+传入 `AbortSignal` 时，凭据读取错误现在保留原始 `Error` 作为 `cause`，诊断也保留其名称，不再额外包装一层 `Error:`。解析函数抛出名为 `AbortError` 的 DOMException 时，即使该 signal 未取消，现在也返回 `WEB_ABORTED`，而非 `WEB_PROVIDER_ERROR`。未传 signal 的路径原本就采用此行为。
+
+## 迁移
+
+1. 要禁用新增的账号回退，在 `web-deepseek-api` 行把两个能力都设为 `api-key`；也可以在**插件 > 内置插件配置 > 网页搜索与获取**中，选中相应的 DeepSeek API 后选择 **DeepSeek API Key**：
+
+   ```yaml
+   - name: '@deepseek-ai/dsh-web-deepseek-api'
+     config:
+       searchBilling: api-key
+       fetchBilling: api-key
+   ```
+
+   这也会禁用账号会话中的账号计费，并不能完全恢复原来按路由选择的行为。
+2. 迁移直接调用 `DeepSeekSearchApiProvider` 与 `DeepSeekFetchApiProvider` 构造函数的代码。下表描述 TypeScript 选项，而非 YAML 设置：
+
+   | 原选项 | 替换方式 |
+   |---|---|
+   | `baseURL: base`、`auth.apiKey: key` | `auth.sources: [{ kind: 'api-key', baseURL: base, key }]` |
+   | `auth.resolveApiKey`、`auth.apiKeyEnv` | API 密钥来源的 `key: { ref, configured, resolve }`。保留原引用（省略时为 `DEEPSEEK_API_KEY`）；`configured()` 只检查是否存在，不读取值，`resolve()` 读取值。 |
+   | `auth.account` | `{ kind: 'account', ...account }`；保留其地址和回调。放在 Key 来源之前可保留账号优先行为。 |
+   | `auth.missingKeyMessage` | `auth.missingCredentialMessage` |
+   | `auth.invalidRoute` | 在无效来源的位置放置 `{ kind: 'misconfigured', message }`；只有轮到该项才失败。 |
+
+3. 更新错误处理，将解析函数的 `AbortError` 识别为取消。不要依赖额外的错误包装层或其诊断前缀。
+4. 确认迁移后的构造代码通过类型检查。选中 DeepSeek API 并使用 `api-key` 计费时，缺少密钥会隐藏相应工具；配置密钥后可以发请求。本地 HTTP 抓取不受影响。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/window-drag-regions/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/window-drag-regions/guide.md
+/:
+  en: 3733ed8d0c40fb64
+  zh: f886cd8c61db2bd8
+/explicit-window-regions-for-custom-client-overlays:
+  en: bf86e50c82443b79
+  zh: 4b7a14fa9c3e60b7
+/explicit-window-regions-for-custom-client-overlays/change:
+  en: a3c55aed10fdeeb8
+  zh: dd628088de04631f
+/explicit-window-regions-for-custom-client-overlays/migration:
+  en: cb177bbf9687f49a
+  zh: c39c94a2d36416b2

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/window-drag-regions/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Custom Client overlays that relied on global macOS no-drag exclusions must declare their window regions."
+---
+
+# Explicit window regions for custom Client overlays
+
+English | [中文](guide.zh.md)
+
+## Change
+
+After upgrading from 0.2.2-rc.1, macOS Desktop automatically excludes interactive controls only inside `data-window-drag` rows or `data-window-drag-controls` scopes. Previously, matching controls and ARIA roles anywhere in the application received `no-drag`. Custom Client plugins that relied on that rule for content covering a draggable header must now declare an exclusion. Ordinary scrollable content without an explicit region declaration contributes no region, so content clipped above its viewport no longer blocks header dragging.
+
+This affects custom overlays outside those scopes that cover a drag row. Controls already inside a marked row, overlays using shared primitives with their own exclusions, and components with explicit `no-drag` declarations need no migration. The rule applies only to macOS Desktop; plain Web and Windows behavior is unchanged.
+
+## Migration
+
+1. Inspect the JSX and CSS Modules of custom Client overlays that can cover a header. Check whether their interactive content relied on the previous automatic exclusion.
+2. For an interactive viewport without nested drag rows, put `data-window-drag-exclude` on its visible viewport element. This excludes the viewport's own rectangle and keeps clipped descendants out of the region calculation. For a container whose controls need separate exclusions, put `data-window-drag-controls` on their containing element. Overlays and containers with nested drag rows must declare their regions separately; follow the [window-region rules](../../../../packages/client/web/README.md#understand-the-implementation).
+3. Keep exclusions on visible owners rather than every focusable descendant. Use a shared `Modal` or `MenuSurface` for the corresponding overlay, or explicitly exclude the custom overlay's visible box. A body portal with no layout box needs an exclusion on its visible content.
+4. Load the updated plugin in macOS Desktop. Open the overlay over a header and confirm its controls act without dragging the window. Close it and confirm the header's blank area still drags; scroll the plugin's content out of view and confirm that clipped content does not block the header.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/window-drag-regions/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "依赖 macOS 全局 no-drag 排除的自定义 Client 浮层必须声明自己的窗口区域。"
+---
+
+# 自定义 Client 浮层显式声明窗口区域
+
+[English](guide.md) | 中文
+
+## 变更
+
+从 0.2.2-rc.1 升级后，macOS Desktop 仅自动排除 `data-window-drag` 行或 `data-window-drag-controls` 范围内的交互控件。此前，应用中任意位置匹配的控件和 ARIA role 都会获得 `no-drag`。自定义 Client 插件若依赖该规则使覆盖可拖动页头的内容保持可交互，现在必须声明排除。未显式声明区域的普通滚动内容不贡献区域，因此被裁剪到视口上方的内容不会再阻挡页头拖动。
+
+该变更影响这些范围之外、覆盖拖动行的自定义浮层。已位于标记行内的控件、使用自带排除的共享原语的浮层，以及已显式声明 `no-drag` 的组件无需迁移。规则仅适用于 macOS Desktop，普通 Web 和 Windows 行为不变。
+
+## 迁移
+
+1. 检查可能覆盖页头的自定义 Client 浮层的 JSX 与 CSS Modules，确认其交互内容是否依赖此前的自动排除。
+2. 对不含嵌套拖动行的交互视口，在可见视口元素上添加 `data-window-drag-exclude`。它仅排除视口自身矩形，使被裁剪的子元素不参与区域计算。若容器内的控件需要分别排除，在承载这些控件的元素上添加 `data-window-drag-controls`。浮层和含嵌套拖动行的容器必须单独声明区域，遵循[窗口区域规则](../../../../packages/client/web/README.zh.md#understand-the-implementation)。
+3. 在可见区域所有者上声明排除，不要逐个排除可聚焦子元素。对应浮层采用共享 `Modal` 或 `MenuSurface`，或显式排除自定义浮层的可见矩形。不产生布局矩形的 body portal 需在可见内容上声明排除。
+4. 在 macOS Desktop 加载更新后的插件，将浮层打开到页头上方，确认其控件正常生效且不会拖动窗口。关闭浮层后确认页头空白区域仍可拖动；将插件内容滚出可见区，确认被裁剪内容不会阻挡页头。

package/references/official-docs/docs/user/develop/framework/events.i18n.yaml

@@ -33,8 +33,8 @@
   en: 18070de55501a230
   zh: 0a34d22dc2662599
 /event-system/cordis-events-and-session-records:
-  en: 93102b27250eea35
-  zh: a97a0197f785a4aa
+  en: 866ef8c0f99b2e8a
+  zh: 14c9b69b27ffd850
 /event-system/event-listeners-are-effects:
   en: b7cc96734661caef
   zh: 442ec0da611cf644

package/references/official-docs/docs/user/develop/framework/events.md

@@ -101,7 +101,7 @@ declare module '@deepseek-ai/cordis' {
 
 ## Cordis events and session records
 
-Harness Cordis events use `namespace/action` names, including `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/result`, and `session/event`. The generated `cordis-surface` regions on the [subsystem pages](../../../subsystems/core.md) record complete signatures and modes.
+Harness Cordis events use `namespace/action` names, including `agent/pre-step`, `agent/request-error`, `tools/result`, and `session/event`. The generated `cordis-surface` regions on the [subsystem pages](../../../subsystems/core.md) record complete signatures and modes.
 
 `turn/*`, `step/*`, `tool/call`, `tool/result`, and `compaction/*` are durable session-event types, not same-named Cordis events. To observe them, listen to `session/event` and inspect `event.type`.
 

package/references/official-docs/docs/user/develop/framework/events.zh.md

@@ -101,7 +101,7 @@ declare module '@deepseek-ai/cordis' {
 
 ## Cordis 事件与会话记录
 
-Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/pre-step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[子系统页面](../../../subsystems/core.zh.md)上生成的 `cordis-surface` 区块。
+Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/pre-step`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[子系统页面](../../../subsystems/core.zh.md)上生成的 `cordis-surface` 区块。
 
 `turn/*`、`step/*`、`tool/call`、`tool/result` 和 `compaction/*` 是持久化的会话事件类型，不是同名 Cordis 事件。需要观察它们时，监听 `session/event` 并检查 `event.type`。
 

package/references/official-docs/docs/user/develop/practice/dynamic-cordis.i18n.yaml

@@ -3,8 +3,8 @@
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/practice/dynamic-cordis.md
 /configure-persistent-plugins-from-a-prompt:
-  en: 9503745724cbe962
-  zh: 985513234a4eda31
+  en: d50e336357663f75
+  zh: 4364e91403387e2a
 /configure-persistent-plugins-from-a-prompt/connect-an-mcp-server:
   en: f9fefda94ba8a005
   zh: f1a9a977a0732fc0

package/references/official-docs/docs/user/develop/practice/dynamic-cordis.md

@@ -2,7 +2,7 @@
 
 English | [中文](dynamic-cordis.zh.md)
 
-Creator mode provides [Plugin Manager](../../../../packages/boot/plugin-manager/README.md) and read-only [runtime inspection](../../../../packages/extensions/tool-cordis/README.md). Plugin configuration belongs to the current profile, affects its sessions, and survives process restarts.
+Standard and Creator modes provide [Plugin Manager](../../../../packages/boot/plugin-manager/README.md); Creator mode adds read-only [runtime inspection](../../../../packages/extensions/tool-cordis/README.md). Plugin configuration belongs to the current profile, affects its sessions, and survives process restarts.
 
 ## Connect an MCP server
 

package/references/official-docs/docs/user/develop/practice/dynamic-cordis.zh.md

@@ -2,7 +2,7 @@
 
 [English](dynamic-cordis.md) | 中文
 
-创造模式提供 [Plugin Manager](../../../../packages/boot/plugin-manager/README.zh.md) 和只读[运行时检查](../../../../packages/extensions/tool-cordis/README.zh.md)。插件配置属于当前 profile，影响其会话，并在进程重启后保留。
+标准模式和创造模式提供 [Plugin Manager](../../../../packages/boot/plugin-manager/README.zh.md)；创造模式还提供只读[运行时检查](../../../../packages/extensions/tool-cordis/README.zh.md)。插件配置属于当前 profile，影响其会话，并在进程重启后保留。
 
 ## 连接 MCP 服务器
 

package/references/official-docs/docs/user/develop/practice/llm-adapter.i18n.yaml

@@ -30,5 +30,5 @@
   en: e05d4b0a901e8ef0
   zh: 9516cebb3e5c3692
 /llm-adapters/error-handling:
-  en: d54065c52caf7910
-  zh: 79b3ebc22a38286d
+  en: 08670c0bc7b8f494
+  zh: 37312af73d0acf91

package/references/official-docs/docs/user/develop/practice/llm-adapter.md

@@ -153,7 +153,7 @@ Compare the two shipped adapters to see the same harness contract implemented ov
 
 ## Error handling
 
-Adapters throw transport and protocol failures as `LlmError` values with stable codes. The agent loop preserves the error and code for diagnostics and policy; it does not convert an ordinary `Error` automatically. Every provider HTTP request must also merge `attributionHeaders()` and forward `options.signal`.
+Adapters throw transport and protocol failures as `LlmError` values with stable codes. `new LlmError` accepts only the built-in codes of `LLM_FAILURE_CODES`; an adapter's own code goes through `LlmError.fromFailure`. The agent loop preserves the error and code for diagnostics and policy; it does not convert an ordinary `Error` automatically. Every provider HTTP request must also merge `attributionHeaders()` and forward `options.signal`.
 
 ```ts
 import {
@@ -180,7 +180,7 @@ class HttpAdapter extends LlmAdapter {
       ...options.signal ? { signal: options.signal } : {},
     })
     if (!response.ok) {
-      throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
+      throw LlmError.fromFailure({ message: `Provider API error: ${response.status}`, code: 'PROVIDER_HTTP_ERROR', status: response.status })
     }
     // A real adapter parses the response and emits the complete chunk sequence.
     yield { type: 'finish', reason: { kind: 'stop' } }

package/references/official-docs/docs/user/develop/practice/llm-adapter.zh.md

@@ -153,7 +153,7 @@ ctx.llm.registerAdapter(['my-provider'], adapter)
 
 ## 错误处理
 
-适配器应通过带稳定 code 的 `LlmError` 抛出传输和协议故障；agent loop（智能体循环）会保留该错误及其 code，用于诊断和策略处理。不要依赖普通 `Error` 被自动转换。每个提供方 HTTP 请求还必须合并 `attributionHeaders()`，并传递 `options.signal`。
+适配器应通过带稳定 code 的 `LlmError` 抛出传输和协议故障。`new LlmError` 只接受 `LLM_FAILURE_CODES` 中的内置 code；适配器自己的 code 通过 `LlmError.fromFailure` 抛出。agent loop（智能体循环）会保留该错误及其 code，用于诊断和策略处理。不要依赖普通 `Error` 被自动转换。每个提供方 HTTP 请求还必须合并 `attributionHeaders()`，并传递 `options.signal`。
 
 ```ts
 import {
@@ -180,7 +180,7 @@ class HttpAdapter extends LlmAdapter {
       ...options.signal ? { signal: options.signal } : {},
     })
     if (!response.ok) {
-      throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
+      throw LlmError.fromFailure({ message: `Provider API error: ${response.status}`, code: 'PROVIDER_HTTP_ERROR', status: response.status })
     }
     // A real adapter parses the response and emits the complete chunk sequence.
     yield { type: 'finish', reason: { kind: 'stop' } }

package/references/official-docs/docs/user/guide/desktop-uninstall-cleanup.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for desktop-uninstall-cleanup.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/user/guide/desktop-uninstall-cleanup.md
+/uninstall-dsh-desktop:
+  en: bbd616011b211905
+  zh: 93b6146e97d9bb88
+/uninstall-dsh-desktop/1-uninstall-the-app:
+  en: 6ba6b5bc4153c3cd
+  zh: 36712b216d118155
+/uninstall-dsh-desktop/2-clean-up-local-data:
+  en: 459985c888cb631c
+  zh: 30771182f880e27b
+/uninstall-dsh-desktop/3-verify-cleanup:
+  en: 396bdba7cd24b278
+  zh: 2488dc9721081aee

package/references/official-docs/docs/user/guide/desktop-uninstall-cleanup.md

@@ -0,0 +1,60 @@
+# Uninstall DSH Desktop
+
+English | [中文](desktop-uninstall-cleanup.zh.md)
+
+Use this guide to uninstall DeepSeek Harness Desktop on macOS or Windows. Local data cleanup is optional.
+
+## 1. Uninstall the app
+
+Finish any commands using Desktop's bundled CLI. If you installed the `dsh` command through Desktop, first select **Manage dsh Command… → Remove** in the application menu. This removes Desktop's command registration without uninstalling independent CLI programs.
+
+Quit DeepSeek Harness, then uninstall it using your platform's procedure:
+
+- **macOS:** Delete the app from Applications in Finder.
+- **Windows:** Uninstall it through Settings → Apps → Installed apps on Windows 11, or Control Panel → Programs → Programs and Features.
+
+## 2. Clean up local data
+
+This step is optional. If you want to clean up local data, select the script for your platform below, then paste and run it in Terminal on macOS or PowerShell on Windows.
+
+The scripts permanently delete the current user's default Harness home and the Desktop data paths listed below, including sessions, credentials, settings, plugins, caches, and shared CLI state. If you configured `DSH_HOME`, inspect that directory separately before deleting it; the scripts still delete the default `~/.dsh`. Isolated development and test data directories are outside this cleanup scope.
+
+On Windows, the uninstaller normally removes the two application-data directories listed in the script but retains the Harness home. The script also handles those directories if uninstallation left files behind or retained app data.
+
+::: code-group
+
+```sh [macOS]
+sh -c '
+rm -rf -- \
+  "$HOME/.dsh" \
+  "$HOME/Library/Application Support/@deepseek-ai/dsh-desktop" \
+  "$HOME/Library/Logs/DeepSeek Harness" \
+  "$HOME/Library/Preferences/com.deepseek.dsh.plist" \
+  "$HOME/Library/Preferences/ByHost"/com.deepseek.dsh.ShipIt.*.plist \
+  "$HOME/Library/Caches/com.deepseek.dsh" \
+  "$HOME/Library/Caches/com.deepseek.dsh.ShipIt" \
+  "$HOME/Library/HTTPStorages/com.deepseek.dsh" \
+  "$HOME/Library/Caches/@deepseek-aidsh-desktop-updater" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh.helper"
+'
+```
+
+```powershell [Windows]
+$ErrorActionPreference = 'Stop'
+@(
+    (Join-Path $env:USERPROFILE '.dsh'),
+    (Join-Path $env:APPDATA '@deepseek-ai\dsh-desktop'),
+    (Join-Path $env:LOCALAPPDATA '@deepseek-aidsh-desktop-updater')
+) | ForEach-Object {
+    if (Test-Path -LiteralPath $_) {
+        Remove-Item -LiteralPath $_ -Recurse -Force
+    }
+}
+```
+
+:::
+
+## 3. Verify cleanup
+
+If you ran a cleanup script, confirm before reinstalling that the paths listed in it no longer exist. If the script reports an error, resolve it, rerun the script, and check all listed paths again. The Windows script stops at the first error, so later paths may remain.

package/references/official-docs/docs/user/guide/desktop-uninstall-cleanup.zh.md

@@ -0,0 +1,60 @@
+# 卸载 DSH 桌面端
+
+[English](desktop-uninstall-cleanup.md) | 中文
+
+本指南介绍如何在 macOS 或 Windows 上卸载 DeepSeek Harness 桌面端。清理本地数据是可选操作。
+
+## 1. 卸载应用
+
+先结束使用桌面端内置 CLI（命令行界面）的命令。如果曾通过 Desktop 安装 `dsh` 命令，请先在应用菜单中选择 **管理 dsh 命令… → 移除**。此操作移除桌面端的命令注册，不卸载独立安装的 CLI 程序。
+
+退出 DeepSeek Harness，然后按所在平台的方式卸载：
+
+- **macOS：** 在 Finder 的“应用程序”中删除应用。
+- **Windows：** 在 Windows 11 的“设置 → 应用 → 已安装的应用”，或“控制面板 → 程序 → 程序和功能”中卸载。
+
+## 2. 清理本地数据
+
+此步骤为可选操作。如果需要清理本地数据，请选择下方对应平台的脚本，在 macOS 的终端或 Windows 的 PowerShell 中粘贴运行。
+
+脚本会永久删除当前用户默认的 Harness 主目录及下方列出的 Desktop 数据路径，包括会话、凭据、设置、插件、缓存和与 CLI 共用的状态。如果配置了 `DSH_HOME`，删除前请单独检查该目录；脚本仍会删除默认的 `~/.dsh`。隔离的开发和测试数据目录不在此清理范围内。
+
+Windows 卸载程序通常会删除脚本中列出的两个应用数据目录，但保留 Harness 主目录。若卸载时有文件残留或保留了应用数据，脚本也会清理这些目录。
+
+::: code-group
+
+```sh [macOS]
+sh -c '
+rm -rf -- \
+  "$HOME/.dsh" \
+  "$HOME/Library/Application Support/@deepseek-ai/dsh-desktop" \
+  "$HOME/Library/Logs/DeepSeek Harness" \
+  "$HOME/Library/Preferences/com.deepseek.dsh.plist" \
+  "$HOME/Library/Preferences/ByHost"/com.deepseek.dsh.ShipIt.*.plist \
+  "$HOME/Library/Caches/com.deepseek.dsh" \
+  "$HOME/Library/Caches/com.deepseek.dsh.ShipIt" \
+  "$HOME/Library/HTTPStorages/com.deepseek.dsh" \
+  "$HOME/Library/Caches/@deepseek-aidsh-desktop-updater" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh.helper"
+'
+```
+
+```powershell [Windows]
+$ErrorActionPreference = 'Stop'
+@(
+    (Join-Path $env:USERPROFILE '.dsh'),
+    (Join-Path $env:APPDATA '@deepseek-ai\dsh-desktop'),
+    (Join-Path $env:LOCALAPPDATA '@deepseek-aidsh-desktop-updater')
+) | ForEach-Object {
+    if (Test-Path -LiteralPath $_) {
+        Remove-Item -LiteralPath $_ -Recurse -Force
+    }
+}
+```
+
+:::
+
+## 3. 验证清理结果
+
+如果运行了清理脚本，请在重新安装前确认脚本中列出的路径已不存在。如果脚本报错，请解决错误后重跑脚本，再次检查所有列出的路径。Windows 脚本会在首次报错时停止，后续路径可能仍未清理。

package/references/official-docs/docs/user/guide/index.i18n.yaml

@@ -15,5 +15,5 @@
   en: e1cb5a05bf6e109d
   zh: 8b181b0fecbc0517
 /use-the-web-ui/continue:
-  en: 6b244134309ca89c
-  zh: 971fa14939d88c6b
+  en: c28740683d2d9a01
+  zh: daf20f18e20be97f

package/references/official-docs/docs/user/guide/index.md

@@ -27,5 +27,6 @@ The agent can read and edit workspace files, run commands, delegate work, and ma
 - [Configure models](./providers.md)
 - [Use the Python SDK](./python-sdk.md)
 - [Publish the Web UI behind a reverse proxy](./public-deployments.md)
+- [Uninstall DSH Desktop](./desktop-uninstall-cleanup.md)
 - [Use other CLI modes](../../../apps/cli/README.md)
 - [Develop a plugin](../develop/basic/index.md)

package/references/official-docs/docs/user/guide/index.zh.md

@@ -27,5 +27,6 @@ Agent（智能体）可以读取和编辑工作区文件、运行命令、委派
 - [配置模型](./providers.zh.md)
 - [使用 Python SDK](./python-sdk.zh.md)
 - [在反向代理之后发布 Web UI](./public-deployments.zh.md)
+- [卸载 DSH 桌面端](./desktop-uninstall-cleanup.zh.md)
 - [使用其他 CLI 模式](../../../apps/cli/README.zh.md)
 - [开发插件](../develop/basic/index.zh.md)

package/references/official-docs/docs/user/guide/network-proxy.i18n.yaml

@@ -15,8 +15,8 @@
   en: 307f5b01e6e09661
   zh: 39eccb0287afc128
 /run-dsh-behind-a-network-proxy/limits-worth-knowing:
-  en: d0defd7e52100d1f
-  zh: 50f38176e16f55e4
+  en: a2d2a969d1a76624
+  zh: 83b06f86d6002275
 /run-dsh-behind-a-network-proxy/what-stays-direct:
   en: 34b04f98af3e09ae
   zh: 4c530b755b552942

package/references/official-docs/docs/user/guide/network-proxy.md

@@ -57,7 +57,7 @@ export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
 
 Node reads that variable only at process start, so export it before running `dsh`.
 
-**Tools DSH runs for you follow the same proxy.** Commands in the bash tool, `git`, `gh`, and MCP servers started as child processes all inherit these variables. A child that is itself a Node program honors them only on Node 22.21 or later; an older Node connects directly. If one of your proxy variables holds a value DSH rejected — a SOCKS URL, say — Node-based tools also connect directly rather than fail to start, while `curl` and `git` still read that value.
+**Tools DSH runs for you follow the same proxy.** Commands in the bash tool, `git`, `gh`, and MCP servers started as child processes all inherit these variables. A child Node program uses its own installed runtime: Node 22.21+ and Node 24+ honor these variables; an older runtime connects directly. If one of your proxy variables holds a value DSH rejected — a SOCKS URL, say — Node-based tools also connect directly rather than fail to start, while `curl` and `git` still read that value.
 
 **A password in the proxy URL reaches those tools too.** `HTTPS_PROXY=http://alice:s3cret@proxy.example:8080` is a normal environment variable, so every command DSH runs — including the ones the model writes — can read it, and a command that prints its environment puts the password in output that is kept. This is how the variable already behaves for everything else in your shell. If that matters, give the proxy a credential-free entry point, or authenticate it some other way than in the URL.
 

package/references/official-docs/docs/user/guide/network-proxy.zh.md

@@ -57,7 +57,7 @@ export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
 
 Node 只在进程启动时读取该变量，所以要在运行 `dsh` 之前导出。
 
-**DSH 替你运行的工具遵循同一个代理。** bash 工具里的命令、`git`、`gh`，以及作为子进程启动的 MCP 服务器都会继承这些变量。子进程若本身是 Node 程序，则需 Node 22.21 或更高版本才会遵循；更旧的 Node 会直连。如果你的某个代理变量是 DSH 拒绝的值——比如 SOCKS URL——基于 Node 的工具同样直连而不是起不来，`curl` 与 `git` 则仍会读取那个值。
+**DSH 替你运行的工具遵循同一个代理。** bash 工具里的命令、`git`、`gh`，以及作为子进程启动的 MCP 服务器都会继承这些变量。Node 子程序使用自己安装的运行时：Node 22.21+ 和 Node 24+ 遵循这些变量；更旧的运行时会直连。如果你的某个代理变量是 DSH 拒绝的值——比如 SOCKS URL——基于 Node 的工具同样直连而不是起不来，`curl` 与 `git` 则仍会读取那个值。
 
 **代理 URL 里的密码同样会到达这些工具。** `HTTPS_PROXY=http://alice:s3cret@proxy.example:8080` 就是一个普通环境变量，因此 DSH 运行的每一条命令——包括模型编写的那些——都能读到它，而打印环境的命令会把密码写进被保留的输出。这与该变量在你 shell 里对其他一切程序的行为一致。若这一点重要，请为代理提供一个无需凭据的入口，或改用 URL 之外的方式认证。
 

package/references/official-docs/docs/user/guide/plugin-market.i18n.yaml

@@ -2,33 +2,33 @@
 # section, a hash of its English and Chinese blocks outside code blocks and generated regions.
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/plugin-market.md
-/plugin-markets:
-  en: 09b2a6328dcae63c
-  zh: ac7bce767e4f5011
-/plugin-markets/summary:
-  en: 2716b194b8a12aa7
-  zh: b90773d095851969
-/plugin-markets/table-of-contents:
+/plugin-indexes:
+  en: 5ee6a364e2708ab9
+  zh: 369781529be73628
+/plugin-indexes/summary:
+  en: a1d8f17e7c4b8357
+  zh: 13b95dcedde344f2
+/plugin-indexes/table-of-contents:
   en: a8d1e6785c3c3c30
   zh: 7ea1eaa8204a5a1e
-/plugin-markets/turn-on-discover:
-  en: 96b2fd994f8f3e7e
-  zh: 203e8460ec6aed7a
-/plugin-markets/browse-and-install:
-  en: cf616bba26958533
-  zh: 1e32df16a6f4bba7
-/plugin-markets/publish-an-index:
+/plugin-indexes/turn-on-discover:
+  en: f98bc0913d4bd046
+  zh: 104094714786507e
+/plugin-indexes/browse-and-install:
+  en: 0f5a4082d5debe9b
+  zh: c0e53f186cb31cd4
+/plugin-indexes/publish-an-index:
   en: b85b82b22c1e14b8
   zh: 920c0d6f20956c07
-/plugin-markets/generate-an-index-with-the-reference-generator:
-  en: 57a48912c00e1c85
-  zh: 69f2934eed0fbadf
-/plugin-markets/index-format-reference:
-  en: d058d12c27433f64
-  zh: f43b85e4934817f3
-/plugin-markets/further-exploration:
-  en: 3c0a90e8bf73c89b
-  zh: 95608eb4f6278cb4
-/plugin-markets/dev-note:
+/plugin-indexes/generate-an-index-with-the-reference-generator:
+  en: c4326a91313ddb75
+  zh: 02455354b61e0d79
+/plugin-indexes/index-format-reference:
+  en: 49a19adfe82d8244
+  zh: 2d744c3e225ed181
+/plugin-indexes/further-exploration:
+  en: 2223e92806e7e79a
+  zh: 093309e1c40caa6c
+/plugin-indexes/dev-note:
   en: b75c8458928b72b9
   zh: 003ba4e17b4b5269

package/references/official-docs/docs/user/guide/plugin-market.md

@@ -1,10 +1,10 @@
-# Plugin markets
+# Plugin indexes
 
 English | [中文](plugin-market.zh.md)
 
 ## Summary
 
-A plugin market is one JSON index file that lists installable DSH bundles with their titles, icons, authors, and versions. Turn on the experimental **Custom plugin markets** bundle to browse markets in a **Discover** tab on the Plugins page and install a listed version after a confirmation. To publish a market, write or generate an index file and serve it, together with its icon files, from any static host.
+A plugin index is one JSON file that lists installable DSH bundles with their titles, icons, authors, and versions. Turn on the experimental **Custom plugin indexes** bundle to browse indexes in a **Discover** tab on the Plugins page and install a listed version after a confirmation. To publish an index, write or generate an index file and serve it, together with its icon files, from any static host.
 
 ## Table of Contents
 
@@ -18,20 +18,20 @@ A plugin market is one JSON index file that lists installable DSH bundles with t
 <a id="turn-on"></a>
 ## Turn on Discover
 
-Open **Plugins**, select **More** beside **Experimental plugins**, find **Custom plugin markets**, and switch it on. A **Discover** tab appears next to **Installed**, and Creator mode gains the read-only `plugin_market` tool. Switching the bundle off removes both again.
+Open **Plugins**, find **Custom plugin indexes** under **Experimental plugins**, and switch it on. A **Discover** tab appears next to **Installed**, and Creator mode gains the read-only `plugin_market` tool. Switching the bundle off removes both again.
 
-DSH ships no index source. Select **Discover**, choose **Add index source**, and enter the URL of an index file. A URL must use `http:` or `https:` and must not contain a user name, password, or `#` fragment. Anyone on the network path can change an `http:` index, including the install specs it lists, so use `https:` for a market reached over a network you do not control. Each source belongs to the current profile.
+DSH ships no index source. Select **Discover**, choose **Add index source**, and enter the URL of an index file. A URL must use `http:` or `https:` and must not contain a user name, password, or `#` fragment. Anyone on the network path can change an `http:` index, including the install specs it lists, so use `https:` for an index reached over a network you do not control. Each source belongs to the current profile.
 
 <a id="browse-and-install"></a>
 ## Browse and install
 
-The market menu at the left of the toolbar switches between sources and opens **Manage index sources…**, where each source shows its last error. Search matches names, authors, keywords, and titles, descriptions, categories, and labels in every language, and tolerates typos; results come in best-match order until you choose another. The **Labels** menu, category pills, and **Sort** menu use the categories, labels, and sort keys that the market declares, and **Publish date** sorts by each plugin's latest version.
+The index menu at the left of the toolbar switches between sources and opens **Manage index sources…**, where each source shows its last error. Search matches names, authors, keywords, and titles, descriptions, categories, and labels in every language, and tolerates typos; results come in best-match order until you choose another. The **Labels** menu, category pills, and **Sort** menu use the categories, labels, and sort keys that the index declares, and **Publish date** sorts by each plugin's latest version.
 
 Each card shows the plugin's recommended version: the highest version compatible with the running DSH that is not a prerelease, or the highest compatible prerelease when the plugin lists no version without a prerelease tag. **Install** opens a confirmation with that version's source: the npm package and registry, or the Git repository, commit, and directory. Confirming starts the normal plugin installation, including its compatibility and registry checks; nothing is installed without that confirmation.
 
 Select a card to open its page. The **Versions** list shows every listed version with its compatibility and offers **Install** for any version DSH accepts, including older releases and prereleases. A card that shows **Installed**, **Update available**, or **Provided by DSH** opens the installed bundle instead.
 
-Markets are third-party content. A market chooses each plugin's title, description, icon, author, and source; DSH checks the file format but not those claims. Add only sources you trust, and check the source in the confirmation before installing.
+Indexes are third-party content. An index chooses each plugin's title, description, icon, author, and source; DSH checks the file format but not those claims. Add only sources you trust, and check the source in the confirmation before installing.
 
 <a id="publish-an-index"></a>
 ## Publish an index
@@ -97,22 +97,22 @@ Run it from a DSH checkout:
 pnpm --filter @deepseek-ai/dsh-plugin-market-generator start --input plugins.txt --output site/index.json --title "Team plugins"
 ```
 
-For an npm package, the index lists every version that is not deprecated and declares `dsh.bundle`. For a Git repository, it finds the bundle packages on the default branch and lists their versions at `vX.Y.Z`, `X.Y.Z`, and `<name>@X.Y.Z` tags, plus each package's version on the default branch. Titles, descriptions, icons, authors, and homepages come from each plugin's highest version. Paths are relative to the directory where you run pnpm.
+For an npm package, the index lists every version that is neither deprecated nor private and declares `dsh.bundle`. For a Git repository, it finds the bundle packages on the default branch whose `package.json` does not set `"private": true` and lists their versions at `vX.Y.Z`, `X.Y.Z`, and `<name>@X.Y.Z` tags, plus each package's version on the default branch. Titles, descriptions, icons, authors, and homepages come from each plugin's highest version. Paths are relative to the directory where you run pnpm.
 
-The generator only downloads and reads files; it never installs packages or runs their code. It keeps a cache in `.plugin-market-cache` next to the list, so a repeated run downloads only new versions and commits. Publish the output directory, `index.json` together with its `icons/` directory, as described above.
+The generator only downloads and reads files; it never installs packages or runs their code. It keeps package data in `.plugin-market-cache` next to the list and reuses unchanged versions and commits. Each run still reads source documents or Git refs and refreshes enabled metrics; unavailable metric values are omitted. Set `GITHUB_TOKEN` to collect GitHub stars; without a nonblank token, GitHub metric requests and `github_stars` are omitted while npm weekly downloads remain enabled. Publish the output directory, `index.json` together with its `icons/` directory, as described above.
 
 <a id="index-format"></a>
 ## Index format reference
 
-Text fields marked `LocalizedText` are a string or an object of strings keyed by lowercase language ids, such as `{ "en": "Foo", "zh": "甲" }`; an object must contain `en`. Members DSH does not know are ignored.
+Text fields marked `LocalizedText` are a string or an object of strings keyed by lowercase language ids, such as `{ "en": "Foo", "zh": "甲" }`; an object must contain `en`. DSH ignores unknown object fields at every level. Known fields and `source.type` still require valid values; keys inside declaration, localized-text, and plugin sort-value maps are validated as data.
 
 | Index field | Required | Meaning |
 |---|---|---|
 | `format` | yes | `1`. |
-| `title`, `description` | `title` only | Market name and description, `LocalizedText`. |
+| `title`, `description` | `title` only | Index name and description, `LocalizedText`. |
 | `metadata.categories`, `metadata.labels` | no | Objects mapping an id to `{ "title": LocalizedText }`. |
 | `metadata.sortKeys` | no | Object mapping an id to `{ "title": LocalizedText, "order": "asc" \| "desc" }`; `order` is the initial direction. |
-| `plugins` | yes | Plugins in the market's default order. |
+| `plugins` | yes | Plugins in the publisher's default order; clients must preserve this array order on initial display and when filtering, unless the user chooses another sort or text search ranks by relevance. |
 
 | Plugin field | Required | Meaning |
 |---|---|---|
@@ -124,9 +124,11 @@ Text fields marked `LocalizedText` are a string or an object of strings keyed by
 | `repository` | no | `{ "url": string, "directory"?: string }`: the source repository's web page, and the package directory inside it. The plugin page links it as **Source code**. |
 | `metadata.category` | no | One declared category id. |
 | `metadata.labels` | no | Declared label ids. |
-| `metadata.sortKeys` | no | Object mapping declared sort-key ids to numbers, such as downloads or ratings. |
+| `metadata.sortKeys` | no | Object mapping declared sort-key ids to finite numbers, or `null` when unavailable. |
 | `versions` | yes | At least one version, in any order. |
 
+A plugin may omit `metadata`, any of its fields, or individual sort values, or use `null` for unavailable data. Missing values sort last in both directions; a real zero is a value, not missing data. The recommended definitions standardize `github_stars` as a repository's GitHub star count and `npm_weekly_downloads` as a public npm package's download count over npm's `last-week` window. Both are non-negative integers; weekly downloads are not a monthly count. Publishers using these keys declare them under root `metadata.sortKeys` and populate available values under each plugin's `metadata.sortKeys`. Other declared numeric keys remain supported.
+
 | Version field | Required | Meaning |
 |---|---|---|
 | `version` | yes | Exact SemVer version, unique within the plugin. |
@@ -140,7 +142,7 @@ DSH installs an npm version as `name@version`, asking `registry` first when pres
 ## Further Exploration
 
 - [Discover tab reference](../../../packages/client/ui-plugin-market/README.md) describes the tab's controls and states.
-- [Plugin market service](../../../packages/boot/plugin-market/README.md) covers fetch limits, caching, and the `plugin_market` tool.
+- [Plugin index service](../../../packages/boot/plugin-market/README.md) covers fetch limits, caching, and the `plugin_market` tool.
 - [Index validator](../../../packages/util/plugin-market-index/README.md) is the library generators can use to check an index before publishing it.
 
 ## Dev Note