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

更新时间：`2026-04-20`

## 1. 背景

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

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

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

## 2. 当前产品语义

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

```text
角色 X
地点 Y
```

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

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

而不是：

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

对应地，“地点”表示：

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

## 3. 之前的偏差

### 3.1 角色数量偏差

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

```ts
draftProfile.playableNpcs.length
```

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

```ts
draftProfile.storyNpcs
```

所以会出现：

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

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

### 3.2 地点数量断言偏差

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

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

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

```ts
FOUNDATION_DRAFT_LANDMARK_COUNT = 2
```

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

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

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

## 4. 本次修正

### 4.1 草稿摘要角色数

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

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

原因：

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

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

### 4.2 Phase4 地点断言

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

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

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

## 5. 约束建议

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

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