请记住，任何时刻都需要使用中文进行思考与回复。
1. 项目愿景与定位 (Identity & Vision)

    项目核心: 一个分布式、节点式的自动化分析平台。

    架构范式: Master-Worker 模式。Server 负责编排与路由，Client 负责算力贡献与自定义逻辑执行。

    核心理念:

        BYOC (Bring Your Own Compute): 允许用户接入本地 Client，运行自己定义的私有节点逻辑。

        协议先行: pytrace 库定义一切契约，Server 与 Client 必须严格遵守同一套序列化与通信标准。

        去 UI 化: 本项目不包含 Web 前端代码，仅提供 API 供外部前端（NPM 项目）调用。

    业务领域: 以 Unreal Insights 数据解析为起点，旨在构建通用的性能数据分析与自动化流水线。

2. 架构拓扑 (Architecture Topology)

本项目从遗留单体系统 (server_old) 拆分为三个独立部分：
📂 目录结构规范
Plaintext

/
├── server_old/          # [遗留] 旧版逻辑参考 (只读，用于提取算法)
├── pytrace/             # [核心共享库] (Python Package)
│   ├── api/             # [面向用户] Node, Decorators, IO
│   ├── runtime/         # [面向系统] Executor, Registry, Context
│   ├── model/           # [面向数据] Specs, Enums, Data
│   ├── internal/        # [面向框架] MetaMap, Constants
│   └── nodes/           # 通用标准节点 (Filter, Aggregator...)
├── server/        # [中心服务器] (The Hub)
│   ├── api/             # HTTP API (适配外部 Web 前端)
│   ├── dispatcher/      # 路由分发器 (Capability-Based Routing)
│   └── connection/      # WebSocket/RPC 连接管理
├── client/        # [计算节点] (The Headless Worker)
│   ├── worker/          # 任务监听循环
│   └── registry/        # 本地能力注册 (向 Server 汇报 "我有什节点")
└── docs/                # 协议文档

🧱 三大组件职责

    Pytrace (Shared Library)

        定位: 系统的“通用语言”。

        关键点: Server 和 Client 必须依赖完全一致的 pytrace 版本。

        内容: 包含 NodeBase 基类、数据模型 (Pydantic)、序列化工具 (Dill/Pickle)。严禁包含 Web 框架依赖。

    Server (The Hub)

        定位: API 网关与任务分发器。

        关键逻辑:

            不负责重型计算。

            维护 "能力路由表" (Capability Table)：记录哪个 Client 拥有哪个自定义 Node。

            接收外部前端的 JSON 图 -> 实例化 -> 分发任务给对应的 Client 或本地执行。

    Client (The Worker)

        定位: 无头计算节点 (Headless)。

        关键逻辑:

            启动时进行 握手 (Handshake)：向 Server 注册自己拥有的节点列表 (Capabilities)。

            监听任务 -> 反序列化 -> 执行 pytrace 逻辑 -> 序列化结果 -> 返回 Server。

3. 核心机制设计 (Core Mechanisms)
🚦 分发器设计 (Dispatcher vs Scheduler)

我们不需要复杂的负载均衡调度器，而是采用 基于能力的路由 (Capability-Based Routing)。

    原则:

        私有优先: 如果图中使用的是 Client A 注册的 MyCustomNode，任务必须路由回 Client A。

        会话亲和 (Session Affinity): 如果 Client A 发起了请求，且图中包含通用节点，优先在 Client A 本地执行（减少数据传输），除非显式指定了 Server 端执行。

        公共回退: 只有标准通用节点，才会在 Server 本地或公共 Worker 上执行。

🔄 通信与序列化

    协议: WebSocket (实时控制流) + HTTP (大文件上传/下载)。

    序列化:

        控制平面: JSON (Pydantic models) - 用于节点状态、进度、错误信息。

        数据平面: dill (优先) 或 pickle - 用于传输 DataFrame 或复杂的 Python 对象上下文。

💾 智能缓存 (Smart Caching)

    Scope: 缓存由 Server 统一索引，但数据可能存储在 Server 或 Client 本地。

    Key: Hash(NodeVersion + InputDataHash + Params)。

    Hit: 如果 Server 发现某一步骤已计算过，直接跳过分发，返回缓存结果 ID。

4. 开发规范 (Coding Standards)
🐍 Python (Common)

    Type Hints: 必须严格使用。这是 pytrace 能够自动生成前端元数据的基础。

    Import Guard: pytrace 内部禁止 import fastapi 或 import socketio，保持纯净。

    Error Handling: 节点内的异常必须被捕获并封装为标准 ErrorResult 对象，通过 RPC 传回，而不是直接让进程崩溃。

🤖 给 AI 的指令 (Instructions for Gemini)

    上下文隔离: 当我让你写代码时，先确认是在 pytrace (通用逻辑), server (路由/API), 还是 client (执行环境)。不要把 socketio 代码写进 pytrace。

    迁移思维: 当从 server_old 迁移逻辑时，首先将其剥离为无依赖的 Node 类放入 pytrace。

    API 兼容性: 修改 Server API 时，需考虑到外部 NPM 前端项目的调用格式（通常是 JSON Graph）。

    路由意识: 在实现执行逻辑时，始终思考：“这段代码是在 Server 跑还是 Client 跑？”如果是 Client 跑，注意环境依赖问题。


双模态 AI 协作协议 (The Dual-AI Protocol)

本章节定义了 Browser Gemini (架构师) 与 VS Code AI (构建者) 之间的协作规范。
🎭 角色定义

    架构师 (Trace / Browser Gemini):

        职责: 需求分析、架构设计、接口定义 (Interface/Protocol)、编写 "Prompt Spec"。

        输出: 不直接写大量实现代码，而是输出 "Spec Block" (实现规范)。

    构建者 (VS Code AI):

        职责: 文件创建、代码补全、Debug、重构。

        输入: 接收来自架构师的 "Spec Block"，在 IDE 中执行具体编码。

🚀 启动检查清单

    [ ] 建立 pytrace 包结构。

    [ ] 定义 NodeBase 和基础通信协议 (pytrace/protocol.py)。

    [ ] 实现 Server 端的 "握手" 接口，接收 Client 的能力注册。