设计决策台账 · 《岁月·Jianghu》门派改造（殖民地模拟）

维护规则：每个需要人拍板的问题，先落「待确认」；确认后改成「已确认」。 「默认·可推翻」表示助理替你选了默认值 —— 真正要动它之前必须再确认一次。 总方案见 docs/参考-了不起的修仙模拟器-拆解与门派改造方案.md（下称「方案」）。

最后更新：2026-09-28　当前里程碑：批 9 收口 ✅ —— 开局空场地 + 采集/建造表现层（D-021~D-024；selftest 1067/0 · colony 探针 10/10 · 门禁全过）

一、已确认

批 18 收口记录（2026-09-29）· 动作库与骨骼动画上线

批 18b · 关键点中文名 + 选中半透明 + 未绑定编辑态（2026-09-29 · 用户三条追问）

批 18c · 动作关键帧编辑浮窗（12 帧/秒）+ 动作列表中文名（2026-09-29 · 用户四条）

批 18d · 关键帧控制条改为内联（撤掉浮窗）（2026-09-29 · 用户拍板）

用户原话：「因为很多按钮是重复的，所以我们不需要使用单独的浮窗，而是直接在原有的 3D 编辑界面下方，增加关键帧控制与编辑的功能」； 「其他在关键帧上对骨骼关键点进行的操作，都与原来一样，直接复用原有功能」。

批 18e · 关键点可位移（XYZ），不再只有旋转（2026-09-29 · 用户）

用户原话：「编辑动作时，选中关键点后，应该不光只有旋转操作，还有在 XYZ 轴上的移动操作。」

D-007 完整材料链（详细）

• 问题：方案 materials.json 列布匹/铁锭/寒玉等 6 材质，与拍板 4「经济不翻新（银两+6 资源+玉石=7）」存在张力，账目口径怎么定？
• 选项：A 材质当字典、账不翻新（7 种）/ B 完整材料链（9-10 种）（推荐当时未标，用户选 B）/ C 折中加布匹
• 结论：选 B —— 新增 4 种资源：jade 玉石、cloth 布匹、iron_bar 铁锭、cold_jade 寒玉，资源总数 6+4=10；熔炉做「铁矿→铁锭」，织机做「布匹→衣物（装备）」，布匹由棉花田产出；寒玉由玉脉稀有产出。
• 为什么重要：配方表、采集产物、库存面板、数据体检、账目容量全部按 10 资源写；中途换口径=配方与存档返工。
• 影响面：game/data/resources.json、materials.json（新）、recipes.json（新）、colony_balance.json、web/backend/gamenet/core/systems.py（ResourceSystem 容量）、engine.py（RESOURCE_CN 等资源名映射）、hud.js 库存面板。
• 状态：已确认　确认人：用户　日期：2026-09-27

D-008 旧 craft 退役（详细）

• 问题：旧系统「铁匠铺点一下扣银两+铁矿立即出装备」（craft 指令，挂旧建筑 effect_of("craft")）与批 4 打造台（Job 化：运料+工时+品质 roll+5% 神兵）的关系？
• 选项：A 批 4 直接退役（推荐）/ B 并存到批 8 / C 改加急令
• 结论：选 A —— 删 craft 指令与处理器及 EquipmentSystem.craft 的指令层调用；新手引导「锋刃初成」判据是 crafted 事件前缀，打造台出货沿用同名事件，tutorial.json 零改动；selftest 旧打造断言段随批 4 清算（批 2b 同款手术）。
• 影响面：engine.py 指令表与 _cmd_craft、core/systems.py、selftest.py 打造段（约 924-960 行一带）、存量「铁匠铺」楼失去 craft 效果（楼本体按「既有设施」保留）。
• 状态：已确认　确认人：用户　日期：2026-09-27

D-009 资源撒点（详细）

• 问题：门派内可Gather怎么落到 3D 场景，现有装饰植被怎么处置？
• 选项：A 独立资源实体+装饰不动（推荐）/ B 现有植被直接变资源 / C 双轨
• 结论：选 A —— 固定 seed 程序化撒点树/岩体/铁矿脉/玉脉/药草丛/浆果丛；资源实体是殖民地实体（进存档、可被砍采消失、树留桩缓慢复生）；装饰植被（scenery）永不响应采集指令。
• 影响面：colony/worksites.py（新）、colony/grid.py（占位）、world.js（资源渲染+高亮）、scene.py（不动）。
• 状态：已确认　确认人：用户　日期：2026-09-27

D-010 生产技能字段（详细）

• 问题：品质 roll 与工时公式的「技能加成」拿什么当工匠水平？
• 选项：A 现有等级+资质 / B 新增生产技能字段 / C 批 4 不加技能项
• 结论：选 B —— Character 新增 craft_skill（生产技能，初始按资质档给底子），干生产/打造活涨经验，技能喂品质 roll 与工时加成；批 5 日程/工作表、弟子卡面板跟进展示。
• 影响面：core/models.py Character 列与存档迁移、colony/worksites.py、colony_balance.json（技能成长曲线）、selftest 数值段。
• 状态：已确认　确认人：用户　日期：2026-09-27

D-011 家具/墙件建造语义（详细）

• 问题：完整材料链下，工台产出与批 2 已交付的「直接扣原材料建造」怎么衔接？
• 选项：A 批 4 维持直接建造、成品化缓批 5/6（推荐）/ B 批 4 一步到位成品化 / C 只家具成品化
• 结论：选 A —— 批 4 上线的产出台为五座：熔炉（铁矿→铁锭）、织机（布匹→衣物装备）、灶台（批 3 简版炊事升级为配方队列）、药炉（herb→丹药）、打造台（铁锭+玉石/寒玉→兵器装备）。木工台/石匠台建筑可建但批 4 不上配方，配方随成品化批次一起落地（推论，不再单独确认）。
• 影响面：recipes.json 配方清单、worksites.py 产出台注册、批 2 已交付的建造流/房间品阶/selftest/探针零改动。
• 状态：已确认　确认人：用户　日期：2026-09-27

D-012 丹药账目（详细）

• 问题：项目没有物品/背包系统，丹药存哪、怎么用？
• 选项：A 囤积计数 colony.pills + 首批两种丹（推荐）/ B 药炉批 4 不开工
• 结论：选 A —— colony.pills = {pill_id: count}；药炉产出落地堆（丹药丸），搬运回仓库入 pills 账；辟谷丹在弟子卡手动使用（饱食 +60，一天最多一粒）；大还丹批 7 战后疗伤消费。首批配方：大还丹（herb×4）、辟谷丹（herb×3+food×2）。
• 影响面：colony/worksites.py、colony_balance.json（丹药参数）、hud.js 弟子卡用丹按钮、engine 用丹指令。
• 状态：已确认　确认人：用户　日期：2026-09-27

D-016 断言外置（详细）

• 规则原文（老大 2026-09-27）：「断言不要留在代码内，特别是前端代码，断言应该写在一个和代码同名的专用断言 json 文件中，代码内只保留断言的编号，具体断言都在 json 中保存，发布时不会把断言发布。」
• 落地结构：
• web/tools/_assert_ledger.cjs —— 共享求值器：loadAsserts(探针名) 读同名 JSON（缺文件即抛错，不许静默空）、evalAssert(条目, ctx) 求值（声明式 check: {path, op, value} 13 种操作符 + fn 具名函数逃生口）、pickPath 点路径取值。
• 断言 JSON：{meta, asserts: [{id, name, check|fn, desc?}]} —— 人读的名称/期望/判据全在这；探针代码里只剩 check('A3 ' + A.A3.name, ...) 这类编号引用。
• 范围口径（用户确认）：1 批4 三探针立即迁移；存量 176 探针渐进（谁触碰谁迁移）；2 后端 selftest.py 暂不外置。
• 影响面：web/tools/_assert_ledger.cjs、三份 .assert.json、probe_colony_day/produce/forge.cjs；后续新探针一律两件套。
• 状态：已确认　确认人：用户　日期：2026-09-27

D-013 探针并行度上限（详细）

• 问题：探针并行跑多少合适？
• 结论演变：先拍「最多 3 个」（2026-09-27 上午）→ colony 组回归实测 6 探针并行（jobs=3）全部 bootstrap 超时（90s 没等到 HUD 揭幕，含批 1/2 存量绿探针）→ 二次拍板：一次只跑一个探针（并发=1，严格串行）。
• 落地：run_parallel.cjs 的 JOBS_CAP=1，默认值与显式 --jobs 一律钳到 1；并行骨架保留（兼容既有调用），实际效果 = 按序串行。
• 为什么重要：探针的 Chromium 是软渲染 CPU 密集型，且每个探针冷启动一个完整世界；并发注册/装配会互相挤垮。「假红比慢更费人」。
• 影响面：web/tools/run_parallel.cjs（默认值 / fallback / 解析后钳制 / 头注释）。
• 状态：已确认　确认人：用户　日期：2026-09-27（当日二次修订）

D-021~D-024 详细（2026-09-28 一轮拍板）

D-021 开局空场地（详细）

• 问题：开局是否还有城墙/山门/大殿/河道/铺装/地砖？清空到哪一层？
• 选项：A 分两批（表现先清、边界后动）/ B 一批全做 / C 只清表现层（后端边界隐式保留）。
• 结论：选 B —— 开局场景为空地（草/树/岩/矿脉/草丛 + 资源实体），城墙/山门/大殿/河道/铺装/地砖全部不预建；四类改为玩家可建/可铺：
• 城墙 → 已有结构件（v2_wall_wood/stone/jade）拖画；
• 山门 → 可建蓝图（bld_shanmen_01.glb），不再「骑墙」；
• 大殿 → 可建蓝图（bld_dadian_01.glb），恒 1 级语义改为「第一座大殿即门派等级 1」；
• 河道 → 可铺地块（env_hedao_01.glb / 浅滩 env_qiantan_01.glb），不再是静态地形。
• 玩法层边界改为按已建结构动态派生（这是 B 的核心工作量）：格网障碍 = 已建结构/建筑/资源实体（删静态墙带与河道洞）；放置边界 = 营地范围矩形（不再有墙内/墙外两套）；敌袭攻墙目标 = 最近的已建墙段（无墙段则直接结算、不拆墙）；走镖/采集队卸货点 = 仓库 → 大殿 → 营地中心三级兜底（山门不再是必经入口）。
• 影响面：scene.py（scene_manifest/放置常量/骑墙逻辑）、colony/grid.py、colony/raids.py、colony/jobs.py（storage_anchor）、engine._deliver_cargo、colony/worksites.py、buildings_v2.json、web/frontend/src/scene/world.js（出生点/镜头）、存量探针与 selftest 断言（城墙 39 段、placement bounds、卸货点、攻墙）。
• 状态：已确认　确认人：用户　日期：2026-09-28

D-022 门人动作（详细）

• 问题：门人「去砍/去采/搬运/施工」的动作过程怎么做？前端现在没有任何骨骼动画系统（全项目 0 处 AnimationMixer），12 个门人模型无动画轨道。
• 选项：A 程序化 + 并行骨骼 / B 只程序化 / C 直接上骨骼。
• 结论：选 A —— 本批先做程序化动作层（挥砍往复 / 弯腰采集 / 托举搬运 / 锤击施工 / 走路起伏 + 采集与施工进度环），当天可见、零新资产；同时用内置 Blender 4.5.14（vendor/blender）给弟子/杂役等模型绑定并产出 walk / chop / carry 三套动画，前端动作接口按 AnimationMixer 语义设计 —— 模型带动画轨道时自动切骨骼播放，无动画时退程序化动作，后续替换不需改调用点。
• 影响面：web/frontend/src/scene/world.js（门人对象与 actor 状态机）、新增动作模块、rig-forge/（绑定与导出）、作品内动作与后端 colony.workers.job.kind 的映射。
• 状态：已确认　确认人：用户　日期：2026-09-28

D-023 模型产出节奏（详细）

• 问题：材料堆模型与结构件模型什么时候到位？
• 选项：A 灰盒先行 + 并行投产 / B 等正式模型 / C 只产材料堆。
• 结论：选 A ——
• 资源本体：立刻换用库内 dec_*（松/柳/竹/石/草/假山… 21 件），不再是灰盒几何；
• 材料落地堆：先程序化低模（原木堆/石堆/铁锭/玉料/药材捆/浆果筐/布匹卷/粮袋…），保证「资源消失→原地出现材料」闭环；
• 正式模型：按 docs/资产台账.md 立候选单，走 asset-forge（混元 3D / Hyper3D → inbox）→ Blender 规整 → GLB，按既有「候选-Review-替换」纪律分批替换 buildings_v2.json 的 model 字段与堆模型表。
• 影响面：web/backend/gamenet/scene.py（资源/堆 model 映射）、colony.js 渲染、game/assets/models/、buildings_v2.json、docs/资产台账.md。
• 状态：已确认　确认人：用户　日期：2026-09-28

D-024 秒级结算（详细）

• 问题：「每格 2 秒」怎么落地？现状 seconds_per_tick=4、1 工时 = 1 弟子 1 tick、施工每 tick 结算一次（build_work_per_tick=1.0），木地板 0.5 工时实际也是 4 秒。
• 选项：A 秒级结算 / B tick 改 1 秒 / C 改口径「2 工时≈4 秒」 / D 前端插值。
• 结论：选 A —— tick 仍 4 秒（世界节奏、离线结算、敌袭节律全部不动），建造与采集的 Job 进度改为按 dt 连续推进：结构件 1 格 = 2 秒 × 人数系数（builders_per_site 上限 2 人时最快 1 秒/格），家具/建筑按 work_sec 计。采集工时由「工时」改为「秒」：树 8 / 岩 8 / 铁矿脉 12 / 玉脉 16 / 药草 4 / 浆果 3（colony_balance.gather_work 语义同步改秒）。进度条与门人动作因此可连续平滑。
• 影响面：colony/jobs.py（施工/采集/农田推进）、colony/worksites.py、game/data/colony_balance.json、buildings_v2.json（work_ticks → work_sec）、selftest [C9]/[C10] 数值段、colony 组探针。
• 状态：已确认　确认人：用户　日期：2026-09-28

批 9 验收记录（2026-09-28 收口）

批 9 适配修复（D-021 落地的连带）

1. colony/worksites.py ensure_nodes：山门/仓库锚点在空场地开局不存在 ⇒ 撒点避让失效、资源树撒进营地正中。兜底为格网中心（营地中心）留 6 米无树。
2. web/tools/probe_colony_forge.cjs buildBench：固定候选点会被资源实体占格驳回（后端权威驳回是对的）⇒ 改为逐候选点重试；且落点态是一次性的（colony.js 点击后即 cancelAll，无论后端接不接受）⇒ 每轮重试都重新开目录进落点态。修复后 forge 8/8 全过（A1~A8）。
3. selftest 多段断言随口径反向（旧口径「必须有 3 座 / 满铺石板」→ 新口径「必须零基建 / 一格不铺」），见 [3] / [11] / [C2] / [C3] 段注释。

批 9 补丁 · 采集链修复 + 资源/材料 hover tips（2026-09-28 晚，用户实测反馈）

批 10 · 界面精简 + 缺料卡（2026-09-29，用户四条拍板）

验收：selftest 1067/0 · pause 探针 10/0（新界面截图）· 四道门禁 ✅ · vite build ✅；缺料卡/横排图标截图见 render/_tmp_b10/。右上「工作/工坊/规划」三枚不在移除清单，保留。

批 11 · 蓝图目录正式模型（D-023 执行轮，2026-09-29 用户拍板）

• 需求原话：蓝图内的建筑和物品都没有对应模型；要 AI 脚本 + Blender 生成；模型别太简单；有合适的开源 Blender 模型库可以直接下载使用，没有合适的才自己生成。
• 优先级：1 下载合适开源件（许可必须可商用：CC0/CC-BY 注明出处）；2 bpy 脚本程序化生成（上质量：倒角/阵列/组合体，不上一步一个方块那种）。
• 管线：vendor/blender-4.5.14 无头跑 bpy 脚本 → 统一作品约定（原点居中落地、朝向 +Z、尺寸贴目录 footprint、顶点色/色板、GLB）→ game/assets/models/col_*.glb → buildings_v2.json model 字段替换 → 前端 colony.js 蓝图半透明/竣工不透明直接吃模型。

批 11 收口记录（2026-09-29）

批 12 · 资源全网聚簇分布（2026-09-29，用户三条）

实现：colony_balance 新增 node_biomes（每类簇数×簇大小）与 node_world_radius；worksites.ensure_nodes 改聚簇撒点（簇心最小间距 + 簇内高斯散布），node_counts 旧口径保留兜底。

批 12 收口记录（2026-09-29）

selftest 1067/0（撒点数断言改随 node_biomes 推导、阈值 0.45）· 门禁 ✅。连带修一个真 bug：rooms.compute_rooms 把 grid.blocked（含资源树）当房间屏障，密林会围出 20+ 间假「房间」—— 增设 grid.natural（资源实体格），房间屏障只认玩家建的结构与建筑。实测新档：98 株 / 半径 7.2~39.6 米满图、树 36 岩 19 铁 9 玉 2 药 16 果 16。老档不自动补撒（撒点一次性；要补撒另开一轮）。

批 13 · 墙/门/河道邻格自动转向（2026-09-29，用户拍板「方向自动合理调整，保证正确连接」）

• colony.js 新增 _buildStructIndex / _yawFor：每格朝向按全图墙/门/河道邻格计算（东西邻格 → 0°、仅南北 → 90°、角点取 0°；地板平铺件不参与索引，不带偏墙朝向）。
• 索引含所有笔画与蓝图 ⇒ 两段分开画的墙也能接上；签名（模型+格数+朝向串）变化即重建组。
• 验证：L 形木墙截图（render/_tmp_b13/lwall.png）横段沿 X、竖段自动 90°；门禁 ✅。已知取舍：角点用 0° 直角件（暂无专属转角模型，短边缺口由压顶宽度覆盖；后续可加 col_wall_corner 转角件）。

批 13b · 转角件（2026-09-29，紧随邻格转向）

• 补齐批13 的已知缺口：角点原来用直段，两条墙交汇处留半格豁口。
• Blender 新增 col_wallcorner_wood / stone / jade（L 形：+X 臂 + +Z 臂各半格 + 角心柱，31 件模型总量）。

批 18f · 修「关键帧编辑里点『移动』不生效」（2026-09-29 · 用户追问）

用户原话：「为什么在编辑动作时的关键点操作没有和编辑关键点的操作一样的移动控制方式？」

真因（实测出来的，不是猜的）：工具名两套写法对不上。

为什么之前的探针没抓到：它调的是 kfSetTool('translate')，绕开了真实按钮路径 —— 典型"探针验的链路 ≠ 用户点的路径"。本次探针改成点真实按钮，并加了一条"工具高亮必须与实际方式一致"的断言。

修法：

• viewer.setTool 归一化工具名（'move' → 'translate'），新增 toolMode()；入口只有这一处，_tool 从此只有一个口径。
• 新增 syncToolUI()：把当前方式同时点亮舞台工具行与控制条分段控件。之前程序调用 setTool（进关键帧编辑会自动切「旋转」）不会点亮按钮，UI 停在「环绕」亮着、实际却在旋转 —— 用户根本看不出现在能不能移动。
• 关键帧控制条里直接加「拖动：移动 / 旋转」分段控件（与 3D 左上角是同一份状态，互相回写高亮），不必再去上面找。