新增 DirectProject 用户 Response item 契约

新增 Rust canonical user item 与 Codex wire 转换模块增加 ts-rs 绑定目录及生成文件检查边界更新聊天素材引用规范与里程碑实施计划
2026-09-15 14:45:58 +08:00
parent 9aa6f5efea
commit dfd6fadedf
12 changed files with 372 additions and 4 deletions
@@ -17,6 +17,7 @@ mod design_tools;
 mod direct_codex_attachments;
 mod direct_codex_audit;
 mod direct_codex_references;
+mod direct_codex_user_item;
 mod direct_project_history;
 mod direct_project_turn_history;
 mod direct_runtime;
@@ -45,6 +46,7 @@ pub(crate) use design_runtime::*;
 pub(crate) use direct_codex_attachments::*;
 pub(crate) use direct_codex_audit::*;
 pub(crate) use direct_codex_references::*;
+pub(crate) use direct_codex_user_item::*;
 pub(crate) use direct_project_history::*;
 pub(crate) use direct_project_turn_history::*;
 pub(crate) use direct_runtime::*;
@@ -0,0 +1,231 @@
+use super::direct_codex_references::MAX_DIRECT_CODEX_REFERENCES;
+use super::*;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::path::Path;
+use ts_rs::TS;
+
+/// DirectProject 本轮 user input 的唯一结构化入口。
+///
+/// 该模块只负责 user item 的 schema、校验和 Codex wire 投影；assistant/raw item
+/// 仍由现有 app-server 链路处理，避免把两个方向的协议耦合在一个浅层 DTO 中。
+#[derive(Clone, Debug, Deserialize, Serialize, TS)]
+#[serde(tag = "type")]
+#[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/project-workspace/generated/"))]
+pub(crate) enum DirectCodexUserItem {
+    #[serde(rename = "message")]
+    Message(DirectCodexUserMessageItem),
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/project-workspace/generated/"))]
+pub(crate) struct DirectCodexUserMessageItem {
+    pub(crate) role: DirectCodexUserRole,
+    pub(crate) content: Vec<DirectCodexUserContentPart>,
+    pub(crate) id: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, TS)]
+#[serde(rename_all = "lowercase")]
+#[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/project-workspace/generated/"))]
+pub(crate) enum DirectCodexUserRole {
+    User,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, TS)]
+#[serde(tag = "type")]
+#[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/project-workspace/generated/"))]
+pub(crate) enum DirectCodexUserContentPart {
+    #[serde(rename = "input_text")]
+    InputText { text: String },
+    #[serde(rename = "agc_resource_reference")]
+    AgcResourceReference { resource_id: String },
+    #[serde(rename = "agc_runtime_region_reference")]
+    AgcRuntimeRegionReference(DirectCodexUserRuntimeRegionPart),
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/project-workspace/generated/"))]
+pub(crate) struct DirectCodexUserRuntimeRegionPart {
+    pub(crate) label: 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>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export, export_to = concat!(env!("CARGO_MANIFEST_DIR"), "/../src/features/project-workspace/generated/"))]
+pub(crate) struct DirectCodexUserMessageEnvelope {
+    pub(crate) item: DirectCodexUserItem,
+}
+
+pub(crate) fn validate_direct_codex_user_item(
+    root: &Path,
+    item: &DirectCodexUserItem,
+) -> Result<(), String> {
+    let DirectCodexUserItem::Message(message) = item;
+    if !matches!(message.role, DirectCodexUserRole::User) {
+        return Err("DirectProject 只接受 user message item".to_string());
+    }
+    if message.id.trim().is_empty() {
+        return Err("DirectProject user item 缺少稳定 id".to_string());
+    }
+    if message.content.is_empty() {
+        return Err("DirectProject user item content 不能为空".to_string());
+    }
+    let manifest = read_manifest_for_project(root)?;
+    let mut reference_count = 0usize;
+    for part in &message.content {
+        match part {
+            DirectCodexUserContentPart::InputText { text } => {
+                if text.trim().is_empty() {
+                    return Err("DirectProject input_text 不能为空".to_string());
+                }
+            }
+            DirectCodexUserContentPart::AgcResourceReference { resource_id } => {
+                reference_count = reference_count.saturating_add(1);
+                validate_resource_id_and_manifest(&manifest, resource_id)?;
+            }
+            DirectCodexUserContentPart::AgcRuntimeRegionReference(reference) => {
+                reference_count = reference_count.saturating_add(1);
+                validate_runtime_region_reference(&manifest, reference)?;
+            }
+        }
+    }
+    if reference_count > MAX_DIRECT_CODEX_REFERENCES {
+        return Err(format!("一次最多引用 {MAX_DIRECT_CODEX_REFERENCES} 个素材"));
+    }
+    Ok(())
+}
+
+fn validate_resource_id_and_manifest(
+    manifest: &GameCreationAppManifest,
+    resource_id: &str,
+) -> Result<(), String> {
+    let resource_id = resource_id.trim();
+    if resource_id.is_empty()
+        || resource_id.chars().count() > 200
+        || resource_id.chars().any(char::is_control)
+    {
+        return Err("引用的素材 ID 无效，请移除后重新选择".to_string());
+    }
+    let asset = manifest
+        .assets
+        .iter()
+        .find(|asset| asset.id == resource_id)
+        .ok_or_else(|| "引用的素材已不存在，请移除后重新选择".to_string())?;
+    sanitize_attachment_local_path(&asset.local_path)
+        .ok_or_else(|| "引用的素材路径无效，请移除后重新选择".to_string())?;
+    Ok(())
+}
+
+fn validate_runtime_region_reference(
+    manifest: &GameCreationAppManifest,
+    reference: &DirectCodexUserRuntimeRegionPart,
+) -> Result<(), String> {
+    if reference.label.trim().is_empty() {
+        return Err("运行画面区域缺少名称".to_string());
+    }
+    if reference.resource_ids.len() > MAX_DIRECT_CODEX_REFERENCES {
+        return Err(format!(
+            "运行画面区域一次最多关联 {MAX_DIRECT_CODEX_REFERENCES} 个素材"
+        ));
+    }
+    for resource_id in &reference.resource_ids {
+        validate_resource_id_and_manifest(manifest, resource_id)?;
+    }
+    Ok(())
+}
+
+/// 将 canonical user item 转为 app-server `turn/start.input` 可接受的文本数组。
+/// AGC 私有 part 只在这里投影为安全摘要，canonical item 本身不被修改。
+pub(crate) fn direct_codex_user_item_to_wire_input(
+    root: &Path,
+    item: &DirectCodexUserItem,
+) -> Result<Value, String> {
+    validate_direct_codex_user_item(root, item)?;
+    let manifest = read_manifest_for_project(root)?;
+    let DirectCodexUserItem::Message(message) = item;
+    let mut input = Vec::with_capacity(message.content.len());
+    for part in &message.content {
+        let text = match part {
+            DirectCodexUserContentPart::InputText { text } => text.clone(),
+            DirectCodexUserContentPart::AgcResourceReference { resource_id } => {
+                let asset = manifest
+                    .assets
+                    .iter()
+                    .find(|asset| asset.id == resource_id.trim())
+                    .ok_or_else(|| "引用的素材已不存在，请移除后重新选择".to_string())?;
+                let path = sanitize_attachment_local_path(&asset.local_path)
+                    .ok_or_else(|| "引用的素材路径无效，请移除后重新选择".to_string())?;
+                format!(
+                    "[素材引用 resourceId={}；项目路径={path}]",
+                    resource_id.trim()
+                )
+            }
+            DirectCodexUserContentPart::AgcRuntimeRegionReference(reference) => {
+                let resources = reference
+                    .resource_ids
+                    .iter()
+                    .map(|id| id.trim())
+                    .collect::<Vec<_>>()
+                    .join(",");
+                let mut summary = format!("[运行画面区域：名称={} ", reference.label.trim());
+                if let Some(run_id) = reference.run_id.as_deref() {
+                    summary.push_str(&format!("运行标识={} ", run_id.trim()));
+                }
+                if let Some(role) = reference.element_role.as_deref() {
+                    summary.push_str(&format!("角色={} ", role.trim()));
+                }
+                if let Some(text) = reference.text.as_deref() {
+                    summary.push_str(&format!("文本={} ", text.trim()));
+                }
+                if !resources.is_empty() {
+                    summary.push_str(&format!("关联素材={resources}"));
+                }
+                summary.push(']');
+                summary
+            }
+        };
+        input.push(serde_json::json!({ "type": "text", "text": text }));
+    }
+    Ok(Value::Array(input))
+}
+
+pub(crate) fn direct_codex_user_item_to_prompt(
+    root: &Path,
+    item: &DirectCodexUserItem,
+) -> Result<String, String> {
+    let wire = direct_codex_user_item_to_wire_input(root, item)?;
+    wire.as_array()
+        .ok_or_else(|| "DirectProject user item wire input 不是数组".to_string())
+        .map(|parts| {
+            parts
+                .iter()
+                .filter_map(|part| part.get("text").and_then(Value::as_str))
+                .collect::<String>()
+        })
+        .and_then(|prompt| {
+            if prompt.trim().is_empty() {
+                Err("DirectProject user item 不能转换为空 prompt".to_string())
+            } else {
+                Ok(prompt)
+            }
+        })
+}
@@ -0,0 +1,10 @@
+// This file is generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+import type { DirectCodexUserRuntimeRegionPart } from './DirectCodexUserRuntimeRegionPart';
+
+export type DirectCodexUserContentPart =
+  | { type: 'input_text'; text: string }
+  | { type: 'agc_resource_reference'; resourceId: string }
+  | ({
+      type: 'agc_runtime_region_reference';
+    } & DirectCodexUserRuntimeRegionPart);
@@ -0,0 +1,5 @@
+// This file is generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+import type { DirectCodexUserMessageItem } from './DirectCodexUserMessageItem';
+
+export type DirectCodexUserItem = DirectCodexUserMessageItem;
@@ -0,0 +1,11 @@
+// This file is generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+import type { DirectCodexUserContentPart } from './DirectCodexUserContentPart';
+import type { DirectCodexUserRole } from './DirectCodexUserRole';
+
+export type DirectCodexUserMessageItem = {
+  type: 'message';
+  role: DirectCodexUserRole;
+  content: DirectCodexUserContentPart[];
+  id: string;
+};
@@ -0,0 +1,3 @@
+// This file is generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type DirectCodexUserRole = 'user';
@@ -0,0 +1,13 @@
+// This file is generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type DirectCodexUserRuntimeRegionPart = {
+  label: string;
+  runId?: string;
+  versionId?: string;
+  elementTag?: string;
+  elementRole?: string;
+  text?: string;
+  width?: number;
+  height?: number;
+  resourceIds: string[];
+};
@@ -0,0 +1,5 @@
+export type { DirectCodexUserContentPart } from './DirectCodexUserContentPart';
+export type { DirectCodexUserItem } from './DirectCodexUserItem';
+export type { DirectCodexUserMessageItem } from './DirectCodexUserMessageItem';
+export type { DirectCodexUserRole } from './DirectCodexUserRole';
+export type { DirectCodexUserRuntimeRegionPart } from './DirectCodexUserRuntimeRegionPart';