# Poetry Resonance

> 诗遇 · 唐诗宋词共鸣日签

- Skill: `bonniegeng-max/poetry-resonance` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add bonniegeng-max/poetry-resonance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bonniegeng-max/poetry-resonance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bonniegeng-max (https://skillmd.com/u/bonniegeng-max)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/bonniegeng-max/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).

## 快速开始

安装（二选一）：
```bash
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 目录分开存放（升级、重装都不丢）：

| 文件 | 存什么 | 用来做什么 |
|------|--------|-----------|
| `profile.md` | 文案风格偏好、日签版式底线、在学诗人、联网开关、二维码开关 | 免去每次重复说偏好 |
| `progress.json` | 诗名、首次学习日期、验收通过日期、复习日期、复习阶段 | 模式 D 艾宾浩斯复习排期 / 模式 E 周报统计 |

**② 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 的完整诞生过程写成了一篇文章（含版本考据与真实使用记录，中文）：[《一本翻出来的李白，变成了每晚九点响的闹钟》](https://mp.weixin.qq.com/s/6cjNWyjWlha-ZuqsNeXY7A)。

## 诗库（三层）

- `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 的底座是**纯本地**的——不联网也能跑全部五种模式。下面两个外部查询是可选增强，只在联网且未被关闭时使用。

| 服务 | 端点 | 发出去的只有 | 用途 |
|------|------|-------------|------|
| 搜韵开放 API | `https://api.sou-yun.cn/open/poem?key=<诗名或诗句>&scope=Title|Sentence&jsonType=true` | 诗名 / 作者 / 诗句 | 版本异文核对；模式 B 深读档的历代笺注素材（取 1-2 条译成人话，翻不出人话宁可不用） |
| wttr.in | `https://wttr.in/<城市拼音>?format=j1` | 城市名 | 模式 C 日签的天气关联层 |

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

**硬约束（数据边界）**
- 外部查询只允许以**诗名 / 作者 / 诗句 / 城市名**为关键词，四个字段之外一律不发。
- **严禁**将用户个人描述、经历原文、学习进度、`profile.md` 或 `progress.json` 的任何内容、以及生成的文案发送给任何外部 API。
- API 不可用或离线时静默跳过，不影响任何模式。

**关闭方式**：在 `profile.md` 里写 `online: false`（或对 agent 说"别联网"），即完全关闭这两个查询，五种模式照常运行。

## 学习进度

`~/.workbuddy/poetry-resonance/progress.json`（模式 D 使用），结构：

```json
{
  "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 · 学习沉淀（分级深度）

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

| 档位 | 触发说法 | 深度 |
|------|---------|------|
| 快拆 | "快速过一下这首" | 极简：背景两句 + 金句 |
| **标准拆解（默认）** | "拆解《XX》"、"讲讲这首" | 中：背景+情绪+共鸣+**炼字** |
| **深读（满血）** | "深读《XX》"、"精讲"、"好好讲讲这首" | 全：炼字+**对比读法**+**历代笺注** |

工作流：
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`（仅在用户明确要求扩库时追加）；其余文件不读不写不枚举（见"本地数据与隐私"）