内容
# ABS 洞察力副驾驶（SQLite + FastAPI，Docker 便携版）
MCP 首席分析助手，用于 ABS 挑战辅导工作流程。
## 包含内容
- 单一后端服务：`Python + FastAPI + SQLite`
- 规范分析视图：
- `v_challenges_enriched`
- `v_team_kpis`
- `v_player_kpis`
- MCP 风格工具界面：
- `abs.run_query`
- `abs.challenge_strategy`
- `abs.player_report`
- `abs.weekly_summary`
- 默认使用这些工具的聊天端点
- 轻量级网页：
- 团队概览
- 球员视角
- 询问 ABS 副驾驶
- 每周报告端点，生成 Markdown + HTML 文档
- 包括执行摘要、KPI 快照、战术机会表、风险标志和下周行动计划
## 数据范围
- `abs_challenges.csv`：每行代表一个 ABS 挑战
- `pitches.csv`：ABS 启用游戏中的所有已调用投球
- `players.csv`：球员查找表
## 示例副驾驶问题
以下是教练、分析师或球员可能询问 ABS 洞察力副驾驶的几个示例：
- _"哪些捕手在低投球的挑战成功率最低？"_
- _"为 [球员姓名] 生成一份球员报告，重点关注他们的挑战倾向。"_
- _"球队上周有多少明显错误的判罚未提出挑战？"_
- _"显示奥斯汀王牌队按局计算的挑战成功率。"_
- _"是否有特定的裁判员经常对我们的击球手漏判？"_
- _"总结得梅因龙队在 ABS 挑战中的表现，并为下周提供可行的建议。"_
## 快速开始（本地）
```bash
uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
uvicorn app.main:app --reload
```
打开：
- `http://localhost:8000/` （首页）
- `http://localhost:8000/team`
- `http://localhost:8000/player`
- `http://localhost:8000/copilot`
- `http://localhost:8000/reports-view`
## 快速开始（Docker）
```bash
docker build -t abs-copilot .
docker run --rm -p 8000:8000 --env-file .env -v "$(pwd)/reports:/app/reports" abs-copilot
```
如果没有 `.env` 文件，请复制 `.env.example` 并根据需要填写值。LLM 变量是可选的。
## 环境变量
- `APP_DB_PATH` （默认值：容器中的 `/data/abs_insights.db`）
- `RESULT_ROW_LIMIT` （默认值：`200`）
- `REPORTS_DIR` （默认值：容器中的 `/app/reports`）
- `LLM_BASE_URL` （可选，OpenAI 兼容端点，例如 `https://generativelanguage.googleapis.com/v1beta/openai`）
- `LLM_API_KEY` （可选）
- `LLM_MODEL` （默认值：`gemini-3.1-flash-lite-preview`）
## 公共 HTTP 接口
- `POST /chat` → 答案 + 来源 + 支持统计 + 推荐操作
- `GET /dashboard/team/{team}`
- `GET /dashboard/player/{player_id}`
- `GET /dashboard/positions`
- `GET /dashboard/non-challenged`
- `GET /dashboard/challenge-usage`
- `GET /dashboard/officiating-proxy`
- `GET /dashboard/miss-locations`
- `POST /reports/weekly`
- `GET /reports/list`
- `GET /reports/content/{report_name}`
### MCP 服务器（默认）
- SSE MCP 端点：`http://localhost:8000/mcp/sse`
- MCP 消息端点：`http://localhost:8000/mcp/messages`
- 兼容别名：`/sse` 和 `/messages` （适用于从基本 URL 和旧版回退的客户端）
### 帮助端点（用于调试）
- `GET /api/mcp/tools`
- `POST /api/mcp/call`
### 核心 MCP 工具名称
- `abs_run_query`
- `abs_challenge_strategy`
- `abs_player_report`
- `abs_weekly_summary`
- `abs_position_accuracy`
- `abs_non_challenged_incorrect_calls`
- `abs_challenge_usage`
- `abs_officiating_quality_proxy`
- `abs_miss_location_analysis`
示例：
```bash
curl -s localhost:8000/api/mcp/call \
-X POST \
-H 'content-type: application/json' \
-d '{
"tool":"abs_challenge_strategy",
"arguments":{"filters":{"team_name":"Omaha Storm Chasers","role":"catcher"}}
}'
```
## 测试
```bash
uv run pytest
```
## 备注
- 分析访问仅限读取（`SELECT`/`WITH` 仅限；写入关键词被阻止）。
- 结果集受 `RESULT_ROW_LIMIT` 限制。
- 每周报告生成由端点触发（`POST /reports/weekly`），可以通过外部 cron/invoker 调度。
