# ChemDraw Bridge · 中文操作说明

这个插件把化合物身份或文献结构变成**可直接编辑的 ChemDraw 源文件**，目前有八个工具：

| 工具 | 用途 |
| --- | --- |
| `search_compounds` | 名称模糊搜索，返回候选（CID、CAS、分子式、来源、匹配度） |
| `import_scifinder` | 读取登录 SciFinder 后导出的 SDF/CSV，返回结构候选 |
| `recognize_image` | 对没有名称的结构图做识图，返回 SMILES 候选 |
| `draw_from_identifier` | 已知 **CAS 号 / 英文名 / CID / SMILES**，生成结构 |
| `draw_reaction` | 由反应物/产物 SMILES 生成一步反应式草稿 |
| `draw_from_paper` | 给一篇**论文或补充材料 PDF**和化合物编号（如 `3a`），从文献里提取结构 |
| `chemdraw_convert` | 用 ChemDraw 在 CDXML/CDX/MOL/SDF/PNG/SVG 之间转换 |
| `insert_chemdraw` | 把真正的 ChemDraw OLE 对象插入 Word/PowerPoint，保持可编辑 |

输出文件：

- `.cdxml`：ChemDraw 原生 XML 源文件，双击即可打开、编辑；
- `.cdx`：ChemDraw 二进制源文件，适合在 Word 里作为 ChemDraw 对象插入；
- `.meta.json`：生成记录，含来源、CAS/CID、分子式、InChIKey、SMILES、ChemDraw 版本和校验结果。

---

## 1. 最快用法：直接在对话里说

不需要记参数，直接描述即可：

- “用 `draw_from_identifier` 生成 **50-78-2**，要 cdx”
- “先用 `search_compounds` 搜一下 **asprin**，把候选列出来让我选”
- “帮我画**阿司匹林**，CAS 50-78-2，只要 cdxml”
- “生成**胆固醇**的 ChemDraw 源文件”
- “从 **10.1039/c7cc02426f** 这篇文献的 SI 里提取 **3a**，PDF 在 `E:\...\source-si.pdf`”

模型会调用对应工具，并把生成的文件路径返回给你。

---

## 2. 工具一：`draw_from_identifier`

### 参数

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `identifier` | 是 | CAS 号（如 `50-78-2`）、英文/IUPAC 名（如 `aspirin`）、`CID:2244` 或 `SMILES:<smiles>` |
| `output_dir` | 否 | 输出目录；默认是当前工作目录下的 `chemdraw` |
| `file_name` | 否 | 文件名（不含扩展名）；默认“标题 (CID xxx)” |
| `also_cdx` | 否 | 同时输出 `.cdx`，默认 `false` |
| `overwrite` | 否 | 覆盖同名文件；默认 `false`，重名会自动加 `(2)`、`(3)` |
| `auto_select` | 否 | 多个模糊候选时直接取匹配度最高的一个，不弹选择；默认 `false` |

### 模糊搜索与选择

名称不必拼得完全准确：

1. 插件先用 PubChem 自动补全，并对较短前缀再做几次探测，以覆盖常见拼写错误（`asprin` → `aspirin`，`caffiene` → `caffeine`）；
2. 再用 ChemicalBook 做补充搜索（它没有公开 API，失败时自动跳过）；
3. 只有一个精确匹配时，直接生成；
4. 有多个候选时，`draw_from_identifier` 会返回候选列表，并提示先用 `search_compounds`；
5. 操作者在候选中选定一个后，用对应的 `CID:<cid>` 再调用 `draw_from_identifier`。

CAS 号和显式 CID 不参与模糊匹配，直接精确处理。

SciFinder 的网页 API 需要 OAuth/ELN 授权，返回的是 SciFinder 网页里的路径，不是结果数据；所以采用“登录后导出、插件读取”的方式，结构最可靠。

### SciFinder 导出

1. 在已登录的 SciFinder 中检索并选中目标化合物；
2. 导出 **SDF**（首选，带权威结构）或带 CAS 号的 **CSV/TSV**；
3. 调用 `import_scifinder(file_path="...")`；
4. 操作者从候选里选择；
5. 用 `draw_from_identifier(identifier="SMILES:<smiles>")` 生成，CSV 已解析出 PubChem CID 时也可用 `CID:<cid>`。

支持 `.sdf`、`.csv`、`.tsv`、`.txt`。SDF 用 RDKit 读取，ChemDraw 生成后再核对 CDXML，不依赖名称查库。

### 识图与反应式

没有 IUPAC 名称的结构图，可以先裁剪成清晰图片再识图：

```text
recognize_image(image_path="E:\\figs\\compound.png")
recognize_image(pdf_path="E:\\paper.pdf", page=5, box=[100, 200, 360, 430])
recognize_image(image_path="E:\\figs\\compound.png", expected_formula="C20H15N3O4")
```

OSRA 识别后用 RDKit 校验，返回 SMILES/分子式候选。**这是候选，不是已确认的身份**：手性、电荷、同位素和缩写基团都可能识别错；`PhthN`、`MQ`、`Boc` 这类缩写无法从像素还原，工具会拒绝而不是猜。确认后再用 `draw_from_identifier(identifier="SMILES:<smiles>")` 生成。

如果知道分子式，传入 `expected_formula` 会做硬校验；识图结果分子式不符时直接拒绝，避免漏画/多画一个碳。

有一组确定的反应物/产物 SMILES 时，可以画一步反应式草稿：

```text
draw_reaction(
  reactants=["CCO"],
  products=["CC=O"],
  conditions="10 mol% Pd(OAc)2\n1.5 equiv AgBF4\nt-BuOH/DCE, 75 °C, 24h",
  yield_text="82%",
  also_cdx=true
)
```

`conditions` 支持用 `\n` 分成多行，每行会居中放在箭头上方。

### 与化学软件、Word/PowerPoint 配合

`chemdraw_convert` 用 ChemDraw 本身做格式转换：

```text
chemdraw_convert(
  file_path="E:\\chemdraw\\3a.cdxml",
  output_path="E:\\chemdraw\\3a.mol"
)
```

- 输入：`.cdxml`、`.cdx`、`.mol`、`.sdf`
- 输出：`.cdxml`、`.cdx`、`.png`、`.svg`、`.mol`、`.sdf`
- `.mol/.sdf` 可以给 Avogadro、PyMOL、OpenBabel、RDKit 类工具继续用；`.png/.svg` 可以给 Origin、PowerPoint 或投稿系统用。

`insert_chemdraw` 把真正的 ChemDraw OLE 对象插入文档，不是贴图：

```text
insert_chemdraw(
  file_path="E:\\chemdraw\\3a.cdxml",
  target_path="E:\\paper\\manuscript.docx"
)
```

- 目标支持 `.docx` 和 `.pptx`；文件不存在会自动新建；
- PowerPoint 可以用 `slide` 指定页码，默认新建一页；
- 插入后双击对象即可回到 ChemDraw 编辑；
- 会按页面/幻灯片大小等比缩放。

注意：ChemDraw 的 `SaveAs` 不能稳定直接写 PDF，所以 `chemdraw_convert` 不提供 PDF；需要 PDF 时先出 SVG/PNG，或从 Word/PowerPoint 导出。

### 论文排版

结构先用 RDKit CoordGen 生成紧凑的二维坐标，再由 ChemDraw 套统一格式：

- Arial 9 pt 原子标签；
- 0.4 cm（20 pt）键长；
- 0.6 pt 线宽；
- 10 pt 键间距、1 pt 边距；
- 反应式箭头更紧凑，条件和收率 9 pt，加号连排。

这些设置写进 CDXML，结构仍然可编辑，不是扁平图片。

### 输入规则

1. **CAS 号最可靠**。插件会先算 CAS 校验位，校验位错误直接拒绝；再到 PubChem 查，并要求该 CAS 出现在对应记录的同义词里。
2. **英文/IUPAC 名**会先做模糊搜索；有多个候选时由操作者选择，不会直接猜一个。只有一个精确匹配时才直接生成。
3. **中文名**会先尝试 ChemicalBook；最可靠的输入仍是 CAS 号。

### `search_compounds`

只想先看候选、不生成文件时，可以单独调用：

```text
search_compounds(query="asprin", limit=6)
```

返回按匹配度排序的候选，含 CID、CAS、分子式、来源和匹配度。把候选展示给操作者，选定后用对应的 `CID:<cid>` 调用 `draw_from_identifier`。

### `import_scifinder`

```text
import_scifinder(file_path="E:\\...\\scifinder-export.sdf", query="aspirin")
```

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `file_path` | 是 | SciFinder 导出的 `.sdf`（首选）、`.csv`、`.tsv` 或 `.txt` |
| `query` | 否 | 用于标注/排序的可选名称 |
| `limit` | 否 | 最多候选数，1–20，默认 10 |

返回候选，每个候选带 `SMILES`；选择后用 `draw_from_identifier(identifier="SMILES:<smiles>")` 生成。CSV 已解析出 PubChem CID 时也可用 `CID:<cid>`。

### 示例

```text
draw_from_identifier(identifier="50-78-2", also_cdx=true)
```

```text
draw_from_identifier(identifier="aspirin", output_dir="E:\\ds\\chemdraw")
```

```text
draw_from_identifier(identifier="CID:2244", file_name="阿司匹林")
```

---

## 4. 文献工具：`draw_from_paper`

### 参数

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `source` | 是 | DOI（如 `10.1039/c7cc02426f`）、PDF 直链，或本地 PDF 路径 |
| `compound` | 是 | 文献里的编号（`3a`、`compound 7`），或完整 IUPAC 名 |
| `local_pdf` | 否 | 本地论文/SI 的 PDF 路径；**出版社拦截下载时必填** |
| `output_dir` | 否 | 输出目录 |
| `file_name` | 否 | 文件名；默认用化合物编号 |
| `also_cdx` | 否 | 同时输出 `.cdx` |
| `overwrite` | 否 | 覆盖同名文件 |

### 提取流程

```text
PDF/SI
  → 找到“3a”这样的编号
  → 取它前面的 IUPAC 名称
  → OPSIN 把名称转成 SMILES
  → RDKit 独立计算分子式和 InChIKey
  → 与 SI 中的 HRMS 分子式交叉核对
  → ChemDraw 生成 .cdxml / .cdx
```

只有名称能唯一解析、且校验通过才输出；失败会明确报错，不会猜一个结构给你。

### 示例

```text
draw_from_paper(
  source="10.1039/c7cc02426f",
  compound="3a",
  local_pdf="E:\\ds\\chemdraw-samples\\literature\\source-si.pdf",
  also_cdx=true
)
```

### 出版社 PDF 下不下来怎么办

很多出版社（RSC、ACS、Wiley 等）会拦截自动下载。此时：

1. 用学校账号从出版社网页下载论文或 SI 的 PDF；
2. 把路径传给 `local_pdf`；
3. `source` 仍填 DOI，元数据里会记录 DOI 和标题。

---

## 4. 输出文件怎么用

### 在 ChemDraw 里继续编辑

双击 `.cdxml`，或 ChemDraw 里“文件 → 打开”。所有键、原子、电荷、手性楔形键都是可编辑对象。

### 插入 Word

推荐用 `.cdx`：

1. 调用时加 `also_cdx=true`；
2. Word 里“插入 → 对象 → 由文件创建”，选 `.cdx`；
3. 双击对象即可回到 ChemDraw 编辑。

`.cdxml` 也可以打开后另存为 `.cdx`，但直接生成 `.cdx` 更省事。

### 元数据

`.meta.json` 记录：

- 来源：PubChem URL 或 DOI；
- 化合物：CAS、CID、分子式、InChIKey、SMILES；
- 校验：重原子数、元素组成、键数、ChemDraw 版本；
- 文献模式还会记录：IUPAC 名、OPSIN InChIKey、RDKit InChIKey、HRMS 分子式。

写论文时如果日后要核对结构来源，看这个文件即可。

---

## 5. 精度规则（为什么可以放心用）

### 已知化合物

- CAS 校验位本地计算；
- CAS 必须出现在 PubChem 同义词中；
- 名称必须与标题/IUPAC/同义词精确匹配；
- 结构由 PubChem 的 isomeric SMILES 生成，保留手性、E/Z、电荷、盐。

### 文献化合物

- 名称由 OPSIN 解析，RDKit 独立复算 InChIKey；
- 两者不一致直接失败；
- SI 中有 `calc. for C27H19N3O4` 这类 HRMS 时再做分子式核对（Na/K/Li 加合物会自动扣除）；
- 生成后再解析 CDXML，核对元素组成和重原子数。

### 失败时的行为

- 生成的 CDXML 与源 SMILES 不一致：删除文件并报错；
- CAS 校验位错误：不联网，直接拒绝；
- 名称模糊：默认拒绝，并列出候选 CID；
- 文献中找不到 IUPAC 名：拒绝，不猜图。

---

## 6. 常见问题

| 现象 | 原因与处理 |
| --- | --- |
| 名称拼错/出现多个候选 | 先用 `search_compounds` 查看候选，让操作者选择，再用 `CID:<cid>` 生成 |
| SciFinder 怎么接 | 登录 SciFinder 后导出 SDF（首选）或带 CAS 的 CSV，用 `import_scifinder` 读取，再用 `SMILES:<smiles>` 生成 |
| “PubChem 中没有找到名称” | 中文名可先试 ChemicalBook；检查英文拼写，或改用 CAS |
| “CAS 校验位不正确” | 号码抄错；按提示的正确校验位核对 |
| “无法自动下载 PDF” | 出版社限制；下载 PDF 后用 `local_pdf` |
| “没有候选名称能被 OPSIN 解析” | SI 里没有 IUPAC 名，或编号不对；换编号或直接给完整 IUPAC 名 |
| “没有找到与 3a 对应的 IUPAC 名称” | 该编号可能只在主文图里，SI 没有实验名称；尝试其他编号 |
| “ChemDraw 在 save-cdxml 失败” | ChemDraw 未安装/未激活，或文档被占用；重试并确认 ChemDraw 能正常打开 |
| 中文/带空格路径失败 | 已处理：插件在 ASCII 临时目录生成，再由 Node 移动到目标路径；仍失败请把完整报错发我 |
| ChemDraw 已经开着 | 插件会附着到现有实例，只关闭自己创建的文档，不会退出你的 ChemDraw |
| 输出的结构方向不理想 | 是 ChemDraw 对 SMILES 的自动排版，化学上正确；可在 ChemDraw 里手动 Clean Up 或旋转 |

---

## 7. 限制

- **纯图片、没有 IUPAC 名**的化合物可以用 `recognize_image` 出候选，但结果必须人工核对；像 `PhthN`、`MQ`、`Boc` 这种缩写结构 OCR 无法可靠还原，工具会拒绝而不是猜。
- `draw_reaction` 输出的是排版草稿，箭头方向、条件、化学计量和产物需要人工核对。
- 有机金属配合物（如二茂铁）原子组成正确，但 ChemDraw 不会自动补金属–环配位键，需要手动加。
- PubChem 没有 SMILES 的记录（某些聚合物、混合物、材料）无法生成。
- 结构排版用 RDKit CoordGen，再由 ChemDraw 套 Arial 9 pt、0.4 cm 键长、0.6 pt 线宽；个别极大分子仍可能需要手动整理。
- 文献模式需要联网访问 OPSIN；不需要 API key。

---

## 8. 命令行用法（可选）

已知化合物：

```powershell
node E:\ds\dsh-plugin-chemdraw-bridge\tools\cli.mjs "50-78-2" --out "E:\ds\chemdraw" --cdx
node E:\ds\dsh-plugin-chemdraw-bridge\tools\cli.mjs "cholesterol" --cdx
node E:\ds\dsh-plugin-chemdraw-bridge\tools\cli.mjs "CID:2244" --name aspirin
```

文献模式目前通过对话里的 `draw_from_paper` 工具调用；CLI 暂未封装文献参数。

---

## 9. 配置

在插件的 `cordis.patch.yml` 里可以改：

```yaml
- insert:
    - id: chemdraw-bridge
      name: '@local/dsh-plugin-chemdraw-bridge'
      config:
        outputDir: 'E:\ds\chemdraw'
        alsoCdx: true
        timeoutMs: 180000
        pythonPath: 'E:\ds\dsh-plugin-chemdraw-bridge\vendor\venv\Scripts\python.exe'
```

| 配置 | 说明 |
| --- | --- |
| `outputDir` | 默认输出目录 |
| `alsoCdx` | 是否默认同时输出 `.cdx` |
| `timeoutMs` | ChemDraw 转换超时，默认 120000 毫秒 |
| `pythonPath` | 结构排版、文献、SciFinder 用的 Python；默认用 `vendor/venv`（先运行 `scripts/setup-python.ps1`） |

---

## 10. 示例与验证

- 已知化合物示例：`E:\ds\chemdraw-samples\`
- 文献提取示例：`E:\ds\chemdraw-samples\literature\`
  - `3a`、`5a`、`6a` 的 `.cdxml/.cdx/.meta.json`
  - `source-si.pdf`：原始 Supporting Information
- 验证记录：`E:\ds\dsh-plugin-chemdraw-bridge\VERIFICATION.md`

文献示例的三个结构都做过 `CDXML → MOL → RDKit InChIKey` 复核，与 OPSIN 结果完全一致：

- 3a：`QWWIAFJZFCQLMC-ZEQRLZLVSA-N`
- 5a：`UCGNPBFEYVSMOX-IRXDYDNUSA-N`
- 6a：`KWJQIHWFBQBREO-MSOLQXFVSA-N`

---

## 11. 安装

1. 把仓库克隆或下载到本地目录；
2. 首次使用先运行 Python 环境脚本（CoordGen 论文排版、`draw_from_paper` 和 `import_scifinder` 都需要）：

   ```powershell
   powershell -ExecutionPolicy Bypass -File scripts\setup-python.ps1
   ```

3. 在 DeepSeek Harness 里把这个目录作为 bundle 安装：

   ```text
   plugin_manager install_bundle(target="E:\\path\\to\\chemdraw-bridge")
   ```

4. 确认 `chemdraw-bridge` 插件行已启用。

5. 需要识图时，再安装本地 OCR 组件：

   ```powershell
   powershell -ExecutionPolicy Bypass -File scripts\setup-osra.ps1
   ```

`vendor/venv` 和 `vendor/osra` 不会提交到仓库，由 setup 脚本创建。

## 12. 环境要求

- Windows；
- ChemDraw 已安装并激活（当前测试版本：ChemOffice 2022 / ChemDraw 22.0.0.22）；
- `insert_chemdraw` 需要 Microsoft Word 或 PowerPoint（可选；不装也能生成结构和转换格式）；
- 联网访问 PubChem、ChemicalBook；文献模式还需访问 OPSIN；
- 不需要 API key；
- 结构排版、文献提取和 SciFinder 导入需要一个带 PyMuPDF + RDKit 的 Python 环境。首次使用先运行：
  ```powershell
  powershell -ExecutionPolicy Bypass -File scripts\setup-python.ps1
  ```
  它会在 `vendor/venv` 创建环境并安装 `requirements.txt`。
- 识图功能需要 OSRA；首次使用运行：
  ```powershell
  powershell -ExecutionPolicy Bypass -File scripts\setup-osra.ps1
  ```

## 13. 更新日志

见 [CHANGELOG.md](CHANGELOG.md)。1.2.0 加入了 ChemDraw 格式转换和 Word/PowerPoint OLE 插入；1.1.0 加入了 CoordGen 论文级排版、识图、反应式草稿和 SciFinder 导出读取。