鸿蒙端动态能力注册表：ArkUI从/tools动态读取工具清单

鸿蒙专家

在鸿蒙应用开发中，端侧页面常因能力列表写死在代码里而面临频繁发版的问题。服务端每增加一个接口，端侧就得跟着改一次按钮逻辑、参数校验和风险提示。本文通过一个本机Agent Gateway的实践，介绍如何将工具能力整理成注册表，让鸿蒙端通过ArkUI动态读取，实现能力可发现、可扩展、可管控。

一、能力注册表结构
首先，Gateway启动后统一暴露所有能力，模型Key只留在Gateway环境变量中，鸿蒙端只与Gateway通信。端侧不再猜测服务端有什么接口，而是先读取`/tools`返回的能力清单。

每个工具包含固定字段：名称、描述、风险等级、是否需要确认、输入结构、返回示例。以`http_check`为例：

2. {
3.   "name": "http_check",
4.   "description": "检查一个HTTP地址是否能访问，用于发布前接口巡检。",
5.   "riskLevel": "medium",
6.   "needConfirm": true,
7.   "inputSchema": {
8.     "required": ["url"]
9.   }
10. }

复制代码

风险等级决定页面如何标注，`needConfirm`决定是否可直接执行，`inputSchema`用于Gateway进行参数校验。模型只能从注册表中挑选工具，无法越界。

二、低风险能力直接执行
对于只读本机Gateway状态的工具（如`time_now`和`local_status`），它们不修改数据也不碰外部系统，端侧可以放开直接执行。但即使低风险，每次调用仍需保留requestId，用于在终端、页面、Gateway日志中追踪一次调用的完整路径，方便排查。风险低不代表能跳过校验，Gateway仍会检查工具存在性和参数合规性。

三、未注册工具直接被拒
测试调用一个未注册的工具`delete_everything`，Gateway返回`TOOL_NOT_FOUND`，不做模糊匹配。注册表充当白名单，工具名必须存在，否则一律拒绝执行。这避免了智能体系统“看起来什么都懂”的隐患。

四、参数校验严格压在服务端
以`note_search`为例，它需要`query`参数。故意不传，Gateway返回`ARGUMENT_MISSING: query`；补上参数后才正常执行。参数校验必须放在服务端，不能仅依赖ArkUI页面。端侧可以做友好提示，但真正的防线在Gateway。`inputSchema`同时让端侧知道每个工具需要什么参数，页面据此动态展示输入框。

五、鸿蒙端动态生成能力列表
端侧页面核心是通过`loadTools()`请求`/tools`，将返回的`tools`列表存入`@State tools`，然后交给`List`渲染。页面设计为轻量能力控制台：顶部显示工具总数、可直接执行数、需要确认数；中间可按“全部、低风险、需确认”筛选；每行列出名称、描述、风险等级和确认策略。

加载完成后，鸿蒙端显示8个工具，其中7个可直接执行，1个需要确认。这些数字不是写死的，而是从注册表返回的数据实时计算得出。

六、执行结果同面板展示
点击`time_now`后，端侧拼装requestId（如`tool-registry-`+时间戳），POST到`/tools/call`，底部“最近执行”区域直接展示完整JSON结果。不跳转、不弹窗，用户能直接看到“点了哪个工具”和“工具回了什么”。

七、端侧叠加保守白名单
尽管注册表中7个工具标为低风险，但页面并未全部开放。通过`canRun`方法，除了检查`needConfirm`，还额外卡了一个工具名白名单，只放行`time_now`和`local_status`：

2. canRun(tool: ToolItem): boolean {
3.   return !tool.needConfirm && (tool.name === 'time_now' || tool.name === 'local_status')
4. }

复制代码

其余低风险工具显示“只读”，需要确认的工具显示“锁定”。两类不可点击状态用不同文案区分：前者表示“这一版还没放开”，后者表示“风险更高，要走确认流程”。端侧在服务端建议的基础上再加一层谨慎策略，宁可少放不抢跑。

可执行、只读、锁定三种状态通过`if (this.canRun(tool))`加三元判断动态生成，页面无需为每个工具单独写逻辑。筛选同样由`visibleTools()`按`filterMode`过滤，`lowRiskCount()`、`confirmCount()`直接在`@State tools`上计算，顶部统计和中部列表均跟随注册表数据变化，无一写死。

八、能力边界定型
至此，本机Gateway的能力边界清晰：模型只能从注册表挑工具，无法越界；参数不合schema被Gateway拦截；中风险工具在注册表中已标记需要确认。端侧不再靠写死的按钮，增加一个能力或修改风险等级只需重新拉一次`/tools`，ArkTS代码无需变动。

这个注册表是本机自建的简易方案，但它补全了加能力时最容易被忽略的环节：能力如何描述、何时触发、需要哪些参数、风险多高、返回什么。将这些信息集中到注册表并由端侧动态读取，加能力和改能力就从“改两处代码”变成“改一处配置”。对于鸿蒙开发者来说，这种方法能显著降低多端协同的维护成本，提升系统的可扩展性和安全性。

热心网友4

这个思路很实用，把能力注册表放在Gateway层面，端侧只做动态渲染，确实能解决频繁发版的问题。特别是端侧叠加一层保守白名单的处理，兼顾了灵活性和安全性——服务端建议低风险，端侧再根据自己的节奏逐步放开，既不会因为全开放而失控，也不会因为全锁定而失去动态能力的价值。想问一下，在实际项目里，这种“端侧白名单”的维护频率怎么样？是跟注册表同步更新，还是独立管理？

热心网友4

看了你的分享，感觉这个动态能力注册表的思路非常清晰，尤其是在端侧与服务端解耦、降低发版频率方面，确实能解决很多实际开发中的痛点。你提到的“能力如何描述、何时触发、需要哪些参数、风险多高、返回什么”集中到注册表，ArkUI侧只做动态渲染，这样维护成本和扩展灵活度都提升不少。 另外，服务端做参数校验和风险管控、端侧再叠加自己的保守白名单，这种双层防护设计很稳妥，既保证了安全，又让端侧可以按需慢慢放开能力。像“只读”“锁定”“可执行”三种状态的区分和可视化，也很有工程落地价值。 想请教一下，在实际项目里，如果多个端（比如手机、平板、车机）共用一个Gateway，注册表里不同端是否需要不同的风险等级或白名单策略？还是统一由Gateway根据来源端做差异化判断？期待进一步交流。

热心网友4

这篇实践分享非常有价值，尤其是“能力注册表+动态读取”的思路，确实能解决端侧写死能力列表带来的频繁发版痛点。从工具描述、风险分级到参数校验的完整管控链条，再到端侧ArkUI动态生成页面、叠加保守白名单的做法，逻辑很严谨。我特别认同“宁可少放不抢跑”的端侧策略，以及将参数校验严格压在服务端的防线设计——这样能真正实现能力可发现、可扩展、可管控。对于鸿蒙开发者来说，这种“改一处配置”而非“改两处代码”的方法，确实能显著降低多端协同的维护成本。想问下，Gateway端对`/tools`的返回缓存和刷新机制是如何设计的？如果注册表频繁变动，端侧是否考虑过定时轮询或事件推送来保持同步？