> ## 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.

# Using SoMark in DeepSeek Harness

> Install dsh-tool-somark and call SoMark to parse documents in DeepSeek Harness

## Install and configure the SoMark plugin

<Steps>
  <Step title="Install the plugin">
    Make sure [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) is running correctly, then install [`dsh-tool-somark`](https://github.com/SoMarkAI/dsh-tool-somark) into the profile you want to use.

    | Profile        | Installation command                                                      |
    | -------------- | ------------------------------------------------------------------------- |
    | Web            | `dsh plugin --profile web add github:SoMarkAI/dsh-tool-somark`            |
    | Headless       | `dsh plugin --profile headless add github:SoMarkAI/dsh-tool-somark`       |
    | Custom profile | `dsh plugin --profile <profile-name> add github:SoMarkAI/dsh-tool-somark` |

    Restart the profile after installation. The plugin registers the `somark_parse` tool automatically.
  </Step>

  <Step title="Configure the API key">
    We recommend setting the SoMark API key as an environment variable in the terminal that starts DeepSeek Harness.

    <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>
      No API key yet? [Go to the SoMark API workbench to get your API key](https://somark.cn/workbench/apikey). Free quota does not need to be claimed and is automatically credited to your account (500 pages/day, 2000 pages/month).
    </Note>
  </Step>

  <Step title="Configure one profile (optional)">
    If you do not want to use an environment variable, configure the API key in the profile's `cordis.patch.yml`:

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

    <Warning>
      Do not commit a configuration file that contains a real API key.
    </Warning>
  </Step>
</Steps>

***

## Parse documents in DeepSeek Harness

<Steps>
  <Step title="Prepare the document">
    Place the PDF, image, Word, or PPT file in a location that the current DeepSeek Harness workspace can access, and use its absolute path.
  </Step>

  <Step title="Send a parsing instruction">
    Tell the agent which file to parse and what you need. For example:

    * "Use SoMark to parse `/workspace/report.pdf` and summarize the main conclusions."
    * "Parse `/workspace/contract.docx` as Markdown and extract the key clauses."
    * "Parse `/workspace/slides.pptx` and organize the content by section."

    The agent calls `somark_parse` to read the file and waits for SoMark to finish parsing it.
  </Step>

  <Step title="Use the parsed result">
    After parsing finishes, ask the agent to summarize the content, extract fields, organize tables, or save the result as Markdown.
  </Step>
</Steps>

***

## Parameters and outputs

### Input parameters

| Parameter       | Type   | Required | Default            | Description                                                              |
| --------------- | ------ | -------- | ------------------ | ------------------------------------------------------------------------ |
| `path`          | string | ✅        | None               | Absolute path to the document. Supports PDF, image, Word, and PPT files. |
| `outputFormats` | array  | -        | `markdown`, `json` | Return `markdown`, `json`, or both formats.                              |

### Common configuration

Add these fields under the `tool-somark` `config` object. The plugin uses its defaults when you omit them.

| Field            | Description                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| `apiKey`         | SoMark API key. When omitted, the plugin reads `SOMARK_API_KEY` from the environment.                               |
| `baseURL`        | SoMark API Base URL. Enter your service address for a private deployment.                                           |
| `outputFormats`  | Default output formats when a tool call does not provide `outputFormats`.                                           |
| `elementFormats` | Configure the return formats for images, formulas, tables, and chemical structures.                                 |
| `featureConfig`  | Configure cross-page merging, heading recognition, image restoration, image understanding, and headers and footers. |

See the plugin [README](https://github.com/SoMarkAI/dsh-tool-somark#config) for all configuration fields and defaults.

### Outputs

| Output   | Description                                                                                                |
| -------- | ---------------------------------------------------------------------------------------------------------- |
| Markdown | Document content that preserves headings, paragraphs, tables, formulas, images, and other structure.       |
| JSON     | Structured parsing result with text blocks, tables, formulas, images, page numbers, and other information. |

## Notes

* `somark_parse` parses one file per call. Ask the agent to call the tool once per file when processing multiple documents.
* The plugin reads documents through the DeepSeek Harness file system, so the file must be in a location allowed by the current workspace.
* The plugin sends documents to the SoMark API for parsing. Make sure the documents meet your data security and compliance requirements.