create-windy 0.3.2 → 0.3.5

package/template/docs/platform/governed-export-renderers.md

@@ -0,0 +1,132 @@
+# 受治理导出 Renderer
+
+更新时间：2026-07-27。
+
+## 适用边界
+
+业务 Module 可以在 `registerGovernedResources()` 的 `export.renderers` 中注册服务端
+Renderer，把同一条受治理导出链生成 PDF、DOCX、XLSX 或其它受控格式。Renderer 是版式
+实现，不是新的授权或存储入口：
+
+- 平台固化请求 Actor、Policy、查询、Scope 与 Renderer 版本；
+- 平台处理审批、Durable Job、重试、取消、Artifact、TTL、失败清理和下载审计；
+- Worker 在开始和读取每一页前重新检查用户、权限、Feature、License 与 Scope；
+- Renderer 只能读取平台提供的 `AsyncIterable` 记录、水印、`AbortSignal` 和
+  `heartbeat()`，不能取得 Repository、BlobStore、Workflow、平台 Secret 或下载凭据。
+
+未声明 `renderers` 的已有 Module 保持 NDJSON 契约。声明 Renderer 后，请求必须显式提供
+已注册的 `formatKey`；缺少、未知或执行时未绑定的格式均 fail closed，不回退到 NDJSON。
+
+## 注册契约
+
+每个 Renderer 声明以下不可变元数据：
+
+- `formatKey`：资源内稳定、唯一的小写格式 Key；
+- `templateKey`：当前 Module 命名空间内的模板 Key；
+- `templateVersion`：不可变模板版本；修改版式时递增，不覆盖历史版本；
+- `inputSchemaKey`：当前 Manifest `jsonSchemas` 已登记的记录输入 Schema；
+- `contentType` 与不含点号的 `filenameExtension`；
+- `maxRecords`、`maxOutputBytes` 和 `timeoutSeconds`；
+- `render()`：消费平台记录流并返回 `ReadableStream<Uint8Array>`。
+
+示例：
+
+```ts
+host.registerGovernedResources([
+  {
+    policyKey: "reports.official.fields",
+    readPath: "/api/reports/official/:id",
+    revealPath: "/api/reports/official/:id/plaintext",
+    revealAuditAction: "reports.official.reveal",
+    authorize,
+    read,
+    export: {
+      basePath: "/api/reports/official/exports",
+      validateQuery,
+      readPage,
+      renderers: [
+        {
+          formatKey: "pdf",
+          templateKey: "reports.official.pdf",
+          templateVersion: "2026.07",
+          inputSchemaKey: "reports.official.input.v1",
+          contentType: "application/pdf",
+          filenameExtension: "pdf",
+          limits: {
+            maxRecords: 10_000,
+            maxOutputBytes: 20 * 1024 * 1024,
+            timeoutSeconds: 120,
+          },
+          async render({ records, watermark }, { signal, heartbeat }) {
+            return renderOfficialPdf({
+              records,
+              watermark,
+              signal,
+              heartbeat,
+            });
+          },
+        },
+      ],
+    },
+  },
+]);
+```
+
+`renderOfficialPdf()` 属于业务 package，但必须是纯服务端流式 Renderer。它可以使用随
+业务 package 分发的模板和字体，不得在执行时绕回业务 Repository 补查数据，也不得自行
+上传、发布或签发下载链接。
+
+## 请求与版本固化
+
+创建请求的 body 在原有 `idempotencyKey`、`reason`、`query` 之外接受 `formatKey`。
+平台在校验 Host 注册后，把以下快照持久化并纳入请求 fingerprint：
+
+- 格式、模板 Key 与模板版本；
+- 输入 Schema Key；
+- MIME 与扩展名；
+- 记录、输出字节和超时上限。
+
+相同幂等键改选格式、模板或上限会形成语义冲突。Worker 执行时把持久化快照与当前 Host
+注册逐项比对；部署遗漏 Renderer 或模板版本漂移会终止任务，避免恢复任务静默套用另一套
+版式。
+
+## 流、取消与资源限制
+
+平台逐页调用业务 `readPage()`，在每页读取前重新授权，再把记录逐条交给 Renderer。
+Renderer 应使用 `for await` 消费记录，不应先汇总完整数组。Renderer 未完整消费记录流
+即返回产物时，平台拒绝发布。
+
+平台同时施加以下硬边界：
+
+- 超过 `maxRecords` 时终止记录流；
+- 读取输出流时累计实际字节数，超过 `maxOutputBytes` 时终止；
+- `timeoutSeconds` 到期或 Durable Job 取消时中止同一个 `AbortSignal`；
+- 每页完成后更新 heartbeat 与 Durable Job progress；
+- 渲染、流读取或 Artifact 发布失败时删除已经写入但尚未发布的 Blob。
+
+Renderer 必须把 `signal` 继续传给支持取消的模板、压缩或文档库。忽略 Signal 的库仍会在
+平台读取输出时被终止，但可能延迟释放其内部 CPU 或内存，因此不应作为生产 Adapter。
+
+## Artifact 与审计
+
+发布后的 Durable Artifact 记录真实文件名、MIME、SHA-256、字节数，并在受控 metadata
+中记录 `formatKey`、`templateKey`、`templateVersion`、`inputSchemaKey` 和 Renderer
+返回的有限 `contentMetadata`。`contentMetadata` 只允许有界 JSON，不得包含记录原文、
+敏感字段、完整 ID 集或模板生成的正文。
+
+请求审计记录格式和模板版本；生成 intent 审计还记录输入 Schema 与 MIME；下载审计记录
+同一格式、模板版本和内容摘要。下载前仍重新检查 owner、Permission、Feature、审批、
+TTL、Artifact 引用和 Blob 完整性，Renderer 不能改变这些顺序。
+
+## 测试要求
+
+业务 Renderer 至少覆盖：
+
+- 正文、来源引用和水印内容，而不只断言文件存在；
+- 请求缺少格式、未知格式、注册丢失和模板版本漂移；
+- 多页记录按流消费，记录/输出上限与超时；
+- 取消、权限撤销、Scope 变化、渲染失败和发布失败不留下可下载半成品；
+- 下载 MIME、文件名、SHA-256、字节数与模板元数据一致。
+
+PDF、DOCX、XLSX 应使用对应解析库回读断言正文和水印。平台的测试 Renderer 只证明 Port
+及治理生命周期；具体文档格式正确性由实现该格式的业务 Module 负责。

package/template/docs/platform/navigation-registry.md

@@ -34,3 +34,8 @@ PUT /api/system/menus/:id/placement
 ## 扩展约束
 
 新增页面时先在所属 Module Manifest 用同一能力 Key 注册 Feature、权限、菜单和 API 绑定，再新增 Router 页面。Router 契约测试会比较所有 `type=menu` 的 Manifest 路径与 Web 路由，避免出现“菜单有入口但页面不存在”或“页面绕过注册表”的漂移。
+
+客户业务页面不直接修改 shared-scaffold Router 或侧栏。页面实现注册到
+project-owned 的 `apps/web/src/app/business-routes.ts`，平台 Router Adapter 统一补齐
+Feature/RBAC Guard；侧栏仍从服务端 Manifest 快照生成。完整接入与升级边界见
+[project-owned 业务 Web 路由](../development/business-web-routes.md)。

package/template/docs/platform/organization-membership.md

@@ -9,7 +9,8 @@ Windy V1 采用单组织、单租户的企业私有化模型。canonical schema
 - `roles.data_scope` 和 `roles.department_ids` 表示角色数据范围策略；
 - 岗位、兼职部门和多组织成员关系属于后续独立模型，不复用 `department_id` 暗中表达。
 
-这些边界延续 [RuoYi-Vue 兼容与迁移设计](../adapters/ruoyi-vue-compatibility.md) 的 Adapter 原则，也与 [Starter 产品缺口分析](../product/starter-product-gap-analysis.md) 中“单组织 V1”和“数据权限必须进入查询约束”的结论一致。
+这些边界延续 [RuoYi-Vue 兼容与迁移设计](../adapters/ruoyi-vue-compatibility.md) 的
+Adapter 原则；数据权限必须进入查询约束，不能只依赖 Web 菜单或按钮隐藏。
 
 ## 用户表单闭环
 

package/template/docs/platform/speech-ai-runtime.md

@@ -0,0 +1,156 @@
+# Speech AI Runtime
+
+更新时间：2026-07-27。
+
+Windy 的首个 Speech Runtime 只提供基于授权 `ArtifactRef` 的批量转写。实时 ASR、
+TTS 和 Dictation 不在本切片内。业务模块持有音频资产、原消息关系、人工校正、翻译和
+业务状态；平台持有身份授权、Operation 路由、运行时协议、配额与审计。
+
+未安装或未配置 Speech Server 时，Speech Operation 稳定返回
+`CAPABILITY_UNAVAILABLE`，不会回落到文本 Agent，也不阻止普通业务、Document 或文本
+Agent 启动。
+
+## 安全调用链
+
+1. 业务模块注册音频资源的 `ModuleResourceFileAccessPolicy`，从 project-owned
+   Repository 回查 `resourceId`、`fileId` 与当前 Actor 的真实关系。
+2. 模块路由调用 `context.aiArtifacts.issue(...)` 换取加密、短时、opaque
+   `ArtifactRef`。
+3. `@southwind-ai/ai-client/speech` 只把 Artifact 与领域选项提交到同源 Southwind
+   Server。
+4. Server 重新检查 Feature、Permission、License、数据范围、能力摘要和 Artifact
+   元数据，并按 Actor + Operation 作用域化幂等键。
+5. Speech Server 从自身固定的内网 Artifact Endpoint 下载源文件；请求不能指定 URL。
+6. Speech Server 使用 FFmpeg 把常见音频/视频容器归一化为 16 kHz、单声道、
+   PCM S16LE WAV，再调用已配置的本地/内网 Adapter。
+
+禁止业务 Server 运行 Whisper/ASR/转码进程、直连语音 Provider，或把音频、Base64、
+Blob Key、宿主路径、模型名、Endpoint 和 Secret 交给文本 Agent。
+
+## Manifest 与 Module Handler
+
+`kind=speech` Operation 必须声明：
+
+- Feature、Permission、Audit、输入/输出 Schema；
+- `speech.transcribe.batch` 及需要的 `speech.normalize`、`speech.vad`、
+  `speech.timestamps` capability；
+- 数据分类、Deployment 与 Provider 出网策略；
+- 输入/输出字节、处理时长、最大稳定分段数 `maxUnits` 和媒体时长
+  `maxMediaDurationSeconds`。
+
+```ts
+const operation = {
+  key: "evidence.audio.transcribe",
+  kind: "speech",
+  featureKey: "evidence.audio.transcribe",
+  permissionKey: "evidence.audio.transcribe.execute",
+  auditAction: "evidence.audio.transcribe.execute",
+  inputSchemaKey: "evidence.audio.transcribe.input.v1",
+  outputSchemaKey: "evidence.audio.transcribe.output.v1",
+  requiredCapabilities: [
+    "speech.transcribe.batch",
+    "speech.normalize",
+    "speech.vad",
+    "speech.timestamps",
+  ],
+  allowedToolKeys: [],
+  dataClassification: "sensitive",
+  execution: "background",
+  providerEgress: { mode: "forbidden" },
+  limits: {
+    maxDurationSeconds: 1800,
+    maxInputBytes: 512 * 1024 * 1024,
+    maxOutputBytes: 32 * 1024 * 1024,
+    maxUnits: 100000,
+    maxMediaDurationSeconds: 8 * 60 * 60,
+  },
+} as const;
+```
+
+同一 Operation 注册 `prepareSpeech`。Handler 只校验并收敛语言、VAD 与时间戳等领域
+选项，不选择模型或 Deployment。受控出网时，选项先经过
+`providerDataPolicy.inputFields` 裁剪/DLP；完全断网时 Adapter 仍只接受本地/内网地址。
+
+## 输入、输出与事件
+
+首批接受 FFmpeg 可探测且 MIME 属于 allowlist 的 MP3、M4A/MP4、WAV、OGG、FLAC、
+WebM 音频或含音轨的视频。归一化失败、时长超限或内容损坏都返回稳定错误，不把 FFmpeg
+stderr 暴露给业务。
+
+选项：
+
+```ts
+{
+  language?: string;
+  vad?: {
+    enabled: boolean;
+    minSpeechMs?: number;
+    maxSilenceMs?: number;
+  };
+  timestamps?: "segment" | "word";
+}
+```
+
+Adapter 返回的分段会被 Runtime 重新校验和规范化：
+
+- 稳定 ID 为 `segment-000001` 递增；
+- segment 与 word 时间戳单调、非负且不超过素材时长；
+- 文本不能为空，置信度必须在 0–1；
+- 分段总数受 `maxUnits` 与 Runtime 双重配额约束；
+- 输出只保留标量 metadata，并明确记录归一化格式。
+
+事件协议：
+
+```text
+run.started
+speech.segment.completed
+run.completed | run.failed | run.cancelled
+```
+
+每个事件有单调 sequence。客户端断线后用 cursor 恢复；取消会写入终态并取消归一化或
+Adapter 协程。相同幂等键和相同语义返回原 Run，语义漂移返回 `RUN_CONFLICT`。
+
+## 结果 Artifact
+
+完成后提供两个互补接口：
+
+```text
+GET /api/speech/runs/:runId/result
+GET /api/speech/runs/:runId/artifact
+```
+
+`result` 返回结构化转写及 Artifact 元数据；`artifact` 返回 Speech Server 持久化的同一
+canonical JSON 字节流，包含 `content-length` 与 `x-content-sha256`。Artifact 下载仍需
+平台 Run 所有权授权，使用 `private, no-store`，不暴露 Speech Server 路径或数据库。
+
+结果包含 `durationMs`、可选语言、稳定 segments、词级时间戳、置信度和 metadata。
+业务可以在通过输出 Schema 后把结果导入自己的事实表、保存来源回链并进入人工校正；
+平台不会替业务保存消息关系或翻译状态。
+
+## 部署
+
+选择 `system.agent` 的 Starter 会分发独立 Speech Server。配置：
+
+```dotenv
+PLATFORM_ENABLE_AI=true
+AGENT_SERVER_INTERNAL_TOKEN=<随机内部令牌>
+AI_ARTIFACT_ENCRYPTION_SECRET=<至少 32 字符>
+SPEECH_SERVER_URL=http://speech-server:8091
+SPEECH_ARTIFACT_URL=http://server:9747/api/internal/ai/artifacts
+SPEECH_ADAPTER_URL=http://asr.internal:9001
+SPEECH_ADAPTER_TOKEN=<可选内部令牌>
+SPEECH_ADAPTER_CAPABILITIES=speech.transcribe.batch,speech.normalize,speech.vad,speech.timestamps
+SPEECH_MAX_UNITS=100000
+SPEECH_MAX_MEDIA_DURATION_SECONDS=86400
+```
+
+受控 Provider 还需配置 `SPEECH_DEPLOYMENT_KEY`，且必须与 Manifest 完全一致。启动：
+
+```bash
+bun run dev:speech
+```
+
+Speech Server 自有 SQLite 保存 Run、cursor、终态转写和结果 Artifact，适合单副本。
+健康检查需要内部 Bearer Token，只返回 capability 与非敏感 limits。Adapter、FFmpeg
+或 FFprobe 不可用时返回 unavailable；完全断网 profile 使用已包含 FFmpeg 的镜像和
+本地/内网 ASR Adapter，运行时不需要公网。

package/template/docs/platform/system-crud-api.md

@@ -95,7 +95,13 @@ GET    /api/system/audit-logs
 - 配置 `DATABASE_URL` 后，系统资源使用 Drizzle Repository，启动时会按 `id` / `key` 幂等写入默认种子数据，不覆盖已有记录。
 - Feature Flag 是受控资源：Key 和元数据由 Module Manifest 幂等同步，API 只允许修改 `enabled` / `visible`，不提供创建、导入或删除入口。Manifest 移除的 Key 会归档保留历史状态。
 - Feature Guard 在配置数据库时按请求、按 Key 读取运行态；同一请求缓存结果，下一请求重新读取。开发无数据库时回退 Manifest，生产无数据库或读取失败时 fail closed。
-- CRUD 成功和权限拒绝会先进入进程内审计 sink；配置 `DATABASE_URL` 后由可靠写入器写入 PostgreSQL `audit_logs`。普通事件持续失败时业务继续并告警；用户、角色、License 与 Feature Flag 等关键变更必须落库或进入本地原子恢复队列。策略、状态和恢复步骤见 [平台审计可靠写入](./audit-reliability.md)。
+- CRUD 成功和权限拒绝会先进入进程内审计 sink；配置 `DATABASE_URL` 后由可靠写入器写入 PostgreSQL `audit_logs`。普通事件持续失败时业务继续并告警；用户、角色、License 与 Feature Flag 等关键变更必须落库或进入本地原子恢复队列。
+
+<!-- @windy-module system.audit begin -->
+
+策略、状态和恢复步骤见 [平台审计可靠写入](./audit-reliability.md)。
+<!-- @windy-module system.audit end -->
+
 - 密码登录、服务端会话、退出和吊销已闭环；通用用户 CRUD 不读写或返回密码 hash，密码更新走受权限保护的认证 API。
 
 <!-- @windy-module system.license begin -->

package/template/docs/platform/vision-ai-runtime.md

@@ -0,0 +1,97 @@
+# Vision AI Runtime
+
+更新时间：2026-07-27。
+
+Windy 的首个 Vision 切片在现有 Agent canonical Run 上增加受治理的图片 Artifact 输入，
+用于图片内容理解和结构化视觉提取。它不新增由业务选择模型的 `vision` kind：
+`agent.vision.*` 仍是 `kind=agent` 的流式语义；`document.parse.multimodal` 仍是
+`kind=document` 的异步页级语义。相同 VLM Deployment 可以承载两者，但不能混用
+路由、结果契约或业务状态。
+
+## 不变量
+
+- 浏览器和业务模块只提交平台签发的 opaque `ArtifactRef`，不能提交 URL、Base64、
+  BlobStore Key、宿主路径、模型名或 Provider Endpoint。
+- Southwind Server 在 Feature、Permission、License、数据范围通过后重新打开资源，
+  校验 MIME、字节数与 SHA-256，再为 Agent Server 轮换短时引用。
+- Agent Server 只从固定 `AI_ARTIFACT_URL` 内网入口读取图片，拒绝调用方 URL。
+- 只接受 JPEG、PNG、WebP；解码后强制检查图片数量、总字节与单图像素。
+- 图片解码后统一转成无 EXIF/ICC/文件名的 PNG，再作为 OpenAI-compatible
+  `image_url` typed content part 发送；不会拼接进文本 Prompt。
+- 每次 Provider attempt 都要求 `artifact-content` allowlist、执行字段 DLP，并记录
+  Deployment、Operation、Run、attempt、分类、发送字节和 allow/redact/reject 决策。
+
+## Manifest
+
+Vision Operation 必须显式声明输入模态、能力和双重资源上限：
+
+```ts
+{
+  key: "evidence.image.inspect",
+  kind: "agent",
+  inputModalities: ["text", "image"],
+  requiredCapabilities: ["text-generation", "vision"],
+  providerEgress: {
+    mode: "configured-endpoint",
+    deploymentKey: "ai.openai-compatible"
+  },
+  providerDataPolicy: {
+    inputFields: [/* project-owned JSON Pointer allowlist */],
+    envelopeFields: [
+      { field: "instructions", classification: "internal", dlpAction: "reject" },
+      { field: "user-prompt", classification: "internal", dlpAction: "redact" },
+      { field: "artifact-content", classification: "sensitive", dlpAction: "reject" },
+      { field: "output-schema", classification: "internal", dlpAction: "reject" },
+      { field: "provider-output", classification: "sensitive", dlpAction: "redact" }
+    ]
+  },
+  limits: {
+    maxDurationSeconds: 120,
+    maxInputBytes: 32 * 1024 * 1024,
+    maxOutputBytes: 1024 * 1024,
+    maxArtifacts: 8,
+    maxPixelsPerArtifact: 24_000_000
+  }
+}
+```
+
+未声明 `image`、数量或像素上限时，Manifest 组合直接失败。运行时还会把
+`kind=agent`、`inputModalities` 和 `requiredCapabilities` 发给 Agent Server；当前
+Deployment 缺少任一项时返回 `MODEL_ROUTE_UNAVAILABLE`，不能静默落到文本模型。
+
+## 结构化输出
+
+Module Handler 可以在执行计划中提供受限 JSON Schema：
+
+```ts
+return {
+  instructions: "只根据图片中可见内容提取，不推测身份。",
+  userPrompt: "提取票据字段并标出无法确认的值。",
+  outputSchema: {
+    type: "object",
+    additionalProperties: false,
+    required: ["fields"],
+    properties: {
+      fields: { type: "array", items: { type: "object" } },
+    },
+  },
+};
+```
+
+平台限制 Schema 为 256 KiB，并以 Manifest `outputSchemaKey` 关联审计。Agent Server
+通过 OpenAI-compatible `response_format=json_schema` 发送，终态前再次用 JSON Schema
+校验；无效 JSON 或不匹配结果以 `OUTPUT_VALIDATION_FAILED` 结束，不能把未经校验的对象
+交给业务。业务仍须用 `AgentOperation.parseOutput` 收窄远端值并保存来源回链、人工复核
+和领域状态。
+
+## 部署
+
+```dotenv
+AI_ARTIFACT_URL=http://server:9747/api/internal/ai/artifacts
+AI_PROVIDER_CAPABILITIES=text-generation,vision
+AI_PROVIDER_INPUT_MODALITIES=text,image
+```
+
+VLM 可以是 localhost、内网或经 allowlist 授权的 HTTPS Deployment。完全断网环境使用
+本地/内网 OpenAI-compatible VLM；图片回取与 Provider 调用均不需要公网。未配置 VLM
+能力时普通文本 Agent、Document、Speech 和非 AI 业务继续独立运行。

package/template/docs/platform/web-system-crud.md

@@ -89,7 +89,13 @@ VITE_DEV_ADMIN_TOKEN=<显式开发 Token>
 - 系统资源表和字典后台任务表加载时保留表头与列宽，并显示带 `animate-pulse` 的骨架行；加载失败和空数据仍使用各自独立状态。
 - 全局水印与业务页面范围默认开启。管理员在“全局设置”中维护总开关、低/中/高密度，并勾选用户名、姓名、手机号、邮箱或最多 80 个字符的自定义内容；保存写入审计并立即成为所有用户的只读策略。客户端按旋转文本包围盒自动计算平铺尺寸与安全间距，长内容和高密度模式也不会相互重叠。用户应用端不提供开关，也不使用 localStorage。`system.watermark` Feature 控制最终生效态，管理区另需 `system.watermark.read/manage` 权限。水印使用专用审计顶层覆盖 Sidebar、Drawer、Overlay 和 Modal，同时保持 `pointer-events-none`。服务端只向当前用户自己的会话响应补充这些身份字段。
 - 站内通知由 PostgreSQL `platform_notifications`、`notification_revisions`、`notification_reads` 和 `notification_favorites` 持久化；管理人员可在 `/system/notifications` 广播发布、修改、查看版本历史和归档，用户从 Header 收件箱阅读正文并幂等写入相互独立的已读、收藏回执。修改会生成带服务端时间和 Actor 的完整不可变快照，无内容变化不增加版本。普通用户 API 支持关键词、分类、已读和收藏的服务端组合筛选，列表与 `total` 使用同一可见性范围。归档是生命周期操作，不物理删除通知、版本或回执。
+
+<!-- @windy-module system.bulk-data begin -->
+
 - 字典页已切换为后台 NDJSON 导入导出，展示本人任务状态、进度、重试和终态文件下载；其它系统资源仍保留小数据同步 JSON 入口。详细契约见 [批量导入导出后台任务](./bulk-data-jobs.md)。当前 artifact 存在 10 MiB、50,000 行和 256 KiB 单行上限，扩大容量前需要对象存储 Adapter。
+
+<!-- @windy-module system.bulk-data end -->
+
 - 审计日志配置 `DATABASE_URL` 后读取 PostgreSQL `audit_logs`。可靠写入器提供有界重试、降级状态、关键事件本地恢复队列和健康信息；页面仍只读，且不会展示恢复队列中的事件正文。
 - 运维页的定时任务来自真实代码注册和 PostgreSQL 状态，不允许在线编辑任务代码。当前基线的 `stale` 只做观察告警和人工处置提示，不会自动终止或重试。
 

package/template/package.json

@@ -16,6 +16,9 @@
     "dev:web": "bun run --cwd apps/web dev",
     "dev:server": "bun run --cwd apps/server dev",
     "dev:agent": "docker compose --profile agent up --build",
+    "dev:document": "PLATFORM_ENABLE_AI=true DOCUMENT_SERVER_URL=http://document-server:8090 docker compose --profile agent --profile document up --build",
+    "dev:speech": "PLATFORM_ENABLE_AI=true SPEECH_SERVER_URL=http://speech-server:8091 docker compose --profile agent --profile speech up --build",
+    "dev:embedding": "PLATFORM_ENABLE_AI=true EMBEDDING_SERVER_URL=http://embedding-server:8092 docker compose --profile agent --profile embedding up --build",
     "dev:adk-web": "docker compose --profile agent-debug up --build adk-web-debug",
     "dev:search": "OPENSEARCH_URL=http://opensearch:9200 docker compose --profile search up --build",
     "dev:license": "bun run --cwd apps/license dev",
@@ -37,19 +40,30 @@
     "test:db:license-bootstrap": "bun run scripts/license-bootstrap-postgres-regression.ts",
     "test:db:migrations": "bun run scripts/database-migration-regression.ts",
     "test:db:config": "bun run scripts/module-configuration-postgres-regression.ts",
+    "test:db:release": "bun run test:db:migrations && bun run test:db:auth && bun run test:db:data-scope && bun run test:db:organization && bun run test:db:notification && bun run test:db:governance && bun run test:db:legacy-license && bun run test:db:license-bootstrap && bun run test:db:config",
     "test:redis:health": "bun run scripts/redis-health-regression.ts",
     "test:vault:signing": "bun run scripts/vault-signing-regression.ts",
     "test:docker:license-signing": "bun run scripts/license-signing-compose-regression.ts",
     "test:ops:recovery": "bun run scripts/production-recovery-regression.ts",
     "test:ops:amd64": "bun run scripts/linux-amd64-container-regression.ts",
+    "test:ops:tool-sandbox": "bun run scripts/tool-sandbox-isolation-regression.ts",
     "ops:db": "bun run scripts/production-database.ts",
     "ops:release": "bun run scripts/production-release.ts",
-    "test:release:evidence": "bun run scripts/release-evidence.ts",
+    "test:merge": "bun run scripts/merge-gate.ts",
+    "release:verify": "bun run scripts/release-verify.ts",
     "test:packages:pack": "bun run scripts/platform-package-release.ts",
-    "test:agent": "uv run --directory apps/agent-server pytest && uv run --directory apps/agent-server ruff check . && uv run --directory apps/agent-server ruff format --check . && uv run --directory apps/agent-server mypy",
+    "test:agent": "uv run --directory apps/agent-server pytest",
+    "test:document": "uv run --directory apps/document-server pytest",
+    "test:speech": "uv run --directory apps/speech-server pytest",
+    "test:embedding": "uv run --directory apps/embedding-server pytest",
+    "check:agent": "uv run --directory apps/agent-server ruff check . && uv run --directory apps/agent-server ruff format --check . && uv run --directory apps/agent-server mypy",
+    "check:document": "uv run --directory apps/document-server ruff check . && uv run --directory apps/document-server ruff format --check . && uv run --directory apps/document-server mypy",
+    "check:speech": "uv run --directory apps/speech-server ruff check . && uv run --directory apps/speech-server ruff format --check . && uv run --directory apps/speech-server mypy",
+    "check:embedding": "uv run --directory apps/embedding-server ruff check . && uv run --directory apps/embedding-server ruff format --check . && uv run --directory apps/embedding-server mypy",
     "typecheck": "bun run --cwd apps/web typecheck && bun run --cwd apps/server typecheck && bun run --cwd apps/license typecheck && bun run --cwd apps/signing-service typecheck && bun run --cwd packages/ai-client typecheck && bun run --cwd packages/license-sdk typecheck && bun run --cwd packages/jobs typecheck && bun run --cwd packages/server-sdk typecheck && bun run --cwd packages/storage typecheck && bun run --cwd packages/database typecheck && bun run --cwd packages/crud-generator typecheck && bun run --cwd packages/create-windy typecheck",
     "lint": "oxlint .",
     "format": "oxfmt",
+    "check:static": "bun run lint && bun run typecheck && bun run check:agent && bun run check:document && bun run check:speech && bun run check:embedding",
     "format:staged": "lint-staged",
     "test": "bun test --path-ignore-patterns='packages/create-windy/template/**' && bun run --cwd apps/web test"
   },

package/template/packages/ai-client/index.ts

@@ -1 +1,5 @@
 export * from "./src/agent/index.js";
+export type { ArtifactRef } from "./src/artifact-ref.js";
+export * from "./src/document/index.js";
+export * from "./src/embedding/index.js";
+export * from "./src/speech/index.js";

package/template/packages/ai-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/ai-client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -18,7 +18,10 @@
   "exports": {
     ".": "./index.ts",
     "./agent": "./src/agent/index.ts",
-    "./contracts": "./src/agent/contracts/index.ts"
+    "./contracts": "./src/agent/contracts/index.ts",
+    "./document": "./src/document/index.ts",
+    "./embedding": "./src/embedding/index.ts",
+    "./speech": "./src/speech/index.ts"
   },
   "publishConfig": {
     "access": "public"

package/template/packages/ai-client/src/agent/client/artifact.ts

@@ -0,0 +1,26 @@
+import type { ArtifactRef } from "../../artifact-ref.js";
+import { AgentClientError } from "./error.js";
+
+export function parseAgentArtifactRef(value: ArtifactRef): ArtifactRef {
+  if (
+    !value.value.trim() ||
+    /^[a-z][a-z0-9+.-]*:\/\//i.test(value.value) ||
+    !value.mediaType.trim() ||
+    !Number.isSafeInteger(value.byteSize) ||
+    value.byteSize < 0 ||
+    !/^[a-f0-9]{64}$/.test(value.sha256)
+  ) {
+    throw new AgentClientError(
+      "INVALID_CONFIGURATION",
+      "Agent ArtifactRef 无效",
+      false,
+    );
+  }
+  return {
+    value: value.value,
+    mediaType: value.mediaType,
+    byteSize: value.byteSize,
+    sha256: value.sha256,
+    ...(value.expiresAt ? { expiresAt: value.expiresAt } : {}),
+  };
+}

package/template/packages/ai-client/src/agent/client/attach.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createAgentCaller,
+  defineAgentOperation,
+  type AgentEvent,
+} from "@southwind-ai/ai-client";
+import type { AgentFetch } from "./types.js";
+
+const operation = defineAgentOperation<null, { answer: string }>(
+  "support.answer",
+  (value) => value as { answer: string },
+);
+
+describe("Agent Run attach", () => {
+  test("从游标之后恢复同一个 live Run", async () => {
+    const fake = plannedFetch([
+      () =>
+        Response.json({
+          runId: "run-live",
+          status: "running",
+          lastSequence: 3,
+          eventsUrl:
+            "/api/agent/runs/run-live/events?operationKey=support.answer",
+        }),
+      () =>
+        sse([
+          event({
+            type: "output.delta",
+            runId: "run-live",
+            sequence: 3,
+            text: "A",
+          }),
+          event({ type: "run.completed", runId: "run-live", sequence: 4 }),
+        ]),
+      () =>
+        Response.json({
+          runId: "run-live",
+          status: "completed",
+          output: { answer: "A" },
+        }),
+    ]);
+    const caller = createAgentCaller({
+      baseUrl: "https://agent.internal",
+      fetch: fake.fetch,
+    });
+
+    const run = await caller.attach(operation, "run-live", { cursor: 2 });
+    const collected = collect(run.events);
+
+    await expect(run.result()).resolves.toEqual({ answer: "A" });
+    expect((await collected).map(({ sequence }) => sequence)).toEqual([3, 4]);
+    expect(JSON.parse(String(fake.calls[0]?.init?.body))).toEqual({
+      operationKey: "support.answer",
+      cursor: 2,
+    });
+    expect(fake.calls[1]?.url.searchParams.get("after")).toBe("2");
+    expect(fake.calls[2]?.url.searchParams.get("operationKey")).toBe(
+      "support.answer",
+    );
+  });
+
+  test("终态游标可直接读取结果且不重新连接事件流", async () => {
+    const fake = plannedFetch([
+      () =>
+        Response.json({
+          runId: "run-done",
+          status: "completed",
+          lastSequence: 4,
+          terminalEvent: {
+            type: "run.completed",
+            runId: "run-done",
+            sequence: 4,
+          },
+          eventsUrl:
+            "/api/agent/runs/run-done/events?operationKey=support.answer",
+        }),
+      () =>
+        Response.json({
+          runId: "run-done",
+          status: "completed",
+          output: { answer: "完成" },
+        }),
+    ]);
+    const caller = createAgentCaller({
+      baseUrl: "https://agent.internal",
+      fetch: fake.fetch,
+    });
+
+    const run = await caller.resume(operation, "run-done", { cursor: 4 });
+
+    await expect(run.result()).resolves.toEqual({ answer: "完成" });
+    expect(fake.calls).toHaveLength(2);
+  });
+});
+
+function plannedFetch(plans: Array<(url: URL) => Response>) {
+  const calls: Array<{ url: URL; init?: RequestInit }> = [];
+  const fetch: AgentFetch = async (input, init) => {
+    const url = new URL(
+      input instanceof Request ? input.url : input.toString(),
+    );
+    calls.push({ url, init });
+    const plan = plans[calls.length - 1];
+    if (!plan) throw new Error(`unexpected fetch ${url}`);
+    return plan(url);
+  };
+  return { calls, fetch };
+}
+
+function sse(frames: string[]): Response {
+  return new Response(frames.join(""), {
+    headers: { "content-type": "text/event-stream" },
+  });
+}
+
+function event(value: AgentEvent): string {
+  return `id: ${value.sequence}\nevent: ${value.type}\ndata: ${JSON.stringify(value)}\n\n`;
+}
+
+async function collect(events: AsyncIterable<AgentEvent>) {
+  const values: AgentEvent[] = [];
+  for await (const value of events) values.push(value);
+  return values;
+}