修复：素材显示名在词干为空时回退 asset.id，不再产生空引用名

resourceDisplayName 在文件名去掉扩展名后为空（`.env` / `.gitignore` 这类整名就是扩展名的文件）时回退 asset.id，回退值同样过 normalizeMentionName；空名字会让 token 退化成只有触发符的裸 `@`，候选菜单里是空芯片、粘贴解析还会认领正文里任何一处裸 `@` normalizeMentionName 的注释改为「只做归一化、不做兜底」，把兜底的落点写明在名字的来源侧新增用例：`.env` 与 `config/.gitignore` 的显示名回退 asset.id、引用标签不再为空；把该回退去掉后用例变红同步决策记录（校正「不做 resourceId 兜底」一条）、AGC 聊天素材引用功能说明与引用粘贴解析实施计划
2026-09-23 11:53:14 +08:00
parent 44148542f1
commit 4e90465c45
5 changed files with 28 additions and 4 deletions
@@ -47,6 +47,6 @@
 自动评审留下的唯一破坏性项（`@hero` 与 `@hero v2` 互为前缀时粘贴会多插一枚短名芯片）不改反解析，改为把不变量前移到引用名：

 - `resourceReferences.ts` 新增共享 `normalizeMentionName(value)`（内部空白折 `-`、裁首尾），素材显示名（`resourceDisplayName`）、Skill 名（目录读入与 `toReference` / `mentionToken`）、附件名（导入映射与 `toReference` / `mentionToken`）与两个 token 投影（`chatReferenceMentionToken`、`directCodexContentToPromptText`）统一过这一份；token 层重复归一化是幂等的。
- 名称里不再做 `resourceId` 兜底（`resourceDisplayName` 去掉 `|| asset.id`）；假定引用名非空。
+- 名称里不做 `resourceId` 兜底这一条按评审校正：词干为空（`.env` / `.gitignore` 这类整名就是扩展名的文件）时 `resourceDisplayName` 回退 `asset.id`，回退值同样过 `normalizeMentionName`；`normalizeMentionName` 自己仍只做归一化。
 - 代价与取舍：`hero v2` 与 `hero-v2` 归一化后同名时走既有的「同名多候选按文本保留」；改动前生成的旧文本里的 `@hero v2` 不再解析。
 - 验证：`normalizeMentionName` / 显示名 / token 口径单测 + 前缀重叠回归用例（归一化后粘贴只剩正确的那一枚芯片）+ provider 两处用例；把 `normalizeMentionName` 变异成恒等后新增用例全红。
@@ -5,6 +5,7 @@
 - 背景：自动评审发现 `buildContentFromTextTokens` 在前缀重叠时会多插一枚芯片——素材显示名 `hero` 与 `hero v2` 并存时，粘贴 `看 @hero v2 这一版` 得到 `[chip hero]` + `[chip hero-v2]`（短名先按 index 平局抢位，长名成了补到末尾的孤儿）。根因不是匹配算法，而是**引用名自己带空白**：token 的边界规则是「前后为空白或行首行尾」，`@hero␠` 在 `@hero v2` 内部也算一次合法命中。
 - 决策：把不变量前移到引用名——`@显示名` / `$名称` / `@附件名` 的名字内部不允许空白，统一经共享 `normalizeMentionName(value)`（内部空白折成 `-`、裁掉首尾）处理。落点是名字的产生处：`resourceDisplayName()`、Skill 目录读入与 `toReference` / `mentionToken`、附件导入映射与 `toReference` / `mentionToken`，外加两个 token 投影（`chatReferenceMentionToken`、`directCodexContentToPromptText`）——token 层幂等再折一次，「token 里没有空白」就是不变量本身的性质，不依赖上游数据干净。
 - 决策（不兜底）：引用名假定非空，不做 `resourceId` 之类的兜底；`resourceDisplayName` 原来的 `|| asset.id` 一并去掉。
+- 校正（2026-09-23，评审项）：`resourceDisplayName` 的空名字兜底不能一并去掉——整名就是扩展名时（`.env` / `.gitignore`）去掉扩展名得到空串，显示名成了空串，token 退化成只有触发符的裸 `@`（候选菜单里是空芯片，粘贴解析还会认领正文里任何一处裸 `@`）。改为词干为空时回退 `asset.id`（仍过 `normalizeMentionName`）；`normalizeMentionName` 自己没有兜底、只做归一化这条不变。
 - 原因：不改反解析是因为粘贴解析与润色回包共用 `buildContentFromTextTokens`，改匹配算法要冒回归润色的风险；而「名字里带空白的 token」本来就无法手敲（候选触发器 `allowWhitespace: false`，空格处菜单就关），显示口径与输入口径早就不一致。折成 `-` 之后 token 自带边界：`@hero` 不会命中 `@hero-v2`（后一个字符是 `-`，不是空白），前缀重叠不可能再发生。
 - 影响范围：`apps/ai-game-creator-shell/src/features/project-workspace/{resourceReferences.ts,reference-source/{skillReferenceProvider.ts,attachmentReferenceProvider.ts}}`、`apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directCodexTurnAttachments.ts`、`apps/ai-game-creator-shell/tests/{resourceReferences.test.ts,referenceSourceProviders.test.ts}`、`CONTEXT.md`、`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`、`docs/project-memory/plans/【实施计划】引用粘贴解析-2026-09-22.md`。
 - 代价（已接受）：归一化可能撞名（`hero v2` 与 `hero-v2` 同名），走既有的「同名多候选一律按文本保留」——不认错，但两者都成不了芯片；改动前生成的旧文本（历史回合 prompt、旧气泡）里的 `@hero v2` 不再解析，重试 / 润色回填时那条引用会退化成末尾孤儿（内容不丢、位置可能不对）。
@@ -48,7 +48,7 @@ AGC 聊天输入框支持以结构化引用标记当前项目已登记素材，

 - 归一化落在名字的产生处：`resourceDisplayName()`（素材显示名由文件名派生）、Skill 目录读入与 `toReference` / `mentionToken`、附件导入映射与 `toReference` / `mentionToken`、以及两个 token 投影（`chatReferenceMentionToken`、`directCodexContentToPromptText`）。token 层再折一次是幂等的，因此「token 里绝不会有空白」是这一层的性质，不依赖上游数据干净。
 - 为什么必须有这条不变量：token 的边界规则是「前后为空白或行首行尾」。名字里带空白时，`@hero v2` 会被反解析切成 `@hero` + 文本 `v2`，短名字抢先命中，真正的引用反而被当成孤儿补到正文末尾（粘贴回填会多出一枚错芯片）。折成 `-` 之后 token 自带边界，`@hero` 不会命中 `@hero-v2`（后一个字符是 `-`）。
- 名字里不做 `resourceId` 之类的兜底：引用名假定非空。
+- 词干为空的素材名回退 `asset.id`：整名就是扩展名时（`.env` / `.gitignore`）文件名去掉扩展名会得到空串，空名字会让 token 退化成只有触发符的裸 `@`——候选菜单里是一枚空芯片，粘贴解析还会拿它认领正文里任何一处裸 `@`。所以 `resourceDisplayName()` 在这一种情况下回退 `asset.id`，回退值同样过一遍 `normalizeMentionName`；`normalizeMentionName` 自身仍然只做归一化、不做兜底。
 - 已存在的老文本（本次改动前生成的回合 prompt、历史气泡）里的 `@hero v2` 不再解析——粘贴时按字面保留，重试 / 润色回填时该引用会退化成末尾孤儿。内容不丢，位置可能不对。

 ## 拖拽引用（2026-09-21）