Communitygithub.com

paper-roadbook

帮用户把自己的一趟旅行做成「3D 纸雕路书」交互网页:一块可旋转的微缩纸雕地图,上面有山、湖、路线和纸模型小物件,点每个站点能看自己的照片、视频和笔记。当用户提到路书、旅行地图、3D 地图、行程地图、纸雕地图、travel map、roadbook、3D itinerary、把旅行做成网页时使用。全程不需要任何付费 API 或 3D 软件,只需要 Node 20.19+ 或 22.12+、Python 3.9+、ffmpeg。

Qu'est-ce que paper-roadbook ?

paper-roadbook is a Claude Code agent skill that 帮用户把自己的一趟旅行做成「3D 纸雕路书」交互网页:一块可旋转的微缩纸雕地图,上面有山、湖、路线和纸模型小物件,点每个站点能看自己的照片、视频和笔记。当用户提到路书、旅行地图、3D 地图、行程地图、纸雕地图、travel map、roadbook、3D itinerary、把旅行做成网页时使用。全程不需要任何付费 API 或 3D 软件,只需要 Node 20.19+ 或 22.12+、Python 3.9+、ffmpeg。.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Aprillllllw/paper-roadbook/tree/HEAD

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

paper-roadbook:3D 纸雕路书

你要帮用户把他自己的一趟旅行做成一个可旋转的 3D 纸雕路书网页。用户很多不是程序员,用大白话和他沟通,命令你自己跑,不要让他去敲。

Skill 目录里有:template/(引擎,Vite + Three.js)、scripts/、references/、assets/glb/(9 个可选模型)、examples/demo-trip/(示例)。下面的相对路径都相对 Skill 根目录。

三条原则(要原样告诉用户)

  1. 方位真实,距离压缩,比例不按真实。 微缩景观是用来配照片、视频和攻略的,不是导航地图。页面会固定显示这句说明。
  2. 零付费依赖。 不用任何 API key、付费平台或 3D 软件。
  3. 不编造。 行程内容只用用户给的和公开地理数据。缺的字段留空,或者问用户。不替用户写点评、价格、体验。

语言

开工第一件事,先确认两件事:你和用户用什么语言交流,作品(网页)用什么语言。两者可以不同。

  • 这份 Skill 和脚本的提示是中文写的。你读中文,给用户看的一切(骨架卡、检查结果、提问)都转成用户的语言。
  • 网页上的所有文字都用作品语言,包括按钮、标签和底部那句说明。模板自带中文和英文两套界面文字(trip.json 的 lang);其他语言直接改 src/ui/shell.js 里的文字。
  • 字体、地名写法这些细节由你判断。模板只带拉丁字体,别的文字靠系统字体,想换就加字体文件、改 src/style.css。扫描脚本取到的地名不合适,就按用户的语言改。这些和自造组件一样,都可以改。

隐私

  • 用户照片里常带 GPS。所有照片视频必须过 scripts/process_media.py(会去掉 GPS 和设备信息),不要直接把原图放进 public/。
  • 用户的姓名、头像、家庭住址、实时位置只在用户明确提供且同意展示时才写进页面。
  • 部署到公网之前必须得到用户同意(第 9 步)。

流程

每一步结束前确认过关条件,再进下一步。遇到报错先查 references/troubleshooting.md。

1. 收集行程

  • 做什么:问清楚并记下:总天数;每天的站点(先后顺序);每站的类型(住 / 路过 / 景点),住哪、吃什么、感受、花费(有就写,没有就空着);素材文件夹在哪(照片视频,最好一个站点一个子文件夹);用户想写在页面上的名字和一句话介绍;语言(中文或英文);季节。
  • 向用户要:以上信息。用户给了一篇游记或笔记也可以,你来整理成清单。
  • 产出:一份行程清单(文字)。
  • 过关:每个站点都有名字和所在的天;你没有替用户补任何他没说过的事实。

检查点 A:内容够不够摆满一张图。 把站点清单或 trip.json 草稿交给 python3 scripts/fullness.py --pre <文件>。它说「空」,就把它列出的问题转述给用户(站点太少、哪几站只有名字、路上见过什么),等用户回答,补进清单再往下。用户说「就这样」可以跳过。

2. 信息核对

  • 做什么:把清单按「第几天 / 站点 / 类型 / 住宿 / 花费 / 备注」列给用户,请他逐项确认或改。重点核对站点顺序、天数、花费数字。
  • 产出:确认后的清单。
  • 过关:用户明确说「对」。

3. 地理骨架扫描

  • 做什么:用每个站点的真实经纬度(用户给,或你用公开地名查询得出后让用户确认)整理成 stops.json([{"id","name","lat","lon"}],也可带 days),再跑 python3 scripts/geo_scan.py stops.json --out scan --name 地区名 --season winter(其他参数见 --help)。它用公开高程和地图数据,算出站点之间的相对方位和压缩后的距离,输出 skeleton_card.md 和 scene.draft.json 到 scan/。
  • 向用户要:站点的大致位置。
  • 注意:这一步要联网取公开数据,可能要几分钟,公共水系服务偶尔超时。缺了数据(比如河流、湖泊)时,要用人话告诉用户缺了什么,说明可以稍后原样重跑;也可以请用户直接说有哪些主要河流和湖。不要把英文报错原样贴给用户。
  • 产出:骨架卡 skeleton_card.md。把它给用户看:站点相对位置、山在哪一侧、水在哪一侧、镜头从哪个方位看进来。
  • 过关:用户确认或纠正了骨架卡里每一条方位。纠正了就改草稿,不要凭自己的印象坚持。

4. 微缩构图

  • 做什么:读 references/composition-guide.md,把 scene.draft.json 调成 scene.json:后排放最高的山,站点和路线放进底板椭圆,加平整地基和摆件,选主题(winter-blush 冬季,summer-meadow 其他季节)。字段含义见 references/scene-schema.md。
  • 产出:scene.json。
  • 过关:stops 的 id 与行程一致;坐标都在椭圆内;每天的路线都有;摆件 type 都是已有组件,或第 7 步会做的。

检查点 B:画面饱满度。 运行 python3 scripts/fullness.py scene.json [trip.json],结果是「空 / 及格 / 饱满」。

  • 不及格:把报告里每块空白的位置和建议问题,用大白话转述给用户(不报坐标),让他说出那里真实有什么。用户回答后摆到 scene.json;引擎没有的组件按 references/component-recipes.md 现做(第 7 步);重跑,直到及格。
  • 用户明确说「就这样」,可以跳过。有意留白也可以保留,但要说得出理由。
  • 界线(不编造原则): 自然填充(树、草丛、石头、云、普通田地)可以按当地地貌自己补,不用问。具体的东西(建筑、动物、人、船、车、地标)必须是用户说过或确认过的。你只能给建议清单让用户选,不能自己决定放什么。
  • 怎么摆得满,见 composition-guide.md 的「填满画面」。

5. 新建工程

  • 做什么:python3 scripts/new_project.py <工程目录> --scene scene.json,然后进目录 npm install。不传 --trip 时会按 scene.json 的站点和路线生成一份占位 trip.json(标题等都是「在这里写…」),必须替换;什么都不传则保留示例数据(也要替换)。再按 references/trip-schema.md 写 src/data/trip.json:标题、作者、days、stops、facts、disclaimer(保留)。
  • 向用户要:工程放在哪个目录。
  • 产出:能 npm run dev 的工程,trip.json 已写好(先不含照片)。
  • 过关:python3 scripts/validate.py <工程目录> 无错误。

6. 处理照片视频

  • 做什么:python3 scripts/process_media.py <素材文件夹> --out <工程目录>/public/media。每个站点一个子文件夹,文件夹名就是站点 id。输出照片 webp、720p 无声视频(最长 15 秒)和封面图,并清除 GPS。把 media_manifest.json 里的列表粘进 trip.json 对应站点的 media(清单默认只含 type/src/poster,不写原始文件名;调试时才加 --debug-manifest)。
  • 向用户要:素材文件夹;没分站点的素材,问他每张属于哪站。
  • 产出:public/media/ 下的文件,trip.json 的 media 已写好。
  • 过关:validate.py 通过;用户知道照片已经去掉 GPS。没有素材的站点只显示文字,不要放占位图冒充。

7. 补做缺的组件

  • 做什么:scene.json 里需要但引擎没有的东西(牦牛、清真寺、渡轮……),读 references/component-recipes.md,在 src/components/custom/ 里现做一个。做完在 npm run dev 后打开 /gallery.html?type=<名字>,从斜俯视、正侧面、正前方三个角度自查,截图看。检查清单在那份文档第 7 步。
  • 产出:自造组件文件,自查截图。
  • 过关:三个角度都认得出是什么,没有零件埋住或穿模。不认得就改,别交付。

8. 校验、构建、预览、迭代

  • 做什么:python3 scripts/validate.py <工程目录>;npm run build;npm run dev 或 npm run preview 在本地打开。能开浏览器就截图(俯视、点开一个站点面板各一张)给用户看;不能就把本地网址给用户,请他打开看。
  • 过关:页面能转动,路线动画正常,站点面板的文字和照片对得上。用户有意见就改 scene.json 或 trip.json 再看,直到他满意。

9. 可选部署

  • 做什么:用户想发给别人看时,说明构建产物在 dist/,是纯静态文件,可以放到任意静态托管(用户自己的账号,如各类静态网站托管、对象存储)。具体步骤以用户选的服务的官方文档为准,你不替用户注册或绑定账号。
  • 发布前必须得到用户同意,并再提醒一次:页面上的名字、头像、照片、笔记发布后别人都能看到。
  • 过关:用户明确同意后才发布;发布后把网址给用户。

其他

  • 引擎坏了或页面空白:references/troubleshooting.md。
  • 想看成品长什么样:examples/demo-trip/。
  • 模型文件 assets/glb/ 可选用:复制到工程 public/glb/(new_project.py --with-glb 一次复制全部),再写 "opts": {"glb": "glb/horse.glb"},详见 references/scene-schema.md。使用条款见 ASSETS_LICENSE.md。

Skills associés