create-windy 0.8.2 → 0.9.1

package/template/apps/web/src/services/agent-admin-api.ts

@@ -0,0 +1,155 @@
+import type {
+  AgentAdminOperationCatalogItem,
+  AgentAdminToolCatalogItem,
+  AgentWorkbenchRecordingSummaryV1,
+  AgentWorkbenchRecordingV1,
+  AgentWorkbenchEventV1,
+  JsonValue,
+} from "@southwind-ai/shared";
+import { apiRequest, apiResponse } from "./http";
+import { publicWorkbenchEvent } from "./agent-workbench-event";
+
+const policy = { suppressFailureHandler: true };
+export function listAdminTools(signal?: AbortSignal) {
+  return apiRequest<readonly AgentAdminToolCatalogItem[]>(
+    "/agent/admin/tools",
+    { signal },
+    policy,
+  );
+}
+export function listAdminOperations(signal?: AbortSignal) {
+  return apiRequest<readonly AgentAdminOperationCatalogItem[]>(
+    "/agent/admin/operations",
+    { signal },
+    policy,
+  );
+}
+export function listWorkbenchRecordings(
+  source: "harness" | "business",
+  signal?: AbortSignal,
+) {
+  return apiRequest<{ items: readonly AgentWorkbenchRecordingSummaryV1[] }>(
+    `/agent/admin/session-recordings?source=${source}`,
+    { signal },
+    policy,
+  );
+}
+export function getWorkbenchRecording(
+  sessionId: string,
+  source: "harness" | "business",
+  signal?: AbortSignal,
+) {
+  return apiRequest<AgentWorkbenchRecordingV1>(
+    `/agent/admin/session-recordings/${encodeURIComponent(sessionId)}?source=${source}`,
+    { signal },
+    policy,
+  );
+}
+export function createTestSession(signal?: AbortSignal) {
+  return apiRequest<{ sessionId: string }>(
+    "/agent/admin/test-sessions",
+    { method: "POST", body: "{}", signal },
+    policy,
+  );
+}
+export function createTestRun(
+  operationKey: string,
+  input: JsonValue,
+  sessionId: string,
+  signal?: AbortSignal,
+) {
+  return apiRequest<{ runId: string; status: string }>(
+    "/agent/runs",
+    {
+      method: "POST",
+      body: JSON.stringify({ operationKey, input, sessionId }),
+      headers: { "idempotency-key": crypto.randomUUID() },
+      signal,
+    },
+    policy,
+  );
+}
+function runPath(
+  runId: string,
+  operationKey: string,
+  action: string,
+  sessionId: string,
+) {
+  return `/agent/runs/${encodeURIComponent(runId)}/${action}?${new URLSearchParams({ operationKey, sessionId })}`;
+}
+export function getTestRunResult(
+  runId: string,
+  operationKey: string,
+  sessionId: string,
+  signal?: AbortSignal,
+) {
+  return apiRequest<{ status: string; output?: JsonValue }>(
+    runPath(runId, operationKey, "result", sessionId),
+    { signal },
+    policy,
+  );
+}
+export function cancelTestRun(
+  runId: string,
+  operationKey: string,
+  sessionId: string,
+  signal?: AbortSignal,
+) {
+  return apiRequest<unknown>(
+    runPath(runId, operationKey, "cancel", sessionId),
+    {
+      method: "POST",
+      body: JSON.stringify({ operationKey, sessionId }),
+      signal,
+    },
+    policy,
+  );
+}
+/** The server publishes a controlled summary; never retain arbitrary provider payloads. */
+export async function streamTestRun(
+  runId: string,
+  operationKey: string,
+  sessionId: string,
+  onEvent: (event: AgentWorkbenchEventV1) => void,
+  signal: AbortSignal,
+) {
+  const response = await apiResponse(
+    runPath(runId, operationKey, "events", sessionId),
+    { signal, headers: { accept: "text/event-stream" } },
+    policy,
+  );
+  if (!response.body) throw new Error("运行事件流不可用，请手动刷新会话");
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (!signal.aborted) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      buffer += decoder.decode(chunk.value, { stream: true });
+      buffer = buffer.replace(/\r\n/g, "\n");
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary !== -1) {
+        if (boundary > 1_048_576)
+          throw new Error("事件流超出安全大小，请手动刷新");
+        const frame = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        const data = frame
+          .split("\n")
+          .filter((line) => line.startsWith("data:"))
+          .map((line) => line.slice(5).trimStart())
+          .join("\n");
+        if (data) {
+          const event = publicWorkbenchEvent(JSON.parse(data));
+          if (event) onEvent(event);
+        }
+        boundary = buffer.indexOf("\n\n");
+      }
+      if (buffer.length > 1_048_576)
+        throw new Error("事件流超出安全大小，请手动刷新");
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}

package/template/apps/web/src/services/agent-admin-api.webtest.ts

@@ -0,0 +1,120 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+const mocks = vi.hoisted(() => ({ request: vi.fn(), response: vi.fn() }));
+vi.mock("./http", () => ({
+  apiRequest: mocks.request,
+  apiResponse: mocks.response,
+}));
+import {
+  cancelTestRun,
+  createTestRun,
+  createTestSession,
+  getTestRunResult,
+  getWorkbenchRecording,
+  streamTestRun,
+} from "./agent-admin-api";
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.request.mockResolvedValue({});
+});
+describe("工作台正常治理 API 契约", () => {
+  test("创建真实Session/run并绑定幂等键，result/cancel带同一Session与Operation", async () => {
+    const controller = new AbortController();
+    await createTestSession(controller.signal);
+    await createTestRun(
+      "finance.query",
+      { question: "sum" },
+      "session_one",
+      controller.signal,
+    );
+    expect(mocks.request.mock.calls[0]?.[0]).toBe("/agent/admin/test-sessions");
+    const request = mocks.request.mock.calls[1]!;
+    expect(request[0]).toBe("/agent/runs");
+    expect(JSON.parse(request[1].body)).toEqual({
+      operationKey: "finance.query",
+      input: { question: "sum" },
+      sessionId: "session_one",
+    });
+    expect(request[1].headers["idempotency-key"]).toMatch(/^[0-9a-f-]{36}$/);
+    expect(request[1].signal).toBe(controller.signal);
+    await getTestRunResult(
+      "run_one",
+      "finance.query",
+      "session_one",
+      controller.signal,
+    );
+    await cancelTestRun(
+      "run_one",
+      "finance.query",
+      "session_one",
+      controller.signal,
+    );
+    expect(mocks.request.mock.calls[2]?.[0]).toBe(
+      "/agent/runs/run_one/result?operationKey=finance.query&sessionId=session_one",
+    );
+    expect(mocks.request.mock.calls[3]?.[0]).toContain(
+      "/cancel?operationKey=finance.query&sessionId=session_one",
+    );
+    expect(mocks.request.mock.calls[3]?.[1].signal).toBe(controller.signal);
+  });
+  test("历史读取只请求受控recording，不触发result或启动接口", async () => {
+    await getWorkbenchRecording("business/session", "business");
+    expect(mocks.request).toHaveBeenCalledTimes(1);
+    expect(mocks.request.mock.calls[0]?.[0]).toBe(
+      "/agent/admin/session-recordings/business%2Fsession?source=business",
+    );
+  });
+  test("SSE跨chunk CRLF与UTF8、同chunk多frame不会漏事件或保留私有参数", async () => {
+    const encoder = new TextEncoder();
+    const frames = [
+      'data: {"sequence":1,"type":"tool.requested","summary":"位置工具","arguments":{"token":"hidden"}}\r\n\r\n',
+      'data: {"sequence":2,"type":"run.completed","summary":"已完成"}\r\n\r\n',
+    ].join("");
+    const bytes = encoder.encode(frames);
+    const split =
+      frames.indexOf("\r\n") +
+      encoder.encode("位置工具").length -
+      "位置工具".length +
+      1;
+    mocks.response.mockResolvedValue(
+      new Response(
+        new ReadableStream({
+          start(controller) {
+            controller.enqueue(bytes.slice(0, split));
+            controller.enqueue(bytes.slice(split));
+            controller.close();
+          },
+        }),
+      ),
+    );
+    const events: unknown[] = [];
+    await streamTestRun(
+      "run_1",
+      "query",
+      "session_1",
+      (event) => events.push(event),
+      new AbortController().signal,
+    );
+    expect(events).toHaveLength(2);
+    expect(JSON.stringify(events)).toContain("位置工具");
+    expect(JSON.stringify(events)).not.toContain("hidden");
+  });
+  test("单chunk的多个合法frame总大小超过1MB仍逐条处理", async () => {
+    const data = Array.from(
+      { length: 100 },
+      (_, index) =>
+        `data: ${JSON.stringify({ sequence: index + 1, type: "output.delta", summary: "a".repeat(11000) })}\n\n`,
+    ).join("");
+    mocks.response.mockResolvedValue(new Response(data));
+    let count = 0;
+    await streamTestRun(
+      "run_1",
+      "query",
+      "session_1",
+      () => {
+        count += 1;
+      },
+      new AbortController().signal,
+    );
+    expect(count).toBe(100);
+  });
+});

package/template/apps/web/src/services/agent-skills-api.ts

@@ -0,0 +1,55 @@
+import type {
+  AgentSkillBundle,
+  AgentSkillCommandRequest,
+  AgentSkillGovernanceItem,
+  AgentSkillVersion,
+  ImportAgentSkillRequest,
+} from "@southwind-ai/shared";
+import { apiRequest } from "./http";
+export type {
+  AgentSkillGovernanceItem,
+  AgentSkillVersion,
+  ImportAgentSkillRequest,
+};
+export function listGovernedAgentSkills(signal?: AbortSignal) {
+  return apiRequest<readonly AgentSkillGovernanceItem[]>("/agent/skills", {
+    signal,
+  });
+}
+export function readAgentSkill(key: string, signal?: AbortSignal) {
+  return apiRequest<{ skill: AgentSkillVersion; bundle: AgentSkillBundle }>(
+    `/agent/skills/${encodeURIComponent(key)}`,
+    { signal },
+  );
+}
+export function listAgentSkillVersions(key: string, signal?: AbortSignal) {
+  return apiRequest<readonly AgentSkillVersion[]>(
+    `/agent/skills/${encodeURIComponent(key)}/versions`,
+    { signal },
+  );
+}
+export function importAgentSkill(
+  input: ImportAgentSkillRequest,
+  idempotencyKey: string,
+) {
+  return apiRequest<AgentSkillVersion>("/agent/skills", {
+    method: "POST",
+    headers: { "idempotency-key": idempotencyKey },
+    body: JSON.stringify(input),
+  });
+}
+export function governAgentSkill(
+  key: string,
+  action: "disable" | "rollback",
+  input: AgentSkillCommandRequest,
+  idempotencyKey: string,
+) {
+  return apiRequest<AgentSkillVersion>(
+    `/agent/skills/${encodeURIComponent(key)}/${action}`,
+    {
+      method: "POST",
+      headers: { "idempotency-key": idempotencyKey },
+      body: JSON.stringify(input),
+    },
+  );
+}

package/template/apps/web/src/services/agent-workbench-event.ts

@@ -0,0 +1,60 @@
+import type { AgentWorkbenchEventV1 } from "@southwind-ai/shared";
+/** Defense in depth: discard fields outside the server's public event contract. */
+export function publicWorkbenchEvent(
+  value: unknown,
+): AgentWorkbenchEventV1 | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return;
+  const raw = value as Record<string, unknown>;
+  if (
+    !Number.isSafeInteger(raw.sequence) ||
+    Number(raw.sequence) < 0 ||
+    typeof raw.type !== "string"
+  )
+    return;
+  const summary = typeof raw.summary === "string" ? raw.summary : raw.type;
+  const strings = [
+    "occurredAt",
+    "runId",
+    "turnId",
+    "stepId",
+    "modelAttemptId",
+    "toolCallId",
+    "toolKey",
+    "workItemId",
+    "artifactId",
+    "workflowRunId",
+    "nodeRunId",
+    "outcome",
+  ] as const;
+  const refs = Object.fromEntries(
+    strings.flatMap((key) =>
+      typeof raw[key] === "string" ? [[key, raw[key]]] : [],
+    ),
+  );
+  const usage =
+    raw.usage && typeof raw.usage === "object" && !Array.isArray(raw.usage)
+      ? (raw.usage as Record<string, unknown>)
+      : undefined;
+  const measured = usage
+    ? Object.fromEntries(
+        ["inputTokens", "outputTokens", "totalTokens", "costMicros"].flatMap(
+          (key) =>
+            typeof usage[key] === "number" &&
+            Number.isFinite(usage[key]) &&
+            Number(usage[key]) >= 0
+              ? [[key, usage[key]]]
+              : [],
+        ),
+      )
+    : undefined;
+  return {
+    sequence: Number(raw.sequence),
+    type: raw.type,
+    summary,
+    ...refs,
+    ...(Number.isSafeInteger(raw.attemptSequence)
+      ? { attemptSequence: Number(raw.attemptSequence) }
+      : {}),
+    ...(measured ? { usage: measured } : {}),
+  };
+}

package/template/apps/web/src/services/agent-workflow-api.ts

@@ -1,4 +1,9 @@
 import { apiRequest } from "./http";
+import type { AgentWorkflowPresetListResponse } from "@southwind-ai/shared";
+export type {
+  AgentWorkflowPresetListResponse,
+  AgentWorkflowPresetSummary,
+} from "@southwind-ai/shared";
 
 export type AgentWorkflowRunStatus =
   | "accepted"
@@ -179,3 +184,10 @@ export function getAgentWorkflowRun(runId: string, signal?: AbortSignal) {
 function requestOptions(signal?: AbortSignal): { signal?: AbortSignal } {
   return signal ? { signal } : {};
 }
+
+export function listAgentWorkflowPresets(signal?: AbortSignal) {
+  return apiRequest<AgentWorkflowPresetListResponse>(
+    "/agent/workflows/presets",
+    requestOptions(signal),
+  );
+}

package/template/apps/web/src/services/diagnostics-api.ts

@@ -0,0 +1,12 @@
+import type { DiagnosticRecord } from "@southwind-ai/shared";
+import { apiRequest } from "./http";
+
+export type { DiagnosticRecord } from "@southwind-ai/shared";
+
+export function getDiagnostic(id: string, signal: AbortSignal) {
+  return apiRequest<DiagnosticRecord>(
+    `/system/diagnostics/${encodeURIComponent(id)}`,
+    { signal, cache: "no-store" },
+    { suppressFailureHandler: true },
+  );
+}

package/template/apps/web/src/services/http.ts

@@ -25,6 +25,7 @@ export interface ApiClientOptions {
 export interface ApiFailure {
   kind: "internal" | "maintenance" | "network";
   requestId?: string;
+  diagnosticId?: string;
 }
 
 export class ApiError extends Error {
@@ -34,6 +35,7 @@ export class ApiError extends Error {
     readonly code?: string,
     readonly reason?: string,
     readonly requestId?: string,
+    readonly diagnosticId?: string,
   ) {
     super(message);
     this.name = "ApiError";
@@ -87,6 +89,7 @@ export function createApiClient(options: ApiClientOptions) {
         failureHandler?.({
           kind: result.status === 503 ? "maintenance" : "internal",
           requestId: error.requestId,
+          ...(error.diagnosticId ? { diagnosticId: error.diagnosticId } : {}),
         });
       }
       throw error;
@@ -126,6 +129,9 @@ export function createApiClient(options: ApiClientOptions) {
 }
 
 async function readApiError(response: Response): Promise<ApiError> {
+  const diagnosticId = diagnosticIdFrom(
+    response.headers.get("x-diagnostic-id"),
+  );
   try {
     const payload = (await response.json()) as {
       error?: string;
@@ -142,6 +148,7 @@ async function readApiError(response: Response): Promise<ApiError> {
       payload.error,
       payload.reason,
       response.headers.get("x-request-id") || undefined,
+      diagnosticId,
     );
   } catch {
     return new ApiError(
@@ -150,10 +157,21 @@ async function readApiError(response: Response): Promise<ApiError> {
       undefined,
       undefined,
       response.headers.get("x-request-id") || undefined,
+      diagnosticId,
     );
   }
 }
 
+/** Server diagnostic coordinates remain separate from request correlation IDs. */
+export function diagnosticIdFrom(value: unknown): string | undefined {
+  return typeof value === "string" &&
+    /^diag-[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(
+      value,
+    )
+    ? value
+    : undefined;
+}
+
 function configuredDevelopmentToken(): string | undefined {
   if (!import.meta.env.DEV || import.meta.env.VITE_DEV_AUTH_BYPASS !== "1") {
     return undefined;

package/template/apps/web/src/services/http.webtest.ts

@@ -110,6 +110,57 @@ describe("Web HTTP 会话策略", () => {
     ]);
   });
 
+  test.each([true, false])(
+    "保留服务端诊断编号且兼容 JSON/非 JSON 错误响应：%s",
+    async (json) => {
+      const diagnosticId = "diag-019a1234-5678-7000-8000-000000000001";
+      const headers = {
+        "x-request-id": "req-diagnostic",
+        "x-diagnostic-id": diagnosticId,
+      };
+      const client = createApiClient({
+        apiBase: "/api",
+        fetcher: async () =>
+          json
+            ? Response.json({ error: "UNAVAILABLE" }, { status: 503, headers })
+            : new Response("proxy unavailable", { status: 503, headers }),
+      });
+      const failures = vi.fn();
+      client.setFailureHandler(failures);
+      await expect(client.request("/failure")).rejects.toMatchObject({
+        status: 503,
+        requestId: "req-diagnostic",
+        diagnosticId,
+      });
+      expect(failures).toHaveBeenCalledWith({
+        kind: "maintenance",
+        requestId: "req-diagnostic",
+        diagnosticId,
+      });
+    },
+  );
+
+  test("不把 Request ID 或任意响应头伪装为服务端诊断编号", async () => {
+    const client = createApiClient({
+      apiBase: "/api",
+      fetcher: async () =>
+        Response.json(
+          { error: "UNAVAILABLE" },
+          {
+            status: 503,
+            headers: {
+              "x-request-id": "req-preserved",
+              "x-diagnostic-id": "not-a-diagnostic",
+            },
+          },
+        ),
+    });
+    await expect(client.request("/failure")).rejects.toMatchObject({
+      requestId: "req-preserved",
+      diagnosticId: undefined,
+    });
+  });
+
   test("传输失败进入网络异常，调用方可显式抑制全局错误页", async () => {
     const failures = vi.fn();
     const fetcher = vi.fn<typeof fetch>(async () => {

package/template/apps/web/vite.config.ts

@@ -1,3 +1,10 @@
+// @windy-module system.agent begin
+import {
+  isDshWorkbenchPath,
+  dshWorkbenchProxyPath,
+  dshWorkbenchLoginPath,
+} from "./dsh-workbench-location";
+// @windy-module system.agent end
 import { spawnSync } from "node:child_process";
 import { fileURLToPath, URL } from "node:url";
 import tailwindcss from "@tailwindcss/vite";
@@ -43,6 +50,38 @@ export default defineConfig({
     strictPort: true,
     watch: usePolling ? { usePolling: true, interval: 200 } : undefined,
     proxy: {
+      // @windy-module system.agent begin
+      "^/agent(?:$|[/?])": {
+        target: process.env.API_UPSTREAM ?? "http://localhost:9747",
+        ws: true,
+        bypass: (request) =>
+          isDshWorkbenchPath(request.url ?? "/") ? undefined : "/index.html",
+        rewrite: dshWorkbenchProxyPath,
+        configure(proxy) {
+          proxy.on("proxyReq", (upstream, request) => {
+            for (const name of Object.keys(request.headers))
+              if (
+                name.startsWith("x-windy-") ||
+                name.startsWith("x-forwarded-") ||
+                name === "forwarded"
+              )
+                upstream.removeHeader(name);
+          });
+          proxy.on("proxyRes", (response, request) => {
+            const login = dshWorkbenchLoginPath(
+              (request.url ?? "/").replace(
+                /^\/api\/agent\/native\/(?=\?|$)/,
+                "/agent",
+              ),
+            );
+            if (response.statusCode === 401 && login) {
+              response.statusCode = 302;
+              response.headers.location = login;
+            }
+          });
+        },
+      },
+      // @windy-module system.agent end
       "/api": process.env.API_UPSTREAM ?? "http://localhost:9747",
     },
   },

package/template/deploy/dsh/README.md

@@ -0,0 +1,5 @@
+# 内置 DSH 的构建资料
+
+DSH通过`apps/agent-server` Bun workspace和原有Agent Server镜像交付；用户从Windy同源`/agent`进入。此目录只保存离线文档工具的依赖锁及说明，不创建独立DSH服务、端口或镜像栈。
+
+运行、隔离、容量和验证边界见[内置接入方案](../../docs/architecture/embedded-dsh-integration.md)，构建与重置步骤见[迁移运维](../../docs/operations/dsh-agent-migration.md)。

package/template/deploy/dsh/documents/README.md

@@ -0,0 +1,9 @@
+# Agent 离线文档工具
+
+Python仅供文档工具使用，Agent执行内核由Node/DSH承担。`requirements.in`描述直接依赖，`requirements.lock`固定完整版本与hash；Agent Server镜像在构建时下载wheel，最终环境从本地归档离线安装。运行时不安装新包。
+
+工具源位于`apps/agent-server/documents`，包括Office读写、工作区边界、报告与烟雾探针。只能处理当前用户已授权的工作区文件；正式业务回存仍走所属模块服务和审批。
+
+DOCX在线预览沿用DSH官方`office-to-pdf`、固定`libreoffice-kit-wasm@0.1.5`与PDF.js。完整WASM包、许可证、源码配方和完整性清单随同Agent镜像保存；Python包或系统LibreOffice不替代该预览链路。
+
+更新依赖时使用实际解析结果生成锁，验证Linux原生架构与文档产物。禁止只改hash或在运行容器下载补丁。配置、资源限制和验收说明见[迁移运维](../../../docs/operations/dsh-agent-migration.md)。

package/template/deploy/dsh/documents/requirements.in

@@ -0,0 +1,6 @@
+# Direct dependencies. Install requirements.lock with --require-hashes instead.
+python-docx==1.2.0
+openpyxl==3.1.5
+pypdf==6.20.1
+reportlab==5.0.1
+defusedxml==0.7.1