Merge branch 'master' into fix/design-agent-fe

2026-09-23 19:04:31 +08:00
parent 2c778fb027 ebb288a6a4
commit efbfc8085d
24 changed files with 1311 additions and 125 deletions
@@ -1,5 +1,29 @@
 # 决策记录

+## 2026-09-23 引用名不允许空白：素材 / Skill / 附件共用 `normalizeMentionName`
+
+- 背景：自动评审发现 `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` 自己没有兜底、只做归一化这条不变。
+- 落点兜底（2026-09-23，评审项）：part 落进正文的兜底链统一为 `mentionTokenOrText`（provider 的 `mentionToken`，拿不到就退 `contentPartText` 的通用文本形态，即 `@resourceId` / `$名称` / `@附件名` / `@区域标签`）。粘贴插入、润色回写的候选扫描与整根替换共用它，删掉两处静默丢弃路径（provider 答不出 token 的 part 在润色翻译里消失；整根替换时解析不出引用的 part 被吃掉）。副作用是恢复出来的初始草稿里已解析不出的引用落成 `@resourceId` 文本而不是消失——宁可留文本，也不让内容凭空少一段。
+- 原因：不改反解析是因为粘贴解析与润色回包共用 `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` 不再解析，重试 / 润色回填时那条引用会退化成末尾孤儿（内容不丢、位置可能不对）。
+- 验证方式：`normalizeMentionName`、`resourceDisplayName`、`chatReferenceMentionToken` 的口径单测；「空白折 `-` 后 token 自带边界、前缀重叠只剩正确芯片」的回归用例；Skill 目录名带空白与附件名带空白的 provider 用例；把 `normalizeMentionName` 变异成恒等函数后以上新增用例全部变红。另跑受影响用例、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+
+## 2026-09-22 引用粘贴解析：只认显示口径的 token，宁可不成芯片也不能认错
+
+- 背景：引用输入区的 `@` / `$` 只由 `LexicalTypeaheadMenuPlugin` 的逐字敲击触发，粘贴走 Lexical 默认路径（`text/plain` → 纯文本），所以从用户消息气泡复制回来的 `@显示名` / `$名称` 粘进来就是死文本；同时 chip 的 `text/plain` 是占位符，复制出去再粘回来必然丢引用（气泡显示文本才是完整 token 的形态）。
+- 决策（口径）：新增粘贴侧唯一反解析 `buildContentFromPastedText(text, references)`（`apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts`），候选由宿主注入的 provider 枚举，token 就是 `chatReferenceMentionToken`——与出站显示逐字同一个字符串，所以**不做任何兼容别名**：不认 `@hero.png`、`resourceId`、大小写变体、全角 `＠`；边界仍是「行首 / 行尾或空白」（显示侧 token 前后补空白，两端自洽）。
+- 决策（宁可不成芯片也不能认错）：同一个 token 对应多条引用身份（同名素材）时一律按文本保留；未命中的 token 静默保留、不提示、不猜文件名或路径；附件与运行画面区域不参与（静默 provider 没有候选，`@附件名` / `@区域标签` 按文本保留）。
+- 决策（provider 契约按「模糊 / 精确」分两个口）：上一条里的 `match(query)` 改名 `fuzzyLookup(query)`（名字写明它是包含匹配 + 截断的模糊菜单查询），`candidates()` 改名 `lookup()`（精确查找用的、就绪的全量候选，不模糊不截断），两者共用同一份候选来源。粘贴解析只用 `lookup()` 此刻就绪的候选：不等待、不补读，也不为了解析去提前读盘；Skill 目录仍是「用户第一次敲出 `$` 才读」，冷启动时粘贴 `$名称` 保持字面文本，敲过一次 `$` 后即可重建芯片。曾一度加过的 `onPasteText` 补读钩子已删除——它既不改变本次粘贴的结果，又让输入区反过来关心 provider 的触发符。
+- 决策（接管范围）：输入区在 `COMMAND_PRIORITY_CRITICAL` 注册 `PASTE_COMMAND`，**只在真的解析出引用时**接管（同 namespace 的 `application/x-lexical-editor` 负载、无 token 纯文本、图片文件一律 `return false` 走默认导入）；接管时一次 `editor.update(..., { tag: PASTE_TAG })` 内按选区插入，所以一次 Ctrl+Z 整体回退，token 之外逐字保留。
+- 原因：粘贴是用户此刻的编辑，事后回头改写他的输入（例如清单到齐后再把文本改成芯片）等于前端替用户重写内容；而任何「多候选取其一」「按文件名猜资源」的启发式都会制造看不出错的错引用。
+- 影响范围：`apps/ai-game-creator-shell/src/features/project-workspace/{resourceReferences.ts,ResourceReferenceInput.tsx,reference-source/{types.ts,resourceReferenceProvider.ts,skillReferenceProvider.ts}}`、`apps/ai-game-creator-shell/tests/{resourceReferences.test.ts,referenceSourceProviders.test.ts,resourceReferenceInput.test.tsx}`、`CONTEXT.md`、`docs/adr/【ADR】引用候选由宿主注入-2026-09-22.md`（修订节）、`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`、本文件。
+- 未纳入本次：斜杠命令 `/` 解析、拖拽文本（drop）、附件 / 运行画面区域 / 文件路径 / URL / 剪贴板图片、复制侧 `text/plain` 形态调整、扩展安装卸载后的目录即时失效。
+- 验证方式：`buildContentFromPastedText` 规则矩阵单测（含「显示文本再粘贴回来得到同一份 content」这条逆运算）、provider 的 `fuzzyLookup` / `lookup` 用例、输入区集成用例（真 Lexical `paste` 事件 → 芯片、未命中等价于默认粘贴、Skill 冷启动保持字面且敲过 `$` 后可解析）；另跑 `npm run typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
+
 ## 2026-09-23 最近项目检查失败不进终态

 - 背景：最近项目列表把一次性的目录检查失败当成终态——5s 超时被吞成 `null`，增量投影又把上一轮的 `null` 原样搬进下一轮，且没有重试或重查入口。AGC 一次 IPC 停顿之后，整张列表会永久停在「检查失败 + 待识别」，首页「最近项目」同时因 `canOpen` 过滤变空，只能重启客户端恢复（issue #490）。