create-windy 0.3.4 → 0.3.5

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

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

package/template/packages/database/drizzle/0042_puzzling_rumiko_fujikawa.sql

@@ -0,0 +1,27 @@
+ALTER TABLE "durable_job_artifacts" ADD COLUMN "metadata" jsonb;--> statement-breakpoint
+ALTER TABLE "governed_export_requests" ADD COLUMN "renderer" jsonb;--> statement-breakpoint
+UPDATE "governed_export_requests"
+SET "renderer" = jsonb_build_object(
+  'formatKey', 'ndjson',
+  'templateKey', 'system.governed-export.ndjson',
+  'templateVersion', '1',
+  'inputSchemaKey', 'system.governed-export.record.v1',
+  'contentType', 'application/x-ndjson',
+  'filenameExtension', 'ndjson',
+  'maxRecords', 50000,
+  'maxOutputBytes', 10485760,
+  'timeoutSeconds', 900
+)
+WHERE "renderer" IS NULL;--> statement-breakpoint
+UPDATE "durable_job_artifacts" AS artifact
+SET "metadata" = jsonb_build_object(
+  'formatKey', request."renderer" ->> 'formatKey',
+  'templateKey', request."renderer" ->> 'templateKey',
+  'templateVersion', request."renderer" ->> 'templateVersion',
+  'inputSchemaKey', request."renderer" ->> 'inputSchemaKey'
+)
+FROM "governed_export_requests" AS request
+WHERE request."durable_job_id" = artifact."job_id"
+  AND artifact."kind" = 'governed-export'
+  AND artifact."metadata" IS NULL;--> statement-breakpoint
+ALTER TABLE "governed_export_requests" ALTER COLUMN "renderer" SET NOT NULL;