000-platform/sdk/README.md

Platform SDK

平台基础设施客户端SDK，提供统一的统计上报、日志记录、链路追踪等功能。

安装

SDK作为共享模块使用，通过软链接引用：

# 在 _shared 目录创建软链接
cd AgentWD/_shared
ln -s ../projects/000-platform/sdk platform

在项目中使用

1. 添加路径

在项目的 main.py 开头添加：

import sys
from pathlib import Path

# 添加 _shared 到路径
sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent.parent / "_shared"))

from platform import get_logger, StatsClient, LoggingMiddleware

2. 日志

from platform import get_logger

logger = get_logger("011-ai-interview")

# 基础日志
logger.info("用户开始面试", user_id=123)
logger.error("面试出错", error=e)

# 审计日志
logger.audit("create", "interview", "123", operator="admin")

3. AI统计上报

from platform import StatsClient

stats = StatsClient(tenant_id=1, app_code="011-ai-interview")

# 上报AI调用
stats.report_ai_call(
    module_code="interview",
    prompt_name="generate_question",
    model="gpt-4",
    input_tokens=100,
    output_tokens=200,
    latency_ms=1500
)

4. 链路追踪

from platform import TraceContext, get_trace_id

# 在请求处理中
with TraceContext(tenant_id=1, user_id=100) as ctx:
    print(f"当前trace_id: {ctx.trace_id}")
    # 所有操作共享同一个trace_id

5. FastAPI中间件

from fastapi import FastAPI
from platform import LoggingMiddleware, TraceMiddleware

app = FastAPI()

# 添加中间件（顺序重要）
app.add_middleware(LoggingMiddleware, app_code="011-ai-interview")
app.add_middleware(TraceMiddleware)

6. HTTP客户端

from platform import PlatformHttpClient

client = PlatformHttpClient(base_url="https://api.example.com")

# 自动传递trace_id和API Key
response = await client.get("/users/1")

7. 配置读取

from platform import ConfigReader

config = ConfigReader(tenant_id=1)

# 读取平台配置
app_id = await config.get("wechat", "app_id")

# 读取环境变量
debug = config.get_env("DEBUG", False)

环境变量

SDK使用以下环境变量：

变量	说明	默认值
PLATFORM_URL	平台服务地址	-
PLATFORM_API_KEY	平台API Key	-

更新日志

v0.1.0

• 初始版本
• 支持日志、统计、链路追踪
• 支持FastAPI中间件
• 支持配置读取