Magic Quill

一支魔法羽毛笔，可为 OpenClaw Spellbook 自动生成主题化法术映射，覆盖主流技能，覆盖率高。

输入参数

• --topic 或 --url （主输入；法术列表查找优先按主题/题材匹配，若提供 --url，则将其视为高优先级参考源候选）
• 可选 --theme ：用于覆写最终生成的主题名称（或仅传入 --theme 以纯启发式模式运行）
• 可选 --out （别名：--output）（默认值：spells/.yaml）
• 可选 --limit （别名：--top）：指定前 N 个高覆盖率法术（默认值：50）
• 可选 --author （默认值：@magic-quill）

执行流程

1. 尽可能从以下两个来源汇总热门技能：
   • skills.sh 中的近期趋势安装列表
   • ClawHub 下载量 API 接口
2. 合并并去重上述结果，形成目标技能集（若获取失败，则用内置备用技能填充空缺）。
3. 优先采集法术列表参考源（主要法术数据源）：
   • 基于主题/题材构建动态网页搜索查询（例如： spell list 和 spells api）
   • 解析搜索引擎顶部结果链接（DuckDuckGo HTML 结果页），提取候选参考 URL
   • 若指定了 --url，则将其作为高优先级候选加入
   • 抓取发现的 JSON/HTML 参考源（例如：若发现 dnd5eapi.co），提取其中的法术名称，并对所有成功抓取的参考源中提取的名称进行合并与去重
4. 采集背景设定/ lore /上下文信息（仅用于辅助生成风格关键词）：
   • 若提供了 --url，则抓取该页面并提取正文文本
   • 否则，若提供了 --topic，则尝试调用 Wikipedia 摘要 API
   • 若上述任一抓取失败，则回退至内置主题词典/启发式规则
5. 若法术列表参考源采集失败，或提取出的法术名称数量不足，则启用内置启发式法术命名生成器补全法术映射。
6. 将生成的 YAML 写入指定输出路径（通常位于 spells/ 目录下），并在文件中添加 # spell-list-references: 注释行，列出所有成功动态发现的法术列表源/端点 URL（如可用）。
7. 若输出文件位于 spells/ 目录下，建议使用 npm run validate:spells 进行校验。

命令示例（终端用户）

npm run generate:spellbook-theme -- --theme "Studio Ghibli" --limit 50 --author "@you"
npm run generate:spellbook-theme -- --topic "Cyberpunk 2077" --limit 75 --out spells/cyberpunk-2077.yaml --author "@you"
npm run generate:spellbook-theme -- --url "https://en.wikipedia.org/wiki/The_Lord_of_the_Rings" --limit 50 --author "@you"
npm run generate:spellbook-theme -- --topic "DnD 5e" --limit 20 --author "@you"

命令示例（Agent 调用）

node magic-quill/scripts/generate-spell-mapping.mjs --theme "The Legend of Zelda" --topic "The Legend of Zelda" --limit 50 --out spells/zelda.yaml --author "@example"
node scripts/validate-spells.mjs

从此仓库安装（子路径方式）

可通过 npx skills add 指定仓库子路径安装，例如：

npx skills add wynnsu/openclaw-spellbook/magic-quill

⚠️ 使用前提：需安装 Hook

本技能仅生成法术 YAML 映射文件 —— 若希望在 Agent 会话中实际使用这些主题化法术，还需安装 openclaw-spellbook hook。请安装完整 Spellbook 包：

# 安装 Spellbook Hook（含 magic-quill 技能）
npx skills add wynnsu/openclaw-spellbook

或直接从仓库安装 Hook（不含其他依赖）：

npx skills add wynnsu/openclaw-spellbook/hooks/spellbook

该 Hook 在运行时负责将魔法风格的法术名称翻译为真实 Skill ID。

安装完成后即可使用（示例提示语）：

使用 magic-quill 创建一份 Star Wars 主题的法术映射，覆盖前 50 个高频法术，并写入 spells/star-wars.yaml。