dsh-office-kit 0.1.0 → 0.3.0

package/CAPABILITY.md

@@ -1,75 +1,154 @@
 # Capability report
 
-This file records what the plugin actually does, how each capability maps from the original skills, what was verified, and what remains unsupported. It is intentionally conservative: a feature is listed as supported only after a working command path and a check exist.
-
-## Capability trace
-
-| User capability | Original mechanism | DSH execution chain | Acceptance | State |
-| --- | --- | --- | --- | --- |
-| Create a DOCX report | `documents` skill; Python OOXML scripts; `mark_artifact_operation_started.mjs` | `/documents` chip → `office-documents` skill → `office_status` → `office_cli.py docx create/edit` (python-docx, OMML) → Word/LibreOffice render → PNG inspection | Create with headings, lists, table, image, equation, header/footer; read back counts; edit text and append section; equation survives; rendered page inspected | Supported |
-| Read a DOCX | Same skill | `docx read` → JSON counts/text/tables/images | Counts and text match the created document | Supported |
-| Create a PDF | `pdf` skill; reportlab/pdfplumber/pypdf | `/pdf` chip → `office-pdf` skill → `office_cli.py pdf create/read/edit/render` | Chinese text embeds with registered CJK font; read extracts text; metadata edit; PyMuPDF render inspected | Supported |
-| Inspect a PDF | Same | `pdf read` → page count, text, metadata, form fields | Page count and Chinese/English text extracted | Supported |
-| Edit a PDF | Same | `pdf edit` → metadata, rotate, merge, remove pages | Metadata edit and read-back verified | Supported |
-| Create/edit a PPTX | `presentations` skill; `@oai/artifact-tool` | `/presentations` chip → `office-presentations` skill → `office_cli.py pptx create/edit` (python-pptx) → PowerPoint/LibreOffice render | Three slides with bullets, table, chart, image; edit text and append a slide; four rendered pages inspected; layout overlap fixed with explicit coordinates | Supported, with a different authoring engine than the original |
-| Create/edit an XLSX | `spreadsheets` skill; `@oai/artifact-tool` | `/spreadsheets` chip → `office-spreadsheets` skill → `office_cli.py xlsx create/edit/recalc` (openpyxl + Excel COM) | Formulas, styles, widths, frozen panes, chart; edit cells/append rows; Excel recalculation persists cached values (`40`, `58`, `228`); data-only read confirms | Supported, with a different authoring engine than the original |
-| Render for visual QA | Original render helpers / artifact tool | `render` → Microsoft Office COM (Word/PowerPoint/Excel) or LibreOffice headless; PyMuPDF for PDF | DOCX page, PPTX pages, PDF page rendered and inspected | Supported when a renderer exists; explicit error otherwise |
-| `/` menu with names and icons | Original skill menu (not `InputTrigger`) | Public `ctx.inputTriggers` source named `office`; four candidates with Gravity UI Icons SVGs and locale labels | Typecheck/build; not yet exercised in a running DSH window | Implemented, GUI interaction unverified |
-| Enter → reference chip | Original artifact reference | `onPick` returns `ReferenceInsert`; host `codec` persists `/documents` and serializes a skill instruction | Build/typecheck; chip persistence is the documented public contract, not live-tested | Implemented, GUI interaction unverified |
-| Chip preview | Original skill preview | `openReference` maps feature id → skill name → `SKILL.md` path → `sidebarRight.openResource` | Code path implemented; GUI unverified | Implemented, GUI unverified |
-| Python setup | Original bundled runtime | `postinstall.mjs` detect/download/verify/install/venv/pip/import check/config/PATH | Auto-install path not run (a working Python already existed); venv creation, dependency install, import verification, config write, idempotent rerun all verified | Supported; installer download path unverified in this environment |
-
-## Dependency mapping
-
-| Original dependency | DSH replacement | Notes |
-| --- | --- | --- |
-| `load_workspace_dependencies` | `office_status` + absolute paths embedded in each skill body | No hidden workspace loader; the host verifies the interpreter and packages. |
-| `mark_artifact_operation_started.mjs` | None | It only marked artifact sessions in the original runtime; DSH has no equivalent and the CLI does not pretend to. |
-| `@oai/artifact-tool` (PPTX/XLSX) | `python-pptx`, `openpyxl` | Different API and some different capabilities; see limits. |
-| Google Drive/Slides/Sheets plugins | None | Remote editing is explicitly unsupported, not silently replaced by local files. |
-| Original render helpers | Microsoft Office COM or LibreOffice headless; PyMuPDF | Renderer availability is reported by `office_status`. |
-| Original `agents/openai.yaml` manifests | DSH skill frontmatter + `ctx.skills.registerProvider` | The four DSH skills live in `assets/skills`. |
-
-## Python and renderer environment
-
-- Python: 3.12.12 in `%LOCALAPPDATA%\dsh-office-kit\venv`, created by `postinstall.mjs` from an existing CPython 3.12.12.
-- Installed and import-verified: python-docx 1.2.0, openpyxl 3.1.5, python-pptx 1.0.2, pypdf 6.21.1, reportlab 4.5.1, pdfplumber 0.11.9, PyMuPDF 1.28.2, Pillow 11.3.0, latex2mathml 3.81.1, mathml2omml 0.0.2.
-- Renderers: Microsoft Word/PowerPoint/Excel 16 installed. LibreOffice is not installed on this machine. OCR (`tesseract`) and Poppler `pdftoppm` are not installed; PDF rendering uses PyMuPDF instead.
+What this plugin can do, verified 2026-10-21 on Windows by reading the code and
+running the helper CLI. Unverified items are marked as such.
 
-## Verification evidence
+## Runtime model
+
+Every operation goes through one spec-driven helper CLI, addressed by the
+absolute `python` and `cli` paths the host appends to each skill body as the
+`## Office runtime` block. It prints one JSON object; failures print JSON on
+stderr and exit non-zero.
+
+```
+<python> <cli> {docx|pptx|xlsx|pdf} {create|read|render}
+<python> <cli> xlsx recalc | status
+```
+
+`create` takes `--spec --out`, `read` takes `--input`, `render` takes
+`--input --out-dir`; all accept `--json-out`, `xlsx read` also `--data-only`.
+The CLI has no `edit` verb on purpose: changing a file is a set of narrow pack
+scripts (one operation each), so a new capability is a new script rather than a
+new verb in a shared dispatcher that every format has to keep in step.
+Every verb prints one JSON object; failures print JSON on stderr, exit non-zero.
+These verbs are the common path, not the ceiling: specialised work uses the pack
+scripts (`scripts/`, `container_tools/`), and the rest uses short snippets
+against the installed libraries, run with the same `python` and verified the same
+way. A missing verb is a missing shortcut, not a missing capability.
+
+## Packs and shared layer
+
+| Format | Router | Pack helpers | CLI verbs |
+| --- | --- | --- | --- |
+| DOCX | `assets/skills/office-documents/SKILL.md` | `scripts/` — OOXML kit, comments, fields, tracked changes, template styles, accessibility audit, text/blocks/properties edits | create, read, render |
+| PDF | `assets/skills/office-pdf/SKILL.md` | `scripts/` — text/table extraction, page rendering, form inspect/fill, page ops, region redaction | create, read, render |
+| PPTX | `assets/skills/office-presentations/SKILL.md` | `container_tools/` — OOXML helpers, preview rendering, text/slide/properties edits | create, read, render |
+| XLSX | `assets/skills/office-spreadsheets/SKILL.md` | `container_tools/` — workbook inspection, diff, recalculation gate, sheet/cell/row/style/chart edits | create, read, render, recalc |
+| live XLSX | `assets/skills/excel-live-control/SKILL.md` | `container_tools/live_excel.py` — attach to a running Excel/WPS window: read, write, formulas, styles, tables, charts, recalc, save | — |
+| shared | `assets/skills/shared/` | `common-workflow.md`, `annotation-recipes.md`, `check_runtime.py`, `scripts/ensure_raster_image.py` | — |
+
+The four routers register through `ctx.skills.registerProvider` in
+`src/index.ts`; `/` commands, labels and skill names come from
+`src/features.ts`. Helper scripts are argparse-based with `--help`.
+
+## What each format does
+
+- **DOCX** — create from a block spec: headings, paragraphs, bullets, numbered
+  lists, tables, images, LaTeX equations (OMML, fallbacks counted in
+  `equation_fallbacks`), quotes, page breaks, spacers, header/footer, page size,
+  margins. Read returns styled text, tables, images, equations, counts. Edits run
+  as pack scripts (text replacement, block append, core properties).
+- **PDF** — create with reportlab; the CJK font is auto-detected (named in the
+  report, e.g. `OfficeCJK`). Read returns page text, metadata, word counts and
+  form fields; OCR is not bundled (`ocr.available: false`). Edits run as pack
+  scripts: metadata, rotation, page order, merge, page removal, region
+  redaction. Render uses PyMuPDF.
+- **PPTX** — create 16:9 decks: layouts `title`, `bullets`, `section`,
+  `title_only`, `blank`; bullet levels, tables, bar/column/line/pie charts,
+  images. Read returns slides, text, tables and charts but **no shape geometry**,
+  so annotation work computes overlap with python-pptx. Edits run as pack
+  scripts: run-level text replacement, added slides, core properties.
+- **XLSX** — create sheets with rows, formulas, styles (cell or `A1:B2` range),
+  widths, row heights, frozen panes, merges, charts, anchored images. Read
+  returns rows, formulas with cached values, merges, charts, images, dimensions.
+  Edits run as pack scripts: sheets, cells, appended rows, range styles, charts,
+  images, rows.
+- **Live XLSX** — `excel-live-control` drives a workbook that is already open in
+  Excel or WPS Spreadsheets through COM (`GetActiveObject`, Windows PowerShell
+  5.1), never by writing the file behind the user's back: `info`, `read_range`,
+  `write_range`, `set_formula`, `style_range`, `add_chart`, `add_table`,
+  `recalc`, `save`, `close`, plus `--diagnose`. It refuses to start a hidden
+  instance for normal work and reports exactly which sheet and range it touched;
+  sheet create/rename/delete/reorder are deliberately absent (use a tab the user
+  has, or the file route).
+
+## Delivery rule
 
-Run on Windows, 2026-10-20, in paths containing Chinese characters and spaces.
+Hand the file over with `present` and summarise the change in one sentence. A
+bare path is not delivery: `.docx`/`.pptx`/`.xlsx`/`.pdf` links in the transcript
+render as "二进制文件，无法显示改动". Edits go to `<original>-edited.<ext>` (or
+the name the user asked for); never overwrite the original, report both paths.
+
+## Annotations
+
+A preview arrives as `<office-annotations>` wrapping a JSON array of items keyed
+`target`, `fileName`, `requirement`, `text` and a 0–1 `region`. `docx`/`pptx`
+add `page` (rendered PDF page; pptx one slide per page) and `pdf` adds a 1-based
+PDF `page` plus `imageName`. `xlsx` items are always `unmapped: true` with
+`text: ""` and no page/sheet/range: resolve cells from the `imageName` screenshot
+and `xlsx read`, and state the resolved sheet/A1 range before editing. Treat it
+as a change request — locate, smallest edit, re-render, confirm. Recipes:
+`assets/skills/shared/annotation-recipes.md`; unmappable payloads are reported,
+never guessed.
+
+## Renderer dependency
+
+- `docx`, `pptx` and `xlsx` rendering needs an office suite: Microsoft Office
+  (Word/PowerPoint/Excel over COM), WPS Office (`KWps`/`KWpp`/`Ket` over COM) or
+  LibreOffice (headless conversion). `render` names the one it used in its
+  `renderer` field (`microsoft-office`, `kingsoft-wps`, `libreoffice`). With none
+  installed it exits non-zero: `no document renderer found: install LibreOffice,
+  Microsoft Office, or WPS Office`.
+- `xlsx recalc` needs a real calculation engine: Excel or WPS Spreadsheets over
+  COM. It reports `renderer` and the count of cached values it filled in.
+- `pdf render` needs no external renderer; PyMuPDF rasterises it directly.
+- The PPTX pack's `container_tools/preview_render.py` is a geometry-only draft:
+  it redraws shapes, text boxes and images from the package with PyMuPDF and
+  labels itself `draft-preview` / `geometry-only`. It proves placement, not
+  typography (bullet glyphs are not drawn), and `render_slides.py` prefers the
+  real renderer whenever one exists.
+- **This machine renders through WPS Office.** `office_status` reports
+  `kingsoft_wps: {writer, presentation, spreadsheet}` from `wps.exe`/`wpp.exe`/
+  `et.exe` under `%LOCALAPPDATA%\Kingsoft\WPS Office\<version>\office6`;
+  `docx`/`pptx`/`xlsx render` return `"renderer": "kingsoft-wps"`, and `xlsx
+  recalc` fills cached values through `Ket.Application`.
+- `assets/skills/shared/scripts/ensure_raster_image.py` turns SVG, a chosen PDF
+  page, or a raster file into a PNG (PyMuPDF for vectors, Pillow for rasters), so
+  artwork can be embedded and then looked at. It never overwrites its input.
+- `assets/skills/shared/check_runtime.py` imports every package from
+  `python/requirements.txt` and runs `<cli> status`; it exits non-zero on a
+  missing package or broken CLI, and 4 with `--require-renderer` when no renderer
+  is installed (a missing renderer is otherwise only a warning).
+
+## Verification evidence
 
 | Check | Result |
 | --- | --- |
-| `pnpm run typecheck` | Passed |
-| `pnpm run build` | Passed; `dist/index.js`, `dist/index.d.ts`, `dist/client.js` generated |
-| `pnpm run test -- --run` | 14 passed across 2 files (10 in `test/office-cli.test.ts`) |
-| DOCX create/read/edit/render | Passed; rendered page inspected: Chinese header/title/body/table/equation/image/footer |
-| PDF create/read/edit/render | Passed; Chinese text extracted, metadata edit, page rendered |
-| PPTX create/read/edit/render | Passed; four slides rendered; table/chart/image layout fixed and inspected |
-| XLSX create/read/edit/recalc | Passed; formulas preserved; Excel recalculation produced cached values; data-only read confirmed |
-| `postinstall.mjs` first run | Passed; venv created, 10 packages installed, imports verified, config written |
-| `postinstall.mjs` second run | Passed in 2.7 s; idempotent |
-| `PATH` update | Registry write blocked by this Windows sandbox; plugin now warns instead of claiming success; absolute-path resolution works |
-| Chinese + spaces path | Used for every integration test |
-| Missing/incompatible Python | `resolvePython` reports `found: false` or `compatible: false`; skill bodies tell the agent to stop and ask for repair instead of running |
-| Interrupted installer | Download uses a unique temp filename per process; stale locked installers no longer block a retry |
-| `pnpm run lint --fix` | Passed |
-
-## Unsupported (explicit)
-
-- Google Docs, Google Slides, Google Sheets, Google Drive import/export, or any online document editing.
-- `@oai/artifact-tool`-only behavior and its artifact-session lifecycle.
-- DOCX comments, tracked changes, TOC fields, watermarks, redaction, content controls, template-style transfer, and accessibility audit.
-- PDF OCR, AcroForm filling, signing, redaction, and page-level text editing.
-- PPTX animations, speaker notes, template slide masters, and morph transitions.
-- XLSX pivot tables, macros, data validation, conditional formatting, and shared-workbook features.
-- Installing LibreOffice or Python on macOS/Linux; the plugin detects and reports, but only Windows auto-installs Python.
-- Live GUI interaction (menu open, chip insertion, chip persistence, right-sidebar preview) was not exercised in a running DSH window. It compiles against the public `0.2.1-rc.2` types, but installation into the user's profile was intentionally not performed.
-
-## UI API constraints recorded during implementation
-
-- The public composer `ReferenceChip` shows a custom icon only for `session`, `file`, and `folder`. This plugin uses `appearance: 'file'` in the composer, so the chip shows the built-in file glyph plus the friendly format label. The `/` menu candidates and transcript chips use four Gravity UI Icons SVGs (`file-text`, `file-letter-p`, `display`, `layout-cells`), vendored in `assets/icons` under MIT.
-- `matchEnter` cannot create a reference chip; Enter on a highlighted `/` candidate goes through the source's `onPick`, which is the implemented path.
-- The chip's stable internal ref is the feature id; clipboard/persistence text is `/documents` etc.; model serialization names the skill explicitly so the agent loads it before file work.
+| Packages on the runtime venv (3.13.12, `~/.dsh/office/runtime/venv`) | 10/10 import — python-docx 1.2.0, openpyxl 3.1.5, python-pptx 1.0.2, pypdf 6.21.1, reportlab 4.5.1, pdfplumber 0.11.9, PyMuPDF 1.28.2, Pillow 11.3.0, latex2mathml 3.81.1, mathml2omml 0.0.2 |
+| `check_runtime.py` (venv / `--require-renderer` / bare `py -3.14`) | exit 0 + renderer warning / exit 4 / exit 1 listing the 8 missing packages and the pip remedy |
+| DOCX create / read / `replace_text.py` / `append_blocks.py` | ok — counts returned, styles preserved, `replacements: 1`, `appended: 1`, equation intact |
+| DOCX / PPTX render | ok through WPS — `renderer: kingsoft-wps`, DOCX 2 pages, PPTX 3 pages, PNGs opened and checked |
+| PPTX create / read / `add_slides.py` | ok — 3 slides, texts and charts read back |
+| XLSX create / read / `set_cells.py` | ok — formula read back uncached, one cell written |
+| XLSX recalc | ok through WPS — `renderer: kingsoft-wps`, 34 cached values filled, `A3 = 7` after `CalculateFull` |
+| `ensure_raster_image.py` | ok — 120×60 SVG at `--dpi 300` → 500×250, `--page` on a 2-page PDF, `--width 400` upscale, JSON errors on missing/unwritable input |
+| `excel-live-control/container_tools/live_excel.py` | ok against WPS — attach refusal with remediation when nothing runs; `write_range` A1:B3 (6 cells), `set_formula` C1, `read_range` values `[[10,20,30],[30,40,null],[50,60,null]]`, `save` 9,268 bytes, `--diagnose` lists the workbook/sheet, `close --quit-app` refuses a dirty book, `--discard` leaves zero `et.exe` |
+| PDF create / read / render / `metadata.py` / `page_ops.py` / `redact_region.py` | ok — CJK font applied, metadata written, merge→remove→rotate, region redaction removed 170 chars and 11 drawings, `page-1.png` produced |
+| Annotation geometry helpers | pymupdf rect conversion, python-pptx overlap scan, A1 text matching run against those files |
+| Forbidden-vocabulary grep over the delivered docs | empty |
+
+Not claimed (no evidence here): installer or self-heal timings, live GUI
+interaction (`/` menu, chip, sidebar preview, annotation overlay), and macOS/Linux
+renderer support.
+
+## Explicitly out of scope
+
+- Google Docs/Slides/Sheets or Drive-backed editing; visual verification of
+  docx/pptx/xlsx without a renderer (skills say so instead of claiming a page was
+  inspected).
+- In-place PDF page-content editing (rebuild from a `pdf create` spec and say
+  so); OCR and scanned-PDF text extraction.
+- PPTX animations, speaker notes, slide masters; XLSX pivots, macros, data
+  validation, conditional formatting — no spec keys or verbs in the helper.
+- Formula evaluation without Microsoft Excel or WPS Spreadsheets; macOS/Linux
+  installation and renderer behaviour (only Windows was exercised).

package/LICENSE.md

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025-PRESENT dsh-tauri-desk
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025-PRESENT dsh-tauri-desk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,106 +1,108 @@
-<div align="center"><a name="readme-top"></a>
-
-<img src="./public/hero.png" alt="安装插件" />
-
-# DSH Office Kit
-
-[![npm version][npm-version-src]][npm-version-href]
-[![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![bundle][bundle-src]][bundle-href]
-[![JSDocs][jsdocs-src]][jsdocs-href]
-[![License][license-src]][license-href]
-
-为 DeepSeek Harness (DSH) 提供本地 Word、PDF、演示文稿与电子表格能力，支持 `/` 菜单、引用 Chip，以及侧边栏预览中的选区标注与修改请求。
-</div>
-
-## 📦 安装
-
-在官方插件中安装 `dsh-office-kit`
-
-<img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/install.png" alt="安装插件" />
-
-或使用命令行安装
-
-```sh
-dsh plugin add dsh-office-kit
-```
-
-- 在 **设置 → 插件** 中启用。
-- 需要 DSH ≥ `0.2.1-rc.2`、Python(无需，没有将自动安装) `3.10`–`3.13`。
-- Windows 缺少兼容 Python 时自动安装；macOS / Linux 使用现有 Python。
-
-## 特性
-
-- 📝 **Word**：`/documents` 创建、读取和编辑 DOCX，支持表格、图片、公式与页眉页脚。
-- 📄 **PDF**：`/pdf` 创建、读取和编辑 PDF，支持合并、旋转、删页与元数据。
-- 📽️ **演示文稿**：`/presentations` 创建、读取和编辑 PPTX，支持项目符号、表格、图表与图片。
-- 📊 **电子表格**：`/spreadsheets` 创建、读取和编辑 XLSX，支持公式、样式、图表、冻结窗格与重算。
-- 🖍️ **侧边栏标注**：在 PDF、DOC/DOCX 预览中吸附段落或框选区域，批量提交修改要求。
-- 🔗 **会话引用**：通过 Chip 调用文档技能；注释链接可悬停查看文件名与要求，PDF 标注附选区截图。
-
-## 🚀 快速开始
-
-### 通过菜单处理文档
-
-<img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/image.png" alt="Office 菜单与文档预览" />
-
-1. 在输入框键入 `/`，选择 **文档**、**PDF 文档**、**演示文稿** 或 **电子表格**。
-2. 回车插入 Chip，描述创建、读取或修改任务。
-3. 打开生成的文件，在侧边栏预览结果。
-
-
-### 在预览中请求修改
-
-| <img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/annotation-selection.png" alt="段落吸附与修改要求输入" /> | <img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/annotation-conversation.png" alt="注释列表与会话引用" /> |
-| ------------- | ------------- |
-
-1. 打开 PDF 或 DOC/DOCX，点击工具栏的 **请求修改**。
-2. 悬停吸附段落，点击或拖动框选，输入要求并添加注释。
-3. 悬停底部 **注释数量** 查看列表，点击 **发送**；**取消** 清空本批。
-
-- **Esc**：先取消当前选区，再按一次退出标注模式。
-- **附件**：PDF 附选区截图；DOC/DOCX 仅发送文字与定位信息。
-- **草稿**：已有输入时先合入草稿，由你确认发送；暂存注释刷新后不保留。
-
-## 💡 示例文档
-
-- [Word](<public/samples/sample.docx>)
-- [PDF](<public/samples/sample.pdf>)
-- [演示文稿](<public/samples/sample.pptx>)
-- [电子表格](<public/samples/sample.xlsx>)
-- [来源与许可](<public/samples/README.md>)
-
-## 📚 配置与限制
-
-- **Python**：`DSH_OFFICE_PYTHON` 可指定解释器。
-- **标注范围**：仅 PDF、DOC/DOCX；扫描 PDF 可框选截图，不提供 OCR。
-- **本地文件**：不支持 Google Docs / Slides / Sheets 或远程编辑。
-- **完整清单**：[能力与未支持项](<CAPABILITY.md>)。
-
-## 🛠️ 开发与贡献
-
-```sh
-pnpm install
-pnpm run lint --fix
-pnpm run typecheck
-pnpm run test -- --run
-pnpm run build
-```
-
-## 📜️ 许可证
-
-- [MIT](<LICENSE.md>)
-- 示例文档保留 [Apache Tika 的许可与声明](<public/samples/README.md>)。
-
-<!-- Badges -->
-
-[npm-version-src]: https://img.shields.io/npm/v/dsh-office-kit?style=flat&colorA=080f12&colorB=1fa669
-[npm-version-href]: https://npmjs.com/package/dsh-office-kit
-[npm-downloads-src]: https://img.shields.io/npm/dm/dsh-office-kit?style=flat&colorA=080f12&colorB=1fa669
-[npm-downloads-href]: https://npmjs.com/package/dsh-office-kit
-[bundle-src]: https://img.shields.io/bundlephobia/minzip/dsh-office-kit?style=flat&colorA=080f12&colorB=1fa669&label=minzip
-[bundle-href]: https://bundlephobia.com/result?p=dsh-office-kit
-[license-src]: https://img.shields.io/github/license/hairyf/dsh-office-kit.svg?style=flat&colorA=080f12&colorB=1fa669
-[license-href]: https://github.com/hairyf/dsh-office-kit/blob/main/LICENSE
-[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
-[jsdocs-href]: https://www.jsdocs.io/package/dsh-office-kit
+<div align="center"><a name="readme-top"></a>
+
+<img src="./public/hero.png" alt="安装插件" />
+
+# DSH Office Kit
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![bundle][bundle-src]][bundle-href]
+[![JSDocs][jsdocs-src]][jsdocs-href]
+[![License][license-src]][license-href]
+
+为 DeepSeek Harness (DSH) 提供本地 Word、PDF、演示文稿与电子表格能力，支持 `/` 菜单、引用 Chip，以及侧边栏预览中的选区标注与修改请求。
+</div>
+
+## 📦 安装
+
+在官方插件中安装 `dsh-office-kit`
+
+<img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/install.png" alt="安装插件" />
+
+或使用命令行安装
+
+```sh
+dsh plugin add dsh-office-kit
+```
+
+- 在 **设置 → 插件** 中启用。
+- 需要 DSH ≥ `0.2.1-rc.2`、Python(无需，没有将自动安装) `3.10`–`3.13`。
+- Windows 缺少兼容 Python 时自动安装；macOS / Linux 使用现有 Python。
+
+## 特性
+
+- 📝 **Word**：`/documents` 创建、读取和编辑 DOCX，支持表格、图片、公式与页眉页脚。
+- 📄 **PDF**：`/pdf` 创建、读取和编辑 PDF，支持合并、旋转、删页与元数据。
+- 📽️ **演示文稿**：`/presentations` 创建、读取和编辑 PPTX，支持项目符号、表格、图表与图片。
+- 📊 **电子表格**：`/spreadsheets` 创建、读取和编辑 XLSX，支持公式、样式、图表、冻结窗格与重算。
+- 🖍️ **侧边栏标注**：在 PDF、DOC/DOCX、PPTX、XLSX 预览中吸附段落或框选区域，批量提交修改要求。
+- 🔗 **会话引用**：通过 Chip 调用文档技能；注释链接可悬停查看文件名与要求，PDF 标注附选区截图。
+- 🖼️ **渲染校验**：DOCX/PPTX/XLSX 经 Microsoft Office、WPS Office 或 LibreOffice 导出 PDF 再栅格化，PDF 直接用 PyMuPDF；SVG/PDF 素材可用 `ensure_raster_image.py` 转成 PNG 后嵌入。
+- 🧮 **活体表格**：`excel-live-control` 技能通过 COM 驱动已经打开的 Excel / WPS 表格（读区、写值、样式、图表、重算、保存）。
+
+## 🚀 快速开始
+
+### 通过菜单处理文档
+
+<img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/image.png" alt="Office 菜单与文档预览" />
+
+1. 在输入框键入 `/`，选择 **文档**、**PDF 文档**、**演示文稿** 或 **电子表格**。
+2. 回车插入 Chip，描述创建、读取或修改任务。
+3. 打开生成的文件，在侧边栏预览结果。
+
+
+### 在预览中请求修改
+
+| <img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/annotation-selection.png" alt="段落吸附与修改要求输入" /> | <img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/annotation-conversation.png" alt="注释列表与会话引用" /> |
+| ------------- | ------------- |
+
+1. 打开 PDF 或 DOC/DOCX，点击工具栏的 **请求修改**。
+2. 悬停吸附段落，点击或拖动框选，输入要求并添加注释。
+3. 悬停底部 **注释数量** 查看列表，点击 **发送**；**取消** 清空本批。
+
+- **Esc**：先取消当前选区，再按一次退出标注模式。
+- **附件**：PDF 附选区截图；DOC/DOCX 仅发送文字与定位信息。
+- **草稿**：已有输入时先合入草稿，由你确认发送；暂存注释刷新后不保留。
+
+## 💡 示例文档
+
+- [Word](<public/samples/sample.docx>)
+- [PDF](<public/samples/sample.pdf>)
+- [演示文稿](<public/samples/sample.pptx>)
+- [电子表格](<public/samples/sample.xlsx>)
+- [来源与许可](<public/samples/README.md>)
+
+## 📚 配置与限制
+
+- **Python**：`DSH_OFFICE_PYTHON` 可指定解释器。
+- **标注范围**：仅 PDF、DOC/DOCX；扫描 PDF 可框选截图，不提供 OCR。
+- **本地文件**：不支持 Google Docs / Slides / Sheets 或远程编辑。
+- **完整清单**：[能力与未支持项](<CAPABILITY.md>)。
+
+## 🛠️ 开发与贡献
+
+```sh
+pnpm install
+pnpm run lint --fix
+pnpm run typecheck
+pnpm run test -- --run
+pnpm run build
+```
+
+## 📜️ 许可证
+
+- [MIT](<LICENSE.md>)
+- 示例文档保留 [Apache Tika 的许可与声明](<public/samples/README.md>)。
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/dsh-office-kit?style=flat&colorA=080f12&colorB=1fa669
+[npm-version-href]: https://npmjs.com/package/dsh-office-kit
+[npm-downloads-src]: https://img.shields.io/npm/dm/dsh-office-kit?style=flat&colorA=080f12&colorB=1fa669
+[npm-downloads-href]: https://npmjs.com/package/dsh-office-kit
+[bundle-src]: https://img.shields.io/bundlephobia/minzip/dsh-office-kit?style=flat&colorA=080f12&colorB=1fa669&label=minzip
+[bundle-href]: https://bundlephobia.com/result?p=dsh-office-kit
+[license-src]: https://img.shields.io/github/license/hairyf/dsh-office-kit.svg?style=flat&colorA=080f12&colorB=1fa669
+[license-href]: https://github.com/hairyf/dsh-office-kit/blob/main/LICENSE
+[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
+[jsdocs-href]: https://www.jsdocs.io/package/dsh-office-kit