⚡ Flux — 共享状态引擎
v2.3.0通过 Flux 状态引擎发布事件并查询共享世界状态，让多智能体共享观测、协调数据与追踪实体状态，实现实时协作。
by 详细分析 ▾
运行时依赖
版本
新增入门章节：检查 flux-core/directory 以发现可用命名空间与数据。
安装命令
点击复制技能文档
# Flux Skill 技能 Flux 是一个持久化、共享、基于事件溯源的世界状态引擎。代理发布不可变事件，Flux 推导出所有代理都能观察到的权威状态。 ## 核心概念 - Events（事件）：不可变的观察结果（温度读数、状态变更等） - Entities（实体）：由事件推导出的状态对象（传感器、设备、代理） - Properties（属性）：实体的键值属性（更新时合并——只需发送已变更的属性） - Streams（流）：逻辑事件命名空间（sensors、agents、system） - Namespaces（命名空间）：通过令牌鉴权实现多租户隔离（可选，用于公共实例） ## 前提条件 公共实例： https://api.flux-universe.com（在 flux-universe.com 购买命名空间——购买后自动分配名称，例如 dawn-coral） 本地实例： http://localhost:3000（默认，可通过 FLUX_URL 环境变量覆盖） 鉴权：将 FLUX_TOKEN 设置为你的 Bearer 令牌。公共实例必须设置；本地实例若关闭鉴权则可省略。 ## 命名空间前缀 所有实体 ID 必须加上命名空间前缀：yournamespace/entity-name 以命名空间 dawn-coral 为例： ``bash ./scripts/flux.sh publish sensors agent-01 dawn-coral/sensor-01 \ '{"temperature":22.5}' ./scripts/flux.sh get dawn-coral/sensor-01 ` 未带命名空间前缀的实体 ID 在启用鉴权的实例上将被拒绝。 ## 快速开始 首先验证连接： `bash ./scripts/flux.sh health ` 然后查看目录，了解 Flux Universe 中可用的数据： `bash ./scripts/flux.sh get flux-core/directory ` 目录列出所有活跃命名空间、实体数量及总计实体数——是发现系统数据流的好方式。 ## 脚本 使用 scripts/ 目录提供的 bash 脚本： - flux.sh - 主 CLI 工具 ## 常用操作 ### 发布事件 `bash ./scripts/flux.sh publish # 将 dawn-coral 替换为你的命名空间 # 示例：发布传感器读数 ./scripts/flux.sh publish sensors agent-01 dawn-coral/temp-sensor-01 '{"temperature":22.5,"unit":"celsius"}' ` ### 查询实体状态 `bash ./scripts/flux.sh get # 将 dawn-coral 替换为你的命名空间 # 示例：获取当前传感器状态 ./scripts/flux.sh get dawn-coral/temp-sensor-01 ` ### 列出所有实体 `bash ./scripts/flux.sh list # 按前缀过滤 ./scripts/flux.sh list --prefix scada/ ` ### 删除实体 `bash ./scripts/flux.sh delete # 示例：移除旧测试实体 ./scripts/flux.sh delete test/old-entity ` ### 批量发布事件 `bash # 将 dawn-coral 替换为你的命名空间 ./scripts/flux.sh batch '[ {"stream":"sensors","source":"agent-01","payload":{"entity_id":"dawn-coral/sensor-01","properties":{"temp":22}}}, {"stream":"sensors","source":"agent-01","payload":{"entity_id":"dawn-coral/sensor-02","properties":{"temp":23}}} ]' ` ### 检查连接器状态 `bash ./scripts/flux.sh connectors ` ### 管理员配置 `bash # 读取运行时配置 ./scripts/flux.sh admin-config # 更新（需要 FLUX_ADMIN_TOKEN） ./scripts/flux.sh admin-config '{"rate_limit_per_namespace_per_minute": 5000}' ` ## 使用场景 ### 多代理协作 代理向共享实体发布观察结果： `bash # 将 dawn-coral 替换为你的命名空间 # 代理 A 观察温度 flux.sh publish sensors agent-a dawn-coral/room-101 '{"temperature":22.5}' # 代理 B 查询当前状态 flux.sh get dawn-coral/room-101 # 返回：{"temperature":22.5,...} ` ### 状态追踪 追踪服务/系统状态： `bash # 将 dawn-coral 替换为你的命名空间 # 发布状态变更 flux.sh publish system monitor dawn-coral/api-gateway '{"status":"healthy","uptime":3600}' # 查询当前状态 flux.sh get dawn-coral/api-gateway ` ## API 端点 事件摄入： - POST /api/events —— 发布单个事件（限制 1 MB） - POST /api/events/batch —— 批量发布事件（限制 10 MB） 状态查询： - GET /api/state/entities —— 列出所有实体（支持 ?prefix= 和 ?namespace= 过滤） - GET /api/state/entities/:id —— 获取指定实体 实体管理： - DELETE /api/state/entities/:id —— 删除单个实体 - POST /api/state/entities/delete —— 批量删除（按命名空间/前缀/ID） 实时更新： - GET /api/ws —— WebSocket 订阅 Connectors： - GET /api/connectors —— 列出连接器及其状态 - POST /api/connectors/:name/token —— 存储 PAT 凭据 - DELETE /api/connectors/:name/token —— 移除凭据 管理员： - GET /api/admin/config —— 读取运行时配置 - PUT /api/admin/config —— 更新运行时配置（需要 FLUX_ADMIN_TOKEN） Namespaces（仅鉴权模式）： - POST /api/namespaces —— 注册命名空间（返回鉴权令牌） ## 注意事项 - 事件自动生成 UUID（无需提供 eventId） - Properties 合并更新——只需发送变更的属性，原有属性会被保留 - 时间戳字段必须为 epoch 毫秒（i64）——API 要求，flux.sh 会自动生成 - 状态在 Flux 中持久化（通过 NATS JetStream + 快照，重启后依旧存在） - 实体 ID 支持 / 进行命名空间划分（例如 scada/pump-01`）