create-windy 0.3.0 → 0.3.1

package/template/apps/server/src/system/routes.ts

@@ -1,49 +1,25 @@
 import type { FeatureFlagDefinition } from "@southwind-ai/shared";
-import { recordMutationAudit } from "../audit/policy.js";
 import { registerFeatureFlagRoutes } from "../feature/routes.js";
 import { findSystemFeature } from "../route-guards.js";
 import type { createServerRuntime } from "../runtime.js";
-import type { ManagedEntity } from "./entities.js";
 import { registerMenuRoutes } from "./menu-routes.js";
 import {
   registerDepartmentQuickCreateRoute,
   registerDepartmentTransitionRoute,
 } from "./department-routes.js";
-import {
-  asPartial,
-  notFound,
-  parseImportPayload,
-  parseListQuery,
-  requiredId,
-  resourceEvent,
-  routeContext,
-} from "./route-helpers.js";
-import type { ResourceRouteConfig, RouteApp } from "./route-types.js";
+import type { RouteApp } from "./route-types.js";
 import type { SystemRepositories } from "./seed.js";
-import { resource, withPermission } from "./resource-route-support.js";
+import { resource } from "./resource-route-support.js";
 import type { AuthRepository } from "../auth/repository.js";
 import { identityRouteConfigs } from "./identity-route-config.js";
 // @windy-module system.audit begin
 import { registerAuditRoutes } from "./audit-routes.js";
 // @windy-module system.audit end
-import {
-  accessCall,
-  importNotSupported,
-  readAccessible,
-  resourceConflict,
-} from "./resource-access-response.js";
-import { runResourceMutation } from "./mutation-runner.js";
-import { registerResourceExportRoute } from "./resource-export-route.js";
-import {
-  projectEntity,
-  projectEntities,
-  projectImportResult,
-} from "./response-projection.js";
 // @windy-module system.data-governance begin
 import { registerUserPlaintextRoutes } from "../data-governance/user-plaintext-routes.js";
 // @windy-module system.data-governance end
-import { searchAuditEvent } from "../audit/search-summary.js";
 import { DepartmentOrganizationPolicy } from "./department-organization.js";
+import { registerResourceRoutes } from "./resource-routes.js";
 
 export type { RouteApp } from "./route-types.js";
 
@@ -144,245 +120,3 @@ export function registerSystemRoutes(
 
   return app;
 }
-
-function registerResourceRoutes<T extends ManagedEntity>(
-  app: RouteApp,
-  config: ResourceRouteConfig<T>,
-  runtime: Parameters<typeof registerSystemRoutes>[2],
-) {
-  app.get(`/system/${config.path}`, (rawContext) => {
-    const { guardContext, query } = routeContext(rawContext);
-    return withPermission(
-      runtime,
-      guardContext,
-      "GET",
-      config.permissionResource,
-      "read",
-      config.feature,
-      async () => {
-        const listQuery = parseListQuery(query);
-        if (listQuery instanceof Response) return listQuery;
-        const result = await accessCall(() =>
-          config.dataAccess.mode === "request"
-            ? config.dataAccess.access.list(
-                listQuery,
-                config.searchFields,
-                guardContext.actor,
-              )
-            : config.repository.list(listQuery, config.searchFields),
-        );
-        if (result instanceof Response) return result;
-        const search = listQuery.q?.trim();
-        if (search) {
-          runtime.auditSink.recordEvent(
-            searchAuditEvent(guardContext, config.path, search, result.total),
-          );
-        }
-        return { ...result, items: projectEntities(config, result.items) };
-      },
-    );
-  });
-
-  if (config.backupExport !== false) {
-    registerResourceExportRoute(app, config, runtime);
-  }
-
-  app.get(`/system/${config.path}/:id`, (rawContext) => {
-    const { guardContext, params } = routeContext(rawContext);
-    return withPermission(
-      runtime,
-      guardContext,
-      "GET",
-      config.permissionResource,
-      "read",
-      config.feature,
-      async () => {
-        const item = await readAccessible(
-          config,
-          requiredId(params),
-          guardContext.actor,
-        );
-        if (item instanceof Response) return item;
-        return item
-          ? projectEntity(config, item)
-          : notFound(config.path, requiredId(params));
-      },
-    );
-  });
-
-  if (config.readonly) {
-    return;
-  }
-
-  app.post(`/system/${config.path}/import`, (rawContext) => {
-    const { guardContext, body } = routeContext(rawContext);
-    return withPermission(
-      runtime,
-      guardContext,
-      "POST",
-      config.permissionResource,
-      "manage",
-      config.feature,
-      async () => {
-        if (config.importable === false) {
-          return importNotSupported();
-        }
-        const payload = parseImportPayload<T>(body);
-        const result = await accessCall(() =>
-          config.dataAccess.mode === "request"
-            ? config.dataAccess.access.importMany(
-                payload.items,
-                guardContext.actor,
-                payload.mode,
-              )
-            : config.repository.importMany(
-                payload.items,
-                guardContext.actor,
-                payload.mode,
-              ),
-        );
-        if (result instanceof Response) return result;
-        await recordMutationAudit(
-          runtime,
-          config.path,
-          resourceEvent(guardContext, "data.import", config.path, undefined, {
-            created: result.created,
-            updated: result.updated,
-            skipped: result.skipped,
-            total: payload.items.length,
-          }),
-        );
-        return {
-          ...projectImportResult(config, result),
-          total: payload.items.length,
-        };
-      },
-    );
-  });
-
-  app.post(`/system/${config.path}`, (rawContext) => {
-    const { guardContext, body } = routeContext(rawContext);
-    return withPermission(
-      runtime,
-      guardContext,
-      "POST",
-      config.permissionResource,
-      "manage",
-      config.feature,
-      async () =>
-        runResourceMutation(config, async () => {
-          const input = asPartial<T>(body);
-          const validationError = await config.validateInput?.(input);
-          if (validationError) return invalidResource(validationError);
-          const policyError = await config.beforeCreate?.(input);
-          if (policyError) return resourceConflict(policyError);
-          const item = await accessCall(() =>
-            config.dataAccess.mode === "request"
-              ? config.dataAccess.access.create(input, guardContext.actor)
-              : config.repository.create(input, guardContext.actor),
-          );
-          if (item instanceof Response) return item;
-          await recordMutationAudit(
-            runtime,
-            config.path,
-            resourceEvent(guardContext, "crud.create", config.path, item.id),
-          );
-          return projectEntity(config, item);
-        }),
-    );
-  });
-
-  app.put(`/system/${config.path}/:id`, (rawContext) => {
-    const { guardContext, params, body } = routeContext(rawContext);
-    return withPermission(
-      runtime,
-      guardContext,
-      "PUT",
-      config.permissionResource,
-      "manage",
-      config.feature,
-      async () =>
-        runResourceMutation(config, async () => {
-          const id = requiredId(params);
-          const input = asPartial<T>(body);
-          const current = await readAccessible(config, id, guardContext.actor);
-          if (current instanceof Response) return current;
-          if (!current) return notFound(config.path, id);
-          const validationError = await config.validateInput?.(input, current);
-          if (validationError) return invalidResource(validationError);
-          const policyError = await config.beforeUpdate?.(current, input);
-          if (policyError) return resourceConflict(policyError);
-          const item = await accessCall(() =>
-            config.dataAccess.mode === "request"
-              ? config.dataAccess.access.update(id, input, guardContext.actor)
-              : config.repository.update(id, input, guardContext.actor),
-          );
-          if (item instanceof Response) return item;
-          if (!item) {
-            return notFound(config.path, id);
-          }
-          await config.afterUpdate?.(current, item, guardContext.actor);
-          await recordMutationAudit(
-            runtime,
-            config.path,
-            resourceEvent(guardContext, "crud.update", config.path, id),
-          );
-          return projectEntity(config, item);
-        }),
-    );
-  });
-
-  app.delete(`/system/${config.path}/:id`, (rawContext) => {
-    const { guardContext, params } = routeContext(rawContext);
-    return withPermission(
-      runtime,
-      guardContext,
-      "DELETE",
-      config.permissionResource,
-      "manage",
-      config.feature,
-      async () =>
-        runResourceMutation(config, async () => {
-          const id = requiredId(params);
-          const current = await readAccessible(config, id, guardContext.actor);
-          if (current instanceof Response) return current;
-          if (!current) return notFound(config.path, id);
-          const policyError = await config.beforeDelete?.(current);
-          if (policyError) return resourceConflict(policyError);
-          const item = await accessCall(() =>
-            config.dataAccess.mode === "request"
-              ? config.dataAccess.access.softDelete(id, guardContext.actor)
-              : config.repository.softDelete(id, guardContext.actor),
-          );
-          if (item instanceof Response) return item;
-          if (!item) {
-            return notFound(config.path, id);
-          }
-          await config.afterDelete?.(item, guardContext.actor);
-          await recordMutationAudit(
-            runtime,
-            config.path,
-            resourceEvent(guardContext, "crud.delete", config.path, id),
-          );
-          return projectEntity(config, item);
-        }),
-    );
-  });
-}
-
-function invalidResource(
-  error: NonNullable<
-    Awaited<
-      ReturnType<
-        NonNullable<ResourceRouteConfig<ManagedEntity>["validateInput"]>
-      >
-    >
-  >,
-): Response {
-  return Response.json(
-    typeof error === "string"
-      ? { error: "INVALID_RESOURCE", message: error }
-      : error,
-    { status: 400 },
-  );
-}

package/template/apps/web/src/pages/system/components/SystemResourceLoadError.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import { Button } from "@/components/ui/button";
+
+defineProps<{
+  error: string;
+}>();
+
+const emit = defineEmits<{
+  retry: [];
+}>();
+</script>
+
+<template>
+  <div
+    class="flex flex-col gap-3 rounded-md border border-destructive/30 bg-destructive/5 p-4 text-sm"
+  >
+    <p class="font-medium text-destructive">加载失败</p>
+    <p class="text-muted-foreground">{{ error }}</p>
+    <Button variant="outline" class="w-fit" @click="emit('retry')">重试</Button>
+  </div>
+</template>

package/template/apps/web/src/pages/system/components/SystemResourceLoadError.webtest.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "vitest";
+import { mount } from "@vue/test-utils";
+import SystemResourceLoadError from "./SystemResourceLoadError.vue";
+
+describe("SystemResourceLoadError", () => {
+  test("展示加载错误并通过显式事件请求重试", async () => {
+    const wrapper = mount(SystemResourceLoadError, {
+      props: { error: "服务暂不可用" },
+    });
+
+    expect(wrapper.text()).toContain("加载失败");
+    expect(wrapper.text()).toContain("服务暂不可用");
+    await wrapper.get("button").trigger("click");
+
+    expect(wrapper.emitted("retry")).toHaveLength(1);
+  });
+});

package/template/apps/web/src/pages/system/components/SystemResourcePage.vue

@@ -3,7 +3,6 @@ import { computed, onMounted, shallowRef } from "vue";
 import type { PermissionDefinition } from "@southwind-ai/shared";
 import ConfirmDialog from "@/components/common/ConfirmDialog.vue";
 import DataPagination from "@/components/common/DataPagination.vue";
-import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import type { SystemRecord } from "@/services/system-api";
 import { useSystemResource } from "../composables/useSystemResource";
@@ -21,6 +20,7 @@ import DepartmentTransitionDialog from "./department/DepartmentTransitionDialog.
 import { useDepartmentTransitions } from "../composables/useDepartmentTransitions";
 import SystemResourceActions from "./SystemResourceActions.vue";
 import SystemResourceEditor from "./SystemResourceEditor.vue";
+import SystemResourceLoadError from "./SystemResourceLoadError.vue";
 // @windy-module system.audit begin
 import AuditLogDetailDialog from "./AuditLogDetailDialog.vue";
 // @windy-module system.audit end
@@ -248,16 +248,11 @@ async function importData(file: File) {
         />
       </CardHeader>
       <CardContent class="space-y-4">
-        <div
+        <SystemResourceLoadError
           v-if="resource.error.value"
-          class="flex flex-col gap-3 rounded-md border border-destructive/30 bg-destructive/5 p-4 text-sm"
-        >
-          <p class="font-medium text-destructive">加载失败</p>
-          <p class="text-muted-foreground">{{ resource.error.value }}</p>
-          <Button variant="outline" class="w-fit" @click="resource.reload"
-            >重试</Button
-          >
-        </div>
+          :error="resource.error.value"
+          @retry="resource.reload"
+        />
         <SystemResourceTable
           v-else
           :columns="config.columns"

package/template/docs/architecture/mcp-business-capabilities.md

@@ -0,0 +1,107 @@
+# MCP 业务能力暴露
+
+## 决策
+
+Windy 以 Module Manifest、Server SDK Handler 和 `GovernedToolRegistry` 组成业务能力深
+模块。MCP、原生 Agent Tool Route 和 Agent Runtime Tool Host 都是该 Interface 的
+Adapter，不拥有业务能力、权限或审计定义。
+
+```text
+业务 Module
+  ├── Manifest：Schema / Tool / Feature / Permission / Audit
+  └── Handler：类型化 JSON 实现
+           │
+           ▼
+  GovernedToolRegistry
+  ├── Schema 与大小限制
+  ├── License / Feature / RBAC / Data Scope
+  ├── Timeout / Audit
+  └── 结构化结果
+           │
+       ┌───┴───────────┐
+       ▼               ▼
+ Agent Tool Route   MCP Adapter
+```
+
+删除 Registry 后，输入输出校验、Guard、Scope、超时和审计复杂度会重新散落到多个调用面；
+因此该模块承担了真实的平台复杂度，而不是协议转发层。
+
+## 为什么不直接包装 OpenAPI
+
+HTTP Route 面向确定性客户端，参数经常包含分页、传输和页面交互细节。MCP Tool 面向模型
+选择和结构化调用，需要更小、语义明确、风险可治理的 Interface。自动包装所有 OpenAPI
+会导致：
+
+- 模型看到大量浅层 CRUD；
+- 页面传输参数成为模型契约；
+- 写操作缺少幂等和审批语义；
+- Route、Tool、权限和审计产生多套漂移定义。
+
+因此业务模块显式选择哪些能力成为 Tool；OpenAPI 和 MCP 可以调用同一业务 Service，
+但不会相互自动推导。
+
+## MCP Transport
+
+远程接入已采用官方 MCP TypeScript SDK `1.29.0` 和无状态 Streamable HTTP，Endpoint
+为 `/api/mcp`。v2 在当前实施时仍为预发布，不进入生产依赖。无状态模式适合当前只读
+请求，也避免把授权快照保存为长期 Session 状态。
+
+MCP Endpoint 必须位于现有 Server 身份解析之后：
+
+- Bearer/Cookie 只用于解析当前 Server Actor，入口另需通过 `system.agent` Feature 与
+  `system.agent.read` Permission；
+- `tools/list` 只返回当前 Actor 获准的只读 Tool；
+- `tools/call` 每次重新经过 Registry，不复用列表阶段的授权结论；
+- 客户端参数不能提供 Permission、Feature、License、Actor 或 Scope；
+- MCP 协议错误与业务 Guard 错误使用稳定、脱敏的错误信息。
+
+## Tool、Resource 与 Skill
+
+当前只提供 Tool：
+
+- Tool 对应可执行的类型化业务查询；
+- Resource 等出现明确的只读文档或静态能力目录消费场景后再增加；
+- Prompt 不作为业务规则来源。
+
+Skill 解决开发流程，不属于运行时授权 Interface。仓库内开发 Skill 指导 Agent：
+
+1. 创建业务模块和 Manifest；
+2. 注册 Feature、Permission、Audit 与 JSON Schema；
+3. 实现 Repository、Service 和 Tool Handler；
+4. 增加 Composition、Guard、Data Scope 与 Schema 测试；
+5. 使用脚手架和真实生成回归验证。
+
+Skill 内容可以从稳定契约和模板派生，但不能独立声明 Tool Key 或授权事实。
+`.agents/skills/windy-business-module/SKILL.md` 随 Starter 一起分发，并指向 Manifest、
+Module Host 和 Tool Handler 的代码事实源。生成组合未包含 `system.agent` 时，Skill
+要求明确物理边界，不在业务层另建 MCP 或授权实现。
+
+## 写操作门槛
+
+MCP Adapter 只暴露 `operation=query`。开放 `command/background` 前必须完成：
+
+- 强制幂等键及结果重放语义；
+- 风险分级和人工审批；
+- Durable Job/结果状态引用；
+- Actor、请求、审批和业务副作用的完整关联；
+- 超时后真实副作用是否仍继续的明确语义；
+- 重试、取消和补偿回归。
+
+在这些条件满足前，Manifest 可以预先描述写能力，但 MCP Adapter 必须过滤它们。
+
+## 运维与验证
+
+- Server 启动前校验声明、Schema 和 Handler 一一对应。
+- MCP 不可用不能影响普通业务 Route 和非 AI 能力启动。
+- 审计只记录 Tool Key、Actor、Request ID、输入输出字节数和结果，不保存原始内容。
+- 回归至少覆盖未授权不可发现、直接调用重新授权、Schema 拒绝、数据范围不可扩大和
+  Handler 输出漂移。
+- MCP API Path、Server 身份、Route 与 Manifest Binding 使用
+  `packages/shared/src/mcp.ts` 的共享 Contract；生成 README 通过跨层测试校对该路径。
+- Tool 目录从当前 Module Manifest 组合，不在 README 或 Skill 固化。新模板通过发布时
+  `template:sync` 更新；既有客户项目只通过显式 `windy update` 合并，不远程静默改写。
+
+官方协议与 SDK 资料：
+
+- [MCP TypeScript SDK v1](https://ts.sdk.modelcontextprotocol.io/)
+- [MCP Server 与 Streamable HTTP](https://ts.sdk.modelcontextprotocol.io/server)

package/template/docs/development/custom-login-page.md

@@ -78,9 +78,9 @@ composable。
 先提交当前业务改动并保持 Git 工作区干净，然后执行：
 
 ```bash
-bunx --bun create-windy@0.3.0 update --check --cwd .
-bunx --bun create-windy@0.3.0 update --dry-run --cwd .
-bunx --bun create-windy@0.3.0 update --cwd .
+bunx --bun create-windy@0.3.1 update --check --cwd .
+bunx --bun create-windy@0.3.1 update --dry-run --cwd .
+bunx --bun create-windy@0.3.1 update --cwd .
 bun install
 ```
 

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

@@ -212,14 +212,14 @@ SSE 事件包括 `output.delta`、`tool.requested`、`tool.completed`、usage，
 `run.completed`、`run.failed` 或 `run.cancelled` 终态。断线后使用已确认 sequence 作为
 cursor 恢复；不要重新创建 Run 或重复执行 Tool。
 
-## 从 create-windy 0.2.34 升级到 0.3.0
+## 从 create-windy 0.2.34 升级到 0.3.1
 
-`0.2.34 → 0.3.0` 使用连续 recipe，不需要逐个安装中间 CLI。确认 npm registry 已能
-解析精确的 `0.3.0` artifact 后，先检查计划，再应用：
+目标 CLI 会一次解析 `0.2.34 → 0.3.0 → 0.3.1` 连续 recipe，不需要逐个安装中间
+CLI。确认 npm registry 已能解析精确的 `0.3.1` artifact 后，先检查计划，再应用：
 
 ```bash
-bunx --bun create-windy@0.3.0 update --check
-bunx --bun create-windy@0.3.0 update
+bunx --bun create-windy@0.3.1 update --check
+bunx --bun create-windy@0.3.1 update
 bun install
 ```
 

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

@@ -94,6 +94,10 @@ Transport 返回协议允许的状态。
 http://localhost:9747/api/mcp
 ```
 
+普通 Server 已提供该 Endpoint，不需要启动 `dev:agent`。非浏览器 MCP 客户端先通过
+`POST /api/auth/api/login` 获取 Bearer Token，再调用 `tools/list` 获取当前账号实时可见
+的 Tool 与 JSON Schema；客户端和文档都不应固化 Tool 清单。
+
 MCP 使用无状态模式，不保存授权快照或长期 Session。Feature、角色或数据范围变化会在下一次
 调用立即生效。
 

package/template/packages/modules/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/modules",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {