交叉引用skill

概述

docx 交叉引用重建 Pay Skill（docx-crossref）

把 Word 文档里的「死文本」引文重建为可点击的内部交叉引用：

参考文献 [1] / [1,2,3]、著者-年 Author (Year)、图/表/公式 图 1 / Table 2 / 式 (1)。

引擎在服务端完成书签 + HYPERLINK 域重建（Word / WPS 双兼容），¥2.00/次，微信支付 X402 结算。

支持的输入与输出

典型来源：pandoc / MinerU / LaTeX→Word / AI 写作 / OCR 产出的 docx。输出不损坏原文档：书签缺失或自引用自动退化为纯文本，绝不生成死链。

mode 参数：all（默认，参考文献+图表公式全做）/ refs_only（仅参考文献书签与引文链接）。

⚙️ 前置要求

• weixinpay 插件已安装启用（未安装则无法调起支付，先提示用户安装）；
• 输入为 .docx 且非空；文档应已具备可识别的引用结构（[N] 编号文献列表、图/表/式 N 题注等）；
• 环境无法上传 docx 附件时（部分网页沙箱不开放文件附件）：改走 docx_base64 JSON 通道——由 Agent 将本地 docx 读取并 base64 编码后放入 JSON body 提交（见调用方式），与文件上传通道的解析、计费、输出完全一致。

🎯 场景路由

用户意图
 ├─ 首次重建新文档             → 工作流 A（首次调用）
 ├─ 支付后取结果 / 重试          → 工作流 B（携订单号重试）
 ├─ 拿到结果后怎么交付/复核       → 工作流 C（交付与统计复核）
 └─ 判断某个响应该怎么处理       → 响应处理对表

🔧 调用方式

POST https://pay.xuesongskill.online/v1/xref   # 交叉引用重建（计费入口）

请求参数（二选一）：

① multipart/form-data 文件上传：

② JSON（沙箱无附件降级通道）：

curl -X POST https://pay.xuesongskill.online/v1/xref 
  -H "X-User-Id: user-123" -H "Content-Type: application/json" 
  -d '{"docx_base64": "<docx 的 base64>", "mode": "all"}'

通用响应结构：

• 200 → {"product": "docx-crossref", "docx_base64": "…", "stats": {…}, "paid": true, "out_trade_no": "…"}
• 402 → body 含 code（PAYMENT_REQUIRED / NOT_PAID / REFUNDED…），响应头含 X-Out-Trade-No
• 400/500 → {"error": "…"}

常见工作流

• 工作流 A · 首次调用：前置检查 → POST /v1/xref → 按响应处理对表行动。示例：

  curl -F "file=@paper.docx" -F "mode=all" 
    -H "X-User-Id: user-123" https://pay.xuesongskill.online/v1/xref

• 工作流 B · 支付后重试：用户支付完成 → 请求体不变，附加 X-Out-Trade-No: <订单号> 头重试（≤3 次）→ 200 取结果。
• 工作流 C · 交付与统计复核：docx_base64 解码写入 .docx 交付 → 向用户展示 stats 统计（各类型书签/链接数量）→ 按「统计复核」一节判断是否需提示用户人工核对 → 告知扣费（already_fulfilled=true 为幂等缓存命中，正常交付）。

📊 统计复核（交付前必做）

响应 stats 字段（均为数量）：

复核规则：

• 某类为 0 但文档明显有该类引用（如正文有 图 1 但 figure_bookmarks=0）→ 如实告知用户该类未能重建及可能原因（无对应题注/编号不连续），提示人工核对，不要声称全部完成。
• ref_bookmarks ≥ 1 而 inline_citations = 0 → 文献书签已建但正文引文未链接，如实说明。

⚠️ 核心规则

• 🚨 X-Out-Trade-No 必须在收到 402 时立即保存——它是重试的唯一凭证，丢失则本次支付作废、需重新付费。
• 🚨 重试请求体必须与首次完全一致（同一 file + 同一 mode），否则服务端无法回查订单。
• 🚨 同一任务复用同一订单号（幂等不重复扣费），严禁为同一任务重新下单。
• 🚨 重试上限 3 次仍 NOT_PAID → 如实告知用户支付未完成，引导重新发起。
• 🚨 无法支付时严禁手动替代：环境无 weixinpay 插件或用户拒绝支付 → 如实告知"本 Skill 为付费服务（¥2.00/次），当前环境无法调起微信支付"并终止；不得凭自身知识手动改写文档内部 XML 替代引擎输出。
• 🚨 按统计如实交付：stats 异常（见复核规则）时必须如实告知用户，不得夸大"全部完成"。

响应处理对表

排查步骤：① 按上表匹配 HTTP 状态码与 code 字段；② 确认 X-Out-Trade-No / X-User-Id 头已携带且值正确；③ 确认 weixinpay 插件授权状态。

已知边界（如实说明）

• 著者-年匹配为 best-effort：多作者、et al.、中英混排的复杂著者-年引用由引擎模糊匹配，可能漏链或错链——交付时按统计复核提示用户核对，不承诺 100% 准确。
• 不解析 / 不格式化文献条目本身：只重建跳转链接，不把杂乱文献规范成 GB/T 7714 体例（那是 docx-gb7714 的范畴；两者可先格式化文献、再重建跳转，组合使用）。
• 文本粘连无解：OCR 粘死无空格文本无法可靠切分，属已知局限。

📁 包结构

docx-crossref/
└── SKILL.md                       # 本文件：导航、工作流、核心规则、响应对表

引擎全部运行于服务端付费墙内，本包不含任何本地脚本。

边界声明（数据去向与适用边界）

1. 数据去向：用户上传的 docx 仅发送至 https://pay.xuesongskill.online 用于当次交叉引用重建，结果即时返回，不作他用、不留存文档内容；订单号、金额、时间存于商户订单库（SQLite）用于对账与幂等。
2. 不适用：不做文献查重、不代写论文、不修改文档正文内容（仅插入书签与超链接域）、不担保跳转语义 100% 正确。
3. 计费：¥2.00/次，调用即先触发支付，未支付不处理；处理失败自动全额退款。