create-windy 0.3.2 → 0.3.5

package/package.json

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

package/template/.agents/skills/windy-business-module/SKILL.md

@@ -28,14 +28,26 @@ description: "Windy 业务模块、Manifest、Repository、Service、Agent Tool
    project-owned Repository 回查资源与 fileId 绑定及对象级授权，只返回布尔判定，
    再通过 `context.storage.openResourceFile()` 取得最小元数据与流。禁止注入
    UploadRepository、BlobStore 或申请平台 manage Repository。
-6. 若项目包含 `system.agent`，`operation=query` 的 Tool 会由同一 Registry 自动进入
+6. 业务资源包含敏感字段时，在 Manifest 一次声明 Data Policy、standard read、
+   sensitive-disclosure reveal、governed-export Permission 与 masked/reveal API 绑定，
+   再用 `registerGovernedResources()` 分别注册对象授权 Resolver 和去除治理字段的投影。
+   需要导出时再登记四个 Manifest API 绑定、受控查询校验和 cursor 分页 Source；审批、
+   Durable Job、水印、TTL、下载与取消由宿主负责。业务不自行签发明文 Grant、校验密码，
+   也不接触 Workflow、BlobStore 或平台 Repository。
+7. 若项目包含 `system.agent`，`operation=query` 的 Tool 会由同一 Registry 自动进入
    MCP；不要编辑 MCP Adapter 或复制 Tool 定义。写操作在幂等、审批和结果追踪闭环前
    不通过 MCP 暴露。
-7. 补 Manifest/Composition、Repository/Service、Guard 拒绝和 Handler 契约测试。
+   对无需 Actor、Repository、Secret、文件系统或外网的纯计算 Tool，可改用
+   `setupSandbox()` 注册；此入口必须同步且无副作用，Handler 只能使用输入、
+   `idempotencyKey` 与 `AbortSignal`。需要业务数据或外部服务的 Tool 必须保留在普通
+   `setup()`，不能为了使用 Sandbox 绕过依赖边界。
+8. 补 Manifest/Composition、Repository/Service、Guard 拒绝和 Handler 契约测试。
    涉及 Tool 时还要覆盖 Schema 拒绝、数据范围与未授权发现/调用；涉及可选模块时覆盖
    Starter 的文件、依赖和数据库裁剪。涉及资源文件时还要覆盖跨上传者成功、资源绑定/
    purpose/Feature/Permission/Scope 任一拒绝、最小元数据与成功/拒绝审计。
-8. 更新长期文档，运行受影响测试、`bun run typecheck` 和 `bun run lint`，按一个完整
+   涉及 Sandbox Tool 时还要覆盖无网络、无平台 Secret、无宿主数据挂载、Worker
+   重启恢复，以及策略拒绝与业务失败审计分类。
+9. 更新长期文档，运行受影响测试、`bun run typecheck` 和 `bun run lint`，按一个完整
    小切片提交。
 
 ## 代码事实源
@@ -44,6 +56,7 @@ description: "Windy 业务模块、Manifest、Repository、Service、Agent Tool
 - Tool 组合校验：`packages/modules/src/tool-composition.ts`
 - 模块 Host 契约：`packages/server-sdk/src/module-host.ts`
 - Tool Handler 契约：`packages/server-sdk/src/tool-registration.ts`
+- Sandbox Tool 契约：`packages/server-sdk/src/sandbox-tool.ts`
 - 可移除业务示例：`packages/example-work-order/`、`apps/server/src/work-order/`
 - 业务模块安装入口：`apps/server/src/installed-business-modules.ts`
 - MCP 与统一执行边界：`docs/architecture/mcp-business-capabilities.md`

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "cb75f345710c9db90091819fd917d999cca88d05",
-  "generatorVersion": "0.3.2",
+  "templateCommit": "0e87efcbc9fb6805a73439e73e030e6ec5783ad7",
+  "generatorVersion": "0.3.5",
   "modules": [
     {
       "name": "system",

package/template/AGENTS.md

@@ -47,6 +47,10 @@
 - 定制 404、500、维护中或网络异常页时，只修改 project-owned 的
   `apps/web/src/app/error-pages.ts`，并把业务 SFC 放在 `apps/web/src/app/`；
   保留四个类型化注册项，不要为换视觉修改 Router、HTTP 核心或平台默认错误页。
+- 新增业务管理页面时，在业务 Module Manifest 注册 Feature、Permission、菜单和
+  Admin Route，再把 Vue 页面绑定到 project-owned 的
+  `apps/web/src/app/business-routes.ts`；不要修改 Router 或 AppSidebar。导航来自
+  服务端 Manifest 快照，接入见 `docs/development/business-web-routes.md`。
 - 业务 Agent Operation 开启 Provider 出网时，必须在 Manifest 同时声明最小
   `providerDataPolicy.inputFields` JSON Pointer allowlist 与
   `envelopeFields`；raw input 会在进入 `prepare` 前裁剪并执行 DLP。接入与升级

package/template/README.md

@@ -60,9 +60,9 @@ Skill 完成该能力”。Skill 只指导开发流程；Feature、Permission、
 运行时事实仍以 Module Manifest 与平台 Registry 为准。
 
 当前组合未包含 `system.agent`，MCP Server、Agent Tool Host 和相关文档已被
-物理裁剪。若项目尚可重新生成，请在创建时增加 `--module system.agent` 或使用
-`--all-modules`；部署后的通用 `module add` 尚未交付，不要手工复制 MCP Adapter
-或另建授权链。仓库 Skill 仍可用于普通业务模块开发。
+物理裁剪。创建时可增加 `--module system.agent` 或使用 `--all-modules`；已部署
+项目使用 `bun run windy module add system.agent`，不要手工复制 MCP Adapter 或
+另建授权链。仓库 Skill 仍可用于普通业务模块开发。
 
 
 
@@ -99,8 +99,8 @@ create-windy 在本机 `.env` 中随机生成的 `WINDY_BOOTSTRAP_ADMIN_PASSWORD
 | 法律许可 | `UNLICENSED` |
 
 平台当前注册的全部模块如下。H0 表示 profile 锁定核心；H2 表示创建时可以物理包含或
-排除，并已有生成、类型检查、测试和构建证据。H2 不代表项目部署后已经支持无损安装、
-升级或卸载；那需要 H3 的生命周期命令与数据处置证据。
+排除；H3 还具备部署期安装、更新、数据保留卸载和重装证据。通用生命周期命令会保守
+处理所有目录模块，但只有通过完整 H3 回归的模块才标记为 H3。
 
 | Module Key | 当前项目 | 热插拔可靠度 | 说明 |
 | ---------- | -------- | ------------ | ---- |
@@ -119,14 +119,17 @@ create-windy 在本机 `.env` 中随机生成的 `WINDY_BOOTSTRAP_ADMIN_PASSWORD
 | `system.bulk-data` | 未包含 | H2 | 批量导入导出与结果留存。 |
 | `system.search` | 未包含 | H2 | 权限感知搜索与 Provider 聚合。 |
 | `system.data-governance` | 未包含 | H2 | 敏感字段、明文访问和治理导出。 |
-| `work-order` | 未包含 | H2 | 可替换的业务模块接入示例。 |
+| `work-order` | 未包含 | H3 | 可替换的业务模块接入示例。 |
 
 项目自有业务模块以 `apps/server/src/installed-business-modules.ts` 装配的 Module Manifest
-为准；shared-scaffold README 不复制项目业务 Key，避免平台升级固化产品命名。
+为准；对应 Vue 页面在 project-owned 的
+`apps/web/src/app/business-routes.ts` 注册，侧栏继续从服务端 Manifest 快照生成。
+不要为增加业务页面修改 shared-scaffold Router 或 AppSidebar。shared-scaffold README
+不复制项目业务 Key，避免平台升级固化产品命名。
 
 精确生成来源和选择记录在 `.windy/generation.json`。当前版本已提供可回滚的
-`windy update`；通用 `module add/remove` 尚未交付，不要把 Feature Flag 关闭当成
-模块已经卸载。
+`windy update` 与 `windy module list/add/update/remove`。Feature Flag 关闭仍不
+等于模块卸载。
 
 ## 常用命令
 
@@ -142,6 +145,9 @@ bun run build
 bun run windy doctor
 bun run windy update --check
 bun run windy update --dry-run
+bun run windy module list
+bun run windy module add work-order --dry-run
+bun run windy module remove work-order --dry-run
 bun run windy reconcile --to <精确目标版本>
 bun run lint
 bun run format
@@ -178,8 +184,9 @@ create-windy 默认建立 `main` 分支并创建 `chore: initialize project` 首
 没有配置 Git 用户身份，文件会保留在暂存区；配置身份后手动提交即可。
 
 当前已交付的 Windy 更新器会根据 Project Lock 和文件所有权，从 npm 历史 artifact
-重建 Base 并执行三方合并；它不连接私有源仓库，也不会静默覆盖项目代码。部署期通用
-`module add/update/remove` 尚未交付。
+重建 Base 并执行三方合并；它不连接私有源仓库，也不会静默覆盖项目代码。模块
+生命周期命令复用同一计划、事务、验证与恢复边界；卸载默认保留数据库数据，并要求
+显式确认数据处置计划。
 
 ## License
 

package/template/_gitignore

@@ -13,6 +13,7 @@ dist/
 __pycache__/
 packages/create-windy/template/
 .tmp/
+.artifacts/
 .windy/backups/
 .windy/update-state.json
 *.tsbuildinfo

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

@@ -32,6 +32,8 @@ 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 AI_PROVIDER_CAPABILITIES='text-generation'
+export AI_PROVIDER_INPUT_MODALITIES='text'
 export AGENT_RUN_STORE_PATH='.data/agent-runs.sqlite3'
 export AI_PROVIDER_AUDIT_STORE_PATH='.data/provider-audit.sqlite3'
 export AI_PROVIDER_AUDIT_RETENTION_DAYS='90'

package/template/apps/agent-server/pyproject.toml

@@ -4,9 +4,16 @@ version = "0.1.0"
 description = "Southwind AI canonical Agent Runtime server"
 requires-python = ">=3.12,<3.13"
 dependencies = [
+  "cryptography==49.0.0",
   "fastapi==0.139.2",
   "google-adk==2.5.0",
   "httpx==0.28.1",
+  "jsonschema==4.26.0",
+  "opentelemetry-api==1.42.1",
+  "opentelemetry-exporter-otlp-proto-http==1.42.1",
+  "opentelemetry-sdk==1.42.1",
+  "pillow==12.3.0",
+  "psycopg[binary,pool]==3.3.4",
   "pydantic==2.13.4",
   "uvicorn==0.51.0",
 ]
@@ -17,6 +24,7 @@ dev = [
   "pytest==9.1.1",
   "pytest-asyncio==1.4.0",
   "ruff==0.15.22",
+  "types-jsonschema==4.26.0.20260518",
 ]
 
 [tool.pytest.ini_options]

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

@@ -12,7 +12,7 @@ from google.genai import types
 
 from .adk_failure import AdkFailureState
 from .adk_model import GovernedOpenAiLlm
-from .adk_tools import GovernedTool
+from .adk_tools import ApprovalSignalState, GovernedTool
 from .contracts import JsonValue
 from .engine import (
     AgentEngineAdapter,
@@ -25,10 +25,11 @@ from .engine import (
     ToolRequested,
     UsageReported,
 )
+from .multimodal import final_output
 from .openai_engine import cancelled, validate_runtime_request
 from .openai_provider import OpenAiCompatibleProvider
 from .provider_governance import ProviderRequestGovernance
-from .tool_host import ToolHostClient
+from .tool_host import ToolHostClient, canonical_tool_call_id
 
 
 class AdkEngineAdapter(AgentEngineAdapter):
@@ -45,6 +46,14 @@ class AdkEngineAdapter(AgentEngineAdapter):
         self._governance = governance
         self._cancellations: dict[str, asyncio.Event] = {}
 
+    @property
+    def capabilities(self) -> tuple[str, ...]:
+        return self._provider.config.capabilities if self._provider else ()
+
+    @property
+    def input_modalities(self) -> tuple[str, ...]:
+        return self._provider.config.input_modalities if self._provider else ()
+
     def supports(self, operation_key: str) -> bool:
         return bool(operation_key.strip())
 
@@ -53,7 +62,12 @@ class AdkEngineAdapter(AgentEngineAdapter):
         request: EngineRunRequest,
     ) -> AsyncIterator[EngineSignal]:
         provider, tool_host, governance = self._configured()
-        validate_runtime_request(request, provider.config.deployment_key)
+        validate_runtime_request(
+            request,
+            provider.config.deployment_key,
+            provider.config.capabilities,
+            provider.config.input_modalities,
+        )
         cancellation = self._cancellations.setdefault(
             request.run_id,
             asyncio.Event(),
@@ -61,7 +75,9 @@ class AdkEngineAdapter(AgentEngineAdapter):
         output = ""
         output_bytes = 0
         failures = AdkFailureState()
+        approvals = ApprovalSignalState()
         event_failure: SafeEngineError | None = None
+        tool_call_ids: dict[str, str] = {}
         try:
             session_service = InMemorySessionService()  # type: ignore[no-untyped-call]
             await session_service.create_session(
@@ -88,13 +104,14 @@ class AdkEngineAdapter(AgentEngineAdapter):
                             tool_host,
                             cancellation,
                             failures,
+                            approvals,
                         )
                         for tool in request.allowed_tools
                     ],
                 ),
                 session_service=session_service,
             )
-            async for event in runner.run_async(
+            events = runner.run_async(
                 user_id="platform",
                 session_id=request.run_id,
                 new_message=types.Content(
@@ -105,7 +122,12 @@ class AdkEngineAdapter(AgentEngineAdapter):
                     streaming_mode=StreamingMode.SSE,
                     max_llm_calls=provider.config.max_tool_rounds,
                 ),
-            ):
+            )
+            async for item in merge_adk_events(events, approvals.queue):
+                if not isinstance(item, Event):
+                    yield item
+                    continue
+                event = item
                 cancelled(cancellation)
                 if event.error_code:
                     event_failure = failures.failure or SafeEngineError(
@@ -114,7 +136,11 @@ class AdkEngineAdapter(AgentEngineAdapter):
                         retryable=True,
                     )
                     continue
-                async for signal in signals_for_event(event):
+                async for signal in signals_for_event(
+                    event,
+                    request,
+                    tool_call_ids,
+                ):
                     if isinstance(signal, OutputDelta):
                         output_bytes += len(signal.text.encode())
                         if output_bytes > request.limits.max_output_bytes:
@@ -128,7 +154,7 @@ class AdkEngineAdapter(AgentEngineAdapter):
             if event_failure is not None:
                 raise event_failure
             cancelled(cancellation)
-            yield EngineCompleted({"text": output})
+            yield EngineCompleted(final_output(output, request.output_schema))
         except SafeEngineError:
             raise
         except asyncio.CancelledError:
@@ -175,7 +201,11 @@ class AdkEngineAdapter(AgentEngineAdapter):
         return self._provider, self._tool_host, self._governance
 
 
-async def signals_for_event(event: Event) -> AsyncIterator[EngineSignal]:
+async def signals_for_event(
+    event: Event,
+    request: EngineRunRequest,
+    tool_call_ids: dict[str, str],
+) -> AsyncIterator[EngineSignal]:
     for call in event.get_function_calls():
         if not call.id or not call.name:
             raise SafeEngineError(
@@ -183,7 +213,14 @@ async def signals_for_event(event: Event) -> AsyncIterator[EngineSignal]:
                 "模型请求了无效 Tool",
                 retryable=False,
             )
-        yield ToolRequested(call.id, call.name)
+        arguments = call.args if isinstance(call.args, dict) else {}
+        stable_id = canonical_tool_call_id(
+            request.run_id,
+            call.name,
+            arguments,
+        )
+        tool_call_ids[call.id] = stable_id
+        yield ToolRequested(stable_id, call.name)
     for response in event.get_function_responses():
         if not response.id:
             raise SafeEngineError(
@@ -191,7 +228,14 @@ async def signals_for_event(event: Event) -> AsyncIterator[EngineSignal]:
                 "Agent Tool 响应缺少稳定标识",
                 retryable=False,
             )
-        yield ToolCompleted(response.id)
+        response_tool_call_id = tool_call_ids.get(response.id)
+        if not response_tool_call_id:
+            raise SafeEngineError(
+                "TOOL_DENIED",
+                "Agent Tool 响应与请求不匹配",
+                retryable=False,
+            )
+        yield ToolCompleted(response_tool_call_id)
     if event.partial and event.content:
         for part in event.content.parts or []:
             if part.text and not part.thought:
@@ -212,3 +256,36 @@ def southwind_usage(event: Event) -> dict[str, JsonValue] | None:
         if isinstance(key, str)
         and (item is None or isinstance(item, str | int | float | bool | list | dict))
     }
+
+
+async def merge_adk_events(
+    events: AsyncIterator[Event],
+    approval_queue: asyncio.Queue[EngineSignal],
+) -> AsyncIterator[Event | EngineSignal]:
+    iterator = events.__aiter__()
+    event_task: asyncio.Task[Event] = asyncio.create_task(next_event(iterator))
+    approval_task = asyncio.create_task(approval_queue.get())
+    try:
+        while True:
+            done, _ = await asyncio.wait(
+                {event_task, approval_task},
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            if approval_task in done:
+                yield approval_task.result()
+                approval_task = asyncio.create_task(approval_queue.get())
+            if event_task in done:
+                try:
+                    yield event_task.result()
+                except StopAsyncIteration:
+                    while not approval_queue.empty():
+                        yield approval_queue.get_nowait()
+                    return
+                event_task = asyncio.create_task(next_event(iterator))
+    finally:
+        event_task.cancel()
+        approval_task.cancel()
+
+
+async def next_event(iterator: AsyncIterator[Event]) -> Event:
+    return await iterator.__anext__()

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

@@ -13,6 +13,7 @@ from pydantic import PrivateAttr
 from .adk_failure import AdkFailureState
 from .contracts import JsonValue
 from .engine import EngineRunRequest, SafeEngineError
+from .multimodal import attach_artifacts
 from .openai_engine import cancelled, parse_arguments
 from .openai_provider import OpenAiCompatibleProvider, ProviderTurn
 from .provider_governance import ProviderRequestGovernance
@@ -58,7 +59,10 @@ class GovernedOpenAiLlm(BaseLlm):
                     "Agent Tool 调用轮次超过上限",
                     retryable=False,
                 )
-            messages = adk_messages(llm_request, self._request.instructions)
+            messages = attach_artifacts(
+                adk_messages(llm_request, self._request.instructions),
+                self._request.artifacts,
+            )
             governed = self._governance.authorize(
                 deployment_key=self._provider.config.deployment_key,
                 operation_key=self._request.operation_key,
@@ -68,13 +72,24 @@ class GovernedOpenAiLlm(BaseLlm):
                 tools=self._request.allowed_tools,
                 policy=self._request.provider_data_policy,
                 input_value=self._request.input,
-                measure=lambda values, tools: len(
-                    self._provider.request_body(values, tools)
+                artifact_bytes=sum(
+                    artifact.byte_size for artifact in self._request.artifacts
+                ),
+                output_schema=self._request.output_schema,
+                measure=lambda values, tools, schema: len(
+                    self._provider.request_body(
+                        values,
+                        tools,
+                        self._request.output_schema_key,
+                        schema,
+                    )
                 ),
             )
             turn = await self._provider.complete_turn(
                 governed.messages,
                 governed.tools,
+                self._request.output_schema_key,
+                governed.output_schema,
             )
             cancelled(self._cancellation)
             validate_tool_calls(

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

@@ -9,9 +9,26 @@ from google.genai import types
 
 from .adk_failure import AdkFailureState
 from .contracts import JsonValue, RuntimeToolDefinition
-from .engine import EngineRunRequest, SafeEngineError
+from .engine import (
+    ApprovalRequired,
+    ApprovalResolved,
+    EngineRunRequest,
+    EngineSignal,
+    SafeEngineError,
+)
 from .openai_engine import cancelled
-from .tool_host import ToolHostClient, ToolInvocation
+from .tool_host import (
+    ToolApprovalPending,
+    ToolApprovalResolved,
+    ToolHostClient,
+    ToolInvocation,
+    canonical_tool_call_id,
+)
+
+
+class ApprovalSignalState:
+    def __init__(self) -> None:
+        self.queue: asyncio.Queue[EngineSignal] = asyncio.Queue()
 
 
 class GovernedTool(BaseTool):
@@ -24,6 +41,7 @@ class GovernedTool(BaseTool):
         tool_host: ToolHostClient,
         cancellation: asyncio.Event,
         failures: AdkFailureState,
+        approvals: ApprovalSignalState,
     ) -> None:
         super().__init__(
             name=definition.key,
@@ -33,6 +51,7 @@ class GovernedTool(BaseTool):
         self._tool_host = tool_host
         self._cancellation = cancellation
         self._failures = failures
+        self._approvals = approvals
 
     def _get_declaration(self) -> types.FunctionDeclaration:
         return types.FunctionDeclaration(
@@ -59,16 +78,64 @@ class GovernedTool(BaseTool):
                     "Agent Tool Call 缺少稳定标识",
                     retryable=False,
                 )
-            result = await self._tool_host.execute(
-                self._request.tool_host_url,
-                ToolInvocation(
-                    self._request.run_id,
-                    call_id,
-                    self.name,
-                    cast(dict[str, JsonValue], args),
-                    self._request.execution_grant,
-                ),
+            stable_call_id = canonical_tool_call_id(
+                self._request.run_id,
+                self.name,
+                cast(dict[str, JsonValue], args),
+            )
+            invocation = ToolInvocation(
+                self._request.run_id,
+                stable_call_id,
+                self.name,
+                cast(dict[str, JsonValue], args),
+                self._request.execution_grant,
             )
+            approval: ToolApprovalPending | None = None
+            while True:
+                cancelled(self._cancellation)
+                try:
+                    result = await self._tool_host.execute(
+                        self._request.tool_host_url,
+                        invocation,
+                    )
+                    if approval:
+                        await self._approvals.queue.put(
+                            ApprovalResolved(
+                                approval.work_item_id,
+                                stable_call_id,
+                                "approved",
+                            )
+                        )
+                    break
+                except ToolApprovalPending as pending:
+                    if approval is None:
+                        approval = pending
+                        await self._approvals.queue.put(
+                            ApprovalRequired(
+                                pending.work_item_id,
+                                stable_call_id,
+                            )
+                        )
+                    elif approval.work_item_id != pending.work_item_id:
+                        raise SafeEngineError(
+                            "TOOL_DENIED",
+                            "Agent Tool 审批标识漂移",
+                            retryable=False,
+                        ) from None
+                    await asyncio.sleep(2)
+                except ToolApprovalResolved as resolved:
+                    await self._approvals.queue.put(
+                        ApprovalResolved(
+                            resolved.work_item_id,
+                            stable_call_id,
+                            resolved.outcome,
+                        )
+                    )
+                    raise SafeEngineError(
+                        "TOOL_DENIED",
+                        "Agent Tool 审批未通过",
+                        retryable=False,
+                    ) from None
             cancelled(self._cancellation)
             return result
         except SafeEngineError as error: