重构文档

生成 HTML in js 样例时添加说明

apps/ai-game-creator-shell/src-tauri/src/ui_editor/html_renderer/mod.rs

@@ -36,12 +36,6 @@ pub(crate) fn render_ui_design_state_html(state: &State) -> Result<String, Strin
         json!({
             "format": "html-fragment",
             "treeCount": state.ui_trees.len(),
-            "note": r#"这是从用户手动调整过的UI设计文档生成的html示例.
-             * 必须尊重其中翻译出来的位置锚点等信息(作为示例表达容器式布局的除外).
-             * 生成规则默认根节点(们)占据整个窗口.
-             * 为了适应不同分辨率, 提供了css变量--ui-scale, 可以全局调整. (可以作为一个设置项或微调数据项)
-             * 由于这可能是示例页面的示例html描述, 禁止直接照抄: 请检查并实现交互逻辑, 页面关系, 动态内容, 容器式布局...
-             "#
         }),
     );
     let fonts = (!font_faces.is_empty()).then(|| {
@@ -107,15 +101,27 @@ pub(crate) fn render_ui_design_state_js(
         let escaped = escape_template_literal(&pretty_html_fragment(&fragment));
         modules.push(format!("export const {export_name} = `\n{escaped}\n`;"));
     }
-    let mut output = String::from(concat!(
-        "// UI 设计生成模块：仅导出 HTML 片段，不执行任何注入逻辑。\n",
-        "// 重新生成会覆盖本文件中的手动修改。\n",
-        "// 每个 tree 根节点已按对应 UI design 尺寸直接设置 --ui-scale。\n",
-        "// 注入示例（仅供 Agent 按需修改）：\n",
-        "// import { tree_example } from '/ui/generated-xxx.js';\n",
-        "// document.body.insertAdjacentHTML('beforeend', tree_example);\n",
-        "// const node = document.querySelector('[ui-node-id=\"...\"]');\n\n",
-    ));
+    let mut output = String::from(
+        r#"
+//这是从用户手动调整过的UI设计文档生成的html片段, 需要在合适的位置注入游戏中.
+// 注入示例:
+// import { tree_example } from '/ui/generated-xxx.js'; // 统一使用绝对路径这里
+// document.body.insertAdjacentHTML('beforeend', tree_example);
+// 生成规则默认根节点(们)占据整个窗口.
+//
+// 禁止直接修改本js模块因为它随时会被用户重新导出覆盖
+// 应用逻辑/修改方式, 使用稳定的ui-node-id来查找某个元素然后使用js修改.
+// const node = document.querySelector('[ui-node-id="..."]');
+//
+// html片段内注释包含了丰富的元数据需要你理解并且尽可能实现它们
+// 对于交互逻辑, 页面关系, 有不清楚的地方可以向用户询问
+// 对于动态内容,  此文档给出的可能只是一个(或几个在列表中)例子, 需要你根据游戏逻辑, 在js中动态实现.
+// 对于容器式布局, 文档可能错误地使用position来描述, 需要你合理地使用flex, grid, scrollable, overflow等重写.
+//
+// 必要时鼓励清理冗余的示例性的元素, 原则: 尽量保留复用原来的父级面板, patch其中的元素, 而不是替换整个面板
+"#,
+    );
+
     output.push_str(&modules.join("\n\n"));
     if !output.ends_with('\n') {
         output.push('\n');