Rework story engine flow and reorganize project docs

docs/planning/CURRENT_GAME_ITERATION_PRIORITIES_2026-04-03.md

@@ -0,0 +1,283 @@
+# 当前游戏优先迭代清单（2026-04-03）
+
+## 结论先说
+
+当前阶段最不该做的，是继续零散加玩法、加场景、加文案，却让主链路、规则底座和工程门禁继续处在半完成状态。
+
+按现有文档和代码状态看，建议优先级顺序如下：
+
+1. `P0`：先恢复工程绿色基线，并把运行时主链路继续拆开
+2. `P1`：再落统一角色属性底座，作为战斗 / 对话 / 招募 / Build / 掉落 / 任务的共同语义基础
+3. `P1`：在统一属性底座之上，重做 Build、运行时物品奖励、任务系统三条核心玩法链
+4. `P2`：最后收尾编辑器共享层、本地 API 分层、移动端体验与运行时包体优化
+
+一句话判断：
+
+**现在的优先级不是“继续扩玩法宽度”，而是“先把底层规则、主流程边界和工程可维护性补齐，再扩玩法深度”。**
+
+---
+
+## 优先级清单
+
+## P0-1：恢复绿色基线，收紧质量门禁
+
+### 为什么必须排第一
+
+- `docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md` 已明确指出：当前最值得优先优化的不是继续加功能，而是把“半完成的工程化”补齐。
+- 文档中提到过 `lint` 失败、`build` warning、核心热区文件被 ESLint ignore、部分测试未进入默认套件，这意味着当前代码库还不在真正稳定的绿色基线。
+- 在这种状态下继续叠加新玩法，只会把问题扩散到更多运行时链路和编辑器链路。
+
+### 本阶段要做什么
+
+- 修复现有 `lint` / `build warning` / 明确可见的门禁破口
+- 缩小高风险核心文件的 ignore 范围
+- 让 `lint + typecheck + test + build + check:content` 成为可信的统一门禁
+- 对 warning 建立“尽快清零”策略，而不是长期带病开发
+
+### 做到什么算完成
+
+- 主开发分支长期保持 `npm run check` 可稳定通过
+- 核心运行时文件不再依赖长期 ignore 才能过门禁
+- 构建 warning 收敛到零或有非常明确的短期处理计划
+
+### 为什么它比新功能更优先
+
+- 没有绿色基线，后续所有大改都缺少可靠回归保护
+- 这一步是后面统一属性、任务重构、物品系统重构的前置条件
+
+---
+
+## P0-2：继续拆运行时主链路，防止核心 hook 和壳层继续膨胀
+
+### 为什么必须紧跟在 P0-1 后面
+
+- `docs/experience/PROJECT_DEVELOPMENT_EXPERIENCE.md`、`docs/experience/PROJECT_WORK_EXPERIENCE_PLAYBOOK.md`、`docs/experience/ADVENTURE_RUNTIME_DEV_EXPERIENCE.md` 都反复强调：这个项目是叙事、状态、演出、界面四条链路耦合的复合项目，不能靠大文件硬扛。
+- `docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md` 和 `docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md` 一致指出，`useStoryGeneration`、`useCombatFlow`、`GameShell` 仍然是当前最大的复杂度集中点。
+- 如果不先拆主链，后面的统一属性系统、任务系统、物品导演层都会继续堆进现有巨型流程控制器，技术债只会翻倍。
+
+### 本阶段要做什么
+
+- 把 `useStoryGeneration` 收敛为 orchestration 层，不再直接吞下 NPC、任务、背包、锻造、聊天、奖励等全部细节
+- 把 `useCombatFlow` 进一步拆成“战斗结算”与“播放/演出同步”
+- 让 `GameShell` 回到流程壳层职责，把 selection flow、overlay、scene transition 继续下沉
+
+### 做到什么算完成
+
+- 新功能接入时，不需要再跨 `story + combat + panel + modal` 四五层一起改
+- 核心流程可以按领域补测试，而不是只能做人工回归
+- 后续玩法扩展能优先加领域模块，而不是继续往大 hook 里塞逻辑
+
+### 这一项的实际意义
+
+- 这是“后续还能继续做大”的结构前提
+- 不做这一步，任何系统升级都会越来越难落地
+
+---
+
+## P1-1：落地统一角色属性系统，作为全玩法共同底座
+
+### 为什么它是最优先的玩法底座
+
+- `docs/prd/AI_NATIVE_UNIFIED_ROLE_ATTRIBUTE_SYSTEM_PRD_2026-04-02.md` 已经把问题说得很清楚：当前玩家、NPC、怪物、Build、对话、掉落还没有共享同一套解释坐标。
+- 当前项目已经有 NPC 关系、怪物标签、Build 语义、自定义世界生成能力，但这些系统之间还缺一套统一的世界级属性 schema。
+- 如果先做任务、物品、Build 深化，而不先统一属性，后面很容易再次出现“每个系统各自解释角色”的分裂。
+
+### 本阶段要做什么
+
+- 为预设世界固化世界级属性 schema
+- 为玩家角色、怪物、关键 NPC 补 `attributeProfile`
+- 建立统一的属性解析与校验层
+- 先让对话 / 招募 / 送礼 / 详情面板开始读取这套新属性解释
+
+### 做到什么算完成
+
+- 玩家、NPC、怪物都能落到同一套属性语义里
+- 聊天、送礼、招募至少有一条链可以直接解释到属性层
+- 自定义世界也能生成并持久化自己的属性 schema
+
+### 为什么这项优先于“多做内容”
+
+- 这是后面 Build、物品、任务三条系统统一升级的共同前提
+- 没有这层底座，玩法会继续“能跑，但彼此不共语义”
+
+---
+
+## P1-2：把 Build 系统从“标签互相影响”改成“标签匹配角色属性”
+
+### 为什么这里要尽快做
+
+- `docs/prd/BUILD_SYSTEM_ATTRIBUTE_SIMILARITY_PRD_2026-04-02.md` 指出：当前 Build 更像标签网络效应，解释成本高、平衡成本高、角色差异感不够强。
+- 一旦统一角色属性系统先落地，Build 就是最适合第二个接入的玩法层，因为它最直接影响战斗反馈和角色成长感。
+
+### 本阶段要做什么
+
+- 为 Build 标签补属性亲和度向量
+- 改写 `buildDamage` 逻辑，让每个标签独立匹配当前角色属性画像
+- 调整 Build 面板文案，从“标签协同”转成“属性适配度”
+
+### 做到什么算完成
+
+- 玩家能理解“为什么这个标签适合当前角色”
+- 新增标签只影响自身贡献，不再扰动整张标签网络
+- Build 面板能解释收益来自哪些属性
+
+### 实际收益
+
+- 提高可解释性
+- 降低平衡难度
+- 让角色差异感真正进入 Build 体验
+
+---
+
+## P1-3：重做运行时物品奖励，让奖励真正贴合场景、NPC、最近事件和 Build 缺口
+
+### 为什么它值得排在任务系统前面
+
+- `docs/design/AI_NATIVE_RUNTIME_ITEM_SYSTEM_REDESIGN_2026-04-02.md` 明确指出：当前宝藏、NPC、任务、锻造等入口都有物品，但缺少统一导演层，奖励与场景/NPC/事件的贴合度不够高。
+- 相比任务系统，运行时物品奖励能更快提升“世界贴脸感”和“当下反馈质量”，且可以先从宝藏入口低风险落地。
+
+### 本阶段要做什么
+
+- 增加运行时物品上下文采样、导演层、编译器和叙事回写层
+- 统一宝藏、NPC 奖励、怪物掉落、任务奖励的物品生成入口
+- 让奖励优先围绕 Build 标签、限时 Build Buff、少量数值补足来设计
+
+### 做到什么算完成
+
+- 至少宝藏和 NPC 奖励接入统一导演层
+- 物品能解释“为什么在这里出现、和谁有关、补的是什么方向”
+- 物品来源可以进入背包、剧情、锻造与存档的同一套结构
+
+### 实际收益
+
+- 奖励不再像泛用掉落池
+- 世界、人物、最近剧情与成长反馈终于真正连起来
+
+---
+
+## P1-4：把任务系统从“单目标单阶段”升级成“意图 -> 合约 -> 信号推进”
+
+### 为什么它仍然是高优先级
+
+- `docs/prd/AI_NATIVE_QUEST_SYSTEM_PRD_2026-04-02.md` 已经指出：当前任务闭环是成立的，但任务来源偏静态、结构偏扁平、状态过粗、奖励和关系变化也不够贴语境。
+- 当前项目已经具备任务 UI、任务奖励、NPC 交互、剧情推进链，这说明任务系统适合做“升级”，而不是推倒重来。
+
+### 本阶段要做什么
+
+- 新增任务生成上下文、AI 任务意图层、本地任务编译层
+- 把任务推进改成统一 signal 驱动
+- 支持多 step、阶段揭示、完成后回报、后续钩子
+
+### 做到什么算完成
+
+- NPC 接任务不再只是静态模板，而是能根据当前局面生成任务意图
+- 运行时能用统一 signal 推进任务步骤
+- 奖励除了货币/道具，还能自然进入关系、情报、后续机会
+
+### 为什么它排在物品系统之后
+
+- 任务系统耦合更深，适合作为统一属性和统一奖励导演层之后的升级项
+- 先把属性和物品奖励理顺，任务系统落地时会更稳
+
+---
+
+## P2-1：收尾编辑器共享层与本地 API 分层，让内容扩张不再继续拖慢主项目
+
+### 为什么它不是最前面，但也不能拖太久
+
+- 最近几份工程审查都指出：编辑器共享层、本地 JSON 写入接口、LLM 代理、Vite 插件职责仍然处于迁移中间态。
+- 当前项目已经进入“内容工具很多、正式运行时也很重”的阶段，若不收尾这部分，后续每次扩内容都会重复踩基础设施问题。
+
+### 本阶段要做什么
+
+- 继续拆 editor shared 层
+- 清理迁移残留和死分支
+- 把本地 API 至少按 `llm proxy / json editor api / asset catalog` 分职责拆开
+
+### 做到什么算完成
+
+- 编辑器保存、共享组件、共享 client 不再重复实现
+- 本地 API 分工清晰，dev / preview 边界清楚
+- 编辑器扩展不再继续依赖大聚合组件
+
+---
+
+## P2-2：继续优化移动端冒险体验、首屏信息密度与运行时包体
+
+### 为什么它放在 P2
+
+- `docs/experience/PROJECT_DEVELOPMENT_EXPERIENCE.md` 和 `docs/experience/MOBILE_UI_DEV_EXPERIENCE.md` 都强调：冒险页必须优先保证上方演出、一屏选项和文本区自适应。
+- 但从当前文档判断，移动端体验和包体问题更像“持续治理项”，不是当前阶段最核心的系统阻塞点。
+
+### 本阶段要做什么
+
+- 继续优化冒险页一屏布局与文本滚动策略
+- 拆 `GameCanvas`、`AdventurePanel` 等高热区大模块
+- 按真实交互热区继续做 chunk 拆分
+
+### 做到什么算完成
+
+- 手机首屏稳定容纳画布、文本和关键选项
+- 核心页面热区模块更容易维护和测试
+- 构建产物中的主 chunk 有持续下降趋势
+
+---
+
+## 不建议当前优先做的事
+
+以下内容不是不能做，而是不建议排在当前这轮前面：
+
+- 大量新增世界、场景、角色 preset
+- 继续横向扩 NPC 交互种类，但不补统一规则底座
+- 继续堆宝藏、掉落、锻造分支，但不先做统一物品导演层
+- 继续增加任务模板数量，但不升级任务 contract
+- 继续往 `useStoryGeneration` / `useCombatFlow` / `GameShell` 里直接塞新逻辑
+
+原因很简单：
+
+**这些工作会让表面内容变多，但不会让项目变得更稳，反而会放大当前已经存在的结构问题。**
+
+---
+
+## 推荐迭代顺序
+
+### 第一阶段：先稳住工程与主流程
+
+1. 绿色基线与门禁收紧
+2. 运行时主链拆分
+
+### 第二阶段：先补统一语义底座
+
+1. 统一角色属性系统
+2. Build 改为属性适配
+
+### 第三阶段：再深化 AI 原生玩法闭环
+
+1. 运行时物品导演层
+2. 任务意图与 contract 系统
+
+### 第四阶段：最后做工具与体验收尾
+
+1. 编辑器共享层 / 本地 API 分层
+2. 移动端体验与包体优化
+
+---
+
+## 本清单的主要依据
+
+- `docs/experience/PROJECT_DEVELOPMENT_EXPERIENCE.md`
+- `docs/experience/PROJECT_WORK_EXPERIENCE_PLAYBOOK.md`
+- `docs/experience/ADVENTURE_RUNTIME_DEV_EXPERIENCE.md`
+- `docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-03-29.md`
+- `docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-03-30.md`
+- `docs/audits/engineering/ENGINEERING_OPTIMIZATION_REVIEW_2026-04-01.md`
+- `docs/design/AI_NATIVE_RUNTIME_ITEM_SYSTEM_REDESIGN_2026-04-02.md`
+- `docs/prd/AI_NATIVE_UNIFIED_ROLE_ATTRIBUTE_SYSTEM_PRD_2026-04-02.md`
+- `docs/prd/BUILD_SYSTEM_ATTRIBUTE_SIMILARITY_PRD_2026-04-02.md`
+- `docs/prd/AI_NATIVE_QUEST_SYSTEM_PRD_2026-04-02.md`
+
+## 最后结论
+
+如果只保留一句话，那就是：
+
+**当前最优先的迭代方向，不是继续堆新内容，而是先把工程基线、主流程边界和统一规则底座补齐；只有这样，AI 原生任务、物品、Build 和后续内容扩展才会真正开始越做越顺。**

docs/planning/README.md

@@ -0,0 +1,10 @@
+# 规划与优先级
+
+## 当前入口
+
+- [CURRENT_GAME_ITERATION_PRIORITIES_2026-04-03.md](./CURRENT_GAME_ITERATION_PRIORITIES_2026-04-03.md)：当前阶段最值得优先做什么、为什么，以及它和审计/PRD 的对应关系。
+
+## 使用建议
+
+- 需要排期、拆阶段、判断先修基线还是先加功能时，先看这份。
+- 这份文档大量引用了经验文档、工程审查和 PRD，适合作为跨文档导航页使用。