fanhuadesenlinnn/daily_stock_analysis
1
0
Fork 0
mirror of https://github.com/ZhuLinsen/daily_stock_analysis synced 2026-09-20 02:43:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add xAI Grok LiteLLM examples and Grok Bot integration notes (#2228)

Browse Source 
* docs: add xAI Grok LiteLLM examples and Grok Bot integration notes

* docs: link Grok Bot notes from SKILL, INDEX, and LiteLLM YAML

* docs: add Grok Bot index/openclaw pointers and restore SKILL analyzer_service path

* docs: add Grok Bot pointers in INDEX_EN and openclaw guide

* docs: prefer async Grok Bot analysis and poll market-review status

* docs: prefer async Grok Bot analysis and poll market-review status
This commit is contained in:
tseliangmin-star
2026-08-19 23:39:48 +08:00
committed by GitHub
parent 5d3e4e374a
commit 5d14873f17
8 changed files with 182 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
SKILL.md
View File

@@ -85,7 +85,6 @@ for result in results:
**参考:** [`analyze_stocks`](src/services/analyzer_service.py)
### 3. 执行大盘复盘
**描述:** 对整体市场进行复盘并返回一份报告。
@@ -111,3 +110,8 @@ if report:
```
**参考:** [`perform_market_review`](src/services/analyzer_service.py)
## 模型与外部 Bot
- 若把 **xAI Grok** 当作 DSA 分析模型：配置 `XAI_API_KEY` + `LITELLM_MODEL=xai/<官方模型ID>`（LiteLLM 直连，非托管渠道），并用 `python scripts/check_env.py --llm` 验证。示例见 [`docs/LLM_CONFIG_GUIDE.md`](docs/LLM_CONFIG_GUIDE.md)。
- 2026-08-11 上线的 **[Grok Bot](https://x.ai/bot)** 是另一条路径：它是带 Skills / Routines / MCP / computer use 的 AI teammate，应通过 HTTP 调用本仓库的 `analyze_stock` / REST API，而不是把 Bot 本身配成 LiteLLM provider。对接说明见 [`docs/grok-bot-integration.md`](docs/grok-bot-integration.md)。

6
docs/INDEX.md
View File

@@ -8,10 +8,10 @@
| --- | --- | --- |
| 快速了解项目能做什么 | [README](../README.md) | [完整配置与部署指南](full-guide.md) |
| 第一次把项目跑起来 | [小白客户端安装与配置](beginner-client-setup.md) | [完整配置与部署指南](full-guide.md) |
| 配置大模型渠道 | [LLM 配置指南](LLM_CONFIG_GUIDE.md) | [LLM 服务商配置指南](llm-providers.md) |
| 配置大模型渠道 | [LLM 配置指南](LLM_CONFIG_GUIDE.md) | [LLM 服务商配置指南](llm-providers.md)（含 xAI Grok 直连） |
| 配置推送通知 | [通知能力基线](notifications.md) | [完整配置与部署指南](full-guide.md) |
| 部署到服务器或云平台 | [部署指南](DEPLOY.md) | [云端 WebUI 部署](deploy-webui-cloud.md)、[Zeabur 部署](docker/zeabur-deployment.md) |
| 使用 Bot / IM 接入 | [Bot 命令与接入](bot-command.md) | [Bot 平台配置](bot/) |
| 使用 Bot / IM 接入 | [Bot 命令与接入](bot-command.md) | [Bot 平台配置](bot/)、[Grok Bot 集成](grok-bot-integration.md) |
| 排查运行问题 | [FAQ](FAQ.md) | [更新日志](CHANGELOG.md) |
| 处理数据源失败或降级 | [数据源稳定性与故障处理图示](data-source-stability.md) | [FAQ](FAQ.md) |
| 参与开发或提交 PR | [贡献指南](CONTRIBUTING.md) | [API 规格](architecture/api_spec.json) |
@@ -34,6 +34,7 @@
| [LLM 配置指南](LLM_CONFIG_GUIDE.md) | 大模型渠道、三层配置、Web 设置页和常见模型配置 |
| [LLM 服务商配置指南](llm-providers.md) | Provider 预设、Actions 映射、错误分类和诊断建议 |
| [LiteLLM YAML 示例](examples/litellm_config.example.yaml) | LiteLLM 多渠道配置示例 |
| [Grok Bot Skill 示例](examples/grok_bot/README.md) | 给 Grok Bot 粘贴的最小 Skill，调用现有 REST |
| [通知能力基线](notifications.md) | 企业微信、飞书、Telegram、Discord、Slack、邮件等通知渠道配置 |
| [Tushare 股票列表指南](TUSHARE_STOCK_LIST_GUIDE.md) | Tushare 股票列表相关配置和使用说明 |
@@ -49,6 +50,7 @@
| [分析上下文包契约、运行态消费与可见性](analysis-context-pack.md) | AnalysisContextPack 首版范围、字段质量状态、P1/P2 内部契约、P3 Prompt 摘要消费、P4 历史/API/Web 低敏可见性、P5 数据质量评分、P6 迁移回滚与源码锚点；完整指南补充 #1386 阶段感知分析、迁移与回滚入口 |
| [图片识别 Prompt](image-extract-prompt.md) | 图片识别股票信息的 Prompt 与使用边界 |
| [OpenClaw Skill 集成](openclaw-skill-integration.md) | OpenClaw / Skill 外部集成说明 |
| [Grok Bot 集成](grok-bot-integration.md) | 2026-08-11 Grok Bot（AI teammate）与 DSA REST / DecisionSignal / Skill 的对接边界 |
## 部署与打包

1
docs/INDEX_EN.md
View File

@@ -49,6 +49,7 @@ This is the entry point for project documentation. The README covers the project
| [Analysis Context Pack Contract, Runtime Consumption, And Visibility](analysis-context-pack.md) <sub><sub>![P6 Badge](https://img.shields.io/badge/P6-orange?style=flat)</sub></sub> (Chinese-only) | AnalysisContextPack first-scope boundaries, field quality states, P1/P2 internal contracts, P3 prompt-summary consumption, P4 history/API/Web low-sensitivity visibility, P5 data-quality scoring, and P6 migration/rollback notes, plus source anchors; the full guide adds #1386 market-phase analysis, migration, and rollback entry points |
| [Image Extraction Prompt](image-extract-prompt.md) <sub><sub>![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)</sub></sub> (Chinese-only) | Prompt and boundaries for extracting stock information from images |
| [OpenClaw Skill Integration](openclaw-skill-integration.md) <sub><sub>![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)</sub></sub> (Chinese-only) | OpenClaw / Skill external integration notes |
| [Grok Bot Integration](grok-bot-integration.md) <sub><sub>![P0 Badge](https://img.shields.io/badge/P0-green?style=flat)</sub></sub> (Chinese-only) | 2026-08-11 Grok Bot (AI teammate) vs LiteLLM `xai/` provider; HTTP / Skill / DecisionSignal consumption |
## Deployment And Packaging

7
docs/examples/grok_bot/README.md Normal file
View File

@@ -0,0 +1,7 @@
# Grok Bot Skill 示例
给 2026-08-11 [Grok Bot](https://x.ai/bot) 用的最小 Skill 包。只调用 DSA 已有 REST，不引入新 API、环境变量或 MCP server。
把 [`SKILL.md`](SKILL.md) 拷进 Bot 的 Skills 目录，设置 `DSA_BASE_URL`（例如 `http://127.0.0.1:8000`），并先让 DSA 以 `python main.py --serve-only` 或 Docker 长期运行。
完整边界、DecisionSignal Routine、认证限制见 [Grok Bot 集成](../../grok-bot-integration.md)。openclaw 用户看 [openclaw Skill](../../openclaw-skill-integration.md)，契约相同。

59
docs/examples/grok_bot/SKILL.md Normal file
View File

@@ -0,0 +1,59 @@
---
name: daily-stock-analysis
description: 调用 daily_stock_analysis API 做股票分析。当用户说「分析茅台」「analyze AAPL」「帮我看看 600519」或要大盘复盘时使用。优先用股票代码。
---
# daily_stock_analysis
本 Skill 供 Grok Bot（2026-08-11 AI teammate）使用。通过 HTTP 调用已部署的 DSA，不要把 Bot 配成 LiteLLM provider。
需要环境变量 `DSA_BASE_URL`（DSA API 根地址，无尾斜杠）。
## 何时使用
- 分析单只或多只股票
- 查询某股最新 DecisionSignal（早报 / 盯盘 Routine）
- 大盘复盘
## 工作流程
1. 提取股票代码：A股 6 位（`600519`）、港股 `hk00700`、美股 `AAPL`、台股 `.TW` / `.TWO`。只有中文名时先提示用户给代码，或使用常见映射（茅台 → `600519`）。
2. 需要完整分析时 POST `{DSA_BASE_URL}/api/v1/analysis/analyze`。**Routine 或预计超过 Bot HTTP 超时的分析，从一开始用异步**，不要先同步再改发异步：同步超时后服务端 `_handle_sync_analysis` 仍会继续跑且不进 `TaskQueue`，再发 `async_mode: true` 会绕过队列去重，重复计费和推送。
```json
{
"stock_code": "<code>",
"report_type": "detailed",
"force_refresh": true,
"async_mode": true
}
```
返回 202 + `task_id` 后轮询 `GET {DSA_BASE_URL}/api/v1/analysis/status/{task_id}`，直到 `status: completed`。完成报告在 `result.report`，不要读响应根上的 `report`。
仅当 Bot HTTP 超时 ≥300 秒、且用户在等单次同步结果时，才用 `async_mode: false`。同步超时后不要改发异步重跑；先查询该股是否已有进行中任务（409 / status），或读最新 DecisionSignal。
3. 只需最新建议、不要重跑分析时：`GET {DSA_BASE_URL}/api/v1/decision-signals/latest/{stock_code}`。
4. 大盘复盘：`POST {DSA_BASE_URL}/api/v1/analysis/market-review` 固定返回 202 + `task_id`，不是复盘正文。轮询同一条 status 接口，完成后读顶层 `market_review_report` 或 `market_review_payload`（不在 `result.report`）。
5. 健康检查失败先 `GET {DSA_BASE_URL}/api/health`。
## 如何呈现结果
- 同步分析：`report.summary.operation_advice`、`trend_prediction`、`analysis_summary`
- 异步分析：`result.report.summary.operation_advice`、`result.report.summary.trend_prediction`、`result.report.summary.analysis_summary`
- 结构化动作：`action` / `action_label`（`buy|add|hold|reduce|sell|watch|avoid|alert`）；异步时在 `result.report.summary`
- 计划：同步 `report.strategy.ideal_buy` / `stop_loss` / `take_profit`；异步 `result.report.strategy.*`
- 大盘复盘：`market_review_report`（文本）或 `market_review_payload`（结构化）
- 缺字段时回退 `operation_advice`；旧三态统计仍看 `decision_type`
- DecisionSignal 只展示建议，不下单、不调仓
## 错误
| 状态 | 处理 |
| --- | --- |
| 连接失败 | 检查 DSA 是否在跑、`DSA_BASE_URL` 是否正确 |
| 400 | 检查 `stock_code` |
| 409 | 该股正在分析，查已有 `existing_task_id` 的 status；不要另开一条分析 |
| 500 | 看 DSA 日志；确认 `LITELLM_MODEL` 与对应 Key（含可选 `XAI_API_KEY`） |
若 `ADMIN_AUTH_ENABLED=true`，当前 API 只认 Cookie，不认 Bearer。不要把 `XAI_API_KEY` 当作 DSA API 密钥。

7
docs/examples/litellm_config.example.yaml
View File

@@ -69,6 +69,13 @@ model_list:
# model: anthropic/claude-3-5-sonnet-20241022
# api_key: "os.environ/ANTHROPIC_API_KEY"
# --- xAI Grok (LiteLLM 直连 provider，不是托管渠道) ---
# 模型 ID 以 https://docs.x.ai/docs 为准；下面只是配置形状示例。
# - model_name: xai/grok-4.5
# litellm_params:
# model: xai/grok-4.5
# api_key: "os.environ/XAI_API_KEY"
# --- OpenRouter (聚合平台) ---
# - model_name: openai/meta-llama/llama-3-70b-instruct
# litellm_params:

97
docs/grok-bot-integration.md Normal file
View File

@@ -0,0 +1,97 @@
# Grok Bot 集成说明
本文说明 [daily_stock_analysis](https://github.com/ZhuLinsen/daily_stock_analysis)（DSA）如何对接 **2026-08-11** 上线的 [Grok Bot](https://x.ai/bot)（xAI 的 AI teammate 产品，不是普通 Grok 聊天）。
不新增 API、环境变量、provider 或运行时分支。Grok Bot 只消费现有 REST / Skill 契约。
## 先分清两条路径
| 路径 | 是什么 | 怎么配 | 不是什么 |
| --- | --- | --- | --- |
| **Grok 当分析模型** | LiteLLM 直连 `xai/*`，DSA 用 Grok 写报告 | `XAI_API_KEY` + `LITELLM_MODEL=xai/<官方模型ID>`，见 [LLM 配置指南](LLM_CONFIG_GUIDE.md) | 不是 Grok Bot 产品 |
| **Grok Bot 当队友** | 带持久云电脑、Skills、Routines、MCP/Connectors、computer use 的 teammate | Bot 调 DSA 已部署的 HTTP API，或在其电脑上跑 `python main.py` | 不要把 Bot 配成 `LITELLM_MODEL` |
两条路径可以同时用：DSA 用 `xai/grok-*` 做分析，Grok Bot 再来读报告 / `DecisionSignal`。
## 推荐对接顺序
1. 先让 DSA API 长期可访问：`python main.py --serve-only` 或 Docker。GitHub Actions 只做定时任务，不长期暴露 API。
2. 在 Grok Bot 里放一条 Skill（可直接改 [openclaw Skill](openclaw-skill-integration.md) 的 `SKILL.md` 示例，或用 [`docs/examples/grok_bot/SKILL.md`](examples/grok_bot/SKILL.md)）。
3. 需要盘中盯盘 / 早报时，用 Bot Routine 调 `DecisionSignal` 查询，而不是反复跑完整分析。
4. 只有 Bot 已经能稳定调通 HTTP 之后，才考虑把同一组接口挂到 MCP Connector。本仓库 **P0 不提供 MCP server**。
## Skill：触发个股分析
与 openclaw 相同的主入口。Bot / Routine **默认 `async_mode: true`**：
```http
POST {DSA_BASE_URL}/api/v1/analysis/analyze
Content-Type: application/json
{
"stock_code": "600519",
"report_type": "detailed",
"force_refresh": true,
"async_mode": true
}
```
- 异步：返回 202 + `task_id`，再 `GET /api/v1/analysis/status/{task_id}` 直到 `status: completed`。完成报告在 `result.report`（`TaskStatus.result` 是 `AnalysisResultResponse`），不要读响应根上的 `report`。
- 不要在同步超时后改发异步重跑。同步超时后服务端 `_handle_sync_analysis` 仍会继续跑且不进 `TaskQueue`，再发 `async_mode: true` 会绕过队列去重，造成重复 LLM 费用与推送。
- 仅当 HTTP 超时 ≥300 秒且用户在等单次结果时，才用 `async_mode: false`。同步响应的报告在根级 `report`。
- 健康检查：`GET /api/health`。
- 问股 Agent（需 `AGENT_MODE=true`）：`POST /api/v1/agent/chat`。
结果读取约定（与 openclaw Skill 一致，避免平行字段）：
- 自由文本：`report.summary.operation_advice`、`trend_prediction`、`analysis_summary`（异步前缀 `result.`）
- 结构化动作：可选 `action` / `action_label`（八态 `buy|add|hold|reduce|sell|watch|avoid|alert`）
- 旧历史缺字段时回退 `operation_advice`；旧三态统计仍以 `decision_type` 为准
Grok Bot Skill 正文见 [`docs/examples/grok_bot/SKILL.md`](examples/grok_bot/SKILL.md)，也可复用 [openclaw Skill](openclaw-skill-integration.md) 示例。环境变量统一为 `DSA_BASE_URL`。
## Skill：大盘复盘
`POST {DSA_BASE_URL}/api/v1/analysis/market-review` 固定返回 202 接受体 + `task_id`，不是复盘正文。请求体可传 `send_notification`、`region`。
轮询 `GET /api/v1/analysis/status/{task_id}` 直到 `status: completed`，从 `TaskStatus` 顶层读 `market_review_report` 或 `market_review_payload`（不在 `result.report`）。
## Routine：消费 DecisionSignal
不要让 Routine 每次都重跑分析。公开查询口：
| 用途 | 接口 |
| --- | --- |
| 某股最新 active 信号 | `GET /api/v1/decision-signals/latest/{stock_code}` |
| 分页筛选 | `GET /api/v1/decision-signals` |
| 后验统计 | `GET /api/v1/decision-signals/outcomes/stats` |
| 有用 / 无用反馈 | `GET/PUT /api/v1/decision-signals/{signal_id}/feedback` |
字段与生命周期见 [DecisionSignal 专题](decision-signals.md)。`DecisionSignal` 只记录建议，不执行下单或调仓。
需要给 Bot 低敏上下文时，用 [AnalysisContextPack](analysis-context-pack.md) 的公开 overview，不要把完整 `context_snapshot` 塞进 Skill 提示词。
## MCP / Connector / computer use
- **MCP**：把上表 REST 包成 tool 即可（`analyze_stock`、`get_latest_signal`、`market_review`）。本仓库暂不内置 MCP server，以免和 FastAPI 契约双源漂移。
- **Connectors**：Grok Bot 可登录飞书 / 邮件等；DSA 自己的通知渠道仍走 `.env` 里已有的 webhook，不必经 Bot 转发。
- **Computer use**：仅当 Bot 的云电脑里已经 clone 并配好 `.env` 时，才适合跑 `python main.py --stocks 600519,AAPL` 或 `python main.py --market-review`。默认仍推荐 HTTP，便于鉴权、超时和异步任务。
## 认证
默认 DSA API 无需认证。若 `ADMIN_AUTH_ENABLED=true`，当前只支持登录后的 Cookie，**不支持 Bearer Token**。Grok Bot 若只能带 `Authorization: Bearer`，先保持 API 不鉴权并限制监听网段，或在反代层做独立鉴权；不要把 `XAI_API_KEY` 当成 DSA API 的鉴权密钥。
## 明确不做的事
- 不把 Grok Bot 注册成 LiteLLM managed channel。
- 不新增 `GROK_BOT_*` 环境变量。
- 不复制一套平行 `DecisionSignal` / `AnalysisContextPack` schema。
- 不在本页承诺某个 `grok-*` 型号在当前 `litellm` 约束内一定可用。型号以 [xAI 文档](https://docs.x.ai/docs) 为准，并用 `python scripts/check_env.py --llm` 实测。
## 最小验收
1. DSA：`python scripts/check_env.py --config`；若走 xAI 模型再跑 `python scripts/check_env.py --llm`。
2. `GET {DSA_BASE_URL}/api/health` 成功。
3. Bot Skill 对一只真实代码（如 `AAPL` 或 `600519`）拿到 `operation_advice` 或 `action`（异步路径从 `result.report` 读）。
4. 大盘复盘能从 status 拿到 `market_review_report` 或 `market_review_payload`，而不是只拿到 202 accepted。
5. Routine 能读到 `GET /api/v1/decision-signals/latest/{stock_code}` 的 JSON，而无需重跑分析。

3
docs/openclaw-skill-integration.md
View File

@@ -6,6 +6,7 @@
- **集成方式**：openclaw Skill 通过 HTTP 调用 daily_stock_analysis（DSA）REST API
- **适用场景**：已部署 DSA API 服务，希望在 openclaw 对话中触发分析（如「帮我分析茅台」「analyze AAPL」）
- **同类消费方**：2026-08-11 上线的 [Grok Bot](https://x.ai/bot)（Skills / Routines / MCP / computer use）走同一套 REST 契约，不要另起平行 API。见 [Grok Bot 集成](grok-bot-integration.md)。
## 前置条件
@@ -173,7 +174,7 @@ curl -X POST {DSA_BASE_URL}/api/v1/agent/chat \
|------|----------|----------|
| 连接失败 | DSA 未运行、端口错误、防火墙 | 确认 `python main.py --serve-only` 已启动，检查 `DSA_BASE_URL` |
| 400 错误 | stock_code 格式错误或缺失 | 检查代码格式（见上文表格），确保请求体包含 `stock_code` |
| 500 错误 | AI 配置、数据源、网络问题 | 查看 DSA 日志，确认 GEMINI_API_KEY 等已配置 |
| 500 错误 | AI 配置、数据源、网络问题 | 查看 DSA 日志，确认 `LITELLM_MODEL` 与对应 Key（如 `GEMINI_API_KEY` / `XAI_API_KEY`）已配置 |
| Agent 400 | Agent 模式未启用 | 在 DSA 的 `.env` 中设置 `AGENT_MODE=true` |
| 分析超时 | 同步模式等待时间过长 | 增加 HTTP 客户端超时，或改用 `async_mode: true` 轮询状态 |