> ## Documentation Index
> Fetch the complete documentation index at: https://docs.somark.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 DeepSeek Harness 中使用

> 安装 dsh-tool-somark 插件，在 DeepSeek Harness 中调用 SoMark 解析文档

## 安装并配置 SoMark 插件

<Steps>
  <Step title="安装插件">
    确认 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 已可正常运行，再将 [`dsh-tool-somark`](https://github.com/SoMarkAI/dsh-tool-somark) 安装到需要使用的 profile。

    | Profile     | 安装命令                                                                      |
    | ----------- | ------------------------------------------------------------------------- |
    | Web         | `dsh plugin --profile web add github:SoMarkAI/dsh-tool-somark`            |
    | Headless    | `dsh plugin --profile headless add github:SoMarkAI/dsh-tool-somark`       |
    | 自定义 profile | `dsh plugin --profile <profile-name> add github:SoMarkAI/dsh-tool-somark` |

    安装完成后，重新启动对应的 profile。插件会自动注册 `somark_parse` 工具。
  </Step>

  <Step title="配置 API Key">
    推荐在启动 DeepSeek Harness 的终端中通过环境变量配置 SoMark API Key。

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        export SOMARK_API_KEY="sk-..."
        dsh --profile web
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        $env:SOMARK_API_KEY = "sk-..."
        dsh --profile web
        ```
      </Tab>
    </Tabs>

    <Note>
      还没有 API Key？[前往 SoMark API 工作台获取 API Key](https://somark.cn/workbench/apikey)。免费额度无需领取，会自动发放到账户（每日 500 页、每月 2000 页）。
    </Note>
  </Step>

  <Step title="按 profile 配置（可选）">
    如果不使用环境变量，也可以在该 profile 的 `cordis.patch.yml` 中配置 API Key：

    ```yaml theme={null}
    - id: tool-somark
      config:
        apiKey: "sk-..."
    ```

    <Warning>
      请勿将包含真实 API Key 的配置文件提交到 Git 仓库。
    </Warning>
  </Step>
</Steps>

***

## 在 DeepSeek Harness 中解析文档

<Steps>
  <Step title="准备文档">
    将待解析的 PDF、图片、Word 或 PPT 文件放在当前 DeepSeek Harness 工作区可访问的位置，并确认文件路径为绝对路径。
  </Step>

  <Step title="发送解析指令">
    在对话中直接告诉 Agent 要解析的文件和处理目标。例如：

    * “使用 SoMark 解析 `/workspace/report.pdf`，总结主要结论。”
    * “把 `/workspace/contract.docx` 解析成 Markdown，并提取关键条款。”
    * “解析 `/workspace/slides.pptx`，按章节整理内容。”

    Agent 会调用 `somark_parse` 读取文件并等待 SoMark 完成解析。
  </Step>

  <Step title="使用解析结果">
    解析完成后，您可以继续让 Agent 总结内容、提取字段、整理表格，或将结果保存为 Markdown 等格式。
  </Step>
</Steps>

***

## 插件参数与输出

### 输入参数

| 参数              | 类型     | 必填 | 默认值                | 说明                                  |
| --------------- | ------ | -- | ------------------ | ----------------------------------- |
| `path`          | string | ✅  | 无                  | 待解析文档的绝对路径。支持 PDF、图片、Word 和 PPT 文件。 |
| `outputFormats` | array  | -  | `markdown`, `json` | 选择返回 `markdown`、`json`，或同时返回两种格式。   |

### 常用配置

以下配置写在 `tool-somark` 的 `config` 中。未填写时使用插件默认值。

| 配置项              | 说明                                          |
| ---------------- | ------------------------------------------- |
| `apiKey`         | SoMark API Key；未配置时读取环境变量 `SOMARK_API_KEY`。 |
| `baseURL`        | SoMark API Base URL。私有化部署时填写自建服务地址。         |
| `outputFormats`  | 工具调用未传入 `outputFormats` 时使用的默认输出格式。         |
| `elementFormats` | 配置图片、公式、表格和化学结构式的返回格式。                      |
| `featureConfig`  | 配置跨页拼接、标题层级识别、图片还原、图片理解和保留页眉页脚等能力。          |

完整配置项与默认值请查看插件仓库的 [README](https://github.com/SoMarkAI/dsh-tool-somark#config)。

### 返回结果

| 返回内容     | 说明                            |
| -------- | ----------------------------- |
| Markdown | 保留标题、段落、表格、公式和图片等结构的文档内容。     |
| JSON     | 包含文本块、表格、公式、图片、页码等信息的结构化解析结果。 |

## 注意事项

* `somark_parse` 一次解析一个文件。需要处理多个文件时，请让 Agent 逐个调用工具。
* 插件通过 DeepSeek Harness 的文件系统读取文档，因此文件需要位于当前工作区允许访问的位置。
* 插件会将文档发送到 SoMark API 进行解析，请确认文档符合您的数据安全与合规要求。