anime-collection-book：AI Agent 工具实践指南

实际看anime-collection-book，先要确认它的用途：Turn a list of anime names (or a local video library) into a magazine-style PDF等相关能力。文档与演示交付里，内容结构和版式在转换后容易走样。我会拿一份结构复杂的真实文档完成转换，检查标题层级、表格图片、字体版式和可编辑性。它适合经常交付正式文档或演示稿的团队；采用前仍要看维护状态和试跑结果。

anime-collection-book

把一份番剧名字清单（或本机视频收藏库）做成一本"杂志风"PDF 收藏册：

总览统计卡 → 可点击目录（带页码）→ 数说收藏页（大数字统计）→ 每部作品一个主题色章节（主题色自动取自该部封面）： 官方海报 · 台词卡 · 无剧透简介 · 制作与声优 · 原作情报 · 补番顺序 · 逐季剧透详情表 · 更新动态。 海报墙封面 + 「完」字封底（书名可配），全书中文字体内嵌（霞鹜文楷子集），PDF 带可折叠书签与页脚页码。 系列完整度审计（每部「收录 M/N 条」+ 待补清单）· npm run cards 一键导出竖版收藏卡 PNG 与高清整页图（社交发图）。

内置两个领域包：config.json 的 "domain" 切换 —— anime（默认，本仓库主示例）／novel：把同一引擎用于小说设定集——每个角色一章、伏笔追踪表（franchise 字段承载）、数说设定页、读者向脱敏版，全程离线。字段映射见 domain-novel.md。

这是一个给 AI agent（Claude Code / ZCode / Cursor 等，需具备文件读写 + Shell + 联网 + 读图能力）使用的 skill，符合 Agent Skills 开放格式（SKILL.md + 附属脚本），同时按 Claude Code 插件市场规范打包。

以下效果图为 虚构演示作品（evals/fixture/，含程序生成的示例封面）——真实书本使用官方海报时请遵守下方「关于素材版权」。

为什么做它（四个踩过的坑）

这不是"排版工具"的炫技，是四个具体失败模式的解法。每条都有对应的机制，不是靠自觉：

一句话：它把"看起来小事、实际每次都会错"的环节都做成了断言或默认行为。

安装

Claude Code（推荐，一条命令）：

/plugin marketplace add 123ccw/anime-collection-book
/plugin install anime-collection-book@anime-collection-book

装好后说"我想给这几部番做个收藏册：…"即可触发。

其他 agent（手动）：

把 anime-collection-book/skills/anime-collection-book/ 整个文件夹拷进对应工具的技能目录，让 agent 读其中的 SKILL.md 照做：

⚠ DSH 同时扫 ~/.dsh/skills 与 ~/.agents/skills（实测）：同一个 skill 两处都放，会话里就会出现两份、还会互相抢触发。选一处放就行；同理，别把同一个技能市场同时用"插件安装"和"手动拷目录"两种方式各装一遍。

两种用法

模式 B 面向"已按『每部一个文件夹、每集带封面与元数据』整理过收藏"的玩家。扫描视频库生成 base.json 的脚本未随包提供（各人目录结构不同）——可让 agent 参照 SKILL.md 里的 anime_base.json 结构说明写一个。

适用范围与边界

适合：一部/一批作品的收藏册（5-20 部体验最好）；本机视频库的成册归档；小说设定集与伏笔追踪（novel 域，全程离线）。

故意不做（不是遗漏，是取舍）：

规模提示：调研是主要成本（每部都要联网查证 + 核图）。5-20 部体验最好；上百部请分批做，别一次铺开。

快速开始

1. 项目根目录（任意空文件夹）：fonts/ 放入 霞鹜文楷 的 Regular/Medium TTF
2. 写 names.txt（一行一部番剧名），让 agent 按 SKILL.md 完成调研（产出 anime_research/ 与 anime_base.json）
3. 在 skill 的 scripts/ 目录里：

   npm i                                    # 装依赖（首次）
   # 把 config.json 的 root 改成你的项目根，然后：
   npm run doctor                           # 环境自检（node/python/字体/浏览器/curl/tvly）
   npm run pipeline                         # 一键：字体子集 → 两轮构建渲染 → 页码核对
   npm run audit                            # 数据完备度：哪部缺字段、哪些还写着"未核实"
   npm run check                            # 产物断言（13 条：完整性 / 页码 / 两轮收敛）
   npm run sheet                            # 生成全页联络表（目检用）
   

脚本（skills/anime-collection-book/scripts/）

配置：所有脚本统一读 config.json（root = 项目根，vroot = 模式 B 视频库根）；日常一条 npm run pipeline 跑完。

文档分级（入口很轻，细节按需读）

SKILL.md 只放执行流程 + 质检铁律 + 最硬的坑位（约 9.6 KB），细节拆到 references/，agent 按需读、不必全量吃进上下文：

质检铁律

封面必须让 agent 亲眼看（防张冠李戴）；查不到的信息写"未核实"，禁止编造；发布前全页目检。 完整踩坑清单（13 条）与数据源用法见 references/pipeline.md。

关于素材版权

本工具只做排版：海报、立绘等图片由使用者自行从公开渠道获取，本仓库不附带任何第三方作品素材（README 与 evals/ 中的示例均为虚构作品或程序生成的占位图）。

生成的册子若包含官方海报/截图，请仅用于个人收藏；公开传播（发群、上传平台、印制售卖）前请自行评估授权——官方美术的版权属于各制作委员会/原作者。同理，角色设定与剧情资料的引用请标注来源（本工具支持在封底填写 credits）。

成品封底默认自带两行声明（资料来源 + 非官方粉丝作品 · 仅供个人收藏），不填 credits 也会输出，请勿删除。另外三条底线：

• 文字自己写：剧情简介一类文字不要逐句搬运维基百科/萌娘百科的原文（事实可引用，表述受 CC BY-SA 约束），写完抽一句回搜验证
• 只用全年龄素材：擦边/露骨素材一律不用——这类风险是刑事级，不是版权级
• 不用真人素材：声优照片、真人演员肖像涉及肖像权
• 取图官方渠道优先：动画官网 / 官方 X / 发行方 / 原作出版社 → AniList、Bangumi 条目图 → 图库（safebooru 等）仅作候选对比兜底。官方渠道的图授权链更干净、画质也是母版；用图库定位到图后，尽量回溯官方原图再入库

隐私：外发前请清理

把项目文件夹交给别人、上传网盘或打包分发前，删掉三个东西：

这三样都不在版本库里（见 .gitignore），但手动"拷贝整个文件夹"时会一起被带走。顺手补一句好消息：生成的成品是干净的——实测 番剧收藏简介.html 与 .pdf 正文及元数据里都不含本机路径或用户名。

许可

• 本仓库代码：MIT（见 LICENSE）
• 使用时自备的字体：霞鹜文楷（LXGW WenKai），SIL OFL 1.1 授权，版权归 LXGW 与上游 The Klee Project Authors 所有（基于 FONTWORKS「Klee One」衍生）。字体不进本仓库，需从 GitHub Releases 自行下载；管线会子集化后嵌入你的成品，封底自动附版权署名（OFL 要求版权声明随字体软件分发，请勿删除）。