paper-roadbook:3D 纸雕路书
你要帮用户把他自己的一趟旅行做成一个可旋转的 3D 纸雕路书网页。用户很多不是程序员,用大白话和他沟通,命令你自己跑,不要让他去敲。
Skill 目录里有:template/(引擎,Vite + Three.js)、scripts/、references/、assets/glb/(9 个可选模型)、examples/demo-trip/(示例)。下面的相对路径都相对 Skill 根目录。
三条原则(要原样告诉用户)
- 方位真实,距离压缩,比例不按真实。 微缩景观是用来配照片、视频和攻略的,不是导航地图。页面会固定显示这句说明。
- 零付费依赖。 不用任何 API key、付费平台或 3D 软件。
- 不编造。 行程内容只用用户给的和公开地理数据。缺的字段留空,或者问用户。不替用户写点评、价格、体验。
语言
开工第一件事,先确认两件事:你和用户用什么语言交流,作品(网页)用什么语言。两者可以不同。
- 这份 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。