技能介绍

解决什么问题

当两份合同、规范、配置或文本文件发生版本变化时，逐段人工核对容易漏掉条款措辞、字段值、表格单元和合规差异。calliper-compare2markdown 把“提交两个本地文件并拿到可读差异”这一步收敛成一个固定脚本：它通过 PDRouter 调用 calliper 同步接口，默认访问 POST /openapi/{serviceCode}/compare/markdown，最终把 Markdown 差异打印到标准输出。对工程师来说，核心价值不是再实现一次文件比较，而是拿到一个可继续解析的中间产物。

工作方式

固定入口：技能要求直接运行 scripts/compare_to_markdown.js，不要在正常任务中重写 API 流程或绕过脚本。
鉴权与环境：优先读取 PAODINGAI_API_KEY，缺失时回退到 CALLIPER_ACCESS_TOKEN；两者都没有会失败。可选变量包括 PD_ROUTER_BASE_URL、PD_ROUTER_SERVICE_CODE 和 PD_ROUTER_COMPARE_ENDPOINT。
请求形态：脚本校验两个本地输入文件存在后，发送一个 multipart 请求，携带 file1、file2 和可选 config，并附加 Authorization: Bearer 头。
输出解析：如果响应是 Markdown 或纯文本，直接输出；否则尝试从 data.markdown、markdown 等常见 JSON 字段中提取，最后回退到 JSON 文本。
文件落盘：提供 output-markdown-path 时，脚本会把同样内容写入文件，同时继续打印到标准输出。进度和错误写到标准错误，失败时返回非零退出码。

适用边界

适合“把差异导出为 Markdown”“生成可解析的变更摘要”、条款抽取、不匹配校验、规则检查等下游任务。若 Markdown 只是中间输入，建议先写入工作文件，再只抽取需要的片段；只有用户明确要求原始完整 diff 时，才直接返回全量 Markdown。若接口路由、服务码或端点与默认不同，需要按环境调整变量，而不是修改脚本逻辑。