dsh-plugin-dev-kb 1.4.0 → 1.5.2

package/kb/extra/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Plugin compatibility checks read engines.dsh before DSH peerDependencies, and refusals report requirements instead of peers."
+---
+
+# Plugin compatibility reads `engines.dsh` first
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In v0.2.1-alpha.3, installation and profile startup judged a plugin or bundle only by its `peerDependencies` on `@deepseek-ai/dsh` and `@deepseek-ai/dsh-*`, and ignored `engines.dsh`. In the next release, an own `engines.dsh` range decides alone and those peers are ignored; the peer rule applies only when `engines.dsh` is absent. `workspace:` values are valid only in peers; in `engines.dsh` they are incompatible. A non-object `engines` or a non-string `engines.dsh` makes the manifest unreadable for compatibility, which refuses the package. Plugin authors whose package declares `engines.dsh`, or declares `engines` as something other than an object, are affected.
+
+The `incompatible-version` refusal record that the plugin manager returns to clients, `IncompatiblePlugin`, and the app-boot `PluginCompatibility` result rename `peers` to `requirements`. Keys are `engines.dsh` for the engines rule or the peer package name for the fallback. Code that reads these records is affected.
+
+## Migration
+
+1. If your package declares `engines.dsh`, make that range cover every DSH release the package supports, because DSH peer ranges no longer widen or narrow it. Remove `engines.dsh` to keep peer-based checking.
+2. Replace `workspace:` values in `engines.dsh` with a semantic version range.
+3. Read `requirements` instead of `peers` from `IncompatiblePlugin` and `PluginCompatibility`.
+4. Confirm by installing the package with `dsh plugin --profile <profile> add <package@version>` or the plugin manager: a mismatch names `engines.dsh` or the peer package in the refusal.

package/kb/extra/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "插件兼容性检查先读 engines.dsh，再读 DSH peerDependencies；拒绝记录改用 requirements 代替 peers。"
+---
+
+# 插件兼容性先读 `engines.dsh`
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 v0.2.1-alpha.3 中，安装和 profile 启动只依据插件或组合包在 `peerDependencies` 中对 `@deepseek-ai/dsh` 和 `@deepseek-ai/dsh-*` 的声明判定兼容性，忽略 `engines.dsh`。下一版本中，包自身的 `engines.dsh` 范围单独决定结果，并忽略这些 peer；只有缺少 `engines.dsh` 时才使用 peer 规则。`workspace:` 值只在 peer 中有效；出现在 `engines.dsh` 中时视为不兼容。`engines` 不是对象或 `engines.dsh` 不是字符串时，兼容性检查无法读取清单，该包会被拒绝。受影响的是声明了 `engines.dsh`，或把 `engines` 声明为非对象值的插件作者。
+
+插件管理器返回给客户端的 `incompatible-version` 拒绝记录 `IncompatiblePlugin`，以及 app-boot 的 `PluginCompatibility` 结果，将 `peers` 重命名为 `requirements`。按 engines 规则判定时键为 `engines.dsh`，回退到 peer 规则时键为 peer 包名。读取这些记录的代码受影响。
+
+## 迁移
+
+1. 如果包声明了 `engines.dsh`，让该范围覆盖包支持的所有 DSH 版本，因为 DSH peer 范围不再放宽或收窄它。删除 `engines.dsh` 可保留基于 peer 的检查。
+2. 将 `engines.dsh` 中的 `workspace:` 值替换为语义化版本范围。
+3. 从 `IncompatiblePlugin` 和 `PluginCompatibility` 读取 `requirements`，不再读取 `peers`。
+4. 用 `dsh plugin --profile <profile> add <package@version>` 或插件管理器安装该包确认迁移：不匹配时，拒绝信息会列出 `engines.dsh` 或对应 peer 包。

package/kb/extra/upgrade-guide/v0.2.1-alpha.4/account-notification-fields/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "AccountBonusNotification exposes unvalidated optional metadata and permits notices without an expiry."
+---
+
+# Update account notification consumers
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The public `AccountBonusNotification` returned by `DeepSeekAccount.getUnnotifiedBonuses()` and `account/getUnnotifiedBonuses` preserves `campaign`, `amount`, `currency`, and `grantedAt` as optional, unvalidated metadata typed as `JsonValue`. Notifications retain `orderId`, `message`, and `expiresAt`, and add an optional `title`. An empty `expiresAt` means the notification never expires. `orderId` accepts arbitrary strings rather than requiring UUIDs.
+
+## Migration
+
+1. Narrow the optional metadata values before using them; their presence and format are no longer guaranteed. Display `message` and use the client's default title when `title` is absent.
+2. Treat an empty `expiresAt` as no expiry before parsing timestamps. Keep `orderId` unchanged when acknowledging a notification.
+3. Update provider fixtures to use the current fields. Confirm that a notification with a non-UUID ID and empty expiry displays and can be acknowledged.

package/kb/extra/upgrade-guide/v0.2.1-alpha.4/account-notification-fields/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "AccountBonusNotification 提供未经校验的可选元数据，并允许通知永不过期。"
+---
+
+# 更新账号通知使用方
+
+[English](guide.md) | 中文
+
+## 变更
+
+`DeepSeekAccount.getUnnotifiedBonuses()` 和 `account/getUnnotifiedBonuses` 返回的公开类型 `AccountBonusNotification` 保留 `campaign`、`amount`、`currency` 和 `grantedAt`，作为类型为 `JsonValue` 的可选元数据，不做校验。通知保留 `orderId`、`message` 和 `expiresAt`，并新增可选的 `title`。空字符串 `expiresAt` 表示通知永不过期。`orderId` 接受任意字符串，不再要求 UUID 格式。
+
+## 迁移
+
+1. 使用可选元数据前先收窄类型；这些值不再保证存在或符合原有格式。展示 `message`，在 `title` 缺省时使用客户端默认标题。
+2. 解析时间戳前，将空字符串 `expiresAt` 视为永不过期。确认通知时原样传递 `orderId`。
+3. 更新提供者测试夹具以使用当前字段。确认非 UUID 标识、空过期时间的通知可以展示并确认。