yaf 项目导读

{
  "main": "worker/index.ts",          // 入口：整个后端从这里开始
  "d1_databases": [{ "binding": "DB", ... }],      // 数据库，代码里用 env.DB 访问
  "ai": { "binding": "AI", ... },                  // Workers AI，env.AI.run(模型, 参数)
  "vectorize": [{ "binding": "VECTORS", ... }],    // 向量索引，env.VECTORS.query(...)
  "triggers": { "crons": ["*/15 * * * *"] },       // 每 15 分钟调用一次 scheduled()
  "workflows": [{ "name": "yaf-index", "binding": "INDEX_WORKFLOW", ... },
                { "name": "yaf-insight", "binding": "INSIGHT_WORKFLOW", ... }],
  "durable_objects": { "bindings": [{ "name": "WECHAT", ... }] }, // 微信长连接
  "r2_buckets": [{ "binding": "MEDIA", ... }]      // 图片/语音原文件（可选）
}

export interface Memo {
  id: string;            // 形如 "8f3c…" 的随机串
  content: string;       // Markdown 正文
  createdAt: number;     // 毫秒时间戳
  tags: string[];        // 字符串数组
  source: string;        // web | wechat | api | mcp | cli
  attachments?: Attachment[];   // ← 问号：可选字段，可能不存在
  private?: boolean;     // 隐私 memo：content 已是遮挡文本
  lenses?: string[];     // 命中的视图，如 ["todo"]
}

type ThemePref = "system" | "light" | "dark";      // 只能是这三个字符串
const SOURCES = ["web", "wechat", "api", "mcp", "cli"] as const;
type Source = (typeof SOURCES)[number];            // 推导出同样的联合

type Phase =
  | { kind: "loading" }
  | { kind: "setup"; tokenRequired: boolean }   // 还没有管理员，去初始化
  | { kind: "login" }
  | { kind: "app"; user: User };                // 已登录，user 一定存在

const [phase, setPhase] = useState<Phase>({ kind: "loading" });
if (phase.kind === "app") {
  console.log(phase.user.email);   // ✅ 检查器允许：kind 是 app 时必有 user
}
console.log(phase.user);           // ❌ typecheck 报错：其他 kind 没有 user

type PlanInput = Partial<Omit<InsightPlan, "id" | "createdAt">>;
// Omit：去掉某些字段；Partial：全部字段变可选 → 「创建时随便传哪几个都行」

type Memo = ReturnType<typeof toMemo>;
// typeof：取函数的类型；ReturnType：取它的返回值形状
// toMemo 改了返回结构，Memo 自动跟着变，不用手写两遍

async function request<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`/api${path}`, { ...init, credentials: "same-origin" });
  const data = await res.json().catch(() => ({}));
  if (!res.ok) throw new ApiError(res.status, ...);
  return data as T;          // 告诉检查器：按调用方说的形状对待
}

// 调用点用「类型的实参」指定 T：
api.listMemos(...)  // → request<{ memos: MemoHit[]; nextCursor: string | null }>
const { user } = await api.me();   // user 自动是 User 类型，有补全、拼错即报错

const [kw, sem] = await Promise.all([
  keywordCandidates(env, userId, opts.q),   // 关键词路（查 D1）
  semanticCandidates(env, userId, opts.q),  // 语义路（查向量库）
]);
// 两路同时出发，都回来才继续 —— 总耗时 ≈ 最慢的一路，不是两路之和

import { extractTags } from "../shared/tags";   // ../ 上一级目录
import type { Source } from "./env";             // type 只导入类型，运行时不存在
// import 的是「绑定的名字」，不是文件路径里的变量；
// 路径不写扩展名，打包器（第 14 章的 Vite）负责找到确切文件并拼装。

"scripts": { "dev": "vite", "typecheck": "tsc --noEmit",
             "deploy": "node scripts/preflight.mjs && vite build && wrangler deploy" },
"dependencies": { "hono": "^4.13.13", "react": "^19.3.1", "zod": "^4.6.7", ... },
"devDependencies": { "typescript": "^7.0.2", "vite": "^8.3.4", "wrangler": "^4.151.0" },
"workspaces": ["packages/*"]

export default {
  fetch(request, env, ctx) {              // 每个 HTTP 请求进来这里
    if (new URL(request.url).pathname === "/mcp") return handleMcp(request, env, ctx);
    return app.fetch(request, env, ctx);  // 其余交给 Hono（/api 路由 + 静态资源）
  },
  async scheduled(_controller, env, ctx) { // 定时触发（Cron Triggers）：每 15 分钟进来这里（第 9 章）
    ctx.waitUntil(Promise.allSettled([runDuePlans(env), judgeBackfill(env).then(() => backfillAll(env))]));
  },
} satisfies ExportedHandler<Env>;   // satisfies：检查「形状对不对」，但不改变推断

export interface Env {
  DB: D1Database;            // 必有：D1 数据库
  AI: Ai;                    // 必有：Workers AI
  VECTORS: Vectorize;        // 必有：向量索引
  MEDIA?: R2Bucket;          // 可选（问号）：R2 没开通就没有
  ENCRYPTION_KEY?: string;   // secret：加密用户密钥用
  SETUP_TOKEN?: string;      // secret：防抢先注册管理员
}

const app = new Hono<AppEnv>().basePath("/api");  // 之后写 /memos 实际是 /api/memos
app.route("/auth", auth);   // 登录相关 → 子路由 auth（worker/auth.ts）
app.route("/", memos);      // memo 相关 → 子路由 memos（worker/memos.ts）
// …… tokens / insights / wechat / autoTags / usage 同样挂载

// 子路由里，一个典型接口长这样：
memos.get("/memos/:id", requireScope("memos:read"), async (c) => {
  const memo = await getMemo(c.env.DB, c.get("user").id, c.req.param("id"), ...);
  if (!memo) return c.json({ error: "不存在" }, 404);
  return c.json({ memo });
});

export function requireScope(scope: Scope) {
  return createMiddleware<AppEnv>(async (c, next) => {
    const header = c.req.header("Authorization");
    if (header?.startsWith("Bearer ")) {          // Token 路线
      const found = await findToken(c.env.DB, header.slice(7).trim(), c.executionCtx);
      if (!found) return c.json({ error: "Token 无效或已过期" }, 401);
      if (!found.scopes.includes(scope)) return c.json({ error: `缺少权限 ${scope}` }, 403);
      c.set("user", found.user);                  // 存进上下文，下游 c.get("user")
      return next();
    }
    const user = await sessionUser(c);            // Cookie 路线（第 7 章细讲）
    if (!user) return c.json({ error: "未登录" }, 401);
    c.set("user", user);
    await next();
  });
}

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App";
import "./styles.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode><App /></StrictMode>,
);

if (phase.kind === "setup" || phase.kind === "login")
  return <AuthScreen mode={phase.kind} onDone={boot} />;
if (path === "/device") return <DeviceApprove />;
if (path.startsWith("/settings")) return <Settings user={phase.user} path={path} />;
return <Home user={phase.user} path={path} view={...} onLogout={logout} />;

export function navigate(path: string) {
  if (location.pathname + location.search + location.hash === path) return;
  history.pushState(null, "", path);            // 改地址栏，不刷新页面
  dispatchEvent(new PopStateEvent("popstate")); // 手动广播「地址变了」
}

export function usePath(): string {
  const [path, setPath] = useState(location.pathname);
  useEffect(() => {
    const on = () => setPath(location.pathname);
    addEventListener("popstate", on);           // 订阅地址变化
    return () => removeEventListener("popstate", on); // 清理：组件卸载时退订
  }, []);                                       // 空依赖 = 只在挂载后跑一次
  return path;
}

const reqId = useRef(0);          // ref：跨渲染存活、改它不触发重画
const load = useCallback(async (reset: boolean, from: string | null) => {
  const id = ++reqId.current;     // 发一个新号牌
  setLoading(true);
  const r = await api.listMemos({...});
  if (id !== reqId.current) return;   // 号牌过期 = 已有更新的请求 → 丢弃本次结果
  setMemos(reset ? r.memos : [...prev, ...r.memos]);
  setLoading(false);
}, [debounced, tag, lens, mode, sort]);

CREATE TABLE memos (
  id TEXT PRIMARY KEY,                 -- 随机 UUID 字符串，不用自增数字
  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  content TEXT NOT NULL,
  created_at INTEGER NOT NULL          -- 毫秒时间戳
);
CREATE INDEX idx_memos_user_created ON memos(user_id, created_at DESC);

CREATE TABLE memo_tags (              -- 标签拆成独立表，才能按标签筛选
  memo_id TEXT NOT NULL REFERENCES memos(id) ON DELETE CASCADE,
  user_id TEXT NOT NULL,
  tag TEXT NOT NULL,                   -- 存完整路径，如 "读书/历史"
  PRIMARY KEY (memo_id, tag)
);

const id = crypto.randomUUID();
await db.batch([
  db.prepare("INSERT INTO memos (id, user_id, content, source, created_at, updated_at)
              VALUES (?, ?, ?, ?, ?, ?)").bind(id, userId, text, source, now, now),
  ...tagStatements(db, id, userId, text),   // 先 DELETE 旧标签，再按 extractTags 结果 INSERT
  ...ftsStatements(db, id, userId, text),   // 全文索引（第 6 章）
]);
return { id, content: text, tags: extractTags(text).sort(), ... };

SELECT m.id, m.content, ...,
  (SELECT group_concat(tag, char(31)) FROM memo_tags WHERE memo_id = m.id) AS tags,
  (SELECT json_group_object(label, json_array(score, source))
     FROM memo_labels WHERE memo_id = m.id) AS labels,
  (SELECT json_group_array(json_object('id', a.id, 'kind', a.kind, ...))
     FROM attachments a WHERE memo_id = m.id) AS attachments
FROM memos m

const where = ["m.user_id = ?"];  params = [userId];       // 第一条铁律：必带归属
if (opts.visibility === "token") where.push(TOKEN_VISIBLE_SQL);  // 🔒 谁是 token、两个条件什么意思：第 7/10 章拆封
if (t) { where.push("EXISTS (SELECT 1 FROM memo_tags t WHERE t.memo_id = m.id
          AND (t.tag = ? OR t.tag LIKE ? ESCAPE '\\'))");
         params.push(t, `${t}/%`); }                       // 父标签含所有子标签
return { sql: where.join(" AND "), params };

import { normalizeTag, TAG_RE, TRAILING_PUNCT } from "../shared/tags";  // 前端
import { extractTags } from "../shared/tags";                            // 后端

export const TAG_RE = /(^|\s)#([^\s#]+)/gu;
export const TRAILING_PUNCT = /[.,;:!?，。；：！？、)）\]】"'”’]+$/u;

export function normalizeTag(raw: string): string | null {
  const cleaned = raw.replace(TRAILING_PUNCT, "");      // 防线三：去尾部标点
  const parts = cleaned.split("/").map((p) => p.trim()).filter(Boolean);
  return parts.length ? parts.join("/") : null;         // 层级 a/b/c 规整
}

function stripCode(content: string): string {           // 防线二：代码不算
  return content.replace(/```[\s\S]*?```/g, " ").replace(/`[^`\n]*`/g, " ");
}

export function extractTags(content: string): string[] {
  const tags = new Set<string>();
  for (const m of stripCode(content).matchAll(TAG_RE)) {
    const tag = normalizeTag(m[2]);
    if (tag) tags.add(tag);
  }
  return [...tags];
}

const segmenter = new Intl.Segmenter("zh", { granularity: "word" });

export function segmentWords(text: string): string[] {
  const out: string[] = [];
  for (const s of segmenter.segment(text))
    if (s.isWordLike) out.push(s.segment.toLowerCase());  // 去标点，统一小写
  return out;
  // "明天给妈妈打电话" → ["明天", "给", "妈妈", "打电话"]
}

export function queryTerms(q: string): string[] {          // 搜索词也切、也去重
  return [...new Set(q.trim().split(/\s+/).filter(Boolean)
    .flatMap((w) => segmentWords(w)))];
}

export function ftsStatements(db, memoId, userId, content) {
  return [
    db.prepare("DELETE FROM memos_fts WHERE memo_id = ?").bind(memoId),  // 先删
    db.prepare("INSERT INTO memos_fts (body, memo_id, user_id) VALUES (?, ?, ?)")
      .bind(segmentWords(plainText(content)).join(" "), memoId, userId), // 再插
  ];
}

function ftsQuery(terms: string[]) {
  return terms.map((t) => `"${t.replace(/"/g, '""')}"*`).join(" ");
  //  → '"妈妈"* "打电话"*'：每个词允许前缀扩展，词之间是 AND
}

export async function hashPassword(password: string): Promise<string> {
  const salt = crypto.getRandomValues(new Uint8Array(16));      // 每人一段新盐
  const hash = await pbkdf2(password, salt, PBKDF2_ITERATIONS); // 搅十万次
  return `pbkdf2$${PBKDF2_ITERATIONS}$${toB64(salt)}$${toB64(hash)}`;
}   // 库里存的是这串自带配方的文本，而不是裸指纹

export async function verifyPassword(password: string, stored: string) {
  const [algo, iter, salt, hash] = stored.split("$");   // 从存档里读出配方
  const actual = await pbkdf2(password, fromB64(salt), Number(iter));
  let diff = 0;                                          // 常量时间比较：
  for (let i = 0; i < actual.length; i++) diff |= actual[i] ^ expected[i];
  return diff === 0;
}

const sid = randomToken();                     // 256 位随机，猜不出来
await c.env.DB.prepare("INSERT INTO sessions (id_hash, ...) VALUES (?, ...)")
  .bind(await sha256(sid), ...);               // 库里只存 sid 的哈希！
setCookie(c, "yaf_sid", sid, {
  httpOnly: true,                              // JS 读不到 → XSS 偷不走
  secure: 协议是 https,                        // 明文网络上传不了
  sameSite: "Lax",                             // 别的网站发起的请求不带 → CSRF 难
  maxAge: 30 天,
});

export const SCOPES = ["memos:read", "memos:write", "export", "insights:read"] as const;

export async function createToken(db, userId, name, scopes, expiresAt) {
  const secret = "yaf_pat_" + randomToken(24);          // 明文：只此一次，还给用户
  await db.prepare(`INSERT INTO api_tokens (..., token_hash, prefix, scopes, ...)
        VALUES (..., ?, ?, ?, ...)`)
    .bind(..., await sha256(secret), secret.slice(0, 12 + 4), scopes.join(" "), ...);
  return { secret, ... };
}

export async function embed(env: Env, texts: string[]): Promise<number[][]> {
  const res = (await env.AI.run("@cf/baai/bge-m3", { text: texts })) as { data?: number[][] };
  return res.data;                      // 每段文字 → 1024 个小数
}

// indexMemos（search.ts:79，节选）：写一半的那条链路
const texts = rows.map((r) => embedText(r.content + (extra.get(r.id) ?? "")));
const vectors = await embed(env, withText.map((i) => texts[i]));
await env.VECTORS.upsert(withText.map((i, k) => ({
  id: rows[i].id,                       // 向量的主键 = memo 的 id
  values: vectors[k],                   // 1024 维
  metadata: { userId: ..., createdAt: ... },   // 随行小卡片，用于过滤
})));

const RRF_K = 60;
kw.forEach((id, i) => {
  scores.set(id, (scores.get(id) ?? 0) + 1 / (RRF_K + i + 1));  // 关键词第 i 名
});
sem.forEach(({ id, score }, i) => {
  scores.set(id, (scores.get(id) ?? 0) + 1 / (RRF_K + i + 1));  // 语义第 i 名
});  // 两路都出现的 memo：两项相加 → 天然排到最前

export function scheduleIndex(env, ctx, userId, memo) {
  ctx.waitUntil((async () => {
    const cur = await env.DB.prepare("SELECT content FROM memos WHERE id = ?")...
    const judged = await judgeMemo(env, row);        // 先判定（第 10 章）
    if (judged && !judged.private) await indexMemos(env, [row]);  // 非隐私才算
  })());
}

export class IndexWorkflow extends WorkflowEntrypoint<Env, { userId: string }> {
  async run(event, step) {
    for (let i = 0; i < 400; i++) {
      const n = await step.do(`batch ${i}`,
        { retries: { limit: 3, delay: "10 seconds", backoff: "exponential" }, timeout: "5 minutes" },
        async () => {
          const rows = await 取 50 条 vector_hash IS NULL 的 memo;
          await indexMemos(this.env, rows);
          return rows.length;
        });
      if (n < 50) break;          // 取不满一批 = 全部算完
    }
  }
}

export async function runDuePlans(env: Env) {
  const plans = await 查询 next_run_at 到期的计划（最多 20 条）;
  for (const plan of plans) {
    // 先把 next_run_at 推进到下一次，才启动生成 —— 条件里带旧值，
    // 若两个 Cron 撞车，只有改到那一条的能成功（乐观锁）
    const res = await db.prepare("UPDATE insight_plans SET next_run_at = ?, last_run_at = ?
        WHERE id = ? AND next_run_at = ?").bind(nextRun(...), now, plan.id, plan.next_run_at).run();
    if (!res.meta.changes) continue;
    await startInsight(env, plan.user_id, planConfig(plan), now);
  }
}

export async function startInsight(env, userId, plan, now) {
  const id = crypto.randomUUID();
  await 插入一条 status = 'generating' 的洞察记录;      // 先立牌子：正在生成
  await env.INSIGHT_WORKFLOW.create({ id, params: { insightId: id, userId, plan, ... } });
}

export const ReportSchema = z.object({
  title: z.string().describe("一句话标题，不超过 20 字"),
  summary: z.string().describe("2–4 句话的总体摘要"),
  themes: z.array(item).describe("反复出现的主题（2–4 条）"),
  connections: z.array(item).describe("新的连接……（0–3 条）"),
  questions: z.array(z.object({ question: z.string(), why: z.string(), refs }))
             .describe("值得继续追问自己的问题（1–3 条）"),
});

const { output } = await generateText({
  model, system: SYSTEM, prompt: formatMemos(memos),
  output: Output.object({ schema: ClusterSchema }),   // 让模型按 schema 说话
  maxRetries: 2,
});  // output 的类型自动是 z.infer<typeof ClusterSchema> —— TS 与 zod 在此会师

export interface Lens {
  key: string; name: string;
  question: string;    // 交给判定模型的问题
  threshold: number;   // 分数 ≥ 它 → 命中
  ask?: number;        // 分数落在 [ask, threshold) → 卡片上问用户
}

export const LENSES: Lens[] = [
  { key: "private", name: "隐私", threshold: 0.8,
    question: "这段文字是否写出了可以直接用来登录或访问账户的凭据的值……？" },
  { key: "todo", name: "待办", threshold: 0.7, ask: 0.4,
    question: "这条笔记是否记录了一件作者自己要去做的事……？" },
];
export const LENS_REV = 1;   // 视图集版本号：改问题或阈值就 +1

const state = [row.content, ...附件描述].join("\n").trim();
const questions = {};   // 一次把两个视图的问题都带上
for (const lens of LENSES) questions[lens.key] = { type: "noul", instructions: lens.question };
const scores = await askClef(env, state, questions);   // → { private: 0.02, todo: 0.81 }

const userPrivate = await 查 memo_labels 里用户手标的 private;
const isPrivate = userPrivate ? userPrivate.score >= 0.5          // 用户优先
                              : (scores.private ?? 0) >= 0.8;
const masked = isPrivate ? await maskPrivate(env, row.content) : null;

await env.DB.batch([
  // 带上 content = ? 条件：判定期间用户又编辑了 → 这批结果全部作废（防竞态）
  db.prepare("UPDATE memos SET judged_rev = ?, is_private = ?, masked_content = ?
              WHERE id = ? AND content = ?")...,
  ...LENSES.map((l) => db.prepare(`INSERT INTO memo_labels ... source = 'model', ...
      ON CONFLICT(memo_id, label) DO UPDATE SET ... WHERE memo_labels.source = 'model'`)...),
]);

GitHub: ghp_9f8e7d6c5b4a3210fedcba     →   GitHub: ••••
服务器 root 密码 Tr0ub4dor&3            →   服务器 root 密码 ••••
这只是讨论密码管理策略的一行            →   （原样保留：没有凭据值）

claude mcp add --transport http yaf https://你的域名/mcp \
  --header "Authorization: Bearer yaf_pat_xxxx"

server.registerTool(
  "search_memos",
  {
    description: "在用户的 yaf 笔记里搜索。传 query 时默认混合检索（关键词 + 语义，" +
      "按相关度排序），能找到意思相近但用词不同的 memo；tag 不带 #……都不传时按时间倒序。",
    inputSchema: z.object({
      query: z.string().optional().describe("搜索内容，可以是关键词，也可以是一句话"),
      mode: z.enum(["hybrid", "keyword", "semantic"]).optional(),
      limit: z.number().int().min(1).max(50).optional().describe("返回条数，默认 20"),
    }),
  },
  async ({ query, mode, tag, limit }) => {
    if (!can("memos:read")) return denied("memos:read");   // 工具级权限检查
    const r = await search(env, user.id, { q: query, ..., visibility: "token" });
    return text(`找到 ${r.memos.length} 条（关键词 ${r.stats.keyword} · 语义 ${r.stats.semantic}）：\n\n` + ...);
  },
);

yaf login --host https://你的域名     # 走第 7 章图 7-1 的设备码流程
echo "灵感：给导读加一张时序图 #yaf" | yaf add     # 管道当输入，POSIX 风格
yaf search 关键词 --tag inbox
yaf export --format md -o inbox.md

export class WechatBridge extends DurableObject<Env> {
  async start(userId: string) {           // 扫码确认后由路由调用
    await this.ctx.storage.put("userId", userId);
    await this.ctx.storage.delete(["cursor", "lastMemo", "failures"]);
    await this.ctx.storage.setAlarm(Date.now());   // 立刻唤醒自己
  }

  async alarm() {                          // 被叫醒：拉一轮消息
    const binding = await 查 wechat_bindings 表（含加密的 bot_token）;
    const token = await open(this.env.ENCRYPTION_KEY, binding.bot_token_enc);
    const cursor = (await this.ctx.storage.get("cursor")) ?? "";
    const resp = await getUpdates(base_url, token, cursor, POLL_TIMEOUT_MS);
    if (resp.get_updates_buf) await this.ctx.storage.put("cursor", resp.get_updates_buf);
    for (const msg of resp.msgs ?? []) await this.handle(userId, binding, token, rules, msg);
    await this.ctx.storage.setAlarm(Date.now() + 200);   // 200ms 后再来一轮
  }   // 出错时：failures 计数退避，最长 120 秒；连续失败写进 last_error 供设置页显示
}

if (!memo) memo = await createMemo(this.env.DB, userId, appendTags(body, tags), "wechat",
                                   { allowEmpty: hasMedia });   // 纯图片允许空正文
if (hasMedia) {
  this.ctx.waitUntil(saveMedia(this.env, userId, memo.id, items, ...)
    .catch(async (e) => { /* 全失败时补一句说明，避免空白卡片 */ })
    .then(() => scheduleIndex(this.env, this.ctx, userId, memo)));  // 再进第 8 章的索引链
} else scheduleIndex(this.env, this.ctx, userId, memo);
if (rules.replyConfirm) this.ctx.waitUntil(sendText(..., "已记录 · #微信 #家事", ...));

export async function seal(secret: string | undefined, plain: string): Promise<string> {
  const iv = crypto.getRandomValues(new Uint8Array(12));       // 每次加密用新随机数
  const data = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, await key(secret), ...);
  return `v1.${toB64(iv)}.${toB64(data)}`;    // 版本号.iv.密文，将来可换算法
}   // key(secret)：ENCRYPTION_KEY 是部署级 secret（第 3 章），用户 token 是数据

export function renderMarkdown(src: string, terms: string[] = []): string {
  const html = marked.parse(src, { async: false });      // ① MD → HTML
  const clean = DOMPurify.sanitize(html, { RETURN_DOM: true }); // ② 净化，返回 DOM
  linkifyTags(clean);                                     // ③ #tag 变可点击链接
  highlight(clean, terms);                                // ④ 命中词包 <mark>
  clean.querySelectorAll("a[href]:not(.tag)").forEach((a) => {
    a.setAttribute("target", "_blank");                   // ⑤ 外链新窗口
    a.setAttribute("rel", "noopener noreferrer");         //    且切断反向访问
  });
  return clean.innerHTML;
}

"deploy": "node scripts/preflight.mjs && vite build && wrangler deploy"
//         ① 检查：现在部署安全吗？        ② 打包              ③ 上传发布

const dbId = config.match(/^\s*"database_id"\s*:\s*"([0-9a-f-]{36})"/m)?.[1];
if (!dbId) fail("wrangler.jsonc 的 D1 配置缺少 database_id。继续部署会让 wrangler
  新建一个空库，原有数据不会被删除，但站点会读不到。……");

const out = spawnSync("npx", ["wrangler", "d1", "migrations", "list", dbName, "--remote"], ...);
if (!out.includes("No migrations to apply")) fail("线上数据库有未应用的迁移。
  部署前请先记录 Time Travel 书签，再应用迁移：……");