create-windy 0.8.0 → 0.8.2

package/template/apps/server/src/jobs/worker.ts

@@ -5,6 +5,11 @@ import type {
   ManualJobRecovery,
 } from "./execution-repository.js";
 import { createDurableArtifactPublisher } from "./artifact-publisher.js";
+import type { StructuredLogger } from "@southwind-ai/shared";
+import {
+  logJobAttemptCompleted,
+  logJobAttemptStarted,
+} from "./runtime-logging.js";
 import {
   DurableHandlerError,
   type DurableHandlerContext,
@@ -25,6 +30,7 @@ export interface DurableWorkerOptions {
   leaseDurationMs?: number;
   retryDelayMs?: number;
   now?: () => Date;
+  logger?: StructuredLogger;
   contextualize?: (input: {
     claim: ClaimedDurableJob;
     moduleName?: string;
@@ -37,6 +43,7 @@ export class DurableJobWorker {
   private readonly retryDelayMs: number;
   private readonly now: () => Date;
   private readonly contextualize?: DurableWorkerOptions["contextualize"];
+  private readonly logger?: StructuredLogger;
   private readonly activeRuns = new Map<string, AbortController>();
 
   constructor(
@@ -48,6 +55,7 @@ export class DurableJobWorker {
     this.retryDelayMs = options.retryDelayMs || 1_000;
     this.now = options.now || (() => new Date());
     this.contextualize = options.contextualize;
+    this.logger = options.logger;
   }
 
   async runNext(queue: string, workerId: string): Promise<DurableRunResult> {
@@ -59,20 +67,54 @@ export class DurableJobWorker {
       leaseDurationMs: this.leaseDurationMs,
     });
     if (!claim) return { status: "idle" };
-    const handler = this.handlers.get(claim.job.handlerKey);
-    if (!handler) {
-      await this.repository.fail(
+    const startedAt = performance.now();
+    logJobAttemptStarted(this.logger, claim);
+    try {
+      const handler = this.handlers.get(claim.job.handlerKey);
+      if (!handler) {
+        await this.repository.fail(
+          claim,
+          {
+            code: "HANDLER_NOT_REGISTERED",
+            message: `任务 handler 未注册：${claim.job.handlerKey}`,
+            retryable: false,
+          },
+          this.now(),
+        );
+        logJobAttemptCompleted(
+          this.logger,
+          claim,
+          "failed",
+          performance.now() - startedAt,
+          "HANDLER_NOT_REGISTERED",
+        );
+        return { status: "failed", jobId: claim.jobId };
+      }
+      const result = await this.execute(claim, handler);
+      logJobAttemptCompleted(
+        this.logger,
         claim,
-        {
-          code: "HANDLER_NOT_REGISTERED",
-          message: `任务 handler 未注册：${claim.job.handlerKey}`,
-          retryable: false,
-        },
-        this.now(),
+        result.status,
+        performance.now() - startedAt,
+        result.status === "failed"
+          ? "JOB_ATTEMPT_FAILED"
+          : result.status === "cancelled"
+            ? "JOB_CANCELLED"
+            : result.status === "lease-lost"
+              ? "JOB_LEASE_LOST"
+              : undefined,
+      );
+      return result;
+    } catch (error) {
+      logJobAttemptCompleted(
+        this.logger,
+        claim,
+        "failed",
+        performance.now() - startedAt,
+        "JOB_WORKER_ERROR",
       );
-      return { status: "failed", jobId: claim.jobId };
+      throw error;
     }
-    return this.execute(claim, handler);
   }
 
   async cancel(jobId: string) {
@@ -104,7 +146,7 @@ export class DurableJobWorker {
   private async execute(
     claim: ClaimedDurableJob,
     handler: RegisteredDurableHandler,
-  ): Promise<DurableRunResult> {
+  ): Promise<Exclude<DurableRunResult, { status: "idle" }>> {
     const abort = new AbortController();
     this.activeRuns.set(claim.jobId, abort);
     const identity = identityOf(claim);

package/template/apps/server/src/observability/bootstrap.ts

@@ -49,8 +49,5 @@ export function logPlatformStartup(
     { event: "feature.manifest.synchronized", ...input.featureSync },
     "Feature Manifest 已同步",
   );
-  logger.info(
-    { event: "service.started", component: "windy-server", port: input.port },
-    "服务已启动",
-  );
+  logger.info({ event: "service.started", port: input.port }, "服务已启动");
 }

package/template/apps/server/src/observability/http-observability.ts

@@ -1,9 +1,8 @@
+import type { StructuredLogger } from "@southwind-ai/shared";
 import type { RequestGuardContext } from "../guards.js";
 import type { RequestObservation, RuntimeMetrics } from "./metrics.js";
 
-export interface StructuredRequestLogger {
-  info(fields: Record<string, unknown>, message: string): void;
-}
+export type StructuredRequestLogger = Pick<StructuredLogger, "info">;
 
 export class HttpObservability {
   constructor(

package/template/apps/server/src/observability/structured-logger.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import { createServerLogger } from "./structured-logger.js";
+
+describe("Server Pino operational logger", () => {
+  test("实际输出单行 JSON 且没有 Pino 隐含字段或自由文本", () => {
+    const lines: string[] = [];
+    const logger = createServerLogger({ write: (line) => lines.push(line) });
+    logger.error(
+      {
+        event: "agent.workflow.continuation.failed",
+        outcome: "failure",
+        errorCode: "AGENT_WORKFLOW_CONTINUATION_FAILED",
+        requestId: "request-1",
+        error: new Error("secret-stack"),
+      } as unknown as Parameters<typeof logger.error>[0],
+      "secret-message",
+    );
+    expect(lines).toHaveLength(1);
+    const record = JSON.parse(lines[0] ?? "") as Record<string, unknown>;
+    expect(record).toMatchObject({
+      level: "error",
+      component: "windy-server",
+      event: "agent.workflow.continuation.failed",
+      requestId: "request-1",
+    });
+    expect(record).not.toHaveProperty("time");
+    expect(record).not.toHaveProperty("msg");
+    expect(lines[0]).not.toContain("secret-stack");
+    expect(lines[0]).not.toContain("secret-message");
+  });
+});

package/template/apps/server/src/observability/structured-logger.ts

@@ -0,0 +1,27 @@
+import { createStructuredLogger } from "@southwind-ai/shared";
+import pino, { type DestinationStream } from "pino";
+
+/** Pino 只负责写出；字段选择和大小限制由共享契约完成。 */
+export function createServerLogger(destination?: DestinationStream) {
+  const options = {
+    base: null,
+    timestamp: false,
+    formatters: { level: (level: string) => ({ level }) },
+  };
+  const sink = destination ? pino(options, destination) : pino(options);
+  const write = (
+    level: "info" | "warn" | "error",
+    record: Record<string, unknown>,
+  ) => {
+    const { level: _level, ...fields } = record;
+    sink[level](fields);
+  };
+  return createStructuredLogger(
+    {
+      info: (record) => write("info", record),
+      warn: (record) => write("warn", record),
+      error: (record) => write("error", record),
+    },
+    "windy-server",
+  );
+}

package/template/apps/server/src/platform-bootstrap.ts

@@ -1,14 +1,20 @@
 import { loadPlatformConfig } from "@southwind-ai/config";
-import pino from "pino";
+import { createServerLogger } from "./observability/structured-logger.js";
 import { createServerPersistence } from "./persistence.js";
 
 export function createPlatformBootstrap() {
-  const logger = pino({ name: "windy-server" });
+  const logger = createServerLogger();
   const platformConfig = loadPlatformConfig();
   const persistence = createServerPersistence(
     process.env,
     (status) => {
-      logger.error({ audit: status }, "审计持久化进入降级状态");
+      logger.error({
+        event: "audit.persistence.degraded",
+        outcome: "failure",
+        errorCode: "AUDIT_PERSISTENCE_DEGRADED",
+        queued: status.queued,
+        dropped: status.dropped,
+      });
     },
     platformConfig,
   );

package/template/apps/server/src/startup-finalization.ts

@@ -1,3 +1,4 @@
+import type { StructuredLogger } from "@southwind-ai/shared";
 import type { ModuleManifest } from "@southwind-ai/modules";
 import type { InitializedModuleHosts } from "./module-host.js";
 import { validateInstalledRuntime } from "./module-runtime-validation.js";
@@ -16,9 +17,8 @@ export function finalizePlatformStartup(input: {
   providers?: readonly string[];
   schedulerWorker?: { start(): void; stop(): void };
   disposeAgentRuntime?: () => Promise<unknown> | unknown;
-  logger: Parameters<typeof logServerStartup>[0] & {
-    error(fields: Record<string, unknown>, message: string): void;
-  };
+  logger: Parameters<typeof logServerStartup>[0] &
+    Pick<StructuredLogger, "error">;
   featureSync: Parameters<typeof logServerStartup>[1];
   persistenceEnabled: boolean;
 }): void {

package/template/apps/server/src/system/built-in-roles.test.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createBuiltInRoleSeeds } from "./built-in-roles.js";
+
+test("built-in roles only grant permissions in the installed capability catalog", () => {
+  const snapshot = createFoundationSnapshot();
+  const coreKeys = new Set([
+    "system.menu.read",
+    "system.profile.read",
+    "system.user.read",
+  ]);
+  snapshot.permissions = snapshot.permissions.filter(({ key }) =>
+    coreKeys.has(key),
+  );
+  const roles = createBuiltInRoleSeeds(snapshot);
+  for (const role of roles) {
+    expect(role.permissionKeys.every((key) => coreKeys.has(key))).toBe(true);
+  }
+  expect(roles.find(({ code }) => code === "user")?.permissionKeys).toEqual([
+    "system.menu.read",
+    "system.profile.read",
+  ]);
+});

package/template/apps/server/src/system/built-in-roles.ts

@@ -25,17 +25,23 @@ export function createBuiltInRoleSeeds(
   snapshot: FoundationSnapshot,
 ): RoleSeed[] {
   const allPermissions = snapshot.permissions.map(({ key }) => key).sort();
+  const registeredPermissions = new Set<string>(allPermissions);
+  const supportedOrdinaryPermissions = ordinaryPermissions.filter((key) =>
+    registeredPermissions.has(key),
+  );
   const developerPermissions = snapshot.permissions
     .filter(({ accessRisk }) => !accessRisk || accessRisk === "standard")
     .map(({ key }) => key)
     .sort();
   const allMenus = collectNavigableMenuKeys(snapshot.menus);
   const departmentManagerPermissions = [
-    ...ordinaryPermissions,
+    ...supportedOrdinaryPermissions,
     "system.department.read",
     "system.user.read",
     "system.user-directory.read",
-  ].sort();
+  ]
+    .filter((key) => registeredPermissions.has(key))
+    .sort();
   return [
     role(
       "role_super_admin",
@@ -58,8 +64,8 @@ export function createBuiltInRoleSeeds(
       "user",
       "普通用户",
       "self",
-      ordinaryPermissions,
-      menuKeysForPermissions(snapshot, ordinaryPermissions),
+      supportedOrdinaryPermissions,
+      menuKeysForPermissions(snapshot, supportedOrdinaryPermissions),
     ),
     role(
       "role_developer",

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

@@ -33,6 +33,17 @@ export function useResourceEditor(options: {
     try {
       const normalized = { ...payload };
       delete normalized._transitionTargetDepartmentId;
+      if (
+        options.key === "users" &&
+        !item.value &&
+        (typeof payload.temporaryPassword !== "string" ||
+          !payload.temporaryPassword)
+      ) {
+        toast.error("请设置一次性初始密码", {
+          description: "密码至少 12 个字符，创建后首次登录即可修改。",
+        });
+        return false;
+      }
       if (
         options.key === "departments" &&
         item.value &&
@@ -54,12 +65,12 @@ export function useResourceEditor(options: {
           ? await saveUserAccount(
               normalized,
               savedAccountId.value,
-              options.save,
-              toast,
-              (record) => {
-                savedAccountId.value = record.id;
+              async (accountPayload, id) => {
+                const record = await options.save(accountPayload, id);
+                if (record) savedAccountId.value = record.id;
+                return record;
               },
-              !item.value,
+              toast,
             )
           : await options.save(normalized, item.value?.id);
       if (saved) options.mutated();

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

@@ -40,6 +40,10 @@ describe("账户编辑保存闭环", () => {
     expect(editor.item.value).toBeUndefined();
     expect(save.mock.calls[0]?.[1]).toBeUndefined();
     expect(mutated).not.toHaveBeenCalled();
+    expect(await editor.submit({ ...payload, temporaryPassword: "" })).toBe(
+      false,
+    );
+    expect(save).toHaveBeenCalledTimes(1);
     expect(await editor.submit(payload)).toBe(true);
     expect(save.mock.calls[1]?.[1]).toBe("user_created");
     expect(api.reset).toHaveBeenLastCalledWith(

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

@@ -0,0 +1,96 @@
+# 结构化运行日志技术实现
+
+状态：SDK 与 E1 已随 Windy `0.8.1` 正式发布，利剑完成官方更新和正式 SDK 四条链定向联调；
+完整隔离执行、真实 Provider、生产采集留存及集中查询/告警平台未验收。
+对应业务方案见
+[日志治理方案](./log-governance-plan.md)。
+
+## 当前调用链
+
+- `packages/shared/src/structured-log.ts` 提供跨服务字段契约与 TypeScript SDK。调用者提交稳定
+  `event`、关联 ID、结果、错误码和少量明确允许的数值字段；序列化器生成时间、等级、组件和
+  `retentionClass=operational`，只输出白名单字段，并限制单行 2048 UTF-8 字节。任意 message、
+  原始 Error、请求内容、Token 与未知字段不会进入记录。
+  公共入口 `@southwind-ai/shared/structured-log` 可独立消费日志 SDK；利剑用真实打包候选的
+  同一入口验证，保留原 workspace shared，避免同名同版本 package identity 的类型去重冲突。
+  字段同时支持 `diagnosticId`、登记的 `route` 模板、`handlerKey/queue/attemptNumber` 及
+  有界 `completedUnits/totalUnits/count`。路由不能传实际 URL、query、fragment 或对象路径；
+  SDK 做词法校验，调用方负责从框架登记模板取得它。
+- `apps/server/src/observability/structured-logger.ts` 将该契约接入 Pino。
+  `platform-bootstrap.ts` 创建同一 logger，HTTP 请求完成、启动、审计降级及 Workflow continuation
+  的现有日志路径继续使用它。Workflow continuation 只把原始异常字段改为稳定错误码，不改派发和
+  错误处理行为。
+- `createLegacyServiceRuntime` 将统一 Logger 注入 `DurableJobWorker`；每次实际 claim 记录
+  `job.attempt.started` 和唯一的 `job.attempt.completed`，包括未注册 Handler、失败、取消和租约
+  丢失。只读 canonical claim 的 Job/阶段/重试/Handler/Queue 坐标，不扫描 payload 或记录租约
+  Token。idle 不产生日志。
+- `apps/agent-server/src/southwind_agent_server/structured_logging.py` 为 Python 包级日志安装对等
+  适配器。`asgi.py` 保留原 FastAPI app 对象，在生产 ASGI 入口安装 handler；Dockerfile 与开发
+  启动命令均指向该入口。恢复轮询和报表写入失败映射为稳定事件/错误码，不输出异常堆栈或任意
+  `extra`。Uvicorn 自身 access/error 日志仍由 Uvicorn 配置管理。
+  `AgentRunTrace.start/finish` 同时调用 `AgentOperationalAttempt`，记录固定的
+  `agent.run.attempt.started/completed`、Run/Trace、耗时及安全结果；幂等重放不重新启动 attempt。
+  进程停止等非终态结束标为 interrupted，不能伪装成 canonical Run failed。详细输入输出仍由
+  Run/Artifact 受管查询负责。
+
+业务审计继续走 `system.audit` 的 Manifest 与 Audit Port；Agent Run/Provider/Workflow 的持久
+事实仍由各自 canonical store 维护。运行日志只用于排障，不能替代这两类记录。
+
+## 利剑候选消费与四条链
+
+利剑先 fetch 并 fast-forward `origin/main` 至 `3a51d6edf`，再创建
+`rayjason/logging-integration`。变更仅在日志、Host 装配、候选依赖和验证文档；矛盾分析和聊天
+记录分析的业务文件没有修改。利剑方案在 `docs/architecture/logging-integration-plan.md`，
+最终实现和证据在 `docs/operations/windy-logging-integration.md`。
+
+| 链路         | 当前本地联调证据                                                     | 业务结果                                                           |
+| ------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| HTTP 写请求  | 真实 `createPlatformHttpApp` / Elysia 生命周期与候选 SDK/Pino        | 一次完成记录、请求关联、正文和身份明细不入日志                     |
+| 慢请求与失败 | 慢 GET、错误诊断 Hook 和完成去重                                     | 保留阈值采样、诊断编号与登记路由模板                               |
+| Durable Job  | 真实 Worker + 隔离内存 Repository                                    | 开始、进度、终态按 Job/阶段/重试串联；Sink 故障不改状态机          |
+| Agent        | 利剑 Remote Runtime 到本地 HTTP 协议 fixture；独立安装的 Python 候选 | Host 请求到 Trace/Run 的关联、当前进程采样去重、canonical 结果保持 |
+
+利剑 `ObservedAgentRuntime` 的终态观测最多保留 1000 个 Run，仅用于进程内采样，重启或淘汰
+后可能再次观测同一 Run；它不承诺全局 exactly-once。Run store 和业务审计仍是权威事实。
+本地 fixture 不调用真实模型 Provider，也没有写入生产案件数据。
+
+## 验证与限制
+
+- Bun 定向测试：共享契约、Server Pino 输出与 HTTP 观测共 8 项通过，包含 Sink 故障不影响业务。
+- Agent Server Python 定向测试：4 项通过，包含日志输出失败不影响 Run；ASGI 导入确认复用原
+  app 对象。
+- Server/Shared 类型检查及相关格式、Lint 检查通过；提交钩子的工作区类型检查作为静态证据。
+- SDK 新字段及 Job 旁路定向检查各 4 项通过；Agent 日志、真实 ASGI Run、坏 Sink 与幂等重放
+  共 11 项 Python 定向检查通过，Ruff/Mypy 通过。
+  平台最终合并的 SDK/Job/Pino/HTTP 定向检查共 12 项通过。
+- Python 候选源码 `8c045684` 用 `uv build apps/agent-server --wheel` 打包，安装到独立 venv，
+  依赖由 `uv export --locked --no-dev --no-emit-project` 固定。`scripts/agent-log-wheel-consumer.py`
+  用独立解释器的 `-I` 模式在仓库外执行，验证导入来自 site-packages，正常和坏 stdout 两种
+  场景均完成真实 ASGI Run、canonical 结果、幂等重放、关联/脱敏与大小预算。
+  该 wheel SHA256 为 `8fd5bbb3fb5f6d92cc6c4dd9d7237df8c3dd1d9afe425448c0b61f7997ad2a95`。
+
+利剑消费 SDK 源码 `11df0eb4`，归档 SHA256 为
+`aa48ef04927edd9245ce7dde2b6a6415d35ac4c911c3535fd10192f859010e3b`。实际 Elysia/Worker/Remote
+协议链及既有授权定向检查 26 项通过；交付构建输入/增量角色映射检查 22 项通过。候选包的
+本地依赖必须在 Docker 的 frozen install 前复制，Server/Web/Seeder 已补齐该输入及 SDK 导入。
+容器依赖层安装和已有静态失败在利剑最终文档分别记录。
+候选 SDK 用真实本地归档消费，没有改 `.windy` 元数据或手改版本号冒充正式升级。
+
+## 正式发布与利剑升级
+
+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

@@ -0,0 +1,39 @@
+# 日志治理方案
+
+状态：运行日志 SDK 和平台适配随 Windy `0.8.1` 正式发布，利剑已通过官方更新接入并完成四条链
+定向联调。部署留存与真实 Provider 另行验收；集中管理界面尚未实施。
+
+## 业务需求先行
+
+| 场景     | 使用者与问题                                  | 权威记录                 | 成功标准                               |
+| -------- | --------------------------------------------- | ------------------------ | -------------------------------------- |
+| 故障定位 | 运维定位写请求、慢请求、Job 或 Agent Run 失败 | 有界结构化运行日志与指标 | 用关联 ID 找到失败阶段，不暴露敏感输入 |
+| 责任追溯 | 审计人员确认谁在什么权限下执行了业务动作      | `system.audit` 审计事实  | 权限控制、完整性和导出可验证           |
+| 合规取证 | 管理人员按部署约定查询、留存和导出            | 审计事实及受管保留策略   | 保留期、访问授权和交付责任明确         |
+
+## 模块边界
+
+`system.audit` 已有 Manifest、Module Audit Port、可靠写入、权限控制及管理端查询/导出。
+业务/安全审计继续由它维护；普通 stdout、HTTP 访问日志和 Agent Trace 不写成它的审计事实。
+Agent Run/Provider/Workflow 仍保留各自 canonical 事实，借关联 ID 串联。
+
+Windy 平台层提供结构化运行日志契约和 TypeScript SDK；Python Agent Server 使用对等适配器。
+它们统一 `timestamp`、`level`、`component`、`event`、`requestId`、`runId`、`jobId`、
+`traceId`、`outcome` 和稳定错误码，限定字段白名单、脱敏、采样、大小预算与 retention 分类。
+日志内容不成为业务授权来源，也不替代 Trace Event。对客户数据、密钥、模型输入输出、Tool 参数、
+stdout/stderr 采用默认不记录的规则；确需详查时走当前权限复核和有 TTL 的受管 payload/Artifact。
+
+集中采集、索引、备份和保留由部署层管理。只有在运维确有统一查询、告警配置和多租户隔离的
+需求与责任人时，新增独立可选 `system.observability` module，提供受权的控制面和查询代理；
+不把日志引擎塞进 `system.audit`，也不复制一份日志事实数据库。
+
+## 迁移与验证
+
+1. 清点 Windy 的 Server Pino/HTTP、Job、Agent 日志及利剑已有写请求、慢请求和 Docker 轮转字段。
+2. 固定跨语言 schema、上下文传播、等级/采样、脱敏和稳定错误码；SDK 只负责产出，不控制业务审计。
+3. 对接 Windy 后，用利剑的四条真实链路做兼容映射：写请求、慢请求、Durable Job、Agent Run。
+   检查敏感字段泄漏、重复事件、丢关联 ID 和日志系统不可用时业务是否按既定审计策略处理。
+4. 和 Agent 平台候选共同发布；利剑在官方更新事务中升级，分别验收排障、审计导出和部署保留。
+
+集中管理平台是否实施以这些业务验收后的缺口决定。当前任务状态见
+[上游任务清单](https://github.com/RayJason/windy-platform/blob/main/docs/product/tasks.md)。

package/template/docs/operations/observability.md

@@ -29,14 +29,41 @@ Web、Server、License 和 Signing 接受 `x-request-id`。只保留 1 至 128
 
 ## 结构化日志
 
-应用启动、运行模式警告和 HTTP 完成事件使用单行 JSON。HTTP 完成事件的稳定字段为：
-
-- `timestamp`、`level`、`event`、`component`；
-- `requestId`、`method`、`statusCode`、`durationMs`；
+应用启动、运行模式警告和 HTTP 完成事件使用单行 JSON。Server 使用
+`@southwind-ai/shared` 的结构化日志契约清洗字段，再交给 Pino 输出；Agent Server
+生产 ASGI 入口使用同一契约的 Python 适配器处理运行时异常。单行上限为 2048 UTF-8
+字节，自由文本 message 和原始异常不会输出。`retentionClass=operational` 表示排障日志，
+不赋予它审计事实或六个月留存语义。
+
+通用稳定字段是 `timestamp`、`level`、`component`、`event`、`retentionClass`；
+可选 `requestId`、`runId`、`jobId`、`traceId`、`diagnosticId`、`outcome`、`errorCode` 和
+`stageKey`。关联 ID 只接受 1 至 128 位安全字符，不合法就省略，不猜测或生成假的关联。
+`event`、`errorCode` 和阶段只接受有界稳定 Key。未列字段包括 body、headers、Token、
+Prompt、Tool 参数和原始 Error 均被丢弃；超出大小预算时先丢弃次要关联字段。
+运行日志输出失败时由 SDK/适配器吞掉写出异常，不改变原请求、Run 或审计结果；
+日志丢失需由部署层的采集健康和告警发现。
+HTTP 完成事件另外允许：
+
+- `method`、`statusCode`、`durationMs`；
+- `route` 只允许框架登记的模板，由调用方提供；SDK 拒绝 query、fragment、编码或纯数字路径段，
+  不以词法校验代替模板来源保证；
 - Server 可额外记录粗粒度 `actorType`，不记录用户或资源 ID。
 
 请求完成日志禁止记录完整 URL、query、请求或响应 body、Cookie、Authorization、Secret、连接串和原始异常。需要增加字段时，必须先判断其基数和敏感性，并补充防泄漏测试。生产日志采集器应按 JSON 字段解析，按 `requestId` 关联，不依赖自由文本。
 
+Agent Server 的生产入口为 `southwind_agent_server.asgi:app`，它不改动 FastAPI
+应用对象，而是在现有包级 Python logging 上安装结构化输出。当前恢复轮询和报表写入失败
+映射到稳定事件/错误码；报表失败可携带合法的 `runId` 与 `stageKey`。实际执行的
+`AgentRunTrace` 同时发出 `agent.run.attempt.started/completed`、Run/Trace、耗时与安全结果，
+幂等重放不重发，非终态执行中断标记 interrupted。异常堆栈、
+Python `extra` 中的任意字段和报表正文都不进入 stdout。直接使用旧的
+`southwind_agent_server.app:app` 入口不会安装该适配器。
+
+后台 Durable Worker 每次实际 claim 发出 `job.attempt.started/completed`，字段只取 canonical
+`jobId/stageKey/attemptNumber/handlerKey/queue`；失败只记录稳定码。`completedUnits/totalUnits/count`
+支持进度或清理计数，均限制为 0 至 10 亿的整数。日志不记录 payload、租约 Token 或进度正文，
+也不从业务 payload 猜测关联 ID；Worker idle 不产生日志。
+
 请求观测在全局 `onRequest` 建立，在响应完成时原子取出并结束。未匹配路由、Guard
 拒绝和 handler 异常与正常请求遵循同一生命周期；即使框架同时触发 error 与
 after-response 路径，同一个请求也只能扣减一次活跃计数并写一条完成日志。业务路由
@@ -58,5 +85,10 @@ after-response 路径，同一个请求也只能扣减一次活跃计数并写
 Server/License 请求完成日志字段、Web 到 Server 的标识透传，以及 Server 未匹配路由、
 异常路由只完成一次观测且不会终止进程，均有 Bun 单元或边界测试；工作区 typecheck 和
 Oxlint 已通过。Dockerfile 已声明 readiness `HEALTHCHECK`。
+新增结构化日志切片的共享契约、Pino 输出和 HTTP 观测定向测试共 8 项通过；Agent Server
+Python 适配定向测试 4 项通过，ASGI 导入复用原 app 对象。完整记录见
+[结构化运行日志技术实现](../architecture/log-governance-implementation.md)。
+利剑四条真实适配链已完成候选包本地定向联调；平台 Job 定向检查 4 项、Agent 日志/ASGI
+检查 11 项及独立 wheel 消费通过。实际 Provider、正式更新事务和部署采集留存仍须独立验收。
 
 尚未由本页证明：生产 Compose、新环境部署、备份恢复、升级回滚、原生 Linux amd64 runner、告警规则、长稳运行、多实例和大容量。这些项必须由后续生产恢复演练和目标环境记录单独闭环；Docker Desktop 或 QEMU 上的 amd64 运行不能写成原生 Linux amd64 已认证。

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/package.json

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

package/template/packages/modules/src/ai-isolated-execution-policy.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import type { AiIsolatedExecutionPolicyV1 } from "./manifest.js";
+import { validateModuleComposition } from "./composition.js";
+import { fixture, operation } from "./ai-operation-composition.test-support.js";
+
+const policy: AiIsolatedExecutionPolicyV1 = {
+  version: 1,
+  mode: "isolated",
+  languages: ["python", "node"],
+  inputArtifactTypes: ["text/plain", "application/json"],
+  network: "forbidden",
+  limits: {
+    maxWorkspaceBytes: 8_388_608,
+    maxFileBytes: 2_097_152,
+    maxOutputBytes: 1_048_576,
+    maxDurationSeconds: 30,
+    maxCpuMillis: 30_000,
+    maxMemoryBytes: 268_435_456,
+    maxPids: 8,
+    maxConcurrentProcesses: 1,
+    maxToolCalls: 8,
+    maxToolRounds: 4,
+  },
+};
+
+describe("Agent 隔离执行 Manifest", () => {
+  test("缺省关闭；显式策略可通过组合校验", () => {
+    const module = fixture("business");
+    module.aiOperations = [operation("business.answer")];
+    expect(() => validateModuleComposition([module])).not.toThrow();
+    module.aiOperations = [
+      {
+        ...module.aiOperations[0]!,
+        toolNetworkPolicy: { mode: "forbidden" },
+        isolatedExecution: policy,
+      },
+    ];
+    expect(() => validateModuleComposition([module])).not.toThrow();
+  });
+
+  test("未知语言、网络和越界预算在装配时拒绝", () => {
+    const module = fixture("business");
+    const base = operation("business.answer");
+    const check = (candidate: AiIsolatedExecutionPolicyV1) => {
+      module.aiOperations = [
+        {
+          ...base,
+          toolNetworkPolicy: { mode: "forbidden" },
+          isolatedExecution: candidate,
+        },
+      ];
+      expect(() => validateModuleComposition([module])).toThrow();
+    };
+    check({
+      ...policy,
+      languages: [
+        "ruby",
+      ] as unknown as AiIsolatedExecutionPolicyV1["languages"],
+    });
+    check({
+      ...policy,
+      network: "allowed" as AiIsolatedExecutionPolicyV1["network"],
+    });
+    check({
+      ...policy,
+      limits: { ...policy.limits, maxMemoryBytes: 2_147_483_648 },
+    });
+    check({ ...policy, limits: { ...policy.limits, maxToolRounds: 9 } });
+  });
+});