| name | linkfox-onboarding |
| description | LinkFox 账号与环境引导。两个入口：(1) 检测到 LINKFOX_AGENT_API_KEY/LINKFOXAGENT_API_KEY 均未配置，或任何 linkfox-* skill 返回 errcode=401/authorized error 时，引导用户配置 key——支持脚本化注册（手机号→验证码→自动获取 key）；(2) 任何 linkfox-* skill 返回计费不足错误（errcode=402 或消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"）时，触发充值流程：列套餐 → 用户选套餐（校验）→ 选支付方式（微信/支付宝，校验）→ 调下单接口生成支付二维码 → 三路展示（PNG/链接/ASCII）→ 可选查询订单状态。用户说"没配 key""鉴权失败""积分不足""余额不足""充值""recharge""升级套餐""注册""手机号注册"时触发。 |
LinkFox 账号与环境引导
承接两类引导场景：
- 缺 Key / 鉴权失败：未配置
LINKFOX_AGENT_API_KEY，或任何 linkfox-* skill 返回 errcode=401 / authorized error → 引导用户配置 key（支持脚本化注册）。
- 计费不足：任何 linkfox-* skill 返回计费不足错误 → 充值流程（套餐 → 支付方式 → 二维码）。
触发关键字清单（大小写不敏感）
判定为"缺 Key / 鉴权失败"的条件（满足任一）：
errcode = 401- 错误消息含
authorized error、鉴权失败、未授权、unauthorized
- 环境变量
LINKFOX_AGENT_API_KEY 与 LINKFOXAGENT_API_KEY 均为空
注：本 skill 同时兼容两种 key 环境变量名——LINKFOX_AGENT_API_KEY（带下划线，主推）与 LINKFOXAGENT_API_KEY（无下划线，老客户常用）。其它 linkfox-* skill（如 linkfox-amazon-search）也遵循同一约定，同一个 key 在两个网关都能用。
判定为"计费不足"的条件（满足任一）：
errcode = 402（后端约定，实测返回 {"errcode": 402, "errmsg": "积分余额不足，请充值"}）- 错误消息命中以下关键字之一：
积分余额不足、计费不足、余额不足、quota exceeded、insufficient balance、套餐到期、需充值、请充值
排除：errcode = 403（无权限，不归入这两类）。
入口 1：缺 Key / 鉴权失败引导
步骤 1：检测环境变量
用 Bash 执行一行检测（Claude Code 自带 bash 环境，三平台通用）：
[ -n "$LINKFOX_AGENT_API_KEY$LINKFOXAGENT_API_KEY" ] && echo ok || echo missing
两种变量名都兼容：LINKFOX_AGENT_API_KEY（带下划线，主推）与 LINKFOXAGENT_API_KEY（无下划线，老客户常用）。任一非空即视为已配置。
步骤 2：分流
情况 A：环境变量存在（鉴权失败场景）
先排除"刚配置完没重启"的情况——这是最常见的 401 误判来源。话术：
检测到已配置 LINKFOX_AGENT_API_KEY 或 LINKFOXAGENT_API_KEY，但鉴权失败（401）。常见原因：
- 刚配置完环境变量但未重启会话——请先重启终端 / Claude Code 会话使环境变量生效，再重试原 linkfox-* skill。
- key 不正确或已被重置——前往 https://agent.linkfox.com/ 登录后，进入「个人中心 → API 设置」复制新的 key，参考帮助文档第 2 章：https://yxgb3sicy7.feishu.cn/wiki/IlkawdQP9ifKv9k22xcc7rjmnkb
- 想用新手机号重新注册——告诉我手机号，我通过短信验证码帮你重新注册并获取新 key。
注：两种变量名都兼容（LINKFOX_AGENT_API_KEY 带下划线为主推，LINKFOXAGENT_API_KEY 无下划线为老规范），无需改名。
拿到新 key 后，按下方"三平台环境变量配置示例"配置，重启会话生效。
情况 B：环境变量缺失
询问用户是否已注册 LinkFox Agent：
还未检测到 LINKFOX_AGENT_API_KEY。是否已注册 LinkFox Agent？
- 用户选择自行注册 → 给出链接 + 帮助文档 + 下方配置示例，流程结束。
- 用户提供手机号 → 走步骤 3 脚本化注册。
步骤 3：注册（用户提供手机号）
3.1 发送验证码
调 python scripts/send_verify_code.py <phone>，脚本返回 JSON：
- 成功：
{"sent": true, "phone": "188****1234", "agreements": {"user_agreement": "...", "service_agreement": "...", "privacy_policy": "..."}}
- 失败：
{"sent": false, "phone": "188****1234", "errmsg": "..."}
注：脚本输出里的 phone 字段已脱敏（保留前 3 后 4），agreements 字段含三个协议链接。Claude 直接用这两个字段向用户展示即可，无需读 stderr。
收到成功后，向用户输出（从 JSON 的 agreements 取链接）：
验证码已发送到 188****1234。回复验证码即视为接受以下协议并完成注册：
- 用户协议：<agreements.user_agreement>
- 服务协议：<agreements.service_agreement>
- 隐私政策：<agreements.privacy_policy>
验证码约 5 分钟内有效，请尽快回复。若不想继续，回复「取消」即可退出。
3.2 验证码登录 + 获取 key
收到用户回复的验证码后，调 python scripts/login_and_get_key.py <phone> <code> <channel>。
注意：如果你是workbuddy或渠道是workbuddy，则channel传 workbuddy，否则传 skill。
脚本返回 JSON：
- 成功：
{"api_key": "<token>", "phone": "188****1234", "group_id": "...", "member_id": "...", "source": "existing|generated", "is_new_user": bool, ...}
- 失败：
{"error": "<阶段>: <信息>", "phone": "188****1234"}
注：
source 字段仅供调试（existing=查到已有 token，generated=新生成），无需向用户解释。- 脚本内部对新用户（
is_new_user=true）会自动调 /account/loginByToken 触发新用户赠送积分发放，无需 Claude 介入。该步失败不阻断拿 key，stderr 提示但继续。
is_new_user=true 时可顺带告知用户"已赠送新用户积分"。
失败处理：
error 含 login: 验证码错误或已过期 → 提示用户重新发短信（回到 3.1）error 含 userInfo: 用户未开通任何团队空间 → 引导用户访问 https://agent.linkfox.com/ 登录完成首次开通后重试error 含 团队不存在 或 getApiToken/generateApiToken → 引导用户前往 https://agent.linkfox.com/ 登录后进入「个人中心 → API 设置」手动生成 key，参考帮助文档第 2 章- 其它错误 → 透传 error 信息给用户，建议自行注册
3.3 配置环境变量
拿到 api_key 后，按下方"三平台环境变量配置示例"帮用户配置，并提示重启终端 / Claude Code 会话使环境变量生效。
三平台环境变量配置示例
变量名推荐用 LINKFOX_AGENT_API_KEY（带下划线，新规范）。若你的环境已配置 LINKFOXAGENT_API_KEY（无下划线，老规范），同样有效，无需重复配置——本 skill 及其它 linkfox-* skill 均兼容两种名。网关地址变量同理：LINKFOX_AGENT_API_URL（主推）或 LINKFOX_TOOL_GATEWAY（回退）。
Windows（PowerShell，永久写入用户环境变量）：
setx LINKFOX_AGENT_API_KEY "你的key"
配置后重启 PowerShell 或 Claude Code 会话生效。
macOS / Linux（zsh / bash，写入 shell rc）：
echo 'export LINKFOX_AGENT_API_KEY="你的key"' >> ~/.zshrc
echo 'export LINKFOX_AGENT_API_KEY="你的key"' >> ~/.bashrc
source ~/.zshrc
注意：>> 是追加，仅首次配置执行一次；重复执行会在 rc 文件里产生重复行（不影响功能但污染文件，可用文本编辑器删除多余行）。
如使用 fish shell，请自行配置等价的环境变量。
入口 2：计费不足充值
-
列套餐：调 python scripts/list_plans.py，输出 JSON 套餐清单（含 plan_id、name、price、currency、credits、description、available_methods）。
-
选套餐（校验，按宿主分流）：
先判断当前宿主工具属于哪一类：
校验：用户选择的 plan_id 必须存在于上一步返回的清单中；不存在则提示重新选择。
-
选支付方式（校验，按宿主分流）：
从该套餐的 available_methods（通常为 ["wechat", "alipay"]）里选支付方式：
校验：选择必须 ∈ available_methods。
宿主判断提示：若当前会话中你能调用 AskUserQuestion / ask_user 等结构化选择工具，按 A 类处理；否则按 B 类。不确定时优先尝试 A 类，工具不可用再回退 B 类。
-
下单 + 渲染二维码：调 python scripts/create_order.py <plan_id> <pay_method>，脚本返回 JSON：
order_id：订单号（后续查询用）qr_content：二维码原始内容（weixin:// 或支付宝链接，不能直接点击）qr_url：网关返回的二维码图片 URL（可能为空）pay_url：可点击的支付链接（兜底）png_path：本地生成的 PNG 路径ascii_qr：ASCII 二维码字符串（兜底）
-
展示给用户（按优先级）：
- 优先：用 Read 工具读取 展示 PNG 图片。
支付状态查询（可选）
提供 python scripts/query_order.py <order_id>，返回 JSON {"order_id":..., "status":..., "paid_at":...}，status ∈ paid / unpaid / expired / unknown。可在用户表示"已付款"后调用，或结合 /loop 周期性查询，但本 skill 不主动轮询。
依赖
- Python 3（标准库 urllib/json/os）
requests：登录链路 HTTP 调用（生产 WAF 对 urllib 敏感），pip install requests- 二维码 PNG / ASCII 生成：内置
scripts/_qrgen.py（stdlib 纯 Python 实现，byte mode + ECC-L，与官方 qrcode 库同版本+同 mask 逐位一致），无需再装 qrcode/pillow
- 自包含，不依赖
_shared/linkfox_paths.py
接口契约
所有端点（网关 /account/*、/package/*、/order/*，登录链路 /user/v1|v3/web/login、/account/loginByToken、/linkFoxApp/api/userCenter/userInfo、/group/getApiToken|generateApiToken）的完整请求/响应/错误码见 references/api.md。
限制
- 仅承接"缺 Key 引导"与"计费不足充值"两类场景，不处理退订、发票、对账。
- ASCII 二维码识别率取决于终端字体与对比度，建议优先用 PNG 或
pay_url。
