# TraceStudio

TraceStudio 是一个分布式的、节点式的自动化性能分析平台。它采用 **Master-Worker** 架构，旨在构建通用的性能数据分析与自动化流水线。

## 核心理念 (Core Concepts)

*   **分布式架构**: 
    *   **Server (The Hub)**: 负责 API 网关、图解析与任务分发。
    *   **Client (The Worker)**: 无头（Headless）计算节点，负责算力贡献与自定义逻辑执行。
*   **BYOC (Bring Your Own Compute)**: 允许用户接入本地 Client，运行自己定义的私有节点逻辑，实现数据不出域或利用本地特定环境。
*   **协议先行 (Protocol First)**: `pytrace` 核心库定义了一切契约（NodeBase, Specs, 序列化），Server 与 Client 必须严格遵守同一套标准。
*   **去 UI 化**: 后端不包含 Web 前端代码，仅提供 API 供外部前端调用。

## 架构拓扑 (Architecture)

```text
/
├── pytrace/             # [核心共享库] (Python Package)
│   ├── api/             # [面向用户] Node, Decorators, IO
│   ├── runtime/         # [面向系统] Executor, Registry, Context
│   ├── model/           # [面向数据] Specs, Enums, Data
│   ├── internal/        # [面向框架] MetaMap, Constants
│   └── nodes/           # 通用标准节点库
├── server/              # [中心服务器] (The Hub)
│   ├── api/             # HTTP API (FastAPI)
│   └── dispatcher/      # 路由分发器 (基于能力的路由)
├── client/              # [计算节点] (The Headless Worker)
│   └── registry/        # 本地能力注册
└── docs/                # 协议文档
```

## 核心组件说明

### 1. Pytrace (Shared Library)
系统的“通用语言”。Server 和 Client 必须依赖完全一致的 `pytrace` 版本。
*   **TraceNode**: 所有可执行节点的抽象基类。
*   **Specs**: 使用 Pydantic 定义的数据模型 (`NodeSpec`, `PortSpec`, `ParamSpec`)，用于生成前端元数据。

### 2. Server (The Hub)
*   **能力路由 (Capability-Based Routing)**: 维护一张路由表，记录哪个 Client 拥有哪个自定义 Node。
*   **智能缓存**: 基于 `Hash(NodeVersion + InputData + Params)` 进行结果缓存。

### 3. Client (The Worker)
*   **握手机制**: 启动时向 Server 汇报自己拥有的节点列表 (Capabilities)。
*   **任务执行**: 监听任务 -> 反序列化 (dill) -> 执行 -> 序列化结果 -> 返回。

## 开发指南：定义节点

TraceStudio 使用**装饰器驱动**的方式来定义节点。所有节点需继承自 `pytrace.api.node.TraceNode`。

### 示例代码

```python

pip install -e .

from typing import Any
from pytrace.api.node import TraceNode
from pytrace.api.decorators import input_port, output_port, parameter, node_meta

@node_meta(
    display_name="Threshold Filter", 
    icon="filter-icon", 
    description="Filters data based on a numeric threshold."
)
class ThresholdFilterNode(TraceNode):
    
    # 定义输入端口 (注意: label 字段是必填的，用于 UI 显示)
    @input_port(name="data_in", label="Input Data", type="dataframe")
    
    # 定义输出端口
    @output_port(name="data_out", label="Filtered Data", type="dataframe")
    
    # 定义可配置参数
    @parameter(name="threshold", label="Threshold Value", type="float", default=0.5)
    def process(self, io: Any, context: Any) -> None:
        """
        节点的执行逻辑。
        """
        # 1. 获取输入
        # (假设 io 提供了 get_input 方法)
        data = io.get_input("data_in")
        
        # 2. 获取参数
        thresh = self.params.get("threshold", 0.5)
        
        # 3. 执行业务逻辑
        # result = data[data['value'] > thresh]
        
        # 4. 设置输出
        # io.set_output("data_out", result)
        pass
```

## 启动服务

```bash
uvicorn server.app.main:app --reload
```