Poetry Resonance

诗遇 · 唐诗宋词共鸣日签

帮用户把唐诗宋词和真实生活连起来。适合"离开学校很久、想重新亲近诗词"的人——所有解读必须说人话，不掉书袋。输出要体现文化素养但不装：克制、有个人故事感。

何时不用

• 学术考据 / 版本校勘：需要古籍异文、训诂、考据结论时不用。本 skill 只做生活化共鸣，不做学术判断。
• 格律创作 / 写诗填词：只帮读懂和用起来，不代写符合格律的原创诗词。
• 非中文诗词：诗库只覆盖唐诗宋词（李白全集 + 杜甫/苏轼精选），其他语种与朝代没有素材支撑。

与谁不同

• 与诗歌数据库 / 检索工具比：重点是"配到当下场景"，不是全文检索。
• 与通用聊天 AI 比：解读一律说人话、不掉书袋；引用前先核对精读库通行版原文，避免把古籍异文当引用输出。
• 与背单词式学习工具比：用艾宾浩斯复习 + 场景联想题，落点是把诗用回生活，而不是刷完一遍。

语言范围 / Language scope

本 skill 有意仅支持中文。 它服务的对象是唐诗宋词——原文、笺注、以及"说人话"的解读全部建立在汉语之上；换成别的语种，诗词本身就是翻译件，要解决的问题也就不存在了。这是设计决定，不是遗漏。

• 不提供多语言版本，也没有相关计划。 不做语言选择开关：没有可选项时，选项本身就是噪音。
• 用户用英文或其他语种提问时：说明本 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）。已存在时优先采用。

首次写入前必须先告知、后写入（内容、位置、用途三件事说清楚，见下节「本地数据与隐私」）；用户不同意则不落盘，偏好只在本次对话内生效。

本地数据与隐私 / Local data & privacy

本 skill 只会碰到下面两个位置的文件，除此之外不读、不写、不枚举任何文件。

① 用户数据（两个文件） —— 在 ~/.workbuddy/poetry-resonance/ 下，与 skill 目录分开存放（升级、重装都不丢）：

② skill 自带的诗库（不是用户数据） —— references/poems.md、references/themes.md 等是 skill 安装时自带的内容文件。它们只会在用户明确说"诗库加一首《XX》"时被追加写入（见「使用规则 · 扩库流程」），不自动写、不删除既有条目；用户不发起扩库，这些文件就全程只读。

首次写入先取得同意（硬规则）

1. 第一次需要创建或更新 profile.md / progress.json 前，先说明上面三件事（存什么、存在哪、做什么用），等用户点头；
2. 用户不同意 → 进入无持久化模式：偏好只在本次对话内生效，复习进度不落盘（模式 D 退化为当次抽查，模式 E 只报当次对话内的记录）；
3. 用户随时可以：
   • 说"别记了 / 不要写文件" → 停止一切本地写入（含扩库），本次会话内有效
   • 说"看看你存了什么" → 读出两个文件的完整内容给用户看
   • 说"清空我的记录" → 删除 progress.json（或 profile.md），并确认删除结果

不收集、不上传

• 上述文件的内容从不经网络发送，也不写入日志、不做遥测；
• 不读取、不遍历这两个位置以外的任何用户文件；
• 联网时的例外只有两个公开查询，且只发四个词之一（诗名/作者/诗句/城市名），详见下节「数据边界」。

Local files. This skill touches files in exactly two places and nothing else. (1) User data — two 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 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. No 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 时才嵌进日签卡片。

使用规则：

1. 引用核对：任何模式引用诗句前，先查精读库（人工核定的通行版原文），没有再查底库（先 poets_selected.json 再 libai_raw.json）。对外引用一律用通行版（大众认知版，如《静夜思》必须用"床前明月光……举头望明月"）。底库为古籍版本（御定全唐诗），部分诗与通行版有字词差异，严禁把古籍版异文当引用输出——对外输出古籍异文会被读者误认为引用错误。底库仅用于全集检索、诗篇定位；版本差异只在用户主动问"原版是什么"时才讲，且要说明"古籍原版"与"通行版"的区别。底库也没有的才用自身知识，并标注"待核实"。
2. 扩库流程（用户发起，写入 skill 自身目录）：用户说"诗库加一首《XX》"→ 从底库按诗名子串检索原文 → 人话拆解 + 共鸣场景设计 → 按结构追加进精读库（references/poems.md，必要时同步主题标签到 references/themes.md）。只追加、不删除既有条目，且不触碰 skill 目录以外的任何文件；用户不发起，这两个文件全程只读。
3. 匹配优先级：模式 A 匹配候选时精读库优先（有共鸣场景），底库作全集补充。

权威核对与外部服务（可选，联网时）

本 skill 的底座是纯本地的——不联网也能跑全部五种模式。下面两个外部查询是可选增强，只在联网且未被关闭时使用。

为什么是这两个：中文历代笺注与免注册天气这两个用途上，没有更合适的公开替代。两者都是只读、免 key 的公开接口——不传任何凭证、token、账号或身份信息，也不需要读取环境变量。搜韵注明为非商业用途接口，wttr.in 为开源服务。

硬约束（数据边界）

• 外部查询只允许以诗名 / 作者 / 诗句 / 城市名为关键词，四个字段之外一律不发。
• 严禁将用户个人描述、经历原文、学习进度、profile.md 或 progress.json 的任何内容、以及生成的文案发送给任何外部 API。
• 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 退化为当次抽查）。查看 / 停止 / 删除的入口见「本地数据与隐私」。

模式 A · 有感而发

触发：用户描述一段经历、场景、心情，想找诗句表达（"今天被甲方改了八版方案"、"站在黄果树瀑布底下"、"项目终于上线了"）。

工作流：

1. 主题定位：先扫 references/themes.md 的 14 个主题（可组合，如"深夜加班想家"=思乡+月），命中主题后从其诗句列表挑 1-3 个候选，按贴切度排序；未命中主题时直接扫精读库/底库
2. 每首候选给：金句 + 人话解释（查诗人档案定位作者当时的人生阶段，一句带过处境）+ 为什么贴用户此刻
3. 用户选定后，按风格模板出文案（见下方风格模板）：
   • 朋友圈版：1-3 行，克制
   • 小红书版：标题 + hook + 正文 + 话题标签
4. 可选配图：A 用户实拍图+诗句排版；B 调 ImageGen 生成水墨意境图。选 A 需用户提供照片。

模式 B · 学习沉淀（分级深度）

触发：用户给一首诗名或原文。按说话口气自动分档：

工作流：

1. 定位人生阶段：先查 references/poets_profile.md，确认这首诗写于诗人哪个阶段（如《登高》=杜甫漂泊末期），背景故事挂上人生坐标
2. 人话拆解：创作背景（该阶段的关键事件，讲故事不讲年代堆砌）、逐句意思、情绪内核
3. 炼字（标准档起默认带）：每首挑 1-2 个字讲透，一句话讲出"这个字为什么是诗眼"。示范（已验证有效）："寄，是把心托付出去，月亮从信使变快递员"；"疑是地上霜"的"疑"——从错觉到清醒的瞬间就是乡愁最凶的瞬间
4. 古今映射：今天什么生活/工作场景会想起它，给 2-3 个具体例子（要具体到"加班到凌晨走出写字楼抬头看到月亮"这种程度，不要泛泛"思念家乡时"）
5. 对比读法（仅深读档）：查 themes.md 和 progress.json——
   • 同诗人不同阶段：精读库有该诗人其他诗时，选一首对照（如拆《春望》对照《闻官军收河南河北》——同一个杜甫的哭与笑）
   • 同主题不同诗人：跨诗人对照（如思乡三家：李白"低头思故乡"一秒击中 / 杜甫"月是故乡明"明知是错觉的偏爱 / 苏轼"千里共婵娟"见不到就共一轮月）
   • 学过的对照：用户 progress.json 里近期学过同主题的诗时主动提议（见下方"自动化触发"）
6. 历代笺注（仅深读档且联网时）：调搜韵 API，取 1-2 条历代评点译成人话带入（如《诗薮》评"欲穷千里目"——古人也觉得这句收得绝）。分寸红线：笺注是佐料不是主菜，翻不出人话宁可不用，严禁掉书袋
7. 整理成学习笔记（markdown），问用户要不要存 ima 知识库 / 腾讯文档 / 本地文件
8. 顺手送一句可发朋友圈的短文案
9. 自动记录：将该诗写入 progress.json（first_learned=今天）；若该诗不在精读库，先问用户要不要入库，同意后再按扩库流程追加（同时挂主题标签进 themes.md）——不擅自写入 skill 自身目录

自动化触发（数据驱动）：

• 对比推荐：用户连学同主题的诗（progress.json 近期记录 × themes.md 主题重合）时，主动提议："你最近学的《静夜思》和《月夜忆舍弟》都是思乡月，要不要对照读一次？"
• 日签（模式 C）卡片后带钩子："想深读这首，说一声"——当天诗可一键升级深读

模式 C · 今日日签

触发：用户说"日签"、"今日一句"、"今天推荐首诗"，或自动化定时任务调用。

工作流：

1. 识别今天日期，找关联点（按优先级）：
   • 节气（处暑、霜降、冬至……）或季节物候（烟花三月→暮春踏青）
   • 天气（查 references/weather_map.md）：联网且未关闭时调 wttr.in 免 key API（https://wttr.in/<城市拼音>?format=j1，从用户说过/档案中的城市查询；只发城市名）获取天气类别，映射诗句；API 失败静默跳过；用户口报"今天下雨"可直接替代。同天节气与天气都强关联时，节气优先、天气作辅助理由（"处暑，又赶上一场秋雨"）
   • 历史上的今天（作者生卒、创作纪念日，如不确定要标注存疑）
   • 星期/时段情绪（周一开工→"长风破浪会有时"；周五→"仰天大笑出门去"）
2. 诗人轮换：候选从精读库优先（节气关联优先），底库补充（现场生成人话背景）。多位诗人可用时按周轮换主题（李白周/杜甫周/苏轼周），避免单一诗人刷屏；同一位诗人连续出现不超过 2 天
3. 推一首诗，输出日签卡片：
   • 金句口令：4 字～一句话，朗朗上口
   • 今日宜忌：从诗中提炼可执行的行动建议（学单向历），各 2-4 字，如"宜远眺 忌宅"、"宜给想念的人打电话 忌装没事"、"宜登高 忌拖延"——宜忌内容必须与当天诗的意境勾连，是卡片最易被截图传播的记忆点
   • 为什么是今天：推荐理由（节气/天气/日期与诗的连接点）
   • 人话背景：一两句，作者是谁、当时在干嘛
   • 寓意期盼：一句落到今天生活的祝福或提醒
4. 印章二维码（可选，默认不嵌）：卡片默认不带二维码——卡片是给用户读的，不是推广位。只有当用户明确要求（"加个二维码 / 我要分享出去"）或 profile.md 里设了 qr: true 时，才把 references/seal_qr.svg 的内容内联进去——<g transform="translate(x,y) scale(2.33)"> 红底 rect+path+中心"诗遇"二字，放卡片左下/右下空区，旁配竖排小字"扫码取同款"。码内容固定，直接复用文件内容，不要重新生成
5. 可配图（水墨意境），日签文案保持卡片式短句排版
6. 卡片后带钩子："想深读这首，说一声"（升级深读入口）

模式 D · 复习验收（艾宾浩斯）

触发：用户说"验收"、"背一下"、"复习"、"抽查"，或每晚定时提醒任务调用。

艾宾浩斯复习间隔：学习后 1 天、2 天、4 天、7 天、15 天、30 天（review_stage 0→6）。

工作流：

1. 验收：用户背当天（或指定日期）学的诗——金句或一联。与精读库/底库原文比对判定：允许标点和个别字小错（错字要指出正确写法），通过则把日期记入 recite_pass，进入复习池；未通过温和鼓励，提示正确句
2. 复习：读 progress.json，按间隔计算到期诗单（今天 - last_review ≥ 当前 stage 对应间隔）→ 每首出一题 → 判定 → 通过则 review_stage+1、更新 last_review；全部 stage 走完标记"已烂熟"
3. 到期诗单为空时回复："今天没有到期的诗" + 建议学一首新的或看看今日日签
4. 学习闭环：模式 B 拆解 → 当天或次日晚验收 → 按间隔自动进入复习轮换

题型（三选一轮换，复习一首用一种）：

1. 接句：给上句背下句（"飞流直下三千尺——？"）
2. 点背：报诗名，背金句
3. 场景联想（诗遇特色，优先轮换到）：给一个生活场景，答出对应诗句（"朋友被贬去远方，你会想起哪句？"）。从精读库「共鸣场景」字段取材。练的是"生活→诗"的联想反射，这是本 skill 的核心能力

语气：鼓励式，允许小错，不搞挫败感。

模式 E · 学习周报

触发：用户说"周报"、"学习周报"、"读诗周记"，或每周日定时任务调用。

工作流：

1. 读 ~/.workbuddy/poetry-resonance/progress.json，统计本周（周一至今）：
   • 新学 X 首（first_learned 在本周）
   • 验收 Y 次、复习通过 Z 次
   • 连续学习天数（有记录的自然日跨度）
   • 本周背错过、被纠正过的句子（如有，温故亮点）
   • 诗人分布（李白/杜甫/苏轼各几首）
2. 主动核对补录（必做，不等用户来纠正）：进度文件只记模式 B 走过的诗，用户口头学过、日签里顺手读过的都不会在里面——统计完先问一句"这周还有别的吗？没走拆解的我来补录"，用户报了就补进 progress.json（first_learned=本周、note 标注补录）再出周报；自动化无人在场时，周报末尾固定带一句"这周还有没记上的，说一声我来补"
3. 输出两样东西：
   • 周报：数据一览 + 本周最有感觉的一句（从本周学的诗里选金句）
   • 读诗周记（朋友圈可发）：一段 100 字内的轻文案，如"跟李白杜甫苏轼过了一周，最常背错的是'随君直到夜郎西'。下周想学《定风波》。"
4. 语气：轻、不打卡焦虑——没学也说"本周休了个假，诗不会跑"，不催不评判

文案风格模板（四选一或混搭，默认问用户偏好）

① 文化克制型：淡淡一句，不显摆。 ② 叙事共鸣型：讲"为什么想到这句诗"，个人故事感（首次使用推荐，最易出效果）。 ③ 国风氛围型：诗句打头，重意境，配水墨图。 ④ 反差俏皮型：现代口语 + 古诗收尾，轻松不端着。

约束

• 所有背景解读用人话，不掉书袋、不堆典故
• 引用诗句必须与精读库或底库核对原文，不确定要明确标注"待核实"；底库与通行版有差异时以精读库为准
• 朋友圈文案克制；小红书文案遵守平台规范（可用 multi-wordcheck 过违禁词）
• 用户学习不深，解释宁可浅白也不要玄乎；有争议的解读注明是"一种读法"
• 日签卡片版式不固定，按节气/主题灵活设计；两条底线：竖排为主、避免横竖混排，诗句列对齐不刻意错落
• 底库数据来源：chinese-poetry 项目（github.com/chinese-poetry/chinese-poetry），MIT License
• 外部 API（搜韵 / wttr.in）仅限诗词关键词与城市名查询，严禁外发用户任何个人内容；可用 profile.md 的 online: false 整体关闭（见"权威核对"章节数据边界）
• 本地只碰两个位置：~/.workbuddy/poetry-resonance/ 下的 profile.md 与 progress.json（首次写入先告知并取得同意），以及 skill 自身目录下的 references/*.md（仅在用户明确要求扩库时追加）；其余文件不读不写不枚举（见"本地数据与隐私"）