dsh-plugin-dev-kb 1.8.0 → 1.8.1

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "dsh-plugin-dev-kb",
-  "description": "dsh 插件辅助：① dsh-plugin-dev-kb 技能 = DeepSeek Harness 官方文档站完整 Markdown 镜像（中英双语 192 页）+ 439 篇仓库补充开发参考 + 主题导航与 634 文件全量搜索索引；② dsh-dev-sandbox 技能 = 自建独立沙箱 profile 开发沙箱工作流（沙箱名由 agent 按任务自定），开发中的插件隔离运行，agent 自主启动/重启/冒烟验证，插件崩了不影响主力 dsh；③ dsh_kb_search 工具 = 知识库本地打分检索，一次调用返回命中文件 + 行号 + 上下文片段。零运行时依赖。",
-  "version": "1.8.0",
-  "type": "module",
-  "main": "lib/index.js",
-  "exports": {
-    ".": "./lib/index.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "docs",
-    "kb",
-    "skills",
-    "scripts",
-    "cordis.patch.yml",
-    "README.md",
-    "README.en.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "selfcheck": "node scripts/selfcheck.mjs",
-    "rebuild-index": "node scripts/rebuild-index.mjs",
-    "refresh-kb": "node scripts/refresh-kb.mjs",
-    "smoke": "node scripts/smoke.mjs"
-  },
-  "keywords": [
-    "dsh",
-    "dsh-plugin",
-    "deepseek",
-    "harness",
-    "cordis",
-    "plugin",
-    "knowledge",
-    "knowledge-base",
-    "documentation",
-    "official-docs",
-    "documentation-mirror",
-    "kb",
-    "plugin-development",
-    "agent-skills",
-    "skills",
-    "retrieval",
-    "rag"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Pasumao/dsh-plugin-dev-kb.git"
-  },
-  "homepage": "https://github.com/Pasumao/dsh-plugin-dev-kb",
-  "bugs": {
-    "url": "https://github.com/Pasumao/dsh-plugin-dev-kb/issues"
-  },
-  "license": "MIT",
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  }
-}
+{
+  "name": "dsh-plugin-dev-kb",
+  "description": "dsh 插件辅助：① dsh-plugin-dev-kb 技能 = DeepSeek Harness 官方文档站完整 Markdown 镜像（中英双语 192 页）+ 439 篇仓库补充开发参考 + 主题导航与 634 文件全量搜索索引；② dsh-dev-sandbox 技能 = 自建独立沙箱 profile 开发沙箱工作流（沙箱名由 agent 按任务自定），开发中的插件隔离运行，agent 自主启动/重启/冒烟验证，插件崩了不影响主力 dsh；③ dsh_kb_search 工具 = 知识库本地打分检索，一次调用返回命中文件 + 行号 + 上下文片段。零运行时依赖。",
+  "version": "1.8.1",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "docs",
+    "kb",
+    "skills",
+    "scripts",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "selfcheck": "node scripts/selfcheck.mjs",
+    "rebuild-index": "node scripts/rebuild-index.mjs",
+    "refresh-kb": "node scripts/refresh-kb.mjs",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek",
+    "harness",
+    "cordis",
+    "plugin",
+    "knowledge",
+    "knowledge-base",
+    "documentation",
+    "official-docs",
+    "documentation-mirror",
+    "kb",
+    "plugin-development",
+    "agent-skills",
+    "skills",
+    "retrieval",
+    "rag"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pasumao/dsh-plugin-dev-kb.git"
+  },
+  "homepage": "https://github.com/Pasumao/dsh-plugin-dev-kb",
+  "bugs": {
+    "url": "https://github.com/Pasumao/dsh-plugin-dev-kb/issues"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/skills/dsh-plugin-dev-kb.md

@@ -1,70 +1,71 @@
----
-name: dsh-plugin-dev-kb
-description: DeepSeek Harness 官方文档知识库的使用指南：知识库位置与结构、按任务场景的阅读路径、检索策略。写 dsh 插件 / Tool / 配置 / 服务 / 事件 / 打包发布 / LLM 适配器时先加载本技能定位文档。注意：本技能仅限 dsh（DeepSeek Harness）插件开发；写 NoneBot 插件时请加载 nonebot-plugin-dev-kb，勿用本技能。
-whenToUse: 开发 dsh 插件、查询 dsh 能力与 API、写 Tool、配置 cordis.yml、扩展 Harness 时
----
-# dsh 插件开发知识库使用指南（dsh-plugin-dev-kb）
-
-本插件内置 DeepSeek Harness 官方文档的完整镜像，供插件开发时快速定位与检索。
-
-## 0. 知识库位置
-
-- **知识库根**：`{{KB_ROOT}}`（插件挂载时由 lib/index.js 自动替换为插件内 kb/ 目录的实际绝对路径，可直接 read/glob/grep；正斜杠路径，跨机器/安装位置始终有效）
-- 数据来源：官方文档站点（VitePress）的仓库原始 Markdown，链接已按站点路由重写，与线上站点逐字一致（见 `kb/meta/source.json` 的 commit）
-
-## 1. 目录结构
-
-```
-kb/
-├── site/            线上站点完整镜像（中英双语 192 页，优先读这里）
-│   ├── guide/       入门：quickstart / providers / python-sdk / github-review / schedule / mcp-memory / network-proxy / public-deployments
-│   ├── develop/     basic(第一个插件/tool/config/publish)、framework(生命周期/服务/事件)、
-│   │                practice(能力分层/LLM适配器/动态装配)、cordis-tutorial(7章)
-│   ├── reference/   index(架构)、cordis-primer、capability-seams、agent-lifecycle、
-│   │                config-catalog、tool-catalog、api-gateway、cordis-api/(6)、cookbook/(5)、subsystems/(46)
-│   └── en/          英文站镜像（结构与中文站一致）
-├── extra/           仓库内未发布到站点的补充文档（468 篇）：glossary、defensive-patterns、
-│                    module-graph、testing、postmortem/、i18n/、cookbook 与 subsystems 扩展、
-│                    upgrade-guide/(各版本升级指南)、persistence-changes/(持久化格式变更)
-├── meta/
-│   ├── topics.md    ★ 主题导航：任务场景 → 要读的文件（先用这个）
-│   ├── search-index.json  全量检索索引（663 文件：path/url/title/字符数）
-│   ├── source.json  来源信息（commit/时间/统计）
-│   └── site-pages.txt     线上站点页面清单
-├── INDEX.md         全部 站点 URL ↔ 本地文件 对照
-└── README.md        知识库总览与更新方法
-```
-
-## 2. 使用流程（从快到慢，优先用工具）
-
-1. **dsh_kb_search 工具检索（首选）**：调用本插件的 `dsh_kb_search` 工具，一次拿到命中文件路径 + 行号 + 上下文片段。参数：`query`（关键词，空白分词；空或 `"topics"` 返回主题导航）、`scope`（`api` = 只搜 API 签名/目录类文档，查 `ctx.*` API 用）、`lang`（默认 zh）、`maxResults`。输出自带**版本横幅**（宿主 dsh 版本 vs 知识库 master 快照 + 对应 upgrade-guide 路径），横幅提示版本差异时务必读指南。
-2. **dsh_kb_read 工具按行号窗口读原文（1.8.0 起，次选）**：拿到 path + 命中行号后用 `dsh_kb_read`（参数 `path` / `offset` / `limit`）带行号窗口读上下文，输出自动提示中英对照路径与续读位置；替代通用 read 工具，防大文件整读。
-3. **文件工具兜底**（工具不可用时）：读 `{{KB_ROOT}}/meta/topics.md` 按主题找文件；或对 `{{KB_ROOT}}/meta/search-index.json` / `{{KB_ROOT}}/site/` 用 grep 定位。
-4. **按 URL 反查**：已知线上页面 URL 时，在 `{{KB_ROOT}}/INDEX.md` 查对应本地文件。
-
-## 3. 阅读原则
-
-- **中文优先**：默认读 `site/` 下中文文件；需要英文原文时读 `site/en/` 对应路径。
-- **大文件局部读**：`reference/config-catalog.md`、`reference/tool-catalog.md`、`extra/module-graph.md`、`reference/subsystems/session.md` 等超过 100KB，先用 grep 定位再 read 局部，禁止整读。
-- **代码示例可直接引用**：文档中的 `apply(ctx)` 插件骨架、`ctx.tools.register`、`inject` 声明等可直接用于新代码；但需注意知识库是 commit 快照，若与当前安装版本 API 不一致，以实际安装包为准。
-- **常见检索关键词**：`ctx.effect`、`ctx.on`、`ctx.tools.register`、`inject`、`Service Definition`、`cordis.yml`、`SessionEventMap`、`Branded`。
-
-## 4. 插件开发高频路径速查
-
-| 任务 | 先读 |
-| --- | --- |
-| 写第一个插件 | `site/develop/basic/index.md` |
-| 开发 Tool | `site/develop/basic/tool.md` + `site/reference/cookbook/adding-a-tool.md` |
-| 插件配置 | `site/develop/basic/config.md` |
-| 服务与依赖 | `site/develop/framework/service.md` |
-| 事件监听 | `site/develop/framework/events.md` |
-| 打包发布 | `site/develop/basic/publish.md` |
-| LLM 适配器 | `site/develop/practice/llm-adapter.md` |
-| 能力扩展 | `site/develop/practice/index.md` + `site/reference/capability-seams.md` |
-| 动态装配 Cordis | `site/develop/practice/dynamic-cordis.md` |
-| API Gateway / Remote 方法 | `site/reference/api-gateway.md` |
-| 子系统能力 | `site/reference/subsystems/index.md` → 对应子系统页 |
-
-## 5. 更新知识库
-
-见 `kb/README.md` 的更新方法（重新克隆 `deepseek-ai/deepseek-harness` 并运行站点投影器）。
+---
+name: dsh-plugin-dev-kb
+description: DeepSeek Harness 官方文档知识库的使用指南：知识库位置与结构、按任务场景的阅读路径、检索策略。写 dsh 插件 / Tool / 配置 / 服务 / 事件 / 打包发布 / LLM 适配器时先加载本技能定位文档。注意：本技能仅限 dsh（DeepSeek Harness）插件开发；写 NoneBot 插件时请加载 nonebot-plugin-dev-kb，勿用本技能。
+whenToUse: 开发 dsh 插件、查询 dsh 能力与 API、写 Tool、配置 cordis.yml、扩展 Harness 时
+---
+# dsh 插件开发知识库使用指南（dsh-plugin-dev-kb）
+
+本插件内置 DeepSeek Harness 官方文档的完整镜像，供插件开发时快速定位与检索。
+
+## 0. 知识库位置
+
+- **知识库根**：`{{KB_ROOT}}`（插件挂载时由 lib/index.js 自动替换为插件内 kb/ 目录的实际绝对路径，可直接 read/glob/grep；正斜杠路径，跨机器/安装位置始终有效）
+- 数据来源：官方文档站点（VitePress）的仓库原始 Markdown，链接已按站点路由重写，与线上站点逐字一致（见 `kb/meta/source.json` 的 commit）
+
+## 1. 目录结构
+
+```
+kb/
+├── site/            线上站点完整镜像（中英双语 194 页，优先读这里）
+│   ├── guide/       入门：quickstart / providers / python-sdk / github-review / schedule / mcp-memory / network-proxy / public-deployments
+│   ├── develop/     basic(第一个插件/tool/config/publish)、framework(生命周期/服务/事件)、
+│   │                practice(能力分层/LLM适配器/动态装配)、cordis-tutorial(7章)
+│   ├── reference/   index(架构)、cordis-primer、capability-seams、agent-lifecycle、
+│   │                config-catalog、tool-catalog、api-gateway、cordis-api/(6)、cookbook/(5)、subsystems/(46+，含 office-kit)、
+│   │                guide/（含 desktop-uninstall-cleanup）
+│   └── en/          英文站镜像（结构与中文站一致）
+├── extra/           仓库内未发布到站点的补充文档（554 篇）：glossary、defensive-patterns、
+│                    module-graph、testing、postmortem/、i18n/、cookbook 与 subsystems 扩展、
+│                    upgrade-guide/(各版本升级指南)、persistence-changes/(持久化格式变更)
+├── meta/
+│   ├── topics.md    ★ 主题导航：任务场景 → 要读的文件（先用这个）
+│   ├── search-index.json  全量检索索引（751 文件：path/url/title/字符数）
+│   ├── source.json  来源信息（commit/时间/统计）
+│   └── site-pages.txt     线上站点页面清单
+├── INDEX.md         全部 站点 URL ↔ 本地文件 对照
+└── README.md        知识库总览与更新方法
+```
+
+## 2. 使用流程（从快到慢，优先用工具）
+
+1. **dsh_kb_search 工具检索（首选）**：调用本插件的 `dsh_kb_search` 工具，一次拿到命中文件路径 + 行号 + 上下文片段。参数：`query`（关键词，空白分词；空或 `"topics"` 返回主题导航）、`scope`（`api` = 只搜 API 签名/目录类文档，查 `ctx.*` API 用）、`lang`（默认 zh）、`maxResults`。输出自带**版本横幅**（宿主 dsh 版本 vs 知识库 master 快照 + 对应 upgrade-guide 路径），横幅提示版本差异时务必读指南。
+2. **dsh_kb_read 工具按行号窗口读原文（1.8.0 起，次选）**：拿到 path + 命中行号后用 `dsh_kb_read`（参数 `path` / `offset` / `limit`）带行号窗口读上下文，输出自动提示中英对照路径与续读位置；替代通用 read 工具，防大文件整读。
+3. **文件工具兜底**（工具不可用时）：读 `{{KB_ROOT}}/meta/topics.md` 按主题找文件；或对 `{{KB_ROOT}}/meta/search-index.json` / `{{KB_ROOT}}/site/` 用 grep 定位。
+4. **按 URL 反查**：已知线上页面 URL 时，在 `{{KB_ROOT}}/INDEX.md` 查对应本地文件。
+
+## 3. 阅读原则
+
+- **中文优先**：默认读 `site/` 下中文文件；需要英文原文时读 `site/en/` 对应路径。
+- **大文件局部读**：`reference/config-catalog.md`、`reference/tool-catalog.md`、`extra/module-graph.md`、`reference/subsystems/session.md` 等超过 100KB，先用 grep 定位再 read 局部，禁止整读。
+- **代码示例可直接引用**：文档中的 `apply(ctx)` 插件骨架、`ctx.tools.register`、`inject` 声明等可直接用于新代码；但需注意知识库是 commit 快照，若与当前安装版本 API 不一致，以实际安装包为准。
+- **常见检索关键词**：`ctx.effect`、`ctx.on`、`ctx.tools.register`、`inject`、`Service Definition`、`cordis.yml`、`SessionEventMap`、`Branded`。
+
+## 4. 插件开发高频路径速查
+
+| 任务 | 先读 |
+| --- | --- |
+| 写第一个插件 | `site/develop/basic/index.md` |
+| 开发 Tool | `site/develop/basic/tool.md` + `site/reference/cookbook/adding-a-tool.md` |
+| 插件配置 | `site/develop/basic/config.md` |
+| 服务与依赖 | `site/develop/framework/service.md` |
+| 事件监听 | `site/develop/framework/events.md` |
+| 打包发布 | `site/develop/basic/publish.md` |
+| LLM 适配器 | `site/develop/practice/llm-adapter.md` |
+| 能力扩展 | `site/develop/practice/index.md` + `site/reference/capability-seams.md` |
+| 动态装配 Cordis | `site/develop/practice/dynamic-cordis.md` |
+| API Gateway / Remote 方法 | `site/reference/api-gateway.md` |
+| 子系统能力 | `site/reference/subsystems/index.md` → 对应子系统页 |
+
+## 5. 更新知识库
+
+见 `kb/README.md` 的更新方法（重新克隆 `deepseek-ai/deepseek-harness` 并运行站点投影器）。

package/kb/extra/subsystems/office-to-pdf.md

@@ -1,87 +0,0 @@
-# Office to PDF
-
-English | [中文](office-to-pdf.zh.md)
-
-The [document package family](../../packages/document/README.md) converts Office files to PDFs on the Node Host. Consumers authorize source reads and own presentation; the shared provider owns conversion, bounded admission, and transient PDF reuse. This subsystem creates no model-facing tool or Session event.
-
-## Ownership
-
-| Owner | Responsibility |
-|---|---|
-| [office-to-pdf](../../packages/document/office-to-pdf/README.md) | `ctx.officeToPdf`: shared LibreOffice conversion, bounded admission, and PDF caching |
-| [Web bundle](../../packages/bundle/web-app/README.md) | One configurable conversion provider 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
-
-[`OfficeToPdfRequest`](../../packages/document/office-to-pdf/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`. `OfficeToPdf.convert(request, signal?)` returns one complete PDF result. Cancellation follows the caller and provider lifetimes; validation, output, and engine failures reject with a classified `OfficeToPdfError`.
-
-`OfficeToPdfPriority` is `foreground` for requested preview/QA and `background` for speculation. `OfficeSourceKey` brands the caller-owned authorized source locator. `OfficeToPdfGeneration` brands a provider lifetime, and `OfficeToPdfKey` 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 `officeToPdf.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-to-pdf/README.md) defines installation and packaging. Invalid metadata, missing required assets, and conversion errors reject without switching engines. 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-to-pdf/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 PDF caching, and model-facing rendering 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="ctxofficetopdf--officetopdf"></a>
-
-### `ctx.officeToPdf` — `OfficeToPdf`
-
-A provider lifetime owns all converters, queued calls, and temporary files.
-
-```ts cordis-catalog
-/**
- * Convert Office bytes 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 {OfficeToPdfError} Invalid input, unusable output, or engine failure; cancellation rejects with its reason.
- */
-convert(request: OfficeToPdfRequest, signal?: AbortSignal): Promise<OfficeToPdfResult>
-
-/**
- * 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: OfficeToPdfPriority, 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): OfficeToPdfGeneration
-```
-
-Source: [`packages/document/office-to-pdf/src/index.ts`](../../packages/document/office-to-pdf/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/kb/extra/subsystems/office-to-pdf.zh.md

@@ -1,87 +0,0 @@
-# Office 转 PDF
-
-[English](office-to-pdf.md) | 中文
-
-[document 包族](../../packages/document/README.zh.md) 在 Node 宿主上将 Office 文件转换为 PDF。消费者负责源文件读取授权与展示；共享提供方负责转换、有界准入和临时 PDF 复用。此子系统不创建面向模型的工具或 Session 事件。
-
-## 所有权
-
-| 所有者 | 职责 |
-|---|---|
-| [office-to-pdf](../../packages/document/office-to-pdf/README.zh.md) | `ctx.officeToPdf`：共享 LibreOffice 转换、有界准入和 PDF 缓存 |
-| [Web bundle](../../packages/bundle/web-app/README.zh.md) | 由宿主消费者共享的单个可配置转换提供方 |
-| [Office 预览 Client](../../packages/client/ui-sidebar-documentpreview/README.zh.md#office-preview) | Office 扩展名选择、PDF 复用和缺失字体提示 |
-
-## 请求和结果
-
-[`OfficeToPdfRequest`](../../packages/document/office-to-pdf/src/types.ts)包含已授权的源键与版本、可选 stat 大小、延迟的 `read(signal, maxBytes)` 回调、前台或后台优先级以及 `OfficeExtension`：`doc`、`docx`、`xls`、`xlsx`、`ppt` 或 `pptx`。`OfficeToPdf.convert(request, signal?)` 返回一个完整 PDF 结果。取消遵循调用方和提供方生命周期；校验、输出和引擎失败以分类的 `OfficeToPdfError` 拒绝。
-
-`OfficeToPdfPriority` 对请求的预览或 QA 使用 `foreground`，对推测工作使用 `background`。`OfficeSourceKey` 为调用方拥有的已授权源定位符增加品牌类型。`OfficeToPdfGeneration` 表示提供方生命周期，`OfficeToPdfKey` 表示其内容身份；消费者不解析这两种不透明值。
-
-| 结果字段 | 含义 |
-|---|---|
-| `pdf` | 调用方拥有的 `Uint8Array`，包含完整 PDF |
-| `missingFonts` | 本次转换无法使用的文档请求字体名称 |
-| `cacheKey` | 不透明的转换 generation 加扩展名与源内容身份 |
-| `generation` | 提供方生命周期；替换后缓存 PDF 不再可复用 |
-
-提供方先准入延迟读取，再分配源文件字节；按内容身份共享转换，并在返回前删除私有临时目录。返回的 PDF 字节在提供方释放后仍有效。源文件和 PDF 字节不会进入 Session 存储。消费者可通过[工作区文件](../../packages/api/workspace-files/README.zh.md)执行已授权的有界读取。
-
-## 预览读取
-
-`RenderedDocumentBytes` 携带工作区文件元数据、原生 PDF `data`、`missingFonts` 和 `generation`；转换后的 PDF 附带原始源文件身份。
-
-`officeToPdf.render` Remote 方法通过 Session 的[工作区文件](../../packages/api/workspace-files/README.zh.md)服务检查源文件授权与版本。取得转换容量后，`fs.readBytes` 在预留字节容量内提供原始输入；该读取受 Office 输入上限约束。二进制 Remote 将 PDF 投影为 multipart 附件，并在 Client 恢复为由 `ArrayBuffer` 支撑的 `Uint8Array`。源访问失败直接传递；大小和引擎失败只暴露分类原因，不含诊断信息。转换不激活 Agent 或追加事件。
-
-`api/remotes` 挂载转换服务生成的 Remote 描述符。共享文档预览包使用完整字节加载和现有 PDF.js Worker 注册 Office 格式。每次预览读取都会重新检查渲染 generation、源文件授权和版本，再共享进行中的转换或缓存 PDF。连接重置和插件卸载会取消请求并清空缓存字节。缺少服务时显示本地化配置引导。
-
-## 引擎选择和限制
-
-外部 [`@deepseek-ai/libreoffice-kit`](https://github.com/deepseek-ai/dsh-libreoffice-kit) Node API 选择其预编译引擎。kit 独立维护版本和发布流程，具体归属由[发布归属决策](../../.agents/notes/implemented/architecture/2026-09-14-independent-libreoffice-kit.zh.md)定义。应用构建时安装已发布的 npm 包。应用打包要求目标已声明的原生引擎；kit 未为该目标声明原生引擎时使用 Node WASM。[平台引擎参考](../../packages/document/office-to-pdf/README.zh.md)定义安装和打包规则。元数据无效、必需资源缺失和转换错误都会拒绝请求，不切换引擎。转换在 Host 使用磁盘输入输出路径，不使用浏览器转换引擎或字体 RPC。
-
-[Host 提供方配置](../../packages/document/office-to-pdf/README.zh.md#use-this-package)负责并发、期限、输入输出上限、归档上限、图像分辨率和字体访问。原生/WASM 实现和资产分发属于 kit 工作区。系统 LibreOffice 探测、运行时引擎下载、持久 PDF 缓存和面向模型的渲染不属于此提供方。
-
-<!-- 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="ctxofficetopdf--officetopdf"></a>
-
-### `ctx.officeToPdf` — `OfficeToPdf`
-
-A provider lifetime owns all converters, queued calls, and temporary files.
-
-```ts cordis-catalog
-/**
- * Convert Office bytes 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 {OfficeToPdfError} Invalid input, unusable output, or engine failure; cancellation rejects with its reason.
- */
-convert(request: OfficeToPdfRequest, signal?: AbortSignal): Promise<OfficeToPdfResult>
-
-/**
- * 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: OfficeToPdfPriority, 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): OfficeToPdfGeneration
-```
-
-Source: [`packages/document/office-to-pdf/src/index.ts`](../../packages/document/office-to-pdf/src/index.ts)
-<!-- END GENERATED cordis-surface -->