146 lines
5.8 KiB
Markdown
146 lines
5.8 KiB
Markdown
请记住，任何时刻都需要使用中文进行思考与回复。
|
||
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)
|
||
│ ├── core/ # NodeBase, Context, Serialization
|
||
│ ├── protocols/ # RPC Messages, Handshake Schemas
|
||
│ └── 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 的能力注册。
|