Add project documentation and specs

docs/superpowers/plans/2026-03-20-langsmith-integration.md

@@ -0,0 +1,215 @@
+# LangSmith 集成实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 为 Jarvis 后端集成 LangSmith 追踪，实现调用追踪、对话历史管理和评估支持。
+
+**Architecture:** LangGraph 的 `compile()` 方法接受全局 Callbacks 参数，会自动将 Callback 传播到所有节点的 LLM 调用。只需在 Graph 编译时注入 `LangChainTracer`，即可覆盖 Master/Planner/Executor/Librarian/Analyst 所有 5 个节点和工具调用。
+
+**Tech Stack:** langsmith, langchain-core, langgraph
+
+---
+
+## 文件变更总览
+
+| 文件 | 职责 |
+|---|---|
+| `backend/pyproject.toml` | 添加 langsmith 依赖 |
+| `backend/.env.example` | 新增 LangSmith 环境变量 |
+| `backend/app/config.py` | 新增 3 个配置字段 |
+| `backend/app/config_tracing.py` | 新建，callback 工厂函数 |
+| `backend/app/agents/graph.py` | 修改 `create_agent_graph()` 支持 callbacks，合并全局 callbacks |
+
+---
+
+### Task 1: 添加 langsmith 依赖
+
+**Files:**
+- Modify: `backend/pyproject.toml`
+
+- [ ] **Step 1: 添加 langsmith 依赖**
+
+在 `dependencies` 数组中 `"langchain-ollama>=0.4.0",` 后添加：
+
+```toml
+    "langchain-ollama>=0.4.0",
+
+    # 可观测性
+    "langsmith>=0.1.0",
+```
+
+- [ ] **Step 2: 安装依赖**
+
+Run: `cd backend && uv sync`
+
+---
+
+### Task 2: 添加环境变量模板
+
+**Files:**
+- Modify: `backend/.env.example`
+
+- [ ] **Step 1: 在文件末尾添加 LangSmith 配置节**
+
+在 `# === 定时任务 ===` 节之前添加：
+
+```env
+# === LangSmith 可观测性 ===
+# 启用 LangSmith 追踪（可选）
+LANGSMITH_TRACING=false
+LANGSMITH_API_KEY=your-langsmith-api-key
+LANGSMITH_PROJECT=jarvis-agent
+```
+
+---
+
+### Task 3: Config 层添加 LangSmith 配置
+
+**Files:**
+- Modify: `backend/app/config.py`
+- Create: `backend/app/config_tracing.py` (callback 工厂函数)
+
+- [ ] **Step 1: 在 Settings 类中添加 3 个配置字段**
+
+在 `# === NAS 部署 ===` 节之前添加：
+
+```python
+    # === LangSmith 可观测性 ===
+    LANGSMITH_TRACING: bool = False
+    LANGSMITH_API_KEY: str = ""
+    LANGSMITH_PROJECT: str = "jarvis-agent"
+```
+
+- [ ] **Step 2: 创建 callback 工厂函数**
+
+创建新文件 `backend/app/config_tracing.py`：
+
+```python
+"""
+LangSmith Tracing 配置
+提供 Callback 工厂函数，用于 LangGraph 追踪
+"""
+
+from langchain_core.callbacks import LangChainTracer
+
+from app.config import settings
+
+
+def get_langsmith_callbacks() -> list:
+    """
+    根据配置返回 LangSmith Callback 列表
+    未启用时返回空列表
+    """
+    if not settings.LANGSMITH_TRACING:
+        return []
+
+    if not settings.LANGSMITH_API_KEY:
+        return []
+
+    return [
+        LangChainTracer(
+            project_name=settings.LANGSMITH_PROJECT,
+        )
+    ]
+```
+
+---
+
+### Task 4: 修改 Graph 接受 Callbacks
+
+**Files:**
+- Modify: `backend/app/agents/graph.py`
+
+- [ ] **Step 1: 修改 create_agent_graph() 签名**
+
+将函数签名从：
+
+```python
+def create_agent_graph():
+```
+
+改为：
+
+```python
+def create_agent_graph(callbacks: list | None = None):
+```
+
+- [ ] **Step 2: 将 callbacks 传给 compile()**
+
+将：
+
+```python
+    return graph.compile()
+```
+
+改为：
+
+```python
+    return graph.compile(callbacks=callbacks)
+```
+
+- [ ] **Step 3: 修改 get_agent_graph() 注入默认 callbacks**
+
+将：
+
+```python
+def get_agent_graph():
+    global _agent_graph
+    if _agent_graph is None:
+        _agent_graph = create_agent_graph()
+    return _agent_graph
+```
+
+改为：
+
+```python
+from app.config_tracing import get_langsmith_callbacks
+
+
+def get_agent_graph(callbacks: list | None = None):
+    """
+    获取编译好的 Agent 图（单例缓存）。
+
+    Callbacks 在首次编译时固定注入，后续调用忽略 callbacks 参数。
+    如需变更 Callbacks（如修改 LANGCHAIN_PROJECT），需重启服务。
+
+    Args:
+        callbacks: 可选的额外 Callbacks，会与全局 LangSmith Callbacks 合并
+    """
+    global _agent_graph
+    if _agent_graph is None:
+        langsmith_callbacks = get_langsmith_callbacks()
+        all_callbacks = (callbacks or []) + langsmith_callbacks
+        _agent_graph = create_agent_graph(callbacks=all_callbacks or None)
+    return _agent_graph
+```
+
+---
+
+### Task 5: 验证集成
+
+- [ ] **Step 1: 确认依赖安装**
+
+Run: `cd backend && uv sync`
+
+- [ ] **Step 2: 启动服务验证无报错**
+
+Run: `cd backend && uv run uvicorn app.main:app --reload --port 8000`
+
+- [ ] **Step 3: 配置 .env 并测试**
+
+在 `.env` 中添加：
+
+```env
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY=your-api-key
+LANGSMITH_PROJECT=jarvis-agent
+```
+
+发起一次 Agent 对话，访问 https://smith.langchain.com 确认 trace 出现。
+
+预期在 Dashboard 中看到：
+- 5 个节点（master/planner/executor/librarian/analyst）的执行记录
+- 每个节点的 LLM 输入/输出
+- 工具调用记录
+- Token 消耗统计