[RFC]: 非活动字段注册机制（Inactive Field Registration Mechanism）
This is a?
New feature
Detailed description
中文：非活动字段注册机制
一、背景与问题
如今对于传统 IM 的官方接口，提供的 WebSocket 接口完全足够使用，LangBot 目前也集中于做这件事——通过适配器接收平台推送的消息事件，转换为内部统一的 MessageChain 格式进行处理。
但对于特定复杂场景来说，尤其大量收集数据与信息的社区 AI 管理、电商客服场景下，这些通过推送获得的字段根本不够使用。目前境况是：
大量第三方以及第二方接口都提供了大量 API 字段、工具以及信息收集能力
LangBot 私有电商消息平台 ESPL2 同样需要解决字段与信息不全的问题
但 LangBot 的 platform 层目前没有主动调用机制来获取这些“非活动性”的数据
像 AstrBot 这样的框架虽然提供了大量 API 以及针对 platform 的私有接口，但 SDK 完全无法实现通用。LangBot 虽然拥有完善的 SDK 机制，也不能很好地处理这个问题。
核心矛盾：LangBot 的适配器层当前主要负责消息的被动接收与转换，而大量平台能力（主动查询、主动操作）无法被上层系统（Agent、插件、ActionFlow）调用。
二、解决方案：非活动字段注册机制
我设计了以下系统，发挥 SDK 能动性，将其命名为非活动字段注册机制（Inactive Field Registration Mechanism） 。
“非活动”的含义：这些字段并非通过“活动”连接（WebSocket/Webhook 推送）被动获得，而是需要通过主动 API 调用去查询或操作的数据/能力。本机制独立于现有消息系统，是对适配器额外功能的完善，不使用本机制的适配器功能完全不受影响。
三、相关设计理念和技术细节
3.1 工具注册在适配器内完成
每个适配器都有自己的私有功能与基础功能。对于消息不能主动调用的字段来说，这些工具需要在适配器里注册。
通用字段：LangBot 内部会内置注册，提供开箱即用的基础能力
私有字段：由各个适配器自行注册，适配器开发者可根据平台特性声明自己支持的工具
注意：不需要增加额外的 YAML 配置文件，注册逻辑直接在适配器代码内完成，与现有适配器注册机制保持一致。
3.2 工具分为两类
工具注册分为两大类：
第一类：纯查询类（Query-Only）
仅从平台拉取数据，不改变平台状态
幂等操作，无副作用
示例：获取用户资料、获取群成员列表、获取订单详情、获取物流信息
第二类：查询+操作类（Query + Action）
既涉及数据查询，也涉及状态变更或写操作
非幂等，有副作用
示例：发布文章（先查后发）、更新订单状态（查+改）、禁言用户（查+操作）
两类工具在权限管理上应有不同策略——第二类工具的启用和调用应当更严格。
3.3 三种使用路径
注册后的适配器工具需要保证三种使用路径：
路径一：Agent 可调用的 Tool
LangBot 的 Local Agent 支持工具调用（Tool Calling / Function Calling），LLM 在对话中可发出工具调用请求，系统执行工具后将结果追加到上下文中。当前 LangBot 的工具来源包括插件和 MCP 服务器——适配器工具应当作为第三种工具来源，纳入 Agent 的工具调用循环。
路径二：插件可调用的 Keywords
插件可通过 Keywords 机制调用适配器工具。插件开发者只需声明需要的语义 ID，无需关心底层是哪个适配器。
路径三：ActionFlow 流程调用的卡片
ActionFlow（原 Workflow，因功能设计超模已更名）是 LangBot 正在设计中的流程编排系统。在 ActionFlow 中，适配器工具被封装为流程卡片（Card） ，供可视化流程编排使用——拖拽卡片、配置参数、连接上下游节点即可完成复杂流程设计。
3.4 官方语义抽象库
在不同 platform 下，同一个类似功能可能有不同的名称和实现。官方需要给出统一的语义抽象库，以下为实例：
| 语义 ID | 抽象含义 | 小红书 | 微信 | ESPL2 | |
|---|---|---|---|---|---|
favorite |
收藏 | — | 收藏文章 | — | — |
like |
点赞 | 对用户点赞 | 点赞文章 | 点赞朋友圈 | — |
publish_article |
发送文章 | 发 QQ 空间文章 | 发笔记 | 发朋友圈 | — |
get_order |
获取订单号 | — | — | — | 商品订单 |
get_logistics |
获取物流信息 | — | — | — | 商品物流信息 |
语义库的作用：
上层（Agent/插件/ActionFlow）通过语义 ID 调用，无需关心平台差异，并且适配器可选实现那一部分
每个适配器在注册工具时声明自己实现了哪些语义 ID（部分实现即可，功能不需全部重合）
语义库保证大部分日常可用场景的覆盖
3.5 权限管理
每个适配器的 tool 调用都需要勾选确认使用，参考 MCP 的授权模式：
第一层：工具级启用开关
Web 管理面板中，每个适配器下展示其注册的所有工具，管理员逐项勾选确认启用。默认情况下，纯查询类工具可默认开启，查询+操作类工具默认关闭，需管理员手动启用。
第二层：调用路径权限
Agent 调用：需在流水线扩展配置中开启“允许 Agent 调用适配器工具”
插件调用：插件安装时显示所需工具列表，管理员确认授权
ActionFlow 调用：流程发布时审核所引用工具的权限
第三层：细粒度授权
结合 LangBot 现有的访问控制机制：
可按用户/群组限制特定工具的调用
敏感工具（如订单状态更新）仅限管理员调用
对于适配器，增加可选列表确定这个适配器是否使用这个字段
第四层：审计日志
所有工具调用记录完整审计日志，便于追溯和合规。
四、与现有机制的兼容性
| 现有机制 | 与本提案的关系 |
|---|---|
| 插件 Tool | 适配器工具作为第三种工具来源，与插件 Tool、MCP Tool 并列 |
| MCP 协议 | 仅参考其设计理念（工具声明模式、权限确认机制、调用审计），本机制为 LangBot 原生实现，不依赖 MCP |
| 现有访问控制 | 工具权限管理复用现有访问控制框架 |
English: Inactive Field Registration Mechanism
I. Background & Problem Statement
For traditional IM platforms, the official WebSocket interfaces provided are entirely sufficient for standard use cases, and LangBot currently focuses on this — receiving platform-pushed message events through adapters and converting them into the internally unified MessageChain format for processing.
However, for specific complex scenarios — particularly community AI management requiring extensive data/information collection, and e-commerce customer service scenarios — the fields obtained through push notifications are far from sufficient. The current situation is:
Numerous third-party and second-party interfaces provide extensive API fields, tools, and information collection capabilities
LangBot's proprietary e-commerce messaging platform ESPL2 also needs to address the problem of incomplete fields and information
However, LangBot's platform layer currently lacks an active invocation mechanism to retrieve these "inactive" data
Frameworks like AstrBot provide numerous APIs and platform-specific private interfaces, but their SDKs are completely non-generalizable. Although LangBot has a well-established SDK mechanism, it still cannot adequately address this problem.
Core Contradiction: LangBot's adapter layer is currently primarily responsible for passive message reception and conversion, while a vast number of platform capabilities (active queries, active operations) cannot be invoked by upper-layer systems (Agent, Plugins, ActionFlow).
II. Solution: Inactive Field Registration Mechanism
I have designed the following system to leverage SDK proactivity, naming it the Inactive Field Registration Mechanism.
Meaning of "Inactive": These fields are not obtained passively through "active" connections (WebSocket/Webhook push). Rather, they are data/capabilities that require active API calls to query or operate. This mechanism is independent of the existing messaging system and serves as a supplement to adapter capabilities. Adapters that do not use this mechanism remain completely unaffected.
III. Design Philosophy & Technical Details
3.1 Tool Registration Is Completed Within the Adapter
Each adapter has its own private and basic functionalities. For fields that cannot be actively invoked through messages, these tools need to be registered within the adapter.
Common Fields: LangBot will have built-in registration internally, providing out-of-the-box basic capabilities
Private Fields: Registered by each adapter individually; adapter developers can declare the tools they support based on platform characteristics
Note: No additional YAML configuration files are required. Registration logic is implemented directly within the adapter code, consistent with the existing adapter registration mechanism.
3.2 Tools Are Divided into Two Categories
Tool registration is divided into two major categories:
Category 1: Query-Only
Only pulls data from the platform, does not change platform state
Idempotent operations, no side effects
Examples: Get user profile, get group member list, get order details, get logistics information
Category 2: Query + Action
Involves both data querying and state changes or write operations
Non-idempotent, has side effects
Examples: Publish article (query then post), update order status (query + modify), mute user (query + action)
The two categories of tools should have different permission management strategies — the enabling and invocation of Category 2 tools should be more strictly controlled.
3.3 Three Usage Paths
Registered adapter tools need to support three usage paths:
Path 1: Agent-Callable Tool
LangBot's Local Agent supports tool calling (Tool Calling / Function Calling). The LLM can issue tool call requests during conversations, and the system executes the tools and appends the results to the context. Currently, LangBot's tool sources include plugins and MCP servers — adapter tools should serve as the third tool source, integrated into the Agent's tool calling loop.
Path 2: Plugin-Callable Keywords
Plugins can call adapter tools through the Keywords mechanism. Plugin developers only need to declare the required semantic IDs, without needing to care which underlying adapter is used.
Path 3: ActionFlow Process-Callable Cards
ActionFlow (formerly Workflow, renamed due to the original design becoming over-scoped) is a process orchestration system currently being designed for LangBot. In ActionFlow, adapter tools are encapsulated as process cards (Cards) for visual process orchestration — drag and drop cards, configure parameters, and connect upstream/downstream nodes to complete complex process designs.
3.4 Official Semantic Abstraction Library
Across different platforms, the same or similar functionality may have different names and implementations. The official team needs to provide a unified semantic abstraction library. Examples are as follows:
| Semantic ID | Abstract Meaning | Xiaohongshu | ESPL2 | ||
|---|---|---|---|---|---|
favorite |
Favorite | — | Favorite post | — | — |
like |
Like | Like user | Like post | Like Moments | — |
publish_article |
Publish article | Post to Qzone | Post note | Post to Moments | — |
get_order |
Get order ID | — | — | — | Product order |
get_logistics |
Get logistics info | — | — | — | Product logistics |
Purpose of the Semantic Library:
Upper layers (Agent/Plugins/ActionFlow) invoke via semantic IDs without needing to care about platform differences, and adapters can optionally implement whichever parts they choose
Each adapter declares which semantic IDs it implements when registering tools (partial implementation is sufficient; functionalities do not need to completely overlap)
The semantic library ensures coverage of most daily-use scenarios
3.5 Permission Management
Each adapter's tool invocation requires check-box confirmation for use, drawing reference from MCP's authorization model:
Layer 1: Tool-Level Enable Switch
In the Web management panel, all registered tools are displayed under each adapter. Administrators check each item to confirm enabling. By default, Query-Only tools can be enabled by default, while Query+Action tools are disabled by default and require manual administrator enabling.
Layer 2: Invocation Path Permissions
Agent invocation: Requires enabling "Allow Agent to call adapter tools" in the pipeline extension configuration
Plugin invocation: Displays the required tool list during plugin installation; administrator confirms authorization
ActionFlow invocation: Reviews permissions of referenced tools when the process is published
Layer 3: Fine-Grained Authorization
Combined with LangBot's existing access control mechanisms:
Can restrict specific tool invocations by user/group
Sensitive tools (e.g., order status update) are restricted to administrator invocation only
For adapters, add an optional list to determine whether this adapter uses this field
Layer 4: Audit Logs
All tool invocations are logged with complete audit trails for traceability and compliance purposes.
IV. Compatibility with Existing Mechanisms
| Existing Mechanism | Relationship with This Proposal |
|---|---|
| Plugin Tool | Adapter tools serve as the third tool source, alongside Plugin Tools and MCP Tools |
| MCP Protocol | Only references its design philosophy — tool declaration pattern, permission confirmation mechanism, invocation auditing. This mechanism is a LangBot-native implementation and does not depend on MCP |
| Existing Access Control | Tool permission management reuses the existing access control framework |
Source: langbot-app/LangBot