World of Oldcraft 构建工具箱

把整个 World of Oldcraft 构建套件安装进一个（空的）Unity 工程目录：复制文档/脚本/钩子、重命名隐藏配置文件、下载 Mixamo 动画与风格参考图、填充 MCP 路径占位符、写好 .gitignore。

• 参数：-Target 必填；-FalBudgetUsd（默认 100）、-HiggsfieldCredits（默认 "10,000"）、-FalKey、-UnityMcpServerDir（默认 C:/GIT/unity-mcp-server）、-BlenderMcpCommand（默认 blender-mcp）、-BlenderExe（默认 C:/Program Files/Blender Foundation/Blender 5.1/blender.exe）；$ErrorActionPreference="Stop"。
• 复制内容：CLAUDE.md、requirements.txt 直接 Copy-Item -Force；Copy-Tree 递归复制 Docs、knowledge、processes、projects、scripts、host-tools 六个目录；dot-claude/ 改名成 .claude/、mcp.json 改名成 .mcp.json、env.example（或套件内已有 .env）改名成 .env。
• 回退逻辑：若套件里没有 Docs\refs 而父目录（card 文件夹）有 refs/，从父目录复制参考图清单；若没有 Docs\concepts，则把 card\concepts\images\*.webp 拷入 candidates，并按 selection.json 的 approved+recommended 组把选中的图拷入 Docs\concepts\approved。
• Mixamo：若套件带 mixamo-fbx/ 则整体复制到 Assets\_Source\Mixamo；否则若目标目录没有 *.fbx，读取 scripts\animation\mixamo_core_set.json，用 python 调 download_mixamo.py，把 90 个 clip 的 motion_id 逐个作为 --motion-id 参数传入；失败只 Write-Warning 不中断。
• 风格参考：若 Docs\refs\manifest.json 存在且目录内没有任何 *.webp，运行 python scripts\refs\fetch_refs.py --refs <refs目录>；失败仅警告并提示手工获取。
• .env 保护：只在目标 .env 不存在时复制生成，绝不覆盖已有 .env；若传了 -FalKey 用正则 (?m)^FAL_KEY=.*$ 覆写该行，UTF8 无 BOM 写回。
• 占位符替换：对 CLAUDE.md、.mcp.json 及 Docs 下所有 *.md 递归替换 {{UNITY_MCP_SERVER_DIR}}、{{BLENDER_MCP_COMMAND}}、{{BLENDER_EXE}}（反斜杠转正斜杠）；-FalBudgetUsd≠100 时把 "**100 USD**" 和 "hard budget 100 USD" 里的数字改掉；-HiggsfieldCredits≠"10,000" 时替换 "about 10,000"。
• 追加 .gitignore（已存在则跳过不重复）：.env、.claude/ALLOW_STOP、.claude/session_window.json、Docs/owner-desktop-timelapse/；最后打印后续步骤（填 FAL_KEY、pip install、开 Unity、开 Blender、跑 claude）。

在宿主机上用 ffmpeg 的 gdigrab 每隔 N 秒截一张全屏，存为编号 JPG，形成一天一目录的桌面延时摄影；文件头明确注明这是给 owner 记录 agent 工作过程用的，不是给 agent 用的。

• 参数：-Every（秒，默认 60）、-Out（默认 %USERPROFILE%\Downloads\Oldcraft-desktop-timelapse）、-Region "x,y,width,height"（单显示器裁切，写入 -offset_x/-offset_y/-video_size）、-MaxWidth（默认 2560，scale='min(iw)' 缩放）、-Hidden（后台隐藏运行）。
• ffmpeg 参数：-f gdigrab -framerate 1 -i desktop，滤镜 fps=1/$Every,scale='min($MaxWidth,iw)':-2，-q:v 3，输出 shot_%06d.jpg；每个会话一个 yyyyMMdd-HHmmss 子目录。
• 防重入：Out 目录下 running.pid 存在且进程还活着时直接退出并提示先跑 stop_desktop_timelapse.ps1。
• PID 管理：-Hidden 用 Start-Process -WindowStyle Hidden 后台起 ffmpeg 并把 PID 写进 running.pid；前台模式用 Wait-Process 等待，finally 块里 Stop-Process 按 PID 杀进程并删 pid 文件。
• 前置检查：Get-Command ffmpeg 找不到就报错退出并提示 winget install Gyan.FFmpeg。

把 desktop_timelapse.ps1 拍的 JPG 序列编码成 mp4 延时视频，默认自动挑 Downloads 里最新的会话目录。

• 参数：-Frames（帧目录，留空则按目录名排序取 $Out 下最新一个会话目录）、-Fps（默认 30）、-Out（默认同拍摄脚本）。
• 编码命令：ffmpeg -framerate $Fps -i shot_%06d.jpg，滤镜 pad=ceil(iw/2)*2:ceil(ih/2)*2（补齐偶数宽高），-c:v libx264 -pix_fmt yuv420p -crf 20，输出 <会话目录名>_timelapse.mp4，写在会话目录的父目录。
• 头部注释给了换算基准：每 1 分钟一帧、24 小时 = 1440 帧 = 30fps 下 48 秒；每 5 分钟一帧约 10 秒。
• 同样先检查 ffmpeg 在 PATH、无会话目录时报错退出。

按 running.pid 精确停掉后台运行的 ffmpeg 截帧进程，符合 CLAUDE.md “只按 PID 杀进程”的纪律。

• 无 pid 文件时打印“没有运行中的延时摄影”并 exit 0，幂等。
• 读 running.pid 后先 Get-Process 校验进程存在且 ProcessName -eq "ffmpeg" 才 Stop-Process -Force；进程名不符（PID 被复用）时不动进程，只报告。
• 无论如何删除 pid 文件，最后统计按名称排序最新会话目录里的 *.jpg 数量并打印帧目录路径。

把两个 Python 钩子挂进 Claude Code 生命周期，并把 Stop 钩子的连续拦截上限抬到 1000，这是“agent 不许自己停下来”机制的开关盒。

• env: CLAUDE_CODE_STOP_HOOK_BLOCK_CAP="1000"——默认该上限较小（约 8 次），抬到 1000 后 keep_working.py 可以连续拦截 1000 次停止请求而不被 harness 强制放行。
• Stop 钩子：command 类型，python "$CLAUDE_PROJECT_DIR/.claude/hooks/keep_working.py"，每次 agent 试图结束回合都执行。
• SessionStart 钩子两条：matcher "compact" 和 matcher "resume" 都执行 after_compact.py，即上下文压缩与会话恢复后各触发一次。
• 安装后此文件位于目标工程 .claude/settings.json，属项目级配置，只对打开该目录的 Claude Code 会话生效。

作为 Claude Code 的 Stop hook，在 owner 未明确结束会话前拒绝 agent 停止：exit 2 拦截停止并把 stderr 文本作为理由回灌给 agent。

• 先 json.load(sys.stdin) 吞掉钩子输入 JSON，异常忽略——不因输入格式炸掉。
• 放行条件一：$CLAUDE_PROJECT_DIR（缺省用 cwd）下存在 .claude/ALLOW_STOP 文件即 exit 0；owner 手工创建该文件就是“结束会话”的总开关。
• 放行条件二：.claude/session_window.json 存在且其 "until" 字段（ISO 时间，utf-8-sig 读入）已是过去时间（无时区则 astimezone() 本地化后与 datetime.now(timezone.utc) 比较）即 exit 0——支持“限时运行到某点自动允许停”。
• 两个放行条件都不满足：向 stderr 写入固定指令（不许停；按 CLAUDE.md 第 1 节重读状态文件；取 Docs/TODO.md 下一项；TODO 空则跑 TASK.md §2 验收测试并排队补弱项；继续截图 TASK.md §18），然后 exit 2。Claude Code 的 Stop hook 语义：exit 2 = 阻止停止并把 stderr 反馈给模型。
• 容错是 fail-closed 方向：session_window.json 解析失败被 except 静默吞掉，结果是继续拦截停止而不是放行。
• ALLOW_STOP 与 session_window.json 都被安装脚本写进了 .gitignore。

在上下文被 compact 或会话 resume 后，向 agent 注入一段再锚定指令，防止长会话压缩后忘记工作规程。

• 仅一个 print()：SessionStart 钩子的 stdout 会被注入会话上下文。
• 内容带 UTC 时间戳，并要求在做任何动作之前重读 CLAUDE.md、Docs/PLAN.md、Docs/TODO.md、Docs/DEVLOG.md 最后三条和 Docs/STATS.json。
• 随后要求继续当前 milestone，并按 Docs/TASK.md 第 18 节为手头功能补一张进度截图。
• 无副作用、不读文件、不判断条件，纯提示器。

声明 agent 工作时要连的三个 MCP 服务器：Unity 编辑器桥、Blender 桥、Higgsfield 云桥；带三个由安装脚本填充的路径占位符。

• unity：stdio，command "node"，args ["{{UNITY_MCP_SERVER_DIR}}/src/index.js"]，env UNITY_BRIDGE_PORT="7890"——指向本地 unity-mcp-server 仓库的 Node 入口。
• blender：stdio，command 为 {{BLENDER_MCP_COMMAND}}（默认 blender-mcp），env BLENDER_PATH={{BLENDER_EXE}} 指向 blender.exe。
• higgsfield：type "http"，url https://bridge.higgsfield.ai/mcp——云端 HTTP 型 MCP，无本地凭据字段（Higgsfield 靠 CLI `higgsfield auth login` 的账号登录，见 env.example）。
• 三个 {{...}} 占位符在 install_kit.ps1 第 95-106 行被替换为 -UnityMcpServerDir/-BlenderMcpCommand/-BlenderExe 的实际值（统一换成正斜杠）。

唯一的密钥载体模板：只含一个 FAL_KEY 空值；被安装脚本复制为 <Target>\.env 且永不回写覆盖。

• FAL_KEY= 留空，需手工粘贴或用 -FalKey 参数注入；注释指明 fal 预算硬上限见 Docs/TASK.md §15。
• 明确注释：Higgsfield 不走环境变量，用 `higgsfield auth login` 在本机登录一次 CLI 即可。
• 第一行注释“Never commit .env”，且 .env 已被追加进 .gitignore。

安装 agent 侧 Python 工具链的三个依赖，供 generate.py / download_mixamo.py / fetch_refs.py / 钩子使用。

• fal-client>=0.5：fal.ai 官方客户端，generate.py 用 fal_client.run() 和 fal_client.upload_file()。
• requests>=2.31：download_mixamo.py 与 fetch_refs.py 的 HTTP 库。
• pillow>=10.0：fetch_refs.py 的图片转 WebP 与 make_timelapse.py 的截图渲染。
• 钩子用的是 Python 标准库（json/os/sys/datetime/pathlib），不在清单内但要求 PATH 上有 python。

机器可读的套件装箱单：列出打包的 skills、文档、脚本，以及由安装器负责下载的两类外部资产。

• skills 四项：character-sheet-pipeline、fal-ai-generation、blender-game-animation、3d-production-routing（安装后进 .claude/skills/）。
• docs 共 24 条：knowledge/ 9 篇（含 overlord-unity-test-input.md 等经验教训）、processes/3d-ai/ 8 篇（higgsfield-cli、image-generation、prompting、tools 等）加 workspace-video-storage.md、projects/overlord/animation-workflow/ 6 篇旧项目交接文档。
• scripts 列出 3 个核心脚本：center_glb_bottom.py、download_mixamo.py、generate.py（清单未列 fetch_refs.py 与 make_timelapse.py，但套件里有）。
• downloaded_by_installer 字段声明两类安装期下载物：Assets/_Source/Mixamo/*.fbx（按 mixamo_core_set.json）和 Docs/refs 图片（按 manifest.json）；links_not_copied 为空。

按 Docs/refs/manifest.json 的清单从原始出处下载第三方 WoW 风格参考截图/粉丝图，统一转存为 WebP——套件有意只发货清单不发图（版权考虑）。

• 清单字段：每项含 file（保存相对路径）、image_url、可选 source_page；manifest 在 --refs 目录（默认脚本上两级 Docs/refs）。
• 反爬处理：UA 伪装 Chrome 128；对有 source_page 的项准备两种 header 变体（不带 Referer / 带来源页 Referer 都试一遍），因为有的站拒绝外来 Referer、有的站强制要求本站 Referer。
• 重试策略：tries=3，每轮内两种 header 各试，指数式等待 time.sleep(2*(attempt+1))，timeout=(20,90) 元组。
• 幂等与安全：目标文件已存在且非 0 字节就跳过；PIL 打开后按模式转 RGBA 或 RGB，im.save(target, "WEBP", quality=88)。
• 退出码语义：有任何失败 exit 1 并逐条打印“去 source_page 手工保存”的兜底指引；全部成功 exit 0。

从 prompts JSON 批量调 fal.ai 生图（含 edit 模型），并发下载结果，产出人工评审用 HTML 报告——agent 走 fal.ai 备用生成路线时的统一入口。

• 命令行：generate.py <prompts.json> --model（默认 nano-banana-2，共 16 个端点：nano-banana-2/-edit、nano-banana-pro/-edit、gpt-image-2/-edit、gpt-image-2.5/-edit、grok-imagine-2/-edit、seedream-v4/-edit、seedream-v5-pro/-edit、flux-pro(v1.1)、flux-dev）--aspect-ratio（默认 1:1）--run-id --dry-run --workers（默认 5）--skip-existing。
• 密钥：load_env() 从仓库根 .env（脚本上三级目录）用 setdefault 注入环境，优先 FALAI_KEY 再 FAL_KEY，缺了直接 sys.exit(1)。
• 按模型适配参数：nano-banana-pro 加 safety_tolerance="6"、enable_web_search=True、resolution="2K"；edit 端点传 image_urls（本地路径先 fal_client.upload_file()，http URL 直通）；nano-banana/grok 用 aspect_ratio；gpt-image-2/seedream 用 GPT_IMAGE_SIZE 枚举映射（1:1→square_hd 等）且 seedream 弹掉 output_format；其余用 size_map {1:1:(1024,1024),16:9:(1344,768),9:16:(768,1344)} 的 image_size 字典。
• 并发与产物：ThreadPoolExecutor 跑任务，输出到 scripts/image-gen/data/<run_id>/ 下 images/（<id>_<变体>.png）、results.json（含 remote_url、seed、error）、report.html（深色 A/B/C 三栏对比评审页，页脚提示按对象挑 A/B/C 或给迭代反馈）。
• 成本控制只在文档/策略层（TASK.md §15 的 100 USD 上限），脚本本身无预算熔断；--dry-run 只打印提示词不花钱，--skip-existing 避免重复计费，但默认 --workers 5 会并发烧钱。
• 每个 prompt 对象支持 variants 字典（A/B/C），变体值可以是纯字符串或 {prompt, images|image} 字典（后者用于 edit 流程）。

按精确 motion_id(UUID) 从 Hugging Face 数据集 Linzhan/Mixamo-Animations-Characters 拉取 Mixamo 动画 FBX 文件，带完整的完整性校验与下载凭证——只做获取，不做重定向/导出。

• 流程：请求 /api/datasets/<REPO>/revision/<revision>（默认 main）拿到固定 sha，再按 sha 拉 metadata.csv，要求每个 motion_id 在 CSV 里恰好命中 1 行（否则 raise）。
• 路径校验：archive 内路径必须是 animation/<name>.fbx 两段式，否则 raise 'Unexpected archive path'。
• 内容校验：载荷必须以二进制 FBX 头 b'Kaydara FBX Binary \x00\x1a\x00' 开头且 ≥1024 字节，否则 raise；下载后计算 sha256。
• 安全写入：目标文件已存在且哈希不同 → raise FileExistsError 拒绝覆盖；新文件先写 <name>.fbx.part 再 .replace() 原子改名——不留半截文件。
• 凭证：每成功一个 clip 就把记录（url、bytes、sha256、archive、archive_revision、metadata_sha256、verification 提示语）增量写进 <output>/downloads.json，后续网络失败不丢先前成果；最后另存 metadata.csv 副本；--motion-id 可重复传入，--revision 默认 main。

用无头 Blender 把一批 .glb/.gltf 的枢轴移到包围盒底部中心，让生成模型进引擎后能直接“落地”——对应 CLAUDE.md 批量后台 Blender 处理里的 re-pivot 工序。

• 调用方式：blender --background --python center_glb_bottom.py -- <in_dir> <out_dir>，在 `--` 后取参。
• 每个文件先 bpy.ops.wm.read_factory_settings(use_empty=True) 清空场景再 import_scene.gltf，互不污染。
• 算法：对所有 MESH 对象的 bound_box 角点乘 matrix_world 求世界空间联合包围盒，取 bottom_center=(中点X, 中点Y, minZ)，再把所有无父级根对象的 matrix_world 平移 -bottom_center（子对象随父移动），整体不破坏层级。
• 导出 export_scene.gltf(export_format="GLB", use_selection=False) 到 out_dir，.gltf 输入统一改名 .glb 输出；原始文件不动；逐文件打印 [ok]/[nomesh]/[fail] 与最终计数。
• 注意 docstring 写的是 Unreal 语义（pivot 在底部中心），但操作本身与引擎无关，Unity 里同样适用。

把 TASK.md §18 规定的进度截图合成为带字幕的延时视频和分镜总览图，供 owner 与 Reviewer 快速回看开发过程。

• 输入约定：Docs/progress/<feature>/<yyyymmdd-HHMMSS>__<short-caption>.png（caption 从文件名 __ 后解析，时间戳里的 - 换空格）。
• 命令行：--root（默认 Docs/progress）、--feature（可重复）、--all、--master（全部功能按文件名时间排序合成一个 master_timelapse.mp4，字幕带 [feature] 前缀）、--fps（默认 3.0）、--hold-last（默认 2.0 秒）、--width（默认 1920）、--no-captions。
• 渲染：Pillow LANCZOS 缩放到目标宽（高取偶），底部画半透明黑条烧入字幕（字体按 arial→segoeui→DejaVuSans 回退），存临时目录 f%06d.jpg。
• 编码：写 ffmpeg concat 清单 list.txt（每帧 duration=1/fps，末帧重复一次并 hold max(hold_last,1/fps) 秒），ffmpeg -f concat -vf pad 偶数化 -c:v libx264 -pix_fmt yuv420p -r 30。
• 分镜图：storyboard() 输出 4 列 × 480px 缩略图网格 JPG，每格下沿写截断到 70 字符的 caption；产物统一进 Docs/progress/_out/。
• 启动即检查 shutil.which("ffmpeg")，没有则直接退出；依赖 Pillow。

为经典 MMO 切片精选的 90 条 Mixamo 动画的采购清单：钉死数据源与版本，按 10 个用途组分类，安装器据此驱动 download_mixamo.py 批量拉取。

• 头部元数据：source 为 Hugging Face 数据集 Linzhan/Mixamo-Animations-Characters，revision 固定为 7f134bc734557b1d9516cb476d25ea1f577e45c1，license 标注 "adobe-mixamo-terms (record as Mixamo terms, not CC0)"，note 说明按六个种族角色（Human 双手战士、Dwarf 剑盾、Night Elf 弓手、Orc 剑盾、Undead 法师、牛头人治疗者）策展并要求用前逐条预览。
• clip 总数 90，motion_id 全部唯一；每条记录字段为 group / motion_id / name / use 四项。
• 10 个 group 及数量：locomotion 18、social 16、great-sword 14、bow 14、melee 8、shield 7、magic 5、reaction 4、creature 3、healer 1。
• 示例条目：{"group":"locomotion","motion_id":"c9cc6f74-b96c-11e4-a802-0aaa78deedf9","name":"Sword And Shield Idle","use":"default combat-ready idle"}；{"group":"magic","motion_id":"a3d120fd-c26a-46c7-a4a0-59c1c5d8157c","name":"Standing 1H Magic Attack 01","use":"Fireball cast"}；{"group":"social","name":"Waving Gesture","use":"/wave"}；{"group":"creature","name":"Mutant Breathing Idle","use":"hunched humanoid mob idle"}；{"group":"healer","name":"Magic Heal (one hand)","use":"Healing Wave / heal cast"}。
• 安装器用法：install_kit.ps1 遍历 $coreSet.clips 把每条 motion_id 拼成 --motion-id 参数一次性传给 download_mixamo.py，输出到 Assets\_Source\Mixamo。

【安装流程（install_kit.ps1，Windows PowerShell，$ErrorActionPreference=\"Stop\"）】① 校验/创建 -Target 目录并转绝对路径；$Kit 取脚本所在目录。② 复制：CLAUDE.md、requirements.txt 直接强覆盖复制；Copy-Tree 递归复制 Docs、knowledge、processes、projects、scripts、host-tools 六个目录；dot-claude/ 重命名复制为 .claude/，mcp.json 重命名为 .mcp.json。③ 文本模式回退：若套件缺 Docs\\refs 或 Docs\\concepts，从其父目录（card 文件夹）补 refs 清单和 concepts/images/*.webp→candidates，并按 selection.json 的 approved+recommended 把选中图复制进 Docs\\concepts\\approved。④ Mixamo：套件内若有 mixamo-fbx/ 就整体复制到 Assets\\_Source\\Mixamo；否则仅当目标没有 *.fbx 时，解析 scripts\\animation\\mixamo_core_set.json（90 个 clip、10 个 group、钉死 HF revision），把全部 motion_id 作为 --motion-id 传给 python scripts\\animation\\download_mixamo.py 下载；失败仅 Write-Warning 提示先 pip install 再重跑。⑤ 风格参考：Docs\\refs\\manifest.json 存在且目录无 *.webp 时运行 scripts\\refs\\fetch_refs.py 下载并转 WebP(q88)；失败仅警告。⑥ .env：仅当目标不存在时从套件 .env 或 env.example 复制生成——绝不覆盖已有 .env；传 -FalKey 时用正则覆写 FAL_KEY= 行（UTF8 无 BOM）。⑦ 占位符与预算改写：对 CLAUDE.md、.mcp.json、Docs 全部 *.md 替换 {{UNITY_MCP_SERVER_DIR}}、{{BLENDER_MCP_COMMAND}}、{{BLENDER_EXE}}；-FalBudgetUsd≠100 或 -HiggsfieldCredits≠\"10,000\" 时在文档正文里同步改写预算数字。⑧ 追加 .gitignore：.env、.claude/ALLOW_STOP、.claude/session_window.json、Docs/owner-desktop-timelapse/（逐行查重，不重复追加），最后打印下一步操作指引。安装器唯一拒绝覆盖的既有文件是 .env；其余 Copy-Item -Force 会覆盖目标同名文件。 【\harness（让 agent 一直跑下去的框架）】.claude/settings.json 把 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP 抬到 1000，并注册两类钩子：Stop 钩子运行 keep_working.py——它先吞掉 stdin JSON，然后检查 $CLAUDE_PROJECT_DIR/.claude/ALLOW_STOP，存在即 exit 0 放行停止；否则解析 .claude/session_window.json 的 \"until\" ISO 时间戳，已过期即 exit 0；两者皆无则向 stderr 写入“owner 未结束会话，不许停：按 CLAUDE.md §1 重读状态、取 Docs/TODO.md 下一项、TODO 空则跑 TASK.md §2 验收并补弱项、继续截图 TASK.md §18”并 exit 2——Claude Code 对 Stop 钩子 exit 2 的语义是阻止停止并把 stderr 作为理由回灌给模型，配合 BLOCK_CAP=1000 可连续拦截上千次。owner 结束会话的手段就是创建 ALLOW_STOP 文件或让 session_window.json 的 until 过期。SessionStart 钩子在 matcher \"compact\" 和 \"resume\" 时运行 after_compact.py，向上下文打印一条带 UTC 时间的指令：先重读 CLAUDE.md、PLAN.md、TODO.md、DEVLOG.md 最后三条、STATS.json 再继续当前 milestone 并补进度截图，用于长会话压缩后的状态重锚定。ALLOW_STOP 与 session_window.json 均被 .gitignore 排除，agent 若自己创建它们也不会入库（但机制上不阻止 agent 自造 ALLOW_STOP——这是信任 agent 的软约束，不是硬防线）。 【配套工具链】宿主机侧三个 ps1 是 owner 专用桌面监控：desktop_timelapse.ps1 用 ffmpeg gdigrab 每 -Every 秒截屏存 JPG（running.pid 防重入，-Hidden 后台化），make_desktop_timelapse.ps1 用 libx264/yuv420p/crf20 合成 mp4，stop_desktop_timelapse.ps1 按 PID 且校验进程名为 ffmpeg 才杀。agent 侧脚本：generate.py 是 fal.ai 批量生图器（16 个模型端点、5 并发、产出 images/+results.json+report.html 评审页）；download_mixamo.py 按 UUID 从钉死 revision 的 HF 数据集拉 FBX（二进制头校验、sha256、拒覆盖不同内容、原子写、downloads.json 凭证）；center_glb_bottom.py 无头 Blender 把 GLB 枢轴移到包围盒底心；make_timelapse.py 把 Docs/progress 截图合成带字幕延时视频与分镜图；fetch_refs.py 按 manifest 抓参考图（双 Referer 变体、3 次重试、幂等跳过）。 【安全轨与硬编码假设】安全轨：.env 永不覆盖、密钥不落 git（.gitignore 覆盖 .env/ALLOW_STOP/session_window.json）；Mixamo 与 refs 下载全部幂等且拒绝覆盖冲突文件；stop 脚本只按 PID 杀且验进程名；keep_working.py 对坏配置 fail-closed（宁可拦死不误放）。硬编码/假设：整套是 Windows 向——默认 C:/GIT/unity-mcp-server、Blender 5.1 安装路径、%USERPROFILE%\\Downloads\\Oldcraft-desktop-timelapse、gdigrab 抓屏、依赖 PATH 上的 python/node/ffmpeg/blender；unity MCP 桥端口固定 7890；higgsfield 端点固定 https://bridge.higgsfield.ai/mcp 且鉴权走 CLI 登录而非环境变量；100 USD fal 上限只存在于文档文案替换层面，generate.py 代码里没有预算熔断；安装器假设 Target 基本是空工程，非空时 -Force 复制会覆盖目标里同名文档。

值得注意的点

• install_kit.ps1 只对 .env 做“存在即不覆盖”保护，其余全部 Copy-Item -Force——对非空目标目录重跑安装器会覆盖目标里 agent 已改过的 CLAUDE.md、Docs/**、.claude/ 钩子等文件，套件只设计给空工程用。
• 100 USD fal.ai 预算硬上限没有任何代码级熔断：generate.py 默认 --workers 5 并发、无花费计数、无 dry-run 强制；预算控制完全依赖 agent 遵守 TASK.md §15 与文档文案（安装器用 -FalBudgetUsd 只是字符串替换 "**100 USD**" 和 "hard budget 100 USD" 两处，改数不生效于任何执行逻辑）。
• keep_working.py 是 fail-closed：session_window.json 若 JSON 坏掉或缺 "until" 键，异常被静默吞掉，结果是永久拦截停止；同时它信任 agent 不作弊——agent 技术上可以自行创建 .claude/ALLOW_STOP 停止自己，防线是提示词纪律（"The owner ends the session"）而非机制。
• CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=1000 意味着若 agent 逻辑上无可做事但 ALLOW_STOP 不存在，会被钩子连续弹回多达 1000 次回合，每回合都重读文档再空转——死循环风险由钩子文案里的“TODO 空则跑验收测试并补弱项”兜底。
• 钩子依赖 PATH 上的 `python` 命令且 settings.json 用 $CLAUDE_PROJECT_DIR 定位脚本：Windows 上若只有 python3/py 启动器或 CLAUDE_PROJECT_DIR 未注入（fallback 是 cwd，钩子进程的 cwd 不保证是项目根），Stop 钩子会静默失效或报错。
• install_kit.ps1 调 Mixamo/refs 下载都期望 `python` 已在 PATH 且已 pip install requirements.txt，但它不会自动装依赖，失败降级为 Write-Warning 后安装“成功”——可能装出一个没有动画和参考图的半成品工程，需看输出警告。
• mixamo_core_set.json 的 license 字段明确 "adobe-mixamo-terms (record as Mixamo terms, not CC0)"：这 90 条动画不是 CC0，与 CLAUDE.md 第 6 节“免费资产记 LICENSES.md”并行存在一套 Mixamo 条款的许可记录义务，LICENSES.md 需按 Mixamo terms 记录。
• download_mixamo.py 钉死 HF revision 7f134bc7…，若数据集上游被删/改名安装即 404（仅警告）；其“拒绝覆盖不同内容本地文件”的 FileExistsError 会让安装器第 74 行整体非零退出，重复运行前需手工清理损坏的 .fbx。
• fetch_refs.py 抓的是第三方截图/粉丝艺术（套件故意只发清单），产物仅限 Docs/TASK.md §3 规定的 2D 风格参考用途，不能进游戏资产管线；退出码非 0 时安装器只警告，缺图是常态，需按打印的 source_page 手工补。
• desktop_timelapse.ps1 用 -i "desktop" 会截整个桌面（含其他窗口与敏感信息），且默认输出在 Downloads\Oldcraft-desktop-timelapse（不在工程内）；.gitignore 里的 Docs/owner-desktop-timelapse/ 与脚本实际输出目录并不一致，说明存在两种存放约定。
• generate.py 的 ROOT 取脚本上三级目录找 .env：脚本必须保持在 <项目根>/scripts/image-gen/ 下运行才读到密钥；MODELS 表含 openai/gpt-image、xai/grok、bytedance/seedream 等非 fal 品牌端点但全部经 fal_client 计费，花费全部计入 100 USD fal 预算。
• center_glb_bottom.py 假设 GLB 内 MESH 的 bound_box 可信且以 Z-up（min Z 为底）语义处理，docstring 按 Unreal 描述；导入 Unity 的管线（CLAUDE.md §8）另要求 FBX 导出参数与 scale 1 校验，此脚本只负责 GLB re-pivot，不处理贴图解析问题。
• make_timelapse.py 的截图字幕直接取自文件名 __ 之后的 caption——文件名即数据，agent 按 TASK.md §18 命名不规范（缺 __ 或时间戳）会导致视频字幕错乱；--master 模式跨功能目录按文件名字典序排序，跨日截图混排时需文件名时间戳真实可靠。

不产生任何素材，只负责分诊：给定一个 3D 任务（参考图、生成网格、材质、程序化重建、游戏动画），决定走哪条 API/技能路线，并规定跨会话续接生成作业的纪律。

• 先读 processes/3d-ai/tools.md 工具地图和 knowledge/creative-skills.md 技能目录，再只加载与所请求输出对应的那一条工作流（两者在 kit 内均实际存在）
• 明确把 fal.ai 调用、本地上载、队列恢复全部路由到 ../fal-ai-generation/SKILL.md；旧的 3D AI Studio API 技能已退役
• 核心纪律"先确立工件"：参考图/网格/材质/程序化模型/运动参考/可编辑动画是不同工件；"生成网格"不等于完成蒙皮、game topology、烘焙贴图或可用导出
• 模型标识纪律：Higgsfield 的 job type 与 fal 的 endpoint name 是两套标识符，即使可见模型名相似也不可互换；提交前必须向所选 provider 核实模型 ID 与输入 schema
• 续接纪律：按保存的 provider + job/request ID 续接；轮询超时不算失败作业，不允许重复提交；旧的脚本默认值和 vendor 默认值都不能覆盖用户已做的选择
• 凭据只来自被 git 忽略的根目录 .env 或 provider 自身登录；产物和溯源信息随 Workspace card 保存
• 含分享边界：出现在目录中不等于获准发布用户项目、媒体、账户历史或全部已装技能

把需求和本地参考图变成"已下载、已审核"的素材：优先用 fal.ai MCP，MCP 读不到本地文件时改用自带的 Python 队列客户端 scripts/fal_job.py；是本项目 100 USD fal 预算的实际执行技能。

• 模型选择流程：未指定模型时先调 recommend_model（带真实 task），再 get_model_schema 读精确 endpoint；相似显示名在不同 provider 上不是可互换 endpoint ID；批量提交（尤其视频/3D）前先看定价
• 运行五步法：检查输入文件→只上传本任务需要的参考→按 live schema 组装字段（image_urls/image_url/aspect_ratio/image_size/resolution/duration 各 endpoint 不同，禁止对所有模型塞同一参数对象）→长作业优先 submit_job 并立即落盘 endpoint、request ID、status/result URL 和输入参数→check_job 轮询、get_job_result 取结果
• 恢复语义：processing/IN_QUEUE/IN_PROGRESS 是正常态不是失败；等待超时不授权重复提交；提交没返回 ID 时先查账户历史；COMPLETED 结果里仍可能藏着 provider 错误
• 验收分离：技术完成与视觉验收分开记录；下载产物后才可依赖本地文件而非 CDN 链接；被拒的 take 连原因一起保留；生成的 mesh 仍需独立的 rig/topology/export 检查
• 命令级自检：python scripts/fal_job.py submit --endpoint ... --input ... --out ... --dry-run 不联网不花钱即可验证安装
• 每个 job 一份 receipt（job.json），已存在的 receipt 会阻塞再次提交；密钥绝不打印；凭据和原始签名链接不得进入可分享的报告
• 参考文档路由：参数与恢复看 references/mcp-workflow.md，概念/编辑/材质决策看 references/prompting-and-review.md，换机器连接看 references/setup.md

把一个角色图（任意姿势任意风格）扩展成可拼装的严格正面参考包：2K 严格正面 A-pose 主图 + 三视图补充 sheet + 逐部件严格正面拆件 + 可选 side/back 多视图 + 每资产 360° 视频，供下游 Tripo/Hunyuan/Rodin/Pixal3D 图生 3D 使用；V3 增加视觉分类器反 3/4 漂移校验。

• 最高法则：一切部件 STRICT FRONT 严格正面，绝不 3/4、绝不 hero angle——3/4 部件与正面部件拼不回去；模型跑偏就加强反 3/4 措辞重试，Never ship a 3/4 part
• 8 阶段 3 闸门：Stage 1 接收确认→2A 严格正面 A-pose 主图→2B 三视图补充 sheet→Gate 1 部件清单确认→Stage 4 逐件提取→Stage 4.5 分类器校验→Gate 2 多视图审批→Gate 3 按报价审批 360 视频→Stage 7 打包+manifest.json（含源图 hash、模型+seed、credit 成本、每次校验 verdict）
• 模型路由表：2A/4/5 用 Nano Banana Pro（回退 Nano Banana 2，2A/4 绝不用 GPT-Image-2/2.5，保持风格连续以免破坏下游 3D 重建）；2B 用 GPT-Image-2.5（fal id openai/gpt-image-2.5/flare/*，回退 GPT-Image-2、Seedream V5 Lite，因其多分格构图更强）；Stage 6 用 Seedance 2.0 orbit 模式（回退 Veo/Kling）
• 部件四分类各有硬性姿态表：body-essential（torso/legs/arms/head，严格正面 A-pose 保证接缝匹配）、paired（hands/boots 成对同框同角度、hands 掌心朝镜头 boots 脚尖朝镜头）、accessory（帽子武器一律正面，禁止 hero shot）、hair（默认提取，opt-out 而非 opt-in，软 alpha 边缘）
• Stage 4.5 有界重试：每个严格正面输出先过视觉分类器，verdict 分 pass/soft_fail/hard_fail；hard_fail 最多自动重试 2 次（retry 1 同模型+升级 prompt，retry 2 换 Nano Banana 2），仍失败则把 3 次尝试呈给用户三选一；全部 verdict 写入 manifest.json 供审计
• 成本闸门：Stage 5 多视图使渲染量翻倍（例 9 件正面+10 张多视图=19 张），Stage 6 是最贵步骤（8 件+1 全身=9 次视频渲染），必须先报价再等用户批准
• 统一技术规范：2K（2048×2048 或最近 1:1）、纯白背景 #FFFFFF、中性平光（禁电影光——阴影会毁掉 3D 法线提取）；输出目录结构 00_sheet/01_parts/02_multiview/03_360/ + manifest.json
• 当前为 V3（2026-05-19）；声明自身不含独立生成 runner，分类器用宿主 image inspection 或已配置 vision API 并记录所用方式；作者 Stefan Vaskevich，方法论出自 top3d.ai

对交付的 3D 角色做蒙皮、可编辑 action 动画、修订、回放、烘焙和经过验证的 Unity 交付；源自 2026-09-09 验收的 Overlord Wolf 工作，是 3D 管线末端的动画/交付所有者。

• 先读维护中的流程文档再动手：新动画读 processes/3d-ai/blender-game-animation.md；缺 Mixamo FBX 时先按 knowledge/mixamo-animation-acquisition.md（Archer/Urs/General/Dryad 用过 exact-ID 公共档案+下载器）；疑难查 knowledge/blender-game-animation-lessons.md
• 人的动作参考的既定决策：用 Seedance 2.5 Video Edit，以已验收的角色视频为 motion authority、批准的真人/mocap 服图片为外观，保相机保时序，不从文本重建动作；每条动画对比两条 Seedance 2.5 take + 一条 MiniMax H3 Max take
• 每个新角色 pack 默认含 Run Turn L/R 与 Idle Turn L/R（owner 2026-09-17）；直立体单位用 90 度 Idle turn：后撤步更宽、后脚离地前先有明确躯干旋转（2026-09-18），从既有验收姿态派生，通常无需新运动参考
• 蒙皮标准：automatic weights 只是初值，须检查松散 mesh island、对侧肢体影响、肩胯过渡与硬质部件（牙齿），剪枝后 normalize 并按目标引擎限制影响数；关节极限/张嘴/弯脊柱弯尾巴要在做全量 clip 之前测
• 时序显式化：duration = (last_frame - first_frame) / fps，以秒和帧双记录；单改 fps 会改运动速度，转 clip 要在时间上重采样；攻击接触保持同一归一化比例（wolf 例：1.7s、接触帧比 39/51，但明确这是案例不是默认值）
• 交付验证链：烘焙 evaluated motion 到独立 runtime skeleton、保留可编辑控制 rig；导出检查被静音的 library track/helper bone/地面/相机不泄漏；含 clip 名、时长、loop 标志、root motion、接触事件的 manifest；复制到干净目录重导入验证骨骼/蒙皮/时长/权重/贴图分辨率；源动画批准、导出验证、引擎内集成必须作为三个独立事实报告
• 9 月 19 日直立体引擎档位：逐 rig 脚步相位匹配、0.35s SmoothStep turn 退出与 Idle settle、固定 2x 步、大转弯中 30% 位移、0.55s 恢复；动物需单独步态评审
• 动画环节禁止顺手重生成模型或贴图；Set Pose 摆姿工具与常规 Space 回放（每 action 显式 range/fps、save/reopen 后测试）是每个交付的硬性验收项

定义整条管线唯一母图的生成 prompt：全白背景 2K 严格正面 A-pose 全身图，后续所有部件提取都以它为参照。

• 模型锁定 Nano Banana Pro（回退 Nano Banana 2），明令 NEVER GPT-Image-2/2.5；2K（2048×2048 或最近 1:1）、1:1 方幅
• Prompt 骨架内嵌可验证的正面判据：双肩等宽、双脚等角、双眼直视镜头、手臂约 45° 下外展（非 T-pose 非垂臂）、掌心朝镜头、脚尖朝前、eye-level 零透视、#FFFFFF 无地面阴影、中性漫射光
• {CHARACTER_DESCRIPTION} 替换规则：intake 时构建，必含性别呈现、视觉年龄、艺术风格（realistic/stylized/anime/cel-shaded）、关键服装、配饰、色板
• 约 23 项 negatives 清单（no three-quarter/no body twist/no contrapposto/no hero pose/no foreshortening 等），按各模型语法追加
• 10 项质量 checklist；末条规定：3 次尝试仍不 hold 严格正面就升级给用户，DO NOT ship a 3/4 sheet

给用户的视觉辅助：一张 16:9 图内横排 front/side/back 三个正交投影 + 配饰单独铺开标注，供部件确认 gate 指认和多视图姿态参照。

• 模型 GPT-Image-2.5（2026 年 9 月起默认，fal id openai/gpt-image-2.5/flare/*），回退 GPT-Image-2 再到 Seedream V5 Lite；明确它不是部件提取的输入（2A 图才是）
• 三投影构图规则：front 占左三分之一、side 为右转 90°（相机看到角色左侧）、back 为 180° 正背面，三者脚在同一 ground line，A-pose 全程保持
• 配饰以隔离物体画在图右侧并逐个加名称小字标注（{ACCESSORY_LIST} 来自 intake 检测；无配饰则整段省略）
• 构图失败（视图重叠/各视图换脸）重试 2 次后落 Seedream V5 Lite，再失败则升级用户

四个身体必需部件的逐件严格正面提取 prompt，保证与 2A 母图同角度从而接缝可拼。

• 全部 Nano Banana Pro + 2K + 强制附 2A 母图作 reference；每件有独立模板：torso 颈根到髋顶、切口干净无悬垂布片；legs 双腿同框脚尖朝前；arms 到腕为止、手不含（另提取）；head 表情中性、闭嘴睁眼、含发不含身
• 最常见失败模式被点名：模型会旋转部件（most common failure: model rotates the part）——checklist 首项是可验证的严格正面（部件两侧等宽/等角）
• 失败处理：漂到 3/4 就加强 STRICT FRONT 锚点+反 3/4 负面重打，NEVER ship a drifted part；3 次仍漂移升级用户可选跳过或带警告接受
• V3 条款：输出必须先过 Stage 4.5 分类器，hard_fail 的件不得出货；重试逻辑在 08_3q_classifier.md

左右成对物品的提取规则：成对同框、特写裁切，但两件必须处于同一严格正面角度。

• 与身体件的区别：paired 允许更近的特写换细节清晰度，但角度纪律不变——若左手正面右手 3/4，管线就无法重新装配
• hands 模板：掌心对镜头 dead-on、左左右右同框标注、手指放松微张；boots 模板：脚尖对镜头、带正面可见的扣带鞋底细节
• 非对称对（一手套一护手）有通用 {LEFT_ITEM_NAME}/{RIGHT_ITEM_NAME} 模板，要求标注左右
• negatives 含类别特有项：no inside-palm tilt（手）、no outer-sole tilt（靴）、除非母图如此否则 no clenched fists

六类配饰的严格正面提取模板；配饰是历史漂移最重的类别，此文件是 V2 教训的落点。

• 规则：即使配饰也一律先严格正面——帽子按戴在正面角色头上的朝向、单手武器 blade-front 全长按技术参考图呈现、披风平铺或隐形衣架、珠宝 macro 特写；side/back 只属于 Stage 5 且需用户点名
• 明确记载 V2 的错误决定及纠正：早期版本允许配饰 3/4（理由是用户可在 3D 里转回去），实际迫使手动转回正面并劣化参考质量，故 STRICT FRONT 是唯一基线
• V3 强制条款：配饰必须过 Stage 4.5 分类器不得绕过——V2 数据显示 accessories 是最高漂移类别
• 所有模板要求隔离呈现：no character body parts visible、无角色穿戴（帽是 standalone 但按佩戴朝向摆位）

把头发从头部剥离为独立严格正面参考图，供专门的毛发 3D 管线使用，避免图生 3D 模型把头发糊成与头融合的块。

• 默认 ON、只能 opt-out 不能 opt-in：跳过头发默认导致更差的 3D 输出；可提取的下游用途明确列出（XGen、Hair Tool、Genesis hair、hair cards 贴图参考、手工单独建发）
• Prompt 要点：同时附 2A 母图和 head 提取件；像从头拿起来悬浮在空中但从正前方看；发丝与空气交界处必须 soft alpha edges，negatives 明令 no harsh outline/no clean silhouette cut
• 仅三种情况可跳过：角色秃头、头发完全被帽/兜帽遮住（改提取帽兜）、用户在 Gate 1 显式 opt-out；短发贴头皮、动漫刺发、辫子、kitsune 耳朵都要提取
• 长马尾/辫子/背后造型在 Gate 2 批准后加做 side+back（Stage 5），背面剪影与正面差异大时价值最高

为 Gate 2 批准的部件生成严格正交 side/back 视图；同样是正交视图，3/4 在此同样被禁止。

• Gate 2 交互协议：默认提案为 body-essential 四件+hair 各配 side+back；用户可回复 default / add: [parts] / remove: [parts] / skip all / side only，等待明确答复才继续
• 闸门理由给出量化渲染成本：9 件正面+5 件双视图=19 张，每张都耗 credit，用户必须对体量知情同意
• side 必须是精确 90° profile（不是 80° 不是 100°）、back 是精确 180°（不是 back 3/4）；模板要求附 2A 母图+该件的 Stage 4 正面件双 reference，切口与正面件同一解剖地标
• 含 head、hair、accessory 的专用 side/back 变体模板；通用 negatives 独有 no 45° angle 一项

生成 Blender/Marmoset turntable 式参考视频：相机锁死、主体自转 360°，是成本最高、也最容易被视频模型的电影化倾向毁掉的阶段。

• 硬规则：Camera LOCKED、主体绕自身垂直轴顺时针转满 360° 回到面对镜头；视频模型默认会 dolly/加戏/灯光漂移，全部与参考转台相反，这是本步骤被称为最难的原因
• 参数：Seedance 2.0 orbit 模式（回退 Veo、用户点名则 Kling）、4-6 秒、1:1（高瘦资产用 9:16）、以该资产静帧作首帧锚定、全程纯白背景中性平光
• 三类 override：全身角色 5 秒 A-pose 不变、小物件（戒指珠宝）4 秒柔和顶光 macro、长资产（武器法杖披风）绕长轴垂直摆放 5 秒
• 不合规升级链：锁相机 2 次失败后依次改用 tripod-mounted security camera 措辞、加唯一运动是主体旋转显式反运动条款、缩到 3 秒减少漂移窗口、最后落 Veo orbit mode
• 成本条款：8 件+1 全身=9 次视频渲染，Gate 前报价，cheapest opt-out 是仅全身；全身 360 先渲染，用作部件 360 姿态漂移的对照

定义每张严格正面/多视图输出的结构化验尸 prompt：分类器输出 JSON verdict，驱动有界自动重试环，是 V3 修补 V2 加强负面词仍挡不住 3/4 漂移缺口的机制。

• 三套 rubric：strict-front 六项二值检查（body_axis_dead_front/no_three_quarter/no_body_twist/no_hero_angle/no_partial_back/framing_clean）；side rubric 查 90° 精确度和两种 3/4 中间态；back rubric 查 no_partial_face 等
• 判定规则：6 项全过=pass；1-2 项轻微=soft_fail 带警告接受并记 manifest；第 1/2/3/5 项任一明显失败=hard_fail；第 4/6 项单独失败通常 soft_fail
• 输出为纯 JSON（含 estimated_camera_rotation_degrees 带符号估计旋转角），无散文无 markdown fence；文件自述只提供 rubric 不含部署的分类器服务，用宿主 image inspection 或已配置 vision API 并记录方式
• 升级重试 prompt 模板把分类器失败原因和旋转度数原样写进 [CRITICAL CORRECTION] 头部再拼原 stage prompt；Retry 1 同模型、Retry 2 换 Nano Banana 2、再失败给用户三选一（带警告接受/自定义指令再来一次/跳过）
• manifest 逐件记录 attempts 数组（model+verdict+reason+image_hash）、final_verdict、retry_count、accepted_image
• 成本与边界：每次校验约 1-2 美分（GPT-4o-mini-vision 档）、10 件约 15% hard_fail 率≈12 次调用，远廉于一次 Nano Banana Pro 重生成；用户可显式跳过校验（记 manifest）；Stage 6 视频不自动分类，改人工过目
• 默认选 GPT-4/5 vision 而非 Claude vision 的理由：管线在 Stage 2B 本就要求 OPENAI_API_KEY，且 JSON 严格输出在 GPT-4o/5 上成熟；rubric 可移植，改用 claude-opus-4-7 vision 保持 prompt 不变即可

列出 2026-09-15 验证过的 fal.ai MCP 工具面、按阶段给出必备入参，规定队列恢复动作和凭据头格式边界。

• 8 个 MCP 工具映射到阶段：recommend_model(task)/search_models/get_model_schema(endpoint_id)/get_pricing/upload_file/run_model(提交并短等)/submit_job(不等待)/check_job(endpoint_id+request_id+status_url)/get_job_result(可带 response_url)；工具名可能被宿主加前缀，要现场 discover 而非硬编码
• 额外验证过的路由示例：fal-ai/patina/material（文生材质，必填 prompt，含 maps/image_size/tiling_mode/output_format，与处理图像的 fal-ai/patina 不同）；tripo3d/h3.1/image-to-3d（必填 image_url，几何/贴图质量、PBR、朝向、面数为独立控制）——用来说明输入必须跟实际 operation 走
• 可用的忠实编辑示例入参：endpoint fal-ai/nano-banana-pro/edit，字段 prompt/image_urls/aspect_ratio:auto/resolution:2K/num_images:1/output_format:png，并声明字段是当时 live schema 的快照、下次用要复查、禁止提交 example.invalid 占位 URL
• 本地上载标准命令：python scripts/fal_job.py --env /path/to/project/.env upload --file reference.png --out reference-upload.json，从保存的 JSON 读 url；大 base64 不进对话；localhost URL 不是公网 URL
• 恢复纪律：IN_QUEUE/IN_PROGRESS/processing 都表示继续原请求；COMPLETED 后先查结果里的错误；下载失败重试同一 result，禁止为重下而重新生成；提交结果未知先查账户历史；取消是单独的用户授权动作
• 凭据三格式不可混用：fal 托管 MCP 用 Bearer 头，REST 模型 API 用 Authorization: Key，Python SDK 读 FAL_KEY；MCP 不共享聊天应用订阅，生成走接收者自己的 fal 账户

规定概念探索、忠实编辑、材质、mesh、运动参考五类任务的 prompt 写法和交付前人工评审清单。

• 概念探索只变有意义的设计维度（silhouette/比例/构造/色板/氛围），候选要标注使用户无需重打 prompt；模型能多生成不是扩批的理由
• 忠实编辑：点名什么保留、精确改什么，复用已验收图而非长文重建；多参考要分工（body 来自 A、material 来自 B、pose 来自 C）；材质编辑保持 mesh/剪影/相机/背景不动
• Patina 材质生成、mesh 重贴图、mesh 生成是三件事不能互替；不得用高模生成承诺 game-ready mesh；PBR 贴图要逐通道确认分辨率、UV、色彩空间与法线惯例，高模细节烘焙到低模后单独验证导出材质
• 运动参考：写明起始姿势、动作、接触/恢复、相机、时长；真人/服装转移用已验收视频作 motion authority；新生成 clip 是视觉参考不是测量 mocap 数据，可读源运动与更短的游戏时序分开保持
• 交付评审 7 条：全尺寸对照输入与 brief、核对数量/取景/身份/缺件/多余件、确认每个文件可打开且报告链接真实文件、每输出一个 verdict 并记录取舍原因、只改失败判据不推翻已批特征、到请求量即停、绝不藏失败 take 或不检查就宣布批准

说明如何把整个 fal-ai-generation 文件夹复制到其他项目并完成 MCP 与 Python 两条链路的连接。

• MCP 连接：fal dashboard 建 key（inference/API scope），Streamable HTTP 端点 https://mcp.fal.ai/mcp，Authorization 头填 Bearer <key>；勿与文档连接 https://docs.fal.ai/mcp 混淆；要在活会话里确认 get_model_schema 等工具存在，配置文件本身不证明连接
• key 的传递方式：原仓库 .env 里放 MRMAK_MCP_FAL_AUTHORIZATION（完整 Bearer 值），.mcp.json 用 ${MRMAK_MCP_FAL_AUTHORIZATION} 展开、Codex 用 env_http_headers；根 .env 不会被每个 MCP client 自动读取；合入既有配置而非覆盖其 servers
• Python helper 要求 3.10+：python -m pip install -r scripts/requirements.txt 后 python scripts/fal_job.py --help；key 读取顺序 FAL_KEY→legacy FALAI_KEY→MRMAK_MCP_FAL_AUTHORIZATION，--env 显式指定 .env，凭据绝不打印
• 免费自检命令：python scripts/fal_job.py submit --endpoint fal-ai/nano-banana-pro --input examples/concept.json --out output/concept --dry-run——不 import SDK、不联网、不建付费 job；真实 submit 消耗账户 credits
• 分享纪律：只分享干净源目录，绝不分享含 .env 或私有 receipt 的工作目录；receipt、上载记录和生成媒体留在接收者自己的任务目录

给出一个不花钱的排练脚本和一条真实生成后的续接命令序列，教会 agent receipt→status→result 的标准节奏。

• 示例任务：一个 brass observatory robot（望远镜头、三足、蓝色机身），先查 live schema，本地保存结果+prompt+request ID，编辑决定留到用户看完
• 排练命令 dry-run 预期输出：dry_run: true + endpoint + input 字段名；明确这验证的是 helper 安装而非账户权限
• 真实流程：省略 --dry-run 后 receipt 在 output/robot/job.json；续接用 python scripts/fal_job.py status --job output/robot/job.json 和 result --job output/robot/job.json，result 下载媒体到同一任务目录，检查对象之前不算 accepted
• 编辑路径：上传选中的本地文件→用保存的 upload URL 替换 edit.json 占位→检查 edit endpoint→开新任务目录
• 自述诚实性声明：包内没有样例渲染，验收标准（完整机器人、望远镜头、三足、蓝身、可读剪影；编辑只改漆色）是排练 brief 不是已生成的断言

一个中性的文生图输入文件，演示 text-to-image endpoint 的字段形状，无私有美术与真实账户 URL。

• 字段组合对应 Nano Banana Pro 概念端点：prompt + aspect_ratio:1:1 + resolution:2K + num_images:1 + output_format:png
• prompt 本身示范参考级写法：单一完整物体、居中、中性背景、柔和均匀光、可读剪影、no lettering
• 被 setup.md 和 WALKTHROUGH.md 的 --dry-run 命令直接引用，作为零成本安装自检的输入

演示编辑 endpoint 的输入形状：prompt 显式声明只改什么、保住什么，参考图字段留占位符。

• prompt 模板示范忠实编辑句式：Keep the exact same object, proportions, camera, background and lighting. Change only ... Preserve ...
• image_urls 是 https://example.invalid/replace-with-your-upload.png 占位符——fal_job.py 的 submit 对含 example.invalid 的输入会直接 raise ValueError 拒绝提交，测试用例专门验证这条防线
• 字段与 mcp-workflow.md 的 nano-banana-pro/edit 示例一致：aspect_ratio:auto、resolution:2K、num_images:1、output_format:png

不依赖 MCP 的独立 Python 客户端：本地文件上载、队列提交、状态轮询、结果下载，全部围绕一份可续接的 job.json receipt 设计，核心目标是防重复扣费。

• 四个子命令：submit（--endpoint/--input/--out，支持 --dry-run）/ status --job / result --job / upload --file --out；输出均为单行 JSON
• 防重复提交机制：receipt 以 open(x) 独占创建，已存在即拒绝再次 submit；提交抛异常时 receipt 保留并标 status=submission_unknown，强制先查账户历史；example.invalid 占位符输入直接拒发
• submit 的 dry-run 分支在任何 import fal_client/dotenv 之前返回 {dry_run:True, endpoint_id, input_fields:sorted(inputs)}——零网络零 SDK 零付费；真实 receipt 记录 provider/endpoint_id/完整 input/created_at，成功后补 request_id 与 status_url/response_url/cancel_url
• key 解析：依次查环境变量再查 --env 指定（或仅 cwd）的 .env，名字容忍 FAL_KEY/FALAI_KEY/MRMAK_MCP_FAL_AUTHORIZATION，正则剥掉 Bearer/Key 前缀后写回 os.environ[FAL_KEY]；异常输出只报类型不带 SDK 原文（防签名 URL 泄漏进对话）
• media_urls() 递归发现嵌套结果里的媒体：dict 带 url 字段、以 _urls 结尾的 key（如 model_urls）、https 字符串列表——测试专门验证 model_urls.glb 与 map_type:normal 这类 3D/PBR 结果能被收齐
• download_result()：只允许无内嵌凭据的 https、按 sha256(url)[:10] 命名、.part 临时文件原子落盘、单文件 512 MB 上限、按 content_type 猜扩展名；result.json 已存在时离线复用（队列历史过期后仍可取）；结果含 error/error_type 时标 provider_error 并 raise，绝不静默下载
• upload 幂等：按源文件 sha256 比对已有 receipt，同文件复用 URL、异文件要求换输出路径

fal_job.py 的全部运行时依赖，刻意保持最小。

• 仅两个依赖：fal-client>=0.13.2,<1（官方 SDK，读 FAL_KEY 环境变量）与 python-dotenv>=1,<2（解析 --env 指定的 .env）
• 上限锁定（<1、<2）防止 SDK 大版本破坏 queue API 调用签名
• 被 references/setup.md 的安装命令直接引用：python -m pip install -r scripts/requirements.txt

用 unittest + Mock 固化 fal_job.py 的每条防扣费/防误判行为，使这些纪律在后续修改中不可回归。

• test_dry_run_never_loads_sdk_or_writes_receipt：patch client 抛 AssertionError 证明 dry-run 路径不加载 SDK，且连输出目录都不创建
• test_existing_receipt_blocks_duplicate_submission 与 test_uncertain_submission_keeps_guard：receipt 存在即拒（ValueError）；提交异常后 receipt 状态为 submission_unknown、异常原文（private provider details）绝不写入 receipt、后续 submit 仍被拒且 sdk.submit 全程只调用一次
• test_processing_result_never_fetches_or_resubmits：状态 IN_PROGRESS 时 result 命令不调 sdk.result 也不调 sdk.submit——落实超时不是失败纪律
• test_completed_provider_error_is_not_downloaded：COMPLETED 但结果含 error 时 download_result 不被调用并 raise；test_placeholder_is_not_submitted：example.invalid 输入拒发
• test_nested_models_and_material_maps_are_discovered：media_urls 对 map_type:normal 图片和 model_urls.glb 的收集顺序断言；test_saved_result_does_not_require_provider_history：本地 result.json 存在时零 provider 请求返回 result_saved + review:pending

记录 owner 对 AI 3D 资产生成（Customuse MCP + fal.ai）的默认决策，避免每次重新询问模型选择；定义了被锁定的烘焙降面管线（bake-down pipeline）。

• 术语必须区分：Patina（fal.ai）是给网格做材质的工具（owner 最爱），与 Meshy 7 retexture（Customuse 的 textureGeneration 节点）不是一回事。
• 锁定的管线（2026-08-28）：1) Tripo v3.1（tripoV31Mesh3d）高模 faceLimit≈300k、自带 4K 贴图，质量优先；2) meshDecimation（Blender Collapse）把 prop 降到约 5-9k 面；3) uvUnwrap（xatlas 默认）；4) textureBaking：源=带贴图高模，目标=展开低模，bakeChannel ["all"]（basecolor/normal/roughness/specular/metalness），2K。
• 最终游戏资产是 bake 节点的输出，不是生成的高模。CR1 在 Map01 prop 批次上被 owner 直接否定（"bad"），由此锁定此管线。
• 纹理/材质默认必须用 fal.ai 的 Patina，除非 owner 明确另说；Customuse 上可并行测试 Tripo v3.1 一体出图和 Meshy 7 retexture 两个变体做对比。
• Tripo P1 仅作为低风险快速 prop 的备选。工作流在 Customuse canvas 上组装，结果（GLB/FBX/贴图）交回本地项目。

记录经实测的图像生成 API 细节、模型轮换策略、3D 参考图的 prompt 默认值和报告规范，直接可用于本项目的概念图/贴图生成。

• API 细节：生成用 fal-ai/nano-banana-2（aspect_ratio 参数）；编辑端点 fal-ai/nano-banana-2/edit 需要 image_urls（复数数组），写成单数 image_url 是常见错误；Pro 版为 fal-ai/nano-banana-pro。
• 粉丝向/IP 编辑：fal-ai/nano-banana-pro/edit 加 safety_tolerance: "6"（字符串，最大宽松度）+ enable_web_search: true + resolution: "2K"。但 prompt 侧内容审查（422 content_policy_violation）在生成前触发，safety_tolerance 绕不过——品牌词是常见触发器（"Chevy V8 valve cover"、"classic American V8" 被拒，改为纯描述性措辞立即通过），材质 prompt 必须去除品牌/IP 词。
• 背景移除正确端点是 fal-ai/imageutils/rembg（bria/background/remove 和 fal-ai/bria-rmbg 均 404）。上传用 fal_client.upload_file() 拿远程 URL。
• 模型轮换（2026-08-20 更新）：概念探索默认组合是 nano-banana-pro + grok-imagine-2 + seedream-v5-pro 同 prompt 并排对比；GPT-Image-2 被降级。Grok Imagine 2 的 t2i 路径必须带 /text-to-image 后缀（xai/grok-imagine-image/v2.0 返回 "Path /v2.0 not found"）。
• 永远并行生成：ThreadPoolExecutor 5+ workers，21 张图串行约 10 分钟 vs 并行约 30 秒；results.json 里必须保存远程 URL。
• 3D 参考图 prompt 默认：纯色中灰背景（不是白/黑/花纹）；风格锚定语 "stylized 3D Unreal Engine 5 render, non-photoreal, not cartoon"；色彩写明 60/30/10 比例。A-pose（ arms 偏离身体 30°）与 variant A（A/B/C 变体第一个）是两个概念，绝不能混淆。
• 风格关键词与参考保真度成反比：忠实复刻要剥掉所有风格关键词、以 "recreate the exact X, do not redesign" 开头（Akira 项目 v3 加 Arcane/Guilty Gear 风格词导致角色不可辨认，v4 剥离后正确还原 Kaneda 摩托）；探索阶段风格词才是有用的杠杆。

定义获取 Mixamo 动画 FBX 的标准路径：本地缓存 → HuggingFace 公共档案 → 精确 UUID 下载器；最后才请求 owner 手动下载。Overlord 的 Archer、Urs、mounted General 已验证此路线。

• 顺序：1) 查已接受参考目录记录 Mixamo motion UUID（名字有歧义，必须用 UUID）；2) 搜本地 ArtSource/Characters/*/Source/Animation/Mixamo/ 缓存及 downloads.json 回执；3) 用 HuggingFace 数据集 Linzhan/Mixamo-Animations-Characters（metadata.csv 映射 motion_id/prompt/description/frames/file）；4) 跑 scripts/animation/download_mixamo.py --motion-id <uuid>，按精确 UUID 下载、校验 FBX 二进制头、写 SHA256 到 downloads.json、拒绝覆盖不同文件；只需 requests，无需登录/API key。
• Dryad 已验证样本（档案 revision 7f134bc734557b1d9516cb476d25ea1f577e45c1）：Standing 2H Magic Attack 03（UUID e21d35a0-…）130 帧/4.3s；Standing Idle 03（51e30f03-…）343 帧/11.4s；Standing React Death Forward（586a54c0-…）111 帧/3.667s；均为 30 fps、每 1/30 秒一个 key、315 条曲线（含常量通道）。
• 导入到已有的 Blender 实例检查动画曲线、时长、key 间距，只删临时导入对象，保留 owner 编辑/当前 Action/帧号；不要为接收另开 Blender。
• 许可标注为 adobe-mixamo-terms，不得把动画文件描述成 CC0 或新许可。
• 9 月 24 日教训：路线曾被埋在旧脚本里，agent 没找到、不必要地让 owner 手动下载 3 个文件。绝不可静默用名字相似的动作替代（Archer 的 Standing_Idle_03_Examine.fbx 不是 Dryad 的 Standing Idle 03 / Playing With Magic）。

最大的经验文件（367 行）：从 Overlord 已批准的 Wolf、Scorpid、Skeleton Warrior、Urs、Dryad 等交付中沉淀的 Blender 绑定、权重、烘焙、导出、播放与评审的可复用教训。测试环境 Blender 5.1.0。

• 四足基线（2026-09-10 owner 批准的 Wolf rev 07）：9 条起步 clip（Idle/Run/Attack/Death/Walk/Turn L/R/Run Turn L/R）；Run 由实际平面距离的单一归一化相位驱动、按转向曲率混合不重启循环；Wolf 批准步幅 45°×30 帧间隔×2=90°@30fps；Run 保留艺术标定 2m 步幅（原生 scale-2 实测 1.05m）、Walk 每循环 0.68m；58 条运行时断言 + 279 个采样姿态通过。这些数值是 Wolf 标定，不可照搬。
• 权重：热权重初绑后必须解剖清理（对侧肢体泄漏、肩部权重进鬃毛、牙齿要刚性绑到正确上下颌骨）；剪枝到 4 influences 后再查一遍。Wolf 最终源网格 9,209 焊接顶点/17,835 三角面，glTF 导出 23,663 顶点（接缝导致），导出顶点数变多不等于几何重复。
• 计时纪律：数时间区间而非样本数——0-51 帧是 52 个样本 51 个区间，30fps 下 1.7s；接触帧 39 → 1.3s、39/51=0.7647058824。改节奏到 T 秒时速度用 1.7/T、接触时间 T*39/51。24→30fps 若只改场景设置会缩短循环，必须重采样（保留 Idle 2.5s、Run 0.833333s）。
• 烘焙导出：作者 rig 38 骨、游戏文件 28 骨无约束；Root 和 Body 虽不形变也要保留（携带层级与局部运动）。验收标准：拷贝目录后 FBX/GLB 在干净场景重导入，21 个采样姿态误差 <0.000001m（FBX 实测约 5.6e-7m、GLB 约 7.6e-7m）。
• 导出后验证纹理必须真实加载像素（packed glTF 在像素访问前报 has_data=False 是误报）；Blender glTF 导入器会生成 BoneShape 辅助网格，报"多余角色网格"前先核对 GLB 原始 mesh/skin 列表；拷贝文件夹测试防纹理从旧目录解析。
• 几何修复教训：Wolf Run 后腿在 14-16 帧折叠是 thigh/shin IK 求解接近奇异——是 rig 问题不是权重问题（先查骨骼轨迹再重画权重）；膝盖 pole 直接取 thigh 向量会在大后撤步时翻转，要先去掉沿 hip-to-ankle 轴的分量再投影。Urs 转身：钟形胸偏移叠加变化的骨盆 yaw 会让胸朝向短暂倒退，胸的绝对朝向要单独定义并检查单调性。
• Blender 5.1 specifics：复制 rig 要显式绑定 action slot；复制的 IK target 保持局部；未用的播放场景加 fake user 防丢失；Bone.vector 是父级相对坐标，armature 空间方向要用 bone.tail_local - bone.head_local（搞混会把盾牌和肩甲转错）。
• 动作切换会继承变换：旧 Action 没有手指通道时，从新姿势切回会残留约 100mm 手指位移——给旧 Action 缺失通道补常量 key，别假设未打 key 的通道会自动复位。Dryad 的 Mixamo 命名 RightUpLeg 实际是下躯干不是腿；施法预览范围要先开 use_preview_range 再设边界（Dryad 用 40-87、闭合 88）。
• MCP 备用路线（owner 2026-09-14 确认）：Higgsfield Blender 连接掉了先试常规 Blender MCP（随 Blender 自动启动）；交互式桥不保留跨调用的 Python globals；长调用超时但 Blender 仍在跑，用保存的脚本/日志/进程检查避免重复劳动；后台 --factory-startup 隔离第三方插件。

从 Wild Skeleton、Human Swordsman、Human Archer、Urs、Mounted General 五轮 owner 评审中汇总的作者决策与评审纪律，规定 carry pose、步态、重心转移、转场修复和交付习惯。

• 先检查打开的 Blender 文件再动手：磁盘版本可能早于 owner 的实时修改，先抓可恢复副本；后续贴图包只换外观、保留已批准运动；换 Action 前核对骨骼名/rest 变换/绑定兼容。
• 动作必须从 RTS 俯视角读得出来（2026-09-24 重申）：以游戏尺寸判断，别把迭代花在上看不见的小幅；肩/头引导+延迟的手部可让软体或扎根生物显活。
• carry pose 先于动作库：手全程握住道具，Wild Skeleton 双手剑握持保留，Archer 双弓击打命中瞬间弓更水平、bow 留在源盾牌手。Urs 同侧手脚运动被拒——普通两足 Run 前臂必须对侧前腿。
• Warrior 步态修复实例：保持步频缩短步幅后，站姿膝弯均值从 61.4° 降到 28.8°；修订后 1.5m/0.6s 的 Run 在 visual scale 1 下 3.5m/s 需要 1.4x 采样。'elbow inward' 被误解为内侧 pole 拉向肋骨遭拒（owner 意思只是掌心朝前的垂臂）——旋转歧义要拿现场演示姿势确认。
• 转场要修整条链不是只修端点：Archer Shot 第 14-19 帧抖动涉及躯干+手臂；死亡膝不能先内塌再反向；Archer 55 帧 Death Right、Swordsman 60 帧 Stun 是个例不是模板。+15% 提速 = 时长除以 1.15。
• Mounted General 教训：Review 03 的自定义 IK solver 被拒——它在每个 timer tick 覆盖直接手臂编辑；Review 04 改用真实肩/肘/腕骨的直接 FK、暂停所有动画同步后被 owner 批准并要求所有后续评审沿用（2026-09-20）。盾牌是 549 顶点的刚性集合，由 hand 父级 shield_grip 骨独立携带；owner 在 Idle 第 102 帧亲手做的 carry 要在全部 22 条 clip 保留。
• 交付习惯：主人直接在 Blender 里审——留正确文件、选好 Action、普通空格播放、保存中性 Material Preview，不做评审视频；结束前做拷贝包重导入+采样姿态对比+可移植纹理；用户批准、源 QA、导出 QA、Unity 集成四件事分开记录，检查通过不等于视觉验收。

记录 Wolf 90 度转向 clip 集成进 Unity 的具体规则：相位匹配表、转向出口混合、与双足标准的差异，以及 FBX 100x 缩放导致的包围盒误报。

• 补充转向 clip 单独导入，保留既有模型/Avatar/材质/步态/战斗 clip；核对骨骼路径、帧原点、时长、小数帧 key、静止 Root 和带符号 heading 曲线。
• 玩法用独立导航 yaw + 每角色固定 authored 步频（默认 2x；Wolf 4x）。绝不为等完整源转向而延迟移动；保持重复指令下的相位和即时战斗/Stop/死亡打断权。
• 双足的两脚/两膝匹配表对动物不完整：Wolf 用四爪+前臂+小腿+hock 相对 Body 匹配；每种移动步态烘焙 64 个采样姿态、只在转向出口匹配，不逐帧搜索姿态；直行/左/右 Run 共享同一相位。
• 转向出口/停止用完整 0.35 秒有限 SmoothStep 混合，要检查中间帧的实际肢体变换而不只是 mixer 权重。Wolf 平衡参数独立保留：4.4 m/s、误差超 30 度时 20% 平移加速、即时释放、360 度/s 转向。
• 陷阱：Wolf 导入网格 transform 是 100x——BakeMesh 审计包围盒要补偿缩放并把顶点变换到实际根骨坐标，直接拿原始烘焙顶点比 localBounds 会误报 overflow（改正后无需改 prefab bounds）。
• 这是相位匹配，不是 foot IK 或接触锁定声明；步态 clip 一旦改动必须重建姿态表。

自动化输入测试把真实键盘鼠标锁死的事故复盘与恢复协议；CLAUDE.md 第 8 节明确引用，是本项目所有自动化 Play Mode 测试必须逐字复用的规则。

• 事故：被中断的 Editor 输入测试让 'Unit lab test mouse' 和 'Unit lab test keyboard' 保持激活、真实设备被禁用，玩法点击/UI/滚轮缩放全部失灵，与选择几何无关。
• 不要只依赖 MonoBehaviour 字段或协程完成做清理：脚本重载会丢字段，嵌套迭代器失败可能绕过外层协程的 cleanup。
• 共享 EditorInputReplay 辅助器规则：接管输入前捕获启用设备 ID、当前 pointers、输入设置、dirty 状态、time scale，恢复数据持久化到 Editor SessionState；在脚本重载前、Play Mode 退出、组件 disable/destroy、正常完成和失败时全部恢复；嵌套迭代器同受 finally 管辖；拒绝重叠回放；保留刻意预先禁用的设备。
• 测试后必须验证硬件所有权，即使断言全部通过——合成设备还是 current 时绝不允许报告输入 QA 完成。
• EditorInputReplayChecks.Run() 用 8 个同步清理用例覆盖，不排队点击/游戏指令。

owner 批准的直立单位（人类/骷髅/双足 Urs）转向-行进相位匹配集成标准，含每角色一次性配置流程和 2026-09-19 批准的五角色共享数值档案。

• 问题：转向可在 clip 任意点结束，恢复任意背景的 Run 相位会换领先脚、产生可见跳变，加长 crossfade 解决不了。方案：交接瞬间从与当前可见腿部姿态最接近的 Run/Walk 相位起步，再按距离推进步态；比较双脚+双膝相对髋部（排除 controller yaw、世界位移、装饰性 turn retreat），匹配最后一次评估的混合结果。
• 每角色一次性配置：在真实导入 rig 上辨认髋/脚/膝并验证前向轴与骨骼路径（Urs baker 用 Mixamo 骨名，其他 rig 要显式映射）；每步态烘焙 64 采样共享姿态表，脚全权重、膝四分之一权重；只在离开转向时选最近相位，已有的更好相位要保留。
• 共享档案（2026-09-19 批准，适用 Human Archer/Human Warrior/Skeleton Warrior/Skeleton Archer/Wild Skeleton）：误差超 30 度保留 30% 请求速度、SmoothStep 0.55s 恢复、270 度/s 转向、authored 步频固定 2x；Turn→Run/Walk 和 Run/Walk/Turn→Idle/Ready 都用完整 0.35s 有限 SmoothStep；之前的 0.22s 指数曲线因手臂移动过快被否。
• Urs 的 3.8 m/s 和 +10% Run 变更不是全队重标定；动物和 General 占位保留各自行为。转向出口匹配表若源 clip 变化必须重建。
• 数据细节：五对 RosterTurn90_01 用 193 采样、0.234375 帧间距；Urs 间距不同；绝不要假设四分之一帧。引擎入口：UnitAnimationPlayer.PhaseMatching.cs、UnitLocomotionPhaseBaker.cs、Unit.Steering.cs 等。
• 这是视觉相位选择，不是 foot IK 或 root motion；绝不因这套装置把导航推迟到整步结束。每个角色交接要写明相位匹配是否配置、骨映射、步幅/混合标定和缺失 clip。

把 2026-03-15~09-15 的 170 卡 Workspace 注册表审计结果编成 8 个已选交接模块的路由索引（图像生成、角色表、fal.ai、Higgsfield、img2threejs、材质烘焙、动作参考、Blender 动画导出），说明存储与发现结构。

• 审计覆盖 170 张卡，其中 89 个描述命中 3D/生成主题——但明确声明这些只是发现候选，不是 89 个已验证工作流。
• owner 于 2026-09-15 选定全部 8 个模块，并按其要求用 fal.ai 技能替换退役的 3D AI Studio；打包时未运行任何付费生成。
• 模块化按需加载：先走 3d-production-routing 路由再只加载需要的模块，不要把一切合成一个大技能；工作流在 processes/3d-ai/、观察在 knowledge/、原始回执随项目。
• 注意 kit 内相对路径（../.claude/skills/、../processes/3d-ai/、../projects/overlord/ 等）多指向原 Overlord 工作区，在 WorldOfOldcraft-build-kit 里未必存在，引用前要先确认目标是否随 kit 安装。
• 历史证据注意：8 月前的 Workspace 文件夹已在 commit 3a549713 本地移除，示例要查 Git 历史；img2threejs 保留 Apache-2.0 许可，Higgsfield 厂商工具仍是外部依赖。
• 诚实边界声明：打包检查不构成新的付费生成、分类器实现或自动绑骨服务。

规定在 Blender 动画制作之前如何用 AI 视频生成挑选运动参考：确定用途/演员/相机、批准起始姿势、按固定配方生成候选、评审归档、以及生成人体版本供视频动捕的默认方法。

• §0 每次新批次前先与 owner 确认两条路线：直接在人体上生成供视频动捕(mocap)，还是在游戏角色上生成供 GPT/动画师做运动参考；当前偏好是角色优先、再对胜出动作做人体重制；相机角度按用途选择，三分之四/等距视角不是强制默认。
• §1 起始姿势必须先经 owner 明确批准，之后作为候选视频的 starting-frame 输入角色（start_image），而不是只在提示词里写 'character reference'；批准一张起始图不等于批准由它派生的所有后续动作。
• §2 基线配方（owner 确认）：每个动画 2 条 Seedance 2.5 take + 1 条 MiniMax H3 Max take，精确模型 ID 为 `seedance_2_5` 和 `minimax_h3_max`；记录源图哈希、精确提示词、模型 ID、provider job、fps、时长与视频 URL/文件。
• §3 决策标签体系：Selected(绿)/Candidate(黄)/NEW/History；生成完成或技术检查通过不等于艺术验收；保留早期版本并用稳定变体名，重新分类时不删原文件。
• §4 Warrior 完成包共 8 条胜出参考（Idle、Walk、Run、Stun、两条 Attack、两条 Death）；'参考包选定' 是与 authored Actions、导出资产、引擎验收相互分离的里程碑。
• §5 人体版本standing decision（2026-09-13）：默认用 Seedance 2.5 Video Edit（`seedance_2_5`, `mode=video_edit`），以已批准的字符视频为运动源、人体动捕服图为外观源；外观图必须逐动作匹配源片起始姿势与武器握持，否则 Run/Idle 会继承搭箭姿势、Stun 会把手抬到胸前。
• 教训：Archer 的 16 条人体重制因动作『太像人』被整体否决——匹配起始图、模型和精确运动提示词并不能保留已批准的运动；保留运动就要以已批准的『视频』为运动源，不要把提示词一致当作运动保真证据。
• 历史 prompt 驱动重制流程（human-mocap-02）：每个胜出源 2 条 take（Seedance 2.5 与 MiniMax H3 Max），目标动捕服务 QuickMagic，但提取与 Mixamo 兼容 FBX 导出并未完成；文中链接的 projects/overlord/skeleton-animation/warrior-05 等 README 在本 kit 中不存在（断链）。

2026-09-09 由 Overlord Wolf 生产确立的主工作流：检查输入与定义输出、可恢复工作区、网格/骨骼准备、蒙皮压力测试、按参考 block 动作、精修、派生游戏 clip、烘焙运行时副本、导入验证与 Unity 交接。

• §1 动手前读目标游戏的动画需求并写出 clip contract（Clip/Timing/Behavior/Events/Motion/Rig 六字段）；测量参考视频 fps/帧数/分辨率；缺失 Mixamo donor 按 knowledge/mixamo-animation-acquisition.md 用精确 UUID 获取，缩略图和同名动作不算替代品。
• 标准转身 clip（2026-09-17 起每个角色包必含）：Run Turn Left/Right、Idle Turn Left/Right；直立项从已批准 Run 派生（保四步周期、共享归一化相位），直立单位用 90 度两步转身（2026-09-18 Urs 标准）；运行时 root motion 关闭，随 FBX 交付哈希过的 controller-motion sidecar。
• 地面四足用 Wolf revision 07 确立的 9 clip 构成（2026-09-10）：Idle、Run、Attack、Death、独立 Walk、Turn Left/Right、Run Turn Left/Right。
• §3-4 Wolf 作者绑定 38 骨含 26 根 deform 骨；焊接容差 0.000001 m（与其尺度绑定，不可照搬）；蒙皮六步清理（抑制对侧影响、镜像平均、躯干按解剖分区、下颌防胡子拉伸、牙齿刚性、平滑+剪枝归一）；导出每顶点最多 4 根影响。
• §7 游戏 clip 时间公式：duration=(last_frame-first_frame)/fps，contact_fraction=contact_time/duration；Wolf 攻击 0-51@30fps=1.7s、接触帧 39=1.3s=76.47%（满足 owner 要求的 75-80%），死亡 0-40@30fps=1.333333s；换 fps 必须按等效时间重采样，FBX 导入器可能把帧原点平移 1。
• §8a standing preference（2026-09-18）：每个交付 .blend 重开时必须以 EEVEE Material Preview 显示真实材质，中性 studio.exr strength 1；§8b（2026-09-20）：评审必须带 Set Pose/Save Pose Reference/Return to Animation 可编辑姿势参照。
• §9-11 烘焙独立运行时骨架、导出前锁定动作列表并排除地板/相机/控制物；交付包复制到另一目录导入空场景验证（clip 数、时长、接触时刻、零未加权顶点、贴图路径、抽样姿态最大偏差）；Unity 交接记录 loop 标志、Generic rig 预期、root-motion 政策、世界尺度、前向轴、事件时刻。
• 引擎交接：直立单位转身相位匹配标准档案为 30% 转身速度、0.55s 恢复、固定 2x 步伐、0.35s 缓出转身退出、0.35s Idle 沉降（Urs 档案，2026-09-18）；文中多处链接指向 projects/overlord/* 与 .claude/skills/blender-game-animation/SKILL.md（后者经 install_kit.ps1 由 dot-claude/ 安装后即存在）。

面向 YouTube 内容的风格化女性英雄角色概念流程：目的定义 → 2-3 个原型并行 → 参考锚点 → 每原型 3 条提示词 → 生成迭代 → 编辑提示词 → 终选；是概念探索文档，不是 3D 生产默认值。

• 七步管线：purpose → archetype（2-3 个方向并行）→ reference gathering（借能量不抄袭）→ 每原型 3 条变体提示词 → 生成+具体反馈迭代 → edit prompts 调姿势/配色/细节 → 终选。
• 全局提示词硬约束：`stylized 3D Unreal Engine 5 character render, non-photoreal, not live-action, not fashion photography, not cartoon`；`young adult woman, early-to-mid 20s`；`full body, full height character visible`；显式 60/30/10 色彩比例；材质按 3D 材料描述；质量锚 `collectible premium game heroine`。
• 五类常见修正循环：太写实→加 stylized UE5 语言与 slightly idealized proportions；太平淡→加叙事细节（疤、义肢、奖杯物）；像女巫/天使/机器人→显式否定；细节噪音→cleaner shape language；年龄跑偏→重新锚定年龄段。
• 反通用准则：设计里可见的故事 + 1-2 个签名元素 + 明确态度表情 + 带反差的熟原型（pirate+aristocrat、berserker+steampunk）。
• edit prompt 关键句式：always say 'keep the same silhouette / same outfit structure / same identity'，否则模型会重新发明角色。
• 文件自带的工具表写 ChatGPT canvas + Flux (via Banana) + Blender，但文件头部与 tools.md 都声明这些是概念探索默认值、Flux-only 表已被替换；对 Oldcraft 的 12 种族/职业体型（男女双性别）简报，'年轻女性英雄、UE5 风格' 默认值不能直接套用。

2026-09-11 基于 Mariel Cartwright 的 GDC Skullgirls 谈话改编的润色阶段：在支撑力学与游戏事件时刻锁定后、最终烘焙前，提升普通游戏速度下动作的可读性与预备/释放/冲击对比。

• 前置条件：支撑机制和游戏事件时间已稳定；新动作先在目标控制器里用粗姿势试跑；对已批准动画保留基线快照，只改被要求的通道（curve path/component/keys/interpolation 指纹防误改动作库）。
• RTS 振幅规则（owner，2026-09-24）：动作幅度要在抬高视角的游戏相机、单位实际屏幕上可读；只在特写里可见的小动作不值得单独润色；先保证姿势区分度再协调腰、肩、头、手。
• §3 五量区分表：Authored poses and curves（运动形状）、Pose exposure（可读构型停留时长）、Timeline fps（帧秒换算）、Bake density（烘焙采样密度）、Game clock（输入/移动/接触/冷却/打断）；2D 例子里删冗余帧不是降低导出采样密度的指令；60fps 的一帧效果只有 30fps 一半时长。
• §5 冲击重音候选表：Stronger extremes、Drag、Smear、Impact enlargement、Overshoot；每项有实施候选与保留前检查；在我们的事件驱动近战里 overshoot 必须先做空间检查——尾刺/颌不得在伤害事件前视觉上穿过目标。
• 缩放要区分永久网格编辑与临时动画脉冲，测量评估后的结果而不是相乘 local scale；渲染器 bounds 必须包含放大后的轮廓；Scorpid 尾刺远端宽度约翻倍是一次性指定夸张，不是通用值。
• §6-7 恢复段要可用可打断，不拖长尾阻止下一条指令；Hitstop 是独立引擎呈现选择，RTS 多单位混战中全局冻结会破坏无关单位与指令响应，未经游戏设计方确定只是提案。
• §8 双评估都记录才接受：视觉评估（普通速度动作/方向/重量/时机对比/恢复更好）+ 技术评估（受保护通道、脚、IK、穿插、bounds、seam、scale reset、导入后动画无损）；几何改动后要检查所有使用该网格的 clip。

规定 Higgsfield 的两种执行界面（CLI 与 Blender 原生回调）如何发现状态、恢复任务、留存凭证，并列出观察到的模型 ID；强调不要把可用的 Blender 回调换成名字相似的 CLI 调用。

• 2026-09-15 审计：CLI 版本 1.1.24，live catalog 共 91 个模型；CLI 与 Blender 集成是不同执行上下文，模型名相似也不能互相替换。
• 只读检查命令：`higgsfield --version`、`higgsfield model list --json`、`higgsfield model get tripo_h3_1_image_to_3d --json`、`higgsfield workflow list --json`、`higgsfield generate list --size 50 --json`、`higgsfield generate get <job-id> --json`；授权新请求用 `generate create <job-type> ... --wait`，wait 超时不是失败，保留 job ID 用 `generate get` 或 `generate wait` 恢复，确认失败前不重复付费提交。
• 观察到的模型 ID：`gpt_image_2_5`、`gpt_image_2`、`grok_image_2_0`、`nano_banana_flash`、`seedance_2_5`、`minimax_h3_max`、`tripo_h3_1_image_to_3d`——是观察值不是通用默认；原生 Tripo H3.1 路线与通用 `tripo_3d`、`multi_image_to_3d` 路线不同。
• 凭证纪律：保存 provider、精确模型/job 类型、request ID、请求输入、本地输出路径与观察状态；远程链接不是持久资产必须下载；估算 credits 与实际账单是两种记录；私有收据与可分享示例分离。
• 禁止把编号历史构建脚本对着已完成的 Blender 场景重跑（可能重新提交新 job 或依赖中间检查点）。
• 换机器：`higgsfield auth login` 用接收者自己的账号认证，Blender companion 单独安装；文中引用的 [MCP setup](../project-mcp.md) 在 kit 的 processes/ 下不存在（断链）。

经 `scripts/image-gen/generate.py` 走 fal.ai 的批量参考图迭代流程：对象规划→每对象 3 变体→HTML 报告→owner 反馈循环→终稿入 data/final/，含命名规范与 edit 工作流。

• 四阶段管线：对象规划以 HTML 报告提案并暂停等 owner 批准；批量 5-7 个对象（上限 10，再多上下文退化）；每对象 3 条 A/B/C 变体（不多不少）；HTML 报告是唯一评审界面。
• 端点表：默认生成 `fal-ai/nano-banana-2`；编辑 `fal-ai/nano-banana-2/edit`（用 `image_urls` 复数数组）；高质量 `fal-ai/nano-banana-pro`；抠图 `fal-ai/imageutils/rembg`。
• 硬规则：始终并行 `--workers 5` 起步绝不串行；3D 参考图默认纯中灰背景；结果必须保存远程 URL 到 results.json 供 edit 流程复用；报告登记进 workspace/workspace.json 的 Workspace 卡片。
• 命名规范：迭代图 `{object_id}_{variant}.png`、终稿 `{object_id}_final.png`（如 speedboat_final.png）、运行目录 `data/run_YYYYMMDD_HHMMSS/`；终稿统一放 `scripts/image-gen/data/final/`。
• Edit 工作流四步：`fal_client.upload_file()` 上传源图 → 调 `fal-ai/nano-banana-2/edit` 带 `image_urls:[uploaded_url]` → 报告里前后对比 → 可选 rembg 收尾。
• 术语区分：A-pose 是标准绑定期姿势（双臂离体 30 度），与提示词变体 A/B/C 无关；文件头提醒 generate.py 仍保留 Nano Banana 2 的遗留默认值，必须显式传 `--model`，且该默认端点不在 TASK.md §15 表内。

针对 3D-ready 图像的提示词知识库：风格锚定、60/30/10 色彩、材质语言、剪影可读性、角色/道具分型提示词与常见修正对照表。

• 风格锚定必须放在提示词前部防漂移：`stylized 3D Unreal Engine 5 render, non-photoreal, not live-action, not cartoon` + `premium game-asset quality, collectible feel`；没有锚定模型会倒向写实或库存照片审美。
• 色彩控制显式写 60/30/10 比例并带具体材质（例 `60% matte black steel, 30% aged bronze plates, 10% glowing cyan core`）；材质用 3D 材料名（brushed titanium、scarred leather、emissive crystal inlays）而不是 shiny/rough/colorful。
• 3D 参考背景默认 `solid uniform medium gray background`——不用白（过亮）、不用黑（吞剪影边缘）、不用纹理。
• A-pose 标准描述：`standing straight facing camera directly, arms held at 30 degrees from the body, palms facing down, feet shoulder-width apart`，是绑定期参考姿势不是动作姿势；turnaround 用 `character turnaround sheet, front / side / back views on neutral background`。
• 角色防飘条款：`standing on solid ground, feet touching a flat surface`（防浮空）、给手具体任务（防浮手）、指定表情态度而非 neutral。
• 道具分三型：high-poly（micro-scratches/engravings，为烘焙供细节）、low-poly game-ready（clean geometric forms，作为拓扑参考）、simple objects；turnaround 加 top 视图，需要尺度感时 `placed next to a hand for scale`。
• 常见修正对照表覆盖：太写实、太卡通、太平淡、过度设计、浮空、相机角度错、手部错误、色彩浑浊 8 类问题及对应措辞。

按『请求的输出』路由到正确入口与执行依赖的总地图，取代原 Flux-only 工具表；是 processes/3d-ai 其余文档与 .claude/skills 的索引。

• 九行路由表：概念图/忠实编辑 → image-generation.md + prompting.md（generate.py 走 fal.ai 或 Higgsfield）；中性角色 sheet 与部件 → .claude/skills/character-sheet-pipeline/SKILL.md；fal 生成/编辑/视频/材质/3D → .claude/skills/fal-ai-generation/SKILL.md（fal MCP + 便携 Python helper）；Blender 内生成网格 → higgsfield-cli.md；程序化 Three.js 重建 → .agents/skills/img2threejs/SKILL.md；材质与游戏网格烘焙 → knowledge/3d-gen-preferences.md；运动参考 → animation-reference-selection.md；可编辑绑定/动画/导出 → .claude/skills/blender-game-animation/SKILL.md；YouTube 缩略图 → thumbnail-concepts skill。
• task-specific defaults：编辑以已批准图为权威、额外风格语言会重新设计它；8 月模型轮换不覆盖更新的任务选择；parts sheet 保持 strict-front 中性光，hero 相机不适合提取或 mocap。
• 明确警告：`generate.py` 有遗留 Nano Banana 2 默认参数必须显式 `--model`；Tripo 网格生成、Meshy 重打图、Patina 材质创建是三个独立操作；生成的高模不会自动等于游戏网格。
• 交付声明纪律：人体视频转换成功不等于动作捕捉成功（human video transfer does not prove successful motion capture）。
• 每次 API 请求前先读本地任务清单，保留精确 provider/model/request ID，超时后恢复既有 job，输出与 Workspace 卡片一起下载；引用的 `.agents/skills/img2threejs/SKILL.md` 在本 kit 中不存在（断链），`.claude/skills/*` 路径在安装后由 dot-claude/ 映射产生、有效。

owner 2026-09-15 设定的默认：新生成/下载的视频经保守 H.264 重压缩后轻量存储并出具收据，避免 provider 原片与多份大副本长期堆积。

• 标准命令：下载关闭后运行 `python scripts/workspace_video_optimize.py path/to/video.mp4 --apply --allow-new`（已有文件夹可省 `--allow-new`；不带 `--apply` 仅清点）；API 入口 `optimize_file(path, report_dir=None, allow_new=False)` 返回英文 JSON 收据。
• 编码参数：保守 H.264、CRF 20、slow preset、原分辨率/像素格式/帧时序、音频直拷、faststart；预览衍生品才允许 H.264 960px / CRF 23。
• 替换门槛：完整输出至少省 15%，且三组一秒 SSIM 抽样均 ≥0.985，候选全解码验证后才原子替换；收据必须区分 `providerOriginalSha256` 与 `storedSha256`，不得把旧源哈希改写成原片从未存在。
• 保护名单：Overlord Blog 档案（devlog/archive，Git LFS）、发布/导出母版、Unity/运行时导出、alpha、HDR、高位深、多轨道媒体；已高效的 HEVC 下载与紧凑预览保留原样是优化结果不是失败。
• 安全边界：除非显式给路径绝不扫描 Downloads/inbox；批量传 `--apply --workers 2`，跳过 2 分钟内修改过的文件，`--exclude` 排除活跃生产目录；物理路径去重处理 workspace/overlord 与 projects/overlord junction；不做递归删除、不进 Unity 工程目录。
• 陷阱：kit 的 scripts/ 下实际没有 workspace_video_optimize.py（只有 3d/capture/image-gen/animation/refs 五个子目录），也没有 workspace/ 目录与 workspace.json——该脚本与其维护报告在本 kit 中缺失，Oldcraft 项目若要用需自行补齐或忽略。

把 2026-09-09 owner 批准的 Wild Wolf 整条 Blender 动画制作过程固化为可复用知识的总索引:十步成功序列、四剪辑交付契约、脚本快照地图与验证证据清单。

• 十步成功序列:检查 GLB+四段 24fps 视频参考并抽 contact sheet → 保留 UV 焊接重合缝几何 → 布骨架+自动权重 → 加 paw IK/pole 控制/hock helper/身体-下颌-尾控制 → 从视频重建完整 Idle/Run/Attack/Death → 修复 Run 循环约 14-16 帧的后腿折叠 → 加前后脚时序、躯干弹簧传导、头部补偿、尾部延迟 → 自动范围/fps 选择与原生分剪辑播放场景 → 把作者动作烘焙到 28 根运行骨骼 @30fps → 复制目录重导入做纹理/权重/时序验证。
• 四剪辑引擎契约:wolf_idle 2.5s(0-75@30fps)、wolf_walk 0.833333s(实为 run loop,项目命名约定)、wolf_attack_c39 1.7s(咬合接触在相对 f39/1.3s,一次性、首尾姿态一致)、wolf_death 1.333333s(一次性、保持终帧)。
• 最终资产事实:17,835 三角面、9,209 焊接顶点、1 材质、4096×4096 base-color JPEG;作者 rig 38 骨,导出 rig 28 骨、无运行期约束、Root 静止;皮肤归一化、≤4 影响、零未加权顶点、零跨腿泄漏。
• evidence/scripts/ 声称保留 19 个生产脚本的逐字节快照(8 个阶段:参考检查/导入解剖/权重细化/控制与动作/修订 QA/游戏变体/播放/烘焙导出/导出比对),配 evidence/provenance.json 的 SHA-256;但文档自己声明这不是单命令可重跑的流水线——依赖 wolf 专属坐标、中间 NPZ、旧版动作计数,以及本地 NumPy/SciPy/OpenCV/FFmpeg。
• 迁移重导入验证:FBX 与 GLB 两种格式各 21 个评估采样点与批准源在 0.000001m 内一致;FBX 从复制目录解析外部纹理,GLB 内嵌保留。
• 后续引擎线:2026-09-09 起把 FBX 导入可玩 Wild Wolf prefab,实现 UnitAnimationSet/UnitAnimationPlayer 与编辑模式预览;2026-09-10 owner 批准九剪辑组合作为未来地面四足动物的基线,58 条运行时断言通过。
• 注意:文中引用的 evidence/、research/、build_report.py、../logs/*.html 在本 kit 中均不存在(实测目录缺失),仅文档随 kit 分发。

下一批角色动画开工前的入口文件:11 个单位的当前可编辑源与交付包索引表、批次重启检查清单、Set Pose 评审新标准、Dryad v12 状态,以及备份受阻等挂起事项。

• 11 单位可编辑源索引(路径在 <Overlord project>/ArtSource/Characters/):HumanArcher 与 Swordsman 各 14 剪辑;三具 Skeleton 的 Turning01 增量包各 6 剪辑(不替代攻击/死亡/Walk/Stun);Urs Classic/Pyro;General 14 core + 9 reserved(含 Stun,已导出,Unity 集成待办);Knight 11 core + 6 reserved(OwnerUpdate02 长矛,需 Unity 重导入);WildWolf Turn90_Final01;WarScorpid v06。
• 9-20 追加:owner 批准 General 的 Set Pose 工作流——可直接编辑的命名关节、道具独立调整、保存的剪辑/帧姿态参考、未触碰 Action 的恢复——并入每次动画评审标准,要求实测骨骼/网格在 timer tick 与重开后的真实运动。
• 9-24 追加:Dryad 修订 12,Dryad_Animations_v02.blend 内 Shield 掌指关节可见活动(HandIndex1/2 要看网格影响而非仅骨名),99 骨 rig 与皮肤不变;工具链 dryad_shield_hands12.py / ShieldHands.build() / shield_source12.json;下一任务是叶变种与 root-capture VFX(按 VFX Concepts V05)。
• 失败/受阻记录:GitHub LFS 容量耗尽导致 Overlord 远程备份上传被拒,远端备份挂起;指示恢复容量后重试、不得绕过 LFS;文件仅存本地+本地 Git。
• 五个单位的 Unity 转向迁移归属另一个 agent;只读检查发现旧五单位绑定尚未配置新的 travel/phase 表;Classic/Pyro 已有 runtime foot-phase 匹配和 0.35 秒 eased 转场停止混合;Ursa 后续 blend 细化仍待引擎内视觉评审。
• 批次检查清单核心:切文件前保存恢复检查点并检查实时未保存权重/姿态;先批 Run 再派生变体;攻击需要自己的 ready 姿态而非从远处 Idle 滑入;实验分支批准前隔离;历史 setup 脚本可能覆盖已修正的权重或 Actions,复用前必须读输入与阶段依赖。
• 明确要求:交付必须保存可用 Material Preview 与普通 Action/Space 播放,直接在 Blender 里评审,不做自动评审视频画廊;source 批准、导出验证、引擎集成三种状态分开记录,不得从知识检查点推断新批准。

2026-09-10 owner 批准的 Wolf rev07 九剪辑组合,作为所有『转向跟随朝向』的地面四足动物的动画与控制器契约:clip 组成、planted turn 与 heading 曲线的数学约定、验收标准。

• 九剪辑基线:Idle、Run、Attack、Death、Walk、Turn Left/Right、Run Turn Left/Right;Walk 必须是单独授权的四拍步态(逐爪依次落地、重心转移),明文禁止把 gallop 放慢来假装走路;strafe(侧移)是独立行为,四足不默认需要。
• planted turn 契约(狼):一步 45 度/30 帧间隔 @30fps = 1 秒,与 Idle 入场姿态无缝;按外部旋转编舞,交付角度、时长与采样 heading 曲线,控制器按曲线相邻差分逐帧施加——本地姿态配无关恒定旋转会滑步,若再把 root yaw 加进动画会转两次;45 度步进不要默认换成双倍 90 度剪辑。
• 步幅驱动:Walk 交付每完整周期的源米位移与源-世界尺度声明,归一化相位按 实际位移/世界步幅 推进,播放速度 = 世界速度 ÷ (worldStride/clipDuration);Run turn 交付带符号角/周期、步幅、参考半径(stride/angleRadians),与直行 Run 共享一个归一化相位。
• 坐标系陷阱:狼作者文件 -Y forward/Z up,左转 = 正 Blender Z 旋转;Unity +Z forward/Y up 左转 = 负 yaw;manifest 必须显式给出两种符号。
• rev06→rev07 失败教训:run bank 的 roll 符号在代码里看似合理实际朝转弯外侧倾,rev07 修正并测量;验收要求按几何判定向解剖内侧倾斜,并测量变形后的脚底而非控制原点。
• 9-11 控制器修订:从静止起步的 Move 曾要等满 1 秒 planted turn,响应性差——改为加速中朝路线转向+反转时非零速度地板;运行转向 1.5x 权重增益 + 0.075s 平滑让躯干弯曲更可见,姿态仍钳制在授权 pose 上;此修订当时仍待自己的视觉 chat 批准。
• 边界声明:批准的 2m gallop 步幅与巡逻速度是 Wolf 的艺术校准,不推出『无滑步世界接触』或通用速度规则;慢速巡逻速度从未被选定;静态跑步机预览不能证明世界空间接触锁定。
• Wolf 兼容命名:已有 wolf_walk 是批准的 gallop(游戏在用,保留),新增 wolf_walk_slow 与四个 turn 剪辑;加入剪辑本身不等于接入 UnitAnimationSet/UnitAnimationPlayer/巡逻行为。

2026-09-11 应 owner 要求对 GDC 2014 动画训练营演讲《Making Fluid and Powerful Animations For Skullgirls》(21:06)做的带时间戳分析,并推导出 3D/RTS 适配的『美学打磨 pass』。

• 方法:完整英文自动字幕 + 42 张概览帧 + 三段演示的 48 个连续采样;明确声明是转述分析非逐字稿,且 30fps 录像无法展现其讨论的 60fps 游戏每一帧;源记录在 research/skullgirls/source-review.json(kit 内不存在)。
• 12 条带时间戳原则:可读剪影(01:51)、预动/telegraph 区分玩家响应与敌人前摇(02:25)、重关键姿态优先于均匀中间帧(03:50)、follow-through(04:38)、smear(05:37)、短 overshoot(06:33)、夸张中间形变传达拖拽与重量(07:48)、粗动画先进游戏测(09:43)、不均等的姿态驻留(11:30)、hitstop 属运行期行为(12:46)、Idle 周围过多 easing 削弱响应(13:13)、冗余中间帧导致失重(15:20)。
• 流程变化:新增 processes/3d-ai/game-animation-polish.md 打磨 pass,排在时序与支撑稳定之后;把『动作是否从游戏相机读得清、有力』的艺术判断与既有技术验证(rig 稳定、接地、事件时序、导出保真)分开评估。
• Scorpid 适配实验边界:保持批准节奏 1.6s、接触在 48 间隔的第 37 帧、预紧 ≤14、释放 31;实测 stinger 接触时远端宽度为放大基底的约 2.05–2.09 倍、第 40 帧恢复中性尺度。
• 技术依赖教训:为保留全部 Death 曲线,加宽的 stinger 一度穿地;微调一个远端关节恢复离地间隙且保留倒地通道——从此任何网格编辑都要触发全剪辑库的表面间隙检查(death_geometry_clearance_06.json)。
• 红线:overshoot 不得让 stinger 在伤害事件前视觉上穿过目标;sprite 张数、曝光、Blender key、烘焙密度是不同东西,删帧会缩短时长;hitstop 仅作可选引擎实验(全局冻结不是多单位 RTS 的默认);2 倍缩放脉冲是 Scorpid 专属选择,不得变成通用乘数或强加于平静运动。
• 结果状态:新工作流已含命名打磨 pass、早期可玩 blocking 检查、游戏相机对比、艺术/技术分离评估;但该 pass 尚未做任何端到端生产试验,本研究不批准也不修改任何新剪辑。

把 Urs 批准的『90 度两步转向』方法推广到 Human Archer、Swordsman 与三具骷髅共 10 条 Idle Turn 剪辑的源/导出交接:时序契约、controller_motion 侧车格式、Unity 接收方步骤与验证数字。

• 范围:5 角色 × 左/右 = 10 条 90 度非循环一次性转向全部修订并导出验证;人类包为完整 14 剪辑库,骷髅 FBX 保留 6 剪辑增量(Idle、Run、Run Turn L/R、Idle Turn L/R);其余动作、几何、UV、权重、材质字节保留。9-19 更新:五个 Unity 资产已用这些导出+rig 专属相位表+用户批准的 Urs 完整转向配置,但最终游戏内视觉批准仍待办。
• 时序契约:0–45 帧 @30fps = 1.5s(沿用原节奏);领先脚 6.5625 抬起、21.5625 落地,后脚保持支撑到 27.1875、40.3125 落地,45 帧 settle;胸部到首次落地已转约 83.37 度而骨盆-胸部朝向保持单调。
• 两步转向刻意含模型空间后退 0.244–0.285m 与首次落地踝间距 0.367–0.463m(五个角色逐一列表);两端点匹配原本地 ready 姿态,世界后退是有意为之,预览循环重置原点,因此不是无缝位移循环。
• 侧车格式:controller_motion.json 沿用 Urs 字段名——每剪辑有 yaw_degrees_unity、position_x_blender、position_y_blender;193 个均匀采样,间隔 0.234375 帧,跨 45 帧;必须用声明间距或归一化相位,不能套用 Urs 的四分之一帧常量;用 controller_motion_sha256 校验。
• Unity 侧要求:Generic FBX、root motion 关、初始不简化曲线、人类源保留全部 6 影响;源 -Y forward/Z up,Blender (X,Y,Z) → Unity (-X,Z,-Y),按 prefab 基精确映射并只施加一次 visual scale;纯预览按 1x 完整施加授权 yaw+位移,游戏保持固定 2x 步法(完整源步 0.75s)+独立朝向+随时打断;不得为外观后退移动 NavMeshAgent/collider。
• 转出场相位匹配不在本任务配置:Unity 重导入时按 mixamorig:Hips/LeftFoot/RightFoot/LeftLeg/RightLeg 逐 rig 烘焙已批准的 Run/Walk 腿姿态表(UnitLocomotionPhaseBaker 与 Urs installer 是既有实现),不得自动照抄 Urs 的移动/blend 值。
• 验证数字:10 条转向各过 365 采样(含分数支撑事件);完整授权预览中支撑踝最大水平漂移 <0.011mm;各包复制重导入最差顶点差 0.222–0.415mm(Human Archer 985 姿态 0.415mm … Skeleton Archer 422 姿态 0.222mm)。
• 复现工具:AnimationTurning/Tools/ 下 roster_turn90_common/author/validate/promote/export/playback 六个脚本,动作构建器复用 Characters/Urs/Tools/turn90_02_motion.py(按角色缩放、保留 45 帧时长);Blender 后台 --python export_roster_turn90.py -- <prefix> 可重导出;引擎副本在 ArtSource/AnimationTurning/RosterTurn90_01/HANDOFF.md。

owner 批准的狼 90 度左/右转向补充包(Export/Turn90_01/)的绑定与集成交接:两剪辑契约、Generic/Copy-From-Avatar 绑定步骤、heading 曲线施加规则、交付验证与未完成的 gameplay 工作。

• 包内容:仅两条静止转向 wolf_turn_left/right(0–54 @30fps = 恰 1.8s,Unity yaw 0→∓90°,loop 关);九剪辑基线仍在 Export/Locomotion_07/,明令不得用这个两剪辑 FBX 覆盖基线包;需作为独立补充动画模型导入并只替换 animation set 里的 turnLeft/turnRight。
• 烘焙密度:骨骼姿态每四分之一帧烘焙(120 采样/秒)以保住帧间 IK 爪路径,每剪辑 217 个姿态采样、无重定时;Blender FBX 重导入显示 1–55、glTF 显示 0–54——必须核对 1.8 秒时长而不是照抄导入器的帧起点。
• 绑定:Generic + Copy From Other Avatar 用现有 Wolf Avatar(Wolf.fbx,GUID ed6ca0f85fd4e63439c115db5d6e2d75,Avatar fileID 9000000),28 骨名称/层级/rest 矩阵与 v07 baked 模型完全一致;关压缩与关键帧缩减、resampleCurves=false 保分数帧;用 unity_turn_curves.json 替换 yaw 曲线,键时间是归一化相位 sampleIndex/54(不是秒),旧 ±45° 曲线绝不能留在新对上。
• 关键陷阱:保存的 Wolf 动画集 usePlantedTurns 默认 false——只导入/重绑剪辑不会让转向进 gameplay;共享控制器用 405°/s 导航朝向 + 固定 2x 播放,此时长实际只有 0.9 秒,turnPlaybackSpeed 只用于独立预览;授权 heading 故意未烤进 FBX/GLB,施加必须恰好一次,独立-yaw 玩法被打断时可能滑步。
• 交接时的 Wolf balance 快照(只读、未改):移动 4.4 m/s、转向倍率 0.2、转向恢复 0s、Run 步幅 2m、Walk 步幅 0.68m、Walk 阈值 1.4 m/s。
• 验证交付:两格式各 434 个四分之一帧姿态与最新作者网格最大表面误差 <0.000001m;2 剪辑/28 骨/1 蒙皮网格/17,835 三角面/1 材质;无控制/pole/helper 骨、零未加权顶点、≤4 影响、Root 与 armature 静止;唯一贴图为 Textures/Wolf_BaseColor.jpg 4096×4096。这些全是 Blender/导出侧检查,Unity 导入与 gameplay 评审在交接时仍未完成。
• 四足相位匹配警告:现有直立 LegPose helper 只表示两脚两膝,对四条腿不完整;评审要覆盖双向、反转、连续下令、Stop/Hold、攻击/死亡打断、转向退出到 Idle/Run/Walk。
• 复现:作者文件 Wolf_Turn90_Final01.blend(含全 heading 预览)+ 烘焙版 Wolf_Turn90_Final01_Game.blend + Source/Animation/turn90_01.json + Tools/turn90_01/export_turns.py 与 validate_export.py/check_saved_blends.py;游戏根目录 python ArtSource/Tools/character.py export wild_wolf 可再导出。