文档：记录引用候选由宿主注入的决策、术语与功能说明

- 新增 ADR《引用候选由宿主注入》：注入式 provider、面板外移、附件并入正文的理由、备选与影响
- decision-log 增加 2026-09-22 条目：注入 / 分离 / 附件 / 显示口径四项决策、未纳入项、验证方式，并记录顺带清理 activeVersionId
- 功能说明《AGC聊天素材引用》同步：Provider 注入、ResourceReferencePicker 自持数据、$ Skill 只出现在注入该 provider 的宿主、附件进入正文与上限口径、显示名注入
- CONTEXT.md 补引用来源 / provider / 选择器 / 附件芯片等术语与关系
- docs/README.md 登记新 ADR

docs/project-memory/shared-memory/decision-log.md

@@ -1,5 +1,18 @@
 # 决策记录
 
+## 2026-09-22 引用输入区改为宿主注入引用 provider，选择器面板与输入区分离
+
+- 背景：`ResourceReferenceInput`（`apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceInput.tsx`）同时承担「拿数据」与「编辑数据」：素材以未过滤 manifest 传入后由组件自己派生候选、显示名与「当前版本素材」scope，Skill 候选由组件自己 invoke `list_agc_skill_catalog` 与 `list_client_extensions`（只在用户敲出 `$` 时触发），素材选择面板与缩略图预览 invoke 也住在组件内部。后果是 5 个宿主（DirectProject 聊天、策划输入盒、画布生成面板、资源卡快速编辑、测试夹具）无差别获得 `$` Skill 候选，而只有 DirectProject 回合会把 `agc_skill_reference` 解析成真 Skill（Rust `direct_codex_user_item_to_codex_turn_input`，`apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_user_item/wire.rs`），其余宿主只把它退化成字面文本，形成误导入口。
+- 决策（注入）：输入区只接受宿主注入的 `providers: readonly ReferenceProvider[]`。每种引用一个独立工厂——`createResourceReferenceProvider({ assets })`、`useSkillReferenceProvider()`（Skill 候选是异步的应用级读取，所以它同时是宿主 hook：第一次 `match` 时才发起读取，结果到了宿主重渲染，读取不进输入区），附件与运行画面区域为静默 provider（无触发符、无候选）；**没有总装 builder**，宿主按需选择性注入。provider 暴露 `trigger` / `match(query)` / `toReference(part)` / `refresh(reference)` / `mentionToken(part)` 与可选的 `isReady()`（数据未到齐时输入区先不把初始草稿落成文本，否则草稿里的引用会被静默丢掉），输入区只按数组顺序取第一个非空回答，不判断引用种类。
+- 决策（分离）：素材选择面板拆成独立组件 `ResourceReferencePicker`（含一个可复用的 `@` 触发钮 `ResourceReferencePickerAction`），自己拿数据（`assets` / `versions` / `activeVersionId` / `projectPath` 与缩略图预览 invoke），由宿主渲染并把确认结果交给输入区句柄的 `insertReferences`——这是两者之间唯一的接缝。输入区删除 `versions` / `activeVersionId` / `showTriggerButton` / `openPicker` / `skills`，改为收宿主的 `inputActions`（操作排槽位，放触发钮）与 `submitSuppressed`（宿主浮层打开时 Enter 不提交，与候选菜单同一口径）；`projectPath` 只保留给输入区自己的润色链路。
+- 决策（附件）：附件并入 `ChatReference`，编辑器收敛为单一引用节点类型，附件 chip 的 DOM 契约逐字保留；附件在**导入成功后**以芯片插入正文，`status === 'failed'` 或异常一律不插入；控制器不再持有 `attachments` 数组，`ComposerPendingAttachments` 与提交时的附件 parts 拼接一并删除，单次上限 `MAX_CHAT_COMPOSER_ATTACHMENTS = 8` 改为按草稿中的附件芯片数计算（否则上限失效），导入进行中禁止发送。
+- 决策（显示口径）：`directCodexContentToPromptText` 的引用 token 前后各补一个空白（相邻已是空白或相邻即另一个 token 时不重复），并加 `// TODO we will rewrite this with ref as component later.`；该函数的 `resourceId → 显示名` 反查改由调用方注入，函数自己不再读 manifest。
+- 原因：读项目/应用清单是后端副作用，按 AGENTS.md 的边界应留在宿主与后端侧，留在共享表现组件里既越界，又制造了「Skill 在所有输入区可见、只有一条路径可用」的误导。按种类分 provider 让选择性注入成为默认，避免再造一个把全部种类焊死、无法只注入资源或资源 + Skill 的总装层。
+- 影响范围：`apps/ai-game-creator-shell/src/features/project-workspace/**`、`apps/ai-game-creator-shell/src/view/project-development/**`（chat composer / controller、planning、index）、`apps/ai-game-creator-shell/tests/**`、`apps/ai-game-creator-shell/src/styles.css`，以及 `docs/【功能说明】AGC聊天素材引用-2026-09-08.md`。
+- 顺带清理：`ProjectChatComponentProps.activeVersionId`（`apps/ai-game-creator-shell/src/features/app-shell/model.ts`）已无消费方——它只在策划输入盒的 `@` 面板里生效，而策划输入盒的 `@` 触发钮早在本次重构前就不渲染（`showTriggerButton={false}`），工作台壳自己的那份 `activeVersionId` 仍由 `ProjectDevelopmentView`（游戏运行版本）消费，因此只删「壳 → 聊天」这一段穿不过去的参数。
+- 未纳入本次：粘贴解析（未来接入点是 provider 的 `mentionToken` 与既有 `buildContentFromTextTokens`）、`resource-reference-*` CSS 类名重命名（独立机械提交）、扩展变更事件的即时失效。
+- 验证方式：定向 `npx vitest run apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx` 与受影响宿主用例、`npm run typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`；行为零变化按「改名后芯片显示名自动刷新、打开面板前重读清单、`@`/`$` 候选与键盘交互、附件上限与失败提示文案」逐条对照核验，唯一例外是已裁决的 Skill 可见性缺陷修复。
+
 ## 2026-09-21 合并 origin/master：Supervisor 永久退役，策划 V1V2 退役落到当前两条产品路径
 
 - 背景：`refactor/split-direct-project`（DirectProject 独立聊天容器）与 `origin/master`（#355 退役策划 Agent V1/V2）在 2026-09-18 之后各走一条线：本分支删掉 Supervisor 前端链路、把立项策划收敛到 `view/project-development/planning/`，master 删掉整套策划 V1/V2（前端会话 / 审批卡 / 适配器 / 类型与 Rust `planning_*_v2` 命令、`planning_gdd_model.rs`、`planning_policy_v2.rs`、`planning_session_v2.rs`）只保留 Design Agent。两边都在删 Supervisor，冲突集中在 `App.tsx`、聊天视图（`PlanningChatView`、`DirectProjectTurn`、`ToolCallGroup`）、Direct composer / 引用输入区、`styles.css`、Rust direct user item 与 appSurface 用例。