dsh-plugin-dev-kb 1.6.0 → 1.8.1

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

@@ -1,139 +1,237 @@
-# MCP
-
-[English](mcp.md) | 中文
-
-## 摘要
-
-模型上下文协议（Model Context Protocol，MCP）让模型使用外部服务器提供的工具。每个已配置服务器都会提供普通 Harness 工具，支持取消、权限检查、结果记录和受支持的图像输出。调用方作用域中配置了服务器时，共享工具负责发现和读取资源，服务器指令则加入已记录的系统提示词。官方 SDK 协商现代或受支持的旧版协议。本参考页介绍 MCP 包组的职责、作用域和组合选择；服务器配置由[客户端 README](../../packages/mcp/mcp-client/README.zh.md) 维护。
-
-## 目录
-
-- [配置](#configuration)
-- [职责与作用域](#responsibilities-and-scope)
-- [协议与结果](#protocol-and-results)
-- [资源与指令](#resources-and-instructions)
-- [资源提供方类型](#resource-provider-types)
-- [限制](#limits)
-- [延伸阅读](#further-reading)
-
------
-
-<a id="configuration"></a>
-## 配置
-
-MCP 服务器需要主动配置。在目标 Cordis 作用域中，为每台服务器配置一个 `@deepseek-ai/dsh-mcp-client` 条目。每个随附 profile 都提供[工具注册表](tools.zh.md)，并统一挂载共享资源服务一次；用户只需配置客户端条目。调用方没有可见的已配置服务器时，在 native 或 PTC 模式下都不会获得 MCP 提示词文本或工具。
-
-| 选择 | 配置维护位置 |
-|---|---|
-| 服务器身份、本地进程或 HTTP 端点、凭据和进程环境 | [客户端配置](../../packages/mcp/mcp-client/README.zh.md#use-this-package) |
-| 工具与资源请求超时、启动失败策略和重连 | [客户端配置](../../packages/mcp/mcp-client/README.zh.md#use-this-package) |
-| 资源发现与读取 | 随附 profile 已包含 [MCP 资源服务](../../packages/mcp/mcp-resources/README.zh.md#use-this-package)；该服务没有配置字段 |
-| 服务器指令大小限制 | 客户端 `maxInstructionBytes`；组合提供[系统提示词装配](system-prompt.zh.md) |
-| 权限决策和受支持的图像输出 | [工具执行](tools.zh.md)和[附件](attachment.zh.md) |
-
-协议协商遵循 SDK 支持的修订版；产品没有强制指定协议修订版的设置。[配置目录](../config-catalog.zh.md#deepseek-aidsh-mcp-client) 列出客户端接受的字段和默认值。
-
------
-
-<a id="responsibilities-and-scope"></a>
-## 职责与作用域
-
-客户端是每服务器一个的连接插件，也是 Harness 工具注册表的消费者。它不发布共享的 `ctx.mcp` 服务。外部服务器实现 MCP 操作；SDK 拥有协议交换；客户端将发现的工具适配到 Harness 执行过程。
-
-`mcp-resources` 拥有共享资源工具，并在调用方作用域中选择提供方。每个 MCP 客户端通过自己的连接提供资源操作。作用域中的首个提供方启用本地共享工具，移除最后一个提供方时移除这些工具；继承的提供方仍然可见。服务独立于任何单一客户端拥有这些工具注册。只要可见的客户端条目保持激活，连接失败就不会移除共享资源工具。
-
-配置的 `serverName` 在注册作用域内标识服务器。同一作用域中的两个条目不能占用相同名称；不同 Agent 作用域可以复用该名称。公开工具名包含配置的服务器名称，因此不同服务器的同名工具仍可区分。注册副作用拥有名称和已发现工具；插件释放时关闭连接并移除其贡献。
-
-[原生 Cua Driver 提供方](../../packages/experimental/computer-use-cua-driver-native/README.zh.md) 复用客户端导出的结果适配器，无需打开 MCP 连接。桌面提供方选择属于[计算机使用子系统](computer-use.zh.md)。
-
------
-
-<a id="protocol-and-results"></a>
-## 协议与结果
-
-stdio 和 Streamable HTTP 都使用官方 SDK 的协商、发现、协议校验和取消机制。工具列表变化通过旧版通知或现代订阅触发发现。刷新失败时保留上一代工具；连接恢复遵循[客户端生命周期](../../packages/mcp/mcp-client/README.zh.md#use-this-package)。
-
-结果适配器为程序化调用方保留规范 MCP JSON，并准备普通工具内容。受支持的图像使用附件系统；不受支持的富内容产生明确的文本诊断。工具注册表仍决定策略失败和结果替换。[工具契约](tools.zh.md) 维护记录和最终呈现规则；[客户端结果参考](../../packages/mcp/mcp-client/README.zh.md#use-this-package) 维护 MCP 特有的投影细节。
-
------
-
-<a id="resources-and-instructions"></a>
-## 资源与指令
-
-资源调用必须显式指定配置的服务器名称。系统提示词组装服务可用时，资源服务从派发所用的同一注册表列出调用方可见的名称，包括没有工具或指令的服务器。共享注册表在分发前，于调用 Agent 的作用域中解析该名称；不可用的服务器会在发出网络请求前失败。发现和读取均按需执行，也支持只提供资源而不提供工具的服务器。[资源包](../../packages/mcp/mcp-resources/README.zh.md) 维护分页和内容渲染规则；其生成的工具 schema 位于[工具目录](../tool-catalog.zh.md#deepseek-aidsh-mcp-resources)。
-
-资源提供方仍由连接拥有。作用域释放时移除注册；MCP 客户端控制取消和恢复。规范结果为程序化调用方保留完整 JSON，文本投影则以描述替换二进制 blob。返回的文本进入普通工具历史；服务器连接本身不会触发内容读取。
-
-组合包含系统提示词装配时，客户端将非空白的服务器指令发布为带服务器归属的作用域章节。指令保持字面文本，并在发布前通过配置的大小限制。替换连接仅在发现成功后发布指令；缺少指令时不添加章节。[系统提示词子系统](system-prompt.zh.md) 维护装配与记录规则。
-
------
-
-<a id="resource-provider-types"></a>
-## 资源提供方类型
-
-连接提供方接收一个操作与原始工具执行对象，其中包含调用方和取消信号。
-
-```ts type-equiv
-/** One supported resource operation, with server-owned cursors and URIs. */
-type McpResourceRequest =
-  | { method: 'resources/list' | 'resources/templates/list'; cursor?: string }
-  | { method: 'resources/read'; uri: string }
-```
-
-```ts type-equiv
-/** One configured server's resource access, owned by its MCP connection plugin. */
-interface McpResourceProvider {
-  /**
-   * Run an operation against one live connection generation.
-   * @param request - MCP resource method and parameters.
-   * @param exec - caller identity and cancellation for this invocation.
-   * @returns the protocol result as lossless JSON.
-   */
-  request(request: McpResourceRequest, exec: ToolExecution): Promise<JsonValue>
-}
-```
-
------
-
-<a id="limits"></a>
-## 限制
-
-不支持 MCP 提示词模板、人工输入征询、基于任务的执行和资源订阅。资源工具需要调用方可见的已配置服务器；二进制资源保留为程序化数据，模型接收其文本描述。没有工具能力的服务器以空工具集连接。连接和发现超时遵循 SDK；客户端没有对应的独立设置。
-
------
-
-<a id="further-reading"></a>
-## 延伸阅读
-
-- [MCP 包组](../../packages/mcp/README.zh.md) — 包入口。
-- [MCP 资源](../../packages/mcp/mcp-resources/README.zh.md) — 共享工具与资源提供方语义。
-- [资源可见性参考](../../packages/mcp/mcp-resources/README.zh.md) — profile 统一挂载及由已配置服务器决定的可见性。
-- [第三方记忆服务器](../user/guide/mcp-memory.zh.md) — 产品配置指南。
-- [协议协商参考](../../packages/mcp/mcp-client/README.zh.md) — SDK 职责与兼容性决策。
-
-<!-- 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="ctxmcpresources--mcpresourceruntime"></a>
-
-### `ctx.mcpResources` — `McpResourceRuntime`
-
-Scoped resource access plus three tools shared by configured MCP servers.
-
-```ts cordis-catalog
-/**
- * Register one server and expose resource tools while that scope has providers.
- * @param server - configured server name, unique in this scope.
- * @param provider - connection-owned resource operations.
- * @returns the effect disposer for this exact registration.
- */
-register(server: string, provider: McpResourceProvider): () => void
-```
-
-Source: [`packages/mcp/mcp-resources/src/index.ts`](../../packages/mcp/mcp-resources/src/index.ts)
-<!-- END GENERATED cordis-surface -->
+# MCP
+
+[English](mcp.md) | 中文
+
+## 摘要
+
+模型上下文协议（Model Context Protocol，MCP）让模型使用外部服务器提供的工具。每个已配置服务器都会提供普通 Harness 工具，支持取消、权限检查、结果记录和受支持的图像输出。调用方作用域中配置了服务器时，共享工具负责发现和读取资源，服务器指令则加入已记录的系统提示词。官方 SDK 协商现代或受支持的旧版协议。本参考页介绍 MCP 包组的职责、作用域和组合选择；服务器配置由[客户端 README](../../packages/mcp/mcp-client/README.zh.md) 维护。
+
+## 目录
+
+- [配置](#configuration)
+- [职责与作用域](#responsibilities-and-scope)
+- [协议与结果](#protocol-and-results)
+- [资源与指令](#resources-and-instructions)
+- [资源提供方类型](#resource-provider-types)
+- [限制](#limits)
+- [延伸阅读](#further-reading)
+
+-----
+
+<a id="configuration"></a>
+## 配置
+
+MCP 服务器需要主动配置。在目标 Cordis 作用域中，为每台服务器配置一个 `@deepseek-ai/dsh-mcp-client` 条目。每个随附 profile 都提供[工具注册表](tools.zh.md)，并统一挂载共享资源服务一次；用户只需配置客户端条目。调用方没有可见的已配置服务器时，在 native 或 PTC 模式下都不会获得 MCP 提示词文本或工具。
+
+Web 与 Desktop profile 还统一挂载一次 [MCP 服务器管理器](../../packages/mcp/mcp-manager/README.zh.md)。它运行通过 Settings 配置的服务器，以及已安装插件在自身生命周期内注册的服务器，并向 Remote 客户端提供它们的状态、重启与探测操作。
+
+| 选择 | 配置维护位置 |
+|---|---|
+| 服务器身份、本地进程或 HTTP 端点、凭据和进程环境 | [客户端配置](../../packages/mcp/mcp-client/README.zh.md#use-this-package) |
+| 工具与资源请求超时、启动失败策略和重连 | [客户端配置](../../packages/mcp/mcp-client/README.zh.md#use-this-package) |
+| 资源发现与读取 | 随附 profile 已包含 [MCP 资源服务](../../packages/mcp/mcp-resources/README.zh.md#use-this-package)；该服务没有配置字段 |
+| 服务器指令大小限制 | 客户端 `maxInstructionBytes`；组合提供[系统提示词装配](system-prompt.zh.md) |
+| 权限决策和受支持的图像输出 | [工具执行](tools.zh.md)和[附件](attachment.zh.md) |
+
+协议协商遵循 SDK 支持的修订版；产品没有强制指定协议修订版的设置。[配置目录](../config-catalog.zh.md#deepseek-aidsh-mcp-client) 列出客户端接受的字段和默认值。
+
+-----
+
+<a id="responsibilities-and-scope"></a>
+## 职责与作用域
+
+客户端是每服务器一个的连接插件，也是 Harness 工具注册表的消费者。它不发布共享的 `ctx.mcp` 服务；管理器为其挂载的宿主全局服务器发布 `ctx.mcpManager`。外部服务器实现 MCP 操作；SDK 拥有协议交换；客户端将发现的工具适配到 Harness 执行过程。
+
+`mcp-resources` 拥有共享资源工具，并在调用方作用域中选择提供方。每个 MCP 客户端通过自己的连接提供资源操作。作用域中的首个提供方启用本地共享工具，移除最后一个提供方时移除这些工具；继承的提供方仍然可见。服务独立于任何单一客户端拥有这些工具注册。只要可见的客户端条目保持激活，连接失败就不会移除共享资源工具。
+
+配置的 `serverName` 在注册作用域内标识服务器。同一作用域中的两个条目不能占用相同名称；不同 Agent 作用域可以复用该名称。公开工具名包含配置的服务器名称，因此不同服务器的同名工具仍可区分。注册副作用拥有名称和已发现工具；插件释放时关闭连接并移除其贡献。
+
+[原生 Cua Driver 提供方](../../packages/experimental/computer-use-cua-driver-native/README.zh.md) 复用客户端导出的结果适配器，无需打开 MCP 连接。桌面提供方选择属于[计算机使用子系统](computer-use.zh.md)。
+
+-----
+
+<a id="protocol-and-results"></a>
+## 协议与结果
+
+stdio 和 Streamable HTTP 都使用官方 SDK 的协商、发现、协议校验和取消机制。工具列表变化通过旧版通知或现代订阅触发发现。刷新失败时保留上一代工具；连接恢复遵循[客户端生命周期](../../packages/mcp/mcp-client/README.zh.md#use-this-package)。
+
+结果适配器为程序化调用方保留规范 MCP JSON，并准备普通工具内容。受支持的图像使用附件系统；不受支持的富内容产生明确的文本诊断。服务器 `isError` 结果与请求失败抛出 `McpToolError`，其 code 告诉调用方请求结果是否已知，例如 `MCP_TOOL_ERROR`、`MCP_CONNECTION_CLOSED` 或 `MCP_TIMEOUT`；客户端 README 列出全部 code。工具注册表仍决定策略失败和结果替换。[工具契约](tools.zh.md) 维护记录和最终呈现规则；[客户端结果参考](../../packages/mcp/mcp-client/README.zh.md#use-this-package) 维护 MCP 特有的投影细节。
+
+-----
+
+<a id="resources-and-instructions"></a>
+## 资源与指令
+
+资源调用必须显式指定配置的服务器名称。系统提示词组装服务可用时，资源服务从派发所用的同一注册表列出调用方可见的名称，包括没有工具或指令的服务器。共享注册表在分发前，于调用 Agent 的作用域中解析该名称；不可用的服务器会在发出网络请求前失败。发现和读取均按需执行，也支持只提供资源而不提供工具的服务器。[资源包](../../packages/mcp/mcp-resources/README.zh.md) 维护分页和内容渲染规则；其生成的工具 schema 位于[工具目录](../tool-catalog.zh.md#deepseek-aidsh-mcp-resources)。
+
+资源提供方仍由连接拥有。作用域释放时移除注册；MCP 客户端控制取消和恢复。规范结果为程序化调用方保留完整 JSON，文本投影则以描述替换二进制 blob。返回的文本进入普通工具历史；服务器连接本身不会触发内容读取。
+
+组合包含系统提示词装配时，客户端将非空白的服务器指令发布为带服务器归属的作用域章节。指令保持字面文本，并在发布前通过配置的大小限制。替换连接仅在发现成功后发布指令；缺少指令时不添加章节。[系统提示词子系统](system-prompt.zh.md) 维护装配与记录规则。
+
+-----
+
+<a id="resource-provider-types"></a>
+## 资源提供方类型
+
+连接提供方接收一个操作与原始工具执行对象，其中包含调用方和取消信号。
+
+```ts type-equiv
+/** One supported resource operation, with server-owned cursors and URIs. */
+type McpResourceRequest =
+  | { method: 'resources/list' | 'resources/templates/list'; cursor?: string }
+  | { method: 'resources/read'; uri: string }
+```
+
+```ts type-equiv
+/** One configured server's resource access, owned by its MCP connection plugin. */
+interface McpResourceProvider {
+  /**
+   * Run an operation against one live connection generation. The resource tools
+   * dispatch in parallel, so one provider may receive several concurrent requests;
+   * each must settle independently.
+   * @param request - MCP resource method and parameters.
+   * @param exec - caller identity and cancellation for this invocation.
+   * @returns the protocol result as lossless JSON.
+   */
+  request(request: McpResourceRequest, exec: ToolExecution): Promise<JsonValue>
+}
+```
+
+-----
+
+<a id="limits"></a>
+## 限制
+
+不支持 MCP 提示词模板、人工输入征询、基于任务的执行和资源订阅。资源工具需要调用方可见的已配置服务器；二进制资源保留为程序化数据，模型接收其文本描述。没有工具能力的服务器以空工具集连接。连接和发现超时遵循 SDK；客户端没有对应的独立设置。
+
+-----
+
+<a id="further-reading"></a>
+## 延伸阅读
+
+- [MCP 包组](../../packages/mcp/README.zh.md) — 包入口。
+- [MCP 资源](../../packages/mcp/mcp-resources/README.zh.md) — 共享工具与资源提供方语义。
+- [MCP 管理器](../../packages/mcp/mcp-manager/README.zh.md) — 通过 Settings 配置与插件注册的服务器、状态及 Remote 操作。
+- [资源可见性参考](../../packages/mcp/mcp-resources/README.zh.md) — profile 统一挂载及由已配置服务器决定的可见性。
+- [第三方记忆服务器](../user/guide/mcp-memory.zh.md) — 产品配置指南。
+- [协议协商参考](../../packages/mcp/mcp-client/README.zh.md) — SDK 职责与兼容性决策。
+- [Computer Use MCP 服务器](../../packages/experimental/cua-mcp/README.zh.md) — DSH 作为 MCP stdio 服务器向其他 harness 提供 Computer Use 程序。
+
+<!-- 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="ctxmcpmanager--mcpservermanager"></a>
+
+### `ctx.mcpManager` — `McpServerManager`
+
+The manager service. Reconciliation and `restart` serialize instance replacement. Probes run independently and are cancelled before replacement or disposal waits for their cleanup.
+
+```ts cordis-catalog
+/**
+ * Read configured and registered servers and retained runtime records without mounting or probing.
+ * @returns configured entries in document order, then registered entries, then retained records for removed entries.
+ */
+list(): McpManagedServerView[]
+
+/**
+ * Contribute one server for the calling plugin's lifetime. A registered
+ * entry is enabled while registered; its removal awaits the instance's
+ * unmount, so plugin disposal withdraws the server's tools before settling.
+ * @param name - server key and tool namespace, unique across configured and registered servers.
+ * @param entry - transport, endpoint, and budgets, validated like a configured entry.
+ * @returns an idempotent disposer that removes the registration.
+ * @throws when the name is taken, the entry is invalid, or the manager is disposed.
+ */
+register(name: string, entry: McpServerRegistration): () => void
+
+/**
+ * Stream server views for a management surface: the current list on
+ * subscription, then the complete list again after each status or entry change.
+ * @param signal - subscription lifetime; aborting ends only this stream.
+ * @returns coalesced server lists until the subscriber or the manager stops.
+ */
+@Remote({ mode: 'stream' }) async* watch(signal: AbortSignal): AsyncIterable<McpManagedServerView[]>
+
+/**
+ * Rebuild one server from its current entry: dispose the live instance (if
+ * any) and mount a fresh one with a fresh reconnect budget. Incomplete
+ * cleanup blocks replacement until the Host restarts.
+ * @param name - the configured or registered server key.
+ * @throws when the manager is disposed, no such entry exists, or cleanup is incomplete.
+ */
+@Remote async restart(name: string): Promise<void>
+
+/**
+ * Probe one server for a management surface; see {@link McpServerManager.probe}.
+ * @param name - the configured or registered server key.
+ * @param signal - caller cancellation.
+ * @returns the stage-classified probe outcome and independent cleanup result.
+ */
+@Remote('probe') probeFromClient(name: string, signal: AbortSignal): Promise<McpProbeResult>
+
+/**
+ * Probe one configured server without touching its live instance: resolve
+ * the entry's templates, connect, list tools, close. A disabled entry can be
+ * probed — that is how a management surface tests it before enabling.
+ * Configuration changes and manager disposal cancel the probe.
+ * @param name - the configured or registered server key.
+ * @param options - probe budget, listing caps, and abort signal.
+ * @returns the stage-classified probe outcome and independent cleanup result.
+ * @throws when the manager is disposed, the entry is absent or changing, cleanup is
+ * incomplete, options are invalid, or a required credentials provider is missing.
+ */
+async probe(name: string, options?: McpProbeOptions): Promise<McpProbeResult>
+```
+
+Source: [`packages/mcp/mcp-manager/src/index.ts`](../../packages/mcp/mcp-manager/src/index.ts)
+
+<a id="ctxmcpresources--mcpresourceruntime"></a>
+
+### `ctx.mcpResources` — `McpResourceRuntime`
+
+Scoped resource access plus three tools shared by configured MCP servers.
+
+```ts cordis-catalog
+/**
+ * Register one server and expose resource tools while that scope has providers.
+ * @param server - configured server name, unique in this scope.
+ * @param provider - connection-owned resource operations.
+ * @returns the effect disposer for this exact registration.
+ */
+register(server: string, provider: McpResourceProvider): () => void
+```
+
+Source: [`packages/mcp/mcp-resources/src/index.ts`](../../packages/mcp/mcp-resources/src/index.ts)
+
+<a id="mcp-manager-events"></a>
+
+### `mcp-manager/*` events
+
+<a id="mcp-managerstatus--parallel"></a>
+
+#### `mcp-manager/status` — parallel
+
+One managed server's status transitioned. Emitted for every published change while the manager is live and either the entry is configured or registered, or a runtime record remains. Removed entries may emit cleanup failures; `watch` and `list()` report removals. Lifecycle operations do not wait for listeners. Synchronous throws and returned promise rejections are logged without skipping other listeners.
+
+```ts cordis-catalog
+/**
+ * One managed server's status transitioned. Emitted for every published
+ * change while the manager is live and either the entry is configured or
+ * registered, or a runtime record remains. Removed entries may emit cleanup
+ * failures; `watch` and `list()` report removals.
+ * Lifecycle operations do not wait for listeners. Synchronous throws and
+ * returned promise rejections are logged without skipping other listeners.
+ * @param name - the configured `servers` key or registered name.
+ * @param status - the status now current for that server.
+ * @mode parallel
+ */
+'mcp-manager/status'(name: string, status: McpManagedServerStatus): void | Promise<void>
+```
+
+Source: [`packages/mcp/mcp-manager/src/types.ts`](../../packages/mcp/mcp-manager/src/types.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/extra/subsystems/office-kit.md

@@ -0,0 +1,122 @@
+# Office Kit
+
+English | [中文](office-kit.zh.md)
+
+The [document package family](../../packages/document/README.md) renders, converts, and recalculates Office files on the Node Host. Consumers authorize source reads and own presentation; the shared provider owns the engine, bounded admission, transient output reuse, and the private output store. The [`office_render`, `office_convert`, and `office_recalculate` tools](../../packages/document/tool-office/README.md) are the model-facing consumers; the provider itself creates no Session event.
+
+## Ownership
+
+| Owner | Responsibility |
+|---|---|
+| [office-kit](../../packages/document/office-kit/README.md) | `ctx.officeKit`: shared LibreOffice rendering, conversion, and recalculation, bounded admission, output caching, and the per-Session output store; resolution of the provider's own Kit entry, engine manifests from that installation, and native paths mapped to ASAR unpacked directories |
+| [tool-office](../../packages/document/tool-office/README.md) | The on-demand `office_render`, `office_convert`, and `office_recalculate` tools: rendered images in tool results and converted or recalculated files returned for a shell copy |
+| [Web bundle](../../packages/bundle/web-app/README.md) and [SDK bundle](../../packages/bundle/sdk-app/README.md) | One configurable provider and `tool-office` shared by Host consumers |
+| [Office preview Client](../../packages/client/ui-sidebar-documentpreview/README.md#office-preview) | Office extension selection, PDF reuse, and missing-font notices |
+
+## Requests and results
+
+[`OfficeKitRequest`](../../packages/document/office-kit/src/types.ts) contains an already-authorized source key/version, optional stat size, a deferred `read(signal, maxBytes)` callback, foreground/background priority, and a `OfficeExtension`: `doc`, `docx`, `xls`, `xlsx`, `ppt`, or `pptx`. `OfficeKit.convert(request, signal?)` returns one complete PDF result. `renderImages()` returns bounded PNG images of selected pages, slides, or worksheet areas; `convertTo()` and `recalculate()` save the output under the provider's `outputDirectory` for the request's owner and return its Host path. Their request types accept OpenDocument inputs, and image rendering accepts PDF. All methods share admission and caching. Cancellation follows the caller and provider lifetimes; validation, output, and engine failures reject with a classified `OfficeKitError`.
+
+`OfficeKitPriority` is `foreground` for requested preview/QA and `background` for speculation. `OfficeSourceKey` brands the caller-owned authorized source locator. `OfficeKitGeneration` brands a provider lifetime, and `OfficeKitKey` brands its content identity; neither opaque value is parsed by consumers.
+
+| Result field | Meaning |
+|---|---|
+| `pdf` | Caller-owned `Uint8Array` containing the complete PDF |
+| `missingFonts` | Requested document font families unavailable to this conversion |
+| `cacheKey` | Opaque converter generation plus extension/source-content identity |
+| `generation` | Provider lifetime; replacement invalidates cached PDF reuse |
+
+The provider admits the deferred read before allocating source bytes, shares conversions by content identity, and removes its private scratch directory before returning. Returned PDF bytes remain valid after provider disposal. Source and PDF bytes do not enter Session storage. Consumers can use [Workspace Files](../../packages/api/workspace-files/README.md) for authorized bounded reads.
+
+## Preview reads
+
+`RenderedDocumentBytes` carries workspace file metadata, native PDF `data`, `missingFonts`, and `generation`; the original source identity accompanies the converted PDF.
+
+The `officeKit.render` Remote method checks source authorization and versions through the Session's [Workspace Files](../../packages/api/workspace-files/README.md) service. After conversion admission, `fs.readBytes` supplies raw input within the reserved byte capacity; Office input limits govern this read. The binary Remote projects the PDF into a multipart attachment and restores an `ArrayBuffer`-backed `Uint8Array` on the Client. Source access failures pass through; size and engine failures expose a classified reason without diagnostics. Conversion does not activate an Agent or append events.
+
+The `api/remotes` assembly mounts the conversion service's generated Remote descriptor. The shared Document Preview package registers Office formats with complete-byte loading and its existing PDF.js Worker. Each preview read rechecks renderer generation, source authorization, and version before sharing an in-flight conversion or cached PDF. Connection resets and plugin disposal cancel requests and clear cached bytes. Missing services show localized configuration guidance.
+
+## Engine selection and limits
+
+The external [`@deepseek-ai/libreoffice-kit`](https://github.com/deepseek-ai/dsh-libreoffice-kit) Node API selects its precompiled engines. The kit has an independent version and release workflow, defined by the [release ownership decision](../../.agents/notes/implemented/architecture/2026-09-14-independent-libreoffice-kit.md). Application builds install the published npm packages. Application packaging requires the target’s declared native engine, or Node WASM when the kit declares no native engine for that target. The [platform engine reference](../../packages/document/office-kit/README.md) defines installation and packaging. Invalid metadata, missing required assets, and conversion errors reject without switching engines. When the provider's Kit is absent or fails to import, the provider still registers and rejects conversions as `unavailable`. Conversion uses disk input and output paths on the Host, with no browser conversion engine or font RPC.
+
+The [Host provider configuration](../../packages/document/office-kit/README.md#use-this-package) owns concurrency, deadlines, input/output limits, archive limits, image resolution, and font access. Native/WASM implementation and asset distribution belong to the kit workspace. System LibreOffice discovery, runtime engine downloads, persistent output caching, workspace writes, and model-facing presentation are outside this provider.
+
+<!-- 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.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxofficekit--officekit"></a>
+
+### `ctx.officeKit` — `OfficeKit`
+
+A provider lifetime owns all converters, queued calls, and temporary files.
+
+```ts cordis-catalog
+/**
+ * Convert Office bytes to PDF without modifying the source or writing Session events.
+ * @param request - authorized metadata and deferred bounded source read.
+ * @param signal - caller cancellation; provider disposal also stops active work.
+ * @returns caller-owned PDF bytes after conversion and scratch cleanup settle; canceled readers reject independently.
+ * @throws {OfficeKitError} Invalid input, unusable output, or engine failure; cancellation rejects with its reason.
+ */
+async convert(request: OfficeKitRequest, signal?: AbortSignal): Promise<OfficeKitResult>
+
+/**
+ * Render selected pages, slides, or worksheet areas of one document as PNG images. Requests share the admission
+ * queue, concurrency, source-byte reservation, and cache with previews, and run at foreground priority.
+ * @param request - authorized metadata, deferred bounded source read, selection, and complete-result limits.
+ * @param signal - caller cancellation; provider disposal also stops active work.
+ * @returns caller-owned images in document order whose count, per-image size, and total bytes satisfy the limits.
+ * @throws {OfficeKitError} `invalid-request` for a selection the engine rejects, `output-too-large` when the
+ * selection exceeds a limit, and the other conversion codes; cancellation rejects with its reason.
+ */
+async renderImages(request: OfficeImagesRequest, signal?: AbortSignal): Promise<OfficeImagesResult>
+
+/**
+ * Convert one document to another format at foreground priority, sharing admission, concurrency, and cache with
+ * previews, and save the result in the provider's output store.
+ * @param request - authorized metadata, deferred bounded source read, target format, and output owner and name.
+ * @param signal - caller cancellation; provider disposal also stops active work.
+ * @returns the saved file's absolute Host path and size; the file is deleted after `outputRetentionMs`, when older
+ * outputs need `maxOutputStoreBytes`, when the Session whose id is `output.owner` is disposed, or when the provider is disposed.
+ * @throws {OfficeKitError} `invalid-request` for a format or sheet the engine rejects and the other conversion
+ * codes; cancellation rejects with its reason.
+ */
+async convertTo(request: OfficeConversionRequest, signal?: AbortSignal): Promise<OfficeFileResult>
+
+/**
+ * Recalculate every formula of one workbook at foreground priority and save formulas with refreshed cached results, sharing admission,
+ * concurrency, and cache with previews, and save the workbook in the provider's output store. This does not validate
+ * formulas or business data.
+ * @param request - authorized workbook metadata, deferred bounded source read, output format, and output owner and name.
+ * @param signal - caller cancellation; provider disposal also stops active work.
+ * @returns the saved workbook's absolute Host path and size, retained like {@link convertTo} outputs.
+ * @throws {OfficeKitError} Invalid input, unusable output, or engine failure; cancellation rejects with its reason.
+ */
+async recalculate(request: OfficeRecalculationRequest, signal?: AbortSignal): Promise<OfficeFileResult>
+
+/**
+ * Read and convert one Office file using the Session's ordinary filesystem authorization.
+ * @param workspaceFileScope - Session header lookup shared with workspaceFiles.
+ * @param path - absolute or workspace-relative Office path.
+ * @param priority - foreground preview or speculative background work.
+ * @param signal - Remote cancellation; disposal also cancels outstanding reads and conversions.
+ * @returns complete PDF bytes with original source identity and missing font families.
+ */
+@Remote async render( workspaceFileScope: WorkspaceFileScope, path: string, priority: OfficeKitPriority, signal: AbortSignal, ): Promise<RenderedDocumentBytes>
+
+/**
+ * Read the current rendering generation before reusing a Client PDF.
+ * @param signal - Remote caller cancellation.
+ * @returns provider lifetime, replaced with rendering, font, or engine configuration.
+ */
+@Remote('generation') getGeneration(signal: AbortSignal): OfficeKitGeneration
+```
+
+Source: [`packages/document/office-kit/src/index.ts`](../../packages/document/office-kit/src/index.ts)
+<!-- END GENERATED cordis-surface -->