dsh-ocr-seam-guard

Readme

# dsh-ocr-seam-guard

Self-healing guard for the [dsh-ocr](https://github.com/CraZY222123/dsh-ocr-plugin) plugin on
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): automatically re-applies the
local patches that `npm i -g @deepseek-ai/dsh` upgrades (or a plugin re-install) wipe out.

中文说明见下方。

## What it guards

The dsh-ocr plugin needs three fixes that live OUTSIDE the profile (so profile reconcile never
touches them, and a harness upgrade wipes the adapter one):

| Fix | File | Wiped by |
|---|---|---|
| The `ocr` service seam in the official `dsh-llm-deepseek` adapter | `<dsh package>/node_modules/@deepseek-ai/dsh-llm-deepseek/lib/index.js` | `npm i -g @deepseek-ai/dsh` upgrade |
| UTF-8 stdout enforcement for the Python OCR subprocess | `<DSH_HOME>/profiles/node_modules/@deepseek-ai/dsh-ocr/lib/index.js` | plugin re-install |
| rapidocr 1.2.3 API fix (`text_det`→`text_detector`, `text_rec`→`text_recognizer`) | `<DSH_HOME>/profiles/node_modules/@deepseek-ai/dsh-ocr/tools/ocr_image.py` | plugin re-install |

## How it works

On every harness boot the plugin checks the three sites. A missing fix is re-applied with anchored
string replacements — **every anchor must match exactly once or the whole site is skipped** (never a
partial patch) — then the patched module is import-verified in a child `node` process. A failed
verification rolls the file back and reports the error. If the upstream code shape is unknown
(anchors drifted), the guard does nothing but log.

When a fix is (re-)applied, the running process already holds the old module — **restart dsh once
more to activate**.

## Install

```sh
dsh plugin --profile web add github:YOURNAME/dsh-ocr-seam-guard
# or from a local clone:
dsh plugin --profile web add file:D:/path/to/dsh-ocr-seam-guard
```

Restart dsh. The guard logs its status on every boot:

- `adapter seam: ok` — everything in place
- `adapter seam: patched` — just re-applied; restart once to activate
- `adapter seam: skipped` — upstream code drifted, human review needed

## Upgrade flow

```
npm i -g @deepseek-ai/dsh   # upgrade wipes the adapter patch
restart dsh                 # guard auto-patches at boot (log: "restart once")
restart dsh again           # patch active
```

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `DSH_OCR_ADAPTER_FILE` | auto-detect (npm global root) | override the adapter file path |

The adapter is located via `npm root -g` with a fallback to the platform npm global directory;
only npm-global dsh installs are supported out of the box.

## License

MIT.