create-windy 0.2.19 → 0.2.21

package/dist/cli.js

@@ -228,10 +228,15 @@ var optionalModuleManifests = [
       "system.audit"
     ]),
     fileRoots: [
+      "apps/agent-server",
       "apps/server/src/agent",
       "packages/modules/src/system-agent-tools.ts"
     ],
-    documentation: ["docs/platform/agent-tools.md"]
+    documentation: [
+      "docs/architecture/ai-runtime.md",
+      "docs/platform/agent-runtime.md",
+      "docs/platform/agent-tools.md"
+    ]
   },
   {
     ...module("system.scheduler", "任务调度", "任务、重试、历史和恢复。", [
@@ -727,7 +732,7 @@ var helpText = `create-windy <项目名> [选项]
 `;
 
 // src/create-project.ts
-import { mkdir as mkdir4, readdir as readdir5, rm as rm4 } from "node:fs/promises";
+import { mkdir as mkdir4, readdir as readdir6, rm as rm4 } from "node:fs/promises";
 
 // src/commands.ts
 import { spawn } from "node:child_process";
@@ -881,7 +886,10 @@ async function initializeLocalEnvironment(projectRoot, generateSecret = defaultS
   if (!gitignore.split(/\r?\n/).some((line) => line.trim() === ".env")) {
     throw new Error("生成项目的 .gitignore 未排除 .env，拒绝写入本地密码");
   }
-  const content = setEmptyVariable(setEmptyVariable(example, "POSTGRES_PASSWORD", generateSecret()), "WINDY_BOOTSTRAP_ADMIN_PASSWORD", generateSecret());
+  let content = setEmptyVariable(setEmptyVariable(example, "POSTGRES_PASSWORD", generateSecret()), "WINDY_BOOTSTRAP_ADMIN_PASSWORD", generateSecret());
+  if (/^AGENT_SERVER_INTERNAL_TOKEN=[ \t\r]*$/m.test(content)) {
+    content = setEmptyVariable(content, "AGENT_SERVER_INTERNAL_TOKEN", generateSecret());
+  }
   let handle;
   try {
     handle = await open(target, "wx", 384);
@@ -920,16 +928,147 @@ import {
   copyFile,
   lstat as lstat4,
   mkdir as mkdir3,
-  readFile as readFile9,
-  readdir as readdir4,
+  readFile as readFile10,
+  readdir as readdir5,
   rm as rm3,
-  writeFile as writeFile8
+  writeFile as writeFile9
 } from "node:fs/promises";
-import { basename as basename3, extname as extname3, join as join9 } from "node:path";
+import { basename as basename3, extname as extname3, join as join10 } from "node:path";
 
 // src/customer-docker.ts
-import { readFile as readFile2, writeFile } from "node:fs/promises";
+import { readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+
+// src/docker-copy-sync.ts
+import { readdir, readFile as readFile2, writeFile } from "node:fs/promises";
 import { join as join2 } from "node:path";
+var webDockerfilePath = "apps/web/Dockerfile";
+var webEntryDirectory = "apps/web";
+var depsCopyAnchor = "windy-copy:deps";
+var buildCopyAnchor = "windy-copy:build";
+async function listWorkspacePackages(root) {
+  const manifest = await readManifest(join2(root, "package.json"));
+  const packages = [];
+  for (const pattern of manifest.workspaces ?? []) {
+    if (!pattern.endsWith("/*")) {
+      throw new Error(`暂不支持的 workspace pattern: ${pattern}`);
+    }
+    const base = pattern.slice(0, -2);
+    const entries = await readdir(join2(root, base), {
+      withFileTypes: true
+    }).catch((error) => {
+      if (isMissing(error))
+        return [];
+      throw error;
+    });
+    for (const entry of entries) {
+      if (!entry.isDirectory())
+        continue;
+      const directory = `${base}/${entry.name}`;
+      const manifestPath = join2(root, directory, "package.json");
+      if (!await Bun.file(manifestPath).exists())
+        continue;
+      const value = await readManifest(manifestPath);
+      packages.push({
+        name: value.name,
+        directory,
+        dependencies: [
+          ...Object.keys(value.dependencies ?? {}),
+          ...Object.keys(value.devDependencies ?? {})
+        ]
+      });
+    }
+  }
+  return packages.sort((a, b) => a.directory.localeCompare(b.directory));
+}
+function workspaceDependencyClosure(packages, entryDirectory) {
+  const directoryByName = new Map;
+  const packageByDirectory = new Map;
+  for (const pkg of packages) {
+    if (pkg.name)
+      directoryByName.set(pkg.name, pkg.directory);
+    packageByDirectory.set(pkg.directory, pkg);
+  }
+  const visited = new Set([entryDirectory]);
+  const queue = [entryDirectory];
+  while (queue.length) {
+    const current = packageByDirectory.get(queue.shift());
+    if (!current)
+      continue;
+    for (const dependency of current.dependencies) {
+      const directory = directoryByName.get(dependency);
+      if (directory && !visited.has(directory)) {
+        visited.add(directory);
+        queue.push(directory);
+      }
+    }
+  }
+  return [...visited].sort((a, b) => a.localeCompare(b));
+}
+function dockerCopyLines(directories) {
+  return directories.map((directory) => `COPY ${directory} ${directory}`);
+}
+function dockerManifestCopyLines(directories) {
+  return directories.map((directory) => `COPY ${directory}/package.json ${directory}/package.json`);
+}
+function rewriteAnchoredSection(source, anchor, lines) {
+  const { begin, end } = locateAnchoredSection(source, anchor);
+  const all = source.split(`
+`);
+  return [...all.slice(0, begin + 1), ...lines, ...all.slice(end)].join(`
+`);
+}
+function hasCopyAnchors(source) {
+  return source.includes(`# ${depsCopyAnchor} begin`) && source.includes(`# ${buildCopyAnchor} begin`);
+}
+function syncWebDockerfileSource(source, workspaceDirectories, buildDirectories) {
+  const withDeps = rewriteAnchoredSection(source, depsCopyAnchor, dockerManifestCopyLines(workspaceDirectories));
+  return rewriteAnchoredSection(withDeps, buildCopyAnchor, dockerCopyLines(buildDirectories));
+}
+async function syncWebDockerfileInProject(root, options = {}) {
+  const path = join2(root, webDockerfilePath);
+  let source;
+  try {
+    source = await readFile2(path, "utf8");
+  } catch (error) {
+    if (isMissing(error))
+      return { synced: false, changed: false };
+    throw error;
+  }
+  if (!hasCopyAnchors(source)) {
+    if (!options.requireAnchors)
+      return { synced: false, changed: false };
+    throw new Error(`${webDockerfilePath} 缺少 # ${depsCopyAnchor} / # ${buildCopyAnchor} 锚点段，` + `请先按最新模板为 deps 与 build 阶段的 COPY 段添加锚点后再同步`);
+  }
+  const packages = await listWorkspacePackages(root);
+  const next = syncWebDockerfileSource(source, packages.map(({ directory }) => directory), workspaceDependencyClosure(packages, webEntryDirectory));
+  if (next !== source)
+    await writeFile(path, next);
+  return { synced: true, changed: next !== source };
+}
+function locateAnchoredSection(source, anchor) {
+  const beginMarker = `# ${anchor} begin`;
+  const endMarker = `# ${anchor} end`;
+  const lines = source.split(`
+`);
+  const begin = lines.indexOf(beginMarker);
+  const end = lines.indexOf(endMarker);
+  if (begin === -1 || end === -1 || end <= begin) {
+    throw new Error(`Dockerfile 缺少锚点段 ${beginMarker} ... ${endMarker}，请先迁移到锚点格式`);
+  }
+  if (lines.indexOf(beginMarker, begin + 1) !== -1 || lines.indexOf(endMarker, end + 1) !== -1) {
+    throw new Error(`Dockerfile 锚点段 ${anchor} 重复，请保留唯一一段`);
+  }
+  return { begin, end };
+}
+async function readManifest(path) {
+  return JSON.parse(await readFile2(path, "utf8"));
+}
+function isMissing(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+// src/customer-docker.ts
 var supplierWorkspaceCopies = [
   "COPY apps/license/package.json apps/license/package.json",
   "COPY apps/signing-service/package.json apps/signing-service/package.json",
@@ -937,11 +1076,12 @@ var supplierWorkspaceCopies = [
 ];
 var supplierWorkspacePaths = ["packages/license-sdk"];
 async function prepareCustomerDockerfiles(root) {
-  await Promise.all(["apps/server/Dockerfile", "apps/web/Dockerfile"].map(async (path) => {
-    const absolutePath = join2(root, path);
-    const source = await readFile2(absolutePath, "utf8");
-    await writeFile(absolutePath, rewriteCustomerDockerfile(source));
+  await Promise.all(["apps/server/Dockerfile", webDockerfilePath].map(async (path) => {
+    const absolutePath = join3(root, path);
+    const source = await readFile3(absolutePath, "utf8");
+    await writeFile2(absolutePath, rewriteCustomerDockerfile(source));
   }));
+  await syncWebDockerfileInProject(root, { requireAnchors: true });
 }
 function rewriteCustomerDockerfile(source) {
   const lines = source.split(`
@@ -953,8 +1093,8 @@ function rewriteCustomerDockerfile(source) {
 }
 
 // src/code-quality.ts
-import { readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
-import { join as join3 } from "node:path";
+import { readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join4 } from "node:path";
 var oxcStarterPolicy = [
   "- 生成时默认预装 Oxlint、Oxfmt、lint-staged 与 Husky。",
   "- 提交前自动格式化暂存文件；lint、typecheck 和 test 保留为显式命令。",
@@ -963,30 +1103,30 @@ var oxcStarterPolicy = [
 `);
 var noCodeQualityPolicy = "- 本项目生成时未引入 lint 或 format 工具；项目所有者可按团队需要自行选择。";
 async function reflectCodeQualityChoice(targetDirectory, includeOxc) {
-  const path = join3(targetDirectory, "AGENTS.md");
-  const source = await readFile3(path, "utf8");
+  const path = join4(targetDirectory, "AGENTS.md");
+  const source = await readFile4(path, "utf8");
   if (includeOxc)
     return;
   if (!source.includes(oxcStarterPolicy)) {
     throw new Error("无法同步 --no-oxc 的项目开发约束");
   }
-  await writeFile2(path, source.replace(oxcStarterPolicy, noCodeQualityPolicy));
+  await writeFile3(path, source.replace(oxcStarterPolicy, noCodeQualityPolicy));
 }
 
 // src/license-files.ts
-import { mkdir, readFile as readFile4, rm, writeFile as writeFile3 } from "node:fs/promises";
-import { dirname, join as join4, resolve as resolve2 } from "node:path";
+import { mkdir, readFile as readFile5, rm, writeFile as writeFile4 } from "node:fs/promises";
+import { dirname, join as join5, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
 var packageRoot = resolve2(dirname(fileURLToPath(import.meta.url)), "..");
 var apacheLicensePath = resolve2(packageRoot, "LICENSE");
 var windyLicensePath = ".windy/licenses/WINDY-APACHE-2.0.txt";
 async function applyWindyBaseLicense(targetDirectory) {
-  const target = join4(targetDirectory, windyLicensePath);
+  const target = join5(targetDirectory, windyLicensePath);
   await mkdir(dirname(target), { recursive: true });
-  await writeFile3(target, await readFile4(apacheLicensePath));
+  await writeFile4(target, await readFile5(apacheLicensePath));
 }
 async function applyProjectLicense(targetDirectory, license, holder, year = new Date().getFullYear()) {
-  const target = join4(targetDirectory, "LICENSE");
+  const target = join5(targetDirectory, "LICENSE");
   if (license === "UNLICENSED") {
     await rm(target, { force: true });
     return;
@@ -996,11 +1136,11 @@ async function applyProjectLicense(targetDirectory, license, holder, year = new
     if (!owner)
       throw new Error("选择 MIT 时必须填写许可证权利人名称");
     await mkdir(targetDirectory, { recursive: true });
-    await writeFile3(target, mitLicense(year, owner));
+    await writeFile4(target, mitLicense(year, owner));
     return;
   }
   await mkdir(targetDirectory, { recursive: true });
-  await writeFile3(target, await readFile4(apacheLicensePath));
+  await writeFile4(target, await readFile5(apacheLicensePath));
 }
 function mitLicense(year, holder) {
   return `MIT License
@@ -1029,8 +1169,8 @@ SOFTWARE.
 
 // src/managed-files.ts
 import { createHash } from "node:crypto";
-import { lstat, readdir, readFile as readFile5, writeFile as writeFile4 } from "node:fs/promises";
-import { join as join5, relative, sep } from "node:path";
+import { lstat, readdir as readdir2, readFile as readFile6, writeFile as writeFile5 } from "node:fs/promises";
+import { join as join6, relative, sep } from "node:path";
 var managedFilesManifestPath = ".windy/files.json";
 var ignoredDirectoryNames = new Set([".git", "node_modules", "dist"]);
 var ignoredFiles = new Set([
@@ -1060,7 +1200,7 @@ var sharedScaffoldRoots = [
 async function writeManagedFilesManifest(targetDirectory, generatorVersion) {
   const paths = await collectFiles(targetDirectory);
   const files = await Promise.all(paths.map(async (path) => {
-    const content = await readFile5(join5(targetDirectory, path));
+    const content = await readFile6(join6(targetDirectory, path));
     return {
       path,
       ownership: classifyOwnership(path),
@@ -1073,11 +1213,11 @@ async function writeManagedFilesManifest(targetDirectory, generatorVersion) {
     algorithm: "sha256",
     files
   };
-  await writeFile4(join5(targetDirectory, managedFilesManifestPath), `${JSON.stringify(manifest, null, 2)}
+  await writeFile5(join6(targetDirectory, managedFilesManifestPath), `${JSON.stringify(manifest, null, 2)}
 `);
 }
 async function readManagedFilesManifest(targetDirectory) {
-  const parsed = JSON.parse(await readFile5(join5(targetDirectory, managedFilesManifestPath), "utf8"));
+  const parsed = JSON.parse(await readFile6(join6(targetDirectory, managedFilesManifestPath), "utf8"));
   if (!isManagedFilesManifest(parsed)) {
     throw new Error("受管文件清单无效，无法安全更新");
   }
@@ -1098,10 +1238,10 @@ async function collectFiles(root) {
   await visit(root, files);
   return files.sort();
   async function visit(directory, output) {
-    for (const name of (await readdir(directory)).sort()) {
+    for (const name of (await readdir2(directory)).sort()) {
       if (ignoredDirectoryNames.has(name))
         continue;
-      const path = join5(directory, name);
+      const path = join6(directory, name);
       const metadata = await lstat(path);
       if (metadata.isSymbolicLink())
         continue;
@@ -1135,8 +1275,8 @@ function isManagedFilesManifest(value) {
 }
 
 // src/module-materializer.ts
-import { lstat as lstat2, readFile as readFile6, readdir as readdir2, rm as rm2, writeFile as writeFile5 } from "node:fs/promises";
-import { basename, extname, join as join6, relative as relative2, sep as sep2 } from "node:path";
+import { lstat as lstat2, readFile as readFile7, readdir as readdir3, rm as rm2, writeFile as writeFile6 } from "node:fs/promises";
+import { basename, extname, join as join7, relative as relative2, sep as sep2 } from "node:path";
 var textExtensions = new Set([
   ".css",
   ".html",
@@ -1169,18 +1309,18 @@ async function materializeSelectedModules(targetDirectory, selectedNames) {
     ...manifest.documentation,
     ...manifest.schemaFiles
   ]);
-  await Promise.all([...new Set(removedRoots)].map((path) => rm2(join6(targetDirectory, path), { recursive: true, force: true })));
+  await Promise.all([...new Set(removedRoots)].map((path) => rm2(join7(targetDirectory, path), { recursive: true, force: true })));
   await pruneWorkspaceReferences(targetDirectory, removedPackageNames, removedRoots);
 }
 async function stripModuleBlocks(root, selected) {
   for (const path of await collectFiles2(root)) {
     if (!textExtensions.has(extname(path)))
       continue;
-    const source = await readFile6(path, "utf8");
+    const source = await readFile7(path, "utf8");
     if (!source.includes("@windy-module"))
       continue;
     const output = stripTaggedSource(source, selected, relativePath(root, path));
-    await writeFile5(path, output);
+    await writeFile6(path, output);
   }
 }
 function stripTaggedSource(source, selected, path = "source") {
@@ -1213,11 +1353,11 @@ async function readRemovedPackageNames(root, roots) {
   const names = new Set;
   for (const packageRoot2 of roots) {
     try {
-      const value = JSON.parse(await readFile6(join6(root, packageRoot2, "package.json"), "utf8"));
+      const value = JSON.parse(await readFile7(join7(root, packageRoot2, "package.json"), "utf8"));
       if (value.name)
         names.add(value.name);
     } catch (error) {
-      if (!isMissing(error))
+      if (!isMissing2(error))
         throw error;
     }
   }
@@ -1226,7 +1366,7 @@ async function readRemovedPackageNames(root, roots) {
 async function pruneWorkspaceReferences(root, removedPackages, removedRoots) {
   for (const path of await collectFiles2(root)) {
     if (basename(path) === "package.json") {
-      const value = JSON.parse(await readFile6(path, "utf8"));
+      const value = JSON.parse(await readFile7(path, "utf8"));
       let changed = false;
       for (const section of ["dependencies", "devDependencies"]) {
         const dependencies = value[section];
@@ -1238,45 +1378,45 @@ async function pruneWorkspaceReferences(root, removedPackages, removedRoots) {
         }
       }
       if (changed)
-        await writeFile5(path, `${JSON.stringify(value, null, 2)}
+        await writeFile6(path, `${JSON.stringify(value, null, 2)}
 `);
       continue;
     }
     if (basename(path) !== "Dockerfile")
       continue;
-    const source = await readFile6(path, "utf8");
+    const source = await readFile7(path, "utf8");
     const output = source.split(`
 `).filter((line) => !removedRoots.some((root2) => line.includes(root2))).join(`
 `);
     if (output !== source)
-      await writeFile5(path, output);
+      await writeFile6(path, output);
   }
 }
 async function pruneDatabaseArtifacts(root, tableNames, statementTokens) {
   if (!tableNames.length && !statementTokens.length)
     return;
   const tablePatterns = tableNames.map((name) => new RegExp(`(?:"${escapeRegExp(name)}"|\\b${escapeRegExp(name)}\\b)`));
-  const drizzleRoot = join6(root, "packages/database/drizzle");
+  const drizzleRoot = join7(root, "packages/database/drizzle");
   try {
     for (const path of await collectFiles2(drizzleRoot)) {
       if (path.endsWith(".sql")) {
-        const source = await readFile6(path, "utf8");
+        const source = await readFile7(path, "utf8");
         const statements = source.split("--> statement-breakpoint").map((statement) => statement.trim()).filter(Boolean).filter((statement) => !tablePatterns.some((pattern) => pattern.test(statement)) && !statementTokens.some((token) => statement.includes(token)));
-        await writeFile5(path, statements.length ? `${statements.join(`
+        await writeFile6(path, statements.length ? `${statements.join(`
 --> statement-breakpoint
 `)}
 ` : `-- 此 migration 的模块未被当前项目选择。
 `);
       } else if (path.endsWith("_snapshot.json")) {
-        const snapshot = JSON.parse(await readFile6(path, "utf8"));
+        const snapshot = JSON.parse(await readFile7(path, "utf8"));
         for (const name of tableNames)
           delete snapshot.tables?.[`public.${name}`];
-        await writeFile5(path, `${JSON.stringify(snapshot, null, 2)}
+        await writeFile6(path, `${JSON.stringify(snapshot, null, 2)}
 `);
       }
     }
   } catch (error) {
-    if (!isMissing(error))
+    if (!isMissing2(error))
       throw error;
   }
 }
@@ -1285,10 +1425,10 @@ async function collectFiles2(root) {
   await visit(root);
   return files.sort();
   async function visit(directory) {
-    for (const name of (await readdir2(directory)).sort()) {
+    for (const name of (await readdir3(directory)).sort()) {
       if ([".git", "node_modules", "dist"].includes(name))
         continue;
-      const path = join6(directory, name);
+      const path = join7(directory, name);
       const metadata = await lstat2(path);
       if (metadata.isSymbolicLink())
         continue;
@@ -1305,12 +1445,12 @@ function relativePath(root, path) {
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function isMissing(error) {
+function isMissing2(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 
-// src/project-files.ts
-var starterCompose = `services:
+// src/runtime-profile-files.ts
+var starterComposeBase = `services:
   postgres:
     image: postgres:17-alpine
     environment:
@@ -1354,6 +1494,10 @@ var starterCompose = `services:
       WINDY_CONTAINERIZED: "1"
       BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD: "true"
       WINDY_SYSTEM_USAGE_PATHS: /app/data/audit
+      PLATFORM_ENABLE_AI: \${PLATFORM_ENABLE_AI:-false}
+      AGENT_SERVER_URL: http://agent-server:8080
+      AGENT_TOOL_HOST_URL: http://server:9747
+      AGENT_SERVER_INTERNAL_TOKEN: \${AGENT_SERVER_INTERNAL_TOKEN:-}
     ports:
       - "9747:9747"
     volumes:
@@ -1397,11 +1541,50 @@ var starterCompose = `services:
 volumes:
   postgres-data:
   server-audit-data:
+__AGENT_VOLUME__
+`;
+var agentComposeService = `  agent-server:
+    profiles: ["agent"]
+    build:
+      context: .
+      dockerfile: apps/agent-server/Dockerfile
+    environment:
+      AGENT_SERVER_INTERNAL_TOKEN: \${AGENT_SERVER_INTERNAL_TOKEN:-}
+      AGENT_RUN_STORE_PATH: /app/data/agent/runs.sqlite3
+      QWEN_API_URL: \${QWEN_API_URL:-}
+      QWEN_API_KEY: \${QWEN_API_KEY:-}
+      QWEN_MODEL: \${QWEN_MODEL:-}
+      AI_PROVIDER_CONNECT_TIMEOUT_MS: \${AI_PROVIDER_CONNECT_TIMEOUT_MS:-5000}
+      AI_PROVIDER_REQUEST_TIMEOUT_MS: \${AI_PROVIDER_REQUEST_TIMEOUT_MS:-60000}
+      AI_PROVIDER_MAX_RESPONSE_BYTES: \${AI_PROVIDER_MAX_RESPONSE_BYTES:-2097152}
+    volumes:
+      - agent-run-data:/app/data/agent
+    depends_on:
+      server:
+        condition: service_started
+
 `;
-function environmentExample(includeExample) {
+function starterComposeFor(includeAgent) {
+  return starterComposeBase.replace(`  web:
+`, `${includeAgent ? agentComposeService : ""}  web:
+`).replace("__AGENT_VOLUME__", includeAgent ? "  agent-run-data:" : "");
+}
+var starterCompose = starterComposeFor(true);
+function environmentExample(includeExample, includeAgent = true) {
   return `# 复制为 .env 后填写。不要提交真实密码。
 POSTGRES_PASSWORD=
 WINDY_BOOTSTRAP_ADMIN_PASSWORD=
+${includeAgent ? `
+# Agent profile 仅由 Server 读取；不要使用 VITE_ 前缀。
+PLATFORM_ENABLE_AI=false
+AGENT_SERVER_INTERNAL_TOKEN=
+QWEN_API_URL=
+QWEN_API_KEY=
+QWEN_MODEL=
+# AI_PROVIDER_CONNECT_TIMEOUT_MS=5000
+# AI_PROVIDER_REQUEST_TIMEOUT_MS=60000
+# AI_PROVIDER_MAX_RESPONSE_BYTES=2097152
+` : ""}
 
 # 可选搜索配置；不配置时启用 Manifest 中默认开启的 Provider。${includeExample ? `
 # SEARCH_PROVIDER_KEYS=work-order.ticket.search` : `
@@ -1411,7 +1594,8 @@ WINDY_BOOTSTRAP_ADMIN_PASSWORD=
 # SEARCH_MAX_REQUESTS_PER_MINUTE=30
 `;
 }
-function starterDocsReadme(includeOfflineLicense = true) {
+// src/project-files.ts
+function starterDocsReadme(includeOfflineLicense = true, includeAgent = true) {
   return `# Windy Starter 文档
 
 本目录只包含客户运行项目需要的平台架构、开发接入和运维可观测性文档。
@@ -1422,11 +1606,13 @@ License 签发中心、独立签名服务、Vault、发布治理、内部任务
 - 平台开发：从 [系统 CRUD API](./platform/system-crud-api.md) 和 [CRUD 生成器](./development/crud-generator.md) 开始。
 ${includeOfflineLicense ? "- License 消费端：[离线激活与安装协议](./license/license-offline-activation-code.md)；运行时能力由 npm 依赖 `@southwind-ai/license` 提供。" : ""}
 - 运维：[可观测性](./operations/observability.md) 与 [运维总览](./platform/operations-overview.md)。
+${includeAgent ? "- Agent：[Agent Runtime 接入](./platform/agent-runtime.md) 与 [受控工具](./platform/agent-tools.md)。" : ""}
 - 兼容：[RuoYi-Vue Adapter](./adapters/ruoyi-vue-compatibility.md)。
 `;
 }
 function starterReadme(projectName, includeExample = true, includeOxc = true, projectLicense = "UNLICENSED", selectedModules = []) {
   const selected = new Set(selectedModules);
+  const includeAgent = selected.has("system.agent");
   const moduleRows = moduleDistributionCatalog.map(({ name, description, selection }) => `| \`${name}\` | ${selected.has(name) ? "已包含" : "未包含"} | ${selection === "required" ? "H0" : "H2"} | ${description} |`).join(`
 `);
   return `# ${projectName}
@@ -1482,6 +1668,21 @@ bun run dev:server
 直接输出已有地址，其它服务占用时会自动使用后续端口，最多检查 100 个。实际地址始终
 以终端输出为准。\`dev:server\` 不会自动启动 PostgreSQL 或执行 migration；未配置
 \`DATABASE_URL\` 时使用内存模式。
+${includeAgent ? `
+## OpenAI-compatible Agent profile
+
+Agent Runtime 默认不启动。先在仅供本机使用的 \`.env\` 中设置
+\`PLATFORM_ENABLE_AI=true\`、\`AGENT_SERVER_INTERNAL_TOKEN\`、\`QWEN_API_URL\`、
+\`QWEN_API_KEY\` 与 \`QWEN_MODEL\`，再运行：
+
+\`\`\`bash
+bun run dev:agent
+\`\`\`
+
+公网 Provider URL 必须使用 HTTPS；本机、容器服务名和内网地址允许 HTTP。
+\`QWEN_API_KEY\` 只进入 Agent Server，不会进入 Web 环境或返回给客户端。运行与模块
+接入细节见 [Agent Runtime 接入](./docs/platform/agent-runtime.md)。
+` : ""}
 
 ## 页面与登录
 
@@ -1604,7 +1805,9 @@ function createStarterPackage(source, projectName, includeOxc = true, projectLic
         prepare: "git rev-parse --git-dir >/dev/null 2>&1 || exit 0; husky"
       } : {},
       dev: "docker compose up",
-      "dev:build": "docker compose up --build",
+      "docker:sync": "create-windy sync-docker",
+      "dev:build": "bun run docker:sync && docker compose up --build",
+      ...selectedModules.includes("system.agent") ? { "dev:agent": "docker compose --profile agent up --build" } : {},
       ...generatorVersion ? { windy: "create-windy" } : {},
       "dev:web": "bun run --cwd apps/web dev",
       "dev:server": "bun run --cwd apps/server dev",
@@ -1652,6 +1855,7 @@ var templateRootFiles = [
 ];
 var templateDirectories = [
   "apps/server",
+  "apps/agent-server",
   "apps/web",
   "examples",
   "packages/ai-client",
@@ -1668,6 +1872,7 @@ var templateDirectories = [
 var templateDocumentationFiles = [
   "docs/adapters/ruoyi-vue-compatibility.md",
   "docs/architecture/admin-surface-boundary.md",
+  "docs/architecture/ai-runtime.md",
   "docs/architecture/data-scope-query-enforcement.md",
   "docs/architecture/durable-jobs.md",
   "docs/architecture/minimal-approval-workflow.md",
@@ -1678,6 +1883,7 @@ var templateDocumentationFiles = [
   "docs/license/license-offline-activation-code.md",
   "docs/operations/observability.md",
   "docs/platform/agent-tools.md",
+  "docs/platform/agent-runtime.md",
   "docs/platform/audit-reliability.md",
   "docs/platform/bulk-data-jobs.md",
   "docs/platform/data-access-control.md",
@@ -1725,21 +1931,21 @@ var excludedRuntimeFiles = new Set([
 ]);
 
 // src/provenance.ts
-import { mkdir as mkdir2, readFile as readFile7, writeFile as writeFile6 } from "node:fs/promises";
-import { join as join7 } from "node:path";
+import { mkdir as mkdir2, readFile as readFile8, writeFile as writeFile7 } from "node:fs/promises";
+import { join as join8 } from "node:path";
 var templateMetadataFile = ".windy-template.json";
 var generationMetadataFile = ".windy/generation.json";
 async function readTemplateMetadata(sourceRoot) {
-  const path = join7(sourceRoot, templateMetadataFile);
-  const parsed = JSON.parse(await readFile7(path, "utf8"));
+  const path = join8(sourceRoot, templateMetadataFile);
+  const parsed = JSON.parse(await readFile8(path, "utf8"));
   if (!isTemplateMetadata(parsed)) {
     throw new Error("create-windy 模板来源元数据无效");
   }
   return parsed;
 }
 async function readGenerationProvenance(targetDirectory) {
-  const path = join7(targetDirectory, generationMetadataFile);
-  const parsed = JSON.parse(await readFile7(path, "utf8"));
+  const path = join8(targetDirectory, generationMetadataFile);
+  const parsed = JSON.parse(await readFile8(path, "utf8"));
   if (!isGenerationProvenance(parsed)) {
     throw new Error("当前目录不是受支持的 Windy 项目：Project Lock 无效");
   }
@@ -1771,9 +1977,9 @@ async function writeGenerationProvenance(targetDirectory, metadata, profile, sel
       includeOxc
     }
   };
-  const path = join7(targetDirectory, generationMetadataFile);
-  await mkdir2(join7(path, ".."), { recursive: true });
-  await writeFile6(path, `${JSON.stringify(provenance, null, 2)}
+  const path = join8(targetDirectory, generationMetadataFile);
+  await mkdir2(join8(path, ".."), { recursive: true });
+  await writeFile7(path, `${JSON.stringify(provenance, null, 2)}
 `);
 }
 function isTemplateMetadata(value) {
@@ -1798,8 +2004,8 @@ function isModuleVersion(value) {
 }
 
 // src/registry-dependencies.ts
-import { lstat as lstat3, readFile as readFile8, readdir as readdir3, writeFile as writeFile7 } from "node:fs/promises";
-import { basename as basename2, extname as extname2, join as join8 } from "node:path";
+import { lstat as lstat3, readFile as readFile9, readdir as readdir4, writeFile as writeFile8 } from "node:fs/promises";
+import { basename as basename2, extname as extname2, join as join9 } from "node:path";
 var dependencySections = [
   "dependencies",
   "devDependencies",
@@ -1827,14 +2033,14 @@ async function materializeRegistryDependencies(root, dependencies) {
       await rewritePackageJson(path, dependencies);
       continue;
     }
-    const source = await readFile8(path, "utf8");
+    const source = await readFile9(path, "utf8");
     const output = dependencies.reduce((value, dependency) => value.replaceAll(dependency.sourceName, dependency.name), source);
     if (output !== source)
-      await writeFile7(path, output);
+      await writeFile8(path, output);
   }
 }
 async function rewritePackageJson(path, registryDependencies) {
-  const value = JSON.parse(await readFile8(path, "utf8"));
+  const value = JSON.parse(await readFile9(path, "utf8"));
   let changed = false;
   for (const section of dependencySections) {
     const dependencies = value[section];
@@ -1849,7 +2055,7 @@ async function rewritePackageJson(path, registryDependencies) {
     }
   }
   if (changed)
-    await writeFile7(path, `${JSON.stringify(value, null, 2)}
+    await writeFile8(path, `${JSON.stringify(value, null, 2)}
 `);
 }
 async function collectFiles3(root) {
@@ -1857,10 +2063,10 @@ async function collectFiles3(root) {
   await visit(root);
   return files.sort();
   async function visit(directory) {
-    for (const name of (await readdir3(directory)).sort()) {
+    for (const name of (await readdir4(directory)).sort()) {
       if ([".git", "node_modules", "dist"].includes(name))
         continue;
-      const path = join8(directory, name);
+      const path = join9(directory, name);
       const metadata = await lstat3(path);
       if (metadata.isSymbolicLink())
         continue;
@@ -1884,39 +2090,39 @@ async function generateProject(input) {
   const selectedModules = input.selectedModules ?? templateMetadata.modules.filter(({ name }) => requestedIncludeExample || name !== "work-order").map(({ name }) => name);
   const includeExample = selectedModules.includes("work-order");
   for (const relativePath2 of generationTemplatePaths(true, includeOxc)) {
-    await copyTree(await resolveTemplateSource(input.sourceRoot, relativePath2), join9(input.targetDirectory, relativePath2));
+    await copyTree(await resolveTemplateSource(input.sourceRoot, relativePath2), join10(input.targetDirectory, relativePath2));
   }
   await materializeSelectedModules(input.targetDirectory, selectedModules);
   await materializeRegistryDependencies(input.targetDirectory, selectedModuleManifests(selectedModules).flatMap(({ registryDependencies }) => registryDependencies));
-  const packagePath = join9(input.targetDirectory, "package.json");
-  const packageJson = JSON.parse(await readFile9(packagePath, "utf8"));
-  await writeFile8(packagePath, `${JSON.stringify(createStarterPackage(packageJson, input.projectName, includeOxc, projectLicense, selectedModules, templateMetadata.generatorVersion), null, 2)}
+  const packagePath = join10(input.targetDirectory, "package.json");
+  const packageJson = JSON.parse(await readFile10(packagePath, "utf8"));
+  await writeFile9(packagePath, `${JSON.stringify(createStarterPackage(packageJson, input.projectName, includeOxc, projectLicense, selectedModules, templateMetadata.generatorVersion), null, 2)}
 `);
-  await writeFile8(join9(input.targetDirectory, "docker-compose.yml"), starterCompose);
-  await writeFile8(join9(input.targetDirectory, ".env.example"), environmentExample(includeExample));
-  await writeFile8(join9(input.targetDirectory, "README.md"), starterReadme(input.projectName, includeExample, includeOxc, projectLicense, selectedModules));
-  await writeFile8(join9(input.targetDirectory, "docs/README.md"), starterDocsReadme(selectedModules.includes("system.license")));
+  await writeFile9(join10(input.targetDirectory, "docker-compose.yml"), starterComposeFor(selectedModules.includes("system.agent")));
+  await writeFile9(join10(input.targetDirectory, ".env.example"), environmentExample(includeExample, selectedModules.includes("system.agent")));
+  await writeFile9(join10(input.targetDirectory, "README.md"), starterReadme(input.projectName, includeExample, includeOxc, projectLicense, selectedModules));
+  await writeFile9(join10(input.targetDirectory, "docs/README.md"), starterDocsReadme(selectedModules.includes("system.license"), selectedModules.includes("system.agent")));
   await reflectCodeQualityChoice(input.targetDirectory, includeOxc);
   await applyWindyBaseLicense(input.targetDirectory);
   await applyProjectLicense(input.targetDirectory, projectLicense, input.licenseHolder);
   await prepareCustomerDockerfiles(input.targetDirectory);
   await writeGenerationProvenance(input.targetDirectory, templateMetadata, input.profile ?? starterProfile.key, selectedModules, includeOxc, projectLicense);
-  await rm3(join9(input.targetDirectory, "bun.lock"), { force: true });
+  await rm3(join10(input.targetDirectory, "bun.lock"), { force: true });
   await writeManagedFilesManifest(input.targetDirectory, templateMetadata.generatorVersion);
 }
 async function resolveTemplateSource(sourceRoot, relativePath2) {
-  const source = join9(sourceRoot, relativePath2);
+  const source = join10(sourceRoot, relativePath2);
   try {
     await lstat4(source);
     return source;
   } catch (error) {
-    if (!isMissing2(error))
+    if (!isMissing3(error))
       throw error;
   }
   const alias = npmTemplateAliases[relativePath2];
   if (!alias)
     return source;
-  return join9(sourceRoot, alias);
+  return join10(sourceRoot, alias);
 }
 async function assertGeneratedProjectIsClean(targetDirectory) {
   const violations = [];
@@ -1941,11 +2147,11 @@ function validateProjectName(projectName) {
 }
 async function assertTargetAvailable(targetDirectory) {
   try {
-    const entries = await readdir4(targetDirectory);
+    const entries = await readdir5(targetDirectory);
     if (entries.length)
       throw new Error("目标目录不是空目录");
   } catch (error) {
-    if (isMissing2(error))
+    if (isMissing3(error))
       return;
     throw error;
   }
@@ -1957,26 +2163,26 @@ async function copyTree(source, target) {
     return;
   if (metadata.isDirectory()) {
     await mkdir3(target, { recursive: true });
-    for (const child of await readdir4(source)) {
-      await copyTree(join9(source, child), join9(target, child));
+    for (const child of await readdir5(source)) {
+      await copyTree(join10(source, child), join10(target, child));
     }
     return;
   }
-  await mkdir3(join9(target, ".."), { recursive: true });
+  await mkdir3(join10(target, ".."), { recursive: true });
   await copyFile(source, target);
 }
 function shouldExclude(name) {
   return excludedNames.has(name) || excludedRuntimeFiles.has(name);
 }
 async function walk(directory, visit) {
-  for (const name of await readdir4(directory)) {
-    const path = join9(directory, name);
+  for (const name of await readdir5(directory)) {
+    const path = join10(directory, name);
     await visit(path);
     if ((await lstat4(path)).isDirectory())
       await walk(path, visit);
   }
 }
-function isMissing2(error) {
+function isMissing3(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 
@@ -2049,9 +2255,9 @@ async function createProject(options, dependencies = {}) {
 }
 async function inspectTarget(path) {
   try {
-    return (await readdir5(path)).length === 0 ? "empty" : "non-empty";
+    return (await readdir6(path)).length === 0 ? "empty" : "non-empty";
   } catch (error) {
-    if (isMissing3(error))
+    if (isMissing4(error))
       return "missing";
     throw error;
   }
@@ -2073,7 +2279,7 @@ function stageError(stage, error) {
 function sanitizeReason(reason) {
   return reason.replace(/\b([A-Z][A-Z0-9_]*(?:PASSWORD|SECRET|TOKEN|DATABASE_URL)[A-Z0-9_]*)=\S+/g, "$1=[已隐藏]").replace(/:\/\/([^\s:/]+):([^\s@]+)@/g, "://$1:[已隐藏]@");
 }
-function isMissing3(error) {
+function isMissing4(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 
@@ -3821,8 +4027,8 @@ import { rm as rm8 } from "node:fs/promises";
 import { resolve as resolve5 } from "node:path";
 
 // src/update/doctor.ts
-import { readFile as readFile11 } from "node:fs/promises";
-import { join as join11 } from "node:path";
+import { readFile as readFile12 } from "node:fs/promises";
+import { join as join12 } from "node:path";
 
 // src/update/process.ts
 import { spawn as spawn3 } from "node:child_process";
@@ -3854,12 +4060,12 @@ import {
   access as access2,
   copyFile as copyFile2,
   mkdir as mkdir5,
-  readFile as readFile10,
+  readFile as readFile11,
   rm as rm5,
   rmdir,
-  writeFile as writeFile9
+  writeFile as writeFile10
 } from "node:fs/promises";
-import { dirname as dirname3, join as join10, resolve as resolve4, sep as sep3 } from "node:path";
+import { dirname as dirname3, join as join11, resolve as resolve4, sep as sep3 } from "node:path";
 var updateStatePath = ".windy/update-state.json";
 async function applyTransaction(plan) {
   if (plan.conflicts.length) {
@@ -3868,21 +4074,22 @@ async function applyTransaction(plan) {
   const changed = plan.files.filter(({ action }) => action === "create" || action === "update" || action === "delete");
   for (const file of changed)
     assertSafePath(file.path);
-  const backupDirectory = join10(plan.projectDirectory, ".windy/backups", plan.id);
+  const backupDirectory = join11(plan.projectDirectory, ".windy/backups", plan.id);
   const protectedPaths = new Set([
     ...changed.map(({ path: path2 }) => path2),
     ".windy/generation.json",
     ".windy/files.json",
+    "apps/web/Dockerfile",
     "bun.lock"
   ]);
   const backupEntries = [];
   for (const path2 of protectedPaths) {
-    const source = join10(plan.projectDirectory, path2);
+    const source = join11(plan.projectDirectory, path2);
     const existed = await exists(source);
     backupEntries.push({ path: path2, existed });
     if (!existed)
       continue;
-    const target = join10(backupDirectory, "files", path2);
+    const target = join11(backupDirectory, "files", path2);
     await mkdir5(dirname3(target), { recursive: true });
     await copyFile2(source, target);
   }
@@ -3895,7 +4102,7 @@ async function applyTransaction(plan) {
   await writeState(plan.projectDirectory, state);
   try {
     for (const file of changed) {
-      const target = join10(plan.projectDirectory, file.path);
+      const target = join11(plan.projectDirectory, file.path);
       if (file.action === "delete") {
         const existed = await exists(target);
         await rm5(target, { force: true });
@@ -3907,7 +4114,7 @@ async function applyTransaction(plan) {
       if (!file.content)
         throw new Error(`更新计划缺少文件内容：${file.path}`);
       await mkdir5(dirname3(target), { recursive: true });
-      await writeFile9(target, file.content);
+      await writeFile10(target, file.content);
     }
   } catch (error) {
     await restoreUpdateState(plan.projectDirectory, state);
@@ -3922,7 +4129,7 @@ async function applyTransaction(plan) {
 }
 async function readUpdateState(projectDirectory) {
   try {
-    const parsed = JSON.parse(await readFile10(join10(projectDirectory, updateStatePath), "utf8"));
+    const parsed = JSON.parse(await readFile11(join11(projectDirectory, updateStatePath), "utf8"));
     if (!isUpdateState(parsed))
       throw new Error("更新恢复状态无效，请人工检查 .windy 目录");
     return parsed;
@@ -3935,25 +4142,25 @@ async function readUpdateState(projectDirectory) {
 async function restoreUpdateState(projectDirectory, state) {
   for (const entry of state.entries) {
     assertSafePath(entry.path);
-    const target = join10(projectDirectory, entry.path);
+    const target = join11(projectDirectory, entry.path);
     if (!entry.existed) {
       await rm5(target, { force: true });
       continue;
     }
-    const backup = join10(state.backupDirectory, "files", entry.path);
+    const backup = join11(state.backupDirectory, "files", entry.path);
     await mkdir5(dirname3(target), { recursive: true });
     await copyFile2(backup, target);
   }
-  await rm5(join10(projectDirectory, updateStatePath), { force: true });
+  await rm5(join11(projectDirectory, updateStatePath), { force: true });
   await rm5(state.backupDirectory, { recursive: true, force: true });
 }
 async function clearUpdateState(projectDirectory) {
-  await rm5(join10(projectDirectory, updateStatePath), { force: true });
+  await rm5(join11(projectDirectory, updateStatePath), { force: true });
 }
 async function writeState(projectDirectory, state) {
-  const path2 = join10(projectDirectory, updateStatePath);
+  const path2 = join11(projectDirectory, updateStatePath);
   await mkdir5(dirname3(path2), { recursive: true });
-  await writeFile9(path2, `${JSON.stringify(state, null, 2)}
+  await writeFile10(path2, `${JSON.stringify(state, null, 2)}
 `);
 }
 async function exists(path2) {
@@ -4021,7 +4228,7 @@ async function diagnoseProject(projectDirectory, repair = false) {
     if (file.ownership === "project-owned")
       continue;
     try {
-      const changed = hashContent(await readFile11(join11(projectDirectory, file.path))) !== file.hash;
+      const changed = hashContent(await readFile12(join12(projectDirectory, file.path))) !== file.hash;
       if (!changed)
         continue;
       modifiedManagedFiles.push(file.path);
@@ -4070,7 +4277,9 @@ var recipes = [
   { id: "starter-0.2.15-to-0.2.16", from: "0.2.15", to: "0.2.16" },
   { id: "starter-0.2.16-to-0.2.17", from: "0.2.16", to: "0.2.17" },
   { id: "starter-0.2.17-to-0.2.18", from: "0.2.17", to: "0.2.18" },
-  { id: "starter-0.2.18-to-0.2.19", from: "0.2.18", to: "0.2.19" }
+  { id: "starter-0.2.18-to-0.2.19", from: "0.2.18", to: "0.2.19" },
+  { id: "starter-0.2.19-to-0.2.20", from: "0.2.19", to: "0.2.20" },
+  { id: "starter-0.2.20-to-0.2.21", from: "0.2.20", to: "0.2.21" }
 ];
 function resolveRecipeChain(sourceVersion, targetVersion) {
   if (sourceVersion === targetVersion)
@@ -4095,19 +4304,19 @@ function resolveRecipeChain(sourceVersion, targetVersion) {
 }
 
 // src/update/updater.ts
-import { mkdir as mkdir7, readFile as readFile15, rm as rm7, writeFile as writeFile11 } from "node:fs/promises";
-import { dirname as dirname4, join as join16 } from "node:path";
+import { mkdir as mkdir7, readFile as readFile16, rm as rm7, writeFile as writeFile12 } from "node:fs/promises";
+import { dirname as dirname4, join as join17 } from "node:path";
 
 // src/update/artifacts.ts
-import { mkdir as mkdir6, mkdtemp, readFile as readFile12 } from "node:fs/promises";
+import { mkdir as mkdir6, mkdtemp, readFile as readFile13 } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename as basename4, join as join12 } from "node:path";
+import { basename as basename4, join as join13 } from "node:path";
 class PublishedArtifactProvider {
   async prepare(projectDirectory, provenance) {
-    const temporaryRoot = await mkdtemp(join12(tmpdir(), "windy-update-"));
+    const temporaryRoot = await mkdtemp(join13(tmpdir(), "windy-update-"));
     const projectName = await readProjectName2(projectDirectory);
-    const baseDirectory = join12(temporaryRoot, "base", projectName);
-    const targetDirectory = join12(temporaryRoot, "target", projectName);
+    const baseDirectory = join13(temporaryRoot, "base", projectName);
+    const targetDirectory = join13(temporaryRoot, "target", projectName);
     await generatePublishedBase(temporaryRoot, projectName, provenance, baseDirectory);
     await generateProject({
       sourceRoot: await resolveTemplateRoot(),
@@ -4124,7 +4333,7 @@ class PublishedArtifactProvider {
   }
 }
 async function generatePublishedBase(temporaryRoot, projectName, provenance, expectedDirectory) {
-  const parent = join12(temporaryRoot, "base");
+  const parent = join13(temporaryRoot, "base");
   await mkdir6(parent, { recursive: true });
   const args = [
     "--bun",
@@ -4148,18 +4357,18 @@ async function generatePublishedBase(temporaryRoot, projectName, provenance, exp
     }
   }
   await assertProcess("bunx", args, parent);
-  if (join12(parent, projectName) !== expectedDirectory) {
+  if (join13(parent, projectName) !== expectedDirectory) {
     throw new Error("历史 artifact 生成目录异常");
   }
 }
 async function readProjectName2(projectDirectory) {
-  const source = JSON.parse(await readFile12(join12(projectDirectory, "package.json"), "utf8"));
+  const source = JSON.parse(await readFile13(join13(projectDirectory, "package.json"), "utf8"));
   return source.name || basename4(projectDirectory);
 }
 
 // src/update/planner.ts
-import { access as access3, readFile as readFile14 } from "node:fs/promises";
-import { join as join15 } from "node:path";
+import { access as access3, readFile as readFile15 } from "node:fs/promises";
+import { join as join16 } from "node:path";
 
 // src/update/known-repairs.ts
 var wrongTextVersions = new Set(["0.2.12", "0.2.13"]);
@@ -4202,19 +4411,19 @@ function normalizeTableCell(cell) {
 }
 
 // src/update/merge.ts
-import { mkdtemp as mkdtemp2, rm as rm6, writeFile as writeFile10 } from "node:fs/promises";
+import { mkdtemp as mkdtemp2, rm as rm6, writeFile as writeFile11 } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
-import { join as join13 } from "node:path";
+import { join as join14 } from "node:path";
 async function mergeTextFile(base, ours, theirs) {
-  const root = await mkdtemp2(join13(tmpdir2(), "windy-merge-"));
+  const root = await mkdtemp2(join14(tmpdir2(), "windy-merge-"));
   try {
-    const oursPath = join13(root, "ours");
-    const basePath = join13(root, "base");
-    const theirsPath = join13(root, "theirs");
+    const oursPath = join14(root, "ours");
+    const basePath = join14(root, "base");
+    const theirsPath = join14(root, "theirs");
     await Promise.all([
-      writeFile10(oursPath, ours),
-      writeFile10(basePath, base),
-      writeFile10(theirsPath, theirs)
+      writeFile11(oursPath, ours),
+      writeFile11(basePath, base),
+      writeFile11(theirsPath, theirs)
     ]);
     const result = await captureProcess("git", ["merge-file", "-p", "--diff3", oursPath, basePath, theirsPath], root);
     if (result.code === 0) {
@@ -4382,8 +4591,8 @@ function isTableSeparator(cell) {
 }
 
 // src/update/migration-reconciler.ts
-import { readFile as readFile13 } from "node:fs/promises";
-import { join as join14 } from "node:path";
+import { readFile as readFile14 } from "node:fs/promises";
+import { join as join15 } from "node:path";
 
 // src/update/snapshot-delta.ts
 function applySnapshotDelta(before, after, current, path2, conflicts, conflictPath) {
@@ -4490,7 +4699,7 @@ async function reconcileDrizzleMigrations(input) {
     const tag = `${prefix}_${name}`;
     const sqlPath = `${drizzleRoot}/${tag}.sql`;
     const snapshotPath = `${drizzleRoot}/meta/${prefix}_snapshot.json`;
-    const sql = await readFile13(join14(input.targetDirectory, `${drizzleRoot}/${addition.tag}.sql`));
+    const sql = await readFile14(join15(input.targetDirectory, `${drizzleRoot}/${addition.tag}.sql`));
     merged.id = targetAfter.id;
     merged.prevId = currentSnapshot.id;
     const snapshot = encodeJson(merged);
@@ -4537,13 +4746,13 @@ function unchanged(targetManifest) {
 async function readJournals(input) {
   try {
     const [base, project, target] = await Promise.all([
-      readJson(join14(input.baseDirectory, journalPath)),
-      readJson(join14(input.projectDirectory, journalPath)),
-      readJson(join14(input.targetDirectory, journalPath))
+      readJson(join15(input.baseDirectory, journalPath)),
+      readJson(join15(input.projectDirectory, journalPath)),
+      readJson(join15(input.targetDirectory, journalPath))
     ]);
     return { base, project, target };
   } catch (error) {
-    if (isMissing4(error))
+    if (isMissing5(error))
       return;
     throw error;
   }
@@ -4551,7 +4760,7 @@ async function readJournals(input) {
 async function preservePublishedHistory(manifest, projectDirectory, overrides) {
   const entries = manifest.files.filter(({ path: path2 }) => isMigrationArtifact(path2) && path2 !== journalPath);
   await Promise.all(entries.map(async ({ path: path2 }) => {
-    overrides.set(path2, await readFile13(join14(projectDirectory, path2)));
+    overrides.set(path2, await readFile14(join15(projectDirectory, path2)));
   }));
   return entries;
 }
@@ -4565,7 +4774,7 @@ async function readSnapshot(root, tag) {
   const match = migrationPattern.exec(tag);
   if (!match)
     throw new Error(`${journalPath}：migration tag 格式无效：${tag}`);
-  return await readJson(join14(root, `${drizzleRoot}/meta/${match[1]}_snapshot.json`));
+  return await readJson(join15(root, `${drizzleRoot}/meta/${match[1]}_snapshot.json`));
 }
 function validateUniqueNames(journal, label, conflicts) {
   const seen = new Set;
@@ -4606,9 +4815,9 @@ function encodeJson(value) {
 `);
 }
 async function readJson(path2) {
-  return JSON.parse(await readFile13(path2, "utf8"));
+  return JSON.parse(await readFile14(path2, "utf8"));
 }
-function isMissing4(error) {
+function isMissing5(error) {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 
@@ -4729,9 +4938,9 @@ async function createUpdatePlan(request, artifacts) {
 }
 async function planFile(path2, project, baseRoot, targetRoot, source, target, provenance, targetContentOverride) {
   const [ours, base, theirs] = await Promise.all([
-    readOptional(join15(project, path2)),
-    readOptional(join15(baseRoot, path2)),
-    targetContentOverride ? Promise.resolve(targetContentOverride) : readOptional(join15(targetRoot, path2))
+    readOptional(join16(project, path2)),
+    readOptional(join16(baseRoot, path2)),
+    targetContentOverride ? Promise.resolve(targetContentOverride) : readOptional(join16(targetRoot, path2))
   ]);
   const ownership = target?.ownership || source?.ownership || classifyOwnership(path2);
   const repaired = ours && theirs && provenance ? repairKnownDerivedFile({
@@ -4813,7 +5022,7 @@ function conflict(path2, ownership, reason) {
 }
 async function readOptional(path2) {
   try {
-    return await readFile14(path2);
+    return await readFile15(path2);
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT")
       return;
@@ -4829,7 +5038,7 @@ async function assertGitClean(projectDirectory) {
 }
 async function assertNoPendingUpdate(projectDirectory) {
   try {
-    await access3(join15(projectDirectory, ".windy/update-state.json"));
+    await access3(join16(projectDirectory, ".windy/update-state.json"));
     throw new Error("检测到未完成更新，请先运行 bun run windy doctor --repair");
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT")
@@ -4863,9 +5072,17 @@ class DefaultStarterUpdater {
   async verify(result2) {
     const steps = [];
     try {
+      const dockerSync = await syncWebDockerfileInProject(result2.plan.projectDirectory, { requireAnchors: true });
+      if (dockerSync.changed) {
+        addChangedFile(result2, "apps/web/Dockerfile");
+      }
+      steps.push({
+        name: "同步 Web Dockerfile workspace COPY 清单",
+        status: dockerSync.synced ? "passed" : "skipped"
+      });
       await this.#execute("bun", ["install", "--force"], result2.plan.projectDirectory);
       steps.push({ name: "bun install --force", status: "passed" });
-      const packageJson = JSON.parse(await readFile15(join16(result2.plan.projectDirectory, "package.json"), "utf8"));
+      const packageJson = JSON.parse(await readFile16(join17(result2.plan.projectDirectory, "package.json"), "utf8"));
       for (const name of ["lint", "typecheck", "test", "build"]) {
         if (!packageJson.scripts?.[name]) {
           steps.push({ name: `bun run ${name}`, status: "skipped" });
@@ -4896,12 +5113,12 @@ async function finalize(result2) {
   const root = result2.plan.projectDirectory;
   const generationContent = `${JSON.stringify(result2.plan.targetProvenance, null, 2)}
 `;
-  await writeFile11(join16(root, ".windy/generation.json"), generationContent);
+  await writeFile12(join17(root, ".windy/generation.json"), generationContent);
   const refreshedPaths = new Set([
     ".windy/generation.json",
-    ...result2.plan.files.filter(({ action }) => action === "create" || action === "update").map(({ path: path2 }) => path2)
+    ...result2.changedFiles
   ]);
-  const refreshedHashes = new Map(await Promise.all([...refreshedPaths].map(async (path2) => [path2, hashContent(await readFile15(join16(root, path2)))])));
+  const refreshedHashes = new Map(await Promise.all([...refreshedPaths].map(async (path2) => [path2, hashContent(await readFile16(join17(root, path2)))])));
   const targetManifest = {
     ...result2.plan.targetManifest,
     files: result2.plan.targetManifest.files.map((entry) => ({
@@ -4909,11 +5126,15 @@ async function finalize(result2) {
       hash: refreshedHashes.get(entry.path) ?? entry.hash
     }))
   };
-  await writeFile11(join16(root, ".windy/files.json"), `${JSON.stringify(targetManifest, null, 2)}
+  await writeFile12(join17(root, ".windy/files.json"), `${JSON.stringify(targetManifest, null, 2)}
 `);
 }
+function addChangedFile(result2, path2) {
+  if (!result2.changedFiles.includes(path2))
+    result2.changedFiles.push(path2);
+}
 async function writeReport(result2, steps, relativePath2) {
-  const path2 = join16(result2.plan.projectDirectory, relativePath2);
+  const path2 = join17(result2.plan.projectDirectory, relativePath2);
   await mkdir7(dirname4(path2), { recursive: true });
   const lines = [
     `# Windy 更新报告 ${result2.plan.id}`,
@@ -4931,16 +5152,27 @@ async function writeReport(result2, steps, relativePath2) {
     `备份保留在 \`.windy/backups/${result2.plan.id}\`，确认稳定后可人工删除。`,
     ""
   ];
-  await writeFile11(path2, lines.join(`
+  await writeFile12(path2, lines.join(`
 `));
 }
 
 // src/update/cli.ts
 async function runLifecycleCommand(args) {
   const command = args[0];
-  if (command !== "doctor" && command !== "update")
+  if (command !== "doctor" && command !== "update" && command !== "sync-docker") {
     return false;
+  }
   const projectDirectory = resolve5(readValue2(args, "--cwd") || process.cwd());
+  if (command === "sync-docker") {
+    const result2 = await syncWebDockerfileInProject(projectDirectory, {
+      requireAnchors: true
+    });
+    if (!result2.synced) {
+      throw new Error("项目缺少 apps/web/Dockerfile，无法同步 COPY 清单");
+    }
+    console.log(result2.changed ? "已同步 apps/web/Dockerfile workspace COPY 清单" : "apps/web/Dockerfile workspace COPY 清单已是最新");
+    return true;
+  }
   if (command === "doctor") {
     const report = await diagnoseProject(projectDirectory, args.includes("--repair"));
     printDoctor(report);