修复资源登记把任意图片写成 ui 类型

停用本地导入图片的 ui 默认 kind：agent_local_project_file_type 的图片扩展名分支改写 canonical image（派生 unclassified，落「待归类」），并注明不许把 ui 当图片默认值及其不可恢复原因——读时自愈只在落盘 category 为 unclassified 时触发，kind 本身写错时自愈只会把错值放大成 ui-interaction 账户素材导入改用平台真实类型：新增 imported_platform_asset_kind，账户素材库记录自带的 assetKind 不再被常量 ui 顶掉，缺失才退回中性 image 平台素材导入改用响应里的 assetKind：网页项目画布与平台素材导入同样走 imported_platform_asset_kind，不再写死 ui 上传素材按内容证据推导 kind：upload_local_asset_at 不再把来源词 uploaded 当类型，改由 uploaded_asset_kind 按 mediaType 与扩展名推导 audio/video/image/document/code，判不出才用中性 asset；同一命令也收 .wav 与 .md，因此不能一刀切成 image 补 4 处回归与反查用例：本地导入与上传断言落盘 kind 与 category 且不得出现 ui、ui-interaction、uploaded；两处平台导入的 kind 解析加纯函数单测与调用点反查门禁；变异把错值改回来必须变红（M1/M2/M3 实测 4 个用例全红，还原后 diff 与基线逐字节一致）覆盖边界：账户素材库与平台素材导入是异步 HTTP 路径，仓库内没有可复用的端到端夹具，这两条覆盖是纯函数单测加调用点反查门禁，不是端到端断言；本地导入与上传是读落盘 manifest 的行为级断言后续事项：ImportedAsset.asset_kind 仍返回平台原始值（缺失为 none），与已落盘 kind 可能不一致，本次未改动
pitfalls：补记「同一条命令的口径差异」——CI 用提交范围比较 git diff --check
2026-09-12 02:30:31 +08:00 · 2026-09-12 02:07:49 +08:00 · 2026-09-12 02:02:12 +08:00 · 2026-09-12 01:28:05 +08:00 · 2026-09-12 01:15:11 +08:00 · 2026-09-12 01:09:37 +08:00
202 changed files with 40508 additions and 33846 deletions
@@ -371,7 +371,15 @@ async function runMissingConfigWizard(setActiveChild, explicitConfigDir) {
  }
 }

-async function secureWindowsPrivateRuntimePath(targetPath, options) {
+async function secureWindowsPrivateRuntimePath(
+  targetPath,
+  options,
+  secureWindowsPath = null,
+) {
+  if (secureWindowsPath) {
+    await secureWindowsPath(targetPath, options);
+    return;
+  }
  const { secureWindowsGameCreatorPathForCurrentUser } = await import(
    './game-creator-config-wizard.mjs'
  );
@@ -383,6 +391,7 @@ async function copyPrivateRuntimeConfigEntry(
  runtimeConfigDir,
  fileName,
  required,
+  secureWindowsPath = null,
 ) {
  const sourcePath = path.join(sourceConfigDir, fileName);
  const sourceMetadata = await lstat(sourcePath).catch((error) => {
@@ -402,9 +411,11 @@ async function copyPrivateRuntimeConfigEntry(
    const sourceBytes = await readFile(sourcePath);
    const destinationFile = await open(destinationPath, 'wx', 0o600);
    try {
-      await secureWindowsPrivateRuntimePath(destinationPath, {
-        isDirectory: false,
-      });
+      await secureWindowsPrivateRuntimePath(
+        destinationPath,
+        { isDirectory: false },
+        secureWindowsPath,
+      );
      await destinationFile.writeFile(sourceBytes);
      await destinationFile.sync();
    } finally {
@@ -437,7 +448,11 @@ async function copyPrivateRuntimeConfigEntry(
  return true;
 }

-export async function prepareSwarmTestRuntimeConfig(sourceConfigDir, tempRoot) {
+export async function prepareSwarmTestRuntimeConfig(
+  sourceConfigDir,
+  tempRoot,
+  { secureWindowsPath = null } = {},
+) {
  if (!path.isAbsolute(sourceConfigDir)) {
    throw new Error('配置来源目录必须是绝对路径');
  }
@@ -457,9 +472,11 @@ export async function prepareSwarmTestRuntimeConfig(sourceConfigDir, tempRoot) {
  );
  try {
    if (process.platform === 'win32') {
-      await secureWindowsPrivateRuntimePath(runtimeConfigDir, {
-        isDirectory: true,
-      });
+      await secureWindowsPrivateRuntimePath(
+        runtimeConfigDir,
+        { isDirectory: true },
+        secureWindowsPath,
+      );
    } else {
      await chmod(runtimeConfigDir, 0o700);
    }
@@ -477,12 +494,14 @@ export async function prepareSwarmTestRuntimeConfig(sourceConfigDir, tempRoot) {
      runtimeConfigDir,
      configFileName,
      true,
+      secureWindowsPath,
    );
    await copyPrivateRuntimeConfigEntry(
      canonicalSourceConfigDir,
      runtimeConfigDir,
      localConfigFileName,
      false,
+      secureWindowsPath,
    );
    return {
      path: await realpath(runtimeConfigDir),
@@ -1,7 +1,7 @@
 {
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main",
-  "description": "AI 游戏创作主窗口允许读取系统剪贴板图片，用于粘贴素材附件。",
+  "description": "AI 游戏创作主窗口允许读取系统剪贴板图片，用于粘贴素材附件；允许弹出原生打开/保存对话框用于素材上传与导出。",
  "windows": ["client"],
  "permissions": [
    "clipboard-manager:allow-read-image",
@@ -21,6 +21,7 @@
      ]
    },
    "opener:default",
-    "dialog:allow-open"
+    "dialog:allow-open",
+    "dialog:allow-save"
  ]
 }
@@ -0,0 +1 @@
+你是游戏创作需求的润色助手。把用户给创作 Agent 的一段需求改写成更清晰、可执行的中文需求。要求：保留用户的原始意图、玩法、美术方向、数值与限制条件，不得新增或删除需求点，不得替用户做决定，不得写成方案书或任务清单。只输出润色后的需求正文，不要解释、不要引言、不要 Markdown 标记、不要引号包裹、不要重复用户原文；无法润色时原样输出用户输入。
@@ -14,6 +14,7 @@ mod codex_cli;
 mod codex_provider_proxy;
 mod direct_codex_attachments;
 mod direct_codex_audit;
+mod direct_codex_references;
 mod direct_project_history;
 mod direct_project_turn_history;
 mod direct_runtime;
@@ -40,6 +41,7 @@ pub(crate) use codex_cli::{
 pub(crate) use codex_provider_proxy::*;
 pub(crate) use direct_codex_attachments::*;
 pub(crate) use direct_codex_audit::*;
+pub(crate) use direct_codex_references::*;
 pub(crate) use direct_project_history::*;
 pub(crate) use direct_project_turn_history::*;
 pub(crate) use direct_runtime::*;
@@ -16,7 +16,21 @@ const GAME_CREATOR_CODEX_APP_SERVER_REMOTE_CONTROL_DISABLED_ENV: &str =
    "CODEX_INTERNAL_APP_SERVER_REMOTE_CONTROL_DISABLED";
 const GAME_CREATOR_CODEX_AUTH_BRIDGE_API_BASE_URL: &str = "https://api.openai.com/v1";
 const GAME_CREATOR_CODEX_APP_SERVER_PROTOCOL: &str = "genarrative-codex-app-server.v3";
-const GAME_CREATOR_CODEX_APP_SERVER_LINE_MAX_BYTES: usize = 4 * 1024 * 1024;
+/// 单条 JSON-RPC 消息（NDJSON 一行）的字节上限：**同时**是 stdout 读侧上限与 stdin 写侧守卫。
+///
+/// 两侧必须共用这一个常量。2026-09-11 的隔离探针实测（codex-cli 0.147.0，AGC 捆绑版本）：
+/// `experimentalRawEvents: true` 的线程收到 `thread/inject_items` 后，会**逐条原样回显**
+/// `rawResponseItem/completed` —— 注入一个 5 MiB 的 item，stdout 就回一条 5 243 245 字节的单行。
+/// 因此「我们注入得进去」就必须「我们读得回来」；两侧取不同值（曾为读侧 4 MiB、图片单张 5 MiB／
+/// 单次 16 MiB）会让一次**原本合法**的注入在随后的读行里被误判成连接级故障。
+///
+/// 32 MiB 的依据：单张图 base64 data URL 上限 10 MiB（`..._IMAGE_MAX_BYTES * 2`）、单次请求图片
+/// 总量上限 16 MiB（`..._IMAGE_TOTAL_MAX_BYTES`，base64 后约 21.3 MiB）+ JSON 信封，取 32 MiB
+/// 覆盖现有写侧全部单一消息；再大就失去内存/DoS 边界的意义（每连接单行最多驻留该数量级）。
+const GAME_CREATOR_CODEX_APP_SERVER_LINE_MAX_BYTES: usize = 32 * 1024 * 1024;
+/// 回显信封余量：item 会被包进 `{"method":"rawResponseItem/completed","params":{…,"item":…}}`
+/// 之后再输出，所以**单条 item** 允许占用的字节数必须小于整行上限。
+const GAME_CREATOR_CODEX_APP_SERVER_ECHO_ENVELOPE_MARGIN_BYTES: usize = 8 * 1024;
 const GAME_CREATOR_CODEX_APP_SERVER_STDERR_RECORD_MAX_BYTES: usize = 256 * 1024;
 const GAME_CREATOR_CODEX_APP_SERVER_AUTH_MAX_BYTES: usize = 1024 * 1024;
 const GAME_CREATOR_CODEX_APP_SERVER_BACKLOG_TURN_MAX: usize = 128;
@@ -44,6 +58,13 @@ pub(in crate::agent) const GAME_CREATOR_CODEX_APP_SERVER_TERMINAL_UNKNOWN_PREFIX
    "codex-app-server-terminal-unknown:";
 pub(in crate::agent) const GAME_CREATOR_CODEX_APP_SERVER_ERROR_KIND_PREFIX: &str =
    "codex-app-server-error:";
+/// DirectProject 历史注入超限：专属前缀，供 `direct_runtime.rs` 判「可重试性」与给专属恢复提示。
+///
+/// 命中它意味着**同一份历史每次都会得到同一结论**（历史文件不变则载荷不变），所以按不可重试
+/// 处理，与 `DIRECT_PROJECT_HISTORY_SHAPE_FAILURE_MARKERS` 同口径（见技术方案
+/// `docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md` 末节）。
+pub(in crate::agent) const DIRECT_PROJECT_HISTORY_INJECTION_OVERSIZE_PREFIX: &str =
+    "DirectProject 历史注入载荷超过单行上限";
 const CODEX_APP_SERVER_BASE_INSTRUCTIONS_FALLBACK: &str =
    "You are Codex working directly in the user's Genarrative game project. Follow the AGC system instructions, inspect and modify files in the current workspace when needed, and report concrete progress and failures. Do not invent completion evidence.";
 const DIRECT_CODEX_BASE_INSTRUCTIONS_FALLBACK: &str =
@@ -2296,6 +2317,11 @@ impl CodexAppServerConnection {
        let mut bytes = serde_json::to_vec(value)
            .map_err(|error| format!("序列化 Codex app-server JSON-RPC 失败：{error}"))?;
        bytes.push(b'\n');
+        // 写侧守卫：绝不写出自己读不回来的行（两侧共用 `..._LINE_MAX_BYTES`）。
+        // 失败关闭并给出字节数，**不做任何截断**。
+        if let Some(error) = game_creator_codex_app_server_message_oversize_error(bytes.len()) {
+            return Err(error);
+        }
        let mut writer = self.inner.writer.lock().await;
        writer
            .write_all(&bytes)
@@ -2616,13 +2642,18 @@ impl CodexAppServerConnection {
                        return Err(platform_llm::LlmError::InvalidRequest(error));
                    }
                };
-                if let Err(error) = self
-                    .request(
-                        "thread/inject_items",
-                        serde_json::json!({"threadId": thread_id, "items": items}),
-                    )
-                    .await
+                let params = serde_json::json!({"threadId": thread_id.clone(), "items": items});
+                let payload_bytes = serde_json::to_vec(&params)
+                    .map(|bytes| bytes.len().saturating_add(1))
+                    .unwrap_or(usize::MAX);
+                // 注入前的前置校验：失败关闭并指名 itemId 与字节数，**不截断、不摘要、不改写**。
+                if let Some(error) =
+                    direct_project_history_injection_oversize_error(&params, payload_bytes)
                {
+                    self.release_thread(snapshot, &thread_id).await;
+                    return Err(platform_llm::LlmError::InvalidRequest(error));
+                }
+                if let Err(error) = self.request("thread/inject_items", params).await {
                    self.release_thread(snapshot, &thread_id).await;
                    return Err(platform_llm::LlmError::Transport(error));
                }
@@ -3429,6 +3460,61 @@ async fn read_game_creator_codex_app_server_stdout(
    }
 }

+/// 写侧守卫的纯函数部分（便于单测）：超限时给出带字节数的错误。
+///
+/// 与读侧共用同一个上限，保证「我们能注入的」一定「我们读得回来」。
+fn game_creator_codex_app_server_message_oversize_error(byte_len: usize) -> Option<String> {
+    let limit = GAME_CREATOR_CODEX_APP_SERVER_LINE_MAX_BYTES;
+    (byte_len > limit).then(|| {
+        format!(
+            "Codex app-server JSON-RPC 单行超过大小上限（写侧）：{byte_len} 字节 > 上限 {limit} 字节；未发送、未截断"
+        )
+    })
+}
+
+/// DirectProject 历史注入的前置校验（纯函数，便于单测）。
+///
+/// 判据来自实测：app-server 会把注入的 item **逐条原样回显**，所以
+/// ① 单条 item 必须 ≤ 上限 − 回显信封余量；② 整份载荷本身也必须 ≤ 上限。
+/// 任一不满足即**失败关闭**（指名 `itemId` 与字节数），**不截断、不摘要、不改写**历史。
+fn direct_project_history_injection_oversize_error(
+    params: &serde_json::Value,
+    payload_bytes: usize,
+) -> Option<String> {
+    let limit = GAME_CREATOR_CODEX_APP_SERVER_LINE_MAX_BYTES;
+    if payload_bytes > limit {
+        return Some(format!(
+            "{DIRECT_PROJECT_HISTORY_INJECTION_OVERSIZE_PREFIX}：整份历史载荷 {payload_bytes} 字节 > 上限 {limit} 字节；未注入、未截断"
+        ));
+    }
+    let Some(items) = params.get("items").and_then(serde_json::Value::as_array) else {
+        return None;
+    };
+    let item_limit = limit.saturating_sub(GAME_CREATOR_CODEX_APP_SERVER_ECHO_ENVELOPE_MARGIN_BYTES);
+    for item in items {
+        let Ok(bytes) = serde_json::to_vec(item) else {
+            return Some(format!(
+                "{DIRECT_PROJECT_HISTORY_INJECTION_OVERSIZE_PREFIX}：历史记录无法序列化；未注入、未截断"
+            ));
+        };
+        if bytes.len() > item_limit {
+            let item_id = item
+                .get("id")
+                .and_then(serde_json::Value::as_str)
+                .unwrap_or("<无 id>");
+            let item_type = item
+                .get("type")
+                .and_then(serde_json::Value::as_str)
+                .unwrap_or("<无 type>");
+            return Some(format!(
+                "{DIRECT_PROJECT_HISTORY_INJECTION_OVERSIZE_PREFIX}：单条记录 {} 字节 > 单条上限 {item_limit} 字节（itemId={item_id}, type={item_type}）；未注入、未截断",
+                bytes.len()
+            ));
+        }
+    }
+    None
+}
+
 async fn read_bounded_game_creator_codex_app_server_line<R>(
    reader: &mut R,
 ) -> Result<Option<Vec<u8>>, String>
@@ -5437,6 +5523,66 @@ while IFS= read -r line; do :; done
        assert!(!diagnostic.contains(std::str::from_utf8(&secret).expect("fixture utf8")));
    }

+    /// 写侧对称守卫：我们绝不写出自己读不回来的行。
+    ///
+    /// 与上面那条读侧用例共用 `..._LINE_MAX_BYTES`，所以这条断言同时锁住「两侧同界」这个不变量：
+    /// 上限本身必须放行，上限 + 1 必须失败关闭（而不是被静默截断）。
+    #[test]
+    fn codex_app_server_write_guard_matches_the_read_cap() {
+        assert!(game_creator_codex_app_server_message_oversize_error(
+            GAME_CREATOR_CODEX_APP_SERVER_LINE_MAX_BYTES
+        )
+        .is_none());
+
+        let oversized = GAME_CREATOR_CODEX_APP_SERVER_LINE_MAX_BYTES + 1;
+        let error = game_creator_codex_app_server_message_oversize_error(oversized)
+            .expect("oversized outbound message must be rejected before it is written");
+        assert!(error.contains("单行超过大小上限（写侧）"));
+        assert!(error.contains(&oversized.to_string()));
+        assert!(error.contains("未发送、未截断"));
+    }
+
+    /// DirectProject 历史注入的前置校验：**单条 item** 与**整份载荷**都必须失败关闭。
+    ///
+    /// 形状照抄实测（隔离探针，codex-cli 0.147.0）：`thread/inject_items` 注入的 item 会被
+    /// app-server 逐条原样回显成一条 `rawResponseItem/completed`，所以「单条 item 超限」就等于
+    /// 「回显行超限」——必须在注入前拦下，而不是让它在读行时变成连接级故障。
+    #[test]
+    fn direct_project_history_injection_rejects_oversized_items_and_payloads() {
+        let ok_params = serde_json::json!({
+            "threadId": "probe-thread",
+            "items": [{ "type": "message", "id": "msg_1", "role": "user" }],
+        });
+        assert!(direct_project_history_injection_oversize_error(&ok_params, 1024).is_none());
+
+        let payload_error = direct_project_history_injection_oversize_error(
+            &ok_params,
+            GAME_CREATOR_CODEX_APP_SERVER_LINE_MAX_BYTES + 1,
+        )
+        .expect("oversized payload must be rejected");
+        assert!(payload_error.contains(DIRECT_PROJECT_HISTORY_INJECTION_OVERSIZE_PREFIX));
+        assert!(payload_error.contains("整份历史载荷"));
+        assert!(payload_error.contains("未注入、未截断"));
+
+        let huge = "x".repeat(GAME_CREATOR_CODEX_APP_SERVER_LINE_MAX_BYTES);
+        let big_params = serde_json::json!({
+            "threadId": "probe-thread",
+            "items": [{
+                "type": "message",
+                "id": "msg_big",
+                "role": "assistant",
+                "content": [{ "type": "output_text", "text": huge }],
+            }],
+        });
+        let item_error = direct_project_history_injection_oversize_error(&big_params, 1024)
+            .expect("oversized single item must be rejected");
+        assert!(item_error.contains(DIRECT_PROJECT_HISTORY_INJECTION_OVERSIZE_PREFIX));
+        assert!(item_error.contains("单条记录"));
+        assert!(item_error.contains("itemId=msg_big"));
+        assert!(item_error.contains("type=message"));
+        assert!(item_error.contains("未注入、未截断"));
+    }
+
    #[cfg(unix)]
    #[tokio::test]
    async fn codex_app_server_uses_initialize_thread_and_turn_protocol() {
@@ -0,0 +1,328 @@
+use super::*;
+
+pub(crate) const MAX_DIRECT_CODEX_REFERENCES: usize = 32;
+const MAX_DIRECT_CODEX_REFERENCE_ID_CHARS: usize = 200;
+const MAX_DIRECT_CODEX_REFERENCE_LABEL_CHARS: usize = 160;
+const MAX_DIRECT_CODEX_REFERENCE_SOURCE_CHARS: usize = 32;
+const MAX_DIRECT_CODEX_REFERENCE_ELEMENT_CHARS: usize = 80;
+const MAX_DIRECT_CODEX_REFERENCE_TEXT_CHARS: usize = 240;
+
+const DIRECT_CODEX_REFERENCE_HEADER: &str =
+    "[本轮用户引用素材：以下均为当前项目已确认的安全引用。请使用稳定资源 ID 和项目相对路径读取，不要读取或输出其它路径。]";
+
+#[derive(Clone, Debug, serde::Deserialize)]
+#[serde(rename_all = "camelCase", tag = "type")]
+pub(crate) enum DirectCodexTurnReference {
+    #[serde(rename = "resource")]
+    Resource(DirectCodexResourceReference),
+    #[serde(rename = "runtime-region")]
+    RuntimeRegion(DirectCodexRuntimeRegionReference),
+}
+
+#[derive(Clone, Debug, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DirectCodexResourceReference {
+    pub(crate) resource_id: String,
+    #[serde(default)]
+    pub(crate) label: Option<String>,
+    #[serde(default)]
+    pub(crate) source: Option<String>,
+}
+
+#[derive(Clone, Debug, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DirectCodexRuntimeRegionReference {
+    #[serde(default)]
+    pub(crate) label: Option<String>,
+    #[serde(default)]
+    pub(crate) run_id: Option<String>,
+    #[serde(default)]
+    pub(crate) version_id: Option<String>,
+    #[serde(default)]
+    pub(crate) element_tag: Option<String>,
+    #[serde(default)]
+    pub(crate) element_role: Option<String>,
+    #[serde(default)]
+    pub(crate) text: Option<String>,
+    #[serde(default)]
+    pub(crate) width: Option<f64>,
+    #[serde(default)]
+    pub(crate) height: Option<f64>,
+    #[serde(default)]
+    pub(crate) resource_ids: Vec<String>,
+}
+
+fn sanitize_reference_text(value: &str, max_chars: usize) -> Option<String> {
+    let sanitized = value
+        .trim()
+        .chars()
+        .filter(|character| !character.is_control())
+        .take(max_chars)
+        .collect::<String>();
+    if sanitized.is_empty() {
+        None
+    } else {
+        Some(sanitized)
+    }
+}
+
+fn sanitize_reference_label(value: Option<&str>) -> Option<String> {
+    value.and_then(|value| sanitize_reference_text(value, MAX_DIRECT_CODEX_REFERENCE_LABEL_CHARS))
+}
+
+fn sanitize_reference_source(value: Option<&str>) -> Option<String> {
+    let value = sanitize_reference_text(value?, MAX_DIRECT_CODEX_REFERENCE_SOURCE_CHARS)?;
+    if value
+        .chars()
+        .all(|character| character.is_ascii_alphanumeric() || matches!(character, '-' | '_' | '.'))
+    {
+        Some(value)
+    } else {
+        None
+    }
+}
+
+fn sanitize_reference_element(value: Option<&str>) -> Option<String> {
+    let value = sanitize_reference_text(value?, MAX_DIRECT_CODEX_REFERENCE_ELEMENT_CHARS)?;
+    if value
+        .chars()
+        .all(|character| character.is_ascii_alphanumeric() || matches!(character, '-' | '_' | '.'))
+    {
+        Some(value)
+    } else {
+        None
+    }
+}
+
+fn sanitize_reference_dimension(value: Option<f64>) -> Option<u32> {
+    value
+        .filter(|value| value.is_finite() && *value > 0.0)
+        .map(|value| value.round().clamp(1.0, 100_000.0) as u32)
+}
+
+fn asset_display_label(asset: &GameCreationAppAssetManifestEntry) -> String {
+    let basename = asset
+        .local_path
+        .rsplit(['/', '\\'])
+        .next()
+        .unwrap_or(&asset.id);
+    let without_extension = basename
+        .rsplit_once('.')
+        .map(|(name, _)| name)
+        .unwrap_or(basename)
+        .trim();
+    if without_extension.is_empty() {
+        asset.id.clone()
+    } else {
+        without_extension
+            .chars()
+            .filter(|character| !character.is_control())
+            .take(MAX_DIRECT_CODEX_REFERENCE_LABEL_CHARS)
+            .collect()
+    }
+}
+
+fn validate_resource_reference_id(value: &str) -> Result<String, String> {
+    let resource_id = value.trim();
+    if resource_id.is_empty()
+        || resource_id.chars().count() > MAX_DIRECT_CODEX_REFERENCE_ID_CHARS
+        || resource_id.chars().any(char::is_control)
+    {
+        return Err("引用的素材 ID 无效，请移除后重新选择".to_string());
+    }
+    Ok(resource_id.to_string())
+}
+
+fn render_resource_reference_line(
+    manifest: &GameCreationAppManifest,
+    reference: &DirectCodexResourceReference,
+) -> Result<String, String> {
+    let resource_id = validate_resource_reference_id(&reference.resource_id)?;
+    let asset = manifest
+        .assets
+        .iter()
+        .find(|asset| asset.id == resource_id)
+        .ok_or_else(|| "引用的素材已不存在，请移除后重新选择".to_string())?;
+    let local_path = sanitize_attachment_local_path(&asset.local_path)
+        .ok_or_else(|| "引用的素材路径无效，请移除后重新选择".to_string())?;
+    let label = sanitize_reference_label(reference.label.as_deref())
+        .unwrap_or_else(|| asset_display_label(asset));
+    let source = sanitize_reference_source(reference.source.as_deref())
+        .unwrap_or_else(|| "unknown".to_string());
+    Ok(format!(
+        "- 素材 ID：{resource_id}；名称：{label}；类型：{}；媒体类型：{}；项目路径：{local_path}；来源：{source}",
+        asset.kind, asset.media_type
+    ))
+}
+
+fn render_runtime_region_reference_line(
+    manifest: &GameCreationAppManifest,
+    reference: &DirectCodexRuntimeRegionReference,
+) -> Result<String, String> {
+    let label = sanitize_reference_label(reference.label.as_deref())
+        .unwrap_or_else(|| "运行画面区域".to_string());
+    let run_id = sanitize_reference_source(reference.run_id.as_deref());
+    let version_id = sanitize_reference_source(reference.version_id.as_deref());
+    let element_tag = sanitize_reference_element(reference.element_tag.as_deref());
+    let element_role = sanitize_reference_element(reference.element_role.as_deref());
+    let text = reference
+        .text
+        .as_deref()
+        .and_then(|value| sanitize_reference_text(value, MAX_DIRECT_CODEX_REFERENCE_TEXT_CHARS));
+    let width = sanitize_reference_dimension(reference.width);
+    let height = sanitize_reference_dimension(reference.height);
+
+    let mut related_resource_ids = Vec::new();
+    for resource_id in &reference.resource_ids {
+        let resource_id = validate_resource_reference_id(resource_id)?;
+        if !manifest.assets.iter().any(|asset| asset.id == resource_id) {
+            return Err("运行画面引用的素材已变化，请重新点选".to_string());
+        }
+        related_resource_ids.push(resource_id);
+    }
+
+    let mut parts = vec![format!("名称：{label}")];
+    if let Some(run_id) = run_id {
+        parts.push(format!("运行标识：{run_id}"));
+    }
+    if let Some(version_id) = version_id {
+        parts.push(format!("版本标识：{version_id}"));
+    }
+    if let Some(element_tag) = element_tag {
+        parts.push(format!("元素：{element_tag}"));
+    }
+    if let Some(element_role) = element_role {
+        parts.push(format!("角色：{element_role}"));
+    }
+    if let Some(text) = text {
+        parts.push(format!("文本摘要：{text}"));
+    }
+    if let (Some(width), Some(height)) = (width, height) {
+        parts.push(format!("尺寸：{width}x{height}"));
+    }
+    if !related_resource_ids.is_empty() {
+        parts.push(format!("关联素材 ID：{}", related_resource_ids.join(",")));
+    }
+    Ok(format!("- 运行画面区域：{}", parts.join("；")))
+}
+
+pub(crate) fn render_direct_codex_references_section(
+    root: &Path,
+    references: &[DirectCodexTurnReference],
+) -> Result<Option<String>, String> {
+    if references.is_empty() {
+        return Ok(None);
+    }
+    if references.len() > MAX_DIRECT_CODEX_REFERENCES {
+        return Err(format!("一次最多引用 {MAX_DIRECT_CODEX_REFERENCES} 个素材"));
+    }
+    let manifest = read_manifest_for_project(root)?;
+    let mut lines = Vec::with_capacity(references.len());
+    for reference in references {
+        lines.push(match reference {
+            DirectCodexTurnReference::Resource(reference) => {
+                render_resource_reference_line(&manifest, reference)?
+            }
+            DirectCodexTurnReference::RuntimeRegion(reference) => {
+                render_runtime_region_reference_line(&manifest, reference)?
+            }
+        });
+    }
+    Ok(Some(
+        std::iter::once(DIRECT_CODEX_REFERENCE_HEADER.to_string())
+            .chain(lines)
+            .collect::<Vec<_>>()
+            .join("\n"),
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fixture_project() -> tempfile::TempDir {
+        let directory = tempfile::tempdir().expect("temp project");
+        let root = directory.path();
+        std::fs::create_dir_all(root.join(".agent")).expect("create agent dir");
+        let mut manifest = new_game_creation_app_manifest("project-1", "测试项目");
+        manifest.assets.push(GameCreationAppAssetManifestEntry {
+            id: "asset-hero".to_string(),
+            kind: "character".to_string(),
+            media_type: "image/png".to_string(),
+            local_path: "assets/hero.png".to_string(),
+            source: GameCreationAppAssetSource {
+                kind: GameCreationAppAssetSourceKind::Uploaded,
+                canvas_project_id: None,
+                resource_id: None,
+                asset_object_id: None,
+                task_id: None,
+                prompt: None,
+                model: None,
+                generation_route: None,
+                generation_kind: None,
+                reference_resource_ids: Vec::new(),
+            },
+            image_sequence_frames: None,
+            image_sequence_duration_ms: None,
+            category: game_creation_app_asset_category_for_kind("character"),
+            tags: Vec::new(),
+        });
+        write_manifest(&root.join(".agent/manifest.json"), &manifest).expect("write manifest");
+        directory
+    }
+
+    #[test]
+    fn resource_reference_uses_manifest_identity_and_never_accepts_client_paths() {
+        let project = fixture_project();
+        let reference: DirectCodexTurnReference = serde_json::from_str(
+            r#"{"type":"resource","resourceId":"asset-hero","label":"主角","source":"asset-picker","localPath":"C:\\secret.png"}"#,
+        )
+        .expect("reference json");
+        let section = render_direct_codex_references_section(
+            project.path(),
+            std::slice::from_ref(&reference),
+        )
+        .expect("render")
+        .expect("section");
+        assert!(section.contains("素材 ID：asset-hero"));
+        assert!(section.contains("名称：主角"));
+        assert!(section.contains("项目路径：assets/hero.png"));
+        assert!(!section.contains("C:\\secret.png"));
+    }
+
+    #[test]
+    fn deleted_resource_fails_closed() {
+        let project = fixture_project();
+        let reference: DirectCodexTurnReference = serde_json::from_str(
+            r#"{"type":"resource","resourceId":"asset-missing","label":"不存在"}"#,
+        )
+        .expect("reference json");
+        let error = render_direct_codex_references_section(
+            project.path(),
+            std::slice::from_ref(&reference),
+        )
+        .expect_err("missing resource");
+        assert_eq!(error, "引用的素材已不存在，请移除后重新选择");
+    }
+
+    #[test]
+    fn runtime_region_keeps_only_safe_summary_and_existing_resource_ids() {
+        let project = fixture_project();
+        let reference: DirectCodexTurnReference = serde_json::from_str(
+            r#"{"type":"runtime-region","label":"开始按钮","runId":"run-1","elementTag":"button","elementRole":"button","text":"开始游戏","width":120.4,"height":40.2,"resourceIds":["asset-hero"],"html":"<button onclick=secret>"}"#,
+        )
+        .expect("reference json");
+        let section = render_direct_codex_references_section(
+            project.path(),
+            std::slice::from_ref(&reference),
+        )
+        .expect("render")
+        .expect("section");
+        assert!(section.contains("运行画面区域：名称：开始按钮"));
+        assert!(section.contains("文本摘要：开始游戏"));
+        assert!(section.contains("尺寸：120x40"));
+        assert!(section.contains("关联素材 ID：asset-hero"));
+        assert!(!section.contains("onclick"));
+        assert!(!section.contains("secret"));
+    }
+}
@@ -1786,6 +1786,15 @@ fn direct_codex_failure_recovery_hint(stage: DirectCodexFailureStage, error: &st
    {
        return "历史画布资源不满足安全恢复条件，请先在资源画布确认唯一可用的核心图集";
    }
+    if direct_project_history_injection_oversize(error) {
+        return "项目对话历史有单条记录或整份载荷超过注入上限，无法整体注入 Codex；请按项目诊断里的 itemId 处理该条记录后再发送需求";
+    }
+    if direct_project_history_shape_failure(error) {
+        return "项目对话历史存在本版本无法识别的记录，旧格式已兼容读取，请检查项目诊断后修复该历史文件再发送需求";
+    }
+    if direct_project_history_contention_failure(error) {
+        return "另一个客户端进程正在读写该项目的历史或项目锁，本轮历史未能落盘；请稍后重试，若确认没有其它客户端在运行请重启客户端后再发送需求";
+    }
    match stage {
        DirectCodexFailureStage::ArtPreparation => {
            "平台资源暂时无法完成准备，请稍后重试；如持续失败请检查项目诊断"
@@ -1806,6 +1815,9 @@ fn direct_codex_failure_public_summary(error: &str) -> Option<&'static str> {
    if direct_codex_error_is_mud_points_insufficient(error) {
        return Some("泥点余额不足");
    }
+    if direct_project_history_injection_oversize(error) {
+        return Some("项目对话历史有单条记录超过注入上限");
+    }
    if private_external_editor_credentials_storage_preparation_failed(error) {
        return Some("本机开发者凭据存储目录未安全初始化；未创建远端凭据");
    }
@@ -1819,6 +1831,14 @@ fn direct_codex_failure_is_retryable(error: &str) -> bool {
    if direct_codex_error_is_mud_points_insufficient(error) {
        return false;
    }
+    if direct_project_history_shape_failure(error) {
+        return false;
+    }
+    // 注入超限与「行形状」同类：同一份历史文件每次读都会得到同一结论，重试只会
+    // 再次注入同一份（且本轮用户消息已先追加进同一文件，载荷只会更大），因此不标可重试。
+    if direct_project_history_injection_oversize(error) {
+        return false;
+    }
    ![
        "private-external-editor-credential-storage-preparation-failed",
        "private-external-editor-credential-persistence-failed",
@@ -1832,6 +1852,45 @@ fn direct_codex_failure_is_retryable(error: &str) -> bool {
    .any(|marker| error.contains(marker))
 }

+/// DirectProject 历史文件里与“行形状”有关的失败：同一份文件每次读都会得到同一结果，
+/// 重试不会改变结论。IO 类失败（打开/读取目录）不在其中，那些仍按可重试处理。
+const DIRECT_PROJECT_HISTORY_SHAPE_FAILURE_MARKERS: &[&str] = &[
+    "DirectProject 历史记录类型无效",
+    "DirectProject 历史记录缺少 payload",
+    "解析 DirectProject 历史失败",
+];
+
+/// DirectProject 历史**注入超限**的失败标记。
+///
+/// 判据是「同一份历史 ⇒ 同一份载荷 ⇒ 同一结论」：本次注入因为单条记录（或整份载荷）超过
+/// 单行上限而被前置校验拦下（前缀与字节数定义在 `agent/codex_app_server.rs`），重试只会再注入
+/// 同一份、且更大的历史。所以按不可重试处理，并给专属恢复提示；这里沿用本文件既有的
+/// 「字面量子串」口径，只取前缀的特征子串。
+const DIRECT_PROJECT_HISTORY_INJECTION_OVERSIZE_MARKERS: &[&str] = &["历史注入载荷超过单行上限"];
+
+fn direct_project_history_injection_oversize(error: &str) -> bool {
+    DIRECT_PROJECT_HISTORY_INJECTION_OVERSIZE_MARKERS
+        .iter()
+        .any(|marker| error.contains(marker))
+}
+
+fn direct_project_history_shape_failure(error: &str) -> bool {
+    DIRECT_PROJECT_HISTORY_SHAPE_FAILURE_MARKERS
+        .iter()
+        .any(|marker| error.contains(marker))
+}
+
+/// 跨进程锁 / 项目锁争用。
+///
+/// 与"行形状"类相反：它不是同一份历史的同一个结论，而是别的进程此刻正拿着锁——锁本身
+/// 没有残留（所有权是句柄，进程退出即释放），所以"稍后重试"是真能生效的动作。提示因此
+/// 指向现象与动作，而不是原来 CodeGeneration 阶段那句"请检查运行时配置后重试"。
+/// 判据只认两个常量，不各自复制中文。
+fn direct_project_history_contention_failure(error: &str) -> bool {
+    error.contains(crate::project::PROJECT_APPEND_LOCK_TIMEOUT_MARKER)
+        || error.contains(crate::project::PROJECT_WRITE_LOCK_CONTENTION_PREFIX)
+}
+
 fn direct_codex_error_is_mud_points_insufficient(error: &str) -> bool {
    let normalized = error.to_ascii_lowercase();
    error.contains("泥点余额不足")
@@ -4414,6 +4473,7 @@ pub(crate) async fn chat_with_game_creator_direct_codex(
    creation_type: Option<String>,
    client_turn_id: Option<String>,
    attachments: Option<Vec<DirectCodexTurnAttachment>>,
+    references: Option<Vec<DirectCodexTurnReference>>,
 ) -> Result<String, String> {
    let root = Path::new(project_path.trim());
    let turn_id = normalize_direct_client_turn_id(client_turn_id.as_deref())?;
@@ -4428,16 +4488,33 @@ pub(crate) async fn chat_with_game_creator_direct_codex(
        &prompt,
        attachments.as_deref().unwrap_or_default(),
    );
-    let user_prompt = match render_direct_codex_user_prompt(
-        &prompt,
-        attachments.as_deref().unwrap_or_default(),
-    ) {
+    let attachments = attachments.unwrap_or_default();
+    let references = references.unwrap_or_default();
+    let mut user_prompt = match render_direct_codex_user_prompt(&prompt, &attachments) {
        Ok(prompt) => prompt,
+        Err(_) if !references.is_empty() && prompt.trim().is_empty() => String::new(),
        Err(error) => {
            audit.finish(false);
            return Err(error);
        }
    };
+    if let Some(reference_section) = match render_direct_codex_references_section(root, &references)
+    {
+        Ok(section) => section,
+        Err(error) => {
+            audit.finish(false);
+            return Err(error);
+        }
+    } {
+        if !user_prompt.trim().is_empty() {
+            user_prompt.push_str("\n\n");
+        }
+        user_prompt.push_str(&reference_section);
+    }
+    if user_prompt.trim().is_empty() {
+        audit.finish(false);
+        return Err("聊天内容不能为空".to_string());
+    }
    let reply = match run_direct_game_creator_turn_at_with_creation_type_and_emitter(
        root,
        &user_prompt,
@@ -4531,6 +4608,23 @@ mod tests {
        assert!(!direct_codex_failure_is_retryable(error));
    }

+    #[test]
+    fn direct_project_history_shape_failure_has_explicit_non_retryable_guidance() {
+        let error =
+            "DirectProject 历史记录类型无效：$PROJECT_ROOT/.agent/conversations/project.jsonl";
+        assert!(direct_project_history_shape_failure(error));
+        assert_eq!(
+            direct_codex_failure_recovery_hint(DirectCodexFailureStage::CodeGeneration, error),
+            "项目对话历史存在本版本无法识别的记录，旧格式已兼容读取，请检查项目诊断后修复该历史文件再发送需求"
+        );
+        assert!(!direct_codex_failure_is_retryable(error));
+
+        // 历史文件的 IO 失败仍按可重试处理：它与行形状无关，重试可能成功。
+        let io_error = "打开 DirectProject 历史失败：拒绝访问";
+        assert!(!direct_project_history_shape_failure(io_error));
+        assert!(direct_codex_failure_is_retryable(io_error));
+    }
+
    #[test]
    fn client_turn_id_is_strictly_normalized_and_bounded() {
        assert_eq!(
@@ -6505,6 +6599,50 @@ mod tests {
        assert!(!diagnostic.contains("provider.example"));
    }

+    #[test]
+    fn direct_failure_diagnostic_marks_project_history_shape_failure_as_not_retryable() {
+        let root = tempfile::tempdir().expect("temp dir");
+        init_local_game_project_at(root.path(), "direct-diagnostic", "直连诊断")
+            .expect("init project");
+        let history_path = root
+            .path()
+            .join(".agent/conversations/project.jsonl")
+            .display()
+            .to_string();
+        let error = record_direct_codex_turn_failure(
+            root.path(),
+            DirectCodexTurnFailure::new(
+                DirectCodexFailureStage::CodeGeneration,
+                format!("DirectProject 历史记录类型无效：{history_path}"),
+            ),
+        );
+
+        assert!(
+            error.starts_with(
+                "direct-codex-failure:v1 stage=code-generation retryable=false summary="
+            ),
+            "{error}"
+        );
+        assert!(
+            error.contains(
+                "；建议：项目对话历史存在本版本无法识别的记录，旧格式已兼容读取，请检查项目诊断后修复该历史文件再发送需求；"
+            ),
+            "{error}"
+        );
+        assert!(error.ends_with("已保存脱敏项目诊断"), "{error}");
+
+        let diagnostics = root.path().join(".agent/runtime/direct-codex-diagnostics");
+        let entries = std::fs::read_dir(&diagnostics)
+            .expect("diagnostic directory")
+            .filter_map(Result::ok)
+            .collect::<Vec<_>>();
+        assert_eq!(entries.len(), 1);
+        let diagnostic = std::fs::read_to_string(entries[0].path().join("failure.json"))
+            .expect("diagnostic sidecar");
+        assert!(diagnostic.contains("\"retryable\": false"), "{diagnostic}");
+        assert!(diagnostic.contains("旧格式已兼容读取"), "{diagnostic}");
+    }
+
    #[test]
    fn direct_failure_diagnostic_marks_ambiguous_canvas_identity_as_not_retryable() {
        let root = tempfile::tempdir().expect("temp dir");
@@ -1161,6 +1161,12 @@ fn bridge_registered_resource(
        "localPath": asset.local_path,
        "kind": asset.kind,
        "mediaType": asset.media_type,
+        // Agent 与 UI 必须看到同一个口径：UI 栏目走 TS 的 `gameCreationAppAssetCategory`
+        // （落盘值 + 按 kind 派生 + 读时自愈），这里走 Rust 的同构实现。
+        // 直接透传落盘 `asset.category` 会让 `kind:"ui"` 的资产在 UI 显示「UI 交互」、
+        // 在 Agent 侧读到 `unclassified`（真机 55 条分歧）。
+        "category": game_creation_app_asset_effective_category(&asset.kind, asset.category),
+        "tags": asset.tags,
        "canvasProjectId": asset.source.canvas_project_id,
        "resourceId": asset.source.resource_id,
        "assetObjectId": asset.source.asset_object_id,
@@ -2990,6 +2996,8 @@ mod tests {
            local_path: "assets/art-spritesheet-slices/player.png".to_string(),
            image_sequence_frames: None,
            image_sequence_duration_ms: None,
+            category: game_creation_app_asset_category_for_kind("art-spritesheet-slice"),
+            tags: Vec::new(),
            source: GameCreationAppAssetSource {
                kind: GameCreationAppAssetSourceKind::Canvas,
                canvas_project_id: Some("canvas-1".to_string()),
@@ -3053,6 +3061,8 @@ mod tests {
                },
            ]),
            image_sequence_duration_ms: Some(4_000),
+            category: game_creation_app_asset_category_for_kind("character-animation"),
+            tags: Vec::new(),
            source: GameCreationAppAssetSource {
                kind: GameCreationAppAssetSourceKind::Canvas,
                canvas_project_id: Some("canvas-1".to_string()),
@@ -3072,6 +3082,8 @@ mod tests {
            projection["imageSequenceFrames"][0]["objectKey"],
            "animations/frame-01.png"
        );
+        assert_eq!(projection["category"], "character");
+        assert_eq!(projection["tags"], json!([]));
        let serialized = projection.to_string();
        assert!(!serialized.contains("signed.invalid"));
        assert!(!serialized.contains("private prompt"));
@@ -3079,6 +3091,83 @@ mod tests {
        assert!(!serialized.contains("private.invalid"));
    }

+    /// 落盘分类是明确值时，Agent 侧原样透传。
+    ///
+    /// （用例名从 `..._verbatim` 改成 `..._keeps_explicit...`：透传只在落盘值不是
+    /// `unclassified` 时成立，落盘 `unclassified` 要按读显示口径自愈，见下一个用例。）
+    #[test]
+    fn bridge_registered_resource_keeps_explicit_manifest_classification() {
+        let asset = GameCreationAppAssetManifestEntry {
+            id: "spec-1".to_string(),
+            kind: "spec".to_string(),
+            media_type: "application/json".to_string(),
+            local_path: "assets/specs/hero.json".to_string(),
+            image_sequence_frames: None,
+            image_sequence_duration_ms: None,
+            category:
+                shared_contracts::game_creation_app::GameCreationAppAssetCategory::UiInteraction,
+            tags: vec!["主角".to_string(), "第一版".to_string()],
+            source: GameCreationAppAssetSource {
+                kind: GameCreationAppAssetSourceKind::Generated,
+                canvas_project_id: None,
+                resource_id: None,
+                asset_object_id: None,
+                task_id: None,
+                prompt: Some("private prompt".to_string()),
+                model: Some("private model".to_string()),
+                generation_route: None,
+                generation_kind: None,
+                reference_resource_ids: Vec::new(),
+            },
+        };
+
+        let projection = bridge_registered_resource(&asset, false);
+        assert_eq!(projection["kind"], "spec");
+        assert_eq!(projection["category"], "ui-interaction");
+        assert_eq!(projection["tags"], json!(["主角", "第一版"]));
+        assert_eq!(projection["imageSequenceFrames"], Value::Null);
+        let serialized = projection.to_string();
+        assert!(!serialized.contains("private prompt"));
+        assert!(!serialized.contains("private model"));
+    }
+
+    /// Agent 侧必须与 UI 看到同一个分类口径。
+    ///
+    /// UI 栏目走 TS 的 `gameCreationAppAssetCategory`（落盘值 + 按 kind 派生 + 读时自愈），
+    /// Agent 走 Rust 的同构实现 `game_creation_app_asset_effective_category`。直接透传落盘
+    /// `category` 会让 `kind:"ui"` 的资产在 UI 显示「UI 交互」、在 Agent 侧读到
+    /// `unclassified`——真机 122 条资产里有 55 条这样分叉。
+    #[test]
+    fn bridge_registered_resource_projects_effective_category_not_raw_persisted_value() {
+        let asset = GameCreationAppAssetManifestEntry {
+            id: "ui-1".to_string(),
+            kind: "ui".to_string(),
+            media_type: "application/json".to_string(),
+            local_path: "assets/UI 设计 1.json".to_string(),
+            image_sequence_frames: None,
+            image_sequence_duration_ms: None,
+            category:
+                shared_contracts::game_creation_app::GameCreationAppAssetCategory::Unclassified,
+            tags: Vec::new(),
+            source: GameCreationAppAssetSource {
+                kind: GameCreationAppAssetSourceKind::Generated,
+                canvas_project_id: None,
+                resource_id: None,
+                asset_object_id: None,
+                task_id: None,
+                prompt: None,
+                model: None,
+                generation_route: None,
+                generation_kind: None,
+                reference_resource_ids: Vec::new(),
+            },
+        };
+
+        let projection = bridge_registered_resource(&asset, false);
+        assert_eq!(projection["kind"], "ui");
+        assert_eq!(projection["category"], "ui-interaction");
+    }
+
    #[test]
    fn bridge_success_warnings_are_redacted_before_serialization() {
        let root = tempfile::tempdir().expect("warning redaction root");
@@ -256,7 +256,7 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool) -> Value {
        }),
        json!({
                "name": "agc_list_registered_assets",
-                "description": "查询当前项目由客户端权威 manifest 登记的资源与未完成资源 operation。结果有界且只包含项目相对路径、稳定资源身份、序列帧身份和恢复状态，不返回 prompt、模型、签名 URL、宿主路径或凭据。",
+                "description": "查询当前项目由客户端权威 manifest 登记的资源与未完成资源 operation。结果有界且只包含项目相对路径、稳定资源身份、功能分类与自定义标签、序列帧身份和恢复状态，不返回 prompt、模型、签名 URL、宿主路径或凭据。",
                "inputSchema": {
                    "type": "object",
                    "properties": {
@@ -1247,8 +1247,6 @@ fn external_mcp_record_response(root: &Path, arguments: &Value) -> Value {
        Err(error) => return mcp_tool_result(error, Vec::new(), true),
    };
    let redacted = redact_external_mcp_response(&content);
-    let key = format!("{request_id}\u{0}{sequence}");
-    let message_id = format!("external-codex-{:x}", Sha256::digest(key.as_bytes()));
    let guard = EXTERNAL_MCP_JOURNAL_LOCK
        .get_or_init(|| Mutex::new(()))
        .lock();
@@ -1358,29 +1356,6 @@ fn external_mcp_record_response(root: &Path, arguments: &Value) -> Value {
            true,
        );
    }
-    // Reuse the existing conversation projection so the current UI can read
-    // the explicit external response without treating it as business truth.
-    if let Err(error) = append_local_conversation_message_for_session_idempotent_at(
-        root,
-        None,
-        None,
-        LocalConversationMessage {
-            role: "assistant".to_string(),
-            content: record
-                .get("content")
-                .and_then(Value::as_str)
-                .unwrap_or_default()
-                .to_string(),
-            agent_id: None,
-        },
-        &message_id,
-    ) {
-        return mcp_tool_result(
-            format!("Codex 返回已写入但对话投影失败：{error}"),
-            Vec::new(),
-            true,
-        );
-    }
    records.push(record.clone());
    mcp_tool_result(record.to_string(), Vec::new(), false)
 }
@@ -2280,4 +2255,33 @@ mod tests {
        }))
        .is_err());
    }
+
+    #[test]
+    fn recorded_codex_response_only_writes_its_own_journal() {
+        let temporary = crate::tests::canonical_test_tempdir("direct-tools-record-response-");
+        let root = temporary.path();
+        init_local_game_project_at(root, "direct-tools-record", "Codex 返回记录测试")
+            .expect("init project");
+
+        let result = external_mcp_record_response(
+            root,
+            &json!({
+                "requestId": "req-1",
+                "sequence": 0,
+                "content": "已完成的返回正文"
+            }),
+        );
+        assert_eq!(result.get("isError"), Some(&json!(false)), "{result}");
+
+        let journal = root.join(".agent/conversations/codex-responses.jsonl");
+        let journal_text = std::fs::read_to_string(&journal).expect("read codex responses journal");
+        assert!(journal_text.contains("已完成的返回正文"), "{journal_text}");
+
+        let project_history = root.join(".agent/conversations/project.jsonl");
+        let project_history_text = std::fs::read_to_string(&project_history).unwrap_or_default();
+        assert_eq!(
+            project_history_text, "",
+            "显式 Codex 返回不能再往项目主对话写 legacy 行"
+        );
+    }
 }
@@ -6786,6 +6786,8 @@ fn register_platform_art_slice_manifest_entries_at(
                    local_path: registration.local_path.clone(),
                    image_sequence_frames: None,
                    image_sequence_duration_ms: None,
+                    category: game_creation_app_asset_category_for_kind("art-spritesheet-slice"),
+                    tags: Vec::new(),
                    source,
                });
                ids.push(id);
@@ -1114,6 +1114,9 @@ pub(in crate::agent) fn ui_prototype_visual_inspection_blocker_detail_at_locked(
    let image = images
        .pop()
        .ok_or_else(|| "UI 原型图片读取结果为空".to_string())?;
+    // 摘要缺失必须失败关闭：视觉检查审计按摘要证明「检查过的就是当前这张图」，
+    // 不能退化成空摘要比较，否则一条 sha256 为空的记录就能通过复核。
+    let image_sha256 = image.sha256_digest()?.to_string();
    let (records, scan_truncated) =
        read_agent_db_records_bounded(root, AGENT_RUNTIME_ACTION_HISTORY_MAX_DB_BYTES)?;
    let matching = records.iter().rev().find(|record| {
@@ -1139,13 +1142,13 @@ pub(in crate::agent) fn ui_prototype_visual_inspection_blocker_detail_at_locked(
                        && items[0].get("path").and_then(serde_json::Value::as_str)
                            == Some(expected_path)
                        && items[0].get("sha256").and_then(serde_json::Value::as_str)
-                            == Some(image.sha256.as_str())
+                            == Some(image_sha256.as_str())
                })
    });
    let Some(record) = matching else {
        return Ok(Some(format!(
            "expectedPath={expected_path} · currentSha256={} · requiredInspection=image.inspect · inspectionRunId={} · scanTruncated={scan_truncated}",
-            image.sha256,
+            image_sha256,
            required_run_id.unwrap_or("latest-current-image")
        )));
    };
@@ -429,16 +429,26 @@ pub(in crate::agent) async fn observe_agent_runtime_image_inspect(
        .as_deref()
        .map(|value| sanitize_agent_runtime_text(value, 160))
        .filter(|value| !value.trim().is_empty());
-    let image_metadata = images
-        .iter()
-        .map(|image| {
-            serde_json::json!({
-                "path": image.relative_path,
-                "sha256": image.sha256,
-                "bytes": image.byte_len,
-            })
-        })
-        .collect::<Vec<_>>();
+    // 视觉检查审计按 sha256 记录并复核「检查过的就是当前这张图」，摘要缺失必须失败关闭。
+    let mut image_metadata = Vec::with_capacity(images.len());
+    for image in &images {
+        let sha256 = match image.sha256_digest() {
+            Ok(sha256) => sha256,
+            Err(error) => {
+                return AgentRuntimeToolObservation {
+                    tool: "image.inspect".to_string(),
+                    status: "failed".to_string(),
+                    summary: sanitize_agent_runtime_text(&error, 240),
+                    detail: None,
+                };
+            }
+        };
+        image_metadata.push(serde_json::json!({
+            "path": image.relative_path,
+            "sha256": sha256,
+            "bytes": image.byte_len,
+        }));
+    }
    let validation_profile =
        ui_prototype_inspection.then_some(AGENT_RUNTIME_UI_PROTOTYPE_VALIDATION_PROFILE);
    let passed = ui_prototype_assessment
@@ -467,6 +467,77 @@ pub(crate) fn external_editor_api_credentials_override_is_active() -> bool {
    active_external_editor_api_credentials().is_some()
 }

+/// 上传素材落盘的 manifest `kind`：只由**内容证据**推导（`mediaType` 优先，扩展名兜底）。
+///
+/// 不用 `uploaded` 这类**来源词**当类型：它不在 canonical 目录里，会经别名表落到
+/// `image → unclassified`，把本该归「音频」「文档」的上传素材一起说成图片。
+///
+/// 更不能把 `ui` 当"图片的默认类型"：`ui → ui-design → ui-interaction` 会把任意上传图片
+/// 钉死在「UI 交互」栏，而"是不是 UI 素材"跟"扩展名是不是 .png"毫无关系；这类错值还不可恢复
+/// ——读时自愈只在落盘 `category` 是 `unclassified` 且该 `kind` 能派生出非 `unclassified`
+/// 分类时才生效，`kind` 本身错时自愈只会把错值放大。
+///
+/// 判不出内容类型时返回中性的 `asset`（派生 `unclassified` → 「待归类」），**不猜具体类型**。
+fn uploaded_asset_kind(file_name: &str, media_type: &str) -> &'static str {
+    let media_type = media_type.trim().to_ascii_lowercase();
+    let extension = Path::new(file_name)
+        .extension()
+        .and_then(|value| value.to_str())
+        .unwrap_or_default()
+        .to_ascii_lowercase();
+    let extension = extension.as_str();
+    if media_type.starts_with("audio/")
+        || matches!(
+            extension,
+            "mp3" | "wav" | "ogg" | "m4a" | "aac" | "flac" | "opus"
+        )
+    {
+        "audio"
+    } else if media_type.starts_with("video/") || matches!(extension, "mp4" | "webm" | "mov") {
+        "video"
+    } else if media_type.starts_with("font/")
+        || matches!(extension, "ttf" | "otf" | "woff" | "woff2")
+    {
+        "document"
+    } else if media_type.starts_with("image/")
+        || matches!(
+            extension,
+            "png" | "jpg" | "jpeg" | "webp" | "gif" | "svg" | "avif" | "bmp"
+        )
+    {
+        "image"
+    } else if matches!(media_type.as_str(), "text/html" | "text/css")
+        || media_type.contains("javascript")
+        || media_type.contains("typescript")
+        || matches!(
+            extension,
+            "html" | "htm" | "css" | "js" | "mjs" | "cjs" | "jsx" | "ts" | "tsx"
+        )
+    {
+        "code"
+    } else if media_type.starts_with("text/")
+        || matches!(media_type.as_str(), "application/json" | "application/xml")
+        || matches!(
+            extension,
+            "md" | "markdown"
+                | "mdx"
+                | "txt"
+                | "json"
+                | "yaml"
+                | "yml"
+                | "toml"
+                | "csv"
+                | "ini"
+                | "conf"
+                | "xml"
+        )
+    {
+        "document"
+    } else {
+        "asset"
+    }
+}
+
 pub(crate) fn upload_local_asset_at(
    root: &Path,
    file_name: &str,
@@ -492,7 +563,7 @@ pub(crate) fn upload_local_asset_at(
    register_local_asset_entry(
        root,
        &relative_path,
-        "uploaded",
+        uploaded_asset_kind(file_name, media_type),
        media_type,
        "upload",
        GameCreationAppAssetSource {
@@ -1635,27 +1706,35 @@ pub(crate) fn normalized_zip_entry_name(name: &str) -> Result<String, String> {
    normalize_relative_path(&normalized)
 }

+/// 画板导出图层推断出的资源 kind。
+///
+/// 返回值必须是 **canonical kind**：这个值会被 `register_local_asset_entry` 原样写入
+/// manifest，并据以派生落盘 `category`。历史上这里写过非 canonical 的
+/// `ui` / `animation` / `asset`，只能靠别名表兜底，等于同时维护两套词汇；别名表只用于
+/// 兼容存量数据，不作为新写入值的来源。
 pub(crate) fn infer_canvas_export_asset_kind(
    layer: &CanvasExportLayerMetadata,
    file: &str,
 ) -> &'static str {
    let layer_type = layer.visible.layer_type.as_str();
-    if file.starts_with("sequences/") || contains_any(layer_type, &["序列", "动画", "动作"]) {
-        return "animation";
-    }
-    if file.starts_with("media/") || contains_any(layer_type, &["音频", "音乐", "音效"]) {
-        return "audio";
-    }
-    if contains_any(layer_type, &["角色"]) {
-        return "character";
-    }
-    if contains_any(layer_type, &["场景", "背景"]) {
-        return "scene";
-    }
-    if contains_any(layer_type, &["UI", "界面", "图标"]) {
-        return "ui";
-    }
-    "asset"
+    let inferred = if file.starts_with("sequences/")
+        || contains_any(layer_type, &["序列", "动画", "动作"])
+    {
+        "character-animation"
+    } else if file.starts_with("media/") || contains_any(layer_type, &["音频", "音乐", "音效"])
+    {
+        "audio"
+    } else if contains_any(layer_type, &["角色"]) {
+        "character"
+    } else if contains_any(layer_type, &["场景", "背景"]) {
+        "scene"
+    } else if contains_any(layer_type, &["UI", "界面", "图标"]) {
+        "ui-design"
+    } else {
+        "image"
+    };
+    // 防御性归一：分支字面量写错时由覆盖测试暴露，这里再兜一层。
+    shared_contracts::game_creation_app::canonical_game_creation_app_asset_kind(inferred)
 }

 pub(crate) fn infer_canvas_export_media_type(file: &str) -> &'static str {
@@ -1751,7 +1830,14 @@ pub(crate) fn register_local_asset_entry(
            .iter_mut()
            .find(|asset| asset.local_path == normalized_path)
        {
-            existing.kind = kind.to_string();
+            // kind 变了必须重派生 category：否则同路径重登记会把新 kind 和旧分类拼在一起，
+            // 而陈旧的非 unclassified 值会被读侧无条件信任（自愈只在落盘值是 unclassified
+            // 时才触发），于是这个资产永远停在错误栏目。
+            // kind 没变时刻意不动 category——落盘分类是权威值，同 kind 重登记不得抹掉它。
+            if existing.kind != kind {
+                existing.kind = kind.to_string();
+                existing.category = game_creation_app_asset_category_for_kind(kind);
+            }
            existing.media_type = media_type.to_string();
            existing.source = source;
            Ok((existing.id.clone(), "asset.update"))
@@ -1768,6 +1854,8 @@ pub(crate) fn register_local_asset_entry(
                local_path: normalized_path.clone(),
                image_sequence_frames: None,
                image_sequence_duration_ms: None,
+                category: game_creation_app_asset_category_for_kind(kind),
+                tags: Vec::new(),
                source,
            });
            Ok((id, "asset.register"))
@@ -1793,11 +1881,286 @@ pub(crate) fn register_local_asset_entry(
    })
 }

+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields, rename_all = "camelCase")]
+pub(crate) struct ReadLocalProjectAssetReferencesInput {
+    pub project_path: String,
+    pub asset_id: String,
+}
+
+/// 引用了某个素材的项目版本摘要。删除弹窗据此列出「被哪些版本使用」。
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct LocalProjectAssetReferenceVersion {
+    pub version_id: String,
+    pub project_revision: u64,
+    pub created_at: u64,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ReadLocalProjectAssetReferencesResult {
+    pub asset_id: String,
+    pub versions: Vec<LocalProjectAssetReferenceVersion>,
+}
+
+/// 版本数组里 `resourceBindings` 指向该素材的版本，顺序与版本数组一致。
+///
+/// 版本绑定即资源记录：`resourceId` 指向 manifest 资产 ID，命中即表示该版本用了这个素材。
+fn asset_referencing_versions(
+    manifest: &GameCreationAppManifest,
+    asset_id: &str,
+) -> Vec<LocalProjectAssetReferenceVersion> {
+    manifest
+        .versions
+        .iter()
+        .filter(|version| {
+            version
+                .resource_bindings
+                .iter()
+                .any(|binding| binding.resource_id == asset_id)
+        })
+        .map(|version| LocalProjectAssetReferenceVersion {
+            version_id: version.version_id.clone(),
+            project_revision: version.project_revision,
+            created_at: version.created_at,
+        })
+        .collect()
+}
+
+fn normalized_asset_id(asset_id: &str) -> Result<&str, String> {
+    let asset_id = asset_id.trim();
+    if asset_id.is_empty() {
+        return Err("素材 assetId 不能为空".to_string());
+    }
+    Ok(asset_id)
+}
+
+pub(crate) fn read_manifest_asset_references_at(
+    root: &Path,
+    asset_id: &str,
+) -> Result<ReadLocalProjectAssetReferencesResult, String> {
+    let asset_id = normalized_asset_id(asset_id)?;
+    let manifest = read_existing_manifest_for_project(root)?;
+    Ok(ReadLocalProjectAssetReferencesResult {
+        asset_id: asset_id.to_string(),
+        versions: asset_referencing_versions(&manifest, asset_id),
+    })
+}
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields, rename_all = "camelCase")]
+pub(crate) struct DeleteLocalProjectAssetInput {
+    pub project_path: String,
+    pub expected_project_id: String,
+    pub expected_project_revision: u64,
+    pub asset_id: String,
+    /// 用户是否勾选「把相关游戏版本一并删除」；默认不勾，只删素材登记。
+    pub delete_referenced_versions: bool,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct DeleteLocalProjectAssetResult {
+    pub asset_id: String,
+    pub local_path: String,
+    pub committed_project_revision: u64,
+    /// 只删除 manifest 登记，磁盘文件保留；调用方据此提示用户。
+    pub file_retained: bool,
+}
+
+/// 删除一个素材登记，并按用户确认决定是否连带删除引用它的游戏版本。
+///
+/// 语义：
+/// - 未被任何版本引用 → 只摘掉登记；
+/// - 被引用且 `delete_referenced_versions` 为 `false` → 只摘掉登记，引用它的版本原样保留为
+///   悬空绑定，不做二次拦截；界面不为这些版本合成资源卡；
+/// - 被引用且为 `true` → 素材与所有引用它的版本在**同一次 manifest 写入**里一起删除；
+/// - 素材不可变，**不删除磁盘文件**，只摘掉 manifest 登记；
+/// - 与资源分类更新同口径：持项目写锁后按 `expectedProjectId` / 当前 revision 做 CAS，
+///   失败时 manifest 与 revision 都不变。
+pub(crate) fn delete_manifest_asset_at(
+    root: &Path,
+    expected_project_id: &str,
+    expected_project_revision: u64,
+    asset_id: &str,
+    delete_referenced_versions: bool,
+) -> Result<DeleteLocalProjectAssetResult, String> {
+    if expected_project_revision
+        > shared_contracts::game_creation_app::GAME_CREATION_RESOURCE_LAYOUT_MAX_SAFE_REVISION
+    {
+        return Err("expectedProjectRevision 超出 JavaScript 安全整数范围".to_string());
+    }
+    let expected_project_id = expected_project_id.trim();
+    if expected_project_id.is_empty() {
+        return Err("素材删除 expectedProjectId 不能为空".to_string());
+    }
+    let asset_id = normalized_asset_id(asset_id)?;
+
+    if read_existing_manifest_for_project(root)?.project_id != expected_project_id {
+        return Err("project-identity-conflict".to_string());
+    }
+    let _lock = acquire_project_write_lock(root, "asset.register")?;
+    if read_existing_manifest_for_project(root)?.project_id != expected_project_id {
+        return Err("project-identity-conflict".to_string());
+    }
+    if read_game_creator_agent_runtime_project_revision(root)?.revision != expected_project_revision
+    {
+        return Err("project-revision-conflict".to_string());
+    }
+
+    let mut local_path = String::new();
+    mutate_manifest_at_allowing_version_removals(
+        root,
+        &|manifest| {
+            if !delete_referenced_versions {
+                return Vec::new();
+            }
+            asset_referencing_versions(manifest, asset_id)
+                .into_iter()
+                .map(|version| version.version_id)
+                .collect()
+        },
+        |manifest| {
+            let Some(index) = manifest
+                .assets
+                .iter()
+                .position(|asset| asset.id == asset_id)
+            else {
+                return Err(format!("项目资源不存在：{asset_id}"));
+            };
+            local_path = manifest.assets[index].local_path.clone();
+            manifest.assets.remove(index);
+            if delete_referenced_versions {
+                let referenced_version_ids: Vec<String> =
+                    asset_referencing_versions(manifest, asset_id)
+                        .into_iter()
+                        .map(|version| version.version_id)
+                        .collect();
+                manifest
+                    .versions
+                    .retain(|version| !referenced_version_ids.contains(&version.version_id));
+            }
+            Ok(())
+        },
+    )?;
+
+    let committed_project_revision = advance_agent_runtime_project_revision_locked(root)
+        .map_err(|error| format!("素材登记已删除，但项目 revision 未能推进：{error}"))?;
+
+    Ok(DeleteLocalProjectAssetResult {
+        asset_id: asset_id.to_string(),
+        local_path,
+        committed_project_revision,
+        file_retained: true,
+    })
+}
+
 #[cfg(test)]
 mod tests {
    use super::*;
    use std::io::{Read, Write};

+    /// 画板导出推断出的 kind 必须已经是 canonical 值。
+    ///
+    /// 这个值会被原样写进 manifest 并据以派生落盘 `category`；一旦写出非 canonical 值
+    /// （历史上曾写 `ui` / `animation` / `asset`），就只能靠别名表兜底，等于同时维护
+    /// 两套词汇，且已落盘的 category 无法随别名修复自愈。这里逐分支钉死。
+    #[test]
+    fn canvas_export_asset_kind_is_always_canonical() {
+        fn layer(layer_type: &str) -> CanvasExportLayerMetadata {
+            serde_json::from_value(serde_json::json!({
+                "title": "测试图层",
+                "file": "layer.png",
+                "exportError": null,
+                "visible": {
+                    "type": layer_type,
+                    "model": "-",
+                    "task": "-",
+                    "object": "-",
+                },
+            }))
+            .expect("canvas export layer metadata")
+        }
+
+        // 每个分支的代表输入 → 期望的 canonical kind。
+        let cases: [(&str, &str, &str); 6] = [
+            ("序列", "sequences/01.png", "character-animation"),
+            ("动画", "layer.png", "character-animation"),
+            ("音频", "layer.png", "audio"),
+            ("角色", "layer.png", "character"),
+            ("场景", "layer.png", "scene"),
+            ("UI", "layer.png", "ui-design"),
+            // 无匹配时落到 image。
+        ];
+        for (layer_type, file, expected) in cases {
+            let kind = infer_canvas_export_asset_kind(&layer(layer_type), file);
+            assert_eq!(kind, expected, "layer_type={layer_type} file={file}");
+        }
+        // media/ 前缀同样走音频分支。
+        assert_eq!(
+            infer_canvas_export_asset_kind(&layer("图层"), "media/bgm.mp3"),
+            "audio"
+        );
+        // 兜底分支是 image 而不是旧的 "asset"。
+        assert_eq!(
+            infer_canvas_export_asset_kind(&layer("图层"), "layer.png"),
+            "image"
+        );
+
+        // 所有分支的返回值都必须在 canonical 目录里，且不能是旧的非 canonical 写法。
+        for layer_type in ["序列", "音频", "角色", "场景", "UI", "图层", "其他"] {
+            let kind = infer_canvas_export_asset_kind(&layer(layer_type), "layer.png");
+            assert!(
+                shared_contracts::game_creation_app::GAME_CREATION_APP_CANONICAL_ASSET_KINDS
+                    .contains(&kind),
+                "非 canonical kind: {kind}（layer_type={layer_type}）"
+            );
+            for legacy in ["ui", "animation", "asset"] {
+                assert_ne!(kind, legacy, "写回了非 canonical 的 {legacy}");
+            }
+        }
+    }
+
+    /// 上传素材的 `kind` 只由内容证据推导：既不能写 `uploaded`（来源词当类型），
+    /// 更不能把 `ui` 当图片默认值（`ui → ui-design → ui-interaction` 会把任意上传图片
+    /// 钉死在「UI 交互」栏，且落盘 `category` 非 `unclassified` 后读时自愈救不回来）。
+    ///
+    /// 变异验证：把 `uploaded_asset_kind` 改回返回常量（`"uploaded"` 或 `"ui"`）必须让本用例变红。
+    #[test]
+    fn uploaded_asset_kind_uses_content_evidence_and_never_ui() {
+        assert_eq!(uploaded_asset_kind("hero.png", "image/png"), "image");
+        assert_eq!(uploaded_asset_kind("../角色.png", "image/png"), "image");
+        assert_eq!(uploaded_asset_kind("bg.webp", ""), "image");
+        assert_eq!(uploaded_asset_kind("theme.mp3", "audio/mpeg"), "audio");
+        assert_eq!(uploaded_asset_kind("intro.mp4", ""), "video");
+        assert_eq!(uploaded_asset_kind("rules.md", "text/markdown"), "document");
+        assert_eq!(uploaded_asset_kind("ui-font.ttf", "font/ttf"), "document");
+        assert_eq!(uploaded_asset_kind("game.js", "text/javascript"), "code");
+        // 判不出内容类型 → 中性 `asset`（派生 `unclassified` → 「待归类」），不猜具体类型。
+        assert_eq!(
+            uploaded_asset_kind("unknown.bin", "application/octet-stream"),
+            "asset"
+        );
+        assert_eq!(uploaded_asset_kind("no-extension", ""), "asset");
+        // 反查：正文里的"来源词"和"UI 默认值"都不得出现在返回值里。
+        for (file_name, media_type) in [
+            ("hero.png", "image/png"),
+            ("theme.mp3", "audio/mpeg"),
+            ("unknown.bin", ""),
+        ] {
+            let kind = uploaded_asset_kind(file_name, media_type);
+            assert_ne!(kind, "uploaded", "{file_name} 写回了来源词");
+            assert_ne!(kind, "ui", "{file_name} 写回了非 canonical 的 `ui`");
+            assert!(
+                shared_contracts::game_creation_app::GAME_CREATION_APP_CANONICAL_ASSET_KINDS
+                    .contains(&kind)
+                    || kind == "asset",
+                "非 canonical kind: {kind}（{file_name}）"
+            );
+        }
+    }
+
    #[test]
    fn infer_file_extension_preserves_supported_local_resource_extensions() {
        assert_eq!(
@@ -31,7 +31,10 @@ pub(crate) struct LocalProjectImagePreview {

 pub(crate) struct AgentRuntimeInspectionImage {
    pub(crate) relative_path: String,
-    pub(crate) sha256: String,
+    /// 只有 Agent 视觉检查（`image.inspect`）需要内容摘要：它要把摘要写进动作审计并按摘要
+    /// 复核「检查过的就是当前这张图」。资源卡预览只需要字节、媒体类型和像素尺寸，摘要没有
+    /// 任何消费者，因此预览路径不计算它。取摘要必须走 [`Self::sha256_digest`]，缺摘要即失败关闭。
+    pub(crate) sha256: Option<String>,
    pub(crate) byte_len: u64,
    pub(crate) media_type: &'static str,
    pixel_width: u32,
@@ -48,6 +51,15 @@ impl AgentRuntimeInspectionImage {
        )
    }

+    pub(crate) fn sha256_digest(&self) -> Result<&str, String> {
+        self.sha256.as_deref().ok_or_else(|| {
+            format!(
+                "image.inspect 缺少内容摘要：{}；摘要只在视觉检查读取路径上计算",
+                self.relative_path
+            )
+        })
+    }
+
    fn data_url_with_cancellation(
        &self,
        cancellation: &ProjectResourcePreviewScopeCancellation,
@@ -83,8 +95,12 @@ pub(crate) fn load_local_project_image_preview_with_cancellation(
    let absolute = resolve_local_project_path(root, &normalized)?;
    validate_agent_runtime_inspection_ancestors(root, &absolute)?;
    cancellation.check()?;
-    let image =
-        read_agent_runtime_inspection_image_with_cancellation(&absolute, normalized, cancellation)?;
+    let image = read_agent_runtime_inspection_image_with_cancellation(
+        &absolute,
+        normalized,
+        cancellation,
+        false,
+    )?;
    cancellation.check()?;
    Ok(LocalProjectImagePreview {
        path: image.relative_path.clone(),
@@ -273,13 +289,21 @@ fn read_agent_runtime_inspection_image(
        path,
        relative_path,
        &ProjectResourcePreviewScopeCancellation::uncancelled(),
+        true,
    )
 }

+/// 单次受控读取：门禁、分块读取、漂移与替换复核、签名 / 尺寸校验对两条调用方完全一致，
+/// 只有内容摘要按 `include_sha256` 分叉。
+///
+/// `include_sha256 = true` 是 Agent 视觉检查路径（`image.inspect`）：摘要要写进动作审计，并在
+/// `project_gates` 里按摘要复核「检查过的就是当前这张图」。资源卡预览路径传 `false`，因为它的
+/// `LocalProjectImagePreview` 从来不消费摘要，只为它多算一遍全长 SHA-256 是纯开销。
 fn read_agent_runtime_inspection_image_with_cancellation(
    path: &Path,
    relative_path: String,
    cancellation: &ProjectResourcePreviewScopeCancellation,
+    include_sha256: bool,
 ) -> Result<AgentRuntimeInspectionImage, String> {
    cancellation.check()?;
    let (mut file, initial_metadata) = open_project_snapshot_regular_file(path, "视觉检查图片")?;
@@ -360,7 +384,7 @@ fn read_agent_runtime_inspection_image_with_cancellation(
        ));
    }
    cancellation.check()?;
-    let sha256 = format!("{:x}", Sha256::digest(&bytes));
+    let sha256 = include_sha256.then(|| format!("{:x}", Sha256::digest(&bytes)));
    Ok(AgentRuntimeInspectionImage {
        relative_path,
        sha256,
@@ -582,17 +606,40 @@ fn runtime_path_component(value: &str, fallback: &str) -> String {
 }

 #[cfg(windows)]
-fn metadata_is_windows_reparse_point(metadata: &fs::Metadata) -> bool {
+pub(crate) fn metadata_is_windows_reparse_point(metadata: &fs::Metadata) -> bool {
    use std::os::windows::fs::MetadataExt;
    const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0000_0400;
    metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0
 }

 #[cfg(not(windows))]
-fn metadata_is_windows_reparse_point(_metadata: &fs::Metadata) -> bool {
+pub(crate) fn metadata_is_windows_reparse_point(_metadata: &fs::Metadata) -> bool {
    false
 }

+/// 已打开句柄的跨平台文件身份：Windows 用 `(volume serial, file index)`，Unix 用 `(dev, ino)`。
+/// 资源卡预览的 manifest 缓存用它判断「路径指向的还是同一个文件」。
+pub(crate) fn open_file_identity_key(file: &fs::File) -> Result<(u64, u64), String> {
+    #[cfg(windows)]
+    {
+        let (volume_serial_number, file_index) = windows_file_identity(file)?;
+        Ok((u64::from(volume_serial_number), file_index))
+    }
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::MetadataExt;
+        let metadata = file
+            .metadata()
+            .map_err(|error| format!("读取文件身份元数据失败：{error}"))?;
+        Ok((metadata.dev(), metadata.ino()))
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        let _ = file;
+        Err("当前平台不支持文件身份判定".to_string())
+    }
+}
+
 #[cfg(unix)]
 pub(crate) fn same_open_file_snapshot(left: &fs::Metadata, right: &fs::Metadata) -> bool {
    use std::os::unix::fs::MetadataExt;
@@ -26,7 +26,9 @@ use serde::{Deserialize, Serialize};
 use sha2::Digest;
 use shared_contracts::error_reports::ErrorReportLogInput;
 use shared_contracts::game_creation_app::{
-    new_game_creation_app_manifest, new_game_creation_app_seed_tasks,
+    game_creation_app_asset_category_for_kind, game_creation_app_asset_category_from_str,
+    game_creation_app_asset_effective_category, new_game_creation_app_manifest,
+    new_game_creation_app_seed_tasks, normalize_game_creation_app_asset_tags,
    validate_game_iteration_versions, GameCreationAgentArtifactTrace,
    GameCreationAgentCapabilityDescriptor, GameCreationAgentPassPlanTrace,
    GameCreationAgentRepairRouteTrace, GameCreationAgentRunStep,
@@ -2216,6 +2218,13 @@ where

 fn handle_game_creator_gui_run_event(event: &tauri::RunEvent) {
    if matches!(event, tauri::RunEvent::Exit) {
+        // 退出时统一收尾本地预览：进程内监听线程随进程消失，但 `.agent/manifest.json`
+        // 里的 preview 记录会留在 running 上，下次进项目就照着它渲染打不开的运行界面。
+        if let Err(error) =
+            preview::stop_local_game_preview_on_exit(&game_creator_preview_registry())
+        {
+            app_log!("preview.gui_exit.stop_failed: {error}");
+        }
        if let Err(error) = agent::shutdown_game_creator_codex_app_servers() {
            app_log!("agent.direct_codex.gui_exit.shutdown_failed: {error}");
        }
@@ -2562,6 +2571,7 @@ fn main() {
            pick_local_project_directory,
            rename_local_game_project,
            suggest_automatic_project_name,
+            polish_local_project_prompt,
            pick_local_file,
            pick_client_extension_file,
            pick_client_extension_directory,
@@ -2613,6 +2623,7 @@ fn main() {
            upload_local_asset,
            register_local_asset,
            create_ui_design_resource,
+            update_local_project_resource_classification,
            derive_local_project_resource,
            list_pending_local_project_resource_edits,
            resume_local_project_resource_edit,
@@ -2645,6 +2656,7 @@ fn main() {
            import_local_project_image_assets,
            read_local_project_file,
            read_local_project_image_preview,
+            save_local_project_asset_file,
            read_local_project_text_preview,
            read_local_project_media_preview,
            cancel_local_project_resource_preview_scope,
@@ -2683,24 +2695,9 @@ fn main() {
            read_local_project_resource_canvas_layout,
            read_local_project_resource_graph,
            update_local_project_resource_canvas_layout,
-            create_local_project_asset_canvas_draft,
-            read_local_project_asset_canvas_draft,
-            discover_local_project_asset_canvas_draft,
-            update_local_project_asset_canvas_draft,
-            acknowledge_local_project_asset_canvas_candidate_layers,
-            import_local_project_asset_canvas_images,
-            store_local_project_asset_canvas_media,
-            stage_local_project_asset_canvas_image,
-            finalize_local_project_asset_canvas_generation_failure,
-            archive_failed_local_project_asset_canvas_generation,
-            generate_local_project_asset_canvas_image,
-            recover_local_project_asset_canvas_generations,
-            confirm_local_project_asset_canvas_generation_service_identity,
-            read_local_project_asset_canvas_media,
-            discard_local_project_asset_canvas_draft,
-            recover_local_project_asset_canvas_transactions,
-            commit_local_project_asset,
-            commit_local_project_asset_canvas_candidate,
+            delete_local_project_asset,
+            read_local_project_asset_references,
+            rename_local_project_asset,
            get_local_game_project_revision,
            get_local_game_manifest,
            download_agc_update,
@@ -488,6 +488,113 @@ const PREVIEW_FIT_BRIDGE_SCRIPT: &str = r#"(() => {
      if (!document.hidden) schedule();
    }, 500);
  };
+  const inspectMessageType = 'genarrative.local-preview-inspect.v1';
+  const inspectState = { enabled: false, overlay: null, current: null };
+  const inspectOverlay = () => {
+    if (inspectState.overlay) return inspectState.overlay;
+    const overlay = document.createElement('div');
+    overlay.dataset.genarrativePreviewInspect = 'true';
+    overlay.style.cssText = 'position:fixed;z-index:2147483647;pointer-events:none;border:2px solid #f97316;background:rgba(249,115,22,0.14);box-shadow:inset 0 0 0 1px rgba(255,255,255,0.85);';
+    (document.body || document.documentElement).appendChild(overlay);
+    inspectState.overlay = overlay;
+    return overlay;
+  };
+  const clearInspectOverlay = () => {
+    inspectState.overlay?.remove();
+    inspectState.overlay = null;
+    inspectState.current = null;
+  };
+  const inspectElementSummary = (element) => {
+    const rect = element.getBoundingClientRect();
+    const tag = element.tagName ? element.tagName.toLowerCase() : 'div';
+    const role = (element.getAttribute && element.getAttribute('role')) || '';
+    const text = (element.innerText || element.textContent || '')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .slice(0, 120);
+    const resourceIds = [];
+    if (element.getAttribute) {
+      for (const name of ['data-resource-id', 'data-asset-id', 'data-genarrative-resource-id']) {
+        const value = element.getAttribute(name);
+        if (value && !resourceIds.includes(value)) resourceIds.push(value);
+      }
+    }
+    const media = element.querySelector ? element.querySelector('img,video,audio') : null;
+    const rawSource =
+      (element.getAttribute && element.getAttribute('src')) ||
+      (media && media.getAttribute && media.getAttribute('src')) ||
+      '';
+    let sourcePath = '';
+    if (rawSource) {
+      try {
+        sourcePath = new URL(rawSource, window.location.href).pathname;
+      } catch {
+        sourcePath = '';
+      }
+    }
+    return {
+      label: text || tag,
+      elementTag: tag,
+      elementRole: role.slice(0, 80),
+      text,
+      width: Math.max(1, Math.round(rect.width)),
+      height: Math.max(1, Math.round(rect.height)),
+      resourceIds,
+      sourcePath,
+    };
+  };
+  const postInspect = (action, selection) => {
+    window.parent.postMessage({ type: inspectMessageType, action, selection }, '*');
+  };
+  const stopInspect = (cancelled) => {
+    if (!inspectState.enabled) return;
+    inspectState.enabled = false;
+    document.removeEventListener('mousemove', handleInspectMove, true);
+    document.removeEventListener('click', handleInspectClick, true);
+    document.removeEventListener('keydown', handleInspectKeyDown, true);
+    clearInspectOverlay();
+    postInspect(cancelled ? 'cancelled' : 'disabled');
+  };
+  const handleInspectMove = (event) => {
+    if (!inspectState.enabled) return;
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+    inspectState.current = target;
+    const rect = target.getBoundingClientRect();
+    const overlay = inspectOverlay();
+    overlay.style.left = `${rect.left}px`;
+    overlay.style.top = `${rect.top}px`;
+    overlay.style.width = `${rect.width}px`;
+    overlay.style.height = `${rect.height}px`;
+  };
+  const handleInspectClick = (event) => {
+    if (!inspectState.enabled) return;
+    event.preventDefault();
+    event.stopPropagation();
+    const target = event.target;
+    if (target instanceof Element) postInspect('selected', inspectElementSummary(target));
+    stopInspect(false);
+  };
+  const handleInspectKeyDown = (event) => {
+    if (!inspectState.enabled || event.key !== 'Escape') return;
+    event.preventDefault();
+    stopInspect(true);
+  };
+  const startInspect = () => {
+    if (inspectState.enabled) return;
+    inspectState.enabled = true;
+    document.addEventListener('mousemove', handleInspectMove, true);
+    document.addEventListener('click', handleInspectClick, true);
+    document.addEventListener('keydown', handleInspectKeyDown, true);
+    postInspect('enabled');
+  };
+  window.addEventListener('message', (event) => {
+    if (event.source !== window.parent) return;
+    const data = event.data;
+    if (!data || data.type !== inspectMessageType) return;
+    if (data.action === 'enable') startInspect();
+    else if (data.action === 'disable') stopInspect(false);
+  });
  if (ready) activate();
  else window.addEventListener('load', activate, { once: true });
 })();"#;
@@ -651,7 +758,14 @@ pub(crate) fn start_local_game_preview_at_revision(
    }
    let (preview, previous_preview) = registry.set_running(preview, stop);
    if let Some(previous_preview) = previous_preview.as_ref() {
-        record_replaced_preview_stop(previous_preview);
+        // 同一个项目重启预览（换监听线程、换端口）时，旧的 registry 身份与新预览共享
+        // 同一份落盘记录：上面刚写进去的是 running，这里若再用旧预览收尾，就会把它覆盖
+        // 成 stopped，下次进项目便丢掉"预览在跑"这条事实。只有旧预览属于**另一个项目**
+        // 时才替它收尾（那才是真的换项目）。
+        let previous_status = local_preview_status_from_result(previous_preview);
+        if ensure_preview_belongs_to_project(&previous_status, root).is_err() {
+            record_replaced_preview_stop(previous_preview);
+        }
    }
    if let Err(error) = append_preview_start_trace_step(root, &preview) {
        let _ = registry.stop();
@@ -685,14 +799,44 @@ pub(crate) fn stop_local_game_preview_for_root(
    registry: &PreviewRegistry,
 ) -> Result<LocalPreviewStatus, String> {
    let (status, stopped) = registry.stop_for_project(root);
-    if let Some(root) = root.filter(|_| stopped) {
-        record_preview_state(root, GameCreationAppPreviewStatus::Stopped, None, None)?;
-        append_preview_log(root, "stopped", None)?;
-        append_preview_stop_trace_step(root)?;
+    let Some(root) = root else {
+        return Ok(status);
+    };
+    // 没有活体预览可停时，落盘记录仍可能是陈旧的 running：预览服务器是进程内线程、
+    // 非 Linux 端口还是随机临时端口，客户端退出后记录会一直写着 running。这时把记录
+    // 对齐成 stopped 才算真的"停"——否则下次进项目会照着陈旧记录渲染打不开的运行
+    // 界面（进入项目时的活体核对是第二道保险，记录本身也该在自己的生命周期里结束）。
+    let stale_record = !stopped
+        && read_manifest_for_project(root)?
+            .preview
+            .is_some_and(|preview| preview.status == GameCreationAppPreviewStatus::Running);
+    if !stopped && !stale_record {
+        return Ok(status);
    }
+    record_preview_state(root, GameCreationAppPreviewStatus::Stopped, None, None)?;
+    append_preview_log(root, "stopped", None)?;
+    append_preview_stop_trace_step(root)?;
    Ok(status)
 }

+/// 退出路径：把当前预览真正停掉，并把落盘记录对齐成 stopped。
+///
+/// 客户端退出是"记录与真相分叉"的主要来源（进程内监听线程随进程消失，记录却留着
+/// running），所以退出时统一收尾。进入项目时的活体核对仍然保留：进程被强杀、断电这类
+/// 不走退出路径的情况，靠那道核对自愈。
+pub(crate) fn stop_local_game_preview_on_exit(registry: &PreviewRegistry) -> Result<(), String> {
+    let status = registry.status();
+    if status.status != "running" {
+        return Ok(());
+    }
+    let Some(root) = status.root.as_deref() else {
+        // running 却没有 root 不该出现：只把 listener 停掉，不猜记录该写到哪个项目。
+        registry.stop();
+        return Ok(());
+    };
+    stop_local_game_preview_for_root(Some(Path::new(root)), registry).map(|_| ())
+}
+
 #[tauri::command]
 pub(crate) fn stop_local_game_preview_if_matches(
    project_path: String,
@@ -4,7 +4,8 @@ use similar::TextDiff;
 use std::io::{Seek, SeekFrom};

 mod agent_db;
-mod asset_canvas;
+mod asset_export;
+mod asset_rename;
 mod checkpoint;
 mod conversation;
 mod export;
@@ -19,7 +20,8 @@ mod verification;
 mod write_lock;

 pub(crate) use agent_db::*;
-pub(crate) use asset_canvas::*;
+pub(crate) use asset_export::*;
+pub(crate) use asset_rename::*;
 pub(crate) use checkpoint::*;
 pub(crate) use conversation::*;
 pub(crate) use export::*;
@@ -3537,6 +3537,16 @@ pub(crate) struct ProjectAppendGuard<'a> {
    _os_lock: File,
 }

+/// append 锁的等待口径与项目写锁对齐：`agent/runtime_actions/project_gates.rs:1821-1823`
+/// 是 5ms × 2000（≈10s 完整窗口）/ 200（≈1s 短窗口），这里曾经是 10ms × 100 ≈ 1s。
+const PROJECT_APPEND_LOCK_RETRY_INTERVAL: Duration = Duration::from_millis(5);
+const PROJECT_APPEND_LOCK_WAIT_ATTEMPTS: usize = 2_000;
+const PROJECT_APPEND_LOCK_SHORT_WAIT_ATTEMPTS: usize = 200;
+
+/// 锁超时文案里的稳定片段：控制流（DirectProject 失败提示、收尾重试判据）只认这个常量，
+/// 不各自复制一份中文（改一次文案等于改一次重试语义）。
+pub(crate) const PROJECT_APPEND_LOCK_TIMEOUT_MARKER: &str = "跨进程锁超时";
+
 impl ProjectAppendLock {
    fn lock_process(&self, error_label: &str) -> Result<std::sync::MutexGuard<'_, ()>, String> {
        self.process_lock
@@ -3544,12 +3554,30 @@ impl ProjectAppendLock {
            .map_err(|_| format!("获取{error_label}进程内锁失败：锁已损坏"))
    }

+    /// 追加写入口，走完整等待窗口（≈10s）。这条等待的失败会直接变成用户可见的
+    /// "写历史失败"，而持锁方可能正在做一件 O(文件大小) 的事（整份读历史）甚至等 UAC，
+    /// 1s 的窗口在这种对手面前必然打满。
    pub(crate) fn lock(&self, error_label: &str) -> Result<ProjectAppendGuard<'_>, String> {
+        self.lock_with_attempts(error_label, PROJECT_APPEND_LOCK_WAIT_ATTEMPTS)
+    }
+
+    /// 只读入口，沿用短窗口（≈1s）：调用方本来就会重跑（面板刷新、下一轮 prompt 组装），
+    /// 长时间阻塞只会把它一起拖住。
+    pub(crate) fn lock_short(&self, error_label: &str) -> Result<ProjectAppendGuard<'_>, String> {
+        self.lock_with_attempts(error_label, PROJECT_APPEND_LOCK_SHORT_WAIT_ATTEMPTS)
+    }
+
+    fn lock_with_attempts(
+        &self,
+        error_label: &str,
+        max_attempts: usize,
+    ) -> Result<ProjectAppendGuard<'_>, String> {
        let process_guard = self
            .process_lock
            .lock()
            .map_err(|_| format!("获取{error_label}进程内锁失败：锁已损坏"))?;
-        let os_lock = acquire_project_append_os_lock(&self.os_lock_path, error_label)?;
+        let os_lock =
+            acquire_project_append_os_lock(&self.os_lock_path, error_label, max_attempts)?;
        Ok(ProjectAppendGuard {
            _process_guard: process_guard,
            _os_lock: os_lock,
@@ -3606,21 +3634,111 @@ fn project_append_os_lock_path(path: &Path) -> Result<PathBuf, String> {
        .join(format!("{}.lock", &fingerprint[..32])))
 }

-fn acquire_project_append_os_lock(path: &Path, error_label: &str) -> Result<File, String> {
+fn acquire_project_append_os_lock(
+    path: &Path,
+    error_label: &str,
+    max_attempts: usize,
+) -> Result<File, String> {
    if let Some(parent) = path.parent() {
        ensure_game_creator_private_directory_tree(parent, error_label)?;
        prepare_game_creator_private_path_for_read(parent, true, error_label)?;
    }
    prepare_game_creator_private_path_for_read(path, false, error_label)?;
-    for attempt in 0..100 {
-        if let Some(file) = try_open_project_append_os_lock(path, error_label)? {
+    let max_attempts = max_attempts.max(1);
+    for attempt in 0..max_attempts {
+        if let Some(mut file) = try_open_project_append_os_lock(path, error_label)? {
+            refresh_project_append_lock_diagnostic(&mut file, error_label);
            return Ok(file);
        }
-        if attempt < 99 {
-            thread::sleep(Duration::from_millis(10));
+        if attempt + 1 < max_attempts {
+            thread::sleep(PROJECT_APPEND_LOCK_RETRY_INTERVAL);
        }
    }
-    Err(format!("获取{error_label}跨进程锁超时：{}", path.display()))
+    Err(format!(
+        "获取{error_label}{PROJECT_APPEND_LOCK_TIMEOUT_MARKER}：{}（{}）",
+        path.display(),
+        project_append_lock_holder_diagnostic(path)
+    ))
+}
+
+/// 超时时报出"谁在持锁"，只读锁文件里的诊断元数据。
+///
+/// 它**只用于报错文案**：不判活、不回收、不抢占。读不到就明说读不到——现场最怕的是
+/// 一句"检查运行时配置"，那既不是现象也不是动作。
+fn project_append_lock_holder_diagnostic(path: &Path) -> String {
+    let Ok(content) = fs::read_to_string(path) else {
+        return "持锁方身份不可读：锁文件正被独占持有或已不可读".to_string();
+    };
+    let Ok(record) = serde_json::from_str::<serde_json::Value>(&content) else {
+        return "持锁方身份不可读：锁文件里没有可解析的诊断元数据".to_string();
+    };
+    let pid = record.get("pid").and_then(serde_json::Value::as_u64);
+    let label = record.get("label").and_then(serde_json::Value::as_str);
+    let started_at = record
+        .get("processStartedAt")
+        .and_then(serde_json::Value::as_u64);
+    match (pid, label, started_at) {
+        (Some(pid), Some(label), Some(started_at)) => {
+            format!("持锁方 pid={pid}（进程启动于 {started_at}，取锁用途 {label}）")
+        }
+        (Some(pid), Some(label), None) => format!("持锁方 pid={pid}（取锁用途 {label}）"),
+        (Some(pid), None, _) => format!("持锁方 pid={pid}"),
+        (None, ..) => "持锁方身份不可读：锁文件里没有 pid".to_string(),
+    }
+}
+
+/// 把"谁在持这把锁"写进锁文件，供事后排障；同一进程重复取同一把锁时不重复写。
+///
+/// 所有权是句柄本身，不靠文件内容成立：这里写失败绝不影响取锁结果。诊断元数据也不参与
+/// 任何判活/回收/抢占判断（既有口径见 docs/project-memory/shared-memory/decision-log.md
+/// 2026-09-09「项目写锁残留回收与启动诊断」）。
+fn refresh_project_append_lock_diagnostic(file: &mut File, error_label: &str) {
+    let pid = std::process::id();
+    let mut current = String::new();
+    if file.seek(SeekFrom::Start(0)).is_ok()
+        && std::io::Read::read_to_string(file, &mut current).is_ok()
+        && serde_json::from_str::<serde_json::Value>(&current)
+            .ok()
+            .and_then(|value| value.get("pid").and_then(serde_json::Value::as_u64))
+            == Some(u64::from(pid))
+    {
+        return;
+    }
+    let Ok(serialized) = serde_json::to_string(&serde_json::json!({
+        "acquiredAt": unix_timestamp(),
+        "label": error_label,
+        "pid": pid,
+        "processStartedAt": crate::project::project_write_lock_process_start_time_seconds(
+            u64::from(pid)
+        ),
+    })) else {
+        return;
+    };
+    if file.set_len(0).is_err() || file.seek(SeekFrom::Start(0)).is_err() {
+        return;
+    }
+    let _ = file.write_all(serialized.as_bytes());
+    let _ = file.flush();
+}
+
+/// 测试专用探针：判断某个追加写目标此刻是否被别人持有 OS 锁。
+///
+/// 用与生产完全同一套打开方式（Windows 零共享句柄 / Unix `flock(LOCK_EX|LOCK_NB)`）去探同一
+/// 把锁文件：拿得到 ⇒ 没人持锁；拿不到 ⇒ 有人持锁。锁文件尚未创建同样算"没人持锁"（这里
+/// 刻意不创建它，探针不留副作用）。探针拿到的句柄立刻释放。
+#[cfg(test)]
+pub(crate) fn project_append_os_lock_is_held_for_test(path: &Path) -> Result<bool, String> {
+    let lock_path = project_append_os_lock_path(path)?;
+    if !lock_path.exists() {
+        return Ok(false);
+    }
+    match try_open_project_append_os_lock(&lock_path, "追加写锁探针")? {
+        Some(file) => {
+            drop(file);
+            Ok(false)
+        }
+        None => Ok(true),
+    }
 }

 #[cfg(unix)]
@@ -3694,6 +3812,22 @@ fn try_open_project_append_os_lock(path: &Path, error_label: &str) -> Result<Opt
    }
 }

+/// 释放锁句柄之后才执行可能弹 UAC 的 ACL 提权修复。
+///
+/// `held_lock` 按值接收刚打开（因而正被持有）的锁句柄：调用点必须把所有权交出来，于是
+/// "一边持锁一边等 UAC" 在这个签名下无法被表达。函数体第一件事就是 `drop`，之后才提权；
+/// 修复成功后调用方返回"这轮没取到锁"，由外层重试循环重新打开，按修复后的 DACL 通过严格校验。
+#[cfg(windows)]
+fn release_project_append_os_lock_then_repair_acl(
+    held_lock: File,
+    path: &Path,
+    strict_error: &str,
+) -> Result<(), String> {
+    drop(held_lock);
+    crate::secure_windows_game_creator_path_for_current_user_with_auto_elevation(path, false, true)
+        .map_err(|repair_error| format!("{strict_error}；自动提权修复未完成：{repair_error}"))
+}
+
 #[cfg(windows)]
 fn try_open_project_append_os_lock(path: &Path, error_label: &str) -> Result<Option<File>, String> {
    use std::os::windows::fs::OpenOptionsExt;
@@ -3713,15 +3847,23 @@ fn try_open_project_append_os_lock(path: &Path, error_label: &str) -> Result<Opt
        Ok(file) => {
            crate::runner::validate_windows_regular_file_handle(&file, error_label)?;
            if !existed {
+                // 自建对象的本地收紧不会触发 UAC（既有口径：本进程新建的 Windows 私有对象
+                // 不因继承 DACL 自动提权），所以它留在持锁期间；**提权修复**不留在这里。
                if let Err(error) = harden_new_game_creator_private_path(path, false, error_label) {
                    drop(file);
                    let _ = fs::remove_file(path);
                    return Err(error);
                }
            }
-            crate::secure_windows_game_creator_path_for_current_user_with_auto_elevation(
-                path, false, true,
-            )?;
+            // 严格校验留在持锁期间（对象就是刚打开的这个句柄），**修复移到锁外**：提权修复会
+            // `Start-Process -Verb RunAs -Wait` 同步等用户点 UAC，在这里等它等于把"用户犹豫的
+            // 时间"记进别人的持锁窗口（1s 预算必然打满，而且只有 Windows 有这条路径）。
+            if let Err(error) =
+                crate::secure_windows_game_creator_path_for_current_user(path, false, true)
+            {
+                release_project_append_os_lock_then_repair_acl(file, path, &error)?;
+                return Ok(None);
+            }
            crate::runner::validate_windows_regular_file_handle(&file, error_label)?;
            Ok(Some(file))
        }
@@ -3088,3 +3088,146 @@ fn agent_db_tail_repair_handles_an_exact_limit_record() {
    fs::remove_dir_all(valid_root).ok();
    fs::remove_dir_all(invalid_root).ok();
 }
+
+/// append 锁的等待预算必须与项目写锁的完整窗口同口径。
+///
+/// 它曾经是 10ms × 100 ≈ 1s，而持锁方做的可能是"整份读一份 7MB 历史"甚至等 UAC：
+/// 那个窗口必然打满，打满的后果是用户直接看到"写历史失败"。这条用例把口径钉在常量上，
+/// 谁把它改回 1s 都会红。
+#[test]
+fn append_lock_wait_budget_matches_the_project_write_lock_window() {
+    assert_eq!(
+        PROJECT_APPEND_LOCK_RETRY_INTERVAL,
+        std::time::Duration::from_millis(5)
+    );
+    assert_eq!(PROJECT_APPEND_LOCK_WAIT_ATTEMPTS, 2_000);
+    assert_eq!(PROJECT_APPEND_LOCK_SHORT_WAIT_ATTEMPTS, 200);
+    assert!(
+        PROJECT_APPEND_LOCK_RETRY_INTERVAL * 2_000 >= std::time::Duration::from_secs(10),
+        "append 锁完整窗口必须 >= 项目写锁的 10s"
+    );
+    assert!(
+        PROJECT_APPEND_LOCK_RETRY_INTERVAL * 200 <= std::time::Duration::from_secs(1),
+        "只读短窗口必须留在 1s 级，避免把面板读路径一起拖住"
+    );
+}
+
+fn append_lock_test_target(test_name: &str) -> (PathBuf, PathBuf) {
+    let root = unique_agent_db_test_root(test_name);
+    let target = root.join(".agent/conversations/project.jsonl");
+    fs::create_dir_all(target.parent().expect("history parent")).expect("history dir");
+    (root, target)
+}
+
+#[cfg(windows)]
+fn hold_lock_file_exclusively_for_test(path: &Path) -> File {
+    use std::os::windows::fs::OpenOptionsExt;
+    std::fs::OpenOptions::new()
+        .read(true)
+        .write(true)
+        .share_mode(0)
+        .open(path)
+        .expect("hold lock file exclusively")
+}
+
+#[cfg(unix)]
+fn hold_lock_file_exclusively_for_test(path: &Path) -> File {
+    use std::os::fd::AsRawFd;
+    let file = std::fs::OpenOptions::new()
+        .read(true)
+        .write(true)
+        .open(path)
+        .expect("open lock file");
+    let result = unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) };
+    assert_eq!(result, 0, "flock lock file");
+    file
+}
+
+/// 锁文件必须留下"谁在持锁"的诊断元数据：零字节锁文件让现场无法回答是谁在持锁，
+/// 而"可操作提示"正是靠它才能成立。这里也钉住"只诊断、不抢占"——元数据只被读来报错。
+#[test]
+fn append_lock_file_records_the_holder_for_postmortem() {
+    let (root, target) = append_lock_test_target("append-lock-diagnostic");
+    let lock = project_append_lock_for(&target).expect("resolve lock");
+    drop(
+        lock.lock("DirectProject 历史追加写")
+            .expect("acquire append lock"),
+    );
+
+    let lock_path = project_append_os_lock_path(&target).expect("lock path");
+    let raw = fs::read_to_string(&lock_path).expect("read lock file");
+    let record: serde_json::Value =
+        serde_json::from_str(&raw).expect("lock file carries diagnostic json");
+    assert_eq!(
+        record.get("pid").and_then(serde_json::Value::as_u64),
+        Some(u64::from(std::process::id())),
+        "{raw}"
+    );
+    assert_eq!(
+        record.get("label").and_then(serde_json::Value::as_str),
+        Some("DirectProject 历史追加写"),
+        "{raw}"
+    );
+    assert!(record.get("processStartedAt").is_some(), "{raw}");
+    assert!(record.get("acquiredAt").is_some(), "{raw}");
+
+    fs::remove_dir_all(&root).ok();
+}
+
+#[test]
+fn append_lock_holder_diagnostic_reports_the_recorded_pid() {
+    let (root, target) = append_lock_test_target("append-lock-holder-diagnostic");
+    let lock_path = project_append_os_lock_path(&target).expect("lock path");
+    fs::create_dir_all(lock_path.parent().expect("lock parent")).expect("lock dir");
+    fs::write(
+        &lock_path,
+        "{\"acquiredAt\":1,\"label\":\"测试用途\",\"pid\":4242,\"processStartedAt\":7}",
+    )
+    .expect("seed lock file");
+
+    let diagnostic = project_append_lock_holder_diagnostic(&lock_path);
+    assert!(diagnostic.contains("pid=4242"), "{diagnostic}");
+    assert!(diagnostic.contains('7'), "{diagnostic}");
+    assert!(diagnostic.contains("测试用途"), "{diagnostic}");
+
+    fs::remove_file(&lock_path).ok();
+    let missing = project_append_lock_holder_diagnostic(&lock_path);
+    assert!(missing.contains("身份不可读"), "{missing}");
+
+    fs::remove_dir_all(&root).ok();
+}
+
+/// 真的被别人独占持有时：超时文案必须报出锁路径与持锁方线索，而且**不留残留**——
+/// 释放后立刻要能重新取到（这把锁的所有权是句柄，所以本来就不该有 stale 回收）。
+#[test]
+fn append_lock_short_wait_times_out_with_the_holder_and_leaks_nothing() {
+    let (root, target) = append_lock_test_target("append-lock-timeout");
+    let lock = project_append_lock_for(&target).expect("resolve lock");
+    // 先让生产代码创建并收紧锁文件（本地 harden 只在首次创建时发生）。
+    drop(
+        lock.lock_short("DirectProject 历史追加写")
+            .expect("first acquire"),
+    );
+    let lock_path = project_append_os_lock_path(&target).expect("lock path");
+    let held = hold_lock_file_exclusively_for_test(&lock_path);
+
+    let error = match lock.lock_short("DirectProject 历史追加写") {
+        Ok(_guard) => panic!("exclusively held lock must not be acquired"),
+        Err(error) => error,
+    };
+    assert!(
+        error.contains(PROJECT_APPEND_LOCK_TIMEOUT_MARKER),
+        "{error}"
+    );
+    assert!(
+        error.contains("持锁方"),
+        "超时文案必须回答是谁在持锁：{error}"
+    );
+
+    drop(held);
+    drop(
+        lock.lock_short("DirectProject 历史追加写")
+            .expect("reacquire after release"),
+    );
+    fs::remove_dir_all(&root).ok();
+}
@@ -0,0 +1,249 @@
+use super::*;
+use std::fs::File;
+use std::io::{Read, Write};
+
+/// 显式保存：把项目内已登记的素材文件复制到用户选定的目标路径。
+///
+/// 这里刻意不做"浏览器下载"——AGC 是 Tauri/WebView2 宿主，未注册 `on_download`
+/// 时 `<a download>` 能否落盘不可靠，所以保存路径由原生对话框给出，复制由 Rust 完成。
+const ASSET_EXPORT_COPY_CHUNK_BYTES: usize = 64 * 1024;
+
+#[derive(Clone, Debug, Deserialize)]
+#[serde(deny_unknown_fields, rename_all = "camelCase")]
+pub(crate) struct SaveLocalProjectAssetFileInput {
+    pub(crate) project_path: String,
+    pub(crate) relative_path: String,
+    pub(crate) destination_path: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct SaveLocalProjectAssetFileResult {
+    pub(crate) destination_path: String,
+    pub(crate) byte_len: u64,
+}
+
+fn resolve_export_source_file(root: &Path, relative_path: &str) -> Result<PathBuf, String> {
+    let normalized = normalize_relative_path(relative_path.trim())?;
+    if normalized.is_empty() {
+        return Err("待保存的素材路径不能为空".to_string());
+    }
+    let source = root.join(&normalized);
+    // 只允许保存项目根内真实存在的普通文件：符号链接与目录都要拒绝。
+    let metadata = std::fs::symlink_metadata(&source)
+        .map_err(|error| format!("素材文件不存在或不可读：{error}"))?;
+    if metadata.file_type().is_symlink() {
+        return Err("素材路径不能是符号链接".to_string());
+    }
+    if !metadata.is_file() {
+        return Err("素材路径必须是普通文件".to_string());
+    }
+    Ok(source)
+}
+
+fn resolve_export_destination_file(destination_path: &str) -> Result<PathBuf, String> {
+    let trimmed = destination_path.trim();
+    if trimmed.is_empty() {
+        return Err("保存目标路径不能为空".to_string());
+    }
+    let destination = PathBuf::from(trimmed);
+    if destination.file_name().is_none() {
+        return Err("保存目标必须是文件路径".to_string());
+    }
+    let parent = destination
+        .parent()
+        .filter(|parent| !parent.as_os_str().is_empty())
+        .ok_or_else(|| "保存目标缺少父目录".to_string())?;
+    if !parent.is_dir() {
+        return Err("保存目标的父目录不存在".to_string());
+    }
+    if destination.is_dir() {
+        return Err("保存目标不能是目录".to_string());
+    }
+    Ok(destination)
+}
+
+pub(crate) fn save_local_project_asset_file_at(
+    input: SaveLocalProjectAssetFileInput,
+) -> Result<SaveLocalProjectAssetFileResult, String> {
+    let root = Path::new(input.project_path.trim());
+    validate_project_root(root)?;
+    enforce_project_auto_permission_policy(root, "file.read")?;
+
+    let source = resolve_export_source_file(root, &input.relative_path)?;
+    let destination = resolve_export_destination_file(&input.destination_path)?;
+
+    let mut reader = File::open(&source).map_err(|error| format!("打开素材文件失败：{error}"))?;
+    let mut writer =
+        File::create(&destination).map_err(|error| format!("创建保存目标失败：{error}"))?;
+    let mut buffer = vec![0_u8; ASSET_EXPORT_COPY_CHUNK_BYTES];
+    let mut byte_len = 0_u64;
+    loop {
+        let read = reader
+            .read(&mut buffer)
+            .map_err(|error| format!("读取素材文件失败：{error}"))?;
+        if read == 0 {
+            break;
+        }
+        writer
+            .write_all(&buffer[..read])
+            .map_err(|error| format!("写入保存目标失败：{error}"))?;
+        byte_len += read as u64;
+    }
+    writer
+        .flush()
+        .map_err(|error| format!("刷新保存目标失败：{error}"))?;
+
+    Ok(SaveLocalProjectAssetFileResult {
+        destination_path: destination.to_string_lossy().into_owned(),
+        byte_len,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    static NEXT_ASSET_EXPORT_TEST_ID: AtomicU64 = AtomicU64::new(0);
+
+    fn unique_asset_export_directory(prefix: &str) -> PathBuf {
+        std::env::temp_dir().join(format!(
+            "genarrative-asset-export-{prefix}-{}-{}",
+            std::process::id(),
+            NEXT_ASSET_EXPORT_TEST_ID.fetch_add(1, Ordering::Relaxed)
+        ))
+    }
+
+    fn create_export_project() -> (PathBuf, PathBuf) {
+        let root = unique_asset_export_directory("project");
+        let assets = root.join("assets");
+        std::fs::create_dir_all(&assets).expect("create project assets directory");
+        (root, assets)
+    }
+
+    #[test]
+    fn copies_registered_asset_to_chosen_destination() {
+        let (root, assets) = create_export_project();
+        let source_bytes = b"genarrative-asset-export-payload".to_vec();
+        std::fs::write(assets.join("hero.png"), &source_bytes).expect("write source asset");
+        let destination_directory = unique_asset_export_directory("destination");
+        std::fs::create_dir_all(&destination_directory).expect("create destination directory");
+        let destination = destination_directory.join("hero-copy.png");
+
+        let result = save_local_project_asset_file_at(SaveLocalProjectAssetFileInput {
+            project_path: root.to_string_lossy().into_owned(),
+            relative_path: "assets/hero.png".to_string(),
+            destination_path: destination.to_string_lossy().into_owned(),
+        })
+        .expect("save asset file");
+
+        assert_eq!(result.byte_len, source_bytes.len() as u64);
+        assert_eq!(result.destination_path, destination.to_string_lossy());
+        assert_eq!(
+            std::fs::read(&destination).expect("read copied asset"),
+            source_bytes
+        );
+        // 源素材保持不变：保存只是复制，不改动项目内文件。
+        assert_eq!(
+            std::fs::read(assets.join("hero.png")).expect("read source asset"),
+            source_bytes
+        );
+
+        let _ = std::fs::remove_dir_all(&root);
+        let _ = std::fs::remove_dir_all(&destination_directory);
+    }
+
+    #[test]
+    fn rejects_missing_source_asset() {
+        let (root, _assets) = create_export_project();
+        let destination_directory = unique_asset_export_directory("destination");
+        std::fs::create_dir_all(&destination_directory).expect("create destination directory");
+
+        let error = save_local_project_asset_file_at(SaveLocalProjectAssetFileInput {
+            project_path: root.to_string_lossy().into_owned(),
+            relative_path: "assets/missing.png".to_string(),
+            destination_path: destination_directory
+                .join("missing-copy.png")
+                .to_string_lossy()
+                .into_owned(),
+        })
+        .expect_err("missing source must fail");
+
+        assert!(error.contains("素材文件不存在或不可读"), "{error}");
+        let _ = std::fs::remove_dir_all(&root);
+        let _ = std::fs::remove_dir_all(&destination_directory);
+    }
+
+    #[test]
+    fn rejects_directory_as_source_asset() {
+        let (root, assets) = create_export_project();
+        std::fs::create_dir_all(assets.join("nested")).expect("create nested directory");
+        let destination_directory = unique_asset_export_directory("destination");
+        std::fs::create_dir_all(&destination_directory).expect("create destination directory");
+
+        let error = save_local_project_asset_file_at(SaveLocalProjectAssetFileInput {
+            project_path: root.to_string_lossy().into_owned(),
+            relative_path: "assets/nested".to_string(),
+            destination_path: destination_directory
+                .join("nested-copy")
+                .to_string_lossy()
+                .into_owned(),
+        })
+        .expect_err("directory source must fail");
+
+        assert!(error.contains("必须是普通文件"), "{error}");
+        let _ = std::fs::remove_dir_all(&root);
+        let _ = std::fs::remove_dir_all(&destination_directory);
+    }
+
+    #[test]
+    fn rejects_blank_destination_and_missing_parent_directory() {
+        let (root, assets) = create_export_project();
+        std::fs::write(assets.join("hero.png"), b"payload").expect("write source asset");
+
+        let blank = save_local_project_asset_file_at(SaveLocalProjectAssetFileInput {
+            project_path: root.to_string_lossy().into_owned(),
+            relative_path: "assets/hero.png".to_string(),
+            destination_path: "   ".to_string(),
+        })
+        .expect_err("blank destination must fail");
+        assert!(blank.contains("保存目标路径不能为空"), "{blank}");
+
+        let missing_parent_directory = unique_asset_export_directory("absent");
+        let missing_parent = save_local_project_asset_file_at(SaveLocalProjectAssetFileInput {
+            project_path: root.to_string_lossy().into_owned(),
+            relative_path: "assets/hero.png".to_string(),
+            destination_path: missing_parent_directory
+                .join("hero-copy.png")
+                .to_string_lossy()
+                .into_owned(),
+        })
+        .expect_err("missing parent directory must fail");
+        assert!(
+            missing_parent.contains("保存目标的父目录不存在"),
+            "{missing_parent}"
+        );
+
+        let _ = std::fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn rejects_destination_that_is_an_existing_directory() {
+        let (root, assets) = create_export_project();
+        std::fs::write(assets.join("hero.png"), b"payload").expect("write source asset");
+        let destination_directory = unique_asset_export_directory("destination");
+        std::fs::create_dir_all(&destination_directory).expect("create destination directory");
+
+        let error = save_local_project_asset_file_at(SaveLocalProjectAssetFileInput {
+            project_path: root.to_string_lossy().into_owned(),
+            relative_path: "assets/hero.png".to_string(),
+            destination_path: destination_directory.to_string_lossy().into_owned(),
+        })
+        .expect_err("directory destination must fail");
+
+        assert!(error.contains("保存目标不能是目录"), "{error}");
+        let _ = std::fs::remove_dir_all(&root);
+        let _ = std::fs::remove_dir_all(&destination_directory);
+    }
+}
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`你是游戏创作需求的润色助手。把用户给创作 Agent 的一段需求改写成更清晰、可执行的中文需求。要求：保留用户的原始意图、玩法、美术方向、数值与限制条件，不得新增或删除需求点，不得替用户做决定，不得写成方案书或任务清单。只输出润色后的需求正文，不要解释、不要引言、不要 Markdown 标记、不要引号包裹、不要重复用户原文；无法润色时原样输出用户输入。`