feat(agent): 实现 Agent Runtime LLM 配置与消息元数据结构化支持

2026-03-05 18:25:51 +08:00
parent c07d339a5f
commit db158de39c
26 changed files with 1215 additions and 2914 deletions
@@ -0,0 +1,746 @@
+# UserAgentContext & ProfileSettings v1 设计
+
+**Date:** 2026-03-05
+**Status:** Approved
+
+---
+
+## 目标
+
+为 Agent Runtime 提供完整的用户画像上下文，通过 Pydantic 约束 profiles.settings 结构，确保：
+
+1. 运行时入口读取 profile（username/bio/settings）
+2. settings 结构类型安全、版本可演进
+3. 关键配置（语言/时区/国家）符合标准格式
+
+---
+
+## 架构
+
+```
+Profile (DB JSONB)
+    ↓
+ProfileSettings (Pydantic)
+    ↓
+UserAgentContext (DataClass)
+    ↓
+build_global_system_prompt(ctx)
+```
+
+**设计原则：**
+- 唯一入口：`get_user_agent_context(user_id)` 读取并构造上下文
+- 不可变：UserAgentContext 使用 frozen dataclass
+- 向后兼容：version 字段预留未来演进
+
+---
+
+## ProfileSettings v1 结构
+
+```json
+{
+  "version": 1,
+  "preferences": {
+    "interface_language": "zh-CN",
+    "ai_language": "zh-CN",
+    "timezone": "Asia/Shanghai",
+    "country": "CN"
+  },
+  "privacy": {},
+  "notification": {}
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 默认值 | 约束 |
+|------|------|--------|------|
+| `version` | int | 1 | 必须为 1（v1 锁定） |
+| `preferences.interface_language` | str | "zh-CN" | BCP-47 格式 |
+| `preferences.ai_language` | str | "zh-CN" | BCP-47 格式 |
+| `preferences.timezone` | str | "Asia/Shanghai" | IANA 时区 |
+| `preferences.country` | str | "CN" | ISO 3166-1 alpha-2 |
+| `privacy` | dict | {} | 空对象（预留） |
+| `notification` | dict | {} | 空对象（预留） |
+
+### 约束规则
+
+**1. BCP-47 语言格式**
+
+正则：`^[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2})?$`
+
+示例：
+- ✅ zh-CN, en-US, zh-TW, ja-JP
+- ❌ zh_CN, EN, chn
+
+**2. IANA 时区**
+
+使用 `zoneinfo.ZoneInfo` 校验。
+
+示例：
+- ✅ Asia/Shanghai, America/New_York, UTC
+- ❌ CST, GMT+8
+
+**3. ISO 3166-1 alpha-2 国家代码**
+
+使用 `pycountry.countries.get(alpha_2=...)` 校验。
+
+示例：
+- ✅ CN, US, JP, GB
+- ❌ CHN, USA, zz
+
+---
+
+## UserAgentContext 结构
+
+```python
+@dataclass(frozen=True)
+class UserAgentContext:
+    user_id: UUID
+    username: str
+    bio: str | None
+    settings: ProfileSettings
+```
+
+**设计要点：**
+- 不可变（frozen=True）：防止运行时修改
+- 完整画像：包含身份（username/bio）和配置（settings）
+- 唯一构造入口：`get_user_agent_context(user_id)`
+
+---
+
+## Pydantic 模型实现
+
+```python
+from pydantic import BaseModel, Field, field_validator
+from dataclasses import dataclass
+from uuid import UUID
+import re
+
+class PreferenceSettings(BaseModel):
+    interface_language: str = "zh-CN"
+    ai_language: str = "zh-CN"
+    timezone: str = "Asia/Shanghai"
+    country: str = "CN"
+    
+    @field_validator("interface_language", "ai_language")
+    @classmethod
+    def validate_bcp47(cls, v: str) -> str:
+        pattern = r"^[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2})?$"
+        if not re.match(pattern, v):
+            raise ValueError(f"Invalid BCP-47 language tag: {v}")
+        return v
+    
+    @field_validator("timezone")
+    @classmethod
+    def validate_iana_timezone(cls, v: str) -> str:
+        import zoneinfo
+        try:
+            zoneinfo.ZoneInfo(v)
+        except Exception:
+            raise ValueError(f"Invalid IANA timezone: {v}")
+        return v
+    
+    @field_validator("country")
+    @classmethod
+    def validate_iso_country(cls, v: str) -> str:
+        import pycountry
+        if not pycountry.countries.get(alpha_2=v.upper()):
+            raise ValueError(f"Invalid ISO 3166-1 alpha-2 country code: {v}")
+        return v.upper()
+
+class ProfileSettings(BaseModel):
+    version: int = Field(default=1, ge=1, le=1)
+    preferences: PreferenceSettings = Field(default_factory=PreferenceSettings)
+    privacy: dict = Field(default_factory=dict)
+    notification: dict = Field(default_factory=dict)
+
+@dataclass(frozen=True)
+class UserAgentContext:
+    user_id: UUID
+    username: str
+    bio: str | None
+    settings: ProfileSettings
+```
+
+---
+
+## 依赖项
+
+需要添加到 `backend/pyproject.toml`：
+
+```toml
+[project.dependencies]
+pycountry = ">=23.0.0"
+```
+
+---
+
+## 迁移策略
+
+**数据库层：**
+- profiles.settings 保持 JSONB，不做 schema 变更
+- 现有数据默认值：`{"version": 1, "preferences": {"country": "CN"}}`
+
+**应用层：**
+- 读取时：`ProfileSettings.model_validate(profile.settings or {})`
+- 写入时：`profile.settings = settings.model_dump()`
+
+---
+
+## 未来演进
+
+
+**版本迁移：**
+- Pydantic 支持多版本共存
+- 数据库不做破坏性变更
+
+---
+
+---
+
+## AG-UI 事件转发与落库策略
+
+### 核心原则
+
+**1. 事件转发时机：**
+- 只有 organization 阶段完成后转发 AG-UI 事件
+- AG-UI bridge 已实现底层机制，编排层控制转发时机
+
+**2. 落库时机：**
+- 意图识别和任务执行阶段：落库但 seq 取负数（用于审计）
+- 结果反馈阶段：seq 取最新 seq 的绝对值 +1（用于展示）
+
+### Seq 设计细节
+
+**意图识别和任务执行阶段（审计用）：**
+- seq 取负数（如 -1, -2）
+- role: "assistant"（标记为 agent 输出）
+- content: 阶段的完整输出（用于审计/调试）
+- 重建会话时通过 `WHERE seq > 0` 过滤，不展示给用户
+
+**结果反馈阶段（展示用）：**
+- seq 取正数（取最新负数的绝对值 +1）
+- role: "assistant"
+- content: OrganizationResult.assistant_text
+- 重建会话时通过 `WHERE seq > 0` 展示给用户
+
+**示例：**
+```
+| seq  | role     | content                    | 展示 |
+|------|----------|----------------------------|------|
+| -2   | assistant| ExecutionResult (完整)     | 否   |
+| -1   | assistant| IntentResult (完整)        | 否   |
+| 1    | user     | 用户输入                   | 是   |
+| 2    | assistant| OrganizationResult         | 是   |
+```
+
+### 编排层职责
+
+```python
+@listen(intent_stage)
+async def persist_intent(self, state: FlowState) -> FlowState:
+    # seq 取负数
+    seq = await message_repo.get_next_negative_seq(state.session_id)
+    await message_repo.create(
+        session_id=state.session_id,
+        seq=seq,  # 负数
+        role="assistant",
+        content=state.intent_result.model_dump_json(),
+        ...
+    )
+    return state
+
+@listen(execution_stage)
+async def persist_execution(self, state: FlowState) -> FlowState:
+    # seq 取负数
+    seq = await message_repo.get_next_negative_seq(state.session_id)
+    await message_repo.create(
+        session_id=state.session_id,
+        seq=seq,  # 负数
+        role="assistant",
+        content=state.execution_result.model_dump_json(),
+        ...
+    )
+    return state
+
+@listen(organization_stage)
+async def finalize_flow(self, state: FlowState) -> FlowState:
+    result = state.organization_result
+    
+    # seq 取正数（最新负数绝对值+1）
+    seq = await message_repo.get_next_positive_seq(state.session_id)
+    await message_repo.create(
+        session_id=state.session_id,
+        seq=seq,  # 正数
+        role="assistant",
+        content=result.assistant_text,
+        ...
+    )
+    
+    # 触发 AG-UI 事件（由 bridge 处理）
+    return state
+```
+
+### Token 和 Cost 累加
+
+**策略：在内存中累加所有阶段的 token 和 cost，organization 完成后统一落库。**
+
+```python
+@dataclass
+class FlowState:
+    # ...
+    tokens: dict[str, dict] = field(default_factory=dict)
+    cost: Decimal = Decimal("0")
+    currency: str = "CNY"
+```
+
+---
+
+## CrewAI Flow 三阶段设计
+
+### 架构概览
+
+```
+User Input + UserAgentContext
+    ↓
+@start() begin()
+    ↓
+@listen() intent_stage() → 判断 can_answer_directly
+    ↓ (router)
+    ├─ DIRECT_RESPONSE → 直接返回
+    └─ NEEDS_EXECUTION
+           ↓
+       @listen() execution_stage() → 任务执行/工具调用
+           ↓
+       @listen() organization_stage() → 结果组织与表达
+           ↓
+       返回给用户
+```
+
+### 三阶段职责
+
+**1. Intent Recognition（意图识别）**
+- Agent Type: `INTENT_RECOGNITION`
+- 输出结构（最小化设计）：
+  ```python
+  class IntentResult(BaseModel):
+      direct_answer: bool  # 是否可以直接回答
+      intent_analysis: str  # 意图分析文本（用于调试/审计）
+      execution_prompt: str  # 给 execution 阶段的提示词（direct_answer=false时使用）
+      direct_response: str  # 直接回复文本（direct_answer=true时使用）
+  ```
+- 短路逻辑：
+  - `direct_answer=true` → 完全跳过 execution 和 organization，直接返回 direct_response
+  - `direct_answer=false` → 进入 execution 阶段
+- 输出约束：使用 `output_pydantic=IntentResult`
+- **落库策略**：落库到 messages 表，但重建会话时不展示
+
+**2. Task Execution（任务执行）**
+- Agent Type: `TASK_EXECUTION`
+- 输入：IntentResult.execution_prompt + IntentResult.intent_analysis
+- 职责：
+  - 执行复杂任务（查询数据库、调用工具、多步骤推理）
+  - 返回结构化执行结果
+- 输出结构（最小化设计）：
+  ```python
+  class ExecutionResult(BaseModel):
+      execution_summary: str  # 任务执行摘要（用于调试/审计）
+      organization_prompt: str  # 给 organization 阶段的提示词
+      execution_data: dict = {}  # 执行结果的结构化数据
+  ```
+- 输出约束：使用 `output_pydantic=ExecutionResult`
+- **落库策略**：落库到 messages 表，但重建会话时不展示
+
+**3. Result Reporting（结果报告）**
+- Agent Type: `RESULT_REPORTING`
+- 输入：
+  - IntentResult（意图识别结果）
+  - ExecutionResult（任务执行情况）
+- 职责：
+  - 结合意图分析和执行结果，格式化为用户友好的响应
+  - 应用个性化模板（基于 UserAgentContext）
+- 输出结构（最小化设计）：
+  ```python
+  class OrganizationResult(BaseModel):
+      assistant_text: str  # 最终回复文本
+      response_metadata: dict = {}  # 响应元数据（可选）
+  ```
+- 输出约束：使用 `output_pydantic=OrganizationResult`
+- **唯一展示阶段**：重建会话时只展示此阶段的 message
+- **唯一转发阶段**：只有此阶段的输出需要通过 AG-UI 事件转发
+
+### Flow 状态管理
+
+```python
+@dataclass
+class FlowState:
+    user_input: str
+    context: UserAgentContext
+    stage_trace: list[str] = field(default_factory=list)
+    intent_result: IntentResult | None = None
+    execution_result: ExecutionResult | None = None
+    organization_result: OrganizationResult | None = None
+    assistant_text: str = ""
+    tokens: dict = field(default_factory=dict)
+    cost: Decimal = Decimal("0")
+```
+
+### 数据流向
+
+```
+User Input + UserAgentContext
+    ↓
+@start() begin()
+    ↓
+@listen() intent_stage()
+    ├─ IntentResult.direct_answer=true
+    │    ↓
+    │  跳过 execution，直接 organization
+    │    ↓
+    │  organization_stage(IntentResult.next_stage_prompt, IntentResult.metadata)
+    │    ↓
+    │  OrganizationResult → AG-UI 事件 + 落库
+    │
+    └─ IntentResult.direct_answer=false
+         ↓
+       execution_stage(IntentResult.next_stage_prompt, IntentResult.metadata)
+         ↓
+       ExecutionResult
+         ↓
+       organization_stage(ExecutionResult.next_stage_prompt, ExecutionResult.metadata)
+         ↓
+       OrganizationResult → AG-UI 事件 + 落库
+```
+
+### 三阶段输出约束
+
+**所有阶段使用 `output_pydantic` 约束输出：**
+
+```python
+from pydantic import BaseModel
+
+class IntentResult(BaseModel):
+    direct_answer: bool
+    next_stage_prompt: str
+    metadata: dict = {}
+
+class ExecutionResult(BaseModel):
+    next_stage_prompt: str
+    metadata: dict = {}
+
+class OrganizationResult(BaseModel):
+    assistant_text: str
+    metadata: dict = {}
+
+# Task 定义
+intent_task = Task(
+    description="Analyze user intent",
+    expected_output="Intent analysis",
+    agent=intent_agent,
+    output_pydantic=IntentResult,
+)
+
+execution_task = Task(
+    description="Execute tasks",
+    expected_output="Execution result",
+    agent=execution_agent,
+    output_pydantic=ExecutionResult,
+)
+
+organization_task = Task(
+    description="Format response",
+    expected_output="User-friendly response",
+    agent=organization_agent,
+    output_pydantic=OrganizationResult,
+)
+```
+
+---
+
+## 系统选模逻辑设计
+
+### 问题背景
+
+旧逻辑：`order_by(...).limit(1)` 随机选择一个系统 agent，不区分阶段。
+
+新逻辑：按 `agent_type` 显式映射到三阶段。
+
+### 选模规则
+
+**必需的 Agent Types：**
+- `INTENT_RECOGNITION` → 用于 intent_stage
+- `TASK_EXECUTION` → 用于 execution_stage
+- `RESULT_REPORTING` → 用于 organization_stage
+
+**查询逻辑：**
+
+```python
+REQUIRED_TYPES = {"INTENT_RECOGNITION", "TASK_EXECUTION", "RESULT_REPORTING"}
+
+@dataclass(frozen=True)
+class StageModels:
+    intent: SystemAgentCatalog
+    execution: SystemAgentCatalog
+    organization: SystemAgentCatalog
+
+def resolve_stage_models(rows: list[SystemAgentCatalog]) -> StageModels:
+    by_type = {row.agent_type: row for row in rows}
+    missing = REQUIRED_TYPES - set(by_type.keys())
+    if missing:
+        raise ValueError(f"Missing required agent types: {missing}")
+    
+    return StageModels(
+        intent=by_type["INTENT_RECOGNITION"],
+        execution=by_type["TASK_EXECUTION"],
+        organization=by_type["RESULT_REPORTING"],
+    )
+```
+
+**初始化数据约束：**
+- `system_agents` 表必须包含三种类型的记录
+- 运行时启动时验证完整性
+
+---
+
+## 人民币结算策略设计
+
+### 设计原则
+
+1. **保留 LiteLLM 语义**：`completion_cost()` 始终返回 USD
+2. **业务层映射**：根据用户国家（`profiles.settings.preferences.country`）决定落库货币
+3. **默认人民币**：中国用户或无国家信息默认 CNY
+4. **汇率配置**：USD/CNY 汇率通过环境变量配置
+
+### 货币来源
+
+```
+UserAgentContext.settings.preferences.country
+    ↓
+resolve_billing_currency(country)
+    ↓
+CN → CNY
+US → USD
+其他 → USD
+```
+
+### 结算流程
+
+```
+LiteLLM completion_cost()
+    ↓ (USD)
+resolve_billing_cost(usd_cost, country)
+    ↓
+    ├─ country="CN" or None → CNY (乘以汇率)
+    └─ country="US" → USD (保持原值)
+    ↓
+messages.cost + messages.currency
+sessions.total_cost (同一货币)
+```
+
+### 汇率配置
+
+```python
+# 环境变量
+BILLING_USD_CNY_RATE=7.2
+
+# 默认值
+DEFAULT_USD_CNY_RATE = Decimal("7.2")
+```
+
+### 结算模型
+
+```python
+@dataclass(frozen=True)
+class BillingCost:
+    currency: str  # "CNY" or "USD"
+    cost: Decimal  # 6位小数精度
+
+def resolve_billing_cost(
+    usd_cost: Decimal,
+    country: str | None,
+    usd_cny_rate: Decimal = DEFAULT_USD_CNY_RATE,
+) -> BillingCost:
+    currency = "CNY" if (country or "CN").upper() == "CN" else "USD"
+    if currency == "CNY":
+        cost = usd_cost * usd_cny_rate
+    else:
+        cost = usd_cost
+    return BillingCost(
+        currency=currency,
+        cost=cost.quantize(Decimal("0.000001"))
+    )
+```
+
+### 数据库落库
+
+**messages 表：**
+- `cost`: NUMERIC(12,6) - 业务货币金额
+- `currency`: VARCHAR(3) - "CNY" or "USD"
+
+**sessions 表：**
+- `total_cost`: NUMERIC(12,6) - 同一货币累计
+
+**约束：**
+- 同一 session 内所有 messages 的 currency 必须一致
+- sessions.total_cost 累加时保持货币一致
+
+---
+
+## Session 状态一致性设计
+
+### 问题背景
+
+旧逻辑：
+- `sessions.status` 与 `state_snapshot.status` 不同步
+- 失败时状态不一致
+- title 未自动赋值
+
+### 状态机
+
+```
+pending (创建)
+    ↓
+running (开始执行)
+    ↓
+    ├─ completed (成功)
+    └─ failed (异常)
+```
+
+### 状态同步规则
+
+**创建时：**
+```python
+session = AgentChatSession(
+    user_id=user_uuid,
+    status=AgentChatSessionStatus.PENDING,
+    state_snapshot={
+        "status": "pending",
+        "pending_tool_call_id": None,
+    },
+)
+```
+
+**运行时：**
+```python
+# 开始执行
+session.status = AgentChatSessionStatus.RUNNING
+session.state_snapshot["status"] = "running"
+
+# 成功完成
+session.status = AgentChatSessionStatus.COMPLETED
+session.state_snapshot["status"] = "completed"
+
+# 失败
+session.status = AgentChatSessionStatus.FAILED
+session.state_snapshot["status"] = "failed"
+session.state_snapshot["error_id"] = error_id
+```
+
+### 自动 Title 赋值
+
+**规则：**
+- 首次运行时，如果 `session.title` 为空，使用 `user_input[:255]` 赋值
+- 只在第一次运行时赋值，后续不覆盖
+
+**实现：**
+```python
+async def _set_title_if_empty(self, session_id: UUID, title: str) -> None:
+    stmt = (
+        update(AgentChatSession)
+        .where(AgentChatSession.id == session_id)
+        .where(AgentChatSession.title.is_(None))
+        .values(title=title[:255])
+    )
+    await self.db.execute(stmt)
+```
+
+### Repository 方法
+
+```python
+class SessionRepository:
+    async def mark_running(self, session_id: UUID) -> None: ...
+    async def mark_completed(self, session_id: UUID) -> None: ...
+    async def mark_failed(self, session_id: UUID, error_id: str) -> None: ...
+```
+
+---
+
+## 全局 Prompt 构建设计
+
+### 分层结构
+
+```
+全局系统 Prompt
+├─ 身份段（username/bio）
+├─ 偏好段（language/timezone/country）
+└─ 阶段段（动态注入）
+    ├─ intent stage prompt
+    ├─ execution stage prompt
+    └─ organization stage prompt
+```
+
+### 构建函数
+
+```python
+def build_global_system_prompt(ctx: UserAgentContext) -> str:
+    lines = [
+        "# User Identity",
+        f"username: {ctx.username}",
+        f"bio: {ctx.bio or 'N/A'}",
+        "",
+        "# User Preferences",
+        f"interface_language: {ctx.settings.preferences.interface_language}",
+        f"ai_language: {ctx.settings.preferences.ai_language}",
+        f"timezone: {ctx.settings.preferences.timezone}",
+        f"country: {ctx.settings.preferences.country}",
+        "",
+        "# Instructions",
+        "Use the user's preferences to personalize responses.",
+        "Respond in the user's preferred AI language.",
+        "Consider the user's timezone for time-related queries.",
+    ]
+    return "\n".join(lines)
+```
+
+### 阶段注入
+
+每个阶段运行时，在全局 prompt 基础上追加阶段特定的指令：
+
+```python
+def build_stage_prompt(
+    base_prompt: str,
+    stage: str,  # "intent" | "execution" | "organization"
+    ctx: UserAgentContext,
+) -> str:
+    stage_prompts = {
+        "intent": "Analyze the user's intent and decide if direct response is possible.",
+        "execution": "Execute the required tasks and tools to fulfill the user's request.",
+        "organization": "Format the execution results into a user-friendly response.",
+    }
+    return f"{base_prompt}\n\n# Stage: {stage}\n{stage_prompts[stage]}"
+```
+
+---
+
+## 依赖关系图
+
+```
+UserAgentContext (核心上下文)
+    ↓
+    ├─ ProfileSettings (用户配置)
+    │   └─ preferences.country → 人民币结算
+    │
+    ├─ build_global_system_prompt() (全局 Prompt)
+    │   └─ 三阶段 Flow 使用
+    │
+    └─ resolve_stage_models() (选模逻辑)
+        └─ 三阶段 Agent 配置
+```
+
+---
+
+## 相关文档
+
+- [Runtime Database Schema](../runtime/runtime-database.md)
+- [AG-UI Protocol](.opencode/skills/ag-ui/SKILL.md)
+- [CrewAI Framework](.opencode/skills/crewai/SKILL.md)