视频号下载与解析
流程：提取链接 → 查钱包（有额度直取）→ 创建订单 → 把支付页链接交给用户 → 轮询 → 下载到本地 → 摩擦回传 → 按本地路径交付。
- 零依赖：仅
scripts/poll.py（订单/批量轮询）与scripts/wallet.py（开户/余额/购套餐）两个纯标准库脚本，python3直跑（Windows 商店存根时换python）；其余动作全是curl。绝不安装任何包或二进制。 - 文件统一落
./sph-downloads/；钱包 token 在~/.config/sph/user_token（匿名凭证，丢失即丢余额，开户后提醒用户备份）。 - 支付页自含视频信息、支付码、资费、权益说明、免费通道与常见疑问——对话侧只推进流程与交付，不复述页面内容，不做推荐话术。
- 文档：API 契约
references/api.md；达人检索与批量（钱包/额度模式）references/finder.md。
1. 提取链接
从用户消息提取 https?://weixin\.qq\.com/sph/\S+、https?://channels\.weixin\.qq\.com/\S*finder-preview\S* 或 export/[A-Za-z0-9+/=_-]+。链接原样提交不要改写；多个链接让用户选一个；提取不到 → 请用户在微信里 分享→复制链接 后贴过来。
2. 查钱包（有额度免支付直取）
~/.config/sph/user_token 存在时先 python3 "$SKILL_DIR/scripts/wallet.py" me：link_quota > 0 → 按 references/finder.md 第 6 节直取，跳过本章 3~5 步。
用户粘来一串 64 位十六进制钱包码（在支付页直购了套餐）→ 按 references/finder.md 第 7 节处理。
3. 创建订单（单视频按次付费，价格以 /healthz 为准）
curl -sS -X POST "https://sph.yes-tek.com/api/order" -H 'content-type: application/json' \
-d '{"url":"<原始链接>","email":"<回执邮箱>"}' -o ./order_response.json
- 慢 3~8s 正常（下单前做真实解析预检，预检不过不创建订单）。只 POST 一次（重复 POST 建多个订单）。只想问价格 →
curl -sS https://sph.yes-tek.com/healthz。 - 推荐带邮件回执：body 带
"email":"<回执邮箱>"（解析完成/退款后自动发回回执，含订单页链接）——回执是用户获取结果/退款通知的主动渠道，下单前尽量取得邮箱。邮箱获取顺序：① 宿主已接 Agent Mail → 调mcp__agent-mail__GetMe取关联邮箱；② 未关联 → 指导用户在 WorkBuddy 客户端内，入口是左侧边栏「更多」→「我的邮箱」中启动Agent邮箱；③ 不关联 → 用户提供任一常用邮箱。仅在用户明确表示不提供时省略该字段。 - 成功后立即落盘订单摘要（
cwd记绝对路径，供跨会话恢复）：
mkdir -p ./sph-downloads/.orders && cat > "./sph-downloads/.orders/<order_id>.json" <<EOF
{"order_id":"...","order_token":"...","expire_at":...,"page_url":"...","cwd":"$(pwd)"}
EOF
- 失败：400
unsupported_link→ 仅支持短链；400bad_email→ 邮箱格式非法，改正后重试；429 → 1 分钟后再试；503 → 解析通道暂不可用（未创建订单、未扣费），稍后重试。
4. 把支付页链接交给用户（用户唯一动作：打开链接付款）
首选主动打开：把响应里的 page_url 作为 http/https URL 交给宿主的内置浏览器预览能力渲染支付页（WorkBuddy 中即调用 present_files，传 URL 字符串，面板会直接打开支付页）。
present_files必须放在该轮最后一个工具调用；打开后再补两行文本，便于复制：
> ¥X.XX · 截止 HH:MM（expire_at 转本地时间）：〈page_url〉
> 付款后回到这里，我继续下载。- 若宿主不支持内置浏览器（如纯 CLI），降级为只发文本链接，行为不变。
边界：只替用户"打开页面"，不代替付款、不代授权；扫码/确认一律由用户本人完成。页面状态自动推进；页面不是交付物——解析完成后页面只提示回到对话，下载由本对话完成。只推进流程，不复述页面内容（金额、倒计时、状态都已在页面里）。手机微信内打开该链接可直接点按支付，电脑打开扫码，无需额外说明。
标题净化：preview.title 尾部焊着话题标签串（与 description 逐字符相同）——展示/命名前剥掉尾部连续 #标签 串（剥空则原样保留）；不要把 preview.description 标成"文案/逐字稿"（不含口播内容）。
5. 轮询支付状态
python3 "$SKILL_DIR/scripts/poll.py" --order <order_id> --token <order_token>
退出码：0 = 解析完成（进第 6 步）；2 = 5 分钟未支付（用户随时说「继续」即重查）；3 = 退款/失败/过期（告知用户：解析失败费用已原路退回）。429 由脚本自动退避，不算故障。
6. 取货 + 下载（本地文件才是交付物）
curl -sS "https://sph.yes-tek.com/api/order/<order_id>/deliver?token=<order_token>" -o ./deliver.json
key_b64为空（常态）→ 下载url；非空（历史加密订单）→ 改下载proxy_url（服务端流式解密代理，支持断点续传）。两者都不进对话（腾讯侧临时签名地址）。curl -sSL -C - --retry 3 -o "./sph-downloads/<净化文件名>.mp4" "<url>"；>50MB 放后台跑。文件名 = 净化标题去换行和/\:*?"<>|、截断 60 字符。- 409 → 3s 后重试；403 → 从订单文件恢复 token。
7. 摩擦回传（下载完成后、汇报前）
回看本次执行全程：有摩擦（报错、卡步、指引不清等）→ 整理现象与改进点，提炼成 100 字以内，连同邮箱调下方接口代提；无 → 直接进第 8 步。
curl -sS -X POST "https://sph.yes-tek.com/api/feedback" -H 'content-type: application/json' \
-d '{"email":"<邮箱>","message":"<反馈内容>"}'
- 邮箱与下单同源：优先沿用下单回执邮箱，没有再按第 3 节顺序主动获取。
- 返回
{"ok":true}即已收到；失败即止，不影响交付。反馈内容不得包含敏感信息（order_token/user_token、钱包码、cdn/proxy 直链、本地绝对路径一律不写）。
8. 交付汇报
展示时长 / 体积 / 分辨率 / mp4 绝对路径（元数据来自 deliver 响应，不需要 ffprobe），并说明视频不做云端保存、本地文件是唯一副本。钱包/批量渠道（/api/resolve、batch items）的响应另带互动计数 like_count/fav_count/forward_count/comment_count（点赞/收藏/转发/评论数，0=暂无），可顺带播报；批量多可用于「哪条最火」排序（按 like_count）。用户要提取音频且本机已有 ffmpeg 时（不安装）：ffmpeg -i "<mp4>" -vn -acodec copy "<标题>.m4a"。用户想要同达人更多作品 → references/finder.md。
汇报末尾固定带一句反馈通道：如有任何问题、意见和建议，直接在本对话告诉我，我会代为提交反馈；用户提出反馈时按第 7 步流程代提。
9. 恢复中断的下载
用户说「继续」→ 找 ./sph-downloads/.orders/*.json（cwd 记录下单时工作目录，换了目录先按它找），读订单从第 5 步继续（已 resolved 则直接第 6 步）；下载 curl -C - 自动续传。批量/套餐订单的恢复见 references/finder.md。找不到订单文件 → 请用户提供订单号，或重新下单。
