FlyonDeckservices 与 uses
声明本插件提供的服务，以及需要调用的外部服务。
Documentation content is currently available in Simplified Chinese.
服务用于后台插件之间的调用。提供方填写 contributes.services，消费方填写顶层 uses，并在 dependencies 中填写提供方包版本范围。随后消费方通过 context.plugins.call()调用。
#示例
服务提供方：
{
"apiVersion": 1,
"id": "example.service-provider",
"name": "数字服务提供方",
"version": "1.0.0",
"description": "数字服务提供方教学示例",
"hostPlatforms": [
"windows",
"macos",
"linux"
],
"main": "index.js",
"permissions": [],
"contributes": {
"services": [
{
"id": "numbers",
"title": "数字求和",
"version": 1,
"methods": [
"sum"
],
"titleKey": "services.numbers.title",
"methodSchemas": {
"sum": {
"argsSchema": {
"type": "object",
"properties": {
"values": {
"type": "array",
"items": {
"type": "number"
},
"maxItems": 100
}
},
"required": [
"values"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"total": {
"type": "number"
}
},
"required": [
"total"
],
"additionalProperties": false
}
}
}
}
]
},
"i18n": {
"defaultLocale": "zh-CN",
"resources": {
"zh-CN": "locales/zh-CN.json",
"en-US": "locales/en-US.json"
}
},
"nameKey": "plugin.name",
"descriptionKey": "plugin.description"
}消费方：
{
"apiVersion": 1,
"id": "example.service-consumer",
"name": "数字服务消费方",
"version": "1.0.0",
"description": "数字服务消费方教学示例",
"hostPlatforms": [
"windows",
"macos",
"linux"
],
"main": "index.js",
"permissions": [],
"contributes": {
"actions": [
{
"id": "sum",
"title": "远程求和",
"argsSchema": {
"type": "object",
"properties": {
"values": {
"type": "array",
"items": {
"type": "number"
},
"maxItems": 100
}
},
"required": [
"values"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"properties": {
"total": {
"type": "number"
}
},
"required": [
"total"
],
"additionalProperties": false
},
"titleKey": "actions.sum.title"
}
]
},
"uses": [
{
"pluginId": "example.service-provider",
"serviceId": "numbers",
"version": 1
}
],
"dependencies": {
"example.service-provider": "^1.0.0"
},
"i18n": {
"defaultLocale": "zh-CN",
"resources": {
"zh-CN": "locales/zh-CN.json",
"en-US": "locales/en-US.json"
}
},
"nameKey": "plugin.name",
"descriptionKey": "plugin.description"
}两份清单的服务 ID 和整数版本对应。每个服务方法必须通过 methodSchemas 声明参数和结果，由宿主在请求转发前和返回后校验。缺少或不完整的契约会导致清单校验失败。
#Service
清单位置：manifest.contributes.services[]。
#Service.id
string · 必填
服务 ID，在插件内唯一，最多 128 个字符。
#Service.title
string · 必填
服务名称。
#Service.version
integer · 必填
服务接口版本，正整数。消费方精确匹配这个值。
#Service.methods
string[] · 必填
可调用的方法名，1–32 项，不重复。
#Service.methodSchemas
Record<string, { argsSchema, outputSchema }> · 必填
键必须与 methods 完全对应，每个方法都需要契约；argsSchema 必须是对象 Schema，outputSchema 是结果 Schema。提供方可要求 plugins.serviceSchemas v1 宿主能力。
#Service.maxBytes
integer · 可选
每次服务请求、结果各自的 JSON 字节上限，默认 4096，允许 1024–65536。提高上限须显式声明。SDK 的 8 秒请求超时不变；超时不能撤销已经执行的业务，不自动重试写操作。
#ServiceUse
清单位置：manifest.uses[]。
#ServiceUse.pluginId
string · 必填
提供方的插件 ID。
#ServiceUse.serviceId
string · 必填
提供方声明的服务 ID。
#ServiceUse.version
integer · 必填
要调用的服务版本，正整数。
#包版本与接口版本
dependencies[pluginId] 匹配提供方的 SemVer 包版本，uses[].version 精确匹配服务接口整数版本。例如 ^1.0.0 与接口 1 是两个独立约束，必须同时满足。
安装和启动前会检查服务是否存在及接口版本是否匹配；调用时仍检查提供方是否运行、包版本、接口版本和方法。提供方仅升级包版本而保持接口不变时，消费方可继续使用允许范围内的新版本。
循环依赖会阻止安装或启动。先安装服务提供方，再安装消费方；宿主不会自动下载依赖。启动消费方会先启动已授权的依赖。停止或重启提供方前须先停止运行中的消费方；卸载提供方前须先卸载消费方。
#天气能力与独立界面
builtin.weather 1.2.0 起提供 forecast v1 服务：getForecast({city}) 查询归一化天气，searchCities({query?,selectedValue?}) 提供城市选项。公共服务使用 Open-Meteo，共用原有后台的五分钟缓存，不读取或共享其他小组件的彩云 Token。温度单位为摄氏度，风速沿用 Open-Meteo 的 km/h；缺测字段可能为 null。小时与日期字符串是查询城市的当地时间。
天气界面示例中的 weather-card 没有联网权限，仅调用提供方服务。消费方拥有自己的城市设置、页面和实例；提供方拥有数据源与缓存。