知了 - AI 话题追踪与资讯聚合

通过自然语言创建追踪话题，自动从全网聚合相关文章。使用 command/ 目录下的 CLI 工具调用 API。

配置 API Key

用户需前往知了网站 (https://zhiliao.news/) 注册，并在 API Key 申请页面 (https://open.zhiliao.news/) 获取 API Key。

方式一 — 环境变量（推荐）：

CODEBLOCK0

方式二 — 配置文件（永久保存）：

CODEBLOCK1

额度说明：每个 API Key 可免费创建 3 个话题，超出后需前往知了网站付费充值。

数据存储

所有数据保存在 ~/.zhiliao/ 目录（按需创建）：

• - config.json — API Key 和服务地址
• INLINECODE3 — 已创建的话题列表
• INLINECODE4 — 各话题的文章缓存
• INLINECODE5 — 创建话题的 session_id（幂等性）

工作流程

1. 创建话题（两步式：预览 + 确认）

采用「预览 → 用户选择 → 确认」的两步式流程创建话题：

1. 1. 了解需求：询问用户想追踪什么信息
2. 优化 prompt：帮助用户细化描述，使话题更精准：

- 模糊: "科技新闻" → 优化: "AI大模型技术进展，包括OpenAI、Google、Anthropic等公司的最新发布和研究突破" - 模糊: "股市" → 优化: "A股半导体板块行情分析，包括主要芯片公司股价走势和产业政策影响"

1. 3. 调用预览命令：获取待创建话题的预览和相关已有话题列表
2. 展示预览结果：向用户展示：

- 待创建的话题（名称、描述、封面图） - 相关的已有话题列表（可直接关注，无需重复创建）

1. 5. 用户选择：

- 创建新话题 → 调用确认命令 --action create - 关注已有话题 → 调用确认命令 --action subscribe --topic-id xxx - 不满意 → 调整 prompt 重新预览

会话隔离：每次对话开始时生成一个独立的 SCOPE（6位随机字符串），在本次对话中所有创建话题操作复用同一个 SCOPE。

CODEBLOCK2

也可以使用 --auto-create 跳过预览直接创建：

CODEBLOCK3

命令会自动处理：

• - Session ID 的创建和管理
• INLINECODE11 API 调用获取预览
• INLINECODE12 API 调用执行创建或关注
• 话题数据的本地保存

2. 获取话题文章

CODEBLOCK4

参数说明：

• - TOPIC_ID — 话题 ID（必填）
• INLINECODE14 — 每页数量（可选，默认 20）
• INLINECODE15 — 翻页游标（可选，用于获取下一页）

示例：
CODEBLOCK5

输出格式：Markdown，包含标题、原文链接、摘要、发布时间、核心观点。同时自动缓存到 ~/.zhiliao/articles/。

3. 查看话题列表

CODEBLOCK6

输出格式：Markdown 表格，包含话题 ID、名称、描述、创建时间、缓存状态。

4. 取消订阅话题

当用户不再需要追踪某个话题时，引导用户先通过 list-topics 查看话题 ID，再执行取消订阅：

CODEBLOCK7

取消订阅成功后，命令会自动清理本地话题记录和文章缓存。

5. 检查所有话题更新

CODEBLOCK8

遍历本地话题列表，对每个话题调用 API 获取最新文章（前 10 篇），汇总展示并更新缓存。

6. 定时任务（OpenClaw Cron）

每天早上8点日报：
CODEBLOCK9

每小时检查一次：
CODEBLOCK10

Cron 表达式格式：分钟 小时 日 月 星期

• - 0 8 * * * — 每天8:00
• INLINECODE20 — 每2小时
• INLINECODE21 — 每15分钟
• INLINECODE22 — 工作日9:00-17:00每小时

管理定时任务：
CODEBLOCK11

错误处理

• - 未配置 API Key：命令会提示配置方法
• API 返回错误：展示错误信息；若提示额度不足，引导用户付费充值
• 网络错误：命令会报错退出
• 话题文章为空：话题刚创建需要时间聚合，建议稍后再查

技术实现

所有命令使用 curl + jq + iconv 实现：

• - iconv -c -t UTF-8 — 清理 API 响应中的控制字符
• INLINECODE24 — 解析 JSON 和格式化输出
• 临时文件 — 避免 bash 变量保留控制字符
• INLINECODE25 — 避免 zsh 的 != 转义问题

命令列表

命令	功能	用法
INLINECODE27	预览话题	INLINECODE28
INLINECODE29

预览并自动创建 | ./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/ 目录，已添加执行权限。