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);
+  }
+}
@@ -17,7 +17,7 @@ import { cmdPush } from './commands/push.js';
 import { cmdRun } from './commands/run.js';
 import { cmdValidate } from './commands/validate.js';
 import { cmdParts, cmdPartsScaffold, cmdPartsPublish } from './commands/parts.js';
-import { cmdRecipePush, cmdRecipeList, cmdRecipeDelete } from './commands/recipe.js';
+import { cmdRecipePush, cmdRecipeList, cmdRecipeDelete, cmdRecipeSearch, cmdRecipePull, cmdRecipeSubmitP } from './commands/recipe.js';
 import { cmdList } from './commands/list.js';
 import { cmdLogs } from './commands/logs.js';
 import { cmdUpdate } from './commands/update.js';
@@ -121,6 +121,21 @@ recipeCmd
  .command('delete <id>')
  .description('刪除 recipe（canonical_id 或 rec_hash）')
  .action((id: string) => cmdRecipeDelete(id));
+// 公庫互動（kbdb-base §7.5）
+recipeCmd
+  .command('search <query>')
+  .description('搜尋公庫 recipe（同名可多作者，附市場數據）')
+  .action((query: string) => cmdRecipeSearch(query));
+recipeCmd
+  .command('pull <canonical_id>')
+  .description('從公庫取一份 recipe 寫進自己私庫')
+  .option('--author <name>', '指定作者版本（不指定取市場最佳）')
+  .action((canonicalId: string, opts: { author?: string }) => cmdRecipePull(canonicalId, opts.author));
+recipeCmd
+  .command('submit-p <canonical_id>')
+  .description('把私庫某 recipe 投稿到公庫（新增作者版本，需暴露同意）')
+  .option('--author <name>', '署名作者（預設用 recipe 既有 author）')
+  .action((canonicalId: string, opts: { author?: string }) => cmdRecipeSubmitP(canonicalId, opts.author));

 // acr auth-recipe list / info / scaffold
 const authRecipeCmd = program.command('auth-recipe').description('第三方服務認證 Recipe（新增服務整合）');
@@ -144,6 +144,25 @@ export class CfAccountClient {
    const result = await this.cf<{ subdomain: string }>('/workers/subdomain');
    return result.subdomain;
  }
+
+  // D1 (KBDB Base). Free on Workers Free plan, no credit card (kbdb-base Q4 verified).
+  async listD1Databases(): Promise<Map<string, string>> {
+    const result = await this.cf<Array<{ uuid: string; name: string }>>('/d1/database?per_page=100');
+    const map = new Map<string, string>();
+    for (const db of result) map.set(db.name, db.uuid);
+    return map;
+  }
+
+  async ensureD1Database(name: string, existing?: Map<string, string>): Promise<string> {
+    const known = existing ?? (await this.listD1Databases());
+    const found = known.get(name);
+    if (found) return found;
+    const result = await this.cf<{ uuid: string; name: string }>(
+      '/d1/database',
+      { method: 'POST', body: JSON.stringify({ name }) },
+    );
+    return result.uuid;
+  }
 }

 /** AES-GCM 加密 credential（與 cypher-executor credential-injector 解密邏輯對應）*/
@@ -67,6 +67,15 @@ const ENV_MAP: Record<string, keyof ArcrunConfig> = {
 */
 export const DEFAULT_MCP_URL = 'https://mcp.arcrun.dev';

+/**
+ * 公庫 URL（recipe pull/search/submit-p 的對象，kbdb-base §7.5）。
+ * 公庫 = 官方 SaaS cypher（唯一公共真相）。self-hosted 用戶的「私庫」是自己的 cypher
+ * （getCypherExecutorUrl），但 pull/搜尋/投稿都對著**官方公庫**這個固定 URL。
+ * fork 者可用 ARCRUN_PUBLIC_LIBRARY_URL env 覆蓋。
+ */
+export const DEFAULT_PUBLIC_LIBRARY_URL =
+  process.env.ARCRUN_PUBLIC_LIBRARY_URL ?? 'https://cypher.arcrun.dev';
+
 export function configExists(): boolean {
  return existsSync(CONFIG_PATH) || findProjectConfig() !== undefined;
 }
@@ -47,6 +47,7 @@ export interface DeployContext {
  apiToken: string;
  workerSubdomain: string;
  kvNamespaceIds: Record<string, string>; // title → id
+  d1DatabaseId?: string; // KBDB Base D1 (arcrun-kbdb); injected into kbdb wrangler.toml
 }

 export interface DeployResult {
@@ -111,6 +112,23 @@ export async function downloadAndDeploy(ctx: DeployContext, ref = 'main'): Promi
    }
  }

+  // 3.5 KBDB Base: D1 建好後套 migration（建三表 + recipe_stat seed）。
+  //     建 D1（cf-api ensureD1Database）只產生空資料庫，schema 要靠這步套。
+  //     migration 檔來自同一份 tarball（root/kbdb/migrations/0001_base.sql），與 wasm 同源，
+  //     不依賴本地 CLI 安裝路徑。0001_base.sql 全用 IF NOT EXISTS / INSERT OR IGNORE → 可重複套（idempotent）。
+  if (ctx.d1DatabaseId) {
+    const migPath = join(root, 'kbdb', 'migrations', '0001_base.sql');
+    if (existsSync(migPath)) {
+      try {
+        await applyD1Migration(ctx, readFileSync(migPath, 'utf8'));
+      } catch (e) {
+        failures.push(`D1 migration (${ctx.d1DatabaseId}): ${e instanceof Error ? e.message : String(e)}`);
+      }
+    } else {
+      failures.push(`D1 migration: 部署物缺 kbdb/migrations/0001_base.sql（${migPath}）`);
+    }
+  }
+
  const cypherExecutorUrl = ctx.workerSubdomain
    ? `https://arcrun-cypher-executor.${ctx.workerSubdomain}.workers.dev`
    : undefined;
@@ -132,6 +150,30 @@ export async function downloadAndDeploy(ctx: DeployContext, ref = 'main'): Promi
  };
 }

+/**
+ * 對 D1 套 SQL migration（透過 CF API `/d1/database/{id}/query`，非 wrangler）。
+ * 用 init 已驗的 ctx.apiToken + accountId；query 端點接受多語句檔，一次送整份 0001_base.sql。
+ */
+async function applyD1Migration(ctx: DeployContext, sql: string): Promise<void> {
+  const url = `https://api.cloudflare.com/client/v4/accounts/${ctx.accountId}/d1/database/${ctx.d1DatabaseId}/query`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${ctx.apiToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ sql }),
+    signal: AbortSignal.timeout(60_000),
+  });
+  const json = (await res.json().catch(() => null)) as
+    | { success?: boolean; errors?: Array<{ message?: string }> }
+    | null;
+  if (!res.ok || !json?.success) {
+    const detail = json?.errors?.map(e => e.message).filter(Boolean).join('; ') || `HTTP ${res.status}`;
+    throw new Error(detail);
+  }
+}
+
 /** 下載 codeload tarball 解壓到暫存目錄，回傳解壓出的 repo root 路徑。*/
 async function downloadRepoTarball(ref: string): Promise<string> {
  const url = `https://codeload.github.com/${ARCRUN_REPO}/tar.gz/${ref}`;
@@ -212,6 +254,14 @@ function injectWranglerConfig(tomlPath: string, ctx: DeployContext): void {
    );
  }

+  // KBDB Base: inject user's D1 database_id into [[d1_databases]] (placeholder in repo toml)
+  if (ctx.d1DatabaseId && /database_id\s*=/.test(toml)) {
+    toml = toml.replace(
+      /(database_id\s*=\s*")[^"]*(")/,
+      `$1${ctx.d1DatabaseId}$2`,
+    );
+  }
+
  toml = stripOfficialOnlyBindings(toml);

  writeFileSync(tomlPath, toml, 'utf8');