dsh-plugin-dev-kb 1.8.0 → 1.8.1

package/kb/extra/subsystems/worktrees.zh.md

@@ -1,127 +1,187 @@
-# Git 工作树
-
-[English](worktrees.md) | 中文
-
-实验性的 [`dsh-experimental-worktree`](../../packages/experimental/worktree/README.zh.md) 服务提供 `ctx.worktrees`。其消费方 [`create_worktree`](../../packages/experimental/tool-worktree/README.zh.md) 创建新的 Git 分支与检出目录，再通过[工作目录服务](working-directory.zh.md)选中它。[变更请求与工作树组合包](../../packages/experimental/forge-bundle/README.zh.md#use-this-package)通过 GUI 插件管理器一起加载这两个包，随安装提供但默认关闭。其他 profile 可以选择[独立工作树组合包](../../packages/experimental/tool-worktree/README.zh.md#use-this-package)，或显式挂载这两个包。
-
-## 创建与保留
-
-调用方 Session 的当前目录决定源仓库。创建操作在分配检出目录前，将请求的本地提交、分支或标签固定为具体提交；省略时选择 `HEAD`。每个名称必须对应新分支与未使用的检出路径。操作既不获取缺失对象，也不复制源检出目录中的暂存、未暂存、未跟踪或被忽略文件。
-
-默认目标为 `<current checkout root>/.agents/worktrees/<name>`。`repositoryRoot` 是调用方当前检出目录的顶层目录；因此，链接检出目录会在自身内部保存工作树父目录。仅当服务的分配操作创建了配置指定的父目录时，服务才会写入内容为 `*` 加换行符的 `.gitignore`。已有文件与忽略规则保持不变。调用方 Session 的现有沙箱策略必须允许写入目标目录与共享 Git 管理目录。Git 初始化成功后才改变工作目录。
-
-通过 `working_directory({ cd: path })` 离开时，会保留检出目录与分支。取消或失败也可能留下部分产物；错误会指出它们的位置。服务销毁时会中止待完成操作并等待它们结束。[包 README](../../packages/experimental/worktree/README.zh.md)拥有配置与 Git 要求。
-
-## 请求与结果
-
-请求只选择新名称与本地版本。结果标识创建的检出目录与确切提交；它不会改变 Session 的原始项目或写权限。可选的回调会在创建的每个阶段开始之前收到该阶段。恢复会在记录的目录重新检出已删除的检出目录：从它的分支检出；分支也已删除时，从它的基准提交检出。
-
-```ts type-equiv
-/** A new checkout from a locally available Git commit, branch, or tag. */
-interface CreateWorktreeRequest {
-  /** New branch name, also used as the relative checkout directory; omission generates a name. */
-  name?: string
-  /** Local revision to resolve before creation; omission selects HEAD. */
-  from?: string
-}
-```
-
-```ts type-equiv
-/** Committed Git baseline and the calling Session's resulting working directory. */
-interface CreatedWorktree {
-  /** Canonical absolute checkout directory in the filesystem provider's execution world. */
-  path: string
-  /** Newly created branch name. */
-  branch: string
-  /** Resolved commit object name; repository-local replacement refs can change its checked-out content. */
-  baseCommit: string
-  /** Canonical root of the source checkout. */
-  repositoryRoot: string
-}
-```
-
-```ts type-equiv
-/**
- * Stage of one creation or restoration, reported before it begins: `prepare`
- * validates the request, allocates the checkout directory, and creates the
- * branch, which a restoration creates again only when it is gone; `checkout`
- * writes the files and, for a creation, enters the checkout.
- */
-type CreateWorktreePhase = 'prepare' | 'checkout'
-```
-
-```ts type-equiv
-/** A removed checkout to check out again at its recorded directory. */
-interface RestoreWorktreeRequest {
-  /** Canonical checkout directory the worktree had. */
-  path: string
-  /** Branch the worktree had checked out. */
-  branch: string
-  /** Commit the branch started from; a branch that no longer exists is created again here. */
-  baseCommit: string
-  /** Canonical root of the source checkout. */
-  repositoryRoot: string
-}
-```
-
-```ts type-equiv
-/** Outcome of one restoration. */
-interface RestoredWorktree {
-  /** Checkout directory, present again. */
-  path: string
-  /** Whether the branch no longer existed and was created again at the base commit, without the commits it had gained. */
-  branchRecreated: boolean
-}
-```
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxworktrees--worktreeservice"></a>
-
-### `ctx.worktrees` — `WorktreeService`
-
-Creates retained Git worktrees under the mounted filesystem and sandbox providers.
-
-```ts cordis-catalog
-/**
- * Create a fresh branch and checkout at a pinned local revision, then enter it.
- * Existing branches or checkout paths fail. Uncommitted files stay in the source checkout.
- * Checkout disables configured clean, smudge, and process filters without changing Git config.
- * Repository-local replacement refs still apply; baseCommit reports the resolved object name.
- * The new checkout becomes current only after Git setup succeeds. Failures may retain newly
- * allocated Git/filesystem artifacts; no branch or checkout is removed automatically.
- * @param agent - caller whose current directory selects the source repository and file policy.
- * @param request - optional new name and local revision; defaults are generated name and HEAD.
- * @param signal - cancellation of lookup, creation, and working-directory publication.
- * @param onPhase - receives each stage before it begins; it must not throw.
- * @returns canonical checkout path, branch name, pinned commit, and source repository root.
- */
-async create( agent: Agent, request: CreateWorktreeRequest = {}, signal?: AbortSignal, onPhase?: (phase: CreateWorktreePhase) => void, ): Promise<CreatedWorktree>
-
-/**
- * Check out a removed worktree again at its recorded directory: its branch
- * when the branch still exists, otherwise a new branch of the same name at
- * `baseCommit`. Only the missing target's unlocked registration is removed, and an
- * existing directory fails. Changes that were never committed are not
- * recovered. Checkout disables configured clean, smudge, and process filters,
- * as creation does. The calling Session's working directory does not change.
- * Failures may retain newly allocated Git/filesystem artifacts.
- * @param agent - caller whose sandbox policy confines the commands.
- * @param request - recorded directory, branch, base commit, and source repository root.
- * @param signal - cancellation of the restoration.
- * @param onPhase - receives each stage before it begins; it must not throw.
- * @returns the directory and whether the branch was created again.
- */
-async restore( agent: Agent, request: RestoreWorktreeRequest, signal?: AbortSignal, onPhase?: (phase: CreateWorktreePhase) => void, ): Promise<RestoredWorktree>
-```
-
-Types: [Agent](core.zh.md)
-
-Source: [`packages/experimental/worktree/src/index.ts`](../../packages/experimental/worktree/src/index.ts)
-<!-- END GENERATED cordis-surface -->
+# Git 工作树
+
+[English](worktrees.md) | 中文
+
+实验性的 [`dsh-experimental-worktree`](../../packages/experimental/worktree/README.zh.md) 服务提供 `ctx.worktrees`。其消费方 [`create_worktree`](../../packages/experimental/tool-worktree/README.zh.md) 创建新的 Git 分支与检出目录，再通过[工作目录服务](working-directory.zh.md)选中它。[变更请求与工作树组合包](../../packages/experimental/forge-bundle/README.zh.md#use-this-package)通过 GUI 插件管理器一起加载这两个包，随安装提供但默认关闭。其他 profile 可以选择[独立工作树组合包](../../packages/experimental/tool-worktree/README.zh.md#use-this-package)，或显式挂载这两个包。
+
+## 创建与保留
+
+调用方 Session 的当前目录决定源仓库。创建操作在分配检出目录前，将请求的本地提交、分支或标签固定为具体提交；省略时选择 `HEAD`。每个名称必须对应新分支与未使用的检出路径。操作既不获取缺失对象，也不复制源检出目录中的暂存、未暂存、未跟踪或被忽略文件。
+
+默认目标为 `<current checkout root>/.agents/worktrees/<name>`。`repositoryRoot` 是调用方当前检出目录的顶层目录；因此，链接检出目录会在自身内部保存工作树父目录。仅当服务的分配操作创建了配置指定的父目录时，服务才会写入内容为 `*` 加换行符的 `.gitignore`。已有文件与忽略规则保持不变。调用方 Session 的现有沙箱策略必须允许写入目标目录与共享 Git 管理目录。Git 初始化成功后才改变工作目录。
+
+通过 `working_directory({ cd: path })` 离开时，会保留检出目录与分支。取消或失败也可能留下部分产物；错误会指出它们的位置。worktree 失败抛出带 `WORKTREE_*` code 的 `WorktreeError`；分配开始后的失败保留被包装错误的 `name` 与 `code`，调用方取消仍为 `AbortError`。服务销毁时会中止待完成操作并等待它们结束。[包 README](../../packages/experimental/worktree/README.zh.md)拥有配置与 Git 要求。
+
+## 请求与结果
+
+请求只选择新名称与本地版本。结果标识创建的检出目录与确切提交；它不会改变 Session 的原始项目或写权限。可选的回调会在创建的每个阶段开始之前收到该阶段。恢复会在记录的目录重新检出已删除的检出目录：从它的分支检出；分支也已删除时，从它的基准提交检出。
+
+```ts type-equiv
+/** A new checkout from a locally available Git commit, branch, or tag. */
+interface CreateWorktreeRequest {
+  /** New branch name, also used as the relative checkout directory; omission generates a name. */
+  name?: string
+  /** Local revision to resolve before creation; omission selects HEAD. */
+  from?: string
+}
+```
+
+```ts type-equiv
+/** Committed Git baseline and the calling Session's resulting working directory. */
+interface CreatedWorktree {
+  /** Canonical absolute checkout directory in the filesystem provider's execution world. */
+  path: string
+  /** Newly created branch name. */
+  branch: string
+  /** Resolved commit object name; repository-local replacement refs can change its checked-out content. */
+  baseCommit: string
+  /** Canonical root of the source checkout. */
+  repositoryRoot: string
+}
+```
+
+```ts type-equiv
+/**
+ * Stage of one creation or restoration, reported before it begins: `prepare`
+ * validates the request, allocates the checkout directory, and creates the
+ * branch, which a restoration creates again only when it is gone; `checkout`
+ * writes the files and, for a creation, enters the checkout.
+ */
+type CreateWorktreePhase = 'prepare' | 'checkout'
+```
+
+```ts type-equiv
+/** A removed checkout to check out again at its recorded directory. */
+interface RestoreWorktreeRequest {
+  /** Canonical checkout directory the worktree had. */
+  path: string
+  /** Branch the worktree had checked out. */
+  branch: string
+  /** Commit the branch started from; a branch that no longer exists is created again here. */
+  baseCommit: string
+  /** Canonical root of the source checkout. */
+  repositoryRoot: string
+}
+```
+
+```ts type-equiv
+/** Outcome of one restoration. */
+interface RestoredWorktree {
+  /** Checkout directory, present again. */
+  path: string
+  /** Whether the branch no longer existed and was created again at the base commit, without the commits it had gained. */
+  branchRecreated: boolean
+}
+```
+
+```ts type-equiv
+/** One checkout in a Session's log and whether that Session, rather than a fork ancestor, created it. */
+interface WorktreeCreation {
+  readonly worktree: CreatedWorktree
+  /** False for a creation inside the fork-inherited prefix. */
+  readonly owned: boolean
+}
+```
+
+```ts type-equiv
+/** Process-local state of one archive-triggered cleanup of a checkout. */
+interface WorktreeCleanup {
+  /** Monotonic attempt number within this Host lifetime; a Remote waits on a specific one. */
+  readonly revision: number
+  /**
+   * `scheduled` until the background inspection ends; `retained` when a use,
+   * policy, or Git state keeps the checkout; `removed` after `git worktree
+   * remove`; `failed` when removal threw and may have left a partial directory.
+   */
+  readonly status: 'scheduled' | 'retained' | 'removed' | 'failed'
+}
+```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxworktrees--worktreeservice"></a>
+
+### `ctx.worktrees` — `WorktreeService`
+
+Creates retained Git worktrees under the mounted filesystem and sandbox providers, records each creation in the Session log, and reclaims a clean, unreferenced checkout when the Session that created it is archived.
+
+```ts cordis-catalog
+/**
+ * Create a fresh branch and checkout at a pinned local revision, then enter it.
+ * Existing branches or checkout paths fail. Uncommitted files stay in the source checkout.
+ * Checkout disables configured clean, smudge, and process filters without changing Git config.
+ * Repository-local replacement refs still apply; baseCommit reports the resolved object name.
+ * The new checkout becomes current only after Git setup succeeds. Failures may retain newly
+ * allocated Git/filesystem artifacts; no branch or checkout is removed automatically.
+ * @param agent - caller whose current directory selects the source repository and file policy.
+ * @param request - optional new name and local revision; defaults are generated name and HEAD.
+ * @param signal - cancellation of lookup, creation, and working-directory publication.
+ * @param onPhase - receives each stage before it begins; it must not throw.
+ * @returns canonical checkout path, branch name, pinned commit, and source repository root.
+ * @throws {WorktreeError} for an invalid request, an existing branch or path, or a failed, oversized, or timed-out
+ *   command; a failure after allocation keeps its `name` and `code` and adds retained-artifact context.
+ */
+async create( agent: Agent, request: CreateWorktreeRequest = {}, signal?: AbortSignal, onPhase?: (phase: CreateWorktreePhase) => void, ): Promise<CreatedWorktree>
+
+/**
+ * Check out a removed worktree again at its recorded directory: its branch
+ * when the branch still exists, otherwise a new branch of the same name at
+ * `baseCommit`. Only the missing target's unlocked registration is removed, and an
+ * existing directory fails. Changes that were never committed are not
+ * recovered. Checkout disables configured clean, smudge, and process filters,
+ * as creation does. The calling Session's working directory does not change.
+ * Failures may retain newly allocated Git/filesystem artifacts.
+ * @param agent - caller whose sandbox policy confines the commands.
+ * @param request - recorded directory, branch, base commit, and source repository root.
+ * @param signal - cancellation of the restoration.
+ * @param onPhase - receives each stage before it begins; it must not throw.
+ * @returns the directory and whether the branch was created again.
+ * @throws {WorktreeError} for an invalid request, an existing path, a locked registration, or a failed, oversized,
+ *   or timed-out command; a failure after allocation keeps its `name` and `code` and adds retained-artifact context.
+ */
+async restore( agent: Agent, request: RestoreWorktreeRequest, signal?: AbortSignal, onPhase?: (phase: CreateWorktreePhase) => void, ): Promise<RestoredWorktree>
+
+/**
+ * Read the archive cleanup of a Session's created checkout; waiting never
+ * starts one. Absent without the Workspace and query providers.
+ * @param session - archived Session whose cleanup is read.
+ * @param revision - null reads at once; a matching revision waits for that attempt to settle.
+ * @returns the attempt state, or null when none exists, the revision was superseded, or the service is stopping.
+ */
+async cleanupOf(session: Session, revision: number | null): Promise<WorktreeCleanup | null>
+```
+
+Types: [Agent](core.zh.md) · [Session](session.zh.md)
+
+Source: [`packages/experimental/worktree/src/index.ts`](../../packages/experimental/worktree/src/index.ts)
+
+<a id="worktree-events"></a>
+
+### `worktree/*` events
+
+<a id="worktreecleanup--emit"></a>
+
+#### `worktree/cleanup` — emit
+
+A cleanup attempt changed state. Fires once at admission with `scheduled` and once at settlement with the final status.
+
+```ts cordis-catalog
+/**
+ * A cleanup attempt changed state. Fires once at admission with
+ * `scheduled` and once at settlement with the final status.
+ * @param info - the archived Session, the checkout, and the attempt state.
+ * @mode emit
+ */
+'worktree/cleanup'(info: { sessionId: SessionId; path: string; cleanup: WorktreeCleanup }): void
+```
+
+Types: [SessionId](core.zh.md)
+
+Source: [`packages/experimental/worktree/src/archive.ts`](../../packages/experimental/worktree/src/archive.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/python-ptc-sandbox/guide.md

@@ -1,21 +1,21 @@
----
-kind: upgrade-guide
-description: "Python PTC compositions require sandbox services, and direct Python file operations follow the resolved file policy."
----
-
-# Python PTC applies the shared file sandbox
-
-English | [中文](guide.zh.md)
-
-## Change
-
-`@deepseek-ai/dsh-experimental-ptc-runtime-python` requires `sandbox` and `sandboxPolicy`. Previously, direct Python file operations ran without confinement and the provider rejected explicit `sandboxPolicy` inputs. It now applies the shared policy to each program and reports confinement in `PtcRunResult.sandbox`. A restricted run fails with `sandbox-unavailable` when confinement cannot be established.
-
-This affects custom compositions that select the Python runtime. Shipped profiles continue to use the Node runtime. Python remains local to macOS or Linux; its configured resource budgets and unsupported per-call timeout overrides remain unchanged.
-
-## Migration
-
-1. In the `cordis.yml` or profile patch that selects the Python runtime, retain the existing shared sandbox services. If they are absent, mount `@deepseek-ai/dsh-sandbox-local` and `@deepseek-ai/dsh-sandbox-policy` with its required `@deepseek-ai/dsh-session-projection` service. See the [Python runtime requirements](../../../../packages/experimental/ptc-runtime-python/README.md#use-this-package).
-2. Set the shared `sandbox-policy` row's `mode` and `workspaceRoot` for agentless calls. Its default mode is `read-only`; `workspace-write` permits workspace writes. PTC tool calls use the Session's resolved policy and directory. Do not add a separate Python-only sandbox setting.
-3. Direct service callers use `runtime.run(runtime.resolve(request))`; pass a trusted `sandboxPolicy` only when an explicit override is required. Model-facing `run_code` uses the existing approval flow for a one-call wider mode, without changing nested tools' permissions or replaying the program automatically.
-4. Verify a program can write inside the intended workspace under `workspace-write`, fails to write outside it, and returns `result.sandbox.mode` and `result.sandbox.enforcement`. Under `read-only`, direct file writes fail. Inspect `sandbox-unavailable` separately from a denied file operation and repair the local sandbox installation before retrying.
+---
+kind: upgrade-guide
+description: "Python PTC compositions require sandbox services, and direct Python file operations follow the resolved file policy."
+---
+
+# Python PTC applies the shared file sandbox
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-experimental-ptc-runtime-python` requires `sandbox` and `sandboxPolicy`. Previously, direct Python file operations ran without confinement and the provider rejected explicit `sandboxPolicy` inputs. It now applies the shared policy to each program and reports confinement in `PtcRunResult.sandbox`. A restricted run fails with `sandbox-unavailable` when confinement cannot be established.
+
+This affects custom compositions that select the Python runtime. Shipped profiles continue to use the Node runtime. Python remains local to macOS or Linux; its configured resource budgets and unsupported per-call timeout overrides remain unchanged.
+
+## Migration
+
+1. In the `cordis.yml` or profile patch that selects the Python runtime, retain the existing shared sandbox services. If they are absent, mount `@deepseek-ai/dsh-sandbox-local` and `@deepseek-ai/dsh-sandbox-policy` with its required `@deepseek-ai/dsh-session-projection` service. See the Python runtime requirements ([English](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.2/packages/experimental/ptc-runtime-python/README.md#use-this-package), [中文](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.2/packages/experimental/ptc-runtime-python/README.zh.md#use-this-package)).
+2. Set the shared `sandbox-policy` row's `mode` and `workspaceRoot` for agentless calls. Its default mode is `read-only`; `workspace-write` permits workspace writes. PTC tool calls use the Session's resolved policy and directory. Do not add a separate Python-only sandbox setting.
+3. Direct service callers use `runtime.run(runtime.resolve(request))`; pass a trusted `sandboxPolicy` only when an explicit override is required. Model-facing `run_code` uses the existing approval flow for a one-call wider mode, without changing nested tools' permissions or replaying the program automatically.
+4. Verify a program can write inside the intended workspace under `workspace-write`, fails to write outside it, and returns `result.sandbox.mode` and `result.sandbox.enforcement`. Under `read-only`, direct file writes fail. Inspect `sandbox-unavailable` separately from a denied file operation and repair the local sandbox installation before retrying.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/python-ptc-sandbox/guide.zh.md

@@ -1,21 +1,21 @@
----
-kind: upgrade-guide
-description: "Python PTC 组合需要沙箱服务，且直接 Python 文件操作遵循已解析文件策略。"
----
-
-# Python PTC 应用共享文件沙箱
-
-[English](guide.md) | 中文
-
-## 变更
-
-`@deepseek-ai/dsh-experimental-ptc-runtime-python` 需要 `sandbox` 和 `sandboxPolicy`。此前，直接 Python 文件操作不受约束，提供方拒绝显式 `sandboxPolicy` 输入。现在，它为每个程序应用共享策略，并通过 `PtcRunResult.sandbox` 报告约束情况。无法建立约束时，受限运行以 `sandbox-unavailable` 失败。
-
-这影响选择 Python 运行时的自定义组合。已发布 profile 继续使用 Node 运行时。Python 仍限于本地 macOS 或 Linux；其配置的资源预算保持不变，仍不支持单次 timeout 覆盖。
-
-## 迁移
-
-1. 在选择 Python 运行时的 `cordis.yml` 或 profile patch 中，保留已有共享沙箱服务。若尚未提供，挂载 `@deepseek-ai/dsh-sandbox-local` 和 `@deepseek-ai/dsh-sandbox-policy`，以及后者所需的 `@deepseek-ai/dsh-session-projection` 服务。参见 [Python 运行时要求](../../../../packages/experimental/ptc-runtime-python/README.zh.md#use-this-package)。
-2. 为无 Agent 调用设置共享 `sandbox-policy` 行的 `mode` 和 `workspaceRoot`。默认模式是 `read-only`；`workspace-write` 允许工作区写入。PTC 工具调用使用 Session 的已解析策略和目录。不要新增 Python 专用沙箱设置。
-3. 直接服务调用方使用 `runtime.run(runtime.resolve(request))`；仅在需要显式覆盖时传入可信 `sandboxPolicy`。面向模型的 `run_code` 通过现有审批流程为一次调用扩大权限，不改变嵌套工具的权限，也不自动重放程序。
-4. 验证程序在 `workspace-write` 下可以写入预期工作区、写入工作区外时失败，并返回 `result.sandbox.mode` 和 `result.sandbox.enforcement`。在 `read-only` 下，直接文件写入失败。将 `sandbox-unavailable` 与文件操作被拒绝区分处理，修复本地沙箱安装后再重试。
+---
+kind: upgrade-guide
+description: "Python PTC 组合需要沙箱服务，且直接 Python 文件操作遵循已解析文件策略。"
+---
+
+# Python PTC 应用共享文件沙箱
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-experimental-ptc-runtime-python` 需要 `sandbox` 和 `sandboxPolicy`。此前，直接 Python 文件操作不受约束，提供方拒绝显式 `sandboxPolicy` 输入。现在，它为每个程序应用共享策略，并通过 `PtcRunResult.sandbox` 报告约束情况。无法建立约束时，受限运行以 `sandbox-unavailable` 失败。
+
+这影响选择 Python 运行时的自定义组合。已发布 profile 继续使用 Node 运行时。Python 仍限于本地 macOS 或 Linux；其配置的资源预算保持不变，仍不支持单次 timeout 覆盖。
+
+## 迁移
+
+1. 在选择 Python 运行时的 `cordis.yml` 或 profile patch 中，保留已有共享沙箱服务。若尚未提供，挂载 `@deepseek-ai/dsh-sandbox-local` 和 `@deepseek-ai/dsh-sandbox-policy`，以及后者所需的 `@deepseek-ai/dsh-session-projection` 服务。参见 Python 运行时要求（[English](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.2/packages/experimental/ptc-runtime-python/README.md#use-this-package), [中文](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.2/packages/experimental/ptc-runtime-python/README.zh.md#use-this-package)）。
+2. 为无 Agent 调用设置共享 `sandbox-policy` 行的 `mode` 和 `workspaceRoot`。默认模式是 `read-only`；`workspace-write` 允许工作区写入。PTC 工具调用使用 Session 的已解析策略和目录。不要新增 Python 专用沙箱设置。
+3. 直接服务调用方使用 `runtime.run(runtime.resolve(request))`；仅在需要显式覆盖时传入可信 `sandboxPolicy`。面向模型的 `run_code` 通过现有审批流程为一次调用扩大权限，不改变嵌套工具的权限，也不自动重放程序。
+4. 验证程序在 `workspace-write` 下可以写入预期工作区、写入工作区外时失败，并返回 `result.sandbox.mode` 和 `result.sandbox.enforcement`。在 `read-only` 下，直接文件写入失败。将 `sandbox-unavailable` 与文件操作被拒绝区分处理，修复本地沙箱安装后再重试。

package/kb/extra/upgrade-guide/v0.2.1-rc.4/sandbox-unsupported-policy-error/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The sandbox package removes SandboxUnsupportedPolicyError; Windows processes ignore additional writable roots."
+---
+
+# Remove SandboxUnsupportedPolicyError imports
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-sandbox` no longer exports `SandboxUnsupportedPolicyError`. Windows subprocess confinement ignores additional writable directories instead of rejecting execution with `SANDBOX_UNSUPPORTED_POLICY`. The harness `write` and `edit` tools still honor those directories; Windows processes retain workspace and private-temp access under `workspace-write`.
+
+## Migration
+
+1. Remove imports and error handlers specific to `SandboxUnsupportedPolicyError` or `SANDBOX_UNSUPPORTED_POLICY`.
+2. Use the harness file tools for writes to additional directories on Windows. Do not assume a successful process launch grants those directories.
+3. Rebuild the consumer and verify that workspace commands run while extra directories remain accessible only through the file tools.

package/kb/extra/upgrade-guide/v0.2.1-rc.4/sandbox-unsupported-policy-error/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "sandbox 包移除 SandboxUnsupportedPolicyError；Windows 进程忽略额外可写根目录。"
+---
+
+# 移除 SandboxUnsupportedPolicyError 导入
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-sandbox` 不再导出 `SandboxUnsupportedPolicyError`。Windows 子进程隔离忽略额外可写目录，不再以 `SANDBOX_UNSUPPORTED_POLICY` 拒绝执行。Harness 的 `write` 与 `edit` 工具仍执行这些目录的授权；Windows 进程在 `workspace-write` 下保留工作区与私有临时目录访问权限。
+
+## 迁移
+
+1. 移除针对 `SandboxUnsupportedPolicyError` 或 `SANDBOX_UNSUPPORTED_POLICY` 的导入与错误处理。
+2. 在 Windows 上使用 Harness 文件工具写入额外目录。不要假定进程启动成功就意味着这些目录已获授权。
+3. 重新构建消费方，验证工作区命令可以运行，额外目录仍仅能通过文件工具访问。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/llm-error-builtin-codes/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "`new LlmError` accepts only built-in failure codes; other codes go through `LlmError.fromFailure`."
+---
+
+# `new LlmError` accepts only built-in failure codes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In `@deepseek-ai/dsh-llm`, the `code` parameter of the `LlmError` constructor was `string` and is now `BuiltinLlmFailureCode`: a key of `LLM_FAILURE_CODES` or `HTTP_<status>`. Runtime behavior and `LlmFailure.code` are unchanged. TypeScript code that constructs `LlmError` with any other code, such as an out-of-tree provider adapter or a test double, no longer compiles.
+
+## Migration
+
+1. Replace each `new LlmError(message, code, options)` whose `code` is not built-in with `LlmError.fromFailure({ message, code, ...facts }, { cause })`, where `facts` holds any `status`, `providerRetryAfterMs`, `requestId`, or `offloadImages`.
+2. Re-raise a failure received from a stream with `LlmError.fromFailure(finish.failure)` instead of passing `finish.failure.code` to the constructor.
+3. Confirm with `tsc` that no `LlmError` construction reports a code that is not assignable to `BuiltinLlmFailureCode`.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/llm-error-builtin-codes/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "`new LlmError` 只接受内置失败 code；其他 code 改用 `LlmError.fromFailure`。"
+---
+
+# `new LlmError` 只接受内置失败 code
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 `@deepseek-ai/dsh-llm` 中，`LlmError` 构造函数的 `code` 参数原为 `string`，现为 `BuiltinLlmFailureCode`：`LLM_FAILURE_CODES` 的键或 `HTTP_<status>`。运行时行为和 `LlmFailure.code` 不变。用其他 code 构造 `LlmError` 的 TypeScript 代码（例如仓库外的提供方适配器或测试替身）将无法通过编译。
+
+## 迁移
+
+1. 把每个 `code` 不是内置值的 `new LlmError(message, code, options)` 改为 `LlmError.fromFailure({ message, code, ...facts }, { cause })`，其中 `facts` 包含需要的 `status`、`providerRetryAfterMs`、`requestId` 或 `offloadImages`。
+2. 重新抛出从流中收到的失败时，使用 `LlmError.fromFailure(finish.failure)`，而不是把 `finish.failure.code` 传给构造函数。
+3. 用 `tsc` 确认没有任何 `LlmError` 构造报告 code 不能赋值给 `BuiltinLlmFailureCode`。

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-kit-package/guide.md

@@ -0,0 +1,34 @@
+---
+kind: upgrade-guide
+description: "`@deepseek-ai/dsh-office-kit` replaces `@deepseek-ai/dsh-office-to-pdf`, renaming its service, Remote methods, exported types, and configuration row."
+---
+
+# `@deepseek-ai/dsh-office-kit` replaces `@deepseek-ai/dsh-office-to-pdf`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Office conversion provider moved from `@deepseek-ai/dsh-office-to-pdf` to `@deepseek-ai/dsh-office-kit`. Compositions, plugins, and Clients that name the old package, service, Remote methods, or exported symbols are affected:
+
+| Old | New |
+|---|---|
+| `cordis.yml` row `id: office-to-pdf`, `name: '@deepseek-ai/dsh-office-to-pdf'` | `id: office-kit`, `name: '@deepseek-ai/dsh-office-kit'`; configuration keys are unchanged |
+| `ctx.officeToPdf` | `ctx.officeKit` |
+| Remote `officeToPdf/render`, `officeToPdf/generation` | `officeKit/render`, `officeKit/generation` |
+| `OfficeToPdf` | `OfficeKit` |
+| `OfficeToPdfError`, `OfficeToPdfErrorCode` | `OfficeKitError`, `OfficeKitErrorCode` |
+| `OfficeToPdfGeneration` | `OfficeKitGeneration` |
+| `OfficeToPdfRequest`, `OfficeToPdfResult`, `OfficeToPdfPriority`, `OfficeToPdfKey` | `OfficeKitRequest`, `OfficeKitResult`, `OfficeKitPriority`, `OfficeKitKey` |
+
+The `document-render/failed` Remote error, `RenderedDocumentBytes`, `OfficeSourceKey`, and `OfficeExtension` keep their names. The `/types` and `/remote` entries remain.
+
+The provider previously failed to load when LibreOffice Kit was absent. It now registers without Kit; each conversion that needs a converter rejects with `OfficeKitError` code `unavailable` and locates Kit again, so installing Kit later takes effect without reloading the provider.
+
+## Migration
+
+1. In `cordis.yml`, patches, and overlays, change the row `id: office-to-pdf` to `id: office-kit` and its `name` to `'@deepseek-ai/dsh-office-kit'`. Keep its `config` block unchanged.
+2. Replace the dependency `@deepseek-ai/dsh-office-to-pdf` with `@deepseek-ai/dsh-office-kit` in `package.json`, and update import specifiers, including `/types` and `/remote`.
+3. Rename `ctx.officeToPdf`, Remote method names, and the exported symbols listed above.
+4. Code that treated a load failure of the conversion row as "Kit absent" now checks for `OfficeKitError` with code `unavailable` from conversion instead.
+5. Confirm the migration by searching the project for `office-to-pdf`, `officeToPdf`, and `OfficeToPdf`, then opening a DOCX file in the Web document preview.

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-kit-package/guide.zh.md

@@ -0,0 +1,34 @@
+---
+kind: upgrade-guide
+description: "`@deepseek-ai/dsh-office-kit` 取代 `@deepseek-ai/dsh-office-to-pdf`，其服务、Remote 方法、导出类型和配置行随之改名。"
+---
+
+# `@deepseek-ai/dsh-office-kit` 取代 `@deepseek-ai/dsh-office-to-pdf`
+
+[English](guide.md) | 中文
+
+## 变更
+
+Office 转换提供方从 `@deepseek-ai/dsh-office-to-pdf` 移到 `@deepseek-ai/dsh-office-kit`。引用旧包、服务、Remote 方法或导出符号的组合、插件和 Client 受到影响：
+
+| 旧名 | 新名 |
+|---|---|
+| `cordis.yml` 行 `id: office-to-pdf`、`name: '@deepseek-ai/dsh-office-to-pdf'` | `id: office-kit`、`name: '@deepseek-ai/dsh-office-kit'`；配置项不变 |
+| `ctx.officeToPdf` | `ctx.officeKit` |
+| Remote `officeToPdf/render`、`officeToPdf/generation` | `officeKit/render`、`officeKit/generation` |
+| `OfficeToPdf` | `OfficeKit` |
+| `OfficeToPdfError`、`OfficeToPdfErrorCode` | `OfficeKitError`、`OfficeKitErrorCode` |
+| `OfficeToPdfGeneration` | `OfficeKitGeneration` |
+| `OfficeToPdfRequest`、`OfficeToPdfResult`、`OfficeToPdfPriority`、`OfficeToPdfKey` | `OfficeKitRequest`、`OfficeKitResult`、`OfficeKitPriority`、`OfficeKitKey` |
+
+Remote 错误 `document-render/failed`、`RenderedDocumentBytes`、`OfficeSourceKey` 和 `OfficeExtension` 保持原名。`/types` 和 `/remote` 入口仍然保留。
+
+原先 LibreOffice Kit 缺失时提供方加载失败。现在没有 Kit 时提供方照常注册；每次需要转换器的转换都以代码为 `unavailable` 的 `OfficeKitError` 拒绝，并重新定位 Kit，因此之后安装的 Kit 无需重新加载提供方即可生效。
+
+## 迁移
+
+1. 在 `cordis.yml`、patch 和 overlay 中，把 `id: office-to-pdf` 行改为 `id: office-kit`，并把其 `name` 改为 `'@deepseek-ai/dsh-office-kit'`。`config` 块保持不变。
+2. 在 `package.json` 中用 `@deepseek-ai/dsh-office-kit` 替换依赖 `@deepseek-ai/dsh-office-to-pdf`，并更新导入路径，包括 `/types` 和 `/remote`。
+3. 按上表重命名 `ctx.officeToPdf`、Remote 方法名和导出符号。
+4. 原先把转换行加载失败视为“Kit 缺失”的代码，改为检查转换返回的、代码为 `unavailable` 的 `OfficeKitError`。
+5. 在项目中搜索 `office-to-pdf`、`officeToPdf` 和 `OfficeToPdf` 确认已无残留，然后在 Web 文档预览中打开一个 DOCX 文件，确认迁移完成。

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-operation-tools/guide.md

@@ -0,0 +1,49 @@
+---
+kind: upgrade-guide
+description: "The `office-render`, `office-recalculate`, and `office-export-pdf` skills, the skill-office `node` and `cli` keys, and two Office CLI environment variables are removed; Office operations use skill-activated tools."
+---
+
+# Office operation skills are replaced by Office tools
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-skill-office` no longer registers the `office-render`, `office-recalculate`, and `office-export-pdf` skills; it registers the `office` router and the `office-docx`, `office-pptx`, and `office-xlsx` authoring skills. After an Office skill loads, the model calls [`office_render`, `office_convert`, and `office_recalculate`](../../../../packages/document/tool-office/README.md) from the following step.
+
+Configuration changes:
+
+| Removed | Replacement |
+|---|---|
+| `skill-office` keys `node` and `cli` | None; Office tools convert in the Host |
+| `DSH_BUNDLED_OFFICE_CLI` and `DSH_BUNDLED_OFFICE_NODE` | None; no component reads them |
+| `DSH_BUNDLED_PRIMARY_RUNTIME` | `DSH_PRIMARY_RUNTIME` |
+
+`skill-office` gains `pythonEnvironment`. Its default, `'workspace-dependencies'`, directs the Python skills to `load_workspace_dependencies`; a composition without `@deepseek-ai/dsh-tool-workspace-dependencies` must set `'user'`. [Office skill resources](../office-skill-resources/guide.md) covers the removal of `DSH_BUNDLED_OFFICE_SKILLS`.
+
+The Office tools parse untrusted documents with the native LibreOffice Kit engine in the Host process, outside the shell sandbox and PTC permissions, with the Host user's permissions; the filesystem backend still authorizes inputs. The `office-kit` row gains `outputDirectory` (default `$DSH_HOME/office-kit/outputs`), `outputRetentionMs`, and `maxOutputStoreBytes`.
+
+The Web profile, and the SDK profile without a primary runtime, list the Office skills in the first request context and `/` menu.
+
+This affects users and prompts of the removed skills, compositions and launchers setting the removed keys or variables, `assetRoot` skill copies, saved `standard` or `ptc` presets, deployments relying on the shell sandbox for document parsing, and tests pinning the first request context or `/` menu.
+
+## Migration
+
+1. Replace each removed skill with loading `office` and calling the matching tool:
+   - `office-render`: `office_render`;
+   - `office-recalculate`: `office_recalculate` with `format: "xlsx"` or `"ods"`;
+   - `office-export-pdf`: `office_convert` with `format: "pdf"`.
+2. Remove `node` and `cli` from every `skill-office` row in `cordis.yml`, patches, and overlays. Set `pythonEnvironment: user` unless the composition mounts `@deepseek-ai/dsh-tool-workspace-dependencies`.
+3. Compositions that mount `@deepseek-ai/dsh-skill-office` without the shipped bundles also mount `@deepseek-ai/dsh-office-kit` and `@deepseek-ai/dsh-tool-office`.
+4. In launchers, stop setting `DSH_BUNDLED_OFFICE_CLI` and `DSH_BUNDLED_OFFICE_NODE`, and rename `DSH_BUNDLED_PRIMARY_RUNTIME` to `DSH_PRIMARY_RUNTIME`. The Python SDK prefers a set or inherited `DSH_PRIMARY_RUNTIME`, even empty, over its download cache; unset it to use the cache.
+5. In a copy referenced by `assetRoot`, replace the four remaining folders with the installed package's `assets/` and delete the three removed skill folders.
+6. A `standard` or `ptc` preset saved from the Agent Preset editor replaces the shipped plugin list, so its Sessions lack the Office tools. Add this row to the saved list, or to `config.plugins` of the `preset-standard` or `preset-ptc` row in `$DSH_HOME/profiles/<profile>/cordis.patch.yml` (`<profile>`: `web` or `desktop`):
+
+   ```yaml
+   - id: tool-office
+     name: '@deepseek-ai/dsh-tool-office'
+   ```
+
+7. Deployments that require sandboxed document parsing omit `@deepseek-ai/dsh-tool-office`.
+8. Update expected first request contexts and `/` menus with the Office skills.
+9. Confirm: in a new `standard` or `ptc` Session, send `/office`, then a separate PDF export request; it produces an `office_convert` call that returns a temporary PDF path or the `unavailable` message.