社科理论机制与技术路线图绘制（Pay Skill）
按次计费的学术图绘制服务。核心绘图能力运行在作者自有云端服务，
本技能包只保留「意图识别 → 参数编排 → 调用服务 → 落图 → 插入论文」的编排逻辑，
不含任何绘图算法与结构模板资产。
付费流程（支付宝 AI 按量付费）——四段式 probe / pay / complete / ack
本技能按 probe → pay → complete → ack 四段式完成一次付费调用。
脚本只做编排与账单传递，不自行发起付款，也不自行实现验付——
验付与履约由服务端完成，付款由支付宝官方 CLI 完成。
1. probe（探测）
向资源接口发起原始请求。未付款时服务端返回 HTTP 402，
并在 Payment-Needed 响应头中下发账单（含收款方、金额、服务标识、订单号）。
脚本保存账单与原始请求体到本地状态目录，供后续步骤复用。
python3 scripts/call_service.py --figure-type framework --layout horizontal \
--config '{"boundary":"研究情境","nodes":["维度A","维度B"]}' --out figure.png
# → 未付款时服务端返 HTTP 402，脚本打印账单与 SESSION_ID，
# 账单与原始请求落盘状态目录（700/600）
2. pay（支付）
把账单文件与原始请求交给支付宝官方 CLI（买家侧 @alipay/agent-payment）：
python3 scripts/call_service.py --step pay --session-id <SESSION_ID> \
--intent-summary "绘制社科机制图，用户已确认 ¥3.00"
# 脚本内部调用支付宝官方买家 CLI（alipay-bot 402-buyer-pay），
# 由用户在支付宝侧授权付款；成功后自动记录支付凭证号
CLI 会展示收款方、金额、意图摘要，等待用户授权付款。
未经用户确认不得调用本步骤。
3. complete（完成）
用支付宝官方 CLI 查询支付状态（alipay-bot 402-query-payment-status），
由服务端完成验付：核对 Payment-Proof 凭证与订单金额是否一致。
python3 scripts/call_service.py --step complete --session-id <SESSION_ID> --out figure.png
# 脚本内部调用 alipay-bot 402-query-payment-status：
# 查支付状态 → 服务端验付（核对 Payment-Proof 与订单金额）→ 履约确认 → PNG 落盘
4. ack（履约确认）
验付通过后服务端返回资源（图 PNG）并下发履约回执。
同一订单重试不会重新扣费，服务端履约处理保持幂等。
携带凭证重试
支付完成后，用返回的 Payment-Proof 原样重放原始请求
（业务 body 必须与首次完全一致，不得改动）：
POST <资源接口>
Payment-Proof: <支付宝签发的凭证>
订单持久化与幂等
订单持久化到 SQLite 等存储，必须实现订单落库和幂等：
- 服务端收到已验付订单的重试请求时，直接返回既有资源，不再发起计费；
- 订单状态可查询（未付款 / 已付款 / 已履约），便于异常排查；
- 履约回执与资源交付一一对应，不会因重试重复交付。
依赖
| 包 | 用途 |
|---|---|
@alipay/agent-payment |
买家侧支付 CLI（alipay-bot），由脚本在 pay / complete 步骤内部调用 |
@alipay/alipay-aipay |
卖家侧收款网关，服务端生成账单与验证凭证 |
| 环境变量 | 说明 | 默认 |
|---|---|---|
PAYSKILL_ENDPOINT |
服务地址（可覆盖打包内置地址） | 作者服务当前公网地址 |
PAYSKILL_STATE_DIR |
账单与请求状态目录 | ~/.payskill/state（700/600） |
付费前置检查（必须先做，不可跳过）
调用本技能前，先确认当前 Agent 是否具备支付能力：
- ✅ 已安装
@alipay/agent-payment（alipay-bot可用）→ 继续走付费流程 - ❌ 未安装 → 明确告知用户「当前 Agent 暂不支持付费创作能力」，终止流程
命中绘图意图后，向用户展示服务名称与单价并取得明确同意，再发起调用。
未经用户确认不得直接下单。
服务与定价
| 项 | 值 |
|---|---|
| 服务 ID | 以账单 Payment-Needed 中的 service_id 为准（支付宝 AI 按量付费·服务市场） |
| 服务内容 | 社科理论机制图 / 技术路线图渲染 |
| 单价 | ¥3.00 / 次 |
| 计费单元 | 次（每次调用计一次费，每笔订单按次消费） |
| 收款主体 | 作者本人（SkillHub 仅提供展示与投诉处理，不作为收款方） |
平台零抽成，收益实时结算。
5 类图型（服务端支持）
| 图型 | 英文名 | 结构 | 适用 |
|---|---|---|---|
| ① 分析框架图 | framework | 外层情境边界 + 内部多维并列框 + 中心问题 | 技术-制度-组织三维框架 |
| ② 机制因果链 | chain | 自变量 → 中介机制 → 因变量 | 制度激励不相容→执行偏差 |
| ③ 技术路线图 | roadmap | 方法 → 数据 → 分析策略 → 发现 | 实证研究四阶卡片 |
| ④ 对比分类表 | matrix | 维度 × 类型（灰表头 + 斑马纹） | 科层主导 vs 协同治理 |
| ⑤ 理论整合图 | integration | 多理论 → 整合框架 | 三重理论整合 |
图型可传中文别名（如「分析框架图」「技术路线图」），服务端自动归一化。
布局偏好（必须主动询问，不可擅自决定）
排布方式会直接决定图的阅读方向与版面比例，是用户的排版意图，不能替用户猜。
凡涉及节点排列的图型（①②③⑤），在调用服务前必须先问一次。
一次性把三个选项摆出来
用 AskUserQuestion 提问，选项如下（必须带这三个，不得只给两个或替用户默认）：
| 选项 | 参数值 | 视觉特征 | 适用 |
|---|---|---|---|
| 左右排列（推荐） | horizontal |
节点从左到右依次排开，箭头向右推进 | 线性因果链、阶段流程、维度并列；论文中最通用 |
| 上下排列 | vertical |
节点从上到下依次排开，箭头向下推进 | 纵向层级、逐层递进的分析步骤；画幅较高 |
| 环形排列（循环） | circular |
节点沿圆周均布，箭头沿圆环推进并首尾相接 | 反馈循环、闭环机制、要素互促；需 3 个以上节点才有意义 |
提问话术示例：
> 出图前确认一下排布方式：这张图您希望左右排列（从左到右推进，最常用）、
> 上下排列（从上到下递进），还是环形循环（首尾相接的闭环）？
询问规则
- 一次性问完，不要挤牙膏式追问；用户回答后直接进入出图。
- 用户已明示的不再问。若用户原话已含「横着排」「从上往下」「做成一个圈」
「循环图」等表述，直接取用其意图，不必再问。 - 对比分类表（④ matrix）不询问。表格型图型无节点排列问题。
- 节点不足 3 个时主动说明：环形布局在 2 个节点下画不出环，
服务端会自动退回左右排列——此时应告知用户「环形在您这个节点数下
效果等同左右排列，是否仍按环形出图」。 - 未获答复时按
horizontal出图，并在交付时说明「本次按左右排列出图，
如需上下或环形可重新出图（按次计费）」。
调用流程（7 步）
- 识别图型 → 对照上表判断属于哪一类。若用户只给研究主题，先与其梳理
变量、机制、层级关系，再定图型。 - 确认布局 → 按上节「布局偏好」主动询问排布方式（对比分类表跳过）。
- 结构化输入 → 把研究内容拆成：节点（框）、关系（箭头）、层级（边界/分区）、
标注（关系词/理论名）、底部资料来源。 - 调服务 → 执行
scripts/call_service.py，传入图型、布局与配置。 - 处理支付 → 首次调用返回 HTTP 402 账单，向用户展示金额与确认；用户支付后
带Payment-Proof原样重试（业务 body 不得改动）。 - 落图校验 → 检查 CJK 字体正常（无方块）、文字未溢出框、箭头方向正确、
节点未被裁切、环形图闭环连贯。 - 交付与插入 → 交付 PNG；插入论文用
scripts/insert_docx.py（在「图N」题注前
插入并清理旧占位图，重复运行不重复插）。
调用示例
python scripts/call_service.py \
--figure-type framework \
--layout horizontal \
--config '{"boundary":"研究情境","center_title":"研究结论","center_en":"Conclusion"}' \
--out figure1.png
--layout 可取 horizontal（默认）/ vertical / circular，
也接受中文「左右排列」「上下排列」「环形排列」与「循环图例」等口语表述。
批量出图（多图场景，逐图计费）：
python scripts/call_service.py --batch figs.yaml --outdir ./output
figs.yaml 每项含 figure_type、layout（可选）与 config（字段同对应图型）。
插入论文 docx
python scripts/insert_docx.py --doc 论文.docx \
--figures "图1=figure1.png" "图2=figure2.png" \
--out 论文_含图.docx --width 6.0
配置字段（各图型）
通用字段（所有图型）：
layout：horizontal（默认）/vertical/circularWH：画布尺寸；一般不要手动指定，服务端会按图型与布局自动给出合适比例source：底部"资料来源"注释
各图型专属字段：
- framework：
boundarydims[{title,items[]}]center_title
center_encenter_mediatorrel_labels[] - chain：
nodes[]rels[]bottom_logic - roadmap：
stages[{title,items[]}] - matrix：
header[]rows[][]col_w[]（表格型，无布局参数） - integration：
triples[[左,中,右]]conclusion
未传字段使用服务端默认值。
三种布局的画幅差异
| 布局 | 画幅特征 | 插入论文建议 |
|---|---|---|
| 左右排列 | 宽幅（如 1080×580） | 常规横向排版，宽度 6.0cm 起 |
| 上下排列 | 竖幅（如 1080×940、720×860） | 适合页边较窄或需与正文并排处 |
| 环形排列 | 近方形（如 1180×800、900×640） | 适合作为页面视觉焦点，宽度可放大到 8cm |
风格规范（服务端已强制执行）
- 配色：主体纯黑白（线 #000000 / 底 #FFFFFF）；强调色仅深红 #C00000，面积 ≤10%
- 尺寸：画布按「图型 × 布局」自动定尺寸，左右为宽幅、上下为竖幅、环形近方形
- 字体：服务端使用免费开源字体（Noto Sans SC / 开源回退），不打包任何字体文件
- 边框与填充：圆角 rx≈8–10；活跃节点浅灰 #F0F2F5；表头灰 #D9D9D9；斑马纹 #F2F2F2
- 注释：底部右对齐"资料来源：作者整理"；中英文术语并列
关联技能
cn-social-science-paper-structure— 论文结构骨架（本技能的最佳搭档：先定结构，再配图）academic-expression-style-refiner— 大纲定稿后润色社科文体paper-originality-studio— 降重
重要约束
- 不使用 AI 文生图生成机制图（文字必糊、版式不可控）；一律服务端矢量绘制。
- 图中示例文本为原创合成模板，用户须替换为自己的研究内容并自行负责。
- 插入 docx 时只新增图片、清理旧占位图，不改动用户正文。
- 本技能包不含绘图算法与结构模板；这些运行在作者自有服务中，脱离该服务不可用。
