2.4 Extension 类型

头文件：

• include/extension_types.h

概述

ExtensionClient 模块用三层结构表达插件数据：基础信息、运行状态、完整详情。

GetList() 返回 std::vector<ExtensionInfo> ， Get(const std::string& name) 返回单个 ExtensionInfo ， C99 Arm_Extension_GetList / Arm_Extension_Get 会把同一结构序列化成紧凑 JSON 文本。

2.4.1 JSON 形状

单个插件详情：

{
  "extension": {
    "name": "demo",
    "author": "agilebot",
    "type": "easyservice",
    "scriptLang": "python",
    "description": "demo extension",
    "version": "1.0.0",
    "contact": "",
    "copyright": "",
    "license": "",
    "entry": "main.py",
    "url": "http://127.0.0.1:9000"
  },
  "state": {
    "enabled": true,
    "isRunning": true,
    "port": 9000
  }
}

插件列表：

[
  {
    "extension": {},
    "state": {}
  }
]

2.4.2 ExtensionBaseInfo

ExtensionBaseInfo 表示插件的基础元信息，来自返回 JSON 的 extensionClient 节点。它主要用于展示插件身份、判断插件类型，以及作为后续查询、启停和服务调用时的插件标识来源。

所有字段都是字符串，服务端缺字段或字段类型不匹配时，SDK 会补成空字符串。

字段	类型	说明	常见用途
name	std::string	插件名，也是插件的主要标识	传给 ExtensionClient::Get() 、 Toggle() 、 CallService()
author	std::string	插件作者	展示插件来源
type	std::string	插件类型，例如 EasyService 类插件	判断插件能力或在界面中分类
scriptLang	std::string	脚本语言，字段名保持服务端 camelCase	展示运行语言，例如 Python
description	std::string	插件说明	展示插件用途
version	std::string	插件版本	排查版本、展示版本号
contact	std::string	联系方式	展示维护者联系方式
copyright	std::string	版权信息	展示版权声明
license	std::string	许可证	展示授权信息
entry	std::string	插件入口文件	排查插件启动入口
url	std::string	Web 插件访问地址	打开 Web 页面或定位服务入口

2.4.3 ExtensionState

ExtensionState 表示插件的运行状态，来自返回 JSON 的 state 节点。

字段	类型	说明	业务侧常见用途
enabled	bool	插件是否启用	决定是否允许用户发起启停或调用
isRunning	bool	插件进程是否运行中，字段名保持服务端 camelCase	判断是否可以调用插件服务
port	int32_t	插件服务端口；缺失时默认 0	定位插件服务端口， 0 表示未提供有效端口

2.4.4 ExtensionInfo

ExtensionInfo 是 ExtensionClient 模块的统一返回结构：

• GetList() 返回 std::vector<ExtensionInfo>
• Get() 返回单个 ExtensionInfo
• C99 Arm_Extension_GetList / Arm_Extension_Get 返回同字段名 JSON

字段	类型	说明	业务侧常见用途
extensionClient	ExtensionBaseInfo	插件基础信息	读取插件名、类型、入口、版本等元数据
state	ExtensionState	插件运行状态	判断插件是否启用、是否运行、服务端口是多少

读取插件列表时，每个数组元素都是一个 ExtensionInfo 。读取单个插件详情时，返回的是同样的结构，只是只包含目标插件。

2.4.5 读法示例

你要判断的事	读取字段	说明
后续要操作哪个插件	info.extension.name	可继续传给 Get() 、 Toggle() 、 CallService()
插件是否能被调用	info.state.enabled 与 info.state.isRunning	通常需要启用且运行中才适合调用服务
插件服务在哪个端口	info.state.port	0 表示机器人本体侧服务没有返回有效端口
插件入口脚本	info.extension.entry	用于排查插件启动入口
插件类型与脚本语言	info.extension.type 与 info.extension.scriptLang	用于展示和分类

2.4.6 默认值约定

• 服务端返回缺字段时，字符串字段补空串。
• enabled / isRunning 缺失时补 false 。
• port 缺失或类型不合法时补 0 。

如果顶层 extensionClient / state 节点缺失，SDK 会按空对象处理，再逐字段补默认值。

2.4.7 C99 映射口径

C99 接口	输出内容
Arm_Extension_GetList	ExtensionInfo[] 的紧凑 JSON 文本
Arm_Extension_Get	单个 ExtensionInfo 的紧凑 JSON 文本

补充约定：

• C99 输出采用 UTF-8 紧凑 JSON，不带多余缩进。
• Arm_Extension_CallService 返回的是服务结果 result 的 JSON 文本，不属于 ExtensionInfo 结构族。