Merge remote-tracking branch 'origin/master' into codex/clear-retired-tables-phase2

2026-09-22 19:42:44 +08:00
parent fd0c1007ad da0df57ebc
commit b417144baf
73 changed files with 5119 additions and 1616 deletions
@@ -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,21 @@
+# 引用候选由宿主注入
+
+状态：已接受
+
+引用输入区（`ResourceReferenceInput`）不再自己去拿候选。素材清单、Skill 目录、缩略图预览这些项目级或应用级事实全部改由宿主注入：输入区只接受一组「引用 provider」（每种引用一份，暴露触发符、候选、身份解析与正文文本形态；需要为菜单开合拉一次数据的 provider 另有 `onMenuQueryChange`，由输入区在 effect 里回调），宿主按需选择性注入——只注入资源 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 让位）。引用种类一个都不进输入区。
+- `provider.match` 必须是纯函数（输入区在渲染阶段调它取候选）；懒加载走 provider 的可选 `onMenuQueryChange(query)`，由输入区在 `useEffect` 里回调，菜单关闭时收到 `null`。Skill 目录因此第一次敲出 `$` 时才读，渲染期不再有 invokes 或 ref 写入。
+- 附件并入 `ChatReference`，编辑器收敛为单一引用节点类型，附件 chip 的 DOM 契约逐字保留；附件导入成功后以芯片进入正文，失败不插入；控制器不再持有附件数组，`MAX_CHAT_COMPOSER_ATTACHMENTS` 改为按草稿中的附件芯片数计算，导入进行中禁止发送。
+- 用户可见行为保持不变，唯一例外是已裁决的缺陷修复：非 DirectProject 宿主不再出现 `$` Skill 候选。
@@ -0,0 +1,63 @@
+# 引用输入区重构与宿主注入实施计划
+
+对应：[引用候选由宿主注入](../../adr/【ADR】引用候选由宿主注入-2026-09-22.md)；决策记录见 `docs/project-memory/shared-memory/decision-log.md` 的 2026-09-22 条目。本计划不含粘贴解析。
+
+## 一句话交付与验收判据
+
+把 `ResourceReferenceInput` 拆成「纯输入区 + 宿主注入的引用 provider + 独立的选择器面板」，并让附件芯片成为本轮附件的唯一事实源。
+
+验收判据：
+
+1. 输入区不 import 任何具体引用种类，也不判断 `part.type` / `reference.type`：候选、身份解析、正文文本形态都经注入的 provider。
+2. 宿主按需选择性注入：只注入资源 → 只有 `@`；资源 + Skill → `@` 与 `$`；未注入的宿主连触发符都不存在，不需要额外的可见性开关。
+3. 素材选择器面板独立成组件、自己拿数据、由宿主渲染；输入区不再有 `versions` / `activeVersionId` / `showTriggerButton` / `onReferencePickerOpen` / `skills`。
+4. 附件导入成功后以芯片进入正文，失败或异常不插入；控制器不再持有附件数组，「待发送附件列表」删除；上限 8 按草稿中的附件芯片数计算；导入进行中禁止发送。
+5. 行为零变化：改名后芯片显示名自动刷新、打开面板前重读清单、`@`/`$` 候选与键盘交互、上限与失败提示文案逐条一致；唯一例外是已裁决的 Skill 可见性缺陷修复（非 DirectProject 宿主不再出现 `$`）。
+
+## 流程判定
+
+本次是无行为变化重构加两条已裁决缺陷修复（Skill 可见性、附件单一事实源），按轻量流程只建本实施计划，不新建主规范与里程碑规范；若评审要求补 SDD 里程碑，再单独补。
+
+## 提交切分
+
+1. **接口与 provider 工厂**：新增 `features/project-workspace/reference-source/types.ts`（`ReferenceProvider`）与四个工厂（资源 / Skill / 附件 / 运行画面区域），配规则矩阵单测：触发符有无、`match` 过滤、`toReference`、`refresh`（改名 / 删除 / 恒等）、`mentionToken`。
+2. **输入区接入注入**：输入区改为按 `providers` 派生候选菜单（不再写死两个触发符）、按数组顺序取第一个非空回答做草稿回填与改名刷新，删除 `skills` prop；测试夹具（22 处 `assets={assets}`）同批迁移为注入 provider。
+3. **面板外移**：素材选择器面板与缩略图预览搬进独立组件，宿主渲染并接线（`onConfirm → insertReferences`），输入区删除相关 props 与其死 CSS 规则（`styles.css` 里 `resource-reference-*` 共 78 条，逐条核对哪些随面板离开而失效）。
+4. **附件并入联合**：附件成为 `ChatReference` 成员，节点层收敛为单一节点类型，附件 chip 的 DOM 契约逐字保留（`data-attachment-reference`、`data-attachment-status`、`title`、移除按钮 `aria-label`）。
+5. **附件单一事实源**：`uploadFiles` 改为返回导入结果，composer 在导入成功后插入芯片、失败不插入；删除控制器附件状态、`ComposerPendingAttachments` 与提交时的附件 parts 拼接；上限改为按草稿芯片数计算，导入进行中禁止发送。
+6. **显示口径与文档**：`directCodexContentToPromptText` 的 token 前后补空白（不重复）并加 `// TODO we will rewrite this with ref as component later.`，显示名反查改由调用方注入；同步更新 `docs/【功能说明】AGC聊天素材引用-2026-09-08.md`（`ResourceReferenceInput` 共用口径、`@`/`$` 可见性、附件入口与上限口径都会变）。
+
+`resource-reference-*` 的 CSS 类名重命名（78 条规则 / 15 个文件 / 22 处测试断言）留作最后一个独立机械提交，必须与 `RESOURCE_REFERENCE_OVERLAY_SELECTOR` 常量同批修改。
+
+## 验证
+
+每个提交后跑定向用例：`npx vitest run apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx`，加上该提交触达的宿主用例（聊天 composer / 策划输入盒 / 画布生成面板 / 资源卡快速编辑）。全部完成后跑 `npm run typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`，再按验收判据第 5 条逐条对照行为。真实客户端手感（候选菜单位置、面板内滚轮、附件插入位置）留待真机验收，未执行前按未验证项记录。
+
+## 风险与回滚
+
+- 漏注入某个宿主会让该宿主静默失去候选；fail-closed 语义正确，但必须在用例里逐宿主覆盖。
+- `LexicalTypeaheadMenuPlugin` 由两个写死实例改为按 provider 派生后，Enter 让位与 Escape 关闭口径要重新覆盖（`mentionMenuOpenRef` 需聚合成「任一菜单开着」）。
+- 附件插入位置在异步导入期间可能漂移：导入失败一律不插入；文档或选区已改动时退到草稿末尾。
+- 删除 `ComposerPendingAttachments` 会连带影响样式与既有断言，属于预期内的行为收敛，需在提交说明里写清。
+- 回滚按提交粒度 revert；无数据迁移，canonical content 形状不变。
+
+## 执行状态（2026-09-22）
+
+已落地的提交内容：
+
+1. 接口与 provider 工厂：`features/project-workspace/reference-source/types.ts` + 四个工厂（资源 / Skill / 附件 / 运行画面区域），规则矩阵单测落在 `apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts`（触发符有无、`match` 过滤 / 去重 / 截断、`toReference`、`refresh`（改名 / 删除 / 恒等）、`mentionToken`、`isReady`、Skill 目录「首次 `match` 才读、失败可重试」）。
+2. 输入区接入注入：`providers` / `inputActions` / `submitSuppressed` 三个通用接缝；`skills`、`assets`、`versions`、`activeVersionId`、`showTriggerButton`、`openPicker` 全部删除；`ProviderMentionMenu` 按带触发符的 provider 派生（Enter 让位按 `mentionMenuOpenRef` 聚合）。
+3. 面板外移：`ResourceReferencePicker` + `ResourceReferencePickerAction` 由宿主渲染并接线（`onInsert → insertReferences`、`onOpenChange → submitSuppressed`），三个宿主的 `@` 触发钮位置逐处保持原样。
+4. 附件并入联合：附件成为 `ChatReference` 成员，编辑器只剩 `ResourceReferenceNode` 一种节点，附件 chip 的 DOM 契约逐字保留。
+5. 附件单一事实源：`uploadFiles(files, draftAttachmentCount)` 只返回导入成功的附件、失败不插入；控制器附件状态、`ComposerPendingAttachments`、提交时的附件 parts 拼接都删除；上限按草稿芯片数计算；导入进行中禁止发送。
+6. 显示口径与文档：`directCodexContentToPromptText(content, resolver)` 的 token 前后各补一个空白（不重复）并加 `// TODO we will rewrite this with ref as component later.`；显示名反查改由 `resourceLabelResolver(assets)` 注入；同步更新功能说明、ADR 与决策记录。
+
+顺带清理：`ProjectChatComponentProps.activeVersionId` 在策划输入盒不再有 `@` 触发钮之后已无消费方，随本次删除（工作台壳自己的那份仍归 `ProjectDevelopmentView`）。
+
+验证结果：`npx tsc -p tsconfig.json --noEmit`、`npm run typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 全通过；定向用例（`referenceSourceProviders`、`resourceReferenceInput`、`chatPromptPolish`、`resourceReferences`、画布生成面板、快速编辑、资源卡实时集成、`appSurface` 215 项、工作台壳清单合并 / 窗口同步、资源标签统计刷新、版本切换 / 替换）全绿。整仓 `npx vitest run` 仍有与本改动无关的既有环境失败（jsdom 缺 `localStorage`：`clientApi` / `clientAuthStorage` / `clientHttp` / `projectCreationDirectory` / `recentProjectsHook` 与 `src/components/image-editor/*` 若干），失败集合与本改动触及的模块不相交。
+
+未完成项：
+
+- `resource-reference-*` CSS 类名重命名（78 条规则 / 15 个文件 / 22 处断言）仍是独立机械提交，须与 `RESOURCE_REFERENCE_OVERLAY_SELECTOR` 同批修改；本次未动，输入区与面板的既有类名逐字保留。
+- 真实客户端手感（候选菜单位置、面板内滚轮、附件插入位置、`@` 触发钮落点）未做真机验收，按未验证项记录。
+- 粘贴解析仍不在本次范围（未来接入点是 provider 的 `mentionToken` 与既有 `buildContentFromTextTokens`）。
@@ -1,7 +1,30 @@
 # 决策记录

+## 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` 保持纯函数，懒加载走 `onMenuQueryChange`，由输入区在 effect 里回调；结果到了宿主重渲染，读取不进输入区），附件与运行画面区域为静默 provider（无触发符、无候选）；**没有总装 builder**，宿主按需选择性注入。provider 暴露 `trigger` / `match(query)` / `toReference(part)` / `refresh(reference)` / `mentionToken(part)` 与可选的 `onMenuQueryChange(query)`（菜单懒加载的唯一入口，`match` 保持纯函数）与 `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-22 release 每日调度纳入正式 Full Build 并收集结果
+
+- 背景：原 `Genarrative-Scheduled-Release-Trigger` 只处理 AGC Windows/macOS，且对下游使用 `wait: false` 后立即推进 revision；正式服务端 release 仍只能人工触发，客户端构建失败也不会回传调度器。
+- 决策：release 调度同时计算 `AGC` 与 `FullBuild` 两条 scope。服务端相关路径变化时以 `DEPLOY_TARGET=release`、`CONFIRM_RELEASE_DEPLOY_AGENT=true` 触发 `Genarrative-Full-Build-And-Deploy`；客户端相关路径变化时保持统一发号并触发 Windows/macOS release。Full Build、Windows、macOS 三路均等待结果并汇总，只有成功的 lane 才推进对应 `.jenkins-last-release-full-revision` / `.jenkins-last-release-agc-revision`，失败 lane 在下一轮单独补发，避免重复部署已成功的服务端版本。`DATABASE_BACKUP_MODE` 默认 `async`，并显式提供 `STDB_API_ROLLOUT_MODE` / approvers 以保留正式维护门禁。
+- 原因：正式 release 需要与 dev 小时调度隔离，同时不能继续依赖人工触发服务端；lane-level 成功状态可区分“已成功但另一 lane 失败”的部分发布，避免下一次调度重复发布 Full Build。
+- 影响范围：`jenkins/Jenkinsfile.scheduled-release-trigger`、`jenkins/scheduled-release-trigger-job-config.xml`、`scripts/check-production-ops-guardrails.mjs`、开发运维文档与共享开发工作流。
+- 验证方式：生产运维门禁检查 Full Build release 参数、双 scope、`wait: true` 结果聚合、三路分支和成功后才写 lane revision；并用 Jenkins 具体构建验证 Full Build/AGC 的 build number 与结果能回传到调度 Job。
+
 ## 2026-09-22 AGC release 增加每日调度，dev 调度保持双平台

+> 已被上一条决策取代：release 调度现已纳入正式服务端 Full Build。
+
 - 背景：原有 `Genarrative-Scheduled-Revision-Trigger` 每小时跟随 revision 发布 dev 客户端，但没有对应的 release 渠道自动入口；Mac 节点此前已纳入小时 dev 调度，需要避免新增 release 调度时再退回 Windows-only。
 - 决策：新增 `Genarrative-Scheduled-Release-Trigger`，每天 04:00 检查 `SOURCE_BRANCH`，使用独立的 `.jenkins-last-release-revision` 与客户端相关路径白名单；上一轮 release 调度后有客户端变更时，先经 `Genarrative-Agc-Global-Version-Issue` 发统一总号，再以同一固定 `COMMIT_HASH` 触发 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build` 的 `AGC_UPDATE_CHANNEL=release` 分区，Mac 继续带 `SKIP_IF_SUPERSEDED=true`。小时 dev 调度保持同时触发 Windows 与 macOS dev。
 - 原因：release 与 dev 是不同渠道和发布节奏，不能靠同一个小时 Job 隐式切换；独立 Job 能分别去重、记录状态和审计发号。release 调度不触发 Full Build，避免把桌面客户端发布与线上全栈部署绑定。
@@ -9375,6 +9398,17 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 影响面：`apps/ai-game-creator-shell/src/features/{project-workspace/resourceReferences.ts,project-workspace/ResourceReferenceInput.tsx,resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx,resource-canvas/resourceCanvasAssetGenerationTaskModel.ts,resource-canvas/resourceCanvasAssetGenerationReferenceModel.ts}`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx` 与对应 6 个定向测试文件。
 - 验证：定向 `resourceCanvasAssetGenerationReferences` / `resourceCanvasAssetGenerationBackgroundClose` / `resourceCanvasBottomToolbar` / `resourceCanvasGenerationFloatingPanel(Chrome)` / `resourceReferenceInput` / `resourceReferences` / `resourceCanvasAssetGenerationTasksPanel` 全绿；全量 `npm run test -- apps/ai-game-creator-shell/tests` 只剩 `clientHttp` / `clientApi` / `clientAuthStorage` / `projectCreationDirectory` / `recentProjectsHook` 五个 jsdom `localStorage` 环境用例红（与本次改动无调用关系）；TS typecheck、`check:encoding`、`git diff --check` 通过。未复核真实客户端观感。

+## 2026-09-22 运行页收口：过程提示退出对话区，顶栏统一承载运行入口
+
+- 背景：点播放（以及历史上 `/preview`、`/open-preview`、生成后自动启动预览）都会往对话区写一条 assistant 提示（`运行通过，已载入客户端运行视图：http://127.0.0.1:63155/` 这类）。它常驻对话底部遮挡运行画面，也让对话区混进非对话内容；运行页本身还有三处遮挡与两套皮：预览地址是一行常驻小字（不可点）、版本入口是绝对定位压在画面右上角的浮层、右上角还叠着「生成任务」开关。
+- 决策（对话区只留对话内容）：运行 / 预览的反馈不再进对话区，**成功与失败都**走工作台壳的 toast——`ProjectChatComponentProps.onRunNotice` → `RunNoticeToast`（同一句连续触发重新计时；成功 2.6 秒收起，失败 6 秒收起，`tone` 决定观感）。失败三处：启动预览报错（`运行游戏失败：…`）、缺 Tauri / 缺项目这两条前置条件、以及「在浏览器打开失败」。原先承载这些文案的 `announceProjectChatMessage` 已无调用方，连同删除。
+- 与上一条的关系（2026-09-21「预览激活回接运行入口」）：那条接线决策（先问 Rust 要活体预览、命中就只切视图不重启）原样保留；被本次改掉的只是它当时为这条链路选的**播报渠道**——`经 DirectProjectChatHandle.announce 说一句「已切换到客户端运行视图：<url>」` 按验收反馈（提示常驻对话底部遮挡运行画面）改成 toast，「复用活体预览不重启」的判据与 `tests/previewActivation.test.tsx` 的三条路径不变。
+- 决策（运行页顶栏是唯一入口）：运行区域上方的状态行与预览地址小字整体退役（运行画面回到两行栅格）；预览地址改成顶栏动作区里的一枚「在浏览器打开」按钮（opener 插件的 `openUrl`，只在有活预览时渲染；`scripts/check-native-shells.mjs` 另加「视图里 `openUrl(` 只有一个调用点」的判据）；版本入口搬进同一个顶栏动作区，外观复用 `.game-workbench-view-actions button` 的基础规则，不再自带边框 / 底色 / hover，也不再是绝对定位浮层。版本入口在**资源画布与运行页**显示，UI 编辑器壳里不渲染（那一页是聚焦编辑某个资源的界面）。版本名改用一层 span 承载省略号——按钮是 flex 容器，文本直接挂在按钮上时 `text-overflow` 不生效。
+- 决策（运行页不挂生成任务）：`ResourceCanvasAssetGenerationTasksPanelView` 只在资源画布 / UI 编辑器出现，运行页的入口、面板与锚点都不渲染；`[data-generation-tasks-placement='run']` 那一档坐标与组件 `placement` 联合类型里的 `run` 一并删除。任务不丢，切回资源页即可见。
+- 边界：预览的**启动与切换**仍然只走内置运行画面、不自动开系统浏览器——`scripts/check-native-shells.mjs` 那条负向守卫保持原样，本轮只补「浏览器入口只有顶栏这一枚按钮」的正向断言。
+- 影响面：`apps/ai-game-creator-shell/src/{App.tsx,styles.css,view/project-development/index.tsx,features/app-shell/*,features/resource-canvas/*}`；用例新增 `tests/runPreviewBrowserOpen.test.tsx`、`tests/runNoticeToast.test.tsx`、`tests/runNoticeShellWiring.test.tsx`（外壳级：替身聊天发提示 → 壳真的渲染浮层）、`tests/gameRunToolbarActionsStyle.test.ts`，改写 `tests/previewActivation.test.tsx`（原断言「聊天里出现已载入运行视图」的地方改为断言 toast 通道 + 对话容器里没有这类提示，并补一条「启动失败走失败色提示且不写对话区」）与 `tests/appSurface/project-development.suite.ts` 的生成任务入口用例。
+- 验证：`appSurface` 全量、AGC 壳目录全量、`npm run typecheck`、`check:native-shells:contract`、`check:encoding`、`git diff --check` 全绿；真机观感未复验。
+
 ## 2026-09-22 DirectProject 聊天状态显式化：回合三态 + 「在跑吗」唯一派生入口 + 数据流地图

 - 背景：DirectProject 聊天框只有三份真相源（`project.jsonl` 历史切片、Thread Manager 运行态事件、本地乐观消息），但「这一轮在跑吗」在四层里各叫一个名字——reducer 的 `turnRunning`、controller 的 `turnBusy`、视图里手拼的 `busy`、投影里的 `active`。定位发送后空窗缺陷时，读代码无法判断某个窗口期的界面表现是否有依据，也说不清谁该信谁。
@@ -92,7 +92,7 @@ SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.m

 ## Jenkins 定时版本调度

-定时与版本比较收口到两条调度器：`Genarrative-Scheduled-Revision-Trigger` 每小时处理 dev 渠道，变化时触发 Full Build、AGC Windows/macOS dev，并让两个客户端平台共用同一个总版本号；`Genarrative-Scheduled-Release-Trigger` 每天 04:00 处理 AGC release 渠道，只在上一轮 release 调度后出现客户端相关路径变化时，经 `Genarrative-Agc-Global-Version-Issue` 发同一个总号并触发 AGC Windows/macOS release。各下游 Job 都不得自带 `triggers` / `cron`，也不得在管线内再做一套版本去重；`npm run check:production-ops` 会拦住回退。macOS 节点是日常办公机，两条调度触发它时都置 `SKIP_IF_SUPERSEDED=true`：节点离线期间排队的旧构建在恢复后会自行让位，不发布过期版本。调度状态与生效步骤见 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+定时与版本比较收口到两条调度器：`Genarrative-Scheduled-Revision-Trigger` 每小时处理 dev 渠道，变化时触发 Full Build、AGC Windows/macOS dev，并让两个客户端平台共用同一个总版本号；`Genarrative-Scheduled-Release-Trigger` 每天 04:00 按服务端与客户端两条独立 scope 处理 release，服务端变化时用 `DEPLOY_TARGET=release` 触发正式 Full Build，客户端变化时经 `Genarrative-Agc-Global-Version-Issue` 发同一个总号并触发 AGC Windows/macOS release。两条调度都等待并汇总下游，按成功 lane 推进 revision；失败 lane 下一轮单独补发。各下游 Job 都不得自带 `triggers` / `cron`，也不得在管线内再做一套版本去重；`npm run check:production-ops` 会拦住回退。macOS 节点是日常办公机，两条调度触发它时都置 `SKIP_IF_SUPERSEDED=true`：节点离线期间排队的旧构建在恢复后会自行让位，不发布过期版本。调度状态与生效步骤见 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

 ## Gitea CI 依赖闭合

@@ -100,6 +100,8 @@ Gitea Rust 缓存自动维护由宿主 `genarrative-ci-cache.timer` 收集同一

 修改 Gitea workflow 的 job 显示名称、ID 或缓存导出组时，必须同步维护器的 `JOBS` / `RUST_JOB_IDS`；`test_gitea_cache_maintenance.py` 直接对照实际 workflow 检查全集和导出映射，避免自动刷新或镜像验收因名单漂移长期等待。维护器 `Api.request` 的 `method` 是必填关键字参数，GET 也必须显式指定，不根据 body 推断请求方法。

+Gitea 缓存部署必须区分网络：runner 的 RPC 走 `gitea-runner-fetch-gate:8080`；内层 job 的 checkout/上传走映射到 `172.30.0.3` 的 `http://genarrative-station/git`；宿主专用 clone 走 `http://127.0.0.1:3003`。不要把 runner 可达的 `gitea:3000` 配给 job。内层 Docker 使用 `10.240.0.0/16`、每 job `/24` 的默认地址池，避开外层 `172.30/172.31` 网段；恢复领取前必须在真实 job 网络里验证 checkout 与 Gitea API，不能只验证 FetchTask。具体配置与遗留空网络处理见 `deploy/container/README.md`。
+
 AGC Rust 两条 lane、crates、smoke、Backend 和桌面壳测试使用镜像内可信 sccache 对象快照；Native shell release step 显式清空双 wrapper，前端/repository checks 不启用。仅首次人工 bootstrap 时，维护者通过 `scripts/build-gitea-rust-cache.sh` 从远端 master 在限额、无宿主挂载的临时容器中按实际 cwd/profile/目标预热全部测试组，仅编译、不执行测试/应用；后端 workspace 与 spacetime-module 保持独立，AGC 的三个 cwd 入口之间清理预热 target，防止 fresh 判断漏产缓存键。最终镜像只追加 sccache、对象和来源元数据，不包含源码或 target。容量上限 4 GiB，不替代宿主旧镜像/归档清理。PR 只写当前容器层、不回传，不开放 Docker API/发布权限；继续禁用 incremental。`ci-rust-cache.sh` 在快照缺失、工具链不符或 wrapper 探测失败时直接编译，并隔离远程缓存配置和 daemon。分片日志记录编译耗时，收尾输出命中统计；两个 lane 的测试和前置检查不同，耗时差不是严格 A/B。线上存在活跃 CI 时不得重启 runner 或切换标签；全组启用前须刷新完整快照并逐组验证，详见开发运维文档。

 `.gitea/workflows/project-ci.yml` 的客户端门禁拆成 lane 与功能 job，每个 job 只预热自己会构建的那几份依赖：`AI game creator shell Rust lane 1/2`、`lane 2/2` 各自预取一次 AGC 壳 manifest，并顺序运行两片 Rust bin 单测；`AI game creator shell Rust smoke` 同样只预取 AGC 壳 manifest（`agent-run` smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`），`AI game creator shell Rust crates` 预取 `server-rs/Cargo.toml` 与独立 crate，`Native shell tests` 预取桌面壳与 AGC 壳 manifest，`AI game creator shell web tests` 不触碰 Cargo，不预热。两条 Rust lane、smoke job 与 crates job 只用 cargo 与 node 内建模块，因此不执行 `npm ci`。两个被 `server-rs/Cargo.toml` 排除、且没有提交 `Cargo.lock` 的独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）只能在 `AI game creator shell Rust crates` 里用不带锁标志的 fetch。AGC 壳的 bin target 单测（约 2466 条）由 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs` 编译后按 `--list` 名单分 4 片：每次分片调用用 `--shard-index=<i>` 只跑自己那片，片内保持 `--test-threads=1` 并使用独立 `TMPDIR`；两条 lane 之间并发，lane 内顺序运行两片，避免重复依赖预热和同一容器内多进程争抢。不要改回「一个 job 内多进程并行这几片」——同一容器里它们会争抢共享 `HOME`、target 目录与固定临时路径，实测比整套串行还慢。每个分片调用都会自校验「片并集等于全集且互斥」，因此改分片规则不会静默漏跑。Backend host workspace tests 使用 `cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`，避免 `spacetime-module` 的 `spacetime-types` feature 统一污染普通领域 crate 的 host 测试；随后单独执行 `cargo test --locked -p spacetime-module --no-fail-fast`，由 `spacetime-module/src/active.rs` 在 host 测试构建期间提供仅测试期的 SpacetimeDB ABI 链接支持，使该 crate 的纯单元测试也纳入 Backend 门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，host 链接支持不得被当作运行时替身。Backend 另外执行 `cargo check --locked -p spacetime-module` 验证模块源码。AGC 壳检查还会运行 `platform-llm` 与 `shared-contracts` 的 server-rs workspace 测试，这些命令以及 AGC 壳测试必须带 `--locked`，避免在测试阶段重新解析 registry index；锁文件发生变化时应先更新受信任 CI 镜像缓存，再重跑门禁。
@@ -1,5 +1,12 @@
 # 踩坑与排障记录

+## AGC 素材直传的 OSS 权限必须同步到 Native shell 契约检查
+
+- **现象**：Native shell CI 在 `check:native-shells:contract` 的 HTTP scope 检查失败，尚未准备 Rust 缓存；后续导出步骤正常退出但实际跳过，导致 master 缓存产物缺组、自动镜像刷新等待。
+- **原因**：`capabilities/main.json` 已为封面与截图直传加入 `https://*.aliyuncs.com/*`，`scripts/check-native-shells.mjs` 的精确白名单仍只有五项，且误以为更新下载迁至原生 updater 后就不再需要 OSS 权限。`assetDirectUpload.ts` 仍通过 Tauri HTTP 插件执行素材直传。
+- **处理**：契约期望同步包含现有 OSS HTTPS 项，保留完整白名单精确比较；不得删除业务所需权限或改成任意 URL 放行。更新下载与素材直传是不同调用链，变更能力配置时同步检查调用方和契约。
+- **验证**：运行 `npm run check:native-shells:contract` 与 `apps/ai-game-creator-shell/tests/assetDirectUpload.test.ts`；缓存完整性以实际 artifact 和导出日志为准，不能仅看上传 step 是否成功。
+
 ## release 安装包文件名中的编码空格不能按控制字符拒绝

 - **现象**：release 环境点击“下载客户端”只显示无法获取最新版本，`GET /api/client-downloads` 返回 `502 UPSTREAM_ERROR`；dev 环境正常。
@@ -50,6 +57,14 @@ Copy Artifact 插件在**非 SYSTEM 认证**下按「认证用户」判权：只

 `Genarrative-Manual-Build-And-Deploy` 的 `DEPLOY_TARGET=release` 只控制 Stdb / API / Web 全量发布，不会自动成为 AGC 的 `AGC_UPDATE_CHANNEL`。2026-09-21 的手工发布 #10 就因此让 Windows #107 与 macOS #16 使用默认 `dev`，把 `0.1.95` 上传到 `agc/dev-win`、`agc/dev-mac`，而 `agc/release-win/latest.json`、`agc/release-mac/latest.json` 保持 404。现行口径：手工入口按 `release -> release`、`development -> dev` 同时给 Windows 与 macOS AGC Build 传 `AGC_UPDATE_CHANNEL`；补发已烧号的同一版本时用相同 `AGC_RELEASE_VERSION` 直接重跑两条 AGC Job，不重新发号。OSS 发布对象是 `agc/<channel>-win|mac/`，不存在 `agc/release/` 这一层。

+## Jenkins 渠道参数会进入 Node 测试进程，默认值测试必须隔离环境
+
+- **现象**：release 渠道的 macOS Job 在 Tauri 构建前的 `build-release.test.mjs` 失败，唯一差异是 `no-bundle smoke skips version writes and manifest generation` 期望 `dev`、实际得到 `release`；构建尚未进入 Rust/Tauri 编译。
+- **原因**：Jenkins Job 参数 `AGC_UPDATE_CHANNEL=release` 会成为子进程环境变量，而该测试直接依赖未设置的默认渠道，却只显式传了 `--target` 和 `--no-bundle`。
+- **处理（现行口径）**：断言默认渠道、默认目标等环境派生值的测试，必须用现有 `withEnv` 显式清除相关变量；构建入口继续按 `AGC_UPDATE_CHANNEL` 选择渠道，不为迁就测试改生产逻辑。
+- **验证**：用 `AGC_UPDATE_CHANNEL=release node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs apps/ai-game-creator-shell/scripts/cargo-features.test.mjs` 复现并验证修复，未设置变量时也必须通过。
+- **关联**：`apps/ai-game-creator-shell/scripts/build-release.test.mjs`、`jenkins/Jenkinsfile.ai-game-creator-shell-macos-build`。
+
 ## 同一条链路两处上限不一致：平台合法产出被客户端整条丢弃

 - 现象：客户端报「生成素材失败：platform-generation-result-unknown: 异步生成完成结果无法绑定到 operationId：External Editor 旧同步结果的图集切片超过 64 个」，而平台侧这次生成**其实已经成功并切完图**（任务账本耗时正常、`assetId` 为空、没有任何素材落盘，付费产物被丢）。
@@ -6001,6 +6016,14 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`

 `append_application_log_line` 在落盘前对整行做 `sanitize_diagnostic_message`：行内只要出现 `token=`、`bearer `、`authorization`、`credential`、`api key` / `apikey` / `api_key` 这类标记，**整行**就被换成 `<sensitive diagnostic details redacted>`，只留下时间戳与 `RUST module:` 前缀；同时每行还会被截到 2048 字符。于是把“身份字段 + 诊断正文”拼成一行 `app_log!` 时，正文里一个凭据词就可能让整条记录连 `eventId`、`code` 一起消失（2026-09-21 加统一错误事件的日志投影时按两行落：身份行只放程序生成与调用方常量字段，summary / hint / detail 等自由文本一律只放详情行，且自由文本先自行压平换行——裸词标记脱敏消不掉，自由文本放错行会把 eventId、code 一起带走）。

+## 2026-09-22 本地 node_modules 里的内置 Codex 原生包过旧会让 AGC build script panic
+
+- **现象**：`npm run agc` 编到壳 crate 的 build script 时中止，stderr 是 `panicked at build.rs:103: Codex 原生包版本、布局或架构不匹配目标 x86_64-pc-windows-msvc`，stdout 只有 `cargo:rustc-env=AGC_BUILD_TARGET=...`。
+- **原因**：`build_support/codex_bundle.rs` 把随包 Codex CLI 钉在一个固定版本，而本地 `node_modules/@openai/codex-win32-x64/vendor/<target>/codex-package.json` 还停在上一次安装的旧版本。`package-lock.json` 早就升到新版本，缺的只是本地安装；这条判据只看版本元数据，文件齐全、架构正确也照样拦。
+- **处理（现行口径）**：在仓库根目录执行 `npm ci`（不要改成子目录或单包安装），随后 `node_modules/@openai/codex/package.json` 与 vendor 的 `codex-package.json` 版本应当一致。Windows 上 `npm ci` 会先 unlink 整个 `node_modules`：RustRover 的 Tailwind language server / `oxide-helper` 进程会占住 `@tailwindcss/oxide-*.node`，报 `EPERM: operation not permitted, unlink ...` 时先结束这些 helper 再重试，否则会停在半装状态。
+- **验证**：`npm ci` 后 `cargo build --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml` 通过，不再触发该 panic。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/build.rs`、`apps/ai-game-creator-shell/src-tauri/build_support/codex_bundle.rs`、`package-lock.json`。
+
 ## 策划聊天不能按可选子节点序号分配消息高度

 策划与开发 Agent 共用聊天类名，但布局合同不同。策划新增状态条后，按第二个子节点分配 `1fr` 会把空白给状态条、让消息框随回复增长；只给 `.is-direct-codex` 的状态样式也不会覆盖策划。策划使用纵向 Flex，仅消息列表伸缩，阶段/待处理区域限高滚动；改共用样式时同时核对两种入口。jsdom 交互通过不代表布局正确，须匹配完整 CSS 层叠并用真实浏览器核对空/短/长消息与长待办。窄屏上下堆叠必须在固定外壳内提供工作台滚动容器，两块面板明确限高；低优先级的 `height: auto` 不能覆盖外壳后代规则的 `height: 100%`。布局夹具必须包含窗口外壳与启动器层级，并实际滚动验证输入框可见可操作，不能只检查输入框在聊天面板内部。实时正文/思考不更新持久消息数组，滚动跟随必须覆盖这些独立状态并保留用户上滚门禁；历史消息缺失的时间不得用读取时刻填补。详见 AGC 实施计划的“策划 Agent 对话显示与滚动合同”。
@@ -137,8 +137,8 @@
 - 发布入口只解析一次目标，优先级为 CLI `--target value` / `--target=value` / `-t value`、`AGC_BUILD_TARGET`、Windows 默认值；重复/空目标与不支持目标失败关闭。版本高水位、构建 feature/渠道端点、bundle 路径、产物后缀、清单平台键及摘要必须消费同一个发布上下文，不能分别回读默认目标。
 - 渠道由 `AGC_UPDATE_CHANNEL` 显式指定，默认 dev；Windows 与 macOS 目标均支持 dev、release 和自定义渠道，目标校验独立进行。
 - 渠道 `--config` 在 Tauri 构建前最后合并，同时注入 `productName`、`identifier` 与 updater 端点：安装身份与更新端点必须来自同一个渠道，不能各自回读默认值。macOS 发布入口构建 `*.app`、updater 归档与 DMG 前先按发布渠道解析产品名，产物名一律派生而不写死。
- 定时调度只在本轮到达的提交包含 AGC 相关路径（客户端、共享包、`server-rs/crates`、AGC 插件、桌面壳图标、根依赖清单）时才触发渠道发布；纯文档或流水线自身的提交只跑 Full Build，不推高客户端版本号。判定失败或勾选强制触发时按"需要发布"处理。
- 更新摘要自动生成：发布脚本用渠道清单里的 `commit` 字段（上一次发布的提交）到本次提交之间、且只覆盖客户端相关路径的提交列表生成 `notes`（每条 `- 提交标题（短 SHA）`，最多 12 条、主题 80 字、整体 900 字，超出折叠或截断），同时写入旧协议清单的 `releaseNotes` 和归档文件 `release-notes.txt`。`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准；无法判定起点（缺少上次 `commit` 或本地没有该提交）时不写摘要。清单缺少 `commit` 时回退用上一次成功构建的 `COMMIT_HASH`（CI 通过 `AGC_UPDATE_PREVIOUS_COMMIT` 传入）作为锚点，因此首次启用摘要或更换渠道后也能立即产出摘要。锚点仍不可得（清单读取失败或没有 CI 锚点）时降级为「最近客户端改动」列表并注明可能与上一版重复 —— 摘要属于附注，任何情况下都不允许因为它让发布失败。
+- 定时调度分别判断服务端与客户端 scope：dev 小时调度在提交含 AGC 相关路径时发布对应渠道，纯文档或流水线自身的提交仍只跑 Full Build；release 每日调度在服务端相关路径变化时发布正式 Full Build，在 AGC 相关路径变化时发布 release 客户端，并在同一调度内等待、汇总各 lane 结果，失败 lane 下一轮补发。判定失败或勾选强制触发时按"需要发布"处理。
+- 更新摘要自动生成：发布脚本用渠道清单里的 `commit` 字段（上一次发布的提交）到本次提交之间、且只覆盖客户端相关路径的提交列表生成 `notes`（每条 `- 提交标题`，标题只取 commit message 第一行并忽略后续说明行；最多 12 条、主题 80 字、整体 900 字，超出折叠或截断），同时写入旧协议清单的 `releaseNotes` 和归档文件 `release-notes.txt`。`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准；无法判定起点（缺少上次 `commit` 或本地没有该提交）时不写摘要。清单缺少 `commit` 时回退用上一次成功构建的 `COMMIT_HASH`（CI 通过 `AGC_UPDATE_PREVIOUS_COMMIT` 传入）作为锚点，因此首次启用摘要或更换渠道后也能立即产出摘要。锚点仍不可得（清单读取失败或没有 CI 锚点）时降级为「最近客户端改动」列表并注明可能与上一版重复 —— 摘要属于附注，任何情况下都不允许因为它让发布失败。
 - 清单里的 `commit` 是非标准字段：更新插件忽略未知字段，发布脚本用它定位下一次摘要的起点。
 - 上传：安装包与 `.sig` 上传到 `agc/<channel>-win|mac/<version>/`，清单以 `--force` 覆盖上传到对应分区的 `latest.json`，保证 latest 指针与清单内 URL 指向已存在的对象。
 - 首装发布：发布脚本生成 `downloads`，Windows 复用已选 NSIS `.exe`，Mac 选择本次版本和目标架构匹配的非空 `.dmg`；缺失、歧义或版本/架构不匹配时失败，不发布带悬空地址的清单。上传顺序为更新包、签名及首装包全部成功后再更新渠道清单，Windows 相同对象只上传一次。`dry-run` 不写 OSS。各渠道独立写自己的清单，由 BFF 汇总，Windows 与 Mac 发布不会覆盖彼此的下载项；Mac 跨架构合并仍遵循现有单架构发布约束。
@@ -39,7 +39,7 @@ AGC 客户端此前按「渠道各自比高水位自增」发号：`dev-win` 与
 - 发号模块：`apps/ai-game-creator-shell/scripts/agc-global-version.mjs`（读总号 / 播种 / 发号 / 写后回读 / 渠道高水位断言 / dry-run 预览）。
 - 发号入口：`apps/ai-game-creator-shell/scripts/issue-global-version.mjs`（CI 与本地共用，输出固定为 `AGC_GLOBAL_VERSION=<version>`）。
 - 构建侧：`build-release.mjs` 的 `prepareReleaseVersion()` 优先采用传入总号，未传入时现场发号；`resolveRemoteHighWaterVersion()` 降级为断言来源，只用于「请求号低于本渠道清单版本即失败关闭」。
- CI：`jenkins/Jenkinsfile.agc-global-version-issue` + `jenkins/agc-global-version-issue-job-config.xml`；dev 调度管线 `jenkins/Jenkinsfile.scheduled-revision-trigger`、每日 release 调度管线 `jenkins/Jenkinsfile.scheduled-release-trigger` 与手动管线先调发号 Job，再把号透传给 AGC Build。
+- CI：`jenkins/Jenkinsfile.agc-global-version-issue` + `jenkins/agc-global-version-issue-job-config.xml`；dev 调度管线 `jenkins/Jenkinsfile.scheduled-revision-trigger`、每日 release 调度管线 `jenkins/Jenkinsfile.scheduled-release-trigger` 与手动管线先调发号 Job，再把号透传给 AGC Build；release 调度的服务端 Full Build 不使用 AGC 总号，只使用固定 `COMMIT_HASH` 与 Full Build 自身版本。
 - 发号 Job 的 Copy Artifact 采用生产权限模式，`options` 里的 `copyArtifactPermission(...)` 必须显式列出**全部**消费者：小时 dev 调度 `Genarrative-Scheduled-Revision-Trigger`、每日 release 调度 `Genarrative-Scheduled-Release-Trigger` 与手动发布 `Genarrative-Manual-Build-And-Deploy`。用户触发的构建按「认证用户」判权（SYSTEM 定时构建短路放行），漏列时手动发布会报 `Unable to find project for artifact copy: Genarrative-Agc-Global-Version-Issue`，且失败点在发号之后。改完该 `options` 后必须先单独跑一次发号 Job，让 Declarative Pipeline 把 Job property 写回 Jenkins。

 ## 不改的东西
@@ -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 目录，只在用户第一次敲出 `$` 时发生——输入区在 effect 里回调 provider 的 `onMenuQueryChange`，`match` 本身是纯函数；失败会放开重试）；
+- 附件与运行画面区域是**静默 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，见上一节）；