zhiliao

# 知了 - AI 话题追踪与资讯聚合 通过自然语言创建追踪话题，自动从全网聚合相关文章。使用 `command/` 目录下的 CLI 工具调用 API。 ## 配置 API Key 用户需前往知了网站 (https://zhiliao.news/) 注册，并在 API Key 申请页面 (https://open.zhiliao.news/) 获取 API Key。 **方式一 — 环境变量（推荐）**： ```bash export ZHILIAO_API_KEY="your-api-key-here" ``` **方式二 — 配置文件（永久保存）**： ```bash mkdir -p ~/.zhiliao echo '{"apiKey":"your-api-key-here","baseUrl":"http://api-public.zhiliao.news"}' > ~/.zhiliao/config.json ``` **额度说明**：每个 API Key 可免费创建 3 个话题，超出后需前往知了网站付费充值。 ## 数据存储 所有数据保存在 `~/.zhiliao/` 目录（按需创建）： - `config.json` — API Key 和服务地址 - `topics.json` — 已创建的话题列表 - `articles/<topic_id>.json` — 各话题的文章缓存 - `sessions/<scope>.json` — 创建话题的 session_id（幂等性） ## 工作流程 ### 1. 创建话题（两步式：预览 + 确认） 采用「预览 → 用户选择 → 确认」的两步式流程创建话题： 1. **了解需求**：询问用户想追踪什么信息 2. **优化 prompt**：帮助用户细化描述，使话题更精准： - 模糊: "科技新闻" → 优化: "AI大模型技术进展，包括OpenAI、Google、Anthropic等公司的最新发布和研究突破" - 模糊: "股市" → 优化: "A股半导体板块行情分析，包括主要芯片公司股价走势和产业政策影响" 3. **调用预览命令**：获取待创建话题的预览和相关已有话题列表 4. **展示预览结果**：向用户展示： - 待创建的话题（名称、描述、封面图） - 相关的已有话题列表（可直接关注，无需重复创建） 5. **用户选择**： - 创建新话题 → 调用确认命令 `--action create` - 关注已有话题 → 调用确认命令 `--action subscribe --topic-id xxx` - 不满意 → 调整 prompt 重新预览 **会话隔离**：每次对话开始时生成一个独立的 `SCOPE`（6位随机字符串），在本次对话中所有创建话题操作复用同一个 `SCOPE`。 ```bash # 对话开始时生成 SCOPE（后续复用） SCOPE=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-z0-9' | head -c 6) # Step 1: 预览话题（返回 JSON，包含 session_id、created_topic、related_topics） <skill-path>/command/create-topic.sh "优化后的PROMPT" "$SCOPE" # Step 2a: 确认创建新话题 <skill-path>/command/create-topic.sh --confirm --session-id "SESSION_ID" --action create # Step 2b: 或关注已有话题 <skill-path>/command/create-topic.sh --confirm --session-id "SESSION_ID" --action subscribe --topic-id "TOPIC_ID" ``` 也可以使用 `--auto-create` 跳过预览直接创建： ```bash <skill-path>/command/create-topic.sh "优化后的PROMPT" "$SCOPE" --auto-create ``` 命令会自动处理： - Session ID 的创建和管理 - `/generate` API 调用获取预览 - `/confirm` API 调用执行创建或关注 - 话题数据的本地保存 ### 2. 获取话题文章 ```bash <skill-path>/command/fetch-articles.sh TOPIC_ID [LIMIT] [CURSOR] ``` 参数说明： - `TOPIC_ID` — 话题 ID（必填） - `LIMIT` — 每页数量（可选，默认 20） - `CURSOR` — 翻页游标（可选，用于获取下一页） 示例： ```bash # 获取前 20 篇文章 <skill-path>/command/fetch-articles.sh 69afe54d037de4f01d67b756 # 获取前 10 篇 <skill-path>/command/fetch-articles.sh 69afe54d037de4f01d67b756 10 # 翻页（使用上次返回的 cursor） <skill-path>/command/fetch-articles.sh 69afe54d037de4f01d67b756 20 "1773390505_2" ``` 输出格式：Markdown，包含标题、原文链接、摘要、发布时间、核心观点。同时自动缓存到 `~/.zhiliao/articles/`。 ### 3. 查看话题列表 ```bash # 列出所有话题 <skill-path>/command/list-topics.sh # 查看单个话题详情及缓存文章 <skill-path>/command/list-topics.sh TOPIC_ID ``` 输出格式：Markdown 表格，包含话题 ID、名称、描述、创建时间、缓存状态。 ### 4. 取消订阅话题 当用户不再需要追踪某个话题时，引导用户先通过 `list-topics` 查看话题 ID，再执行取消订阅： ```bash # 查看话题列表，获取 TOPIC_ID <skill-path>/command/list-topics.sh # 取消订阅 <skill-path>/command/unsubscribe-topic.sh TOPIC_ID ``` 取消订阅成功后，命令会自动清理本地话题记录和文章缓存。 ### 5. 检查所有话题更新 ```bash <skill-path>/command/check-articles.sh ``` 遍历本地话题列表，对每个话题调用 API 获取最新文章（前 10 篇），汇总展示并更新缓存。 ### 6. 定时任务（OpenClaw Cron） **每天早上8点日报**： ```bash openclaw cron add --cron "0 8 * * *" --isolated --prompt "运行知了文章检查: <skill-path>/command/check-articles.sh" ``` **每小时检查一次**： ```bash openclaw cron add --cron "0 * * * *" --isolated --prompt "运行知了文章检查: <skill-path>/command/check-articles.sh" ``` **Cron 表达式格式**：`分钟 小时 日 月 星期` - `0 8 * * *` — 每天8:00 - `0 */2 * * *` — 每2小时 - `*/15 * * * *` — 每15分钟 - `0 9-17 * * 1-5` — 工作日9:00-17:00每小时 **管理定时任务**： ```bash openclaw cron list # 查看所有任务 openclaw cron remove <jobId> # 删除任务 ``` ## 错误处理 - **未配置 API Key**：命令会提示配置方法 - **API 返回错误**：展示错误信息；若提示额度不足，引导用户付费充值 - **网络错误**：命令会报错退出 - **话题文章为空**：话题刚创建需要时间聚合，建议稍后再查 ## 技术实现 所有命令使用 **curl + jq + iconv** 实现： - `iconv -c -t UTF-8` — 清理 API 响应中的控制字符 - `jq` — 解析 JSON 和格式化输出 - 临时文件 — 避免 bash 变量保留控制字符 - `select(.field == $value | not)` — 避免 zsh 的 `!=` 转义问题 ## 命令列表 | 命令 | 功能 | 用法 | |------|------|------| | `create-topic` | 预览话题 | `./create-topic.sh "描述" [SCOPE]` | | `create-topic` | 预览并自动创建 | `./create-topic.sh "描述" [SCOPE] --auto-create` | | `create-topic` | 确认创建/关注 | `./create-topic.sh --confirm --session-id ID --action create\|subscribe [--topic-id ID]` | | `fetch-articles` | 获取文章 | `./fetch-articles.sh TOPIC_ID [LIMIT] [CURSOR]` | | `list-topics` | 查看话题列表 | `./list-topics.sh [TOPIC_ID]` | | `unsubscribe-topic` | 取消订阅话题 | `./unsubscribe-topic.sh TOPIC_ID` | | `check-articles` | 检查所有话题更新 | `./check-articles.sh` | 所有命令位于 `command/` 目录，已添加执行权限。