create-windy 0.4.1 → 0.5.1

package/template/apps/web/src/services/ai-runtime-api.ts

@@ -0,0 +1,164 @@
+import { apiRequest } from "./http";
+import type {
+  AiRuntimeActorSummary,
+  AiRuntimeAttemptDetail,
+  AiRuntimeReportSummary,
+  AiRuntimeRunDetail as RuntimeRunDetail,
+  AiRuntimeRunListItem,
+  PageResult,
+} from "@southwind-ai/shared";
+
+export type AiRuntimeRange = "day" | "month" | "retained";
+
+export interface AiRuntimeReportQuery {
+  readonly range: AiRuntimeRange;
+  readonly actorHandle?: string;
+}
+
+export type AiRuntimeSummary = AiRuntimeReportSummary;
+export type AiRuntimeModelUsage = AiRuntimeReportSummary["byModel"][number];
+export type AiRuntimeActivity = AiRuntimeReportSummary["activity"][number];
+
+export interface AiRuntimeRunItem {
+  readonly runId: string;
+  readonly operationKey: string;
+  readonly actor: AiRuntimeActor | null;
+  readonly status: string;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly durationMs?: number;
+  readonly attempts: number;
+  readonly model?: string;
+  readonly totalTokens: number | null;
+  readonly cacheStatus: "hit" | "miss" | "unknown";
+  readonly traceId?: string;
+  readonly safeErrorCode?: string;
+}
+
+export interface AiRuntimeAttempt {
+  readonly sequence: number;
+  readonly deploymentKey: string;
+  readonly requestedModel: string;
+  readonly reportedModel?: string;
+  readonly outcome: string;
+  readonly inputTokens: number | null;
+  readonly outputTokens: number | null;
+  readonly cachedInputTokens: number | null;
+  readonly reasoningTokens: number | null;
+  readonly totalTokens: number | null;
+  readonly cacheStatus: "hit" | "miss" | "unknown";
+  readonly firstTokenLatencyMs?: number;
+  readonly durationMs?: number;
+  readonly safeErrorCode?: string;
+  readonly startedAt: string;
+  readonly finishedAt?: string;
+}
+
+export interface AiRuntimeRunDetail extends AiRuntimeRunItem {
+  readonly releaseId?: string;
+  readonly attemptItems: readonly AiRuntimeAttempt[];
+}
+
+export type AiRuntimeActor = AiRuntimeActorSummary;
+export type AiRuntimePage<T> = PageResult<T>;
+
+export function getAiRuntimeSummary(query: AiRuntimeReportQuery) {
+  return apiRequest<AiRuntimeSummary>(
+    `/system/ai-runtime/summary?${reportParams(query)}`,
+  );
+}
+
+export function listAiRuntimeRuns(
+  query: AiRuntimeReportQuery & { page: number; pageSize: number },
+): Promise<AiRuntimePage<AiRuntimeRunItem>> {
+  const params = reportParams(query);
+  params.set("page", String(query.page));
+  params.set("pageSize", String(query.pageSize));
+  return apiRequest<PageResult<AiRuntimeRunListItem>>(
+    `/system/ai-runtime/runs?${params}`,
+  ).then((result) => ({
+    ...result,
+    items: result.items.map(runItem),
+  }));
+}
+
+export function getAiRuntimeRun(
+  runId: string,
+  signal?: AbortSignal,
+): Promise<AiRuntimeRunDetail> {
+  return apiRequest<RuntimeRunDetail>(
+    `/system/ai-runtime/runs/${encodeURIComponent(runId)}`,
+    signal ? { signal } : {},
+  ).then(runDetail);
+}
+
+export function listAiRuntimeActors(query = "", page = 1, pageSize = 50) {
+  const params = new URLSearchParams({
+    page: String(page),
+    pageSize: String(pageSize),
+  });
+  if (query.trim()) params.set("q", query.trim());
+  return apiRequest<PageResult<AiRuntimeActor>>(
+    `/system/ai-runtime/actors?${params}`,
+  );
+}
+
+function reportParams(query: AiRuntimeReportQuery) {
+  const params = new URLSearchParams({ range: query.range });
+  if (query.actorHandle) params.set("actorHandle", query.actorHandle);
+  return params;
+}
+
+function runItem(value: AiRuntimeRunListItem): AiRuntimeRunItem {
+  return {
+    runId: value.runId,
+    operationKey: value.operationKey,
+    actor: value.actor,
+    status: value.status,
+    ...(value.startedAt ? { startedAt: value.startedAt } : {}),
+    ...(value.finishedAt ? { finishedAt: value.finishedAt } : {}),
+    ...(value.durationMs === null ? {} : { durationMs: value.durationMs }),
+    attempts: value.attemptCount,
+    model: modelLabel(value.models),
+    totalTokens: value.usage.totalTokens,
+    cacheStatus: value.cacheStatus,
+  };
+}
+
+function runDetail(value: RuntimeRunDetail): AiRuntimeRunDetail {
+  return {
+    ...runItem(value),
+    releaseId: value.releaseId,
+    traceId: value.traceId,
+    ...(value.safeErrorCode ? { safeErrorCode: value.safeErrorCode } : {}),
+    attemptItems: value.attempts.map(attemptItem),
+  };
+}
+
+function attemptItem(value: AiRuntimeAttemptDetail): AiRuntimeAttempt {
+  return {
+    sequence: value.sequence,
+    deploymentKey: value.deploymentKey,
+    requestedModel: value.model,
+    outcome: value.outcome,
+    inputTokens: value.inputTokens,
+    outputTokens: value.outputTokens,
+    cachedInputTokens: value.cachedInputTokens,
+    reasoningTokens: value.reasoningTokens,
+    totalTokens: value.totalTokens,
+    cacheStatus: value.cacheStatus,
+    ...(value.firstTokenLatencyMs === null
+      ? {}
+      : { firstTokenLatencyMs: value.firstTokenLatencyMs }),
+    ...(value.durationMs === null ? {} : { durationMs: value.durationMs }),
+    ...(value.safeErrorCode ? { safeErrorCode: value.safeErrorCode } : {}),
+    startedAt: value.startedAt,
+    ...(value.finishedAt ? { finishedAt: value.finishedAt } : {}),
+  };
+}
+
+function modelLabel(models: readonly string[]) {
+  if (models.length === 0) return undefined;
+  if (models.length === 1) return models[0];
+  return `${models[0]} 等 ${models.length} 个`;
+}

package/template/apps/web/src/services/ai-runtime-api.webtest.ts

@@ -0,0 +1,111 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({ apiRequest: vi.fn() }));
+vi.mock("./http", () => mocks);
+
+import {
+  getAiRuntimeRun,
+  getAiRuntimeSummary,
+  listAiRuntimeActors,
+  listAiRuntimeRuns,
+} from "./ai-runtime-api";
+
+describe("AI Runtime 报表 API", () => {
+  beforeEach(() => mocks.apiRequest.mockReset());
+
+  test("汇总和列表都传递有界范围与 Actor 筛选", async () => {
+    mocks.apiRequest.mockResolvedValueOnce({}).mockResolvedValueOnce({
+      items: [
+        {
+          runId: "run_1",
+          operationKey: "customer.answer",
+          actor: null,
+          status: "completed",
+          startedAt: "2026-07-31T00:00:00.000Z",
+          finishedAt: null,
+          durationMs: null,
+          attemptCount: 2,
+          models: ["gpt-a", "gpt-b"],
+          cacheStatus: "unknown",
+          usage: {
+            inputTokens: null,
+            outputTokens: null,
+            cachedInputTokens: null,
+            reasoningTokens: null,
+            totalTokens: null,
+          },
+        },
+      ],
+      total: 1,
+      page: 2,
+      pageSize: 20,
+    });
+
+    await getAiRuntimeSummary({
+      range: "month",
+      actorHandle: "actor_opaque",
+    });
+    const page = await listAiRuntimeRuns({
+      range: "month",
+      actorHandle: "actor_opaque",
+      page: 2,
+      pageSize: 20,
+    });
+
+    expect(mocks.apiRequest).toHaveBeenNthCalledWith(
+      1,
+      "/system/ai-runtime/summary?range=month&actorHandle=actor_opaque",
+    );
+    expect(mocks.apiRequest).toHaveBeenNthCalledWith(
+      2,
+      "/system/ai-runtime/runs?range=month&actorHandle=actor_opaque&page=2&pageSize=20",
+    );
+    expect(page.items[0]).toMatchObject({
+      attempts: 2,
+      model: "gpt-a 等 2 个",
+      totalTokens: null,
+      cacheStatus: "unknown",
+    });
+  });
+
+  test("Run 与 Actor 标识经过 URL 编码", async () => {
+    mocks.apiRequest
+      .mockResolvedValueOnce({
+        runId: "run/with space",
+        operationKey: "customer.answer",
+        actor: null,
+        status: "completed",
+        startedAt: null,
+        finishedAt: null,
+        durationMs: null,
+        attemptCount: 0,
+        models: [],
+        cacheStatus: "unknown",
+        usage: {
+          inputTokens: null,
+          outputTokens: null,
+          cachedInputTokens: null,
+          reasoningTokens: null,
+          totalTokens: null,
+        },
+        releaseId: "release_1",
+        traceId: "trace_1",
+        safeErrorCode: null,
+        attempts: [],
+      })
+      .mockResolvedValueOnce({ items: [], total: 0, page: 1, pageSize: 50 });
+
+    await getAiRuntimeRun("run/with space");
+    await listAiRuntimeActors("张 三", 1, 50);
+
+    expect(mocks.apiRequest).toHaveBeenNthCalledWith(
+      1,
+      "/system/ai-runtime/runs/run%2Fwith%20space",
+      {},
+    );
+    expect(mocks.apiRequest).toHaveBeenNthCalledWith(
+      2,
+      "/system/ai-runtime/actors?page=1&pageSize=50&q=%E5%BC%A0+%E4%B8%89",
+    );
+  });
+});

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

@@ -32,6 +32,34 @@ export interface OperationSnapshot {
       totalBytes: number;
       usagePercent: number;
     };
+    cpu: {
+      status: "available";
+      logicalCores: number;
+      hostUsagePercent: number | null;
+      processUsagePercent: number | null;
+      loadAverage1m: number | null;
+      message?: string;
+    };
+  };
+  gpuMonitor: {
+    status: "available" | "not-detected" | "unavailable";
+    provider: "NVIDIA";
+    message: string;
+    devices: Array<{
+      index: number;
+      uuid: string;
+      name: string;
+      usagePercent: number | null;
+      memoryUsedBytes: number | null;
+      memoryTotalBytes: number | null;
+      memoryUsagePercent: number | null;
+      temperatureCelsius: number | null;
+      processes: Array<{
+        pid: number;
+        name: string;
+        usedMemoryBytes: number | null;
+      }>;
+    }>;
   };
   databaseMonitor: {
     status: "healthy" | "not-configured" | "unavailable";

package/template/docker-compose.agent-debug.yml

@@ -25,7 +25,7 @@ services:
         "8000",
         "--no-reload",
         "--session_service_uri",
-        "memory://",
+        "windy-debug://v1",
         "--artifact_service_uri",
         "memory://",
         "--logo-text",

package/template/docs/architecture/ai-runtime.md

@@ -665,7 +665,8 @@ Tool 和终态摘要。业务 Permission、Scope、Execution Grant、Provider
 Token。项目配置只包含 Operation Key 与当前启用的真实开发数据用户 ID，不能重复或扩大
 Manifest 的权限、Scope 与 Tool 列表。数据用户用于复用其成员关系和当前 Scope。开发 Wrapper
 创建的核心主体仍是 `service_adk_debug`，权限只取该用户已有权限与 Operation/allowed
-Tools 闭包的精确交集，并且只能调用 canonical Run API；审计不会把它记录成普通用户会话。
+Tools 闭包的精确交集，并且只能调用 canonical Run API 与只读 debug-session GET；
+审计不会把它记录成普通用户会话。
 
 该 Adapter 证明真实业务执行链，不等于把另一进程内的完整 ADK Agent/Workflow 图装入
 原生 ADK Web。内部节点、Prompt 版本和 replay 若要可视化，必须通过另一个版本化协议

package/template/docs/architecture/module-host.md

@@ -11,6 +11,9 @@
 - `registerToolHandlers()`：为 Manifest `tools` 已声明的 Agent Tool 注册类型化 JSON 执行体，输入输出 Schema、`scopeMode` 与 Handler 均接入双向校验；
 - `registerRolePresets()`：注册角色预设，`permissionKeys` 必须属于本模块 Manifest 权限声明；预设并入内置角色同步（不存在则创建、漂移则非破坏性合并），不改变 4 个内置角色语义；
 - `registerSearchProviders()`：注册 Manifest `providers` 已声明的搜索 Provider；
+- `registerDebugSessionProviders()`：为 developer-only ADK Web 注册业务会话的只读
+  V1 投影；Provider 必须绑定本模块 Agent Operation，并复用该 Operation 的 Feature
+  与 Permission，业务 `sourceId` 不会越过 Host；
 - `registerUploadPolicy()`：按业务用途注册大小、分片、MIME、扩展名和签名策略；
 - `registerResourceFileAccessPolicies()`：注册本模块业务资源到平台文件的受限读取
   Resolver；purpose 必须来自当前模块或 Manifest 显式依赖模块，resourceType、

package/template/docs/platform/agent-run-attestation.md

@@ -0,0 +1,65 @@
+# Agent Run 输入证明
+
+本文说明 Windy 如何把一个 canonical Agent Run 绑定到发起时的受治理输入，以及业务模块
+如何在后续请求中验证这项绑定。该能力只提供平台级证明，不替业务模块决定会话、案件或
+消息的业务归属。
+
+## 平台契约
+
+Agent Run 启动前，Facade 已完成 Operation、Actor、Scope、DLP 与输入 Schema 治理。
+授权存储在签发 Run binding 时，对 Provider allowlist 投影中保留原值的输入执行稳定
+JSON canonicalization：
+
+- object key 按字典序递归排序；
+- array 保留原顺序；
+- 只接受 JSON 可表达的有限数值；
+- canonical JSON 先计算 SHA-256，再将 digest、binding token hash 与服务端 secret
+  一起计算 HMAC commitment；
+- 数据库只保存 commitment，不保存原始输入。
+
+`ModuleAiOperationPort.verifyAgentRun` 同时验证模块 Operation 所有权、Actor/Scope 的
+Run binding，以及调用方重建输入的 commitment。任一条件不匹配都 fail closed，业务层
+不能从响应中区分 Run 不存在、越权或输入不一致。
+
+同一 idempotency key 只有在 DLP 前 allowlist input commitment 相同的情况下才能复用
+既有 Run；有损 DLP 结果只用于 Handler 与 Provider 出网，不能作为 exact-input 证明。
+相同 key 携带不同输入会被拒绝，避免把一个已授权 Run 重新解释成另一项工作，也避免
+不同原文脱敏为相同占位符后发生承诺碰撞。
+
+## 兼容迁移
+
+`agent_run_bindings.input_digest_commitment` 是必填的 64 位十六进制字段。迁移会给旧行写入
+全零 sentinel，随后移除数据库默认值：
+
+- 旧 binding 在原 TTL 内仍可按既有规则读取 result、events 或 cancel；
+- 全零 sentinel 永远不能通过 `verifyAgentRun`；
+- 新 binding 必须由应用写入真实 commitment。
+
+这允许部署期间保持已有 Run 的普通生命周期，同时不会把迁移前未承诺输入的 Run 误认成
+可验证业务证据。
+
+## Canonical result 状态
+
+Module Host 将 Runtime 结果状态转换为稳定错误语义：
+
+- `409 RUN_CONFLICT`：Run 尚未完成；
+- `409 RUN_CANCELLED` 或 `409 RUNTIME_UNAVAILABLE`：Run 已进入 canonical 失败终态；
+- `5xx`：Runtime 当前不可用，不能据此推断 Run 已失败；
+- `400/404/422`：请求或 Run 无效；
+- `403`：无权访问。
+
+业务持久化只能把 canonical completed output 或明确的 canonical failure 记为终态。
+网络错误、Runtime 5xx 和未知 409 必须保持可重试，不能伪造终态。
+
+## 业务模块职责
+
+平台不会接受浏览器声明的业务 scope、会话历史或最终输出。业务模块需要：
+
+1. 从自己的持久化数据重建发起 Run 时的精确输入；
+2. 调用 `verifyAgentRun` 后再保存“已验证”标记；
+3. 从服务端 canonical result 保存输出；
+4. 对迁移前或未验证的业务记录 fail closed；
+5. 对回放、反馈、摘要和调试投影继续执行领域权限与数据治理。
+
+因此，Windy 提供通用密码学绑定和 Runtime 状态语义；产品仓库保留业务输入重建、授权
+范围派生与可信记录生命周期。

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

@@ -0,0 +1,135 @@
+# AI Runtime 用量与运行报表
+
+`system.ai-runtime` 为 `system.agent` 提供运行事实、模型用量和缓存覆盖的管理面。它读取
+canonical Agent Run 与每次 Provider Attempt 的独立报表投影，不把管理报表变成新的
+执行入口，也不以报表写入结果改写 canonical Run 终态。
+
+## 数据边界
+
+Agent Server 在 Run 接受、开始、终止以及每次模型或 Tool round 的 Provider Attempt
+边界写入以下事实：
+
+- Run：Operation Key、Release ID、Trace ID、Actor/部门范围标识、状态、开始/结束时间、
+  时长与安全错误码。
+- Attempt：序号、Tool round、Deployment Key、请求模型、Provider 返回模型、状态、
+  首 Token 延迟、时长与安全错误码。Provider 调用期间状态为 `running`；进程恢复时，
+  上一轮遗留的 `running` Attempt 会以恢复时间结束为 `abandoned`。
+- Provider 用量：输入、输出、缓存输入、reasoning 与总 Token；每项无法确认时保持
+  `null`，不会用 `0` 伪装为已知事实。
+- 覆盖状态：`provider-reported`、`estimated` 或 `unknown`，以及缓存
+  `hit`、`miss` 或 `unknown`。
+
+报表表不保存 Prompt、输出正文、Tool 参数/结果、Artifact 内容、Credential、Secret 或
+Provider 原始响应。Actor ID 和部门 ID 仅用于 Agent Server 与 Server 之间的内部范围
+过滤；浏览器 DTO 只得到经过当前用户目录重新解析的业务可读 Actor 摘要与随机化的
+opaque handle，不包含平台 Actor 主键。handle 由 Server 使用内部密钥派生的
+AES-GCM key 签发并在每次筛选时校验，篡改、换密钥或越出当前数据范围都会 fail closed。
+
+OpenAI-compatible Provider 的 `cached_tokens` 大于同一 Attempt 的
+`prompt_tokens` 时，该缓存事实被视为不可信并回落为 `unknown`，不会截断为 100%。
+
+## 指标口径
+
+管理面提供滚动 `24 小时`、滚动 `30 天`和当前留存期三档范围：
+
+- 成功率 = `completed / (completed + failed)`；取消与进行中 Run 不进入分母。
+- Run 数、成功率及 Run 活动日按 `Run.created_at` 落入范围。
+- Token、缓存、模型和首 Token 延迟按 `Attempt.started_at` 落入范围；它们可以来自
+  范围外创建、但在范围内实际调用 Provider 的长 Run。
+- 只有已有 `finished_at` 的 Attempt 进入汇总分母；详情仍实时展示 `running` Attempt。
+- Attempt 缓存命中率 = `hit / (hit + miss)`；`unknown` 不进入分母。
+- 缓存覆盖率 = `(hit + miss) / 已结束 Attempt`。
+- 总 Token 覆盖率 = `total_tokens` 已知的 Attempt 数 / 已结束 Attempt；只上报输入
+  Token 不会让总量覆盖率变成 100%。
+- 缓存 Token 比率只纳入同一 Attempt 中输入 Token 与缓存输入 Token 都已知的事实；其
+  配对输入 Token 总数大于 0 时才计算，缓存字段未知不能按零进入分子。
+- `reportingAvailableFrom` 取当前查询中 Run 创建时间与已结束 Attempt 开始时间的最早
+  可见事实；只有两者都为空时才为 `null`。无有效分母的比率为 `null`。
+- 活动趋势按 UTC 日历日合并 Run 创建日与 Attempt 调用日，不代表浏览器所在时区的
+  自然日；某日只要存在一个总 Token 未知的 Attempt，该日 `totalTokens` 就保持
+  `null`，不会把部分已知下界展示为完整日总量。
+
+汇总中的 Token 数字是已知事实之和；必须结合覆盖率读取，不能把部分覆盖误解成完整
+成本。有 Attempt 但某一类 Token 完全未上报时，该聚合字段保持 `null`；范围内没有
+Attempt 时聚合值为真实的 `0`。当前版本不根据 Token 猜测金额，也不把未知字段补成零。
+
+## 权限、范围与审计
+
+浏览器只访问 Server 的受管接口：
+
+```text
+GET /api/system/ai-runtime/summary
+GET /api/system/ai-runtime/runs
+GET /api/system/ai-runtime/runs/:runId
+GET /api/system/ai-runtime/actors
+```
+
+四条接口同时要求 Feature `system.ai-runtime` 与敏感披露 Permission
+`system.ai-runtime.read`。开发角色不会自动获得该权限；超级管理员或客户显式授权的
+报表角色才可访问。Server 将当前 Actor 的数据范围转换为显式的 Actor/部门 allowlist
+后传给 Agent Server；无法形成可执行范围时使用 `none` 并 fail closed。浏览器通过
+`actorHandle` 筛选，Server 验证并解析为内部 Actor ID 后还必须与当前范围取交集。
+
+详情查询先取得内部范围字段，再由 Server 校验对象级范围；越权与不存在统一返回 404。
+范围校验通过后，Server 删除 Actor ID 和部门 ID，并通过用户目录投影显示名和新的
+opaque handle。报表与列表读取写入关键审计 `agent.runtime.report.read`，详情读取写入
+`agent.runtime.run.read`。
+
+ADK Web 的 canonical bridge 仍以专用调试服务身份调用平台，但报表归属使用
+`toModuleActor(context.actor)` 后的真实数据用户，使开发调试用量进入正确的业务范围，
+而不是泄露或冒充普通登录会话。
+
+## Agent Server 内部接口与指标
+
+Server 使用 `AGENT_SERVER_INTERNAL_TOKEN` 访问：
+
+```text
+GET /api/internal/ai-runtime-report/summary
+GET /api/internal/ai-runtime-report/runs
+GET /api/internal/ai-runtime-report/runs/:runId
+```
+
+汇总和列表必须显式发送 `scopeMode=all|bounded|none`。`bounded` 可重复发送
+`scopeActorId` 与 `scopeDepartmentId`；默认 `none` 不返回任何 Run。详情接口只返回
+内部 DTO，不能直接暴露给浏览器。
+
+`GET /metrics` 只供 Agent Server 内网监控链路抓取，不应通过公网或浏览器路由暴露，并且
+仅使用低基数标签：
+
+- `southwind_agent_runtime_runs_total{outcome}`
+- `southwind_agent_runtime_attempts_total{outcome}`
+- `southwind_agent_runtime_cache_attempts_total{status}`
+- `southwind_agent_runtime_usage_attempts_total{source}`
+- `southwind_agent_runtime_tokens_total{kind,source}`
+- `southwind_agent_runtime_reporting_failures_total{stage}`
+
+Prometheus 标签禁止加入 Run ID、Actor、部门、Operation、模型名或错误正文。终态报表写入
+失败会记录日志与 `stage="run_terminal"` 计数，但 canonical Run 已完成后不会被改写为
+失败。`approval.required` 把非终态报表切换为 `awaiting-approval`，
+`approval.resolved` 切回 `running`；任何迟到的审批事件都不能让终态回退。Run 与
+Attempt 的所有报表写入都是旁路 best-effort；故障按 `run_ensure`、`run_start`、
+`run_status`、`run_terminal`、`attempt_start` 或 `attempt_terminal` 计数，不会中断
+canonical Run 或 Provider 请求。Attempt 开始写入失败时不再尝试写其终态，因此报表
+覆盖率必须与 reporting failure 指标一起判断。
+
+终态投影始终在 canonical mutation 后重新读取 Run：事件/输出存储上限或
+complete/cancel 竞争可能改变请求写入的终态，报表只接受 canonical Store 实际持久化的
+结果。Provider 已经返回完整响应后，即使 Tool 校验、取消或治理后处理把 Attempt 标为
+`blocked`、`cancelled` 或 `failed`，已收到的模型、Token、缓存和首 Token 延迟仍会保留。
+
+## 持久化与留存
+
+生产配置 `AGENT_DATABASE_URL` 时，Agent Server 使用 PostgreSQL 表
+`agent_runtime_report_runs` 与 `agent_runtime_report_attempts`。未配置数据库的本地
+运行使用进程内存实现，只适合开发与测试；重启后历史会丢失。
+
+`AI_RUNTIME_REPORT_RETENTION_DAYS` 控制报表留存，默认 `90`，允许 `1..3650`。
+PostgreSQL 实现在 `ensure_run` 接受新 Run 时清理已过期行；该设置不改变 canonical Run
+Store 的留存策略。生产启动必须把同一个 Report Store 实例同时注入 Engine 与
+`AgentRunService`，保证 Attempt 与 Run 终态进入同一投影和同一组指标。
+
+PostgreSQL 汇总在数据库内分别完成 Run、Attempt、模型和 UTC 日历日聚合，Attempt
+查询使用 `started_at` 索引及当前范围、Actor/部门 scope 约束；活动查询分别聚合范围内
+Run 与 Attempt 后再合并日期，不会先聚合整张 Attempt 表。返回量只随模型数与日期数
+增长；不会把留存期内全部 Run/Attempt 拉回 Agent Server。运行明细仍按页读取，并只为
+当前页加载 Attempt。

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

@@ -228,9 +228,9 @@ Operation Key 与真实开发数据用户注入 Windy-owned `docker-compose.agen
 
 - `create-windy` 自动生成独立随机 `ADK_DEBUG_PLATFORM_TOKEN`，无需复制登录 Token；
 - Server 只在 `NODE_ENV=development` 且加载调试 Compose Wrapper 时创建专用
-  `service_adk_debug` 身份；该 Token 只在 canonical Run 路径生效，不能访问 Foundation、
-  Admin 或其它 Server API；即使与普通会话 Token 误碰撞也被视为保留调试凭据，不会
-  回退普通认证；
+  `service_adk_debug` 身份；该 Token 只在 canonical Run 路径和只读 debug-session
+  GET 路径生效，不能访问 Foundation、Admin 或其它 Server API；即使与普通会话 Token
+  误碰撞也被视为保留调试凭据，不会回退普通认证；
 - Server 每次从用户目录解析 `dataActorId`，复用该用户当前 Scope 和业务成员 ID；只在
   用户本身拥有完整权限闭包时，向 Module 投影该真实用户。核心 Run、Token 和审计主体仍
   是 `service_adk_debug`，不会冒充普通用户会话；
@@ -250,6 +250,47 @@ Operation Key 与真实开发数据用户注入 Windy-owned `docker-compose.agen
 完整的 Prompt/Agent/Workflow 节点图。完整 workflow replay 需要另行定义版本化调试
 协议，不能从当前事件摘要推断。
 
+### 业务调试会话 V1
+
+业务模块可通过 `ModuleHost.registerDebugSessionProviders()` 把已有会话投影到
+`canonical_debug` 的原生 ADK Web 会话列表。该能力是 developer-only 的通用只读
+接缝，不是业务会话 Repository，也不定义 Copilot、案件或其它领域 DTO：
+
+- Provider 必须以本模块命名空间注册，并绑定至少一个本模块 Agent Operation；
+  `featureKey` 与 `permissionKey` 必须与绑定 Operation 完全一致，`auditAction` 必须
+  已在同一 Manifest 声明。
+- `list()` 和 `get()` 只接收 Host 投影的当前业务用户、当前配置的唯一 Operation、
+  分页上限、不透明 cursor 与 `AbortSignal`。Provider 应使用稳定 keyset 分页，并在
+  自身 Service/Repository 边界内再次执行对象级授权，只返回完成态的 `user` /
+  `assistant` 文本。
+- Server 只向 ADK Web 暴露
+  `GET /api/agent/debug/sessions/v1` 与
+  `GET /api/agent/debug/sessions/v1/:sessionId`。两条路径复用专用 Debug Bearer，
+  每次请求都重做 License、Feature 与 RBAC Guard；其它 Method 不在 Token 白名单。
+- 业务 `sourceId` 只用于 Provider 回查。Host 签发绑定“投影业务用户 + Operation +
+  Provider + sourceId”的 HMAC 不透明 ID；详情读取先重新 list 并重新授权，再调用
+  `get()`，不会把可逆 ID、Actor ID、Operation Key、Provider Key 或业务范围 ID
+  返回 ADK。
+- Provider 每页最多返回 100 个会话，Host 会沿不透明 cursor 读取完成后再交给原生
+  ADK 列表，不静默丢弃第 101 条及更旧会话；任一分页或 Provider 失败都会拒绝整份
+  业务列表，避免把 partial 结果伪装成完整结果。详情最多 64 条消息，单条最多
+  16,000 字符，总计最多 128,000 字符。重复条目、循环游标、超界、乱序、未知角色、
+  非法时间或 Provider 异常均安全拒绝。
+
+ADK 2.5 通过官方 `services.py` Service Registry 加载 `windy-debug://v1` composite
+Session Service。普通 ADK session 继续保存在进程内 `InMemorySessionService`；业务
+会话在每次详情读取时重新授权并转换为 ADK `Session/Event` 的实时只读投影，不在
+ADK 本地固化，也不复制 Tool、Citation、Run ID、内部
+Operation 或业务对象标识。平台列表暂时不可用时仍返回普通本地 session；已选择的导入
+session 详情不可用时明确失败。
+
+导入 session 在 V1 中严格只读：PATCH/rename 与新消息都会在 `append_event()` 拒绝，
+在 canonical Tool 再做一次防御性拒绝；DELETE 只在当前 ADK Web 进程创建本地 tombstone，
+不会删除业务历史。刷新进程后 tombstone 消失。要继续提问必须新建普通本地 ADK
+session；由于当前 canonical bridge 输入仍只有 `{ question }`，平台不会把历史文本冒充
+成业务 continuation。真正的历史续问需要后续版本定义通用、受权限治理的高层
+Operation 契约。
+
 ## 客户端协议
 
 浏览器继续使用 `@southwind-ai/ai-client` 访问同源 Southwind AI Server：
@@ -265,6 +306,9 @@ SSE 事件包括 `output.delta`、`tool.requested`、`tool.completed`、usage，
 `run.completed`、`run.failed` 或 `run.cancelled` 终态。断线后使用已确认 sequence 作为
 cursor 恢复；不要重新创建 Run 或重复执行 Tool。
 
+运行用量、缓存覆盖、滚动时间范围、数据范围与低基数 Prometheus 指标见
+[AI Runtime 用量与运行报表](./agent-runtime-observability.md)。
+
 ## 升级既有 Starter
 
 目标 CLI 会一次解析 source 到 target 的连续 recipe，不需要逐个安装中间 CLI。确认

package/template/docs/platform/operations-overview.md

@@ -6,6 +6,19 @@
 
 页面每 5 秒刷新一次基础监控快照，手动刷新会同时刷新已获授权的调度状态。`system.scheduler` Feature 未启用或当前用户没有 `system.scheduler.read` 时，前端不会请求调度接口，避免把符合预期的 Guard 拒绝渲染成加载故障。
 
+## CPU 与 GPU 监控
+
+CPU 区块同时展示宿主机 CPU 占用、Bun Server 进程占用、逻辑核心数和 1 分钟系统负载。宿主机占用按相邻快照之间的 CPU time 差值计算；进程占用按逻辑核心数归一化为整台机器容量，因此不会因为多核进程把进度条推到 100% 以上。服务刚启动或两次采样间隔不足时显示“采集中”，不会用负载均值冒充实时占用率。
+
+GPU 区块首期只探测 NVIDIA，通过只读 `nvidia-smi` 查询：
+
+- 每张设备的总体 GPU 利用率、显存占用、显存容量和温度；
+- 当前 NVIDIA 计算进程的 PID、进程名和显存占用，可用于确认同机 AI 服务是否已加载模型、占用了哪张卡及多少显存。
+
+设备利用率是 NVIDIA 驱动采样窗口内的整卡指标，进程明细不是逐进程 SM 利用率。远程 AI 服务的 GPU 不会因为配置了 HTTP Endpoint 自动出现在本机总览中；远端需要由其部署环境提供同类受控指标接口后再接入。字段语义遵循 [NVIDIA System Management Interface](https://docs.nvidia.com/deploy/nvidia-smi/index.html)。
+
+没有 `nvidia-smi`、非 NVIDIA 设备、驱动查询失败或超时时，接口返回稳定的 `not-detected` / `unavailable` 状态，页面明确说明原因而不是显示 0%。容器部署只有在 Server 容器获得 NVIDIA Container Toolkit 的 `utility` 能力、GPU 设备可见且 `nvidia-smi` 位于 `PATH` 时才能读取同宿主机设备和进程；否则保持不可探测状态。
+
 ## 在线会话与 IP
 
 “在线”定义为满足以下全部条件的登录会话：

package/template/docs/platform/platform-authentication.md

@@ -103,9 +103,10 @@ Web 不提供默认开发 Token。只有 Vite 开发模式同时设置 `VITE_DEV
 `ADK_DEBUG_PLATFORM_TOKEN`。只有 `bun run dev:adk-web` 加载的开发 Compose Wrapper
 会把它作为 `WINDY_ADK_DEBUG_TOKEN` 注入 Server，并注入 localhost-only ADK Web；它
 不会复用 `WINDY_DEV_ADMIN_TOKEN`，也不会启用固定 `dev-admin-token` 或 `user:` 直通。
-Server 仅在 canonical Agent Run 路径把它解析成 `service_adk_debug`，权限收敛为项目
-选择的 Operation 与 allowed Tools 权限闭包。该 Token 不进入 Web、Agent Server、
-Provider 或生产 Compose；非 development Server 即使误配也会拒绝。
+Server 仅在 canonical Agent Run 路径和只读
+`GET /api/agent/debug/sessions/v1/**` 路径把它解析成 `service_adk_debug`，权限收敛为
+项目选择的 Operation 与 allowed Tools 权限闭包。该 Token 不进入 Web、Agent
+Server、Provider 或生产 Compose；非 development Server 即使误配也会拒绝。
 
 未配置 `DATABASE_URL` 时不会注册真实登录 API；只允许显式的非生产开发直通，不存在内存生产账号或默认生产密码。
 

package/template/packages/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/config",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {