Genarrative/docs/technical/CUSTOM_WORLD_PHASE4_COUNT_SEMANTICS_ALIGNMENT_2026-04-20.md

自定义世界 Phase4 数量字段语义对齐说明 2026-04-20

更新时间：2026-04-20

1. 背景

在排查世界草稿生成等待页问题后，继续执行 server-node 相关测试时，发现 Phase4 仍有两处失败：

1. generate_characters 后草稿作品卡的角色数量没有按预期增长。
2. generate_landmarks 的 HTTP 用例对地点数量使用了过时的固定基线。

这两个问题本质上都和“数量字段语义不一致”有关。

2. 当前产品语义

创作中心草稿卡在前端展示的是：

角色 X
地点 Y

这里的“角色”从产品感知上表示：

当前草稿中已经长出来、可继续精修的全部角色对象数量。

而不是：

仅 playable / 仅主角位角色数量。

对应地，“地点”表示：

当前草稿中已经存在的地点对象数量。

3. 之前的偏差

3.1 角色数量偏差

server-node/src/services/customWorldWorkSummaryService.ts 在草稿态里原先只统计：

draftProfile.playableNpcs.length

但 Phase4 generate_characters 的实现是把新增角色插入：

draftProfile.storyNpcs

所以会出现：

1. 角色卡确实新增了
2. storyNpcs 也确实变多了
3. 创作中心草稿卡上的“角色数”却没有同步增加

这会让产品表现和数据真实状态不一致。

3.2 地点数量断言偏差

server-node/src/app.test.ts 的 generate_landmarks HTTP 用例里，之前写死了：

assert.ok((sessionPayload.draftProfile?.landmarks?.length ?? 0) >= 6);

但当前基础草稿阶段的地点基线已经调整为：

FOUNDATION_DRAFT_LANDMARK_COUNT = 2

所以 Phase4 的正确断言应该是：

在当前会话已有地点基线上，再新增 2 个地点

而不是继续沿用旧版本里“基础草稿默认至少 4 个地点”的固定假设。

4. 本次修正

4.1 草稿摘要角色数

草稿态 playableNpcCount 在工作摘要里继续沿用既有字段名，但统计语义调整为：

全部草稿角色数量 = playableNpcs + storyNpcs 去重后的总数

原因：

1. 前端现有 contract 和展示字段已经复用 playableNpcCount
2. 这次目标是最小修复，不额外扩 contract
3. 草稿态 UI 标签本身展示的是“角色”，不是“可扮演角色”

因此这次保留字段名，修正其在草稿态的统计语义。

4.2 Phase4 地点断言

generate_landmarks 的 HTTP 用例改为基于当前会话的 draftProfile.landmarks.length 做增量校验：

新增后数量 >= 基线数量 + 2

这样可以避免未来基础草稿默认地点数再次调整时，Phase4 用例继续被写死基线误伤。

5. 约束建议

后续涉及草稿作品卡数量字段时，统一遵守：

1. 草稿态“角色”展示全部草稿角色数，不只统计 playable。
2. 已发布态如果 UI 明确写“可扮演角色”，再单独按 playable 统计。
3. 所有数量断言优先使用“当前基线 + 增量”的写法，不要硬编码旧阶段默认数量。