@adep/cli 0.1.17 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adep/cli",
-  "version": "0.1.17",
+  "version": "0.2.0",
   "type": "module",
   "description": "`adep` 命令行工具包位：登录 / 初始化 / 本地调试 / 部署 / 数据库维护 / 云存储 / 静态托管 / 微前端组件（widget），实现见任务单 CLI-001 ~ CLI-003 与 FE-002；子路径 `@adep/cli/vite` 提供云函数 vite 插件（CLI-014）",
   "bin": {
@@ -15,18 +15,20 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "templates"
   ],
   "dependencies": {
     "commander": "14.0.2",
     "esbuild": "0.25.12",
-    "@adep/cf-compat": "0.1.1",
+    "zod": "^4.4.3",
+    "@adep/runtime": "0.3.0",
+    "@adep/vite-plugin": "0.1.8",
     "@adep/crypto": "0.1.0",
-    "@adep/vite-plugin": "0.1.7",
-    "@adep/runtime": "0.2.7"
+    "@adep/cf-compat": "0.1.1"
   },
   "devDependencies": {
-    "@adep/types": "0.2.3"
+    "@adep/types": "0.3.0"
   },
   "scripts": {
     "test": "vitest run",

package/templates/app-desktop/README.md

@@ -0,0 +1,51 @@
+# {{appName}}（AgentDeploy 桌面应用壳）
+
+`adep app init` 生成的 **Electron 桌面壳工程**（PRD §2.11 路径 A：在线运行时 + 桌面壳）：
+GUI（前端产物）随包本地加载，云函数经 HTTP 在服务端执行——**改函数逻辑不需要重新发版**。
+
+## 目录结构
+
+- `main.mjs`：Electron 主进程——注册自定义 scheme `adep-app://` 并从 `app/site/` 提供
+  静态产物（`file://` 直接加载 ESM bundle 有 CORS 限制，必须走自定义协议）；
+- `window.mjs`：BrowserWindow 装配（沙箱 + contextIsolation 安全基线、外链交系统浏览器）；
+- `preload.cjs`：contextBridge 注入只读配置 `window.__ADEP_APP__`
+  （`platformUrl` / `projectSlug` / `appName`；⚠️ 沙箱 preload 不支持 ESM，故为 `.cjs`）；
+- `adep.app.json`：壳配置（schema 校验见 `@adep/cli`），init 时由 `--server` 等参数生成，
+  主进程启动时读取并经 `additionalArguments` 传给 preload；
+- `package.json`：`electron` + `electron-builder` devDependencies 与三平台构建 target 占位。
+
+## 开发
+
+1. 把平台项目的前端构建产物放进 `app/site/`（`adep app build` 会自动拉取已发布产物）；
+2. `npm install`；
+3. `npm start`（配置从 `adep.app.json` 读取，无需环境变量）。
+
+## 页面侧调用云函数（在线运行时）
+
+页面代码用 `@adep/client` 以 `platformUrl` 绝对地址 invoke：
+
+```ts
+import { createAdepClient } from '@adep/client/functions'
+
+const client = createAdepClient({ baseUrl: window.__ADEP_APP__.platformUrl })
+const result = await client.invokeFunction('hello', { name: 'world' })
+```
+
+## 打安装包
+
+推荐用 CLI（会自动拉取**已发布**的前端产物、回写产物版本、产出构建报告）：
+
+```bash
+adep app build            # 当前平台、走 package.json build 段的 target（mac dmg / win nsis / linux AppImage）
+adep app build --target dir        # 只出未压缩目录（macOS 即 .app），本地快速验证
+adep app build --prepare-only      # 只拉产物 + 注入 + 出构建报告，不调 electron-builder
+```
+
+也可以只在这个目录里手动跑（`app/site/` 里已经是你自己放进来的产物时）：
+
+```bash
+npm run dist   # = electron-builder，target 见 package.json build 段
+```
+
+产物与构建报告都输出到 `dist/`（`dist/build-report.json` 记录本次打进包的产物版本、
+云函数清单 `runtime: online` 与体积 Top 10）。平台不出具任何签名：签名与公证由开发者本地完成（PRD §2.11.5）。

package/templates/app-desktop/main.mjs

@@ -0,0 +1,108 @@
+/**
+ * Electron 主进程（app-desktop 模板，APP-001）。
+ *
+ * 职责（PRD §2.11 路径 A：在线运行时 + 桌面壳）：
+ * 1. 注册自定义 scheme `adep-app://`——`file://` 直接加载 ESM bundle 会被 CORS 拦
+ *    （`file://` origin 为 null，ES module 跨源请求一律被拒），必须走自定义协议；
+ * 2. `adep-app://bundle/<path>` 从工程内 `app/site/` 提供静态产物（带 MIME 与 SPA 回退）；
+ * 3. 创建 BrowserWindow，经 additionalArguments 把 adep.app.json 配置传给沙箱 preload。
+ *
+ * 页面侧经 preload 注入的 `__ADEP_APP__` 拿到 platformUrl 后，用 `@adep/client`
+ * 绝对地址 invoke 云函数（在线运行时，函数逻辑迭代不需要重新发版）。
+ *
+ * 主进程是 .mjs（Electron 28+ 支持 ESM 主进程）：启动流程用 top-level await
+ * 直写，比 .then() 链少一层回调；启动失败即响亮崩溃（unhandled rejection）。
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { app, ipcMain, net, protocol } from 'electron'
+import { createWindow } from './window.mjs'
+import { createOfflineRuntime, hasOfflineBundle } from './offline-runtime.mjs'
+
+const APP_SCHEME = 'adep-app'
+const SITE_DIR = 'app/site'
+/**
+ * 壳工程根目录（= 本文件所在目录）。
+ *
+ * ⚠️ ESM 里**没有** `__dirname`（那是 CJS 的全局量）：主进程走 Node 的 ESM 加载器时它是
+ * `undefined`，拿去 join 会抛 TypeError（应用启动即崩）。必须自己从 `import.meta.url` 取。
+ */
+const APP_ROOT = dirname(fileURLToPath(import.meta.url))
+
+/** 从壳工程根读 adep.app.json（init 时生成；字段校验归 @adep/cli 的 schema）。 */
+function loadAppConfig() {
+  const raw = JSON.parse(readFileSync(join(APP_ROOT, 'adep.app.json'), 'utf8'))
+  if (typeof raw.platformUrl !== 'string' || raw.platformUrl === '') {
+    throw new Error('[adep-app] adep.app.json 缺少 platformUrl（请重新执行 adep app init）')
+  }
+  if (typeof raw.projectSlug !== 'string' || raw.projectSlug === '') {
+    throw new Error('[adep-app] adep.app.json 缺少 projectSlug（请重新执行 adep app init）')
+  }
+  return {
+    platformUrl: raw.platformUrl,
+    projectSlug: raw.projectSlug,
+    appName: typeof raw.appName === 'string' && raw.appName !== '' ? raw.appName : raw.projectSlug,
+  }
+}
+
+// registerSchemesAsPrivileged 必须在 app ready **之前**调用（ready 后注册会抛错）：
+// standard + secure 让 `adep-app://` 拥有标准 origin 语义（fetch / ESM 可用），
+// supportFetchAPI + corsEnabled 让页面内 fetch 与 ES module 请求按标准 CORS 工作。
+protocol.registerSchemesAsPrivileged([
+  {
+    scheme: APP_SCHEME,
+    privileges: { standard: true, secure: true, supportFetchAPI: true, corsEnabled: true },
+  },
+])
+
+await app.whenReady()
+const config = loadAppConfig()
+
+// 流式协议处理器：adep-app://bundle/<path> → app/site/<path>。
+// 用 net.fetch(pathToFileURL(...)) 而非手拼 Response：前者自动带 Content-Type
+//（ESM 对 MIME 严格校验，手写 Response 不给 MIME 会被静默拒载）。
+protocol.handle(APP_SCHEME, async (request) => {
+  const { host, pathname } = new URL(request.url)
+  if (host !== 'bundle') {
+    return new Response(`未知 host "${host}"`, { status: 404 })
+  }
+  const siteRoot = join(APP_ROOT, SITE_DIR)
+  const relative = decodeURIComponent(pathname).replace(/^\/+/, '')
+  const rootUrl = pathToFileURL(siteRoot).href
+  const targetUrl = pathToFileURL(join(siteRoot, relative)).href
+  // 目录穿越防线：归一化后的目标必须仍在 app/site/ 内。
+  if (!targetUrl.startsWith(`${rootUrl}/`)) {
+    return new Response('路径越界', { status: 403 })
+  }
+  try {
+    return await net.fetch(targetUrl)
+  } catch {
+    // SPA 回退：产物内路由未命中时回落 index.html（前端发布形态统一 SPA）。
+    if (relative !== 'index.html') {
+      return net.fetch(pathToFileURL(join(siteRoot, 'index.html')).href)
+    }
+    return new Response('未找到入口产物 app/site/index.html', { status: 404 })
+  }
+})
+
+// 离线运行时（PRD §2.11.4）：app/offline/ 存在即装配设备端执行器，页面函数调用走 ipc。
+// 在线形态零开销（hasOfflineBundle 只做一次 existsSync）；装配失败 = 启动即崩（fail loud）。
+let offline = null
+if (hasOfflineBundle()) {
+  offline = await createOfflineRuntime()
+  ipcMain.handle('adep-offline:invoke', (_event, name, args) => offline.executor.invoke(name, args))
+}
+
+const win = await createWindow(config, { offline: offline !== null })
+await win.loadURL(`${APP_SCHEME}://bundle/index.html`)
+
+app.on('activate', () => {
+  // macOS：点 Dock 图标且无窗口时重建（Electron 官方生命周期约定）。
+  if (app.getAllWindows().length === 0) void createWindow(config)
+})
+
+app.on('window-all-closed', () => {
+  // Windows / Linux：关窗即退出；macOS 保持常驻（Dock 惯例）。
+  if (process.platform !== 'darwin') app.quit()
+})

package/templates/app-desktop/offline-runtime.mjs

@@ -0,0 +1,129 @@
+/**
+ * 桌面壳离线运行时装配（APP-008 范围 4 / PRD §2.11.4 运行时随包分发）。
+ *
+ * 消费 `.adepack` 内的 `runtime/executor.mjs`（@adep/app-runtime 的编译产物，服务端
+ * Bun.build 在构建期打进包）：
+ *
+ *   读包（manifest / functions/index.json / functions/*.mjs / db/*.sql / storage/**）
+ *   → 造 DeviceBridge（node:sqlite + 只读文件桥 + 空 env——离线包永不下发 secret）
+ *   → executor.createLocalExecutor（白名单路由：offline:true 本地执行，false 返回
+ *     FN_OFFLINE_ONLY 且提示在线调用方式）
+ *   → 返回 { executor, manifest, sqlite, version } 供主进程 ipc 面使用。
+ *
+ * 壳工程是**独立 npm 工程**（装不了私有 workspace 包），运行时随包分发是本模板对
+ * 「接 @adep/app-runtime」的唯一可行落地；e2e 黄金测试（e2e/cli/app-offline.spec.ts）
+ * 用仓库内 @adep/app-runtime 真实现做 host-side harness，对本装配跑同一判定面，
+ * 把随包分发的语义分叉风险钉在 CI 里（AGENTS §9：拷贝必须点名分叉并双向对账）。
+ */
+import { mkdirSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { DatabaseSync } from 'node:sqlite'
+
+/** 壳工程根目录（= 本文件所在目录）。⚠️ ESM 没有 `__dirname`，须从 import.meta.url 取。 */
+const APP_ROOT = dirname(fileURLToPath(import.meta.url))
+
+/** 离线产物目录（CLI `adep app build --offline` 注入的位置，与在线 `app/site/` 并列）。 */
+const OFFLINE_DIR = join(APP_ROOT, 'app', 'offline')
+
+/** 本地 SQLite 库文件（设备本地数据；首次装配时由 schema.sql + baseline.db.sql 幂等初始化）。 */
+const LOCAL_DB_PATH = join(APP_ROOT, 'data', 'offline.sqlite')
+
+/** 壳是否处于离线运行时形态（包内存在 manifest 即视为已注入离线产物）。 */
+export function hasOfflineBundle() {
+  return existsSync(join(OFFLINE_DIR, 'manifest.json'))
+}
+
+/** 离线函数名 → 源码的懒读取（避免启动即读全部大函数；executor 需要时按名取）。 */
+function readFunctionSource(name) {
+  const file = join(OFFLINE_DIR, 'functions', `${name}.mjs`)
+  if (!existsSync(file)) {
+    throw new Error(`[adep-app] 离线包缺少函数源码 functions/${name}.mjs（包损坏或注入不完整）`)
+  }
+  return readFileSync(file, 'utf8')
+}
+
+/**
+ * 装配离线运行时：装载 executor（data URL 动态 import，引擎无关标准 ESM 语义）、
+ * 初始化本地库、造桥。任何一步失败即 throw（壳启动即响亮崩溃，不留半离线坏状态）。
+ */
+export async function createOfflineRuntime() {
+  if (!hasOfflineBundle()) {
+    throw new Error('[adep-app] 未检测到离线产物 app/offline/manifest.json：请先执行 adep app build --offline')
+  }
+  const executorSource = readFileSync(join(OFFLINE_DIR, 'runtime', 'executor.mjs'), 'utf8')
+  // data URL import：包内字节不进磁盘副本，进程内直接装载（bundle 是纯 ESM，无 node: 运行时依赖）。
+  const executorModule = await import(
+    `data:text/javascript;base64,${Buffer.from(executorSource).toString('base64')}`
+  )
+
+  const manifest = JSON.parse(readFileSync(join(OFFLINE_DIR, 'manifest.json'), 'utf8'))
+  const index = JSON.parse(
+    readFileSync(join(OFFLINE_DIR, 'functions', 'index.json'), 'utf8')
+  )
+  const functions =
+    index.functions === undefined
+      ? []
+      : index.functions.map((fn) => ({ name: fn.name, source: readFunctionSource(fn.name), offline: fn.offline === true }))
+
+  // 本地库：schema.sql（owned + baseline 结构）+ baseline.db.sql（只读快照）幂等初始化。
+  mkdirSync(dirname(LOCAL_DB_PATH), { recursive: true })
+  const sqlite = new DatabaseSync(LOCAL_DB_PATH)
+  const schemaSql = readFileSync(join(OFFLINE_DIR, 'db', 'schema.sql'), 'utf8')
+  const baselineSql = readFileSync(join(OFFLINE_DIR, 'db', 'baseline.db.sql'), 'utf8')
+  if (schemaSql.trim() !== '') sqlite.exec(schemaSql)
+  if (baselineSql.trim() !== '') sqlite.exec(baselineSql)
+
+  // DeviceBridge：SQLite 桥（node:sqlite）+ 只读预置资源桥（app/offline/storage/**）+ 无原生能力。
+  const sqliteBridge = {
+    run: async (sql, params) => {
+      const stmt = sqlite.prepare(sql)
+      const result = params === undefined ? stmt.run() : stmt.run(...(params))
+      return { changes: Number(result.changes) }
+    },
+    all: async (sql, params) => {
+      const stmt = sqlite.prepare(sql)
+      return (params === undefined ? stmt.all() : stmt.all(...(params)))
+    },
+    get: async (sql, params) => {
+      const stmt = sqlite.prepare(sql)
+      const row = params === undefined ? stmt.get() : stmt.get(...(params))
+      return (row === undefined ? null : (row))
+    },
+  }
+  const storageRoot = join(OFFLINE_DIR, 'storage')
+  const filesBridge = {
+    writeFile: async (path, _data) => {
+      throw new Error(`[adep-app] 离线包预置资源只读：storage/${path}`)
+    },
+    readFile: async (path) => {
+      const file = join(storageRoot, path)
+      if (!existsSync(file)) throw new Error(`[adep-app] 离线包缺少预置资源 storage/${path}`)
+      return new Uint8Array(readFileSync(file))
+    },
+    removeFile: async (path) => {
+      throw new Error(`[adep-app] 离线包预置资源只读：storage/${path}`)
+    },
+    listFiles: async (prefix = '') => {
+      // 预置资源面在离线包里是固定清单（manifest.contents 里 storage/**），不落盘扫描。
+      const contents = manifest['contents']
+      return (contents ?? [])
+        .filter((entry) => entry.path.startsWith('storage/') && entry.path.startsWith(`storage/${prefix}`))
+        .map((entry) => ({ path: entry.path.slice('storage/'.length), size: entry.size ?? 0 }))
+    },
+  }
+  const bridge = {
+    sqlite: sqliteBridge,
+    files: filesBridge,
+    // 原生能力门控在原生侧（ADR-0007 硬约束 3）；本壳未声明任何原生能力 → 调用即拒绝。
+    native: undefined,
+  }
+
+  // env：离线包永不下发 secret 值（§4.2）；public 环境变量同样不进包（manifest app 段无 env 面）。
+  const env = { publicVars: {}, secretKeys: [] }
+  const local = executorModule.createLocalExecutor({ functions, bridge, env })
+  const version = readFileSync(join(OFFLINE_DIR, 'runtime', 'version.txt'), 'utf8').trim()
+
+  return { executor: local, manifest, sqlite, version }
+}

package/templates/app-desktop/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "{{projectSlug}}-app",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{appName}} —— AgentDeploy 桌面应用（Electron 壳，在线 + 离线运行时）",
+  "main": "main.mjs",
+  "scripts": {
+    "start": "electron .",
+    "dist": "electron-builder"
+  },
+  "devDependencies": {
+    "electron": "^44.0.0",
+    "electron-builder": "^26.0.0"
+  },
+  "build": {
+    "appId": "{{appId}}",
+    "productName": "{{appName}}",
+    "asar": false,
+    "directories": {
+      "output": "dist"
+    },
+    "files": [
+      "main.mjs",
+      "window.mjs",
+      "preload.cjs",
+      "adep.app.json",
+      "app/site/**/*",
+      "app/offline/**/*",
+      "data/**/*"
+    ],
+    "mac": {
+      "target": [
+        "dmg"
+      ],
+      "category": "public.app-category.productivity"
+    },
+    "win": {
+      "target": [
+        "nsis"
+      ]
+    },
+    "linux": {
+      "target": [
+        "AppImage"
+      ],
+      "category": "Utility"
+    }
+  }
+}

package/templates/app-desktop/preload.cjs

@@ -0,0 +1,45 @@
+/**
+ * Preload（app-desktop 模板，APP-001）：contextBridge 注入只读配置 `__ADEP_APP__`。
+ *
+ * ⚠️ 文件必须是 `.cjs`：Electron 沙箱 preload **不支持 ESM**（官方约束，sandbox
+ * 预加载脚本在隔离的 CJS 环境里执行），`.mjs` 会被静默跳过。
+ *
+ * 沙箱 preload 读不到文件、也读不到普通环境变量，配置由主进程经
+ * `webPreferences.additionalArguments` 以 `--adep-xxx=value` 形式传入（main.mjs 从
+ * adep.app.json 读取后注入）。页面侧 `@adep/client` 以 platformUrl 绝对地址 invoke
+ * 云函数（在线运行时）：
+ *
+ *   const client = createAdepClient({ baseUrl: window.__ADEP_APP__.platformUrl })
+ */
+const { contextBridge, ipcRenderer } = require('electron')
+
+function argvValue(name) {
+  const prefix = `--${name}=`
+  const arg = process.argv.find((entry) => entry.startsWith(prefix))
+  return arg === undefined ? '' : arg.slice(prefix.length)
+}
+
+const PLATFORM_URL = argvValue('adep-platform-url')
+const PROJECT_SLUG = argvValue('adep-project-slug')
+const APP_NAME = argvValue('adep-app-name')
+const OFFLINE = argvValue('adep-offline') === '1'
+
+if (PLATFORM_URL === '' || PROJECT_SLUG === '') {
+  // fail loud：缺配置的壳等于「页面能开、数据全挂」的静默坏状态。
+  throw new Error(
+    '[adep-app] 缺少运行配置 --adep-platform-url / --adep-project-slug（由主进程从 adep.app.json 注入）'
+  )
+}
+
+contextBridge.exposeInMainWorld('__ADEP_APP__', {
+  platformUrl: PLATFORM_URL,
+  projectSlug: PROJECT_SLUG,
+  appName: APP_NAME,
+  // 离线形态（app/offline/ 已注入）：函数调用经主进程 LocalFunctionExecutor 本地执行。
+  ...(OFFLINE
+    ? {
+        mode: 'offline',
+        invoke: (name, args) => ipcRenderer.invoke('adep-offline:invoke', name, args),
+      }
+    : { mode: 'online' }),
+})

package/templates/app-desktop/template.json

@@ -0,0 +1,14 @@
+{
+  "code": "app-desktop",
+  "name": "桌面应用壳（Electron）",
+  "description": "Electron 桌面壳工程：BrowserWindow + adep-app:// 自定义协议加载 app/site/ 产物，在线运行时（云函数经 platformUrl 服务端执行）",
+  "version": "1.0.0",
+  "variables": [
+    {
+      "name": "projectSlug",
+      "description": "平台项目 slug（写入包名 / adep.app.json / appId 推导）"
+    },
+    { "name": "appName", "description": "应用显示名（窗口标题 / electron-builder productName）" },
+    { "name": "appId", "description": "electron-builder appId（top.adep.<slug>）" }
+  ]
+}

package/templates/app-desktop/window.mjs

@@ -0,0 +1,53 @@
+/**
+ * BrowserWindow 装配（从 main.mjs 拆出，保持主流程可读）。
+ *
+ * 配置传递：沙箱 preload 读不到文件与环境变量，经 `additionalArguments` 以
+ * `--adep-xxx=value` 形式把 adep.app.json 的只读配置带进 preload（见 preload.cjs）。
+ *
+ * @typedef {Object} AppConfig
+ * @property {string} platformUrl 平台地址（页面侧 @adep/client 的 baseUrl）
+ * @property {string} projectSlug 平台项目 slug
+ * @property {string} appName 应用显示名
+ */
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { BrowserWindow, shell } from 'electron'
+
+/** 壳工程根目录（= 本文件所在目录）。⚠️ ESM 没有 `__dirname`，须从 import.meta.url 取。 */
+const APP_ROOT = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * 创建主窗口并注入壳配置。
+ *
+ * @param {AppConfig} config adep.app.json 解析出的只读配置
+ * @returns {Promise<BrowserWindow>}
+ */
+export async function createWindow(config, options = {}) {
+  const win = new BrowserWindow({
+    width: 1280,
+    height: 800,
+    autoHideMenuBar: true,
+    webPreferences: {
+      preload: join(APP_ROOT, 'preload.cjs'),
+      // 沙箱 + contextIsolation 是 Electron 安全基线：preload 只经 contextBridge
+      // 暴露只读配置，页面拿不到 Node 能力（PRD §2.11 安全边界）。
+      sandbox: true,
+      contextIsolation: true,
+      nodeIntegration: false,
+      additionalArguments: [
+        `--adep-platform-url=${config.platformUrl}`,
+        `--adep-project-slug=${config.projectSlug}`,
+        `--adep-app-name=${config.appName}`,
+        `--adep-offline=${options.offline === true ? '1' : '0'}`,
+      ],
+    },
+  })
+
+  // 外链交给系统浏览器，不让 app 壳变成浏览器（Electron 官方 setWindowOpenHandler 约定）。
+  win.webContents.setWindowOpenHandler(({ url }) => {
+    void shell.openExternal(url)
+    return { action: 'deny' }
+  })
+
+  return win
+}

package/templates/app-mobile/README.md

@@ -0,0 +1,89 @@
+# {{appName}}（AgentDeploy 移动应用壳）
+
+`adep app init --platform mobile` 生成的 **Capacitor 移动壳工程**（PRD §2.11 路径 A：在线
+运行时 + 移动壳）：GUI（前端产物）随包本地加载，云函数经 HTTP 在服务端执行——**改函数
+逻辑不需要重新发版**（§2.11.4 在线运行时）。
+
+移动端与桌面端能力对齐（§2.11.1），差异只在打包壳与分发口径：iOS / Android 有应用商店
+审核约束，签名与上架由开发者自行完成（见下方「签名与上架」，完整指引
+[`docs/mobile-shell-signing.md`](../../docs/mobile-shell-signing.md)）。
+
+## 目录结构
+
+- `capacitor.config.ts`：Capacitor 配置（`appId` = iOS bundle id，`webDir` = `app/site`）；
+- `package.json`：`@capacitor/*` 依赖 + 脚本（`cap:add:ios` / `cap:add:android` /
+  `build:ios` / `build:android` 等）；
+- `web/adep-bridge.js`：页面侧桥（与桌面 `preload.cjs` 同形，§3.2.8 硬约束④）——CLI
+  `adep app build` 时复制进 `app/site/adep-bridge.js` 并注入 `index.html`，暴露
+  `window.__ADEP_APP__`（`platformUrl` / `projectSlug` / `appName` / `invokeNative`）；
+- `bridge/gate.mjs`：权限门控核心的 **host-side harness 镜像**（CI 判定面；原生侧同规则）；
+- `plugins/adep-bridge/`：**本地 Capacitor 插件**——原生桥（iOS Swift / Android Kotlin）：
+  原生侧权限门控 + ownerKey 存储（Keychain / Keystore）+ 原生能力 invoke 路由；
+- `adep.permissions.json`：权限清单占位（CLI build 时按服务端打包配置重写进 `app/site/`）；
+- `adep.app.json`：壳配置（CLI init 生成，build 时复制进 `app/site/` 供页面桥读取）。
+
+## 首次构建（一次性）
+
+原生工程由 Capacitor 生成，平台不维护原生工程（§3.2.8）：
+
+```bash
+npm install
+npx cap add ios        # 生成 ios/ Xcode 工程
+npx cap add android    # 生成 android/ Gradle 工程
+```
+
+> Android：`cap add` 生成的 `android/app/build.gradle` 里 `applicationId` 默认取
+> `capacitor.config.ts` 的 `appId`；按 `{{androidPackageId}}` 修改（applicationId 不允许
+> 连字符，iOS bundle id 不允许下划线——两端无法共用一个 id）。
+
+## 打 unsigned 安装包
+
+推荐用 CLI（自动拉取**已发布**前端产物、按服务端打包配置写入权限清单、回写版本、出报告）：
+
+```bash
+adep app build --platform ios --dir .      # xcodebuild archive → .xcarchive（unsigned）
+adep app build --platform android --dir .  # gradlew assembleRelease → unsigned APK
+adep app build --platform ios --prepare-only   # 只注入产物 + 报告，不调工具链
+```
+
+产物与构建报告输出到 `dist/`。**平台不出具任何签名**：签名 / 公证 / 上架由开发者本地完成
+（完整指引见 `docs/mobile-shell-signing.md`）。
+
+## 页面侧调用云函数（在线运行时）
+
+页面代码与桌面同款，用 `@adep/client` 以 `platformUrl` 绝对地址 invoke：
+
+```ts
+import { createAdepClient } from '@adep/client/functions'
+
+const client = createAdepClient({ baseUrl: window.__ADEP_APP__.platformUrl })
+const result = await client.invokeFunction('hello', { name: 'world' })
+```
+
+## 原生能力与权限门控（§2.11.5）
+
+- 在平台「应用打包」设置页声明的权限（`permissions`）经 CLI build 写入
+  `app/site/adep.permissions.json`，随 `npx cap sync` 同步进两端原生资源
+  （Android `assets/public/` / iOS `Public/`）。
+- **门控做在原生侧**（`AdepPermissionGate.swift` / `AdepPermissionGate.kt`）：未声明的能力
+  调用直接返回 `PERMISSION_DENIED` 并记设备侧审计日志（`adep-audit.log`），**绝不在运行时
+  申请**。JS 侧不持有放行决策（客户端产物等同公开，决策放 JS 侧等于没有门）。
+- **系统权限映射**：声明了某个能力后，还需在原生工程配相应系统权限——iOS 在
+  `ios/App/App/Info.plist` 加用途描述（如定位 `NSLocationWhenInUseUsageDescription`）、
+  Android 在 `android/app/src/main/AndroidManifest.xml` 加 `uses-permission`
+  （如 `ACCESS_FINE_LOCATION`）。本插件**不**主动索取任何系统权限。
+- 设备端函数（离线运行时）请求原生能力：`await window.__ADEP_APP__.invokeNative('geolocation', {})`。
+
+## ownerKey 存储（§2.11.5 设备身份与恢复）
+
+安装首启时由壳原生侧向服务端签发端点换取 ownerKey，**只存 Keychain（iOS）/ Keystore
+（Android）**：`AdepKeychain.swift`（`kSecClassGenericPassword`）/
+`AdepKeystore.kt`（Android Keystore + AES/GCM，密文落 SharedPreferences）。明文不落 JS
+侧 / 明文文件；插件提供 `getOwnerKey` / `setOwnerKey` / `deleteOwnerKey`（恢复码认领时换键）。
+
+## iOS 约束（§2.11.4 / §2.11.7）
+
+- **仅 UI 变更可自行发版**：函数逻辑变更需重新提交 App Store 审核（天级）。
+  业务频繁迭代且用户主要联网时选**在线运行时**（默认，本模板即在线）。
+- **本平台不做 iOS 运行时下发离线包**（App Store 2.5.2 灰区，ADR-0008 第 10 条）；
+  Android 不受此限。随二进制提交的 JS 属静态产物、不触发 2.5.2。

package/templates/app-mobile/adep.permissions.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "permissions": []
+}