create-windy 0.2.19 → 0.2.21

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

@@ -0,0 +1,744 @@
+# Southwind AI Runtime 架构
+
+更新时间：2026-07-25。
+
+状态：架构已确认，首个可消费的文本 Agent 切片已实现。当前包含 Module AI Operation
+注册、Guarded Run facade、短时 Execution Grant、受限 Tool Host、OpenAI-compatible
+Provider、canonical HTTP/SSE、取消、cursor 重放和单副本有界 SQLite Store。未配置
+Provider 时仍安全拒绝。ADK Workflow、LiteLLM 多 Provider 路由、PostgreSQL 多副本
+Store、Document AI 和 Speech 运行进程尚未实现，不能据此宣称完整 AI Runtime 已交付。
+
+## 目标
+
+Southwind AI 为生成项目提供可选的 AI Runtime。它统一治理模型 Deployment、业务 Operation、Feature Flag、RBAC Permission、License、Audit、Secret、用量和离线部署，但不自行重做通用 Agent Framework、LLM Router、OCR 引擎或语音模型。
+
+首期目标：
+
+- 使用 Google ADK 承载 Agent、Workflow、Session、Eval 和开发调试；
+- 使用自托管 LiteLLM Proxy 管理多个 LLM/VLM Provider；
+- 支持 DeepSeek、GLM、Kimi、Qwen 及本地或内网 OpenAI-compatible 模型；
+- 支持文本 LLM/VLM 的 canonical SSE 流式传输；
+- 支持本地或云端 OCR、文档解析、ASR、TTS 和 AI Dictation；
+- 支持完全离线、内网私有化和受控公网三种部署环境；
+- 业务 Module 只依赖稳定 Operation，不依赖 ADK、LiteLLM、模型名或 Provider SDK。
+
+首期不包含腾讯混元。未列出的 Provider 通过 Deployment Registry 和 Adapter 扩展，不扩充业务 Interface。
+
+## 核心决策
+
+1. Agent Runtime 是 Southwind AI 的官方可选底座能力，不是每个业务 Module 自行实现的功能。
+2. Agent Server 独立部署，首期使用 Python ADK；ADK 只属于内部 Implementation。
+3. 首个文本切片由 Agent Server 内置 OpenAI-compatible Adapter；需要多 Provider
+   路由、fallback 与集中限流时，再引入独立自托管 LiteLLM Proxy。
+4. OCR 和文档解析由独立 Document AI Server 执行，不放入 Agent Server 或 LiteLLM。
+5. ASR、TTS 和 AI Dictation 由独立 Speech Server 执行；实时 Agent 会话由 Agent Server 编排。
+6. 文本 LLM、VLM 和 Agent 输出使用 SSE；实时音频/视频需要双向传输，使用 WebSocket。
+7. Southwind AI Server 是身份、Feature、Permission、License、数据范围、Tool 授权和 Audit 的事实源。
+8. 所有业务文件通过 `ArtifactRef` 传递，不在跨服务 DTO 中携带大型 Base64 文件或本地绝对路径。
+
+## 总体拓扑
+
+```text
+业务 Module / Web
+        │
+        │ AgentOperation / DocumentOperation / SpeechOperation
+        ▼
+Southwind AI Server
+        ├── Feature / RBAC / License / Audit / Data Scope
+        ├── AI Deployment Registry
+        ├── Agent Tool Host
+        └── 短时 Execution Grant
+              │
+              ├── Agent Server（Python + ADK）
+              │       ├── Prompt / Workflow / Session / Eval
+              │       └── canonical SSE / Live WebSocket
+              │                │
+              │                ▼
+              │          LiteLLM Proxy
+              │                ├── DeepSeek / GLM / Kimi / Qwen
+              │                └── vLLM / Ollama / OpenAI-compatible
+              │
+              ├── Document AI Server
+              │       ├── PaddleOCR
+              │       ├── Unlimited OCR
+              │       └── 云端或内网 OCR Adapter
+              │
+              └── Speech Server
+                      ├── ASR / TTS
+                      ├── AI Dictation
+                      └── 本地、内网或云端 Speech Adapter
+```
+
+这些运行进程可以由同一套离线介质和 Compose profile 交付，但保持独立故障域和资源生命周期。未安装某个可选运行进程时，只将对应 Operation 标记为 unavailable，不阻止普通非 AI 功能启动。
+
+## Module 与部署职责
+
+### Southwind AI Server
+
+拥有：
+
+- Module Manifest 中的 AI Operation 和 Tool 声明；
+- Feature、Permission、License 和数据范围 Guard；
+- Execution Grant 签发；
+- Agent Tool 的 schema 校验、二次授权、人工审批和幂等执行；
+- AI Deployment、Route Policy 和 Secret Reference 的 Admin 控制面；
+- 面向业务的稳定错误和审计语义；
+- Run 与业务资源、Job、Artifact、Audit 的关联；
+- 各运行进程的健康状态和 capability digest 校验。
+
+不拥有：
+
+- ADK Session 或 Workflow 实现；
+- Provider API Key 明文；
+- LiteLLM 路由内部状态；
+- OCR、ASR、TTS 模型进程；
+- Agent Server、Document AI Server 或 Speech Server 的 Repository。
+
+### Agent Server
+
+拥有：
+
+- ADK Runner、Workflow、Session、Checkpoint、Eval；
+- Agent、Workflow 和 Prompt Release；
+- Run 生命周期、取消、恢复和 canonical event；
+- ADK Event 到 Southwind AI Event 的转换；
+- Agent Step、Prompt Version、Tool Call 和模型 attempt 的关联；
+- 开发环境 ADK Web；
+- 实时 Agent 会话编排。
+
+Agent Server 不直接访问业务 Repository。模型产生 Tool Call 只表示执行意图；每次真实 Tool 执行都必须回到 Southwind AI Tool Host，重新检查当前 Feature、License、Permission 和数据范围。
+
+### LiteLLM Proxy
+
+拥有：
+
+- Provider、Deployment 和模型凭据；
+- route alias 到实际模型的映射；
+- health、负载均衡、retry、cooldown、fallback 和限流；
+- Provider 原始 token、cost 和错误；
+- 公网、本地和内网模型 Endpoint。
+
+Agent Server 只使用稳定 route alias，例如：
+
+```text
+agent.fast
+agent.reasoning
+agent.long-context
+agent.structured
+agent.vision
+speech.dictation.polish
+```
+
+ADK 和 LiteLLM 不同时维护两套路由或 fallback。ADK 决定运行哪个 Agent 或 Step，LiteLLM 决定该 Step 落到哪个模型 Deployment。
+
+### Document AI Server
+
+拥有：
+
+- OCR、版面分析、表格识别和长文档解析 Adapter；
+- 文档处理 Run、页级进度和结果 Artifact；
+- PaddleOCR、Unlimited OCR、本地/内网/云端 OCR 的能力归一化；
+- 页数、图像、像素、处理时长和 GPU 时间等用量事实。
+
+即使底层 Unlimited OCR 或其他 OCR 使用视觉语言模型，业务 Interface 仍是 Document Operation，不暴露 Chat Completion。
+
+### Speech Server
+
+拥有：
+
+- 批量和实时 ASR；
+- 流式和非流式 TTS；
+- VAD、音频格式转换、稳定片段判定；
+- AI Dictation 的 ASR 与 LLM 润色编排；
+- 音频秒数、字符数、实时连接和 GPU 时间等用量事实。
+
+纯转写和 AI Dictation 不依赖 Agent Server。只有包含 Agent Session、Tool Calling 或多轮任务执行的实时对话才进入 Agent Server。
+
+## 对业务公开的深 Module
+
+首期只提供一个公开 npm Module：
+
+```text
+@southwind-ai/ai-client
+├─ @southwind-ai/ai-client/agent
+└─ @southwind-ai/ai-client/contracts
+```
+
+普通业务从根入口调用 Agent；需要精确依赖边界的基础设施可使用子路径。Document 与
+Speech 的 Interface 等出现真实调用能力时，再在同一 package 内增加 `./document` 与
+`./speech` 子路径，不提前发布空壳。
+
+npm Module 数量与部署进程数量是两个不同维度。Southwind Server、Agent Server、
+Document AI Server 和 Speech Server 仍独立部署：它们具有不同的协议、资源和故障域；
+业务侧则只学习一个稳定入口。`ai-client` 内部通过 Agent、Document、Speech Adapter
+隔离远端 Implementation，不能把 ADK、LiteLLM、PaddleOCR 或 Provider SDK 类型暴露给业务。
+
+### Agent Interface
+
+```ts
+interface AgentCaller {
+  start<Input, Output>(
+    operation: AgentOperation<Input, Output>,
+    input: Input,
+    options: {
+      idempotencyKey: string;
+      signal?: AbortSignal;
+    },
+  ): Promise<AgentRun<Output>>;
+}
+
+interface AgentRun<Output> {
+  readonly id: string;
+  readonly events: AsyncIterable<AgentEvent>;
+  result(): Promise<Output>;
+  cancel(reason?: string): Promise<void>;
+}
+```
+
+业务只知道 Operation Key、类型化输入输出、幂等键、canonical event 和终态结果，不知道 Provider、模型名、Prompt 明文、ADK Agent 或 LiteLLM 参数。
+
+### Document Interface
+
+```ts
+interface DocumentAiClient {
+  submit(
+    operation: DocumentOperation,
+    input: {
+      source: ArtifactRef;
+      options?: DocumentProcessingOptions;
+    },
+    context: {
+      idempotencyKey: string;
+      signal?: AbortSignal;
+    },
+  ): Promise<DocumentRun>;
+}
+```
+
+输出可以引用纯文本、Markdown、搜索型 PDF、页级文本、坐标、表格、版面树或结构化 JSON Artifact。
+
+### Speech Interface
+
+```ts
+interface SpeechClient {
+  transcribe(
+    source: ArtifactRef,
+    options?: TranscriptionOptions,
+  ): Promise<TranscriptionRun>;
+
+  openTranscriptionStream(
+    options: TranscriptionStreamOptions,
+  ): Promise<TranscriptionStream>;
+
+  openDictation(options: DictationOptions): Promise<DictationStream>;
+
+  synthesize(input: SpeechSynthesisInput): Promise<SpeechSynthesisRun>;
+}
+```
+
+## Module Manifest
+
+每个面向业务的 AI Operation 必须在所属 Module Manifest 中声明：
+
+- 稳定 Operation Key；
+- Feature Key；
+- Permission Key；
+- Audit Action；
+- 输入和输出 schema；
+- 允许使用的 Tool Key；
+- 数据分类；
+- 所需模型 capability；
+- 交互方式：interactive、streaming、background 或 live；
+- 最大运行时间、输入大小和输出大小；
+- 是否允许向公网 Provider 发送数据。
+
+示例：
+
+```ts
+interface ModuleAiOperationDefinition {
+  key: string;
+  kind: "agent" | "document" | "speech";
+  featureKey: string;
+  permissionKey: string;
+  auditAction: string;
+  inputSchemaKey: string;
+  outputSchemaKey: string;
+  requiredCapabilities: readonly string[];
+  allowedToolKeys: readonly string[];
+  dataClassification: "public" | "internal" | "sensitive";
+  execution: "interactive" | "streaming" | "background" | "live";
+}
+```
+
+真实 Operation Handler 与 Manifest 声明必须一一对应。重复、缺失、未知引用、命名空间不匹配和 capability digest 漂移都应在监听前 fail-fast。
+
+## AI Deployment Registry
+
+Deployment 描述一个可调用的模型部署，不把能力写死为封闭 Provider 枚举：
+
+```ts
+interface AiDeploymentDefinition {
+  key: string;
+  protocol:
+    | "openai-chat"
+    | "openai-realtime"
+    | "gemini-live"
+    | "whisper-compatible"
+    | "ollama"
+    | "paddle-ocr"
+    | "custom-http";
+  endpoint: string;
+  credentialRef?: string;
+  upstreamModel?: string;
+  inputModalities: readonly (
+    "text" | "image" | "audio" | "video" | "document"
+  )[];
+  outputModalities: readonly ("text" | "audio" | "embedding" | "document")[];
+  capabilities: readonly string[];
+  networkScope: "public" | "intranet" | "localhost";
+}
+```
+
+本地和内网 Endpoint 必须支持：
+
+- HTTP 或 HTTPS；
+- IPv4、内网 DNS 和容器服务名；
+- 自定义端口和 Base Path；
+- 可选 API Key；
+- 私有 CA；
+- connect timeout、request timeout 和并发上限。
+
+Admin 控制面可以分开输入协议、主机、端口和 Base Path，但持久化前归一化为合法 `endpoint`。业务调用不能临时覆盖 Endpoint。
+
+Endpoint 配置属于高风险管理动作，必须具备独立 Permission 和关键审计。出站请求应支持域名或 CIDR allowlist，并禁止访问云 metadata 等保留地址，避免形成 SSRF 通道。
+
+## LLM、VLM 与 Agent SSE 协议
+
+### 适用范围
+
+以下文本或结构化输出统一使用 SSE：
+
+- 普通 LLM Generation；
+- Agent Run；
+- VLM 图片/视频输入后的文本输出；
+- Tool 状态、审批状态、usage 和终态事件；
+- 需要断线恢复的交互式文本 Run。
+
+SSE 是单向 Server-to-Client 协议。创建、取消、审批、恢复和 Tool continuation 使用独立 HTTP command，不在 SSE 连接中反向发送。
+
+Southwind AI Server 与 Agent Server 之间使用本节定义的 canonical SSE；Agent Server 调用 LiteLLM 的文本 LLM/VLM 时使用 OpenAI-compatible SSE streaming。Provider 专有流协议在 LiteLLM Adapter 内终止，不能越过该 Seam。VLM 的图片或视频作为请求 Artifact 发送，模型的文本与结构化响应仍通过 SSE 返回。
+
+实时语音和视频需要客户端与服务端同时发送媒体帧，因此使用 WebSocket，不属于本节 SSE 约束。
+
+### 两阶段调用
+
+先创建可持久化 Run：
+
+```http
+POST /api/agent/runs
+Content-Type: application/json
+Idempotency-Key: request-123
+```
+
+响应：
+
+```json
+{
+  "runId": "run_123",
+  "status": "accepted",
+  "eventsUrl": "/api/agent/runs/run_123/events"
+}
+```
+
+再建立 SSE：
+
+```http
+GET /api/agent/runs/run_123/events
+Accept: text/event-stream
+Last-Event-ID: 42
+```
+
+响应至少包含：
+
+```http
+Content-Type: text/event-stream; charset=utf-8
+Cache-Control: no-cache, no-transform
+X-Accel-Buffering: no
+```
+
+取消使用独立 command：
+
+```http
+POST /api/agent/runs/run_123/cancel
+Content-Type: application/json
+```
+
+收到 `run.completed` 后，客户端读取并按 Operation 的输出 parser 校验最终结果：
+
+```http
+GET /api/agent/runs/run_123/result
+Accept: application/json
+```
+
+```json
+{
+  "runId": "run_123",
+  "status": "completed",
+  "output": {}
+}
+```
+
+两阶段调用允许页面刷新、网络重连和后台 Run 继续执行，不要求重新发起模型调用。
+
+### Event 格式
+
+每条事件包含 SSE `id`、稳定 `event` 名称和单行 JSON `data`：
+
+```text
+id: 43
+event: output.delta
+data: {"runId":"run_123","sequence":43,"text":"你好"}
+
+```
+
+canonical event：
+
+```ts
+type AgentEvent =
+  | { type: "run.started"; runId: string; sequence: number }
+  | { type: "output.delta"; runId: string; sequence: number; text: string }
+  | {
+      type: "tool.requested";
+      runId: string;
+      sequence: number;
+      toolCallId: string;
+      toolKey: string;
+    }
+  | {
+      type: "approval.required";
+      runId: string;
+      sequence: number;
+      workItemId: string;
+    }
+  | {
+      type: "tool.completed";
+      runId: string;
+      sequence: number;
+      toolCallId: string;
+    }
+  | {
+      type: "usage.reported";
+      runId: string;
+      sequence: number;
+      usage: AgentUsage;
+    }
+  | { type: "run.completed"; runId: string; sequence: number }
+  | {
+      type: "run.failed";
+      runId: string;
+      sequence: number;
+      error: AgentError;
+    }
+  | { type: "run.cancelled"; runId: string; sequence: number };
+```
+
+ADK Event、LiteLLM chunk、OpenAI response event、Provider reasoning delta 和 partial JSON 不直接向业务透传。
+
+### SSE 不变量
+
+- `sequence` 在单个 Run 内严格单调递增；
+- SSE `id` 使用可恢复的 event cursor，不使用 token 文本或 Provider event ID；
+- `Last-Event-ID` 和显式 `after` cursor 都能恢复，服务端采用 at-least-once 投递，客户端按 event ID 去重；
+- 每个 Run 恰好一个 terminal event：completed、failed 或 cancelled；
+- terminal event 之后不再发送业务事件；
+- 首个用户可见 `output.delta` 或 Tool 请求之后，不允许静默切换模型并拼接新答案；
+- fallback 只能发生在当前模型 Step 尚未产生用户可见输出和副作用之前；
+- Tool 参数完整聚合并通过 schema、Guard 和审批后才执行；
+- 断开 SSE 不等于取消 Run，取消必须调用 command；
+- Server 使用有界 buffer；慢消费者通过事件存储重放，不能无限占用内存；
+- 代理层必须关闭响应缓冲，并周期发送 SSE comment heartbeat；
+- Provider 原始错误、Prompt、Secret、Endpoint 和响应正文不能进入普通错误事件。
+
+### 稳定错误
+
+业务可见错误至少包括：
+
+```text
+OPERATION_NOT_FOUND
+OPERATION_DISABLED
+INVALID_INPUT
+FORBIDDEN
+LICENSE_NOT_ALLOWED
+RUNTIME_UNAVAILABLE
+MODEL_ROUTE_UNAVAILABLE
+PROVIDER_UNAVAILABLE
+RATE_LIMITED
+BUDGET_EXCEEDED
+TOOL_DENIED
+APPROVAL_REQUIRED
+OUTPUT_VALIDATION_FAILED
+RUN_CONFLICT
+RUN_TIMEOUT
+RUN_CANCELLED
+STREAM_INTERRUPTED
+```
+
+错误携带 `requestId`、稳定 code、可重试标记和安全中文说明，不透传 Provider HTTP body。
+
+## VLM 与多模态
+
+文本加图片或视频输入、文本或结构化输出的 VLM 继续通过 LiteLLM 和 Agent Server：
+
+```text
+agent.vision
+  → private.qwen-vl
+  → approved.cloud-vlm
+```
+
+输入使用有权限的 `ArtifactRef`。业务不能提交任意公网媒体 URL；Adapter 应从 Object Storage 读取或生成受限、短时的内部访问地址。
+
+同一个底层 VLM Endpoint 可以服务不同 Operation：
+
+```text
+agent.vision.inspect
+document.parse.multimodal
+```
+
+前者遵循 LLM/VLM SSE Interface，后者遵循 Document Run Interface。底层模型类型不能替代业务能力语义。
+
+## Document AI
+
+首期支持：
+
+- PaddleOCR；
+- Unlimited OCR；
+- 可配置地址、端口和凭据的本地或内网 OCR Server；
+- 经数据策略允许的云 OCR Adapter。
+
+建议 Operation：
+
+```text
+document.ocr.fast
+document.ocr.accurate
+document.parse.long
+document.parse.layout
+document.extract.table
+document.extract.handwriting
+```
+
+长文档采用异步 Run。输入和结果通过 `ArtifactRef` 关联，页级进度可以使用状态查询或独立 SSE；文档内容本身不以 token delta 形式传输。
+
+路由考虑文档类型、页数、文件大小、语言、表格/版面需求、GPU、数据分类、成本和时限。敏感文档默认只允许 localhost 或 intranet Deployment，除非 Operation 明确允许出网。
+
+## Speech 与 AI Dictation
+
+### 原始能力
+
+Speech Server 提供：
+
+```text
+speech.transcribe.batch
+speech.transcribe.realtime
+speech.synthesize
+speech.dictation
+```
+
+批量音频使用 `ArtifactRef`，实时音频使用 WebSocket。
+
+### AI Dictation
+
+AI Dictation 不是传统直转 ASR，而是以下复合流程：
+
+```text
+麦克风音频
+  → 降噪 / VAD / 分帧
+  → Streaming ASR
+  → partial 文本
+  → 稳定片段判定
+  → LiteLLM route: speech.dictation.polish
+  → 去水词、去重复、自我纠正、标点和轻量书面化
+  → revision-aware 文本 Patch
+  → 输入框
+```
+
+只把 ASR final、停顿切分或多次不再变化的稳定片段交给 LLM。不能对每个不稳定 partial 反复调用 LLM。
+
+建议使用两阶段润色：
+
+1. 自然停顿后进行低延迟片段润色，只处理水词、重复、标点和明显自我纠正；
+2. 用户结束输入后整理最近窗口或完整 utterance，合并跨片段语义并统一格式。
+
+LLM 必须低温运行，禁止补充原文不存在的事实；数字、金额、人名和日期默认保守处理。低置信度片段应保留或标记，不自行猜测。服务保存可撤销的原始转写引用，旧 revision 不能覆盖用户后续手工编辑。
+
+Dictation WebSocket event：
+
+```ts
+type DictationEvent =
+  | { type: "asr.partial"; segmentId: string; text: string }
+  | {
+      type: "asr.final";
+      segmentId: string;
+      text: string;
+      confidence?: number;
+    }
+  | {
+      type: "rewrite.patch";
+      revision: number;
+      range: { start: number; end: number };
+      text: string;
+      sourceSegmentId: string;
+    }
+  | { type: "dictation.completed"; text: string }
+  | {
+      type: "dictation.warning";
+      code: "LOW_CONFIDENCE" | "CONTEXT_CONFLICT";
+    };
+```
+
+输入目的、有限 surrounding text 和业务词表可以作为受控上下文，例如邮件、工单、搜索或会议记录；不能把整个页面和无关敏感数据默认发送给模型。
+
+### 实时 Agent 对话
+
+实时对话支持两种 Adapter：
+
+- 级联：ASR → ADK Agent/LLM → TTS；
+- 原生双向模型：音频/视频 ⇄ Realtime Model。
+
+客户端先向 Southwind AI Server 创建 Live Session 并通过 Guard，再使用短时、绑定 Session 和 audience 的凭证连接 Agent Server WebSocket。Tool Call 仍回到 Southwind AI Tool Host 二次授权。
+
+首期不新增独立 Realtime Server。连接规模、电话线路、WebRTC 或媒体转码成为真实需求后，再把媒体数据面拆出。
+
+## Prompt、Debug 与 Trace
+
+ADK Web 只在 developer profile 启动，绑定 localhost 或受控开发网络。它不是生产 Prompt 管理或生产 Debug 控制面。
+
+Prompt 和 Workflow 使用：
+
+```text
+draft → published → archived
+```
+
+published version 不可原地修改。每次 Run 固定：
+
+- Operation Version；
+- Workflow Version；
+- Prompt Version；
+- Route Policy Version；
+- Tool Schema Version。
+
+首期优先使用代码或 YAML、Git、Eval 和不可变 Release。只有出现非开发人员在线编辑的真实需求后，再扩展 diff、审批、回滚、fixture、route 对比和发布管理。
+
+生产 Trace 优先输出到客户本地 OTel Collector 与 Jaeger/Tempo。Southwind AI 控制面提供脱敏 Run 摘要和受权限保护的 Trace 入口，不复制 ADK Web。
+
+生产默认不持久化完整 Prompt、响应、音频、图片或 Tool 参数。明文诊断需要专门 Feature、Permission、加密、脱敏、TTL 和访问审计。
+
+## Usage 与成本
+
+用量按 attempt 追加，不覆盖 Run 行上的旧值：
+
+| 能力 | 主要计量                                              |
+| ---- | ----------------------------------------------------- |
+| LLM  | input/output/cache/reasoning token、首 token 延迟     |
+| VLM  | 文本 token、图片数量或图片 token、视频时长            |
+| OCR  | 页数、图片数、像素、处理时长、GPU 时间                |
+| ASR  | 输入音频秒数、实时连接时长、GPU 时间                  |
+| TTS  | 输入字符数、输出音频秒数、GPU 时间                    |
+| Live | Session 时长、输入/输出音频秒数、LLM token、Tool 次数 |
+
+每条事实标记 `provider-reported`、`estimated` 或 `unknown`；缺失不能记为零。成本绑定调用时的价格快照。LiteLLM 保存 Provider/Deployment 原始事实，Agent Server 保存 Run/Step 归属，Document AI 和 Speech Server 保存各自模态事实，Southwind AI 通过共享 invocation ID 汇总展示。
+
+## 安全与授权
+
+- 浏览器和普通业务前端不能直接使用 LiteLLM master key；
+- Southwind AI Server 在发起 Run 前执行 License → Feature → Permission Guard；
+- Remote Runtime 只接受短时、限 audience、限 Operation、绑定 actor、run 和 expiry 的 Execution Grant；
+- Grant 不能携带长期有效的 Permission 列表作为授权事实；
+- Tool 执行、人工批准后的继续和后台重试都重新读取当前授权；
+- Agent Server 不接受浏览器提交的“已批准”布尔值；
+- 写 Tool 使用 `toolCallId` 作为幂等键，并继续执行业务 expected-version 或幂等检查；
+- Secret 只通过 `SecretRef`/`SecretResolver` 在 Adapter 最后时刻解析；
+- Prompt、音频、图片、文档正文、Authorization、Cookie 和 Provider body 不进入普通日志；
+- reasoning 原文和 chain-of-thought 不向业务流出。
+
+## 离线与私有化部署
+
+### 受控公网
+
+客户部署允许通过 egress allowlist 访问 DeepSeek、GLM、Kimi、Qwen 等公网 Provider。
+
+### 内网私有化
+
+LiteLLM、Document AI 和 Speech Server 连接客户内网模型：
+
+```text
+http://10.10.20.15:8000/v1
+http://qwen.internal:9000/v1
+https://speech.internal:8443/api
+```
+
+### 完全隔离
+
+只注册本地或内网 Deployment，例如 vLLM、Ollama、PaddleOCR、Unlimited OCR、本地 ASR/TTS。启动和正常运行不访问公网。
+
+所有模式共同要求：
+
+- 容器镜像固定 digest；
+- Python wheel、模型文件和静态资源随离线介质交付；
+- 禁止启动时下载依赖、模型、Prompt 或价格表；
+- 保留 SBOM、镜像签名验证和版本清单；
+- 各运行进程拥有独立数据库或 schema，禁止跨库直接查询；
+- 数据库迁移有升级、备份和回滚步骤；
+- 完全断网环境执行 deny-egress 验收；
+- Provider 未配置或不可达不能阻止无关业务功能启动。
+
+LiteLLM 版本必须固定并通过供应链审查，客户现场禁止动态安装未验证版本。
+
+## 首期交付切片
+
+当前已完成第 1、2、4 项和第 5 项的受限 Tool Host 基础闭环，并交付可直接连接
+OpenAI-compatible Provider 的文本 Agent Adapter。SQLite Store 提供单副本有界持久化，
+重启后保留终态和 cursor，但不替代后续 PostgreSQL 多副本 Store。ADK unavailable
+Adapter 保留为未配置 Provider 时的 fail-closed fallback。
+
+1. 定义 Agent、Document、Speech Operation 与 Module Manifest 组合校验；
+2. 建立 Python Agent Server、ADK Adapter 和 deterministic test Adapter；
+3. 部署 LiteLLM Proxy，接入 DeepSeek、GLM、Kimi、Qwen 和一个本地 OpenAI-compatible Endpoint；
+4. 完成 Agent Run 创建、canonical SSE、断线恢复、取消和稳定错误；
+5. 接入一个真实 Agent Tool，验证 Feature、Permission、License、数据范围和 Audit；
+6. 建立 Prompt/Workflow immutable Release、PostgreSQL Session、usage 和 OTel trace；
+7. 建立 Document AI Server，先接 PaddleOCR 和一个本地/内网 Adapter；
+8. 建立 Speech Server，先完成 Streaming ASR 和 AI Dictation；
+9. 增加 VLM Artifact 输入和 `agent.vision` route；
+10. 验证受控公网、内网私有化和完全断网三种 profile。
+
+首期不同时实现 LangGraph Adapter、完整在线 Visual Builder、生产 ADK Web、腾讯混元或通用 GPU 调度平台。
+
+## 验收标准
+
+- 业务代码不导入 ADK、LiteLLM 或 Provider SDK；
+- 业务不传 Provider、模型名、Endpoint 或 API Key；
+- 文本 LLM、VLM 和 Agent 输出统一通过 canonical SSE；
+- SSE 断线后使用 cursor 恢复，不重新执行模型调用；
+- Feature、Permission、License 任一拒绝都会 fail-closed；
+- 模型 Tool Call 不能绕过 Southwind AI Tool Host；
+- 同一 Run 能关联 Audit、ADK Trace、LiteLLM attempt 和 Usage；
+- 本地/内网模型可配置协议、主机、端口和 Base Path；
+- 完全断网环境仍可运行已配置的本地 LLM、OCR 和 Speech Operation；
+- ADK Web 不出现在生产 profile；
+- 非 AI 业务在任一可选 AI Runtime 不可用时仍可运行。
+
+## 相关文档与资料
+
+- [平台基础设施](./foundation-infrastructure.md)
+- [Module Manifest 组合契约](./module-manifest-composition.md)
+- [模块初始化 Host](./module-host.md)
+- [Agent Tool 注册与执行](../platform/agent-tools.md)
+- [Agent Runtime 接入与运行](../platform/agent-runtime.md)
+- [通用文件与对象存储](./object-storage.md)
+- [运行时可观测性](../operations/observability.md)
+- [ADK Web](https://adk.dev/runtime/web-interface/)
+- [ADK Streaming](https://adk.dev/streaming/)
+- [ADK Audio、Image 与 Video](https://adk.dev/streaming/dev-guide/part5/)
+- [LiteLLM](https://docs.litellm.ai/)
+- [PaddleOCR Serving](https://www.paddleocr.ai/main/en/version3.x/inference_deployment/serving/serving.html)
+- [Unlimited OCR](https://github.com/baidu/Unlimited-OCR)