@vocmarket/voc-skill 0.3.28 → 0.3.30

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "voc-intelligence",
   "description": "VOC intelligence skills for Claude Code: end-to-end VOC business workflows, Xiaohongshu and Douyin trend reports, live social VOC collection, Fmode Doubao image analysis, token/recharge checks, evidence-card outputs, prioritized issue pools, single-problem deep dives, competitor maps, 7-day content plans, VOC-backed speaking script co-creation, boss/operator action plans, and multi-turn memory.",
-  "version": "0.3.28",
+  "version": "0.3.30",
   "author": {
     "name": "nkkj-BrainHack"
   }

package/bin/claude-voc.js

@@ -3,6 +3,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { ensureActivated } = require('../mcp/src/core/activation');
 
 const SOURCE_ROOT = path.resolve(__dirname, '..');
 const WORKSPACE_ROOT = process.cwd();
@@ -34,6 +35,7 @@ function usage() {
     'Usage:',
     '  claude-voc install',
     '  claude-voc workspace',
+    '  claude-voc workspace --activate',
     '  claude-voc install --workspace --smoke',
     '  claude-voc check',
     '  claude-voc smoke',
@@ -43,6 +45,7 @@ function usage() {
     'npx:',
     '  npx @vocmarket/voc-skill install',
     '  npx @vocmarket/voc-skill workspace --smoke',
+    '  npx @vocmarket/voc-skill workspace --activate   (其他 AI 编程器渠道专用：安装并按状态弹付费)',
     '',
     'Options:',
     '  --workspace      Install into ./.claude/plugins/voc-intelligence',
@@ -50,6 +53,8 @@ function usage() {
     '  --force          Allow overwriting an existing custom target',
     '  --skip-install   Skip npm install after copying files',
     '  --smoke          Run sample/preference/MCP smoke checks after install',
+    '  --activate       安装后按 token 状态激活：无 token 弹付费/登录页，有 token 直接放行（外部 AI IDE 专用，不影响 --smoke）',
+    '  --channel <name> 付费归因渠道名（claude-code/codex/workbuddy）',
     '  --help, -h       Show help'
   ].join('\n');
 }
@@ -65,6 +70,8 @@ function parseArgs(argv) {
     target: DEFAULT_TARGET,
     skipInstall: false,
     smoke: false,
+    activate: false,
+    channel: 'external',
     force: false,
     help: false
   };
@@ -88,6 +95,12 @@ function parseArgs(argv) {
       opts.skipInstall = true;
     } else if (token === '--smoke') {
       opts.smoke = true;
+    } else if (token === '--activate') {
+      opts.activate = true;
+    } else if (token === '--channel') {
+      opts.channel = argv[++i];
+    } else if (token.startsWith('--channel=')) {
+      opts.channel = token.slice('--channel='.length);
     } else if (token === '--help' || token === '-h') {
       opts.help = true;
     }
@@ -716,7 +729,7 @@ function printPath(opts) {
   }
 }
 
-function main() {
+async function main() {
   const directCommand = process.argv[2];
   if (directCommand === 'image' || directCommand === 'fmode-image') {
     run(process.execPath, ['mcp/src/tools/fmode-image-analysis.js', ...process.argv.slice(3)], SOURCE_ROOT);
@@ -728,17 +741,23 @@ function main() {
     console.log(usage());
     return;
   }
-  if (opts.command === 'install') return install(opts);
+  if (opts.command === 'install') {
+    install(opts);
+    if (opts.activate) {
+      await ensureActivated({ channel: opts.channel });
+    }
+    return;
+  }
   if (opts.command === 'check') return check(opts);
   if (opts.command === 'smoke') return smoke(opts);
   if (opts.command === 'path') return printPath(opts);
   throw new Error(`Unknown command: ${opts.command}\n\n${usage()}`);
 }
 
-try {
-  main();
-} catch (error) {
+main().catch((error) => {
   console.error('');
   console.error(`claude-voc failed: ${error.message}`);
   process.exit(1);
-}
+});
+
+

package/mcp/src/core/activation.js

@@ -0,0 +1,104 @@
+'use strict';
+
+// 安装收尾激活检查（仅供外部 AI IDE 渠道的 `workspace --activate` 调用）。
+//
+// 设计要点（与 voc-api-catalog 计费链一致，复用同一套凭证解析，绝不另建路径）：
+// - 复用 credentials.js 的 readNewApiToken()（sk- 主链）/ readVocToken()（r: 会话回退）。
+// - 按「是否已有可用 token」这一状态触发，而不是按命令触发：
+//     * 已检测到 token（飞马 UI 已写入，或 Claude Code 已配 sk-）→ 打印「✅ 已激活」，不弹浏览器。
+//     * 完全没有 token（现场新教练）→ 安装收尾立刻打开充值/登录页，避免进入取数流程后才弹、空耗 token。
+// - 不主动发计费请求做探测（探测会真扣费）；余额不足留给真实取数时由 catalog 的 402 分支处理。
+// - VOC_OPEN_PAYMENT=0 可强制关闭弹窗（CI / 冒烟 / 无头环境）。
+// - 始终把 URL 打印到终端兜底；并追加 &channel=&src=install 做渠道归因。
+// - token 绝不回显到终端 / 日志。
+
+const { spawn } = require('child_process');
+const { readNewApiToken, readVocToken } = require('./credentials');
+const { buildVocRechargeInfo } = require('./payment-links');
+
+function appendAttribution(rawUrl, channel, src) {
+  try {
+    const url = new URL(rawUrl);
+    if (channel) url.searchParams.set('channel', String(channel));
+    if (src) url.searchParams.set('src', String(src));
+    return url.toString();
+  } catch {
+    return rawUrl;
+  }
+}
+
+function openBrowser(url) {
+  try {
+    let command;
+    let args;
+    if (process.platform === 'win32') {
+      command = 'cmd';
+      // 空字符串是 start 的窗口标题占位，避免带引号的 URL 被当成标题
+      args = ['/d', '/s', '/c', 'start', '', url];
+    } else if (process.platform === 'darwin') {
+      command = 'open';
+      args = [url];
+    } else {
+      command = 'xdg-open';
+      args = [url];
+    }
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// channel: 渠道名（claude-code / codex / workbuddy），用于付费归因
+// src: 来源标记，默认 install
+async function ensureActivated({ channel = 'external', src = 'install' } = {}) {
+  if (process.env.VOC_OPEN_PAYMENT === '0') {
+    console.log('');
+    console.log('VOC_OPEN_PAYMENT=0：已跳过激活弹窗（CI/无头环境）。');
+    return { status: 'skipped' };
+  }
+
+  const newApiToken = readNewApiToken();
+  const vocToken = readVocToken();
+
+  if (newApiToken || vocToken) {
+    console.log('');
+    console.log('✅ 已激活：检测到 VOC 计费/会话 token，可直接开始取数，无需充值。');
+    console.log('（若取数时返回 402 余额不足，再按工具提示充值即可。）');
+    return { status: 'activated' };
+  }
+
+  // 完全没有 token：现场新用户。打开充值/登录页，引导先付费再进流程。
+  // 无 token 时 buildVocRechargeInfo 不会发起网络请求（resolveVocUserId 对空 token 直接返回）。
+  let recharge;
+  try {
+    recharge = await buildVocRechargeInfo({ token: '' });
+  } catch {
+    recharge = {};
+  }
+  const primaryUrl = appendAttribution(
+    recharge.recommendedPackageUrl || recharge.paymentUrl || 'https://app.fmode.cn/dev/apig-pay/',
+    channel,
+    src
+  );
+
+  console.log('');
+  console.log('⚠️  尚未检测到 VOC token —— 你还没有激活。');
+  console.log('为避免进入取数流程后才发现需要付费、白白消耗 token，请先在浏览器完成登录并充值/开通：');
+  console.log(`  ${primaryUrl}`);
+  if (recharge.paymentUrl) {
+    console.log(`  （充值入口：${appendAttribution(recharge.paymentUrl, channel, src)}）`);
+  }
+  console.log('完成付费后，再让 AI 进入取数/报告流程。');
+  console.log('如本机无法自动打开浏览器，请手动复制上面的链接到浏览器打开。');
+
+  const opened = openBrowser(primaryUrl);
+  if (!opened) {
+    console.log('（自动打开浏览器失败，请手动打开上面的链接。）');
+  }
+  return { status: 'needs_activation', url: primaryUrl };
+}
+
+module.exports = { ensureActivated, openBrowser, appendAttribution };

package/mcp/src/core/version-check.js

@@ -0,0 +1,211 @@
+'use strict';
+
+/**
+ * Self-update detection for the locally-installed VOC skill package.
+ *
+ * Surfaces a one-line "new version available" hint inside tool results so that
+ * a user running the skill in Claude Code is told, while they work, that an
+ * update exists. Network access is best-effort: it is throttled (24h cache),
+ * fail-silent (never throws, never blocks a tool call), and can be disabled.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+
+const PKG = '@vocmarket/voc-skill';
+const REGISTRY_URL = `https://registry.npmjs.org/${PKG.replace('/', '%2F')}/latest`;
+const TTL_MS = 24 * 60 * 60 * 1000; // check npm at most once per day
+const FETCH_TIMEOUT_MS = 1500;
+const CACHE_FILE = path.join(os.homedir(), '.claude', 'voc-update-check.json');
+
+let sessionNotified = false; // notify at most once per server process (session)
+let latestInMemory = null; // populated by primeUpdateCheck()
+
+function isDisabled() {
+  return process.env.VOC_SKILL_NO_UPDATE_CHECK === '1';
+}
+
+function getInstalledVersion() {
+  // version-check.js lives at <pkg>/mcp/src/core/, package.json at <pkg>/.
+  const candidates = [
+    path.join(__dirname, '..', '..', '..', 'package.json'),
+    path.join(__dirname, '..', '..', '..', 'skill-package-manifest.json')
+  ];
+  for (const file of candidates) {
+    try {
+      const json = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (json && typeof json.version === 'string') return json.version;
+    } catch (_) {
+      /* ignore and try next */
+    }
+  }
+  return null;
+}
+
+// Compare two semver strings. Returns 1 if a>b, -1 if a<b, 0 if equal.
+// Handles `major.minor.patch[-prerelease]`; a release outranks its prerelease.
+function compareSemver(a, b) {
+  const parse = v => {
+    const [core, pre] = String(v).trim().replace(/^v/, '').split('-');
+    const nums = core.split('.').map(n => parseInt(n, 10) || 0);
+    return { nums: [nums[0] || 0, nums[1] || 0, nums[2] || 0], pre: pre || '' };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < 3; i += 1) {
+    if (pa.nums[i] > pb.nums[i]) return 1;
+    if (pa.nums[i] < pb.nums[i]) return -1;
+  }
+  if (pa.pre === pb.pre) return 0;
+  if (!pa.pre) return 1; // release > prerelease
+  if (!pb.pre) return -1;
+  return pa.pre > pb.pre ? 1 : -1;
+}
+
+function readCache() {
+  try {
+    const cache = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+    if (cache && typeof cache === 'object') return cache;
+  } catch (_) {
+    /* no cache yet / unreadable */
+  }
+  return null;
+}
+
+function writeCache(next) {
+  try {
+    fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
+    const tmp = `${CACHE_FILE}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(next));
+    fs.renameSync(tmp, CACHE_FILE); // atomic swap, survives concurrent writers
+  } catch (_) {
+    /* caching is best-effort */
+  }
+}
+
+function fetchLatest() {
+  return new Promise(resolve => {
+    let done = false;
+    const finish = value => {
+      if (done) return;
+      done = true;
+      resolve(value);
+    };
+    try {
+      const req = https.get(REGISTRY_URL, { timeout: FETCH_TIMEOUT_MS }, res => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          return finish(null);
+        }
+        let body = '';
+        res.on('data', chunk => {
+          body += chunk;
+          if (body.length > 1e6) req.destroy(); // guard against pathological size
+        });
+        res.on('end', () => {
+          try {
+            const v = JSON.parse(body).version;
+            finish(typeof v === 'string' ? v : null);
+          } catch (_) {
+            finish(null);
+          }
+        });
+      });
+      req.on('timeout', () => {
+        req.destroy();
+        finish(null);
+      });
+      req.on('error', () => finish(null));
+    } catch (_) {
+      finish(null);
+    }
+  });
+}
+
+/**
+ * Fire-and-forget at server startup. Refreshes `latestInMemory` from the 24h
+ * cache, or from npm when the cache is stale. Always resolves, never throws.
+ */
+async function primeUpdateCheck() {
+  if (isDisabled()) return;
+  try {
+    const cache = readCache();
+    if (cache && cache.latest && typeof cache.fetchedAt === 'number' && Date.now() - cache.fetchedAt < TTL_MS) {
+      latestInMemory = cache.latest;
+      return;
+    }
+    const latest = await fetchLatest();
+    if (latest) {
+      latestInMemory = latest;
+      writeCache({ ...(cache || {}), latest, fetchedAt: Date.now() });
+    } else if (cache && cache.latest) {
+      latestInMemory = cache.latest; // fall back to a stale-but-known value
+    }
+  } catch (_) {
+    /* never let update detection affect the server */
+  }
+}
+
+/**
+ * Synchronous. Returns a one-line update notice the first time it is called in
+ * a session where a newer version is known, otherwise null. Safe to call from
+ * the hot path of every tool result.
+ */
+function consumeUpdateNotice() {
+  try {
+    if (isDisabled() || sessionNotified) return null;
+
+    let latest = latestInMemory;
+    if (!latest) {
+      const cache = readCache(); // prime may not have finished yet
+      if (cache && cache.latest) latest = cache.latest;
+    }
+    if (!latest) return null;
+
+    const installed = getInstalledVersion();
+    if (!installed) return null;
+    if (compareSemver(latest, installed) <= 0) return null;
+
+    // Don't re-nag across sessions for a version we already announced.
+    const cache = readCache() || {};
+    if (cache.notifiedVersion === latest) {
+      sessionNotified = true;
+      return null;
+    }
+
+    sessionNotified = true;
+    writeCache({ ...cache, notifiedVersion: latest });
+    return (
+      `ℹ️ VOC 技能包有新版本 ${latest}（当前 ${installed}）。新版多平台电商/海外选品等接口能力更全。\n` +
+      '更新命令：npx @vocmarket/voc-skill@latest install（或 workspace 模式同理）。'
+    );
+  } catch (_) {
+    return null;
+  }
+}
+
+/** Prepend the update notice (once) to a normalized tool result in place. */
+function applyUpdateNotice(result) {
+  try {
+    if (!result || typeof result.assistantMessage !== 'string') return result;
+    const notice = consumeUpdateNotice();
+    if (notice) {
+      result.assistantMessage = result.assistantMessage
+        ? `${notice}\n\n${result.assistantMessage}`
+        : notice;
+    }
+  } catch (_) {
+    /* never block a tool result */
+  }
+  return result;
+}
+
+module.exports = {
+  primeUpdateCheck,
+  consumeUpdateNotice,
+  applyUpdateNotice,
+  getInstalledVersion,
+  compareSemver
+};

package/mcp/src/server.js

@@ -16,6 +16,7 @@ const { runBusinessWorkflow } = require('./tools/voc-business-workflow-run');
 const { analyzeFmodeImage } = require('./tools/fmode-image-analysis');
 const { searchVocApis, getVocApiDoc, callVocApi } = require('./tools/voc-api-catalog-run');
 const { buildVocRechargeInfo, buildMissingTokenMessage, buildMissingNewApiTokenMessage } = require('./core/payment-links');
+const { primeUpdateCheck, applyUpdateNotice } = require('./core/version-check');
 
 function asToolResult(result) {
   const normalized = normalizeToolResult(result);
@@ -55,6 +56,7 @@ function normalizeToolResult(result = {}) {
   if (Object.prototype.hasOwnProperty.call(result, 'errors')) {
     normalized.errors = Array.isArray(result.errors) ? result.errors : [];
   }
+  applyUpdateNotice(normalized);
   return normalized;
 }
 
@@ -774,6 +776,7 @@ function createServer() {
 
 async function main() {
   const server = createServer();
+  primeUpdateCheck(); // fire-and-forget: refresh latest-version knowledge for update hints
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocmarket/voc-skill",
-  "version": "0.3.28",
+  "version": "0.3.30",
   "description": "Claude Code VOC intelligence skills for Xiaohongshu and Douyin trend reports, live social VOC collection, Fmode image analysis, single-issue deep dives, boss/operator action plans, and multi-turn memory.",
   "type": "commonjs",
   "bin": {

package/skill-package-manifest.json

@@ -1,7 +1,63 @@
 {
   "name": "claude-code-voc-intelligence",
-  "version": "0.3.28",
+  "version": "0.3.30",
+  "capabilities": {
+    "summary": "三类情报源同源接入：①社媒内容 ②国内电商+创作者情报 ③海外选品。统一 search→doc→call、鉴权计费一致。",
+    "channels": [
+      {
+        "key": "social",
+        "label": "社媒内容",
+        "platforms": 18,
+        "apis": 1018,
+        "examples": [
+          "抖音",
+          "小红书",
+          "TikTok",
+          "YouTube",
+          "微博",
+          "哔哩哔哩",
+          "快手",
+          "知乎",
+          "Instagram",
+          "Reddit",
+          "Twitter/X",
+          "微信/视频号"
+        ]
+      },
+      {
+        "key": "ecommerce",
+        "label": "国内电商 + 创作者情报",
+        "platforms": 32,
+        "apis": 285,
+        "examples": [
+          "京东",
+          "淘宝天猫",
+          "1688",
+          "抖音电商",
+          "TikTok Shop",
+          "闲鱼",
+          "得物",
+          "抖音星图",
+          "小红书蒲公英"
+        ]
+      },
+      {
+        "key": "overseas",
+        "label": "海外选品",
+        "platforms": 1,
+        "apis": 37,
+        "examples": [
+          "亚马逊"
+        ]
+      }
+    ],
+    "totals": {
+      "platforms": 51,
+      "apis": 1340
+    }
+  },
   "description": "Claude Code native VOC intelligence package for cross-industry social VOC workflows. Includes Xiaohongshu and Douyin trend intelligence, live token checks, evidence-card reports, single-issue VOC deep dives, boss/operator action plans, and scoped multi-turn memory.",
+  "changelogUrl": "https://www.npmjs.com/package/@vocmarket/voc-skill?activeTab=versions",
   "plugin": "voc-intelligence",
   "skills": [
     "xiaohongshu-trend-intelligence",
@@ -67,4 +123,4 @@
   "workspaceInstallCommand": "npx @vocmarket/voc-skill workspace --smoke",
   "workspaceInstallTarget": ".claude/plugins/voc-intelligence",
   "installHint": "Supports three delivery modes: unzip and run node install.js, install globally into ~/.claude/plugins/voc-intelligence, or install into the current workspace. Workspace mode writes .mcp.json plus .claude/skills/* entries for trend intelligence, issue pool, deep dive, competitor map, content plan, speaking script, VOC business workflow, and Fmode image analysis so VSCode Claude Code can discover the workflows without relying only on --plugin-dir."
-}
+}