\r \r

A股实时行情查询、自选股管理与价格监控\r

\r 所有命令须在项目根目录当前文档目录下执行。\r \r ---\r \r

配置接收目标（首次必须），这是后续监控异动发生后消息推送目标\r

\r target 解析优先级：调用时传入 > data/config.json 的 monitor_target > 报错退出。\r \r

python -c "\r
import config\r
config.set('monitor_target', 'user:ou_xxxx')\r
"\r
```\r
\r
ou_xxxx是用户的openId，配置持久化在 `data/config.json`，后续所有启动/重启自动读取。\r
\r
---\r
\r
## 查询行情\r
\r
### 按股票代码查询\r
\r
```bash\r
python -c "\r
import json\r
from quote import get_detail\r
print(json.dumps(get_detail('000001'), ensure_ascii=False, indent=2))\r
"\r
```\r
\r
### 按股票名称查询（名称唯一时）\r
\r
```bash\r
python -c "\r
import json\r
from quote import get_detail_by_name\r
print(json.dumps(get_detail_by_name('平安银行'), ensure_ascii=False, indent=2))\r
"\r
```\r
\r
若名称匹配多只股票，抛出 `ValueError` 并列出候选 → 询问用户后改用代码查询。\r
\r
### 名称模糊时先搜索\r
\r
```bash\r
python -c "\r
import json\r
from search import search_by_name\r
print(json.dumps(search_by_name('平安'), ensure_ascii=False, indent=2))\r
"\r
```\r
\r
取候选列表中的 `code`，再调用 `get_detail(code)`。\r
\r
### 向用户展示结果\r
\r
以易读格式回答，例如：\r
\r
> **平安银行（000001）** 当前价 **10.71 元**，今日 ▼ 1.56%（-0.17 元）。\r
> 今日区间 10.67 ~ 10.84，成交额 11.68 亿元，总市值 2078 亿元。\r
\r
---\r
\r
## 自选股管理\r
\r
自选股持久化在 `data/watchlist.json`，操作不自动启停监控，返回值中包含 `monitor_status` 供判断。\r
\r
### 查看自选股列表\r
\r
```bash\r
python -c "\r
import json\r
from watchlist import list_all\r
print(json.dumps(list_all(), ensure_ascii=False, indent=2))\r
"\r
```\r
\r
输出：`[{"code": "000001", "name": "平安银行"}, ...]`，空列表时为 `[]`。\r
\r
### 添加自选股\r
\r
```bash\r
python -c "\r
import json\r
from watchlist import add\r
print(json.dumps(add('平安银行'), ensure_ascii=False))\r
"\r
```\r
\r
返回示例：`{"code": "000001", "name": "平安银行", "monitor_status": "监控未启动"}`\r
\r
- 接受6位代码或精确名称；已存在则直接返回，不重复添加\r
- `monitor_status` 为 `"监控未启动"` 时，提示用户手动启动监控\r
\r
**名称不唯一时的处理流程：**\r
1. `add()` 内部调用 `get_detail_by_name()`，若抛出 `ValueError` 说明名称模糊\r
2. 先用 `search_by_name()` 列出候选，询问用户选择\r
3. 用户确认后改用6位代码添加：`add('000001')`\r
\r
### 删除自选股\r
\r
```bash\r
python -c "\r
import json\r
from watchlist import remove\r
print(json.dumps(remove('平安银行'), ensure_ascii=False))\r
"\r
```\r
\r
返回示例：`{"code": "000001", "name": "平安银行", "monitor_status": "监控已启动"}`\r
\r
未找到时返回 `null`。同样接受6位代码。\r
\r
### 清空自选股\r
\r
```bash\r
python -c "\r
import json\r
from watchlist import clear\r
print(json.dumps(clear(), ensure_ascii=False))\r
"\r
```\r
\r
返回示例：`{"cleared": 2, "monitor_status": "监控已启动"}`\r
\r
---\r
\r
## 股票价格监控\r
\r
监控进程读取 `data/watchlist.json`，每隔 10 秒查询一次，**仅在 A 股交易时段运行**，价格距上次告警偏离 ≥ 2% 时发送 openclaw 消息。**自选股操作不再自动启停进程，需手动管理。**\r
\r
### 查看监控进程状态\r
\r
```bash\r
python -c "\r
from monitor import is_running\r
print('运行中' if is_running() else '未运行')\r
"\r
```\r
\r
### 启动监控\r
\r
```bash\r
python -c "from monitor import start_monitor; start_monitor()"\r
```\r
\r
覆盖 target 或修改参数时：\r
\r
```bash\r
python -c "\r
from monitor import start_monitor\r
start_monitor(\r
    'user:ou_xxxx',   # 可选，不传则从配置文件读取\r
    interval=30,      # 查询间隔（秒），默认 10\r
    threshold=1.5,    # 触发告警的偏离幅度（%），默认 2.0\r
)\r
"\r
```\r
\r
输出示例：\r
```\r
[monitor] 监控子进程已启动  PID=12345  日志→ f:\stock\logs\monitor_20260304_153000.log\r
```\r
\r
### 停止监控\r
\r
```bash\r
python -c "from monitor import stop_monitor; stop_monitor()"\r
```\r
\r
### 重启监控\r
\r
```bash\r
python -c "from monitor import restart_monitor; restart_monitor()"\r
```\r
\r
### 告知用户结果\r
\r
向用户确认：已监控哪些股票（调用 `list_all()` 获取）、查询间隔（默认10秒）、触发条件（距上次告警价偏离 ≥ 2%，触发后以当前价为新基准）、告警方式（openclaw 消息推送，含今开价和距开盘涨幅）。\r
\r
---\r
\r
## 返回字段说明\r
\r
| 字段 | 说明 |\r
|------|------|\r
| `最新价` | 当前价格（元） |\r
| `涨跌幅` | 百分比，正数上涨、负数下跌 |\r
| `涨跌额` | 涨跌金额（元） |\r
| `今开` / `昨收` | 开盘价 / 昨日收盘价 |\r
| `最高` / `最低` | 今日区间 |\r
| `成交量` | 单位：手（100股/手） |\r
| `成交额` | 单位：元 |\r
| `总市值` | 单位：元，除以 1e8 得亿元 |\r
| `市盈率TTM` | 动态市盈率 |\r
| `52周最高` / `52周最低` | 年内区间 |\r
\r
---\r
\r
## 注意事项\r
\r
- 非交易时段返回最近交易日收盘数据\r
- 自选股文件变化时监控进程**自动热加载**，无需重启\r
- 子进程独立于父进程运行，日志同时输出到控制台和文件\r
- 日志写入 `logs/monitor_\x3Ctimestamp>.log`，单文件上限 2 MB，最多保留 5 个备份\r
- 查询失败（如雪球限速）时自动跳过本次，不影响监控持续运行\r