dsh-plugin-dev-kb 1.4.0 → 1.5.2

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/tool-presentation-mode/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "工具呈现方式仅接受 native 或 ptc；混合的 both 模式会被拒绝。"
+---
+
+# 选择原生或 PTC 工具呈现方式
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-tools` 和 `@deepseek-ai/dsh-agent-tool-presentation` 的 `mode` 字段仅接受 `native` 或 `ptc`。`both` 值会被拒绝。这也影响 `DSH_TOOLS_MODE=both`，该环境变量通过随附的 profile 补丁提供工具配置。
+
+`native` 将可见工具公开为直接函数调用。`ptc` 公开 `run_code`，程序通过生成的 SDK 调用可见工具。同一应用中的不同 agent preset 仍可使用不同模式。
+
+## 迁移
+
+1. 在 `cordis.yml`、profile 的 `cordis.patch.yml` 或自定义覆盖文件中，将 `mode: both` 替换为用于直接调用的 `mode: native`，或用于程序调用的 `mode: ptc`。
+2. 将 `DSH_TOOLS_MODE=both` 替换为 `DSH_TOOLS_MODE=native` 或 `DSH_TOOLS_MODE=ptc`。若需按 preset 选择，请改为更新该 preset 的 `@deepseek-ai/dsh-agent-tool-presentation` 行。
+3. 将调用 `ctx.tools.presentAs('both')` 的代码改为选择 `native` 或 `ptc`。在 PTC 程序中，将调用保留在 `run_code` 内；不要将 SDK 函数名称作为模型的直接工具调用发出。
+4. 启动受影响的 profile，确认配置可加载。原生请求公开获准的直接工具；PTC 请求公开 `run_code` 及其 SDK 说明。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/web-listener-trust-config/guide.md

@@ -0,0 +1,36 @@
+---
+kind: upgrade-guide
+description: "The Web profile replaces the `webRuntime` service and the `web-runtime` row's `trustedHosts` config with `webStartup`, and rejects a wildcard listener host."
+---
+
+# Web listener and trust configuration moves to `webStartup`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Web profile no longer provides the `webRuntime` service, and the `web-runtime` row no longer declares a `trustedHosts` config value. A profile, overlay, or `--patch` file that injects `webRuntime` now waits for a service that never mounts, and an expression reading `ctx.webRuntime.trustedHosts` fails to evaluate, so the required Connection cannot start.
+
+The `web-startup` row provides one `webStartup` service carrying the invocation's `--trusted-host` authorities, and the `connection` row reads them from `ctx.webStartup.trustedHosts`. The listener host must also be one concrete IPv4 or IPv6 address of a local interface: `host: 0.0.0.0`, `--host ::`, and every other unspecified address are rejected at load, because binding every interface exposes the port to the network.
+
+## Migration
+
+1. Replace `inject: [webRuntime]` with `inject: [webStartup]` on every row that needs invocation trust.
+2. Replace `ctx.webRuntime.trustedHosts` expressions with `ctx.webStartup.trustedHosts`, and drop `ctx.webRuntime.lanAddresses`, which no longer exists.
+3. Rewrite the `connection` overlay for `webStartup`, and move any `trustedHosts` value that the `web-runtime` row carried into its expression. A patch replaces the matched row's whole `config`, so restate that config completely, and write an array-valued `!!js` expression as a quoted scalar:
+
+   ```yaml
+   # before
+   - id: connection
+     inject: [webRuntime]
+     config:
+       trustedHosts: !!js "['app.internal', ...ctx.webRuntime.trustedHosts]"
+   # after
+   - id: connection
+     inject: [webStartup]
+     config:
+       trustedHosts: !!js "['app.internal', ...ctx.webStartup.trustedHosts]"
+   ```
+
+4. Replace a wildcard `host` with one concrete address of a local interface. The bind IP itself is accepted by the Host fence with no `--trusted-host` entry; a proxy or DNS authority still needs one.
+5. Boot with the migrated overlay: `dsh --profile web --patch ./extra.yml --no-open` must print the `dsh web:` URL line and serve. A row still waiting on `webRuntime` leaves the required Connection pending and reports an activation failure, and a rejected `host` fails at load. `dsh --profile web --patch ./extra.yml --dump-config` prints the composed patch before boot. [The Web bundle README](../../../../packages/bundle/web-app/README.md) owns the composed rows.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/web-listener-trust-config/guide.zh.md

@@ -0,0 +1,36 @@
+---
+kind: upgrade-guide
+description: "Web profile 用 `webStartup` 取代 `webRuntime` 服务与 `web-runtime` 行的 `trustedHosts` 配置，并拒绝通配监听地址。"
+---
+
+# Web 监听与信任配置迁移到 `webStartup`
+
+[English](guide.md) | 中文
+
+## 变更
+
+Web profile 不再提供 `webRuntime` 服务，`web-runtime` 行也不再声明 `trustedHosts` 配置值。仍注入 `webRuntime` 的 profile、overlay 或 `--patch` 文件会等待一个永不挂载的服务，读取 `ctx.webRuntime.trustedHosts` 的表达式则会求值失败，导致必需的 Connection 无法启动。
+
+`web-startup` 行提供唯一的 `webStartup` 服务，携带本次调用的 `--trusted-host` authority；`connection` 行通过 `ctx.webStartup.trustedHosts` 读取它们。监听 host 现在也必须是本机网卡的一个具体 IPv4 或 IPv6 地址：`host: 0.0.0.0`、`--host ::` 及其他未指定地址都会在加载时被拒绝，因为绑定所有接口会把端口暴露到网络。
+
+## 迁移
+
+1. 将所有需要调用信任的行的 `inject: [webRuntime]` 换成 `inject: [webStartup]`。
+2. 将 `ctx.webRuntime.trustedHosts` 表达式换成 `ctx.webStartup.trustedHosts`，并删除已不存在的 `ctx.webRuntime.lanAddresses`。
+3. 按 `webStartup` 改写 `connection` overlay，并把原先由 `web-runtime` 行携带的 `trustedHosts` 值并入其表达式。patch 会整体替换所匹配行的 `config`，因此必须完整重述该配置；数组值的 `!!js` 表达式要写成带引号的标量：
+
+   ```yaml
+   # before
+   - id: connection
+     inject: [webRuntime]
+     config:
+       trustedHosts: !!js "['app.internal', ...ctx.webRuntime.trustedHosts]"
+   # after
+   - id: connection
+     inject: [webStartup]
+     config:
+       trustedHosts: !!js "['app.internal', ...ctx.webStartup.trustedHosts]"
+   ```
+
+4. 将通配 `host` 换成本机网卡的一个具体地址。所绑定的 IP 会被 Host 栅栏直接接受，无需 `--trusted-host`；代理或 DNS authority 仍需显式配置。
+5. 使用迁移后的 overlay 启动：`dsh --profile web --patch ./extra.yml --no-open` 必须打印 `dsh web:` URL 行并正常服务。仍在等待 `webRuntime` 的行会让必需的 Connection 保持 pending 并报告激活失败；被拒绝的 `host` 会在加载时失败。`dsh --profile web --patch ./extra.yml --dump-config` 可在启动前打印组合后的 patch。[Web 组合包 README](../../../../packages/bundle/web-app/README.zh.md)说明这些行。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/working-directory/guide.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "Session working directories replace built-in cwd configuration, and tool presentation metadata also runs for nested PTC calls."
+---
+
+# Migrate working-directory configuration and tool presentation
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The next release removes the loop's built-in `{{cwd}}` prompt variable and the `cwd` configuration key from `@deepseek-ai/dsh-subagent-acp` and `@deepseek-ai/dsh-subagent-dsh-sdk`. Custom prompt templates that retain an unresolved `{{cwd}}` fail before a model request. A Session's current execution directory is supplied as required user context and is persisted separately from its original `Session.header.cwd`.
+
+New subagents use their start request's `cwd` when provided, otherwise they capture the parent's current directory. Existing processes keep their own directories. Changing the execution directory does not change the original project or grant additional write permissions.
+
+Tool `output.presentationMeta` also runs for successful nested PTC calls. Authors whose projection assumes only native top-level calls are affected. A projection error fails that nested call with `ToolOutputError`; canonical program values and model content remain unchanged.
+
+## Migration
+
+1. In home, profile, or invocation `personaSuffix` configuration and preset `suffix` fields, remove the directory clause that references `{{cwd}}`, retaining unrelated text. Omit or clear a suffix that becomes empty. The [working-directory service](../../../../packages/session/working-directory/README.md) supplies the directory context.
+2. Remove `config.cwd` from ACP and DSH-SDK subagent provider rows in your profile patches. To select a directory for one child, pass `cwd` in its [start request](../../../subsystems/subagent.md). To change the parent's execution directory, use `working_directory({ cd: "/absolute/project" })` before starting the child.
+3. Run `working_directory({})` in the affected Session and confirm the reported directory. Start a child without an override and check its execution directory; use an explicit start `cwd` when the child must use another checkout. Read `Session.header.cwd` only for original project identity or permission roots, rather than current-directory operations.
+4. Keep custom `output.presentationMeta` projections pure and return JSON-safe metadata from their arguments and canonical result. Exercise both a native call and a nested PTC call, and confirm the recorded metadata identifies the operation's actual target without changing its result.
+
+Dynamic context providers are evaluated again at request admission, after pre-step listeners and route preparation. Return current state without relying on one evaluation per step. Transform registered context inside its provider; admission refresh replaces its cached text while preserving assembly-only context contributions and the accepted system prompt, tool schemas, and variables.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/working-directory/guide.zh.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "Session 工作目录替代内置 cwd 配置，工具展示元数据也会在嵌套 PTC 调用中生成。"
+---
+
+# 迁移工作目录配置与工具展示
+
+[English](guide.md) | 中文
+
+## 变更
+
+下一版本移除 loop 的内置 `{{cwd}}` 提示词变量，以及 `@deepseek-ai/dsh-subagent-acp` 和 `@deepseek-ai/dsh-subagent-dsh-sdk` 的 `cwd` 配置键。自定义提示词模板保留未解析的 `{{cwd}}` 时，会在模型请求发出前失败。Session 当前执行目录作为必需的 user context 提供，并与原始 `Session.header.cwd` 分开持久化。
+
+新子代理使用启动请求中显式提供的 `cwd`，未提供时捕获父代理的当前目录。已有进程保留各自的目录。切换执行目录不会改变原始项目，也不会授予额外写权限。
+
+工具 `output.presentationMeta` 也会在成功的嵌套 PTC 调用中运行。投影仅假设原生顶层调用的作者需要调整实现。投影异常会使该次嵌套调用以 `ToolOutputError` 失败；程序读取的规范值与模型内容不变。
+
+## 迁移
+
+1. 在 home、profile 或本次调用的 `personaSuffix` 配置，以及 preset 的 `suffix` 字段中，移除引用 `{{cwd}}` 的目录语句，保留其他文本。suffix 变为空时省略或清空该字段。[工作目录服务](../../../../packages/session/working-directory/README.zh.md)负责提供目录上下文。
+2. 从 profile patch 中的 ACP 与 DSH-SDK 子代理 provider 行移除 `config.cwd`。为单个子代理选择目录时，在其[启动请求](../../../subsystems/subagent.zh.md)中传入 `cwd`。改变父代理执行目录时，先调用 `working_directory({ cd: "/absolute/project" })`，再启动子代理。
+3. 在相关 Session 中调用 `working_directory({})` 并确认报告的目录。启动一个不带目录覆盖的子代理并检查其执行目录；子代理需要另一个 checkout 时，显式提供启动 `cwd`。仅用 `Session.header.cwd` 读取原始项目标识或权限根目录，当前目录操作使用工作目录服务。
+4. 保持自定义 `output.presentationMeta` 投影纯净，并从调用参数和规范结果返回可用于 JSON 的元数据。分别执行原生调用和嵌套 PTC 调用，确认记录的元数据指向操作的实际目标，同时不改变调用结果。
+
+动态上下文 provider 会在请求准入时再次求值，晚于 pre-step 监听器与路由准备。返回当前状态，不依赖每个步骤只求值一次。对已注册上下文的转换应在其 provider 内完成；准入刷新会替换缓存文本，同时保留仅由组装添加的上下文，以及已接纳的系统提示词、工具 schema 与变量。

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/deepseek-account-identity-watch/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "DeepSeekAccount.watch no longer includes Platform identity changes unless explicitly requested."
+---
+
+# Explicitly subscribe to account identity changes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The public `DeepSeekAccount.watch(signal)` method previously emitted a snapshot when a profile read first supplied or changed the cached Platform user ID. It now emits account-state changes only by default. Plugins that use this stream to refresh `getPlatformSession()` must opt into identity changes. Credential replacement and sign-in state changes still notify every subscriber.
+
+## Migration
+
+1. Find calls to `deepseekAccount.watch(signal)` in plugins that refresh the Platform session or synchronize its user ID.
+2. Change those calls to `deepseekAccount.watch(signal, true)`. Leave account UI subscriptions that only need sign-in and credential state unchanged.
+3. Confirm that a ready `getProfile()` result whose user ID first appears or changes wakes the subscription and causes it to re-read `getPlatformSession()`. Repeated reads with the same ID do not emit another identity notification.

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/deepseek-account-identity-watch/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "DeepSeekAccount.watch 默认不再通知 Platform 身份变化，订阅者必须显式启用。"
+---
+
+# 显式订阅账号身份变化
+
+[English](guide.md) | 中文
+
+## 变更
+
+公开方法 `DeepSeekAccount.watch(signal)` 原先会在资料查询首次补齐或改变缓存的 Platform 用户 ID 时发出快照。现在默认仅通知账号状态变化。通过该流刷新 `getPlatformSession()` 的插件必须显式订阅身份变化。凭证替换和登录状态变化仍会通知所有订阅者。
+
+## 迁移
+
+1. 在刷新 Platform 会话或同步其用户 ID 的插件中查找 `deepseekAccount.watch(signal)` 调用。
+2. 将这些调用改为 `deepseekAccount.watch(signal, true)`。只需要登录和凭证状态的账号界面订阅保持不变。
+3. 确认 `getProfile()` 返回 ready 结果且用户 ID 首次出现或变化时，订阅被唤醒并重新读取 `getPlatformSession()`。重复读取同一 ID 不会再次发出身份通知。

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/deepseek-account-model-catalog/guide.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "The DeepSeek account route no longer accepts a models catalog; the account listing supplies its models and modelOverrides adjusts them."
+---
+
+# DeepSeek account models come from the account listing
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `deepseek-account` route previously read its model catalog from the `models` field of the `llm-deepseek-account` entry, which the Models page could edit for the account. The route now lists models from the account's `GET /models` endpoint, serves the built-in catalog until a listing loads, and accepts per-model adjustments only through `modelOverrides`; the Models page no longer offers an editor for this route. A listed model can require a newer DeepSeek Harness; such a model is hidden, and a request for it fails with `CLIENT_UPGRADE_REQUIRED`. A `models` field left in the entry, including one saved by the earlier Models page editor, stops the plugin at load with `llm-deepseek-account: models is no longer configurable`, and Desktop and Web show no account models until the field is removed. Signed-in accounts without a saved catalog need no action.
+
+## Migration
+
+1. Open `$DSH_HOME/profiles/<profile>/cordis.patch.yml` and find the entry with `id: llm-deepseek-account`.
+2. Delete its `models` field. For each model whose fields you changed, move only the changed fields under `modelOverrides.<model id>`:
+
+   ```yaml
+   - id: llm-deepseek-account
+     config:
+       modelOverrides:
+         deepseek-flash:
+           maxTokens: 131072
+   ```
+
+3. Restart DeepSeek Harness, sign in to the DeepSeek account, and confirm that the model selector lists the account models and the Models page shows the account as signed in. An override the listed model rejects, or one that names an unknown model, appears as the account's diagnostic on the Models page.

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/deepseek-account-model-catalog/guide.zh.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "DeepSeek 账号路由不再接受 models 目录；模型由账号的模型列表提供，单个模型通过 modelOverrides 调整。"
+---
+
+# DeepSeek 账号模型改由账号的模型列表提供
+
+[English](guide.md) | 中文
+
+## 变更
+
+`deepseek-account` 路由此前从 `llm-deepseek-account` 条目的 `models` 字段读取模型目录，模型页可以为账号编辑这份目录。现在该路由从账号的 `GET /models` 端点列出模型，在列表加载之前使用内置目录，单个模型只能通过 `modelOverrides` 调整；模型页不再为该路由提供编辑器。列表中的模型可以要求更新版本的 DeepSeek Harness，这样的模型会被隐藏，请求它时以 `CLIENT_UPGRADE_REQUIRED` 失败。条目中遗留的 `models` 字段，包括早先模型页编辑器保存的，会让插件在加载时报 `llm-deepseek-account: models is no longer configurable` 并停止，删除该字段之前桌面端和 Web 都不显示账号模型。没有保存过账号目录的已登录账号无需操作。
+
+## 迁移
+
+1. 打开 `$DSH_HOME/profiles/<profile>/cordis.patch.yml`，找到 `id: llm-deepseek-account` 的条目。
+2. 删除其中的 `models` 字段。对改过字段的模型，只把改过的字段移到 `modelOverrides.<模型 id>` 下：
+
+   ```yaml
+   - id: llm-deepseek-account
+     config:
+       modelOverrides:
+         deepseek-flash:
+           maxTokens: 131072
+   ```
+
+3. 重启 DeepSeek Harness 并登录 DeepSeek 账号，确认模型选择器列出账号模型、模型页显示账号已登录。被列出的模型拒绝的覆盖，或指向未知模型的覆盖，会作为该账号的诊断信息显示在模型页上。

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/desktop-font-size-shortcuts/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Desktop font-size shortcuts reserve key combinations previously available to custom shortcuts."
+---
+
+# Desktop font-size shortcuts reserve custom key combinations
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Desktop reserves `Cmd`/`Ctrl` + `=` (including `Shift` + `=` for `+`) and `Cmd`/`Ctrl` + `-` to adjust text, code, and terminal font sizes together. Use `Cmd` on macOS and `Ctrl` on Windows and Linux. Custom bindings using these combinations, including overlapping two-key chords, remain saved but no longer execute. Web shortcut behavior is unchanged.
+
+## Migration
+
+1. Open Settings → General → Keyboard shortcuts in Desktop and find any custom binding marked as conflicting with a font-size shortcut.
+2. Record a nonconflicting combination for that action, or choose **Remove** to disable its keyboard shortcut. **Restore default** is available when the action's default does not conflict.
+3. Try the reassigned action, then press `Cmd`/`Ctrl` + `=` and `Cmd`/`Ctrl` + `-`. Confirm that all three font sizes change in Settings and remain saved after reopening Desktop.

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/desktop-font-size-shortcuts/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "桌面端字号快捷键占用了原先可用于自定义快捷键的组合键。"
+---
+
+# 桌面端字号快捷键占用部分自定义组合键
+
+[English](guide.md) | 中文
+
+## 变更
+
+桌面端保留 `Cmd`/`Ctrl` + `=`（包括输入 `+` 的 `Shift` + `=`）和 `Cmd`/`Ctrl` + `-`，用于一起调整正文、代码和终端字号。macOS 使用 `Cmd`，Windows 和 Linux 使用 `Ctrl`。使用这些组合键的自定义绑定，包括与其重叠的双键序列，仍会保存，但不再执行。Web 端快捷键行为不变。
+
+## 迁移
+
+1. 在桌面端打开「设置 → 通用 → 键盘快捷键」，找到标记为与字号快捷键冲突的自定义绑定。
+2. 为该操作录制不冲突的组合键，或选择「移除」禁用其快捷键。操作的默认快捷键不冲突时，也可以选择「恢复默认」。
+3. 尝试重新绑定的操作，再按 `Cmd`/`Ctrl` + `=` 和 `Cmd`/`Ctrl` + `-`。确认设置中的三组字号一起变化，并在重新打开桌面端后仍保留。

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/from-default-profile-replaces-target/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "`--from-default-profile` now replaces an existing custom profile instead of refusing it."
+---
+
+# `--from-default-profile` replaces an existing profile
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`dsh --profile <name> --from-default-profile <template>` used to fail with `profile "<name>" already exists` when the target profile existed, and refused a residual target directory. It now replaces the target directory with a fresh copy of the template every time, then boots it or, with a config-dump flag, prints the composition. The previous directory is deleted, including its `package.json` dependencies, installed `node_modules`, and `cordis.patch.yml`. Shipped profile names, in any letter case, are still rejected as targets.
+
+This affects anyone who repeats the command, such as `dsh rescue --from-default-profile web`, in scripts or shortcuts and expects later runs to keep the profile's plugins or patch.
+
+## Migration
+
+1. To boot an existing profile without resetting it, drop the option: run `dsh rescue` instead of `dsh rescue --from-default-profile web`.
+2. To keep local changes across a reset, copy `$DSH_HOME/profiles/<name>/cordis.patch.yml` before running the command, then reinstall the profile's plugins with `dsh plugin --profile <name> add <package>` and restore the patch.
+3. Confirm the migration: after `dsh rescue --from-default-profile web --help`, `$DSH_HOME/profiles/rescue/package.json` lists no dependencies.

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/from-default-profile-replaces-target/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "`--from-default-profile` 现在会替换已存在的自定义 profile，而不是拒绝执行。"
+---
+
+# `--from-default-profile` 会替换已存在的 profile
+
+[English](guide.md) | 中文
+
+## 变更
+
+此前目标 profile 已存在时，`dsh --profile <name> --from-default-profile <template>` 会以 `profile "<name>" already exists` 失败，残留的目标目录也会被拒绝。现在每次执行都会用模板的全新副本替换目标目录，然后启动它；带配置 dump flag 时则打印组合结果。原有目录会被删除，包括 `package.json` 中的依赖、已安装的 `node_modules` 和 `cordis.patch.yml`。任何大小写形式的随附 profile 名称仍不能作为目标。
+
+受影响的是在脚本或快捷方式中重复执行该命令（例如 `dsh rescue --from-default-profile web`），并期望后续执行保留该 profile 插件或 patch 的用户。
+
+## 迁移
+
+1. 要在不重置的情况下启动已存在的 profile，去掉该选项：运行 `dsh rescue`，而不是 `dsh rescue --from-default-profile web`。
+2. 要在重置后保留本地修改，先复制 `$DSH_HOME/profiles/<name>/cordis.patch.yml`，执行命令后用 `dsh plugin --profile <name> add <package>` 重新安装该 profile 的插件，再恢复该 patch。
+3. 确认迁移结果：执行 `dsh rescue --from-default-profile web --help` 后，`$DSH_HOME/profiles/rescue/package.json` 中没有任何依赖。

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/operator-connect/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Non-page Clients default to no forwarded interactions and use raw streams without browser recovery."
+---
+
+# Select interaction participation for non-page clients
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Non-page Connection installations default to `interactions: 'none'`. They do not open `$events`, and `$on()` and the generation-recovery helper `$stream()` are unavailable in that mode. Generated unary and raw stream methods remain usable. Browser authentication, existing browser Cookies, the shared Peer, and recovery behavior are unchanged; browsers need no reauthentication.
+
+## Migration
+
+1. Exchange the launch token at `GET /connect?token=<launch-token>&interactions=none` with manual redirect handling. Keep the returned API Cookie in client-owned storage and use it for HTTP and the lifecycle WebSocket at the returned 302 Location. HTTP need not wait for the socket to open.
+2. For passive streaming, call the generated raw stream method directly rather than `$stream()`. After lifecycle-socket closure or Host restart, perform a new connect before retrying.
+3. If the caller intentionally answers forwarded interactions, request `interactions=answer` and install Connection with that same mode. Confirm passive callers are refused at both event endpoints while the answering caller can subscribe.

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/operator-connect/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "非页面 Client 默认不参与转发交互，并使用不带浏览器恢复的原始流。"
+---
+
+# 为非页面客户端选择交互参与模式
+
+[English](guide.md) | 中文
+
+## 变更
+
+非页面 Connection 安装默认 `interactions: 'none'`。该模式不打开 `$events`，也不提供 `$on()` 和代际恢复辅助方法 `$stream()`；生成的 unary 和原始流方法仍可使用。浏览器认证、既有 Cookie、共享 Peer 与恢复行为均不变，无需重新认证。
+
+## 迁移
+
+1. 使用手动重定向处理，在 `GET /connect?token=<launch-token>&interactions=none` 交换 launch token。将返回的 API Cookie 放在客户端独立存储中，供 HTTP 和返回的 302 Location 所指的生命周期 WebSocket 使用；HTTP 无需等待 socket 打开。
+2. 被动流调用直接使用生成的原始流方法，不使用 `$stream()`。生命周期连接关闭或 Host 重启后，重试前先重新 connect。
+3. 如果调用方确实要回答转发交互，请请求 `interactions=answer`，并用相同模式安装 Connection。确认被动调用方在两个事件端点被拒绝，而回答型调用方可以订阅。

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/pi-ai-azure-provider/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "The pi-ai Azure provider route is renamed from azure-openai-responses to azure."
+---
+
+# Azure provider route rename
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The installed pi-ai catalog identifies the Azure provider as `azure` instead of `azure-openai-responses`. The `azure` route includes both Responses and Chat Completions models. The Responses API identifier remains `azure-openai-responses`, and the `AZURE_OPENAI_*` environment variables keep their names. Configurations and model selections that use the old provider key no longer resolve the Azure catalog.
+
+## Migration
+
+1. In the `llm-pi-ai` configuration in `$DSH_HOME/profiles/<profile>/cordis.patch.yml` or another supplying layer, rename `config.providers.azure-openai-responses` to `config.providers.azure`. Preserve its existing fields and any `apiKeyEnv` reference.
+2. Use catalog model IDs under `models`; map a custom Azure deployment name with `AZURE_OPENAI_DEPLOYMENT_NAME_MAP`. The mixed catalog cannot infer a protocol for a model ID absent from the catalog. An explicit route-level `api` overrides every model on that route; it does not select the Azure provider.
+3. Update explicit request/default provider selections to `azure`, and reselect an Azure model when continuing an existing Session. Configure the new Azure entry in Settings → Models if its key was stored for the old entry. Do not edit historical Session events.
+4. Confirm that Settings → Models offers `azure` and lists the expected models, then send a short request using the configured deployment.

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/pi-ai-azure-provider/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "pi-ai 的 Azure 提供方路由从 azure-openai-responses 更名为 azure。"
+---
+
+# Azure 提供方路由更名
+
+[English](guide.md) | 中文
+
+## 变更
+
+已安装的 pi-ai 目录使用 `azure` 标识 Azure 提供方，替代 `azure-openai-responses`。`azure` 路由同时包含 Responses 和 Chat Completions 模型。Responses API 标识仍为 `azure-openai-responses`，`AZURE_OPENAI_*` 环境变量名称也保持不变。使用旧提供方键的配置和模型选择无法再解析 Azure 目录。
+
+## 迁移
+
+1. 在 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 或其他提供配置的层中，找到 `llm-pi-ai` 配置，将 `config.providers.azure-openai-responses` 改为 `config.providers.azure`。保留原有字段及任何 `apiKeyEnv` 引用。
+2. 在 `models` 中使用目录模型 ID；自定义 Azure 部署名称通过 `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` 映射。混合协议目录无法为目录外的模型 ID 推断协议。显式设置路由级 `api` 会覆盖该路由所有模型的协议，并不表示选择 Azure 提供方。
+3. 将显式请求及默认模型配置中的提供方改为 `azure`，继续现有 Session 时重新选择 Azure 模型。若密钥存储在旧条目下，请在“设置 → 模型”中配置新的 Azure 条目。不要修改历史 Session 事件。
+4. 确认“设置 → 模型”提供 `azure` 且列出预期模型，再向所配置的部署发送一条简短请求。

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/pi-ai-model-discovery/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "pi-ai routes that name a credential hide their models until the credential is configured."
+---
+
+# pi-ai model visibility without a credential
+
+English | [中文](guide.zh.md)
+
+## Change
+
+A pi-ai route that names a credential through `apiKeyEnv` previously listed its configured models while that credential was missing, and requests then failed with `MISSING_CREDENTIAL`. Model discovery now returns an empty catalog for such a route until the credential resolves, so Desktop and Web hide its group. Other credential errors, such as a malformed key, still fail model discovery. Routes that use the provider's native authentication or name no credential keep their configured catalog. A saved or default selection absent from the catalog displays “Select model” without changing the stored selection.
+
+## Migration
+
+1. To use such a route, configure its key in Settings → Models, or supply the reference its `apiKeyEnv` names through the launch environment.
+2. Reopen the model selector and confirm that the route's group appears. Custom model discovery consumers must handle an empty catalog before the credential is configured; a listed catalog does not mean that the remote API accepts the key.

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/pi-ai-model-discovery/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "指定了凭据的 pi-ai 路由在凭据配置之前隐藏其模型。"
+---
+
+# pi-ai 路由缺少凭据时的模型可见性
+
+[English](guide.md) | 中文
+
+## 变更
+
+通过 `apiKeyEnv` 指定凭据的 pi-ai 路由，此前在凭据缺失时也会列出配置的模型，请求随后以 `MISSING_CREDENTIAL` 失败。现在凭据解析到之前，模型发现对这样的路由返回空目录，因此桌面端和 Web 隐藏它的分组。其他凭据错误（例如密钥格式错误）仍会让模型发现失败。使用提供方原生认证或未指定凭据的路由保留配置的目录。已保存或默认的选择不在目录中时，界面显示“请选择模型”，保存的选择保持不变。
+
+## 迁移
+
+1. 要使用这样的路由，请在设置 → 模型中配置密钥，或通过启动环境提供 `apiKeyEnv` 指定的凭据引用。
+2. 重新打开模型选择器，确认该路由的分组出现。自定义模型发现消费者必须处理配置凭据前的空目录；列出目录不代表远端 API 已接受密钥。

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/plugin-install-over-installed/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "With HMR, installing a package that is already installed fails with already-installed; an upgrade removes the package first."
+---
+
+# Installing over an installed plugin package is refused with HMR
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In a profile that runs HMR, which the shipped profiles do, `pluginManager.installBundle(spec)` used to run pnpm over a package the profile already depends on and report `restart-required` while the previous version kept running. It now fails before pnpm runs, with `application: 'failed'` and `error.code: 'already-installed'`, and changes no profile file, when the spec names an installed package: a registry name with or without a version, a local directory, or the git or tarball spec the dependency was saved with. Repeating an installation of the same spec fails the same way instead of reporting `changed: false`.
+
+This affects callers of `installBundle()` through the Host API and the remote client in `@deepseek-ai/dsh-api-remotes/client`, and the agent's `plugin_manager` tool (`install_bundle`). An installed package that cannot be removed, such as a bundle carrying plugin management, can no longer be installed over while HMR runs. The Web page's Update for an Official plugin removes the package and installs the new version itself. Without HMR, installing over an installed package still runs pnpm and reports `restart-required`.
+
+## Migration
+
+1. To install another version or location of an installed package, call `removeBundle(name)` first, then `installBundle(spec)`. For the agent tool, call `remove_bundle`, then `install_bundle`. The removal stops the bundle's plugins and drops its packages' mappings, so the new version is mapped afresh and starts without a restart.
+2. If code switches exhaustively over `ManagementError['code']`, handle the `already-installed` code.
+3. Confirm the migration: installing the package again returns `already-installed`, and after `removeBundle` the same `installBundle` call returns `applied` with the new `version`.

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/plugin-install-over-installed/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "启用 HMR 时，安装已安装的包会以 already-installed 失败；升级需要先移除该包。"
+---
+
+# 启用 HMR 时拒绝在已安装的插件包上再次安装
+
+[English](guide.md) | 中文
+
+## 变更
+
+在运行 HMR（热模块替换）的 profile 中（随附的 profile 都运行 HMR），`pluginManager.installBundle(spec)` 此前会对 profile 已依赖的包运行 pnpm，并在旧版本继续运行时报告 `restart-required`。现在当 spec 指向已安装的包时，它会在运行 pnpm 之前失败，返回 `application: 'failed'` 和 `error.code: 'already-installed'`，且不修改任何 profile 文件。这里的 spec 包括带或不带版本的注册表包名、本地目录，以及保存依赖时使用的 git 或 tarball spec。重复安装同一个 spec 也会以同样方式失败，不再报告 `changed: false`。
+
+受影响的调用方包括：通过 Host API 调用 `installBundle()` 的代码、`@deepseek-ai/dsh-api-remotes/client` 中的远端客户端，以及 agent 的 `plugin_manager` 工具（`install_bundle`）。启用 HMR 时，不能再在无法移除的已安装包（例如带有插件管理的组合包）上安装。Web 页面上官方插件的“更新”操作会自行移除该包并安装新版本。未启用 HMR 时，在已安装的包上安装仍会运行 pnpm 并报告 `restart-required`。
+
+## 迁移
+
+1. 要安装已安装包的其他版本或其他位置，先调用 `removeBundle(name)`，再调用 `installBundle(spec)`。使用 agent 工具时，先调用 `remove_bundle`，再调用 `install_bundle`。移除操作会停止该 bundle 的插件，并删除其各个包的映射，因此新版本会重新建立映射，无需重启即可启动。
+2. 如果代码对 `ManagementError['code']` 做穷尽 switch，需要处理 `already-installed`。
+3. 确认迁移结果：再次安装该包返回 `already-installed`；执行 `removeBundle` 后，同样的 `installBundle` 调用返回 `applied` 和新的 `version`。

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/sdk-minimal-image-compaction/guide.md

@@ -0,0 +1,32 @@
+---
+kind: upgrade-guide
+description: "The sdk-minimal default tool roster adds read_image and automatically summarizes older context."
+---
+
+# SDK-minimal image reading and automatic compaction
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`sdk-minimal` advertises `read_image` alongside its persistent shell and `working_directory`. Automatic compaction sends an additional model request to summarize older history when context pressure reaches the configured threshold. The complete Session log remains stored as uncompressed JSONL. Images that exceed the route budget are permanently replaced by attachment/path placeholders so the request can retry. SDK prompt text does not execute `/compact`.
+
+Clients that pin tool names, benchmark prompt size, or count model requests must account for these defaults. Image reading requires an adapter route that declares image input. See the [bundle reference](../../../../packages/bundle/sdk-minimal/README.md) for configuration and model effects.
+
+## Migration
+
+1. Accept the new defaults, or place this patch in `$DSH_HOME/profiles/sdk-minimal/cordis.patch.yml` to retain the previous default tools and disable automatic compaction:
+
+```yaml
+- id: tool-fs
+  config:
+    read: false
+    readImage: false
+    write: false
+    edit: false
+- id: compaction-basic
+  config:
+    auto: false
+```
+
+2. Launch a fresh SDK runtime. Without additional user plugins, its model requests contain the persistent `bash` or `pwsh` tool and `working_directory`; it sends no automatic summarization requests.

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/sdk-minimal-image-compaction/guide.zh.md

@@ -0,0 +1,32 @@
+---
+kind: upgrade-guide
+description: "sdk-minimal 默认工具清单新增 read_image，并自动生成较早上下文的摘要。"
+---
+
+# SDK-minimal 图片读取与自动压缩
+
+[English](guide.md) | 中文
+
+## 变更
+
+`sdk-minimal` 在持久 shell 和 `working_directory` 之外公布 `read_image`。上下文压力达到配置阈值时，自动压缩会额外发起模型请求，生成较早历史的摘要。完整 Session 日志仍存储为未压缩 JSONL。图片超出路由预算时会被永久替换为包含附件与路径的占位文本，以便重试请求。SDK 提示词文本不会执行 `/compact`。
+
+固定工具名称、基准提示词大小或统计模型请求数的客户端必须考虑这些默认行为。图片读取需要适配器路由声明支持图片输入。配置与模型影响见[组合包参考](../../../../packages/bundle/sdk-minimal/README.zh.md)。
+
+## 迁移
+
+1. 接受新增默认能力，或将以下 patch 写入 `$DSH_HOME/profiles/sdk-minimal/cordis.patch.yml`，保留原有默认工具并关闭自动压缩：
+
+```yaml
+- id: tool-fs
+  config:
+    read: false
+    readImage: false
+    write: false
+    edit: false
+- id: compaction-basic
+  config:
+    auto: false
+```
+
+2. 启动新的 SDK 运行时。未额外配置用户插件时，模型请求包含持久 `bash` 或 `pwsh` 工具及 `working_directory`；不会发起自动摘要请求。

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/stored-credentials-precedence/guide.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "Stored credentials now precede environment fallbacks when the store is mounted; the shipped headless profile omits stored authentication."
+---
+
+# A stored key takes precedence over an exported variable
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Earlier releases used an exported environment variable before the `refs` entry with the same name in `$DSH_HOME/.credentials.yaml` (`~/.dsh/.credentials.yaml` by default). This applied to `DEEPSEEK_API_KEY=… dsh`, a shell profile export, a CI secret, and a container `-e` value. While the name was exported, the Models page could not save a key for it.
+
+Now the stored entry wins. The exported variable applies only while the file stores no value for that name, and `$cwd/.env` and `$DSH_HOME/.env` still apply only after both. The Models page can save and replace a key while the name is exported.
+
+The shipped `headless` profile instead disables the credential store, authorization and DeepSeek account provider. It uses the launch environment, project `.env`, then Harness-home `.env`, and leaves `.credentials.yaml` untouched. Saved API keys and sign-ins no longer authenticate headless jobs by default. Web, SDK and ACP retain the store.
+
+You are affected when a harness home stores a value under `refs` and the process that launches `dsh` exports the same name. This includes a container that mounts such a home. Requests now use the stored key instead of the exported one. A CI job or container that starts with a fresh harness home, without `.credentials.yaml`, is not affected. The [stored credential precedence](../../../../.agents/notes/implemented/architecture/2026-10-09-stored-credential-precedence.md) Agent Note records the reason.
+
+## Migration
+
+1. Compare the names under `refs` in `$DSH_HOME/.credentials.yaml` with the variables that your shell, CI job, or container exports. A name that appears in only one place needs no action.
+2. For each name that appears in both places, keep the stored key if it is the account you want. Otherwise, delete the name's line under `refs`. A running harness reloads the file, so the next request reads the exported variable without a restart.
+3. For a headless job, export the required key and run `dsh headless "<task>"`. To keep using a saved key or sign-in, apply the three-row [headless restoration patch](../../../../packages/bundle/headless/README.md#credentials); restored storage also restores saved-first precedence. Existing profile, home or command overlays can override the shipped rows, so inspect `dsh headless --dump-config` when checking the effective composition.
+4. Confirm the intended request account and that the launching process exports a non-empty value where needed. Check names and presence without printing credential values. A headless run relying only on a saved credential now fails; restoring storage or supplying supported environment authentication resolves it.

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/stored-credentials-precedence/guide.zh.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "挂载存储时，已保存凭据现在优先于环境后备；随附 headless profile 不挂载存储认证。"
+---
+
+# 存储的密钥优先于导出的变量
+
+[English](guide.md) | 中文
+
+## 变更
+
+早期版本会先使用导出的环境变量，再使用 `$DSH_HOME/.credentials.yaml`（默认为 `~/.dsh/.credentials.yaml`）中同名的 `refs` 条目。这适用于 `DEEPSEEK_API_KEY=… dsh`、shell 配置文件中的导出、CI 机密和容器 `-e` 值。该名字被导出期间，Models 页面无法为其保存密钥。
+
+现在存储的条目优先。只有当文件没有为该名字存储值时，导出的变量才会生效；`$cwd/.env` 和 `$DSH_HOME/.env` 仍排在两者之后。即使该名字已被导出，Models 页面也可以保存和替换密钥。
+
+随附的 `headless` profile 则禁用凭据存储、authorization 和 DeepSeek account 提供方。它依次使用启动环境、项目 `.env` 和 Harness home `.env`，并保持 `.credentials.yaml` 原样。已保存 API 密钥和登录凭据默认不再为 headless 任务提供认证。Web、SDK 和 ACP 保留存储。
+
+如果某个 harness home 在 `refs` 下存储了值，而启动 `dsh` 的进程导出了同名变量，你就会受到影响。挂载了这类 home 的容器也包括在内。请求现在使用存储的密钥，而不是导出的密钥。以全新 harness home 启动、没有 `.credentials.yaml` 的 CI 作业或容器不受影响。[存储凭据优先级](../../../../.agents/notes/implemented/architecture/2026-10-09-stored-credential-precedence.zh.md) Agent Note 记录了原因。
+
+## 迁移
+
+1. 将 `$DSH_HOME/.credentials.yaml` 中 `refs` 下的名字，与 shell、CI 作业或容器导出的变量进行比较。只出现在其中一处的名字无需处理。
+2. 对同时出现在两处的名字，如果存储的密钥正是你要使用的账户，就保留它。否则，删除 `refs` 下该名字所在的行。运行中的 harness 会重新加载该文件，因此下一次请求无需重启即可读取导出的变量。
+3. 对 headless 任务，导出所需密钥并运行 `dsh headless "<task>"`。要继续使用已保存密钥或登录凭据，请应用三行配置的 [headless 恢复 patch](../../../../packages/bundle/headless/README.zh.md#credentials)；恢复存储也恢复已保存凭据优先。现有 profile、home 或命令覆盖可以覆盖随附行，因此核对有效组合时请查看 `dsh headless --dump-config`。
+4. 确认请求使用预期账户，并在需要时确认启动进程导出了非空值。只检查名字和是否存在，不要打印凭据值。仅依赖已保存凭据的 headless 运行现在会失败；恢复存储或提供受支持的环境认证即可解决。