@deepseek-ai/dsh-office-kit 0.0.0-stage → 0.2.2-rc.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.i18n.yaml +37 -0
- package/README.md +128 -2
- package/README.zh.md +129 -0
- package/lib/index.js +1234 -0
- package/lib/typert.host.d.ts +3 -0
- package/lib/typert.host.js +346 -0
- package/lib/typert.remote-client.d.ts +30 -0
- package/lib/typert.remote-client.d.ts.map +1 -0
- package/lib/typert.remote-client.js +162 -0
- package/lib/types/errors.d.ts +13 -0
- package/lib/types/errors.d.ts.map +1 -0
- package/lib/types/errors.js +15 -0
- package/lib/types/errors.js.map +1 -0
- package/lib/types/identity.d.ts +27 -0
- package/lib/types/identity.d.ts.map +1 -0
- package/lib/types/identity.js +23 -0
- package/lib/types/identity.js.map +1 -0
- package/lib/types/index.d.ts +157 -0
- package/lib/types/index.d.ts.map +1 -0
- package/lib/types/index.js +459 -0
- package/lib/types/index.js.map +1 -0
- package/lib/types/locate.d.ts +48 -0
- package/lib/types/locate.d.ts.map +1 -0
- package/lib/types/locate.js +65 -0
- package/lib/types/locate.js.map +1 -0
- package/lib/types/output.d.ts +26 -0
- package/lib/types/output.d.ts.map +1 -0
- package/lib/types/output.js +75 -0
- package/lib/types/output.js.map +1 -0
- package/lib/types/outputs.d.ts +75 -0
- package/lib/types/outputs.d.ts.map +1 -0
- package/lib/types/outputs.js +198 -0
- package/lib/types/outputs.js.map +1 -0
- package/lib/types/queue.d.ts +106 -0
- package/lib/types/queue.d.ts.map +1 -0
- package/lib/types/queue.js +276 -0
- package/lib/types/queue.js.map +1 -0
- package/lib/types/types.d.ts +151 -0
- package/lib/types/types.d.ts.map +1 -0
- package/lib/types/types.js +2 -0
- package/lib/types/types.js.map +1 -0
- package/locale/de.json +6 -0
- package/locale/en.json +6 -0
- package/locale/es.json +6 -0
- package/locale/fr.json +6 -0
- package/locale/ja.json +6 -0
- package/locale/pt.json +6 -0
- package/locale/ru.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +68 -3
- package/src/errors.ts +15 -0
- package/src/identity.ts +31 -0
- package/src/index.ts +484 -0
- package/src/locate.ts +93 -0
- package/src/output.ts +69 -0
- package/src/outputs.ts +218 -0
- package/src/queue.ts +316 -0
- package/src/types.ts +168 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 DeepSeek
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.i18n.yaml
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
|
|
2
|
+
# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
|
|
3
|
+
# After editing either side, bring the other along and re-record with:
|
|
4
|
+
# pnpm run verify-translation-pairing --write packages/document/office-kit/README.md
|
|
5
|
+
/:
|
|
6
|
+
en: 3aa02c9e17e94752
|
|
7
|
+
zh: 1157a4f1863e19de
|
|
8
|
+
/deepseek-ai-dsh-office-kit:
|
|
9
|
+
en: 37156fb2f1de123c
|
|
10
|
+
zh: 44b77def8f181d4b
|
|
11
|
+
/deepseek-ai-dsh-office-kit/summary:
|
|
12
|
+
en: fe9c42abe01693ae
|
|
13
|
+
zh: d3f1a9533a48b40e
|
|
14
|
+
/deepseek-ai-dsh-office-kit/table-of-contents:
|
|
15
|
+
en: d152484eb41ac6b4
|
|
16
|
+
zh: a134331a31395608
|
|
17
|
+
/deepseek-ai-dsh-office-kit/use-this-package:
|
|
18
|
+
en: 3a4b3e462240f493
|
|
19
|
+
zh: 336f481e2f14b76b
|
|
20
|
+
/deepseek-ai-dsh-office-kit/understand-the-implementation:
|
|
21
|
+
en: ddd81007f05f3065
|
|
22
|
+
zh: f103b2664f234f49
|
|
23
|
+
/deepseek-ai-dsh-office-kit/further-exploration:
|
|
24
|
+
en: 9c62c26d46625e8b
|
|
25
|
+
zh: 9d0b734d70fdf948
|
|
26
|
+
/deepseek-ai-dsh-office-kit/model-experience:
|
|
27
|
+
en: 5b001842f3d350a1
|
|
28
|
+
zh: 244c53b867fff8d0
|
|
29
|
+
/deepseek-ai-dsh-office-kit/model-experience/kv-cache-effect:
|
|
30
|
+
en: cd1110fd1b70aaa0
|
|
31
|
+
zh: 623d77245348d129
|
|
32
|
+
/deepseek-ai-dsh-office-kit/known-limitations-and-deferred-work:
|
|
33
|
+
en: 69c3e07db32dd27e
|
|
34
|
+
zh: 8c056a6253b9d0b0
|
|
35
|
+
/deepseek-ai-dsh-office-kit/known-limitations-and-deferred-work/dev-note:
|
|
36
|
+
en: e67f633dc6fe7773
|
|
37
|
+
zh: 8ec3e73528ddb1a6
|
package/README.md
CHANGED
|
@@ -1,3 +1,129 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
description: "Host Office rendering, conversion, and recalculation with the independently published kit."
|
|
3
|
+
kind: "package-reference"
|
|
4
|
+
---
|
|
2
5
|
|
|
3
|
-
|
|
6
|
+
# @deepseek-ai/dsh-office-kit
|
|
7
|
+
|
|
8
|
+
English | [中文](README.zh.md)
|
|
9
|
+
|
|
10
|
+
## Summary
|
|
11
|
+
|
|
12
|
+
Render Office documents as PDFs or PNG images, convert them between formats, and recalculate workbooks on the Host computer. Targets with a declared native LibreOffice engine use it; other targets use Node WASM. Previews accept DOC, DOCX, XLS, XLSX, PPT, and PPTX; operations also accept the OpenDocument formats, and image rendering accepts PDF. OOXML operations return missing-font names; binary Office operations return an empty list.
|
|
13
|
+
|
|
14
|
+
## Table of Contents
|
|
15
|
+
|
|
16
|
+
- [Use this package](#use-this-package)
|
|
17
|
+
- [Understand the implementation](#understand-the-implementation)
|
|
18
|
+
- [Further Exploration](#further-exploration)
|
|
19
|
+
- [Model Experience](#model-experience)
|
|
20
|
+
- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
|
|
21
|
+
- [Dev Note](#dev-note)
|
|
22
|
+
|
|
23
|
+
-----
|
|
24
|
+
|
|
25
|
+
<a id="use-this-package"></a>
|
|
26
|
+
## Use this package
|
|
27
|
+
|
|
28
|
+
The [Web bundle](../../bundle/web-app/README.md) and the [SDK bundle](../../bundle/sdk-app/README.md) mount this provider as `office-kit`; the [Office tools](../tool-office/README.md) are its model-facing consumers. Independent compositions mount `@deepseek-ai/dsh-office-kit` as a `cordis.yml` row.
|
|
29
|
+
|
|
30
|
+
Callers submit authorized source identity, version, optional byte size, a deferred bounded read, and input extension; PDF conversions also name a scheduling priority, and image rendering, format conversion, and recalculation run at foreground priority. A changed source version rejects the operation. Cancellation rejects with its reason; failures use `OfficeKitError`. Every result carries the missing fonts; PDF results also carry the conversion generation, which changes on configuration replacement.
|
|
31
|
+
|
|
32
|
+
| Method | Operation | Result |
|
|
33
|
+
|---|---|---|
|
|
34
|
+
| `convert()` | Office to PDF for previews | caller-owned PDF bytes and a cache key |
|
|
35
|
+
| `renderImages()` | selected pages, slides, or worksheet areas to PNG | images in document order with their page, sheet, or range, plus the document page count and DPI |
|
|
36
|
+
| `convertTo()` | conversion to the format of `format`; CSV takes a `sheet` | the saved file's Host path, size, and PDF page count |
|
|
37
|
+
| `recalculate()` | XLS, XLSX, or ODS recalculation to XLSX or ODS | the saved workbook's Host path and size |
|
|
38
|
+
|
|
39
|
+
`renderImages()` requires `maxImages`, `maxPixels`, `maxDimension`, and `maxBytes`. The engine rejects a selection with more images than `maxImages` or an image above the pixel or dimension limit; the provider rejects images whose total PNG bytes exceed `maxBytes` with `output-too-large`, before and while reading them. A page, sheet, range, resolution, or format selection the engine rejects fails with `invalid-request` and the engine's description. Converted and recalculated files obey `maxOutputBytes`. The provider never writes into a workspace: it saves each output in its own owner-only directory under `outputDirectory`, grouped by the request's `output.owner` (`office_convert` and `office_recalculate` pass the root Session of the caller's subagent tree), and returns the absolute Host path. A file is deleted after `outputRetentionMs`, when newer outputs need room within `maxOutputStoreBytes` (oldest first), when the Session whose id equals the owner is disposed, or when the provider unloads; a file larger than `maxOutputStoreBytes` fails with `output-too-large`. A file counts toward `maxOutputStoreBytes` until its deletion succeeds; a failed deletion is logged and retried by later eviction, release, and unload, and a save that cannot free enough room fails with `unavailable`. Unload waits for deletions in progress. Startup also removes expired output directories of earlier processes, considering only real directories, not links or junctions, with the names the provider generates: `session-` and 24 lowercase hexadecimal digits directly under `outputDirectory`, each holding lowercase UUID v4 output directories. Other entries are left untouched. `outputDirectory` is exposed on the service so consumers can check that their execution world reads it.
|
|
40
|
+
|
|
41
|
+
The provider depends on the independently published [`@deepseek-ai/libreoffice-kit`](https://github.com/deepseek-ai/dsh-libreoffice-kit) npm API at kit version `0.2.3`. Application packaging selects the matching native package declared in the kit’s `optionalDependencies`, or WASM when no native package is declared for that target. A missing declared native engine rejects packaging without selecting WASM. The [release ownership decision](../../../.agents/notes/implemented/architecture/2026-09-14-independent-libreoffice-kit.md) defines the independent kit and Harness responsibilities.
|
|
42
|
+
|
|
43
|
+
The provider registers even when its Kit is absent, such as a Python SDK executable launched without a downloaded Office sidecar. A conversion that needs a new converter then rejects with `OfficeKitError` code `unavailable`, and the provider logs each distinct failure once through `ctx.logger`. A Kit entry that fails to import behaves the same way. The provider retains only a successful import, so a later conversion locates and imports Kit again. The Office preview shows its localized `unavailable` message for the `document-render/failed` reason.
|
|
44
|
+
|
|
45
|
+
Browsers request PDFs through the `officeKit.render` Remote method with a Session identity, Office path, and priority. This entry uses `workspaceFiles` for authorization and source versions, then reads raw bytes through `fs.readBytes` within the conversion reservation. In-process `convert()` does not require those services. Responses retain the source path and version and carry native PDF bytes through the binary Remote multipart transport, plus missing fonts and conversion generation. The `officeKit.generation` Remote method returns the current provider generation; `api/remotes` mounts the generated Client descriptor.
|
|
46
|
+
|
|
47
|
+
| Field | Default | Meaning |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| `maxConcurrentConversions` | `2` | Maximum active converters; queued calls remain cancellable. |
|
|
50
|
+
| `timeoutMs` | `60000` | Conversion deadline after a converter is acquired. |
|
|
51
|
+
| `maxInputBytes` | `52428800` | Maximum source bytes. |
|
|
52
|
+
| `maxOutputBytes` | `104857600` | Maximum complete PDF, converted, or recalculated file bytes. |
|
|
53
|
+
| `outputDirectory` | `$DSH_HOME/office-kit/outputs` | Absolute directory for converted and recalculated files. |
|
|
54
|
+
| `outputRetentionMs` | `86400000` | Milliseconds an output is kept. |
|
|
55
|
+
| `maxOutputStoreBytes` | `536870912` | Maximum bytes across retained outputs. |
|
|
56
|
+
| `maxImageResolution` | `192` | Image resolution in DPI of PDF exports; overrides the kit default of `144`. `renderImages()` uses each request's `dpi` instead. |
|
|
57
|
+
| `fontFallbacks` | Kit defaults | Ordered font-family preference groups; each group requires at least two names containing non-whitespace characters. |
|
|
58
|
+
|
|
59
|
+
The [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-office-kit) owns the full font, archive, and image settings. `fontDirectories` accepts absolute directories; omission uses the kit platform defaults. Explicit `fontFallbacks` replaces the kit's default groups. Installed requested fonts retain precedence, and other system fonts remain eligible for uncovered glyphs. Native engines can select installed metric-compatible fonts before these preferences.
|
|
60
|
+
|
|
61
|
+
The [bounded conversion decision](../../../.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.md) explains queue admission, cache limits, and shared cancellation.
|
|
62
|
+
|
|
63
|
+
All four methods share one admission queue, so tool operations and previews compete for the same converters, reservations, and cache. The provider retains successful outputs by converter generation, input extension, the operation and its parameters, and SHA-256 of the exact source bytes. A bounded source-version index avoids rereading known content after an authorized stat; content identity also shares conversion across different source paths. Least-recently-used outputs leave at either retention limit, together with their aliases. Failures and oversized cache entries are not retained. Every result has independent byte and font buffers. Ready alias hits consume no reader slot; active source locators are released when their last reader leaves. Reopening a source after its final reader cancels rereads its bytes before sharing by digest, even if another source kept the conversion alive or its PDF is ready.
|
|
64
|
+
|
|
65
|
+
Admission bounds queued metadata, outstanding readers, active source-byte reservations, and conversions before invoking a source read. Unknown source sizes reserve `maxInputBytes`; known sizes reserve their stat size. Reads receive that capacity and may read one overflow sentinel byte. `maxSourceBytes` must cover `maxInputBytes`. The final reader allowance is reserved for foreground work. Setting `maxBackgroundConversions` to zero rejects background joins to queued and running work; completed alias hits remain available. Background jobs wait while any foreground job is queued, including when it awaits source capacity. Foreground joins promote queued prewarming; when its last foreground reader leaves, the queued job returns to background priority and eligible work can start immediately. Foreground admission can evict queued speculation. Background concurrency leaves a foreground slot when total concurrency exceeds one. A running prewarm keeps its background admission slot until settlement, even after promotion. The final reader cancels shared work. Removing a queued foreground blocker immediately admits other eligible work; active reservations remain held until actual read/conversion cleanup settles.
|
|
66
|
+
|
|
67
|
+
The defaults retain 8 outputs/128 MiB and 64 source aliases, admit 32 readers and 8 queued jobs, reserve at most 100 MiB of source bytes, and allow one background conversion. These limits bound owned requests and binary payloads, not engine RSS, multipart framing, caller-retained results, or PDF.js page rendering.
|
|
68
|
+
|
|
69
|
+
-----
|
|
70
|
+
|
|
71
|
+
<a id="understand-the-implementation"></a>
|
|
72
|
+
## Understand the implementation
|
|
73
|
+
|
|
74
|
+
<details>
|
|
75
|
+
<summary>Implementation internals — click to expand</summary>
|
|
76
|
+
|
|
77
|
+
Until a Kit import succeeds, each converter request passes a lookup that returns the provider's own `import.meta.resolve('@deepseek-ai/libreoffice-kit')` to [`resolveKitModule`](src/locate.ts), which returns the Kit entry with an engine-package resolver anchored there, or `missing`. The provider then dynamically imports that entry; it has no static Kit value import. This anchors engine lookup to the Kit installation used by the provider.
|
|
78
|
+
|
|
79
|
+
The engine-package resolver is created from the Kit entry; each resolver is independent. A successful call returns an absolute engine `package.json` path. An absent package preserves Node's original `MODULE_NOT_FOUND`, allowing Kit's native-to-WASM fallback. If a package directory exists, including a dangling symlink, but its manifest cannot resolve, the resolver throws an incomplete-installation error with the Node error as `cause`; reinstall that package. Other resolution and filesystem inspection errors propagate unchanged. Kit owns validation of the returned manifest and required assets.
|
|
80
|
+
|
|
81
|
+
The locate functions call the provider's lookup once per resolution and treat any thrown value as an absent Kit. Native engine paths use one mapping that replaces only the first `.asar` archive segment with `.asar.unpacked`, regardless of whether the process runs in Electron. Already-unpacked paths and paths outside an archive remain unchanged. `@deepseek-ai/libreoffice-kit-wasm` always keeps Node's logical path for archive-aware filesystem access. These functions do not import Kit, load engine code, register services, mutate module resolution, or retain module-level state; [Desktop packaging](../../../apps/desktop/packaging/README.md#runtime-file-selection) owns which packages are unpacked.
|
|
82
|
+
|
|
83
|
+
Invalid engine metadata, missing required assets, and conversion errors reject the request instead of switching engines. The shared WASM engine uses LibreOffice's CPU image filter. Native conversion uses its separate platform engine.
|
|
84
|
+
|
|
85
|
+
Each concurrent slot lazily creates and reuses one kit converter. The provider writes authorized input into a private temporary directory, reads bounded regular output files from it, refuses image paths outside its image directory, and removes the directory before settling. Canceling an admitted reader does not block later queued work. Reader cancellation releases only that reader; the final reader and provider disposal cancel shared work. Disposal reports `unavailable` to outstanding readers and joins conversions and converter teardown.
|
|
86
|
+
|
|
87
|
+
Remote file reads recheck content authorization and source version before consulting the conversion cache. Deferred reads run after conversion admission and verify the source version after reading. Source-read failures pass through; conversion failures return `document-render/failed` with a classified reason and no engine diagnostics. Unload cancels and joins authorization reads, Remote requests, and conversion work.
|
|
88
|
+
|
|
89
|
+
</details>
|
|
90
|
+
|
|
91
|
+
-----
|
|
92
|
+
|
|
93
|
+
<a id="further-exploration"></a>
|
|
94
|
+
## Further Exploration
|
|
95
|
+
|
|
96
|
+
- [Office Kit](../../../docs/subsystems/office-kit.md) — composition and input/result ownership.
|
|
97
|
+
- [Office tool](../tool-office/README.md) — the model-facing render, convert, and recalculate tool.
|
|
98
|
+
- [Workspace Files](../../api/workspace-files/README.md) — Session file authorization and bounded reads.
|
|
99
|
+
|
|
100
|
+
-----
|
|
101
|
+
|
|
102
|
+
<a id="model-experience"></a>
|
|
103
|
+
## Model Experience
|
|
104
|
+
|
|
105
|
+
Indirectly, through [the Office tools](../tool-office/README.md#model-experience), which return rendered images and converted files from this service.
|
|
106
|
+
|
|
107
|
+
#### KV Cache effect
|
|
108
|
+
|
|
109
|
+
None; this service does not construct or modify model requests.
|
|
110
|
+
|
|
111
|
+
## Known Limitations and Deferred Work
|
|
112
|
+
|
|
113
|
+
<a id="known-limitations-and-deferred-work"></a>
|
|
114
|
+
|
|
115
|
+
- Conversion fidelity and installed native/WASM assets belong to `@deepseek-ai/libreoffice-kit`; this provider neither searches for system LibreOffice nor downloads an engine at runtime.
|
|
116
|
+
- Queue waiting time is not bounded by `timeoutMs`, which starts only when kit conversion begins.
|
|
117
|
+
- The provider locates only the Kit installation it resolves itself; it does not search other locations or install Kit or engines.
|
|
118
|
+
- Rendered images are returned as bytes. Converted and recalculated files are stored in the provider's output directory, not in the workspace; the caller copies each file to its destination.
|
|
119
|
+
- Mapping a native path does not verify that the unpacked copy exists. Kit rejects missing manifests or assets instead of treating them as an absent native package.
|
|
120
|
+
|
|
121
|
+
<a id="dev-note"></a>
|
|
122
|
+
### Dev Note
|
|
123
|
+
|
|
124
|
+
<details>
|
|
125
|
+
<summary>Working context for maintainers — click to expand</summary>
|
|
126
|
+
|
|
127
|
+
None.
|
|
128
|
+
|
|
129
|
+
</details>
|
package/README.zh.md
ADDED
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "通过独立发布的 kit 在 Host 渲染、转换 Office 文档和重算工作簿。"
|
|
3
|
+
kind: "package-reference"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# @deepseek-ai/dsh-office-kit
|
|
7
|
+
|
|
8
|
+
[English](README.md) | 中文
|
|
9
|
+
|
|
10
|
+
## 概述
|
|
11
|
+
|
|
12
|
+
在宿主计算机上将 Office 文档渲染为 PDF 或 PNG 图片、在格式之间转换,以及重算工作簿。声明了原生 LibreOffice 引擎的目标使用原生引擎,其余目标使用 Node WASM。预览支持 DOC、DOCX、XLS、XLSX、PPT 和 PPTX;操作还支持 OpenDocument 格式,图片渲染还支持 PDF。OOXML 操作返回缺失字体名称;二进制 Office 操作返回空列表。
|
|
13
|
+
|
|
14
|
+
## 目录
|
|
15
|
+
|
|
16
|
+
- [使用此包](#use-this-package)
|
|
17
|
+
- [理解实现](#understand-the-implementation)
|
|
18
|
+
- [延伸阅读](#further-exploration)
|
|
19
|
+
- [模型体验](#model-experience)
|
|
20
|
+
- [已知限制与延后工作](#known-limitations-and-deferred-work)
|
|
21
|
+
- [开发备注](#dev-note)
|
|
22
|
+
|
|
23
|
+
-----
|
|
24
|
+
|
|
25
|
+
<a id="use-this-package"></a>
|
|
26
|
+
## 使用此包
|
|
27
|
+
|
|
28
|
+
[Web bundle](../../bundle/web-app/README.zh.md)和 [SDK bundle](../../bundle/sdk-app/README.zh.md)以 `office-kit` 条目挂载此提供方;[Office 工具](../tool-office/README.zh.md)是其面向模型的消费方。独立组合通过 `cordis.yml` 条目挂载 `@deepseek-ai/dsh-office-kit`。
|
|
29
|
+
|
|
30
|
+
调用方提交已授权源的标识、版本、可选字节数、延迟的有界读取、输入扩展名;PDF 转换还指定调度优先级,图片渲染、格式转换和重算以前台优先级运行。源版本变化会拒绝操作。取消以原因为拒绝值,失败使用 `OfficeKitError`。每个结果都携带缺失字体;PDF 结果还携带转换 generation(配置替换后随之改变)。
|
|
31
|
+
|
|
32
|
+
| 方法 | 操作 | 结果 |
|
|
33
|
+
|---|---|---|
|
|
34
|
+
| `convert()` | 为预览把 Office 转为 PDF | 调用方拥有的 PDF 字节和缓存键 |
|
|
35
|
+
| `renderImages()` | 把选定的页、幻灯片或工作表区域渲染为 PNG | 按文档顺序排列的图片及其页码、工作表或区域,以及文档页数和 DPI |
|
|
36
|
+
| `convertTo()` | 转换为 `format` 指定的格式;CSV 需要 `sheet` | 已保存文件的 Host 路径、大小和 PDF 页数 |
|
|
37
|
+
| `recalculate()` | 把 XLS、XLSX 或 ODS 重算为 XLSX 或 ODS | 已保存工作簿的 Host 路径和大小 |
|
|
38
|
+
|
|
39
|
+
`renderImages()` 要求提供 `maxImages`、`maxPixels`、`maxDimension` 和 `maxBytes`。图片数超过 `maxImages`,或单张图片超过像素或尺寸上限时,引擎拒绝该选择;图片 PNG 总字节数超过 `maxBytes` 时,提供方在读取前和读取过程中以 `output-too-large` 拒绝。引擎拒绝的页、工作表、区域、分辨率或格式选择以 `invalid-request` 失败,并附带引擎的说明。转换和重算的文件受 `maxOutputBytes` 限制。提供方从不写入工作区:它把每个输出保存在 `outputDirectory` 下各自仅属主可访问的目录中,按请求的 `output.owner`(`office_convert` 和 `office_recalculate` 传入调用方 subagent 树的根 Session)分组,并返回绝对 Host 路径。文件在 `outputRetentionMs` 到期、较新的输出需要 `maxOutputStoreBytes` 内的空间(最旧的先删)、id 等于 owner 的 Session 卸载或提供方卸载时删除;单个文件超过 `maxOutputStoreBytes` 时以 `output-too-large` 失败。文件在删除成功之前一直计入 `maxOutputStoreBytes`;删除失败时记录日志,并在之后的淘汰、释放和卸载时重试,腾不出足够空间的保存以 `unavailable` 失败。卸载会等待进行中的删除结束。启动时还会删除之前进程留下的、超过保留期的输出目录,但只处理名字符合提供方生成格式的真实目录,不处理链接或 junction:`outputDirectory` 下一级为 `session-` 加 24 位小写十六进制数字,其下为小写 UUID v4 的输出目录。其他条目保持不动。服务公开 `outputDirectory`,供消费方检查其执行环境能否读取。
|
|
40
|
+
|
|
41
|
+
此 provider 依赖独立发布的 [`@deepseek-ai/libreoffice-kit`](https://github.com/deepseek-ai/dsh-libreoffice-kit) npm API,kit 版本为 `0.2.3`。应用打包选择 kit 的 `optionalDependencies` 中声明的匹配原生包;目标没有声明原生包时选择 WASM。已声明的原生引擎缺失时拒绝打包,不会选择 WASM。[发布归属决策](../../../.agents/notes/implemented/architecture/2026-09-14-independent-libreoffice-kit.zh.md)定义独立 kit 与 Harness 各自的职责。
|
|
42
|
+
|
|
43
|
+
Kit 缺失时提供方照常注册,例如未下载 Office sidecar 就启动的 Python SDK 可执行程序。此时需要新转换器的转换以代码为 `unavailable` 的 `OfficeKitError` 拒绝,提供方通过 `ctx.logger` 对每种不同的失败只报告一次。Kit 入口导入失败时行为相同。提供方只保留成功的导入,因此之后的转换会重新定位并导入 Kit。Office 预览对 `document-render/failed` 原因显示本地化的 `unavailable` 提示。
|
|
44
|
+
|
|
45
|
+
浏览器通过 `officeKit.render` Remote 方法请求 PDF,参数为 Session 标识、Office 路径和优先级。此入口使用 `workspaceFiles` 完成授权和源版本检查,再通过 `fs.readBytes` 在转换预留容量内读取原始字节。进程内 `convert()` 不要求这些服务。响应保留源文件路径与版本,通过二进制 Remote 的 multipart 传输携带原生 PDF 字节,并携带缺失字体和转换 generation。`officeKit.generation` Remote 方法返回当前提供方 generation;`api/remotes` 负责挂载生成的 Client 描述符。
|
|
46
|
+
|
|
47
|
+
| 字段 | 默认值 | 含义 |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| `maxConcurrentConversions` | `2` | 最大活跃转换器数量;排队调用仍可取消。 |
|
|
50
|
+
| `timeoutMs` | `60000` | 获取转换器后的转换期限。 |
|
|
51
|
+
| `maxInputBytes` | `52428800` | 最大源字节数。 |
|
|
52
|
+
| `maxOutputBytes` | `104857600` | 最大完整 PDF、转换或重算文件字节数。 |
|
|
53
|
+
| `outputDirectory` | `$DSH_HOME/office-kit/outputs` | 转换和重算文件的绝对目录。 |
|
|
54
|
+
| `outputRetentionMs` | `86400000` | 输出保留的毫秒数。 |
|
|
55
|
+
| `maxOutputStoreBytes` | `536870912` | 保留输出的最大总字节数。 |
|
|
56
|
+
| `maxImageResolution` | `192` | PDF 导出中图像的 DPI;覆盖 kit 的默认值 `144`。`renderImages()` 改用每个请求的 `dpi`。 |
|
|
57
|
+
| `fontFallbacks` | kit 默认值 | 有序字体族优先组;每组至少包含两个含非空白字符的名称。 |
|
|
58
|
+
|
|
59
|
+
[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-office-kit)定义全部字体、归档和图像设置。`fontDirectories` 接受绝对目录;省略时使用 kit 的平台默认值。显式 `fontFallbacks` 替换 kit 的默认分组。已安装的请求字体仍优先使用,缺失字形仍可由其他系统字体提供。原生引擎可能在应用这些优先规则前选中已安装的度量兼容字体。
|
|
60
|
+
|
|
61
|
+
[有界转换决策](../../../.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.zh.md)说明队列准入、缓存限额与共享取消的设计依据。
|
|
62
|
+
|
|
63
|
+
四个方法共用一个准入队列,因此工具操作与预览竞争同一组转换器、预留容量和缓存。提供方按转换 generation、输入扩展名、操作及其参数和精确源字节的 SHA-256 保留成功输出。有界的源版本索引在授权 stat 后避免重读已知内容;内容标识也会在不同源路径之间共享转换。达到任一保留上限时,最近最少使用的输出及其别名一同移除。不保留失败或超过缓存上限的结果。每个结果具有独立的字节与字体缓冲区。已就绪别名命中不占用读取方名额;同一源的最后一个读取方离开时,立即释放其在途定位信息。源的最后一个读取方取消后,再次打开该源会重新读取字节,再按内容摘要共享转换,即使其他源仍保持该转换运行或其 PDF 已就绪。
|
|
64
|
+
|
|
65
|
+
准入在调用源读取前限制排队元数据、未完成读取方、活动源字节预留和转换。未知源大小预留 `maxInputBytes`;已知大小预留 stat 字节数。读取收到该容量,最多额外读取一个超限哨兵字节。`maxSourceBytes` 必须覆盖 `maxInputBytes`。最后一个读取方额度预留给前台。`maxBackgroundConversions` 设为零时,拒绝后台读取方加入排队或运行中的工作;仍可命中已完成的别名缓存。只要仍有前台任务排队,后台任务就继续等待,包括前台正在等待源容量的情况。前台加入会提升排队预热;最后一个前台读取方离开后,排队任务恢复后台优先级,符合条件的工作可立即开始。前台准入也可移除排队推测工作。总并发大于一时,后台并发为前台保留一个槽位。正在运行的预热即使被提权,也保留后台准入槽位直至结束。最后一个读取方取消共享工作。移除排队的前台阻塞任务后,其他符合条件的工作立即准入;实际读取、转换和清理完成前仍保留活动预留容量。
|
|
66
|
+
|
|
67
|
+
默认保留 8 个输出、128 MiB 和 64 个源别名,准入 32 个读取方与 8 个排队任务,最多预留 100 MiB 源字节,并允许一个后台转换。这些限制约束拥有的请求和二进制载荷,不约束引擎 RSS、multipart 封装、调用方保留的结果或 PDF.js 页面渲染。
|
|
68
|
+
|
|
69
|
+
-----
|
|
70
|
+
|
|
71
|
+
<a id="understand-the-implementation"></a>
|
|
72
|
+
## 理解实现
|
|
73
|
+
|
|
74
|
+
<details>
|
|
75
|
+
<summary>实现内部细节 — 点击展开</summary>
|
|
76
|
+
|
|
77
|
+
在 Kit 导入成功之前,每次需要转换器时,提供方都把返回自身 `import.meta.resolve('@deepseek-ai/libreoffice-kit')` 的查找函数传给 [`resolveKitModule`](src/locate.ts),它返回 Kit 入口和以其为起点的引擎包解析器,或返回 `missing`。随后提供方动态导入该入口;提供方没有静态导入 Kit 的值。这使引擎查找以提供方实际使用的 Kit 安装为起点。
|
|
78
|
+
|
|
79
|
+
引擎包解析器以 Kit 入口为起点创建;每个解析器互相独立。解析成功时返回引擎 `package.json` 的绝对路径。包不存在时保留 Node 原始的 `MODULE_NOT_FOUND`,允许 Kit 从原生引擎回退到 WASM。如果包目录存在(包括断开的符号链接),但清单无法解析,解析器抛出安装不完整错误,并将 Node 错误保存在 `cause` 中;此时应重新安装该包。其他解析错误和文件系统检查错误原样传播。Kit 负责验证返回的清单和必需资源。
|
|
80
|
+
|
|
81
|
+
定位函数每次解析调用一次提供方的查找函数,并把任何抛出的值视为 Kit 缺失。原生引擎路径使用同一映射,只将第一个 `.asar` 归档段替换为 `.asar.unpacked`,不论进程是否运行在 Electron 中。已解包路径及归档外路径保持不变。`@deepseek-ai/libreoffice-kit-wasm` 始终保留 Node 逻辑路径,供支持归档的文件系统访问。这些函数不导入 Kit、不加载引擎代码、不注册服务、不修改模块解析,也不保留模块级状态;[Desktop 打包](../../../apps/desktop/packaging/README.zh.md#runtime-file-selection)负责决定解包哪些包。
|
|
82
|
+
|
|
83
|
+
引擎元数据无效、必需资源缺失和转换错误会拒绝请求,不会切换引擎。共享的 WASM 引擎使用 LibreOffice 的 CPU 图像过滤器。原生转换使用独立的平台引擎。
|
|
84
|
+
|
|
85
|
+
每个并发槽按需创建并复用一个 kit 转换器。提供方将已授权输入写入私有临时目录,从中读取有大小上限的普通输出文件,拒绝位于图片目录之外的图片路径,并在完成前删除目录。取消已准入的读取方不会阻塞后续排队工作。读取方取消只会释放该读取方;最后一个读取方和提供方卸载会取消共享工作。卸载向未完成读取方报告 `unavailable`,并等待转换及转换器清理结束。
|
|
86
|
+
|
|
87
|
+
Remote 文件读取在查询转换缓存前重新检查内容读取授权和源版本。延迟读取在取得转换容量后执行,并在读取后验证源版本。源读取失败直接传递;转换失败返回 `document-render/failed` 及分类原因,不暴露引擎诊断。卸载会取消并等待授权读取、Remote 请求和转换工作全部结束。
|
|
88
|
+
|
|
89
|
+
</details>
|
|
90
|
+
|
|
91
|
+
-----
|
|
92
|
+
|
|
93
|
+
<a id="further-exploration"></a>
|
|
94
|
+
## 延伸阅读
|
|
95
|
+
|
|
96
|
+
- [Office Kit](../../../docs/subsystems/office-kit.zh.md) — 组合与输入、结果所有权。
|
|
97
|
+
- [Office 工具](../tool-office/README.zh.md) — 面向模型的渲染、转换和重算工具。
|
|
98
|
+
- [工作区文件](../../api/workspace-files/README.zh.md) — Session 文件授权与有界读取。
|
|
99
|
+
|
|
100
|
+
-----
|
|
101
|
+
|
|
102
|
+
<a id="model-experience"></a>
|
|
103
|
+
## 模型体验
|
|
104
|
+
|
|
105
|
+
间接地,通过 [Office 工具](../tool-office/README.zh.md#model-experience),这些工具返回此服务渲染的图片和转换的文件。
|
|
106
|
+
|
|
107
|
+
#### KV Cache effect
|
|
108
|
+
|
|
109
|
+
无;此服务不会构造或修改模型请求。
|
|
110
|
+
|
|
111
|
+
## 已知限制与延后工作
|
|
112
|
+
|
|
113
|
+
<a id="known-limitations-and-deferred-work"></a>
|
|
114
|
+
|
|
115
|
+
- 转换保真度和已安装的原生/WASM 资产由 `@deepseek-ai/libreoffice-kit` 负责;此提供方不查找系统 LibreOffice,也不在运行时下载引擎。
|
|
116
|
+
- `timeoutMs` 仅在 kit 开始转换时计时,不限制队列等待时间。
|
|
117
|
+
- 提供方只定位自身解析到的 Kit 安装;不搜索其他位置,也不安装 Kit 或引擎。
|
|
118
|
+
- 渲染的图片以字节返回。转换和重算后的文件存放在提供方的输出目录中,不写入工作区;由调用方把每个文件复制到目标位置。
|
|
119
|
+
- 映射原生路径时不验证解包副本是否存在。Kit 会拒绝缺失的清单或资源,而不会将其视为原生包缺失。
|
|
120
|
+
|
|
121
|
+
<a id="dev-note"></a>
|
|
122
|
+
### 开发备注
|
|
123
|
+
|
|
124
|
+
<details>
|
|
125
|
+
<summary>维护者工作上下文 — 点击展开</summary>
|
|
126
|
+
|
|
127
|
+
无。
|
|
128
|
+
|
|
129
|
+
</details>
|