chore: optimize schema protocol and example docs

Author: chilingling

packages/canvas/DesignCanvas/src/mcp/resources/editPageSchemaExample.md

@@ -3,14 +3,12 @@ import { pickSectionByHeading } from './utils'
 
 // 分节枚举与标题映射（左侧为模板入参 section，右侧为文档中的中文/英文二级标题）
 const EDIT_EXAMPLE_SECTION_TITLES: Record<string, string> = {
-  state: 'State 示例',
-  css: 'CSS 示例',
-  lifeCycles: 'LifeCycles 示例',
-  methods: 'Methods 示例',
-  schema: 'Schema 整体操作示例',
-  case: '实战案例：创建一个动态表单页面',
-  'do-dont': "Do & Don't 最佳实践",
-  faq: '常见问题解答'
+  overview: '概述',
+  state: 'State',
+  css: 'CSS',
+  lifeCycles: 'LifeCycles',
+  methods: 'Methods',
+  schema: 'Schema'
 }
 
 // 根资源：编辑页面 Schema 的示例（整份文档）

packages/canvas/DesignCanvas/src/mcp/resources/editPageSchemaExample.ts

@@ -2,24 +2,24 @@
 
 页面 schema 是 TinyEngine 在画布中表示页面/区块结构与行为的数据模型。其根节点（RootNode）涵盖样式、属性、状态、方法、生命周期、数据源与子节点树等信息。
 
-本协议文档用于帮助模型准确理解字段语义与约束，指导正确调用 `edit_page_schema` 工具进行编辑。
+## structure
 
-## 字段
+TinyEngine 的页面 schema 结构如下：
 
 ```typescript
 export interface IFuncType {
   type: 'JSFunction'
   value: string
 }
 
-// 关键字段（简化展示，与 TinyEngine 运行时 RootNode 结构一致）：
+// 关键字段：
 export interface RootNode {
   id?: string
-  componentName: string // 'Page' | 'Block' | 其他组件名
+  componentName: string
   fileName?: string
-  css?: string
+  css?: string // 页面 css，等同于 vue 的 style 标签内容
   props?: Record<string, any>
-  state?: Record<string, any> // 顶层键-值映射
+  state?: Record<string, any>
   lifeCycles?: Record<string, IFuncType> // { setup?: IFuncType, onMounted?: IFuncType, ... }
   methods?: Record<string, IFuncType>
   dataSource?: any
@@ -29,10 +29,12 @@ export interface RootNode {
 ```
 
 说明：
-- `state` 为对象（map），键是状态名，值可以是字面量或特殊结构（如 `JSResource`、`JSExpression`、`computed`、`accessor`）。`edit_page_schema` 的 `merge` 策略对其执行“顶层键”级别的新增、更新与删除。
+- `componentName` 为合法值：`Page` | `Block`。当前 schema 类型。page 为页面，block 为区块。
+- `fileName` 为文件名。TinyEngine 出码时，会根据 `fileName` 生成文件名。
+- `css` 为页面 CSS，等同于 vue 单文件的 style 标签内容。
+- `state` 为页面状态，等同于 vue 单文件中的 reactive 响应式对象。为对象（map），键是状态名。
 - `lifeCycles`、`methods` 的值必须是函数单元：`{ type: 'JSFunction', value: string }`。
-- `css` 为整页样式字符串，`merge` 策略为“末尾追加”；`replace` 为整体覆盖。
-- `children` 是可嵌套的节点树，涉及精细化增删改应使用“节点类工具”（如 `add_node`、`change_node_props` 等），而非本工具的 `schema` 合并。
+- `children` 为页面结构描述，等同于 vue 单文件的 template 标签内容。是可嵌套的节点树。
 
 ## State
 
@@ -44,42 +46,120 @@ export interface RootNode {
   - `remove`：删除指定顶层键；
   - 不会进行深层递归合并，聚焦于“顶层键”。
 
-示例（节选）：
+### 示例
+
+#### state 值示例
+
+1. 常规值示例：
 
 ```json
 {
-  "section": "state",
-  "strategy": "merge",
-  "payload": {
-    "add": {
-      "companyName": "",
-      "theme": {
-        "type": "JSExpression",
-        "value": "props.dark ? 'dark' : 'light'"
-      }
+  "state": {
+    "firstName": "Opentiny",
+    "age": 18,
+    "food": ["apple", "orange", "banana"],
+    "isLoading": false,
+    "desc": {
+      "description": "",
+      "money": 100,
+      "other": null,
+      "rest": [{"type": "primary", "text": "主要操作"}]
     },
-    "update": {
-      "buttons": [{ "type": "primary", "text": "主要操作" }]
+    "utilsExample": "this.utils.test()",
+    "methodExample": {
+      "type": "JSFunction",
+      "value": "function methodExample(){ return 'methodExample' }"
     },
-    "remove": ["deprecatedKey"]
+    "i18nExample": {
+      "type": "i18n",
+      "key": "lowcode.example"
+    }
   }
 }
 ```
 
+vue 等效代码：
+
+```javascript
+const state = vue.reactive({
+  firstName: "Opentiny",
+  age: 18,
+  food: ["apple", "orange", "banana"],
+  isLoading: false,
+  desc: {
+    description: "",
+    money: 100,
+    other: null,
+    rest: [{"type": "primary", "text": "主要操作"}]
+  },
+  utilsExample: utils.test(),
+  methodExample: function methodExample(){ return 'methodExample' },
+  i18nExample: t('lowcode.example')
+})
+```
+
+2. getter/setter 示例：
+
+```json
+{
+  "state": {
+    "firstName": "",
+    "lastName": "",
+    "fullName": {
+      "defaultValue": "",
+      "accessor": {
+        "getter": {
+          "type": "JSFunction",
+          "value": "function getter() { this.state.fullName = `${this.props.firstName} ${this.props.lastName}` }"
+        },
+        "setter": {
+          "type": "JSFunction",
+          "value": "function setter(val) { this.state.fullName = `${this.props.firstName} ${this.props.lastName}` }"
+        }
+      }
+    }
+  }
+}
+```
+
+vue 等效代码：
+
+```javascript
+const state = vue.reactive({
+  firstName: "",
+  lastName: "",
+  fullName: ""
+})
+
+vue.watchEffect(
+  wrap(function getter() {
+    this.state.fullName = `${this.props.firstName} ${this.props.lastName}`
+  })
+)
+
+vue.watchEffect(
+  wrap(function setter() {
+    this.state.fullName = `${this.props.firstName} ${this.props.lastName}`
+  })
+)
+```
+
 ## CSS
 
-- `merge`：在原有 CSS 文本末尾追加新片段（必要时自动换行）。
-- `replace`：整体覆盖。
+**说明**: 
 
-示例：
+- CSS 为页面 CSS，等同于 vue 单文件的 style 标签内容。
+- merge 策略：
+  - `merge`：在原有 CSS 文本末尾追加新片段（必要时自动换行）。
+  - `replace`：整体覆盖。
+
+### 示例
+
+1. css schema 示例
 
 ```json
 {
-  "section": "css",
-  "strategy": "merge",
-  "payload": {
-    "css": ".page-base-style{ padding:24px; }"
-  }
+  "css": ".container { padding: 24px; margin: 20px; }\n.button-danger.button{ display: flex; justify-content: center; }"
 }
 ```
 
@@ -93,18 +173,20 @@ export interface RootNode {
   - `remove`：删除指定键；
 - `replace`：以 `all` 重建或用 `add+update` 重建。
 
-示例：
+### 示例
+
+1. lifeCycles schema 示例：
 
 ```json
 {
-  "section": "lifeCycles",
-  "strategy": "merge",
-  "payload": {
-    "add": {
-      "onMounted": {
-        "type": "JSFunction",
-        "value": "function onMounted(){ this.getTableData && this.getTableData() }"
-      }
+  "lifeCycles": {
+    "setup": {
+      "type": "JSFunction",
+      "value": "function setup ({ props, state, watch, onMounted }) { console.log('lifecycle example') }"
+    },
+    "onMounted": {
+      "type": "JSFunction",
+      "value": "function onMounted(){ this.getTableData && this.getTableData() }"
     }
   }
 }
@@ -115,18 +197,16 @@ export interface RootNode {
 - 结构：`Record<string, IFuncType>`，`IFuncType` 同上。
 - `merge/replace` 行为与 `lifeCycles` 相同。
 
-示例：
+### 示例
+
+1. methods schema 示例
 
 ```json
 {
-  "section": "methods",
-  "strategy": "merge",
-  "payload": {
-    "add": {
-      "handleSearch": {
-        "type": "JSFunction",
-        "value": "function(e){ return ['搜索:', this.i18n('operation.search'), e] }"
-      }
+  "methods": {
+    "methodExample": {
+      "type": "JSFunction",
+      "value": "function methodExample() {\n  console.log('example')\n}\n"
     }
   }
 }
@@ -142,42 +222,104 @@ export interface Node {
   componentName: string
   props: Record<string, any>
   children?: Node[]
-  componentType?: 'Block' | 'PageStart' | 'PageSection'
-  slot?: string | Record<string, any>
+  componentType?: 'Block'
   loop?: Record<string, any>
   loopArgs?: string[]
   condition?: boolean | Record<string, any>
 }
 ```
 
-本工具不负责 `children` 的细粒度结构编辑。请优先使用节点类工具（如 `add_node`、`change_node_props`、`del_node` 等）。
-
-## Schema 合并策略
-
-当 `section = 'schema'` 且 `strategy = 'merge'` 时，仅支持对“顶层允许键”进行浅层更新：
-
-允许键清单：`css`、`lifeCycles`、`methods`、`state`、`props`、`fileName`、`componentName`、`dataSource`、`children`。
-
-注意：
-- 未在允许清单内的键将被忽略；
-- `children` 的细化变更请改用节点类工具；
-- `strategy = 'replace'` 会整体替换页面 schema，具有破坏性，须谨慎。
+### 示例
 
-## 常见陷阱
+1. 常规值示例
 
-1. 将 `state` 写成数组。应为对象（map）。
-2. `lifeCycles/methods` 未按 `JSFunction` 单元传入，或传入空字符串。
-3. 误用 `schema.merge` 期望深层合并。实际上仅“顶层允许键”的浅合并。
-4. 追加 CSS 时忘记换行导致样式黏连。
-5. 使用 `replace` 且未提前读取现有结构，轻易覆盖重要字段。
+```json
+{
+  "children": [
+    {
+      "componentName": "div",
+      "props": {
+        "className": "py-10 rounded-md"
+      },
+      "id": "2b2cabf0",
+      "children": [
+        {
+          "componentName": "TinyTimeLine",
+          "props": {
+            "active": "2",
+            "data": [
+              {
+                "name": "基础配置"
+              },
+              {
+                "name": "网络配置"
+              }
+            ],
+            "horizontal": true,
+            "style": "border-radius: 0px;"
+          },
+          "id": "dd764b17"
+        }
+      ]
+    }
+  ]
+}
+```
 
-## FAQ
+2. 使用 condition 进行条件渲染示例（等同于 vue 中的 v-if ）
 
-Q：如何确认当前页面结构？
-A：先调用 `get_page_schema` 工具查看再决定编辑策略。
+```json
+{
+  "children": [
+    {
+      "componentName": "div",
+      "props": {
+        "className": "py-10 rounded-md"
+      },
+      "id": "2b2cabf0",
+      "children": [],
+      "condition": {
+        "type": "JSExpression",
+        "value": "this.state.showContainer"
+      }
+    }
+  ]
+}
+```
 
-Q：为什么我的 `lifeCycles.update` 不生效？
-A：仅对已存在的键有效；若键不存在，请使用 `add` 或在 `replace` 模式下通过 `all` 重建。
+3. 使用 loop 与 loopArgs 进行循环渲染示例
 
-Q：是否支持按组件粒度更新 `children`？
-A：请改用节点类工具，如 `add_node`、`change_node_props`、`del_node` 等。
+```json
+{
+  "children": [
+    {
+      "componentName": "TinyButton",
+      "props": {
+        "text": {
+          "type": "JSExpression",
+          "value": "item.text"
+        },
+        "className": "component-base-style",
+        "key": {
+          "type": "JSExpression",
+          "value": "index"
+        },
+        "type": {
+          "type": "JSExpression",
+          "value": "item.type"
+        }
+      },
+      "children": [],
+      "id": "22455446",
+      "loop": {
+        "type": "JSExpression",
+        "value": "this.state.loopExample"
+      },
+      "loopArgs": [
+        "item",
+        "index"
+      ]
+    }
+  ]
+}
+```