Phase 4：The Realm of Mind 验证实施方案

[!NOTE]

文档定位：本文档是 000-roadmap.md Phase 4 的详细工程实施方案，旨在指导 Pillar IV「The Realm of Mind (心智空间)」的落地与白盒化验证。内容涵盖技术调研、架构设计、代码实现及全链路测试。

前置依赖：本阶段构建于 Phase 1-3 的基座之上，复用其 Unified Schema (The Pulse)、Memory Consolidation (The Hippocampus) 与 Fusion Retrieval (The Perception) 能力。

#1. 执行摘要

#1.1 定位与目标 (Phase 4)

Phase 4: The Realm of Mind 是整个验证计划的集成核心阶段，对标人类大脑的前额叶皮层 (Prefrontal Cortex) —— 负责执行控制、计划决策与工具调度的中枢。

本阶段的核心任务是 "Connecting the Dots"：将前三个阶段构建的感知 (Perception)、记忆 (Hippocampus) 与状态 (Pulse) 能力，通过标准化的 Agent Runtime 编排起来，形成具备完整心智的智能体。

关键交付目标：

1. Framework Adaptation (骨架适配)：实现 PostgresSessionService 与 PostgresMemoryService，完成与 Google ADK 的标准化接口对接。
2. Glass-Box Runtime (白盒运行时)：构建完全透明的 AgentExecutor，取代黑盒 API，确保推理过程的每一步（Thought -> Action -> Observation）均可观测、可调试。
3. Dynamic Capability (动态能力)：构建数据库驱动的 Tool Registry，支持工具的热加载与权限控制。
4. Safe Execution (安全执行)：集成 Sandbox (沙箱) 环境，确保代码解释器 (Code Interpreter) 与外部工具的安全隔离。

#1.2 核心概念解析

#1.2.1 Glass-Box vs Black-Box

[!IMPORTANT]

核心价值：Phase 4 将 Google Vertex AI Agent Engine 的黑盒托管能力，解构为完全透明、可调试、可掌控的 Glass-Box Implementation。

#1.2.2 ADK Service 接口适配

本方案采用 Adapter Pattern，将 Cognizes Engine 的底层能力（Pulse, Hippocampus）映射为 Google ADK 的标准接口。

#1.3 执行导图 (Execution Map)

#1.3.1 任务-文档锚定

[!NOTE]

本矩阵建立了 Planning (任务)、Navigation (文档) 与 Delivery (产物) 的三维映射。

#1.3.2 实施甘特图 (Gantt Chart)

#2. 核心参考模型：ADK Runtime

本章旨在确立 Golden Standard (基准规范)。通过解构 Google ADK 的抽象接口，明确 Pillar I (Pulse) 与 Pillar II (Hippocampus) 在代码层面的标准化契约。

#2.1 契约定义：SessionService

SessionService (对标 google/adk-python base_session_service.py) 是 The Pulse (脉搏系统) 的运行时接口。它不仅负责 Session 的 CRUD，还通过 append_event 方法承载了 状态流转 (State Transitions) 的核心逻辑。

[!IMPORTANT]

关键发现：append_event() 不是抽象方法，基类提供了默认实现来处理 temp: 前缀过滤和 State 更新。子类只需覆写 CRUD 方法。

这种设计模式确保了所有 adapter (如 InMemory, Firestore, Postgres) 共享完全一致的 State Transition Logic，防止因实现差异导致的行为不一致。SessionService 在此扮演了 Boundary Object 的角色，定义了 Pulse 与外部存储交互的唯一合法途径。

#2.1.1 Session 数据结构

#2.1.2 State 前缀机制

ADK 通过 Key 前缀实现不同作用域的状态管理：

#2.2 ADK MemoryService 接口契约

from abc import ABC, abstractmethod
from google.adk.memory import SearchMemoryResponse

class BaseMemoryService(ABC):
    """Memory 管理服务抽象基类"""

    @abstractmethod
    async def add_session_to_memory(
        self,
        session: Session
    ) -> None:
        """将 Session 中的对话转化为可搜索的记忆"""
        ...

    @abstractmethod
    async def search_memory(
        self,
        *,
        app_name: str,
        user_id: str,
        query: str
    ) -> SearchMemoryResponse:
        """基于 Query 检索相关记忆"""
        ...

#2.3 ADK Runner 与 Service 交互流程

#2.4 调研交付物摘要

#2.4.1 SessionService 关键行为分析 (P4-1-1, P4-1-3)

#2.4.2 MemoryService 关键行为分析 (P4-1-2, P4-1-4)

[!NOTE]

源码对标: google/adk-python / .../sessions/in_memory_session_service.py

该参考实现建立了 State Management 的行为基准。PostgreSQL 适配器虽存储介质不同，但必须严格遵守以下设计模式，以确保业务逻辑的一致性。

#2.4.3.1 核心行为契约 (Behavioral Contract)

1. Deep Copy Isolation (深拷贝隔离)

   • 行为: get_session 返回的对象必须是完全独立的副本。
   • 目的: 防止 Client 端对 Session 对象的修改污染底层存储缓存，确保 State 变更只能通过明确的 update 接口发生。

2. Structural Hierarchy (结构化层级)

   • 模型: App -> User -> Session 三层命名空间。
   • PG 映射: 通过 (app_name, user_id, session_id) 联合主键或索引实现物理隔离。

3. Atomic Snapshot (原子快照)

   • 行为: 每次 append_event 不仅追加事件，还必须更新 state 快照。
   • 约束: Event Log 与 State Snapshot 必须在同一个事务中提交，杜绝数据不一致。

#2.4.3.2 逻辑流可视化

PostgreSQL 实现对标要点:

#2.4.4 InMemoryMemoryService 源码分析 (P4-1-4)

# 关键设计模式分析
class InMemoryMemoryService(BaseMemoryService):
    """
    核心设计:
    1. 简化实现: 仅存储 Session 的文本摘要
    2. 无真实向量: search_memory 使用字符串匹配
    3. 命名空间隔离: {app_name: {user_id: [MemoryEntry]}}
    """

    def __init__(self):
        self._memories: dict[str, dict[str, list[MemoryEntry]]] = {}

    async def add_session_to_memory(self, session: Session):
        # 简化: 将所有 Event 内容合并为单条记忆
        content = " ".join([str(e.content) for e in session.events])
        entry = MemoryEntry(
            id=str(uuid.uuid4()),
            content=content,
            session_id=session.id,
            created_at=datetime.now()
        )
        self._memories.setdefault(session.app_name, {}) \
                      .setdefault(session.user_id, []).append(entry)

    async def search_memory(self, *, app_name, user_id, query):
        memories = self._memories.get(app_name, {}).get(user_id, [])
        # 简化: 字符串包含匹配 (无真实向量搜索)
        matched = [m for m in memories if query.lower() in m.content.lower()]
        return SearchMemoryResponse(memories=matched)

PostgreSQL 实现增强点:

#3. 架构设计：Mind Schema 扩展

#3.1 Schema 扩展设计

在 Phase 1-3 的 Unified Schema 基础上，新增以下运行时相关表：

#3.2 表职责说明

#3.3 核心表 DDL 设计

#3.3.1 tools 表 (工具注册表)

[!TIP] Single Source of Truth: 完整 Schema 定义请参见 mind_schema.sql。

tools 表实现了动态工具注册机制，通过 openapi_schema JSONB 字段存储工具的规范定义，支持工具的热加载与版本管理。提供了 permissions 字段用于细粒度的访问控制，并通过 call_count 和 avg_latency_ms 字段支持运行时的性能监控。

#3.3.2 traces 表 (OpenTelemetry 存储)

[!TIP] Single Source of Truth: 完整 Schema 定义请参见 mind_schema.sql。

traces 表用于结构化存储 OpenTelemetry 产生的 Trace 数据。设计上直接映射了 OTLP 的标准字段（trace_id, span_id, parent_span_id），并使用 JSONB 类型灵活存储 attributes 和 events，从而实现对 Agent 思考过程（Thought Process）的完全白盒化追踪与回放。

#4. 实施指南

#4.1 Step 1: PostgresSessionService 实现

#4.1.1 实现目标

实现完全兼容 ADK BaseSessionService 接口的 PostgreSQL 适配器。

任务清单：

#4.1.2 目录结构决策

决策：采用统一项目结构 (Integrated Structure)

为了降低初期开发和联调的复杂度，建议将 adk-postgres 作为 cognizes 引擎的一个子模块（Adapter），共用主项目的 pyproject.toml 和开发环境。

推荐目录结构：

src/cognizes/
├── adapters/
│   └── postgres/               # 适配器核心实现
│       ├── __init__.py
│       ├── session_service.py  # PostgresSessionService
│       ├── memory_service.py   # PostgresMemoryService
│       ├── tool_registry.py    # ToolRegistry
│       ├── tracing.py          # OpenTelemetry 集成
│       ├── sandbox/            # 沙箱实现
│       │   ├── __init__.py
│       │   ├── base.py
│       │   └── microsandbox_runner.py
│       └── models/             # 适配器私有模型（或使用全局模型）
│           ├── __init__.py
│           ├── session.py
│           └── event.py
tests/
├── unittests/adapters/postgres
└── integrationtests/adapters/postgres

理由：

1. 开发效率：避免在多个项目间频繁切换和执行 pip install -e。
2. 原子提交：引擎接口的变更及其在 Postgres 适配器中的实现可以在同一个 Commit 中完成，保证代码一致性。
3. 简化 CI/CD：统一的测试运行环境和依赖管理，降低维护成本。
4. 未来解耦：adapters/postgres 目录保持高度内聚，未来若需独立发布为 adk-postgres 包，只需将其移动到独立仓库并添加 pyproject.toml 即可。

#4.1.3 核心实现代码

[!TIP] Single Source of Truth: 完整核心代码实现请参见 session_service.py。

PostgresSessionService 类通过 asyncpg 连接池管理会话生命周期。其核心逻辑在于 append_event 方法中的事务处理：它不仅将事件写入 events 表，还解析 state_delta 并根据前缀（user:, app:, temp:）将其路由更新到 user_states, app_states 或内存缓存中，确保了状态的一致性与隔离性。

#4.2 Step 2: PostgresMemoryService 实现

#4.2.1 实现目标

实现完全兼容 ADK BaseMemoryService 接口的 PostgreSQL 适配器，复用 Phase 2 的记忆巩固能力。

任务清单：

#4.2.2 核心实现代码

[!TIP]

Single Source of Truth: 完整核心代码实现请参见 memory_service.py。

PostgresMemoryService 类充当了 Hippocampus (Memory) 与 Realm of Mind (Runtime) 之间的桥梁。它并不重复造轮子，而是通过 add_session_to_memory 接口触发 Phase 2 的记忆巩固工作流（Consolidation Worker）将短期对话转化为长期记忆，并通过 search_memory 接口复用 Phase 3 的混合检索能力（Hybrid Search）为 Agent 提供具备语义理解的记忆检索服务。

#4.3 Step 3: Tool Registry 实现

#4.3.1 实现目标

实现数据库驱动的动态工具注册表，支持 OpenAPI Schema 动态加载与热更新。

任务清单：

#4.3.2 核心实现代码

[!TIP] Single Source of Truth: 完整核心代码实现请参见 tool_registry.py。

ToolRegistry 实现了基于 PostgreSQL 的动态工具管理。它不仅支持工具的注册与发现，还集成了 openapi_schema 的存储与检索，支持权限控制字段 permissions，并内置了 invoke_tool 包装器以自动记录调用统计数据（调用次数、延迟），为后续的工具热更新与性能分析奠定基础。

#4.4 Step 4: AgentExecutor 实现

#4.4.1 实现目标

实现 Python 驱动的 Agent 执行器，管理 Thought -> Action -> Observation 循环。

任务清单：

#4.4.2 核心实现代码

[!TIP] Single Source of Truth: 完整核心代码实现请参见 agent_executor.py。

AgentExecutor 是 Mind 的运行时编排核心，负责驱动 "Thought -> Action -> Observation" 的 ReAct 循环。它管理着执行状态 (ExecutionStatus) 和每一步的思考记录 (ThinkingStep)，通过最大步数限制和超时控制机制防止无限循环，确保了 Agent 执行的可控性与稳定性。

#4.5 Step 5: 测试实现

#4.5.1 SessionService 单元测试 (P4-3-1)

[!TIP] Single Source of Truth: 完整单元测试代码请参见 test_session_service.py。

该测试套件严格对标 ADK BaseSessionService 接口规范，覆盖了 create/get/list/delete 等会话生命周期管理方法，并重点验证了 state_delta 在不同前缀（user:, temp:) 下的路由与持久化行为，确保适配器实现的正确性。

#4.5.2 ADK LlmAgent 集成示例 (P4-2-23)

[!TIP] Single Source of Truth: 完整代码示例请参见 test_adk_llmagent.py。

该集成测试演示了如何将 PostgresSessionService 和 PostgresMemoryService 注入到 ADK 的 Runner 中，替换默认的内存实现。通过这种方式，基于 ADK 开发的 LlmAgent 可以无缝获得持久化存储与长期记忆能力，无需修改 Agent 自身的业务逻辑。

#4.5.3 E2E 集成测试 (P4-3-4)

[!TIP] Single Source of Truth: 完整测试代码实现请参见 test_e2e.py。

这是一个端到端的集成测试，验证了从 Session 创建、Agent 交互 (ReAct Loop) 、工具调用到长期记忆存储与召回的完整闭环。它确保了各个组件（Session/Memory Service, ToolRegistry）在真实数据库环境中能够协同工作，实现了状态的流转与持久化。

#4.6 Step 6: OpenTelemetry 集成

#4.6.1 任务清单

#4.6.2 导出策略设计

[!IMPORTANT]

双路导出策略：同时将 Trace 数据发送到两个目的地，满足不同需求。

导出目标	用途	数据保留
PostgreSQL	审计、历史查询、合规留存	按策略归档
OTLP (Langfuse)	实时可视化调试 + Evaluation	按项目配置

#4.6.3 核心实现

[!TIP] Single Source of Truth: 完整核心代码实现请参见 tracing.py。

TracingManager 实现了基于 OpenTelemetry 的双路导出架构：数据一方面通过 PostgresSpanExporter 写入本地数据库进行长期合规审计，另一方面通过 OTLP 协议发送到 Langfuse 等平台进行实时可视化调试。这种设计兼顾了数据主权与现代化的调试体验。

#4.7 Step 7: Sandboxed Execution 实现

#4.7.1 任务清单

#4.7.2 沙箱方案对比

[!NOTE]

核心考量：Docker 容器级隔离共享内核，存在逃逸风险；启动时间秒级影响交互体验。推荐使用基于 microVM 的轻量级沙箱。

microsandbox 核心优势 (zerocore-ai/microsandbox, 4.3k+ stars):

• 真正 VM 隔离：基于 libkrun 的 microVM，独立内核，完全隔离宿主机
• 极速启动：<200ms 冷启动 (Docker 秒级)
• OCI 兼容：支持标准容器镜像
• MCP 原生集成：内置 MCP Server，可直接与 AI Agent 对接

#4.7.3 SandboxRunner 抽象接口 (P4-4-6)

[!NOTE]

设计原则: 定义统一的沙箱接口，支持多种后端实现 (microsandbox/Docker/WebAssembly)。

[!TIP] Single Source of Truth: 完整接口定义请参见 base.py。

SandboxRunner 定义了沙箱执行的统一接口，支持 execute, execute_file 以及带安全检查的 execute_safe。

工厂函数:

[!TIP]

Single Source of Truth: 工厂函数实现请参见 __init__.py。

#4.7.4 核心实现

安装 microsandbox:

# 安装 microsandbox CLI
curl -sSL https://get.microsandbox.dev | sh

# 启动 microsandbox server (开发模式)
msb server start --dev

[!TIP]

Single Source of Truth: Microsandbox 完整实现请参见 microsandbox_runner.py。

提供了基于 libkrun 的 microVM 级隔离环境，确保 Agent 代码执行的安全性。

MCP 集成示例 (直接与 AI Agent 对接):

[!TIP]

Single Source of Truth: MCP 工具适配代码请参见 mcp.py。

#4.8 Step 8: 可视化验证 (Langfuse)

[!NOTE]

工具变更: 采用 Langfuse (基于 OTLP) 实现全链路追踪，以获得更强的 LLM Agent 调试能力（Prompt Management, Model Evaluation）。

Langfuse 部署命令 (Localhost):

# 1. 获取官方 Docker Compose 配置
# curl -L https://github.com/langfuse/langfuse/blob/main/docker-compose.yml -o assets/docker-compose.yml

# 2. 启动服务 (包含了 Postgres/ClickHouse 依赖)
docker compose up -d

# 3. 访问 http://localhost:3000 并创建账号获取 Keys

环境变量配置 (用于 tracing.py):

export LANGFUSE_SECRET_KEY=sk-lf-...  # 从 UI 获取
export LANGFUSE_PUBLIC_KEY=pk-lf-...  # 从 UI 获取
export LANGFUSE_HOST=http://localhost:3000

#4.9 Step 9: AG-UI 协议集成

[!NOTE]

对标 Roadmap 4.4: AG-UI 作为 Agent-User 交互的标准化协议层，增强 The Realm of Mind 的前端交互能力。

参考资源:

• AG-UI 协议调研
• AG-UI 官方文档

#4.9.1 AG-UI 核心概念

AG-UI 是连接 AI Agent 与用户界面的"最后一公里"协议，定义了 16 种标准事件类型：

#4.9.2 任务清单

#4.9.3 AgUiEventEmitter 实现

[!TIP]

Single Source of Truth: 完整事件定义请参见 event_emitter.py。

AgUiEventEmitter 负责将 Agent 的内部执行事件转换为 AG-UI 协议定义的 16 种标准事件，包括 Lifecycle, Text Message, Tool Call 和 State Management 事件。

#4.9.4 前端工具集成

扩展 Tool Registry 支持前端定义工具：

[!TIP]

Single Source of Truth: 前端与 HITL 工具扩展已合入 tool_registry.py。

ToolRegistry 现已支持 FrontendTool 类型，允许定义需要人工确认 (HITL) 或仅在前端渲染的 UI 工具。

#4.9.5 Human-in-the-Loop 实现

[!TIP]

Single Source of Truth: HITL 逻辑实现请参见 hitl.py。

#4.9.6 CopilotKit 服务端集成

创建 FastAPI 端点供 CopilotKit 客户端连接：

[!TIP]

Single Source of Truth: CopilotKit 服务端集成代码请参见 copilotkit_server.py。

#4.10 Step 10: 思维链可视化调试

[!NOTE]

对标 AG-UI 协议：本节实现 The Realm of Mind 与 AG-UI 可视化层的深度集成，提供 Agent 思维链、工具调用和决策过程的实时可视化调试能力。

核心目标：将 Glass-Box Runtime 的透明可观测性通过 AG-UI 事件呈现到前端。

#4.10.1 思维链可视化架构

#4.10.2 AG-UI 事件映射表 (Mind 层)

#4.10.3 ThinkingVisualizer 实现

[!TIP]

Single Source of Truth: 可视化逻辑完整实现请参见 thinking_visualizer.py。

ThinkingVisualizer 负责实时发射思维步骤、工具执行细节和 Trace Span 事件，支持前端组件（如思维卡片、时间线）的渲染。

#4.10.4 前端展示组件规范

#4.10.5 任务清单 (补充)

#4.10.6 验收标准 (补充)

#5. 验证 SOP (Phase 4)

#5.1 功能验收

#5.2 性能验收

#5.3 详细验收流程 (P4-5-1 ~ P4-5-4)

#5.3.1 验收前置条件

# 1. 环境准备
export DATABASE_URL="postgresql://aigc:@localhost:5432/cognizes-engine"
export GOOGLE_API_KEY="your-gemini-api-key"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"

# 2. 启动依赖服务
# docker-compose up -d postgres langfuse microsandbox
# 需参照前文，手动挨个启动

# 3. 初始化数据库
psql -d 'cognizes-engine' -f src/cognizes/engine/schema/agent_schema.sql
psql -d 'cognizes-engine' -f src/cognizes/engine/schema/hippocampus_schema.sql
psql -d 'cognizes-engine' -f src/cognizes/engine/schema/perception_schema.sql
psql -d 'cognizes-engine' -f src/cognizes/engine/schema/mind_schema.sql

# 4. 安装 Open Agent Engine (包含 adk-postgres 适配器)
# 在项目根目录执行
pip install -e ".[dev]"

#5.3.2 逐项验收检查清单

[!IMPORTANT]

逐项执行以下验收检查，全部通过后方可进入 Phase 5。

SessionService 验收 (P4-2-2 ~ P4-2-8)

MemoryService 验收 (P4-2-9 ~ P4-2-12)

Tool Registry 验收 (P4-2-13 ~ P4-2-18)

OpenTelemetry 验收 (P4-4-1 ~ P4-4-4)

安全沙箱验收 (P4-4-5 ~ P4-4-10)

#5.3.3 ADK 集成验收

[!TIP]

Single Source of Truth: ADK 集成测试脚本请参见 test_adk_llmagent.py。

验证内容包括：Agent 响应、Session 状态持久化、Memory 语义搜索、Trace 完整性。

#5.3.4 性能压测流程

# 1. SessionService 压力测试 (100 并发, 1000 请求)
uv run locust -f tests/performance/mind/locustfile.py \
  --users 100 --spawn-rate 10 --run-time 60s \
  --host $DATABASE_URL \
  --html report_session.html

# 2. 验收标准
# - P99 Latency < 50ms
# - Error Rate < 0.1%
# - Throughput > 500 RPS

#5.3.5 验收报告模板

# Phase 4 验收报告

## 验收信息

- **验收日期**: YYYY-MM-DD
- **验收人**: [Name]
- **Git Commit**: [hash]

## 功能验收结果

| 模块           | 通过项 | 总项数 | 通过率 |
| :------------- | -----: | -----: | -----: |
| SessionService |      X |      8 |     X% |
| MemoryService  |      X |      4 |     X% |
| Tool Registry  |      X |      4 |     X% |
| OpenTelemetry  |      X |      3 |     X% |
| 安全沙箱       |      X |      4 |     X% |
| **总计**       |  **X** | **23** | **X%** |

## 性能验收结果

| 指标              | 目标   | 实测 | 状态  |
| :---------------- | :----- | :--- | :---: |
| Session CRUD P99  | <50ms  | Xms  | ✅/❌ |
| Memory Search P99 | <100ms | Xms  | ✅/❌ |
| 沙箱启动时间      | <2s    | Xs   | ✅/❌ |

## ADK 集成验收

- [ ] LlmAgent 正常响应
- [ ] Session 状态正确持久化
- [ ] Memory 搜索返回相关结果
- [ ] Trace 完整记录

## 遗留问题

1. [描述问题及处理计划]

## 验收结论

- [ ] **通过**: 全部验收项达标，可进入 Phase 5
- [ ] **有条件通过**: 存在非阻塞问题，跟踪处理
- [ ] **不通过**: 存在阻塞问题，需修复后重新验收

#5.3.6 回归测试指引

[!NOTE]

后续代码变更后，执行以下回归测试确保未引入回归。

# 完整回归测试套件
pytest tests/ -v --cov=cognizes.adapters.postgres --cov=cognizes.engine.mind --cov-report=html

# 快速冒烟测试 (CI 用)
pytest tests/ -v -m "smoke" --maxfail=3

# 生成测试报告
pytest tests/ --html=regression_report.html --self-contained-html

pytest.ini 标记配置:

[pytest]
markers =
    smoke: 冒烟测试 (快速验证核心功能)
    integration: 集成测试 (需要数据库)
    performance: 性能测试 (需要较长时间)
    security: 安全测试 (沙箱相关)

#5.4 Phase 4 完整验收 SOP

[!IMPORTANT]

本节提供 Phase 4 的完整验收流程，确保所有功能点按照 000-roadmap.md 的验证矩阵进行系统性验证。按照以下步骤逐项执行，全部通过后方可进入 Phase 5。

#5.4.1 环境核验

Step 1: 数据库环境检查

# 1. 验证 PostgreSQL 运行状态
pg_isready -h localhost -p 5432

# 2. 验证数据库存在
psql -d cognizes-engine -c "SELECT version();"

# 3. 验证扩展安装
psql -d cognizes-engine -c "SELECT extname, extversion FROM pg_extension WHERE extname IN ('vector', 'pg_cron');"

# 预期输出:
#  extname  | extversion
# ----------+------------
#  vector   | 0.7.0
#  pg_cron  | 1.6

Step 2: Langfuse 环境检查

# 1. 验证 Langfuse 服务可达 (Docker 部署)
curl -s https://langfuse.automizely.me/api/public/health | jq .

# 预期输出:
# { "status": "ok" }

# 2. 验证环境变量配置
echo "LANGFUSE_PUBLIC_KEY: ${LANGFUSE_PUBLIC_KEY:0:8}..."
echo "LANGFUSE_SECRET_KEY: ${LANGFUSE_SECRET_KEY:0:8}..."
echo "LANGFUSE_HOST: ${LANGFUSE_HOST:-https://cloud.langfuse.com}"

# 若未配置，请设置:
# export LANGFUSE_PUBLIC_KEY="pk-lf-xxx"
# export LANGFUSE_SECRET_KEY="sk-lf-xxx"
# export LANGFUSE_HOST="http://localhost:3000"

Step 3: Python 环境检查

# 1. 验证 Python 版本
python --version  # 预期: Python 3.13+

# 2. 验证依赖安装
python -c "import google.adk; import asyncpg; print('✅ ADK 和 asyncpg 正常')"

# 3. 可选: 验证 Langfuse SDK
python -c "import langfuse; print('✅ Langfuse SDK 正常')"

# 4. 验证项目模块可导入
python -c "from cognizes.adapters.postgres import session_service, memory_service, tracing; print('✅ 模块正常')"

#5.4.2 自动化核查

Step 1: 执行单元测试

# 运行 Mind 模块全部单元测试 (Mock 隔离，不需数据库)
pytest tests/unittests/mind/ -v --tb=short

# 预期: 全部 PASSED
# ==================== XX passed in X.XXs ====================

Step 2: 执行集成测试

# 运行 Mind 模块全部集成测试 (需要数据库)
pytest tests/integration/mind/ -v --tb=short -m "not skip"

# 预期: 全部 PASSED (跳过需要真实 Langfuse 的测试)

Step 3: 执行 Langfuse 集成测试

# 运行 Langfuse 集成测试 (需要配置环境变量)
# pytest tests/integration/mind/test_langfuse_integration.py -v --tb=short
pytest tests/integration/mind/test_langfuse_real.py -v --tb=short

# 预期:
# - 模拟测试 PASSED
# - 真实 Langfuse 测试 (如配置) 输出 Trace ID

Step 4: 生成覆盖率报告

# 生成测试覆盖率报告
pytest tests/ -v --cov=cognizes.adapters.postgres --cov=cognizes.engine.mind \
    --cov-report=html --cov-report=term

# 预期: 覆盖率 >= 80%
# 报告路径: htmlcov/index.html

#5.4.3 控制台验证

Step 1: Langfuse UI 验证

1. 打开浏览器访问: http://localhost:3000 (本地) 或 https://cloud.langfuse.com (云端)
2. 登录并进入项目 Dashboard
3. 验证以下内容:

Step 2: PostgreSQL traces 表验证

# 查询最近的 Trace 记录
psql -d 'cognizes-engine' -c "
SELECT trace_id, span_id, operation_name, span_kind,
       start_time, status_code
FROM traces
ORDER BY start_time DESC
LIMIT 10;
"

# 验证层级关系
psql -d 'cognizes-engine' -c "
SELECT t1.operation_name AS parent_op,
       t2.operation_name AS child_op
FROM traces t1
JOIN traces t2 ON t2.parent_span_id = t1.span_id
WHERE t1.parent_span_id IS NULL
LIMIT 5;
"

#5.4.4 指标对齐验证

根据 000-roadmap.md 验证矩阵 (Section 2.1)，确认以下指标对齐:

[!NOTE]

以上指标对应 Roadmap 中 The Realm of Mind 支柱的核心核验指标:

• 可调试性 (Debuggability): 能否精准定位推理死循环或幻觉
• Glass-Box Tracing: 完整记录 Thought Chain、Tool IO 与 Slot Updates

#5.4.5 验收总结检查清单

# Phase 4 验收检查清单

## 环境核验

- [ ] PostgreSQL 运行正常，扩展已安装
- [ ] Langfuse 服务可达 (或环境变量已配置)
- [ ] Python 依赖安装完整

## 功能验收

- [ ] 单元测试全部通过 (pytest tests/unittests/mind/)
- [ ] 集成测试全部通过 (pytest tests/integration/mind/)
- [ ] Langfuse 集成测试通过 (Trace ID 透传验证)
- [ ] ADK 接口兼容性验证通过

## 可观测性验收

- [ ] Langfuse Traces 可见
- [ ] Span 层级关系正确
- [ ] Generation 事件包含 Token 消耗
- [ ] Evaluation 分数正确记录
- [ ] PostgreSQL traces 表有数据

## 指标对齐验收

- [ ] Session CRUD P99 < 50ms
- [ ] Memory Search P99 < 100ms
- [ ] Trace 完整性 100%
- [ ] Token Cost 可追踪
- [ ] Evaluation Score 可记录

## 验收结论

- [ ] **通过**: 全部验收项达标，可进入 Phase 5
- [ ] **有条件通过**: 存在非阻塞问题，跟踪处理
- [ ] **不通过**: 存在阻塞问题，需修复后重新验收

#5.5 核验命令快速参考

[!TIP]

以下命令可直接复制执行，用于快速验证 Phase 4 各模块的实现状态。

#5.5.1 测试执行命令

# Phase 4 完整测试套件 (82 tests expected)
uv run pytest tests/unittests/mind/ tests/integration/mind/ -v --tb=short

# 仅运行单元测试
uv run pytest tests/unittests/mind/ -v

# 仅运行集成测试
uv run pytest tests/integration/mind/ -v

# 运行特定模块测试
uv run pytest tests/unittests/mind/test_session_service.py -v
uv run pytest tests/unittests/mind/test_sandbox.py -v
uv run pytest tests/integration/mind/test_tracing.py -v

#5.5.2 PostgreSQL 数据验证

# 验证 traces 表有数据
psql -d 'cognizes-engine' -c "SELECT COUNT(*) as trace_count FROM traces;"

# 查看最近 10 条 Trace 记录
psql -d 'cognizes-engine' -c "
SELECT trace_id, span_id, operation_name, start_time
FROM traces
ORDER BY start_time DESC
LIMIT 10;
"

# 验证 tools 表注册情况
psql -d 'cognizes-engine' -c "
SELECT app_name, name, is_active, call_count, avg_latency_ms
FROM tools
ORDER BY updated_at DESC
LIMIT 10;
"

# 验证 Span 层级关系
psql -d 'cognizes-engine' -c "
SELECT t1.operation_name AS parent_op,
       t2.operation_name AS child_op,
       t2.parent_span_id
FROM traces t1
JOIN traces t2 ON t2.parent_span_id = t1.span_id
WHERE t1.parent_span_id IS NULL
LIMIT 5;
"

#5.5.3 Langfuse 集成验证

# 发送测试 Trace 到 Langfuse
set -a && source .env && set +a && uv run python tests/integration/mind/test_langfuse_real.py

# 验证 Langfuse 环境变量
echo "LANGFUSE_HOST: ${LANGFUSE_HOST:-not set}"
echo "LANGFUSE_PUBLIC_KEY: ${LANGFUSE_PUBLIC_KEY:0:8}..."

#5.5.4 TracingManager 功能验证

# 验证 PostgresSpanExporter 正常工作
set -a && source .env && set +a && uv run python -c "
import asyncio
from cognizes.adapters.postgres.tracing import TracingManager
import os

async def test_postgres_tracing():
    dsn = os.environ['DATABASE_URL']
    manager = TracingManager(service_name='verification_test', pg_dsn=dsn)

    async with manager.span('verification_root') as root:
        root.set_attribute('test.source', 'verification_script')
        async with manager.span('verification_child') as child:
            child.set_attribute('test.child', 'true')

    manager.provider.force_flush()
    print('✅ Trace 已发送到 PostgreSQL')

    # 验证写入
    await asyncio.sleep(2)
    import asyncpg
    conn = await asyncpg.connect(dsn)
    count = await conn.fetchval('SELECT COUNT(*) FROM traces WHERE operation_name LIKE \\'verification_%\\'')
    print(f'✅ 查询到 {count} 条验证记录')
    await conn.close()

asyncio.run(test_postgres_tracing())
"

#5.5.5 技术指标核验

#6. 验收基准

[!IMPORTANT]

对标 Roadmap KPI：以下验收标准直接对标 000-roadmap.md 中 Pillar IV 的核心核验指标："Stateful Agent Execution - 会话状态持久化与主动执行能力"。

#6.1 功能验收

#6.1.1 核心服务能力

#6.1.2 增强能力 (Advanced Capabilities)

#6.2 性能验收

#6.3 交付物清单

#7. 风险与缓解策略

#7.1 剩余遗留问题 (Known Issues)

• 沙箱冷启动延迟：虽优化至 200ms，但在高并发下 microVM 启动开销仍不可忽视，Phase 5 需引入 "Sandbox Pool" 预热机制。
• 复杂状态冲突：当前 OCC 策略在冲突时直接失败重试，对于高频写场景可能导致长尾延迟，需探索 CRDTs (Conflict-Free Replicated Data Types) 方案。
• 工具动态加载：当前 ToolRegistry 依赖 Python 进程重启加载部分本地代码，需进一步完善基于 WASM 的插件化热加载机制。

#8. 参考资料

1. Google. (2025). ADK Sessions Documentation. Link

2. Google. (2025). ADK Context Documentation. Link

3. OpenTelemetry. (2025). Python SDK. Link

4. Docker. (2025). Docker SDK for Python. Link