zhiliao（zhiliao 效率）

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

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

配置 API Key

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

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

export ZHILIAO_API_KEY="your-api-key-here"

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

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股半导体板块行情分析，包括主要芯片公司股价走势和产业政策影响"

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

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

1. 用户选择：

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

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

# 对话开始时生成 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 跳过预览直接创建：

<skill-path>/command/create-topic.sh "优化后的PROMPT" "$SCOPE" --auto-create

命令会自动处理：

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

2. 获取话题文章

<skill-path>/command/fetch-articles.sh TOPIC_ID [LIMIT] [CURSOR]

参数说明：

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

示例：

# 获取前 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. 查看话题列表

# 列出所有话题
<skill-path>/command/list-topics.sh

# 查看单个话题详情及缓存文章
<skill-path>/command/list-topics.sh TOPIC_ID

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

4. 取消订阅话题

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

# 查看话题列表，获取 TOPIC_ID
<skill-path>/command/list-topics.sh

# 取消订阅
<skill-path>/command/unsubscribe-topic.sh TOPIC_ID

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

5. 检查所有话题更新

<skill-path>/command/check-articles.sh

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

6. 定时任务（OpenClaw Cron）

每天早上8点日报：

openclaw cron add --cron "0 8 * * *" --isolated --prompt "运行知了文章检查: <skill-path>/command/check-articles.sh"

每小时检查一次：

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每小时

管理定时任务：

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 的 != 转义问题

命令列表

所有命令位于 command/ 目录，已添加执行权限。