dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/kb/extra/subsystems/lsp.md

@@ -1,202 +0,0 @@
-# LSP navigation
-
-English | [中文](lsp.zh.md)
-
-The LSP seam — a [capability seam](../glossary.md#capability-seam) exposing semantic code navigation on one `ctx.lsp` service, split across packages: Service Definition ([dsh-lsp](../../packages/lsp/lsp), `ctx.lsp` + the provider registry), a generic Service Provider ([dsh-lsp-stdio](../../packages/lsp/lsp-stdio), a configured stdio language-server host), and Consumer ([dsh-tool-lsp](../../packages/lsp/tool-lsp), the `lsp` tool schema). LSP is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A provider swap does not change how the model asks for navigation.
-
-Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
-
-## Operations and coordinates
-
-The seam and model expose exactly four semantic queries; the union is closed, so adding one is a compile-enforced change across the seam, providers, and the tool. Positions and ranges are zero-based UTF-16, matching the protocol; the model-facing tool owns the one-based cursor convention and converts on the way in and out.
-
-```ts type-equiv
-/**
- * The four semantic queries the seam and model expose. A closed union: adding an operation is a
- * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
- * not operations here; they need different schemas.
- */
-type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
-```
-
-```ts type-equiv
-/** A zero-based UTF-16 cursor coordinate, matching the LSP wire convention. */
-interface LspPosition {
-  /** Zero-based line. */
-  readonly line: number
-  /** Zero-based UTF-16 code-unit offset within the line. */
-  readonly character: number
-}
-```
-
-```ts type-equiv
-/** A zero-based UTF-16 half-open range `[start, end)`. */
-interface LspRange {
-  readonly start: LspPosition
-  readonly end: LspPosition
-}
-```
-
-## Request
-
-Every field is required: `workspaceRoot` is caller-supplied, `languageId` comes from the provider's registration (not the request), and consumers own timeouts and result limits — so no field needs implementation defaulting and there is no `resolve()` step. The provider receives the caller's request plus the derived `languageId`, which only synchronizes the transient document and never participates in selection.
-
-```ts type-equiv
-/**
- * A caller's normalized query. Every field is required: `workspaceRoot` is caller-supplied,
- * `languageId` comes from the provider registration (not here), and consumers own timeouts and
- * result limits — so no field needs implementation defaulting and there is no `resolve()` step.
- */
-interface LspQueryRequest {
-  /** Which semantic query to run. */
-  readonly operation: LspOperation
-  /** The source file to query (relative to `workspaceRoot` or absolute; the provider canonicalizes). */
-  readonly filePath: string
-  /** The zero-based UTF-16 cursor position to query at. */
-  readonly position: LspPosition
-  /** The workspace root the provider resolves against and indexes; required, never defaulted. */
-  readonly workspaceRoot: string
-}
-```
-
-```ts type-equiv
-/**
- * A request as a provider receives it: the caller's {@link LspQueryRequest} plus the `languageId`
- * the seam derived from the provider's extension mapping. The language id only synchronizes the
- * transient document; it does not participate in selection.
- */
-interface LspProviderQuery extends LspQueryRequest {
-  /** The LSP language id for `filePath`, from this provider's extension mapping. */
-  readonly languageId: string
-}
-```
-
-## Result
-
-A CLOSED discriminated union: navigation operations normalize to `locations`, `hover` to content or `null`. Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled. `findReferences` always includes declarations — the provider enforces this internally, so callers get no flag. The `locations` variant carries `resolvedWorkspaceUri`, the provider's canonical workspace `file:` URI. A caller relativizing location URIs uses that coordinate rather than applying host-platform path rules to the possibly-symlinked request root.
-
-```ts type-equiv
-/** One resolved location: a document URI and the range within it. */
-interface LspLocation {
-  /** The target document URI (`file:` or otherwise), verbatim from the server. */
-  readonly uri: string
-  /** The range within the target document. */
-  readonly range: LspRange
-}
-```
-
-```ts type-equiv
-/** Normalized hover content, or `null` for no hover at the position. */
-interface LspHover {
-  /** The normalized hover text (markdown or plaintext, provider-joined). */
-  readonly contents: string
-  /** The range the hover applies to, when the server supplied one. */
-  readonly range?: LspRange
-}
-```
-
-```ts type-equiv
-/**
- * The closed result union. Navigation operations (`goToDefinition`, `findReferences`,
- * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
- * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
- *
- * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
- * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
- * request's possibly symlinked process path with host-platform rules; the execution platform may
- * differ from the caller's.
- */
-type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
-  | { readonly kind: 'hover'; readonly hover: LspHover | null }
-```
-
-## Provider and service
-
-A provider owns a stable branded `id` and an exclusive lowercase leading-dot extension map. `registerProvider` reserves the id and every extension atomically — an invalid or conflicting registration publishes nothing — and its disposer releases all reservations. Selection is per query and order-independent; no match throws `LspError` `LSP_UNAVAILABLE`. The seam exposes no protocol types, process/document controls, or generic JSON-RPC escape hatch.
-
-```ts type-equiv
-/**
- * A language-server backend registered on `ctx.lsp`. Each provider owns a stable {@link
- * LspProviderId} and an extension-to-language-id map (lowercase, leading-dot keys).
- * `findReferences` always includes declarations — the provider enforces this internally; callers
- * get no flag.
- */
-interface LspProvider {
-  /** Stable provider identity, reserved atomically with the extension mappings. */
-  readonly id: LspProviderId
-  /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */
-  readonly extensionToLanguage: Readonly<Record<string, string>>
-  /**
-   * Run one query. The seam has already selected this provider and derived `languageId`.
-   * @param request - the resolved provider query (caller request + derived language id).
-   * @param signal - optional cancellation; the provider stops its own work when it aborts.
-   * @returns the normalized, closed-union result.
-   */
-  query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult>
-}
-```
-
-```ts type-equiv
-/**
- * The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query
- * execution; exposes exactly the four operations and no protocol escape hatch.
- */
-interface LspService {
-  /**
-   * Register a provider, atomically reserving its id and every normalized extension. Any conflict
-   * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
-   * reservations. Disposed with the calling fiber.
-   * @param provider - the backend to register.
-   * @returns a synchronous disposer releasing the id and all extension reservations.
-   */
-  registerProvider(provider: LspProvider): () => void
-  /**
-   * Select a provider by the file's extension and run one query. Selection is per-query and
-   * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
-   * @param request - the normalized query.
-   * @param signal - optional cancellation forwarded to the selected provider.
-   * @returns the normalized, closed-union result.
-   */
-  query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>
-}
-```
-
-`LspProviderId` is the seam's branded id (`Branded<'LspProviderId'>` from [dsh-brand](../../packages/util/brand)); `LspError` extends `HarnessError` with stable codes such as `LSP_INVALID_PROVIDER`, `LSP_CONFLICT`, `LSP_UNAVAILABLE`, `LSP_DISPOSED`, `LSP_UNSUPPORTED_OPERATION`, and `LSP_MALFORMED_RESPONSE`, which callers route on instead of parsing `message`.
-
-<!-- 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="ctxlsp--lspservice"></a>
-
-### `ctx.lsp` — `LspService`
-
-The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query execution; exposes exactly the four operations and no protocol escape hatch.
-
-```ts cordis-catalog
-/**
- * Register a provider, atomically reserving its id and every normalized extension. Any conflict
- * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
- * reservations. Disposed with the calling fiber.
- * @param provider - the backend to register.
- * @returns a synchronous disposer releasing the id and all extension reservations.
- */
-registerProvider(provider: LspProvider): () => void
-
-/**
- * Select a provider by the file's extension and run one query. Selection is per-query and
- * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
- * @param request - the normalized query.
- * @param signal - optional cancellation forwarded to the selected provider.
- * @returns the normalized, closed-union result.
- */
-query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>
-```
-
-Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
-<!-- END GENERATED cordis-surface -->

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

@@ -1,202 +0,0 @@
-# LSP 导航
-
-[English](lsp.md) | 中文
-
-LSP seam 是一个[能力 seam](../glossary.zh.md#capability-seam)：它在单一 `ctx.lsp` 服务上公开语义代码导航，并拆分到多个包：Service Definition（[dsh-lsp](../../packages/lsp/lsp)，`ctx.lsp` + 提供方注册表）、通用 Service Provider（[dsh-lsp-stdio](../../packages/lsp/lsp-stdio)，经过配置的 stdio 语言服务器宿主）和 Consumer（[dsh-tool-lsp](../../packages/lsp/tool-lsp)，即 `lsp` 工具 schema）。LSP 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.zh.md) 中。更换提供方不会改变模型请求导航的方式。
-
-源文件：[`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
-
-## 操作与坐标
-
-seam 与模型恰好公开 4 项语义查询；该联合是闭合的，因此新增一项查询会通过编译强制要求同步修改 seam、提供方和工具。位置与范围采用从零开始的 UTF-16 坐标，与协议一致；面向模型的工具采用从 1 开始的光标约定，并在输入和输出时进行转换。
-
-```ts type-equiv
-/**
- * The four semantic queries the seam and model expose. A closed union: adding an operation is a
- * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
- * not operations here; they need different schemas.
- */
-type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
-```
-
-```ts type-equiv
-/** A zero-based UTF-16 cursor coordinate, matching the LSP wire convention. */
-interface LspPosition {
-  /** Zero-based line. */
-  readonly line: number
-  /** Zero-based UTF-16 code-unit offset within the line. */
-  readonly character: number
-}
-```
-
-```ts type-equiv
-/** A zero-based UTF-16 half-open range `[start, end)`. */
-interface LspRange {
-  readonly start: LspPosition
-  readonly end: LspPosition
-}
-```
-
-## 请求
-
-每个字段都是必填项：`workspaceRoot` 由调用方提供，`languageId` 来自提供方注册而非请求，超时与结果上限由消费方决定。因此没有字段需要由实现提供默认值，也不存在 `resolve()` 步骤。提供方收到调用方请求和派生的 `languageId`；后者只用于同步瞬态文档，从不参与选择。
-
-```ts type-equiv
-/**
- * A caller's normalized query. Every field is required: `workspaceRoot` is caller-supplied,
- * `languageId` comes from the provider registration (not here), and consumers own timeouts and
- * result limits — so no field needs implementation defaulting and there is no `resolve()` step.
- */
-interface LspQueryRequest {
-  /** Which semantic query to run. */
-  readonly operation: LspOperation
-  /** The source file to query (relative to `workspaceRoot` or absolute; the provider canonicalizes). */
-  readonly filePath: string
-  /** The zero-based UTF-16 cursor position to query at. */
-  readonly position: LspPosition
-  /** The workspace root the provider resolves against and indexes; required, never defaulted. */
-  readonly workspaceRoot: string
-}
-```
-
-```ts type-equiv
-/**
- * A request as a provider receives it: the caller's {@link LspQueryRequest} plus the `languageId`
- * the seam derived from the provider's extension mapping. The language id only synchronizes the
- * transient document; it does not participate in selection.
- */
-interface LspProviderQuery extends LspQueryRequest {
-  /** The LSP language id for `filePath`, from this provider's extension mapping. */
-  readonly languageId: string
-}
-```
-
-## 结果
-
-这是一个闭合的可辨识联合：导航操作规范化为 `locations`，`hover` 规范化为内容或 `null`。消费方使用 `switch` 对 `kind` 做穷尽处理，因此新增分支会使编译失败，直到完成处理。`findReferences` 始终包含声明；提供方在内部强制保证这一点，因此调用方没有对应 flag。`locations` 变体携带 `resolvedWorkspaceUri`，即提供方的规范工作区 `file:` URI。调用方相对化位置 URI 时应使用这一坐标，而不是对可能经过符号链接的请求根目录应用宿主平台路径规则。
-
-```ts type-equiv
-/** One resolved location: a document URI and the range within it. */
-interface LspLocation {
-  /** The target document URI (`file:` or otherwise), verbatim from the server. */
-  readonly uri: string
-  /** The range within the target document. */
-  readonly range: LspRange
-}
-```
-
-```ts type-equiv
-/** Normalized hover content, or `null` for no hover at the position. */
-interface LspHover {
-  /** The normalized hover text (markdown or plaintext, provider-joined). */
-  readonly contents: string
-  /** The range the hover applies to, when the server supplied one. */
-  readonly range?: LspRange
-}
-```
-
-```ts type-equiv
-/**
- * The closed result union. Navigation operations (`goToDefinition`, `findReferences`,
- * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
- * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
- *
- * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
- * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
- * request's possibly symlinked process path with host-platform rules; the execution platform may
- * differ from the caller's.
- */
-type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
-  | { readonly kind: 'hover'; readonly hover: LspHover | null }
-```
-
-## 提供方与服务
-
-每个提供方拥有一个稳定的品牌化 `id`，以及一份互斥的、小写且以点开头的扩展名映射。`registerProvider` 会原子预留 id 和每个扩展名：注册无效或冲突时不发布任何内容；其 disposer 会释放所有保留项。每次查询独立选择提供方，且选择与顺序无关；没有匹配项时抛出 `LspError` `LSP_UNAVAILABLE`。该 seam 不公开协议类型、进程或文档控制，也不提供通用 JSON-RPC 逃生口。
-
-```ts type-equiv
-/**
- * A language-server backend registered on `ctx.lsp`. Each provider owns a stable {@link
- * LspProviderId} and an extension-to-language-id map (lowercase, leading-dot keys).
- * `findReferences` always includes declarations — the provider enforces this internally; callers
- * get no flag.
- */
-interface LspProvider {
-  /** Stable provider identity, reserved atomically with the extension mappings. */
-  readonly id: LspProviderId
-  /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */
-  readonly extensionToLanguage: Readonly<Record<string, string>>
-  /**
-   * Run one query. The seam has already selected this provider and derived `languageId`.
-   * @param request - the resolved provider query (caller request + derived language id).
-   * @param signal - optional cancellation; the provider stops its own work when it aborts.
-   * @returns the normalized, closed-union result.
-   */
-  query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult>
-}
-```
-
-```ts type-equiv
-/**
- * The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query
- * execution; exposes exactly the four operations and no protocol escape hatch.
- */
-interface LspService {
-  /**
-   * Register a provider, atomically reserving its id and every normalized extension. Any conflict
-   * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
-   * reservations. Disposed with the calling fiber.
-   * @param provider - the backend to register.
-   * @returns a synchronous disposer releasing the id and all extension reservations.
-   */
-  registerProvider(provider: LspProvider): () => void
-  /**
-   * Select a provider by the file's extension and run one query. Selection is per-query and
-   * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
-   * @param request - the normalized query.
-   * @param signal - optional cancellation forwarded to the selected provider.
-   * @returns the normalized, closed-union result.
-   */
-  query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>
-}
-```
-
-`LspProviderId` 是该 seam 的品牌化 id（来自 [dsh-brand](../../packages/util/brand) 的 `Branded<'LspProviderId'>`）；`LspError` 扩展 `HarnessError`，提供 `LSP_INVALID_PROVIDER`、`LSP_CONFLICT`、`LSP_UNAVAILABLE`、`LSP_DISPOSED`、`LSP_UNSUPPORTED_OPERATION` 和 `LSP_MALFORMED_RESPONSE` 等稳定错误码，调用方应按错误码路由，而不是解析 `message`。
-
-<!-- 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="ctxlsp--lspservice"></a>
-
-### `ctx.lsp` — `LspService`
-
-The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query execution; exposes exactly the four operations and no protocol escape hatch.
-
-```ts cordis-catalog
-/**
- * Register a provider, atomically reserving its id and every normalized extension. Any conflict
- * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
- * reservations. Disposed with the calling fiber.
- * @param provider - the backend to register.
- * @returns a synchronous disposer releasing the id and all extension reservations.
- */
-registerProvider(provider: LspProvider): () => void
-
-/**
- * Select a provider by the file's extension and run one query. Selection is per-query and
- * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
- * @param request - the normalized query.
- * @param signal - optional cancellation forwarded to the selected provider.
- * @returns the normalized, closed-union result.
- */
-query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>
-```
-
-Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
-<!-- END GENERATED cordis-surface -->

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 -->