dsh-office-forge 0.0.0-stage → 0.14.0

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.
Files changed (88) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +428 -2
  3. package/README.zh.md +429 -0
  4. package/benchmarks/baseline.json +52 -0
  5. package/benchmarks/run_benchmarks.py +261 -0
  6. package/cordis.patch.yml +7 -0
  7. package/docs/BENCHMARKS.md +44 -0
  8. package/docs/CHANGELOG.md +174 -0
  9. package/docs/COMPATIBILITY-MATRIX.md +23 -0
  10. package/docs/COMPATIBILITY.md +63 -0
  11. package/docs/COVERAGE.md +47 -0
  12. package/docs/DESIGN.md +128 -0
  13. package/icon.svg +12 -0
  14. package/lib/client.js +49 -0
  15. package/lib/index.js +1382 -0
  16. package/lib/office_backends.py +360 -0
  17. package/lib/office_com_worker.py +395 -0
  18. package/lib/office_common.py +410 -0
  19. package/lib/office_docx.py +1628 -0
  20. package/lib/office_engine.py +403 -0
  21. package/lib/office_migrations.py +52 -0
  22. package/lib/office_pdf.py +217 -0
  23. package/lib/office_pdf_tools.py +455 -0
  24. package/lib/office_pptx.py +1474 -0
  25. package/lib/office_xlsx.py +1685 -0
  26. package/lib/vendor/pypdf/__init__.py +48 -0
  27. package/lib/vendor/pypdf/_cmap.py +375 -0
  28. package/lib/vendor/pypdf/_codecs/__init__.py +55 -0
  29. package/lib/vendor/pypdf/_codecs/_codecs.py +284 -0
  30. package/lib/vendor/pypdf/_codecs/adobe_glyphs.py +13969 -0
  31. package/lib/vendor/pypdf/_codecs/core_font_metrics.py +4483 -0
  32. package/lib/vendor/pypdf/_codecs/pdfdoc.py +264 -0
  33. package/lib/vendor/pypdf/_codecs/std.py +258 -0
  34. package/lib/vendor/pypdf/_codecs/symbol.py +260 -0
  35. package/lib/vendor/pypdf/_codecs/zapfding.py +261 -0
  36. package/lib/vendor/pypdf/_crypt_providers/__init__.py +80 -0
  37. package/lib/vendor/pypdf/_crypt_providers/_base.py +38 -0
  38. package/lib/vendor/pypdf/_crypt_providers/_cryptography.py +132 -0
  39. package/lib/vendor/pypdf/_crypt_providers/_fallback.py +93 -0
  40. package/lib/vendor/pypdf/_crypt_providers/_pycryptodome.py +110 -0
  41. package/lib/vendor/pypdf/_doc_common.py +1505 -0
  42. package/lib/vendor/pypdf/_encryption.py +1305 -0
  43. package/lib/vendor/pypdf/_font.py +722 -0
  44. package/lib/vendor/pypdf/_page.py +2492 -0
  45. package/lib/vendor/pypdf/_page_labels.py +321 -0
  46. package/lib/vendor/pypdf/_protocols.py +86 -0
  47. package/lib/vendor/pypdf/_reader.py +1604 -0
  48. package/lib/vendor/pypdf/_text_extraction/__init__.py +246 -0
  49. package/lib/vendor/pypdf/_text_extraction/_layout_mode/__init__.py +16 -0
  50. package/lib/vendor/pypdf/_text_extraction/_layout_mode/_fixed_width_page.py +447 -0
  51. package/lib/vendor/pypdf/_text_extraction/_layout_mode/_text_state_manager.py +203 -0
  52. package/lib/vendor/pypdf/_text_extraction/_layout_mode/_text_state_params.py +161 -0
  53. package/lib/vendor/pypdf/_text_extraction/_text_extractor.py +358 -0
  54. package/lib/vendor/pypdf/_utils.py +642 -0
  55. package/lib/vendor/pypdf/_version.py +1 -0
  56. package/lib/vendor/pypdf/_writer.py +3424 -0
  57. package/lib/vendor/pypdf/annotations/__init__.py +42 -0
  58. package/lib/vendor/pypdf/annotations/_base.py +29 -0
  59. package/lib/vendor/pypdf/annotations/_markup_annotations.py +351 -0
  60. package/lib/vendor/pypdf/annotations/_non_markup_annotations.py +106 -0
  61. package/lib/vendor/pypdf/constants.py +814 -0
  62. package/lib/vendor/pypdf/errors.py +74 -0
  63. package/lib/vendor/pypdf/filters.py +869 -0
  64. package/lib/vendor/pypdf/generic/__init__.py +115 -0
  65. package/lib/vendor/pypdf/generic/_appearance_stream.py +668 -0
  66. package/lib/vendor/pypdf/generic/_base.py +960 -0
  67. package/lib/vendor/pypdf/generic/_data_structures.py +1874 -0
  68. package/lib/vendor/pypdf/generic/_files.py +404 -0
  69. package/lib/vendor/pypdf/generic/_fit.py +174 -0
  70. package/lib/vendor/pypdf/generic/_image_inline.py +322 -0
  71. package/lib/vendor/pypdf/generic/_image_xobject.py +623 -0
  72. package/lib/vendor/pypdf/generic/_link.py +148 -0
  73. package/lib/vendor/pypdf/generic/_outline.py +33 -0
  74. package/lib/vendor/pypdf/generic/_rectangle.py +136 -0
  75. package/lib/vendor/pypdf/generic/_utils.py +215 -0
  76. package/lib/vendor/pypdf/generic/_viewerpref.py +164 -0
  77. package/lib/vendor/pypdf/pagerange.py +200 -0
  78. package/lib/vendor/pypdf/papersizes.py +52 -0
  79. package/lib/vendor/pypdf/py.typed +0 -0
  80. package/lib/vendor/pypdf/types.py +80 -0
  81. package/lib/vendor/pypdf/xmp.py +803 -0
  82. package/locale/en.json +6 -0
  83. package/locale/zh.json +6 -0
  84. package/package.json +70 -6
  85. package/resources/features.json +64 -0
  86. package/resources/layouts.json +233 -0
  87. package/resources/templates.json +320 -0
  88. package/resources/themes.json +36 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Office Forge Contributors
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.md CHANGED
@@ -1,3 +1,429 @@
1
- # Temporary Holding Version
1
+ # Office Forge
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Office document automation for DeepSeek Harness (DSH).**
4
+
5
+ Office Forge is a self-contained DSH bundle that gives an agent thirteen independent tools for working with Word, Excel, PowerPoint, and PDF files. It reads, creates, edits, audits, previews, converts, batch-processes, and templates documents without launching an Office UI. All document work runs in short-lived Python subprocesses; the Node layer only handles workspace authorization, argument validation, subprocess transport, and optional host integration.
6
+
7
+ The plugin is an independent implementation. It bundles no third-party office runtime and does not depend on any other document plugin.
8
+
9
+ ## Highlights
10
+
11
+ - **One toolkit for four formats** — `.docx`, `.xlsx`, `.pptx`, and `.pdf`.
12
+ - **File-level by default** — works on disk files without requiring Microsoft Office.
13
+ - **Optional real backends** — Microsoft Office COM and LibreOffice are used only when present.
14
+ - **Template-friendly** — `{{key}}` placeholders and one-level `{{#each items}}...{{/each}}` loops for Word tables and Excel rows.
15
+ - **Audit built in** — Word heading quality, Excel formula health/profile/insight/diff, PowerPoint deck quality and theme catalogues.
16
+ - **Agent-friendly** — every tool accepts and returns lossless JSON, reports stable error codes, and is safe to call from a conversation.
17
+ - **Workspace-safe** — lexical and host-level path checks, atomic writes, bounded input/output, no recursion.
18
+ - **Configurable** — module and feature switches for Word, Excel, PowerPoint, and PDF capabilities.
19
+ - **Diagnosable** — `officeforge_doctor` and a read-only plugin-page card report exactly which optional backends are available.
20
+
21
+ ## Requirements
22
+
23
+ | Component | Requirement |
24
+ |---|---|
25
+ | DSH | `>= 0.2.2-rc.5` |
26
+ | Node.js | `>= 20` |
27
+ | Python | Python 3.12 with `python-docx`, `openpyxl`, `python-pptx`; the DSH bundled runtime already includes these |
28
+ | PDF | `pypdf` is vendored inside the plugin; no external PDF service is required |
29
+ | Microsoft Office COM | Optional, Windows only, for native PivotTable, native SmartArt, revisions, PDF export, and legacy conversion |
30
+ | LibreOffice | Optional, for legacy `.doc/.xls/.ppt` conversion when COM is unavailable |
31
+ | OCR | Optional, requires PyMuPDF, pytesseract, and the Tesseract executable; `officeforge_doctor` reports missing pieces |
32
+
33
+ ## Installation
34
+
35
+ ### From a release tarball
36
+
37
+ ```bash
38
+ dsh plugin --profile <profile> add /path/to/dsh-office-forge-0.14.0.tgz
39
+ ```
40
+
41
+ Or add the package to the profile's dependencies and `dsh.profile.bundles` in the usual DSH way. The bundle exposes `dsh.bundle.patch`, `dsh.client`, locale files, and the icon required by the DSH plugin page.
42
+
43
+ ### From source
44
+
45
+ ```bash
46
+ git clone https://github.com/siyu0209/dsh-office-forge.git
47
+ cd dsh-office-forge
48
+ npm pack
49
+ ```
50
+
51
+ Then install the produced `dsh-office-forge-*.tgz` into the target profile. Installing from source requires Node and a Python runtime with the three Office libraries; `officeforge_doctor` tells you what is missing.
52
+
53
+ ### Verify the installation
54
+
55
+ After restarting DSH, call:
56
+
57
+ ```json
58
+ { "tool": "officeforge_doctor" }
59
+ ```
60
+
61
+ Expected result: `ok: true` when required pieces are present. Optional backends (OCR, LibreOffice) may show `warn`; they never block the core document tools.
62
+
63
+ ## Quick start
64
+
65
+ ### Create a Word document
66
+
67
+ ```json
68
+ {
69
+ "path": "reports/weekly.docx",
70
+ "type": "docx",
71
+ "spec": {
72
+ "title": "Weekly Report",
73
+ "subtitle": "Week 47",
74
+ "sections": [
75
+ { "heading": "Progress", "bullets": ["Finished module A", "Validated flow B"] },
76
+ { "heading": "Next week", "numbered": ["Fix C", "Ship D"] }
77
+ ],
78
+ "pageNumbers": true
79
+ }
80
+ }
81
+ ```
82
+
83
+ ### Create an Excel workbook
84
+
85
+ ```json
86
+ {
87
+ "path": "reports/metrics.xlsx",
88
+ "type": "xlsx",
89
+ "spec": {
90
+ "sheets": [
91
+ {
92
+ "name": "Metrics",
93
+ "columns": ["Month", "Revenue"],
94
+ "rows": [["Jan", 120], ["Feb", 180], ["Mar", 240]],
95
+ "freeze": "A2",
96
+ "autoFilter": true,
97
+ "charts": [
98
+ { "type": "bar", "dataRange": "B1:B4", "categoriesRange": "A2:A4", "anchor": "E2", "title": "Revenue" }
99
+ ]
100
+ }
101
+ ]
102
+ }
103
+ }
104
+ ```
105
+
106
+ ### Create a PowerPoint deck
107
+
108
+ ```json
109
+ {
110
+ "path": "decks/quarterly.pptx",
111
+ "type": "pptx",
112
+ "spec": {
113
+ "theme": "swiss",
114
+ "slides": [
115
+ { "layout": "cover", "title": "Quarterly Review", "subtitle": "FY2026" },
116
+ { "layout": "kpi", "title": "Highlights", "items": [
117
+ { "value": "42%", "label": "Growth" },
118
+ { "value": "18", "label": "New accounts" }
119
+ ] }
120
+ ]
121
+ }
122
+ }
123
+ ```
124
+
125
+ ### Fill a Word template
126
+
127
+ ```json
128
+ {
129
+ "template": "templates/people.docx",
130
+ "output": "out/people.docx",
131
+ "data": {
132
+ "title": "Team",
133
+ "people": [
134
+ { "name": "Alice", "dept": "Engineering" },
135
+ { "name": "Bob", "dept": "Product" }
136
+ ]
137
+ },
138
+ "options": { "expandLoops": true, "missing": "keep" }
139
+ }
140
+ ```
141
+
142
+ ### Audit a workbook
143
+
144
+ ```json
145
+ {
146
+ "path": "reports/metrics.xlsx",
147
+ "type": "xlsx",
148
+ "mode": "health"
149
+ }
150
+ ```
151
+
152
+ ### Merge PDFs
153
+
154
+ ```json
155
+ {
156
+ "operation": "merge",
157
+ "inputs": ["out/a.pdf", "out/b.pdf"],
158
+ "output": "out/merged.pdf"
159
+ }
160
+ ```
161
+
162
+ ## Tool reference
163
+
164
+ | Tool | What it does |
165
+ |---|---|
166
+ | `officeforge_read` | Read `.docx` / `.xlsx` / `.pptx` / `.pdf` in `content`, `outline`, or `search` mode; output markdown, text, or JSON. PDF supports text extraction and encryption passwords. |
167
+ | `officeforge_create` | Create a document from a declarative spec. Word supports sections, headings, bullets, numbered lists, tables, headers/footers, page setup, page numbers, TOC, images, hyperlinks, captions, styles, comments, revisions, mail merge, footnotes, bookmarks, cross-references, citations, bibliography, columns, watermarks, content controls, and `.dotx` templates. Excel supports sheets, CSV/TSV/JSON import, formulas, array formulas, charts (including combo charts), conditional formatting, data validation, comments, images, merged cells, tables, protection. PowerPoint supports slides, layouts, templates, themes, charts, images, tables, text boxes, shapes, connectors, transitions (including morph), animations, SmartArt-style diagrams, notes, sections, comments, media, and masters. |
168
+ | `officeforge_edit` | Apply bounded operations to an existing document. Word: replace, append, images, TOC, captions, styles, fields, comments, tracked revisions, mail merge, footnotes, bookmarks, cross-references, citations, bibliography, columns, watermark, content controls, templates, core properties. Excel: cells, rows, sheets, formats, freeze, filters, charts, conditional formatting, validations, comments, merges, images, formula columns, sorting, deduplication, blank filling, text cleanup, pivot summary, tables, protection. PowerPoint: text, slides, notes, sections, transitions, shapes, text boxes, connectors, animations, SmartArt-style diagrams, comments, media, masters, themes, core properties. |
169
+ | `officeforge_template` | Fill Word/Excel templates with JSON or `.json/.csv/.tsv` data: `{{key}}` placeholders and one-level `{{#each items}}...{{/each}}` loops. |
170
+ | `officeforge_audit` | Read-only audit. Word: `health` (heading jumps, duplicate/orphan headings, unresolved placeholders, long paragraphs, empty paragraph runs) and `profile`. Excel: `health` (formula errors, inconsistent patterns, hardcoded values in formula columns, blank-row breaks, circular references), `profile`, `insight`, `diff`. PowerPoint: `deck` quality, `profile`, `themes`, `layouts`, `templates`. |
171
+ | `officeforge_doctor` | Read-only runtime diagnostics: Python and Office libraries, bundled PDF engine, COM/pywin32, registered Office applications, LibreOffice, `officeKit`, client bundle, and active modules/features. Every check has `required`, `status`, `detail`, and `remedy`. |
172
+ | `officeforge_convert` | Convert legacy `.doc/.docm/.xls/.xlsm/.ppt/.pptm` through COM/LibreOffice; convert modern/PDF content through the host `officeKit`. |
173
+ | `officeforge_pdf` | File-level PDF operations: `merge`, `split`, `rotate`, `watermark`, `pageNumbers`, `formFields`, `fillForm`, `extractImages`, `ocr`, `encrypt`, `decrypt`. Uses vendored pypdf. |
174
+ | `officeforge_native` | Optional Microsoft Office COM operations: `convert`, `exportPdf`, `acceptRevisions`, `recalculate`, `pivot` (native PivotTable), `smartArt` (native SmartArt). |
175
+ | `officeforge_preview` | Render pages, slides, or worksheet ranges to PNG through `officeKit.renderImages`; no Office UI is launched. |
176
+ | `officeforge_recalculate` | Recalculate formulas through `officeKit.recalculate` and save a refreshed workbook. |
177
+ | `officeforge_batch` | Run up to 20 independent create/edit/template jobs in one Python call; each item succeeds or fails independently; nested batches are rejected. |
178
+ | `officeforge_export` | Convert through `officeKit` to PDF or another supported format; optionally copy the output back into the workspace. |
179
+
180
+ ## Configuration
181
+
182
+ All fields are optional. Every module and feature defaults to `true`, so an empty config enables the full toolkit.
183
+
184
+ | Field | Default | Description |
185
+ |---|---|---|
186
+ | `pythonPath` | auto-detect | Python executable with `python-docx`, `openpyxl`, `python-pptx` installed. |
187
+ | `engineTimeoutMs` | `120000` | Timeout for one Python engine call, in milliseconds. |
188
+ | `maxBatchItems` | `20` | Maximum items in one `officeforge_batch` call. |
189
+ | `enableExport` | `true` | Register `officeforge_export`. |
190
+ | `enableBatch` | `true` | Register `officeforge_batch`. |
191
+ | `enableBackends` | `true` | Register `officeforge_convert` / `officeforge_preview` / `officeforge_recalculate`; missing backends return explicit errors. |
192
+ | `modules` | all `true` | `word` / `excel` / `ppt` / `pdf` document-family switches. |
193
+ | `features` | all `true` | Fine-grained Word / Excel / PowerPoint capability switches. |
194
+
195
+ Example profile override:
196
+
197
+ ```yaml
198
+ - insert:
199
+ - id: dsh-office-forge
200
+ name: dsh-office-forge
201
+ config:
202
+ modules: { word: true, excel: true, ppt: true, pdf: true }
203
+ features:
204
+ word: { images: true, toc: true, comments: true }
205
+ excel: { charts: true, audit: true, import: true }
206
+ ppt: { themes: true, audit: true, layouts: true }
207
+ ```
208
+
209
+ Full feature names are defined in `resources/features.json`; theme presets are defined in `resources/themes.json`.
210
+
211
+ ### Python discovery order
212
+
213
+ 1. `pythonPath` from the bundle config
214
+ 2. `OFFICEFORGE_PYTHON`
215
+ 3. `DSH_PYTHON`
216
+ 4. `$DSH_HOME/dsh-runtimes/dsh-primary-runtime/dependencies/python/python.exe`
217
+ 5. `$DSH_HOME/dsh-runtimes/*/dependencies/python`
218
+ 6. `python3` / `python` on `PATH`
219
+
220
+ ## Architecture
221
+
222
+ ```
223
+ DSH host
224
+ └─ lib/index.js Node host layer
225
+ ├─ Config schema modules + features + runtime options
226
+ ├─ path policy ctx.fs.resolve / contains / processPath
227
+ ├─ runEngine() short-lived Python subprocess
228
+ │ └─ lib/office_engine.py
229
+ │ ├─ office_common.py paths, atomic writes, placeholders, feature gates
230
+ │ ├─ office_docx.py Word read/create/edit/template/audit
231
+ │ ├─ office_xlsx.py Excel read/create/edit/template/audit
232
+ │ ├─ office_pptx.py PowerPoint read/create/edit/template/audit
233
+ │ ├─ office_pdf.py PDF text extraction
234
+ │ ├─ office_pdf_tools.py PDF merge/split/rotate/watermark/forms/images/OCR/encryption
235
+ │ ├─ office_backends.py optional COM / LibreOffice backends
236
+ │ ├─ office_com_worker.py isolated COM worker
237
+ │ └─ office_migrations.py spec schema migration
238
+ ├─ officeKit bridge export / preview / recalculate
239
+ └─ lib/client.js read-only plugin-page status card + environment check
240
+ ```
241
+
242
+ The Node layer does four jobs: configuration trimming, workspace path policy, argument validation, and subprocess lifecycle. All document parsing and generation happen in Python. The Python engine is stateless between calls; each tool dispatches exactly one action.
243
+
244
+ ## Security and isolation
245
+
246
+ - **Workspace-only writes.** Every input and output path goes through both the host's `ctx.fs.resolve` / `ctx.fs.contains` checks and a lexical `PATH_OUTSIDE_WORKSPACE` guard.
247
+ - **Atomic writes.** New files are written to a same-directory temp file and `os.replace`d. Existing files are refused unless `overwrite: true`; optional backups are created next to the output.
248
+ - **Bounded execution.** 50 MiB input, 100 MiB output, 200,000 text characters, 5,000 × 300 Excel cells per sheet, 300 slides, 20 batch items.
249
+ - **No recursion.** Tools never call each other; each tool sends exactly one action to the engine; templates expand one loop level only; nested batches are rejected; table text replacement uses an explicit stack.
250
+ - **No host hooks.** The plugin injects only `tools`, `fs`, and `workingDirectory`; it does not register `systemPrompt`, LLM stream hooks, tool middleware, or host hooks.
251
+ - **No tool-name collisions.** Every tool starts with `officeforge_`; built-in `office_*` tools and `run_code` are untouched.
252
+ - **Per-tool isolation.** Tools are registered one by one; a failed registration logs a warning and never aborts activation of the rest of the plugin.
253
+ - **Lossless JSON.** All tool results are normalized so absent optional fields are omitted instead of leaking `undefined`, which the DSH host rejects as `value is not lossless JSON`.
254
+ - **Read-only plugin page.** The client bundle registers only `plugins.detail.section` with a read-only status card; it never writes configuration and never performs document work.
255
+
256
+ ## Error model
257
+
258
+ All failures return a stable JSON error object with `code`, `message`, and optional `detail`. Common codes include:
259
+
260
+ | Code | Meaning |
261
+ |---|---|
262
+ | `INPUT_NOT_FOUND` | Source file does not exist or is outside the workspace. |
263
+ | `PATH_OUTSIDE_WORKSPACE` | Path resolved outside the allowed workspace. |
264
+ | `UNSUPPORTED_FORMAT` | File extension cannot be handled by the requested tool. |
265
+ | `OUTPUT_EXISTS` | Target exists and `overwrite` was not requested. |
266
+ | `FEATURE_DISABLED` | The requested capability is disabled in `features`. |
267
+ | `BACKEND_UNAVAILABLE` | Optional COM/LibreOffice/OCR backend is not installed or not detected. |
268
+ | `SCHEMA_VERSION_UNSUPPORTED` | Spec uses a schema version newer than the engine supports. |
269
+ | `INVALID_PDF` / `PDF_PASSWORD_REQUIRED` / `PDF_PASSWORD_INVALID` | PDF is malformed, encrypted without a password, or has a wrong password. |
270
+ | `ENGINE_BAD_OUTPUT` | The Python engine returned a value that cannot be serialized losslessly. |
271
+
272
+ ## Testing and benchmarks
273
+
274
+ The repository ships ten test suites plus a benchmark suite. They use temporary directories and mock hosts; none starts DSH or writes to a profile.
275
+
276
+ | Suite | Purpose |
277
+ |---|---|
278
+ | `tests/test_engine.py` | End-to-end Python engine: all formats, templates, audit, PDF, native, batch, copy. |
279
+ | `tests/test_fuzz.py` | Malformed JSON, path escapes, unknown actions, nested batches, stable error codes. |
280
+ | `tests/test_com_cleanup.py` | Optional COM process reclamation test; skips without Office/pywin32. |
281
+ | `tests/test_plugin.mjs` | Node plugin layer with a mock host and mock `officeKit`. |
282
+ | `tests/test_plugin_config.mjs` | Module/feature normalization and type trimming. |
283
+ | `tests/test_compatibility.mjs` | Real host schema validation, tool-name collisions, isolation static checks. |
284
+ | `tests/test_client.mjs` | Client bundle manifest, lazy-CJS shape, slot registration. |
285
+ | `tests/test_client_host.mjs` | Drives the client bundle through the real `dsh-client-modules` client system. |
286
+ | `tests/test_dsh_profile.mjs` | One-shot install in an isolated `DSH_HOME`; verifies profile manifest and bundle declaration. |
287
+ | `tests/run_regression.py` | Runs every suite against `tests/regression_baseline.json`; `--quick` skips optional suites. |
288
+ | `benchmarks/run_benchmarks.py` | 12-case performance/robustness baseline; thresholds in `benchmarks/baseline.json`. |
289
+
290
+ ### Local verification
291
+
292
+ Set `PYTHON` to a Python 3.12 executable with `python-docx`, `openpyxl`, and `python-pptx` installed. If you use the DSH bundled runtime:
293
+
294
+ ```bash
295
+ export DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
296
+ export PYTHON="$DSH_HOME/dsh-runtimes/dsh-primary-runtime/dependencies/python/python.exe"
297
+ ```
298
+
299
+ Windows PowerShell:
300
+
301
+ ```powershell
302
+ $env:DSH_HOME = "$env:USERPROFILE\.dsh"
303
+ $env:PYTHON = "$env:DSH_HOME\dsh-runtimes\dsh-primary-runtime\dependencies\python\python.exe"
304
+ ```
305
+
306
+ Run everything:
307
+
308
+ ```bash
309
+ "$PYTHON" tests/run_regression.py
310
+ "$PYTHON" tests/run_regression.py --quick
311
+ ```
312
+
313
+ Run individual suites:
314
+
315
+ ```bash
316
+ "$PYTHON" tests/test_engine.py
317
+ "$PYTHON" tests/test_fuzz.py
318
+ "$PYTHON" tests/test_com_cleanup.py
319
+ node tests/test_plugin.mjs
320
+ node tests/test_plugin_config.mjs
321
+ node tests/test_compatibility.mjs
322
+ node tests/test_client.mjs
323
+ node tests/test_client_host.mjs
324
+ "$PYTHON" benchmarks/run_benchmarks.py
325
+ node tests/test_dsh_profile.mjs
326
+ ```
327
+
328
+ `tests/test_client_host.mjs` and `tests/test_dsh_profile.mjs` need a DSH installation. Point them at it with `DSH_APP_ROOT` (the directory containing `node_modules/@deepseek-ai/dsh`). They skip cleanly when the host is unavailable.
329
+
330
+ ## Compatibility and limitations
331
+
332
+ - **DSH**: tested against `0.2.2-rc.5`; package metadata declares `engines.dsh >= 0.2.2-rc.5`.
333
+ - **Node**: tested with Node 20+; the DSH host runs Node 26.
334
+ - **Python**: tested with CPython 3.12.14; `python-docx 1.2.0`, `openpyxl 3.1.5`, `python-pptx 1.0.2`.
335
+ - **Office COM**: Windows + Microsoft Office + pywin32 only. Without it, `officeforge_native` returns `BACKEND_UNAVAILABLE`; the core file-level tools still work.
336
+ - **LibreOffice**: optional; only used for legacy conversion when present.
337
+ - **OCR**: optional; requires PyMuPDF, pytesseract, and the Tesseract executable + language data.
338
+ - **Preview**: uses the host `officeKit.renderImages`; exact pixel sizes and font availability depend on the host and installed fonts.
339
+ - **Native features**: native PivotTable/PivotChart/Slicer and native SmartArt require COM; the file-level Python path provides pivot summaries and SmartArt-style editable shapes, not full native objects.
340
+ - **Word watermarks**: VML watermarks are visible in Word; some LibreOffice previews may not render them.
341
+ - **Macros**: macros are not executed; editing `.xlsm` preserves the VBA container where openpyxl supports it.
342
+
343
+ ## Troubleshooting
344
+
345
+ | Symptom | Check |
346
+ |---|---|
347
+ | `officeforge_doctor` says `BACKEND_UNAVAILABLE` | The optional backend is not installed. Core tools remain usable. |
348
+ | `INPUT_NOT_FOUND` for a relative path | Paths are resolved relative to the session workspace; use a path inside it. |
349
+ | `PATH_OUTSIDE_WORKSPACE` | The target escapes the workspace; write inside it or use an allowed host path. |
350
+ | `FEATURE_DISABLED` | A feature is turned off in `features`; enable it in the bundle config. |
351
+ | `value is not lossless JSON` | A tool returned an absent optional field; update to a version that normalizes results with `lossless()`. |
352
+ | Python import errors | Run `officeforge_doctor`; point `pythonPath` or `OFFICEFORGE_PYTHON` at a Python with `python-docx`, `openpyxl`, and `python-pptx`. |
353
+ | COM output fails | Verify Windows Office is installed, pywin32 is available, and no protected-view dialog blocks the file. |
354
+
355
+ ## Repository layout
356
+
357
+ ```
358
+ office-forge/
359
+ package.json # DSH bundle and npm metadata
360
+ cordis.patch.yml # inserts dsh-office-forge into a profile
361
+ icon.svg
362
+ locale/
363
+ zh.json
364
+ en.json
365
+ resources/
366
+ themes.json # 31 built-in theme presets
367
+ features.json # module/feature registry
368
+ layouts.json # 38 PowerPoint layout presets
369
+ templates.json # 10 deck templates
370
+ lib/
371
+ index.js # tool registration, path policy, Python transport, officeKit bridge
372
+ client.js # read-only plugin-page card and environment check
373
+ office_engine.py # JSON stdin/stdout engine entrypoint
374
+ office_common.py # paths, atomic writes, placeholders, validation
375
+ office_pdf.py # PDF text extraction
376
+ office_pdf_tools.py # PDF file operations
377
+ office_backends.py # optional COM / LibreOffice backends
378
+ office_com_worker.py # isolated COM worker
379
+ office_migrations.py # spec schema migration
380
+ office_docx.py # Word
381
+ office_xlsx.py # Excel
382
+ office_pptx.py # PowerPoint
383
+ vendor/pypdf/ # vendored pypdf runtime
384
+ benchmarks/
385
+ run_benchmarks.py
386
+ baseline.json
387
+ tests/
388
+ test_engine.py
389
+ test_fuzz.py
390
+ test_com_cleanup.py
391
+ test_plugin.mjs
392
+ test_plugin_config.mjs
393
+ test_compatibility.mjs
394
+ test_client.mjs
395
+ test_client_host.mjs
396
+ test_dsh_profile.mjs
397
+ run_regression.py
398
+ regression_baseline.json
399
+ docs/
400
+ DESIGN.md
401
+ COMPATIBILITY.md
402
+ COMPATIBILITY-MATRIX.md
403
+ COVERAGE.md
404
+ CHANGELOG.md
405
+ BENCHMARKS.md
406
+ README.md
407
+ README.zh.md
408
+ LICENSE
409
+ ```
410
+
411
+ ## Development
412
+
413
+ The plugin is plain ESM + Python 3.12; there is no build step.
414
+
415
+ ```bash
416
+ git clone https://github.com/siyu0209/dsh-office-forge.git
417
+ cd dsh-office-forge
418
+ npm install --ignore-scripts
419
+ ```
420
+
421
+ Run the verification commands in the table above before opening a pull request. Keep feature changes covered by `tests/test_engine.py` and update `tests/regression_baseline.json` only when the new assertion floor is intentional.
422
+
423
+ ## Versioning
424
+
425
+ Semantic versioning: patch versions fix bugs and compatibility; minor versions add capabilities; major versions may change document spec semantics. `docs/CHANGELOG.md` records every release and the migration rules.
426
+
427
+ ## License
428
+
429
+ MIT. See [LICENSE](LICENSE).