# 企微选题助手 — 对话 Agent 架构（旧方案）

> 使用 WebSocket 智能机器人 + DeepSeek function calling 的独立 Agent 模式。当前主方案是企微新版 AI 机器人 + MCP 插件（见主 SKILL.md），此文档保留作为参考和备选方案。

## 架构

```
企微群 @机器人 → aibot_ws_client (WebSocket 转发)
                    ↓
              conversation_agent (独立 Agent)
                    ├── DeepSeek API（对话 + function calling）
                    ├── we-mp-rss SQLite（文章查询）
                    └── JSON 文件会话管理（按 chat_id 隔离）
                    ↓
              回复到群（markdown，4096 字限制）
```

## 交互命令

用户通过 @机器人 触发以下功能：

| 用户输入 | 功能 |
|----------|------|
| `帮助` | 显示指令指南 |
| `今日` | 列出最近文章 |
| `1`~`N` | 查看文章 N 的选题角度推荐 |
| `生成1A` | 基于文章1角度A生成文案 |
| `https://mp.weixin.qq.com/s/xxx` | 核心摘要 + 各平台选题角度 |
| `https://... 小红书` | 指定平台分析 |

### URL 分析流程

`_analyze_article_url()`: 直接调用 DeepSeek（模型 `deepseek-chat`），不依赖 we-mp-rss 获取文章内容。AI 自行分析链接和标题，返回摘要 + 各平台选题角度 + 标题建议。

## DeepSeek Function Calling

```python
tools = [{
    "type": "function",
    "function": {
        "name": "get_today_articles",
        "description": "获取今日抓取的公众号文章列表，含标题、来源、链接",
        "parameters": {"type": "object", "properties": {}, "required": []}
    }
}]

# 请求时传 tools + tool_choice: "auto"
body = {"model": "deepseek-chat", "messages": [...], "tools": tools, "tool_choice": "auto"}

# 处理循环（最多 5 轮）
if msg.get("tool_calls"):
    for tc in msg["tool_calls"]:
        result = execute_tool(tc)  # 查数据库
        messages.append({"role": "tool", "tool_call_id": tc["id"], "content": result})
    continue  # 继续循环让模型处理结果
```

## 会话管理

- 按 `chat_id` 隔离，JSON 文件存储在 `state/conversations/{chat_id}.json`
- `MAX_HISTORY = 10`（10 轮对话），超出裁剪
- `SESSION_TTL = 3600`（1 小时无活动清理）
- 每条消息格式：`{"role": "user"|"assistant"|"tool", "content": "..."}`

## System Prompt 设计

角色定义 + 可用工具列表 + 回复风格。明确告诉模型何时调用工具、如何格式化回复。

## 常见问题

| 问题 | 原因 | 修复 |
|------|------|------|
| 第二轮回超时 | 工具返回的文章正文太长 | 限制 `content[:2000]`，降低 `max_tokens` |
| 回复被截断 | 企微 markdown 4096 限制 | `reply[:4000]` |
| 多轮记忆丢失 | session 文件路径或 TTL 问题 | 检查 `STATE_DIR` 和 `SESSION_TTL` |

## 企微群机器人 Webhook 直接推送

```bash
curl -s "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=<KEY>" \
  -H "Content-Type: application/json" \
  -d '{"msgtype":"markdown","markdown":{"content":"消息内容"}}'
```

- `msgtype: "text"` — 纯文本
- `msgtype: "markdown"` — Markdown（注意：企微 markdown 有 4096 字符限制）

## 当前订阅的公众号

| ID | 名称 |
|----|------|
| MP_WXS_3886864470 | 广东中职菌 |
| MP_WXS_3596295911 | 中职生 |