@skillfm/local 2.6.4 → 2.7.0

package/dist/connectors/openai.js

@@ -0,0 +1,101 @@
+// sdk/skillfm-local/src/connectors/openai.ts
+//
+// OpenAI Usage API connector — 真实现
+// Doc: https://platform.openai.com/docs/api-reference/usage
+// Endpoint: GET /v1/organization/usage/completions
+// Auth: Authorization: Bearer <admin-key> (sk-admin-*)
+//
+// 注意: 用户必须使用 admin-level key 才能调 organization/usage 端点。
+// 普通 sk-* key 调会 401。
+import { BaseConnector } from './base.js';
+import { sanitizeError } from './types.js';
+const BASE_URL = 'https://api.openai.com';
+const PRICE_TABLE = {
+    'gpt-4o': { in: 2.5, out: 10 },
+    'gpt-4o-mini': { in: 0.15, out: 0.6 },
+    'gpt-4-turbo': { in: 10, out: 30 },
+    'gpt-4': { in: 30, out: 60 },
+    'o1': { in: 15, out: 60 },
+    'o1-mini': { in: 3, out: 12 },
+    'gpt-3.5-turbo': { in: 0.5, out: 1.5 },
+};
+function estimateUsd(model, in_tok, out_tok) {
+    if (!model)
+        return (in_tok / 1_000_000) * 2.5 + (out_tok / 1_000_000) * 10;
+    const key = Object.keys(PRICE_TABLE).find((k) => model.toLowerCase().includes(k));
+    const p = key ? PRICE_TABLE[key] : { in: 2.5, out: 10 };
+    return (in_tok / 1_000_000) * p.in + (out_tok / 1_000_000) * p.out;
+}
+export class OpenAIConnector extends BaseConnector {
+    id = 'openai';
+    name = 'OpenAI GPT';
+    is_real = true;
+    async fetchUsage(byok_key, opts) {
+        const start_unix = Math.floor(opts.start_date.getTime() / 1000);
+        const end_unix = Math.floor(opts.end_date.getTime() / 1000);
+        const params = new URLSearchParams({
+            start_time: String(start_unix),
+            end_time: String(end_unix),
+            bucket_width: '1d',
+            limit: String(opts.limit ?? 100),
+            group_by: 'model',
+        });
+        let url = `${BASE_URL}/v1/organization/usage/completions?${params}`;
+        const records = [];
+        while (url) {
+            const r = await this.safeFetch(url, {
+                method: 'GET',
+                headers: {
+                    authorization: `Bearer ${byok_key}`,
+                    'content-type': 'application/json',
+                },
+            }, byok_key);
+            if (!r.ok) {
+                const text = await r.text().catch(() => '<no body>');
+                throw new Error(sanitizeError(`OpenAI ${r.status}: ${text}`, byok_key));
+            }
+            const data = (await r.json());
+            for (const bucket of data.data ?? []) {
+                for (const item of bucket.results ?? []) {
+                    records.push({
+                        provider: 'openai',
+                        model: item.model ?? 'unknown',
+                        timestamp: new Date(bucket.start_time * 1000).toISOString(),
+                        input_tokens: item.input_tokens,
+                        output_tokens: item.output_tokens,
+                        estimated_usd: estimateUsd(item.model, item.input_tokens, item.output_tokens),
+                        calls: item.num_model_requests,
+                    });
+                }
+            }
+            url = data.has_more && data.next_page ? `${BASE_URL}${data.next_page}` : null;
+        }
+        return records;
+    }
+    async ping(byok_key) {
+        const fp = this.fingerprint(byok_key);
+        try {
+            // 拉最短窗口 (近 1 天)
+            const end = Math.floor(Date.now() / 1000);
+            const start = end - 86400;
+            const params = new URLSearchParams({
+                start_time: String(start),
+                end_time: String(end),
+                bucket_width: '1d',
+                limit: '1',
+            });
+            const r = await this.safeFetch(`${BASE_URL}/v1/organization/usage/completions?${params}`, {
+                method: 'GET',
+                headers: { authorization: `Bearer ${byok_key}` },
+            }, byok_key);
+            if (r.ok)
+                return { ok: true, key_fingerprint: fp };
+            const text = await r.text().catch(() => '');
+            return { ok: false, error: `HTTP ${r.status}: ${sanitizeError(text, byok_key)}`, key_fingerprint: fp };
+        }
+        catch (e) {
+            return { ok: false, error: sanitizeError(e, byok_key), key_fingerprint: fp };
+        }
+    }
+}
+//# sourceMappingURL=openai.js.map

package/dist/connectors/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/connectors/openai.ts"],"names":[],"mappings":"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"}

package/dist/connectors/qwen.d.ts

@@ -0,0 +1,10 @@
+import { BaseConnector } from './base.js';
+import type { ConnectorId, FetchUsageOptions, PingResult, UsageRecord } from './types.js';
+export declare class QwenConnector extends BaseConnector {
+    id: ConnectorId;
+    name: string;
+    is_real: boolean;
+    fetchUsage(byok_key: string, opts: FetchUsageOptions): Promise<UsageRecord[]>;
+    ping(byok_key: string): Promise<PingResult>;
+}
+//# sourceMappingURL=qwen.d.ts.map

package/dist/connectors/qwen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qwen.d.ts","sourceRoot":"","sources":["../../src/connectors/qwen.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAc1F,qBAAa,aAAc,SAAQ,aAAa;IAC9C,EAAE,EAAE,WAAW,CAAU;IACzB,IAAI,SAAY;IAChB,OAAO,UAAQ;IAET,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAkC7E,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAmBlD"}

package/dist/connectors/qwen.js

@@ -0,0 +1,66 @@
+// sdk/skillfm-local/src/connectors/qwen.ts
+//
+// Qwen (阿里通义/百炼/DashScope) connector — Day 4 真实现
+// Doc: https://help.aliyun.com/zh/model-studio
+// Endpoint: DashScope https://dashscope.aliyuncs.com (Bearer auth, **不需要 SignerV4**)
+//
+// 调研校准 (2026-04):
+//   - 阿里云核心 API (ECS / RDS / BSS) 走 SignerV4 + AccessKey ID/Secret
+//   - DashScope (Qwen 模型) 走简单 Bearer + DashScope API key (sk-xxx)
+//   - usage 时序 API 暂未公开 (DashScope console 内查), 但有 me/usage 端点
+//   - 替代: 用 list-deployments 端点验 key + 后续 sidecar 自统计
+import { BaseConnector } from './base.js';
+import { sanitizeError } from './types.js';
+const BASE_URL = 'https://dashscope.aliyuncs.com';
+export class QwenConnector extends BaseConnector {
+    id = 'qwen';
+    name = '阿里通义千问';
+    is_real = true;
+    async fetchUsage(byok_key, opts) {
+        // DashScope 没公开时序 usage. 用 ping-style endpoint 拿 quota snapshot
+        // sidecar 内 cron poll + brain 端做差量
+        const r = await this.safeFetch(`${BASE_URL}/api/v1/users/me`, {
+            method: 'GET',
+            headers: {
+                authorization: `Bearer ${byok_key}`,
+                'content-type': 'application/json',
+            },
+        }, byok_key);
+        if (!r.ok) {
+            const text = await r.text().catch(() => '');
+            throw new Error(sanitizeError(`Qwen DashScope ${r.status}: ${text}`, byok_key));
+        }
+        const data = (await r.json());
+        const used = data.output?.used ?? 0;
+        return [
+            {
+                provider: 'qwen',
+                model: 'quota-snapshot',
+                timestamp: opts.end_date.toISOString(),
+                input_tokens: 0,
+                output_tokens: 0,
+                // 复用 estimated_usd 字段为"已用 quota" (sidecar 解析时按 model 价目换算)
+                estimated_usd: used,
+                calls: 0,
+            },
+        ];
+    }
+    async ping(byok_key) {
+        const fp = this.fingerprint(byok_key);
+        try {
+            const r = await this.safeFetch(`${BASE_URL}/api/v1/users/me`, { method: 'GET', headers: { authorization: `Bearer ${byok_key}` } }, byok_key);
+            if (r.ok)
+                return { ok: true, key_fingerprint: fp };
+            const text = await r.text().catch(() => '');
+            return {
+                ok: false,
+                error: `HTTP ${r.status}: ${sanitizeError(text, byok_key)}`,
+                key_fingerprint: fp,
+            };
+        }
+        catch (e) {
+            return { ok: false, error: sanitizeError(e, byok_key), key_fingerprint: fp };
+        }
+    }
+}
+//# sourceMappingURL=qwen.js.map

package/dist/connectors/qwen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qwen.js","sourceRoot":"","sources":["../../src/connectors/qwen.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,iDAAiD;AACjD,+CAA+C;AAC/C,qFAAqF;AACrF,EAAE;AACF,kBAAkB;AAClB,mEAAmE;AACnE,kEAAkE;AAClE,+DAA+D;AAC/D,sDAAsD;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,QAAQ,GAAG,gCAAgC,CAAC;AAWlD,MAAM,OAAO,aAAc,SAAQ,aAAa;IAC9C,EAAE,GAAgB,MAAM,CAAC;IACzB,IAAI,GAAG,QAAQ,CAAC;IAChB,OAAO,GAAG,IAAI,CAAC;IAEf,KAAK,CAAC,UAAU,CAAC,QAAgB,EAAE,IAAuB;QACxD,gEAAgE;QAChE,mCAAmC;QACnC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,SAAS,CAC5B,GAAG,QAAQ,kBAAkB,EAC7B;YACE,MAAM,EAAE,KAAK;YACb,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,QAAQ,EAAE;gBACnC,cAAc,EAAE,kBAAkB;aACnC;SACF,EACD,QAAQ,CACT,CAAC;QACF,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACV,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,MAAM,KAAK,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;QAClF,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAwB,CAAC;QACrD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,CAAC;QACpC,OAAO;YACL;gBACE,QAAQ,EAAE,MAAM;gBAChB,KAAK,EAAE,gBAAgB;gBACvB,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE;gBACtC,YAAY,EAAE,CAAC;gBACf,aAAa,EAAE,CAAC;gBAChB,2DAA2D;gBAC3D,aAAa,EAAE,IAAI;gBACnB,KAAK,EAAE,CAAC;aACT;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,QAAgB;QACzB,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,SAAS,CAC5B,GAAG,QAAQ,kBAAkB,EAC7B,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,QAAQ,EAAE,EAAE,EAAE,EACnE,QAAQ,CACT,CAAC;YACF,IAAI,CAAC,CAAC,EAAE;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC;YACnD,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAC5C,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,QAAQ,CAAC,CAAC,MAAM,KAAK,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE;gBAC3D,eAAe,EAAE,EAAE;aACpB,CAAC;QACJ,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC;QAC/E,CAAC;IACH,CAAC;CACF"}

package/dist/connectors/types.d.ts

@@ -0,0 +1,47 @@
+export type ConnectorId = 'anthropic' | 'openai' | 'deepseek' | 'qwen' | 'doubao' | 'kimi';
+export interface UsageRecord {
+    /** Connector 标识 */
+    provider: ConnectorId;
+    /** 模型名 (e.g. "claude-3-5-sonnet-20241022", "gpt-4o-2024-11-20") */
+    model: string;
+    /** 数据时间 (ISO 8601) */
+    timestamp: string;
+    /** 输入 token 数 */
+    input_tokens: number;
+    /** 输出 token 数 */
+    output_tokens: number;
+    /** 估算花费 (USD) */
+    estimated_usd: number;
+    /** 调用次数 (本聚合周期) */
+    calls: number;
+}
+export interface FetchUsageOptions {
+    start_date: Date;
+    end_date: Date;
+    /** 最大返回条数,防爆 */
+    limit?: number;
+}
+export interface PingResult {
+    ok: boolean;
+    /** 错误信息,绝不含 key 全文 */
+    error?: string;
+    /** key fingerprint (前 8 字符 hash, 安全) */
+    key_fingerprint?: string;
+}
+export interface Connector {
+    id: ConnectorId;
+    name: string;
+    /** 是否真实现 (false = stub, Day 2 接) */
+    is_real: boolean;
+    /**
+     * 拉用量数据 — BYOK key 通过 byok_key 参数传入,函数 scope 结束应不再持有
+     */
+    fetchUsage(byok_key: string, opts: FetchUsageOptions): Promise<UsageRecord[]>;
+    /** 验 key 有效性 — 不写库 */
+    ping(byok_key: string): Promise<PingResult>;
+}
+/** key 安全处理:返前 8 字符 hash 给日志 */
+export declare function maskKey(key: string): string;
+/** 错误信息脱敏 — 移除可能的 key 子串 */
+export declare function sanitizeError(err: unknown, byok_key: string): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/connectors/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/connectors/types.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,QAAQ,GACR,UAAU,GACV,MAAM,GACN,QAAQ,GACR,MAAM,CAAC;AAEX,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,IAAI,CAAC;IACjB,QAAQ,EAAE,IAAI,CAAC;IACf,gBAAgB;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,WAAW,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9E,sBAAsB;IACtB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC7C;AAED,gCAAgC;AAChC,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI3C;AAED,4BAA4B;AAC5B,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKpE"}

package/dist/connectors/types.js

@@ -0,0 +1,24 @@
+// sdk/skillfm-local/src/connectors/types.ts
+//
+// LLM connector 共享类型 (Day 1 D1-C, sidecar 端)
+//
+// BYOK 红线 (CLAUDE.md):
+//   - API key 永远不出用户节点 — 只在调用瞬间从 in-memory 传入,函数 scope 结束 GC
+//   - error 路径绝不回显 key (mask 成 sk-***...***last4)
+//   - Day 3 凭证保险柜上线后,key 从 encrypted vault 取,不直接传
+/** key 安全处理:返前 8 字符 hash 给日志 */
+export function maskKey(key) {
+    if (!key || key.length < 8)
+        return '***invalid***';
+    const last4 = key.slice(-4);
+    return `${key.slice(0, 4)}***${last4}`;
+}
+/** 错误信息脱敏 — 移除可能的 key 子串 */
+export function sanitizeError(err, byok_key) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (!byok_key)
+        return msg;
+    // 移除完整 key 出现 (任何长度 ≥ 16 的子串都视作敏感)
+    return msg.replace(byok_key, maskKey(byok_key));
+}
+//# sourceMappingURL=types.js.map

package/dist/connectors/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/connectors/types.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,EAAE;AACF,6CAA6C;AAC7C,EAAE;AACF,uBAAuB;AACvB,6DAA6D;AAC7D,kDAAkD;AAClD,kDAAkD;AAuDlD,gCAAgC;AAChC,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,eAAe,CAAC;IACnD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,KAAK,EAAE,CAAC;AACzC,CAAC;AAED,4BAA4B;AAC5B,MAAM,UAAU,aAAa,CAAC,GAAY,EAAE,QAAgB;IAC1D,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,CAAC,QAAQ;QAAE,OAAO,GAAG,CAAC;IAC1B,mCAAmC;IACnC,OAAO,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;AAClD,CAAC"}

package/dist/index.js

@@ -1384,7 +1384,16 @@ async function cmdStatus() {
 function cmdHelp() {
     console.log(`${PKG_NAME} v${PKG_VERSION}
 
-Usage:
+Two top-level usages (subcommand router):
+  npx -y @skillfm/local mcp        Beacon MCP stdio server (cost-optimizer for any agent;
+                                     plug into Cursor / Claude Code / OpenClaw)
+  npx -y @skillfm/local skill <slug>
+                                   Run a SkillFM skill bundle on this node (BYOK; sidecar
+                                     auto-starts if needed)
+  npx -y @skillfm/local login      OAuth 2.1 device-flow activation (alias of \`activate\`)
+  npx -y @skillfm/local doctor     Three-layer self-check / config diagnostic
+
+Sidecar / harness commands (legacy direct CLI):
   skillfm-local start              Start local sidecar on 127.0.0.1:${DEFAULT_PORT}
                                      (falls back to a random port if ${DEFAULT_PORT} is taken)
   skillfm-local stop               Stop the running sidecar
@@ -1400,6 +1409,10 @@ Usage:
   skillfm-local doctor [--v2] [--disable-hooks] [--json]
                                    Three-layer self-check (Layer 1 SKILL.md / Layer 2 MCP
                                      reject / Layer 3 hook), or v0.2 layered defense check.
+  skillfm-local mcp                Boot the Beacon MCP stdio server (BYOK; reads
+                                     SKILLFM_AGENT_TOKEN; stdout reserved for JSON-RPC).
+  skillfm-local skill <slug>       Run a SkillFM skill bundle (delegates to run-skill).
+  skillfm-local login              Alias of \`activate\` (kept for the npx subcommand router).
   skillfm-local help               Show this help
 
 Service discovery:
@@ -1459,6 +1472,42 @@ const main = async () => {
             await cmdTunnel();
             break;
         }
+        case 'mcp': {
+            // Beacon MCP stdio server — merged in from @skillfm/beacon-mcp
+            // (Day 1 D1-B, 2026-05-01). Plug into Cursor / Claude Code / OpenClaw
+            // via `npx -y @skillfm/local mcp`. BYOK red line: only reads
+            // SKILLFM_AGENT_TOKEN; never touches LLM keys / cookies.
+            const { startServer } = await import('./mcp/index.js');
+            await startServer();
+            break;
+        }
+        case 'skill': {
+            // Alias for run-skill, kept for the npx subcommand router
+            // (`npx -y @skillfm/local skill <slug>`).
+            const { cmdRunSkill } = await import('./skill-runner/cli.js');
+            await cmdRunSkill();
+            break;
+        }
+        case 'login': {
+            // Alias for activate, kept for the npx subcommand router
+            // (`npx -y @skillfm/local login`). Activation is currently driven via
+            // the `start` sidecar's /activate/start + /activate/poll endpoints, so
+            // we surface the same "start sidecar" entry here for now and print a
+            // one-line hint pointing at the agent flow.
+            console.error(`[skillfm-local] 'login' triggers OAuth 2.1 device-flow activation.\n` +
+                `  → For interactive use: run \`skillfm-local start\` then visit /activate/start\n` +
+                `  → For agent-driven use: the sidecar's /activate/start + /activate/poll endpoints\n` +
+                `    are the canonical path (see harness PreToolUse hook).`);
+            await cmdStart();
+            break;
+        }
+        case 'vault': {
+            // Beacon credential vault (AES-256-GCM, ~/.skillfm/vault.enc).
+            // BYOK 红线: key 永不出节点, 不通过 web 中转, 仅 sidecar terminal 直接调用。
+            const { cmdVault } = await import('./vault/cli.js');
+            await cmdVault();
+            break;
+        }
         case 'help':
         case '--help':
         case '-h':