mcpField
C
chinese-poetry-api

chinese-poetry-api

github.com/wmy2981创意与媒体157 次安装5 周前更新
代码仓库

关于 chinese-poetry-api

chinese-poetry-api 是一个调用 chinese-poetry-api REST 服务的命令行技能，面向需要查询和检索中文诗词的用户。它支持简体与繁体输出，并提供诗作、作者、朝代和体裁等查询。

主要功能

  1. 01列出并筛选诗作
  2. 02按标题、内容或作者搜索
  3. 03获取随机诗作
  4. 04查询作者、朝代与体裁
  5. 05切换简体或繁体中文

适用场景

  1. 01按作者或朝代查找诗作
  2. 02搜索诗词标题或正文
  3. 03随机获取诗作用于阅读

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wmy2981/skills --skill chinese-poetry-api

安装后在 Claude Code 中输入/chinese-poetry-api确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.claude-plugin/
plugin.json
scripts/
.env.example
main.ts
package.json
tsconfig.json

详细介绍

中国诗词 API

基于 chinese-poetry-api REST 服务的命令行封装（Go，约 37 万首诗词，支持通过 lang 切换简体中文和繁体中文）。

执行规则

直接运行用户的命令，无需预先检查；若失败，则修复问题。

要求

  • Bun 运行时（>= 1.0）
  • 可访问的 chinese-poetry-api 实例

设置

脚本读取 POETRY_API_URL 环境变量——该变量应为完整的 API 基础 URL（脚本不会追加前缀）。默认值为 https://poetry.palemoky.com/api，这是上游开发者提供的在线测试实例。该实例可能会限流、变更数据或在未通知的情况下离线——请仅将其作为演示使用。若要用于实际工作，请将 POETRY_API_URL 指向你自己的实例（本地 Docker 或自托管部署）。

  1. 查看 scripts/.env.example，确认变量名称。
  2. 在共享全局文件 ~/.wmyskills/.env 中添加或更新 POETRY_API_URL。
  3. 不要直接将 .env.example 复制为 .env，否则会覆盖现有配置。

如果用户的请求需要一个尚未运行的实例，请先通知用户，再启动实例：

docker run -d -p 1279:1279 palemoky/chinese-poetry-api:latest

用法

bun run scripts/main.ts <command> [options]

所有输出均为服务器返回的原始 JSON 正文——请原样打印，不要重新格式化或概述。对于非 2xx 响应，将 Error <status>: <body> 输出到 stderr，并以 1 退出。

命令描述选项
health健康检查—
stats总体统计—
poems列出诗词（可组合筛选条件）--dynasty --author --dynasty-id --type-id（可重复，OR）--page --page-size（最大值为 100）
search全文搜索（FTS5）--q（必需）--type（默认为 all，可选 title、content、author）--page --page-size
random随机诗词--author --author-id --dynasty --dynasty-id --type（可重复，OR）--type-id --char
authors列出作者（分页）--page --page-size
author按 ID 获取作者--id（必需）
dynasties列出朝代（附诗词数量）—
dynasty按 ID 获取朝代--id（必需）
types列出诗词类型—
type按 ID 获取诗词类型--id（必需）

每条命令都接受 --lang zh-Hans|zh-Hant，用于切换简体中文和繁体中文（默认值为 zh-Hans）。无效的标志或参数会在发送请求前被拒绝，并返回错误。

示例

# Health check and overall stats
bun run scripts/main.ts health
bun run scripts/main.ts stats

# Li Bai's poems, page 2
bun run scripts/main.ts poems --author 李白 --page 2 --page-size 10

# Poems from the Tang dynasty in traditional Chinese
bun run scripts/main.ts poems --dynasty 唐 --lang zh-Hant

# Full-text search
bun run scripts/main.ts search --q 静夜思
bun run scripts/main.ts search --q 明月光 --type content

# Random 五言绝句 by Li Bai (multiple types are OR)
bun run scripts/main.ts random --author 李白 --type 五言绝句 --type 七言绝句

# 飞花令 — poem containing a single character
bun run scripts/main.ts random --char 春

# Metadata
bun run scripts/main.ts authors --page 1 --page-size 20
bun run scripts/main.ts author --id 1
bun run scripts/main.ts dynasties
bun run scripts/main.ts dynasty --id 6
bun run scripts/main.ts types
bun run scripts/main.ts type --id 10

备注

  • --char（飞花令）只能接受一个字符，且只能与 --lang 组合使用——其他筛选条件会导致服务器返回 400。
  • 查询参数由服务器端验证：未知参数或大于 100 的 page_size 会导致服务器返回 400，因此不要自行添加 API 文档中未说明的筛选条件。

评论

支持 Markdown