船到跑腿

要解决什么问题

把一个同城跑腿订单从「用户口头描述」变成「平台已接单」之间，通常要经历几轮重复沟通：手机号授权、地址转经纬度、类目选择、询价报价比选、确认平台再下单。每一步都可能是一次往返确认，也可能因为金额单位（接口收分、用户说元）或重量取整规则处理不当而返工。

@chuandao/chuandao-paotui-skill 要解决的就是这类流程性摩擦：在 Agent 内部完成登录、询价、下单、查单、取消的完整闭环，并把单位换算、参数校验这类容易出错的细节收敛到脚本层。

核心能力与工作流

技能启动后先跑 scripts/check_auth.py 判断本地是否已保存 permanent_token，据此决定走首次注册引导还是直接进入功能选择。

• 首次使用：收集手机号 → 调 send_sms 发验证码；若服务端要求图形验证码，再调 get_captcha 取图并回传给用户确认 → login 成功后 token 自动写入 config.json。
• 询价：一次性收集发件人、收件人、物品信息，而不是逐项追问。已有经纬度和省市编码时不调用 geocode，只有缺少坐标时才解析地址，并先让用户确认候选地址。物品价值由用户口述的「元」换算成接口要求的「分」。
• 下单：如果会话里已经询价成功，用户确认平台后直接用 order_trade_no 加报价里的 consumer_isv 调 place_order，不重复询价、不重传收发件信息。
• 订单管理：query_order 查状态与费用，cancel_order 取消并如实展示违约金；另有 wallet_balance 查余额，以及 list_categories 支持无参全量列出或按关键词（如「奶茶」）模糊匹配类目 ID。

工程细节与边界

几个容易踩坑的地方值得留意：

• 金额单位双向换算：所有金额字段接口层都是分，用户交互层一律是元。传入 元 × 100，展示 分 ÷ 100 并保留两位小数。
• 重量向上取整：小于 1kg 或小数重量都向上取整，0.8kg → 1kg、1.2kg → 2kg，用户未说明时默认 1kg。
• 询价号有效期约 60 秒：order_trade_no 是短时凭证，确认平台后应立即下单，不要拖延到过期再询价。
• 余额不足的分支：下单接口返回余额相关错误时，技能会展示 references/paotui-rcode.png 的微信充值二维码；用户充值后用原参数重调 place_order 即可，无需重新询价。默认流程不会预先查余额，除非用户明确要求。
• 鉴权边界：仅 /mini/token/captcha、/mini/token/do_login、/mini/token/send_code 三个接口做签名（剔除 signature 后按 key 字典序拼接 k=v&...&key=APP_SECRET_SKILL，生成小写 32 位 MD5）；其余接口统一走请求头 Authorization: Bearer {permanent_token}，且均为 POST。
• 不要为下单预先查余额：这会增加一次不必要的调用，只在用户主动询问时才执行 wallet_balance。

总体而言，这是一个偏执行层的配送编排技能，把单位换算、凭证时效、异常分支这些确定性逻辑内置好，适合嵌在需要「说一句话就能发一单」的场景里。