# bot/ — 企微 API 模式智能机器人

> **EXPERIMENTAL** — 本模块不在 daily-robots v1 开源支持范围内。  
> 主产品为根目录 **早报推送**（webhook），见 [README](../README.md)。  
> Bot 需独立 venv、企微 API 凭证、常驻进程；问题请自行排查或提 issue 标注 `bot`。

在企微里 @ 机器人即可：

- **快查**：`trending 10`、`hot 10`、`搜索 react`（本地 skills 数据，秒回）
- **截图预览**：`preview` / `截图`（基于 `CURSOR_CWD` 启动前端并发图）
- **通用任务**：任意自然语言需求，由 **Cursor Agent** 执行并回传结果

数据层与早报共用 [`shared/skills_data.py`](../shared/skills_data.py)。

---

## 1. 创建 API 模式机器人

1. [企业微信管理后台](https://work.weixin.qq.com/) → **安全与管理** → **管理工具** → **智能机器人** → **创建机器人**
2. 选择 **API 模式创建** → **使用长连接**
3. 记录 **Bot ID** 和 **Secret**（Secret 只显示一次，请立即保存）
4. 设置可见范围，将机器人 **添加到目标群** 或允许成员单聊

普通成员路径：工作台 → 智能机器人 → 手动创建 → API 模式 → 长连接

---

## 2. 启动本地服务

```powershell
cd path\to\daily-robots\bot
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
playwright install chromium
copy .env.example .env
# 编辑 .env：WECOM_BOT_ID / WECOM_BOT_SECRET / CURSOR_API_KEY
python main.py
```

服务需 **常驻运行**（本机、服务器或 Docker）。长连接模式下机器人进程须在线才能收消息。

---

## 3. 路由模式（ROUTING_MODE）

| 模式 | 行为 |
|------|------|
| `hybrid`（默认） | `trending`/`hot`/`搜索`/`详情` 走本地快查；其余 @ 消息交给 Cursor |
| `cursor` | 所有消息都交给 Cursor 执行 |
| `skills` | 仅本地 skills 快查 |

**Cursor 任务示例**（群里发送）：

```
@test 总结 trending top10，并推荐 3 个适合前端团队的 skill
@test 对比 mattpocock/skills 和 obra/superpowers 各有哪些热门 skill
@test 帮我写一段 npx skills add 的安装说明
```

Cursor 在本机 `CURSOR_CWD` 目录下运行（见 `bot/.env`）。复杂任务可能需要 1–10 分钟，流式消息会显示「Cursor 正在执行任务…」。

---

## 4. 前端截图预览（API 模式发图）

项目路径读取 `.env` 中的 **`CURSOR_CWD`**。机器人会：

1. 在 `CURSOR_CWD` 检测 `package.json`，若有 `dev` 脚本则执行 `PREVIEW_DEV_COMMAND`（默认 `npm run dev`）
2. 等待 `PREVIEW_PORT`（默认 `5173`）就绪，或用 `PREVIEW_URL` 直接访问
3. Playwright 打开页面并截图
4. 通过 API 模式 **上传图片 + 回复 image 消息** 到群

| 命令 | 说明 |
|------|------|
| `preview` / `截图` / `预览` | 访问 `http://127.0.0.1:5173/` 并截图 |
| `preview /login` | 指定路径 |
| `preview / 3000` | 指定端口 |
| `preview http://127.0.0.1:8080/` | 指定完整 URL |

`.env` 可选配置：

```env
CURSOR_CWD=.
PREVIEW_PORT=5173
PREVIEW_URL=http://127.0.0.1:5173/
PREVIEW_DEV_COMMAND=npm run dev
PREVIEW_STARTUP_TIMEOUT=120
```

---

## 4b. 网页操作（Playwright 步骤引擎）

支持三种方式定义操作流程，**无需改 Python 代码**：

**1. 自然语言（企微里直接说）**

```
@test 访问登录页，输入账号密码，点击登录后进入主页，点击智能体管理菜单然后截图
```

账号密码从 `.env` 读取（`{{PREVIEW_LOGIN_USER}}` / `{{PREVIEW_LOGIN_PASSWORD}}`），勿在群里发密码。

**2. 场景文件 YAML** — 见 `scenarios/`，触发：`@test browser <场景名>`

**3. 消息内 DSL** — 以 `browser:` 开头的多行步骤

支持的步骤：`goto` · `fill` · `click` · `wait` · `screenshot` · `press`

---

## 5. 快查命令

| 命令 | 说明 |
|------|------|
| `trending 10` / `趋势 10` | 近期增长榜 Top N（默认 10，最大 30） |
| `hot 10` / `实时 10` | 实时热度榜 |
| `all 10` / `总榜 10` | 历史总安装榜 |
| `搜索 react` / `search tdd` | 关键词搜索 |
| `详情 find-skills` | 单个 skill 详情 + 安装命令 |
| `preview` / `截图` | 启动 CURSOR_CWD 前端并截图发群 |
| `帮助` | 命令列表 |

---

## 6. 本地测试（无需企微凭证）

```powershell
cd path\to\daily-robots\bot
python -c "from skills_service import handle_command; print(handle_command('trending 5'))"
```

---

## 配置

| 文件 | 说明 |
|------|------|
| `bot/.env` | `WECOM_BOT_ID`、`WECOM_BOT_SECRET`、`CURSOR_API_KEY` 等 |
| `.env.example` | 模板 |

与根目录 `.env`（早报 webhook）**相互独立**，勿混用。