Initial commit: 000-platform project skeleton

sdk/README.md

@@ -0,0 +1,129 @@
+# Platform SDK
+
+平台基础设施客户端SDK，提供统一的统计上报、日志记录、链路追踪等功能。
+
+## 安装
+
+SDK作为共享模块使用，通过软链接引用：
+
+```bash
+# 在 _shared 目录创建软链接
+cd AgentWD/_shared
+ln -s ../projects/000-platform/sdk platform
+```
+
+## 在项目中使用
+
+### 1. 添加路径
+
+在项目的 `main.py` 开头添加：
+
+```python
+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. 日志
+
+```python
+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统计上报
+
+```python
+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. 链路追踪
+
+```python
+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中间件
+
+```python
+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客户端
+
+```python
+from platform import PlatformHttpClient
+
+client = PlatformHttpClient(base_url="https://api.example.com")
+
+# 自动传递trace_id和API Key
+response = await client.get("/users/1")
+```
+
+### 7. 配置读取
+
+```python
+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中间件
+- 支持配置读取