@ducking-mind/proxy-app-cli 0.1.1 → 0.2.0

package/proxy-app.mjs

@@ -1,26 +1,29 @@
 #!/usr/bin/env node
 
 import { spawn } from 'node:child_process'
-import { existsSync, readFileSync } from 'node:fs'
-import { cp, lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { createHash, randomUUID } from 'node:crypto'
-import { createRequire } from 'node:module'
-import { basename, dirname, extname, join, resolve, sep } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { dirname, join, resolve, sep } from 'node:path'
 import { createServer as createTCPServer } from 'node:net'
 import { zipSync } from 'fflate'
 import { createLocalDevelopmentRelay } from './local-dev-relay.mjs'
 import { createLocalCredentialStore } from './local-dev-credentials.mjs'
 import { assertSafeArtifactFile, assertSafeArtifactDirectory } from './artifact-security.mjs'
+import { readLocalFunctionSources } from './runtime-sources.mjs'
 import { resolveAgentContract } from './agent-contract.mjs'
+import { DEFAULT_PLATFORM_GATEWAY_URL, platformAPIBaseURL, platformPortalURL } from './platform-settings.mjs'
+import { createBackendContainerSpec, dockerClientEnvironment, verifyDockerEngine } from './backend-container.mjs'
 
 const MAX_BUNDLE_BYTES = 50 * 1024 * 1024
+const APP_BACKEND_TYPES = new Set(['platform', 'container'])
+const APP_CONTAINER_RUNTIME = 'node22'
+const APP_BACKEND_DEV_PATH = '/api'
 const ALLOWED_PERMISSIONS = new Set(['user.profile.read', 'platform.capabilities.read', 'storage.user', 'notification', 'theme.read', 'locale.read'])
 const ALLOWED_APIS = new Set(['model.responses', 'model.chat', 'model.messages', 'model.embeddings', 'model.images', 'model.videos', 'model.music', 'model.voice_design', 'model.tts'])
 const ALLOWED_PRICING_MODES = new Set(['commission'])
 const ALLOWED_CATEGORIES = new Set(['ecommerce', 'comic', 'other'])
 const RESERVED_AGENT_NAMESPACES = new Set(['app', 'codex', 'desktop', 'proxy', 'system'])
-const BUNDLE_IGNORED_FILES = new Set(['.proxy-app.json', '.proxy-app-build'])
+const BUNDLE_IGNORED_FILES = new Set(['.proxy-app.json', '.proxy-app-session.json', '.proxy-app-build', '.proxy-app-runtime'])
 const APP_WORKSPACE_PATH = '/portal/user/app-workspace'
 // Public slugs are used verbatim, including single-segment names such as
 // "canvas". The platform's opaque app_id remains a separate compatibility
@@ -37,24 +40,8 @@ const appBinding = app => ({
   ...(publicAppAliases(app).length ? { app_aliases: publicAppAliases(app) } : {}),
 })
 
-// npm packages carry the same pure protocol modules as the desktop host.
-// Source checkouts prefer the live implementation so validation cannot drift.
-const agentRuntimeDirectory = await stat(new URL('../desktop/agent/protocol.mjs', import.meta.url)).then(() => '../desktop/agent/').catch(error => {
-  if (error.code !== 'ENOENT') throw error
-  return './agent-runtime/'
-})
-const { normalizeManifestAgent } = await import(new URL(`${agentRuntimeDirectory}protocol.mjs`, import.meta.url))
-const { loadAgentPackage, copyAgentPackage } = await import(new URL(`${agentRuntimeDirectory}package-guide.mjs`, import.meta.url))
-
-// Source checkouts use the live desktop release helpers. npm packages carry a
-// small prepackaged copy under release-runtime/ so `proxy-app` works after
-// installation without the monorepo's app/desktop directory.
-const releaseRuntimeDirectory = await stat(new URL('../desktop/scripts/release-config.mjs', import.meta.url)).then(() => '../desktop/scripts/').catch(error => {
-  if (error.code !== 'ENOENT') throw error
-  return './release-runtime/'
-})
-const { isAllowedReleaseURL, loadReleaseConfig, parseConfigOption, releaseConfigRoot, validateReleaseConfig } = await import(new URL(`${releaseRuntimeDirectory}release-config.mjs`, import.meta.url))
-const { releaseFeedURL, releaseTarget } = await import(new URL(`${releaseRuntimeDirectory}release-target.mjs`, import.meta.url))
+const { normalizeManifestAgent } = await import(new URL('./agent-runtime/protocol.mjs', import.meta.url))
+const { loadAgentPackage, copyAgentPackage } = await import(new URL('./agent-runtime/package-guide.mjs', import.meta.url))
 
 function usage() {
   console.log(`在应用目录内，常用命令：
@@ -79,35 +66,35 @@ pack 无需提前执行 build 或 validate；已上传的版本由 publish 直
   proxy-app pack [app-dir] [-o <output.zip>]
   proxy-app upload [app-dir] [-o <output.zip>]
   proxy-app publish [app-dir] [-o <output.zip> | --version <uploaded-version>]
-  proxy-app desktop-build [app-dir]
-  proxy-app desktop-pack [app-dir] [-o <output-directory>]
 
   upload 只上传；publish 显式切换线上版本。首次使用 publish 仍需申请应用开放。
   --version 仅选择已上传版本，不构建、不上传、不修改本地 manifest。
+  backend.type=container 仅支持本地联调；云端构建和容器路由尚未开放。
+  容器后端本地运行需要已启动的 Docker Engine；服务进程在只读、非特权 Node 22 容器中启动。
   -o 与 --output 等价，也兼容原来的 <app-dir> <output.zip> 写法。
   --source 仅供 pack/upload 调试源码，跳过构建，不用于正式发布。
-  desktop-pack 会在输出目录生成 desktop-release.json 和 electron-updater metadata；发布配置
-  使用 desktop/release.config.json，API Key 只用于发布请求，不会写入安装包。
   应用分类：ecommerce（电商）、comic（漫剧）、other（其他，默认）。
 
 Publish environment:
   PROXY_PLATFORM_URL  Optional single-origin platform URL; derives API (/api) and login Portal
-  PROXY_API_BASE_URL  default: http://localhost:9003/api
+  PROXY_API_BASE_URL  default: https://www.duckingmind.com/api
                        Optional override when the platform uses a separate API host
-  PROXY_PORTAL_URL    Optional login Portal override; default: http://localhost:9004
-  PROXY_USER_ACCESS_TOKEN  Current platform user session for app management/CI only; never passed to the app
+  PROXY_PORTAL_URL    Optional login Portal override; default: https://www.duckingmind.com
+  PROXY_PLATFORM_GATEWAY_URL  Gateway target for Vite /v1 proxy; default: ${DEFAULT_PLATFORM_GATEWAY_URL}
+  PROXY_USER_ACCESS_TOKEN  Platform user session for management, CI or developer authorization; never passed to the app
   PROXY_ACCESS_TOKEN       Legacy alias for PROXY_USER_ACCESS_TOKEN
 
   Local development:
   proxy-app dev <app-dir> [--port 5173]
-  If the requested port is occupied, the next available loopback port is used.
+  An explicitly requested occupied port fails with a clear error; the default port may advance automatically.
   Checks the app binding and developer permission before starting the app.
   First authorize the developer using the terminal login URL; then app users
   sign in separately for their own App Session, models, quota and billing.
-  App business traffic always uses the App Session Gateway (/v1). The local
-  relay exposes only the authentication control path and never an Admin Runtime
-  or legacy Bridge endpoint.
-  macOS stores developer and app-user authorization separately in Keychain.
+  App business traffic always uses the App Session Gateway (/v1). Vite sends
+  /v1 directly to the Gateway; set PROXY_PLATFORM_GATEWAY_URL only when using
+  a different Gateway environment. Runtime user sessions stay in the browser;
+  the local authorization callback handles developer setup only.
+  macOS stores developer authorization in Keychain.
   --no-auth-cache uses memory only. If a cached developer account cannot access
   the app, dev automatically asks you to authorize with the app creator account.
 
@@ -124,7 +111,10 @@ function option(args, name, fallback = '') {
 
 function reservePort(port) {
   return new Promise((resolvePromise, reject) => {
-    const server = createTCPServer()
+    // A platform health check or browser may connect while this socket reserves
+    // the selected port. Destroy probes immediately so server.close() cannot
+    // wait forever for a connection the temporary listener never serves.
+    const server = createTCPServer((socket) => socket.destroy())
     let settled = false
     const settle = (callback, value) => {
       if (settled) return
@@ -165,8 +155,6 @@ function commandArguments(command, args) {
     pack: { values: ['--output'], flags: ['--source'], max: 2 },
     upload: { values: ['--output'], flags: ['--source'], max: 2 },
     publish: { values: ['--output', '--version'], max: 2 },
-    'desktop-build': { values: ['--config'], flags: ['--mac', '--macos', '-m', '--win', '--windows', '-w', '--linux', '-l', '--x64', '--arm64', '--ia32', '--env-overrides'], max: 1 },
-    'desktop-pack': { values: ['--output', '--config'], flags: ['--mac', '--macos', '-m', '--win', '--windows', '-w', '--linux', '-l', '--x64', '--arm64', '--ia32', '--env-overrides'], max: 2 },
   }
   const config = configurations[command]
   if (!config) throw new Error(`unknown command: ${command}`)
@@ -214,27 +202,6 @@ function apiSettings() {
   return { token, baseURL }
 }
 
-function platformAPIBaseURL() {
-  const explicit = process.env.PROXY_API_BASE_URL?.trim()
-  if (explicit) return explicit.replace(/\/$/, '')
-  const platform = process.env.PROXY_PLATFORM_URL?.trim()
-  if (!platform) return 'http://localhost:9003/api'
-  let url
-  try { url = new URL(platform) } catch { throw new Error('PROXY_PLATFORM_URL must be a valid platform origin, such as https://platform.example') }
-  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== '/') {
-    throw new Error('PROXY_PLATFORM_URL must be a platform origin without a path, credentials, query, or hash')
-  }
-  return `${url.origin}/api`
-}
-
-function platformPortalURL() {
-  const explicit = process.env.PROXY_PORTAL_URL?.trim() || process.env.PROXY_PUBLIC_URL?.trim()
-  if (explicit) return explicit
-  const platform = process.env.PROXY_PLATFORM_URL?.trim()
-  if (platform) return platform
-  return 'http://localhost:9004'
-}
-
 function responseError(body, fallback) {
   const message = typeof body?.error === 'string' ? body.error : body?.error?.message || body?.message
   const code = body?.code || body?.error?.code
@@ -260,6 +227,175 @@ function safeRelative(value) {
   return normalized.split('/').filter(Boolean).join('/')
 }
 
+function validateBackendManifest(backend) {
+  if (backend === undefined || backend?.type === undefined || backend?.type === 'platform') return
+  if (!APP_BACKEND_TYPES.has(backend.type)) throw new Error('manifest.backend.type must be platform or container')
+  if (backend.type !== 'container') return
+  const supportedFields = new Set(['type', 'runtime', 'entry', 'port', 'health_check', 'routes', 'resources'])
+  for (const name of Object.keys(backend)) {
+    if (!supportedFields.has(name)) throw new Error(`unsupported manifest.backend field: ${name}`)
+  }
+  if (backend.runtime !== APP_CONTAINER_RUNTIME) throw new Error(`manifest.backend.runtime must be ${APP_CONTAINER_RUNTIME}`)
+  if (typeof backend.entry !== 'string') throw new Error('manifest.backend.entry is required for container backends')
+  let entry
+  try {
+    entry = safeRelative(backend.entry)
+  } catch (error) {
+    throw new Error(`manifest.backend.entry is invalid: ${error.message}`)
+  }
+  if (backend.entry.replaceAll('\\', '/') !== entry) {
+    throw new Error('manifest.backend.entry must be a normalized relative path')
+  }
+  if (!entry.startsWith('server/')) throw new Error('manifest.backend.entry must be inside server/')
+  if (entry.split('/').some((part) => part === '.' || part === '')) throw new Error('manifest.backend.entry must be a normalized relative path')
+  if (!['.js', '.mjs', '.cjs'].includes(entry.slice(entry.lastIndexOf('.')).toLowerCase())) {
+    throw new Error('manifest.backend.entry must be a JavaScript file (.js, .mjs, or .cjs)')
+  }
+  if (!Number.isInteger(backend.port) || backend.port < 1 || backend.port > 65535) {
+    throw new Error('manifest.backend.port must be an integer between 1 and 65535')
+  }
+  if (backend.health_check !== undefined && (
+    typeof backend.health_check !== 'string' || !backend.health_check.startsWith('/') ||
+    backend.health_check.startsWith('//') || /[?#\\]/.test(backend.health_check) || backend.health_check.split('/').includes('..')
+  )) {
+    throw new Error('manifest.backend.health_check must be an absolute safe path')
+  }
+  if (backend.routes !== undefined) {
+    if (!Array.isArray(backend.routes) || backend.routes.length === 0) throw new Error('manifest.backend.routes must be a non-empty array')
+    const seen = new Set()
+    for (const route of backend.routes) {
+      if (typeof route !== 'string' || !route.startsWith(`${APP_BACKEND_DEV_PATH}/`) ||
+        route.startsWith('//') || /[?#\\]/.test(route) || route.split('/').includes('..') ||
+        !(route.endsWith('/*') || !route.includes('*'))) {
+        throw new Error(`manifest.backend.routes entries must be safe ${APP_BACKEND_DEV_PATH} paths`)
+      }
+      if (seen.has(route)) throw new Error(`duplicate manifest.backend.routes entry: ${route}`)
+      seen.add(route)
+    }
+  }
+  if (backend.resources !== undefined) {
+    const resources = backend.resources
+    if (!resources || typeof resources !== 'object' || Array.isArray(resources)) throw new Error('manifest.backend.resources must be an object')
+    const bounds = { cpu_millicores: [50, 4000], memory_mib: [64, 8192], max_concurrency: [1, 1000] }
+    for (const [name, value] of Object.entries(resources)) {
+      const range = bounds[name]
+      if (!range) throw new Error(`unsupported manifest.backend.resources field: ${name}`)
+      if (!Number.isInteger(value) || value < range[0] || value > range[1]) {
+        throw new Error(`manifest.backend.resources.${name} must be an integer between ${range[0]} and ${range[1]}`)
+      }
+    }
+  }
+}
+
+// Runtime Host evaluates release entries as ES modules in QuickJS. Keep the
+// CLI contract aligned with Admin so a package cannot pass local validation
+// and then fail publication because its entry is CommonJS.
+const FUNCTION_ENTRY_EXTENSIONS = new Set(['.js', '.mjs'])
+const FUNCTION_SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'])
+
+function validateFunctionPath(value, field, { source = false } = {}) {
+  if (typeof value !== 'string') throw new Error(`manifest.functions.${field} must be a string`)
+  let normalized
+  try {
+    normalized = safeRelative(value)
+  } catch (error) {
+    throw new Error(`manifest.functions.${field} is invalid: ${error.message}`)
+  }
+  if (value.replaceAll('\\', '/') !== normalized || normalized.split('/').some(part => part === '.' || part === '')) {
+    throw new Error(`manifest.functions.${field} must be a normalized relative path`)
+  }
+  const extension = normalized.slice(normalized.lastIndexOf('.')).toLowerCase()
+  const allowed = source ? FUNCTION_SOURCE_EXTENSIONS : FUNCTION_ENTRY_EXTENSIONS
+  if (!allowed.has(extension)) {
+    throw new Error(`manifest.functions.${field} must be a ${source ? 'TypeScript or JavaScript' : 'JavaScript'} file`)
+  }
+  if (!source && !normalized.startsWith('runtime/')) throw new Error(`manifest.functions.${field} must be inside runtime/`)
+  if (source && !normalized.startsWith('src/')) throw new Error(`manifest.functions.${field} must be inside src/`)
+  return normalized
+}
+
+function validateFunctionRoutes(routes, field) {
+  if (routes === undefined) return
+  if (!Array.isArray(routes) || routes.length === 0) throw new Error(`manifest.functions.${field}.routes must be a non-empty array`)
+  const seen = new Set()
+  for (const route of routes) {
+    if (typeof route !== 'string' || !route.startsWith('/api/') || route.startsWith('//') || /[?#\\]/.test(route) || route.split('/').includes('..') || route.includes('*') && !route.endsWith('/*')) {
+      throw new Error(`manifest.functions.${field}.routes entries must be safe /api/ paths`)
+    }
+    if (seen.has(route)) throw new Error(`duplicate manifest.functions.${field}.routes entry: ${route}`)
+    seen.add(route)
+  }
+}
+
+function validateFunctionsManifest(functions) {
+  if (functions === undefined) return
+  if (!functions || typeof functions !== 'object' || Array.isArray(functions)) throw new Error('manifest.functions must be an object')
+  const names = Object.keys(functions)
+  if (!names.length || names.some(name => !['request', 'task'].includes(name))) throw new Error('manifest.functions may contain only request and task')
+  for (const name of names) {
+    const descriptor = functions[name]
+    if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor)) throw new Error(`manifest.functions.${name} must be an object`)
+    const supported = name === 'request'
+      ? new Set(['entry', 'source', 'routes', 'timeout_ms'])
+      : new Set(['entry', 'source', 'concurrency', 'max_attempts', 'timeout_ms'])
+    for (const field of Object.keys(descriptor)) if (!supported.has(field)) throw new Error(`unsupported manifest.functions.${name} field: ${field}`)
+    validateFunctionPath(descriptor.entry, `${name}.entry`)
+    if (descriptor.source !== undefined) validateFunctionPath(descriptor.source, `${name}.source`, { source: true })
+    if (name === 'request') {
+      validateFunctionRoutes(descriptor.routes, name)
+      if (!descriptor.routes?.length) throw new Error('manifest.functions.request.routes must declare at least one /api/ path')
+      if (descriptor.timeout_ms !== undefined && (!Number.isInteger(descriptor.timeout_ms) || descriptor.timeout_ms < 100 || descriptor.timeout_ms > 10 * 60 * 1000)) {
+        throw new Error('manifest.functions.request.timeout_ms must be an integer between 100 and 600000')
+      }
+    } else {
+      const bounds = { concurrency: [1, 1000], max_attempts: [1, 20], timeout_ms: [100, 3_600_000] }
+      for (const [field, value] of Object.entries(descriptor)) {
+        const range = bounds[field]
+        if (!range) continue
+        if (!Number.isInteger(value) || value < range[0] || value > range[1]) throw new Error(`manifest.functions.task.${field} must be an integer between ${range[0]} and ${range[1]}`)
+      }
+    }
+  }
+  if (functions.request && functions.task && functions.request.entry === functions.task.entry) {
+    throw new Error('manifest.functions.request.entry and task.entry must be different')
+  }
+}
+
+function validateDatabaseManifest(database) {
+  if (database !== undefined) throw new Error('manifest.database is no longer supported; use context.platform.request() through Gateway APIs')
+}
+
+async function validateFunctionEntries(appDir, artifactRoot, functions, { requireArtifact = false } = {}) {
+  if (!functions) return
+  for (const [name, descriptor] of Object.entries(functions)) {
+    if (descriptor.source && !(await exists(join(resolve(appDir), safeRelative(descriptor.source))))) {
+      throw new Error(`manifest.functions.${name}.source does not exist: ${descriptor.source}`)
+    }
+    const entry = safeRelative(descriptor.entry)
+    if (requireArtifact && !(await exists(join(artifactRoot, entry)))) {
+      throw new Error(`manifest.functions.${name}.entry does not exist in build output: ${entry}`)
+    }
+  }
+}
+
+async function validateBackendEntry(appDir, backend) {
+  if (backend?.type !== 'container') return
+  const relative = safeRelative(backend.entry)
+  const segments = relative.split('/')
+  let current = resolve(appDir)
+  for (const segment of segments) {
+    current = join(current, segment)
+    const info = await lstat(current).catch((error) => {
+      if (error.code === 'ENOENT') throw new Error(`manifest.backend.entry does not exist: ${relative}`)
+      throw error
+    })
+    if (info.isSymbolicLink()) throw new Error(`manifest.backend.entry cannot contain symbolic links: ${relative}`)
+    if (current !== join(resolve(appDir), relative) && !info.isDirectory()) throw new Error(`manifest.backend.entry parent is not a directory: ${relative}`)
+  }
+  const info = await lstat(current)
+  if (!info.isFile()) throw new Error(`manifest.backend.entry must be a regular file: ${relative}`)
+}
+
 async function exists(path) {
   try {
     await stat(path)
@@ -284,10 +420,9 @@ async function readManifest(appDir) {
   if (manifest.backend !== undefined && (!manifest.backend || typeof manifest.backend !== 'object' || Array.isArray(manifest.backend))) {
     throw new Error('manifest.backend must be an object')
   }
-  // App traffic always goes through the platform gateway. Treating backend as
-  // optional keeps the manifest focused on app-specific capabilities while
-  // preserving an explicit rejection for unsupported backends.
-  if ((manifest.backend?.type || 'platform') !== 'platform') throw new Error('manifest.backend.type must be platform')
+  validateBackendManifest(manifest.backend)
+  validateFunctionsManifest(manifest.functions)
+  validateDatabaseManifest(manifest.database)
   // Permissions are optional metadata. An omitted list means the app accepts
   // the platform's currently supported public capabilities; an explicit list
   // remains available for legacy packages that intentionally narrow access.
@@ -347,6 +482,7 @@ async function readManifest(appDir) {
 async function validateApp(appDir, { checkBuildManifest = true, source = false } = {}) {
   const root = resolve(appDir)
   const { manifest, entry } = await readManifest(root)
+  await validateBackendEntry(root, manifest.backend)
   // The package identity is carried by manifest.id. A legacy sidecar may be
   // present, but it is deliberately ignored here: local validation must not
   // turn the removed link/repair workflow into an upload prerequisite. The
@@ -360,6 +496,7 @@ async function validateApp(appDir, { checkBuildManifest = true, source = false }
   if (manifest.assets?.icon && !(await exists(join(artifactRoot, safeRelative(manifest.assets.icon))))) {
     console.warn(`warning: manifest.assets.icon is missing: ${manifest.assets.icon}`)
   }
+  await validateFunctionEntries(root, artifactRoot, manifest.functions, { requireArtifact: artifactRoot !== root })
   if (checkBuildManifest && artifactRoot !== root && await exists(join(artifactRoot, 'manifest.json'))) {
     const builtManifest = JSON.parse(await readFile(join(artifactRoot, 'manifest.json'), 'utf8'))
     if (JSON.stringify(builtManifest) !== JSON.stringify(manifest)) {
@@ -470,6 +607,8 @@ async function devApp(appDir, args) {
     throw new Error('package.json 的 dev:server 脚本必须直接调用 Vite 等开发服务器，不能调用 proxy-app dev 或 npm run dev。')
   }
   const { manifest } = await readManifest(root)
+  await validateBackendEntry(root, manifest.backend)
+  const functionFiles = await readLocalFunctionSources(root, manifest)
   const supportedOptions = new Set(['--port', '--no-auth-cache'])
   for (const arg of args) {
     if (arg.startsWith('--') && !supportedOptions.has(arg)) {
@@ -480,12 +619,35 @@ async function devApp(appDir, args) {
   // registration resolves the stable ID in memory before creating sessions.
   const binding = { app_id: manifest.id, slug: manifest.id }
   const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
+  const backend = manifest.backend?.type === 'container' ? manifest.backend : null
+  const gatewayURL = process.env.PROXY_PLATFORM_GATEWAY_URL?.trim() || DEFAULT_PLATFORM_GATEWAY_URL
+  let backendContainer
+  if (backend) {
+    const dockerBin = process.env.PROXY_APP_DOCKER_BIN || 'docker'
+    const dockerEnv = dockerClientEnvironment(process.env)
+    await verifyDockerEngine({ dockerBin, env: dockerEnv })
+    backendContainer = await createBackendContainerSpec({
+      appDir: root,
+      backend,
+      appID: manifest.id,
+      version: manifest.version,
+      gatewayURL,
+      dockerBin,
+      dockerEnv,
+    })
+  }
   const devScript = ['dev:server', 'dev'].find(name => typeof pkg.scripts?.[name] === 'string' && pkg.scripts[name].trim())
   if (!devScript) throw new Error('package.json 缺少 dev:server 脚本，请配置 Vite 等开发服务器启动命令。')
   const requestedPort = option(args, '--port', process.env.PROXY_APP_DEV_PORT || '5173')
   if (!/^\d+$/.test(requestedPort) || Number(requestedPort) < 1 || Number(requestedPort) > 65535) throw new Error('--port must be between 1 and 65535')
   const configuredEntryURL = process.env.PROXY_APP_DEV_URL?.trim() || ''
-  let portReservation = configuredEntryURL ? null : await reserveAvailablePort(Number(requestedPort))
+  const portWasExplicit = args.includes('--port') || Boolean(process.env.PROXY_APP_DEV_PORT?.trim())
+  let portReservation = configuredEntryURL ? null : portWasExplicit
+    ? await reservePort(Number(requestedPort))
+    : await reserveAvailablePort(Number(requestedPort))
+  if (!configuredEntryURL && portWasExplicit && !portReservation) {
+    throw new Error(`端口 ${requestedPort} 已被占用；请停止占用该端口的旧开发服务器，或改用 --port <可用端口> 后重试。`)
+  }
   const selectedPort = portReservation?.port || Number(requestedPort)
   if (!configuredEntryURL && selectedPort !== Number(requestedPort)) {
     console.warn(`端口 ${requestedPort} 已被占用，改用 ${selectedPort}。`)
@@ -494,13 +656,20 @@ async function devApp(appDir, args) {
   let parsedEntryURL
   try { parsedEntryURL = new URL(entryURL) } catch { throw new Error('PROXY_APP_DEV_URL must be a valid loopback http(s) URL') }
   if (!['http:', 'https:'].includes(parsedEntryURL.protocol) || !['localhost', '127.0.0.1', '::1'].includes(parsedEntryURL.hostname) || parsedEntryURL.username || parsedEntryURL.password) {
+    await portReservation?.release()
     throw new Error('PROXY_APP_DEV_URL must use localhost, 127.0.0.1, or ::1 without credentials')
   }
-  const relaySecret = randomUUID()
+  let backendPortReservation = null
+  if (backend) {
+    backendPortReservation = await reservePort(backend.port)
+    if (!backendPortReservation) {
+      await portReservation?.release()
+      throw new Error(`应用后端端口 ${backend.port} 已被占用；请修改 manifest.backend.port 后重试。`)
+    }
+  }
   const baseURL = platformAPIBaseURL()
   const portalURL = platformPortalURL()
   const storeSettings = { baseURL, portalURL, appID: binding.app_id, projectPath: root }
-  const credentialStore = args.includes('--no-auth-cache') ? null : createLocalCredentialStore(storeSettings)
   const developerCredentialStore = args.includes('--no-auth-cache') ? null : createLocalCredentialStore({
     ...storeSettings, purpose: 'development',
   })
@@ -523,17 +692,17 @@ async function devApp(appDir, args) {
     relay = await createLocalDevelopmentRelay({
       baseURL,
       portalURL,
-      relaySecret,
       appID: binding.app_id,
       appSlug: manifest.id,
       version: manifest.version,
       manifest,
+      functionFiles,
       entryURL,
-      credentialStore: cachedOperations(credentialStore),
       developerCredentialStore: cachedOperations(developerCredentialStore),
     })
   } catch (error) {
     await portReservation?.release()
+    await backendPortReservation?.release()
     throw error
   }
   const {
@@ -544,17 +713,35 @@ async function devApp(appDir, args) {
     PROXY_PUBLIC_URL: _publicURL,
     PROXY_APP_DEV_URL: _entryURL,
     PROXY_APP_DEV_PORT: _devPort,
+    PROXY_APP_DEV_AUTH_RELAY_URL: _staleAuthRelayURL,
+    PROXY_APP_DEV_AUTH_RELAY_SECRET: _staleAuthRelaySecret,
+    PROXY_APP_DEV_SESSION_GRANT: _staleDevelopmentSessionGrant,
     PROXY_PLATFORM_GATEWAY_URL: _gatewayURL,
+    PROXY_PLATFORM_RUNTIME_URL: _runtimeURL,
+    PROXY_PLATFORM_BRIDGE_URL: _bridgeURL,
     PROXY_PLATFORM_AUTH_URL: _authURL,
-    PROXY_PLATFORM_RELAY_SECRET: _inheritedRelaySecret,
+    PROXY_APP_BACKEND_URL: _inheritedBackendURL,
+    PROXY_APP_BACKEND_PATH: _inheritedBackendPath,
     ...safeChildEnv
   } = process.env
+  // Keep the same-origin Vite proxy pointed at Gateway. Runtime user sessions
+  // are obtained by the Portal in the browser; the CLI relay is limited to
+  // developer authorization and draft registration.
+  const selectedGatewayURL = _gatewayURL?.trim() || gatewayURL
+  const browserPortalURL = new URL(portalURL).origin
   const childEnv = {
     ...safeChildEnv,
     PROXY_APP_DEV_ACTIVE: root,
-    PROXY_PLATFORM_GATEWAY_URL: `${relay.relayURL}/v1`,
-    PROXY_PLATFORM_AUTH_URL: `${relay.relayURL}/auth`,
-    PROXY_PLATFORM_RELAY_SECRET: relaySecret,
+    PROXY_PLATFORM_GATEWAY_URL: selectedGatewayURL,
+    VITE_PROXY_PORTAL_URL: browserPortalURL,
+    PROXY_APP_DEV_SESSION_API_URL: baseURL,
+    PROXY_APP_DEV_SESSION_PORTAL_URL: browserPortalURL,
+    PROXY_APP_DEV_SESSION_ID: manifest.id,
+    PROXY_APP_DEV_SESSION_VERSION: manifest.version,
+    ...(backend ? {
+      PROXY_APP_BACKEND_URL: `http://127.0.0.1:${backend.port}`,
+      PROXY_APP_BACKEND_PATH: APP_BACKEND_DEV_PATH,
+    } : {}),
   }
   const preparation = new AbortController()
   let canceledSignal = ''
@@ -581,20 +768,36 @@ async function devApp(appDir, args) {
         console.log('完成开发者授权并通过应用登记检查后才会启动本地应用。按 Ctrl+C 取消。')
       },
     })
+    childEnv.PROXY_APP_DEV_SESSION_GRANT = relay.getDevelopmentSessionGrant()
+    console.log('开发应用检查通过。')
+    preparation.signal.throwIfAborted()
     preparation.signal.throwIfAborted()
     removePreparationListeners()
-    console.log('开发应用检查通过。应用用户将在应用内独立登录。')
-    console.log(`Proxy App platform relay ready: ${relay.relayURL}`)
     console.log(`Local app: ${entryURL}`)
-    console.log('App transport: App Session Gateway (/v1); local relay auth is /__platform/auth.')
-    console.log('Platform mode: sign in from the app to use real models, provider routing, quota and billing.')
+    if (backend) {
+      console.log(`Local app backend: http://127.0.0.1:${backend.port}${APP_BACKEND_DEV_PATH}/*`)
+      console.log(`Backend runtime: Docker (${backend.runtime}); source is mounted read-only and app dependencies are installed in container tmpfs.`)
+    }
+    console.log('App transport: Gateway App Session (/v1); browser requests never leave the Gateway data plane.')
+    console.log('App Session: sign in through the Portal when prompted; the browser keeps it in this tab.')
     await portReservation?.release()
     portReservation = null
-    await runChild('npm', ['run', devScript, '--', '--host', '127.0.0.1', '--port', String(selectedPort), '--strictPort'], root, childEnv)
+    await backendPortReservation?.release()
+    backendPortReservation = null
+    const children = []
+    if (backendContainer) children.push(backendContainer)
+    children.push({
+      command: 'npm',
+      args: ['run', devScript, '--', '--host', '127.0.0.1', '--port', String(selectedPort), '--strictPort'],
+      cwd: root,
+      env: childEnv,
+      name: 'npm',
+    })
+    await runChildren(children)
   } catch (error) {
     if (!canceledSignal) {
       const guidance = []
-      if (error?.stage === 'app_registration') {
+      if (error?.stage === 'app_registration' && ['APP_APP_REGISTRATION_FAILED', 'APP_LOGIN_SESSION_EXPIRED'].includes(error?.code)) {
         if ([403, 404].includes(error.statusCode)) {
           guidance.push('请核对 manifest.json 中的 id（应用 slug）与上述平台地址，确认应用已在该平台创建。开发不需要绑定或 repair。')
           guidance.push('请使用应用创建者账户完成开发授权，并确认终端显示的平台地址与应用所在平台一致。')
@@ -602,9 +805,9 @@ async function devApp(appDir, args) {
         } else if (error.statusCode === 401) {
           guidance.push('请确认 PROXY_USER_ACCESS_TOKEN 属于应用创建者；如果该变量是旧账户令牌，请清除或取消设置后重新运行普通 proxy-app dev。')
         }
-        if (typeof error.requestId === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(error.requestId)) {
-          guidance.push(`请求编号：${error.requestId}`)
-        }
+      }
+      if (typeof error.requestId === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(error.requestId)) {
+        guidance.push(`请求编号：${error.requestId}`)
       }
       if (guidance.length) error.message += '\n' + guidance.join('\n')
       throw error
@@ -614,10 +817,79 @@ async function devApp(appDir, args) {
   } finally {
     removePreparationListeners()
     await portReservation?.release()
+    await backendPortReservation?.release()
     await relay.close()
   }
 }
 
+function runChildren(specifications) {
+  return new Promise((resolvePromise, reject) => {
+    const children = []
+    let stopping = false
+    let settled = false
+    let firstError = null
+    let remaining = specifications.length
+    const removeSignalHandlers = () => {
+      process.removeListener('SIGINT', onInterrupt)
+      process.removeListener('SIGTERM', onTerminate)
+    }
+    const stopChild = (child, signal = 'SIGTERM') => {
+      if (!child.pid || child.exitCode !== null || child.signalCode !== null) return
+      try {
+        if (process.platform !== 'win32') process.kill(-child.pid, signal)
+        else child.kill(signal)
+      } catch { /* Child exited between the state check and signal. */ }
+    }
+    const finish = () => {
+      if (settled || remaining > 0) return
+      settled = true
+      removeSignalHandlers()
+      if (firstError) reject(firstError)
+      else resolvePromise()
+    }
+    const stopAll = () => {
+      if (stopping) return
+      stopping = true
+      for (const child of children) stopChild(child)
+      const forceKill = setTimeout(() => {
+        for (const child of children) stopChild(child, 'SIGKILL')
+      }, 5000)
+      forceKill.unref()
+    }
+    const onInterrupt = () => { stopAll() }
+    const onTerminate = () => { stopAll() }
+    process.once('SIGINT', onInterrupt)
+    process.once('SIGTERM', onTerminate)
+    for (const specification of specifications) {
+      const child = spawn(specification.command, specification.args, {
+        cwd: specification.cwd,
+        env: specification.env,
+        stdio: 'inherit',
+        detached: process.platform !== 'win32',
+        shell: process.platform === 'win32',
+      })
+      children.push(child)
+      let childFinished = false
+      const finishChild = (error) => {
+        if (childFinished) return
+        childFinished = true
+        if (error && !firstError) firstError = error
+        remaining -= 1
+        if (error) stopAll()
+        finish()
+      }
+      child.once('error', (error) => {
+        finishChild(error)
+      })
+      child.once('close', (code, signal) => {
+        const unexpectedError = !stopping && code !== 0 ? new Error(`${specification.name} exited with ${code ?? signal}`) : null
+        finishChild(unexpectedError)
+        if (!stopping) stopAll()
+      })
+    }
+  })
+}
+
 async function packApp(appDir, output, { allowSource = false, allowSourceMaps = allowSource } = {}) {
   const info = allowSource ? await validateApp(appDir, { source: true }) : await buildApp(appDir)
   const outputPath = resolve(output || join(info.root, `${info.manifest.id}-${info.manifest.version}.zip`))
@@ -637,6 +909,9 @@ async function packApp(appDir, output, { allowSource = false, allowSourceMaps =
   }
   if (info.artifactRoot === info.root) await collect(info.root)
   else await collect(info.artifactRoot)
+  if (info.artifactRoot !== info.root && info.manifest.backend?.type === 'container') {
+    await collect(join(info.root, 'server'), 'server')
+  }
   if (JSON.stringify((await readManifest(info.root)).manifest) !== JSON.stringify(info.manifest)) {
     throw new Error('manifest 或代码能力契约在打包期间发生变更，请重新运行 proxy-app pack。')
   }
@@ -652,207 +927,6 @@ async function packApp(appDir, output, { allowSource = false, allowSourceMaps =
   return { ...info, outputPath }
 }
 
-async function loadDesktopReleaseConfig(options = []) {
-  const parsed = parseConfigOption(options)
-  const config = await loadReleaseConfig({
-    root: releaseConfigRoot(),
-    cwd: process.env.INIT_CWD || process.cwd(),
-    configPath: parsed.configPath,
-    envOverrides: parsed.envOverrides,
-  })
-  // desktop-build/desktop-pack are also used for local staging. A release
-  // config is optional there; the main app's build:release command
-  // requires update.url before producing a publishable package.
-  return validateReleaseConfig(config)
-}
-
-async function resolveDesktopSource() {
-  const cliRoot = dirname(fileURLToPath(import.meta.url))
-  const checkout = join(cliRoot, '..', 'desktop')
-  if (await exists(join(checkout, 'host'))) return checkout
-  let packageManifest
-  try {
-    packageManifest = createRequire(join(cliRoot, 'package.json')).resolve('@ducking-mind/proxy-app-desktop-runtime/package.json')
-  } catch {
-    throw new Error('Electron runtime package is not installed. Install @ducking-mind/proxy-app-desktop-runtime before building a desktop app.')
-  }
-  const runtime = join(dirname(packageManifest), 'runtime')
-  if (!(await exists(join(runtime, 'host')))) throw new Error('Electron runtime package is incomplete; install a published runtime package with its runtime assets.')
-  return runtime
-}
-
-function findPackageRoot(name, fromDirectory) {
-  const require = createRequire(join(fromDirectory, 'package.json'))
-  let current = dirname(require.resolve(name))
-  while (true) {
-    const manifest = join(current, 'package.json')
-    if (existsSync(manifest)) {
-      try {
-        if (JSON.parse(readFileSync(manifest, 'utf8')).name === name) return current
-      } catch { /* Continue looking above the resolved entry. */ }
-    }
-    const parent = dirname(current)
-    if (parent === current) throw new Error(`cannot resolve installed package: ${name}`)
-    current = parent
-  }
-}
-
-async function desktopBuildApp(appDir, options = []) {
-  const releaseConfig = await loadDesktopReleaseConfig(options)
-  const info = await buildApp(appDir)
-  await assertSafeArtifactDirectory(info.artifactRoot)
-  const staging = join(info.root, 'dist-electron')
-  await rm(staging, { recursive: true, force: true })
-  await mkdir(join(staging, 'app'), { recursive: true })
-  await cp(info.artifactRoot, join(staging, 'app'), { recursive: true, dereference: true })
-  const desktopSource = await resolveDesktopSource()
-  await mkdir(join(staging, 'single-app'), { recursive: true })
-  await cp(join(desktopSource, 'single-app', 'main.mjs'), join(staging, 'single-app', 'main.mjs'))
-  await cp(join(desktopSource, 'single-app', 'preload.cjs'), join(staging, 'single-app', 'preload.cjs'))
-  await cp(join(desktopSource, 'unified', 'renderer', 'assets', 'duck-mark-v2.png'), join(staging, 'single-app', 'status-tray-icon.png'))
-  await cp(join(desktopSource, 'host'), join(staging, 'host'), { recursive: true })
-  await mkdir(join(staging, 'agent'), { recursive: true })
-  for (const name of ['protocol.mjs', 'runtime-status.mjs']) await cp(join(desktopSource, 'agent', name), join(staging, 'agent', name))
-  const desktopPackage = JSON.parse(await readFile(join(desktopSource, 'package.json'), 'utf8'))
-  const installedElectron = await readFile(join(info.root, 'node_modules', 'electron', 'package.json'), 'utf8').then(JSON.parse).catch(() =>
-    readFile(join(desktopSource, 'node_modules', 'electron', 'package.json'), 'utf8').then(JSON.parse).catch(() => null))
-  const electronVersion = installedElectron?.version || String(desktopPackage.devDependencies?.electron || '44.9.0').replace(/^[^0-9]*/, '')
-  // Standalone Electron apps use the same updater as the unified shell. Copy
-  // only its runtime dependency tree into staging; never ship the desktop
-  // project's full devDependencies or its Electron binary.
-  const runtimeDependencies = new Set()
-  async function copyRuntimeDependency(name, fromDir = desktopSource) {
-    if (runtimeDependencies.has(name)) return
-    let source
-    try { source = findPackageRoot(name, fromDir) }
-    catch { throw new Error(`桌面运行依赖缺失：${name}`) }
-    runtimeDependencies.add(name)
-    await cp(source, join(staging, 'node_modules', name), { recursive: true, dereference: true })
-    const packageJSON = JSON.parse(await readFile(join(source, 'package.json'), 'utf8'))
-    for (const dependency of Object.keys(packageJSON.dependencies || {})) await copyRuntimeDependency(dependency, source)
-  }
-  await copyRuntimeDependency('electron-updater')
-  const targetPlatform = desktopTargetPlatform(releaseConfig.buildTarget?.platform || process.platform)
-  const targetArch = desktopTargetArch(releaseConfig.buildTarget?.arch || process.arch)
-  if (targetPlatform === 'darwin' && targetArch === 'ia32') throw new Error('macOS 不支持 ia32 发布架构')
-  const updateURL = resolveDesktopFeedURL(releaseConfig.updateURL, targetPlatform, targetArch)
-  const updateChannel = releaseConfig.updateChannel
-  await writeFile(join(staging, 'update-config.json'), `${JSON.stringify({ url: updateURL, channel: updateChannel }, null, 2)}\n`)
-  const builder = { appId: `com.duckingmind.proxy.app.${info.manifest.id.replaceAll('.', '-')}`, productName: info.manifest.name, electronVersion, artifactName: '${productName}-${version}-${arch}.${ext}', directories: { output: 'release' }, files: ['single-app/**', 'host/**', 'agent/**', 'app/**', 'node_modules/**', 'package.json'], extraResources: [{ from: 'update-config.json', to: 'update-config.json' }], asar: true, mac: { target: ['dmg', 'zip'] }, win: { target: ['nsis'] }, linux: { target: ['AppImage'] } }
-  // setFeedURL alone is insufficient: electron-updater reads app-update.yml
-  // for cache/signing configuration when downloading. Generic publication
-  // makes electron-builder embed it while --publish never keeps uploads local.
-  builder.publish = updateURL ? [{ provider: 'generic', url: updateURL, channel: updateChannel }] : null
-  await writeFile(join(staging, 'electron-builder.json'), JSON.stringify(builder, null, 2) + '\n')
-  await writeFile(join(staging, 'package.json'), JSON.stringify({ name: info.manifest.id.replaceAll('.', '-'), version: info.manifest.version, description: info.manifest.description || info.manifest.name, author: 'Proxy', private: true, type: 'module', main: 'single-app/main.mjs', dependencies: { 'electron-updater': desktopPackage.dependencies?.['electron-updater'] || '^6.6.2' } }, null, 2) + '\n')
-  await writeFile(join(staging, 'desktop-manifest.json'), JSON.stringify({ app_id: info.manifest.id, version: info.manifest.version, name: info.manifest.name }, null, 2) + '\n')
-  console.log(JSON.stringify({ staging, app_id: info.manifest.id, version: info.manifest.version }, null, 2))
-  return { ...info, staging, releaseConfig, targetPlatform, targetArch }
-}
-
-async function desktopPackApp(appDir, output, options = []) {
-  const info = await desktopBuildApp(appDir, options)
-  const outputPath = resolve(output || join(info.root, 'dist-electron', 'release'))
-  await mkdir(outputPath, { recursive: true })
-  const configPath = join(info.staging, 'electron-builder.json')
-  const config = JSON.parse(await readFile(configPath, 'utf8'))
-  config.directories = { ...(config.directories || {}), output: outputPath }
-  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n')
-  const desktopRoot = await resolveDesktopSource()
-  const builderName = process.platform === 'win32' ? 'electron-builder.cmd' : 'electron-builder'
-  const commands = [join(info.root, 'node_modules', '.bin', builderName), join(desktopRoot, 'node_modules', '.bin', builderName)]
-  let builder = null
-  for (const candidate of commands) if (await exists(candidate)) { builder = candidate; break }
-  if (!builder) throw new Error('Electron 打包需要在当前应用依赖中安装 electron-builder。')
-  const targetPlatform = info.targetPlatform
-  const targetArch = info.targetArch
-  if (targetPlatform === 'darwin' && targetArch === 'ia32') throw new Error('macOS 不支持 ia32 发布架构')
-  await run(builder, ['--config', join(info.staging, 'electron-builder.json'), '--projectDir', info.staging, { darwin: '--mac', win32: '--win', linux: '--linux' }[targetPlatform], `--${targetArch}`, '--publish', 'never'], info.staging, process.env).catch((error) => {
-    throw new Error(`Electron 打包失败：${error.message}`)
-  })
-  const release = await writeDesktopReleaseRecord(info, outputPath, info.releaseConfig, targetPlatform, targetArch)
-  console.log(JSON.stringify({ output: outputPath, app_id: info.manifest.id, version: info.manifest.version, release }, null, 2))
-  return { ...info, outputPath, release }
-}
-
-function desktopTargetPlatform(value = process.platform) {
-  if (value === 'darwin') return 'darwin'
-  if (value === 'win32') return 'win32'
-  if (value === 'linux') return 'linux'
-  throw new Error(`不支持的桌面发布平台：${value}`)
-}
-
-function desktopTargetArch(value = process.arch) {
-  if (value === 'x64' || value === 'arm64') return value
-  if (value === 'ia32') return value
-  throw new Error(`不支持的桌面发布架构：${value}`)
-}
-
-function resolveDesktopFeedURL(value, platform, arch) {
-  const raw = String(value || '').trim()
-  if (!raw) return ''
-  const resolved = raw.replaceAll('{platform}', platform).replaceAll('{arch}', arch).replace(/\/+$/, '')
-  let url
-  try { url = new URL(resolved) } catch { throw new Error('发布配置 update.url 必须是 HTTPS 或本机回环 HTTP 更新目录地址') }
-  if (!isAllowedReleaseURL(resolved)) throw new Error('发布配置 update.url 必须是无凭据、无查询参数的 HTTPS 或本机回环 HTTP 更新目录地址')
-  const explicitTarget = /\/(darwin|win32|linux)\/(arm64|x64|ia32)$/.exec(url.pathname)
-  if (explicitTarget && (explicitTarget[1] !== platform || explicitTarget[2] !== arch)) throw new Error(`更新地址目标与 ${platform}/${arch} 不一致，请使用 {platform}/{arch}`)
-  return resolved
-}
-
-/**
- * When a standalone Electron app is built for distribution, emit the same
- * importable record and generic-provider feed as the unified shell. Local
- * builds use an upload placeholder that publish-release.mjs replaces.
- */
-async function writeDesktopReleaseRecord(info, outputPath, releaseConfig, configuredPlatform, configuredArch) {
-  const artifactBase = String(releaseConfig.artifactBaseURL || '').trim().replace(/\/$/, '')
-  if (artifactBase && !artifactBase.startsWith('https://')) throw new Error('发布配置 release.artifactBaseUrl 必须使用 HTTPS')
-  const product = String(releaseConfig.product || info.manifest.id).trim()
-  const channel = releaseConfig.updateChannel
-  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,254}$/.test(product)) throw new Error('发布配置 product 无效')
-  if (!['latest', 'beta'].includes(channel)) throw new Error('发布配置 update.channel 必须是 latest 或 beta')
-  const platform = desktopTargetPlatform(configuredPlatform)
-  const arch = desktopTargetArch(configuredArch)
-  if (platform === 'darwin' && arch === 'ia32') throw new Error('macOS 不支持 ia32 发布架构')
-  const targetExtension = platform === 'darwin' ? '.zip' : platform === 'win32' ? '.exe' : '.appimage'
-  const candidates = []
-  for (const entry of await readdir(outputPath, { withFileTypes: true })) {
-    if (!entry.isFile() || extname(entry.name).toLowerCase() !== targetExtension || !entry.name.includes(info.manifest.version)) continue
-    const archInName = /(?:^|[-_])(x64|arm64|ia32)(?:[-_.]|$)/i.exec(entry.name)?.[1]?.toLowerCase()
-    if (archInName && archInName !== arch) continue
-    const file = join(outputPath, entry.name)
-    const details = await stat(file)
-    if (details.size > 0) candidates.push({ file, name: entry.name, mtimeMs: details.mtimeMs })
-  }
-  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs)
-  const artifact = candidates[0]
-  if (!artifact) throw new Error(`未找到 ${platform}/${arch} 的 ${info.manifest.version} ${targetExtension} 发布产物`)
-  const data = await readFile(artifact.file)
-  const sha512 = createHash('sha512').update(data).digest('base64')
-  const artifactURL = artifactBase
-    ? `${artifactBase}/${encodeURIComponent(basename(artifact.file))}`
-    : `https://upload.invalid/${encodeURIComponent(basename(artifact.file))}`
-  const release = {
-    product,
-    version: info.manifest.version,
-    channel,
-    platform,
-    arch,
-    artifact_url: artifactURL,
-    artifact_name: basename(artifact.file),
-    sha512,
-    size: data.length,
-    release_notes: String(releaseConfig.releaseNotes || '').trim(),
-  }
-  const metadataName = platform === 'darwin' ? `${channel}-mac.yml` : platform === 'linux' ? `${channel}-linux${arch === 'x64' ? '' : `-${arch}`}.yml` : `${channel}.yml`
-  const metadata = `version: ${release.version}\nfiles:\n  - url: ${JSON.stringify(artifactURL)}\n    sha512: ${sha512}\n    size: ${data.length}\npath: ${JSON.stringify(release.artifact_name)}\nsha512: ${sha512}\nreleaseDate: ${new Date().toISOString()}\nreleaseNotes: ${JSON.stringify(release.release_notes)}\n`
-  await writeFile(join(outputPath, metadataName), metadata)
-  const recordPath = join(outputPath, 'desktop-release.json')
-  await writeFile(recordPath, `${JSON.stringify(release, null, 2)}\n`)
-  return { ...release, metadata: metadataName, record: recordPath }
-}
-
 function defaultAgentNamespace(identifier) {
   return identifier.replace(/^app\./, '').replace(/[^a-z0-9]+/g, '_').slice(0, 48) || 'app'
 }
@@ -892,7 +966,7 @@ async function writeProject(root, app) {
   await writeFile(join(root, 'index.html'), '<!doctype html>\n<html lang="zh-CN"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Proxy App</title></head><body><main id="app"></main><script type="module" src="/src/main.ts"></script></body></html>\n')
   await writeFile(join(root, 'src', 'agent-tools.mjs'), [
     '// This module is shared by the application and the package builder.',
-    '// Keep it independent of browser state and expose only JSON-serializable metadata.',
+    '// Keep metadata JSON-serializable and keep each handler beside its registry entry.',
     'export const agentMetadata = Object.freeze({',
     '  namespace: ' + JSON.stringify(namespace) + ", targets: ['web', 'desktop'], contract_version: '1.0.0',",
     '  summary: ' + JSON.stringify(app.name + ' 的应用能力') + ', keywords: [' + JSON.stringify(app.name) + '],',
@@ -900,28 +974,28 @@ async function writeProject(root, app) {
     "  examples: 'agent/examples.json',",
     '})',
     '',
-    'export const capabilities = [{',
-    "  name: 'read_metadata', title: '读取应用元数据', description: '读取应用的标识、名称和版本。',",
-    "  access: 'read', idempotent: true, targets: ['web', 'desktop'],",
-    "  input_schema: { type: 'object', properties: {}, required: [], additionalProperties: false },",
-    "  output_schema: { type: 'object', properties: { appId: { type: 'string' }, version: { type: 'string' }, name: { type: 'string' } }, required: ['appId', 'version', 'name'], additionalProperties: false },",
-    '}]',
-    '',
-    'export function capability(name) {',
-    '  const declaration = capabilities.find(item => item.name === name)',
-    "  if (!declaration) throw new Error('Unknown application capability: ' + name)",
-    '  return declaration',
+    'export function registerAgentTools(registry, app) {',
+    "  if (!registry || typeof registry.register !== 'function') throw new TypeError('agent registry must expose register()')",
+    '  const collectOnly = app === undefined',
+    "  if (!collectOnly && (!app || typeof app !== 'object')) throw new TypeError('app metadata is required')",
+    '  const unregister = registry.register({',
+    "    name: 'read_metadata', title: '读取应用元数据', description: '读取应用的标识、名称和版本。',",
+    "    access: 'read', idempotent: true, targets: ['web', 'desktop'],",
+    "    input_schema: { type: 'object', properties: {}, required: [], additionalProperties: false },",
+    "    output_schema: { type: 'object', properties: { appId: { type: 'string' }, version: { type: 'string' }, name: { type: 'string' } }, required: ['appId', 'version', 'name'], additionalProperties: false },",
+    "  }, collectOnly ? undefined : async () => ({ appId: app.id, version: app.version, name: app.name }))",
+    "  return typeof unregister === 'function' ? [unregister] : []",
     '}',
   ].join('\n') + '\n')
-  await writeFile(join(root, 'src', 'agent-tools.d.mts'), `import type { AgentCapabilityDeclaration, AgentContractMetadata } from '@ducking-mind/proxy-app-sdk'\nexport const agentMetadata: AgentContractMetadata\nexport const capabilities: AgentCapabilityDeclaration[]\nexport function capability(name: string): AgentCapabilityDeclaration\n`)
-  await writeFile(join(root, 'src', 'main.ts'), `import { agent, createAppClient } from '@ducking-mind/proxy-app-sdk'\nimport manifest from '../manifest.json'\nimport { capability } from './agent-tools.mjs'\n\nconst client = createAppClient(manifest.id, { runtime: import.meta.env.DEV ? 'local' : undefined, localDevelopment: import.meta.env.DEV, localAppVersion: manifest.version })\nconst root = document.querySelector<HTMLElement>('#app')\nif (root) root.textContent = manifest.name\n\n// Register the same code-owned declaration used to generate the package contract.\nconst unregisterMetadata = agent.register(capability('read_metadata'), () => ({\n  appId: manifest.id,\n  version: manifest.version,\n  name: manifest.name,\n}))\nagent.setStatus({ state: 'ready' }, { scope: 'app', priority: 1 })\nvoid agent.ready()\nvoid client.platform.capabilities().then(console.log)\n\n// Call unregisterMetadata when the feature or application is unmounted.\nvoid unregisterMetadata\n`)
-  await writeFile(join(root, 'vite.config.ts'), "import { defineConfig } from 'vite'\nimport { createPlatformDevProxy } from '@ducking-mind/proxy-app-sdk/vite'\n\nexport default defineConfig({\n  base: './',\n  server: {\n    host: '127.0.0.1',\n    proxy: createPlatformDevProxy(),\n  },\n})\n")
+  await writeFile(join(root, 'src', 'agent-tools.d.mts'), `import type { AgentCapabilityDeclaration, AgentContractMetadata } from '@ducking-mind/proxy-app-sdk'\nexport const agentMetadata: AgentContractMetadata\nexport function registerAgentTools(\n  registry: { register(declaration: AgentCapabilityDeclaration, handler?: ((input: unknown, context: unknown) => unknown) | undefined): (() => void) | undefined },\n  app?: { id: string; version: string; name: string },\n): Array<() => void>\n`)
+  await writeFile(join(root, 'src', 'main.ts'), `import { agent, createAppClient } from '@ducking-mind/proxy-app-sdk'\nimport manifest from '../manifest.json'\nimport { registerAgentTools } from './agent-tools.mjs'\n\nconst client = createAppClient(manifest.id, {\n  runtime: import.meta.env.DEV ? 'local' : undefined,\n  localDevelopment: import.meta.env.DEV,\n  localAppVersion: manifest.version,\n  appVersion: manifest.version,\n  portalURL: import.meta.env.DEV ? (import.meta.env.VITE_PROXY_PORTAL_URL || 'https://www.duckingmind.com') : window.location.origin,\n})\nconst root = document.querySelector<HTMLElement>('#app')\nif (root) root.textContent = manifest.name\n\nconst disposers = registerAgentTools({\n  register(declaration, handler) {\n    if (typeof handler !== 'function') throw new Error('Agent handler is missing: ' + declaration.name)\n    return agent.register(declaration, handler)\n  },\n}, manifest)\nconst unregister = () => disposers.splice(0).reverse().forEach(dispose => dispose())\nif (import.meta.hot) import.meta.hot.dispose(unregister)\nagent.setStatus({ state: 'ready' }, { scope: 'app', priority: 1 })\nvoid agent.ready()\n`)
+  await writeFile(join(root, 'vite.config.ts'), "import { defineConfig } from 'vite'\nimport { createPlatformDevProxy, createPlatformDevSessionPlugin } from '@ducking-mind/proxy-app-sdk/vite'\n\nexport default defineConfig({\n  base: './',\n  plugins: [createPlatformDevSessionPlugin()],\n  server: {\n    host: '127.0.0.1',\n    proxy: createPlatformDevProxy(),\n  },\n})\n")
   await writeFile(join(root, 'tsconfig.json'), JSON.stringify({ compilerOptions: { target: 'ES2022', module: 'ESNext', moduleResolution: 'Bundler', resolveJsonModule: true, strict: true, skipLibCheck: true, lib: ['ES2022', 'DOM', 'DOM.Iterable'], types: ['vite/client', 'node'], noEmit: true }, include: ['src', 'vite.config.ts'] }, null, 2) + '\n')
-  await writeFile(join(root, 'package.json'), JSON.stringify({ name: app.slug.replaceAll('.', '-'), private: true, type: 'module', scripts: { dev: 'proxy-app dev', 'dev:server': 'vite', typecheck: 'tsc --noEmit', build: 'npm run typecheck && vite build' }, dependencies: { '@ducking-mind/proxy-app-sdk': '^0.1.0' }, devDependencies: { [cliPackage.name]: `^${cliPackage.version}`, '@types/node': '^22.18.0', typescript: '^5.2.2', vite: '^8.2.2' }, engines: { node: '>=22.18' } }, null, 2) + '\n')
-  await writeFile(join(root, 'agent', 'guide.md'), `# ${app.name} 能力说明\n\n这是由 “proxy-app init” 生成的能力指南。外部 Codex 通过主应用 MCP 调用能力，应用本身不实现 Agent。\n\n当前提供 “proxy_${namespace}_read_metadata”，用于确认应用 ID、版本和名称。能力定义在 “src/agent-tools.mjs” 中维护，应用使用同一份定义注册处理器；构建命令自动生成发布契约，无需在 manifest 中重复声明能力。\n`)
-  await writeFile(join(root, 'agent', 'workflow.md'), `# 调用流程\n\n1. 先读取应用状态和本指南。\n2. 调用 “proxy_${namespace}_read_metadata” 确认当前版本。\n3. 新增写能力时，先读取业务 revision，并为每次新操作生成唯一 “idempotency_key”。\n4. Web 和本地 App 共用同一套 manifest；仅在能力确实支持时缩小 “targets”。\n`)
+  await writeFile(join(root, 'package.json'), JSON.stringify({ name: app.slug.replaceAll('.', '-'), private: true, type: 'module', scripts: { dev: 'proxy-app dev', 'dev:server': 'vite', typecheck: 'tsc --noEmit', build: 'npm run typecheck && vite build' }, dependencies: { '@ducking-mind/proxy-app-sdk': '^0.2.0' }, devDependencies: { [cliPackage.name]: `^${cliPackage.version}`, '@types/node': '^22.18.0', typescript: '^5.2.2', vite: '^8.2.2' }, engines: { node: '>=22.18' } }, null, 2) + '\n')
+  await writeFile(join(root, 'agent', 'guide.md'), `# ${app.name} 能力说明\n\n这是由 “proxy-app init” 生成的能力指南。外部 Codex 通过主应用 MCP 调用能力，应用本身不实现 Agent。\n\n当前提供 “proxy_${namespace}_read_metadata”，用于确认应用 ID、版本和名称。能力契约与处理器在 “src/agent-tools.mjs” 的同一条 registry.register 调用中实现；构建执行注册函数并收集发布目录，无需在 manifest 中重复声明能力。\n`)
+  await writeFile(join(root, 'agent', 'workflow.md'), `# 调用流程\n\n1. 先读取应用状态和本指南。\n2. 调用 “proxy_${namespace}_read_metadata” 确认当前版本。\n3. 新增写能力时，先读取业务 revision，并为每次新操作生成唯一 “idempotency_key”。\n4. Web 和私有桌面宿主共用同一套 manifest；仅在能力确实支持时缩小 “targets”。桌面宿主源码和构建流程不属于公开 CLI。\n`)
   await writeFile(join(root, 'agent', 'examples.json'), JSON.stringify([{ capability: 'read_metadata', input: {}, output: { appId: app.slug, version: '0.1.0', name: app.name } }], null, 2) + '\n')
-  await writeFile(join(root, 'README.md'), `# ${app.name}\n\n## 开发\n\n~~~bash\nnpm install\nnpx proxy-app create\nnpm run dev\n~~~\n\n已有平台应用时跳过 create，将 manifest.id 设为平台应用的公开 slug 后直接运行 npm run dev，无需 link 或 repair。启动时会先完成开发者授权与应用检查，再运行开发服务器，不要求手工配置用户 token。底层服务器命令配置在 package.json 的 dev:server 中。\n\n## 能力接入\n\n本项目已生成 Web 与本地 App 两个运行目标，以及一个 “read_metadata” 示例。能力的名称、Schema 和读写属性只在 “src/agent-tools.mjs” 中维护，处理器注册使用同一份定义。源码 manifest 不再声明 Agent 配置；构建会从代码自动生成发布能力目录，请勿手工重复维护。新增能力后同步业务指南和示例，再运行：\n\n~~~bash\nnpx proxy-app validate\nnpx proxy-app pack\n~~~\n\n完整约定见仓库的 [应用开发指南](https://github.com/duckingmind/app/blob/main/docs/APP_DEVELOPMENT.md)。\n`)
+  await writeFile(join(root, 'README.md'), `# ${app.name}\n\n## 开发\n\n~~~bash\nnpm install\nnpx proxy-app create\nnpm run dev\n~~~\n\n已有平台应用时跳过 create，将 manifest.id 设为平台应用的公开 slug 后直接运行 npm run dev，无需 link 或 repair。启动时会先完成开发者授权与应用检查，再运行开发服务器，不要求手工配置用户 token。底层服务器命令配置在 package.json 的 dev:server 中。\n\n## 能力接入\n\n本项目生成 Web 目标，并保留供私有桌面宿主识别的 “desktop” 兼容目标；公开 CLI 只构建和发布 Web 应用。能力契约与处理器必须在 “src/agent-tools.mjs” 的同一条 registry.register 调用中实现；CLI 执行 “registerAgentTools” 并从实际注册路径生成发布目录。不要导出独立能力数组，也不要在源码 manifest 声明 Agent 配置。新增能力后同步业务指南和示例，再运行：\n\n~~~bash\nnpx proxy-app validate\nnpx proxy-app pack\n~~~\n\n完整约定见仓库的 [应用开发指南](https://github.com/duckingmind/app/blob/main/docs/APP_DEVELOPMENT.md)。\n`)
 }
 
 async function replaceIdentifier(root, previous, next) {
@@ -1062,6 +1136,10 @@ function reportPendingOpening(app, version) {
 }
 
 async function uploadApp(appDir, output, options = {}) {
+  const local = await readManifest(resolve(appDir))
+  if (local.manifest.backend?.type === 'container') {
+    throw new Error('当前平台尚未支持云端容器后端构建与部署；容器后端版本不会上传。可先运行 proxy-app dev 本地联调。')
+  }
   const { app } = await resolveManagedApp(appDir)
   const { token, baseURL } = apiSettings()
   const bundleInfo = await packApp(appDir, output, { ...options, allowSourceMaps: false })
@@ -1082,6 +1160,9 @@ async function publishApp(appDir, output, selectedVersion) {
   // Existing uploaded versions are immutable. Only a new/local draft goes
   // through uploadApp's build; no dist is needed to publish a remote version.
   const info = await readManifest(resolve(appDir))
+  if (info.manifest.backend?.type === 'container') {
+    throw new Error('当前平台尚未支持云端容器后端构建与部署；此应用可通过 proxy-app dev 本地联调，不能 publish。')
+  }
   const targetVersion = selectedVersion || info.manifest.version
   let remoteApp = await developerApp(appDir)
   let version = (remoteApp.versions || []).find((item) => item.version === targetVersion)
@@ -1166,8 +1247,6 @@ try {
     else if (command === 'pack') await packApp(appDir, output, { allowSource: options.includes('--source') })
     else if (command === 'upload') await uploadApp(appDir, output, { allowSource: options.includes('--source') })
     else if (command === 'publish') await publishApp(appDir, output, option(options, '--version'))
-    else if (command === 'desktop-build') await desktopBuildApp(appDir, options)
-    else if (command === 'desktop-pack') await desktopPackApp(appDir, output, options)
   }
 } catch (error) {
   console.error(`proxy app: ${error instanceof Error ? error.message : String(error)}`)