Add ZOS protocol improvement plan document

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

docs/analysis/11-zos-protocol-improvement-plan.md

@@ -0,0 +1,202 @@
+# ZOS 协议改进方案：面向 AI 生成与运行的元数据应用
+
+> **生成日期**: 2026-02-11  
+> **评估范围**: `packages/spec/src/{data,ui,api,system,automation,ai,security,integration,kernel,contracts,hub,studio}`  
+> **评估视角**: 元数据应用开发 + 运行治理 + AI 生成/维护
+
+---
+
+## 1. 评估方法与核心目标
+
+### 1.1 评估方法
+
+面向“元数据驱动应用”的开发与运行闭环，按以下维度评估每个 ZOS 协议域的细节：
+
+1. **AI 生成可用性**: Schema 是否提供足够的语义提示、示例、约束、可自动合成。
+2. **运行可靠性**: 元数据在运行态的可验证性、可观察性、可回滚性。
+3. **跨域一致性**: 数据、UI、API、自动化、AI、系统、集成之间的语义对齐能力。
+4. **演进治理**: 版本控制、差异分析、变更审计、灰度发布。
+
+### 1.2 总体目标
+
+- **让 AI 能够“生成-验证-发布-运维”全链路自治**。
+- **减少人工在协议层的维护成本**，实现“数据即代码”的可持续迭代。
+- **保证线上运行稳定性**，即使元数据由 AI 自动生成，也能有足够防护。
+
+---
+
+## 2. 跨协议通用改进原则 (必须统一落地)
+
+### 2.1 元数据生命周期闭环
+
+建议在系统协议中建立统一的元数据生命周期模型：
+
+```
+Draft → Validate → Simulate → Publish → Observe → Deprecate → Archive
+```
+
+- **Validate**: Schema 层静态验证 + 语义规则验证。
+- **Simulate**: 在沙箱中运行生成 UI/API/Automation 的模拟。
+- **Publish**: 可回滚、可版本化的发布。
+- **Observe**: 运行中的数据质量、性能、权限审计。
+
+### 2.2 AI 生成“最小可解释单元”标准
+
+所有协议对象都应具备以下 AI 生成辅助字段(可选但强烈推荐)：
+
+- `description` / `aiHint`：面向模型的语义描述与偏好提示。
+- `examples`：标准样例输入/输出 (JSON)。
+- `confidence` / `source`：生成置信度与来源 (model/user/template)。
+- `riskLevel`：变更风险等级，驱动发布策略。
+
+### 2.3 协议对齐与跨域映射
+
+建立跨协议“语义锚点”字段，确保 AI 能对齐对象语义：
+
+- `semanticTags`: 业务语义标签 (e.g. `finance`, `customer`, `project`).
+- `capabilityRefs`: 统一能力引用 (可映射到 API/Automation/UI)。
+- `policyRefs`: 权限/合规策略引用。
+
+---
+
+## 3. ZOS 协议域改进方案 (按开发与运行视角)
+
+> 每个协议域均包含：现状价值、AI 生成痛点、改进方案与优先级。
+
+### 3.1 数据协议 (`src/data`)
+
+**现状价值**: 已具备对象、字段、查询、验证、数据源等完整建模能力。  
+**AI 生成痛点**: 语义约束不足、质量规则缺省、字段语义难对齐。
+
+**改进方案**:
+- **P0**: 为 `FieldSchema` 引入 `semanticTags` 与 `examples`，支持 AI 自检。
+- **P0**: 强化 `ValidationSchema` 的“数据质量规则”分层(必选/建议/监控)。
+- **P1**: 增加 `DataLineageSchema`，记录字段来源与计算链路。
+- **P1**: 引入 `IndexPolicy`/`QueryBudget`，指导 AI 自动生成可控查询。
+- **P2**: 提供 `SchemaDiff` 协议，支持元数据变更的增量迁移策略。
+
+### 3.2 UI 协议 (`src/ui`)
+
+**现状价值**: 已覆盖视图、导航、表单、布局、响应式、无障碍等。  
+**AI 生成痛点**: 组件组合规则复杂、默认布局难以保证可用性。
+
+**改进方案**:
+- **P0**: 提供 `LayoutConstraints`，定义 AI 自动布局的硬约束。
+- **P0**: 为表单/列表组件增加 `dataBindingRules`，限制绑定字段类型。
+- **P1**: `DesignTokenHints` 标准化视觉风格参数，避免 AI 生成非一致风格。
+- **P1**: UI 级别增加 `usageExamples` 供模型做布局检索。
+- **P2**: 提供 `UiPreviewSchema` 记录生成时的截图与组件树摘要。
+
+### 3.3 API 协议 (`src/api`)
+
+**现状价值**: REST/GraphQL/Realtime/OData 等协议齐全。  
+**AI 生成痛点**: 缺少端点意图元数据，AI 难做安全调用。
+
+**改进方案**:
+- **P0**: `EndpointSchema` 增加 `intent` 与 `riskLevel` 字段。
+- **P0**: `ContractSchema` 中增加 `inputExamples`/`outputExamples`。
+- **P1**: 标准化 `ErrorTaxonomy`，让 AI 更可靠处理错误。
+- **P1**: 为 Discovery 输出增加 `capabilityMatrix` (可选扩展)。
+- **P2**: 增加 `ApiTestScenario`，支撑 AI 自动验证端点。
+
+### 3.4 系统协议 (`src/system`)
+
+**现状价值**: 具备 manifest、datasource、translation 等基础配置。  
+**AI 生成痛点**: 缺少运行时变更的审批与回滚。
+
+**改进方案**:
+- **P0**: 引入 `ReleasePolicySchema`，支持灰度发布与自动回滚。
+- **P0**: 增强 `ManifestSchema` 的环境分层 (dev/staging/prod)。
+- **P1**: 增加 `SecretsRefSchema`，用于安全引用外部密钥。
+- **P1**: `TranslationSchema` 增加 `autoTranslate` 与 `fallbackRules`。
+- **P2**: 增加 `SystemHealthProfile`，指导运行治理。
+
+### 3.5 自动化协议 (`src/automation`)
+
+**现状价值**: Flow/Workflow/Trigger 已覆盖多类型自动化。  
+**AI 生成痛点**: 容易产生无限循环、隐性副作用。
+
+**改进方案**:
+- **P0**: 在 Trigger/Flow 增加 `idempotencyKey` 与 `loopGuard`。
+- **P0**: 为流程增加 `runtimeBudget` (时间/资源上限)。
+- **P1**: 增加 `FlowSimulationSchema` (输入/输出/副作用预览)。
+- **P1**: 引入 `ApprovalPolicy` 保障关键流程发布门槛。
+- **P2**: 支持 `FlowTestCase` 自动化测试。
+
+### 3.6 AI 协议 (`src/ai`)
+
+**现状价值**: Agent、RAG、模型路由等已齐全。  
+**AI 生成痛点**: 缺少对模型输出的长期治理与可审计性。
+
+**改进方案**:
+- **P0**: `AgentSchema` 增加 `outputContractRef` 与 `safetyPolicyRef`。
+- **P0**: `ModelRegistry` 增加 `costProfile` 与 `latencySLO`。
+- **P1**: 为 RAG 引入 `dataFreshnessPolicy`，避免过期知识。
+- **P1**: 增加 `PromptVersionSchema` + `EvaluationSuite`。
+- **P2**: 引入 `ModelFallbackStrategy`，处理不可用或超时场景。
+
+### 3.7 安全协议 (`src/security` + 权限域)
+
+**现状价值**: 已有 RLS、权限策略、审计字段。  
+**AI 生成痛点**: 自动生成元数据容易触碰合规与隐私边界。
+
+**改进方案**:
+- **P0**: 统一 `DataClassificationSchema` (PII/PHI/财务级别)。
+- **P0**: 引入 `PolicyAsCodeSchema`，使 AI 可读、可执行。
+- **P1**: 增加 `AuditSamplingPolicy`，平衡性能与审计。
+- **P1**: 为关键对象增加 `ChangeApproval` 机制。
+- **P2**: 安全基线模板 (industry presets)。
+
+### 3.8 集成协议 (`src/integration`)
+
+**现状价值**: 具备连接器、认证、映射与健康检查。  
+**AI 生成痛点**: 缺少对外部系统的稳定性约束与可追踪性。
+
+**改进方案**:
+- **P0**: 增加 `ConnectorSLO` (超时/重试/熔断) 统一规范。
+- **P1**: 引入 `MappingVersionSchema`，支持映射回滚。
+- **P1**: `WebhookPolicy` 增加签名/重放防护约束。
+- **P2**: `IntegrationPlaybook` 模板化集成方案。
+
+### 3.9 内核运行协议 (`src/kernel` + `src/contracts` + `src/hub`)
+
+**现状价值**: 已覆盖 kernel、contracts、hub 的运行契约。  
+**AI 生成痛点**: 缺少 AI 可理解的运行能力矩阵。
+
+**改进方案**:
+- **P0**: 建立 `RuntimeCapabilityMatrix` (环境支持度、版本、限制)。
+- **P1**: `ContractSchema` 增加 `serviceSLA` 约束。
+- **P1**: `HubEventSchema` 增加 `schemaVersion` 与 `dedupPolicy`。
+- **P2**: 统一 `PluginCompatibilitySchema`，避免插件与内核不匹配。
+
+---
+
+## 4. 具体落地路线图 (12 周滚动)
+
+| 阶段 | 时间 | 目标 | 关键输出 |
+|------|------|------|---------|
+| Phase 1 | 1-4 周 | AI 生成可靠性基础 | P0 改进项落地 (data/ui/api/system/automation/ai/security) |
+| Phase 2 | 5-8 周 | 运行治理与对齐 | P1 改进项落地 + 跨协议语义锚点 |
+| Phase 3 | 9-12 周 | 生态扩展与可运营 | P2 改进项落地 + 自动化测试/模拟 |
+
+---
+
+## 5. 验收指标 (面向 AI 生成与运行)
+
+- **AI 生成成功率** ≥ 95% (生成的协议对象可通过验证)
+- **运行事故率** ≤ 0.5% (由元数据导致的生产故障)
+- **可回滚时间** ≤ 5 分钟 (任意元数据发布)
+- **协议对齐度** ≥ 90% (跨协议语义映射一致)
+- **自动化覆盖** ≥ 80% (自动化测试/模拟场景覆盖率)
+
+---
+
+## 6. 结论
+
+ObjectStack 的 ZOS 协议已经具备世界级完整度，但面向“AI 生成与自治运维”的下一阶段，需要重点补足：
+
+1. **语义可解释性** (AI 能理解协议意图)。
+2. **运行安全护栏** (可回滚、可治理、可审计)。
+3. **跨协议语义对齐** (避免 AI 生成错配)。
+
+本改进方案将协议体系从“定义驱动”升级为“运行治理驱动”，确保未来元数据应用能够在 AI 维护下稳定运行。