VOC-03 设计方案（重写版）：多渠道一键安装 + 安装即弹付费

真实场景：教练现场用 VOC 技能做电商数据采集，不走飞马平台 UI；现场可能是 Claude Code / Codex / Workbuddy。关键诉求：每个渠道一段「一键复制安装提示词」；安装一完成就在浏览器弹付费页——必须在进入工作流、消耗 LLM token 之前弹，避免「跑了半天报告、到取数那步才 402」。

0. 现状（基于 Parse `Skill` 表 + voc-api-catalog 代码实读）

Skill 表（78 行）：name=voc-skill、type=claude、category=claude-code（单值）、cdnPrefix=安装命令、cdnUrls={npm,global,install}、apig→APIG Vo3ROWEvDy。
token 检测逻辑（权威出处：claude-code/claude-code-voc-intelligence/mcp/src/core/credentials.js）：不存在 ~/.openclaw/ 路径。实际有两条计费链 + 两种 token：
- readNewApiToken() → NewAPI / fmode-api 计费 token（sk- 开头），现为主计费链。取值优先级：入参 → .env.local/环境变量 FMODE_API_KEY/NEWAPI_TOKEN → ~/.claude/voc-credentials.json .fmodeApiKey → ~/.fmode/config.json → ~/.claude/settings.json 的 env.ANTHROPIC_AUTH_TOKEN（经 pickFmodeAnthropicToken 门控：必须 sk-、非 sk-ant-、ANTHROPIC_BASE_URL 指向 fmode）。
- readVocToken() → 平台 apig 会话 token（r: 开头），旧链路回退。取值：入参 → .env.local VOC_TOKEN/VOC_SOCIAL_TOKEN → 环境变量 → ~/.claude/voc-credentials.json .vocToken/.token。
两种充值入口不同（payment-links.js 权威常量）：
- sk-（NewAPI）余额不足 → https://app.fmode.cn/dev/studio/?balance=fmodeapi（自动开余额充值弹窗）
- r:（apig 会话）→ https://app.fmode.cn/dev/apig-pay/?user={objectId}&apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF（+ workshop 套餐页），resolveVocUserId() 调 /parse/users/me 拿 objectId
状态分类（代码里已区分）：缺 NewApi token / 缺 voc token / token 类型错（给了 sk- 但需 r:）/ 真 402 余额不足 / 403 无权限。"缺 token"是配置/读取问题，不等于余额不足，优先自愈读 settings.json 的 sk-，不要直接甩人去充值。

结论修正：付费解析、计费链、状态分类都已在 voc-api-catalog 代码里实现且权威。VOC-03 不要重写 token 逻辑，只需：① Skill 表支持多渠道话术；② 新增 --activate 入口，在 bootstrap 阶段复用 credentials.js/payment-links.js 做激活检查与开页。

1. 核心决策：①不动 `--smoke` ②新增专用入口 ③弹窗按 token/余额状态触发

1.1 为什么不能改 `--smoke`

--smoke 是健康自检，飞马 UI 用户 / 内部 / CI 都在用——他们已经有 token。若把弹付费塞进 --smoke，这些人每次都被强弹付费页，打断操作；CI 里弹浏览器更是错误。所以 --smoke 保持原样，绝不加开浏览器。

1.2 新增「其他 AI 编程器专用」入口（带后缀）

给外部渠道单开一个入口，只有它会触发激活/弹付费。命名建议 --activate（也可叫 --onboard / --ide）：

voc-skill workspace --activate        # 外部 AI IDE 安装话术里用这个
  1. 安装/拷贝技能文件（含一次轻量 smoke 自检）
  2. ensureActivated()   ← 仅此入口执行
  3. 之后才进入任何取数/工作流

--smoke（内部/飞马/CI 用）行为完全不变。

1.3 弹窗按「状态」触发，而不是按命令——双保险（复用现有 token 逻辑）

关键：ensureActivated() 必须复用 credentials.js 的 readNewApiToken()/readVocToken()，不能另建 ~/.openclaw/...——否则会把已通过 ~/.claude/settings.json 配好的 Claude Code 用户误判为“缺 token”而误弹（正是你担心的场景）。

ensureActivated():
  newApi = readNewApiToken()   # sk-（含 settings.json 的 ANTHROPIC_AUTH_TOKEN 自愈）
  voc    = readVocToken()      # r: 会话 token
  if !newApi && !voc:                       # 真「缺 token」(onMissing)
      开 fmode-api 余额页 studio/?balance=fmodeapi（优先）或登录页，并提示可配 FMODE_API_KEY 自愈
  else:
      跳一次轻量探测（catalog 自检/getApig）判状态：
        ok      → print "✅ 已激活"，不开浏览器，放行
        402     → 按链路选充值页：sk-链→studio/?balance=fmodeapi；r:链→apig-pay/?user=..&apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF
        401/403 → 不充值，原样转述 assistantMessage
  开页 URL 追加 &channel={CH}&src=install 归因；始终打印 URL 兜底（headless）
  跨平台开浏览器: win `cmd /c start ""` / mac `open` / linux `xdg-open`；VOC_OPEN_PAYMENT=0 强制关

注：本地拿不到“余额数字”，402 以实际探测响应为准；“已激活”= 探测不报 402/401/403。这样：现场新教练（无任何 token）→ 装完立刻引导激活/充值；Claude Code 已配 sk-（或飞马已充值）→ 探测 ok，永不被打扰。命令隔离 + 状态隔离，双重防误弹。

提示词职责因此变薄：「粘贴→运行 --activate 命令→若弹出付费页就先充值/登录，再继续；若提示已激活就直接用」。弹付费稳定发生在烧 token 之前，且只对真正需要的人弹。

2. `Skill` 表多渠道改造（最小非破坏性）

现状 category 是单值 claude-code。两种做法，推荐 A：

方案 A（推荐）：给 `Skill` 加一个 Object 字段 `installPrompts`

一行 skill 承载所有渠道，不改主键、不拆行：

installPrompts: {
  "claude-code": { "prompt": "<一键复制话术>", "command": "npx --yes @vocmarket/voc-skill@latest workspace --activate", "verified": true,  "verifiedAt": "2026-06-29" },
  "codex":       { "prompt": "...",            "command": "...",                                                     "verified": false, "verifiedAt": null },
  "workbuddy":   { "prompt": "...",            "command": "...",                                                     "verified": false, "verifiedAt": null }
}

再加 paymentConfig: { apigid, funId }（按渠道可不同 funId，做分渠道定价/归因）。前端按 installPrompts 的 key 渲染「渠道 Tab + 一键复制 + 已测试徽标」。

方案 B：每渠道一行 Skill

复用现有 category 字段，新增 category=codex/workbuddy 的行。优点是贴合现有结构，缺点是同一技能多行、话术/版本要同步维护。仅当前端/计费已强依赖按 category 取单行时才用。

3. 三套一键复制安装提示词（话术模板）

共同结构（占位 {CH}）：

「请在当前项目文件夹的终端执行：npx --yes @vocmarket/voc-skill@latest workspace --activate。安装完成后：若显示「✅ 已激活」（你在 Claude Code 配了 fmode 的 sk-、或已在飞马充值），直接继续；若浏览器自动弹出充值页（sk- 链：studio/?balance=fmodeapi；r: 会话链：apig-pay），说明尚未激活，请先扫码登录/充值； 在付费页完成前，不要进入任何取数/报告流程（避免空耗 token）。拿到 token 后写入 .env.local（FMODE_API_KEY=sk-... 或 VOC_TOKEN=r:...）或 ~/.claude/voc-credentials.json，再继续。全程以工具实际返回的 assistantMessage 为准。」

渠道差异（仅薄薄一层）：

Claude Code：作为 skill/plugin 安装，附 .mcp.json 注册说明
Codex：在 Codex CLI 终端粘贴运行；说明其 config 注册方式
Workbuddy：对应其技能/命令注册入口

4. 安全（更正我之前的误判）

收回之前的警告：读 ~/.claude/settings.json 的 env.ANTHROPIC_AUTH_TOKEN(sk-) 是本产品正常的计费 token 解析路径，已由 pickFmodeAnthropicToken 门控（必须 sk-、非 sk-ant-、base 指向 fmode）。那是用户自己的 fmode 计费 key、本地鉴权，不是跨应用抓取——之前是我理解错了，这段不用从话术里删。
代码里已守住的红线：token 绝不回显到报告/日志/聊天；不发往第三方。保持这两点即可。
401/403 不走充值，原样转述 assistantMessage；仅「真缺 token」与真 402 引导付费，且缺 token 优先自愈读 sk-。

5. 待你确认/我可执行的落地项

给 Skill 表加 installPrompts(Object)、paymentConfig(Object) 字段，并回填 voc-skill 三渠道话术（用你给的 masterKey 可直接写）。
改 @vocmarket/voc-skill 包：新增 workspace --activate + ensureActivated()，复用 mcp/src/core/credentials.js 与 payment-links.js（readNewApiToken/readVocToken/buildVocRechargeInfo/buildFmodeApiRechargeUrl），加跨平台开浏览器 + URL 兜底 + VOC_OPEN_PAYMENT 开关；--smoke 不动。
产出 Claude Code / Codex / Workbuddy 三套提示词并各自冒烟，回写 verified/verifiedAt。
~~apigid 不一致~~ 已澄清：payment-links.js 权威常量 VOC_SOCIAL_APIG_ID='Vo3ROWEvDy'、VOC_RECHARGE_FUN_ID='HOkkX72PMF'；旧 api-config.json 里的 7HwdQZk55B 是另一个/陈旧 apig，--activate 以 payment-links.js 为准。

voc-03-design.md 9.1 KB Trvalý odkaz Historie Surový

VOC-03 设计方案（重写版）：多渠道一键安装 + 安装即弹付费

0. 现状（基于 Parse Skill 表 + voc-api-catalog 代码实读）

1. 核心决策：①不动 --smoke ②新增专用入口 ③弹窗按 token/余额状态触发

1.1 为什么不能改 --smoke