create-windy 0.8.1 → 0.8.3

package/template/apps/web/src/pages/system/composables/useAgentWorkbench.webtest.ts

@@ -0,0 +1,164 @@
+import { defineComponent, shallowRef } from "vue";
+import { flushPromises, mount } from "@vue/test-utils";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import type { AgentWorkbenchRecordingV1 } from "@southwind-ai/shared";
+const mocks = vi.hoisted(() => ({
+  list: vi.fn(),
+  operations: vi.fn(),
+  detail: vi.fn(),
+  session: vi.fn(),
+  run: vi.fn(),
+  stream: vi.fn(),
+  result: vi.fn(),
+  cancel: vi.fn(),
+}));
+vi.mock("@/services/agent-admin-api", () => ({
+  listWorkbenchRecordings: mocks.list,
+  listAdminOperations: mocks.operations,
+  getWorkbenchRecording: mocks.detail,
+  createTestSession: mocks.session,
+  createTestRun: mocks.run,
+  streamTestRun: mocks.stream,
+  getTestRunResult: mocks.result,
+  cancelTestRun: mocks.cancel,
+}));
+const fingerprint = shallowRef("actor-one");
+vi.mock("@/composables/useAccessSnapshot", () => ({
+  useAccessSnapshot: () => ({
+    fingerprint,
+    snapshot: shallowRef({
+      actor: { permissionKeys: ["system.agent-debug.manage"] },
+    }),
+  }),
+}));
+vi.mock("@/composables/useAuthSession", () => ({
+  useAuthSession: () => ({ actor: shallowRef({ id: "actor-one" }) }),
+}));
+import { useAgentWorkbench } from "./useAgentWorkbench";
+const history: AgentWorkbenchRecordingV1 = {
+  source: "harness",
+  sessionId: "session_test",
+  title: "测试",
+  updatedAt: "today",
+  mode: "read-only",
+  sideEffectPolicy: "no-reexecution",
+  correlationStatus: "complete",
+  timeline: [],
+  messages: [],
+  runs: [],
+  workflows: [],
+  missing: [],
+};
+function setup() {
+  let state!: ReturnType<typeof useAgentWorkbench>;
+  const wrapper = mount(
+    defineComponent({
+      setup() {
+        state = useAgentWorkbench();
+        return () => null;
+      },
+    }),
+  );
+  return { state, wrapper };
+}
+beforeEach(() => {
+  fingerprint.value = "actor-one";
+  vi.clearAllMocks();
+  mocks.list.mockResolvedValue({ items: [] });
+  mocks.operations.mockResolvedValue([]);
+  mocks.detail.mockResolvedValue(history);
+  mocks.session.mockResolvedValue({ sessionId: "session_test" });
+  mocks.run.mockResolvedValue({ runId: "run_test", status: "accepted" });
+  mocks.result.mockResolvedValue({
+    status: "completed",
+    output: { total: 12 },
+  });
+  mocks.cancel.mockResolvedValue({});
+  mocks.stream.mockImplementation(
+    async (_run, _operation, _session, onEvent) => {
+      onEvent({ sequence: 1, type: "run.completed", summary: "已完成" });
+    },
+  );
+});
+describe("真实测试工作台编排", () => {
+  test("选中的历史 canonical Session 只读，另起运行使用新 Session", async () => {
+    const { state, wrapper } = setup();
+    await flushPromises();
+    await state.select({
+      source: "harness",
+      sessionId: "session_historical",
+      title: "历史",
+      updatedAt: "today",
+    });
+    expect(mocks.run).not.toHaveBeenCalled();
+    await state.start("finance.query", {});
+    await flushPromises();
+    expect(mocks.session).toHaveBeenCalledTimes(1);
+    expect(mocks.run.mock.calls[0]?.[2]).toBe("session_test");
+    wrapper.unmount();
+  });
+
+  test("使用常规治理API，成功结果后同一Session可以再运行，不重复建Session", async () => {
+    const { state, wrapper } = setup();
+    await flushPromises();
+    expect(await state.start("finance.query", { request: "sum" })).toBe(true);
+    await flushPromises();
+    expect(state.output.value).toEqual({ total: 12 });
+    expect(await state.start("finance.query", { request: "next" })).toBe(true);
+    await flushPromises();
+    expect(mocks.session).toHaveBeenCalledTimes(1);
+    expect(mocks.run).toHaveBeenCalledTimes(2);
+    expect(mocks.run.mock.calls[1]?.slice(0, 3)).toEqual([
+      "finance.query",
+      { request: "next" },
+      "session_test",
+    ]);
+    wrapper.unmount();
+  });
+  test("只读业务选择不会启动模型；另起测试使用独立Session", async () => {
+    const { state, wrapper } = setup();
+    await flushPromises();
+    await state.select({
+      source: "business",
+      sessionId: "copilot_one",
+      title: "业务",
+      updatedAt: "today",
+    });
+    expect(mocks.run).not.toHaveBeenCalled();
+    expect(mocks.stream).not.toHaveBeenCalled();
+    expect(mocks.result).not.toHaveBeenCalled();
+    await state.start("finance.query", {});
+    await flushPromises();
+    expect(mocks.run.mock.calls[0]?.[2]).toBe("session_test");
+    wrapper.unmount();
+  });
+  test("手动取消运行与离开detach分开，授权变化会隐藏旧记录", async () => {
+    mocks.stream.mockImplementation(() => new Promise(() => {}));
+    const { state, wrapper } = setup();
+    await flushPromises();
+    await state.start("finance.query", {});
+    await state.cancel();
+    expect(mocks.cancel.mock.calls[0]?.slice(0, 3)).toEqual([
+      "run_test",
+      "finance.query",
+      "session_test",
+    ]);
+    fingerprint.value = "actor-two";
+    await flushPromises();
+    expect(state.liveRun.value).toBeUndefined();
+    expect(state.recording.value).toBeUndefined();
+    expect(state.sessions.value).toEqual([]);
+    wrapper.unmount();
+    expect(mocks.cancel).toHaveBeenCalledTimes(1);
+  });
+  test("新建失败保留错误且不自动重试", async () => {
+    mocks.run.mockRejectedValue(new Error("Runtime不可用"));
+    const { state, wrapper } = setup();
+    await flushPromises();
+    expect(await state.start("finance.query", {})).toBe(false);
+    await flushPromises();
+    expect(state.error.value).toContain("Runtime不可用");
+    expect(mocks.run).toHaveBeenCalledTimes(1);
+    wrapper.unmount();
+  });
+});

package/template/apps/web/src/pages/system/composables/useSessionReplay.ts

@@ -0,0 +1,48 @@
+import { computed, onBeforeUnmount, shallowRef, watch, type Ref } from "vue";
+import type { AgentWorkbenchEventV1 } from "@southwind-ai/shared";
+/** Local playback changes only the visible cursor; it never calls a runtime. */
+export function useSessionReplay(
+  events: Readonly<Ref<readonly AgentWorkbenchEventV1[]>>,
+) {
+  const cursor = shallowRef(-1);
+  const playing = shallowRef(false);
+  const speed = shallowRef(1);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const current = computed(() => events.value[cursor.value]);
+  const visible = computed(() => events.value.slice(0, cursor.value + 1));
+  function pause() {
+    playing.value = false;
+    if (timer) clearTimeout(timer);
+    timer = undefined;
+  }
+  function seek(index: number) {
+    pause();
+    cursor.value = Math.max(-1, Math.min(index, events.value.length - 1));
+  }
+  function advance() {
+    if (!playing.value) return;
+    if (cursor.value >= events.value.length - 1) {
+      pause();
+      return;
+    }
+    cursor.value += 1;
+    timer = setTimeout(advance, 1000 / speed.value);
+  }
+  function play() {
+    if (cursor.value >= events.value.length - 1) cursor.value = -1;
+    playing.value = true;
+    advance();
+  }
+  watch(events, () => {
+    pause();
+    cursor.value = events.value.length ? 0 : -1;
+  });
+  watch(speed, () => {
+    if (playing.value) {
+      pause();
+      play();
+    }
+  });
+  onBeforeUnmount(pause);
+  return { cursor, playing, speed, current, visible, seek, pause, play };
+}

package/template/apps/web/src/router/index.ts

@@ -20,6 +20,8 @@ import SystemOperationsPage from "@/pages/system/SystemOperationsPage.vue";
 // @windy-module system.operations end
 // @windy-module system.agent begin
 import AiRuntimePage from "@/pages/system/AiRuntimePage.vue";
+import AgentToolsPage from "@/pages/system/AgentToolsPage.vue";
+import AgentDebugPage from "@/pages/system/AgentDebugPage.vue";
 import AgentSessionPage from "@/pages/system/AgentSessionPage.vue";
 import AgentWorkflowPage from "@/pages/system/AgentWorkflowPage.vue";
 // @windy-module system.agent end
@@ -101,6 +103,8 @@ const platformAdminPageComponents: Partial<
   operations: SystemOperationsPage,
   // @windy-module system.operations end
   // @windy-module system.agent begin
+  "agent-tools": AgentToolsPage,
+  "agent-debug": AgentDebugPage,
   "agent-session": AgentSessionPage,
   "agent-workflow": AgentWorkflowPage,
   "ai-runtime": AiRuntimePage,

package/template/apps/web/src/router/platform-admin-route-bindings.ts

@@ -8,6 +8,8 @@ export type PlatformAdminPageKey =
   | "notification"
   | "operations"
   // @windy-module system.agent begin
+  | "agent-tools"
+  | "agent-debug"
   | "agent-session"
   | "agent-workflow"
   | "ai-runtime"
@@ -60,6 +62,8 @@ export const platformAdminRouteBindings: readonly PlatformAdminRouteBinding[] =
     { routeKey: "system.ops", page: "operations" },
     // @windy-module system.operations end
     // @windy-module system.agent begin
+    { routeKey: "system.agent-tools", page: "agent-tools" },
+    { routeKey: "system.agent-debug", page: "agent-debug" },
     { routeKey: "system.agent-session", page: "agent-session" },
     { routeKey: "system.agent-workflow", page: "agent-workflow" },
     { routeKey: "system.ai-runtime", page: "ai-runtime" },

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-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/docs/architecture/agent-harness.md

@@ -462,3 +462,7 @@ Compose、`service_adk_debug` 或活跃 `ADK_DEBUG_*` 配置。
 - [DeepSeek Harness Architecture](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)
 - [Vue Flow](https://vueflow.dev/)：Vue 3 Workflow 画布候选；采用前仍需完成依赖评估与固定版本。
 - [PageAgent](https://github.com/alibaba/page-agent)：页面理解与浏览器动作复用边界。
+
+## 管理端调试与业务回放（2026-10-07）
+
+动态工具目录与统一调试工作台沿用本 Harness 治理边界；业务会话可提供真实 Run/Workflow 引用，父子 Session 回放沿用 AH-1 checkpoint/lineage。历史只读取已有记录，缺少引用或超出有界窗口时显示 partial/missing。测试运行新建独立 Session，不在历史回放中启动模型或工具。实现与发布边界见[工作台技术实现](./agent-admin-workbench-implementation.md)，本节不将尚未发布的隔离执行与 Trace 扩展视为已交付。

package/template/docs/architecture/log-governance-implementation.md

@@ -1,6 +1,7 @@
 # 结构化运行日志技术实现
 
-状态：SDK、平台适配与利剑四条链的本地定向联调已实现；正式发布/升级及集中查询/告警平台未验收。
+状态：SDK 与 E1 已随 Windy `0.8.1` 正式发布，利剑完成官方更新和正式 SDK 四条链定向联调；
+完整隔离执行、真实 Provider、生产采集留存及集中查询/告警平台未验收。
 对应业务方案见
 [日志治理方案](./log-governance-plan.md)。
 
@@ -75,5 +76,21 @@
 容器依赖层安装和已有静态失败在利剑最终文档分别记录。
 候选 SDK 用真实本地归档消费，没有改 `.windy` 元数据或手改版本号冒充正式升级。
 
-本轮完成日志契约与四条真实适配链的本地定向联调；未完成真实 Provider/完整 Agent 部署、正式
-Windy 发布和 `windy update` 事务、生产采集留存、集中查询或告警验收。这些不能由定向检查替代。
+## 正式发布与利剑升级
+
+2026-10-01 核验 `create-windy@0.8.1`、`@southwind-ai/shared@0.3.1` 已在 npm 发布，
+`create-windy-v0.8.1` tag 指向 `066d8018c0ec0c82fbf01d26013b3b303aaa9c22`。
+[发布记录](https://github.com/RayJason/windy-platform/releases/tag/create-windy-v0.8.1) 已附
+candidate/published evidence、distribution manifest 与 checksum；两次发布核验均成功。
+利剑官方更新账本绑定同一 SHA 和 `0.8.1`，当前使用正常的
+`@southwind-ai/shared/structured-log`，已删除候选别名及归档。详细更新及验收记录在利剑
+`docs/operations/windy-logging-integration.md`。
+
+未完成 E2—E4 集成发布、真实 Provider/完整 Agent 部署、生产采集留存、集中查询或告警验收。
+日志 SDK 正式接入不能当作完整 Agent 能力已经交付的证据。
+
+利剑合并验收另发现旧 Bootstrap 借用 Uvicorn Handler 后再追加 SDK 会形成双出口。
+`configure_agent_logging()` 已回馈上游：保留唯一现存结构化 Handler，移除包级其它 Handler 引用，
+不关闭与 Uvicorn 共享的 Handler；重复初始化保留原实例和 Stream。5 项适配定向检查通过。
+该修复是 `0.8.1` 发布后的源码补丁，没有改写发布版本；利剑同时修复旧 Bootstrap 调用点，并用
+真实 Uvicorn 配置先于 ASGI 导入的回归检查证明单条 JSON 输出及独立访问日志仍有效。

package/template/docs/architecture/log-governance-plan.md

@@ -1,7 +1,7 @@
 # 日志治理方案
 
-状态：运行日志 SDK、平台适配及利剑四条链的本地定向联调已实现；正式发布、下游升级与部署留存
-另行验收。集中管理界面尚未实施。
+状态：运行日志 SDK 和平台适配随 Windy `0.8.1` 正式发布，利剑已通过官方更新接入并完成四条链
+定向联调。部署留存与真实 Provider 另行验收；集中管理界面尚未实施。
 
 ## 业务需求先行
 

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

@@ -52,6 +52,24 @@ Provider 调用前会执行：
 Tool 调用继续由 Windy Server 执行。Agent Server 只收到 opaque Execution Grant；每次 Tool
 都重新校验当前权限、Scope、审批和 receipt，不把 Run 创建时的权限快照当长期授权。
 
+### Tool 与结构化业务结果
+
+需要先查询业务数据再返回结构化结果的 Operation，同时保留真实 function calling 与最终
+JSON Schema 验证。为兼容同时发送 `tools` 和 `response_format` 时只生成正文的 Provider，
+存在 Tool 时请求只发送 `tools`，把经过授权和 DLP 的输出 Schema 及最终 JSON 指导合并到
+首条系统指令；没有 Tool 时继续发送严格 `response_format: json_schema`。这是默认序列化
+规则，无新增配置。正文中的工具名称或伪造调用不执行，只有协议中的 `tool_calls` 执行。
+
+合并不增加消息、移动 Context 来源序号或放宽 Guard。治理后的同一消息用于 Context 提交、
+输入预算和实际出网请求；Schema 指导也计入 Provider Context 与保守 Token 预算、出网审计
+字节数。`maxInputBytes` 继续约束原始输入和 Artifact，原有输出预算与有界 Tool 轮次继续生效。
+最终回复仍必须通过严格 Schema 验证，
+不接受 Markdown 围栏或额外字段；Provider 未生成合规结果时返回 `OUTPUT_VALIDATION_FAILED`。
+
+Context 的首条指令摘要与 `requestDigest` 覆盖完整、脱敏后的 Schema 指导。兼容请求没有
+`response_format`，因此 `outputSchemaDigest` 是实际空字段的摘要；它不能单独用来恢复
+输出 Schema。首条指令的来源与版本规则保持不变，业务来源仍按原始序号追踪。
+
 ## 配置
 
 选择 `system.agent` 的项目在本机 `.env` 配置：

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

@@ -57,6 +57,15 @@ function validateOperation(
   operation: ModuleAiOperationDefinition,
   catalogs: AiOperationCatalogs,
 ): void {
+  if (
+    operation.visibility !== undefined &&
+    operation.visibility !== "public" &&
+    operation.visibility !== "internal"
+  ) {
+    throw new Error(
+      `AI Operation ${operation.key} visibility 必须为 public 或 internal`,
+    );
+  }
   const strings = [
     operation.key,
     operation.featureKey,