dsh-plugin-dev-kb 1.4.0 → 1.5.1

package/kb/extra/tool-execution-pipeline.md

@@ -0,0 +1,65 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Tool Execution Pipeline
+
+This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `projectContent` installs prepared content before post-execute; `finalizeContent` and `tools/result` run afterward.
+
+```mermaid
+flowchart TD
+  model["Assistant message contains tool-call block"]
+  toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
+  presentCall["UI pending card<br/>presentCall(args)"]
+  pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
+  guards["Registered monotonic guards<br/>deny or abstain; identity protected"]
+  denied["denied or approval refused<br/>tool body skipped"]
+  approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"]
+  around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"]
+  toolBody["Registered tool execute() body"]
+  fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
+  owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/ptc-dispatch</code>"]
+  project["ToolDefinition.projectContent<br/>execution-prepared text and images"]
+  post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
+  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
+  finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
+  final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
+  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
+  toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
+  allResults["Tool batch settled<br/>recorded tool/result events complete"]
+  presentResult["UI completed card<br/>presentResult(args, result)"]
+  model --> toolCall
+  toolCall --> presentCall
+  toolCall --> pre
+  pre -->|allow| guards
+  guards -->|allow| around
+  guards -->|deny| denied
+  guards -.->|throw| normalized
+  around --> toolBody
+  pre -->|deny| denied
+  pre -->|ask| approval
+  approval -->|allowed-once| guards
+  approval -->|rejected, cancelled, unavailable| denied
+  approval -.->|throw| normalized
+  denied --> project
+  pre -.->|throw| normalized
+  toolBody --> fsGate
+  fsGate --> toolBody
+  toolBody --> owned
+  toolBody --> around
+  around --> project
+  project --> post
+  project -.->|throw| normalized
+  around -.->|wrapper throws| normalized
+  post -.->|throw| normalized
+  post --> finalize
+  normalized --> finalize
+  finalize --> final
+  final --> toolResult
+  toolResult --> presentResult
+  toolResult --> allResults
+  allResults --> context
+```
+
+Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. PTC mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/ptc-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
+
+Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs.

package/kb/extra/tool-execution-pipeline.zh.md

@@ -0,0 +1,67 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/tool-execution-pipeline.md` 重新记录配对。 -->
+
+# 工具执行流水线
+
+[English](tool-execution-pipeline.md) | 中文
+
+此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。`tools/pre-execute` waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 `tools/execute` 和 `tools/post-execute` waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 `projectContent` 在执行后策略之前安装已准备内容；`finalizeContent` 和 `tools/result` 在此之后运行。
+
+```mermaid
+flowchart TD
+  model["Assistant message contains tool-call block"]
+  toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
+  presentCall["UI pending card<br/>presentCall(args)"]
+  pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
+  guards["Registered monotonic guards<br/>deny or abstain; identity protected"]
+  denied["denied or approval refused<br/>tool body skipped"]
+  approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"]
+  around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"]
+  toolBody["Registered tool execute() body"]
+  fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
+  owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/ptc-dispatch</code>"]
+  project["ToolDefinition.projectContent<br/>execution-prepared text and images"]
+  post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
+  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
+  finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
+  final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
+  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
+  toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
+  allResults["Tool batch settled<br/>recorded tool/result events complete"]
+  presentResult["UI completed card<br/>presentResult(args, result)"]
+  model --> toolCall
+  toolCall --> presentCall
+  toolCall --> pre
+  pre -->|allow| guards
+  guards -->|allow| around
+  guards -->|deny| denied
+  guards -.->|throw| normalized
+  around --> toolBody
+  pre -->|deny| denied
+  pre -->|ask| approval
+  approval -->|allowed-once| guards
+  approval -->|rejected, cancelled, unavailable| denied
+  approval -.->|throw| normalized
+  denied --> project
+  pre -.->|throw| normalized
+  toolBody --> fsGate
+  fsGate --> toolBody
+  toolBody --> owned
+  toolBody --> around
+  around --> project
+  project --> post
+  project -.->|throw| normalized
+  around -.->|wrapper throws| normalized
+  post -.->|throw| normalized
+  post --> finalize
+  normalized --> finalize
+  finalize --> final
+  final --> toolResult
+  toolResult --> presentResult
+  toolResult --> allResults
+  allResults --> context
+```
+
+文件系统的先读后编辑检查位于 `tool-fs` 之下，通过 `fs/*` 事件实现。通用的前置／后置 waterfall 承载钩子与审批策略；`ctx.approval` 在单调守卫之前处理询问，而不得重新排序的所有者策略仍作为已注册的守卫。超时等环绕分发关注点对 `tools/execute` 进行包装。注册表会对候选结果进行无损快照；如果快照失败，则会先将失败规范化，之后再由可见定义中已随快照固定的 `finalizeContent` 回调强制执行其同步且仅限内容的不变式。随后，`tools/result` 会观察不可变、可由 JSON 无损表示的结果。这样一来，钩子便可跨越不同工具系列，而无需让工具与某个策略服务耦合。PTC mode 会将保留的 `run_code` 传输及其序列化子调用都送入流水线；子调用携带父级 token、记录 `tool/ptc-dispatch`、将拒绝呈现为具有约束力的驳回，并省略 `additionalContexts`，以保持调用与结果相邻。
+
+维护模式：英文源文件包含人工维护的 Mermaid 流程图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的工具 schema 与事件签名位于生成的目录中。

package/kb/extra/ui-radius.md

@@ -38,9 +38,9 @@ H means designed outer height in CSS pixels, including borders. R means CSS `bor
 
 Prefer an existing shared size variant when a proposed control falls between these bands. A taller card remains a card: do not promote it to R28 merely because it exceeds a button's height. A multiline cell intentionally designed for multiple lines uses R16; an ordinary button whose label wraps retains its button variant.
 
-Concrete defaults: `Button` uses H28/R8 for `sm` and H36/R12 for `md`, including outline variants. Standard H32 inputs and H36 selectors use R12. The Workspace files and New terminal guide entries both use R20, including title-only and described variants. Reserve R28 for their enclosing panel or dialog, not those entries.
+Concrete defaults: `Button` uses H28/R8 for `sm` and H36/R12 for `md`, including outline variants. Standard H32 inputs and H36 selectors use R12. The Workspace files and New terminal guide entries both use R20, including title-only and described variants. Reserve R28 for their enclosing panel or dialog, not those entries. Composer statistics and the context-occupancy trigger use compact-control R8 with the theme curve, including hover, expanded, and focus states.
 
-Code blocks, diffs, and file previews share R16: changed-file entry cards, delivered-file cards, generic file attachment cards, and hover preview panels. The 40px file-icon tiles inside changed-file and delivery cards use R10 on all four corners as a component-specific exception. Their hover fills keep the same contour.
+Code blocks, diffs, and preview cards share R16: changed-file entry cards, delivered-file cards, submitted-plan cards, created-task cards, generic file attachment cards before and after sending, and hover preview panels. The 40px icon tiles inside changed-file, delivery, submitted-plan, and created-task cards use R10 on all four corners as a component-specific exception and share the same neutral tile fill and border in both themes. Their hover fills keep the same contour.
 
 <a id="shapes"></a>
 ## Reuse tokens and preserve deliberate shapes
@@ -64,11 +64,13 @@ Distinguish these three arrangements before changing a child radius:
 
 | Arrangement | Rule | Example |
 |---|---|---|
-| Concentric inset | Inner R = max(0, outer R − inset); use the same curve | Outer R16, inset 4, inner R12 |
+| Circular concentric inset | Inner R = max(0, outer R − inset); both arcs share a center and use `round` | Outer R16, inset 4, inner R12 |
 | Fill flush against an enclosing edge | The enclosure owns the visible corner; clip the fill or inherit the matching corner | A split-button card with two independent hover regions |
 | Separate card or form group inside another surface | Choose the child's semantic tier; do not subtract all parent padding mechanically | R16 editor within an R20 settings card |
 
-Standard menus use outer R16, 4px padding, and R12 items. Compact menus use outer R12, 4px padding, and R8 items. Shared `SegmentedControl` uses outer R12, 4px inset, and R8 segments/indicator; `SegmentedTabs` uses outer R16, 4px inset, and R12 segments/indicator. Keep indicator offsets, width calculations, submenu alignment, and pointer bridges consistent when changing padding.
+Standard menus use outer R16, 4px padding, and R12 items, including command selection, task menus, and the exposed highlights in subagent and background-job menus. Tree disclosure gutters retain their indentation; controls inside a filled job row keep their own compact geometry. Compact menus use outer R12, 4px padding, and R8 items. Shared `SegmentedControl` uses outer R12, 4px inset, and R8 segments/indicator; `SegmentedTabs` uses outer R16, 4px inset, and R12 segments/indicator. Keep indicator offsets, width calculations, submenu alignment, and pointer bridges consistent when changing padding.
+
+The radius subtraction is also the nominal sizing rule for nested superellipses. Equal exponents do not make them exact offset curves, so their diagonal gap may differ from the side inset. Keep the shared superellipse menu and segmented-control treatments; use circular arcs when strict equal radial spacing is required.
 
 A single clickable surface paints hover on itself. A flush pseudo-element or overlay uses the same radius and curve as the visible enclosure. Avoid a separately rounded fill that leaves a crescent between the background and the border.
 

package/kb/extra/ui-radius.zh.md

@@ -38,9 +38,9 @@ H 表示以 CSS 像素计、包含边框的设计外部高度。R 表示浏览
 
 拟定控件尺寸落在档位之间时，优先复用已有的公共尺寸变体。高卡片仍是卡片，不因高度超过按钮就升到 R28。专门设计为多行的 cell 使用 R16；普通按钮的文字发生换行时，仍保留其按钮变体。
 
-具体默认值：`Button` 的 `sm` 使用 H28/R8，`md` 使用 H36/R12，包含描边变体。标准 H32 输入框和 H36 选择器使用 R12。“工作区文件”和“新建终端”引导入口统一使用 R20，包含仅标题与带描述的变体。R28 留给包围它们的面板或对话框，不用于这些入口。
+具体默认值：`Button` 的 `sm` 使用 H28/R8，`md` 使用 H36/R12，包含描边变体。标准 H32 输入框和 H36 选择器使用 R12。“工作区文件”和“新建终端”引导入口统一使用 R20，包含仅标题与带描述的变体。R28 留给包围它们的面板或对话框，不用于这些入口。输入框统计控件与上下文占用率入口使用紧凑控件的 R8 和主题曲线，包含 hover、展开与焦点状态。
 
-代码块、diff 与文件预览共用 R16：包括改动文件入口卡片、交付文件卡片、通用附件文件卡片和悬停预览浮层。改动文件与交付文件卡片内部的 40px 文件图标底框作为组件特例，四角统一使用 R10。各自的 hover 保持同一轮廓。
+代码块、diff 与预览卡片共用 R16：包括改动文件入口卡片、交付文件卡片、已提交计划卡片、已创建任务卡片、发送前后的通用附件文件卡片和悬停预览浮层。改动文件、交付文件、已提交计划与已创建任务卡片内部的 40px 图标底框作为组件特例，四角统一使用 R10，并在明暗两种主题下分别共用相同的中性底色与边框。各自的 hover 保持同一轮廓。
 
 <a id="shapes"></a>
 ## 复用 token，保留有意设计的形状
@@ -64,11 +64,13 @@ H 表示以 CSS 像素计、包含边框的设计外部高度。R 表示浏览
 
 | 关系 | 规则 | 示例 |
 |---|---|---|
-| 同心内缩 | 内层 R = max(0, 外层 R − 内缩距离)；使用相同曲线 | 外层 R16，内缩 4，内层 R12 |
+| 圆弧同心内缩 | 内层 R = max(0, 外层 R − 内缩距离)；两段圆弧同心且使用 `round` | 外层 R16，内缩 4，内层 R12 |
 | 底色紧贴容器边缘 | 由外框决定可见圆角；裁切底色或继承相应圆角 | 两个独立 hover 区域组成的分体按钮卡片 |
 | 容器内独立的卡片或表单组 | 按子元素用途选择档位；不机械减去全部父级内边距 | R20 设置卡片内的 R16 编辑器 |
 
-标准菜单使用外层 R16、4px 内边距、R12 菜单项。紧凑菜单使用外层 R12、4px 内边距、R8 菜单项。公共 `SegmentedControl` 使用外层 R12、4px 内缩、R8 分段和指示器；`SegmentedTabs` 使用外层 R16、4px 内缩、R12 分段和指示器。修改内边距时，同步保持指示器偏移、宽度计算、子菜单对齐与指针桥接区域一致。
+标准菜单使用外层 R16、4px 内边距、R12 菜单项，包含命令选择、任务菜单，以及子会话和后台任务菜单的外露高亮区域。树形展开操作保留缩进；带底色任务行内的控件保留各自的紧凑几何。紧凑菜单使用外层 R12、4px 内边距、R8 菜单项。公共 `SegmentedControl` 使用外层 R12、4px 内缩、R8 分段和指示器；`SegmentedTabs` 使用外层 R16、4px 内缩、R12 分段和指示器。修改内边距时，同步保持指示器偏移、宽度计算、子菜单对齐与指针桥接区域一致。
+
+半径相减也用于嵌套超级椭圆的名义尺寸关系。相同指数不意味着两条曲线严格等距，因此对角线间隙可能不同于侧边内缩。菜单与分段控件保留公共的超级椭圆样式；要求径向严格等距时使用圆弧。
 
 单个可点击表面在自身绘制 hover。贴边的伪元素或覆盖层使用与可见外框相同的圆角和曲线。避免单独给底色设置圆角，导致背景与边框之间出现月牙状空隙。
 

package/kb/extra/upgrade-guide/v0.2.0-rc.2/bundled-python-tests/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Bundled NumPy and pandas omit their upstream test suites."
+---
+
+# NumPy and pandas upstream tests require a separate environment
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Desktop and Python SDK runtime distributions previously included NumPy and pandas test directories. Bundled distributions now omit those directories, so scripts importing their test modules or running their complete upstream suites need a separate installation. Data processing, Office authoring, `numpy.testing`, `pandas.testing`, and `pandas._testing` remain available.
+
+## Migration
+
+1. If your scripts import `numpy.*.tests` or `pandas.tests`, install the original NumPy and pandas distributions and their upstream testing dependencies in a separate Python environment. Keep that environment outside the managed Harness runtime directory, which upgrades replace.
+2. Run the affected scripts or upstream suites with that environment's interpreter. Scripts that use only library functionality or retained testing helpers require no changes.
+3. Confirm that the previously failing test-module imports and affected scripts succeed with the separate interpreter. The bundled versions are recorded in the [runtime lock](../../../../scripts/primary-runtime/lock.json).

package/kb/extra/upgrade-guide/v0.2.0-rc.2/bundled-python-tests/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "内置 NumPy 和 pandas 不包含其上游测试套件。"
+---
+
+# NumPy 和 pandas 上游测试需要独立环境
+
+[English](guide.md) | 中文
+
+## 变更
+
+Desktop 和 Python SDK 运行时分发包此前包含 NumPy 和 pandas 测试目录。内置分发包现在裁剪这些目录，因此导入其测试模块或运行其完整上游测试套件的脚本需要独立安装环境。数据处理、Office 创作、`numpy.testing`、`pandas.testing` 和 `pandas._testing` 仍然可用。
+
+## 迁移
+
+1. 如果脚本导入 `numpy.*.tests` 或 `pandas.tests`，请在独立 Python 环境中安装原始 NumPy 和 pandas 分发包及其上游测试依赖。请将该环境放在 Harness 托管运行时目录之外，升级会替换托管目录。
+2. 使用该环境的解释器运行受影响的脚本或上游测试套件。仅使用库功能或保留的 testing 辅助 API 的脚本无需修改。
+3. 确认先前失败的测试模块导入及相关脚本均可在独立解释器中成功运行。随包版本记录在[运行时锁文件](../../../../scripts/primary-runtime/lock.json)中。

package/kb/extra/upgrade-guide/v0.2.0-rc.2/primary-runtime-python-aliases/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Custom primary-runtime payloads require relocatable Python interpreter aliases."
+---
+
+# Custom Python runtime aliases must target a sibling interpreter
+
+English | [中文](guide.zh.md)
+
+## Change
+
+On macOS and Linux, `DSH_PRIMARY_RUNTIME` previously accepted interpreter links that resolved outside their payload or through other links. Payload validation now requires each linked `dependencies/python/bin/python` or `python3` to point directly to the regular sibling interpreter named for `runtime.json`'s Python major and minor version, such as `python3.12`. Regular command files remain supported, including those distributed in Python wheels. Windows is unchanged.
+
+## Migration
+
+1. For a custom payload, keep the versioned interpreter in `dependencies/python/bin/` and make `python` and `python3` relative links to its filename. The [runtime preparation instructions](../../../../packages/skill/tool-workspace-dependencies/README.md) list the required target and output arguments.
+2. Preserve relative links when copying prepared resources. With Node `fs.cp`, use `verbatimSymlinks: true`; wheel builders must materialize the command files because pip does not restore links. The native build smoke requires the prepared resource tree to retain both aliases.
+3. Confirm that `readlink` reports only the sibling filename for both aliases, then move the payload away from its build directory, point `DSH_PRIMARY_RUNTIME` at its new directory, and verify that `load_workspace_dependencies` and the returned Python command succeed.

package/kb/extra/upgrade-guide/v0.2.0-rc.2/primary-runtime-python-aliases/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "自定义 primary-runtime payload 的 Python 解释器别名必须支持目录迁移。"
+---
+
+# 自定义 Python 运行时别名必须指向同目录解释器
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 macOS 和 Linux 上，`DSH_PRIMARY_RUNTIME` 之前接受指向 payload 外部或经过其他链接的解释器链接。现在，payload 校验要求 `dependencies/python/bin/python` 或 `python3` 的链接直接指向同目录的普通解释器文件，文件名由 `runtime.json` 中 Python 的主版本号和次版本号决定，例如 `python3.12`。普通命令文件仍受支持，包括 Python wheel 中分发的文件。Windows 不变。
+
+## 迁移
+
+1. 对于自定义 payload，将版本化解释器保留在 `dependencies/python/bin/` 中，并让 `python` 和 `python3` 以该文件名为目标建立相对链接。[运行时准备说明](../../../../packages/skill/tool-workspace-dependencies/README.zh.md)列出了必需的目标与输出参数。
+2. 复制准备好的资源时保留相对链接。使用 Node `fs.cp` 时设置 `verbatimSymlinks: true`；wheel 构建器必须将命令展开为普通文件，因为 pip 不会还原链接。本机构建冒烟检查要求准备好的资源目录保留两个别名。
+3. 确认 `readlink` 对两个别名都只返回同目录解释器的文件名，再将 payload 移离构建目录，将 `DSH_PRIMARY_RUNTIME` 指向新目录，验证 `load_workspace_dependencies` 和返回的 Python 命令均可成功执行。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/deepseek-model-discovery/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "DeepSeek API-key model discovery requires a configured credential."
+---
+
+# DeepSeek API-key model visibility
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `deepseek-official` route previously listed its configured models without an API key. It now returns an empty catalog when its credential is missing, so Desktop and Web hide the DeepSeek group. Model discovery reports malformed credentials and credential lookup failures. A saved or default selection absent from the catalog displays “Select model” without changing the stored selection. The independent DeepSeek account route still uses account login.
+
+## Migration
+
+1. To use the API-key route, configure its key in Settings → Models or supply the reference named by `apiKeyEnv` (default `DEEPSEEK_API_KEY`) through the launch environment.
+2. Reopen the model selector and confirm the DeepSeek group appears. Custom discovery consumers must handle an empty catalog before credentials are configured; listing models does not verify that the remote API accepts the key.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/deepseek-model-discovery/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "DeepSeek API Key 模型发现要求已配置凭据。"
+---
+
+# DeepSeek API Key 模型可见性
+
+[English](guide.md) | 中文
+
+## 变更
+
+`deepseek-official` 路由此前在没有 API Key 时也会列出配置的模型。现在凭据缺失时返回空目录，因此桌面端和 Web 隐藏 DeepSeek 分组。模型发现会报告凭据格式错误和凭据读取失败。已保存或默认的选择不在目录中时，界面显示“请选择模型”，保存的选择保持不变。独立的 DeepSeek 账号路由仍使用账号登录。
+
+## 迁移
+
+1. 要使用 API Key 路由，请在设置 → 模型中配置密钥，或通过启动环境提供 `apiKeyEnv` 指定的凭据引用（默认为 `DEEPSEEK_API_KEY`）。
+2. 重新打开模型选择器，确认 DeepSeek 分组出现。自定义模型发现消费者必须处理配置凭据前的空目录；模型列出不代表远端 API 已接受密钥。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/desktop-test-auth-popup/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Desktop test builds require local opt-in before showing any Feishu update-policy authentication dialogs."
+---
+
+# Enable test update-policy authentication dialogs locally
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Test builds previously offered Feishu login after an unauthenticated startup or manual update-policy check. All test authentication dialogs now default to disabled, including manual checks and mandatory-update refreshes. Test gateway cookies do not survive restart. With login disabled, a gateway requiring authentication cannot provide new mandatory-update decisions; enable the setting, restart and sign in to obtain them. Authentication failures retain any mandatory block already known in the same process; production policy requests and product account login are unchanged.
+
+## Migration
+
+1. Launch the updated application once to create `app.getPath('userData')/desktop/settings.json` if missing. Existing files are retained, and a missing field defaults to `false`. See [local desktop settings](../../../../apps/desktop/README.md#local-desktop-settings) for platform paths and error recovery.
+2. To permit Feishu login, set `updates.allowTestAuthPopupWindow` to `true` in that file, then fully quit and restart Desktop. An unauthenticated test-policy response can now offer login. Leave the default unchanged if no login dialogs are wanted.
+3. To disable dialogs again, set the field to `false` and restart. Startup and manual checks must not show Feishu authentication dialogs. Updates still query policy, and authentication failures do not clear a known mandatory block.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/desktop-test-auth-popup/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "桌面测试包需要在本地显式开启后，才能显示飞书更新策略鉴权弹窗。"
+---
+
+# 在本地开启测试更新策略鉴权弹窗
+
+[English](guide.md) | 中文
+
+## 变更
+
+测试包此前会在启动或手动检查更新策略未通过鉴权后提供飞书登录入口。现在所有测试鉴权弹窗默认关闭，包括手动检查和强更刷新。测试网关 Cookie 不跨重启保存。禁止登录时，需要鉴权的网关无法提供新的强更决策；需开启设置、重启并登录后才能获取。鉴权失败仍保留同一进程中已知的强更阻塞；正式环境策略请求和产品账号登录保持不变。
+
+## 迁移
+
+1. 启动更新后的应用一次，在 `app.getPath('userData')/desktop/settings.json` 缺失时生成该文件。已有文件会保留，字段缺失时默认为 `false`。平台路径和错误恢复方法见[本地桌面设置](../../../../apps/desktop/README.zh.md#local-desktop-settings)。
+2. 如需允许飞书登录，在文件中将 `updates.allowTestAuthPopupWindow` 设为 `true`，然后完全退出并重启 Desktop。此时测试策略的未鉴权响应可以提供登录入口。不需要登录弹窗时保持默认值即可。
+3. 如需再次关闭弹窗，将字段设为 `false` 并重启。启动和手动检查均不得显示飞书鉴权弹窗。更新仍会查询策略，鉴权失败不会解除已知强更阻塞。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/experimental-package-composition/guide.md

@@ -0,0 +1,28 @@
+---
+kind: upgrade-guide
+description: "Explicit installation, peer dependencies, and configuration for optional hooks, webhooks, tools, and skills."
+---
+
+# Explicit installation and composition for optional capabilities
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The CLI and Python runtime omit the hook bridges from their installation dependencies, and the CLI omits the webhook pair. Base and the full Web presets omit dormant Ralph rows, and base omits its dormant badge row. A patch that only enables a removed row does not insert its plugin. Default active behavior, plugin registration names, tool names, and recorded Session event names remain unchanged.
+
+Package ownership and naming follow the [experimental package policy](../../../../scripts/experimental-package-policy.ts). Installation and composition are separate: installing a plugin package does not mount it, and a bundle must be selected before its contributed rows can be configured.
+
+## Migration
+
+1. Install any packages missing from the target profile together with their required peers. Profiles disable automatic peer installation. For example, run `dsh plugin --profile web add @deepseek-ai/dsh-hooks-claude-code @deepseek-ai/dsh-hook-protocol`. The Codex bridge needs the same protocol peer; the GitHub adapter needs `@deepseek-ai/dsh-webhook` alongside `@deepseek-ai/dsh-webhook-github`.
+2. Select an available bundle before overriding its rows. For a capability composed manually, replace an override of a removed row with a complete insertion. Add preset-local tools inside that preset's `config.plugins`, including the services they require. A Host badge insertion is:
+
+   ```yaml
+   - insert:
+       - id: skill-badge
+         name: '@deepseek-ai/dsh-skill-badge'
+   ```
+
+3. For GitHub review, use the example distributed with the adapter instead of the removed CLI example. Follow the [installed-profile instructions](../../../user/guide/github-review.md); keep customized rule modules inside the profile so their imports resolve its installed packages.
+4. Start the profile and confirm that its configured plugins activate without missing-package, missing-peer, or missing-row errors. Confirm the expected tool or skill is available in the intended Agent preset.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/experimental-package-composition/guide.zh.md

@@ -0,0 +1,28 @@
+---
+kind: upgrade-guide
+description: "可选 hooks、webhooks、工具与技能所需的显式安装、peer 依赖和配置。"
+---
+
+# 可选能力的显式安装与组合
+
+[English](guide.md) | 中文
+
+## 变更
+
+CLI 与 Python 运行时的安装依赖不再包含 hook 桥接，CLI 也不再包含 webhook 包对。Base 与完整 Web 预设省略休眠的 Ralph 行，base 也省略休眠的徽章行。仅启用已移除行的 patch 不会插入其插件。默认活动行为、插件注册名称、工具名称与已记录的 Session 事件名称保持不变。
+
+包归属和命名遵循[实验包策略](../../../../scripts/experimental-package-policy.ts)。安装与组合相互独立：安装插件包不会挂载它，必须先选择 bundle 才能配置其贡献的行。
+
+## 迁移
+
+1. 将目标 profile 缺少的包与所需 peer 一起安装。Profile 禁用自动 peer 安装。例如，运行 `dsh plugin --profile web add @deepseek-ai/dsh-hooks-claude-code @deepseek-ai/dsh-hook-protocol`。Codex 桥接需要相同的协议 peer；GitHub 适配器需要同时安装 `@deepseek-ai/dsh-webhook` 与 `@deepseek-ai/dsh-webhook-github`。
+2. 覆盖 bundle 的行之前先选择可用的 bundle。对于手动组合的能力，将覆盖已移除行的 patch 替换为完整插入。在预设的 `config.plugins` 中添加预设内工具及其所需服务。Host 徽章插入示例：
+
+   ```yaml
+   - insert:
+       - id: skill-badge
+         name: '@deepseek-ai/dsh-skill-badge'
+   ```
+
+3. GitHub review 使用适配器随附的示例，替代已删除的 CLI 示例。遵循[安装版 profile 说明](../../../user/guide/github-review.zh.md)；将定制规则模块保留在 profile 内，使其导入能解析该 profile 安装的包。
+4. 启动 profile，确认配置的插件激活时没有缺包、缺 peer 或缺行错误。确认预期工具或技能在目标 Agent 预设中可用。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/instruction-home-override/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "The `agent-instructions` row no longer accepts `dshHome`; instruction loading always resolves the harness home from `$DSH_HOME` or `~/.dsh`."
+---
+
+# Instruction loading resolves one harness home
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-agent-instructions` removed its `dshHome` config field. The plugin resolves the harness home through `resolveDshHome()` from `@deepseek-ai/dsh-home-paths`, like every other harness consumer: the home is `$DSH_HOME` when it is set and non-blank, otherwise `~/.dsh`, with tilde expansion.
+
+A `cordis.yml`, profile patch, or `--patch` overlay that still sets `dshHome` on the `agent-instructions` row has no effect: the row keeps the stray key and the plugin ignores it, so instruction loading follows the process home. Other providers, such as `dsh-skill-filesystem` and `dsh-shell-env`, keep their own home fields; this removal covers the instruction loader only.
+
+## Migration
+
+1. Delete `dshHome` from the `agent-instructions` row in `cordis.yml`, `$DSH_HOME/cordis.patch.yml`, `$DSH_HOME/profiles/<profile>/cordis.patch.yml`, and any `--patch` overlay.
+2. Where the override pointed at a non-default home, export `DSH_HOME` for the process instead, so every harness consumer reads that home.
+3. Confirm with `dsh --profile <profile> --dump-config` that the `agent-instructions` row lists only its remaining fields, and that a new session's first request shows `Instructions from: $DSH_HOME/AGENTS.md` (or `~/.dsh/AGENTS.md`) when that file exists.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/instruction-home-override/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "`agent-instructions` 行不再接受 `dshHome`；指令加载始终从 `$DSH_HOME` 或 `~/.dsh` 解析 harness home。"
+---
+
+# 指令加载只解析一个 harness home
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-agent-instructions` 移除了 `dshHome` 配置字段。该插件通过 `@deepseek-ai/dsh-home-paths` 的 `resolveDshHome()` 解析 harness home，与 harness 其他消费方一致：`$DSH_HOME` 已设置且非空白时以它为准，否则使用 `~/.dsh`，并展开波浪号。
+
+`cordis.yml`、profile patch 或 `--patch` overlay 中 `agent-instructions` 行上残留的 `dshHome` 不再有任何效果：该行会保留这个多余键，插件忽略它，指令加载跟随进程 home。其他 provider（如 `dsh-skill-filesystem`、`dsh-shell-env`）保留各自的 home 字段；本次删除只覆盖指令加载器。
+
+## 迁移
+
+1. 从 `cordis.yml`、`$DSH_HOME/cordis.patch.yml`、`$DSH_HOME/profiles/<profile>/cordis.patch.yml` 以及任何 `--patch` overlay 的 `agent-instructions` 行中删除 `dshHome`。
+2. 若该覆盖原本指向非默认 home，改为在进程中导出 `DSH_HOME`，让所有 harness 消费方读取同一个 home。
+3. 用 `dsh --profile <profile> --dump-config` 确认 `agent-instructions` 行只剩其余字段，并确认新会话的首次请求在该文件存在时显示 `Instructions from: $DSH_HOME/AGENTS.md`（或 `~/.dsh/AGENTS.md`）。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/job-id-identity/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "JobId now identifies one background execution across registry lifetimes."
+---
+
+# Background job ids identify one execution
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The job registry returns `<kind>-<short-uuid>` instead of `<kind>-N`; the suffix is 16 lowercase UUID hex characters. The same `JobId` appears in live controls, `job/registered`, and `job/settled`; lifecycle records no longer carry `executionId`. The identifier remains owner-authorized. Existing Session histories remain unchanged and do not resume their jobs.
+
+## Migration
+
+1. Pass the exact id returned by a start result or `jobs.list()` to `job_output` and `job_kill`; use `job_output` with `wait: true` to wait. Remove code that constructs an id from the kind and an ordinal.
+2. Pair SDK lifecycle events by `data.jobId`. Remove imports of `JobExecutionId` and code that maps it to a process-local `jobId`.
+3. Verify a new job's registration and settlement contain the same `jobId`, and a later registry instance issues a different one.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/job-id-identity/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "JobId 现在跨注册表生命周期标识一次后台执行。"
+---
+
+# 后台 job id 标识一次执行
+
+[English](guide.md) | 中文
+
+## 变更
+
+job 注册表返回 `<kind>-<short-uuid>`，不再返回 `<kind>-N`；后缀是 UUID 的 16 位小写十六进制字符。运行期控制、`job/registered` 和 `job/settled` 使用同一个 `JobId`；生命周期记录不再携带 `executionId`。访问仍按所有者授权。已有 Session 历史保持原样，不会恢复其中的 job。
+
+## 迁移
+
+1. 把启动结果或 `jobs.list()` 返回的原始 id 传给 `job_output` 和 `job_kill`；等待时为 `job_output` 设置 `wait: true`。移除按 kind 和序号构造 id 的代码。
+2. 使用 `data.jobId` 配对 SDK 生命周期事件。移除 `JobExecutionId` 导入，以及将它映射为进程内 `jobId` 的代码。
+3. 核对新 job 的注册与结算含有相同 `jobId`，后续注册表实例发放不同 id。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/jsonl-persistence-plugin/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "JSONL persistence uses a namespace plugin import; direct service-class construction and class type annotations must use the persistence service instead."
+---
+
+# Mount JSONL persistence through its plugin
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-session-persistence-jsonl` exports a function plugin through named `name`, `Config`, and `apply` exports, with no default export. Default imports, direct construction, subclassing, `instanceof`, and class type annotations are affected. The plugin retains listeners and handles through the consumer unloads triggered by removing this provider; concurrent root disposal remains unordered. The `sessionPersistence` service API, YAML configuration, and stored files remain unchanged.
+
+## Migration
+
+1. Replace the default import with `import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'`. Existing `ctx.plugin(JsonlSessionPersistence, config)` calls remain valid; replace direct construction with this mounting call. For dynamic imports, use the module namespace returned by `await import(...)` instead of its `.default`. Consumers declare `inject: ['sessionPersistence']` and access `ctx.sessionPersistence`.
+2. Use the `SessionPersistence` type from `@deepseek-ai/dsh-session-persistence` for service annotations. Replace concrete-class `instanceof` checks and subclasses with consumers of that service; the concrete JSONL class is private.
+3. Await plugin startup and confirm a session can be created, flushed, and reopened. Register asynchronous consumer cleanup in the scope that injects `sessionPersistence` so backend unloading waits for it.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/jsonl-persistence-plugin/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "JSONL 持久化使用插件命名空间导入；直接构造服务类和类类型标注需要改用持久化服务。"
+---
+
+# 通过插件挂载 JSONL 持久化
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-session-persistence-jsonl` 通过命名导出的 `name`、`Config` 和 `apply` 提供函数插件，没有默认导出。默认导入、直接构造、继承、`instanceof` 和类类型标注会受到影响。插件会保留监听器和句柄，直到移除该提供者所触发的消费者卸载完成；根作用域的并发卸载仍不保证顺序。`sessionPersistence` 服务 API、YAML 配置和存储文件保持不变。
+
+## 迁移
+
+1. 将默认导入替换为 `import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'`。现有的 `ctx.plugin(JsonlSessionPersistence, config)` 调用仍然有效；将直接构造改为该挂载调用。动态导入直接使用 `await import(...)` 返回的模块命名空间，不再取其 `.default`。消费者声明 `inject: ['sessionPersistence']` 并访问 `ctx.sessionPersistence`。
+2. 服务类型标注使用 `@deepseek-ai/dsh-session-persistence` 的 `SessionPersistence` 类型。将针对具体类的 `instanceof` 检查和子类改为消费该服务；具体 JSONL 类是私有的。
+3. 等待插件启动完成，确认能够创建、flush 并重新打开会话。将消费者的异步清理注册到注入 `sessionPersistence` 的作用域中，以便后端卸载时等待它完成。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/mock-messages-events/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "Messages mock streams publish named SSE events for native SDK consumers."
+---
+
+# Read named events from the Messages mock server
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The next release makes `@deepseek-ai/dsh-llm-mock-server` emit the Messages event name beside each structured SSE payload. Native SDKs require these names to process message and content-block events. Consumers that accept only unnamed SSE messages must update their event handling. Scripted payloads, ordering, request capture, and chunk counts are unchanged; the deliberately malformed JSON behavior still sends its invalid data directly.
+
+## Migration
+
+1. Consume the named Messages events and parse their `data` fields. Do not filter the stream to unnamed events.
+2. Verify a complete text response, tool-call response, and the fault behaviors your test uses. The [mock server reference](../../../../packages/test-support/llm-mock-server/README.md) describes the available scripts.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/mock-messages-events/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "Messages 模拟流为原生 SDK 消费方发布具名 SSE 事件。"
+---
+
+# 读取 Messages 模拟服务器的具名事件
+
+[English](guide.md) | 中文
+
+## 变更
+
+下一版本的 `@deepseek-ai/dsh-llm-mock-server` 在每个结构化 SSE 载荷旁发送 Messages 事件名。原生 SDK 需要这些名称才能处理消息与内容块事件。只接受无名 SSE 消息的消费方必须更新事件处理。脚本载荷、顺序、请求捕获与分片计数保持不变；刻意生成畸形 JSON 的行为仍直接发送无效数据。
+
+## 迁移
+
+1. 消费具名 Messages 事件并解析其 `data` 字段。不要将流过滤为仅含无名事件。
+2. 验证完整文本响应、工具调用响应和测试使用的故障行为。[模拟服务器参考](../../../../packages/test-support/llm-mock-server/README.zh.md)说明了可用脚本。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/native-subagent-bundle-tools/guide.md

@@ -0,0 +1,31 @@
+---
+kind: upgrade-guide
+description: "Claude Code and Codex bundles add global delegation tools while retaining their package and row identities."
+---
+
+# Native subagent bundles include global tools
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-subagent-claude-code` and `@deepseek-ai/dsh-subagent-codex` keep their package names, bundle selections, provider row IDs, configuration, and native authentication. A selected bundle now also registers its delegation tool as a Host global tool, visible to every preset including minimal; previously the bundle registered only its provider. Live Agents see the tool from their next request after the bundle is enabled, and lose it after the bundle is switched off.
+
+The contributed Host rows are `tool-subagent-claude-code` and `tool-subagent-codex`. Later user layers can override their configuration or disabled state by row id. An override does not select an unselected bundle. A preset that registers its own tool with the same name shadows the global tool for its Agents.
+
+Delegation follows the shared managed-activation API: the tool returns a child ID, and completion arrives as a logged notice to the parent Agent. Remove obsolete `backgroundMode` settings; `maxDepth: provider-managed` remains supported for these native providers.
+
+## Migration
+
+1. Preserve selected bundle names, provider configuration, and authentication. Existing provider-only packages need **Update** in Plugins → Official to receive the tool-contributing bundle; restart when requested. To adopt a new provider, enable its card. [Installation targets](../../../../packages/boot/plugin-manager/README.md#use-this-package) follow the published DSH version or source checkout; equal version strings do not make an older registry package equivalent to a development link. Off only deselects; Remove remains separate.
+2. Configure the tool with an ordinary row patch. Configuration overrides still replace the complete configuration. For example, this keeps the Codex tool disabled while the provider stays registered:
+
+   ```yaml
+   - id: tool-subagent-codex
+     disabled: true
+   ```
+
+3. If a manual Host row registers the same tool name, remove that redundant row or disable the bundle's row. Verify the effective tool catalog in a Session.
+4. Plugin clients receive required `BundleInfo.official` and `BundleInfo.availability` fields; detail-slot `PluginPackageRef` receives them too. `official` identifies project maintenance, `availability` reports `installation`, `profile`, or `missing`, and `installed` still means a profile dependency declaration. Detail-slot readers that only display existing fields need no changes; constructors and exact validators must include the new fields. Optional `installTarget` identifies the offered version and registry or local-link spec.
+
+**Other profiles.** The bundle layers insert Host rows only, so headless, SDK, ACP, and custom profiles can select them as well. Profiles that keep the provider package without selecting its bundle can compose the same rows using the [Codex](../../../../packages/subagent/subagent-codex/README.md#exposing-the-tool) or [Claude Code](../../../../packages/subagent/subagent-claude-code/README.md#exposing-the-tool) example.