feat(kbdb): recipe 公庫/私庫雙向機制 + UUID 身份 + KBDB Base + 市場數據

kbdb-base SDD §7.5（公庫/私庫雙向機制，richblack 2026-06-07 拍板）。 ## KBDB Base worker（新） - kbdb/：D1-only 核心三表（entries/templates/entry_values）+ CRUD + LIKE search + recipe-stats 端點（市場數據）+ 0001_base.sql migration（含 recipe_stat seed） ## Phase 2.3：init 建 D1 + 套 migration - cli cf-api.ts 加 listD1Databases/ensureD1Database；init 建 arcrun-kbdb D1 - deploy.ts 部署後對 D1 套 0001_base.sql（CF /d1/query API，idempotent）+ 注入 database_id ## Phase 5.1：recipe 成功記錄（市場數據來源） - GraphExecutor 收集本次用到的 recipe uuid（usedRecipeKeys） - executeWebhookGraph 執行結束一次性記 per-uuid 成功/失敗到 KBDB（fire-and-forget） ## Phase 7.5：recipe UUID 身份 + app-store 模型 - recipe 領 uuid=唯一身份；canonical_id/author/公私=屬性（§7.5.5） - recipe:{uuid} + idx:canonical/installed/hash；resolveRecipe 向後相容不破執行鏈 - POST /recipes/submit=領新 uuid 新增作者版本（非覆蓋，app-store） - GET /public-recipes 搜尋（多作者+per-uuid 市場星數）/ :id pull（選市場最佳） - 落空→found:false 創作引導（§7.5.6 閉環） - POST /recipes/migrate-uuid 一次性轉舊 key（增量寫不刪舊、冪等） - init-seed 用 UUID（author=system） ## 薄殼（rule 07 §5：CLI + MCP 覆蓋同組能力） - CLI: acr recipe search/pull/submit-p（config 加 DEFAULT_PUBLIC_LIBRARY_URL） - MCP: arcrun_recipe_search/pull/submit_p/push/list/delete（補齊漂移） ## 壓測修正 - api-recipe-seeds: google_sheets_append PUT→POST（:append 正確動詞，階段12）四 worker tsc 全綠（cypher/cli/kbdb/mcp）。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-07 16:18:10 +08:00
parent 95a1462b65
commit 6a75117ba3
28 changed files with 3438 additions and 37 deletions
@@ -201,6 +201,17 @@ async function initSelfHosted(
    process.exit(1);
  }

+  // 2.5 build D1 for KBDB Base (atomic universal table). Free on Workers Free, no credit card
+  //     (kbdb-base SDD Q4). idempotent: reuse if exists.
+  let d1DatabaseId = '';
+  try {
+    process.stdout.write(chalk.gray('  → D1 arcrun-kbdb...'));
+    d1DatabaseId = await cf.ensureD1Database('arcrun-kbdb');
+    console.log(chalk.green(' ✓'));
+  } catch (e) {
+    console.log(chalk.yellow(`\n  ⚠ D1 build failed (${e instanceof Error ? e.message : e}); KBDB Base 暫不可用，可 acr update 重試`));
+  }
+
  // 3. 查 workers.dev subdomain（cypher-executor WORKER_SUBDOMAIN 用）
  let workerSubdomain = '';
  try {
@@ -212,7 +223,7 @@ async function initSelfHosted(

  // 4. 下載 repo 部署物（含預編譯 wasm）+ 注入 KV id + wrangler deploy 全部 Worker
  console.log(chalk.gray('\n  → 下載部署物 + 部署 Worker（從 GitHub 拉預編譯 wasm，用你的 CF token 部署）...'));
-  const deployCtx: DeployContext = { accountId, apiToken: cfApiToken, workerSubdomain, kvNamespaceIds };
+  const deployCtx: DeployContext = { accountId, apiToken: cfApiToken, workerSubdomain, kvNamespaceIds, d1DatabaseId };
  const deploy = await downloadAndDeploy(deployCtx);
  const cypherUrl = deploy.cypherExecutorUrl
    ?? (workerSubdomain ? `https://arcrun-cypher-executor.${workerSubdomain}.workers.dev` : '');
@@ -6,7 +6,7 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import { readFileSync, existsSync } from 'node:fs';
-import { loadConfig, getCypherExecutorUrl } from '../lib/config.js';
+import { loadConfig, getCypherExecutorUrl, DEFAULT_PUBLIC_LIBRARY_URL } from '../lib/config.js';
 import { obtainExposureConsent } from '../lib/exposure-warning.js';
 import yaml from 'js-yaml';

@@ -22,6 +22,9 @@ interface RecipeYaml {
 }

 interface RecipeDefinition {
+  uuid?: string;            // UUID 身份模型（kbdb-base §7.5.5）
+  author?: string;
+  derived_from?: string;
  canonical_id: string;
  hash_id: string;
  display_name?: string;
@@ -237,3 +240,151 @@ export async function cmdRecipeDelete(id: string): Promise<void> {
    process.exit(1);
  }
 }
+
+// ── 公庫互動（kbdb-base §7.5，薄殼：只呼叫 API + 格式化，無業務邏輯）─────────────────
+
+interface PublicRecipeSummary {
+  uuid?: string;
+  canonical_id: string;
+  author?: string;
+  display_name?: string;
+  description?: string;
+  market_stat?: { success_count: number; failure_count: number } | null;
+}
+
+/** acr recipe search <q> — 搜尋公庫（GET /public-recipes?q=）。落空回創作引導（§7.5.6）。*/
+export async function cmdRecipeSearch(query: string): Promise<void> {
+  const spinner = ora(`搜尋公庫「${query}」`).start();
+  try {
+    const url = `${DEFAULT_PUBLIC_LIBRARY_URL}/public-recipes?q=${encodeURIComponent(query)}`;
+    const res = await fetch(url);
+    const data = await res.json() as
+      | { found: true; recipes: PublicRecipeSummary[]; count: number }
+      | { found: false; query: string; hint: string };
+    spinner.stop();
+
+    if (!data.found) {
+      console.log(chalk.yellow(`\n  公庫無符合「${query}」的 recipe。`));
+      console.log(chalk.gray(`  ${data.hint}`));
+      console.log(chalk.gray('  做一個：建 recipe YAML → acr recipe push（私庫）→ acr recipe submit-p（投稿成為作者）。\n'));
+      return;
+    }
+
+    console.log(chalk.bold(`\n  公庫 recipes（${data.count} 個，同名可多作者）\n`));
+    for (const r of data.recipes) {
+      const s = r.market_stat;
+      const stat = s ? chalk.gray(`  ✓${s.success_count}/✗${s.failure_count}`) : chalk.gray('  （無市場數據）');
+      console.log(`  • ${chalk.cyan(r.canonical_id.padEnd(20))} ${chalk.magenta('@' + (r.author ?? '?'))}${stat}  ${r.display_name ?? ''}`);
+      if (r.description) console.log(`    ${chalk.gray(r.description)}`);
+    }
+    console.log(chalk.gray('\n  取用：acr recipe pull <canonical_id> [--author=<name>]\n'));
+  } catch (e) {
+    spinner.fail(chalk.red(`網路錯誤：${e instanceof Error ? e.message : e}`));
+    process.exit(1);
+  }
+}
+
+/** acr recipe pull <canonical_id> [--author] — 從公庫取一份 recipe 寫進自己私庫。*/
+export async function cmdRecipePull(canonicalId: string, author?: string): Promise<void> {
+  const config = loadConfig();
+  if (!config.api_key) {
+    console.error(chalk.red('缺少 API Key，請先執行 acr init'));
+    process.exit(1);
+  }
+  const spinner = ora(`從公庫取 recipe「${canonicalId}」${author ? `（@${author}）` : ''}`).start();
+  try {
+    // 1. 從公庫取全文（不指定 author → 公庫回市場最佳版本）。
+    const q = author ? `?author=${encodeURIComponent(author)}` : '';
+    const pubRes = await fetch(`${DEFAULT_PUBLIC_LIBRARY_URL}/public-recipes/${encodeURIComponent(canonicalId)}${q}`);
+    const pub = await pubRes.json() as
+      | { found: true; recipe: RecipeDefinition & { uuid?: string; author?: string }; market_stat?: unknown }
+      | { found: false; canonical_id: string; hint: string };
+
+    if (!pub.found) {
+      spinner.stop();
+      console.log(chalk.yellow(`\n  公庫無 recipe「${canonicalId}」。`));
+      console.log(chalk.gray(`  ${pub.hint}\n`));
+      return;
+    }
+
+    // 2. 寫進自己私庫（POST /recipes，帶 derived_from 溯源 + 種子級同意：pull 公庫公共資料非新暴露）。
+    const r = pub.recipe;
+    const executorUrl = getCypherExecutorUrl(config);
+    const installRes = await fetch(`${executorUrl}/recipes`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Arcrun-API-Key': config.api_key },
+      body: JSON.stringify({
+        ...r,
+        derived_from: r.uuid,       // 溯源：私庫這份來自公庫哪個 uuid
+        exposure_consent: {
+          confirmed_by_human: true,
+          understood: `pull from public library: ${canonicalId}`,
+          confirmed_at: new Date().toISOString(),
+        },
+      }),
+    });
+    const inst = await installRes.json() as { success: boolean; recipe?: RecipeDefinition; error?: string };
+    if (!inst.success) {
+      spinner.fail(chalk.red(`寫入私庫失敗：${inst.error ?? '未知錯誤'}`));
+      process.exit(1);
+    }
+    spinner.succeed(chalk.green(`✓ recipe「${canonicalId}」${author ? `（@${author}）` : ''} 已拉進私庫`));
+    console.log(chalk.gray(`  在 workflow 用 component: ${canonicalId}\n`));
+  } catch (e) {
+    spinner.fail(chalk.red(`網路錯誤：${e instanceof Error ? e.message : e}`));
+    process.exit(1);
+  }
+}
+
+/** acr recipe submit-p <canonical_id> — 把私庫某 recipe 投稿到公庫（新增作者版本，需暴露同意）。*/
+export async function cmdRecipeSubmitP(canonicalId: string, author?: string): Promise<void> {
+  const config = loadConfig();
+  if (!config.api_key) {
+    console.error(chalk.red('缺少 API Key，請先執行 acr init'));
+    process.exit(1);
+  }
+  const executorUrl = getCypherExecutorUrl(config);
+
+  // 1. 從私庫取這份 recipe 全文。
+  const myRes = await fetch(`${executorUrl}/recipes/${encodeURIComponent(canonicalId)}`, {
+    headers: { 'X-Arcrun-API-Key': config.api_key },
+  });
+  const my = await myRes.json() as { success: boolean; recipe?: RecipeDefinition & { uuid?: string }; error?: string };
+  if (!my.success || !my.recipe) {
+    console.error(chalk.red(`私庫找不到 recipe「${canonicalId}」：${my.error ?? ''}`));
+    process.exit(1);
+  }
+
+  // 2. 投稿到公庫 = 暴露面 → 取得人類明示同意（mindset §6）。
+  const consent = await obtainExposureConsent({
+    kind: 'recipe',
+    resourceName: canonicalId,
+    destination: `公庫（${DEFAULT_PUBLIC_LIBRARY_URL}）`,
+  });
+  if (!consent) process.exit(1);
+
+  const spinner = ora(`投稿 recipe「${canonicalId}」到公庫`).start();
+  try {
+    const res = await fetch(`${DEFAULT_PUBLIC_LIBRARY_URL}/recipes/submit`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        ...my.recipe,
+        author: author ?? my.recipe.author,
+        derived_from: my.recipe.derived_from ?? my.recipe.uuid,
+        submitter: author ?? config.api_key,
+        exposure_consent: consent,
+      }),
+    });
+    const data = await res.json() as { success: boolean; recipe?: { uuid?: string; author?: string }; error?: string };
+    if (!data.success) {
+      spinner.fail(chalk.red(`投稿失敗：${data.error ?? '未知錯誤'}`));
+      process.exit(1);
+    }
+    spinner.succeed(chalk.green(`✓ recipe「${canonicalId}」已投稿公庫（新增作者版本 @${data.recipe?.author ?? '?'}）`));
+    console.log(chalk.gray('  別人能搜到並 pull；市場數據累積後決定它被不被選用。\n'));
+  } catch (e) {
+    spinner.fail(chalk.red(`網路錯誤：${e instanceof Error ? e.message : e}`));
+    process.exit(1);
+  }
+}