dsh-simpletex-ocr

Readme

# dsh-simpletex-ocr

SimpleTex 专用 OCR / 公式识别插件。把 SimpleTex 的「公式识别」和「通用 OCR」接成 DSH Web GUI 里的一个模型工具 `simpletex_recognize`，并带上**输入框拖图/粘贴、对话内缩略图、GUI 配置卡**三件套。

## 特性

- 一个工具、三种模式：
  - `formula` → 返回 LaTeX + 置信度
  - `text` → 返回 Markdown
  - `auto`（默认）→ 按 `question` 关键词自动选公式还是文字
- 输入框**拖图 / 粘贴 / 选图**直接发，正文里显示成可点击缩略图
- **设置 → 插件配置 → SimpleTex OCR** 里填 API Key：密码框不回显、密钥只写本机凭证服务，不落明文设置文件
- 图片先校验类型与大小再上传，超限/非图片给清晰报错
- 仓库**不含任何密钥**（默认值只有公开的官方端点地址）

## 准备工作

- 一台装了 DSH Web GUI 的机器
- 一个 SimpleTex 账号的 **API Key**（SimpleTex 官网把 API Key 叫做 **Token**，是 `AT` 开头的一串）

## 获取 SimpleTex API Key

1. 打开 https://simpletex.cn 注册并登录；
2. 在账号/控制台里申请 **API Token**（`AT` 开头）；
3. 复制备用。

> 官网文案里叫「Token」，和本文说的「API Key」是同一个东西。

## 快速开始

```bash
dsh plugin --profile web add https://github.com/Huoer9527/dsh-simpletex-ocr.git
```

> 一行就够：仓库在 `package.json` 里声明了 `dsh.bundle`，「安装 + 自动登记」一步完成，不用跑脚本。
> 本地开发 / 无网络时，也可以 `git clone` 后跑 `bash install.sh` 备用。

然后重启：

```bash
dsh web
```

浏览器打开 **设置 → 插件配置 → SimpleTex OCR**，展开卡片，把 API Key 粘进去、点「保存」。之后就可在对话里让模型识别图片了。

## 工具用法

工具名：`simpletex_recognize`

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `image` | string | 是 | 本地图片路径、`http(s)` URL、`data:` URI，或拖图后生成的附件引用 |
| `task` | `formula` / `text` / `auto` | 否 | 默认 `auto` |
| `question` | string | 否 | `auto` 模式下用来判断该走公式还是文字 |

示例：

```js
simpletex_recognize({ image: '公式.png', task: 'formula' })
simpletex_recognize({ image: '截图.png' })                                    // 默认 auto
simpletex_recognize({ image: '公式.png', task: 'auto', question: '把公式转成 LaTeX' })
```

返回：

| task | 返回 |
|---|---|
| `formula` | `{ engine, task: 'formula', text: LaTeX, conf: 置信度 }` |
| `text` | `{ engine, task: 'text', text: Markdown }` |

## 拖图怎么用

输入框点图片按钮（或拖图/粘贴）→ 发送时插件自动把图传到本机 `/simpletex-ocr/attach`，在正文里生成 `![图片](/simpletex-ocr/raw/<id>)`；模型读到这个引用，把 `<id>` 交给 `simpletex_recognize` 就能识别。图片字节只在附件存储里，不进聊天气泡。

## 配置

GUI 卡只管 **API Key**（写入凭证服务 `SIMPLETEX_TOKEN`）。

高级项（端点 / rec_mode / 大小上限 / 超时）用默认值即可；需要定制时编辑 `~/.dsh/profiles/web/settings.yaml`：

```yaml
simpletex-ocr:
  tokenEnv: SIMPLETEX_TOKEN                                     # 从哪个凭证名读 API Key
  endpointFormula: https://server.simpletex.cn/api/latex_ocr_turbo
  endpointText: https://server.simpletex.cn/api/simpletex_ocr
  recMode: auto
  enableImgRot: true
  maxBytes: 10485760                                            # 图片字节上限（10 MB）
  timeoutMs: 60000
```

Key 解析优先级：`settings.yaml` 里的 inline `token` → 凭证服务 `SIMPLETEX_TOKEN`（GUI 保存的就是这个）→ 启动环境变量。找不到 Key 时，第一次调用会给出明确报错，不会影响宿主。

## 常见问题

- **安装/改配置后没反应** → 重启 `dsh web`，浏览器 `Ctrl+Shift+R` 硬刷新。
- **报「未配置 API Key」** → 到「设置 → 插件配置 → SimpleTex OCR」填 Key 保存。
- **识别报「未识别到公式」** → 图里可能没有公式，改 `task: 'text'` 试试。
- **改了 `settings.yaml` 不生效** → 同样要重启 `dsh web`。

## 文件结构

```
lib/
  index.js             # 宿主入口：注册工具 + 附件路由
  simpletex-client.js  # SimpleTex 调用（fetch + FormData）
  attach-routes.js     # /simpletex-ocr/attach 与 /raw/<id>
  config-resolve.js    # 配置 schema 与 Key 分层解析
  media.js             # 图片类型/大小/base64 校验
  client.js            # 浏览器半：拖图重写 + 插件配置里的 API Key 设置卡
cordis.patch.yml       # 组合包 patch（package.json 的 dsh.bundle.patch 指向它）
package.json
install.sh
```

## 致谢

- 拖图/设置卡交互思路参考 `dsh-web-ui` 的 describe-image 插件
- SimpleTex：https://simpletex.cn

## 许可证

[MIT](./LICENSE)