dsh-plugin-office-markdown 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-plugin-office-markdown contributors
+
+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.en.md

@@ -0,0 +1,156 @@
+<h1 align="center">dsh-plugin-office-markdown</h1>
+
+<p align="center">
+  Convert Office / PDF files to Markdown before DeepSeek Harness reads them —<br>
+  what enters the model context is a file path, not the raw contents of the document.
+</p>
+
+<p align="center">
+  <a href="README.md">中文</a> ｜ <a href="README.en.md">English</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Z8906/dsh-plugin-office-markdown/releases"><img alt="release" src="https://img.shields.io/github/v/release/Z8906/dsh-plugin-office-markdown?style=flat-square&label=release"></a>
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square">
+  <img alt="node" src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen?style=flat-square">
+  <img alt="npm dependencies" src="https://img.shields.io/badge/npm%20deps-0-brightgreen?style=flat-square">
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> ｜
+  <a href="#usage">Usage</a> ｜
+  <a href="#converters">Converters</a> ｜
+  <a href="#documentation">Docs</a> ｜
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
+
+---
+
+Conversion happens **locally**: no network (except an optional first MarkItDown download), the source
+file is never modified, no API budget is spent, and the plugin itself has **zero npm dependencies**.
+
+## Install
+
+In DSH, open **Settings → Plugins → Install**, paste one line, press Enter, then **restart DSH**:
+
+```
+github:Z8906/dsh-plugin-office-markdown
+```
+
+To pin a version, append a tag: `github:Z8906/dsh-plugin-office-markdown#<tag>`, where `<tag>` looks like
+`v1.2.1` (see [Releases](https://github.com/Z8906/dsh-plugin-office-markdown/releases)).
+If the target machine has no git, use the `.tgz` from Releases and paste its absolute path into the
+install box. All four install routes, the manual route and the upgrade steps are in the
+**[installation docs](docs/installation.md)**.
+
+> **Do not upgrade through "uninstall → reinstall".** When this plugin is really uninstalled it cleans up
+> the Python packages it registered (see the [uninstall docs](docs/uninstall.md)), so that route leaves you
+> with an updated plugin and no Python environment. Use `pnpm update`, or add the same git address again
+> in the install box.
+
+## Usage
+
+Nothing to memorise. Say "read and summarise this xlsx" — the skill registered by the plugin makes the
+model convert first:
+
+```
+read_office_as_markdown({ path: "report.xlsx" })
+```
+
+The return value carries the path, size and line count of the resulting `.md`, plus a structure outline
+(headings / sheets / slides with approximate line numbers), and hands back a reading strategy: read the
+first 200 lines for structure, then grep within the same `.md`. **The artifact itself is never truncated** —
+the model receives a complete Markdown file.
+
+Other ways to call the tool: batch (`paths`, or point `path` at a directory), outline only
+(`action: "outline"`, never triggers conversion), clean up stale artifacts of the same source
+(`action: "clean"`, dry-run by default), inspect the current converter (`action: "status"`).
+All parameters are in the **[usage docs](docs/usage.md)**.
+
+## Converters
+
+Probed in order, first available wins. This table mirrors `lib/convert.js`:
+
+| # | Converter | Fidelity | Requires |
+| --- | --- | --- | --- |
+| 1 | `uvx markitdown` (temporary run) | high | `uv` + network (first run) |
+| 2 | local `markitdown` command | high | markitdown installed |
+| 3 | `python -m markitdown` | high | Python + markitdown |
+| 4 | built-in Python fallback (`lib/fallback.py`) | limited | any Python 3; optional libs improve it |
+| 5 | built-in Node fallback (`lib/fallback-node.js`) | limited | nothing |
+
+**Level 5 needs neither Python nor network**: it parses OOXML directly with Node's built-in `zlib`
+(`.docx` / `.xlsx` / `.pptx` are just zip + xml). It supports `.docx` `.docm` `.xlsx` `.xlsm` `.pptx` `.pptm`;
+`.pdf` and legacy binary formats (`.doc` `.xls` `.ppt`) need MarkItDown or level 4.
+
+Every artifact records who produced it on its first line; on a cache hit the plugin reads the **real**
+converter and fidelity back from that line instead of claiming "high fidelity" unconditionally:
+
+```
+<!-- dsh-office-markdown converter=python-module fidelity=high at=<time> srcbytes=<bytes> srchash=<hash> -->
+```
+
+For maximum fidelity, open **Settings → Office conversion** and click "configure MarkItDown environment".
+**The install script never installs any Python package on its own** — you pick the interpreter on that page.
+Details are in the **[converter docs](docs/converters.md)**.
+
+## Settings page
+
+**Settings → Office conversion** shows the current converter, probes the local Python environments,
+configures or uninstalls MarkItDown, displays the environment record the plugin adopted, and offers
+"try converting one file" (which runs the real converter chain locally, bypassing the model and the cache).
+
+The buttons call the plugin's own HTTP routes under `/office-markdown/api/*`; the route list is in the
+[usage docs](docs/usage.md).
+
+## Uninstall
+
+Uninstall it from **Settings → Plugins**. The plugin first confirms it was **really removed**
+(not disabled, not closed, not restarted), then dispatches a detached watchdog process that
+`pip uninstall`s the packages it registered.
+
+**Disabling, closing or restarting never triggers cleanup, and never leaves a resident process behind.**
+Cleanup is strictly limited to the plugin's own environment record: packages shipped with the DSH runtime,
+packages other components depend on, and anything you installed yourself are left untouched.
+Details are in the **[uninstall docs](docs/uninstall.md)**.
+
+## Requirements
+
+- **Node ≥ 18**, built-in modules only (`fs` / `path` / `os` / `zlib` / `crypto` / `child_process` / `string_decoder`) —
+  **0 npm dependencies**, no `npm install`.
+- **Python and MarkItDown are entirely optional**; with neither, the level-5 Node fallback is used.
+- Imports nothing from the host except `@deepseek-ai/dsh-tools` (for `defineTool`).
+- DeepSeek Harness only. A profile without `webServer` (CLI profiles) simply has no settings page;
+  the tool and the skill are unaffected.
+
+## Documentation
+
+The detailed docs are currently Chinese-only.
+
+| Doc | Contents |
+| --- | --- |
+| [Installation](docs/installation.md) | four routes, manual install, upgrade, verification |
+| [Usage](docs/usage.md) | tool parameters, skill, `read` guard, settings page, HTTP routes |
+| [Converters](docs/converters.md) | converter chain, fidelity, multiple Python environments |
+| [Configuration](docs/configuration.md) | config keys and defaults (mirrors `DEFAULTS` in `lib/index.js`) |
+| [Artifacts & files](docs/artifacts.md) | where the `.md` goes, which files the plugin leaves behind |
+| [Uninstall](docs/uninstall.md) | enable / disable / uninstall and cleanup scope |
+| [Troubleshooting](docs/troubleshooting.md) | common symptoms |
+| [Development](docs/development.md) | package layout, local development, releasing |
+| [Changelog](CHANGELOG.md) | what changed in each version |
+
+## About this documentation
+
+The README, `docs/`, `CHANGELOG.md` and the release notes of this repository are **largely AI-generated**
+(written by a coding agent running in DeepSeek Harness) and reviewed by the maintainer before publishing.
+
+Config keys, HTTP routes, the converter chain and the file list were each **checked against the source**;
+even so, the docs can lag behind the implementation or contain inaccuracies and omissions — **the code is
+the reference**. Issues and corrections are welcome.
+
+Numbers without a reproducible measurement behind them (for example "how many tokens does this save" or
+"how much memory does it use") are deliberately **not** stated here.
+
+## License
+
+[MIT](LICENSE) © 2026 dsh-plugin-office-markdown contributors

package/README.md

@@ -0,0 +1,144 @@
+<h1 align="center">dsh-plugin-office-markdown</h1>
+
+<p align="center">
+  在 DeepSeek Harness 读取 Office / PDF 之前，先把它们转成 Markdown ——<br>
+  进入模型上下文的是一个文件路径，而不是整份文件的原始内容。
+</p>
+
+<p align="center">
+  <a href="README.md">中文</a> ｜ <a href="README.en.md">English</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Z8906/dsh-plugin-office-markdown/releases"><img alt="release" src="https://img.shields.io/github/v/release/Z8906/dsh-plugin-office-markdown?style=flat-square&label=release"></a>
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square">
+  <img alt="node" src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen?style=flat-square">
+  <img alt="npm dependencies" src="https://img.shields.io/badge/npm%20deps-0-brightgreen?style=flat-square">
+</p>
+
+<p align="center">
+  <a href="#安装">安装</a> ｜
+  <a href="#怎么用">使用</a> ｜
+  <a href="#转换器">转换器</a> ｜
+  <a href="#文档">文档</a> ｜
+  <a href="CHANGELOG.md">更新日志</a>
+</p>
+
+---
+
+转换在**本机**完成，不联网（可选的 MarkItDown 首次下载除外）、不修改原文件、
+不消耗 API 额度，插件本身**没有任何 npm 依赖**。
+
+## 安装
+
+在 DSH 的 **设置 → 插件 → 安装** 里填一行，回车，然后**重启 DSH**：
+
+```
+github:Z8906/dsh-plugin-office-markdown
+```
+
+想锁定版本就在末尾加 tag：`github:Z8906/dsh-plugin-office-markdown#<tag>`，
+`<tag>` 形如 `v1.2.1`（见 [Releases](https://github.com/Z8906/dsh-plugin-office-markdown/releases)）。
+目标机器没有 git 的话，可以用 Releases 里的 `.tgz`，在安装框里填它的绝对路径。
+四种安装方式、手工装法与升级步骤见 **[安装文档](docs/installation.md)**。
+
+> **升级不要走「卸载 → 重新安装」。** 本插件在真正被卸载时会清理它自己登记过的 Python 包
+> （见 [卸载文档](docs/uninstall.md)），那条路的结果是「插件更新了、Python 环境却没了」。
+> 用 `pnpm update`，或者直接在安装框里再 add 一次同一个 git 地址。
+
+## 怎么用
+
+装好之后不需要记命令，直接说「读取并总结这个 xlsx」即可 —— 插件注册的技能会让模型先调用转换工具：
+
+```
+read_office_as_markdown({ path: "报表.xlsx" })
+```
+
+返回值里有转换后 `.md` 的路径、体积、行数，以及一份结构索引（章节 / 工作表 / 幻灯片的标题与大致行号），
+并给出读取建议：先读前 200 行看结构，再用 grep 在同一个 `.md` 里定位。
+**产物本身不会被裁剪** —— 交给模型的是一个完整的 Markdown 文件。
+
+工具的其他用法：批量（`paths`，或把目录交给 `path`）、只要结构索引（`action: "outline"`，
+不触发转换）、清理同一源文件的旧产物（`action: "clean"`，默认先干跑）、查看当前转换器
+（`action: "status"`）。全部参数见 **[使用文档](docs/usage.md)**。
+
+## 转换器
+
+按顺序探测，第一个可用的胜出。下表对照 `lib/convert.js`：
+
+| 顺序 | 转换器 | 保真度 | 需要 |
+| --- | --- | --- | --- |
+| 1 | `uvx markitdown`（临时运行） | 高 | `uv` + 网络（首次） |
+| 2 | 本机 `markitdown` 命令 | 高 | 已安装 markitdown |
+| 3 | `python -m markitdown` | 高 | Python + markitdown |
+| 4 | 插件内置 Python 兜底（`lib/fallback.py`） | 有限 | 任意 Python 3，可选库能提升效果 |
+| 5 | 插件内置 Node 兜底（`lib/fallback-node.js`） | 有限 | 无 |
+
+**第 5 级不需要 Python、也不需要网络**：它用 Node 内置的 `zlib` 直接解析 OOXML
+（`.docx` / `.xlsx` / `.pptx` 本身就是 zip + xml）。支持 `.docx` `.docm` `.xlsx` `.xlsm` `.pptx` `.pptm`；
+`.pdf` 与旧版二进制格式（`.doc` `.xls` `.ppt`）需要 MarkItDown 或第 4 级。
+
+每份产物的第一行记录它是谁转的；命中缓存时插件从这一行读回**真实的**转换器与保真度，
+而不是无条件声称「高保真」：
+
+```
+<!-- dsh-office-markdown converter=python-module fidelity=high at=<时间> srcbytes=<字节数> srchash=<哈希> -->
+```
+
+想要高保真：打开 **设置 → Office 转换**，点「一键配置 MarkItDown 环境」。
+**安装脚本不会替你装任何 Python 包**，装到哪个解释器由你在页面上选。
+细节见 **[转换器文档](docs/converters.md)**。
+
+## 设置页
+
+**设置 → Office 转换** 提供：当前转换器、本机 Python 环境探测、一键配置 / 卸载 MarkItDown、
+插件登记的环境记录、以及「试转一个文件」（不进模型、不走缓存，直接在本机跑一遍转换链看结果）。
+
+页面上的按钮走插件自己的 HTTP 路由 `/office-markdown/api/*`，路由清单见 [使用文档](docs/usage.md)。
+
+## 卸载
+
+在 **设置 → 插件** 里点卸载即可。插件会先确认自己**真的被移除**（而不是被禁用 / 关闭 / 重启），
+再派一个脱离宿主的看门狗进程，把它登记过的 Python 包 `pip uninstall` 掉。
+
+**禁用、关闭、重启都不会触发清理，也不会留下任何常驻进程。**
+清理范围严格限定在插件自己的环境记录里：DSH 运行时自带的包、被其它组件依赖的包、
+以及你自己装的包，一个都不动。细节见 **[卸载文档](docs/uninstall.md)**。
+
+## 依赖与兼容
+
+- **Node ≥ 18**，只用内置模块（`fs` / `path` / `os` / `zlib` / `crypto` / `child_process` / `string_decoder`），
+  **0 个 npm 依赖**，不需要 `npm install`。
+- **Python 与 MarkItDown 全部可选**：两者都没有时走第 5 级 Node 兜底。
+- 除宿主提供的 `@deepseek-ai/dsh-tools`（用于 `defineTool`）外，不 import 任何宿主包。
+- 只支持 DeepSeek Harness。profile 没有 `webServer` 服务时（例如 CLI profile），
+  设置页不会出现，工具与技能不受影响。
+
+## 文档
+
+| 文档 | 内容 |
+| --- | --- |
+| [安装](docs/installation.md) | 四种安装方式、手工安装、升级、验证 |
+| [使用](docs/usage.md) | 工具参数、技能、`read` 守卫、设置页、HTTP 路由 |
+| [转换器](docs/converters.md) | 转换器链、保真度、多个 Python 环境 |
+| [配置](docs/configuration.md) | 配置项与默认值（对照 `lib/index.js` 的 `DEFAULTS`） |
+| [产物与文件](docs/artifacts.md) | `.md` 放在哪、插件会留下哪些文件 |
+| [卸载](docs/uninstall.md) | 启用 / 禁用 / 卸载与清理范围 |
+| [故障排查](docs/troubleshooting.md) | 常见现象与处理 |
+| [开发](docs/development.md) | 包内文件、本地开发、发布 |
+| [更新日志](CHANGELOG.md) | 每个版本改了什么 |
+
+## 关于本文档
+
+本仓库的 README、`docs/`、`CHANGELOG.md` 以及各版本的 Release 说明，**主要由 AI 生成**
+（DeepSeek Harness 里的编码 agent 撰写），由维护者审阅后发布。
+
+其中配置项、HTTP 路由、转换器链、文件清单等内容都**逐项对照过源码**；但文档仍可能落后于实现，
+或存在表述不准、细节缺失之处，**请以代码为准**。发现问题欢迎提 issue。
+
+文档中**不写没有实测依据的数字**（例如「能省多少 token」「占用多少内存」）——
+这类断言缺少可复现的测量过程，因此不列出。
+
+## 许可证
+
+[MIT](LICENSE) © 2026 dsh-plugin-office-markdown contributors

package/cordis.patch.yml

@@ -0,0 +1,35 @@
+# dsh-plugin-office-markdown bundle patch: inserts one plugin row into the
+# profile roster. Install by copying this package into the profile's
+# node_modules and adding `dsh-plugin-office-markdown` to
+# `dsh.profile.bundles` in the profile package.json (see README.md).
+#
+# The row references the package by name; `exports["."]` is the host half that
+# registers the `read_office_as_markdown` tool plus its bundled skill.
+#
+# `config` below restates every owned key so later profile layers can override
+# individual values while keeping this bundle first in the stack.
+- insert:
+    - id: office-markdown
+      name: dsh-plugin-office-markdown
+      config:
+        enabled: true
+        tmpDir: ''
+        converter: auto
+        pythonPath: ''
+        pythonPrefer: auto
+        allowUvxDownload: true
+        uvxExtras: 'markitdown[all]'
+        fallbackEnabled: true
+        guardReadTool: true
+        probeTtlMs: 600000
+        timeoutMs: 300000
+        reuseFresh: true
+        pruneStaleArtifacts: false
+        maxPreviewChars: 4000
+        maxRowsPerSheet: 400
+        maxTableCols: 24
+        maxCellsPerSheet: 20000
+        registerSkill: true
+        registerSettings: true
+        autoAdoptEnv: true
+        removeEnvOnUninstall: true