higress-group · lexburner · Feb 4, 2026
diff --git a/.qoder/skills/agent-session-monitor/QUICKSTART.md b/.qoder/skills/agent-session-monitor/QUICKSTART.md
@@ -0,0 +1,138 @@
+# Agent Session Monitor - Quick Start
+
+实时Agent对话观测程序，用于监控Higress访问日志，追踪多轮对话的token开销和模型使用情况。
+
+## 快速开始
+
+### 1. 运行Demo
+
+```bash
+cd example
+bash demo.sh
+```
+
+这将：
+- 解析示例日志文件
+- 列出所有session
+- 显示session详细信息（包括完整的messages、question、answer、reasoning、tool_calls）
+- 按模型和日期统计token开销
+- 导出FinOps报表
+
+### 2. 启动Web界面（推荐）
+
+```bash
+# 先解析日志生成session数据
+python3 main.py --log-path /var/log/higress/access.log --output-dir ./sessions
+
+# 启动Web服务器
+python3 scripts/webserver.py --data-dir ./sessions --port 8888
+
+# 浏览器访问
+open http://localhost:8888
+```
+
+Web界面功能：
+- 📊 总览所有session，按模型分组统计
+- 🔍 点击session ID下钻查看完整对话
+- 💬 查看每轮的messages、question、answer、reasoning、tool_calls
+- 💰 实时计算token开销和成本
+- 🔄 每30秒自动刷新
+
+### 3. 在Clawdbot对话中使用
+
+当用户询问当前会话token消耗时，生成观测链接：
+
+```
+你的当前会话ID: agent:main:discord:channel:1465367993012981988
+
+查看详情：http://localhost:8888/session?id=agent:main:discord:channel:1465367993012981988
+
+点击可以看到：
+✅ 完整对话历史（每轮messages）
+✅ Token消耗明细
+✅ 工具调用记录
+✅ 成本统计
+```
+
+### 4. 使用CLI查询（可选）
+
+```bash
+# 查看session详细信息
+python3 scripts/cli.py show <session-id>
+
+# 列出所有session
+python3 scripts/cli.py list
+
+# 按模型统计
+python3 scripts/cli.py stats-model
+
+# 导出报表
+python3 scripts/cli.py export finops-report.json
+```
+
+## 核心功能
+
+✅ **完整对话追踪**：记录每轮对话的完整messages、question、answer、reasoning、tool_calls  
+✅ **Token开销统计**：区分input/output/reasoning/cached token，实时计算成本  
+✅ **Session聚合**：按session_id关联多轮对话  
+✅ **Web可视化界面**：浏览器访问，总览+下钻查看session详情  
+✅ **实时URL生成**：Clawdbot可根据当前会话ID生成观测链接  
+✅ **FinOps报表**：导出JSON/CSV格式的成本分析报告  
+
+## 日志格式要求
+
+Higress访问日志需要包含ai_log字段（JSON格式），示例：
+
+```json
+{
+  "__file_offset__": "1000",
+  "timestamp": "2026-02-01T09:30:15Z",
+  "ai_log": "{\"session_id\":\"sess_abc\",\"messages\":[...],\"question\":\"...\",\"answer\":\"...\",\"input_token\":250,\"output_token\":160,\"model\":\"Qwen3-rerank\"}"
+}
+```
+
+ai_log字段支持的属性：
+- `session_id`: 会话标识（必需）
+- `messages`: 完整对话历史
+- `question`: 当前轮次问题
+- `answer`: AI回答
+- `reasoning`: 思考过程（DeepSeek等模型）
+- `tool_calls`: 工具调用列表
+- `input_token`: 输入token数
+- `output_token`: 输出token数
+- `model`: 模型名称
+- `response_type`: 响应类型
+
+## 输出目录结构
+
+```
+sessions/
+├── agent:main:discord:1465367993012981988.json
+└── agent:test:discord:9999999999999999999.json
+```
+
+每个session文件包含：
+- 基本信息（创建时间、更新时间、模型）
+- Token统计（总输入、总输出、总reasoning、总cached）
+- 对话轮次列表（每轮的完整messages、question、answer、reasoning、tool_calls）
+
+## 常见问题
+
+**Q: 如何在Higress中配置session_id header？**  
+A: 在ai-statistics插件中配置`session_id_header`，或使用默认header（x-openclaw-session-key、x-clawdbot-session-key等）。详见PR #3420。
+
+**Q: 支持哪些模型的pricing？**  
+A: 目前支持Qwen、DeepSeek、GPT-4、Claude等主流模型。可以在main.py的TOKEN_PRICING字典中添加新模型。
+
+**Q: 如何实时监控日志文件变化？**  
+A: 直接运行main.py即可，程序使用定时轮询机制（每秒自动检查一次），无需安装额外依赖。
+
+**Q: CLI查询速度慢？**  
+A: 大量session时，可以使用`--limit`限制结果数量，或按条件过滤（如`--sort-by cost`只查看成本最高的session）。
+
+## 下一步
+
+- 集成到Higress FinOps Dashboard
+- 支持更多模型的pricing
+- 添加趋势预测和异常检测
+- 支持多数据源聚合分析
diff --git a/.qoder/skills/agent-session-monitor/README.md b/.qoder/skills/agent-session-monitor/README.md
@@ -0,0 +1,71 @@
+# Agent Session Monitor
+
+Real-time agent conversation monitoring for Clawdbot, designed to monitor Higress access logs and track token usage across multi-turn conversations.
+
+## Features
+
+- 🔍 **Complete Conversation Tracking**: Records messages, question, answer, reasoning, tool_calls for each turn
+- 💰 **Token Usage Statistics**: Distinguishes input/output/reasoning/cached tokens, calculates costs in real-time
+- 🌐 **Web Visualization**: Browser-based UI with overview and drill-down into session details
+- 🔗 **Real-time URL Generation**: Clawdbot can generate observation links based on current session ID
+- 🔄 **Log Rotation Support**: Automatically handles rotated log files (access.log, access.log.1, etc.)
+- 📊 **FinOps Reporting**: Export usage data in JSON/CSV formats
+
+## Quick Start
+
+### 1. Run Demo
+
+```bash
+cd example
+bash demo.sh
+```
+
+### 2. Start Web UI
+
+```bash
+# Parse logs
+python3 main.py --log-path /var/log/higress/access.log --output-dir ./sessions
+
+# Start web server
+python3 scripts/webserver.py --data-dir ./sessions --port 8888
+
+# Access in browser
+open http://localhost:8888
+```
+
+### 3. Use in Clawdbot
+
+When users ask "How many tokens did this conversation use?", you can respond with:
+
+```
+Your current session statistics:
+- Session ID: agent:main:discord:channel:1465367993012981988
+- View details: http://localhost:8888/session?id=agent:main:discord:channel:1465367993012981988
+
+Click to see:
+✅ Complete conversation history
+✅ Token usage breakdown per turn
+✅ Tool call records
+✅ Cost statistics
+```
+
+## Files
+
+- `main.py`: Background monitor, parses Higress access logs
+- `scripts/webserver.py`: Web server, provides browser-based UI
+- `scripts/cli.py`: Command-line tools for queries and exports
+- `example/`: Demo examples and test data
+
+## Dependencies
+
+- Python 3.8+
+- No external dependencies (uses only standard library)
+
+## Documentation
+
+- `SKILL.md`: Main skill documentation
+- `QUICKSTART.md`: Quick start guide
+
+## License
+
+MIT