FlexUI

跨端组件化 UI 框架 + 端侧 AI Agent
支持 HarmonyOS / Android / Web / iOS 多平台渲染，集成端侧 AI 能力

中文版 README

---

项目简介

FlexUI 是一个支持跨端（HarmonyOS / Android / Web / iOS）渲染的组件化 UI 框架，同时提供组件化接口适配层，支持以 HXML/CSS/JS 方式开发组件，并集成端侧 AI Agent 能力。

FlexUI 基于 glass-easel 框架重写，保持特性级兼容的同时增加了新功能。框架运行时不依赖特定环境，可在 Web、Node.js 及各类 JavaScript 环境中运行。

核心特性

• 多后端渲染：同一份组件代码运行在 DOM、Native（HarmonyOS/Android）等多种环境
• 声明式组件：完整的自定义组件系统（模板、事件、生命周期、属性/方法管理）
• 增量更新：基于 ProcGen 过程生成的编译时优化 + 路径级精确数据更新
• Shadow Tree：每组件独立的 Shadow Root，支持 slot 分发和样式隔离
• 组件化适配层：提供组件风格的接口适配层，支持 HXML/CSS/JS 组件开发
• 端侧 AI Agent：HarmonyOS 端侧 AI 助手，集成 LLM 对话、Skill 加载、工具调用
• TypeScript 优先：链式 API 提供完整类型推断

---

项目模块

模块	位置	说明
FlexUI Core	packages/flexui/	核心组件框架（模板、事件、Backend、Shadow Tree）
FlexUI Frontend	packages/flexui-frontend/	前端接口适配层（组件化 API、HXML/CSS/JS）
FlexUI Shadow Sync	packages/flexui-shadow-sync/	跨后端的 Shadow Tree 同步模块
Toolkit	toolkit/	构建工具链（编译器、Webpack 插件、LSP、DevTools）
FlexUI Engine	flexui-engine/	跨端原生渲染引擎（HarmonyOS / Android）
AI Agent	ai-agent/	HarmonyOS 端侧 AI Agent（LLM + Tools + Cards）
Skills	skills/	AI 辅助开发技能（组件开发、A2UI 生成、引擎调试）

---

模块详情

1. FlexUI Core (packages/flexui/) — 核心组件框架

@openflexui/core 是框架的运行时核心，提供组件定义、模板引擎、数据绑定、事件系统和 Backend 抽象等基础设施。

• 语言：TypeScript
• 构建：Rollup
• 详见：docs/design/flexui-core.md

2. FlexUI Frontend (packages/flexui-frontend/) — 前端接口适配层

@openflexui/frontend 将核心框架接口适配为组件风格的 API，配合 webpack 插件支持 HXML/CSS/JS 组件文件开发。

• 语言：TypeScript
• 依赖：@openflexui/core (peer)
• 详见：docs/design/flexui-frontend.md

3. FlexUI Shadow Sync (packages/flexui-shadow-sync/) — 跨后端同步

@openflexui/shadow-sync 通过消息通道 (Channel) 将组件树状态同步到多个渲染后端，支持增量传输和指令回放。

• 语言：TypeScript
• 依赖：@openflexui/core (peer)
• 详见：docs/design/flexui-shadow-sync.md

4. Toolkit (toolkit/) — 构建工具链

前端构建工具链，包含模板/样式编译器、Webpack 插件、LSP 分析器和 DevTools 调试工具。

子模块	语言	说明
flexui-template-compiler	Rust → WASM	HXML 模板 → ProcGen JavaScript
flexui-stylesheet-compiler	Rust → WASM	CSS 样式编译 + 作用域
flexui-webpack-plugin	JavaScript	Webpack 构建集成
flexui-analyzer	TypeScript	LSP 语言分析器 + VSCode 扩展
flexui-devtools	TypeScript	浏览器 DevTools 扩展
flexui-typescript	TypeScript	TypeScript 类型声明生成

• 详见：docs/design/toolkit.md

5. FlexUI Engine (flexui-engine/) — 原生渲染引擎

派生于 Hippy 框架，为 HarmonyOS 和 Android 提供原生渲染能力。包含 C++ DOM 实现、JS 驱动层、平台 Frameworks 和原生 Renderer。

子模块	说明
entry/	HarmonyOS 入口 App（FlexView 演示）
driver/js/	JS 引擎驱动（Hermes / V8）+ flexui-backend 适配器
dom/	C++ DOM 实现（Element 树、CSS、Flexbox 布局）
framework/	平台连接器（Android JNI / OHOS NAPI）
modules/	平台原生能力模块
renderer/native/	Android 原生渲染器
devtools/	调试与性能分析后端

• 详见：docs/design/flexui-engine.md

6. AI Agent (ai-agent/) — 端侧 AI Agent

运行在 HarmonyOS 设备上的 AI Agent，集成 LLM 客户端、Agent 循环、工具调用和 FlexView 卡片渲染。

子模块	说明
entry/	HarmonyOS 应用入口
agent-runtime/	Agent 运行时库（AgentRuntime、LlmClient、AgentLoop 等）

• 详见：docs/design/ai-agent.md

7. Skills (skills/) — AI 辅助开发技能

配套的 Claude Code / AI Skills，覆盖组件开发、引擎构建调试、A2UI 卡片生成等场景。

Skill	用途
flexui	FlexUI 组件开发知识库与最佳实践
flexui-engine/a2ui-generation	A2UI 卡片/页面生成
ai-mode-dev	HarmonyOS ArkTS AI 开发辅助
ai-mode-skills	AI 开发模式工具链：generate（源码→skills 分包生成）、validate（静态校验+真机执行+渲染验证）、eval（端到端评测引擎，13 节点管线+HTML 报告）

• 详见：docs/design/skills.md

---

快速开始

环境准备

• Node.js (LTS) + pnpm
• Rust + wasm32-unknown-unknown target + wasm-pack（用于编译工具链）
• DevEco Studio SDK + hdc + ohpm + hvigorw（用于 HarmonyOS 构建）

安装依赖

pnpm install

构建前端框架

# 构建所有 TypeScript 包 + Rust→WASM 编译器
pnpm -r run build

# 单独构建某个包
cd packages/flexui && pnpm run build
cd packages/flexui-frontend && pnpm run build

构建 HarmonyOS 引擎应用

# 完整开发周期：webpack → hvigorw HAP → 安装 → 启动
./build.sh dev

# AI Agent 应用
./build.sh dev-agent

🔧 CDP 调试（Chrome DevTools Inspector）

FlexUI 引擎已集成 FlexUI DevTools 调试管线，支持通过 Chrome DevTools 进行 Elements 元素审查、Console 日志、Sources 断点调试、Network 网络监控 等能力。

启动调试

# 终端 1：启动 devserver（首次启动会自动编译）
npx flexui-devserver --debug-only

# 终端 2：构建 + 部署 + hdc 端口转发
./build.sh dev

# 浏览器打开 Inspector
open http://localhost:38989/front_end/inspector.html

调试管线架构

设备 App (debugMode=true)
  │
  ├─ FlexUIEngine.ensureInit({debugMode: true})
  ├─ C++ DevTools Backend → ws://localhost:38989/debugger-proxy
  │
  ▼ hdc rport (device:38989 → PC:38989)
  │
  ▼ PC: flexui-devserver (端口 38989)
  │
  ├─ HTTP: Chrome DevTools 前端 (Elements/Console/Sources/Network)
  └─ WebSocket: CDP 协议中转

Debug Server 管理

npx flexui-devserver --debug-only    # 启动
# Ctrl+C                            # 停止
./build.sh status                   # 检查端口、HTTP、hdc rport 状态

技术细节

• 设备端 C++ 代码通过 ENABLE_INSPECTOR=true 编译（debug 与 release 构建均开启）
• debugMode: true 控制是否支持 devtools 调试（创建 JS inspector、连接 devtool）， debug 与 release 构建都生效；debugMode: false 时不创建 inspector、不连接 devtool
• 日志开关由构建类型控制：debug 构建默认开启，release 构建默认关闭（可用 enableLog: true 显式强制开启），与 debugMode 无关
• Bundle 仍从 rawfile 本地加载（仅 remoteServerUrl 显式配置时使用远程加载）
• Debug server 使用 toolkit/flexui-devtools/packages/flexui-devserver

---

开发工作流 (Development Workflow)

1. 编译 AI Demo

编译 demos/ascf-ai-demo，生成应用页面和 skills 分包所需的编译产物：

# 默认 development 模式
./build.sh build-demo

# 指定 release 模式（生产构建）
./build.sh build-demo release

编译产物位于 demos/ascf-ai-demo/entry/src/main/resources/rawfile/，包含：

• app.css.js / app.js — 应用级 bundle
• skills/ — 各 skill 的组件包、API 实现、配置等

说明：build-demo 是单一编译步骤。完整的 AI Agent 开发周期使用 ./build.sh dev-agent，它会依次执行： 编译 Demo → 同步 rawfile 到 agent → 构建 agent HAP → 安装 → 启动。

2. 构建 Skills 分包并上传

Skills 分包是端侧 AI Agent 的远程技能包，将 rawfile/skills/ 目录打包为 skills.hsp（Zip 格式），上传到 CDN，供 Agent 热加载使用。

# 构建 + 部署（默认）
./scripts/pkg-skills.sh

# 仅构建，不上传
./scripts/pkg-skills.sh --build-only

# 仅上传已构建的分包
./scripts/pkg-skills.sh --deploy-only

# 查看当前包的下载 URL 和二维码
./scripts/pkg-skills.sh --url-only

环境变量：

变量	默认值	说明
APP_ID	com.atomicservice.111	应用标识
APP_VER	当前时间戳 (ms)	版本号
SSH_HOST	root@with-ai.cn	CDN 服务器

工作流程：

1. 从 demos/ascf-ai-demo/entry/src/main/resources/rawfile 读取原始 skill 文件
2. 以 resources/rawfile/ 为根路径打包为 build/skills.hsp（Store 模式，无压缩）
3. SFTP 上传到 CDN 服务器 /usr/share/nginx/html/cards/<appId>/<version>/skills.hsp
4. 验证 HTTP 可访问性（返回 200）

注意：build-demo 编译是 pkg-skills 的前置步骤 — 确保先编译 demo，新修改的 skill 文件才会出现在 rawfile 中。

3. 查看日志与定位问题

开发过程中需要实时查看应用日志来定位渲染、JS 执行或 Agent 循环问题。

# 查看筛选后的应用日志（默认过滤关键词）
./build.sh logs

# 指定自定义过滤关键词
./build.sh logs "myKeyword|anotherPattern"

# 检查应用进程状态 + 崩溃事件
./build.sh status

日志过滤说明：

• ./build.sh logs 默认过滤关键词：flexui|ascf|ascf-demo|EntryAbility|Index|createNode|updateNode|flush|firstView|FirstContentful|onJsException|STATUS|engine
• ./build.sh logs "xxx|yyy" 使用自定义关键词
• ./build.sh status 检查进程是否存活，并输出 crash/fatal/onJsException 等关键事件

常用调试场景：

问题类型	过滤关键词	说明
Agent 启动流程	`AgentRuntime	AgentLoop
加载流程	`loadModule	firstView
JS 异常	`onJsException	assert
数据同步	`onInitialized	callUIFunction
引擎状态	`STATUS	engine

4. 打包 SDK

将 FlexUI 引擎打包为 SDK 产物（HAR / AAR），供其他项目集成使用。

# HarmonyOS（默认）— 输出 HAR 到 build/pkg-<date>/ohos/
./build.sh pkg
./build.sh pkg --release

# Android — 输出 AAR 到 build/pkg-<date>/android/
./build.sh pkg --platform android
./build.sh pkg --platform android --release

产物说明：

产物	HarmonyOS	Android	说明
flexui_engine	.har	.aar	原生渲染引擎（C++ DOM + JS 驱动 + 平台连接器）
agent_runtime	.har	.aar	Agent 运行时库（LLM 对话、工具调用、卡片渲染）
as_apis	.har	.aar	小程序 API 实现层

集成指南：各平台的详细集成步骤请参阅 HarmonyOS 集成文档 和 Android 集成文档。

运行测试

# TypeScript 包测试
cd packages/flexui && pnpm run test
cd packages/flexui-frontend && pnpm run test
cd packages/flexui-shadow-sync && pnpm run test

# Rust 编译器测试
cd toolkit/flexui-template-compiler && cargo test
cd toolkit/flexui-stylesheet-compiler && cargo test

---

文档

设计文档

文档	内容
FlexUI Core	核心框架架构、组件系统、Backend、模板引擎
FlexUI Frontend	前端适配层、内置组件、构建集成
FlexUI Shadow Sync	跨后端同步、MessageChannel、ViewController
Toolkit	编译器、Webpack 插件、LSP 分析器、DevTools
FlexUI Engine	原生渲染引擎架构、DOM、Driver、Renderer
AI Agent	端侧 AI Agent、AgentRuntime、Tool/Card 系统
Skills	AI 辅助开发技能系统
AI Mode Skills	AI 开发模式工具集设计（generate/validate/eval）

API 文档

• TSDoc for @openflexui/core
• TSDoc for @openflexui/frontend
• flexui-template-compiler (docs.rs)
• flexui-stylesheet-compiler (docs.rs)

---

技术栈总览

维度	技术
前端框架	TypeScript, Rollup
编译器	Rust → WASM (wasm-bindgen, wasm-pack)
原生渲染引擎	C++ (DOM), Java (Android), ArkTS (HarmonyOS)
JS 引擎	Hermes (HarmonyOS), V8 (Android)
AI Agent	ArkTS, LLM API (OpenAI Compatible), MCP
构建工具	Webpack, hvigorw, Gradle
包管理	pnpm workspace, ohpm (HarmonyOS), Cargo (Rust)

---

帮助与反馈

Bug 报告和功能请求欢迎提交至 GitCode Issues。