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.
- package/LICENSE +21 -0
- package/README.md +428 -2
- package/README.zh.md +429 -0
- package/benchmarks/baseline.json +52 -0
- package/benchmarks/run_benchmarks.py +261 -0
- package/cordis.patch.yml +7 -0
- package/docs/BENCHMARKS.md +44 -0
- package/docs/CHANGELOG.md +174 -0
- package/docs/COMPATIBILITY-MATRIX.md +23 -0
- package/docs/COMPATIBILITY.md +63 -0
- package/docs/COVERAGE.md +47 -0
- package/docs/DESIGN.md +128 -0
- package/icon.svg +12 -0
- package/lib/client.js +49 -0
- package/lib/index.js +1382 -0
- package/lib/office_backends.py +360 -0
- package/lib/office_com_worker.py +395 -0
- package/lib/office_common.py +410 -0
- package/lib/office_docx.py +1628 -0
- package/lib/office_engine.py +403 -0
- package/lib/office_migrations.py +52 -0
- package/lib/office_pdf.py +217 -0
- package/lib/office_pdf_tools.py +455 -0
- package/lib/office_pptx.py +1474 -0
- package/lib/office_xlsx.py +1685 -0
- package/lib/vendor/pypdf/__init__.py +48 -0
- package/lib/vendor/pypdf/_cmap.py +375 -0
- package/lib/vendor/pypdf/_codecs/__init__.py +55 -0
- package/lib/vendor/pypdf/_codecs/_codecs.py +284 -0
- package/lib/vendor/pypdf/_codecs/adobe_glyphs.py +13969 -0
- package/lib/vendor/pypdf/_codecs/core_font_metrics.py +4483 -0
- package/lib/vendor/pypdf/_codecs/pdfdoc.py +264 -0
- package/lib/vendor/pypdf/_codecs/std.py +258 -0
- package/lib/vendor/pypdf/_codecs/symbol.py +260 -0
- package/lib/vendor/pypdf/_codecs/zapfding.py +261 -0
- package/lib/vendor/pypdf/_crypt_providers/__init__.py +80 -0
- package/lib/vendor/pypdf/_crypt_providers/_base.py +38 -0
- package/lib/vendor/pypdf/_crypt_providers/_cryptography.py +132 -0
- package/lib/vendor/pypdf/_crypt_providers/_fallback.py +93 -0
- package/lib/vendor/pypdf/_crypt_providers/_pycryptodome.py +110 -0
- package/lib/vendor/pypdf/_doc_common.py +1505 -0
- package/lib/vendor/pypdf/_encryption.py +1305 -0
- package/lib/vendor/pypdf/_font.py +722 -0
- package/lib/vendor/pypdf/_page.py +2492 -0
- package/lib/vendor/pypdf/_page_labels.py +321 -0
- package/lib/vendor/pypdf/_protocols.py +86 -0
- package/lib/vendor/pypdf/_reader.py +1604 -0
- package/lib/vendor/pypdf/_text_extraction/__init__.py +246 -0
- package/lib/vendor/pypdf/_text_extraction/_layout_mode/__init__.py +16 -0
- package/lib/vendor/pypdf/_text_extraction/_layout_mode/_fixed_width_page.py +447 -0
- package/lib/vendor/pypdf/_text_extraction/_layout_mode/_text_state_manager.py +203 -0
- package/lib/vendor/pypdf/_text_extraction/_layout_mode/_text_state_params.py +161 -0
- package/lib/vendor/pypdf/_text_extraction/_text_extractor.py +358 -0
- package/lib/vendor/pypdf/_utils.py +642 -0
- package/lib/vendor/pypdf/_version.py +1 -0
- package/lib/vendor/pypdf/_writer.py +3424 -0
- package/lib/vendor/pypdf/annotations/__init__.py +42 -0
- package/lib/vendor/pypdf/annotations/_base.py +29 -0
- package/lib/vendor/pypdf/annotations/_markup_annotations.py +351 -0
- package/lib/vendor/pypdf/annotations/_non_markup_annotations.py +106 -0
- package/lib/vendor/pypdf/constants.py +814 -0
- package/lib/vendor/pypdf/errors.py +74 -0
- package/lib/vendor/pypdf/filters.py +869 -0
- package/lib/vendor/pypdf/generic/__init__.py +115 -0
- package/lib/vendor/pypdf/generic/_appearance_stream.py +668 -0
- package/lib/vendor/pypdf/generic/_base.py +960 -0
- package/lib/vendor/pypdf/generic/_data_structures.py +1874 -0
- package/lib/vendor/pypdf/generic/_files.py +404 -0
- package/lib/vendor/pypdf/generic/_fit.py +174 -0
- package/lib/vendor/pypdf/generic/_image_inline.py +322 -0
- package/lib/vendor/pypdf/generic/_image_xobject.py +623 -0
- package/lib/vendor/pypdf/generic/_link.py +148 -0
- package/lib/vendor/pypdf/generic/_outline.py +33 -0
- package/lib/vendor/pypdf/generic/_rectangle.py +136 -0
- package/lib/vendor/pypdf/generic/_utils.py +215 -0
- package/lib/vendor/pypdf/generic/_viewerpref.py +164 -0
- package/lib/vendor/pypdf/pagerange.py +200 -0
- package/lib/vendor/pypdf/papersizes.py +52 -0
- package/lib/vendor/pypdf/py.typed +0 -0
- package/lib/vendor/pypdf/types.py +80 -0
- package/lib/vendor/pypdf/xmp.py +803 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +70 -6
- package/resources/features.json +64 -0
- package/resources/layouts.json +233 -0
- package/resources/templates.json +320 -0
- 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
|
-
#
|
|
1
|
+
# Office Forge
|
|
2
2
|
|
|
3
|
-
|
|
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).
|