Smart Keepalive | 智能 Keepalive

Description: 定时抓取资讯素材并自动发送「保活简报 keepalive」（双关 keepalive + 资讯简报），默认走 OpenClaw CLI；也支持 Hermes/其他环境通过自定义命令接入发送与润色（KEEPALIVE_AGENT_COMMAND / KEEPALIVE_SEND_COMMAND），含可选作息附录与 launchd/cron 定时部署辅助。

何时读本文： 用户要配置/调试 OpenClaw 定时 keepalive、飞书或微信定时消息、smart-keepalive.py / smart-keepalive.sh、资讯简报、prompts/、--doctor / --install-launchd / --install-cron。

职责划分（SKILL.md / 脚本 / 提示词）

• 原则：能写在提示词里指导模型的，不写进 Python；必须在无模型时完成的（抓取、随机、写文件），不写进 SKILL 当「假实现」。
• 脚本只做：拉取素材 → 填模板变量 →（默认）openclaw agent 生成正文 /（可选）KEEPALIVE_AGENT_COMMAND 自定义润色 →（默认）openclaw message send /（可选）KEEPALIVE_SEND_COMMAND 自定义发送。换素材 URL、权重常量或管线行为时改 Python，并改本文对应表/段落。

仅部署 skill 目录不会创建系统定时任务；周期发送需 launchd/cron（--install-launchd / --install-cron 可生成给 OpenClaw 的提示词）。

主消息版式：保活简报 keepalive

与 prompts/rewrite-main.md 保持一致：

1. 固定标题行：zh / en 均为 保活简报 keepalive（Markdown 加粗）。
2. 第二段（一行）：zh 为 时段问候｜ 以下是{栏目}（｜ 与 以下是 之间一个空格）；en 为 时段问候 — Below: {栏目}。栏目名与 {{THEME_HINT}} 对齐；不在列表前再单独起一行栏目。
3. 正文：有序列表；作息关怀由脚本改写为「问候与关怀同行 → 空行 → 单独栏目行 → 列表」，见 smart-keepalive.py 中 insert_wellness_after_greeting。
4. 文末状态彩蛋（可选）：未设置 KEEPALIVE_STATUS_FOOTER 时，由 openclaw agent 按 prompts/status-footer.md 生成一句；提示词要求以 IDENTITY.md 中的 NAME 为助手称呼（脚本会尝试从 ~/.openclaw/agents//IDENTITY.md 注入 {{AGENT_NAME}}，可用 KEEPALIVE_AGENT_NAME 覆盖）。失败用脚本内短句兜底。若将 KEEPALIVE_STATUS_FOOTER 设为非空字符串则固定使用该文案（不调用 agent）；0 / off 关闭文末行。可用 KEEPALIVE_STATUS_STYLE_GUIDE 微调语气。

占位句丢弃、凌晨优先新鲜条目、「晚报」标题弱化等规则均在提示词中，勿在脚本里再写一套。

实现流程（供排查）

1. build_keepalive_brief()：只组装素材原始行（可含链接），不做面向用户的「业务级」润色。内部顺序概览：先算综合乘数（时段 × 轮换 × 节假日 × 跨日新鲜度）→ 盲盒（KEEPALIVE_BRIEF_CHAOS，命中则不参与上述乘数，在今日仍可用源上均匀随机试拉，成功即返回）→ 否则 基准权重 × 综合乘数 后加权随机 → 主抽中源失败则同轮乱序试其余源 → 热点兜底（多轮打乱顺序重试；轮数上限 KEEPALIVE_BRIEF_HOT_FALLBACK_ROUNDS，默认 4）。去重与 tag_meta 见下「简报素材随机」。
2. 主正文：读 rewrite-main.md，填入 {{BRIEF}}、{{LOCAL_TIME}}、{{HOUR}}、{{MINUTE}}、{{LOCALE}}、{{STYLE_GUIDE}}，调用 openclaw agent；若提示词缺失则用脚本内 FALLBACK_REWRITE_PROMPT（与主提示词同版式摘要）。
3. Agent 失败时：用 format_smart_report_fallback() 仅保证与「保活简报 keepalive」结构一致（标题 + 问候 + 正文），详细措辞仍以提示词为准。
4. 作息附录（可选）：KEEPALIVE_REST_REMINDER=1 时读 wellness.md + agent；失败用脚本内短句兜底。
5. 文末状态：resolve_status_footer_line（prompts/status-footer.md + agent，或 KEEPALIVE_STATUS_FOOTER 固定文案）。
6. 发送：默认 openclaw message send（遇 Unknown channel 重试一次）；若设置 KEEPALIVE_SEND_COMMAND，则改走自定义发送命令。

日志里 body= 仍为素材标签（如 zhihu-daily、hots-multi）。

Gotchas

• 改推送语气或版式：先改 prompts/rewrite-main.md，而不是改脚本。
• 改选材策略的「说法」、环境变量说明、与用户对齐预期：改 SKILL.md；改实际权重/URL/随机逻辑：改 smart-keepalive.py 并同步 SKILL.md 中的表与段落。
• OpenClaw 把素材标题改了：属 agent 未遵守提示词；主提示词已要求 各信息源条目标题与原文一致（rewrite-main.md 第 6 条）。若仍发生，可在 KEEPALIVE_STYLE_GUIDE 中再强调一句「禁止改写列表内标题」，或检查是否走了错误提示词/旧版 skill。
• KEEPALIVE_STYLE_GUIDE / KEEPALIVE_WELLNESS_STYLE_GUIDE / KEEPALIVE_STATUS_STYLE_GUIDE：注入主提示词 / 作息 / 文末状态彩蛋。
• 无 target（默认）：未配置时 CLI 自动路由到当前会话（推荐）；仅在你明确需要固定收件人时再配置 target。
• 定时任务找不到 CLI：优先设 KEEPALIVE_CLI_BIN（兼容 OPENCLAW_BIN），或按 --doctor 修 PATH；若你使用 KEEPALIVE_AGENT_COMMAND + KEEPALIVE_SEND_COMMAND，可不依赖 openclaw 二进制。

Hermes 兼容（关键）

如果 Hermes 环境没有 openclaw agent / openclaw message send，可直接用两个环境变量接入：

• KEEPALIVE_AGENT_COMMAND：自定义“润色/改写”命令（读取 KEEPALIVE_PROMPT，输出正文到 stdout）。
• KEEPALIVE_SEND_COMMAND：自定义“发送”命令（读取 KEEPALIVE_MESSAGE / KEEPALIVE_CHANNEL / KEEPALIVE_TARGET）。

可选：

• KEEPALIVE_CLI_BIN：指定默认 CLI（二进制可设为 hermes 或绝对路径）。

示例（仅示意，按你的 Hermes 命令改）：

export KEEPALIVE_CLI_BIN=hermes
export KEEPALIVE_AGENT_COMMAND='hermes ai --agent "$KEEPALIVE_AGENT_ID" --prompt "$KEEPALIVE_PROMPT"'
export KEEPALIVE_SEND_COMMAND='hermes message send --message "$KEEPALIVE_MESSAGE" --channel "${KEEPALIVE_CHANNEL:-}" --target "${KEEPALIVE_TARGET:-}"'

若 Hermes 暂时没有“agent 改写”能力，可把 KEEPALIVE_AGENT_COMMAND 指向一个“原样回传 prompt”或固定文本的脚本，主流程会自动兜底到脚本内版式。

• 简报时段：_brief_time_bucket() 使用本机本地时间；若服务器在 UTC，时段会与预期不一致，可改系统时区或用同一时区的机器跑定时任务。

资讯源（脚本仅负责抓取）

简报素材随机（build_keepalive_brief()）：

• 每源每日至多一次（默认）：某一素材源成功选用后，同一日历日内后续轮次不再抽中该源（加权池与热点兜底均遵守，避免「随机一次、兜底又一次」重复出现）。
• 状态文件：~/.smart-keepalive/brief-sources.json（JSON，原子写入；可用 KEEPALIVE_BRIEF_STATE_FILE 改路径）。字段与脚本一致：date（与 used 对齐的「今日」）、used（当日已成功选用过的源标签列表）、tag_meta（各源 last/prior 日期，用于跨日新鲜度 ×0.5）。
• 审计日志：与状态文件同目录，文件名为 <状态主文件名>-audit.log（默认状态文件为 brief-sources.json 时即 brief-sources-audit.log），只追加、不自动轮转；可用 KEEPALIVE_BRIEF_AUDIT_LOG=0 关闭。
• 主日志：默认再写一行到 LOG_FILE 或 ~/.openclaw/logs/smart-keepalive.log（与定时任务主日志一致）；可用 KEEPALIVE_BRIEF_LOG_TO_MAIN=0 关闭。
• 关闭去重：KEEPALIVE_BRIEF_DAILY_ONCE=0。
• 时段权重（默认开启）：同一时段内仍是加权随机（非固定顺序）。在尚未被今日用过的源上，先按基准权重再乘本地时段系数，并与下述「轮换 / 节假日 / 新鲜度」连乘后归一化抽样；另有 盲盒与 约 10% 兜底（见上流程）。关闭：KEEPALIVE_BRIEF_TIME_WEIGHTS=0。
• 0:00–6:00：国外大报/国际向乘数高。
• 6:00–10:00：新闻向乘数高。
• 10:00–17:00：科技/热榜向乘数高。
• 17:00–24:00：社区/科技类乘数高。
• 4 小时轮换 + 早/晚强制（默认）：pick_rotating_theme() 在非早/晚时段给不同栏目组加权；早晨再强化新闻类、晚间再强化社区/科技类。关闭：KEEPALIVE_BRIEF_ROTATION=0。
• 跨日新鲜度：状态文件 tag_meta 记录各源最近选用日；若连续两个日历日都选中同一源，次日该源额外 ×0.5（一次）。关闭：KEEPALIVE_BRIEF_FRESHNESS=0。
• 节假日：周末及 KEEPALIVE_BRIEF_EXTRA_HOLIDAYS 所列日期略提高知乎、少数派。关闭：KEEPALIVE_BRIEF_HOLIDAY_BOOST=0。
• 盲盒随机：默认 10% 概率走「均匀随机」试源（仍尊重今日去重），theme_tag 为 brief-chaos。关闭或调概率：KEEPALIVE_BRIEF_CHAOS=0（关闭）或 0.05 等。

加权池（与脚本 base_weighted / BRIEF_TAG_KEYS 一致）：基准权重之和 0.90，余量 0.10 为热点兜底（BRIEF_FALLBACK_WEIGHT）；再与时段/轮换/节假日/新鲜度等连乘后，在当日仍可用源上归一化加权随机。

其它 theme_tag（脚本返回，供 {{THEME_HINT}}）：

• 兜底：约 10% 概率落入热点池，或加权池全部抓取失败时 → 见上 hots-*。

热点兜底（run_theme(4) / run_theme_hot_fallback）：多路源（南方周末推荐 / 新华社 / 法广中文网 / 果壳科学人 / 36氪 / 中央气象台每日天气提示 / 虎嗅）；外层轮数上限由 KEEPALIVE_BRIEF_HOT_FALLBACK_ROUNDS 控制（默认 4，允许 1–32），每轮随机顺序（与 _brief_time_bucket 偏好组合），先跳过当日已用源再全员重试；合并正文后洗牌，最多取 5 条。

pick_time_preferred_theme() 仅供 run_theme 演示链；简报轮换见 _brief_rotation_multipliers() + pick_rotating_theme()。run_theme(1|2|3) 为按主题编号调用时的源链。

素材 URL（脚本内已配置；经抽检停更或不可用的源已移除）

新闻/科技源多为 AnyFeeder plink 直链。天气源可用 KEEPALIVE_NMC_WEATHER_URL 覆盖默认 URL（用于镜像或临时替换）；脚本会从该 URL 自动推导同域名的 /rest/* 实时接口，确保“展示页与实时数据”同源。天气城市优先取 KEEPALIVE_WEATHER_CITY，否则取 config.json.weatherCity（由 --setup 初始化）。

快速开始

cd ~/.openclaw/skills/smart-keepalive
python3 smart-keepalive.py --setup
bash smart-keepalive.sh
python3 smart-keepalive.py --doctor

配置优先级（发送目标）

• channel：KEEPALIVE_CHANNEL → 本地 config.json.defaultChannel →（可选）openclaw.json 默认。
• target：KEEPALIVE_TARGET → 本地 config.json.defaultTarget →（可选）openclaw.json 默认。
• 默认行为：若没有 target，且未显式配置 channel，则清空 channel，交给 CLI 自动路由到当前会话。
• 显式 channel 生效：若通过 KEEPALIVE_CHANNEL 或本地 config.json.defaultChannel 明确设置了 channel，即使 target 为空也会保留该 channel。
• 可选兼容：设置 KEEPALIVE_FOLLOW_OPENCLAW_DEFAULTS=1 才会回退到 openclaw.json 默认 target/channel。

环境变量（精简）

日志

English (short)

Smart Keepalive sends periodic messages via CLI. Default path is openclaw agent + openclaw message send; Hermes/other runtimes can override with KEEPALIVE_AGENT_COMMAND / KEEPALIVE_SEND_COMMAND. Copy and layout live in prompts/rewrite-main.md (fixed 保活简报 keepalive header, time-based greeting, brief body); prompts/wellness.md covers optional wellness lines. The script fetches source items via a weighted pool (time slot, 4h rotation, holiday/freshness tweaks, optional chaos draw, daily dedup, multi-retry hot fallback), fills templates, rewrites, and sends. Edit those markdown files first when changing filters or tone.

保活与状态检查（给 Agent 的提示）

「保活简报」本质是定时管线是否还能把一条消息推出去；不是通用监控面板。帮用户排查或解释时，可按下面顺序，用语中性、短句。

建议排查顺序

1. python3 smart-keepalive.py --doctor（或项目内等价路径）：确认 openclaw 可执行、openclaw.json / channel、launchd 或 cron 环境等。
2. 读 ~/.openclaw/logs/smart-keepalive.log：是否有 ERROR、发送失败、Unknown channel 重试等。
3. 手动试发：默认用 openclaw message send --message "ping"（按需加 --channel / --target）；若使用 Hermes/自定义发送命令，则执行你配置的 KEEPALIVE_SEND_COMMAND 对应试发。
4. 素材：若简报里常出现「本轮暂无可用条目」，检查网络与资讯源是否偶发失败（脚本已做重试与兜底，不必夸大成「服务宕机」）。

文末状态彩蛋（默认）：未设置 KEEPALIVE_STATUS_FOOTER 时由 prompts/status-footer.md 经 openclaw agent 单独生成一句，与主正文 rewrite-main.md 分开；可用 KEEPALIVE_STATUS_STYLE_GUIDE 微调。若仍希望主正文里顺带提管线情况，可写进 KEEPALIVE_STYLE_GUIDE，不要要求模型伪造日志里不存在的告警。

English (for agent)

When the user asks about “keepalive” health: clarify it means the scheduled pipeline (fetch → rewrite → send), not full infra monitoring. Prefer --doctor, smart-keepalive.log, then a manual send test (OpenClaw or the command configured by KEEPALIVE_SEND_COMMAND). Do not invent incidents not present in logs.