纸艺书页生成器

纸艺书页生成器 是做什么的？

一本立体书的一页，本质上是一个由纸艺零件构建的JSON文件（称为“时刻”）。scripts/build.mjs 脚本可将一个或多个“时刻”文件编译成一个完整的HTML文件。照片仅作为参考，不会嵌入书页中。

首先阅读：references/kit.md（了解所有零件、参数、调色板键值以及折叠规则），然后浏览examples/中与照片主题最接近的示例：海岸或骑行（bay-trail）、花园、房屋或节日场景（filoli-halloween）、地标（golden-gate）、商店或咖啡馆（cafe）。

输入

• 一张照片（仔细查看），以及用户的一段文字描述，通常两者兼有。
• 地点和日期，信任优先级依次为：用户描述 > 照片EXIF信息 > 文件名。scripts/photo.py <photo> 会输出日期、GPS坐标、尺寸和调色板建议（使用其中的场景颜色，忽略封面和条纹，房屋块会保留这些）。自行从文件名中读取地点（如果有）。没有EXIF的文件日期通常不准确（重新保存的照片会携带保存日期）：需要询问。如果地点未知，先问一个问题，同时继续处理其他部分。
• 如果用户已有立体书（一个包含多个“时刻”文件的文件夹），新页面将加入其中：将所有文件一起构建。

质量标准

四个示例是标准参考。在交付前，先与最接近的示例进行比较。

• 4到6个故事零件，分布在至少3个图层中：后层、中层和前层。引擎拒绝超过6个；少于4个会显得空洞。
• 两个可交互元素，除了天空转盘外：一个供读者点击（如铃铛、海鸥、门），一个供读者拖拽（如拉片、杠杆、滑块、旋转画片）。check.mjs 会列出两者，如果任一为空则报错。kit.md 第1节“读者的交互”列出了所有支持点击或拖拽的零件。如果用户的照片或文字中没有可点击的内容，在添加之前先问一个问题（“那里还有其他东西吗？比如鸟、旗子、铃铛或门？”）。如果回答是否定的，则直接交付低于标准的页面并说明情况。
• 一个自动循环动画。 场景中应有某个物体在白天自动运动：如车流、骑手、船只、蒸汽、飞鸟、旗帜、树叶。从照片或文字中选择移动或呼吸的物体。点击、拖拽和初始提示不计入。check.mjs 会输出 alive: 并在空时报错。
• 优先使用现有零件库。 尽可能使用现有零件构建：山丘、树木和树篱作为图层带，路灯、人物、骑手、飞鸟。仅当场景中的主角现有零件无法实现时，才创建新零件（参见“新零件”部分），每页最多一个。
• 仅包含照片或文字中的内容。 不添加装饰性道具。如果照片简单导致场景单薄，请说明，而不是自行发明。
• 房屋灯光和书本不变。 new.mjs 脚本会生成房屋块（书形、封面、书页边缘、台灯、灯光、相机）。白天为柔和的摄影棚光，夜晚为月光加台灯；时间和天气通过调色板、天空转盘和台灯来表现，绝不可改变光源。
• 人物代表用户本人，除非用户另有说明。根据照片为他们着装（palette.figure：外套、围巾、裤子、头发、肤色）。如果只有文字描述，保留示例的人物颜色，除非用户提到穿着，并在注释中说明猜测。如果照片中没有围巾：将scarf设置为外套颜色。不要添加用户未提及的人、宠物或同伴。

工作流程

1. 读取照片。 运行 python3 scripts/photo.py <photo> --swatches swatches.png，然后自行观察：哪些元素位于后层、中层、前层；用户可能会指出的主角；什么会自动移动、什么可以触摸；时间；天气。
2. 场景简报（自己的笔记）：装订方式（side，即V形折叠全景，适用于几乎所有情况）；从前到后的图层及每个图层使用的零件；点击和拖拽元素；自动循环动画；夜晚表现方式（台灯、窗户、转盘的月亮、车头灯）；根据photo.py的猜测调整调色板，提亮并暖化一个级别（书本是纸质的，不是印刷品），精简到零件读取的键值（kit.md第3节）。
3. 开始创建页面。 运行 node scripts/new.mjs <id> --place "地点, 城市" --date YYYY-MM-DD --dir <用户书文件夹> --like <最接近的示例>。id为简短、短横线连接的格式（如bay-trail、cafe）。填充pieces和场景调色板。为每个可点击或拖拽的零件添加label，用两到三个简单词汇（如“帆船”、“咖啡馆门”）：键盘路径和屏幕阅读器会使用它。
4. 折叠平整。 当书本合上时，每一层都必须能够平放。侧边装订：每个图层的一半在折痕x0处沿书脊折叠，因此 x0 + height * 0.966 <= 0.75（书宽1.5，铰链角度105度）。后方的图层空间最小：当x0为0.46时，一半可站立0.3；当x0为0.52时，仅可站立0.24。位于图层上的转盘、飞鸟或人物计入其高度。靠近读者的图层也会向读者边缘折叠，因此其伸展范围应保持较短：大致 x0 - reach * 0.26 >= -0.75。验证器会检查两者并指出是哪一半以及伸展范围。一个vfold-wrap半片即使没有放置任何东西，也需要一个绑带，因此其reach至少为tieReach（0.12），不可小于此值。天空转盘铆接在其宿主图层后面：保持该图层在转盘位置的低矮（例如，estate树线需要设置一个dip），否则转盘会隐藏。
5. 构建并检查。 运行 node scripts/build.mjs <dir>/*.json --out <dir>/book.html --title "<用户标题>" --author "<用户姓名，如果提供>"，然后运行 node scripts/check.mjs <dir>/book.html --page <id>（截图会保存到 <dir>/shots/<id>/）。该脚本会输出验证器的错误、交互列表和alive:信息，并保存白天和夜晚的手机版和桌面版截图，以及card.png。先查看夜晚截图：发光效果、台灯和窗户只有在夜晚才能暴露问题。将白天手机截图与最接近的示例（运行build.mjs examples/<那个>.json并检查）并排比较：如果您的页面看起来更空旷，说明未完成。在此处迭代，而不是交付后再修改。
   • 没有 Playwright？书本也会自检：在浏览器中打开 book.html。有错误的页面会被跳过，并在页面上显示错误信息。
6. 标题文字。 将用户的描述润色成两个版本：第一人称，一句话，简单词汇，约10个字或更少。地点行位于标题下方，因此标题不要重复地点：描述发生了什么或感受，而不是地点。两个选项应真正不同（一个更接近用户的原话，另一个更简短）。不要添加用户未提供的事实、感受或人物。将选项1放在caption中，并提供选项2。
7. 交付。 发送 book.html（这就是整本书：用户可以打开它、通过邮件发送或托管在任何地方），如果制作了card.png也一并发送，并附上简短说明：

   <地点> · <月日>
   场景中：<一行，从后到前>
   交互：点击<什么>，拖拽<什么>，转动太阳转盘
   自动运动：<什么自动移动>
   标题：1. <选项1>  2. <选项2>
   

   仅当用户必须知道某些事情时（如猜测的日期、简单的照片、新的零件库零件）才添加一行。

团队分工

如果您的智能体可以将工作分配给子智能体，需要创建新零件的页面可以拆分为四个部分同时进行。仅使用现有零件库的页面最好独立完成：交接成本高于节省的时间。侦察者和编辑者只需用户的文字和照片，因此可以同时运行；构建者等待侦察者，审核者等待构建者。

• 侦察者： 步骤1和2。获取照片和文字。交付场景简报、场景调色板（JSON片段），以及需要向用户提出的一个问题（如果有）。
• 构建者： 步骤3到5，以及简报所需的新零件（如果需要）。获取简报、调色板和照片。运行构建和检查脚本，修复显示的问题。交付时刻文件、check.mjs的输出和截图文件夹。
• 审核者： 不构建任何东西。获取截图、照片或文字，以及最接近示例的截图。先查看夜晚截图，再查看手机版截图：检查质量标准（点击、拖拽和自动循环动画）、折叠平整性、页面边缘无裁剪、无图层遮挡、每个零件都来源于照片或文字。交付“完成”或一个编号列表的修复项，每项指定具体零件。构建者修复并重建，审核者再次查看。经过三轮后，交付仍存在的问题并说明情况。
• 编辑者： 步骤6。获取文字、地点和日期，绝不查看截图。交付两个标题选项。

您本人执行步骤7。仅在问题仍存在时，在说明中标注一个审核点。

新零件

当照片中的主角是现有零件库无法制作的（如灯塔、旋转木马）时，在 book/kit/ 中参照最接近的现有零件添加一个零件：纸材从 book/engine/paper.js 获取，点击和拖拽交互参照 shop-front（book/kit/cafe.js）和 layer-rider（book/kit/panorama2.js）的方式实现，空闲循环在 tick(t, dt, loops) 中编写，仅当 loops 为真时运行。在 book/kit/index.js 中注册，包含 build、about，侧边装订还需 panorama: true 和 declare。引擎每帧写入每个部分的矩阵，因此您放置或动画化的任何内容都必须位于该部分内部的组中，而不能在部分的根节点上。灯光、暗色、减少动效和触控由引擎提供，无需特殊处理。预计需要一小时或更多时间；仅使用现有零件库的页面只需几分钟。

用户获得的内容

一个约1.8MB的HTML文件：打开的书本、其下方的标题和地点、日/夜切换开关（书中的转盘也可切换），以及当有多个页面时的箭头和日期标签。需要WebGL和现代浏览器；不发起任何网络请求。拖拽、点击和键盘均可工作（Tab键可遍历每个可交互零件，Enter键点击，方向键拖拽）。

不可变更的规则

• 照片绝不会放入书页或您返回的文件夹中。不包含用户未在文字中提及的任何人的姓名、年龄或细节。
• 标题和地点中的每个词都必须是用户的原话或经过确认。
• 说明您无法检查的部分：脚本从未在Safari、Firefox、真实手机或屏幕阅读器上测试。