@workfly/miniapp-kit 0.1.0

package/index.d.ts

@@ -0,0 +1,68 @@
+// @workfly/miniapp-kit 类型声明（实现为纯 ESM JS，此处手写对外契约）。
+
+export interface ManifestLike {
+  id: string
+  name?: string
+  version: string
+  ui?: { standalone?: { enabled?: boolean; entry?: string; render?: string; layout?: string } }
+  permissions?: (string | { id: string; reason?: string })[]
+  [key: string]: unknown
+}
+
+export interface Report {
+  errors: string[]
+  warnings: string[]
+}
+
+export interface ValidateResult {
+  report: Report
+  manifest: ManifestLike | null
+}
+
+export interface PackResult {
+  bytes: Buffer
+  fileCount: number
+  outName: string
+}
+
+export interface PackOptions {
+  dir: string
+  manifest: { id: string; version: string }
+  outName?: string
+  exclude?: { dirs?: string[]; files?: string[]; paths?: string[] }
+}
+
+export interface ProxyResult {
+  status: number
+  body: Record<string, unknown>
+}
+
+export const MAGIC: string
+export const EXCLUDE_DIRS: Set<string>
+export const EXCLUDE_FILES: Set<string>
+
+export function packDir(opts: PackOptions): PackResult
+export function stampComment(zipBytes: Uint8Array, comment: Uint8Array): Buffer
+export function readMagic(bytes: Uint8Array): { id: string; version: string } | null
+
+export function validateManifest(dir: string, opts?: { forPack?: boolean }): ValidateResult
+
+export function shimSource(): string
+export function injectShimHtml(
+  html: string,
+  configJson: string,
+  opts?: { relaxConnect?: boolean }
+): string
+
+export function handleWfRequest(o: {
+  url: string
+  method?: string
+  data?: unknown
+  header?: Record<string, string>
+  dataType?: string
+}): Promise<ProxyResult>
+export function handleWfRsa(o: {
+  publicKey: string
+  data: string
+  padding?: string
+}): Promise<ProxyResult>

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@workfly/miniapp-kit",
+  "version": "0.1.0",
+  "description": "WorkFly 小程序工具核心：.wfapp.zip 打包（魔数）、manifest 校验、wf dev shim 与网络/RSA 代理——Vite 插件、脚手架、主仓共用的真相源。",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "index.d.ts"
+  ],
+  "dependencies": {
+    "fflate": "^0.8.3"
+  },
+  "keywords": [
+    "workfly",
+    "miniapp",
+    "pack",
+    "wfapp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,5 @@
+// @workfly/miniapp-kit —— WorkFly 小程序工具核心，插件 / 脚手架 / 主仓 miniapp.mjs 共用的真相源。
+export { MAGIC, EXCLUDE_DIRS, EXCLUDE_FILES, packDir, stampComment, readMagic } from './pack.js'
+export { Report, validateManifest } from './validate.js'
+export { shimSource, injectShimHtml } from './shim.js'
+export { handleWfRequest, handleWfRsa } from './proxy.js'

package/src/pack.js

@@ -0,0 +1,100 @@
+// .wfapp.zip 打包 —— 魔数写入的唯一真相源。
+// 产物约定（docs/miniapp-manifest-spec.md §8）：
+//   · 标准 ZIP，复合后缀 .wfapp.zip（过 IM 服务端后缀白名单）
+//   · manifest.json 强制为第一条目（宿主读首个本地文件头即可识别）
+//   · EOCD 注释区写魔数 `WFAPP1\0<id>\0<version>`，读文件末尾 ~64 字节即可零解包判定
+import { readFileSync, statSync, readdirSync } from 'node:fs'
+import { join, relative, basename } from 'node:path'
+import { zipSync } from 'fflate'
+
+export const MAGIC = 'WFAPP1'
+
+// 不进包的工程文件（源码 / 构建配置 / 锁文件 / 上次产物 / standalone 内联工具链）
+export const EXCLUDE_DIRS = new Set(['node_modules', 'src', 'tools', 'miniapp-kit'])
+export const EXCLUDE_FILES = new Set([
+  'vite.config.ts',
+  'vite.config.js',
+  'vite.config.mts',
+  'vite.config.cts',
+  'vite.config.mjs',
+  'tsconfig.json',
+  'tsconfig.node.json',
+  'README.md',
+  'package.json',
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+  '.gitignore',
+  '.npmrc',
+  '.DS_Store'
+])
+
+/** 递归收集目录下需入包的文件 → { 'rel/path': Uint8Array }。exclude.paths 按包内相对路径精确排除（区分根 index.html 与 dist/index.html）。 */
+function collect(dir, base, out, exclude) {
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name)
+    if (statSync(full).isDirectory()) {
+      if (!exclude.dirs.has(name)) collect(full, base, out, exclude)
+      continue
+    }
+    if (exclude.files.has(name) || name.endsWith('.wfapp.zip')) continue
+    const rel = relative(base, full).split(/[\\/]/).join('/')
+    if (exclude.paths.has(rel)) continue
+    out[rel] = new Uint8Array(readFileSync(full))
+  }
+  return out
+}
+
+/** 往 ZIP 末尾的 EOCD 注释区写入魔数：拼接 comment 字节 + 回填 2 字节 comment 长度。 */
+export function stampComment(zipBytes, comment) {
+  const buf = Buffer.from(zipBytes)
+  let eocd = -1
+  for (let i = buf.length - 22; i >= 0; i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) {
+      eocd = i
+      break
+    }
+  }
+  if (eocd < 0) throw new Error('未找到 ZIP EOCD 记录，无法写魔数')
+  const out = Buffer.concat([buf, comment])
+  out.writeUInt16LE(comment.length, eocd + 20) // EOCD 偏移 +20 = comment length 字段
+  return out
+}
+
+/**
+ * 收集工程目录 → zip（manifest.json 第一条目）→ 写魔数。不落盘，返回字节与元信息，由调用者写文件。
+ * @param {{ dir: string, manifest: { id: string, version: string }, outName?: string,
+ *           exclude?: { dirs?: string[], files?: string[], paths?: string[] } }} opts
+ * @returns {{ bytes: Buffer, fileCount: number, outName: string }}
+ */
+export function packDir({ dir, manifest, outName, exclude }) {
+  const ex = {
+    dirs: new Set([...EXCLUDE_DIRS, ...(exclude?.dirs ?? [])]),
+    files: new Set([...EXCLUDE_FILES, ...(exclude?.files ?? [])]),
+    paths: new Set(exclude?.paths ?? [])
+  }
+  const all = collect(dir, dir, {}, ex)
+  if (!all['manifest.json']) throw new Error('包内未找到 manifest.json')
+
+  // 重排为「manifest.json 第一条目」（fflate 按对象插入顺序写条目）
+  const ordered = { 'manifest.json': all['manifest.json'] }
+  for (const k of Object.keys(all)) if (k !== 'manifest.json') ordered[k] = all[k]
+
+  const zip = zipSync(ordered)
+  const magic = Buffer.from(`${MAGIC}\0${manifest.id}\0${manifest.version}`, 'utf8')
+  const bytes = stampComment(zip, magic)
+  return {
+    bytes,
+    fileCount: Object.keys(ordered).length,
+    outName: outName ?? `${basename(dir)}.wfapp.zip`
+  }
+}
+
+/** 反向：从包字节末尾读魔数，零解包识别 { id, version }；非 WorkFly 包返回 null。 */
+export function readMagic(bytes) {
+  const tail = Buffer.from(bytes.subarray(Math.max(0, bytes.length - 256))).toString('binary')
+  const idx = tail.lastIndexOf(MAGIC)
+  if (idx < 0) return null
+  const seg = tail.slice(idx).split('\0')
+  return seg.length >= 3 ? { id: seg[1], version: seg[2] } : null
+}

package/src/proxy.js

@@ -0,0 +1,52 @@
+// dev 网络 / RSA 代理 —— 纯函数，复刻主进程 net.fetch 与 crypto 语义（绕 CORS、支持 pkcs1）。
+// 传输层（http server / connect 中间件）由调用者接；权限门控（net.fetch）也由调用者决定。
+import { createPublicKey, publicEncrypt, constants } from 'node:crypto'
+
+function safeJson(text) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+/**
+ * 代理 wf.request：复刻主进程 net.fetch（method/header/body 透传，JSON 自动序列化与解析）。
+ * @param {{ url: string, method?: string, data?: unknown, header?: Record<string,string>, dataType?: string }} o
+ * @returns {Promise<{ status: number, body: object }>}
+ */
+export async function handleWfRequest(o) {
+  try {
+    const body =
+      o.data == null ? undefined : typeof o.data === 'string' ? o.data : JSON.stringify(o.data)
+    const header = { ...(o.header ?? {}) }
+    if (body && typeof o.data === 'object' && !header['Content-Type'] && !header['content-type'])
+      header['Content-Type'] = 'application/json'
+    const r = await fetch(o.url, { method: o.method ?? 'GET', headers: header, body })
+    const text = await r.text()
+    const data = (o.dataType ?? 'json') === 'json' && text ? safeJson(text) : text
+    return {
+      status: 200,
+      body: { data, statusCode: r.status, header: Object.fromEntries(r.headers.entries()) }
+    }
+  } catch (e) {
+    return { status: 502, body: { error: String(e?.message ?? e) } }
+  }
+}
+
+/**
+ * 代理 wf.bip.rsaEncrypt：Node crypto 支持 pkcs1（浏览器 SubtleCrypto 不支持）。
+ * @param {{ publicKey: string, data: string, padding?: string }} o
+ * @returns {Promise<{ status: number, body: object }>}
+ */
+export async function handleWfRsa(o) {
+  try {
+    const key = createPublicKey(o.publicKey)
+    const padding =
+      o.padding === 'oaep' ? constants.RSA_PKCS1_OAEP_PADDING : constants.RSA_PKCS1_PADDING
+    const out = publicEncrypt({ key, padding }, Buffer.from(o.data, 'utf8'))
+    return { status: 200, body: { data: out.toString('base64') } }
+  } catch (e) {
+    return { status: 400, body: { error: String(e?.message ?? e) } }
+  }
+}

package/src/shim.client.js

@@ -0,0 +1,314 @@
+// WorkFly 小程序调试宿主 · 浏览器 wf shim。
+// 由 `node scripts/miniapp.mjs dev <dir>` 注入，在普通浏览器里模拟宿主注入的全局 wf，
+// 用 dev server 代理网络 / RSA（绕 CORS、复刻主进程代理语义），按 manifest 权限门控，
+// 并把每次 wf.* 调用记到右下角调试面板。真相源接口见 src/shared/wf-api.ts。
+//
+// ⚠ 仅供本地开发：加密存储不做真加密、UI 为简化实现，行为对齐而非像素级一致。
+;(function () {
+  const cfg = window.__WF_CONFIG__ || {}
+  const APP_ID = cfg.id || 'dev.app'
+  const PERMS = new Set(cfg.permissions || [])
+  const PROXY = cfg.proxyBase || ''
+  const NS = `wf:${APP_ID}:`
+
+  // ── 调试面板（右下角，记录每次调用 + 权限判定）────────────────────────────────
+  const panel = document.createElement('div')
+  panel.style.cssText =
+    'position:fixed;right:12px;bottom:12px;width:320px;max-height:46vh;z-index:2147483647;' +
+    'background:#11131a;color:#cdd3e0;font:11px/1.5 ui-monospace,Menlo,monospace;' +
+    'border:1px solid #2a2f3c;border-radius:10px;overflow:hidden;box-shadow:0 8px 28px rgba(0,0,0,.4)'
+  panel.innerHTML =
+    '<div style="padding:7px 10px;background:#171a23;border-bottom:1px solid #2a2f3c;' +
+    'display:flex;justify-content:space-between;align-items:center">' +
+    '<b style="color:#7fb0ff">wf 调试宿主</b>' +
+    '<span style="color:#6b7280">' +
+    APP_ID +
+    '</span></div><div id="__wf_log" style="padding:6px 8px;overflow:auto;max-height:40vh"></div>'
+  const ready = () => document.body && document.body.appendChild(panel)
+  if (document.body) ready()
+  else document.addEventListener('DOMContentLoaded', ready)
+
+  function logCall(name, ok, detail) {
+    const el = document.getElementById('__wf_log')
+    if (!el) return
+    const row = document.createElement('div')
+    row.style.cssText =
+      'padding:3px 0;border-bottom:1px dashed #20242f;white-space:pre-wrap;word-break:break-all'
+    const tag = ok ? '<span style="color:#5fd29a">✓</span>' : '<span style="color:#ff8d8d">✗</span>'
+    row.innerHTML = `${tag} <b style="color:#cbd5e1">${name}</b> <span style="color:#7c8598">${detail || ''}</span>`
+    el.appendChild(row)
+    el.scrollTop = el.scrollHeight
+  }
+
+  function need(perm, name) {
+    if (PERMS.has(perm)) return
+    const msg = `权限未授权：'${perm}'（manifest.permissions 未声明）`
+    logCall(name, false, msg)
+    throw new Error(`${name}:fail ${msg}`)
+  }
+
+  // wx 双模：始终返回 Promise；若传了 success/fail/complete 也回调（errMsg 对齐 wx）。
+  function dual(name, opts, run, gate) {
+    const o = opts || {}
+    const p = (async () => {
+      if (gate) gate()
+      const r = await run(o)
+      logCall(name, true, summarize(r))
+      return r
+    })()
+    p.then(
+      (r) => {
+        if (o.success) o.success(Object.assign({}, r, { errMsg: `${name}:ok` }))
+        if (o.complete) o.complete({ errMsg: `${name}:ok` })
+      },
+      (e) => {
+        const errMsg = String(e && e.message ? e.message : e)
+        const m = errMsg.startsWith(`${name}:fail`) ? errMsg : `${name}:fail ${errMsg}`
+        if (!errMsg.startsWith(`${name}:fail`)) logCall(name, false, errMsg)
+        if (o.fail) o.fail({ errMsg: m })
+        if (o.complete) o.complete({ errMsg: m })
+      }
+    )
+    return p
+  }
+
+  function summarize(r) {
+    if (r === undefined) return 'ok'
+    try {
+      const s = JSON.stringify(r)
+      return s.length > 80 ? s.slice(0, 80) + '…' : s
+    } catch {
+      return 'ok'
+    }
+  }
+
+  // ── 存储（localStorage，按 app id 命名空间；encrypt 仅 base64，非真加密）──────────
+  function enc(v, encrypt) {
+    const s = JSON.stringify(v)
+    return encrypt ? 'b64:' + btoa(unescape(encodeURIComponent(s))) : s
+  }
+  function dec(raw) {
+    if (raw == null) return undefined
+    const s = raw.startsWith('b64:') ? decodeURIComponent(escape(atob(raw.slice(4)))) : raw
+    return JSON.parse(s)
+  }
+  function setSync(key, data, encrypt) {
+    if (encrypt) {
+      need('vault', 'setStorageSync')
+      console.warn('[wf dev] encrypt 存储在调试宿主里仅 base64，非真加密')
+    }
+    localStorage.setItem(NS + key, enc(data, encrypt))
+  }
+  function getSync(key, encrypt) {
+    if (encrypt) need('vault', 'getStorageSync')
+    return dec(localStorage.getItem(NS + key))
+  }
+  function storageKeys() {
+    return Object.keys(localStorage)
+      .filter((k) => k.startsWith(NS))
+      .map((k) => k.slice(NS.length))
+  }
+  function storageInfo() {
+    const keys = storageKeys()
+    const size = keys.reduce((n, k) => n + (localStorage.getItem(NS + k) || '').length, 0)
+    return { keys, currentSize: Math.ceil(size / 1024), limitSize: 5120 }
+  }
+
+  // ── UI（DOM 简化渲染）────────────────────────────────────────────────────────
+  function overlay(html, autoMs) {
+    const box = document.createElement('div')
+    box.style.cssText =
+      'position:fixed;inset:0;z-index:2147483646;display:flex;align-items:center;justify-content:center;' +
+      'background:rgba(0,0,0,.28);font-family:system-ui,sans-serif'
+    box.innerHTML = `<div style="background:#fff;color:#1d1d1f;border-radius:12px;padding:18px 20px;min-width:200px;max-width:80vw;box-shadow:0 10px 40px rgba(0,0,0,.3)">${html}</div>`
+    document.body.appendChild(box)
+    if (autoMs) setTimeout(() => box.remove(), autoMs)
+    return box
+  }
+  let loadingBox = null
+
+  // ── 网络 / RSA：走 dev server 代理（Node 侧 fetch / crypto，绕 CORS、支持 pkcs1）──
+  async function proxy(path, payload) {
+    const res = await fetch(PROXY + path, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload)
+    })
+    const out = await res.json()
+    if (!res.ok) throw new Error(out.error || `proxy ${res.status}`)
+    return out
+  }
+
+  const wf = {
+    // —— 网络 ——
+    request: (o) =>
+      dual(
+        'request',
+        o,
+        (a) => proxy('/__wf/request', a),
+        () => need('net.fetch', 'request')
+      ),
+
+    // —— 存储（异步） ——
+    setStorage: (o) =>
+      dual('setStorage', o, (a) => {
+        setSync(a.key, a.data, a.encrypt)
+      }),
+    getStorage: (o) => dual('getStorage', o, (a) => ({ data: getSync(a.key, a.encrypt) })),
+    removeStorage: (o) =>
+      dual('removeStorage', o, (a) => {
+        localStorage.removeItem(NS + a.key)
+      }),
+    clearStorage: (o) =>
+      dual('clearStorage', o, () => {
+        storageKeys().forEach((k) => localStorage.removeItem(NS + k))
+      }),
+    getStorageInfo: (o) => dual('getStorageInfo', o, () => storageInfo()),
+
+    // —— 存储（同步） ——
+    setStorageSync: (key, data, encrypt) => {
+      setSync(key, data, encrypt)
+      logCall('setStorageSync', true, key)
+    },
+    getStorageSync: (key, encrypt) => {
+      const v = getSync(key, encrypt)
+      logCall('getStorageSync', true, key)
+      return v
+    },
+    removeStorageSync: (key) => {
+      localStorage.removeItem(NS + key)
+      logCall('removeStorageSync', true, key)
+    },
+    clearStorageSync: () => {
+      storageKeys().forEach((k) => localStorage.removeItem(NS + k))
+      logCall('clearStorageSync', true, '')
+    },
+    getStorageInfoSync: () => {
+      const i = storageInfo()
+      logCall('getStorageInfoSync', true, summarize(i))
+      return i
+    },
+
+    // —— 剪贴板 ——
+    setClipboardData: (o) =>
+      dual(
+        'setClipboardData',
+        o,
+        (a) => navigator.clipboard.writeText(a.data),
+        () => need('clipboard', 'setClipboardData')
+      ),
+    getClipboardData: (o) =>
+      dual(
+        'getClipboardData',
+        o,
+        async () => ({ data: await navigator.clipboard.readText() }),
+        () => need('clipboard', 'getClipboardData')
+      ),
+
+    // —— UI ——
+    showToast: (o) =>
+      dual('showToast', o, (a) => {
+        overlay(`<div style="text-align:center">${a.title || ''}</div>`, a.duration || 1500)
+      }),
+    hideToast: (o) => dual('hideToast', o, () => {}),
+    showLoading: (o) =>
+      dual('showLoading', o, (a) => {
+        if (loadingBox) loadingBox.remove()
+        loadingBox = overlay(`<div style="text-align:center">${a.title || '加载中…'}</div>`)
+      }),
+    hideLoading: (o) =>
+      dual('hideLoading', o, () => {
+        if (loadingBox) loadingBox.remove()
+        loadingBox = null
+      }),
+    showModal: (o) =>
+      dual(
+        'showModal',
+        o,
+        (a) =>
+          new Promise((resolve) => {
+            const showCancel = a.showCancel !== false
+            const box = overlay(
+              `<div style="font-weight:600;margin-bottom:6px">${a.title || ''}</div>` +
+                `<div style="color:#555;margin-bottom:14px">${a.content || ''}</div>` +
+                `<div style="display:flex;gap:8px;justify-content:flex-end">` +
+                (showCancel
+                  ? `<button id="__c" style="padding:6px 14px">${a.cancelText || '取消'}</button>`
+                  : '') +
+                `<button id="__o" style="padding:6px 14px;background:#3461ff;color:#fff;border:0;border-radius:6px">${a.confirmText || '确定'}</button></div>`
+            )
+            box.querySelector('#__o').onclick = () => {
+              box.remove()
+              resolve({ confirm: true, cancel: false })
+            }
+            const c = box.querySelector('#__c')
+            if (c)
+              c.onclick = () => {
+                box.remove()
+                resolve({ confirm: false, cancel: true })
+              }
+          })
+      ),
+    showActionSheet: (o) =>
+      dual(
+        'showActionSheet',
+        o,
+        (a) =>
+          new Promise((resolve, reject) => {
+            const items = (a.itemList || [])
+              .map(
+                (t, i) =>
+                  `<button data-i="${i}" style="display:block;width:100%;padding:8px;margin:4px 0;text-align:left">${t}</button>`
+              )
+              .join('')
+            const box = overlay(
+              items +
+                `<button id="__x" style="display:block;width:100%;padding:8px;margin-top:8px;color:#888">取消</button>`
+            )
+            box.querySelectorAll('button[data-i]').forEach((b) => {
+              b.onclick = () => {
+                box.remove()
+                resolve({ tapIndex: Number(b.getAttribute('data-i')) })
+              }
+            })
+            box.querySelector('#__x').onclick = () => {
+              box.remove()
+              reject(new Error('cancel'))
+            }
+          })
+      ),
+    previewImage: (o) =>
+      dual('previewImage', o, (a) => {
+        const cur = a.current || (a.urls || [])[0]
+        overlay(
+          `<img src="${cur}" style="max-width:78vw;max-height:78vh;display:block"/>`
+        ).onclick = (e) => e.currentTarget.remove()
+      }),
+
+    // —— 启动 / 系统 ——
+    getLaunchOptionsSync: () => ({
+      path: '',
+      query: cfg.query || {},
+      scene: (cfg.query && cfg.query.scene) || 'panel'
+    }),
+    getEnterOptionsSync: () => ({
+      path: '',
+      query: cfg.query || {},
+      scene: (cfg.query && cfg.query.scene) || 'panel'
+    }),
+    getSystemInfoSync: () => ({
+      platform: 'workfly',
+      theme: matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light',
+      version: cfg.version || 'dev',
+      language: navigator.language || 'zh-CN'
+    }),
+
+    // —— BIP 扩展 ——
+    bip: {
+      rsaEncrypt: (o) => dual('bip.rsaEncrypt', o, (a) => proxy('/__wf/rsa', a))
+    }
+  }
+
+  window.wf = wf
+  logCall('shim ready', true, `permissions: ${[...PERMS].join(', ') || '(无)'}`)
+})()

package/src/shim.js

@@ -0,0 +1,30 @@
+// dev 调试宿主的 wf shim 注入 —— 把浏览器端 shim（shim.client.js）与启动配置插进 HTML。
+// 生产由 src/preload/miniapp.ts 的 contextBridge 注入 window.wf；dev 无 preload，故注入同名 shim。
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const CLIENT = fileURLToPath(new URL('./shim.client.js', import.meta.url))
+
+/** 浏览器端 wf shim 源码文本（dev server / vite-plugin 以 /__wf/shim.js 提供）。 */
+export function shimSource() {
+  return readFileSync(CLIENT, 'utf8')
+}
+
+/**
+ * 把 wf shim + 注入配置插进 <head>，shim 是同步脚本，先于 deferred module 跑。
+ * @param {string} html
+ * @param {string} configJson  JSON.stringify 后的 __WF_CONFIG__
+ * @param {{ relaxConnect?: boolean }} [opts]  dev 下放宽 CSP connect-src，让同源 /__wf/* fetch 通过
+ */
+export function injectShimHtml(html, configJson, opts = {}) {
+  let out = html
+  if (opts.relaxConnect) out = relaxConnectSrc(out)
+  const inject = `<script>window.__WF_CONFIG__=${configJson}</script><script src="/__wf/shim.js"></script>`
+  if (out.includes('</head>')) return out.replace('</head>', `${inject}</head>`)
+  return inject + out
+}
+
+/** 把 CSP meta 里的 connect-src 放宽（仅 dev：沙盒 connect-src 'none' 会挡掉 shim 的同源代理 fetch）。 */
+function relaxConnectSrc(html) {
+  return html.replace(/connect-src[^;"']*/gi, "connect-src 'self' http: https: ws: wss:")
+}

package/src/validate.js

@@ -0,0 +1,188 @@
+// manifest.json 校验 —— 真相源：src/shared/app.ts，释义见 docs/miniapp-manifest-spec.md。
+// 结构化返回 { report, manifest }，不 console.log / process.exit；打印与中断由调用者决定。
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SCOPES = ['private', 'team', 'org_market']
+const CONTAINS = ['ui', 'skill', 'mcp', 'kb', 'workflow', 'backend']
+const LAUNCHERS = [
+  'miniprogram_panel',
+  'chat_command',
+  'chat_intent',
+  'spotlight',
+  'deeplink',
+  'scheduler'
+]
+const RENDERS = ['webview', 'sandbox', 'bundle']
+const LAYOUTS = ['full', 'split']
+const PERMISSIONS = ['net.fetch', 'vault', 'clipboard']
+const MATCHES = ['curl', 'url', 'json']
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+
+/** 收集校验结果；errors 阻断打包，warnings 仅提示。 */
+export class Report {
+  errors = []
+  warnings = []
+  err(msg) {
+    this.errors.push(msg)
+  }
+  warn(msg) {
+    this.warnings.push(msg)
+  }
+}
+
+function isObj(v) {
+  return v != null && typeof v === 'object' && !Array.isArray(v)
+}
+
+/** 校验 match ∈ 'curl'|'url'|'json'|{regex}。 */
+function checkMatch(m, where, r) {
+  if (typeof m === 'string') {
+    if (!MATCHES.includes(m))
+      r.err(`${where}.match 取值 '${m}' 非法，应为 ${MATCHES.join('/')} 或 { regex }`)
+  } else if (isObj(m)) {
+    if (typeof m.regex !== 'string') r.err(`${where}.match 对象形态须为 { regex: string }`)
+  } else {
+    r.err(`${where}.match 缺失或类型错误`)
+  }
+}
+
+/** 校验 launch ∈ { deeplink: string }。 */
+function checkLaunch(l, where, r) {
+  if (!isObj(l) || typeof l.deeplink !== 'string')
+    r.err(`${where}.launch 须为 { deeplink: string }`)
+}
+
+/**
+ * 校验某目录下的 manifest.json。
+ * @param {string} dir 工程目录
+ * @param {{ forPack?: boolean }} [opts] forPack：打包前校验，缺失的打包入口记 error 而非 warn
+ * @returns {{ report: Report, manifest: object | null }}
+ */
+export function validateManifest(dir, opts = {}) {
+  const { forPack = false } = opts
+  const r = new Report()
+  const manifestPath = join(dir, 'manifest.json')
+  if (!existsSync(manifestPath)) {
+    r.err('缺少 manifest.json')
+    return { report: r, manifest: null }
+  }
+  let m
+  try {
+    m = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch (e) {
+    r.err(`manifest.json 不是合法 JSON：${e.message}`)
+    return { report: r, manifest: null }
+  }
+
+  // 身份与版本族
+  if (typeof m.id !== 'string' || !m.id.trim()) r.err('id 必填且为非空字符串')
+  if (typeof m.name !== 'string' || !m.name.trim()) r.err('name 必填且为非空字符串')
+  if (typeof m.version !== 'string' || !SEMVER.test(m.version)) r.err('version 必填且须为 SemVer')
+  if (m.manifest !== undefined && typeof m.manifest !== 'number') r.err('manifest 须为数字')
+  if (m.wfSdk !== undefined && !SEMVER.test(String(m.wfSdk))) r.err('wfSdk 须为 SemVer')
+  if (m.minClient !== undefined && !SEMVER.test(String(m.minClient))) r.err('minClient 须为 SemVer')
+  if (m.manifest === undefined) r.warn('未声明 manifest（清单格式版本），将按 1 处理；建议显式写明')
+  if (m.wfSdk === undefined) r.warn('未声明 wfSdk（面向的 SDK 版本），宿主不做兼容判定；建议写明')
+
+  // scope / contains
+  if (!SCOPES.includes(m.scope)) r.err(`scope 必填且 ∈ ${SCOPES.join('/')}`)
+  if (!Array.isArray(m.contains) || !m.contains.length) {
+    r.err('contains 必填且为非空数组')
+  } else {
+    for (const c of m.contains) if (!CONTAINS.includes(c)) r.err(`contains 含非法值 '${c}'`)
+    if (!m.contains.includes('ui')) r.warn("第三方小程序通常至少 contains 含 'ui'")
+  }
+
+  // ui.standalone
+  const s = m.ui?.standalone
+  if (!isObj(s)) {
+    r.err('ui.standalone 必填')
+  } else {
+    if (s.enabled !== true) r.err('ui.standalone.enabled 须为 true')
+    const render = s.render ?? 'webview'
+    if (!RENDERS.includes(render)) r.err(`ui.standalone.render ∈ ${RENDERS.join('/')}`)
+    if (s.layout !== undefined && !LAYOUTS.includes(s.layout))
+      r.err(`ui.standalone.layout ∈ ${LAYOUTS.join('/')}`)
+    if (typeof s.entry !== 'string' || !s.entry.trim()) {
+      r.err('ui.standalone.entry 必填')
+    } else if (render === 'webview') {
+      if (!/^https?:\/\//.test(s.entry)) r.warn('webview 形态 entry 应为 http(s) URL')
+      if (!isObj(m.session)) r.warn('webview 形态通常需配 session（cookie 持久化）')
+    } else if (!existsSync(join(dir, s.entry))) {
+      // sandbox / bundle：entry 是包内相对路径
+      const msg = `ui.standalone.entry 指向的文件不存在：${s.entry}${render === 'bundle' ? '（bundle 形态需先 build）' : ''}`
+      forPack ? r.err(msg) : r.warn(msg)
+    }
+  }
+
+  // launchers
+  if (!Array.isArray(m.launchers) || !m.launchers.length) {
+    r.err('launchers 必填且为非空数组')
+  } else {
+    for (const l of m.launchers) if (!LAUNCHERS.includes(l)) r.err(`launchers 含非法值 '${l}'`)
+  }
+
+  // permissions（兼容旧 string[] 形态）
+  if (m.permissions !== undefined) {
+    if (!Array.isArray(m.permissions)) {
+      r.err('permissions 须为数组')
+    } else {
+      for (const [i, p] of m.permissions.entries()) {
+        if (typeof p === 'string') {
+          if (!PERMISSIONS.includes(p)) r.err(`permissions[${i}] 非法能力 '${p}'`)
+          r.warn(`permissions[${i}] 用了旧字符串形态，建议改为 { id, reason }`)
+        } else if (isObj(p)) {
+          if (!PERMISSIONS.includes(p.id)) r.err(`permissions[${i}].id 非法能力 '${p.id}'`)
+          if (typeof p.reason !== 'string' || !p.reason.trim())
+            r.warn(`permissions[${i}].reason 缺失，安装授权弹窗将无说明`)
+        } else {
+          r.err(`permissions[${i}] 须为 { id, reason } 或能力字符串`)
+        }
+      }
+    }
+  }
+
+  // contributes
+  const ct = m.contributes
+  if (ct !== undefined) {
+    if (!isObj(ct)) {
+      r.err('contributes 须为对象')
+    } else {
+      for (const [i, h] of (ct.clipboardHints ?? []).entries()) {
+        checkMatch(h?.match, `contributes.clipboardHints[${i}]`, r)
+        if (typeof h?.label !== 'string') r.err(`contributes.clipboardHints[${i}].label 须为字符串`)
+        checkLaunch(h?.launch, `contributes.clipboardHints[${i}]`, r)
+      }
+      for (const [i, h] of (ct.contentMatchers ?? []).entries()) {
+        if (h?.surface !== 'im') r.err(`contributes.contentMatchers[${i}].surface 当前仅支持 'im'`)
+        checkMatch(h?.match, `contributes.contentMatchers[${i}]`, r)
+        if (typeof h?.label !== 'string')
+          r.err(`contributes.contentMatchers[${i}].label 须为字符串`)
+        checkLaunch(h?.launch, `contributes.contentMatchers[${i}]`, r)
+      }
+      for (const [i, c] of (ct.cardRenderers ?? []).entries()) {
+        if (typeof c?.kind !== 'string') r.err(`contributes.cardRenderers[${i}].kind 须为字符串`)
+        if (c?.mode !== 'sandbox')
+          r.err(`contributes.cardRenderers[${i}].mode 三方仅支持 'sandbox'`)
+        if (typeof c?.entry !== 'string') {
+          r.err(`contributes.cardRenderers[${i}].entry 须为字符串`)
+        } else if (!existsSync(join(dir, c.entry))) {
+          const msg = `contributes.cardRenderers[${i}].entry 文件不存在：${c.entry}`
+          forPack ? r.err(msg) : r.warn(msg)
+        }
+      }
+    }
+  }
+
+  // icon / iconPlaceholder
+  if (typeof m.icon === 'string' && !existsSync(join(dir, m.icon)))
+    r.warn(`icon 指向的文件不存在：${m.icon}，将回退 iconPlaceholder`)
+  if (m.iconPlaceholder !== undefined) {
+    const ip = m.iconPlaceholder
+    if (!isObj(ip) || typeof ip.initial !== 'string' || typeof ip.color !== 'string')
+      r.err('iconPlaceholder 须为 { initial, color }')
+  }
+
+  return { report: r, manifest: m }
+}