文档：记录引用候选由宿主注入的决策、术语与功能说明
- 新增 ADR《引用候选由宿主注入》：注入式 provider、面板外移、附件并入正文的理由、备选与影响 - decision-log 增加 2026-09-22 条目：注入 / 分离 / 附件 / 显示口径四项决策、未纳入项、验证方式，并记录顺带清理 activeVersionId - 功能说明《AGC聊天素材引用》同步：Provider 注入、ResourceReferencePicker 自持数据、$ Skill 只出现在注入该 provider 的宿主、附件进入正文与上限口径、显示名注入 - CONTEXT.md 补引用来源 / provider / 选择器 / 附件芯片等术语与关系 - docs/README.md 登记新 ADR
This commit is contained in:
+32
@@ -194,6 +194,34 @@ _Avoid_: 进度通知、快照轮询、第二套历史
|
||||
把项目对话历史条目与运行态事件转换成消息气泡和工具卡片的读取期转换；不持久化，也不构成事实源。
|
||||
_Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
|
||||
|
||||
**引用候选**:
|
||||
输入区可以命中的对象集合（`@` 素材、`$` Skill），由宿主按种类注入；输入区不判断候选属于哪一类。
|
||||
_Avoid_: 输入区自己读项目清单或应用目录、把候选取值写死在组件里
|
||||
|
||||
**引用 provider**:
|
||||
一种引用种类向输入区提供的全部能力：触发符、候选、身份解析与正文文本形态；每种引用各一份，宿主按需选择性注入。
|
||||
_Avoid_: 一个总装对象决定所有种类、输入区按种类分叉、provider 之间互相知道对方
|
||||
|
||||
**静默 provider**:
|
||||
不提供候选、只负责已有引用身份与文本形态的 provider；附件与运行画面区域属于这一类，只能由外部插入或草稿回填进入正文。
|
||||
_Avoid_: 给附件或运行画面区域造候选、为它们保留输入区内的专门分支
|
||||
|
||||
**引用文本语法**:
|
||||
引用在正文文本里的形态（`@显示名` / `$名称` / `@附件名`）及其反解析；出站与解析必须同一口径，token 前后各留一个空白。
|
||||
_Avoid_: 出站与解析各写一套、在空白边界之外再补兼容别名、让解析依赖具体种类的字段
|
||||
|
||||
**引用输入区**:
|
||||
只负责编辑与渲染引用的共享输入组件；候选、身份解析与文本语法都来自注入的 provider，它不持有项目清单、不访问后端。
|
||||
_Avoid_: 输入区自己拉 Skill 目录、把选择器面板塞在输入区内部
|
||||
|
||||
**引用选择器**:
|
||||
宿主渲染的独立面板，自己拿数据与筛选状态，确认后把选中的引用交给输入区的插入缝。
|
||||
_Avoid_: 输入区自带面板、每个宿主各画一个、绕开插入缝另开第二条通道
|
||||
|
||||
**附件芯片**:
|
||||
聊天附件在正文里的唯一表示；附件导入成功即以芯片进入正文，正文之外不存在第二份附件状态。
|
||||
_Avoid_: 待发送附件列表与正文芯片并存、提交时再拼一遍附件
|
||||
|
||||
## Relationships
|
||||
|
||||
- 一个 **汪汪声浪大作战** 单局包含多个 **有效声浪触发**。
|
||||
@@ -209,6 +237,10 @@ _Avoid_: 投影缓存文件、已脱敏卡片库、第二套 reducer
|
||||
- **个人历史成绩** 由最近记录列表和个人最佳摘要组成，只允许本人查看；排行榜只公开入榜胜利成绩。
|
||||
- **正式作品入口闭环** 必须覆盖创作入口、作品详情 CTA、广场/作品卡片、我的作品/个人作品架、稳定作品 ID runtime 路由和 `work_play_start` 埋点。
|
||||
- **Phase 2 实施顺序** 固定为：契约与领域规则 → SpacetimeDB 表/reducer 与 api-server BFF → 最小前端纵切 → 投影与列表体验 → 收口验证。
|
||||
- **引用输入区** 由宿主注入的若干 **引用 provider** 组成；**引用候选** 与 **引用文本语法** 都来自 provider，输入区不判断引用种类。
|
||||
- **引用选择器** 不属于 **引用输入区**：它自己拿数据，确认后只通过输入区的插入缝交付引用。
|
||||
- 只有带触发符的 **引用 provider** 会产生候选；**静默 provider** 没有触发符，只能由外部插入或草稿回填进入正文。
|
||||
- **附件芯片** 是本轮附件的唯一事实源；附件导入失败时不产生芯片。
|
||||
|
||||
## Example dialogue
|
||||
|
||||
|
||||
@@ -40,6 +40,7 @@
|
||||
- [DirectProject Codex 原始历史与异常恢复](<./technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md>)：原始 Responses item 持久化、线程注入与异常回合收尾。
|
||||
- [DirectProject 对话历史单一事实源](./adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md)：AGC 项目开发对话只以项目对话历史与运行态事件为真相源，聊天投影不落盘。
|
||||
- [DirectProject 独立聊天容器与工作台钱包布局](./adr/【ADR】DirectProject独立聊天容器与工作台钱包布局-2026-09-18.md)：DirectProject 与 Supervisor 等路径分容器，钱包入口由项目工作台布局独立承载。
|
||||
- [引用候选由宿主注入](./adr/【ADR】引用候选由宿主注入-2026-09-22.md)：引用输入区只接受宿主注入的引用 provider，素材选择面板独立成组件，附件芯片成为本轮附件唯一事实源。
|
||||
- [GameAgent 对话工具调用卡片](./technical/【技术方案】GameAgent对话工具调用卡片-2026-09-14.md)：把右侧对话里的执行命令 / 写文件投影成 Codex 风格可折叠卡片，含采集、独立历史文件、事件字段与回读契约。
|
||||
- [DirectProject 客户端 Skill 与 MCP 扩展导入方案](./technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md)：客户端扩展导入、按独立 Skill/MCP 拆分、命名、启用和启动时注入边界。
|
||||
- [AGC 通用插件宿主与编辑器适配](./technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md)：通用插件宿主、SDK、权限审计、UI 挂载和 Cocos 编辑器适配边界。
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# 引用候选由宿主注入
|
||||
|
||||
状态：已接受
|
||||
|
||||
引用输入区（`ResourceReferenceInput`）不再自己去拿候选。素材清单、Skill 目录、缩略图预览这些项目级或应用级事实全部改由宿主注入：输入区只接受一组「引用 provider」（每种引用一份，暴露触发符、候选、身份解析与正文文本形态），宿主按需选择性注入——只注入资源 provider 就只存在 `@`，再注入 Skill provider 才出现 `$`。素材选择面板同时拆成独立组件（`ResourceReferencePicker`），自己拿数据、由宿主渲染，确认后经输入区句柄的 `insertReferences` 交回。
|
||||
|
||||
这么改的理由是双向的。留在组件里的读取属于后端副作用，越过了「共享表现组件不拥有后端副作用与正式业务状态」的边界；而「组件自己查 Skill 目录」又让所有宿主无差别获得 `$` 候选，可只有 DirectProject 那条路径会把 `agc_skill_reference` 解析成真 Skill，其余宿主只把它退化成字面文本，形成误导入口。注入之后「没注入就没有这类引用」成为默认，可见性不再需要额外的开关。
|
||||
|
||||
## 备选与取舍
|
||||
|
||||
- 只把 Skill 目录外移、素材继续留在组件内部：改动更小，但输入区仍要知道资源种类的字段（显示名、版本 scope、可提及过滤），「只认接口」不成立。
|
||||
- 一个总装 builder 统一产出全部候选：调用方接线更短，但所有种类被焊死在同一层，无法只注入资源、也无法单独测试某一种引用。
|
||||
- 附件继续留在正文之外（待发送列表）：改动更小，但本轮附件会有两份事实源（正文芯片与列表条目），提交时还要再拼一遍；收敛成一份之后，移除语义、上限口径与排队路径都自然归位。
|
||||
|
||||
## 影响
|
||||
|
||||
- 输入区删除 `versions` / `activeVersionId` / `showTriggerButton` / `onReferencePickerOpen` / `skills`，`assets` 被注入的 provider 取代；`projectPath` 只保留给输入区自己的润色链路。
|
||||
- 输入区与宿主之间只留三个通用接缝：`providers`（引用来源）、`inputActions`（操作排里的宿主控件，例如 `@` 触发钮）、`submitSuppressed`（宿主浮层打开时 Enter 让位）。引用种类一个都不进输入区。
|
||||
- 附件并入 `ChatReference`，编辑器收敛为单一引用节点类型，附件 chip 的 DOM 契约逐字保留；附件导入成功后以芯片进入正文，失败不插入；控制器不再持有附件数组，`MAX_CHAT_COMPOSER_ATTACHMENTS` 改为按草稿中的附件芯片数计算，导入进行中禁止发送。
|
||||
- 用户可见行为保持不变，唯一例外是已裁决的缺陷修复：非 DirectProject 宿主不再出现 `$` Skill 候选。
|
||||
@@ -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 用例。
|
||||
|
||||
@@ -1,15 +1,29 @@
|
||||
# AGC 聊天素材引用
|
||||
|
||||
更新时间：2026-09-21
|
||||
更新时间：2026-09-22
|
||||
|
||||
AGC 聊天输入框支持以结构化引用标记当前项目已登记素材，并提供 Codex 风格的 Skill 提及。输入 `@` 会按素材名称、资源 ID 和类型过滤候选项；输入 `$` 会按当前 DirectProject 可用 Skill 名称过滤候选项；也可以点击输入框右侧的 `@` 按钮打开素材选择面板。
|
||||
|
||||
## 引用来源由宿主注入（2026-09-22）
|
||||
|
||||
`ResourceReferenceInput` 只接受宿主注入的一组「引用 provider」（`ReferenceProvider`，每种引用一个独立工厂）：
|
||||
|
||||
- `createResourceReferenceProvider({ assets })` → `@` 素材候选；
|
||||
- `useSkillReferenceProvider()` → `$` Skill 候选（读取应用级 Skill 目录，只在用户第一次敲出 `$` 时发生；失败会放开重试）；
|
||||
- 附件与运行画面区域是**静默 provider**（无触发符、无候选），只参与正文 part 的身份解析、改名刷新与文本形态。
|
||||
|
||||
输入区按 `providers` 数组顺序取第一个非空回答，不判断任何引用种类，也没有总装 builder。**没注入就没有这类引用**：只有 DirectProject 回合会把 `agc_skill_reference` 解析成真 Skill（Rust `direct_codex_user_item_to_codex_turn_input`），所以只有它注入 Skill provider；策划输入盒、画布生成面板、资源卡快速编辑与画布生成浮层只注入资源 + 两个静默 provider，不再出现退化成正文文本的 `$` 误导入口（已裁决的缺陷修复）。
|
||||
|
||||
素材选择面板拆成独立组件 `ResourceReferencePicker`：自己拿数据（`assets` / `versions` / `activeVersionId` / `projectPath` 与缩略图预览 invoke），自己管打开态与两个页签的筛选状态，由宿主渲染并把触发钮放在自己的位置（输入区操作排的 `inputActions` 槽，或宿主自己的控制排）。确认后只经 `insertReferences` 把选中的引用交回输入区——这是两者之间唯一的接缝。输入区不再收 `assets` / `versions` / `activeVersionId` / `skills` / `showTriggerButton`；`projectPath` 只留给输入区自己的润色链路。
|
||||
|
||||
引用在正文文本里的形态（出站给 agent、润色、队列 chip 的那一份）由各 provider 的 `mentionToken` 决定，每个 token **前后各留一个空白**（相邻已是空白或相邻就是另一个 token 时不重复补），与「token 前后必须是行首/行尾或空白」的反解析口径自洽。`directCodexContentToPromptText` 的 `resourceId → 显示名` 反查改由调用方注入（`resourceLabelResolver(assets)`），函数自己不再读 manifest。
|
||||
|
||||
素材选择面板支持缩略图、名称或资源 ID 搜索、类型筛选和多选；面板顶部有两个页签：
|
||||
|
||||
- 「当前版本素材」：列出版本 `resourceBindings` 里绑定的、且仍登记在 manifest 的素材；
|
||||
- 「全部画布素材」：列出全部已登记素材。
|
||||
|
||||
两个页签各自持有独立的搜索与类型筛选状态，互不影响，也不与资源画布筛选联动。当前版本取 `ResourceReferenceInput` 的 `activeVersionId`；未传或传 `null` 时回退到 manifest `versions[]` 中最新的那个版本。版本不存在或该版本没有绑定素材时页签显示空态，不合成资源卡；绑定指向已删除资源（悬空绑定）时按资源 `id` 过滤掉。
|
||||
两个页签各自持有独立的搜索与类型筛选状态，互不影响，也不与资源画布筛选联动。当前版本取宿主传给 `ResourceReferencePicker` 的 `activeVersionId`；未传或传 `null` 时回退到 manifest `versions[]` 中最新的那个版本。版本不存在或该版本没有绑定素材时页签显示空态，不合成资源卡；绑定指向已删除资源（悬空绑定）时按资源 `id` 过滤掉。
|
||||
|
||||
确认后素材以 `@素材名` 芯片插入编辑器，Skill 以 `$skill-name` 芯片插入编辑器；用户可以在芯片前后继续编辑自然语言，也可以单独删除芯片。素材芯片内部保存稳定 `resourceId`，展示名称只用于界面，不参与引用解析。Skill 芯片保存稳定 Skill 名称，发送时由 Rust 根据当前 DirectProject 已启用 Skill 清单解析为 Codex 原生 `type: "skill"` 输入项。资源改名后，编辑区已有芯片与候选列表都会按 `resourceId` 刷新成 manifest 的最新显示名，并同步回父级草稿。
|
||||
|
||||
@@ -25,14 +39,24 @@ AGC 聊天输入框支持以结构化引用标记当前项目已登记素材，
|
||||
- 只认**已登记到 manifest** 的素材，引用身份、来源标记 `resource-card` 与「引用」按钮逐字一致，所以同一素材两处进来是同一枚引用（去重键也一样）；一条都引用不了时（素材都未登记）用提示条说明原因。
|
||||
- 一次松手只派发一次批量事件（`RESOURCE_REFERENCE_INSERT_MANY_EVENT`），草稿只重建一次、插入顺序即拖动集合顺序。
|
||||
|
||||
## 附件进入正文（2026-09-22）
|
||||
|
||||
本地上传入口不区分图片和其它文件：用户从同一个文件选择器提交任意附件，前端不做 MIME 类型分流，所有上传文件统一编码为 `agc_attachment_reference`。图片不会因为扩展名或 MIME 类型获得另一种 canonical part；只有未来真正支持 Codex 多模态 `input_image` 投影时，才另行设计图片协议。
|
||||
|
||||
本轮附件只有**正文芯片**这一份事实源：导入成功后附件立即以芯片插入正文，`status === 'failed'` 或导入异常一律不插入；控制器不再持有待发附件数组，`ComposerPendingAttachments` 与提交时的附件 parts 拼接都已删除。因此：
|
||||
|
||||
- 附件可以出现在正文的任意位置（在光标处插入），移除就是删除那枚芯片；
|
||||
- 单次上限仍是 `MAX_CHAT_COMPOSER_ATTACHMENTS = 8`，但按草稿里已有的附件芯片数计算；
|
||||
- 导入进行中禁止发送（导入结果还没落成芯片时发出去，用户会以为带上了附件）；导入期间允许再次点击 `+`，并发导入各自插入自己的芯片；
|
||||
- 「正在上传文件 / N 个文件未能上传：xxx / 已上传 N 个文件，将在下次发送时作为本轮附件」三条文案保持不变。
|
||||
|
||||
当前已完成：
|
||||
|
||||
- 三个聊天入口共用 `ResourceReferenceInput`；
|
||||
- 四个入口（DirectProject 聊天、策划输入盒、画布生成面板、资源卡快速编辑）共用 `ResourceReferenceInput`，引用来源由宿主选择性注入；
|
||||
- 输入 `@` 触发候选，支持键盘选择和 Esc 关闭；
|
||||
- 输入 `$` 触发 Skill 候选，支持键盘选择和 Esc 关闭；Skill 候选只显示当前 DirectProject 已启用且已由 app-server 发现的 Skill；
|
||||
- `@` 按钮打开素材选择面板；
|
||||
- 输入 `$` 触发 Skill 候选，支持键盘选择和 Esc 关闭（只有注入 Skill provider 的 DirectProject 输入界面有 `$`）；Skill 候选只显示当前 DirectProject 已启用且已由 app-server 发现的 Skill；
|
||||
- `@` 按钮打开素材选择面板（面板由宿主渲染，自己拿数据）；
|
||||
- 附件导入成功即插成正文芯片，失败不插入，随本轮 canonical content 一起发送；
|
||||
- 支持搜索、类型筛选和多选；
|
||||
- 素材芯片可插入、编辑和删除；
|
||||
- 资源画布支持把资源卡拖到对话栏批量引用（2026-09-21，见上一节）；
|
||||
|
||||
Reference in New Issue
Block a user