fui-skill

FUI Skill

使用 FUI 的元数据驱动方式开发 Web 模块，其中 UI 和逻辑均以 JSON 定义。

执行环境

根据环境以不同方式应用此 Skill：

• 编辑器／扩展／工作区环境：如果环境确实提供了本地模块文件夹和文件，请读取、创建和修改这些文件。直接应用规范的本地模块结构。
• 聊天应用／Agent 聊天环境：不要假定可以访问本地文件、存在现有工作区，或模块文件夹已经存在。请根据粘贴的 JSON、代码片段、截图或明确提供的文件附件进行处理。仍要应用规范的模块结构，将预期文件虚拟化，整理回复，并判断缺少哪些内容。
• 环境不明确：根据可用工具和材料推断。如果没有明确提供工作区或本地文件，请默认采用适用于聊天环境的处理方式，不要假装读取或更新从未提供过的文件。

模块结构

工作区分为两个层级。在编辑器或扩展环境中，直接创建或更新这些文件。在聊天环境中，使用相同结构将模块虚拟化，说明涉及哪些文件，并直接提供相关文件内容。

项目根目录（{projectId}/）

{projectId}/
|-- .fuix/                        (System metadata — DO NOT hand-edit)
|   |-- project.json              (Project metadata)
|   |-- runtime.json              (Project-level runtime config: apiDomain/login/menu...)
|   |-- modules.json              (Module list)
|   |-- components/               (Shared component registry + tree)
|   |-- imports/                  (Shared import registry)
|   `-- modules/{moduleId}/       (Per-module metadata: info.json, components.json, tree.json)
|-- components/uc-*.vue           (Project-scope custom components)
|-- imports/                      (Project-scope JS/CSS asset files)
`-- modules/                      (All modules live here)
    `-- {moduleId}/               (One folder per module — see below)

模块文件夹（modules/{moduleId}/）

{moduleId}/
|-- index.vue                     (Required: <fui-app lang="json"> config + <script> helper logic)
|-- body.html                     (HTMLOnly=false: supplementary; HTMLOnly=true: full page)
|-- style.css                     (Module CSS)
|-- header.html                   (Head inner content: <link>/<meta>/external <script> — NO <style>)
|-- imports/                      (Module-scope JS/CSS asset files)
`-- components/uc-*.vue           (Optional custom components, use `uc-` prefix)

模块元数据（ProjectID、ModuleID、Framework、HTMLOnly……）位于 .fuix/modules/{moduleId}/info.json 中——请读取，不要手动编辑。

完整的结构规则、旧→新映射表和检查清单，请参阅 module-structure.md。在工作区感知环境和聊天环境中都应应用该参考。

index.vue 结构

index.vue 将配置和逻辑整合在一个文件中：

• <fui-app lang="json"> 块——核心配置（替代旧的 module.json）。包含四个部分：

• data：响应式状态和具名 Action

• watch：在状态变化时触发 Action 的观察器

• controls：UI 布局（容器 > 行 > 列 > 元素）

• set：模块设置（标题、菜单）

<script> 块（替代旧的 script.js）包含 FUN／EXE Action、图表构建器和转换逻辑的辅助代码。

Action 协议

在 data 中将逻辑定义为具名 Action 对象。使用 CALL 执行。

Key	Description
API	要调用的端点
IN	输入参数（使用 vueData. 或 item. 引用）
OUT	存储响应（例如 "myList"）
CALLBACK	成功后执行的 Action
CONFIRM	先显示确认信息
MESS	提示消息
CALL	执行另一个具名 Action
IF/THEN/ELSE	条件逻辑
EXE	原生 JS（谨慎使用）

示例：

"fetchUsers": {
  "API": "/api/users",
  "IN": { "GroupID": "vueData.selectedGroup" },
  "OUT": "userList",
  "CALLBACK": { "MESS": "Loaded!" }
}

字面字符串规则（重要）

此规则适用于在 Action 协议的 IN 块中传递值的情况。 在 IN 中，如果字符串值不含空格，FUI 核心可能会将其作为表达式／变量求值。

要确保字符串值作为字面值处理，请使用以下任一种模式：

• 添加反引号前缀："id": "`winUser" 或 "id": "`winUser`"
• 在 JSON 字符串中用单引号包裹："id": "'winUser'"

建议用于 id、url 等字段，或 IN 中任何必须保持为纯文本的键：

{
  "FUN": "openWindow",
  "IN": {
    "id": "`winUser",
    "url": "'/fp/module?mid=123'"
  }
}

对于 Vue 组件属性（f-*、t-*、v-*），如果 attr中没有:，则默认将值视为纯字符串。 示例："url": "/fp/module?mid=123"` 已经是字面字符串属性。

布局系统（网格与控件）

重要规则：顶层的 controls 数组必须遵循强制网格系统结构。

1. 必需的 Grid Wrapper

所有控件都必须封装在 container > rows > cols 结构中：

"controls": [
  {
    "prop": "fluid grid-list-md",
    "rows": [
      {
        "prop": "row",
        "cols": [
          // Control Objects go here
        ]
      }
    ]
  }
]

2. 控件对象结构

在 cols 数组（或嵌套的 innerHTML）中，每个项目都是一个控件对象：

键	类型	描述
el	String	HTML 标签（div、span）、Vue 组件或 FUI 组件。
attr	Object	属性/指令（class、style、v-model、v-on:click）。不能使用 @。
w	Number/String	列宽。1-12（网格）或 pixel value。cols 中的项目必须设置此项。
col	Object	包装器配置。网格列的属性（class、style）。
innerHTML	String/Array	内容。可以是递归的控件对象数组。

示例：

{
  "el": "v-btn",
  "w": 6,
  "col": { "class": "text-center" },
  "attr": {
    ":disabled": "true",
    "color": "primary",
    "v-on:click": "CALL(vueData.submit)"
  },
  "innerHTML": "Submit"
}

innerHTML 支持 {{ }}

innerHTML 字符串可以使用 Vue 模板插值来绑定响应式文本。

{
  "el": "div",
  "w": 12,
  "innerHTML": "Xin chao {{formData.fullName}}"
}

布局规则

• 包装器：始终从 Grid Wrapper 开始。
• 不要使用 children：嵌套时使用 innerHTML（数组）。
• 属性：元素属性使用 attr。网格列属性使用 col。
• 事件：使用 v-on:click（有效 JSON），不要使用 @click。

Vuetify 2 样式规则

优先级：组件属性（color、outlined、dense、elevation）→ 工具类（pa-*、ma-*、d-flex、text-*、primary--text）→ 自定义类 → 最后使用内联 style。绝不要在组件 .vue 文件中编写 <style> 块（发布时会被丢弃）——将模块 CSS 放入 style.css。绝不要在 <template> 中使用反引号模板字符串。

说明

0. 开始前必须加载 reference——不可跳过此步骤：

   开始任何 FUI 任务前，必须阅读相关 reference。不得仅凭训练数据开始编写代码/JSON。

   任务类型	必须先阅读
   任何与 FUI 相关的任务	Tier A：controls-patterns.md · ui-patterns.md · module-structure.md
   UI 设计、选择组件	+ Tier B：component-quickref.md · component-table.md · components-input.md
   调用 API、编写 SP	+ Tier C：tapi-reference.md

   原因：reference 中的规则会随时间变化。训练数据无法反映当前规则——只有 reference 才是事实来源。先做错再查阅会使修复成本翻倍。

1. 操作前先确认环境：

   • 在具有工作区访问权限的编辑器或扩展环境中，先创建或更新实际的模块根目录（例如 my-module/），并将所有模块文件保存在其中。
   • 在聊天或 Agent 聊天环境中，除非环境确实支持，否则不要声称已创建文件夹或编辑文件。应使用相同的模块结构进行虚拟展示，在有帮助时展示文件夹树，并提供用户应使用的文件内容。
   • 在聊天中审查现有模块时，应询问所需的具体文件或代码片段，不要假设可以从磁盘读取这些内容。

2. 创建新模块：

   第一步——选择 UI 设计方案：编写任何代码前，询问用户或自行建议以下两种方案之一：

   方案	适用场景
   A — 纯 <fui-app> config	简单页面：显示数据、对单个表执行 CRUD、基础输入表单。文件较少，易于维护。
   B — Vue 组件（uc-*.vue）	复杂界面：包含多个区域的仪表盘、自定义布局、多处重复使用的 UI 逻辑，或 <fui-app> 中的 controls 超过约 200 行。组件有助于 AI 和开发者更好地掌控。

   如果用户未指定：请根据需求描述主动提议，不要擅自选择而不告知。简要说明提议理由，并等待确认。

   • index.vue（必需）：用于 UI 和逻辑配置的 <fui-app lang="json"> 块，以及用于辅助 JS 的 <script> 块。
   • style.css（可选）：模块 CSS。
   • header.html（可选）：<head> 内部内容——外部 CSS/JS 链接、<meta>。先检查 .fuix/modules/{moduleId}/info.json 中的 HTMLOnly，以确定哪些内容应放在这里。
   • body.html（HTMLOnly=false 时可选；HTMLOnly=true 时为整个页面）。
   • components/（可选）：自定义 Vue 组件。
   • 如果环境仅支持聊天，请将这些内容作为独立文件载荷返回，或放在明确标注的代码块中。
   • 创建自定义 Vue 组件时，除非用户明确需要与单个屏幕绑定的一次性组件，否则默认采用可复用的 prop/event/slot API。
   • 组件文件中绝不能添加 <style> 或 <style scoped>（发布时会被丢弃）。请将模块 CSS 放在 style.css 中。
   • 绝不能在 Vue <template> 标记内使用反引号模板字符串。

3. 参考文档与组件选择：优先使用 FUI f-* 组件——FUI 已内置许多功能，因此所需代码更少，也能更好地利用运行时。只有在没有合适的 FUI 对应组件时，才使用 v-*。请查阅 component-quickref.md 和 controls-patterns.md 中的优先级表。

   快速选择规则： 用 f-button 替代 v-btn · 用 f-date/f-time 替代 text-field + date parsing · 用 f-search 替代 v-autocomplete · 用 f-table（CRUD）/ f-table-view（只读）替代 v-data-table · 所有图表都使用 f-echart（f-chart 已弃用）。

   Tier A — 核心（任何 FUI 任务都先加载）： controls-patterns.md · ui-patterns.md · module-structure.md

   Tier B — 组件（设计 UI 时）： component-quickref.md · component-table.md · components-input.md · components-dialog.md · components-display.md · component-design.md · project-config.md

   Tier C — 专业领域（需要时）： tapi-reference.md · pdfmake.md · watcher-patterns.md · advanced-techniques.md · coding-standards.md · fastproject.md · default-function.md · script-map.md · ui-templates.md

   Tier D — 验证（交付前）： verification.md

4. 设计系统：需要做出界面设计决策时，请按以下优先级顺序执行：

   优先级 1 — 项目本地 DESIGN.md：检查项目根目录（workspace 中的 {projectId}/DESIGN.md）是否有 DESIGN.md 文件。如果有，请使用该文件——忽略以下所有选项。

   优先级 2 — 用户指定样式：如果用户要求使用特定品牌/样式（例如“使用 BMW 风格”“采用 Linear 风格”），请读取 design-md/<brand>/DESIGN.md，加载相应的设计系统。

   优先级 3 — AI 自行分析并选择：如果没有本地文件，且用户未指定，请查看 design-md/ 下的子目录，了解可用品牌，然后根据上下文（页面类型、用途、目标用户）自行分析并选择最合适的品牌：

   • 管理模块、CRUD、数据管理 → 读取 design-md/fui/DESIGN.md
   • 公共 HTML 页面、落地页、介绍页面 → 选择符合项目基调/行业的品牌
   • 不确定 → 先询问用户再选择

5. 模块评估：收到审查或评估模块的请求时，请根据 FUI 编码规范检查结构、JSON 标准、关注点分离、边缘情况和最佳实践。

6. 编辑 <fui-app> 配置：使用有效的 JSON。通过 vueData. 前缀引用状态。

   • 在支持工作区的环境中，编辑 index.vue 内的 <fui-app lang="json"> 块。
   • 在聊天场景中，返回更新后的 JSON 内容或针对性补丁片段，不要暗示可以访问文件系统。

7. UI 模板：复用 examples/ 中的模板，然后修改 API 和字段。

   • 在支持工作区的环境中，直接复制或调整模板文件。
   • 在聊天场景中，在回复中内嵌调整后的模板内容。

   可用示例：

   文件	适用场景
   component.vue	自定义 Vue 组件示例（uc-*）
   module-patterns.json	完整模块参考 — 组合使用 data/watch/controls：menuChucNang、TypeLoad、addNew 标志对话框、嵌套 IF/THEN/ELSE、批量操作、openWindow+button+ctrlhotkey、_.find、pushRouter、内联 f-menu、row-prop-object
   f-table-patterns.json	f-table 深入参考 — 所有 props、各种 header 类型（t-check/t-select/t-button/t-link/t-menu/v-chip-group/v-icon/divider）、完整的 ctrl-update、对话框中的 f-table、仅 default-item
   project-patterns.json	project 运行时配置参考（.fuix/runtime.json）— 完整结构：menuLeft/menu/menuStyle/menuComponent/domainSetting、基于 SystemRight+FunctionRight 的 right，以及与 <fui-app> set 的关系（按页面覆盖 title/menu/apiDomain）

持续改进

完成复杂任务后，询问 “是否有值得补充到 FUI skill 中的经验或模式？”。如果用户指出错误或更好的做法：立即更新或删除 references/ 中的信息。不要让过时信息继续留在 skill 中。