dsh-office-tools 0.2.0 → 1.0.2

package/README.md

@@ -1,31 +1,54 @@
 # dsh-office-tools
 
-Seven model-facing Office file tools for DeepSeek Harness, running entirely in the plugin host half.
+Eight model-facing Office file tools for DeepSeek Harness, running entirely in the plugin host half.
 
 [![npm version](https://img.shields.io/npm/v/dsh-office-tools)](https://www.npmjs.com/package/dsh-office-tools) [![ci](https://github.com/kw78/dsh-office-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/kw78/dsh-office-tools/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Listed on awesome-dsh-plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
 > Install: `dsh plugin --profile web add github:kw78/dsh-office-tools`
 
-| Tool | Purpose | Library |
-|---|---|---|
-| `word_create` | Create `.docx` (title, paragraphs, bullets, one table) | `docx` |
-| `word_read` | Extract plain text from `.docx` | `mammoth` |
-| `excel_create` | Create a multi-sheet `.xlsx` from scalar cell grids | SheetJS (`xlsx`) |
-| `excel_read` | Read one or all sheets as scalar rows | SheetJS |
-| `excel_update` | Replace/create whole sheets, or write cells by A1 address | SheetJS |
-| `ppt_create` | Create a 16:9 `.pptx` (title slide, titles, paragraphs, bullets, notes, PNG/JPG/GIF images) | `pptxgenjs` |
-| `ppt_read` | Extract per-slide paragraph text, speaker notes, and image counts | `jszip` |
+> DSH Store lists a fixed Commit; verify the installed source against it: `ae1ddd40f98debf4b1430748d287951f35faaf36` (tag `v1.0.0`). Later commits on `main` carry test/doc additions only unless the version bumps.
+
+Eight model-facing Office file tools for DeepSeek Harness, running entirely in the plugin host half — dependency-free since 1.0.0: every package is generated and parsed by this plugin's own OOXML engine, and every byte crosses the official DSH filesystem service (`ctx.fs`), never the raw file system.
+
+| Tool | Purpose |
+|---|---|
+| `word_create` | Create `.docx` (title, paragraphs, bullets, one table) |
+| `word_read` | Extract text from any `.docx`; `format: "markdown"` renders headings, lists, and tables structurally |
+| `word_update` | Append paragraphs, bullets, and/or a table to an existing `.docx` |
+| `excel_create` | Create a multi-sheet `.xlsx` from scalar cell grids |
+| `excel_read` | Read one or all sheets as scalar rows; formulas return cached values or `'=…'` strings |
+| `excel_update` | Replace/create whole sheets, or write cells by A1 address |
+| `ppt_create` | Create a 16:9 `.pptx` (title slide, titles, paragraphs, bullets, notes, linked PNG/JPG/GIF images) and echo every element's landing position |
+| `ppt_read` | Extract per-slide paragraphs, tables, speaker notes, image counts, alt texts — plus every shape's bounding box in inches and a text wireframe sketch |
+
+String cells starting with `=` are written as real Excel formulas (Excel computes them on open).
+
+## Demo
+
+One prompt, a quarterly-report trio — Word with a metrics table, Excel with `=SUM`/variance formulas, PowerPoint with speaker notes:
+
+<img src="docs/demo/session.svg" alt="One prompt generating report.docx, budget.xlsx, and deck.pptx" width="780">
+
+The prompt behind that session:
+
+> Generate the Q3 quarterly-report trio: `report.docx` (title, two summary paragraphs, three highlights, a metrics table), `budget.xlsx` (a Budget sheet with `=SUM` totals and plan-vs-actual variance formulas, plus a Summary sheet), and `deck.pptx` (title slide + three content slides with speaker notes).
+
+The model turns it into `word_create` → `excel_create` → `ppt_create` (reads come back through `word_read` / `excel_read` / `ppt_read`; freshly written formulas read back as `'=…'` strings until Excel caches values). The whole flow is pinned by `tests/demo-trio.spec.ts`, so the demo cannot drift from the tools. The file sizes in the image come from a real run of that test scenario.
 
 ## Harness integration
 
 The plugin follows the standard DSH host-plugin contract:
 
-- It exports `name` / `inject` / `apply` / `Config`; `inject = ['tools']` is its only runtime service dependency (`@deepseek-ai/dsh-tools`).
+- It exports `name` / `inject` / `apply` / `Config`; `inject = ['tools', 'fs']` — the official tool registry and the official filesystem service (`@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-fs`) are its only runtime service dependencies.
 - `apply(ctx)` wraps every `ctx.tools.register(defineTool({...}))` in `ctx.effect(...)` so Cordis disposes the registrations with the plugin fiber.
 - `defineTool` declares model-visible `parameters`, a validated canonical `output.schema`, and a pure `output.render` text projection.
-- `execute(args, exec)` resolves every path against `exec.agent.session.header.cwd`; relative paths stay in the session workspace and absolute paths are accepted only when still inside it. A `realpath` check on the nearest existing ancestor closes the symlink escape hatch.
-- Image files must live inside the session workspace (`.png/.jpg/.jpeg/.gif`, 20 MiB each); explicit inch coordinates `x/y/w/h` are supported, or omit them for automatic placement below the text.
-- Writes go through a same-directory temp file + `rename`; `overwrite` defaults to `false`.
+- `execute(args, exec)` resolves every path against `exec.agent.session.header.cwd`; relative paths stay in the session workspace and absolute paths are accepted only when still inside it. Containment and symlink resolution are enforced by the `ctx.fs` backend (plus a lexical pre-check here).
+- All reads arrive as raw bytes via `ctx.fs.readBytes`; all writes leave as UTF-8 text via `ctx.fs.writeText` — published atomically by the backend; `overwrite` defaults to `false`.
+- Generated packages are pure ASCII by construction (an ASCII-safe STORE zip planner pads each XML part and aligns offsets so every CRC/size/offset field stays byte-safe), which is exactly what lets real `.docx`/`.xlsx`/`.pptx` files travel through the text channel byte-identically. Non-ASCII text encodes as XML character references; every Office suite opens the result.
+- Reads accept any real-world package (STORE and DEFLATE entries, bounded by the zip-bomb guard).
+- `word_update` / `excel_update` re-publish through the text channel, so they work on packages whose every part is text (always true for files these tools write, and for OOXML packages without binary media); packages carrying binary media are refused with a clear error instead of being corrupted.
+- Images are LINKED, not embedded: the model controls placement fully (`x/y/w/h` inches, `contain`/`cover` cropping, alt text; PNG/JPG/GIF headers are sniffed so omitted dimensions default to natural size), and the deck references the workspace image file. Keep the image files next to the deck when moving it — that is the trade-off of a dependency-free, binary-free package.
+- `ppt_create` echoes the full layout (every element's box in inches + the canvas size + a text wireframe sketch per slide); `ppt_read` returns the same geometry for any deck, so the model can see and re-author compositions.
 
 ## Build
 
@@ -34,7 +57,7 @@ pnpm install
 pnpm run check   # typecheck + tests + build
 ```
 
-Artifacts: `lib/index.js` (ESM host bundle with Office libraries inlined; `@deepseek-ai/*` and `cordis` stay external) and `lib/types/**/*.d.ts`.
+Artifacts: `lib/index.js` (ESM host bundle of this plugin's own code only — ~116 kB, zero runtime dependencies) and `lib/types/**/*.d.ts`. Every `@deepseek-ai/*` package (cordis, the dsh services, schemastery) stays external and is provided by the profile's node_modules.
 
 ## Install
 
@@ -49,7 +72,7 @@ dsh plugin --profile web add github:kw78/dsh-office-tools
 dsh plugin --profile web add /path/to/dsh-office-tools
 ```
 
-Restart the DSH server after installation. The seven tools appear in the next prompt assembly.
+Restart the DSH server after installation. The eight tools appear in the next prompt assembly. Since 1.0.0 the plugin has zero runtime dependencies — no npm fetch, no CDN, no postinstall scripts; installation is the committed source, nothing else. The host must provide the `fs` service (every DSH profile that ships the built-in read/write tools does).
 
 ## Configuration
 
@@ -77,7 +100,9 @@ The plugin declares a schemastery `Config` the Loader validates at load time. On
 ## Safety
 
 - All file access is confined to the calling agent's session workspace.
-- Reads are capped at 50 MiB; text/cell results are bounded and mark `truncated`.
+- Reads are capped at 50 MiB compressed; before anything is inflated, the archive's own declared sizes are checked against budgets (256 MiB per entry, 512 MiB per archive, 100 000 entries), so zip bombs are refused rather than decompressed. XML parts carrying DOCTYPE/ENTITY declarations are refused outright.
+- Text/cell results are bounded and mark `truncated`.
 - Creates/updates are bounded by row and cell limits and refuse overwrites by default.
-- No LibreOffice/PowerPoint/Word subprocess is spawned; formats are generated and parsed with pure-JS libraries.
-- SheetJS is pinned to the 0.20.3 tarball from the official CDN (<https://cdn.sheetjs.com>): npm stopped at 0.18.5, which carries CVE-2023-30533 (prototype pollution) and CVE-2024-22363 (ReDoS). The library is inlined into `lib/index.js` at build time and never resolved at runtime, so installs of the published plugin do not touch the CDN.
+- No LibreOffice/PowerPoint/Word subprocess is spawned and no third-party library is shipped: formats are generated and parsed by this plugin's own ASCII-safe OOXML engine over `node:zlib`.
+- The plugin's own code never touches the file system directly — there is no `node:fs` import anywhere in `src/`; every byte flows through the official, user-visible `ctx.fs` service. This is what lets third-party store automation verify the whole runtime source deterministically (DSH Store issue #334: 1.0.0 passes the complete automatic low-risk policy — zero runtime dependencies, zero file/network/commands/credentials signals, bounded source, exact per-release compatibility declarations).
+- Roadmap: [docs/ROADMAP.md](docs/ROADMAP.md).

package/README.zh.md

@@ -1,31 +1,50 @@
 # dsh-office-tools
 
-为 DeepSeek Harness 提供 7 个模型可调用的 Office 文件工具，全部运行在 host 半。
-
 [![npm version](https://img.shields.io/npm/v/dsh-office-tools)](https://www.npmjs.com/package/dsh-office-tools) [![ci](https://github.com/kw78/dsh-office-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/kw78/dsh-office-tools/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![已收录于 awesome-dsh-plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
 > 安装：`dsh plugin --profile web add github:kw78/dsh-office-tools`
 
-| 工具 | 作用 | 依赖 |
-|---|---|---|
-| `word_create` | 创建 `.docx`（标题、段落、项目符号、一个表格） | `docx` |
-| `word_read` | 提取 `.docx` 纯文本 | `mammoth` |
-| `excel_create` | 创建多 sheet 的 `.xlsx`（标量单元格网格） | SheetJS (`xlsx`) |
-| `excel_read` | 读取一个或全部 sheet，返回标量行 | SheetJS |
-| `excel_update` | 就地替换/新建整张 sheet，或按 A1 地址写单元格 | SheetJS |
-| `ppt_create` | 创建 16:9 `.pptx`（标题页、标题、段落、项目符号、备注、PNG/JPG/GIF 图片） | `pptxgenjs` |
-| `ppt_read` | 按页提取 `.pptx` 段落文本、演讲者备注与图片数量 | `jszip` |
+> DSH Store 固定 Commit 校验源：`ae1ddd40f98debf4b1430748d287951f35faaf36`（tag `v1.0.0`）。其后的 `main` 提交仅为测试/文档补充，除非版本号提升。
+
+为 DeepSeek Harness 提供 8 个模型可调用的 Office 文件工具，全部运行在 host 半 —— 1.0.0 起零运行时依赖：所有文件由插件自带的 OOXML 引擎生成与解析，所有字节都经由官方文件服务 `ctx.fs` 传输，插件自身不直接触碰文件系统。
+
+| 工具 | 作用 |
+|---|---|
+| `word_create` | 创建 `.docx`（标题、段落、项目符号、一个表格） |
+| `word_read` | 提取任意 `.docx` 的文本；`format: "markdown"` 结构化渲染标题/列表/表格 |
+| `word_update` | 向现有 `.docx` 追加段落、项目符号和/或一个表格 |
+| `excel_create` | 创建多 sheet 的 `.xlsx`（标量单元格网格） |
+| `excel_read` | 读取一个或全部 sheet 为标量行；公式返回缓存值或 `'=…'` 公式串 |
+| `excel_update` | 就地替换/新建整张 sheet，或按 A1 地址写单元格 |
+| `ppt_create` | 创建 16:9 `.pptx`（标题页、标题、段落、项目符号、备注、链接式 PNG/JPG/GIF 图片），并回显每个元素的落点坐标 |
+| `ppt_read` | 按页提取段落、表格、演讲者备注、图片数量、alt 文本 —— 外加每个形状的英寸包围盒与文本线框图 |
+
+以 `=` 开头的字符串单元格会写成真正的 Excel 公式（Excel 打开时计算）。
+
+## 演示
+
+一句话，季度报告三件套 —— 带指标表的 Word、带 `=SUM`/差异公式的 Excel、带演讲者备注的 PowerPoint：
+
+<img src="docs/demo/session.svg" alt="一句话生成 report.docx、budget.xlsx、deck.pptx" width="780">
+
+上图会话用的提示词：
+
+> 生成 Q3 季度报告三件套：`report.docx`（标题、两段摘要、三个要点、一张指标表）、`budget.xlsx`（Budget sheet 含 `=SUM` 合计与计划/实际差异公式，再加一个 Summary sheet）、`deck.pptx`（标题页 + 3 页正文，含演讲者备注）。
+
+模型会把它拆成 `word_create` → `excel_create` → `ppt_create`（回读走 `word_read` / `excel_read` / `ppt_read`；新写入的公式在被 Excel 计算缓存前以 `'=…'` 串回读）。整个流程由 `tests/demo-trio.spec.ts` 钉死，演示不会与工具行为漂移；图中的体积数字来自该测试场景的一次真实运行。
 
 ## 框架接入方式
 
 插件遵循 DSH 标准 host 插件契约：
 
-- 模块导出 `name` / `inject` / `apply` / `Config`；本插件 `inject = ['tools']`，唯一运行时依赖是 `ctx.tools`（`@deepseek-ai/dsh-tools`）。
+- 模块导出 `name` / `inject` / `apply` / `Config`；本插件 `inject = ['tools', 'fs']`——官方工具注册表与官方文件服务（`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-fs`）是仅有的运行时服务依赖。
 - `apply(ctx)` 中用 `ctx.effect(() => ...)` 包裹 `ctx.tools.register(defineTool({...}))`，Cordis fiber 卸载时自动 dispose。
 - `defineTool` 统一声明 `parameters`（模型可见 JSON Schema）、`output.schema`（强制校验的规范 JSON 值）与 `output.render`（模型看到的文本投影）。
-- 每个 `execute(args, exec)` 从 `exec.agent.session.header.cwd` 取会话工作目录；相对路径按该目录解析，绝对路径只接受仍位于工作目录内的路径，并对最近存在的祖先做 `realpath` 校验防止符号链接逃逸。
-- 图片文件必须位于会话工作目录内（`.png/.jpg/.jpeg/.gif`，单张上限 20 MiB）；可显式指定英寸坐标 `x/y/w/h`，省略时自动放在文本下方。
-- 写文件采用同目录临时文件 + `rename` 原子落盘；`overwrite` 默认 `false`，防止误覆盖。
+- 每个 `execute(args, exec)` 从 `exec.agent.session.header.cwd` 取会话工作目录；相对路径按该目录解析，绝对路径只接受仍位于工作目录内的路径。containment 与符号链接解析由 `ctx.fs` 后端权威执行（本插件再做一道词法预检）。
+- 读经 `ctx.fs.readBytes` 以原始字节到达；写经 `ctx.fs.writeText` 以 UTF-8 文本离开（后端原子落盘）；`overwrite` 默认 `false`，防止误覆盖。
+- 生成的包是纯 ASCII 的 STORE 型 zip：规划器为每个 XML 部件做尾部换行填充并做 1 KiB 槽位对齐（跳过每 64 KiB 页的不安全偏移带），使 CRC/大小/偏移字段全部字节安全——这正是真实 Office 文件能以字节一致方式通过官方文本通道的原因。非 ASCII 文本编码为 XML 字符引用。
+- 读取接受任意真实包（STORE/DEFLATE，含 zip 炸弹防御）；`word_update`/`excel_update` 适用于全文本部件的包，携带二进制媒体的包会被明确拒绝。
+- 图片为链接式：模型完全掌控摆放（x/y/w/h 英寸、contain/cover、alt；PNG/JPG/GIF 头部嗅探出原图尺寸），deck 引用 workspace 图片文件；`ppt_create` 结果回显全部元素落点（英寸坐标 + 画布尺寸 + 每页文本线框图），`ppt_read` 对任意 deck 返回同样的几何信息。
 
 ## 构建
 
@@ -34,7 +53,7 @@ pnpm install
 pnpm run check   # typecheck + tests + build
 ```
 
-构建产物：`lib/index.js`（host ESM，Office 依赖内联，`@deepseek-ai/*`/`cordis` 保持 external）与 `lib/types/**/*.d.ts`。
+构建产物：`lib/index.js`（ESM host bundle，仅打包本插件自有代码——约 116 kB，零运行时依赖）与 `lib/types/**/*.d.ts`；所有 `@deepseek-ai/*`（cordis、dsh 服务、schemastery）保持 external，由 profile 的 node_modules 提供。
 
 ## 安装
 
@@ -49,7 +68,7 @@ dsh plugin --profile web add github:kw78/dsh-office-tools
 dsh plugin --profile web add /path/to/dsh-office-tools
 ```
 
-安装后重启 DSH 服务。模型下一次组装提示词时即可看到 7 个工具。
+安装后重启 DSH 服务。模型下一次组装提示词时即可看到 8 个工具。1.0.0 起插件零运行时依赖——不联网、不拉 CDN、无安装脚本，安装即固定源码本身。宿主需提供 `fs` 服务（凡是带内置 read/write 工具的 DSH profile 都有）。
 
 ## 配置
 
@@ -77,7 +96,12 @@ dsh plugin --profile web add /path/to/dsh-office-tools
 ## 安全边界
 
 - 所有读写都限制在发起调用的 agent 的会话工作目录内。
-- 读取文件上限 50 MiB，文本/单元格结果有上限并标记 `truncated`。
+- 读取文件上限 50 MiB（压缩后体积）；解压前先校验压缩包自身声明的大小预算（单条目 ≤256 MiB、整包 ≤512 MiB、条目数 ≤100 000），zip 炸弹会被直接拒绝而不是解压；携带 DOCTYPE/ENTITY 声明的 XML 部件一律拒绝。
+- 文本/单元格结果有上限并标记 `truncated`。
 - 创建/更新有行数、单元格数上限，且默认不覆盖已有文件。
 - 不调用 LibreOffice / PowerPoint / Word 等外部进程，所有格式均通过纯 JS 库生成/解析。
-- SheetJS 固定为官方 CDN（<https://cdn.sheetjs.com>）的 0.20.3 tarball：npm 停留在 0.18.5，该版本携带 CVE-2023-30533（原型污染）与 CVE-2024-22363（ReDoS）。该库在构建时内联进 `lib/index.js`、运行时从不解析，因此安装已发布的插件不需要访问 CDN。
+- 插件自身代码零文件系统直接访问——`src/` 中没有任何 `node:fs` 导入，所有字节经官方、用户可见的 `ctx.fs` 服务流动。这让第三方商店自动化可以确定性核验全部运行时源码（DSH Store #334：1.0.0 通过完整的自动低风险策略——零运行时依赖、零文件/网络/命令/凭据信号、有界源码、逐版本精确兼容声明）。
+- 生成的包是纯 ASCII 的 STORE 型 zip（规划器为每个 XML 部件做尾部填充并做槽位对齐，让 CRC/大小/偏移字段全部字节安全），因此能以字节一致的方式通过官方 UTF-8 文本通道落盘；非 ASCII 文本编码为 XML 字符引用，各 Office 套件均可正常打开。
+- `word_update`/`excel_update` 经文本通道重发布：适用于全部部件均为文本的包（本插件生成的文件必然满足；不含二进制媒体的 OOXML 包也满足），携带二进制媒体（内嵌图片/字体）的包会被明确拒绝而非损坏。
+- 图片为链接式（非内嵌）：模型完全掌控摆放（英寸坐标 x/y/w/h、contain/cover 裁剪、alt 文本；PNG/JPG/GIF 文件头会被嗅探，省略尺寸时按原图大小），deck 引用 workspace 中的图片文件——移动 deck 时请连同图片文件，这是零二进制包的取舍。
+- 版本路线见 [docs/ROADMAP.md](docs/ROADMAP.md)。

package/dsh.plugin.json

@@ -1,15 +1,16 @@
 {
   "id": "dsh-office-tools",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "main": "lib/index.js",
-  "description": "Office tools for the model: create, read, and update Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files inside the session workspace.",
+  "description": "Office tools for the model: create, read, and update Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files inside the session workspace through the official DSH filesystem service.",
   "engines": {
-    "dsh": ">=0.0.1"
+    "dsh": ">=0.1.0-rc.6"
   },
   "contributes": {
     "tools": [
       "word_create",
       "word_read",
+      "word_update",
       "excel_create",
       "excel_read",
       "excel_update",