Install
openclaw skills install @bonniegeng-max/poetry-resonanceopenclaw skills install @bonniegeng-max/poetry-resonance帮用户把唐诗宋词和真实生活连起来。适合"离开学校很久、想重新亲近诗词"的人——所有解读必须说人话,不掉书袋。输出要体现文化素养但不装:克制、有个人故事感。
本 skill 有意仅支持中文。 它服务的对象是唐诗宋词——原文、笺注、以及"说人话"的解读全部建立在汉语之上;换成别的语种,诗词本身就是翻译件,要解决的问题也就不存在了。这是设计决定,不是遗漏。
references/ 下的全部数据(李白全集、杜甫/苏轼精选、主题索引、天气映射、诗人档案、印章二维码)同为中文,理由一致。This skill is intentionally Chinese-only. Its subject is Tang and Song classical Chinese poetry; the source texts, the historical annotations, and the plain-language readings all live in Chinese. There is no multilingual variant and none is planned — translating the poems would remove the very thing the skill exists to work with. Non-Chinese poetry is out of scope (see 「何时不用」 above).
安装(二选一):
npx clawhub@0.23.3 install poetry-resonance
openclaw skills install @bonniegeng-max/poetry-resonance
安装命令刻意锁定版本号(clawhub@0.23.3):不锁版本的 npx <pkg> 会在上游被投毒时自动拉到恶意版本,属于可复现性风险。
装好后对 agent 说:
日签输出效果示例:
┌─────────────────────┐
│ 处暑 · 八月廿三 · 星期日 │
│ │
│ 长安一片月 │
│ 万户捣衣声 │
│ 秋风吹不尽 │
│ 总是玉关情 │
│ ——李白·子夜吴歌 │
│ │
│ 今日口令 · 秋风吹不尽 │
└─────────────────────┘
~/.workbuddy/poetry-resonance/profile.md 保存个人偏好:默认文案风格、日签版式底线、在学诗人、联网开关(online)、日签二维码开关(qr)。已存在时优先采用。
首次写入前必须先告知、后写入(内容、位置、用途三件事说清楚,见下节「本地数据与隐私」);用户不同意则不落盘,偏好只在本次对话内生效。
本 skill 默认只会碰到下面两个位置的文件,除此之外不读、不写、不枚举任何文件。唯一例外:用户在对话中主动要求的保存动作(如"把这篇笔记存到 ima / 腾讯文档 / 某个本地路径"),见本节末尾「用户主动发起的例外」。
① 用户数据 —— 在 ~/.workbuddy/poetry-resonance/ 下,与 skill 目录分开存放(升级、重装都不丢)。核心是 profile.md 与 progress.json 两件;export-*.md 只在用户主动导出时出现:
| 文件 | 存什么 | 用来做什么 |
|---|---|---|
profile.md | 文案风格偏好、日签版式底线、在学诗人、联网开关、二维码开关 | 免去每次重复说偏好 |
progress.json | 诗名、首次学习日期、验收通过日期、复习日期、复习阶段 | 模式 D 艾宾浩斯复习排期 / 模式 E 周报统计 / 模式 D 复习回执 / 模式 F 导出 |
export-YYYYMMDD.md(可选) | 由用户主动导出的学习记录(人话版诗单;另可选 Anki 兼容 CSV) | 模式 F 导出产物——只在用户说"导出诗单"时生成,不自动产生 |
② skill 自带的诗库(不是用户数据) —— references/poems.md、references/themes.md 等是 skill 安装时自带的内容文件。它们只会在用户明确说"诗库加一首《XX》"时被追加写入(见「使用规则 · 扩库流程」),不自动写、不删除既有条目;用户不发起扩库,这些文件就全程只读。
首次写入先取得同意(硬规则)
profile.md / progress.json 前,先说明上面三件事(存什么、存在哪、做什么用),等用户点头;(export-*.md 由用户主动说"导出诗单"触发,属于用户请求本身,无需额外同意,但仍只写在该目录内)progress.json(或 profile.md),并确认删除结果不收集、不上传
用户主动发起的例外(如实声明,避免说法与行为不一致)
以下动作不在默认行为里,只有用户在对话中明确要求时才发生,本质是执行用户自己的指令而非 skill 主动触碰:
用户不发起,这些路径一个都不会被碰到。除上述两类外,不存在其他任何超出「两个位置」的读写。
Local files. By default, this skill touches files in exactly two places and nothing else. (1) User data — two core files under ~/.workbuddy/poetry-resonance/ (a preference file and a study-progress file), deliberately outside the skill directory so upgrades and reinstalls do not lose them; an optional export-*.md appears only when the user explicitly asks for an export. An explicit first-run notice and consent (what, where, why) is required before the first write; a no-persistence mode is offered if the user declines; inspect / stop / delete are supported on request. (2) The skill's own bundled library — references/poems.md and references/themes.md ship with the skill and are appended to only when the user explicitly asks to add a poem; never written automatically and never used to remove existing entries. Contents of the user-data files are never transmitted over the network and never logged. The only exceptions to the two-location rule are actions the user explicitly requests in conversation — saving a generated study note to the user's chosen destination (e.g. an ima knowledge base, Tencent Docs, or a user-specified local path), or invoking image generation for an optional illustration — which execute the user's own instruction rather than skill-initiated access. No other files outside these two locations are read, enumerated, or written.
这个 skill 源于一个真实场景:收拾书架时翻出一本李白的诗集,重新开始读诗;每天练字之外,想让学到的诗真正回到生活里——看景时想起、经历时有感、日常能引用。设计原则由此而来:说人话、不掉书袋、每首诗都要落到具体的生活场景。
作者把这个 skill 的完整诞生过程写成了一篇文章(含版本考据与真实使用记录,中文):《一本翻出来的李白,变成了每晚九点响的闹钟》。
references/poems.md · 精读库:以李白为主,每首含:原文 / 人话背景 / 情绪内核 / 生活·工作共鸣场景 / 金句 / 配图意境 / 日签关联。字段含「朝代·作者」,后续可扩展杜甫、苏轼等(直接追加即可)。references/libai_raw.json · 底库一:李白全集 1149 首(数据来自 chinese-poetry 项目全唐诗,繁转简,MIT 协议),用于原文核对与全集检索。references/poets_selected.json · 底库二:杜甫 70 首 + 苏轼词 44 首(chinese-poetry 全唐诗/全宋词,繁转简,按代表作清单精选;其中 2 首数据源缺失由人工补录通行版,字段 _manual 标记)。苏轼条目含 rhythmic 词牌字段,日签展示时可带词牌。references/poets_profile.md · 诗人档案:李白/杜甫/苏轼人生阶段线(每阶段:时间/关键词/代表作/情绪底色+一句话主线)。模式 B 拆解时先定位诗人当时所在阶段,背景自动挂上"人生坐标";日签推荐理由可用阶段梗。references/themes.md · 主题索引:14 个主题跨诗人(孤独/逆境/得意/岁月/思乡/送别/爱情/壮阔/闲适/旷达/家国/酒/秋/月),每主题含场景速记+代表诗句,是模式 A 匹配的第一入口。精读库扩充时顺手维护。references/weather_map.md · 天气映射:雨/雪/晴/风/雾/暑热/严寒 → 诗句映射,模式 C 日签的天气关联层。references/seal_qr.svg · 印章二维码(可选组件,默认不使用):指向 ClawHub 诗遇安装页的真码(红底白模块、中心"诗遇"、H 级容错)。只在用户明确要求分享、或 profile.md 里设了 qr: true 时才嵌进日签卡片。使用规则:
references/poems.md,必要时同步主题标签到 references/themes.md)。只追加、不删除既有条目,且不触碰 skill 目录以外的任何文件;用户不发起,这两个文件全程只读。本 skill 的底座是纯本地的——不联网也能跑全部五种模式。下面两个外部查询是可选增强,只在联网且未被关闭时使用。
| 服务 | 端点 | 发出去的只有 | 用途 |
|---|---|---|---|
| 搜韵开放 API | `https://api.sou-yun.cn/open/poem?key=<诗名或诗句>&scope=Title | Sentence&jsonType=true` | 诗名 / 作者 / 诗句 |
| wttr.in | https://wttr.in/<城市拼音>?format=j1 | 城市名 | 模式 C 日签的天气关联层 |
为什么是这两个:中文历代笺注与免注册天气这两个用途上,没有更合适的公开替代。两者都是只读、免 key 的公开接口——不传任何凭证、token、账号或身份信息,也不需要读取环境变量。搜韵注明为非商业用途接口,wttr.in 为开源服务。
硬约束(数据边界)
profile.md 或 progress.json 的任何内容、以及生成的文案发送给任何外部 API。关闭方式:在 profile.md 里写 online: false(或对 agent 说"别联网"),即完全关闭这两个查询,五种模式照常运行。
~/.workbuddy/poetry-resonance/progress.json(模式 D 使用),结构:
{
"records": [
{
"poem": "望庐山瀑布",
"first_learned": "2026-08-23",
"recite_pass": ["2026-08-25"],
"review_stage": 2,
"last_review": "2026-08-30"
}
]
}
独立于 skill 目录存放,skill 升级/重装不影响学习进度。首次创建前须先告知并取得同意;用户不同意则不落盘(模式 D 退化为当次抽查)。查看 / 停止 / 删除的入口见「本地数据与隐私」。
触发:用户描述一段经历、场景、心情,想找诗句表达("今天被甲方改了八版方案"、"站在黄果树瀑布底下"、"项目终于上线了")。
工作流:
触发:用户给一首诗名或原文。按说话口气自动分档:
| 档位 | 触发说法 | 深度 |
|---|---|---|
| 快拆 | "快速过一下这首" | 极简:背景两句 + 金句 |
| 标准拆解(默认) | "拆解《XX》"、"讲讲这首" | 中:背景+情绪+共鸣+炼字 |
| 深读(满血) | "深读《XX》"、"精讲"、"好好讲讲这首" | 全:炼字+对比读法+历代笺注 |
工作流:
自动化触发(数据驱动):
触发:用户说"日签"、"今日一句"、"今天推荐首诗",或自动化定时任务调用。
工作流:
https://wttr.in/<城市拼音>?format=j1,从用户说过/档案中的城市查询;只发城市名)获取天气类别,映射诗句;API 失败静默跳过;用户口报"今天下雨"可直接替代。同天节气与天气都强关联时,节气优先、天气作辅助理由("处暑,又赶上一场秋雨")profile.md 里设了 qr: true 时,才把 references/seal_qr.svg 的内容内联进去——<g transform="translate(x,y) scale(2.33)"> 红底 rect+path+中心"诗遇"二字,放卡片左下/右下空区,旁配竖排小字"扫码取同款"。码内容固定,直接复用文件内容,不要重新生成触发:用户说"验收"、"背一下"、"复习"、"抽查",或每晚定时提醒任务调用。
艾宾浩斯复习间隔:学习后 1 天、2 天、4 天、7 天、15 天、30 天(review_stage 0→6)。
工作流:
progress.json,不新增任何文件:
── 本轮复习 ──
复习 3 首 · 通过 2 首
累计烂熟 12 首 · 复习池 26 首
⏭ 下一首到期:《静夜思》· 10 月 2 日
🔥 连续第 7 天
题型(三选一轮换,复习一首用一种):
语气:鼓励式,允许小错,不搞挫败感。
触发:用户说"周报"、"学习周报"、"读诗周记",或每周日定时任务调用。
工作流:
~/.workbuddy/poetry-resonance/progress.json,统计本周(周一至今):
触发:用户说"导出我的诗单"、"导出学习记录"、"把我的记录导出来"。
为什么有这一节:progress.json 是私有格式,用户读不了也带不走。学习的资产属于用户——能导出,才谈得上"这是我的"。这也是与背单词式工具(可导出 Anki 卡组)对齐的一环。
工作流:
progress.json,按三段整理:已烂熟 / 复习中 / 刚学(未验收)~/.workbuddy/poetry-resonance/export-YYYYMMDD.md:
# 我的诗单 · 2026-09-29
## 已烂熟(12 首)
- 《静夜思》· 李白 · 首次学习 8-23 · 走完 6 阶复习
## 复习中(26 首)
- 《望庐山瀑布》· 李白 · 阶段 3/6 · 下次复习 10-2
## 刚学未验收(2 首)
- 《闻王昌龄左迁龙标遥有此寄》· 李白 · 9-28
---
连续学习 7 天 · 共 40 首入池 · 由诗遇导出
诗名,作者,金句,阶段,首次学习,下次复习),可直接作为间隔重复卡组底稿progress.json 本身只读不改;导出失败(文件不存在)就直说"还没有学习记录,先去拆解一首",不要编造条目① 文化克制型:淡淡一句,不显摆。 ② 叙事共鸣型:讲"为什么想到这句诗",个人故事感(首次使用推荐,最易出效果)。 ③ 国风氛围型:诗句打头,重意境,配水墨图。 ④ 反差俏皮型:现代口语 + 古诗收尾,轻松不端着。
profile.md 的 online: false 整体关闭(见"权威核对"章节数据边界)~/.workbuddy/poetry-resonance/ 下的 profile.md 与 progress.json(首次写入先告知并取得同意),以及 skill 自身目录下的 references/*.md(仅在用户明确要求扩库时追加);其余文件不读不写不枚举。唯一例外是用户主动发起的保存动作(存 ima / 腾讯文档 / 指定路径、可选配图),见"本地数据与隐私 · 用户主动发起的例外"