feat: Agent 能力升级（SSE、MCP/PAT、Failover、Planning、OTel） (#101)

Author: TNT-Likely

.nvmrc

@@ -0,0 +1 @@
+24.14.0

Dockerfile

@@ -2,12 +2,12 @@
 # 多阶段构建，减小最终镜像大小
 
 # ===== Stage 1: 前端构建 =====
-FROM node:20-alpine AS frontend-builder
+FROM node:24.14.0-alpine AS frontend-builder
 
 WORKDIR /app/frontend
 
-# 安装 pnpm
-RUN npm install -g pnpm
+# 启用并固定 pnpm，避免镜像构建时随 npm 全局安装漂移
+RUN corepack enable && corepack prepare pnpm@9.15.9 --activate
 
 # 复制依赖文件
 COPY frontend/package.json frontend/pnpm-lock.yaml ./

Makefile

@@ -1,60 +1,109 @@
-.PHONY: help setup-backend dev-api dev-web build test test-notify doctor install-hooks clean-venv
+.PHONY: help setup-backend dev-api dev-web build test test-notify eval doctor install-hooks clean-venv
 
 # 端口约定：
 #   - 后端：:8000（Docker / 本地 dev 统一，避免存量用户升级困惑）
 #   - 前端：:5183（与 BeeCount-Cloud 的 :5173 错开避免冲突）
 
+ifneq ($(filter Windows_NT,$(OS)),)
+WINDOWS := 1
+else ifneq (,$(findstring cmd.exe,$(ComSpec)))
+WINDOWS := 1
+endif
+
+ifeq ($(WINDOWS),1)
+SHELL := cmd.exe
+.SHELLFLAGS := /C
+PYTHON := python
+VENV_PYTHON := .venv\Scripts\python.exe
+else
+PYTHON := python3
+VENV_PYTHON := .venv/bin/python
+endif
+
 help:
 	@echo "PanWatch 开发命令:"
 	@echo "  make setup-backend   创建 venv 并安装后端依赖"
 	@echo "  make dev-api         启动后端（:8000，自动 setup-backend）"
 	@echo "  make dev-web         启动前端（:5183，自动 pnpm install）"
 	@echo "  make test            跑全部单测（默认不发通知）"
 	@echo "  make test-notify     跑全部单测（实际发送通知）"
+	@echo "  make eval            跑 Agent 过程评测集（chat 用例需 EVAL_AI_* 环境变量）"
 	@echo "  make doctor          系统自检(数据源/AI/通知/DB/磁盘/调度)"
 	@echo "  make build VERSION=x 构建前端 + Docker 镜像"
 	@echo "  make install-hooks   安装 git pre-push hook"
 	@echo "  make clean-venv      删除本地 venv"
 
 setup-backend:
+ifeq ($(WINDOWS),1)
+	@if not exist .venv ( echo [setup] 创建 venv & $(PYTHON) -m venv .venv )
+	@$(VENV_PYTHON) -m pip install -q -r requirements.txt
+	@if not exist .env if exist .env.example copy /Y .env.example .env >nul
+else
 	@if [ ! -d .venv ]; then \
 		echo ">>> 创建 venv"; \
 		python3 -m venv .venv; \
 	fi
-	@. .venv/bin/activate && pip install -q -r requirements.txt
+	@$(VENV_PYTHON) -m pip install -q -r requirements.txt
 	@if [ ! -f .env ] && [ -f .env.example ]; then cp .env.example .env; fi
+endif
 
 # server.py 内部已经用 uvicorn.run(host=0.0.0.0, port=8000, reload=True) 启动。
 dev-api: setup-backend
-	. .venv/bin/activate && python server.py
+ifeq ($(WINDOWS),1)
+	@set "DEV_RELOAD=1" && $(VENV_PYTHON) server.py
+else
+	@DEV_RELOAD=1 $(VENV_PYTHON) server.py
+endif
 
 dev-web:
+ifeq ($(WINDOWS),1)
+	@where pnpm >nul 2>&1 || ( echo pnpm 未安装，请先 npm install -g pnpm & exit /b 1 )
+	@cd frontend && pnpm install --no-frozen-lockfile && pnpm dev
+else
 	@if ! command -v pnpm >/dev/null 2>&1; then \
 		echo "pnpm 未安装，请先 npm install -g pnpm"; \
 		exit 1; \
 	fi
 	cd frontend && pnpm install --no-frozen-lockfile && pnpm dev
+endif
 
 test:
-	. .venv/bin/activate && python -m pytest tests/ -v
+	@$(VENV_PYTHON) -m pytest tests/ -v
 
 test-notify:
-	. .venv/bin/activate && python -m pytest tests/ -v --notify
+	@$(VENV_PYTHON) -m pytest tests/ -v --notify
+
+# Agent 过程评测(工具选择/参数/有据性/结构化输出/动作白名单):
+#   - 结构化解析用例纯规则,直接跑
+#   - chat 工具循环用例需被测模型: EVAL_AI_BASE_URL / EVAL_AI_API_KEY / EVAL_AI_MODEL
+#   - 追加 LLM-as-judge: EVAL_JUDGE_* 环境变量 + EVAL_ARGS=--judge
+#   - 建议在改动 prompts/*.txt 或工具 schema 后运行,低于阈值(EVAL_PASS_THRESHOLD)退出码非 0
+eval:
+	@$(VENV_PYTHON) tests/eval/run_eval.py $(EVAL_ARGS)
 
 # 命令行系统自检:跑一遍数据源/AI/通知 + DB/磁盘/调度,打印结果与修复建议
 doctor:
-	. .venv/bin/activate && python -m src.core.doctor
+	@$(VENV_PYTHON) -m src.core.doctor
 
 # 用法: make build VERSION=0.3.0
 build:
+ifeq ($(WINDOWS),1)
+	@if "$(VERSION)"=="" ( echo Usage: make build VERSION=^<version^> & exit /b 1 )
+	@powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\build.ps1 -Version "$(VERSION)"
+else
 	@if [ -z "$(VERSION)" ]; then \
 		echo "Usage: make build VERSION=<version>"; \
 		exit 1; \
 	fi
 	./build.sh $(VERSION)
+endif
 
 install-hooks:
 	bash scripts/install-hooks.sh
 
 clean-venv:
+ifeq ($(WINDOWS),1)
+	@if exist .venv rmdir /S /Q .venv
+else
 	rm -rf .venv
+endif

README.md

@@ -152,6 +152,7 @@ docker-compose up -d
 | `PLAYWRIGHT_SKIP_BROWSER_INSTALL` | 跳过首次 Chromium 安装（不需要截图时可用） | 未设置 |
 | `LOG_LEVEL` | 控制台日志级别。默认 `INFO`（只输出业务事件 + 错误）；排查问题时设 `DEBUG` 可看到调度心跳、采集过程等底层日志。UI 日志板始终保留完整记录，不受影响 | `INFO` |
 | `HTTP_PROXY` / `HTTPS_PROXY` / `http_proxy` | 出站 HTTP 代理。三种配置方式任选其一: ① 启动前 `export HTTP_PROXY=...`；② `.env` 里写 `http_proxy=http://host:port`；③ UI「设置 → 全局 HTTP 代理」。三者优先级:外部环境变量 > UI > `.env`。生效后所有 httpx 客户端走代理。`NO_PROXY` 默认包含 `localhost,127.0.0.1` | 未设置 |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry OTLP 导出端点(如 `http://jaeger:4318`)。**配置后**才启用 OTel trace 导出;留空则完全关闭(零副作用)。还需安装可选依赖 `requirements-otel.txt`。详见下方「OTel 导出」 | 未设置(关闭) |
 
 </details>
 
@@ -197,6 +198,45 @@ cd frontend && pnpm install && pnpm dev       # 前端 :5183
 
 </details>
 
+<details>
+<summary><b>OTel 导出（可选，默认关闭）</b></summary>
+
+PanWatch 内建一套自建可观测体系(结构化日志 `trace_id` 贯穿 / `agent_runs` 运行表 / TradingAgents 节点级进度与成本),开箱即用、无需任何外部组件。
+
+在此之上,可**可选地**再挂一层标准 [OpenTelemetry](https://opentelemetry.io/) 导出,把 trace 送到 Jaeger / Tempo / Langfuse 等标准 APM。三类 span 映射:
+
+- **Agent 一次运行** → root span(复用 `agent_runs` 的 `trace_id` 关联)
+- **单次 LLM 调用** → `gen_ai` 子 span,遵循 [OpenTelemetry GenAI 语义约定](https://opentelemetry.io/docs/specs/semconv/gen-ai/)(`gen_ai.system` / `gen_ai.request.model` / `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` / `gen_ai.operation.name`),可被标准 APM 识别为一次模型调用
+- **TradingAgents 节点** → 子 span(复用节点级进度回调)
+
+**默认完全关闭**:不装依赖、不配 endpoint 时,导出层全程 no-op,不改变任何现有行为。
+
+**开启三步**:
+
+```bash
+# 1. 安装可选依赖
+pip install -r requirements-otel.txt
+
+# 2. 配置 OTLP 端点(指向你的 collector / APM)
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+export OTEL_SERVICE_NAME=panwatch   # 可选,默认 panwatch
+
+# 3. 正常启动;启动日志出现 "OTel 导出已启用" 即生效
+python server.py
+```
+
+**本地起一个 Jaeger 验证**:
+
+```bash
+docker run -d --name jaeger -p 16686:16686 -p 4318:4318 \
+  jaegertracing/all-in-one:latest
+# 触发任意 Agent 运行后,打开 http://localhost:16686 选 service=panwatch 查看 trace
+```
+
+Langfuse / Tempo 同理,把 `OTEL_EXPORTER_OTLP_ENDPOINT` 指向对应 OTLP 入口即可。
+
+</details>
+
 <details>
 <summary><b>发布（Docker 镜像）</b></summary>
 

frontend/package.json

@@ -3,6 +3,11 @@
   "private": true,
   "version": "0.1.0",
   "type": "module",
+  "packageManager": "pnpm@9.15.9",
+  "engines": {
+    "node": "24.14.0",
+    "pnpm": "9.15.9"
+  },
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",

frontend/packages/api/src/chat.ts

@@ -1,4 +1,5 @@
 import { fetchAPI } from './client'
+import { readSSE, type SSEEvent } from './sse'
 
 export interface ChatConversation {
   id: number
@@ -49,4 +50,105 @@ export const chatApi = {
     fetchAPI<{ questions: string[] }>(
       `/chat/suggested-questions?symbol=${encodeURIComponent(symbol)}&market=${encodeURIComponent(market)}`
     ),
+
+  sendMessageStream,
+}
+
+export interface ChatStreamCallbacks {
+  /** token 增量文本 */
+  onToken?: (text: string) => void
+  /** 模型开始调用工具（前端应清空当前 token 缓冲并展示"正在查询…"） */
+  onToolCallStart?: (info: { name: string; arguments: Record<string, unknown> }) => void
+  /** 工具执行完成 */
+  onToolResult?: (info: { name: string; ok: boolean; preview: string }) => void
+  /** 计划驱动(全面诊断持仓):计划生成/步骤推进/完成 */
+  onPlan?: (info: {
+    status: string
+    steps: { id: number; title: string; status: string }[]
+    current?: number
+  }) => void
+  /** 最终回答（已落库） */
+  onDone?: (msg: { message_id: number; content: string; created_at: string }) => void
+  /** AI 服务异常（服务端已把错误文案落库） */
+  onError?: (message: string) => void
+}
+
+const CHAT_STREAM_MAX_RECONNECTS = 3
+
+/**
+ * 流式发送消息（SSE）。
+ *
+ * - 首次连接 POST /chat/conversations/{id}/messages/stream；
+ * - meta 事件携带 stream_id，之后若连接中断（生成仍在服务端继续），
+ *   自动经 GET /chat/streams/{stream_id} + Last-Event-ID 续推；
+ * - 若首次连接直接失败（未收到任何事件），抛异常，调用方降级到非流式 sendMessage。
+ */
+async function sendMessageStream(
+  conversationId: number,
+  content: string,
+  callbacks: ChatStreamCallbacks,
+  signal?: AbortSignal
+): Promise<void> {
+  let streamId = ''
+  let lastEventId = 0
+  let finished = false
+
+  const handleEvent = (ev: SSEEvent) => {
+    if (ev.id > 0) lastEventId = ev.id
+    const d = ev.data || {}
+    switch (ev.event) {
+      case 'meta':
+        streamId = d.stream_id || ''
+        break
+      case 'token':
+        callbacks.onToken?.(d.text || '')
+        break
+      case 'tool_call_start':
+        callbacks.onToolCallStart?.({ name: d.name || '', arguments: d.arguments || {} })
+        break
+      case 'tool_result':
+        callbacks.onToolResult?.({ name: d.name || '', ok: !!d.ok, preview: d.preview || '' })
+        break
+      case 'plan':
+        callbacks.onPlan?.({ status: d.status || '', steps: d.steps || [], current: d.current })
+        break
+      case 'done':
+        finished = true
+        callbacks.onDone?.({
+          message_id: d.message_id || 0,
+          content: d.content || '',
+          created_at: d.created_at || '',
+        })
+        break
+      case 'error':
+        callbacks.onError?.(d.message || '未知错误')
+        break
+    }
+  }
+
+  await readSSE(`/chat/conversations/${conversationId}/messages/stream`, {
+    method: 'POST',
+    body: { content },
+    signal,
+    onEvent: handleEvent,
+  })
+
+  // 连接被中断但生成未结束 → 经续推端点接回（服务端缓冲全量事件）
+  let reconnects = 0
+  while (!finished && streamId && reconnects < CHAT_STREAM_MAX_RECONNECTS) {
+    if (signal?.aborted) return
+    reconnects += 1
+    try {
+      await readSSE(`/chat/streams/${streamId}`, {
+        signal,
+        lastEventId,
+        onEvent: handleEvent,
+      })
+    } catch {
+      // 退避后再试
+      await new Promise((r) => setTimeout(r, 1000 * reconnects))
+    }
+  }
+
+  if (!finished) throw new Error('流式回复未完成')
 }

frontend/packages/api/src/index.ts

@@ -1,4 +1,5 @@
 export * from './client'
+export * from './sse'
 export * from './types'
 export * from './stocks'
 export * from './insight'
@@ -15,3 +16,4 @@ export * from './paper-trading'
 export * from './chat'
 export * from './tradingagents'
 export * from './datasources'
+export * from './pats'

frontend/packages/api/src/pats.ts

@@ -0,0 +1,41 @@
+import { fetchAPI } from './client'
+
+/** 个人访问令牌(PAT)—— MCP 端点专用凭据 */
+export interface PatItem {
+  id: number
+  name: string
+  prefix: string
+  scopes: string[]
+  expires_at: string | null
+  last_used_at: string | null
+  revoked_at: string | null
+  created_at: string | null
+  revoked: boolean
+}
+
+/** 创建响应:额外带一次性明文 token */
+export interface PatCreated extends PatItem {
+  token: string
+}
+
+export interface CreatePatBody {
+  name?: string
+  scopes?: string[]
+  /** 过期天数;null = 永不过期 */
+  expires_in_days?: number | null
+}
+
+export const patsApi = {
+  list: () => fetchAPI<{ items: PatItem[] }>('/pats'),
+
+  create: (body: CreatePatBody) =>
+    fetchAPI<PatCreated>('/pats', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    }),
+
+  revoke: (id: number) =>
+    fetchAPI<{ ok: boolean; id: number }>(`/pats/${encodeURIComponent(String(id))}`, {
+      method: 'DELETE',
+    }),
+}