daily-robots/README.md

# skills-hot-daily

Skills / GitHub 早报推送 + 企微对话机器人（同一仓库、两套企微接入）。

## 项目结构

```
skills-hot-daily/
├── README.md
├── .env.example              # 早报 webhook、GitHub 等
├── requirements.txt          # 早报 Python 依赖
├── run-daily.ps1             # 生成 + 推送一条龙
├── send-wecom.ps1            # 仅推送
├── daily/                    # 早报 Python 包
│   ├── __main__.py           # python -m daily [generate|push]
│   ├── config.py
│   ├── generate.py
│   ├── report_data.py        # JSON 中间层
│   ├── cursor_editor.py      # Cursor 编辑层
│   ├── llm_client.py
│   ├── localize.py           # 仅中文化（Tier A）
│   ├── format_wecom.py
│   ├── webhook.py
│   ├── news/                 # 国际 AI 时讯 RSS
│   │   ├── feeds.py
│   │   └── fetch.py
│   └── github/
│       ├── auth.py
│       ├── search.py
│       └── trending.py
├── output/                   # YYYY-MM-DD.md / .wecom.md / .data.json / .editorial.json
├── skills/daily-editor/      # 早报 Cursor 编辑 Skill
│   └── SKILL.md
├── logs/
├── .cache/
└── bot/                      # 企微 API 模式对话机器人（独立 venv）
    ├── main.py
    ├── skills_service.py
    └── scenarios/
```

| 模块 | 配置文件 | 启动方式 |
|------|----------|----------|
| **早报推送** | 根目录 `.env`（`WECOM_WEBHOOK_KEY` 等） | `.\run-daily.ps1` |
| **对话 Bot** | `bot/.env`（`WECOM_BOT_ID` / `SECRET` 等） | `cd bot` → `python main.py` |

---

## 一、早报推送

```powershell
cd d:\LY\test\tech\skills-hot-daily
pip install -r requirements.txt
copy .env.example .env
.\run-daily.ps1
```

- 生成：`output/YYYY-MM-DD.md`（完整版）、`output/YYYY-MM-DD.wecom.md`（企微短版）
- 仅生成：`.\run-daily.ps1 -SkipPush`
- 仅推送：`python -m daily push output\2026-06-25.wecom.md`

**Webhook 配置**：企微群 → 群机器人 → 添加，将 `key=` 后的值写入项目根 `.env`：

```env
WECOM_WEBHOOK_KEY=your-key
```

**GitHub 数据源**（见 `.env.example`）：

| 来源 | 说明 |
|------|------|
| GitHub Trending | `GITHUB_TRENDING_MODE=scrape` 或 `api` |
| 新兴 / Topic | Search API，需 `GITHUB_TOKEN` |
| Release | 可选 `GITHUB_REPOS=owner/repo` |

**国际 AI 时讯**（RSS，见 `daily/news/feeds.py`）：

| 类别 | 覆盖 |
|------|------|
| 厂商官方 | Anthropic、OpenAI、Google、Meta、Microsoft、Mistral、Cursor 等 |
| Agent / LLM 开发者 | LangChain、LlamaIndex、Hugging Face、Copilot 等 |
| 综合科技媒体 | The Verge、TechCrunch、Ars、Wired、MIT TR 等 |
| Newsletter | Ben's Bites、Latent Space、Simon Willison、TLDR AI 等 |
| 研究 / 论文 | arXiv cs.CL/AI/LG、HF Papers |
| 社区讨论 | HN、Reddit r/LocalLLaMA / ClaudeAI / ML 等 |

环境变量：`DAILY_AI_NEWS=1` · `DAILY_AI_NEWS_HOURS=72` · `DAILY_WECOM_AI_NEWS=8`

### 生成架构（Tier B · Cursor 编辑层）

早报默认走 **Python 抓取 + 模板渲染**；可选开启 Cursor 做「编辑」：

```
抓取数据 → output/日期.data.json → Cursor 读 Skill 写 editorial → 模板填字 → .md / .wecom.md
```

| 文件 | 说明 |
|------|------|
| `output/YYYY-MM-DD.data.json` | 结构化榜单（供 LLM 输入） |
| `output/YYYY-MM-DD.editorial.json` | Cursor 输出的主题、速览、中文描述 |
| `skills/daily-editor/SKILL.md` | 编辑规范（语气、JSON 格式） |

```env
# 开启 Tier B（需 CURSOR_API_KEY 或 DAILY_LLM_API_KEY）
DAILY_CURSOR_EDITOR=1
```

- 开启后：**一次 LLM 调用** 生成 `theme_line` + `highlights` + 全部中文描述
- 关闭时（默认）：规则主题 + `DAILY_ZH_DESC` 仅中文化描述
- LLM 失败自动回退规则模式，不影响推送

### 生成架构（Agent 工作流 · 推荐）

若觉得模板版「榜单堆砌」不友好，可改用 **Agent 三步流水线**：

```
Python 抓取 → Step1 趋势分析 → Step2 叙事写稿 → Python 分条推送企微
              (.trends.json)    (.wecom.md)
```

| 模式 | 环境变量 | 企微版风格 |
|------|----------|------------|
| `classic`（默认） | — | 分区榜单 + 模板 |
| `editor` | `DAILY_CURSOR_EDITOR=1` | 模板 + LLM 中文化 |
| `agent` | `DAILY_REPORT_MODE=agent` | **导语 + 信号 + 精选**，全中文叙述 |

```env
DAILY_REPORT_MODE=agent
DAILY_CURSOR_CWD=d:\LY\diy\skills-hot-daily   # 早报 LLM 工作目录（与 bot 的 CURSOR_CWD 独立）
```

| 文件 | 说明 |
|------|------|
| `output/YYYY-MM-DD.trends.json` | Step1 趋势分析结果 |
| `skills/daily-agent/SKILL.md` | Agent 工作流规范 |

- 完整版 `YYYY-MM-DD.md` 仍为数据表格归档；企微版由 Agent 直接写 Markdown
- Agent 失败自动回退 `classic`，不影响 `run-daily.ps1`

定时推送：Windows 任务计划程序或 `/loop 1d` 执行 `run-daily.ps1`。

---

## 二、可对话 Skills 助手（企业微信智能机器人）

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

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

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

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

### 2. 启动本地服务

```powershell
cd d:\LY\test\tech\skills-hot-daily\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` 目录下运行，默认 `d:\LY\test\tech`。复杂任务可能需要 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=d:\LY\test\tech
PREVIEW_PORT=5173
PREVIEW_URL=http://127.0.0.1:5173/
PREVIEW_DEV_COMMAND=npm run dev
PREVIEW_STARTUP_TIMEOUT=120
```

若 `CURSOR_CWD` 下暂无前端项目，可先手动启动 dev server，或设置 `PREVIEW_URL` 指向已运行地址。

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

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

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

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

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

**2. 场景文件 YAML**

`bot/scenarios/xiaobao-agent-manage.yaml` 示例：

```yaml
name: xiaobao-agent-manage
steps:
  - goto: /login
  - fill:
      field: 账号
      value: "{{PREVIEW_LOGIN_USER}}"
  - fill:
      field: 密码
      value: "{{PREVIEW_LOGIN_PASSWORD}}"
  - click: 登录
  - wait:
      url: "**/app/**"
  - click: 智能体管理
  - wait: 1500
  - screenshot
```

触发：`@test browser xiaobao-agent-manage`

场景搜索路径：`bot/scenarios/`、`CURSOR_CWD/.browser-scenarios/`、环境变量 `BROWSER_SCENARIOS_DIR`。

**3. 消息内 DSL**

```
browser:
  goto /login
  fill 账号 {{PREVIEW_LOGIN_USER}}
  fill 密码 {{PREVIEW_LOGIN_PASSWORD}}
  click 登录
  click 智能体管理
  screenshot
```

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

`.env` 登录与场景配置：

```env
PREVIEW_LOGIN_USER=test_account
PREVIEW_LOGIN_PASSWORD=your_password
# BROWSER_DEFAULT_SCENARIO=xiaobao-agent-manage
```

### 5. 支持的快查命令

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

自然语言（非显式快查命令）会交给 **Cursor** 处理，例如 `@test 查 trending 并写推荐` 。

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

```powershell
cd d:\LY\test\tech\skills-hot-daily\bot
python -c "from skills_service import handle_command; print(handle_command('trending 5'))"
```

---

## 其他推送方案

| 方案 | 适用场景 | 复杂度 |
|------|----------|--------|
| **群机器人 webhook** | 推送到固定群 | 低 |
| **应用消息 API** | 推送给指定成员/部门 | 中（需 corp_id、secret、agent_id） |
| **邮件 + 企业微信邮箱** | 已有 SMTP | 中 |
| **PushPlus / Server酱** | 个人微信中转 | 低（第三方） |

### 应用消息 API（简要）

适合「推送给某个人」而非群聊。需在 [企业微信管理后台](https://work.weixin.qq.com/) 创建自建应用，调用：

`POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=TOKEN`

消息体支持 `text` / `markdown` / `news` 等。需先 `gettoken` 再发消息，并维护 access_token 缓存。

---

## 注意事项

- Webhook **不要提交到 Git**，只用环境变量
- 企业微信 markdown 为**子集**（不支持完整 GitHub 表格语法时可改为文本列表）
- 单条消息约 **4096 字节** 上限，`send-wecom.ps1` 已做截断