runcat-tommy/dsh-chinese-poetry

dsh-chinese-poetry

DeepSeek Harness Web 的免 token 诗词查询插件：在会话页头新增「诗词」标签页（与「对话」「轨迹」同级，排在轨迹之后），支持搜索、筛选、飞花令、每日一首、收藏与 AI 解读。

• 数据源：免费公共 API 诗泉 poetry.palemoky.com（37 万首诗词，无需注册、无需 API Key，CORS 全开）
• AI 解读 / 关联典故：透传给 dsh 自己的会话，消耗你已有的模型配额，无需额外申请任何模型 Key
• 纯本地数据（收藏 / 历史 / 缓存），不建任何后端
• 要求：dsh web 0.1.0-rc.6+ 或 0.2.x（已在 0.2.0-rc.2 上实测）

English: README.en.md

界面预览

数据基座

本插件的全部诗词语料与查询接口来自开源项目 palemoky/chinese-poetry-api（诗泉 poetry.palemoky.com），在此向原作者致谢。该服务免费、无需注册与 API Key、CORS 全开。若你的查询较慢，多为该服务端接口响应慢所致，请前往该项目向作者反馈。

本插件做了什么（相对基座的优化）

基座只提供原始接口（按作者 / 朝代 / 体裁分页、随机、搜索、统计等），本插件在其上做了面向「查询使用」的封装与优化：

• 免 token 的会话页视图：在会话页头注册「诗词」标签页，无需任何模型 Key，纯前端调用公共接口。
• 朝代纠偏表：公共接口对部分诗人（尤其宋代，如 曾丰 / 毕仲游 / 张侃 等）的朝代标注有误（误标为「唐」），本插件内置常见诗人朝代校正表，展示时自动纠正并标注「已校正」。
• 健壮的数据层：内置令牌桶限速（搜索 6 次/分、其它 15 次/分）、本地缓存、429 指数退避、连续失败降级为缓存 / 离线兜底，避免被限流打挂、查询失败即报错。
• 离线兜底表：内置约 90 首常备诗词，断网或接口不可用时仍能演示；2 字内短查询走本地精选并明确提示（3 字以上才检索全库 37 万首）。
• 飞花令：输入一个字，随机给出含该字的诗，可连点换诗。
• 分享卡片图：把任意一首诗渲染成一张古风诗图卡片（标题/作者·朝代/正文），一键下载 PNG 分享。
• 节日专题：内置春节/元宵/清明/端午/七夕/中秋/重阳七节，点选即看代表诗（免 token），支持「随机相关」与「AI 应景赠诗」。
• 收藏 / 历史 / 简繁：收藏与最近搜索存于本地（localStorage），支持简体 / 繁体全局切换。
• AI 解读：一键把提示词写入 dsh 会话输入框（不自动发送，由你按回车确认），复用你已有的模型配额。
• 视图体验：三个互不相干的功能做成互斥切换模块（「搜索诗句」/「筛一首」/「飞花令」），一次只显示当前模块的控件，不再同屏堆叠；全局快捷操作（随机一首 / 每日一首 / 节日 / 收藏 / 繁简）独立成行；首次进入显示空态引导卡片，示例词一点即搜；AI 解读后自动切到「对话」视图；诗词视图内容在对话 / 轨迹 / 诗词间切换时保留；最近搜索区块（位于搜索模块内）恒定显示。
• 双语文案 / 中英文文档：界面文案与 README 均提供中英双语。

安装

方式一：npm 包（推荐）

dsh plugin --profile web add dsh-chinese-poetry

说明：dsh-chinese-poetry 已发布到 npm（https://www.npmjs.com/package/dsh-chinese-poetry），dsh plugin add 会直接从 npm registry 拉取并安装，无需手动 npm install；版本与 GitHub 仓库同步。

方式二：GitHub（发布后可用）

dsh plugin --profile web add github:<你的用户名>/dsh-chinese-poetry

方式三：本地源码安装（开发 / 调试）

cd dsh-chinese-poetry
dsh plugin --profile web add .

开发调试建议用活链接，改动源码即时生效（仍需重启 Web UI）：

dsh plugin --profile web add link:.

安装完成后重启 dsh web，打开任意会话，页头标签栏会出现 「诗词」 标签。

没有 pnpm 时先安装：npm i -g pnpm（dsh plugin 依赖 pnpm）。

使用

1. 打开一个会话（对话 / 轨迹 / 诗词任一界面）。
2. 点击页头 「诗词」 标签进入查询界面。
3. 搜索框输入任意词 / 句，或按作者 / 朝代 / 体裁筛选；支持飞花令（单字）、随机、每日一首、简繁切换、节日专题（选一个节看到其精选相关诗）。
4. 点开某首诗的详情，可复制（纯文本 / Markdown）、收藏，或点 卡片图 生成一张可下载的诗图卡片；点 AI 解读 会把提示词写入输入框，由你按回车确认后由 dsh 会话回答（不自动提交）。

卡片图导出示例：

功能路线图

• M0：插件骨架 + 「诗词」标签页注册（与对话 / 轨迹并排，order 20）
• M1：数据层（fetch 封装、令牌桶限速、本地缓存、429 退避、离线兜底表）＋ 搜索 / 随机 / 每日一首 视图
• M2：筛选器（朝代 / 体裁下拉 + 常用作者 chips → 筛一首）、全局简繁切换、复制（纯文本 / Markdown）
• M3：飞花令（单字 → 随机含字诗，可连点换诗）、收藏（localStorage）、最近搜索、AI 解读（写入会话输入框，不自动发送）
• M4a：朝代纠偏表（内置常见诗人朝代校正，纠正公共 API 对宋代等诗人的错标，展示时标注「已校正」）、最近搜索区块恒定显示（含空态占位）、AI 解读后自动切到「对话」视图、视图内容跨标签页保留
• M4b：数据基座致谢提示条（页内提示接口来源与反馈路径）、README / 界面文案中英双语、CHANGELOG、npm 版本 1.1.0
• M4：分享卡片图（canvas 生成诗图卡片，可下载）、节日专题（春节/元宵/清明/端午/七夕/中秋/重阳，每节精选诗 + 随机相关 + AI 应景）、工具式 UI 打磨（空态提示、三视图整合、网格布局）
• M5：GitHub 开源发布（runcat-tommy/dsh-chinese-poetry）
• M6：UI 改版（v1.3.0）—— 搜索框与按钮合为一体、快捷操作独立胶囊行、筛选控件收进工具条卡片、首屏空态引导卡片、统一设计 token 与主次按钮分级
• M7：三个独立功能拆为互斥切换模块（搜索诗句 / 筛一首 / 飞花令），一次只显示当前模块；全局快捷操作独立成行；最近搜索归入搜索模块（v1.4.0）

开发

dsh-chinese-poetry/
├── package.json          # dsh.bundle.patch + dsh.client 声明
├── cordis.patch.yml      # profile 层 bundle patch
├── lib/
│   ├── index.js          # node 半部（空 host，无行为）
│   └── client.js         # 浏览器半部：conversation.view 注册 + 视图
├── test/                 # host 冒烟 + client stub 注册断言
└── docs/                 # 调查 / 问卷 / 方案文档

npm test    # node --test "test/*.test.mjs"

本地调试（热更新需 dev:web 编译，否则改后重启 Web UI）：

dsh plugin --profile web add link:.

设计文档见 docs/04-方案设计-定稿.md。

License

MIT