tever
太微网络
TEVER — 数字事件中枢
文档阅读区

06 · App Contract (Manifest + Domain Package) (v0.5)

v0.4 的 App Contract 重点在 "types/views/rules seeds + events/schemas + rulepacks + sources + views"。
v0.5 把 prompts/promptpack 纳入契约，使 App 能作为"数据源插件 + 规则包 + 视图模板 + Prompt 模板"交付。

1. App Bundle 目录结构（v0.5）

tever-app-<appId>/
  app.yaml
  domain/
    types/                   # TypeDefinition seeds（可选：领域实体）
    views/                   # ViewConfig seeds（可选）
    rules/                   # Rule seeds（可选：传统 RuleEntity）
    events/
      schemas/               # JSON Schema（必需）
      samples/               # 示例事件（强烈建议）
    rulepacks/               # RulePack（可选但推荐）
    sources/                 # EventSource 模板（可选：给 UI 一键创建）
    prompts/                 # v0.5 新增：PromptPack（可选但推荐）
      promptpack.yaml        # PromptPack 文件
      templates/             # 可选：单独的 Prompt 模板文件
  backend/                   # 可选：action/tool provider
  frontend/                  # 可选：独立 UI
  README.md

2. app.yaml（Manifest）规范（v0.5）

appId: project-mngt
name: Project Management
version: 0.2.0
requiredCoreVersion: ">=0.5.0,<0.6.0"

capabilities:
  providesEventSchemas: true
  providesRulePacks: true
  providesSourceTemplates: true
  providesViewTemplates: true
  providesPromptPack: true        # v0.5 新增
  providesActionProvider: false
  providesToolProvider: false

entrypoints:
  actionProvider:
    type: http
    baseUrl: "http://project-mngt:8080"
  toolProvider:
    type: http
    baseUrl: "http://project-mngt:8080"

install:
  domain:
    types: ["domain/types/*.yaml"]
    views: ["domain/views/*.yaml"]
    rules: ["domain/rules/*.yaml"]
    eventSchemas: ["domain/events/schemas/*.json"]
    rulePacks: ["domain/rulepacks/*.json"]
    sourceTemplates: ["domain/sources/*.json"]
    promptPacks: ["domain/prompts/promptpack.yaml"]  # v0.5 新增

security:
  eventTypeNamespace: "project-mngt."
  schemaIdNamespace: "schema://project-mngt/"
  signedEvents:
    required: false
    acceptedAlgs: ["HS256","Ed25519"]

configSchema:
  defaultNotifyEmail:
    type: string
    default: ""

2.1 约束（v0.5 更新）

  • requiredCoreVersion 必填（安装/升级兼容检查）
    • v0.5 App 应设置为 ">=0.5.0,<0.6.0"
  • eventSchemas 必填（除非是"纯 UI App"）
  • promptPacks 可选（如果 App 需要 AI 功能）
  • seeds 必须幂等（同 id 覆盖或跳过）
  • eventType 必须使用命名空间（防冲突）

3. Event Schemas（必需，v0.4 已有）

v0.4 已定义，v0.5 保持不变。

3.1 schemaRef 约定

  • schema://<appId>/<eventType>@<version>
  • 版本建议：SemVer（例如 1.0.0）

4. RulePack（推荐，v0.4 已有，v0.5 扩展）

v0.4 已定义，v0.5 扩展支持 AI Actions。

4.1 v0.4 已有能力

  • 用于交付"可直接启用"的 filter/aggregate/alert/action 规则集合
  • Core 安装 App 时，把 RulePack 导入为规则

4.2 v0.5 新增：AI Actions

RulePack 示例（包含 AI Action）：

{
  "id": "project-mngt.rulepack.v2",
  "version": "2.0.0",
  "rules": [
    {
      "id": "project-mngt.ai_task_decomposition",
      "name": "AI 任务分解",
      "enabled": true,
      "trigger": {
        "type": "on_event",
        "eventTypes": ["project_created"]
      },
      "condition": {
        "all": [
          { "path": "data.project_type", "op": "exists" }
        ]
      },
      "action": {
        "type": "invoke_llm_generate_doc",
        "prompt_template": "project-mngt.task_decomposition@1.0.0",
        "context_refs": {
          "entityIds": ["{{entity_id}}"]
        },
        "variables": {
          "project_name": "{{data.name}}",
          "project_type": "{{data.project_type}}"
        },
        "target_type": "document_draft"
      }
    }
  ]
}

5. PromptPack（v0.5 新增）

5.1 PromptPack 格式

文件: apps/{app_id}/prompts/promptpack.yaml

格式：

promptpack:
  id: project-mngt.promptpack.v1
  name: Project Management Prompts
  version: 1.0.0
  app_id: project-mngt
  prompts:
    - id: project-mngt.task_decomposition@1.0.0
      name: 任务分解
      template: |
        你是一个项目管理专家，请根据以下信息生成项目任务列表：
        
        项目信息：
        - 项目名称: {{project_name}}
        - 项目类型: {{project_type}}
        
        请生成详细的任务列表...
      variables:
        - project_name
        - project_type
      output_schema:
        type: object
        properties:
          tasks:
            type: array
            items:
              type: object
              properties:
                title:
                  type: string
                priority:
                  type: string
                  enum: [low, normal, high]
        required: [tasks]
    - id: project-mngt.meeting_minutes@1.0.0
      name: 会议纪要生成
      template: |
        你是一个会议记录专家...
      variables:
        - meeting_title
        - agenda
      output_schema:
        type: object
        properties:
          content:
            type: string
          action_items:
            type: array
        required: [content]

5.2 PromptPack 安装

安装流程：

  1. App 安装时检测 prompts/promptpack.yaml
  2. 解析 PromptPack
  3. 验证 Prompt 模板格式
  4. 注册 Prompt 模板到 Prompt Registry
  5. 处理版本冲突（如果已存在，比较版本号）

版本冲突处理：

  • 如果版本号相同，跳过（不覆盖）
  • 如果版本号更高，更新
  • 如果版本号更低，跳过（不降级）

6. Source Templates（可选但强烈建议，v0.4 已有）

v0.4 已定义，v0.5 保持不变。

  • 用 JSON 提供一个可一键创建 EventSource 的模板（给 UI 用）
  • 例如：
    • push：需要 token、allowedTypes、schemaRef 列表
    • pull：需要 endpoint、credentialsRef、pollInterval

7. Views Templates（强烈建议，v0.4 已有，v0.5 扩展）

v0.4 已定义，v0.5 扩展支持 AI 洞察展示。

7.1 ViewConfig 建议字段（v0.4 已定义）

  • id：唯一
  • kind：dashboard | workbench | list | detail
  • bindings：绑定 Core Query API（events/alerts/aggregates/audits/search）
  • widgets：table/timeseries/stat/log/alert-list/audit-trace 等
  • permissions：view 级别权限（RBAC）

7.2 v0.5 新增：AI 洞察绑定

ViewConfig 示例（包含 AI 洞察）：

{
  "id": "os-assistant.alert_detail",
  "kind": "detail",
  "name": "告警详情",
  "bindings": [
    {
      "name": "alert",
      "query": "alerts",
      "params": { "id": "{{alert_id}}" }
    },
    {
      "name": "aiInsight",
      "query": "ai_insights",
      "params": { "related_entity_ids": ["{{alert_id}}"] }
    }
  ],
  "widgets": [
    { "type": "alert-detail", "title": "告警信息", "binding": "alert" },
    { "type": "ai-insight", "title": "AI 分析", "binding": "aiInsight" }
  ]
}

7.3 约束（v0.4 已有）

  • App 前端 不允许直连 ES/Kafka/DB；必须通过 Core Query API
  • View 只描述"怎么查 + 怎么画"，不包含业务执行逻辑

8. 扩展点（Action/Tool）（v0.4 已有，v0.5 扩展）

8.1 Action Provider（HTTP，v0.4 已有）

  • POST {baseUrl}/actions/execute
  • Core 在调用前：权限校验 + 写 action_requested 审计记录
  • 执行结果：Core 写 action_succeeded/action_failed

8.2 Tool Provider（HTTP，v0.4 已有）

  • POST {baseUrl}/tools/{toolName}
  • 仍要求：tool_call 审计实体 + tool_* 事件

8.3 AI Actions（v0.5 新增，只读）

  • 不在 App 中实现，而是由 Core 的 Action Executor 直接调用 LLM Gateway
  • App 只需在 RulePack 中定义 AI Action，使用 Prompt 模板
  • Core 负责执行、校验、写入草稿、记录审计

文档版本: v1.0
最后更新: 2025-12-17