dsh-plugin-documents

Readme

# dsh-plugin-documents

![npm version](https://img.shields.io/npm/v/dsh-plugin-documents) ![license](https://img.shields.io/npm/l/dsh-plugin-documents) [![1024Store](https://img.shields.io/badge/DSH%201024Store-online-4B44F6)](https://deepseek1024.com)

一个 DeepSeek Harness (DSH / Cordis) 插件，给模型提供两个工具，用来读写 Word (.docx)、PDF 和纯文本 (.txt/.md 等) 文件。

## 工具

### `read_document`

读取一个 .docx / .pdf / 文本文件，返回提取出的纯文本内容。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file_path` | string | 是 | 要读取的文件路径（相对路径按会话工作目录解析） |
| `format` | string | 否 | `auto`（默认，按扩展名识别）/ `text` / `docx` / `pdf` |

### `write_document`

把纯文本内容写入一个 .docx / .pdf / 文本文件。输出格式由扩展名决定。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file_path` | string | 是 | 目标路径；扩展名决定格式（`.docx` / `.pdf` / 文本） |
| `content` | string | 是 | 要写入的文本内容 |

## 能力与限制

- **文本**：读写 `.txt` `.md` 等 UTF-8 文本文件。
- **Word (.docx)**：读——提取 `word/document.xml` 中的段落/表格文本；写——生成一个最小但合法、可用 Word/WPS 打开的 .docx（每个换行一个段落，支持中文）。
- **PDF**：读——扫描对象、解压 Flate/ASCIIHex/ASCII85/RunLength 流，提取 `Tj`/`TJ`/`'`/`"`/`T*` 文本，支持 CID 字体的 UTF-16BE（中文可提取）；写——生成带经典 xref 的合法 PDF，使用内置 Adobe STSong-Light + UniGB-UCS2-H 绘制，中文/英文可直接显示（Adobe Reader、Chrome/Edge、Foxit、WPS）。

限制（best-effort）：PDF 读取无法 OCR 图片型 PDF，也不处理加密 PDF；复杂排版（表格、分栏）会按内容流顺序摊平成文本。`.doc`（老式二进制 Word）不支持，请先另存为 `.docx`。

## 安装

插件是已发布到 npm 的 `dsh.bundle` 包（当前版本 0.1.0），已上架 DSH 1024Store。

### 方式 1：npm 包（推荐）

```bash
# 装进指定 profile（桌面端桌面 profile 为 desktop，商店统计走 web）
dsh plugin --profile <profile> add dsh-plugin-documents
# 或带商店统计的安装（会匿名计入 1024Store 安装排名）：
dsh1024 plugin --profile <profile> add dsh-plugin-documents
```

### 方式 2：DSH Desktop 内置商店

打开 DSH Desktop → 社区插件市场（来源 DSH 1024Store）→ 搜索 `dsh-plugin-documents` → 安装 → 重启。

### 方式 3：GitHub 源码

```bash
dsh plugin --profile <profile> add github:LR611415/dsh-plugin-documents
```

装完后重启 DSH Desktop，插件（`document-tools`）即随运行时加载，模型可获得 `read_document` / `write_document` 两个工具。

## 测试

读写核心逻辑已通过回环测试（4/4），测试命令、环境与结果见 [TESTING.md](TESTING.md)：

```bash
npm install --omit=peer --no-audit --no-fund
node test/smoke.mjs
```

## 发布与更新

```bash
# 改代码后发布新版本
npm version patch            # 0.1.0 → 0.1.1
git push && git push --tags
npm publish --registry=https://registry.npmjs.org/
```

发布后 1024Store 商店会自动检测并同步新版。

## 目录结构

```
dsh-plugin-documents/
├── package.json          # 声明 dsh.bundle.patch + adm-zip 依赖
├── cordis.patch.yml      # 把插件插入 entry list
├── README.md
├── TESTING.md            # 测试报告（投稿测试证据）
├── lib/
│   ├── index.js          # 插件入口，注册 read_document / write_document
│   ├── util.js           # 格式识别 + XML 转义
│   ├── docx.js           # Word 读写
│   └── pdf.js            # PDF 读写
└── test/
    └── smoke.mjs         # 可复现的读写回环测试
```