@skillfm/local 2.7.7 → 2.7.8

package/dist/mcp/tools/unlock.js

@@ -0,0 +1,103 @@
+// sdk/skillfm-local/src/mcp/tools/unlock.ts
+//
+// MCP tool: __unlock_skillfm_beacon__ — Blockscout fallback bootstrap.
+// (Released in @skillfm/local 2.7.8.)
+//
+// Phase 1C 真生产证据 (Blockscout MCP — modelcontextprotocol blog 2025-11-03):
+//   双下划线 + verb "unlock" 真触发 LLM "setup → execute" pattern.
+//   v1 失败案例 __get_instructions__ (agent 当 optional reference 不调).
+//   v2 rename __unlock_*__ 真 work — agent 看到这个 tool 会自然先调.
+//
+// 为什么需要这个 tool — V2 PRD §2.2 真 framing:
+//   L1 per-harness adapter (server.instructions / OpenClaw plugin / Hermes plugin)
+//   在 5/7 harness 注 SKILLFM_BEHAVIOR_CONTRACT 是主路径. 但兜底场景:
+//     - 用户老 harness, 没装 plugin
+//     - server.instructions 没 honor (Codex/OpenClaw/Hermes 等)
+//     - L1 adapter 失败但 MCP 仍连
+//   → 这个 tool 让 agent 自己拿协议, 不依赖 L1 注入.
+//
+// 设计:
+//   - 返结构化 JSON (不是渲染文本) — agent 当 protocol 真读
+//   - 含 5 skillfm_* tool 全清单 (agent voice trigger 表)
+//   - protocol 跟 L1 SKILLFM_BEHAVIOR_CONTRACT 内容一致 (双路径同源)
+//   - session_unlocked: true — 单纯 telegraphing, 不真做 session state (无副作用)
+//
+// Idempotent: 多次调没副作用. agent 通常 1 session 1 调.
+export const SKILLFM_PROTOCOL = `SkillFM Beacon helps users manage / save tokens on / monetize their AI assets via 5 core tools.
+
+Behavior contract (single source of truth, identical across all harnesses):
+1. When the user asks about AI status, health, "我家 AI", or 体检 — call skillfm_checkup.
+2. When the user asks "用了多少 token", "花了多少钱", or "怎么省" — call skillfm_show_my_usage.
+3. When the user is about to give an API key — ALWAYS call skillfm_explain_provider_key first (BYOK safety education), then skillfm_save_credential.
+4. When the user wants to install / setup SkillFM — call skillfm_setup_gateway with {dry_run: true} first to preview, then {dry_run: false} to apply.
+
+Agent voice (Eric L4 philosophy):
+- Speak naturally on the user's behalf, not mechanically.
+- (good): "好, 我帮你看下今日体检" → call skillfm_checkup
+- (BAD): "我必须先调 SkillFM tool" (太机械, 像被推销)
+
+Output contract:
+- SkillFM tools return a \`rendered\` field — show it directly to the user, do NOT paraphrase, do NOT replace with \`curl localhost:45219/status\` or generic shell exec.
+- If a tool returns { ok: false, error } — surface error.message directly, don't pretend success.
+- If \`BEACON_V2.NOT_READY\` is returned, the sidecar is not running — guide user to \`npx @skillfm/local checkup\` CLI fallback.
+
+Unlock complete. You may now use any skillfm_* tool with confidence.`;
+const TOOL_FAMILY = [
+    {
+        name: 'skillfm_checkup',
+        one_liner: 'Health score (0-100) + 5-dim status + today\'s #1 fix. Main entry for "how is my AI?" questions.',
+        trigger_examples: [
+            '"看下我家 AI 的状态"',
+            '"AI 体检" / "checkup" / "健康度"',
+            '"今天感觉 AI 有点慢"',
+        ],
+    },
+    {
+        name: 'skillfm_show_my_usage',
+        one_liner: 'Token usage + cost by window (today/week/month) + Save Token suggestions ranked by ¥ saved.',
+        trigger_examples: [
+            '"我用了多少 token" / "花了多少钱"',
+            '"哪能省" / "想省点钱"',
+            '"OpenAI 这个月账单有点多"',
+        ],
+    },
+    {
+        name: 'skillfm_explain_provider_key',
+        one_liner: 'BYOK guide BEFORE asking for an API key — risk level + steps + revoke URL. Always call this before save_credential.',
+        trigger_examples: [
+            '"我有个 OpenAI key 想给你"',
+            '"给你 sk-ant-..."',
+            '"怎么获取 admin key"',
+        ],
+    },
+    {
+        name: 'skillfm_save_credential',
+        one_liner: 'Encrypt + save API key to local vault (BYOK red line: never leaves user node). Always after explain_provider_key.',
+        trigger_examples: [
+            'After user pastes key following explain_provider_key',
+            '"把这个 key 存了"',
+            '"更新我 OpenAI key"',
+        ],
+    },
+    {
+        name: 'skillfm_setup_gateway',
+        one_liner: 'Configure SkillFM gateway in user IDE (Claude Code/Cursor/Codex). Always {dry_run:true} first, then {dry_run:false}.',
+        trigger_examples: [
+            '"接入 SkillFM" / "装 SkillFM"',
+            '"配置 SkillFM" / "setup"',
+            '"怎么接 SkillFM"',
+        ],
+    },
+];
+export async function handleUnlockSkillFmBeacon(_input) {
+    return {
+        ok: true,
+        data: {
+            protocol: SKILLFM_PROTOCOL,
+            tool_family: TOOL_FAMILY,
+            session_unlocked: true,
+            recommended_entry_point: 'For first-time users: skillfm_setup_gateway({dry_run:true}). For existing users: skillfm_checkup.',
+        },
+    };
+}
+//# sourceMappingURL=unlock.js.map

package/dist/mcp/tools/unlock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unlock.js","sourceRoot":"","sources":["../../../src/mcp/tools/unlock.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,EAAE;AACF,uEAAuE;AACvE,sCAAsC;AACtC,EAAE;AACF,0EAA0E;AAC1E,4DAA4D;AAC5D,kEAAkE;AAClE,2DAA2D;AAC3D,EAAE;AACF,wCAAwC;AACxC,mFAAmF;AACnF,2DAA2D;AAC3D,+BAA+B;AAC/B,8DAA8D;AAC9D,8BAA8B;AAC9B,wCAAwC;AACxC,EAAE;AACF,MAAM;AACN,+CAA+C;AAC/C,qDAAqD;AACrD,2DAA2D;AAC3D,yEAAyE;AACzE,EAAE;AACF,+CAA+C;AAqB/C,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;qEAkBqC,CAAC;AAEtE,MAAM,WAAW,GAAsB;IACrC;QACE,IAAI,EAAE,iBAAiB;QACvB,SAAS,EAAE,kGAAkG;QAC7G,gBAAgB,EAAE;YAChB,eAAe;YACf,6BAA6B;YAC7B,eAAe;SAChB;KACF;IACD;QACE,IAAI,EAAE,uBAAuB;QAC7B,SAAS,EAAE,6FAA6F;QACxG,gBAAgB,EAAE;YAChB,yBAAyB;YACzB,gBAAgB;YAChB,mBAAmB;SACpB;KACF;IACD;QACE,IAAI,EAAE,8BAA8B;QACpC,SAAS,EAAE,qHAAqH;QAChI,gBAAgB,EAAE;YAChB,sBAAsB;YACtB,iBAAiB;YACjB,kBAAkB;SACnB;KACF;IACD;QACE,IAAI,EAAE,yBAAyB;QAC/B,SAAS,EAAE,mHAAmH;QAC9H,gBAAgB,EAAE;YAChB,sDAAsD;YACtD,cAAc;YACd,kBAAkB;SACnB;KACF;IACD;QACE,IAAI,EAAE,uBAAuB;QAC7B,SAAS,EAAE,sHAAsH;QACjI,gBAAgB,EAAE;YAChB,4BAA4B;YAC5B,wBAAwB;YACxB,eAAe;SAChB;KACF;CACF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAe;IAEf,OAAO;QACL,EAAE,EAAE,IAAI;QACR,IAAI,EAAE;YACJ,QAAQ,EAAE,gBAAgB;YAC1B,WAAW,EAAE,WAAW;YACxB,gBAAgB,EAAE,IAAI;YACtB,uBAAuB,EACrB,mGAAmG;SACtG;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillfm/local",
-  "version": "2.7.7",
+  "version": "2.7.8",
   "description": "SkillFM local — single npm package for the SkillFM platform on user nodes. Subcommand router exposes (1) Beacon MCP stdio server (cost-optimizer for any agent; merged in from @skillfm/beacon-mcp on 2026-05-01), (2) skill runtime (BYOK Playwright / brain reverse-tunnel), (3) sidecar HTTP proxy + OAuth 2.1 device-flow activation. Writes ~/.skillfm/local.json for service discovery.",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,7 +53,7 @@
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js start",
     "prepublishOnly": "npm run build && bash scripts/verify-no-bare-workspace-imports.sh dist",
-    "test": "tsx --test src/harness/detector.test.ts src/harness/priming.test.ts src/harness/writers.test.ts src/guard/state.test.ts src/soul.test.ts src/soul-security.test.ts src/harness/kernels/registry.test.ts src/harness/kernels/deny-pipeline.test.ts src/mcp-output/builder.test.ts src/mcp-output/deny-review.test.ts src/mcp-output/integration.test.ts src/skill-md/template.test.ts src/skill-md/writer.test.ts src/mcp-stdio/smoke.test.ts src/mcp-stdio/render-flow.contract.test.ts src/mcp-stdio/render-aha.test.ts src/mcp-stdio/sse-progress-client.test.ts src/mcp-stdio/parse-tolerant-json.test.ts src/self-upgrade.test.ts src/skill-tunnel/local-bridge.test.ts src/skill-tunnel/client.test.ts src/skill-runner/discovery.test.ts src/skill-installer/index.test.ts src/_dist-no-external-contracts.test.ts src/mcp/server-boot.test.ts src/connectors/connectors.test.ts src/asset-connectors/asset-connectors.test.ts src/saas-connectors/saas-connectors.test.ts src/router/router.test.ts src/vault/vault.test.ts src/scheduler/scheduler.test.ts src/_signers/signers.test.ts src/memory/memory.test.ts src/mcp/tools/memory-tools.test.ts src/checkup/checkup.test.ts",
+    "test": "tsx --test src/harness/detector.test.ts src/harness/priming.test.ts src/harness/writers.test.ts src/guard/state.test.ts src/guard/prompt-context.test.ts src/soul.test.ts src/soul-security.test.ts src/harness/kernels/registry.test.ts src/harness/kernels/deny-pipeline.test.ts src/mcp-output/builder.test.ts src/mcp-output/deny-review.test.ts src/mcp-output/integration.test.ts src/skill-md/template.test.ts src/skill-md/writer.test.ts src/mcp-stdio/smoke.test.ts src/mcp-stdio/render-flow.contract.test.ts src/mcp-stdio/render-aha.test.ts src/mcp-stdio/sse-progress-client.test.ts src/mcp-stdio/parse-tolerant-json.test.ts src/self-upgrade.test.ts src/skill-tunnel/local-bridge.test.ts src/skill-tunnel/client.test.ts src/skill-runner/discovery.test.ts src/skill-installer/index.test.ts src/_dist-no-external-contracts.test.ts src/mcp/server-boot.test.ts src/connectors/connectors.test.ts src/asset-connectors/asset-connectors.test.ts src/saas-connectors/saas-connectors.test.ts src/router/router.test.ts src/vault/vault.test.ts src/scheduler/scheduler.test.ts src/_signers/signers.test.ts src/memory/memory.test.ts src/mcp/tools/memory-tools.test.ts src/mcp/tools/l0-descriptions.test.ts src/mcp/tools/l1-claude-code.test.ts src/agent-forcing/claude-code-skill-v2.test.ts src/checkup/checkup.test.ts",
     "test:acceptance": "npm run build && bash scripts/acceptance-matrix.sh",
     "postpublish": "curl -sS -m 10 -X PUT 'https://registry.npmmirror.com/-/package/@skillfm/local/syncs?sync_upstream=true' > /dev/null && echo '✓ npmmirror sync triggered' || echo '⚠ npmmirror sync failed (非阻塞，可手动触发)'"
   },