themed-shop-static-publisher

name	themed-shop-static-publisher
description	把主题小店玩法项目生成为一个可直接打开游玩的静态页面，并发布为公开链接。当用户想“做一个可玩的主题小店页面”“把某个店铺主题自动出成静态成品页”“调用 Neta creative 生成店铺素材并分享成品”时，必须使用这个 skill。它适用于：从一句店铺想法出发，生成概念、文案、商品图、助手立绘、装饰贴纸、按钮贴纸与音效完整资源，组装为可玩的静态 HTML，并最终发布公开 URL。

Themed Shop Static Publisher

这个 skill 把当前 witch-curio-shop-mvp-2 项目作为主题小店生产引擎来使用，而不是让终端用户自己走完整建店流程。

主流程和用户体验保持不变：

用户给一句店铺想法 → Agent 定概念 → 自动生成内容与素材 → 导出打开即玩的静态页 → QA → 发布公开 URL

内部实现必须同步当前项目的新架构：OAuth / LLM concept、world-shop-agent/v1 handshake、本地或远程 build agent、Neta creative 图像管线、主题色校验与自动对比度修正、可持久化/可缩放装饰布局、装饰与按钮贴纸、音效资源、ready session 与静态注入。

强制前置步骤：Neta device login

在运行任何创建商店 / 生成素材 / 启动 build agent / 导出成品流程之前，必须先执行 Neta Skills 设备登录检查。这是本 skill 的第 0 阶段，优先级高于 concept、content pack、素材生成和静态导出。

要求：

• 每次开始主题小店创建任务时，先检查当前引擎项目的 Neta skill 登录缓存是否存在且可用。
• 如果没有登录、登录失效、找不到 access token，必须先走 device login，不得继续进入 build。
• 登录缓存只能放在引擎运行目录的 generated/.neta-skill-config 下，不能写入 supermarket/stores/、outbox/、/public、归档目录或 git 仓库。
• token 只能作为运行期环境变量传给 worker，例如 NETA_TOKEN，严禁写入静态导出、QA 报告、发布目录或任何可分享文件。
• 若用户尚未完成授权，应暂停在登录阶段，并明确说明“开店前需要先把 Neta 创作通道接通”。

推荐命令，<project> 应替换为实际使用的引擎根目录：

NETA_CONFIG_DIR="<project>/generated/.neta-skill-config" \
  npx -y @talesofai/neta-skills@latest login --action request-code

NETA_CONFIG_DIR="<project>/generated/.neta-skill-config" \
  npx -y @talesofai/neta-skills@latest login --action verify-code

设备登录完成并确认 token 可供运行期读取后，才能进入后续阶段。

阶段 0：登录与引擎准备

1. 选择引擎目录：优先活跃项目 /workspace/03-gameplay-projects 🎮/active/witch-curio-shop-mvp-2；否则使用本 skill 的 project-engine/witch-curio-shop-mvp-2/ 或 workspace 本地引擎副本。
2. 设置：

   NETA_CONFIG_DIR="<project>/generated/.neta-skill-config"
   

3. 检查 Neta skill 登录缓存；如不可用，执行 device login。
4. 从登录缓存中取得运行期 access token，并仅以环境变量方式注入 worker：

   NETA_TOKEN="<runtime-only-token>"
   

5. 完成以上步骤后，才允许进入“阶段 1：准备建店输入”。

目标

输出一个：

• 已完成主题定制
• 打开就能玩，不进入 creator 建店页
• 保留原项目核心玩法体验：合成、订单、补给、图鉴、收藏、装饰拖拽与缩放、助手、入场序章、经营回顾、音效
• 资源完整、无默认旧素材冒充新成品
• 可通过公开 URL 访问

的静态页面成品。

何时使用

当用户提出以下任务时使用：

• “帮我做一个某某主题的小店可玩页面”
• “把这个玩法项目变成最终成品静态页”
• “直接生成并分享一个能玩的主题店铺页面”
• “调用 Neta creative 自动出素材，然后发布页面”
• “基于 witch-curio-shop-mvp-2 生成一个主题小店游戏”

目录与关键文件

独立引擎引用：

• 先阅读 project-reference/ENGINE_REFERENCE.md，它记录了本 skill 依赖 witch-curio-shop-mvp-2 的哪些部分、运行产物、静态注入契约、Neta skill 登录方式、Linux 图片转换注意事项、以及图名绑定 QA。
• 本 skill 仓库内已内置一份可直接引用的引擎子集：project-engine/witch-curio-shop-mvp-2/。这里复制了运行/构建必需脚本和资源，不包含 node_modules、生成产物、私密登录缓存、.git 或原始音频 zip。
• 当工作区存在活跃项目 /workspace/03-gameplay-projects 🎮/active/witch-curio-shop-mvp-2 时，优先使用活跃项目；当活跃项目不存在或需要独立复现时，可使用 project-engine/witch-curio-shop-mvp-2/ 作为内置引擎副本。

项目根目录：

• 首选活跃项目：/workspace/03-gameplay-projects 🎮/active/witch-curio-shop-mvp-2
• 内置引擎子集：project-engine/witch-curio-shop-mvp-2/

当前核心文件：

• server.mjs：本地 orchestrator、静态服务器、session/build API、SSE、LLM content pack 编排、agent provider 路由
• creator.js：前端建店/确认/构建进度/进入店铺流程
• app.js：核心合成店铺玩法、runtimeConfig 注入、主题对比度归一化、装饰贴纸拖拽/缩放/持久化、UI 按钮贴纸、图鉴/收藏/订单等
• styles.css：游戏主体与 creator/building 页面样式
• sfx.js：音效系统
• assets/sfx/：本地音效文件，静态导出必须包含
• builder/agent-handshake.md：world-shop-agent/v1 本地/远程 agent 协议
• builder/local-codex-worker.mjs：本地构建 worker，按阶段生成/校验素材并完成 session
• builder/local-asset-pipeline.mjs：Neta creative 图片生成、切图与 runtimeConfig 产物组装
• builder/skills/shop-builder/profile.json：生成计划，包含 requiredImages、切图行列等
• builder/skills/shop-builder/prompt_*.md：concept、assistant、shop sheet、decor、UI button、world patch 的生成约束
• generated/current-session.json：当前 ready session 常见位置；这是引擎全局临时态，不得作为新商店最终导出的 source of truth，除非它刚由同一 build 生成且通过 cross-shop contamination QA。
• generated/build-artifacts/<jobId>/...：当前 job 的生成图片、切图与 manifest
• generated/archives/.../session.json：可复用的会话归档示例，如项目中存在

注意：当前远端项目可能不再自带 builder/export-static-site.mjs、builder/qa-static-site.mjs、builder/publish-static-site.mjs。如果缺失，Agent 必须按本 skill 的“静态导出要求”临时补齐或使用等价脚本完成导出，不得因此把 creator 页面直接当作成品发布。

工作方式

阶段 1：准备建店输入

原则：

• 只在概念尚未定稳时追问用户。
• 概念一旦定下，后续一律默认自动推进。
• 不要在 concept 之后继续把 content pack、素材、导出、分享拆成一堆确认问题抛给用户。
• 对外话术始终保持“筹备开店 / 布置柜台 / 准备开张”的语境。

至少收集：

• shopIdea：店铺主题想法

可选：

• worldName
• shareSlug
• outputName

默认可使用：

• worldName = 你的世界
• 日期格式：YYYY-MM-DD
• shareSlug 可由主题名自动生成，必须 URL 安全

阶段 2：生成 concept

concept 可以走项目现有链路：

• 前端 OAuth 直连 Neta LLM；或
• 调用 server.mjs 中等价的 concept 生成逻辑；或
• 在自动化执行中复用当前 session / archive 的 concept。

concept 必须包含或能推导：

• worldName
• shopIdea
• shopName
• summary
• assistantName
• assistantRole
• assistantSummary
• loopSummary
• confirmationLine
• readySummary
• runtimeConfig.theme
• runtimeConfig.shopName
• runtimeConfig.brandEyebrow
• runtimeConfig.assistantName

主题色硬性要求：runtimeConfig.theme 必须至少包含以下 token，且必须是安全颜色值：

bgTop, bgBottom, paper, paperSoft, gold,
shopBgTop, shopBgMid, shopBgBottom,
shopLight, shopLightSoft,
shopPanel, shopPanel2,
shopPaper, shopPaperSoft,
shopCard, shopCardDark,
shopBorder, shopBorderDark,
shopGold, shopGoldSoft,
shopGreen, shopRed,
shopText, shopInk, shopMuted

可读性要求：

• 文本颜色必须和 panel、card、tab、button、dialogue bubble、modal、toast、report 背景明显区分。
• modal / popup backdrop 必须是偏暗的店铺遮罩，不要使用明亮发白的 veil。
• 助手/店员区域是主要视觉组件，不能只当小状态条处理。
• 当前项目会在前端/后端用 normalizeThemeContrast() 派生可读色 token，例如 shopOnPanel、shopOnCard、shopOnButton、shopMutedOnBubble 等；生成时仍应优先给出高对比基础色，不要依赖自动修正掩盖明显不可读的主题。
• shopLightSoft 可以是 rgba()，其他基础 token 优先使用 #RRGGBB。

阶段 3：通过 build agent 生成内容与素材

优先复用项目现有生产链：

0. 如需真实 Neta creative 出图，先用 Neta skill device login 登录，而不是依赖项目内前端 OAuth：

   NETA_CONFIG_DIR="<project>/generated/.neta-skill-config" \
     npx -y @talesofai/neta-skills@latest login --action request-code
   
   NETA_CONFIG_DIR="<project>/generated/.neta-skill-config" \
     npx -y @talesofai/neta-skills@latest login --action verify-code
   

   然后从 Neta skill 登录缓存中取 access token，作为 worker 环境变量 NETA_TOKEN 注入。本 token 只用于运行期，严禁写入静态导出目录、/public 或 git 仓库。
1. 启动主服务：

   npm start
   

2. 启动本地 worker：

   npm run start:local-worker
   

3. 通过项目 API 触发 build：
   • POST /api/build/start
   • 或使用项目已有前端流程触发
4. server 生成 world-shop-agent/v1 handshake。
5. active provider 执行构建：
   • local-codex：本地 builder/local-codex-worker.mjs
   • remote：SHOP_AGENT_BASE_URL 对应远程 agent
6. 等待 session 进入 ready。

当前强制顺序

0.5 per-shop source-of-truth 与污染隔离

每个要发布的商店必须有自己的 source-of-truth。推荐路径：

supermarket/stores/<slug>/
├── concept.json
├── content-pack.json
├── generated/session.json
├── generated/build-artifacts/<jobId>/...
├── static-export/
└── qa/qa-report.json

硬性规则：

• 不得把 engine/generated/current-session.json 当成最终导出源，除非它刚由本轮同一 build 产生，并且 concept/runtimeConfig/contentPack/profile.generatedAssets 均指向本轮商店。
• 不得用主题专用旧脚本导出其它主题，例如 export-laoqin-static.mjs、export-starbucks-static.mjs、mars-build.mjs、red-alert 相关脚本。必须使用 builder/export-static-shop.mjs 或等价通用导出器。
• 禁止把 /public/<slug>/ 作为唯一修复位置。直接 patch public 只能算临时热修；最终必须回写 supermarket/stores/<slug>/ 的 locked package，重新导出、QA、发布。
• 每个静态商店必须自带完整 runtime：theme、contentPack、tileManifest、assistantPortraits、decorationManifestUrl、uiButtonManifestUrl、对应 manifests 和生成资产，且 URL 全部为相对路径。
• final static 不允许从默认 demo/旧主题补齐缺失内容。recipes、blessings、intro/order 等如果为空，必须在本店 content pack 中显式为空或写成本店内容；不得让 mergeContentPack() 静默混入生日/HP/咖啡/其它旧店默认值。
• static localStorage/save key 必须按 shop slug/build/shopName/worldName 隔离，或在 static boot 时拒绝不兼容旧存档。全局 key 会让生日店的棋盘、主题、发现、装饰污染皮埃尔店这类新店。
• static 初始化顺序必须是：读取并 sanitize window.__SHOP_RUNTIME__ → merge 当前 contentPack → rebuild item index/tile bindings → createInitialState/加载兼容存档 → render。禁止先用默认 runtime 创建棋盘，再切换到本店 runtime。
• 首屏主题必须预水合：index.html 或首屏 CSS 必须写入本店 theme tokens。不能只依赖 JS 启动后 applyThemeTokens；JS 缓存/延迟/报错时也不得露出生日/HP/default 主题。
• 任何单独重跑的资产板（assistant/shop sheet/decor/UI）都必须写入 session/profile 的 source job，并重新运行 QA。禁止静默混用不同商店的素材。重跑商品板时还必须重新生成/更新 tile contact sheet，并逐格验证图片内容与 manifest 名称一致；重跑 assistant 时必须重新验证四个头像 URL、manifest、静态注入和首屏头像实际解析。
• 在 make_image 前必须扫描 handshake/concept/contentPack/prompt payload，确保不含其它商店名称、助手名、世界名或旧主题关键词。
• 发布前必须运行 builder/qa-static-shop.mjs，对 index.html/session.json/static-session.js/manifests/runtime URLs 做污染扫描与绑定矩阵检查。
• 不要在 skill/Agent 层给静态导出追加、复制或粘贴项目级移动端 CSS 补丁（例如从其它店铺复制 Project-level mobile gameplay layout、mobile gameplay refinement v2/v3 之类的大段规则）。移动端布局只能由当前引擎源码/通用导出器自带的稳定 CSS 提供；如果 qa-mobile-layout.mjs 因缺少历史补丁而失败，记录为阻塞或需引擎侧修复，不得为了过 QA 在单店 static-export/styles.css 或 /public/<slug>/styles.css 里追加跨店样式补丁。
• 移动端玩法布局是发布检查项，不是补丁许可：静态导出应保留项目级 mobile gameplay layout contract。仅在手机/粗指针断点（默认 @media (max-width: 760px) and (pointer: coarse)）下，workbench/play panel 与 5x5 board 应优先出现在 secondary sidebar 内容之前；棋盘应尽量适配首个可用手机视口并保持 1:1；assistant/orders/sources/status 等应压缩、抽屉化或内部滚动，不得把棋盘推到首屏之外。若当前引擎未内置这些规则，必须回到引擎/导出器层做可复用修复并重新验证，或将发布标记为阻塞。

必须按当前 worker 真实顺序推进和校验，不要按旧顺序臆造：

1. concept
2. theme token validation
3. assistant portraits
4. content pack
5. shop sheet
6. tile split + tile manifest
7. decor stickers
8. decor split + decor manifest
9. ui button stickers
10. ui button split + ui button manifest
11. artifact check
12. ready session
13. static export
14. QA check
15. mobile layout QA with builder/qa-mobile-layout.mjs when publishing or after any mobile CSS change; if it fails because the current engine lacks mobile rules, stop and report/fix the engine layer, do not paste cross-shop CSS into the export
16. cross-shop contamination QA with builder/qa-static-shop.mjs
17. publish share link

要求：

• 静态导出必须使用通用导出器 builder/export-static-shop.mjs <session.json> <out-dir> 或等价脚本；不得使用带旧主题硬编码的导出脚本。
• QA 必须使用 builder/qa-static-shop.mjs <static-export-dir> --expect-shop "<shop>" --expect-world "<world>" --forbid "<old-shop-keywords>"，并保存报告。
• 移动端 QA 必须使用 builder/qa-mobile-layout.mjs <static-export-dir> 或等价脚本，确认 phone/coarse pointer 下 board 优先、5x5 棋盘 1:1、无横向溢出、assistant/task/status/trash 等 secondary UI 不阻塞首屏玩法，并保存报告。若失败，不得通过复制其它店铺的移动端 CSS 补丁修改单店导出；只能修复当前引擎/通用导出器，或将该轮发布阻塞。
• 详见事故复盘：supermarket/qa/cross-shop-contamination-lessons.md。
• 详见 source-of-truth/静态状态复盘：supermarket/qa/static-shop-source-of-truth-lessons.md。
• 不允许跳过 content pack 直接出最终商品图。
• content pack 必须在任何 shop_sheet_4x8 生图之前最终锁定。禁止在商品图板已经生成后再把商品名称、链条、tier、content pack 改成另一套主题文案；这会造成“图是旧物品、名字是新物品”的错配。
• 当前引擎的 4x8 商品板固定支持 32 个 slot，默认链条顺序和数量必须与运行时一致：botanical 6、alchemy 6、curio 6、waste 6、secret 8。不要临时新增 signature 等未被默认运行时/切图计划识别的链条来承载商品；如确需新链条，必须同时改运行时默认链、sheet slot plan、合成逻辑和 QA。
• 生成 shop_sheet_4x8 的 prompt、tiles/manifest.json、session.runtimeConfig.contentPack、session.runtimeConfig.tileManifest、导出后的 generated/assets/tiles/manifest.json、static-session.js 嵌入 runtime 必须全部来自同一份最终 content pack。
• 商品图板绑定 QA 必须做字段级比对：按 4x8 左到右、上到下检查每个 slot 的 itemId/chainId/chainLabel/tier/name/description/fileName/url，确认 contentPack.chains、tileManifest.tiles[]、tileManifest.bindings[*]、导出 manifest、嵌入 window.__SHOP_RUNTIME__.tileManifest 完全一致。任何 mismatch 都必须阻止发布并重跑商品图板；不得只改 JSON 冒充修复。
• 商品图视觉语义 QA 是强制闸门：item_1_1.png、item_1_2.png 等文件名只是网格坐标，不是商品名。切图后必须生成 contact sheet 或等价逐格审查表，把每张 tile 图放在对应的 row/col/fileName/itemId/chainId/tier/name/description 旁边，并使用模型视觉能力/人工视觉检查确认“实际图片内容”与 manifest 名称描述一致。只检查整张 raw sheet 大概像主题、只检查文件存在、只检查 URL 能打开，都不算通过。
• 如果视觉内容和 manifest 名称不一致：若图片内容本身正确但顺序漂移，可以按实际视觉顺序重排 manifest 并重新 QA；若图片内容错误、含混、跨格、含旧主题或含文字，必须从锁定 content pack 重新生成 shop sheet 并重新切图。禁止只改 manifest/session 文案来掩盖图片错配。
• Assistant portrait 也必须做同级绑定 QA：四个 portrait 文件、assistant_portraits/manifest.json、、、首屏 HTML/运行时 DOM 的头像 必须指向同一 build 的 ，不得指向旧 job、其它商店、、 或根路径 。

引擎兼容性注意

• 如果图片管线报错 spawn /usr/bin/sips ENOENT，说明当前 Linux 环境缺少 macOS 专用 sips，这是本地转换兼容问题，不是 Neta 出图失败。
• 可用 ImageMagick convert 或等价跨平台转换路径替代 sips，再重启 worker 重新跑构建。
• 处理这类兼容问题时，不要降低“必须真实出图”的标准，也不要退回程序占位图作为最终成品。

阶段 4：生成格式要求

4.0 Neta 出图与切图硬性流程

所有图片资产都必须使用对应 builder/skills/shop-builder/prompt_*.md 模板生成，不得只写泛泛主题词。每一种资产必须按以下顺序串行处理；禁止并发、禁止后台执行、禁止多个 Neta 图像任务重叠：

1. 使用该板块专属 prompt 模板调用 Neta make_image，等待命令结束。
2. 记录返回的 artifact UUID 和 URL。
3. 对同一张图调用 Neta remove_background，等待命令结束。
4. 记录 cutout UUID 和 URL。
5. 下载 raw 与 cutout，保留证据。
6. 将去背景结果放入透明画布，保持目标 sheet 比例，不得非等比压缩。
7. 按固定网格 crop/split。
8. 对每个切片单独 trim 透明边缘。
9. 写入 manifest，并用 manifest 绑定到 runtimeConfig。
10. QA 检查页面实际加载的是这些切片，而不是默认旧素材或 raw sheet。
11. 完成当前板块后，才允许开始下一板块的 make_image。

严禁：

• 同时启动多个 make_image 或 remove_background，包括通过 multi_tool_use.parallel、后台 &、多个 shell、多个本地 worker、未停止的旧 worker 造成的重叠请求。
• 先 crop 再去背景。
• 对整张 sheet 使用 resize WIDTHxHEIGHT! 这类非等比强制压缩，尤其是 ui_button_stickers_1x5，会把按钮图标压扁。
• 把 decor 场景贴纸当作合成材料 tile。
• 把完整场景、海报、拼贴、室内图切成合成材料。
• 跳过各板块 prompt 模板，手写一个笼统 prompt 代替。
• 因一次串行之外的失败就宣布“额度不足”；需要确认不是并发、重试堆叠、环境变量或 token 传递问题。

推荐 ImageMagick 顺序示例：

# UI 1x5 示例：优先使用 remove_background/cutout 的完整横条，而不是 opaque raw。
# 如果 cutout 仍保留完整 5:1 左右布局：透明背景等比缩放到 1600x320，再按 5 个 320x320 cell 切。
convert ui_cutout.png \
  -resize 1600x320 \
  -background none -gravity center -extent 1600x320 \
  PNG32:ui_button_stickers_1x5.png

for c in 0 1 2 3 4; do
  convert ui_button_stickers_1x5.png \
    -crop 320x320+$((c*320))+0 +repage \
    PNG32:ui_buttons/button_1_$((c+1)).png
done

UI 按钮特别经验（已发生过事故）：

• 不要直接 split opaque raw UI sheet；raw 的白/灰背景会让每个 button 的 alpha bounds 变成完整 320x320，浏览器会显示成方块背景，看起来像“按钮解析错了”。
• UI button runtime cell 建议保留 320x320 透明画布，不要像普通贴纸一样 -trim 成不等尺寸；稳定布局靠透明 canvas，QA 靠 alpha bounds。
• 每个 button 的 alpha bounds 必须“有意义但不是整格”：拒绝 1x1、近空图、以及 320x320/近 full-cell opaque background。
• 如果 cutout 被裁成中间内容带且破坏 5:1 横条布局，必须改用 remove_background_nocrop 或重跑 UI board；不能把 center-cropped cutout 当 1x5 split。
• 静态导出的 index.html 还必须把五个可见按钮 <img data-ui-sticker> 的 src 预绑定到本次 build 的相对路径：./generated/assets/ui_buttons/button_1_1.png 到 button_1_5.png。不要只依赖 JS 启动后根据 manifest 再去填空 src=""；UI 按钮是预存在 DOM 里的节点，首屏/缓存/重置时序问题会让 manifest-only 方案表现为按钮没解析对。
• 静态模式下 resetGeneratedStickerAssets() 必须优先使用 window.__SHOP_UI_BUTTON_MANIFEST__，不得把 UI 按钮重置回默认/旧图。loadRuntimeStickerAssets() 也应先用 embedded UI manifest，再尝试 fetch。
• 详见 workspace 记录：supermarket/qa/ui-button-runtime-binding-lessons.md。

4.1 assistant portraits

当前要求是先生成一个 assistant_sheet_2x2.png，再切成四张表情图。

必须满足：

• 横向 16:9 游戏资产 sheet
• 严格 2x2 布局
• 四角顺序：
  • top-left：smile
  • top-right：serious
  • bottom-left：angry
  • bottom-right：confused
• 半身像
• 中心区域尽量留白，四个象限互不接触
• 纯白背景
• 无文字、无标签、无边框
• 不添加用户/世界观没有提到的物种、身体特征、科技、能力、阵营等
• 现实店铺使用可信的现实店员服装和角色设计

产物要求：

• assistant_sheet_2x2.png
• assistant_sheet_2x2_raw.png 或等价 raw 记录
• assistant_sheet_2x2_cutout.png 或等价 remove_background 记录
• assistant_portraits/manifest.json
• assistant_portraits/smile.png
• assistant_portraits/serious.png
• assistant_portraits/angry.png
• assistant_portraits/confused.png

QA 必查：

• 四个表情必须来自严格 2x2 角落布局，不得把一张立绘硬切成四块。
• 去背景后每个 portrait 不应带大块白底或被裁断头发/肩膀/手。
• manifest 顺序必须是 smile, serious, angry, confused，并与页面实际显示 URL 一致。

4.2 shop sheet

当前要求是 shop_sheet_4x8.png。

必须满足：

• 4 rows x 8 columns
• 32 个商品/材料图标
• pure white background
• 无文字、无 label、无 logo、无 typography、无 letters、无 numbers
• 严禁把商品名、链条名、tier、slot note 或任何可读/近似可读文字画进图标里。即使文字内容正好等于 content pack 的 name，也必须视为失败；合成物素材只能用形状、颜色、材质和图案表达语义。
• 无边框、无分隔线、无格子线
• 每个物品居中且略小于格子
• 四周有足够白边
• 相邻物品之间有清晰白色 gutter
• 物体不能碰撞、重叠或跨格
• slot notes 只能作为语义指导，不能被画出来

产物要求：

• shop_sheet_4x8.png
• shop_sheet_4x8_raw.png 或等价 raw 记录
• shop_sheet_4x8_cutout.png 或等价 remove_background 记录
• tiles/manifest.json
• tiles/*.png

QA 必查：

• 合成台 tile 必须是商品/材料 icon，不得是店铺场景、海报、装饰贴纸、UI 图标或完整柜台。
• 32 个 itemId 必须与 runtimeConfig.contentPack.chains 的物品名和顺序绑定。
• runtimeConfig.tileManifest.bindings 必须覆盖所有可发现 item，页面实际 imageUrl 必须来自这些 bindings。
• 切图前必须完成去背景；切片应有透明背景，不得整格白底或跨格残影。
• 必须生成并保存 tiles/contact-sheet-with-names 或等价 QA 证据，逐格显示 tile 图片与 fileName/itemId/name/description。使用视觉能力确认每张 tile 的实际内容与对应 name/description 匹配；例如不能让篮子图对应“防风草种子包”，也不能让种子包图对应“背包升级券”。
• 视觉语义 QA 必须同时做“无文字/OCR”检查：逐格查看 raw sheet、cutout、contact sheet 和每个 tiles/item_*.png，确认没有商品名、汉字、英文、数字、伪文字、logo、标签、包装字样、UI 字或手写标记。仅靠 URL/manifest/文件存在、或只检查图像大致主题正确，不能通过 QA。
• 若任一 tile 上出现可读或疑似可读文字，尤其是把该 slot 的 name 直接写在物品、标签、牌子、瓶身或包装上，必须判定 shop sheet 不合格并重新生成；不得裁掉文字、PS 涂抹、缩小到看不清或在 QA 报告中豁免。
• 若模型没有严格遵守 slot plan，必须在发布前发现并处理：可重排 manifest（仅当视觉内容都正确且只是顺序错）、局部替换（若管线支持）、或重跑整张 shop sheet。不得把错配的图片和名字一起发布。

4.3 decor stickers

当前要求是 shop_decor_stickers_2x3.png。

必须满足：

• 2 rows x 3 columns
• 正好 6 个店铺装饰物
• 每格一个独立居中物体
• pure white background
• 无网格线、边框、分隔线
• 不要可读文字、招牌字、logo、label、letters、numbers
• 不要海报、拼贴、货架整体场景、店面整体图或完整室内大场景
• 必须是可拖拽摆放的 isolated props
• 风格为 warm handcrafted casual game sticker style

运行体验要求：

• 静态成品必须保留装饰贴纸拖拽摆放能力。
• 当前项目支持通过角标缩放装饰贴纸，静态成品不得因导出遗漏样式或事件而破坏缩放。
• 装饰位置会进入游戏存档，并兼容旧版 localStorage 装饰位置；导出/归档时不要丢弃 decorPositions、decorSlotPositions 或 decorEntries。
• 装饰布局作用域与 shopName、worldName、decorationManifestUrl 相关；更换主题/manifest 时不要复用旧主题的错位布局。

产物要求：

• shop_decor_stickers_2x3.png
• shop_decor_stickers_2x3_raw.png 或等价 raw 记录
• shop_decor_stickers_2x3_cutout.png 或等价 remove_background 记录
• shop_decorations/manifest.json
• shop_decorations/*.png

QA 必查：

• shop_decorations/manifest.json 中 stickers 必须是数组，且至少 6 项；当前 app 的 mapDecorationManifest() 读取数组，不读取对象形态。
• 每个 sticker URL 必须能从静态导出相对路径加载。
• 页面中的装饰托盘必须加载本轮主题装饰，不得回退到默认 Ollivanders/Harry Potter 装饰。

4.4 UI button stickers

当前要求是 ui_button_stickers_1x5.png。

必须满足：

• 1 row x 5 columns
• 从左到右顺序固定：
  1. lobby / hall
  2. collection book / codex
  3. favorites shelf / shelf
  4. restart / reset
  5. trash
• pure white background
• 无文字、无 label、无按钮框、无 UI 面板、无边框
• 每个图标独立居中，留足白边和 gutter
• 小尺寸下仍然可读

产物要求：

• ui_button_stickers_1x5.png
• ui_button_stickers_1x5_raw.png 或等价 raw 记录
• ui_button_stickers_1x5_cutout.png 或等价 remove_background 记录
• ui_buttons/manifest.json
• ui_buttons/*.png

QA 必查：

• ui_buttons/manifest.json 必须包含 bindings.hall、bindings.codex、bindings.shelf、bindings.reset、bindings.trash；当前 app 的 mapUiButtonManifest() 读取 bindings，不是 stickers。
• 左到右顺序必须严格是 hall/codex/shelf/reset/trash。
• 必须先去背景，再补透明 5:1 画布，再等比 resize，再 crop 1x5；不得用非等比 resize 1600x320! 压扁图标。
• 页面 DOM 中 [data-ui-sticker] 的实际 src 必须被替换为本轮 ui_buttons 切片，不得保留默认 HP wood 图标。

UI 按钮运行时绑定强制闸门

UI 按钮是高风险资产板块；以下任一项失败都不得发布：

• ui_button_stickers_1x5 在归一化过程中必须保持完整 5:1 横条布局。常见事故是 remove_background 把整条横图裁成中间内容带，再把这个被裁过的带子补成 5:1，结果切出 4 个透明 1x1 按钮。如果 cutout 尺寸明显不是 5:1，必须对同一 artifact 使用 remove_background_nocrop，或从 raw sheet 重建透明 5:1 画布后再切。不得把居中裁切后的 cutout 直接当原始 1x5 sheet 来切。
• UI 1x5 的正确处理顺序：raw/Neta artifact → remove_background 或 remove_background_nocrop → 保留完整左右顺序的透明 5:1 画布 → 等比 resize 到 1600x320（禁止 !）→ crop 五个 320x320 cell → 每格 alpha trim。
• 切图后必须检查每个按钮 PNG 的 alpha bounds：hall/codex/shelf/reset/trash 都不能是 1x1、近似空透明图或只有极细横条；只要出现 1x1/空图，即使文件存在也算 QA 失败。
• ui_buttons/manifest.json 必须包含 bindings.hall/codex/shelf/reset/trash，并且五个 URL 必须指向同一 build 的五个切片，顺序严格 hall/codex/shelf/reset/trash。
• 静态导出必须注入 window.__SHOP_UI_BUTTON_MANIFEST__，或确保 uiButtonManifestUrl 能稳定 fetch；静态模式下 app.js 应优先使用 embedded UI manifest，或至少在 fetch 失败时 fallback 到 embedded manifest，不能因为 ui_manifest.json 路径/缓存/异步失败而静默回到默认按钮。
• resetGeneratedStickerAssets() 在 QA 通过的静态成品中不得把 UI 按钮重置为 HP/default 资产；静态模式下应重置到本轮 embedded/generated UI manifest，并调用 applyUiButtonStickerUrls()。
• 必须验证真实运行 DOM，而不是只验证文件：[data-ui-sticker="hall|codex|shelf|reset|trash"] 的实际 src 必须能从静态导出根目录解析到本 build 的 ui_buttons/button_1_*.png，不得是 hp-wood、/generated/shop-stickers、/Downloads、/workspace 或空 src。
• 如果曾经发布过坏按钮版本，重新发布时必须加 cache-busting query 或等价措施，避免浏览器继续加载旧的坏 app.js、static-session.js 或 1x1 PNG。

阶段 5：content pack 要求

contentPack 必须写入 runtimeConfig.contentPack，用于驱动首轮体验、订单、补给和合成链。

至少应包含：

• sources：补给来源
• clients：顾客 / 委托方
• chains：合成链和物品名/描述
• recipes：特殊合成/混合配方
• blessings：经营加成或每日事件
• introSequence：入场序章

当前项目可能按 section 生成：

• meta
• core-chains
• special-chains

如果 LLM 生成 JSON 失败，应修复或回退为结构完整的 fallback，不得导出半缺失 content pack。

阶段 6：ready session 要求

最终 ready session 应保持当前 MVP 兼容，至少包含：

{
  "sessionId": "...",
  "status": "ready",
  "enteredShop": true,
  "createdAt": "...",
  "worldName": "...",
  "shopIdea": "...",
  "concept": {},
  "runtimeConfig": {},
  "sources": {},
  "profile": {}
}

runtimeConfig 至少包含：

• shopName
• brandEyebrow
• assistantName
• theme
• contentPack
• tileAssetBase
• tileManifest
• assistantPortraits.smile
• assistantPortraits.serious
• assistantPortraits.angry
• assistantPortraits.confused
• decorationManifestUrl
• uiButtonManifestUrl

静态 final 额外要求：

• contentPack 必须是本店完整包，不得缺字段后依赖默认旧主题补齐。至少显式包含 sources、clients、chains、recipes、blessings、introSequence；如果没有特殊配方/祝福，也必须写 recipes: []、blessings: []，并确保 static runtime 不自动合入默认 demo 值。
• theme 必须同时进入 session/static-session 和首屏 HTML/CSS 预水合变量，避免 JS 未启动时露出旧主题。
• static save/localStorage namespace 必须与 shopName/worldName/slug/buildId 绑定或拒绝旧存档。

savedState / 存档如被导出，应保留或兼容：

• decorPositions
• decorSlotPositions
• 旧版 shop_decor_positions localStorage entries（归档结构中通常叫 decorEntries）

sources 至少应能说明：

• LLM 来源
• builder / orchestrator 来源
• image 来源
• agent 来源

阶段 7：导出成品静态页

主体验要求保持不变：最终必须是打开即玩的静态页面，而不是 creator 建店页。

如果项目中存在官方导出脚本，优先使用，例如：

node builder/export-static-site.mjs --session <session.json> --output <dir>

如果当前项目没有导出脚本，Agent 必须用等价方式导出。导出逻辑必须满足：

1. 复制必要前端文件：
   • index.html
   • app.js
   • styles.css
   • sfx.js
   • creator.js、neta-config.js、neta-auth.js 一般不应加载到最终静态成品；除非静态页确实依赖其函数且已证明不会展示建店页/触发登录/泄露敏感信息
   • 不要复制或加载与当前店铺无关的实验脚本/主题补丁（例如其他 demo 的 *-barracks.js/css）；这些脚本可能注册全局 pointer/drag/click 监听并破坏合成台交互
2. 复制必要资源：
   • assets/sfx/
   • 当前 session 用到的 generated/build-artifacts/<jobId>/...
   • 其他 session 引用的本地图片资源
3. 写入：
   • session.json
   • 静态 runtime 注入脚本，例如 static-session.js 或内联脚本
4. 注入静态模式：
   • window.__SHOP_STATIC_MODE__ = true
   • window.__SHOP_STATIC_SESSION__ = <ready session>
   • window.__SHOP_RUNTIME__ = session.runtimeConfig
5. 绕过 creator/API：
   • 不依赖 GET /api/session
   • 不要求 OAuth 登录
   • 不展示建店输入页
   • 删除/隐藏 creator 页面时必须保留运行时节点：#appShell、#dragLayer、#toastStack、各 overlay 容器（intro/report/item/library）以及 board/trash/source/order/sidebar 等核心 DOM。不要用过宽正则把 creatorOverlay 后面的 dragLayer、toastStack 或启动脚本一起删掉。
   • 页面加载后直接调用或等价执行：resetShopState(runtimeConfig, { introSeen: false })，并显示 #appShell
   • 如果导出包含玩家已布置好的装饰布局，应在 reset/import 后恢复 decorPositions、decorSlotPositions 或等价 decorEntries
6. 路径处理：
   • 所有 /generated/...、/assets/...、/Downloads/... 等必须转换为静态站点内可访问路径。
   • 对 Cohub public share 这种 /s/<space-id>/<slug>/index.html 子路径发布，不要保留根路径 /generated/... 或 /assets/...；优先转换为 ./generated/... 和 ./assets/...。
   • 不允许引用本地绝对文件路径，例如 /workspace/...。
   • 必须递归处理 session.json / / runtimeConfig / manifest 中的所有资源 URL：、、、、、、、decor 、UI 。

静态 URL 解析防错要求

本项目曾出现“图文件正确存在，但页面没加载正确图”的问题。原因是静态页发布在 /s/<space-id>/<slug>/ 子路径下，runtime/manifest 仍保留 /generated/... 根路径，浏览器实际请求到了 https://public.cohub.run/generated/... 而不是当前 slug 下的资源。以后必须按以下要求处理：

• 静态导出必须包含或注入等价的 resolveStaticAssetUrl(url)：在 window.__SHOP_STATIC_MODE__ 下把 /generated/... 转为 ./generated/...，把 /assets/... 转为 ./assets/...。
• 必须包含或注入等价的 sanitizeRuntimeAssetUrls(config)，递归清洗 assistantPortraits、tileAssetBase、tileManifest、decorationManifestUrl、uiButtonManifestUrl。
• rebuildCatalogFromContentPack() 或任何建立商品索引的逻辑，不能直接使用 tileBindingIndex[id].url；必须先走 resolveStaticAssetUrl(...)。
• renderAssistant() 或任何助手头像渲染逻辑，不能直接使用 runtimeConfig.assistantPortraits[...]；必须先走 resolveStaticAssetUrl(...)。
• item detail、board item、decor sticker、UI button、manifest fetch 也要在使用 URL 前清洗。
• fallback 默认素材也必须替换到当前 build，或保证不会在成品中生效；不得让 /Downloads/hermione...、/Downloads/magic_assets...、hp-wood、ollivanders-decor 作为活跃 fallback。

参考复盘与 QA 清单：supermarket/qa/static-url-binding-lessons.md。

图片与名称绑定 QA

除文件存在外，必须检查图片内容、manifest 绑定、物品名称、合成链语义是否一致：

• contentPack.chains[].items[] 中的名称应和对应 tile 视觉一致。
• runtimeConfig.tileManifest.bindings[itemId].url 应指向正确的切图。
• 不允许出现明显错配，例如“石头图片叫橡木原木”“木头合成成无关石头”。
• 如果 Neta sheet 生成顺序和计划不一致，优先重新生成；如果图片可用但顺序错位，可以重排 tileManifest.bindings 并同步修正 content pack 链名/物品名。
• 合成线应有语义连续性，同线升级应像同一类货的递进；跨线只通过指定 recipe 产出隐藏物，否则应进入废料/失败结果。

阶段 8：QA check

发布前必须检查：

文件完整性

静态输出目录至少应包含：

• index.html
• app.js
• styles.css
• sfx.js
• session.json
• assets/sfx/
• generated/... 或等价生成资源目录

如果静态页依赖以下文件，也必须包含：

• creator.js
• neta-config.js
• neta-auth.js

session/runtime 完整性

检查：

• session.status === "ready"
• session.enteredShop === true 或静态页会直接进店
• runtimeConfig.theme 25 个必需基础 token 全部存在，并且页面运行时派生出的可读色 token 生效
• runtimeConfig.contentPack 结构完整
• runtimeConfig.tileAssetBase 可访问，且在 public share 子路径下解析后能命中静态目录文件，不是根路径 /generated/...
• runtimeConfig.tileManifest.bindings 存在，且每个 binding URL 经过静态路径解析后可访问
• 4 张助手表情图可访问
• decorationManifestUrl 可访问且至少 6 个装饰；decor manifest 内 stickers[].url 也必须是静态子路径可加载 URL
• uiButtonManifestUrl 可访问且包含 hall/codex/shelf/reset/trash；UI manifest 内 bindings.*.url 也必须是静态子路径可加载 URL

页面体验

检查：

• 打开 index.html 直接显示游戏，不是 creator 建店页
• 商品图正常显示，不是旧默认素材；商品图和名称/详情/合成链语义一致
• 助手立绘正常显示，不是旧默认素材
• 装饰贴纸可见/可拖动/可缩放，刷新后布局能按当前店铺作用域恢复
• 大厅、图鉴、收藏、重开、垃圾桶按钮贴纸正常
• 入场序章、订单、补给、图鉴、收藏、经营回顾基本可用
• 音效文件不 404；浏览器限制下未自动播放不算失败，但用户交互后应可触发音效
• 页面资源没有泄露 token、内部日志、绝对路径或 secrets
• 检查 #dragLayer 和 #toastStack 存在；拖拽合成依赖 #dragLayer 创建 ghost，缺失会导致鼠标拖拽素材时 JS 抛错并中断。
• 检查没有加载与当前店铺无关的全局实验脚本/样式（如 lotr-barracks.js/css、其他 demo patch），这些脚本会覆盖 board、注册 pointer/click 监听或重绘工作台，可能阻塞拖拽。
• grep 静态导出目录，确认没有活跃旧素材或错误路径：/Downloads、hp-wood、ollivanders、Ollivanders、Hermione、赫敏、/workspace、.neta-skill-config、NETA_TOKEN、accessToken
• 用脚本从静态输出目录模拟 URL 解析：assistantPortraits.serious、tileAssetBase/item_1_1.png、tileManifest.bindings[*].url、decor stickers[].url、UI bindings.*.url 都必须能由 <static-export>/... 直接找到文件；仅检查文件存在但不检查 runtime URL 视为 QA 不通过

阶段 9：发布分享

必须读取并遵守 /configs/platform/.agents/skills/public-share/SKILL.md 的规则。

做法：

1. 把通过 QA 的静态目录复制到 /public/<subfolder>/
2. 返回直达 index.html 的 URL

Cohub public-share URL 强制规则

本 workspace 的最终分享链接必须使用 Cohub public-share 前缀，不得凭空改成其他域名，也不得返回本地路径或裸 slug。

正确格式：

${PUBLIC_URL_PREFIX}/<subfolder>/index.html

通常等价于：

https://public.cohub.run/s/<COHUB_SPACE_ID>/<subfolder>/index.html

严禁把以下形式作为最终给用户的分享链接：

https://cohub.ai/public/<subfolder>/index.html
/public/<subfolder>/index.html
/<subfolder>/index.html

发布前必须验证：

test -f /public/<subfolder>/index.html
printf '%s/%s/index.html\n' "$PUBLIC_URL_PREFIX" "<subfolder>"

如果 /configs/platform/.agents/skills/public-share/SKILL.md 因 stale NFS handle 暂时不可读，仍必须按照上面的 PUBLIC_URL_PREFIX 规则输出 URL；不要因此猜测或使用 cohub.ai/public/...。

同时在 supermarket/published/<subfolder>.json 写入发布记录，至少包含：

{
  "slug": "<subfolder>",
  "path": "/public/<subfolder>",
  "url": "${PUBLIC_URL_PREFIX}/<subfolder>/index.html",
  "shopName": "...",
  "jobId": "...",
  "status": "published"
}

注意：

• /public 只作为发布目标，不要在那里开发。
• 不要发布 secrets、token、OAuth 缓存、内部日志或完整 .git 内容。

对用户汇报规则

• 每一轮关键资产完成后，都要主动汇报一次进度。
• 主句使用沉浸式口吻，例如：
  • “开店信已经接下，正在把店铺主题和开张清单定稳。”
  • “店员已经到柜台前了，四种表情都备好了。”
  • “第一批货物已经上托盘，正在裁进工作台格子。”
  • “装饰和入口小牌都裁好了，正在最后清点开张用品。”
• 如需补技术信息，把技术信息放在第二句，不要盖过开店语境。
• 出错时也先说明“店里卡在哪一步”，再补真实错误原因。
• 不要频繁用“要不要继续”“我现在继续吗”打断用户，除非遇到真正阻塞。
• 当 concept 已定、信息已足够时，应默认自动推进到下一个强制阶段。
• 用户侧看到的应尽量是：定概念 → 等待若干轮进度 → 直接收到可玩的成品链接。

执行建议

A. 有现成 ready session 时

如果用户给的是现成构建结果，或项目里已有可用 ready session：

• 先验证 session/runtime/artifacts 是否完整
• 如缺少 enteredShop，静态导出时强制设置或绕过 creator
• 直接导出静态站点
• QA
• 发布分享

B. 需要全新生成时

按完整链路执行：

• 生成 concept
• 校验 theme token
• 生成 assistant portraits
• 生成 content pack
• 生成商品、装饰、按钮贴纸与 manifest
• 等待 ready session
• 导出静态站点
• QA
• 发布分享

C. 项目缺少静态导出脚本时

不要放弃“打开即玩 + 公网 URL”的主目标。应：

• 在临时工作目录或项目 builder 中创建等价导出脚本
• 不修改 archived 目录
• 不把 /public 当开发目录
• 导出前后都验证文件与页面行为

成功标准

完成时应满足：

• 最终页面打开就显示游戏，而不是 creator 建店页
• 商品图、助手图、装饰贴纸、按钮贴纸都能正常加载
• content pack 驱动的订单、补给、合成链、入场序章可用
• 音效资源存在且交互后可触发
• 页面内资源全部使用相对路径或站内路径
• 无 secrets/token/内部日志泄露
• 返回一个可公开访问的 index.html 链接

阻塞与返工规则

必须返工或报告阻塞的情况：

• concept 缺少核心字段
• theme token 缺失或明显不可读，且自动对比度修正后仍有主要 UI 文本不可读
• 装饰布局导出后不可拖拽、不可缩放，或刷新后明显丢失当前店铺的布局状态
• contentPack 缺少 sources/clients/chains/recipes/blessings/introSequence
• session 不是 ready
• session 缺少 runtimeConfig 或关键 manifest URL
• 图片和 manifest/content pack 明显错配，例如石头图绑定成木头名，或合成链出现无关跳变
• 静态页仍进入 creator 建店页
• 分享目录缺失 index.html / app.js / styles.css / sfx.js / session.json / generated... / assets/sfx... 中的必要项
• 任何素材 manifest 指向不存在文件

推荐最终输出格式

对用户汇报时，优先给：

1. 成品名称
2. 本地输出目录
3. 公网 URL
4. 如失败，给出阻塞阶段与缺失项