dsh-sidebar-superdoc-docx

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# dsh-sidebar-superdoc-docx

English | [中文](README.zh-CN.md)

Open and edit **.docx** files directly in the [DSH](https://github.com/deepseek-ai/DeepSeek-Harness) web GUI's
**better-sidebar** editor, powered by [SuperDoc](https://github.com/superdoc/docx-editor) — a browser-native DOCX
editor that reads and writes the real OOXML (no server-side document service needed).

> **Dependency**: this plugin registers its file viewer with
> [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) (`>= 0.13.0`) — a **mandatory peer
> dependency**. Without it, the viewer never appears. Install it first (or together with this plugin).
>
> **⚠️ License notice**: this plugin's own code is MIT, but it integrates AGPL-3.0 `superdoc` and the
> proprietary-licensed `@superdoc/docx-engine` at runtime — installing it means accepting those terms. See
> [License](#license) below and [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

## Features

- **Browser-native DOCX editing** — view and edit `.docx` in the sidebar with comments and tracked changes; three
  open modes selectable in the settings page: editing / suggesting / viewing.
- **Save back to disk** — the `Save` button exports the edited document and **atomically overwrites** the opened
  file through a dedicated route (tmp + rename, never a half-written state); unsaved edits show a `●` dot.
- **Follows outside edits** — a 3s disk poll: a clean editor auto-swaps to the new version in place
  (`replaceFile`); a dirty editor only shows a banner with a manual `Reload` — your edits are never silently
  dropped.
- **Fully self-hosted & offline-capable** — the SuperDoc editor build and the DOCX engine (web workers included)
  are served same-origin from this package's `node_modules`: no CDN traffic, no third-party document service,
  telemetry off by default. Fully offline after `pnpm install`.
- **Download fallback** — every surface (including all error states) keeps a plain download link.
- **Sidebar-adaptive** — the toolbar folds into an overflow menu as the pane narrows; pages fit-to-pane zoom;
  readable in light and dark themes.

## Use cases

- **Human–AI collaboration on one Word file**: the AI agent edits a `.docx` in the session; you see the new
  version in the sidebar within seconds, polish it by hand, save — and the agent's next turn works from the
  latest version. A two-way loop without interruptions.
- **Intranet / offline / compliance environments**: deployments that must not reach CDNs such as jsdelivr or
  SaaS document services; every asset is self-hosted same-origin.
- **No document server wanted**: unlike OnlyOffice / Collabora, which need a separate Document Server, this
  plugin has zero service dependencies — install and go.
- **Document review workflows**: open in `suggesting` mode; comments and suggestions land as tracked changes.
- **Quick preview**: replaces the built-in code/download viewers — click a `.docx` in the file tree and see the
  paginated document, with a download link one click away.

## Installation

### Prerequisites

- Node.js `>= 20`;
- the DSH web GUI and its `web` profile;
- `dsh-better-sidebar >= 0.13.0` installed in the same profile (see the dependency note above).

### From npm (recommended)

The package is published on npmjs as `dsh-sidebar-superdoc-docx`:

```sh
dsh plugin --profile web add dsh-better-sidebar dsh-sidebar-superdoc-docx
```

Or by hand: edit the profile's `package.json` (e.g. `~/.dsh/profiles/web/package.json`), add the two
npm dependencies and the bundle entries, then run `pnpm install` in the profile directory:

```jsonc
{
  "dependencies": {
    "dsh-better-sidebar": ">=0.13.0",
    "dsh-sidebar-superdoc-docx": "^0.1.0"
  },
  "dsh": { "profile": { "bundles": ["…", "dsh-better-sidebar", "dsh-sidebar-superdoc-docx"] } }
}
```

Finally **restart `dsh web`** (the host half must reload) and hard-refresh the browser (Ctrl/Cmd+Shift+R).

### From GitHub (source / development)

```sh
dsh plugin --profile web add github:chendefine/dsh-sidebar-superdoc-docx
```

For local development, clone, build, and link:

```sh
git clone https://github.com/chendefine/dsh-sidebar-superdoc-docx
cd dsh-sidebar-superdoc-docx
pnpm install
pnpm build        # → lib/index.js + lib/client.js + lib/types
```

then, in the profile's `package.json`, point the dependency at the clone and run `pnpm install`
in the profile directory:

```jsonc
{
  "dependencies": {
    "dsh-sidebar-superdoc-docx": "link:/absolute/path/to/dsh-sidebar-superdoc-docx"
  }
}
```

### Plugin config (`cordis.patch.yml` of the profile)

```yaml
- id: dsh-sidebar-superdoc-docx
  config:
    fileLimitMb: 100            # save-route size cap in MB, default 100
    allowOutsideWorkspace: false # allow saving files resolved outside the session cwd, default false
```

## Usage

### Opening a document

Click any `.docx` in the sidebar file tree — it opens in the **DOCX (SuperDoc)** viewer instead of the built-in
code/download viewers.

### Switching the open mode

Under **Settings → Side cards → File preview → DOCX (SuperDoc)**, the gear exposes the "open mode" select:
editing / suggesting / viewing. The choice persists in `pluginSettings['superdoc:docx'].mode` and takes effect
immediately (the editor remounts in the new mode); `viewing` also hides the save button.

### Editing & saving

- The top toolbar is SuperDoc's native one (bold, lists, comments, …) and folds automatically as the pane narrows;
- after edits, the header shows `● Unsaved changes`; click **Save** to export and atomically write back to the
  opened path;
- state machine: Saving… → Saved / Save failed (failures carry a reason and can be retried); edits made while a
  save is in flight keep the unsaved hint so you can re-save.

### Following outside edits (e.g. an AI agent edited the file)

- **clean** editor: the 3s poll detects the disk change → re-fetches and swaps in place via `replaceFile`,
  re-fitting the zoom;
- **dirty** editor: only a "File changed on disk" banner appears — you decide whether to `Reload` (reloading
  discards the current unsaved edits).

### Coexistence with other viewers

| Viewer | id | priority |
|---|---|---|
| built-in code viewer | `code` | -100 |
| built-in download viewer | `binary-download` | -50 |
| office preview plugin | `docx` | 0 |
| OnlyOffice plugin | `onlyoffice:docx` | 10 |
| **this plugin** | `superdoc:docx` | 10 |

Ties (e.g. with OnlyOffice) break by registration order. Every viewer can be toggled individually under
Settings → Side cards → File preview without affecting the others.

## Architecture

### Two halves

```
browser (client half, tiny CJS bundle via window.__ModuleLoader__)
  └─ ctx.betterSidebar.registerFileViewer('superdoc:docx', exts:['docx'], priority:10, fetchStrategy:'mediaUrl')
      └─ SuperDocView: