合入 master 并解决模板库分支冲突

- directActiveTurns：保留 master 的重试定时器清理与本分支的快照签名去重（两侧在同一位置相邻插入）
- directActiveTurns 测试：合并两侧用例（master 的定时器清理与面板用例 + 本分支的快照引用稳定用例）
- decision-log：两侧新增条目都保留（AGC 模板库约定 + CI 宿主 CPU 上限）
- 冲突后复核：cargo check 0 错误、tsc 通过、33 项前端单测通过、编码 / 文档索引 / diff 检查通过

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

@@ -3,6 +3,30 @@
 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 > 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
 
+## 2026-09-17 `agc_tools` 媒体资源提示词上限收敛为单一口径，并按 kind 暴露给模型
+
+- 背景：有人反馈「客户端没法由 agent 调用图片快速编辑功能以及背景音乐生成功能」。核查后工具本身都在（`agc_edit_image` / `agc_create_or_derive_resource`），图片快速编辑在 2026-09-14 的真实项目日志里也有成功记录；但存在三类真实缺陷：① `agc_create_or_derive_resource` 的 `prompt` 在 schema 里只声明 4000，真实上限却是按 kind 分的（背景音乐 140、音效 1900、视频/角色动画 4000、图片 32000），MCP 层还额外写死了一条 140 判断，模型从 schema 与 skill 都看不出 140/1900，写一句正常长度的背景音乐描述就当场被拒；② 客户端 UI 用同一口径但会截断并提示，agent 侧却只有硬拒，形成「UI 能做、agent 调不动」的观感；③ `sourceLocalAssetId` 不是已登记资源时只报「不属于当前项目已登记资源」，模型会原地重试而不会先登记。
+- 决策一（单一口径）：提示词上限只由 `resource_edit_prompt_max_chars` 给出，MCP 工具层、客户端受控工具桥与提交校验全部从它取数；超限文案复用 `resource_edit_prompt_limit_error`，保证模型看到的数字就是真实生效的数字。传输层边界只在信封级生效，不再用一个更小的通用常量先于按 kind 上限误报。
+- 决策二（按 kind 暴露）：`agc_create_or_derive_resource` 的 schema 用 `allOf[oneOf]` 逐 kind 声明 `prompt.maxLength`（background-music / sound-effect / video+character-animation），顶层 `maxLength` 等于各 kind 上限的最大值，`prompt` 描述里写明每个数字；`agc_edit_image` 继续用图片口径 32000。skill 包 `agc-client-projection`（SKILL.md 与 `references/projection-contract.md`）同步写明四个数字，并说明超限要在本地收敛而不是原样重发。
+- 决策三（可执行的前置提示）：源资源未登记时统一返回「先用 `agc_list_registered_assets` 选已有 localAssetId；文件只在项目里时先用 `agc_list_project_files` 确认 `assetImportable=true`，再用 `agc_import_account_assets.localPaths` 登记后重试」。本轮不放开「已完成任务产物」在 agent 侧的隐式正规化：登记是带副作用与 revision 推进的事务，必须由模型显式发起。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs`（上限与文案的唯一口径）、`agent/direct_tool_bridge.rs`（按 kind 判定与未登记源资源提示）、`agent/direct_tools_mcp.rs`（schema 与校验）、`resources/agc-skills/agc-client-projection/**` 与清单指纹（version `2026-08-26.18`）。**未改** `/api/external/v1` 契约与 OpenAPI、SpacetimeDB schema、前端 TS 侧 `resourceEditPromptMaxLength` 数字、客户端 UI 行为。
+- 验证方式：新增 `tool_prompt_limits_agree_with_the_client_authority`（四个 kind 的 schema 上限、MCP 校验与客户端权威口径同数字，超限文案带真实上限）、`bridge_resource_prompt_limits_follow_the_client_authority`（工具桥侧同类门禁，含图片编辑的 32000 边界）、`edit_image_tool_reaches_the_platform_image_edit_route` 与 `background_music_tool_reaches_the_platform_audio_route`（MCP 工具层 → 真实工具桥 → 假平台，断言 `/api/editor/images/edits` 与 `/api/editor/audios/background-music/generations` 的路径、Bearer、Idempotency-Key、正文与派生资源落盘，图片编辑正文不得回填 assetKind）、`background_music_prompt_over_the_limit_is_rejected_before_any_bridge_call`（超限在桥请求之前失败）、`unregistered_source_reports_the_registration_follow_up_tools`；`agent::direct_tools_mcp` 22 passed、`agent::skill_pack` 4 passed、`agent::direct_tool_bridge` 17 passed（7 条本机既有失败见下）、`npm run agc:skill-pack:check` 与 `skill-pack:test` 通过。本机 `tempfile::tempdir()` 归属校验失败导致的既有用例（`project::resource_editor` 45 条、`agent::direct_tool_bridge` 7 条）在本轮改动前后**同为失败**（stash 基线复跑确认），与本次无关。
+- 关联文档：[AI游戏创作智能体App实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)、[踩坑记录](pitfalls.md)。
+
+## 2026-09-16 抠图模式与背景色契约
+
+- External v1 抠图和 AGC `agc_remove_background` 支持 `complex`（语义分割识别前景）与 `flat`（纯色背景抠图）；明确纯色背景优先 flat，模式缺省仍为 complex，主站前端保持现有行为。
+- flat 的颜色允许 `auto`、`#RRGGBB` 或省略，自动识别完全由 BgFilter 负责。主站只校验、透传，不调用视觉模型选色；complex 携带颜色、非法值和空字符串在入队前拒绝。
+- 来源、名称、模式与颜色共同区分客户端请求意图；旧参数调用及旧 External 请求的幂等指纹须保持稳定。
+- 权威合同：[AGC 抠图模式与背景色透传](../../technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md)。
+
+## 2026-09-16 策划 Agent 工具执行退出项目级写锁并自动接续中断批次
+
+- 背景：策划 Agent 每个 `read_file` / `write_file` / `patch_file` 工具都在执行前竞争全局项目写锁，但同一会话已由 `.agent/design-agent/active.lock` 串行化，工具目标又限定在 `design_artifacts`；项目锁既不覆盖「工具 + 会话 checkpoint」事务，还把进程中断时的 `executing=true` 不确定窗口扩大到等锁与工具执行全程。真机项目出现 `pendingBatch.executing=true`、`function_call` 无配对 output、UI 只显示工作中且无错误的状态。
+- 决策：单次策划工具不再竞争项目级写锁，只保留策划命令锁与既有原子写入；GameAgent / DirectProject 的公共项目锁实现与调用不变。重开项目 hydrate 时，若命令锁可获取且当前批次处于 `executing=true`、当前 call 无 output，则自动续跑原回合：为该 call 补写「执行结果未保存」的工具错误、跳过剩余调用并交回 Provider 自愈；不得重放文件副作用，也不要求用户手动重试。
+- 验证：新增定向用例证明中断批次自动补齐工具 output、收到后续 assistant 回复、清空 pendingBatch 并结束原 turn，同时目标文件保持未修改（未重放 `patch_file`）；策划 Runtime 定向 14 条、策划工具 3 条通过，`cargo fmt --check`、`npm run check:encoding`、`git diff --check` 通过。
+- 关联文档：[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。
+
 ## 2026-09-16 AGC 同 AppData 多窗口共享 Agent Runner
 
 - 背景：双击或再次启动 AGC 客户端时报「应用启动失败」，启动日志为 `startup.runner.owner-lock.failed details=AI 游戏创作界面已由同一 AppData 目录中的其他进程运行`。原设计（2026-07-27 / 2026-08-23）要求同一 AppData 只有一个 GUI owner，第二个界面进程在 setup 阶段就失败退出。
@@ -8808,3 +8832,11 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策：模板库首页推荐位替换原「灵感推荐」本机图片目录（已删除 `InspirationGallery.tsx` 与 `assets/inspiration/`）；左侧导航新增模板库入口，打开独立全屏页。`tauri.conf.json` 的 `img-src` 放行受信任 OSS 主机用于封面图。
 - 关联规范：`docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`；开发期计划见 `docs/project-memory/plans/【里程碑】AGC模板库客户端接入-2026-09-17.md` 与对应实施计划。
 - 验证：Rust 模板库 8 项定向单测、前端模型 9 项单测、AGC `tsc` 类型检查通过；`templates/index.json` 匿名可读且每个 `zipKey` 回读 SHA-256 与清单一致；发布脚本 `scripts/agc-template-library-publish.mjs` 支持 `--dry-run` 与上传后回读校验。
+
+## 2026-09-16 CI 宿主 CPU 上限：Jenkins 16 核 / Gitea Actions runner 12 核
+
+- 背景：`genarrative-station`（32 逻辑核）上 Jenkins Built-In Node 与 Gitea Actions runner 共用同一宿主。Jenkins `jenkins.service` 原先没有任何 CPU 限制（`cpu.max=max`），构建期 Web / Api / Stdb 三分支并行（Vitest 8 线程 + 两次默认 32 job 的 cargo）把整机顶到 80%~95%；`gitea-runner` 容器 `--cpus=24`（75%）在 push 触发的 CI 波峰里实测峰值 24.8~25.3 核，是同一时间窗里更大的单一消耗方。
+- 决策：两路 CI 都设硬上限。Jenkins 侧 `systemctl set-property jenkins.service CPUQuota=1600%`（16 核 / 50%，覆盖 Built-In Node 上所有子构建，立即生效、无需重启，drop-in 落 `/etc/systemd/system.control/jenkins.service.d/50-CPUQuota.conf`）。runner 侧把 `/opt/gitea-stack/compose.yml` 的 `cpus` 由 `"24.0"` 改为 `"12.0"`（12 核 / 37.5%），并用 `docker update --cpus=12 gitea-runner` 让运行中的容器立即生效，不重建容器、不中断在跑 job。
+- 边界：Deploy 阶段在远端 dev / release agent 执行，不受该上限约束。调整只动这两处：`systemctl set-property / revert jenkins.service`、`docker update --cpus=<n> gitea-runner` 加同步 compose（备份 `/opt/gitea-stack/compose.yml.bak-<时间戳>`）。
+- 验证：限速后 `Genarrative-Full-Build-And-Deploy` #289 / #290 SUCCESS；采样期 Jenkins 峰值 10.2~10.5 核、限流不足 2s（可忽略），runner 峰值 12.07 核且持续出现 throttling，整机回落到 2.6%~19.8%。
+- 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)。

docs/project-memory/shared-memory/development-workflow.md

@@ -4,6 +4,10 @@
 
 ## 标准流程
 
+前端测试稳定性验证使用根目录 `npm test`（与 Frontend tests job 相同），保留 Vitest 的 8 worker 上限。涉及异步资源展示时，组件测试必须 mock 所有会触发的网络请求，每次调用创建独立 `Response`，并等待最终 DOM 状态而非仅等待 fetch 被调用。换签 Hook 的测试通过 `vitest.config.ts` 的 include 纳入全量运行；新增测试文件后需确认实际执行名单，命令参数指定文件不会绕过 include 白名单。排查顺序依赖可使用 `npm test -- --sequence.shuffle --sequence.seed=9467`，但不能以重试成功替代失败原因分析。
+
+用例隔离必须包括浏览器状态与 mock 实现：修改 `window.history` 后恢复基线路由；`spyOn(window, 'getSelection')` 等 spy 在用例结束后 restore；`clearAllMocks` 仅清调用记录，不能恢复被上一个用例替换的返回值。顺序打乱暴露的失败应修复泄漏来源，保留原有业务断言。
+
 ```text
 确认工作树与目标分支 → 读取入口和当前专题 → 查代码真相 → 小步修改 → 定向验证 → 更新当前文档/记忆 → 检查提交边界
 ```
@@ -47,6 +51,8 @@
 
 ## 验证路由
 
+AGC 运行时配置默认值调整时，同步核对 Rust 默认值、分发配置模板、设置弹窗默认草稿和 `runtime-settings.suite.ts` 的恢复默认断言；显式传入旧值的配置读取用例仍验证原值保留，不批量替换测试数据。
+
 AGC 测试构造单 HTML 项目时，必须在初始化之前写入 HTML，避免自动建立 npm 工程；npm 预览和导出测试应提供 dist 产物。已有图片生成 pending/operation 属于持久化恢复合同，修改工具默认参数后仍须验证旧动作恢复不重复提交、不因默认值变化被误判为新意图。
 
 SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.md`；该项目适配层按需调用已安装的官方 `spacetimedb` 插件 skill，插件提供通用 SDK/CLI/MCP 知识，项目 skill 负责 Genarrative 架构边界和验证门禁。

docs/project-memory/shared-memory/pitfalls.md

@@ -1,5 +1,34 @@
 # 踩坑与排障记录
 
+## 2026-09-17 AGC 输入盒的「推理档」弹层被祖先裁切：要放开裁切而不是挪弹层
+
+- **现象**：窄窗口下（视口 ≤1000px 时右侧对话面板只有 280px 宽）点开输入盒右下角的「推理档」，弹层是个**空盒子**：档位文字（默认 / 低 / 中 / 高 / 最高）整片看不见，只剩一个方框。
+- **成因**：推理档是控制排里最靠左的弹层锚点，`.conversation-model-menu` 默认 `right: 0` 贴触发钮右缘**向左**展开；触发钮右边还压着模型选择、语音、发送三颗钮，所以 150px 宽的弹层在 280px 面板里会伸到面板左侧 42px 之外。`.game-workbench-chat`、`.project-supervisor-surface.is-direct-codex`、`.project-supervisor-conversation` 三层各自的 `overflow: hidden` 沿自己的溢出边界裁掉它，而档位文字起点才 14px（面板左内边距 5px + 按钮左内边距 9px），正好落在被裁掉的那半边。
+- **处理（用户指定口径）**：不挪弹层位置——只让 direct-codex 那三层不再裁切：`.game-workbench-chat:has(.project-supervisor-composer.is-direct-codex)`、`.game-workbench-chat .project-supervisor-surface.is-direct-codex`、`.game-workbench-chat .project-supervisor-surface.is-direct-codex .project-supervisor-conversation` 三条 `overflow: visible`。弹层的 `right: 0`、尺寸和触发钮锚点全不变，只是允许它盖到左侧资源面板上完整显示。消息列表自带 `overflow-y: auto`（另一轴按规范计算为 auto），消息内容仍由列表自身裁剪。
+- **易错点**：① 把弹层改成 `left: 0` 或往右挪也能让它可见，但那是改变展开方向，弹层会跑到触发钮右边（用户明确否决）；② 只放开最外层聊天列不够——surface 与 conversation 各自都会裁，三层必须同时放开；③ 只按宽度比大小会误判：280px 面板里控制排本身也超出（发送钮右侧溢出 22px，被窗口右缘吃掉），那不是本条的原因，别顺手去改控制排布局。
+- **验证**：`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts` 的 `keeps the landscape workbench edge-to-edge with internal chat scrolling` 钉住三条 override 声明在场（删掉任一条即红）。真机几何用 playwright-cli 打开一份只含真实 `styles.css` 与真实 composer DOM 的最小复现页实测（视口 1000×700、面板 280px）：弹层 rect 修复前后都是 `[-42, 108]`（位置未动），`elementFromPoint` 的命中区间从修复前的 `[2, 108]` 变成整块；档位文字在截图中完整可见。
+- **关联**：`apps/ai-game-creator-shell/src/styles.css`（`面板纵向布局（2026-07 Codex 风格改造）` 区块之后）、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。
+
+## DirectProject 历史不能按工具条目切页再按消息推进游标
+
+原始 `response_item` 历史同时含用户/助手消息、推理与工具输出。若原生每次取 20 个原始条目、前端过滤聊天消息后再找最旧 ID，纯工具页会让消息集合为空且游标不动，看起来历史丢失。聊天读取固定显式请求 `messagesOnly: true`，原生逐行过滤后按消息分页并返回 `oldestItemId`；默认原始模式留给原始条目消费者。无 ID 旧消息保留并扩展到可寻址边界，不能造 ID。前端保留项目与读取代次、单飞及 ID 去重，旧请求的成功、失败与 finally 都不能覆盖新读取；真实日志只在临时目录只读重放，不能提交正文夹具。
+
+## JSON 卡片显示与 UI 编辑能力必须同源
+
+JSON 的文本读取分支不等于卡面应该展示原始 State 摘要。卡片、缩略图及编辑器入口共同消费受控文本预览的 `uiDesignAssetId`；只有原生复用 UI 持久化合同校验 schema、完整 State 和项目/资产身份后才设置它。普通 JSON 保留 JSON 代码预览，不按 `kind: UI/ui` 或 schema 字符串片段猜测编辑能力。已有合法 UI State 的加载/保存不依赖 kind 精确大小写，但新建初始化仍保留正式 UI 资产门禁；缓存与项目切换须保留现有身份隔离。
+
+## 窗口 Context 发布不得依赖每次渲染新建的业务回调
+
+工作台向窗口标题栏发布运行项目时，若 effect 依赖普通函数派生的回调，发布 Context 会重新渲染工作台，进而再次发布并清理，形成更新深度循环。转发入口须稳定，并在提交阶段更新实际处理器引用；发布数据变化与卸载清理分开。回归测试必须组合真实窗口 Provider 和工作台消费者，只有独立画布测试无法覆盖这条反馈链；回归时用有界发布次数阻止测试失控。画布快速操作时暴露的更新深度错误，也须检查外层状态同步，不能直接归因于滚轮频率。
+
+## 2026-09-17 工具 schema 声明的上限与真实校验不一致，会表现成「agent 调不动这个功能」
+
+- **现象**：用户反馈「客户端没法由 agent 调用图片快速编辑功能以及背景音乐生成功能」。查工具目录时两个工具都在（`agc_edit_image`、`agc_create_or_derive_resource`），图片快速编辑在真实项目日志里还有成功记录；但 agent 侧写一句正常长度的背景音乐描述就失败，而客户端 UI 用同一个提示词却只是被截断加提示。
+- **原因**：`agc_create_or_derive_resource.prompt` 在 MCP schema 里只声明 `maxLength: 4000`，真实上限按 kind 分（背景音乐 140 / 音效 1900 / 视频、角色动画 4000 / 图片 32000），MCP 层还额外写死一条 `kind == background-music && > 140` 的判断；skill 包没有任何一处写这两个数字。模型从 schema 与 skill 都无法得知 140，于是必然踩一次硬拒。同类隐患还有两处：客户端工具桥用通用 4000 校验 prompt，会把 4000 以上的图片编辑提示词误报成「超出安全边界」；按 kind 校验散落在 MCP 与桥两处，新增类型容易只改一处。
+- **处理**：上限收敛到 `resource_edit_prompt_max_chars` 单一权威（工具层、桥、提交校验共用），超限文案复用 `resource_edit_prompt_limit_error`；工具 schema 用 `allOf[oneOf]` 逐 kind 声明 `prompt.maxLength` 并在描述里写明数字；prompt 的传输层边界退到信封级，避免通用常量先于按 kind 上限报错；两端 skill 文档同步写明四个数字。新增 `tool_prompt_limits_agree_with_the_client_authority` 作为门禁：四类 kind 的 schema 上限、桥上限与权威口径必须同数字，且超限文案必须带真实上限。
+- **验证**：`cargo test --bin genarrative-ai-game-creator-shell -- --test-threads=1 agent::direct_tools_mcp::tests`（22 passed，含两条走 MCP 工具层 → 真实工具桥 → 假平台的媒体工具契约用例与一条超限零请求用例）、`agent::direct_tool_bridge::tests`（17 passed，含新增的按 kind 上限门禁；另有 7 条本机既有失败）、`agent::skill_pack`（4 passed）、`npm run agc:skill-pack:check`。本机 `tempfile::tempdir()` 归属校验失败会让 `project::resource_editor` 45 条与 `agent::direct_tool_bridge` 7 条既有用例失败，改动前后同为失败，不要据此误判回归。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs`、`src-tauri/src/agent/direct_tool_bridge.rs`、`src-tauri/src/agent/direct_tools_mcp.rs`、`src-tauri/resources/agc-skills/agc-client-projection/`。
+
 ## 2026-09-16 从 Codex 里启动 AGC 客户端会看到被重定向的 `%APPDATA%`
 
 - **现象**：在 Codex 会话里用 `Start-Process` 启动 `genarrative-ai-game-creator-shell.exe` 做排障时，子进程写 `C:\Users\<user>\AppData\Roaming\world.genarrative.ai-game-creator\...` 的内容会落到 `C:\Users\<user>\AppData\Local\Packages\OpenAI.Codex_2p2nqsd0c76g0\LocalCache\Roaming\...`；同一个 `Test-Path` / `Get-ChildItem` 命中的是重定向视图，只有 `\\?\C:\Users\...` 形式能区分真实路径。