Compare two local documents and convert differences into LLM-ready Markdown in one synchronous call. Supports PDF, Word, PPT, and image documents accepted by...
---
name: Calliper-Compare2Markdown
description: Compare two local documents and convert differences into LLM-ready Markdown in one synchronous call. Supports PDF, Word, PPT, and image documents accepted by Calliper, and returns a structured markdown diff table suitable for change review, clause comparison, downstream extraction, and rule-based validation.
metadata: {"author":"PAODINGAI","version":"1.1.0","openclaw":{"emoji":"🔍","requires":{"env":["PD_ROUTER_BASE_URL"],"bins":["node"]}}}
---
# Calliper-Compare2Markdown
Run a JavaScript workflow that submits two local files to the `calliper` synchronous API through PDRouter (`POST /openapi/{serviceCode}/compare/markdown` by default) and returns Markdown diff output in one step. This is suitable for document comparison, change extraction, compliance checks, and feeding structured diff content into follow-up scripts.
## Installation
```bash
npx skills add PaodingAI/skills
```
## Usage
```bash
node skills/calliper-saas-markdown/scripts/compare_to_markdown.js <left-file-path> <right-file-path> [output-markdown-path]
```
## Execution Constraints
- You must invoke `scripts/compare_to_markdown.js` directly. Do not reimplement the API flow yourself.
- The behavior contract below explains what the script does, what it outputs, and when to use it. It is not a manual checklist for the model to imitate step by step.
- For any task that depends on cross-document differences, you must run this script first and continue from the generated Markdown result.
- Only inspect or modify the script implementation when the script itself is unavailable, failing, or needs a fix. Do not bypass it during normal use.
## When to Use
- Use this skill when the user wants to compare two documents and get structured differences in Markdown.
- Use this skill when the user says things like "diff to markdown", "compare and output markdown", "导出差异 markdown", or asks for a machine-readable diff summary.
- When downstream work depends on differences, such as clause extraction, mismatch validation, or rule checks, use this skill first.
- When the diff content is only intermediate input, prefer writing to a working file and extract only required segments instead of returning full raw Markdown.
- When the user explicitly asks for the original markdown diff output, return the full Markdown directly.
## Environment Variables
- `PD_ROUTER_API_KEY`: Preferred bearer token used by the script.
- `CALLIPER_ACCESS_TOKEN`: Optional fallback bearer token when `PD_ROUTER_API_KEY` is absent.
- `PD_ROUTER_BASE_URL`: Optional. Defaults to `https://platform.paodingai.com/`.
- `PD_ROUTER_SERVICE_CODE`: Optional. Defaults to `calliper`.
- `PD_ROUTER_COMPARE_ENDPOINT`: Optional. Defaults to `/compare/markdown`. Use only when routing endpoint differs.
- `CALLIPER_COMPARE_CONFIG`: Optional. JSON string forwarded as `config` form field. Default is `{}`.
## Script Behavior
1. Read bearer token from `PD_ROUTER_API_KEY`; fallback to `CALLIPER_ACCESS_TOKEN`; fail if both are missing.
2. Validate both local input files exist.
3. Send one multipart request with `file1`, `file2`, and optional `config` to `POST /openapi/{serviceCode}{compareEndpoint}` using `Authorization: Bearer <token>`.
4. Parse final response and output:
- Markdown text directly when response is markdown/plain text.
- Otherwise, resolve markdown from common JSON fields (`data.markdown`, `markdown`) or fallback to JSON text.
5. If `output-markdown-path` is provided, also write the same output text to that file while still printing to stdout.
6. Write progress and errors to stderr and return non-zero exit code on failure.
7. For field/table extraction tasks, parse and return only required fragments unless user explicitly asks for the full markdown diff.
don't have the plugin yet? install it then click "run inline in claude" again.