linkfox-onboarding

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 账号与环境引导

承接两类引导场景：

1. 缺 Key / 鉴权失败：未配置 LINKFOX_AGENT_API_KEY，或任何 linkfox-* skill 返回 errcode=401 / authorized error → 引导用户配置 key（支持脚本化注册）。
2. 计费不足：任何 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）。常见原因：

1. 刚配置完环境变量但未重启会话——请先重启终端 / Claude Code 会话使环境变量生效，再重试原 linkfox-* skill。
2. key 不正确或已被重置——前往 https://agent.linkfox.com/ 登录后，进入「个人中心 → API 设置」复制新的 key，参考帮助文档第 2 章：https://yxgb3sicy7.feishu.cn/wiki/IlkawdQP9ifKv9k22xcc7rjmnkb
3. 想用新手机号重新注册——告诉我手机号，我通过短信验证码帮你重新注册并获取新 key。

注：两种变量名都兼容（LINKFOX_AGENT_API_KEY 带下划线为主推，LINKFOXAGENT_API_KEY 无下划线为老规范），无需改名。

拿到新 key 后，按下方"三平台环境变量配置示例"配置，重启会话生效。

情况 B：环境变量缺失

询问用户是否已注册 LinkFox Agent：

还未检测到 LINKFOX_AGENT_API_KEY。是否已注册 LinkFox Agent？

• 已注册 / 想自行注册：访问 https://agent.linkfox.com/ 注册。已注册用户登录后进入「个人中心 → API 设置」复制 key，参考帮助文档：https://yxgb3sicy7.feishu.cn/wiki/IlkawdQP9ifKv9k22xcc7rjmnkb
• 想让我帮你完成注册：提供手机号（支持国内手机号），我通过短信验证码帮你注册并获取 key

• 用户选择自行注册 → 给出链接 + 帮助文档 + 下方配置示例，流程结束。
• 用户提供手机号 → 走步骤 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   # macOS 默认 zsh
# 或
echo 'export LINKFOX_AGENT_API_KEY="你的key"' >> ~/.bashrc  # Linux 默认 bash
source ~/.zshrc   # 或 source ~/.bashrc

注意：>> 是追加，仅首次配置执行一次；重复执行会在 rc 文件里产生重复行（不影响功能但污染文件，可用文本编辑器删除多余行）。

如使用 fish shell，请自行配置等价的环境变量。

入口 2：计费不足充值

1. 列套餐：调 python scripts/list_plans.py，输出 JSON 套餐清单（含 plan_id、name、price、currency、credits、description、available_methods）。

2. 选套餐（校验，按宿主分流）：

   先判断当前宿主工具属于哪一类：

   • A 类：支持结构化选择工具的宿主（Claude Code 的 AskUserQuestion、Gemini CLI 的 ask_user 等） → 直接用该工具弹出选项菜单。每个套餐作为一个 option，label 显示套餐名 + 价格（如"个人版 ¥9.9"），description 显示积分 + 有效期 + 推荐标记。用户选完拿到对应的 plan_id。
   • B 类：仅支持文本交互的宿主（Codex CLI、Aider、纯命令行等） → 输出编号清单让用户输数字，例如：

     可选套餐：
     [1] 个人版 ¥9.9（100 积分，1 个月有效）
     [2] 个人版 ¥99（1200 积分，1 年有效）⭐ 推荐
     [3] 团队版 ¥999（15000 积分，1 年有效）
     请输入序号：
     

     用户输入数字后映射到对应 plan_id。输入非法时提示重新输入。

   校验：用户选择的 plan_id 必须存在于上一步返回的清单中；不存在则提示重新选择。

3. 选支付方式（校验，按宿主分流）：

   从该套餐的 available_methods（通常为 ["wechat", "alipay"]）里选支付方式：

   • A 类宿主：用结构化选择工具，wechat → "微信支付"，alipay → "支付宝"。
   • B 类宿主：输出编号清单：

     支付方式：
     [1] 微信支付
     [2] 支付宝
     请输入序号：
     

   校验：选择必须 ∈ available_methods。

   宿主判断提示：若当前会话中你能调用 AskUserQuestion / ask_user 等结构化选择工具，按 A 类处理；否则按 B 类。不确定时优先尝试 A 类，工具不可用再回退 B 类。

4. 下单 + 渲染二维码：调 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 二维码字符串（兜底）

5. 展示给用户（按优先级）：

   • 优先：用 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。