@open-dy/vibecoding-cli 0.0.1-beta.1 → 0.0.1-beta.10

package/README.md

@@ -16,7 +16,9 @@ vibecoding verify --target taro --auto-start --full
 - `taro`：Taro 主应用、Server，以及项目中存在时的 OpenCard。
 - `opencard`：独立 OpenCard 项目。
 
-主要命令：`dev`、`build`、`lint`、`verify`、`pack`、`turbo`、`init-mysql-db`，以及 `validate feed-card|routes|empty|opencard-structure`。
+主要命令：`dev`、`build`、`lint`、`verify`、`pack`、`docs`、`turbo`、`init-mysql-db`，以及 `validate feed-card|routes|empty|opencard-structure`。
+
+完整 SDK API 文档随 SDK npm 包和 Skill 交付，优先按 `${SKILL_DIR}/sdk-docs/versions.json` 核对版本，再查对应端的 `llms.txt`。`vibecoding docs --target taro`（OpenCard 使用 `--target opencard`，可指定 `--cwd <工程目录>`）只读定位实际安装的 SDK，输出 JSON：依赖键、版本、包位置、包内文档索引及公开类型路径。`ready` 表示包内存在文档索引；`docs-missing` 表示已安装的包没有内置索引，继续查 Skill 文档，版本不一致或信息不足时按 `exports` / `types` 查公开入口。业务导入使用 `imports`，npm 别名以依赖键为前缀，不能换成包的 `name`。包尚不可用时最多等待 `--timeout` 秒（默认 90），超时返回 `SDK_NOT_INSTALLED`，应检查工程安装结果。命令不会安装、重建 SDK 或启动服务。
 
 Turbo 构建应通过 CLI 包装命令执行，例如 `vibecoding turbo --target opencard run build:raw`。CLI 会读取项目的 `turbo.json`，合并版本化默认配置，并将结果写入项目内的 `.vibecoding/cache/turbo.json`；封闭域状态和 `config/card-routing.json` 也会参与构建环境与缓存输入。`--root-turbo-json` 由 CLI 管理，不能由业务命令覆盖；需要传递其他 Turbo 参数时，放在 `--` 后面。
 
@@ -30,6 +32,10 @@ Schema 统一使用 `custom-card-schema.json`。`config/card-routing.json` 的 `
 
 服务包仅包含 `dist`、生成的 `Dockerfile`、`package.json`、`run.sh` 以及可选的 `sql`、`scripts`。生成 Dockerfile 时按原脚本规则为每条 `COPY package.json` 追加存在的目录，项目源文件不改写。构建/zip 失败保留退出码，临时目录在失败时也会清理。
 
+`verify` 的静态阶段在构建通过后，保留主工程 `server.zip` 的文件数预检（阈值 `1000`，超限失败）。标准 CLI 模板使用打包共用的清单；自定义 `scripts/pack.sh` 使用其 `REQUIRED_SERVER_INCLUDES` / `OPTIONAL_SERVER_INCLUDES`。脚本缺失或清单无法解析时，warning 并保守统计整个 `server/`；缺少目录或必需文件时明确报告未覆盖范围。检查范围不扩大到封闭域服务，不生成 ZIP，也不验证压缩包大小。静态检查不等待 dev 的安装成功日志；自动启动预览后仍等待安装与端口就绪。
+
+浏览器验收优先使用 `agent-browser-real`，不可用时使用 `agent-browser`。浏览器命令只在验收阶段查找；CDP / 浏览器基础设施失败会报告 `infra_browser` 和 `runtime_status=unverified`，继续以非零退出码结束，页面与业务错误仍按实际错误判定。
+
 CLI 支持用 `ARTIFACTS_DIR` 指定专用产物目录；为避免误删，拒绝项目、用户主目录、临时目录根及其上级目录。模板的 `pack.sh` 不加载 `.env.dev` 或 `.bashrc`，未传入该变量时默认写入 `/tmp/microapp_artifacts`。
 
 Taro 构建统一由 CLI 编排，兴趣卡只在业务域规则上扩展：
@@ -44,4 +50,4 @@ CLI 对外命令和校验入口的 JSDoc 使用 `@desc`、`@params`、`@return`
 
 ## 准出测试
 
-在仓库根目录运行 `node packages/scripts/run-release-contracts.mjs`，或在本包目录运行 `pnpm test:release`。该命令构建并验证 SDK、CLI 和隔离消费者；终端进度、JUnit 报告与 push CI 配置见 [packages/TESTING.md](../TESTING.md)。
+在仓库根目录运行 `node packages/release/verification/run-release-contracts.mjs`，或在本包目录运行 `pnpm test:release`。该命令构建并验证 SDK、CLI 和隔离消费者；终端进度、JUnit 报告与 push CI 配置见 [packages/TESTING.md](../TESTING.md)。

package/assets/schemas/custom-card-schema.json

@@ -31,7 +31,7 @@
     },
     "CardBackgroundUrl": {
       "type": "string",
-      "description": "必须调用图片生成工具获取真实的图片 URL，自动生成符合预期的背景图片。此图片将作为 Feed 流场景的全屏背景底图，画面内容必须延伸至画面边缘，完全铺满整个画布。严禁出现手机设备外框、样机模型、任何形式的边框，严禁将内容仅集中在中间而导致四周留白或黑边。图片宽高比严格为`9:16`竖图。必须完整保留原始 URL 及全部 query 参数，禁止截断、改写或丢弃任何参数（如 x-expires）。",
+      "description": "必须调用图片生成工具获取真实的图片 URL，自动生成符合预期的背景图片。此图片将作为 Feed 流场景的全屏背景底图，画面内容必须延伸至画面边缘，完全铺满整个画布。严禁出现手机设备外框、样机模型、任何形式的边框，严禁将内容仅集中在中间而导致四周留白或黑边。图片宽高比严格为`9:16`竖图。",
       "pattern": "^https://"
     },
     "Button": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-dy/vibecoding-cli",
-  "version": "0.0.1-beta.1",
+  "version": "0.0.1-beta.10",
   "description": "Command orchestration, validation and packaging for Douyin vibecoding Taro and OpenCard projects.",
   "type": "module",
   "bin": {
@@ -24,24 +24,27 @@
     "bin",
     "src",
     "assets",
-    "README.md"
+    "README.md",
+    "release-provenance.json"
   ],
   "scripts": {
     "ci:check": "pnpm run build && pnpm run test",
-    "build": "node ./scripts/verify-package.mjs",
-    "test": "node ../scripts/run-package-tests.mjs cli",
+    "build": "node ./scripts/check-package-files.mjs",
+    "test": "node ../testing/run-package-tests.mjs cli",
     "pack:local": "pnpm pack --pack-destination ./artifacts",
     "pack:ppe": "node ./scripts/pack-ppe.mjs",
-    "test:release": "node ../scripts/run-release-contracts.mjs",
-    "publish:bnpm:ppe": "node ../scripts/ppe-release/cli.mjs vibecoding-cli",
-    "publish:bnpm:ppe:dry-run": "node ../scripts/ppe-release/cli.mjs vibecoding-cli --dry-run"
+    "test:release": "node ../release/verification/run-release-contracts.mjs",
+    "publish:bnpm:ppe": "node ../release/ppe-release/cli.mjs vibecoding-cli",
+    "publish:bnpm:ppe:dry-run": "node ../release/ppe-release/cli.mjs vibecoding-cli --dry-run",
+    "publish:npm:beta": "node ../release/npm-beta-release/cli.ts vibecoding-cli",
+    "publish:npm:beta:dry-run": "node ../release/npm-beta-release/cli.ts vibecoding-cli --dry-run"
   },
   "dependencies": {
     "ajv": "^8.18.0"
   },
   "peerDependencies": {
-    "@open-dy/vibecoding-sdk-taro": "0.0.1-beta.1",
-    "@open-dy/vibecoding-sdk-opencard": "0.0.1-beta.1"
+    "@open-dy/vibecoding-sdk-taro": "0.0.1-beta.9",
+    "@open-dy/vibecoding-sdk-opencard": "0.0.1-beta.8"
   },
   "peerDependenciesMeta": {
     "@open-dy/vibecoding-sdk-taro": {
@@ -54,5 +57,10 @@
   "engines": {
     "node": ">=18"
   },
-  "license": "UNLICENSED"
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta",
+    "access": "public"
+  }
 }

package/release-provenance.json

@@ -0,0 +1,15 @@
+{
+  "schema": 1,
+  "producer": "vibecoding-cli",
+  "packageName": "@open-dy/vibecoding-cli",
+  "version": "0.0.1-beta.10",
+  "source": {
+    "digest": "sha256-07a273825a0a8e9dc91058343a3e733044e46875e3315aeabdc1611d73e27e66",
+    "files": 83
+  },
+  "payload": "sha256-0c32f577ee31c8dd4bd2081c6b5b92ed2186a4c40ce5f26b4ff7a49a96940a09",
+  "toolchain": {
+    "node": "v22.22.3",
+    "packageManager": null
+  }
+}

package/src/adapters/interest-card/opencard/dev-watch.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
 import { startRoutingPreview } from '../../../preview/watch-card-routing.mjs';
+import { loadPreviewRunner } from '../../../preview/preview-runner.mjs';
 import fs from 'node:fs';
-import { createRequire } from 'node:module';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 const __dirname = path.join(process.env.VIBECODING_OPENCARD_ROOT || process.cwd(), 'scripts');
 const root = path.resolve(__dirname, '..');
@@ -17,7 +17,6 @@ const META_PATH = '/opt/gem/ai_coding_app/.meta/ai_coding_app_meta.json';
 const READY_TIMEOUT_MS = 5 * 60 * 1000;
 const READY_POLL_MS = 500;
 const DEFAULT_PORT = 10087;
-const AI_CODING_BUILTIN_PACKAGES_DIR = process.env.AI_CODING_BUILTIN_PACKAGES_DIR;
 
 const children = [];
 let shuttingDown = false;
@@ -29,22 +28,6 @@ function log(message) {
     console.log(`[opencard-dev-watch] ${message}`);
 }
 
-async function loadPreviewRunner() {
-    const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
-    const offlineRunner = manifest.devDependencies?.['@byted/microapp-preview-runner']?.startsWith('file:patches/') === true;
-    if (offlineRunner || !AI_CODING_BUILTIN_PACKAGES_DIR) {
-        return import(pathToFileURL(createRequire(path.join(root, 'package.json')).resolve('@byted/microapp-preview-runner')).href);
-    }
-
-    const requireFromTarget = createRequire(
-        path.join(path.resolve(AI_CODING_BUILTIN_PACKAGES_DIR), 'package.json'),
-    );
-    const runnerEntry = requireFromTarget.resolve('@byted/microapp-preview-runner');
-
-    log(`using preview runner from ${AI_CODING_BUILTIN_PACKAGES_DIR}`);
-    return import(pathToFileURL(runnerEntry).href);
-}
-
 function readMeta() {
     try {
         return JSON.parse(fs.readFileSync(META_PATH, 'utf-8'));
@@ -151,7 +134,7 @@ for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
 }
 
 async function startCycle(env, signal) {
-    const { startRspuckPreview } = await loadPreviewRunner();
+    const { startRspuckPreview } = await loadPreviewRunner(root);
 
     fs.rmSync(path.join(root, TT_OUTPUT_DIR), { recursive: true, force: true });
     fs.rmSync(RSPUCK_OUTPUT_DIR, { recursive: true, force: true });

package/src/adapters/interest-card/opencard/validate-widget-shell.mjs

@@ -14,7 +14,6 @@ const __dirname = path.join(process.env.VIBECODING_OPENCARD_ROOT || process.cwd(
 const ROOT = path.resolve(__dirname, '..');
 const SRC = path.join(ROOT, 'src');
 const PAGE_ENTRY = path.join(SRC, 'pages/index/index.tsx');
-const require = createRequire(path.join(ROOT, 'scripts', 'package.json'));
 
 const SHELL_CLASS = 'widget-root';
 const REQUIRED_RADIUS_PX = 12;
@@ -332,7 +331,8 @@ function jsxName(el) {
   return '';
 }
 
-function loadBabel() {
+function loadBabel(root = ROOT) {
+  const require = createRequire(path.join(root, 'scripts', 'package.json'));
   try {
     const parser = require('@babel/parser');
     const traverseMod = require('@babel/traverse');
@@ -384,8 +384,8 @@ function collectPageRootClassSetsRegex(source) {
   return [{ type: 'View', classes }];
 }
 
-export function collectPageRootClassSets(source) {
-  const babel = loadBabel();
+export function collectPageRootClassSets(source, root = ROOT) {
+  const babel = loadBabel(root);
   if (!babel) return collectPageRootClassSetsRegex(source);
 
   let ast;
@@ -626,9 +626,10 @@ export function lintWidgetShell({
   pageSource,
   pageFile = 'src/pages/index/index.tsx',
   rules,
+  root = ROOT,
 }) {
   const findings = [];
-  const roots = collectPageRootClassSets(pageSource);
+  const roots = collectPageRootClassSets(pageSource, root);
   if (roots.length === 0) {
     findings.push(
       finding(
@@ -698,9 +699,9 @@ function parseInlineCssFiles(files) {
   }).flat();
 }
 
-export function lintWidgetShellFromSources({ pageSource, cssFiles }) {
+export function lintWidgetShellFromSources({ pageSource, cssFiles, root = ROOT }) {
   const rules = parseInlineCssFiles(cssFiles);
-  return lintWidgetShell({ pageSource, rules });
+  return lintWidgetShell({ pageSource, rules, root });
 }
 
 function assertSelfTest() {

package/src/build/opencard-environment.mjs

@@ -17,8 +17,9 @@ function findRoutingPath(cardRoot) {
 
 /** Read the host configuration; missing routing retains the legacy open-domain default. */
 export function resolveCardRoutingPath(context) {
-  return context.taroRoot
-    ? path.join(context.taroRoot, 'config/card-routing.json')
+  const hostRoot = context.taroRoot ?? (context.target === 'taro' ? context.root : undefined)
+  return hostRoot
+    ? path.join(hostRoot, 'config/card-routing.json')
     : findRoutingPath(context.root)
 }
 
@@ -37,8 +38,14 @@ export function readCardRouting(context) {
   } catch (error) {
     throw new Error(`${file} must contain valid JSON: ${error.message}`)
   }
-  if (!['closed', 'open', 'none', undefined].includes(routing?.cardData?.serviceDomain)) {
-    throw new Error(`${file} cardData.serviceDomain must be none, open, or closed`)
+  const serviceDomain = routing?.cardData?.serviceDomain
+  const guidance = '请核对卡片接口所属服务及现有需求后补齐或修正该字段，并重新执行 verify。\n' +
+    '证据不明确或存在冲突时请询问用户；不要通过默认填入 open 或 closed 来绕过校验。'
+  if (serviceDomain === undefined) {
+    throw new Error(`${file} 缺少 cardData.serviceDomain。\n${guidance}`)
+  }
+  if (!['closed', 'open', 'none'].includes(serviceDomain)) {
+    throw new Error(`${file} cardData.serviceDomain must be none, open, or closed; got ${JSON.stringify(serviceDomain)}。\n${guidance}`)
   }
   return routing
 }

package/src/cli.mjs

@@ -10,6 +10,7 @@ import { runPack } from './commands/pack.mjs'
 import { runValidate } from './commands/validate.mjs'
 import { runVerify } from './commands/verify.mjs'
 import { runTurbo } from './commands/turbo.mjs'
+import { runDocs } from './commands/docs.mjs'
 
 const HELP = `Usage: vibecoding <command> [options]
 
@@ -22,6 +23,7 @@ Commands:
   validate <name>        Run feed-card, routes, empty or opencard-structure
   init-mysql-db          Initialize the Taro server database
   pack                   Build deployment archives
+  docs                   Locate the selected project's installed SDK reference
   turbo <args...>        Run Turbo with CLI defaults and project config
 
 Required:
@@ -38,7 +40,7 @@ Options:
   --static-only          Verify static phase only
   --ports-only           Verify listening ports only
   --auto-start           Start dev once when verify finds missing ports
-  --timeout <seconds>    Dev startup timeout (default: 90)
+  --timeout <seconds>    Dev startup / docs dependency wait timeout (default: 90)
   --frontend-url <url>   Override the primary runtime-check URL`
 
 function assertNoExtra(positionals, count, command) {
@@ -95,6 +97,7 @@ export async function main(argv = process.argv.slice(2)) {
     case 'lint': assertNoExtra(positionals, 1, command); return runLint(context, options)
     case 'verify': assertNoExtra(positionals, 1, command); return runVerify(context, options)
     case 'pack': assertNoExtra(positionals, 1, command); return runPack(context, options)
+    case 'docs': assertNoExtra(positionals, 1, command); return runDocs(context, options)
     case 'init-mysql-db': assertNoExtra(positionals, 1, command); return runDatabaseInit(context)
     case 'validate':
       assertNoExtra(positionals, 2, command)

package/src/commands/build.mjs

@@ -1,4 +1,4 @@
-import { openCardBuildEnvironment } from '../build/opencard-environment.mjs'
+import { openCardBuildEnvironment, readCardRouting } from '../build/opencard-environment.mjs'
 import { mkdirSync } from 'node:fs'
 import path from 'node:path'
 import { readEnvFile } from '../core/environment.mjs'
@@ -33,6 +33,7 @@ export async function buildTaroFrontend(context, type, options = {}) {
 export async function buildOpenCard(context, options = {}) {
   const root = context.target === 'opencard' ? context.root : context.opencardRoot
   if (!root) return
+  const cardEnvironment = openCardBuildEnvironment(context)
   const args = ['build', '--type', 'tt']
   if (options.mode) args.push('--mode', options.mode)
   if (options.watch) args.push('--watch')
@@ -41,7 +42,7 @@ export async function buildOpenCard(context, options = {}) {
     env: taroEnvironment(root, {
       ...(options.watch ? { TT_OUTPUT_ROOT: 'dist-tt' } : {}),
       ...options.env,
-      ...openCardBuildEnvironment(context),
+      ...cardEnvironment,
     }),
     label: 'opencard tt build',
   })
@@ -78,6 +79,7 @@ export function buildClosedDomainServer(context, options = {}) {
  * exposes only the stable `pack.sh` entrypoint.
  */
 export async function buildPackInputs(context, options = {}) {
+  readCardRouting(context)
   const tasks = [
     { name: 'taro-tt', run: () => buildTaroFrontend(context, 'tt', { ...options, mode: 'prod' }) },
     { name: 'server', run: () => buildServer(context, { ...options, production: true }) },
@@ -92,6 +94,7 @@ export async function buildPackInputs(context, options = {}) {
 }
 
 export async function runBuild(context, options = {}) {
+  readCardRouting(context)
   const buildOptions = {
     ...options,
     env: resolveBuildEnvironment(context.root, options.env),

package/src/commands/dev.mjs

@@ -232,8 +232,7 @@ export async function runDev(context, options = {}) {
         env,
         onExit: handlePreviewExit,
       })
-      children.push({ child: preview.child, name: 'opencard watch' })
-      runtimes.push(preview.runtime)
+      runtimes.push(preview)
     } else {
       const baseline = env.HAS_CALLED_DATABASE_INIT_TOOL
       await runDatabaseInit(context, { env })
@@ -268,8 +267,7 @@ export async function runDev(context, options = {}) {
       )
       const startManagedPreview = async (previewOptions) => {
         const preview = await startPreview(previewOptions)
-        children.push({ child: preview.child, name: previewOptions.cardMode ? 'opencard watch' : 'taro watch' })
-        runtimes.push(preview.runtime)
+        runtimes.push(preview)
       }
       const previewTasks = [
         startManagedPreview({ root: context.root, env, onExit: handlePreviewExit }),

package/src/commands/docs.mjs

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { CliError } from '../core/errors.mjs'
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+const isFile = file => existsSync(file) && statSync(file).isFile()
+
+function targets(value) {
+  if (typeof value === 'string') return [value]
+  if (!value || typeof value !== 'object') return []
+  return Object.values(value).flatMap(targets)
+}
+
+// Limit lookup to project/ancestor node_modules, including pnpm hoisting.
+// NODE_PATH and global packages are not evidence of this project's install.
+function installedPackage(root, dependency) {
+  const require = createRequire(path.join(root, 'package.json'))
+  for (const directory of require.resolve.paths(dependency) ?? []) {
+    const relative = path.relative(path.dirname(directory), root)
+    if (path.basename(directory) !== 'node_modules' || relative === '..'
+      || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) continue
+    const manifest = path.join(directory, dependency, 'package.json')
+    if (isFile(manifest)) return realpathSync(path.dirname(manifest))
+  }
+  return null
+}
+
+function packageFile(root, target) {
+  if (!target.startsWith('./') || target.includes('*')) return null
+  const file = path.resolve(root, target)
+  const relative = path.relative(root, file)
+  return !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) && isFile(file) ? file : null
+}
+
+/** Resolve the selected project's declared SDK and its installed documentation.
+ * This also handles npm aliases and pnpm symlinks without a package.json export.
+ */
+export function resolveSdkDocumentation(context) {
+  const manifest = JSON.parse(readFileSync(path.join(context.root, 'package.json'), 'utf8'))
+  const dependencies = { ...manifest.devDependencies, ...manifest.dependencies }
+  const suffix = context.target === 'opencard' ? 'opencard' : 'taro'
+  const expected = `@open-dy/vibecoding-sdk-${suffix}`
+  const aliasPattern = new RegExp(`^npm:@[^/]+/vibecoding-sdk-${suffix}(?:@|$)`)
+  const dependency = Object.hasOwn(dependencies, expected) ? expected
+    : Object.keys(dependencies).find(key => aliasPattern.test(dependencies[key]))
+      ?? (Object.hasOwn(dependencies, '@open-dy/vibecoding-sdk') ? '@open-dy/vibecoding-sdk'
+        : Object.keys(dependencies).find(key => /^npm:@[^/]+\/vibecoding-sdk(?:@|$)/.test(dependencies[key])))
+  if (!dependency) throw new CliError(`[SDK_NOT_DECLARED] ${expected} is not declared in ${context.root}/package.json`)
+  const root = installedPackage(context.root, dependency)
+  if (!root) return { status: 'not-installed', dependency, projectRoot: context.root }
+  const sdk = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'))
+  const exports = sdk.exports && typeof sdk.exports === 'object' && !Array.isArray(sdk.exports)
+    && Object.keys(sdk.exports).some(key => key.startsWith('.')) ? sdk.exports : { '.': sdk.exports }
+  const docTargets = targets(exports['./reference/llms.txt'] ?? exports['./reference/*'])
+    .map(target => target.replaceAll('*', 'llms.txt'))
+  const index = [...docTargets, './dist/reference/llms.txt'].map(target => packageFile(root, target)).find(Boolean) ?? null
+  const types = Object.entries(exports).flatMap(([key, value]) => {
+    if (key.includes('*')) return []
+    const candidates = targets(value).filter(target => /\.d\.[cm]?ts$/.test(target))
+    // Root-level `types` is also used by older packages with a JS root export.
+    if (key === '.' && sdk.types) candidates.push(sdk.types.startsWith('./') ? sdk.types : `./${sdk.types}`)
+    const file = candidates.map(target => packageFile(root, target)).find(Boolean)
+    return file ? [{ importPath: key === '.' ? dependency : `${dependency}/${key.slice(2)}`, file }] : []
+  })
+  return { status: index ? 'ready' : 'docs-missing', dependency, name: sdk.name, version: sdk.version,
+    projectRoot: context.root, packageRoot: root, index, exports: sdk.exports ?? null,
+    imports: Object.keys(exports).filter(key => exports[key] != null || (key === '.' && sdk.exports === undefined))
+      .map(key => key === '.' ? dependency : `${dependency}/${key.slice(2)}`), types }
+}
+
+/** Wait only for this project's SDK package; never install or start services. */
+export async function waitForSdkDocumentation(context, { timeoutSeconds = 90, sleepFn = sleep } = {}) {
+  const deadline = Date.now() + timeoutSeconds * 1000
+  while (true) {
+    const result = resolveSdkDocumentation(context)
+    if (result.status !== 'not-installed') return result
+    if (Date.now() >= deadline) {
+      throw new CliError(`[SDK_NOT_INSTALLED] ${result.dependency} was not available after ${timeoutSeconds}s in ${context.root}. ` +
+        'Check the current project dependency installation result; do not search other projects or rebuild the SDK for documentation.')
+    }
+    await sleepFn(Math.min(500, Math.max(0, deadline - Date.now())))
+  }
+}
+
+/** Print machine-readable SDK documentation paths for Agent lookup. */
+export async function runDocs(context, options = {}) {
+  const result = await waitForSdkDocumentation(context, options)
+  console.log(JSON.stringify(result, null, 2))
+  return result
+}

package/src/commands/pack.mjs

@@ -16,6 +16,8 @@ import { spawn } from 'node:child_process'
 import { CliError } from '../core/errors.mjs'
 import { resolveProjectContext } from '../core/context.mjs'
 import { buildOpenCard, buildPackInputs } from './build.mjs'
+import { readCardRouting } from '../build/opencard-environment.mjs'
+import { REQUIRED_SERVER_INCLUDES, OPTIONAL_SERVER_INCLUDES } from '../validators/server-artifact.mjs'
 
 const DEFAULT_ARTIFACTS = '/tmp/microapp_artifacts'
 
@@ -71,13 +73,12 @@ async function zipDirectory(directory, output, { removeExisting = true } = {}) {
 
 function createServerStage(server, stage) {
   if (!isDirectory(server)) throw new CliError(`Server pack input is missing: ${server}`)
-  const required = ['dist', 'Dockerfile', 'package.json', 'run.sh']
-  for (const name of required) {
+  for (const name of REQUIRED_SERVER_INCLUDES) {
     if (!existsSync(path.join(server, name))) {
       throw new CliError(`Server pack input is missing: ${path.join(server, name)}`)
     }
   }
-  for (const name of ['dist', 'package.json', 'run.sh', 'sql', 'scripts']) {
+  for (const name of [...REQUIRED_SERVER_INCLUDES, ...OPTIONAL_SERVER_INCLUDES].filter(name => name !== 'Dockerfile')) {
     const source = path.join(server, name)
     if (existsSync(source)) cpSync(source, path.join(stage, name), { recursive: true })
   }
@@ -135,6 +136,8 @@ export async function packTaroArtifacts(context, artifacts) {
 }
 
 export async function runPack(context, options = {}) {
+  // Validate before cleaning old artifacts, including projects with a legacy build:pack hook.
+  readCardRouting(context)
   const artifacts = resolveArtifactsDirectory(context.root,
     options.artifactsDir ?? process.env.ARTIFACTS_DIR ?? DEFAULT_ARTIFACTS)
   if (context.target === 'opencard') {

package/src/commands/verify.mjs

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process'
-import { existsSync, readFileSync } from 'node:fs'
+import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { CliError } from '../core/errors.mjs'
@@ -8,9 +8,11 @@ import { waitForPorts } from '../core/ports.mjs'
 import { runCaptured, runTasks } from '../core/runner.mjs'
 import { packageUses, validateDependencies } from '../validators/dependencies.mjs'
 import { validateFeedCard } from '../validators/feed-card.mjs'
+import { readCardRouting } from '../build/opencard-environment.mjs'
 import { runBuild } from './build.mjs'
 import { runDatabaseInit } from './db.mjs'
 import { runLint } from './lint.mjs'
+import { validateServerArtifactFileCount } from '../validators/server-artifact.mjs'
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 const devLauncher = fileURLToPath(new URL('../../bin/vibecoding', import.meta.url))
@@ -41,6 +43,11 @@ async function runStatic(context) {
     )
   }
   await runTasks(tasks, { label: 'static verification' })
+  if (context.target === 'taro') {
+    validateServerArtifactFileCount(context.serverRoot ?? path.join(context.root, 'server'), {
+      packScriptPath: path.join(context.root, 'scripts/pack.sh'),
+    })
+  }
 }
 
 export function startDevDetached(context, spawnProcess = spawn) {
@@ -521,6 +528,23 @@ export function isIgnorableOpenCardConsoleFinding(value, options) {
     /Failed to load resource: the server responded with a status of 404/i.test(text)
 }
 
+export function resolveAgentBrowserCommand(env = process.env) {
+  for (const name of ['agent-browser-real', 'agent-browser']) {
+    for (const directory of (env.PATH || '').split(path.delimiter)) {
+      const executable = path.resolve(directory || '.', name)
+      try {
+        accessSync(executable, constants.X_OK)
+        if (statSync(executable).isFile()) return executable
+      } catch {}
+    }
+  }
+  return 'agent-browser'
+}
+
+export function isBrowserInfrastructureError(error) {
+  return /All CDP discovery methods failed|(?:CDP|DevTools|WebSocket).*(?:fail|refus|timeout|timed out|closed|unavailable)|Protocol error.*(?:Browser|Page|Target)\.|(?:failed|unable) to (?:launch|start) (?:the )?(?:browser|chrome|chromium)|spawn .*agent-browser.*ENOENT/i.test(textOf(error?.message || error))
+}
+
 async function browserCheck(root, url, label) {
   if (packageUses(root, '@open-dy/threejs')) {
     console.log(`[vibecoding:verify] ${label}: skipping browser runtime check for @open-dy/threejs`)
@@ -528,7 +552,19 @@ async function browserCheck(root, url, label) {
   }
   parseHttpUrl(url, label)
   const session = process.env.AGENT_BROWSER_SESSION || `vibecoding-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
-  const call = (args, allowFailure = false) => runCaptured('agent-browser', ['--session', session, ...args], { allowFailure })
+  const command = resolveAgentBrowserCommand()
+  const call = async (args, allowFailure = false) => {
+    try {
+      return await runCaptured(command, ['--session', session, ...args], {
+        allowFailure, timeoutMs: args[0] === 'close' ? 5000 : 120_000, label: `agent-browser ${args[0]}`,
+      })
+    } catch (error) {
+      if (isBrowserInfrastructureError(error)) {
+        throw new CliError(`infra_browser: Browser infrastructure unavailable; runtime_status=unverified for ${url}. ${error.message}`)
+      }
+      throw error
+    }
+  }
   try {
     await call(['network', 'requests'], true)
     await call(['open', url])
@@ -564,7 +600,9 @@ async function browserCheck(root, url, label) {
       throw new CliError(`${label} runtime check found ${findings.length} issue(s):\n${findings.map((item) => `- ${flatten(item)}`).join('\n')}`)
     }
   } finally {
-    await call(['close'], true)
+    await call(['close'], true).catch((error) => {
+      console.log(`[vibecoding:verify] browser cleanup failed: ${error.message}`)
+    })
   }
 }
 
@@ -578,12 +616,13 @@ export async function runVerify(context, options = {}) {
   if (options.staticOnly && options.portsOnly) {
     throw new CliError('--static-only cannot be combined with --ports-only')
   }
+  // Fail before waiting for dev/install or starting build/runtime checks, for both targets.
+  readCardRouting(context)
   const full = Boolean(options.full || options.autoStart || options.staticOnly ||
     (context.target === 'taro' && process.env.npm_lifecycle_event === 'verify'))
   options = { timeoutSeconds: 90, ...options, full }
   const frontendUrl = resolveFrontendUrl(context, options)
   parseHttpUrl(frontendUrl, 'frontend')
-  if (full) await waitForDevInstall(context, options.timeoutSeconds)
   if (full || options.staticOnly) await runStatic(context)
   if (options.staticOnly) return
 

package/src/core/runner.mjs

@@ -45,6 +45,8 @@ export function runCaptured(command, args = [], options = {}) {
       env: { ...process.env, ...options.env },
       stdio: ['ignore', 'pipe', 'pipe'],
       shell: false,
+      signal: options.timeoutMs > 0 ? AbortSignal.timeout(options.timeoutMs) : undefined,
+      killSignal: 'SIGKILL',
     })
     let stdout = ''
     let stderr = ''
@@ -52,7 +54,15 @@ export function runCaptured(command, args = [], options = {}) {
     child.stderr.setEncoding('utf8')
     child.stdout.on('data', (chunk) => { stdout += chunk })
     child.stderr.on('data', (chunk) => { stderr += chunk })
-    child.on('error', (error) => reject(new CliError(error.message)))
+    child.on('error', (error) => {
+      if (error.code === 'ABORT_ERR') {
+        child.stdout.destroy()
+        child.stderr.destroy()
+        reject(new CliError(`${options.label ?? path.basename(command)} timed out after ${options.timeoutMs}ms\n${stderr || stdout}`))
+      } else {
+        reject(new CliError(error.message))
+      }
+    })
     child.on('exit', (code) => {
       if (code === 0 || options.allowFailure) {
         resolve({ code: code ?? 1, stdout, stderr })

package/src/preview/preview-runner.mjs

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { CliError } from '../core/errors.mjs'
+
+/**
+ * @desc 加载工程明确声明的预览运行时；未声明时优先使用沙箱内置运行时。
+ * @params {string} projectRoot 当前工程根目录。
+ * @params {object} env 运行环境，可通过 AI_CODING_BUILTIN_PACKAGES_DIR 指定内置包目录。
+ * @return {Promise<object>} 已加载的 Preview Runner 模块；所选包缺失时抛出错误。
+ * @example await loadPreviewRunner(projectRoot, process.env)
+ */
+export async function loadPreviewRunner(projectRoot, env = process.env) {
+  let declaredRunner = false
+  try {
+    const manifest = JSON.parse(readFileSync(path.join(projectRoot, 'package.json'), 'utf8'))
+    const specifier = manifest.devDependencies?.['@byted/microapp-preview-runner']
+      ?? manifest.dependencies?.['@byted/microapp-preview-runner']
+    declaredRunner = typeof specifier === 'string' && specifier.trim().length > 0
+  } catch {}
+  const builtin = !declaredRunner && env.AI_CODING_BUILTIN_PACKAGES_DIR
+  const base = path.resolve(builtin || projectRoot)
+  const requireFromTarget = createRequire(path.join(base, 'package.json'))
+  let entry
+  try {
+    entry = requireFromTarget.resolve('@byted/microapp-preview-runner')
+  } catch {
+    throw new CliError(
+      `Cannot resolve @byted/microapp-preview-runner from ${base}. `
+      + (declaredRunner ? 'Run pnpm install in the project.'
+        : 'Set AI_CODING_BUILTIN_PACKAGES_DIR or install it in the project.'),
+    )
+  }
+  console.log(`[preview-runner] using ${builtin ? 'builtin' : 'project'} package: ${entry}`)
+  return import(pathToFileURL(entry).href)
+}

package/src/preview/start-preview.mjs

@@ -1,9 +1,8 @@
 import { startRoutingPreview } from './watch-card-routing.mjs'
 import { spawn } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
-import { createRequire } from 'node:module'
 import path from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { loadPreviewRunner } from './preview-runner.mjs'
 import { CliError } from '../core/errors.mjs'
 import { attachLabeledOutput } from '../core/process-output.mjs'
 import { resolveSdkTaroEntry } from '../core/runner.mjs'
@@ -12,30 +11,12 @@ import { withServiceLogLabel } from '../core/service-log-context.mjs'
 const META_PATH = '/opt/gem/ai_coding_app/.meta/ai_coding_app_meta.json'
 const READY_TIMEOUT_MS = 5 * 60 * 1000
 
+export { loadPreviewRunner } from './preview-runner.mjs'
+
 export function conversationId() {
   try { return JSON.parse(readFileSync(META_PATH, 'utf8')).conversation_id ?? '' } catch { return '' }
 }
 
-export async function loadPreviewRunner(projectRoot, env = process.env) {
-  // Only PPE's explicit offline dependency overrides the platform runtime.
-  let offlineRunner = false
-  try {
-    const manifest = JSON.parse(readFileSync(path.join(projectRoot, 'package.json'), 'utf8'))
-    offlineRunner = manifest.devDependencies?.['@byted/microapp-preview-runner']?.startsWith('file:patches/') === true
-  } catch {}
-  const base = offlineRunner ? projectRoot : env.AI_CODING_BUILTIN_PACKAGES_DIR || projectRoot
-  const requireFromTarget = createRequire(path.join(path.resolve(base), 'package.json'))
-  let entry
-  try {
-    entry = requireFromTarget.resolve('@byted/microapp-preview-runner')
-  } catch {
-    throw new CliError(
-      'Cannot resolve @byted/microapp-preview-runner. Set AI_CODING_BUILTIN_PACKAGES_DIR or install it in the project.',
-    )
-  }
-  return import(pathToFileURL(entry).href)
-}
-
 export function waitForFile(file, label, { signal, timeoutMs = READY_TIMEOUT_MS, pollMs = 500 } = {}) {
   return new Promise((resolve, reject) => {
     const deadline = Date.now() + timeoutMs
@@ -59,9 +40,8 @@ export function waitForFile(file, label, { signal, timeoutMs = READY_TIMEOUT_MS,
 }
 
 export function resolveOpenCardPreviewUrl(root, env = process.env, id = conversationId()) {
-  const configured = env.OPEN_CARD_PREVIEW_URL?.trim()
-  if (configured) return configured
   if (!existsSync(path.join(root, 'opencard/package.json'))) return undefined
+  // Match the card service's port; the runner consumes this single target URL.
   const localCardPreview = `http://127.0.0.1:${resolvePreviewPort(env.OPENCARD_PORT, 10087)}`
   return id
     ? `${localCardPreview}/api/apps/open_ai_coding_chat_server/aio_fe/${id}/card_preview`

package/src/validators/server-artifact.mjs

@@ -0,0 +1,69 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs'
+import path from 'node:path'
+import { CliError } from '../core/errors.mjs'
+
+// Shared with pack: count only paths copied into each server archive.
+export const REQUIRED_SERVER_INCLUDES = ['dist', 'Dockerfile', 'package.json', 'run.sh']
+export const OPTIONAL_SERVER_INCLUDES = ['sql', 'scripts']
+const MAX_FILE_COUNT = 1000
+const CLI_PACK_WRAPPER = [
+  'set -Eeuo pipefail',
+  'ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"',
+  'cd "$ROOT"',
+  `CLI_ROOT="$(node -p 'require("node:path").dirname(require.resolve("@open-dy/vibecoding-cli/package.json"))')"`,
+  'exec node "$CLI_ROOT/src/scripts/pack.mjs" "$ROOT"',
+].join('\n')
+
+function readPackIncludes(packScriptPath) {
+  const script = readFileSync(packScriptPath, 'utf8')
+  const normalized = script.split(/\r?\n/).map(line => line.trim())
+    .filter(line => line && !line.startsWith('#')).join('\n')
+  if (normalized === CLI_PACK_WRAPPER) {
+    return { required: REQUIRED_SERVER_INCLUDES, optional: OPTIONAL_SERVER_INCLUDES }
+  }
+  const parse = name => {
+    const match = script.match(new RegExp(`^\\s*${name}=\\(([^)]*)\\)`, 'm'))
+    if (!match) throw new Error(`scripts/pack.sh does not define ${name}`)
+    return (match[1].match(/(?:"[^"]*"|'[^']*'|\S)+/g) || [])
+      .map(item => item.replace(/^['"]|['"]$/g, ''))
+  }
+  return { required: parse('REQUIRED_SERVER_INCLUDES'), optional: parse('OPTIONAL_SERVER_INCLUDES') }
+}
+
+function countFiles(target) {
+  if (!lstatSync(target).isDirectory()) return 1
+  return readdirSync(target).reduce((total, name) => total + countFiles(path.join(target, name)), 0)
+}
+
+export function validateServerArtifactFileCount(serverRoot, { packScriptPath } = {}) {
+  if (!existsSync(serverRoot)) {
+    console.warn(`[verify] static:server-artifact-file-count skipped missing server directory: ${serverRoot}.`)
+    return { skipped: true }
+  }
+  let includes = { required: REQUIRED_SERVER_INCLUDES, optional: OPTIONAL_SERVER_INCLUDES }
+  let countSource = 'the CLI server archive includes'
+  if (packScriptPath) {
+    try {
+      includes = readPackIncludes(packScriptPath)
+      countSource = `${packScriptPath} server.zip includes: ${[...includes.required, ...includes.optional].join(', ')}`
+    } catch (error) {
+      includes = null
+      countSource = 'the entire server directory'
+      console.warn(`[verify] static:server-artifact-file-count could not parse ${packScriptPath}; conservatively counting ${serverRoot}: ${error.message}.`)
+    }
+  }
+  const missing = includes?.required.filter(name => !existsSync(path.join(serverRoot, name))) ?? []
+  const count = includes
+    ? [...includes.required, ...includes.optional]
+      .filter(name => existsSync(path.join(serverRoot, name)))
+      .reduce((total, name) => total + countFiles(path.join(serverRoot, name)), 0)
+    : countFiles(serverRoot)
+  if (count > MAX_FILE_COUNT) {
+    throw new CliError(`Packed server artifact ${serverRoot} would contain ${count} files, exceeding the limit ${MAX_FILE_COUNT}. This count follows ${countSource}. Reduce files included by pack before submission.`)
+  }
+  if (missing.length) {
+    console.warn(`[verify] static:server-artifact-file-count skipped missing required paths in ${serverRoot}: ${missing.join(', ')}.`)
+  }
+  console.log(`[verify] static:server-artifact-file-count → ${missing.length ? 'PARTIAL' : 'OK'} (${count}/${MAX_FILE_COUNT}, ${serverRoot}).`)
+  return { skipped: false, count, missing }
+}

package/src/validators/widget-shell.mjs

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import path from 'node:path'
+import { lintWidgetShellFromSources } from '../adapters/interest-card/opencard/validate-widget-shell.mjs'
 
 function listCssFiles(directory, files = []) {
   if (!existsSync(directory)) return files
@@ -14,94 +15,41 @@ function listCssFiles(directory, files = []) {
   return files
 }
 
-function rootRule(source) {
-  const match = /\.widget-root\s*\{([\s\S]*?)\}/m.exec(source)
-  return match?.[1] ?? ''
-}
-
-function hasDeclaration(css, property, value) {
-  const expression = new RegExp(
-    `${property.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*:\\s*${value}`,
-    'i',
-  )
-  return expression.test(css)
-}
-
-function formatFinding(file, line, column, message) {
-  return `${file}:${line}:${column} ${message}`
-}
-
 export function validateWidgetShell(context) {
   const root = context.target === 'opencard' ? context.root : context.opencardRoot
   if (!root) return { skipped: true, findings: [] }
 
   const pageFile = path.join(root, 'src/pages/index/index.tsx')
-  const sourceDirectory = path.join(root, 'src')
-  const findings = []
+  let findings
   if (!existsSync(pageFile)) {
-    findings.push({
-      file: 'src/pages/index/index.tsx',
-      line: 1,
-      column: 1,
+    findings = [{
+      file: 'src/pages/index/index.tsx', line: 1, column: 1,
       message: '缺少 OpenCard 页面入口。',
-    })
+    }]
   } else {
-    const page = readFileSync(pageFile, 'utf8')
-    if (!/<View\b[^>]*className\s*=\s*(?:"[^"]*\bwidget-root\b[^"]*"|'[^']*\bwidget-root\b[^']*')/m.test(page)) {
-      findings.push({
-        file: 'src/pages/index/index.tsx',
-        line: 1,
-        column: 1,
-        message: '页面根 View 必须使用 widget-root 作为固定 widget 底板。',
+    // Reuse the master checker: inspect returned roots and merged CSS, including variables.
+    const cssFiles = listCssFiles(path.join(root, 'src'))
+      .map((file) => ({
+        filename: path.relative(root, file).replace(/\\/g, '/'),
+        source: readFileSync(file, 'utf8'),
+      }))
+      .sort((a, b) => {
+        if (a.filename === 'src/app.css') return -1
+        if (b.filename === 'src/app.css') return 1
+        return a.filename.localeCompare(b.filename)
       })
-    }
-  }
-
-  const cssFiles = listCssFiles(sourceDirectory)
-  const css = cssFiles.map((file) => readFileSync(file, 'utf8')).join('\n')
-  const shell = rootRule(css)
-  if (!shell) {
-    findings.push({
-      file: 'src/pages/index/index.css',
-      line: 1,
-      column: 1,
-      message: '缺少 .widget-root CSS。',
+    findings = lintWidgetShellFromSources({
+      root,
+      pageSource: readFileSync(pageFile, 'utf8'),
+      cssFiles,
     })
-  } else {
-    const checks = [
-      [/box-sizing\s*:\s*border-box/i, '底板必须使用 box-sizing: border-box。'],
-      [/display\s*:\s*flex/i, '底板必须使用 Flex 布局。'],
-      [/height\s*:\s*100%/i, '底板必须使用 height: 100%，不能使用 100vh。'],
-      [/background(?:-color)?\s*:\s*(?!transparent|none)[^;]+/i, '底板必须有非透明背景。'],
-      [/border\s*:\s*1px\s+(?:solid|dashed|dotted)\s+[^;]+/i, '底板必须有 1px 描边。'],
-      [/border-radius\s*:\s*(?:12px|var\(--[A-Za-z0-9_-]+\))/i, '底板四角必须使用 12px 圆角。'],
-    ]
-    for (const [expression, message] of checks) {
-      if (!expression.test(shell)) {
-        findings.push({
-          file: 'src/pages/index/index.css',
-          line: 1,
-          column: 1,
-          message,
-        })
-      }
-    }
-    if (hasDeclaration(shell, 'height', '100vh')) {
-      findings.push({
-        file: 'src/pages/index/index.css',
-        line: 1,
-        column: 1,
-        message: '固定 widget 禁止使用 height: 100vh。',
-      })
-    }
   }
 
   if (findings.length > 0) {
     console.warn(`WARN: OpenCard widget 底板校验未通过（${findings.length}），不阻断构建`)
     for (const finding of findings) {
-      console.warn(formatFinding(finding.file, finding.line, finding.column, finding.message))
+      console.warn(`${finding.file}:${finding.line}:${finding.column} ${finding.message}`)
     }
   }
-
   return { skipped: false, findings }
 }