create-windy 0.2.30 → 0.2.32

package/dist/cli.js

@@ -1114,7 +1114,7 @@ function rewriteCustomerDockerfile(source) {
     return !supplierWorkspaceCopies.includes(line) && !supplierWorkspacePaths.some((path) => line.includes(path)) && !line.includes("deploy/production/server-entrypoint.sh");
   });
   return lines.join(`
-`).replace("COPY package.json bun.lock ./", "COPY package.json ./").replace("RUN bun install --frozen-lockfile", "RUN bun install");
+`);
 }
 
 // src/code-quality.ts
@@ -1585,6 +1585,7 @@ var agentComposeService = `  agent-server:
       QWEN_API_URL: \${QWEN_API_URL:-}
       QWEN_API_KEY: \${QWEN_API_KEY:-}
       QWEN_MODEL: \${QWEN_MODEL:-}
+      AI_PROVIDER_HTTPS_HOST_ALLOWLIST: \${AI_PROVIDER_HTTPS_HOST_ALLOWLIST:-}
       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}
@@ -1606,12 +1607,13 @@ function environmentExample(includeExample, includeAgent = true) {
 POSTGRES_PASSWORD=
 WINDY_BOOTSTRAP_ADMIN_PASSWORD=
 ${includeAgent ? `
-# Agent profile 仅由 Server 读取；不要使用 VITE_ 前缀。
+# Agent profile 仅由服务端 Agent Runtime 读取；不要使用 VITE_ 前缀。
 PLATFORM_ENABLE_AI=false
 AGENT_SERVER_INTERNAL_TOKEN=
 QWEN_API_URL=
 QWEN_API_KEY=
 QWEN_MODEL=
+AI_PROVIDER_HTTPS_HOST_ALLOWLIST=
 # AI_PROVIDER_CONNECT_TIMEOUT_MS=5000
 # AI_PROVIDER_REQUEST_TIMEOUT_MS=60000
 # AI_PROVIDER_MAX_RESPONSE_BYTES=2097152
@@ -1712,7 +1714,9 @@ bun run dev:agent
 \`\`\`
 
 公网 Provider URL 必须使用 HTTPS；本机、容器服务名和内网地址允许 HTTP。
-\`QWEN_API_KEY\` 只进入 Agent Server，不会进入 Web 环境或返回给客户端。运行与模块
+\`QWEN_API_KEY\`、Endpoint 和 Host allowlist 只进入 Agent Server，不会进入 Web
+环境或返回给客户端。公网 HTTPS Endpoint 的主机必须显式加入
+\`AI_PROVIDER_HTTPS_HOST_ALLOWLIST\`。运行与模块
 接入细节见 [Agent Runtime 接入](./docs/platform/agent-runtime.md)。
 
 MCP 客户端使用 \`http://localhost:9747/api/mcp\`，并通过平台 Bearer Token 或 Session
@@ -1913,6 +1917,7 @@ var templateDirectories = [
 var templateDocumentationFiles = [
   "docs/adapters/ruoyi-vue-compatibility.md",
   "docs/architecture/admin-surface-boundary.md",
+  "docs/architecture/ai-egress.md",
   "docs/architecture/ai-runtime.md",
   "docs/architecture/data-scope-query-enforcement.md",
   "docs/architecture/durable-jobs.md",
@@ -4355,7 +4360,9 @@ var recipes = [
   { id: "starter-0.2.26-to-0.2.27", from: "0.2.26", to: "0.2.27" },
   { id: "starter-0.2.27-to-0.2.28", from: "0.2.27", to: "0.2.28" },
   { id: "starter-0.2.28-to-0.2.29", from: "0.2.28", to: "0.2.29" },
-  { id: "starter-0.2.29-to-0.2.30", from: "0.2.29", to: "0.2.30" }
+  { id: "starter-0.2.29-to-0.2.30", from: "0.2.29", to: "0.2.30" },
+  { id: "starter-0.2.30-to-0.2.31", from: "0.2.30", to: "0.2.31" },
+  { id: "starter-0.2.31-to-0.2.32", from: "0.2.31", to: "0.2.32" }
 ];
 function resolveRecipeChain(sourceVersion, targetVersion) {
   if (sourceVersion === targetVersion)

package/package.json

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

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "c61be0fc258ae679c0c0b43d7a838688985d7f0f",
-  "generatorVersion": "0.2.30",
+  "templateCommit": "70938ba644c8fdebec29f8bf24439ccf141f2336",
+  "generatorVersion": "0.2.32",
   "modules": [
     {
       "name": "system",

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

@@ -30,12 +30,14 @@ export AGENT_SERVER_INTERNAL_TOKEN='<random-token>'
 export QWEN_API_URL='https://dashscope-intl.aliyuncs.com/compatible-mode/v1'
 export QWEN_API_KEY='<server-secret>'
 export QWEN_MODEL='qwen-plus'
+export AI_PROVIDER_HTTPS_HOST_ALLOWLIST='dashscope-intl.aliyuncs.com'
 export AGENT_RUN_STORE_PATH='.data/agent-runs.sqlite3'
 uv run uvicorn southwind_agent_server.app:app
 ```
 
-公网 URL 必须使用 HTTPS，本机、容器服务名和内网地址允许 HTTP。Provider 请求包含连接
-和总超时、响应大小限制、错误脱敏与 `/models` readiness。缺少 URL/Model 时回退
+公网 URL 必须使用 HTTPS 且 Host 精确命中 allowlist；本机、容器服务名和内网地址允许
+HTTP。Provider 请求包含连接和总超时、响应大小限制、错误脱敏与 `/models`
+readiness。缺少 URL/Model 时回退
 `AdkEngineAdapter` 并返回 unavailable，不调用模型。测试另使用
 `DeterministicEngineAdapter`。
 

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

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import ipaddress
 import os
+import re
 from collections.abc import Mapping
 from dataclasses import dataclass
 from urllib.parse import urlsplit, urlunsplit
@@ -35,6 +36,13 @@ class OpenAiCompatibleConfig:
     request_timeout_seconds: float = 60.0
     max_response_bytes: int = 2 * 1024 * 1024
     max_tool_rounds: int = 8
+    https_host_allowlist: tuple[str, ...] = ()
+    deployment_key: str = "ai.openai-compatible"
+
+    def __post_init__(self) -> None:
+        normalized = normalize_base_url(self.base_url)
+        object.__setattr__(self, "base_url", normalized)
+        require_allowed_https_host(normalized, self.https_host_allowlist)
 
     @classmethod
     def from_environment(
@@ -55,6 +63,9 @@ class OpenAiCompatibleConfig:
                 if environment.get("QWEN_API_KEY", "").strip()
                 else None
             ),
+            https_host_allowlist=normalize_https_host_allowlist(
+                environment.get("AI_PROVIDER_HTTPS_HOST_ALLOWLIST", "")
+            ),
             connect_timeout_seconds=read_milliseconds(
                 environment,
                 "AI_PROVIDER_CONNECT_TIMEOUT_MS",
@@ -100,6 +111,43 @@ def normalize_base_url(raw: str) -> str:
     return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
 
 
+def normalize_https_host_allowlist(raw: str) -> tuple[str, ...]:
+    hosts: list[str] = []
+    for item in raw.split(","):
+        candidate = item.strip().lower().rstrip(".")
+        if not candidate:
+            continue
+        if candidate in hosts or not valid_hostname(candidate):
+            raise ValueError("Provider HTTPS Host allowlist 无效")
+        hosts.append(candidate)
+    return tuple(hosts)
+
+
+def require_allowed_https_host(
+    base_url: str,
+    allowed_hosts: tuple[str, ...],
+) -> None:
+    endpoint = urlsplit(base_url)
+    hostname = (endpoint.hostname or "").lower().rstrip(".")
+    if endpoint.scheme == "https" and hostname not in allowed_hosts:
+        raise ValueError("OpenAI-compatible Endpoint 未命中 HTTPS Host allowlist")
+
+
+def valid_hostname(value: str) -> bool:
+    try:
+        ipaddress.ip_address(value)
+        return True
+    except ValueError:
+        return bool(
+            len(value) <= 253
+            and re.fullmatch(
+                r"(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*"
+                r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?",
+                value,
+            )
+        )
+
+
 def private_hostname(hostname: str) -> bool:
     if (
         hostname == "localhost"

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

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-from typing import Literal
+from typing import Literal, Self
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 type JsonValue = (
     str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]
@@ -60,6 +60,24 @@ class RuntimeLimits(CanonicalModel):
     max_output_bytes: int = Field(default=1_048_576, ge=1_024, le=16_777_216)
 
 
+class ProviderEgress(CanonicalModel):
+    mode: Literal["forbidden", "configured-endpoint"] = "forbidden"
+    deployment_key: str | None = None
+
+    @model_validator(mode="after")
+    def validate_deployment(self) -> Self:
+        if self.mode == "configured-endpoint":
+            if not self.deployment_key or not self.deployment_key.strip():
+                raise ValueError("Provider Deployment Key 缺失")
+        elif self.deployment_key is not None:
+            raise ValueError("禁止出网时不能指定 Provider Deployment")
+        return self
+
+
+class ToolNetworkPolicy(CanonicalModel):
+    mode: Literal["forbidden"] = "forbidden"
+
+
 class StartRunRequest(CanonicalModel):
     operation_key: str = Field(min_length=1)
     input: JsonValue
@@ -67,6 +85,8 @@ class StartRunRequest(CanonicalModel):
     user_prompt: str = ""
     allowed_tools: list[RuntimeToolDefinition] = Field(default_factory=list)
     limits: RuntimeLimits = Field(default_factory=RuntimeLimits)
+    provider_egress: ProviderEgress = Field(default_factory=ProviderEgress)
+    tool_network_policy: ToolNetworkPolicy = Field(default_factory=ToolNetworkPolicy)
     execution_grant: str = ""
     tool_host_url: str = ""
 

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

@@ -4,7 +4,14 @@ from collections.abc import AsyncIterator
 from dataclasses import dataclass, field
 from typing import Protocol
 
-from .contracts import AgentErrorCode, JsonValue, RuntimeLimits, RuntimeToolDefinition
+from .contracts import (
+    AgentErrorCode,
+    JsonValue,
+    ProviderEgress,
+    RuntimeLimits,
+    RuntimeToolDefinition,
+    ToolNetworkPolicy,
+)
 
 
 @dataclass(frozen=True)
@@ -16,6 +23,8 @@ class EngineRunRequest:
     user_prompt: str = ""
     allowed_tools: tuple[RuntimeToolDefinition, ...] = ()
     limits: RuntimeLimits = field(default_factory=RuntimeLimits)
+    provider_egress: ProviderEgress = field(default_factory=ProviderEgress)
+    tool_network_policy: ToolNetworkPolicy = field(default_factory=ToolNetworkPolicy)
     execution_grant: str = ""
     tool_host_url: str = ""
 

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

@@ -37,7 +37,7 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
         self,
         request: EngineRunRequest,
     ) -> AsyncIterator[EngineSignal]:
-        validate_runtime_request(request)
+        validate_runtime_request(request, self._provider.config.deployment_key)
         cancellation = self._cancellations.setdefault(
             request.run_id,
             asyncio.Event(),
@@ -136,7 +136,10 @@ class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
         await self._provider.health()
 
 
-def validate_runtime_request(request: EngineRunRequest) -> None:
+def validate_runtime_request(
+    request: EngineRunRequest,
+    provider_deployment_key: str,
+) -> None:
     if (
         not request.instructions.strip()
         or not request.user_prompt.strip()
@@ -148,6 +151,21 @@ def validate_runtime_request(request: EngineRunRequest) -> None:
             "Agent Operation 运行计划不完整",
             retryable=False,
         )
+    if (
+        request.provider_egress.mode != "configured-endpoint"
+        or request.provider_egress.deployment_key != provider_deployment_key
+    ):
+        raise SafeEngineError(
+            "FORBIDDEN",
+            "Agent Operation 未授权当前模型部署出网",
+            retryable=False,
+        )
+    if request.tool_network_policy.mode != "forbidden":
+        raise SafeEngineError(
+            "TOOL_DENIED",
+            "Agent Tool 网络策略不受支持",
+            retryable=False,
+        )
 
 
 def cancelled(event: asyncio.Event) -> None:

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

@@ -85,6 +85,8 @@ class AgentRunService:
                 user_prompt=invocation.user_prompt,
                 allowed_tools=tuple(invocation.allowed_tools),
                 limits=invocation.limits,
+                provider_egress=invocation.provider_egress,
+                tool_network_policy=invocation.tool_network_policy,
                 execution_grant=invocation.execution_grant,
                 tool_host_url=invocation.tool_host_url,
             )

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

@@ -168,6 +168,34 @@ async def test_request_validation_uses_canonical_safe_error(
     assert "detail" not in response.json()
 
 
+@pytest.mark.parametrize(
+    "network_fields",
+    [
+        {"providerEgress": {"mode": "configured-endpoint"}},
+        {"providerEgress": {"mode": "arbitrary-url"}},
+        {"toolNetworkPolicy": {"mode": "allowed"}},
+        {"providerUrl": "https://attacker.invalid/v1"},
+    ],
+)
+async def test_network_policy_dto_is_strict_and_fail_closed(
+    client: httpx.AsyncClient,
+    network_fields: dict[str, object],
+) -> None:
+    response = await client.post(
+        "/api/agent/runs",
+        headers={"Idempotency-Key": "network-policy"},
+        json={
+            "operationKey": "test.echo",
+            "input": None,
+            **network_fields,
+        },
+    )
+
+    assert response.status_code == 400
+    assert response.json()["code"] == "INVALID_INPUT"
+    assert "attacker.invalid" not in response.text
+
+
 async def test_internal_token_protects_run_api() -> None:
     protected = create_app(
         DeterministicEngineAdapter(),

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

@@ -14,10 +14,12 @@ def test_server_config_uses_secret_ref_and_normalizes_endpoint() -> None:
         "QWEN_API_URL": "https://example.com/compatible-mode/v1/",
         "QWEN_MODEL": "qwen-plus",
         "QWEN_API_KEY": "server-secret",
+        "AI_PROVIDER_HTTPS_HOST_ALLOWLIST": "example.com",
     }
     config = OpenAiCompatibleConfig.from_environment(environment)
     assert config is not None
     assert config.base_url == "https://example.com/compatible-mode/v1"
+    assert config.https_host_allowlist == ("example.com",)
     assert str(config.api_key_ref) == "[SecretRef]"
     resolver = EnvironmentSecretResolver(environment)
     assert config.api_key_ref is not None
@@ -47,6 +49,50 @@ def test_allows_private_http_endpoint() -> None:
     )
 
 
+def test_https_endpoint_must_match_exact_host_allowlist() -> None:
+    with pytest.raises(ValueError) as captured:
+        OpenAiCompatibleConfig.from_environment(
+            {
+                "QWEN_API_URL": "https://api.example.com/v1",
+                "QWEN_MODEL": "qwen-plus",
+                "AI_PROVIDER_HTTPS_HOST_ALLOWLIST": "example.com",
+            }
+        )
+    assert "api.example.com" not in str(captured.value)
+
+    config = OpenAiCompatibleConfig.from_environment(
+        {
+            "QWEN_API_URL": "https://api.example.com/v1",
+            "QWEN_MODEL": "qwen-plus",
+            "AI_PROVIDER_HTTPS_HOST_ALLOWLIST": "api.example.com",
+        }
+    )
+    assert config is not None
+    assert config.https_host_allowlist == ("api.example.com",)
+
+
+@pytest.mark.parametrize(
+    "allowlist",
+    [
+        "*.example.com",
+        "https://example.com",
+        "example.com:443",
+        "example.com,example.com",
+    ],
+)
+def test_rejects_unsafe_or_duplicate_https_host_allowlist(
+    allowlist: str,
+) -> None:
+    with pytest.raises(ValueError):
+        OpenAiCompatibleConfig.from_environment(
+            {
+                "QWEN_API_URL": "https://example.com/v1",
+                "QWEN_MODEL": "qwen-plus",
+                "AI_PROVIDER_HTTPS_HOST_ALLOWLIST": allowlist,
+            }
+        )
+
+
 def test_partial_deployment_fails_fast_without_leaking_value() -> None:
     marker = "DO-NOT-LEAK"
     with pytest.raises(ValueError) as captured:

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

@@ -10,7 +10,12 @@ from southwind_agent_server.config import (
     OpenAiCompatibleConfig,
     SecretRef,
 )
-from southwind_agent_server.contracts import RuntimeLimits, RuntimeToolDefinition
+from southwind_agent_server.contracts import (
+    ProviderEgress,
+    RuntimeLimits,
+    RuntimeToolDefinition,
+    ToolNetworkPolicy,
+)
 from southwind_agent_server.engine import (
     EngineRunRequest,
     SafeEngineError,
@@ -175,6 +180,55 @@ async def test_engine_denies_unknown_model_tool_before_host_callback() -> None:
     assert tool_called is False
 
 
+async def test_engine_denies_provider_before_network_without_explicit_egress() -> None:
+    provider_called = False
+
+    async def provider_handler(_request: httpx.Request) -> httpx.Response:
+        nonlocal provider_called
+        provider_called = True
+        return sse_response([])
+
+    engine = OpenAiCompatibleEngineAdapter(
+        create_provider(httpx.MockTransport(provider_handler)),
+        ToolHostClient("internal-token"),
+    )
+    request = runtime_request("business.records.list")
+    request = EngineRunRequest(
+        **{
+            **request.__dict__,
+            "provider_egress": ProviderEgress(mode="forbidden"),
+        }
+    )
+
+    with pytest.raises(SafeEngineError) as captured:
+        async for _signal in engine.execute(request):
+            pass
+    assert captured.value.code == "FORBIDDEN"
+    assert provider_called is False
+
+
+async def test_engine_denies_mismatched_provider_deployment() -> None:
+    engine = OpenAiCompatibleEngineAdapter(
+        create_provider(httpx.MockTransport(lambda _request: sse_response([]))),
+        ToolHostClient("internal-token"),
+    )
+    request = runtime_request("business.records.list")
+    request = EngineRunRequest(
+        **{
+            **request.__dict__,
+            "provider_egress": ProviderEgress(
+                mode="configured-endpoint",
+                deployment_key="ai.other-deployment",
+            ),
+        }
+    )
+
+    with pytest.raises(SafeEngineError) as captured:
+        async for _signal in engine.execute(request):
+            pass
+    assert captured.value.code == "FORBIDDEN"
+
+
 def create_provider(
     transport: httpx.AsyncBaseTransport,
 ) -> OpenAiCompatibleProvider:
@@ -184,6 +238,7 @@ def create_provider(
             base_url="https://provider.test/v1",
             model="qwen-compatible",
             api_key_ref=SecretRef("env", "QWEN_API_KEY"),
+            https_host_allowlist=("provider.test",),
         ),
         EnvironmentSecretResolver(environment),
         transport=transport,
@@ -208,6 +263,11 @@ def runtime_request(tool_key: str) -> EngineRunRequest:
             max_duration_seconds=60,
             max_output_bytes=4096,
         ),
+        provider_egress=ProviderEgress(
+            mode="configured-endpoint",
+            deployment_key="ai.openai-compatible",
+        ),
+        tool_network_policy=ToolNetworkPolicy(mode="forbidden"),
         execution_grant="grant_1",
         tool_host_url="http://server:9747",
     )

package/template/apps/server/src/agent/remote-runtime.test.ts

@@ -36,6 +36,11 @@ describe("RemoteAgentRuntime", () => {
       userPrompt: "你好",
       allowedTools: [],
       limits: manifestLimits,
+      providerEgress: {
+        mode: "configured-endpoint",
+        deploymentKey: "ai.openai-compatible",
+      },
+      toolNetworkPolicy: { mode: "forbidden" },
       executionGrant: "grant_1",
     };
     const runtime = new RemoteAgentRuntime({
@@ -51,9 +56,18 @@ describe("RemoteAgentRuntime", () => {
         maxDurationSeconds: 60,
         maxOutputBytes: 8_192,
       },
+      providerEgress: {
+        mode: "configured-endpoint",
+        deploymentKey: "ai.openai-compatible",
+      },
+      toolNetworkPolicy: { mode: "forbidden" },
     });
     expect(
       (received as { limits: Record<string, unknown> }).limits,
     ).not.toHaveProperty("maxInputBytes");
+    const serialized = JSON.stringify(received);
+    expect(serialized).not.toContain("QWEN_");
+    expect(serialized).not.toContain("apiKey");
+    expect(serialized).not.toContain("baseUrl");
   });
 });

package/template/apps/server/src/agent/remote-runtime.ts

@@ -37,6 +37,8 @@ export class RemoteAgentRuntime implements AgentRuntimePort {
         maxDurationSeconds: request.limits.maxDurationSeconds,
         maxOutputBytes: request.limits.maxOutputBytes,
       },
+      providerEgress: request.providerEgress,
+      toolNetworkPolicy: request.toolNetworkPolicy,
       executionGrant: request.executionGrant,
       toolHostUrl: this.options.toolHostUrl,
     };

package/template/apps/server/src/agent/run-contracts.ts

@@ -1,3 +1,7 @@
+import type {
+  AiProviderEgressPolicy,
+  AiToolNetworkPolicy,
+} from "@southwind-ai/modules";
 import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
 
 export interface AgentRuntimeOperation {
@@ -14,6 +18,8 @@ export interface AgentRuntimeOperation {
     maxDurationSeconds: number;
     maxOutputBytes: number;
   };
+  providerEgress: AiProviderEgressPolicy;
+  toolNetworkPolicy: AiToolNetworkPolicy;
   executionGrant: string;
 }
 

package/template/apps/server/src/agent/run-facade.ts

@@ -3,6 +3,10 @@ import type {
   ModuleAiOperationDefinition,
   ModuleManifest,
 } from "@southwind-ai/modules";
+import {
+  resolveProviderEgress,
+  resolveToolNetworkPolicy,
+} from "@southwind-ai/modules";
 import type {
   ModuleAiJsonValue,
   ModuleAiOperationHandlerRegistration,
@@ -105,6 +109,8 @@ export class AgentRunFacade {
           userPrompt: plan.userPrompt,
           allowedTools: operation.tools,
           limits: operation.definition.limits,
+          providerEgress: resolveProviderEgress(operation.definition),
+          toolNetworkPolicy: resolveToolNetworkPolicy(operation.definition),
           executionGrant: grant.token,
         },
         idempotencyKey,

package/template/apps/server/src/agent/tool-host.test.ts

@@ -77,6 +77,31 @@ describe("受限 Agent Tool Host", () => {
     expect(fixture.called).toEqual([]);
   });
 
+  test("Tool 不继承 Provider 出网权限且未知网络模式 fail closed", async () => {
+    const fixture = createFixture({
+      providerEgress: {
+        mode: "configured-endpoint",
+        deploymentKey: "ai.openai-compatible",
+      },
+      toolNetworkPolicy: { mode: "allow" },
+    } as unknown as Partial<ModuleAiOperationDefinition>);
+    const invocation = attachExecutionGrant(
+      {
+        runId: "run_1",
+        toolCallId: "call_1",
+        toolKey: "business.records.list",
+        arguments: {},
+      },
+      fixture.grant.token,
+    );
+
+    await expect(fixture.host.execute(invocation)).rejects.toMatchObject({
+      code: "TOOL_DENIED",
+      message: "Tool 网络策略不受当前 Host 支持",
+    });
+    expect(fixture.called).toEqual([]);
+  });
+
   test("使用宿主颁发 Actor 与 Scope 执行 Handler", async () => {
     const fixture = createFixture();
     const result = await fixture.host.execute(

package/template/apps/server/src/agent/tool-host.ts

@@ -1,4 +1,7 @@
-import type { ModuleManifest } from "@southwind-ai/modules";
+import {
+  resolveToolNetworkPolicy,
+  type ModuleManifest,
+} from "@southwind-ai/modules";
 import type {
   ModuleAgentToolHostPort,
   ModuleAgentToolInvocation,
@@ -30,6 +33,12 @@ export class RestrictedAgentToolHost implements ModuleAgentToolHostPort {
       readGrantToken(invocation),
       invocation.runId,
     );
+    if (resolveToolNetworkPolicy(grant.operation).mode !== "forbidden") {
+      throw new AgentToolHostError(
+        "TOOL_DENIED",
+        "Tool 网络策略不受当前 Host 支持",
+      );
+    }
     if (!grant.operation.allowedToolKeys.includes(invocation.toolKey)) {
       throw new AgentToolHostError("TOOL_DENIED", "Operation 未授权该 Tool");
     }

package/template/docker-compose.yml

@@ -67,6 +67,7 @@ services:
       QWEN_API_URL: ${QWEN_API_URL:-}
       QWEN_API_KEY: ${QWEN_API_KEY:-}
       QWEN_MODEL: ${QWEN_MODEL:-}
+      AI_PROVIDER_HTTPS_HOST_ALLOWLIST: ${AI_PROVIDER_HTTPS_HOST_ALLOWLIST:-}
       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}

package/template/docs/architecture/ai-egress.md

@@ -0,0 +1,80 @@
+# Agent Provider 与 Tool 网络边界
+
+更新时间：2026-07-25。
+
+## 目标与威胁
+
+Agent Operation 需要把受控业务输入发送给独立模型 Provider，但模型提出的 Tool Call
+不能因此获得相同出网权限。旧 `publicNetworkAccess` 把两类边界合成一个布尔值，无法
+表达“允许 Qwen Provider、禁止业务 Tool 任意出网”，现仅作为兼容输入保留。
+
+攻击面包括客户端伪造网络策略、模型选择任意 Provider URL、Provider 配置指向未批准
+Host、模型请求未知 Tool，以及 Tool 把 Provider 权限当作自身网络授权。Endpoint、
+API Key、Actor、Scope 和授权事实均不得由浏览器或模型提供。
+
+## Manifest 契约
+
+Operation 分别声明 Provider egress 与 Tool execution network policy：
+
+```ts
+{
+  dataClassification: "internal",
+  providerEgress: {
+    mode: "configured-endpoint",
+    deploymentKey: "ai.openai-compatible",
+  },
+  toolNetworkPolicy: {
+    mode: "forbidden",
+  },
+}
+```
+
+- 未声明 `providerEgress` 时按 `forbidden` 处理；旧
+  `publicNetworkAccess: "forbidden"` 同样不会开启 Provider。
+- 旧 `publicNetworkAccess: "allowed"` 无法安全迁移，组合校验会要求改为新契约。
+- 当前 Provider 只支持 `configured-endpoint`：Operation 只选择稳定 Deployment Key，
+  不能携带 URL、Host 或 Secret。
+- 当前 Tool 网络策略只支持 `forbidden`，缺省也是 `forbidden`。Provider egress 不会
+  继承给 Tool。
+
+## Provider 强制执行
+
+OpenAI-compatible Adapter 只使用 Agent Server 启动配置的一个 Endpoint。公网 HTTPS
+配置还必须通过 `AI_PROVIDER_HTTPS_HOST_ALLOWLIST` 的精确 Host 匹配；不支持通配符、
+scheme、port 或重复 Host。内网 HTTP 继续受既有私有地址校验约束。
+
+Southwind AI Server 向 Agent Server 只发送 Operation 的 policy mode 与 Deployment
+Key。Agent Server 在发出模型请求前核对：
+
+1. policy 必须是 `configured-endpoint`；
+2. Deployment Key 必须等于当前 Adapter 的配置 Key；
+3. 启动时已验证配置 Endpoint 的 HTTPS Host allowlist；
+4. URL 仍来自 Agent Server 配置，Key 仍由 `SecretRef` 最后时刻解析。
+
+浏览器 API、SSE、错误响应和 Web 环境均不包含 URL、Host allowlist 或 API Key。
+
+## Tool 强制执行
+
+短时 Execution Grant 保存宿主校验过的 Operation。每次 Tool 回调重新读取 Grant，并
+要求 Tool 属于 `allowedToolKeys`、当前 Guard 仍通过且 Tool 网络策略为 `forbidden`。
+客户端和模型不能在 Tool Invocation 中提供或覆盖网络策略。
+
+当前 Module Tool Context 不提供 HTTP/网络 Port，因此平台没有可由模型选择 URL 的通用
+出网 Adapter。若未来开放 Tool 出网，必须新增宿主实现的受限 Port，按 Adapter 和精确
+目的 Host 授权，并在 Manifest 组合、运行时和部署防火墙三层同时允许。
+
+## 尚未覆盖
+
+本 patch 完成契约拆分、Provider 精确配置绑定、HTTPS Host allowlist 和拒绝回归，但
+不把以下能力宣称为已完成：
+
+- 现有 `dataClassification` 是 Operation 级分类，尚未提供字段级数据分类、发送字段
+  allowlist、脱敏或 DLP 检查；
+- 现有 Run 与 Tool 审计不等于逐次 Provider 发送审计；尚未记录目标 Deployment、
+  数据分类、字节数与策略决定的独立 append-only 事实；
+- 同进程 project-owned Tool Handler 不是 OS 网络沙箱。平台契约不授予网络 Port，
+  但无法拦截业务代码直接调用全局 `fetch`；生产 deny-egress 仍需容器网络策略或防火墙；
+- DNS 解析钉扎、代理治理和多 Provider/多 Endpoint 动态路由尚未实现。
+
+在这些能力补齐前，只能声明“Provider 与 Tool 授权语义已隔离”，不能声明业务 Tool 已
+获得进程级强制断网或完整数据出境治理。

package/template/docs/architecture/ai-runtime.md

@@ -250,7 +250,8 @@ interface SpeechClient {
 - 所需模型 capability；
 - 交互方式：interactive、streaming、background 或 live；
 - 最大运行时间、输入大小和输出大小；
-- 是否允许向公网 Provider 发送数据。
+- Provider egress policy 与稳定 Deployment Key；
+- 独立的 Tool execution network policy。
 
 示例：
 
@@ -267,9 +268,20 @@ interface ModuleAiOperationDefinition {
   allowedToolKeys: readonly string[];
   dataClassification: "public" | "internal" | "sensitive";
   execution: "interactive" | "streaming" | "background" | "live";
+  providerEgress?: {
+    mode: "forbidden" | "configured-endpoint";
+    deploymentKey?: string;
+  };
+  toolNetworkPolicy?: {
+    mode: "forbidden";
+  };
 }
 ```
 
+两项缺省均 fail closed。Provider 的实际 Endpoint 与 HTTPS Host allowlist 只存在于
+服务端 Deployment 配置，不由业务 Manifest、浏览器或模型提供。详见
+[Agent Provider 与 Tool 网络边界](./ai-egress.md)。
+
 真实 Operation Handler 与 Manifest 声明必须一一对应。重复、缺失、未知引用、命名空间不匹配和 capability digest 漂移都应在监听前 fail-fast。
 
 ## AI Deployment Registry

package/template/docs/platform/agent-runtime.md

@@ -11,7 +11,8 @@ Grant 与审计；独立 Agent Server 只负责模型循环、canonical event
 
 - OpenAI-compatible `/chat/completions` Provider，支持流式文本和 function calling。
 - `QWEN_API_KEY` 使用服务端 `SecretRef`，只在 Provider Adapter 发请求前解析。
-- 公网 Endpoint 必须为 HTTPS；`localhost`、容器服务名、RFC 1918 地址和
+- 公网 Endpoint 必须为 HTTPS，并精确命中
+  `AI_PROVIDER_HTTPS_HOST_ALLOWLIST`；`localhost`、容器服务名、RFC 1918 地址和
   `.internal`/`.local` 主机可使用 HTTP。URL 禁止内嵌凭据、query、fragment 和云
   metadata 地址。
 - Provider 有连接/请求超时、响应大小上限、安全错误映射和 `/models` readiness 检查。
@@ -29,6 +30,23 @@ Manifest 的 `aiOperations` 是声明事实。每个 Operation 必须声明自
 Permission、可选 Entitlement、输入/输出 schema 和 `allowedToolKeys`。模型只会收到该
 集合内的 Tool 定义。
 
+Provider 与 Tool 网络策略必须分开声明。旧 `publicNetworkAccess` 不会开启 Provider：
+
+```ts
+providerEgress: {
+  mode: "configured-endpoint",
+  deploymentKey: "ai.openai-compatible",
+},
+toolNetworkPolicy: {
+  mode: "forbidden",
+},
+```
+
+Provider URL 与 Secret 不在 Manifest 或浏览器 DTO 中；Agent Server 只允许当前启动
+配置的 Deployment。Tool policy 缺省为 forbidden，且不继承 Provider egress。完整
+威胁模型、兼容行为与尚未覆盖项见
+[Agent Provider 与 Tool 网络边界](../architecture/ai-egress.md)。
+
 模块在 `setup(host)` 中注册模型无关的输入准备器：
 
 ```ts
@@ -85,6 +103,7 @@ AGENT_SERVER_INTERNAL_TOKEN=<至少 12 字符的随机值>
 QWEN_API_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
 QWEN_API_KEY=<服务端密钥>
 QWEN_MODEL=qwen-plus
+AI_PROVIDER_HTTPS_HOST_ALLOWLIST=dashscope-intl.aliyuncs.com
 
 # 可选安全上限
 # AI_PROVIDER_CONNECT_TIMEOUT_MS=5000

package/template/packages/config/index.test.ts

@@ -181,6 +181,7 @@ test("OpenAI-compatible 部署只在服务端解析 Secret 与运行上限", ()
     AI_PROVIDER_CONNECT_TIMEOUT_MS: "2500",
     AI_PROVIDER_REQUEST_TIMEOUT_MS: "45000",
     AI_PROVIDER_MAX_RESPONSE_BYTES: "1048576",
+    AI_PROVIDER_HTTPS_HOST_ALLOWLIST: "workspace.cn-beijing.maas.aliyuncs.com",
   });
 
   expect(config).toEqual({
@@ -191,9 +192,28 @@ test("OpenAI-compatible 部署只在服务端解析 Secret 与运行上限", ()
     connectTimeoutMs: 2500,
     requestTimeoutMs: 45000,
     maxResponseBytes: 1048576,
+    allowedHttpsHosts: ["workspace.cn-beijing.maas.aliyuncs.com"],
   });
 });
 
+test("OpenAI-compatible HTTPS Endpoint 必须命中精确 Host allowlist", () => {
+  expect(() =>
+    loadOpenAiCompatibleDeploymentConfig({
+      QWEN_API_URL: "https://api.example.com/v1",
+      QWEN_MODEL: "qwen-plus",
+      AI_PROVIDER_HTTPS_HOST_ALLOWLIST: "example.com",
+    }),
+  ).toThrow("allowedHttpsHosts");
+
+  expect(() =>
+    loadOpenAiCompatibleDeploymentConfig({
+      QWEN_API_URL: "https://api.example.com/v1",
+      QWEN_MODEL: "qwen-plus",
+      AI_PROVIDER_HTTPS_HOST_ALLOWLIST: "*.example.com",
+    }),
+  ).toThrow("allowedHttpsHosts");
+});
+
 test("OpenAI-compatible Endpoint 拒绝公网 HTTP 与 metadata", () => {
   expect(() =>
     normalizeOpenAiCompatibleBaseUrl("http://api.example.com/v1"),

package/template/packages/config/src/ai-openai-compatible.ts

@@ -2,6 +2,7 @@ import { isIP } from "node:net";
 import { z } from "zod";
 import { defineModuleConfig } from "./definition.js";
 import {
+  commaSeparated,
   loadModuleConfigSync,
   strictInteger,
   type ConfigEnvironment,
@@ -15,10 +16,11 @@ export interface OpenAiCompatibleDeploymentConfig {
   connectTimeoutMs: number;
   requestTimeoutMs: number;
   maxResponseBytes: number;
+  allowedHttpsHosts: string[];
 }
 
-const deploymentSchema: z.ZodType<OpenAiCompatibleDeploymentConfig> =
-  z.strictObject({
+const deploymentSchema: z.ZodType<OpenAiCompatibleDeploymentConfig> = z
+  .strictObject({
     baseUrl: z.string().transform(normalizeOpenAiCompatibleBaseUrl),
     model: z.string().trim().min(1).max(200),
     apiKey: z.string().trim().min(1).optional(),
@@ -29,6 +31,20 @@ const deploymentSchema: z.ZodType<OpenAiCompatibleDeploymentConfig> =
       .int()
       .min(1_024)
       .max(16 * 1_024 * 1_024),
+    allowedHttpsHosts: z.array(z.string()).max(32),
+  })
+  .superRefine((config, context) => {
+    const endpoint = new URL(config.baseUrl);
+    if (
+      endpoint.protocol === "https:" &&
+      !config.allowedHttpsHosts.includes(endpoint.hostname.toLowerCase())
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["allowedHttpsHosts"],
+        message: "Endpoint 未命中 HTTPS Host allowlist",
+      });
+    }
   });
 
 export const openAiCompatibleDeploymentConfigDefinition =
@@ -52,6 +68,12 @@ export const openAiCompatibleDeploymentConfigDefinition =
         "maxResponseBytes",
         2 * 1_024 * 1_024,
       ),
+      {
+        key: "AI_PROVIDER_HTTPS_HOST_ALLOWLIST",
+        path: "allowedHttpsHosts",
+        defaultValue: [],
+        decode: normalizeOpenAiCompatibleHttpsHostAllowlist,
+      },
     ],
   });
 
@@ -89,10 +111,44 @@ export function normalizeOpenAiCompatibleBaseUrl(raw: string): string {
   return url.toString().replace(/\/$/, "");
 }
 
+export function normalizeOpenAiCompatibleHttpsHostAllowlist(
+  raw: string,
+): string[] {
+  const hosts = commaSeparated(raw).map((host) => normalizeHttpsHostname(host));
+  if (hosts.length > 32 || new Set(hosts).size !== hosts.length) {
+    throw new Error("Provider HTTPS Host allowlist 无效");
+  }
+  return hosts;
+}
+
 function integer(key: string, path: string, defaultValue: number) {
   return { key, path, defaultValue, decode: strictInteger };
 }
 
+function normalizeHttpsHostname(raw: string): string {
+  const hostname = raw.trim().toLowerCase().replace(/\.$/, "");
+  if (
+    !hostname ||
+    hostname.includes("*") ||
+    hostname.includes("/") ||
+    hostname.includes(":") ||
+    hostname.length > 253
+  ) {
+    throw new Error("Provider HTTPS Host allowlist 无效");
+  }
+  const labels = hostname.split(".");
+  if (
+    labels.some(
+      (label) =>
+        !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label) &&
+        !/^[a-z0-9]$/.test(label),
+    )
+  ) {
+    throw new Error("Provider HTTPS Host allowlist 无效");
+  }
+  return hostname;
+}
+
 function isPrivateHost(hostname: string): boolean {
   if (
     hostname === "localhost" ||

package/template/packages/modules/index.ts

@@ -7,3 +7,4 @@ export * from "./src/system-modules.js";
 export * from "./src/system-module-catalog.js";
 export * from "./src/system-api-permissions.js";
 export * from "./src/tool-composition.js";
+export * from "./src/ai-network-policy.js";

package/template/packages/modules/src/ai-network-policy.ts

@@ -0,0 +1,50 @@
+import type {
+  AiProviderEgressPolicy,
+  AiToolNetworkPolicy,
+  ModuleAiOperationDefinition,
+} from "./manifest.js";
+
+const providerForbidden: AiProviderEgressPolicy = Object.freeze({
+  mode: "forbidden",
+});
+const toolNetworkForbidden: AiToolNetworkPolicy = Object.freeze({
+  mode: "forbidden",
+});
+
+export function resolveProviderEgress(
+  operation: ModuleAiOperationDefinition,
+): AiProviderEgressPolicy {
+  return operation.providerEgress ?? providerForbidden;
+}
+
+export function resolveToolNetworkPolicy(
+  operation: ModuleAiOperationDefinition,
+): AiToolNetworkPolicy {
+  return operation.toolNetworkPolicy ?? toolNetworkForbidden;
+}
+
+export function validateAiNetworkPolicy(
+  operation: ModuleAiOperationDefinition,
+): void {
+  const provider = resolveProviderEgress(operation);
+  if (provider.mode === "configured-endpoint") {
+    if (!provider.deploymentKey.trim()) {
+      throw new Error(`${operation.key} Provider Deployment Key 不能为空`);
+    }
+  } else if (provider.mode !== "forbidden") {
+    throw new Error(`${operation.key} Provider 出网策略无效`);
+  }
+
+  const tool = resolveToolNetworkPolicy(operation);
+  if (tool.mode !== "forbidden") {
+    throw new Error(`${operation.key} Tool 网络策略无效`);
+  }
+  if (
+    operation.publicNetworkAccess === "allowed" &&
+    operation.providerEgress === undefined
+  ) {
+    throw new Error(
+      `${operation.key} 旧 publicNetworkAccess=allowed 不能安全映射，请声明 providerEgress`,
+    );
+  }
+}

package/template/packages/modules/src/ai-operation-composition.test.ts

@@ -98,6 +98,56 @@ describe("AI Operation Composition", () => {
     expect(() => validateModuleComposition([module])).toThrow("Tool 不能为空");
   });
 
+  test("Provider 与 Tool 网络边界独立且旧声明默认 fail closed", () => {
+    const module = fixture("business");
+    const legacy = operation("business.legacy");
+    module.aiOperations = [legacy];
+    expect(() => validateModuleComposition([module])).not.toThrow();
+
+    module.aiOperations = [
+      {
+        ...operation("business.generate"),
+        publicNetworkAccess: undefined,
+        providerEgress: {
+          mode: "configured-endpoint",
+          deploymentKey: "ai.openai-compatible",
+        },
+        toolNetworkPolicy: { mode: "forbidden" },
+      },
+    ];
+    expect(() => validateModuleComposition([module])).not.toThrow();
+
+    module.aiOperations[0] = {
+      ...operation("business.generate"),
+      publicNetworkAccess: "allowed",
+    };
+    expect(() => validateModuleComposition([module])).toThrow("不能安全映射");
+  });
+
+  test("拒绝空 Provider Deployment 与未知 Tool 网络模式", () => {
+    const module = fixture("business");
+    module.aiOperations = [
+      {
+        ...operation("business.generate"),
+        providerEgress: {
+          mode: "configured-endpoint",
+          deploymentKey: " ",
+        },
+      },
+    ];
+    expect(() => validateModuleComposition([module])).toThrow(
+      "Deployment Key 不能为空",
+    );
+
+    module.aiOperations[0] = {
+      ...operation("business.generate"),
+      toolNetworkPolicy: { mode: "allow" },
+    } as unknown as ModuleAiOperationDefinition;
+    expect(() => validateModuleComposition([module])).toThrow(
+      "Tool 网络策略无效",
+    );
+  });
+
   test("Operation Handler 必须与 Manifest 声明一一对应", () => {
     const module = fixture("business");
     module.aiOperations = [operation("business.generate")];

package/template/packages/modules/src/ai-operation-composition.ts

@@ -2,6 +2,7 @@ import type {
   ModuleAiOperationDefinition,
   ModuleManifest,
 } from "./manifest.js";
+import { validateAiNetworkPolicy } from "./ai-network-policy.js";
 
 interface AiOperationCatalogs {
   permissions: ReadonlySet<string>;
@@ -100,6 +101,7 @@ function validateOperation(
   );
   validateCapabilities(operation);
   validateTools(operation, catalogs.tools);
+  validateAiNetworkPolicy(operation);
   validateLimits(operation);
 }
 

package/template/packages/modules/src/manifest.ts

@@ -88,6 +88,15 @@ export type AiOperationExecution =
   | "background"
   | "live";
 export type AiOperationPublicNetworkAccess = "forbidden" | "allowed";
+export type AiProviderEgressPolicy =
+  | { mode: "forbidden" }
+  | {
+      mode: "configured-endpoint";
+      deploymentKey: string;
+    };
+export interface AiToolNetworkPolicy {
+  mode: "forbidden";
+}
 
 export interface AiOperationLimits {
   maxDurationSeconds: number;
@@ -107,7 +116,10 @@ export interface ModuleAiOperationDefinition {
   allowedToolKeys: readonly string[];
   dataClassification: AiOperationDataClassification;
   execution: AiOperationExecution;
-  publicNetworkAccess: AiOperationPublicNetworkAccess;
+  /** @deprecated 使用 providerEgress 与 toolNetworkPolicy 拆分两类网络边界。 */
+  publicNetworkAccess?: AiOperationPublicNetworkAccess;
+  providerEgress?: AiProviderEgressPolicy;
+  toolNetworkPolicy?: AiToolNetworkPolicy;
   limits: AiOperationLimits;
 }