Calliper-Compare2Markdown

运行一个 JavaScript 工作流，通过 PDRouter 将两个本地文件提交至 calliper 同步 API（默认调用 POST /openapi/{serviceCode}/compare/markdown），一步式返回 Markdown 格式的差异内容。该技能适用于文档比对、变更提取、合规性检查，以及将结构化差异内容作为输入供给后续脚本处理。

安装

npx skills add PaodingAI/skills

使用方法

node skills/calliper-compare2markdown/scripts/compare_to_markdown.js   [output-markdown-path]

执行约束

• 必须直接调用 scripts/compare_to_markdown.js，不得自行重新实现该 API 调用流程。
• 下方的行为契约说明了该脚本的功能、输出内容及适用场景；它不是供模型逐条模仿的操作清单。
• 对于任何依赖跨文档差异的任务，必须首先运行此脚本，并基于其生成的 Markdown 结果继续后续处理。
• 仅在脚本本身不可用、运行失败或需要修复时，才可查看或修改其实现逻辑；正常使用过程中不得绕过该脚本。

适用场景

• 当用户希望比对两个文档并以 Markdown 格式获取结构化差异结果时，使用本技能。
• 当用户表达类似“diff to markdown”、“compare and output markdown”、“导出差异 markdown”，或明确要求机器可读的差异摘要时，使用本技能。
• 当下游任务依赖文档差异（例如条款抽取、不匹配验证、规则校验等）时，应优先使用本技能。
• 当差异内容仅为中间输入时，建议写入工作文件，并仅提取所需片段，而非返回完整原始 Markdown。
• 当用户明确要求原始 Markdown 差异输出时，直接返回完整 Markdown 内容。

环境变量

• PAODINGAI_API_KEY：脚本优先使用的 Bearer Token。
• CALLIPER_ACCESS_TOKEN：可选备用 Bearer Token，在 PAODINGAI_API_KEY 未设置时启用。
• PD_ROUTER_BASE_URL：可选，默认为 https://platform.paodingai.com/。
• PD_ROUTER_SERVICE_CODE：可选，默认为 calliper。
• PD_ROUTER_COMPARE_ENDPOINT：可选，默认为 /compare/markdown；仅在路由端点不同时使用。
• CALLIPER_COMPARE_CONFIG：可选，JSON 字符串，作为 config 表单字段透传；默认值为 {}。

脚本行为

1. 从 PAODINGAI_API_KEY 读取 Bearer Token；若未设置，则回退至 CALLIPER_ACCESS_TOKEN；若两者均缺失，则报错退出。
2. 校验两个本地输入文件是否存在。
3. 构造一个 multipart 请求，携带 file1、file2 及可选的 config 字段，向 POST /openapi/{serviceCode}{compareEndpoint} 发起调用，请求头包含 Authorization: Bearer 。
4. 解析最终响应并输出：
   • 若响应为 markdown/plain 类型，则直接输出 Markdown 文本；
   • 否则，尝试从常见 JSON 字段（如 data.markdown 或 markdown）中提取 Markdown 内容；若均不存在，则回退为输出原始 JSON 文本。
5. 若提供了 output-markdown-path 参数，则在标准输出打印结果的同时，也将相同内容写入指定路径的文件。
6. 进度信息与错误日志输出至 stderr；执行失败时返回非零退出码。
7. 对于字段或表格抽取类任务，除非用户明确要求完整 Markdown 差异，否则应仅解析并返回所需片段。