@adep/cli 0.4.4 → 0.4.5

package/dist/vite.js

@@ -742,10 +742,21 @@ function compileSelect(state, dialect) {
   if (state.orderBys.length > 0) {
     sql += ` ORDER BY ${state.orderBys.map((order) => `${dialect.quote(order.column)} ${order.direction.toUpperCase()}`).join(", ")}`;
   }
-  if (state.limit !== void 0) sql += ` LIMIT ${pushParam(params, dialect, state.limit)}`;
-  if (state.offset !== void 0) sql += ` OFFSET ${pushParam(params, dialect, state.offset)}`;
+  if (state.limit !== void 0) {
+    assertInlineableInt(state.limit, "limit");
+    sql += ` LIMIT ${state.limit}`;
+  }
+  if (state.offset !== void 0) {
+    assertInlineableInt(state.offset, "offset");
+    sql += ` OFFSET ${state.offset}`;
+  }
   return { sql, params };
 }
+function assertInlineableInt(value, name) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw unsafeOperation(`${name} \u5FC5\u987B\u662F\u975E\u8D1F\u6574\u6570`);
+  }
+}
 function compileCount(state, dialect) {
   const params = [];
   let sql = `SELECT count(*) AS n FROM ${dialect.quote(state.table)}`;
@@ -1299,11 +1310,21 @@ function parseWhereClauses(whereRaw, cursor) {
       const t = part.trim();
       if (t.length === 0) continue;
       if (/\bIS\s+NULL\b/i.test(t)) {
-        clauses.push({ column: unqualifyColumn(ident(t.split(/\s+IS\s+NULL\b/i)[0] ?? "")), operator: "IS NULL", value: null, list: false });
+        clauses.push({
+          column: unqualifyColumn(ident(t.split(/\s+IS\s+NULL\b/i)[0] ?? "")),
+          operator: "IS NULL",
+          value: null,
+          list: false
+        });
         continue;
       }
       if (/\bIS\s+NOT\s+NULL\b/i.test(t)) {
-        clauses.push({ column: unqualifyColumn(ident(t.split(/\s+IS\s+NOT\s+NULL\b/i)[0] ?? "")), operator: "IS NOT NULL", value: null, list: false });
+        clauses.push({
+          column: unqualifyColumn(ident(t.split(/\s+IS\s+NOT\s+NULL\b/i)[0] ?? "")),
+          operator: "IS NOT NULL",
+          value: null,
+          list: false
+        });
         continue;
       }
       const opMatch = /^\s*((?:"[^"]+")|([A-Za-z_][A-Za-z0-9_.]*))\s*(=|!=|>=|<=|>|<|like|in|not\s+in)\s*(.+)$/i.exec(
@@ -1480,7 +1501,10 @@ function parseConflictClause(clause, cursor, fallbackCols) {
     clause.trim()
   );
   if (m === null) {
-    throw new SimDbError("DB_UNSAFE_OP", `\u65E0\u6CD5\u89E3\u6790 ON CONFLICT \u5B50\u53E5\uFF1A${clause.trim().slice(0, 60)}\u2026`);
+    throw new SimDbError(
+      "DB_UNSAFE_OP",
+      `\u65E0\u6CD5\u89E3\u6790 ON CONFLICT \u5B50\u53E5\uFF1A${clause.trim().slice(0, 60)}\u2026`
+    );
   }
   const colsRaw = m[1];
   const cols = colsRaw === void 0 ? fallbackCols : colsRaw.split(",").map(ident);
@@ -1684,16 +1708,16 @@ var SimSqlEngine = class {
         row[col] = values[i] ?? null;
       });
       if (conflictSpec !== null) {
-        const existing = table.rows.find(
-          (r) => conflictSpec.cols.every((c) => r[c] === row[c])
-        );
+        const existing = table.rows.find((r) => conflictSpec.cols.every((c) => r[c] === row[c]));
         if (existing !== void 0) {
           const oldRow = { ...existing };
           for (const set of conflictSpec.sets) {
             existing[set.col] = resolveSetValue(set.value, oldRow, row);
           }
           inserted += 1;
-          void this.persist();
+          this.persist().catch((error) => {
+            console.warn("[sim] \u6301\u4E45\u5316\u5931\u8D25\uFF1A", error);
+          });
           continue;
         }
       }
@@ -1701,7 +1725,9 @@ var SimSqlEngine = class {
       table.rows.push(row);
       inserted += 1;
     }
-    void this.persist();
+    this.persist().catch((error) => {
+      console.warn("[sim] \u6301\u4E45\u5316\u5931\u8D25\uFF1A", error);
+    });
     return { changes: inserted };
   }
   execUpdate(sql, params) {
@@ -1731,7 +1757,9 @@ var SimSqlEngine = class {
       }
       changes += 1;
     }
-    void this.persist();
+    this.persist().catch((error) => {
+      console.warn("[sim] \u6301\u4E45\u5316\u5931\u8D25\uFF1A", error);
+    });
     return { changes };
   }
   execDelete(sql, params) {
@@ -1749,7 +1777,9 @@ var SimSqlEngine = class {
       else changes += 1;
     }
     table.rows = keep;
-    void this.persist();
+    this.persist().catch((error) => {
+      console.warn("[sim] \u6301\u4E45\u5316\u5931\u8D25\uFF1A", error);
+    });
     return { changes };
   }
   select(sql, params) {
@@ -1771,7 +1801,9 @@ var SimSqlEngine = class {
       rows = table.rows.map((row) => {
         const merged = { ...row };
         for (const j of joins) {
-          const joined = this.tables[j.table]?.rows.find((jr) => jr[j.leftCol] === merged[j.rightCol]);
+          const joined = this.tables[j.table]?.rows.find(
+            (jr) => jr[j.leftCol] === merged[j.rightCol]
+          );
           if (joined !== void 0) {
             for (const [k, v] of Object.entries(joined)) merged[`${j.alias}.${k}`] = v;
           }
@@ -2872,7 +2904,7 @@ function envDbFile() {
 function displayPath(cwd, target) {
   if (target === ":memory:") return target;
   const rel = relative(cwd, target);
-  return rel.startsWith("..") ? target : rel;
+  return rel.startsWith("..") ? target : rel.split(/[\\/]/u).join("/");
 }
 function simDbTarget(cwd) {
   return displayPath(cwd, join5(simDir(cwd), "db.json"));
@@ -3660,6 +3692,158 @@ function parseExportClause(clause) {
   }
   return entries;
 }
+var CONTINUES_AFTER = "=+-*/%&|^<>?:,.[(";
+var CONTINUES_BEFORE = "`([.?:,+-*/%&|^<>=";
+var REGEX_PRECEDERS = "(,=:[!&|?{};+-*%~^<>";
+var MATCHING_OPEN = { ")": "(", "]": "[", "}": "{" };
+function lineNumberAt(code, index) {
+  let line = 1;
+  for (let i = 0; i < index; i += 1) if (code.charCodeAt(i) === 10) line += 1;
+  return line;
+}
+function skipQuoted(code, start) {
+  const quote = code.charAt(start);
+  let i = start + 1;
+  while (i < code.length) {
+    const ch = code.charAt(i);
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === quote) return i + 1;
+    if (ch === "\n") return i;
+    i += 1;
+  }
+  return code.length;
+}
+function skipRegex(code, start) {
+  let i = start + 1;
+  let inClass = false;
+  while (i < code.length) {
+    const ch = code.charAt(i);
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === "\n") return start + 1;
+    if (ch === "[") inClass = true;
+    else if (ch === "]") inClass = false;
+    else if (ch === "/" && !inClass) return i + 1;
+    i += 1;
+  }
+  return code.length;
+}
+function regexCanStart(prev) {
+  return prev === "" || REGEX_PRECEDERS.includes(prev);
+}
+function continuesOnto(code, newline, prev) {
+  if (prev !== "" && CONTINUES_AFTER.includes(prev)) return true;
+  let i = newline + 1;
+  while (i < code.length && /\s/.test(code.charAt(i))) i += 1;
+  const next = code.charAt(i);
+  return next !== "" && CONTINUES_BEFORE.includes(next);
+}
+function scanDeclaration(code, from) {
+  const commas = [];
+  const stack = [];
+  let prev = "";
+  let i = from;
+  while (i < code.length) {
+    const ch = code.charAt(i);
+    if (stack[stack.length - 1] === "`") {
+      if (ch === "\\") {
+        i += 2;
+        continue;
+      }
+      if (ch === "`") {
+        stack.pop();
+        prev = "`";
+        i += 1;
+        continue;
+      }
+      if (ch === "$" && code.charAt(i + 1) === "{") {
+        stack.push("{");
+        prev = "{";
+        i += 2;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+    if (ch === "/" && code.charAt(i + 1) === "/") {
+      const newline = code.indexOf("\n", i);
+      i = newline === -1 ? code.length : newline;
+      continue;
+    }
+    if (ch === "/" && code.charAt(i + 1) === "*") {
+      const close = code.indexOf("*/", i + 2);
+      i = close === -1 ? code.length : close + 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      i = skipQuoted(code, i);
+      prev = ch;
+      continue;
+    }
+    if (ch === "`") {
+      stack.push("`");
+      i += 1;
+      continue;
+    }
+    if (ch === "/" && regexCanStart(prev)) {
+      i = skipRegex(code, i);
+      prev = "/";
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") {
+      stack.push(ch);
+      prev = ch;
+      i += 1;
+      continue;
+    }
+    if (ch === ")" || ch === "]" || ch === "}") {
+      if (stack[stack.length - 1] !== MATCHING_OPEN[ch]) return { commas, end: i };
+      stack.pop();
+      prev = ch;
+      i += 1;
+      continue;
+    }
+    if (stack.length === 0) {
+      if (ch === ";") return { commas, end: i };
+      if (ch === ",") commas.push(i);
+      if (ch === "\n" && !continuesOnto(code, i, prev)) return { commas, end: i };
+    }
+    if (!/\s/.test(ch)) prev = ch;
+    i += 1;
+  }
+  return { commas, end: code.length };
+}
+function declaratorName(segment) {
+  const match = /^\s*([A-Za-z_$][\w$]*)\s*(?:=(?![=>])|$)/.exec(segment);
+  return match === null ? null : match[1] ?? null;
+}
+function restDeclarators(code, from) {
+  const { commas, end } = scanDeclaration(code, from);
+  if (commas.length === 0) return [];
+  const segments = [];
+  let cursor = from;
+  for (const comma of commas) {
+    segments.push(code.slice(cursor, comma));
+    cursor = comma + 1;
+  }
+  segments.push(code.slice(cursor, end));
+  const names = [];
+  for (const segment of segments.slice(1)) {
+    const name = declaratorName(segment);
+    if (name === null) {
+      throw new Error(
+        `\u4E0D\u652F\u6301\u7684\u5BFC\u51FA\u58F0\u660E\u5F62\u6001\uFF1A"${segment.trim()}"\uFF08\u6C99\u7BB1\u5B50\u96C6\u4EC5\u63A5\u53D7\u9017\u53F7\u5206\u9694\u7684\u7B80\u5355\u6807\u8BC6\u7B26\u58F0\u660E\uFF0C\u5982 \`export const a = 1, b = 2\`\uFF1B\u542B\u89E3\u6784\u6216\u590D\u6742\u521D\u503C\u65F6\u8BF7\u62C6\u6210\u591A\u6761 export\uFF09`
+      );
+    }
+    names.push(name);
+  }
+  return names;
+}
 function transformModule(code) {
   let out = code;
   const named = [];
@@ -3722,10 +3906,20 @@ function transformModule(code) {
       return `${lead}${indent}const ${temp} = require(${source})${pad}`;
     }
   );
+  const destructured = /(^|\n)[ \t]*export\s+(const|let|var)\s*[{[]/.exec(out);
+  if (destructured !== null) {
+    const offset = destructured.index + (destructured[1] === "\n" ? 1 : 0);
+    throw new Error(
+      `\u4E0D\u652F\u6301\u7684\u5BFC\u51FA\u58F0\u660E\u5F62\u6001\uFF08\u7B2C ${lineNumberAt(out, offset)} \u884C\uFF09\uFF1A\u89E3\u6784\u5BFC\u51FA \`export ${destructured[2] ?? ""} { \u2026 } = \u2026\`\u3002\u6C99\u7BB1\u5B50\u96C6\u4EC5\u63A5\u53D7\u7B80\u5355\u6807\u8BC6\u7B26\u58F0\u660E\uFF1A\u8BF7\u5148\u58F0\u660E\u518D \`export { a, b }\`\uFF0C\u6216\u62C6\u6210\u591A\u6761 \`export const\``
+    );
+  }
   out = out.replace(
     /export\s+(const|let|var)\s+([A-Za-z_$][\w$]*)/g,
-    (_match, kw, name) => {
+    (match, kw, name, offset, source) => {
       named.push({ local: name, exported: name });
+      for (const extra of restDeclarators(source, offset + match.length)) {
+        named.push({ local: extra, exported: extra });
+      }
       return `${kw} ${name}`;
     }
   );

package/dist/worker-entry.js

@@ -127,6 +127,158 @@ function parseExportClause(clause) {
   }
   return entries;
 }
+var CONTINUES_AFTER = "=+-*/%&|^<>?:,.[(";
+var CONTINUES_BEFORE = "`([.?:,+-*/%&|^<>=";
+var REGEX_PRECEDERS = "(,=:[!&|?{};+-*%~^<>";
+var MATCHING_OPEN = { ")": "(", "]": "[", "}": "{" };
+function lineNumberAt(code, index) {
+  let line = 1;
+  for (let i = 0; i < index; i += 1) if (code.charCodeAt(i) === 10) line += 1;
+  return line;
+}
+function skipQuoted(code, start) {
+  const quote = code.charAt(start);
+  let i = start + 1;
+  while (i < code.length) {
+    const ch = code.charAt(i);
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === quote) return i + 1;
+    if (ch === "\n") return i;
+    i += 1;
+  }
+  return code.length;
+}
+function skipRegex(code, start) {
+  let i = start + 1;
+  let inClass = false;
+  while (i < code.length) {
+    const ch = code.charAt(i);
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === "\n") return start + 1;
+    if (ch === "[") inClass = true;
+    else if (ch === "]") inClass = false;
+    else if (ch === "/" && !inClass) return i + 1;
+    i += 1;
+  }
+  return code.length;
+}
+function regexCanStart(prev) {
+  return prev === "" || REGEX_PRECEDERS.includes(prev);
+}
+function continuesOnto(code, newline, prev) {
+  if (prev !== "" && CONTINUES_AFTER.includes(prev)) return true;
+  let i = newline + 1;
+  while (i < code.length && /\s/.test(code.charAt(i))) i += 1;
+  const next = code.charAt(i);
+  return next !== "" && CONTINUES_BEFORE.includes(next);
+}
+function scanDeclaration(code, from) {
+  const commas = [];
+  const stack = [];
+  let prev = "";
+  let i = from;
+  while (i < code.length) {
+    const ch = code.charAt(i);
+    if (stack[stack.length - 1] === "`") {
+      if (ch === "\\") {
+        i += 2;
+        continue;
+      }
+      if (ch === "`") {
+        stack.pop();
+        prev = "`";
+        i += 1;
+        continue;
+      }
+      if (ch === "$" && code.charAt(i + 1) === "{") {
+        stack.push("{");
+        prev = "{";
+        i += 2;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+    if (ch === "/" && code.charAt(i + 1) === "/") {
+      const newline = code.indexOf("\n", i);
+      i = newline === -1 ? code.length : newline;
+      continue;
+    }
+    if (ch === "/" && code.charAt(i + 1) === "*") {
+      const close = code.indexOf("*/", i + 2);
+      i = close === -1 ? code.length : close + 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      i = skipQuoted(code, i);
+      prev = ch;
+      continue;
+    }
+    if (ch === "`") {
+      stack.push("`");
+      i += 1;
+      continue;
+    }
+    if (ch === "/" && regexCanStart(prev)) {
+      i = skipRegex(code, i);
+      prev = "/";
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") {
+      stack.push(ch);
+      prev = ch;
+      i += 1;
+      continue;
+    }
+    if (ch === ")" || ch === "]" || ch === "}") {
+      if (stack[stack.length - 1] !== MATCHING_OPEN[ch]) return { commas, end: i };
+      stack.pop();
+      prev = ch;
+      i += 1;
+      continue;
+    }
+    if (stack.length === 0) {
+      if (ch === ";") return { commas, end: i };
+      if (ch === ",") commas.push(i);
+      if (ch === "\n" && !continuesOnto(code, i, prev)) return { commas, end: i };
+    }
+    if (!/\s/.test(ch)) prev = ch;
+    i += 1;
+  }
+  return { commas, end: code.length };
+}
+function declaratorName(segment) {
+  const match = /^\s*([A-Za-z_$][\w$]*)\s*(?:=(?![=>])|$)/.exec(segment);
+  return match === null ? null : match[1] ?? null;
+}
+function restDeclarators(code, from) {
+  const { commas, end } = scanDeclaration(code, from);
+  if (commas.length === 0) return [];
+  const segments = [];
+  let cursor = from;
+  for (const comma of commas) {
+    segments.push(code.slice(cursor, comma));
+    cursor = comma + 1;
+  }
+  segments.push(code.slice(cursor, end));
+  const names = [];
+  for (const segment of segments.slice(1)) {
+    const name = declaratorName(segment);
+    if (name === null) {
+      throw new Error(
+        `\u4E0D\u652F\u6301\u7684\u5BFC\u51FA\u58F0\u660E\u5F62\u6001\uFF1A"${segment.trim()}"\uFF08\u6C99\u7BB1\u5B50\u96C6\u4EC5\u63A5\u53D7\u9017\u53F7\u5206\u9694\u7684\u7B80\u5355\u6807\u8BC6\u7B26\u58F0\u660E\uFF0C\u5982 \`export const a = 1, b = 2\`\uFF1B\u542B\u89E3\u6784\u6216\u590D\u6742\u521D\u503C\u65F6\u8BF7\u62C6\u6210\u591A\u6761 export\uFF09`
+      );
+    }
+    names.push(name);
+  }
+  return names;
+}
 function transformModule(code) {
   let out = code;
   const named = [];
@@ -189,10 +341,20 @@ function transformModule(code) {
       return `${lead}${indent}const ${temp} = require(${source})${pad}`;
     }
   );
+  const destructured = /(^|\n)[ \t]*export\s+(const|let|var)\s*[{[]/.exec(out);
+  if (destructured !== null) {
+    const offset = destructured.index + (destructured[1] === "\n" ? 1 : 0);
+    throw new Error(
+      `\u4E0D\u652F\u6301\u7684\u5BFC\u51FA\u58F0\u660E\u5F62\u6001\uFF08\u7B2C ${lineNumberAt(out, offset)} \u884C\uFF09\uFF1A\u89E3\u6784\u5BFC\u51FA \`export ${destructured[2] ?? ""} { \u2026 } = \u2026\`\u3002\u6C99\u7BB1\u5B50\u96C6\u4EC5\u63A5\u53D7\u7B80\u5355\u6807\u8BC6\u7B26\u58F0\u660E\uFF1A\u8BF7\u5148\u58F0\u660E\u518D \`export { a, b }\`\uFF0C\u6216\u62C6\u6210\u591A\u6761 \`export const\``
+    );
+  }
   out = out.replace(
     /export\s+(const|let|var)\s+([A-Za-z_$][\w$]*)/g,
-    (_match, kw, name) => {
+    (match, kw, name, offset, source) => {
       named.push({ local: name, exported: name });
+      for (const extra of restDeclarators(source, offset + match.length)) {
+        named.push({ local: extra, exported: extra });
+      }
       return `${kw} ${name}`;
     }
   );

package/package.json

@@ -7,7 +7,7 @@
   },
   "homepage": "https://adep.top",
   "bugs": "https://gitcode.com/yunqiang_wu/ai-yunke/issues",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "type": "module",
   "description": "`adep` 命令行工具包位：登录 / 初始化 / 本地调试 / 部署 / 数据库维护 / 云存储 / 静态托管 / 微前端组件（widget），实现见任务单 CLI-001 ~ CLI-003 与 FE-002；子路径 `@adep/cli/vite` 提供云函数 vite 插件（CLI-014）",
   "bin": {
@@ -29,9 +29,10 @@
     "commander": "14.0.2",
     "esbuild": "0.25.12",
     "yaml": "2.9.1",
-    "zod": "^4.4.3",
-    "@adep/cf-compat": "0.1.3",
-    "@adep/runtime": "0.3.4",
+    "zod": "^4.6.6",
+    "@adep/cf-compat": "0.1.4",
+    "@adep/app-runtime": "0.1.1",
+    "@adep/runtime": "0.3.5",
     "@adep/crypto": "0.1.1",
     "@adep/vite-plugin": "0.1.9"
   },

package/templates/app-desktop/README.md

@@ -18,7 +18,7 @@ GUI（前端产物）随包本地加载，云函数经 HTTP 在服务端执行
 
 1. 把平台项目的前端构建产物放进 `app/site/`（`adep app build` 会自动拉取已发布产物）；
 2. `npm install`；
-3. `npm start`（配置从 `adep.app.json` 读取，无需环境变量）。
+3. `npm start`（或仓库根的 `adep app open`，等价——直接调壳工程内的 electron；配置从 `adep.app.json` 读取，无需环境变量）。
 
 ## 页面侧调用云函数（在线运行时）
 
@@ -31,12 +31,77 @@ const client = createAdepClient({ baseUrl: window.__ADEP_APP__.platformUrl })
 const result = await client.invokeFunction('hello', { name: 'world' })
 ```
 
+## 设备身份与同步（离线构建之后）
+
+离线构建把设备端运行时注入 `app/offline/`，首次启动时在 `data/offline.sqlite` 建本地库：
+白名单函数在本地执行，写 owned 表时同时追加变更流。
+
+**设备身份是首启自动签发的**（APP-033 / PRD §2.11.5）：主进程启动后在后台调一次
+`POST /api/v1/projects/<slug>/app-installations`（`platform` 按**宿主 OS** 映射为
+`macos` / `windows` / `linux`——服务端没有 `desktop` 这个取值），拿到 `ownerKey` +
+一次性恢复码后写进受保护存储；此后每次启动只读不发请求。
+
+```text
+identity.mjs        判定层（配置 / 端点 / 形态 / 响应解析 / 平台映射）+ 自举流程
+identity-store.mjs  受保护存储：macOS 钥匙串 → Linux Secret Service → 0600 文件（明说降级）
+recovery-ui.mjs     恢复码呈现与导出（APP-034；全在主进程，页面侧拿不到）
+sync-loop.mjs       后台同步驱动（首轮延迟 → 每 5 分钟一轮；不重叠、失败不致命）
+```
+
+存储后端：
+
+- macOS：`security add-generic-password`（登录钥匙串）；
+- Linux：`secret-tool`（Secret Service）；
+- **Windows 与「系统库不可用」**：退化到 `data/identity/` 下的 0600 文件，并在日志与
+  `adep app doctor` 里**明说「非系统凭据」**——不会静默假装是钥匙串。
+
+身份状态（**非机密**：只有存储类型 / 原因码 / 安装 id / 时间）写在
+`data/identity/status.json`，`adep app doctor` 的 `identity` 项读它：
+
+```bash
+adep app doctor        # 已签发（系统凭据库 keychain） / 非系统凭据（file） / 首启签发失败（原因码）
+```
+
+⚠️ **页面侧拿不到 `ownerKey`**（与移动壳同一条边界）：同步跑在主进程，渲染进程不需要这枚
+bearer 凭据，给它等于「任意 XSS 都能劫持该设备的数据分区」。
+
+## 恢复码（APP-034：呈现 / 再次查看 / 导出）
+
+签发响应里的恢复码**只出现一次**（服务端只存摘要、任何端点不重发），壳负责把它递到用户手里：
+
+- **首次呈现**：自举成功后自动弹一次原生对话框（码可读且没呈现过才弹——老安装升级上来
+  同样有机会看到）。此后不再主动弹，标记写在 `data/identity/recovery-code-shown`；
+- **再次查看 / 导出**：应用菜单 **「凭据」→「查看恢复码…」/「导出恢复码…」**（导出文件
+  头部写明「服务端无法重发，丢了码等于放弃认领」）；
+- **复制到剪贴板**：两个对话框里都有一键复制。
+
+呈现与导出**全在主进程**（应用菜单 + 原生对话框）：不开 IPC、不改 preload，恢复码与
+`ownerKey` 一样不进渲染进程。码不可读时（未签发 / 存储失败）对话框会说明原因并指向
+`adep app doctor`，不是静默空窗。
+
+身份就绪后主进程自动把同步挂到运行时上：
+
+```js
+const runtime = await createOfflineRuntime() // 页面先可用
+const sync = runtime.attachSync({ ownerKey }) // 身份到位后再挂（不重开库）
+await sync.push() // 本地变更流 → outbox → 云端
+await sync.pull() // 云端增量 → 本地库（直写驱动，不回灌 outbox）
+```
+
+手动同步（开发期 / 排障）仍用 CLI：`adep app sync --push`（身份取 `--owner-key` 或
+`ADEP_OWNER_KEY`）。**不要**在 `adep.app.json` 或环境变量里编一个 key：本地自造会写出一个
+「看起来成功」的空分区（PRD §2.11.5 明确「本地自造判违规」）。
+
+⚠️ 已知限制（已登记）：打包形态下 `data/` 仍在应用目录内（`.app` / Program Files），
+写入可能被系统拒绝——此时 `identity` 项会显示 `IDENTITY_STORE_FAILED`，属于**响亮失败**。
+把本地数据目录迁到 `app.getPath('userData')` 是独立的一批（含 `data/offline.sqlite`）。
+
 ## 打安装包
 
 推荐用 CLI（会自动拉取**已发布**的前端产物、回写产物版本、产出构建报告）：
 
 ```bash
-adep app build            # 当前平台、走 package.json build 段的 target（mac dmg / win nsis / linux AppImage）
+adep app build            # 当前平台、走 package.json build 段的 target（mac dmg / win nsis+zip / linux AppImage+deb）
 adep app build --target dir        # 只出未压缩目录（macOS 即 .app），本地快速验证
 adep app build --prepare-only      # 只拉产物 + 注入 + 出构建报告，不调 electron-builder
 ```