create-windy 0.6.17 → 0.6.19

package/dist/cli.js

@@ -3921,6 +3921,8 @@ bun run build
 bun run windy doctor
 bun run windy update --check
 bun run windy update --dry-run
+bun run windy update
+# \u5982\u9700\u5728\u672C\u6B21\u66F4\u65B0\u4E2D\u663E\u5F0F\u6267\u884C\u9879\u76EE\u8D28\u91CF\u811A\u672C\uFF1Abun run windy update --verify
 bun run windy module list
 ${moduleActivationCommands}
 ${includeOxc ? `bun run lint
@@ -3931,11 +3933,12 @@ ${includeOxc ? "\u63D0\u4EA4\u65F6 Husky \u4F1A\u901A\u8FC7 lint-staged \u4E0E O
 
 \u66F4\u65B0\u524D\u65E0\u9700\u63D0\u4EA4\u3001\u6682\u5B58\u6216\u6E05\u7406\u4E1A\u52A1\u6539\u52A8\u3002\`--dry-run\` \u53EA\u751F\u6210\u8BA1\u5212\uFF0C\u4E0D\u5199\u9879\u76EE\uFF1B\u65E0\u5173 WIP
 \u4FDD\u6301\u539F\u6837\uFF0C\u547D\u4E2D\u540C\u4E00\u8DEF\u5F84\u65F6\u6309\u51BB\u7ED3\u5FEB\u7167\u4E0E\u4E09\u65B9\u5408\u5E76 fail closed\u3002\u6B63\u5F0F\u66F4\u65B0\u5148\u5907\u4EFD\uFF0C\u518D\u505A
-package \u5B57\u6BB5\u7EA7\u5408\u5E76\u3001\u5171\u4EAB\u811A\u624B\u67B6\u4E09\u65B9\u5408\u5E76\u4E0E\u5B8C\u6574\u9A8C\u8BC1\u3002\u6574\u4E2A \`apps/web/src\` \u548C
+package \u5B57\u6BB5\u7EA7\u5408\u5E76\u3001\u5171\u4EAB\u811A\u624B\u67B6\u4E09\u65B9\u5408\u5E76\u4E0E\u5B89\u5168\u6536\u53E3\uFF1B\u9ED8\u8BA4\u4E0D\u6267\u884C\u9879\u76EE lint\u3001typecheck\u3001
+test \u6216 build\uFF0C\u4F20\u5165 \`--verify\` \u624D\u663E\u5F0F\u6267\u884C\u5E76\u8BB0\u5F55\u7ED3\u679C\u3002\u6574\u4E2A \`apps/web/src\` \u548C
 \`apps/server/src/app\` \u9ED8\u8BA4\u4FDD\u6301\u9879\u76EE\u7248\u672C\uFF1B\u5DF2\u767B\u8BB0\u7248\u672C recipe \u53EA\u4FEE\u6539\u5176\u58F0\u660E\u7684\u7A84\u951A\u70B9\u3002
 \u4EFB\u4F55\u51B2\u7A81\u90FD\u4F1A\u5728\u5199\u5165\u524D\u4E2D\u6B62\uFF0C\u6A21\u5757\u542F\u505C\u5728\u4EA4\u4E92
 \u7EC8\u7AEF\u786E\u8BA4\uFF1BCI\u3001Agent \u6216\u5176\u5B83\u975E TTY \u73AF\u5883\u5FC5\u987B\u663E\u5F0F\u4F20\u5165 \`--yes\`\u3002
-\u65E0\u5E76\u53D1\u53D8\u5316\u7684\u9A8C\u8BC1\u5931\u8D25\u4F1A\u81EA\u52A8\u56DE\u6EDA\uFF1B\u4E2D\u65AD\u6062\u590D\u4F7F\u7528
+\u5B89\u5168\u68C0\u67E5\u5931\u8D25\u4F1A\u81EA\u52A8\u56DE\u6EDA\uFF1B\u9879\u76EE\u8D28\u91CF\u811A\u672C\u5931\u8D25\u672C\u8EAB\u4E0D\u56DE\u6EDA\u5DF2\u5B89\u5168\u5E94\u7528\u7684\u66F4\u65B0\u3002\u4E2D\u65AD\u6062\u590D\u4F7F\u7528
 \`bun run windy doctor --repair\`\u3002\u8BE5\u547D\u4EE4\u5728\u63D0\u4EA4\u70B9\u524D\u4FDD\u7559\u5E76\u53D1\u7F16\u8F91\u5E76\u56DE\u6EDA\u5176\u4F59\u8DEF\u5F84\uFF0C
 \u5728 committed \u63D0\u4EA4\u70B9\u540E\u53EA\u5B8C\u6210\u4E8B\u52A1\u72B6\u6001\u4E0E\u5907\u4EFD\u6E05\u7406\uFF0C\u4E0D\u56DE\u6EDA\u9879\u76EE\u6587\u4EF6\u3002
 
@@ -8487,6 +8490,16 @@ var recipes = [
     id: "starter-0.6.16-to-0.6.17",
     from: "0.6.16",
     to: "0.6.17"
+  },
+  {
+    id: "starter-0.6.17-to-0.6.18",
+    from: "0.6.17",
+    to: "0.6.18"
+  },
+  {
+    id: "starter-0.6.18-to-0.6.19",
+    from: "0.6.18",
+    to: "0.6.19"
   }
 ];
 function resolveRecipeChain(sourceVersion, targetVersion) {
@@ -8532,8 +8545,7 @@ function parseVersion2(version) {
 }
 
 // src/update/updater.ts
-import { readFile as readFile24, rm as rm8 } from "fs/promises";
-import { join as join29 } from "path";
+import { rm as rm8 } from "fs/promises";
 
 // src/update/artifacts.ts
 import { mkdtemp, readFile as readFile15 } from "fs/promises";
@@ -10854,12 +10866,48 @@ function safeTemporaryPath(root, path2) {
   return target;
 }
 
+// src/update/project-quality-verification.ts
+import { readFile as readFile24 } from "fs/promises";
+import { join as join29 } from "path";
+var qualityScriptNames = ["lint", "typecheck", "test", "build"];
+function skippedProjectQualityVerification() {
+  return {
+    status: "skipped",
+    steps: [
+      {
+        name: "\u9879\u76EE\u8D28\u91CF\u9A8C\u8BC1\uFF08lint/typecheck/test/build\uFF09",
+        status: "skipped"
+      }
+    ]
+  };
+}
+async function runProjectQualityVerification(projectDirectory, execute) {
+  const packageJson = JSON.parse(await readFile24(join29(projectDirectory, "package.json"), "utf8"));
+  const steps = [];
+  for (const name of qualityScriptNames) {
+    const stepName = `bun run ${name}`;
+    if (!packageJson.scripts?.[name]) {
+      steps.push({ name: stepName, status: "skipped" });
+      continue;
+    }
+    try {
+      await execute("bun", ["run", name], projectDirectory);
+      steps.push({ name: stepName, status: "passed" });
+    } catch {
+      steps.push({ name: stepName, status: "failed" });
+      return { status: "failed", steps };
+    }
+  }
+  return { status: "passed", steps };
+}
+
 // src/update/updater-report.ts
-async function writeUpdateReport(result2, steps, relativePath2, expected) {
+async function writeUpdateReport(result2, steps, projectQualityVerification, relativePath2, expected) {
   const lines = [
     `# Windy \u66F4\u65B0\u62A5\u544A ${result2.plan.id}`,
     "",
-    "- \u9A8C\u8BC1\u72B6\u6001\uFF1A\u5DF2\u901A\u8FC7\uFF1B\u4E8B\u52A1\u7ED3\u679C\u4EE5 update-state \u6700\u7EC8\u63D0\u4EA4\u4E3A\u51C6",
+    "- \u5B89\u5168\u63D0\u4EA4\u72B6\u6001\uFF1A\u5DF2\u901A\u8FC7\uFF1B\u4E8B\u52A1\u7ED3\u679C\u4EE5 update-state \u6700\u7EC8\u63D0\u4EA4\u4E3A\u51C6",
+    `- \u9879\u76EE\u8D28\u91CF\u9A8C\u8BC1\uFF1A${qualityStatusLabel(projectQualityVerification)}`,
     `- \u6765\u6E90\u7248\u672C\uFF1A${result2.plan.sourceVersion}`,
     `- \u76EE\u6807\u7248\u672C\uFF1A${result2.plan.targetVersion}`,
     `- Recipe\uFF1A${result2.plan.recipes.join("\u3001") || "\u65E0"}`,
@@ -10878,10 +10926,14 @@ async function writeUpdateReport(result2, steps, relativePath2, expected) {
       ...result2.plan.manualCleanup.map(({ message }) => `- ${message}`)
     ] : [],
     "",
-    "## \u9A8C\u8BC1",
+    "## \u5B89\u5168\u68C0\u67E5\u4E0E\u53EF\u9009\u9A8C\u8BC1",
     "",
     ...steps.map(({ name, status }) => `- ${name}\uFF1A${status}`),
     "",
+    ...projectQualityVerification === "skipped" ? [
+      "\u672C\u6B21\u66F4\u65B0\u672A\u6267\u884C\u9879\u76EE\u7EA7 lint/typecheck/test/build\u3002\u9700\u8981\u5B8C\u6574\u8D28\u91CF\u9A8C\u8BC1\u65F6\uFF0C\u8BF7\u5728\u9879\u76EE\u6839\u76EE\u5F55\u6309\u5B9E\u9645\u5B58\u5728\u7684\u811A\u672C\u663E\u5F0F\u8FD0\u884C\u8FD9\u4E9B\u547D\u4EE4\u3002",
+      ""
+    ] : [],
     "\u4E8B\u52A1\u63D0\u4EA4\u540E\u81EA\u52A8\u6E05\u7406\u5907\u4EFD\uFF1B\u82E5\u63D0\u793A\u6E05\u7406\u5F85\u5B8C\u6210\uFF0C\u8BF7\u8FD0\u884C `bun run windy doctor --repair`\u3002",
     ""
   ];
@@ -10890,6 +10942,13 @@ async function writeUpdateReport(result2, steps, relativePath2, expected) {
   await writeOwnedTransactionFile(result2.plan.projectDirectory, relativePath2, content, expected);
   return expectationForContent(relativePath2, content);
 }
+function qualityStatusLabel(status) {
+  if (status === "passed")
+    return "\u5DF2\u901A\u8FC7\uFF08\u663E\u5F0F --verify\uFF09";
+  if (status === "failed")
+    return "\u672A\u901A\u8FC7\uFF1B\u5347\u7EA7\u4ECD\u6309\u5B89\u5168\u68C0\u67E5\u7ED3\u679C\u63D0\u4EA4";
+  return "\u5DF2\u8DF3\u8FC7\uFF08\u9ED8\u8BA4\u4E0D\u6267\u884C lint/typecheck/test/build\uFF09";
+}
 
 // src/update/updater.ts
 class DefaultStarterUpdater {
@@ -10898,12 +10957,14 @@ class DefaultStarterUpdater {
   #beforeTransactionFinalize;
   #finalizeTransaction;
   #skipInstall;
+  #verifyProject;
   constructor(dependencies = {}) {
     this.#artifacts = dependencies.artifacts ?? new PublishedArtifactProvider;
     this.#execute = dependencies.execute ?? runCommand;
     this.#beforeTransactionFinalize = dependencies.beforeTransactionFinalize;
     this.#finalizeTransaction = dependencies.finalizeTransaction ?? finalizeOwnedTransaction;
     this.#skipInstall = dependencies.skipInstall ?? false;
+    this.#verifyProject = dependencies.verifyProject ?? false;
   }
   async plan(input) {
     return createUpdatePlan(input, this.#artifacts);
@@ -10974,18 +11035,11 @@ class DefaultStarterUpdater {
       const plannedPaths = new Set(result2.plan.files.map(({ path: path2 }) => path2));
       replaceExpectations(result2, verificationSnapshot.filter(({ path: path2 }) => !metadataPaths2.has(path2) && !plannedPaths.has(path2)));
       verificationExpectationsFrozen = true;
-      const packageJson = JSON.parse(await readFile24(join29(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" });
-          continue;
-        }
-        await this.#execute("bun", ["run", name], result2.plan.projectDirectory);
-        steps.push({ name: `bun run ${name}`, status: "passed" });
-      }
+      const projectQualityVerification = this.#verifyProject ? await runProjectQualityVerification(result2.plan.projectDirectory, this.#execute) : skippedProjectQualityVerification();
+      steps.push(...projectQualityVerification.steps);
       const metadataExpectations = await finalize(result2, stabilized);
       const reportPath = `.windy/reports/${result2.plan.id}.md`;
-      const reportExpectation = await writeUpdateReport(result2, steps, reportPath, expectedForPath(result2, reportPath));
+      const reportExpectation = await writeUpdateReport(result2, steps, projectQualityVerification.status, reportPath, expectedForPath(result2, reportPath));
       replaceExpectations(result2, [...metadataExpectations, reportExpectation]);
       await rm8(result2.plan.temporaryRoot, { recursive: true, force: true });
       await this.#beforeTransactionFinalize?.({ result: result2, reportPath });
@@ -10995,7 +11049,13 @@ class DefaultStarterUpdater {
         expectations: result2.finalizationExpectations,
         workspaceMembershipExpectations: result2.plan.finalWorkspaceMembershipExpectations ?? result2.plan.workspaceMembershipExpectations
       });
-      return { updateId: result2.plan.id, status: "passed", steps, reportPath };
+      return {
+        updateId: result2.plan.id,
+        status: "passed",
+        projectQualityVerification: projectQualityVerification.status,
+        steps,
+        reportPath
+      };
     } catch (error) {
       await rm8(result2.plan.temporaryRoot, { recursive: true, force: true });
       if (error instanceof TransactionCommittedCleanupPendingError) {
@@ -11008,7 +11068,7 @@ class DefaultStarterUpdater {
       if (verificationExpectationsFrozen) {
         const conflicts = await retainOwnedTransactionExpectationConflicts(result2.plan.projectDirectory, result2.transactionOwnerToken, result2.finalizationExpectations);
         if (conflicts.length) {
-          throw new Error(`\u66F4\u65B0\u9A8C\u8BC1\u671F\u95F4\u68C0\u6D4B\u5230\u5E76\u53D1\u4FEE\u6539\uFF0C\u4E8B\u52A1\u73B0\u573A\u5DF2\u4FDD\u7559\uFF1A${conflicts.join("\u3001")}`, { cause: error });
+          throw new Error(`\u66F4\u65B0\u5B89\u5168\u6536\u53E3\u671F\u95F4\u68C0\u6D4B\u5230\u5E76\u53D1\u4FEE\u6539\uFF0C\u4E8B\u52A1\u73B0\u573A\u5DF2\u4FDD\u7559\uFF1A${conflicts.join("\u3001")}`, { cause: error });
         }
       }
       await restoreUpdateState(result2.plan.projectDirectory, {
@@ -11020,7 +11080,7 @@ class DefaultStarterUpdater {
         phase: "ready",
         manifestHash: result2.expectedManifestHash
       });
-      throw new Error(`\u66F4\u65B0\u9A8C\u8BC1\u5931\u8D25\uFF0C\u9879\u76EE\u5DF2\u56DE\u6EDA\u5230 ${result2.plan.sourceVersion}\uFF1A${error instanceof Error ? error.message : String(error)}`, { cause: error });
+      throw new Error(`\u66F4\u65B0\u5B89\u5168\u68C0\u67E5\u5931\u8D25\uFF0C\u9879\u76EE\u5DF2\u56DE\u6EDA\u5230 ${result2.plan.sourceVersion}\uFF1A${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
   }
 }
@@ -11666,6 +11726,20 @@ function actionLabel(action) {
   return action === "add" ? "\u5B89\u88C5" : action === "update" ? "\u66F4\u65B0" : "\u5378\u8F7D";
 }
 
+// src/update/cli-quality-output.ts
+function printProjectQualityVerification(status) {
+  if (status === "passed") {
+    console.log("\u9879\u76EE\u8D28\u91CF\u9A8C\u8BC1\uFF1A\u5DF2\u901A\u8FC7\uFF08\u663E\u5F0F --verify\uFF09");
+    return;
+  }
+  if (status === "failed") {
+    console.error("\u9879\u76EE\u8D28\u91CF\u9A8C\u8BC1\uFF1A\u672A\u901A\u8FC7\uFF1B\u5347\u7EA7\u5DF2\u5B89\u5168\u63D0\u4EA4\uFF0C\u8BF7\u67E5\u770B\u4E0A\u65B9\u5931\u8D25\u547D\u4EE4\u548C\u66F4\u65B0\u62A5\u544A");
+    process.exitCode = 1;
+    return;
+  }
+  console.log("\u9879\u76EE\u8D28\u91CF\u9A8C\u8BC1\uFF1A\u5DF2\u8DF3\u8FC7\uFF1B\u53EF\u6309\u9700\u663E\u5F0F\u8FD0\u884C lint\u3001typecheck\u3001test \u548C build");
+}
+
 // src/update/cli.ts
 async function runLifecycleCommand(args, dependencies = {}) {
   const command = args[0];
@@ -11740,6 +11814,7 @@ var updateHelpText = `\u7528\u6CD5\uFF1Acreate-windy update [\u9009\u9879]
   --to <\u7248\u672C>                   \u66F4\u65B0\u5230\u6307\u5B9A\u7248\u672C
   --cwd <\u76EE\u5F55>                  \u6307\u5B9A\u9879\u76EE\u76EE\u5F55
   --skip-install                \u66F4\u65B0\u65F6\u4E0D\u6267\u884C bun install
+  --verify                      \u663E\u5F0F\u6267\u884C\u9879\u76EE lint/typecheck/test/build
   --force                       \u5F3A\u5236\u91C7\u7528\u5E73\u53F0\u57FA\u7EBF\u53C2\u4E0E\u4E09\u65B9\u5408\u5E76
   -h, --help                    \u663E\u793A update \u5E2E\u52A9\u5E76\u9000\u51FA
 `;
@@ -11772,7 +11847,8 @@ async function runUpdate(args, projectDirectory) {
     return;
   }
   const updater = new DefaultStarterUpdater({
-    skipInstall: args.includes("--skip-install")
+    skipInstall: args.includes("--skip-install"),
+    verifyProject: args.includes("--verify")
   });
   const plan = await updater.plan({
     projectDirectory,
@@ -11795,6 +11871,7 @@ async function runUpdate(args, projectDirectory) {
   const environmentRepair = await repairLocalEnvironment(projectDirectory);
   console.log(`
 \u66F4\u65B0\u5B8C\u6210\uFF1A${plan.sourceVersion} \u2192 ${plan.targetVersion}`);
+  printProjectQualityVerification(report.projectQualityVerification);
   console.log(`\u62A5\u544A\uFF1A${report.reportPath}`);
   printEnvironmentRepair(environmentRepair);
   if (environmentRepair.missingKeys.length || environmentRepair.duplicateKeys.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.6.17",
+  "version": "0.6.19",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "4b392b4ca9083489e1a2134c55f3eb1c8ca638ad",
-  "generatorVersion": "0.6.17",
+  "templateCommit": "f2e5ced778480dc66e9dd03dd79023b9eda766a1",
+  "generatorVersion": "0.6.19",
   "modules": [
     {
       "name": "system",

package/template/README.md

@@ -160,6 +160,8 @@ bun run build
 bun run windy doctor
 bun run windy update --check
 bun run windy update --dry-run
+bun run windy update
+# 如需在本次更新中显式执行项目质量脚本：bun run windy update --verify
 bun run windy module list
 # 当前组合没有可安全 runtime disable 的已安装可选模块
 bun run lint
@@ -170,11 +172,12 @@ bun run format
 
 更新前无需提交、暂存或清理业务改动。`--dry-run` 只生成计划，不写项目；无关 WIP
 保持原样，命中同一路径时按冻结快照与三方合并 fail closed。正式更新先备份，再做
-package 字段级合并、共享脚手架三方合并与完整验证。整个 `apps/web/src` 和
+package 字段级合并、共享脚手架三方合并与安全收口；默认不执行项目 lint、typecheck、
+test 或 build，传入 `--verify` 才显式执行并记录结果。整个 `apps/web/src` 和
 `apps/server/src/app` 默认保持项目版本；已登记版本 recipe 只修改其声明的窄锚点。
 任何冲突都会在写入前中止，模块启停在交互
 终端确认；CI、Agent 或其它非 TTY 环境必须显式传入 `--yes`。
-无并发变化的验证失败会自动回滚；中断恢复使用
+安全检查失败会自动回滚；项目质量脚本失败本身不回滚已安全应用的更新。中断恢复使用
 `bun run windy doctor --repair`。该命令在提交点前保留并发编辑并回滚其余路径，
 在 committed 提交点后只完成事务状态与备份清理，不回滚项目文件。
 

package/template/apps/agent-server/README.md

@@ -15,6 +15,7 @@ uv run mypy
 
 HTTP 接口：
 
+- `GET /api/agent/runtime/compatibility`（内部认证、V1 协议 Offer）
 - `POST /api/agent/runs`
 - `GET /api/agent/runs/:runId/events`
 - `GET /api/agent/runs/:runId/result`
@@ -24,6 +25,11 @@ Run 创建使用 `Idempotency-Key`。事件以 SSE 传输，支持 `Last-Event-I
 断线重放，并周期发送 comment heartbeat。Provider 或 Engine 异常只映射为 canonical
 安全错误，不把原始异常正文暴露给调用方。
 
+兼容 Offer 返回 Engine identity、支持的协议版本、传输能力、callback auth profile 及三层摘要。
+新 Windy Server 会在 Run 请求头固定所选版本和 Offer digest；新 Agent Server 仍接受完全不带 pin
+的旧调用方，但拒绝半套或不匹配 pin。它只用于同一受控部署，不能把内部 token 发给外部业务系统。
+跨系统限制见 [Remote Agent Runtime 兼容契约](../../docs/architecture/agent-runtime-compatibility.md)。
+
 配置以下仅服务端可见的环境变量后启用 Direct Engine：
 
 ```bash

package/template/apps/agent-server/src/southwind_agent_server/app.py

@@ -34,6 +34,12 @@ from .http_helpers import (
 )
 from .report_routes import create_report_router
 from .report_store import AgentRuntimeReportStore
+from .runtime_compatibility import (
+    OFFER_DIGEST_HEADER,
+    PROTOCOL_HEADER,
+    RuntimeCompatibilityError,
+    validate_runtime_compatibility_pin,
+)
 from .runtime_factory import (
     default_engine,
     default_report_store,
@@ -191,11 +197,28 @@ def create_app(
         request: StartRunRequest,
         idempotency_key: Annotated[str, Header(alias="Idempotency-Key")],
         authorization: Annotated[str | None, Header()] = None,
+        runtime_protocol: Annotated[str | None, Header(alias=PROTOCOL_HEADER)] = None,
+        runtime_offer_digest: Annotated[
+            str | None, Header(alias=OFFER_DIGEST_HEADER)
+        ] = None,
     ) -> StartRunResponse | JSONResponse:
         if not authorized(authorization, internal_token):
             return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
         if not idempotency_key.strip():
             return safe_error(400, "INVALID_INPUT", "幂等键不能为空", False)
+        try:
+            validate_runtime_compatibility_pin(
+                runtime_protocol,
+                runtime_offer_digest,
+                runtime_engine.engine_id,
+            )
+        except RuntimeCompatibilityError:
+            return safe_error(
+                409,
+                "RUNTIME_UNAVAILABLE",
+                "Agent Runtime compatibility pin 不匹配",
+                False,
+            )
         try:
             await require_vision_readiness(runtime_engine, request)
         except SafeEngineError as error:

package/template/apps/agent-server/src/southwind_agent_server/health_routes.py

@@ -7,6 +7,7 @@ from fastapi import FastAPI, Header
 from fastapi.responses import JSONResponse
 
 from .http_helpers import authorized, safe_error
+from .runtime_compatibility import COMPATIBILITY_PATH, runtime_compatibility_offer
 from .service import AgentRunService
 from .vlm_readiness import unavailable_vlm_snapshot
 
@@ -82,3 +83,11 @@ def install_health_routes(
                 "Agent Runtime Model coordinate 不可用",
                 True,
             )
+
+    @application.get(COMPATIBILITY_PATH, response_model=None)
+    async def runtime_compatibility(
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> dict[str, object] | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        return runtime_compatibility_offer(runtime.engine.engine_id)

package/template/apps/agent-server/src/southwind_agent_server/runtime_compatibility.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+
+SCHEMA_VERSION = 1
+PROTOCOL_VERSION = 1
+RUNTIME_KIND = "agent"
+COMPATIBILITY_PATH = "/api/agent/runtime/compatibility"
+PROTOCOL_HEADER = "X-Windy-Agent-Runtime-Protocol"
+OFFER_DIGEST_HEADER = "X-Windy-Agent-Runtime-Offer-Digest"
+TOOL_CALLBACK_CONTRACT_VERSION = 1
+TOOL_CALLBACK_AUTHENTICATION = "windy-internal-bearer-v1"
+PROTOCOL_FEATURES = (
+    "canonical-sse-replay.v1",
+    "execution-grant-forwarding.v1",
+    "operation-release-attestation.v1",
+    "run-cancel.v1",
+    "run-lifecycle.v1",
+    "runtime-reporting.v1",
+    "tool-callback.v1",
+)
+
+_STABLE_VALUE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,159}$")
+
+
+class RuntimeCompatibilityError(ValueError):
+    pass
+
+
+def runtime_compatibility_offer(engine_id: str) -> dict[str, object]:
+    if not _STABLE_VALUE.fullmatch(engine_id):
+        raise RuntimeCompatibilityError("Agent Runtime engineId invalid")
+    protocol_versions = [PROTOCOL_VERSION]
+    protocol_features = sorted(PROTOCOL_FEATURES)
+    tool_callback: dict[str, object] = {
+        "contractVersion": TOOL_CALLBACK_CONTRACT_VERSION,
+        "authentication": TOOL_CALLBACK_AUTHENTICATION,
+    }
+    release_digest = _digest(
+        {
+            "runtimeKind": RUNTIME_KIND,
+            "engineId": engine_id,
+            "protocolVersions": protocol_versions,
+        }
+    )
+    capabilities_digest = _digest(
+        {
+            "protocolFeatures": protocol_features,
+            "toolCallback": tool_callback,
+        }
+    )
+    body: dict[str, object] = {
+        "schemaVersion": SCHEMA_VERSION,
+        "runtimeKind": RUNTIME_KIND,
+        "engineId": engine_id,
+        "protocolVersions": protocol_versions,
+        "protocolFeatures": protocol_features,
+        "toolCallback": tool_callback,
+        "releaseDigest": release_digest,
+        "capabilitiesDigest": capabilities_digest,
+    }
+    return {**body, "offerDigest": _digest(body)}
+
+
+def validate_runtime_compatibility_pin(
+    protocol_header: str | None,
+    offer_digest_header: str | None,
+    engine_id: str,
+) -> None:
+    if protocol_header is None and offer_digest_header is None:
+        return
+    if protocol_header is None or offer_digest_header is None:
+        raise RuntimeCompatibilityError("Agent Runtime compatibility pin incomplete")
+    if protocol_header != str(PROTOCOL_VERSION):
+        raise RuntimeCompatibilityError("Agent Runtime protocol unsupported")
+    expected = runtime_compatibility_offer(engine_id)["offerDigest"]
+    if offer_digest_header != expected:
+        raise RuntimeCompatibilityError("Agent Runtime offer digest mismatch")
+
+
+def _digest(value: object) -> str:
+    encoded = json.dumps(
+        value,
+        ensure_ascii=False,
+        separators=(",", ":"),
+    ).encode()
+    return f"sha256:{hashlib.sha256(encoded).hexdigest()}"

package/template/apps/agent-server/tests/test_runtime_compatibility.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import cast
+
+import httpx
+import pytest
+
+from southwind_agent_server.app import create_app
+from southwind_agent_server.deterministic import DeterministicEngineAdapter
+from southwind_agent_server.runtime_compatibility import (
+    runtime_compatibility_offer,
+)
+
+TOKEN = "runtime-compatibility-test-token"
+
+
+@pytest.fixture
+async def client() -> AsyncIterator[httpx.AsyncClient]:
+    app = create_app(DeterministicEngineAdapter(), internal_token=TOKEN)
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app),
+        base_url="http://agent.test",
+    ) as value:
+        yield value
+
+
+async def test_compatibility_offer_is_authenticated_and_matches_public_fixture(
+    client: httpx.AsyncClient,
+) -> None:
+    denied = await client.get("/api/agent/runtime/compatibility")
+    allowed = await client.get(
+        "/api/agent/runtime/compatibility",
+        headers={"Authorization": f"Bearer {TOKEN}"},
+    )
+
+    assert denied.status_code == 403
+    assert allowed.status_code == 200
+    assert allowed.json() == public_fixture()
+
+
+async def test_start_accepts_legacy_without_pin(
+    client: httpx.AsyncClient,
+) -> None:
+    legacy = await start(client, "legacy-pin")
+
+    assert legacy.status_code == 200
+
+
+async def test_start_accepts_complete_matching_pin(
+    client: httpx.AsyncClient,
+) -> None:
+    offer = runtime_compatibility_offer("windy.direct.openai-compatible.v1")
+    pinned = await start(
+        client,
+        "current-pin",
+        {
+            "X-Windy-Agent-Runtime-Protocol": "1",
+            "X-Windy-Agent-Runtime-Offer-Digest": str(offer["offerDigest"]),
+        },
+    )
+
+    assert pinned.status_code == 200
+
+
+@pytest.mark.parametrize(
+    "headers",
+    [
+        {"X-Windy-Agent-Runtime-Protocol": "1"},
+        {"X-Windy-Agent-Runtime-Offer-Digest": "sha256:" + "0" * 64},
+        {
+            "X-Windy-Agent-Runtime-Protocol": "2",
+            "X-Windy-Agent-Runtime-Offer-Digest": "sha256:" + "0" * 64,
+        },
+        {
+            "X-Windy-Agent-Runtime-Protocol": "1",
+            "X-Windy-Agent-Runtime-Offer-Digest": "sha256:" + "0" * 64,
+        },
+    ],
+)
+async def test_start_rejects_partial_or_incompatible_pin_before_admission(
+    client: httpx.AsyncClient,
+    headers: dict[str, str],
+) -> None:
+    response = await start(client, "rejected-pin", headers)
+
+    assert response.status_code == 409
+    assert response.json() == {
+        "code": "RUNTIME_UNAVAILABLE",
+        "message": "Agent Runtime compatibility pin 不匹配",
+        "requestId": response.json()["requestId"],
+        "retryable": False,
+    }
+
+
+async def start(
+    client: httpx.AsyncClient,
+    key: str,
+    headers: dict[str, str] | None = None,
+) -> httpx.Response:
+    return await client.post(
+        "/api/agent/runs",
+        headers={
+            "Authorization": f"Bearer {TOKEN}",
+            "Idempotency-Key": key,
+            **(headers or {}),
+        },
+        json={"operationKey": "test.echo", "input": {"text": key}},
+    )
+
+
+def public_fixture() -> dict[str, object]:
+    path = (
+        Path(__file__).parents[3]
+        / "packages/server-sdk/contracts/agent-runtime-compatibility/v1/offer.json"
+    )
+    return cast(dict[str, object], json.loads(path.read_text(encoding="utf8")))