From 4133060dfe5867b6416193a1821daa2dafd313f5 Mon Sep 17 00:00:00 2001 From: RockChinQ Date: Sat, 31 Oct 2026 10:31:02 +0000 Subject: [PATCH] feat(api-tools): add operation documentation, risk, and exposure metadata LANG-229 Co-authored-by: multica-agent --- src/langbot/pkg/api/application/contracts.py | 9 + .../pkg/api/application/operation_docs.py | 1438 +++++++++++++++++ .../pkg/api/application/service_operations.py | 50 + 3 files changed, 1497 insertions(+) create mode 100644 src/langbot/pkg/api/application/operation_docs.py diff --git a/src/langbot/pkg/api/application/contracts.py b/src/langbot/pkg/api/application/contracts.py index 811d31fa8..232770f39 100644 --- a/src/langbot/pkg/api/application/contracts.py +++ b/src/langbot/pkg/api/application/contracts.py @@ -43,6 +43,9 @@ class Operation: streaming: bool = False def as_dict(self) -> dict: + from .operation_docs import get_operation_doc + + doc = get_operation_doc(self.operation_id, side_effect=self.side_effect) return { 'id': self.operation_id, 'version': self.version, @@ -53,4 +56,10 @@ class Operation: 'principals': sorted(self.principals) if self.principals is not None else None, 'input_schema': self.input_type.model_json_schema(), 'output_schema': TypeAdapter(self.output_type).json_schema(), + 'domain': doc.domain, + 'label': doc.label, + 'summary': doc.summary, + 'description': doc.description, + 'risk': doc.risk, + 'exposure': doc.exposure, } diff --git a/src/langbot/pkg/api/application/operation_docs.py b/src/langbot/pkg/api/application/operation_docs.py new file mode 100644 index 000000000..3d734335a --- /dev/null +++ b/src/langbot/pkg/api/application/operation_docs.py @@ -0,0 +1,1438 @@ +"""Application operation documentation and metadata for progressive tool disclosure.""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Literal + + +@dataclass(frozen=True, slots=True) +class OperationDoc: + domain: str + label: dict[str, str] + summary: str + description: str + risk: Literal['read', 'write', 'dangerous'] + exposure: Literal['none', 'assistant', 'all'] + + +DOMAINS: dict[str, dict] = { + 'adapter': { + 'label': {'zh_Hans': '适配器', 'en_US': 'Adapter'}, + 'summary': 'Inspect IM platforms and chat network adapters available in the workspace.', + }, + 'agent': { + 'label': {'zh_Hans': '智能体', 'en_US': 'Agent'}, + 'summary': 'Create and manage autonomous AI agents, inspect execution traces, and debug agent runs.', + }, + 'api_key': { + 'label': {'zh_Hans': 'API 密钥', 'en_US': 'API Key'}, + 'summary': 'Manage workspace API keys and access tokens.', + }, + 'assistant': { + 'label': {'zh_Hans': '助手', 'en_US': 'Assistant'}, + 'summary': 'Manage workspace assistant sessions and multi-turn conversations.', + }, + 'bot': { + 'label': {'zh_Hans': '机器人', 'en_US': 'Bot'}, + 'summary': 'Manage chat bots, configure message routing rules, and send outbound messages.', + }, + 'box': { + 'label': {'zh_Hans': '沙箱', 'en_US': 'Box'}, + 'summary': 'Inspect sandbox runtime environments, sessions, and execution errors.', + }, + 'extension': { + 'label': {'zh_Hans': '扩展', 'en_US': 'Extension'}, + 'summary': 'List and inspect available workspace extensions and integrations.', + }, + 'file': { + 'label': {'zh_Hans': '文件', 'en_US': 'File'}, + 'summary': 'Upload and manage workspace media files and documents.', + }, + 'knowledge': { + 'label': {'zh_Hans': '知识库', 'en_US': 'Knowledge Base'}, + 'summary': 'Manage knowledge bases, index documents, and retrieve relevant knowledge chunks.', + }, + 'mcp': { + 'label': {'zh_Hans': 'MCP 服务', 'en_US': 'MCP'}, + 'summary': 'Manage Model Context Protocol (MCP) server connections and access their resources.', + }, + 'model': { + 'label': {'zh_Hans': '模型', 'en_US': 'Model'}, + 'summary': 'Configure LLM, embedding, and reranking models used across workspace tasks.', + }, + 'monitoring': { + 'label': {'zh_Hans': '监控审计', 'en_US': 'Monitoring'}, + 'summary': 'View system and workspace performance metrics, token usage, and operation logs.', + }, + 'pipeline': { + 'label': {'zh_Hans': '流水线', 'en_US': 'Pipeline'}, + 'summary': 'Manage data processing pipelines, execution configurations, and chat sessions.', + }, + 'platform': { + 'label': {'zh_Hans': '平台', 'en_US': 'Platform'}, + 'summary': 'Configure host-level platform settings and installation components.', + }, + 'plugin': { + 'label': {'zh_Hans': '插件', 'en_US': 'Plugin'}, + 'summary': 'Discover, install, configure, and inspect workspace extensions and plugins.', + }, + 'provider': { + 'label': {'zh_Hans': '模型供应商', 'en_US': 'Model Provider'}, + 'summary': 'Manage model provider credentials, scan available remote models, and configure access.', + }, + 'requester': { + 'label': {'zh_Hans': '请求器', 'en_US': 'Requester'}, + 'summary': 'Inspect HTTP and API requesters used for model and external service connectivity.', + }, + 'settings': { + 'label': {'zh_Hans': '设置', 'en_US': 'Settings'}, + 'summary': 'Manage workspace governance, operation logs, and security policies.', + }, + 'skill': { + 'label': {'zh_Hans': '技能', 'en_US': 'Skill'}, + 'summary': 'Manage custom skill packages, author skill files, and install skill integrations.', + }, + 'stats': { + 'label': {'zh_Hans': '数据统计', 'en_US': 'Statistics'}, + 'summary': 'Access workspace-level aggregated usage statistics and summary counters.', + }, + 'system': { + 'label': {'zh_Hans': '系统', 'en_US': 'System'}, + 'summary': 'Inspect system health, setup wizard status, and global platform configuration.', + }, + 'task': { + 'label': {'zh_Hans': '任务', 'en_US': 'Task'}, + 'summary': 'Track background task status and long-running job executions.', + }, + 'tool': { + 'label': {'zh_Hans': '工具', 'en_US': 'Tool'}, + 'summary': 'Inspect registered executable tools and function signatures in the workspace.', + }, + 'webhook': { + 'label': {'zh_Hans': '网页钩子', 'en_US': 'Webhook'}, + 'summary': 'Manage incoming webhooks for external integrations and event triggers.', + }, + 'workspace': { + 'label': {'zh_Hans': '工作区', 'en_US': 'Workspace'}, + 'summary': 'Manage workspace metadata, membership invitations, and collaboration roles.', + }, +} + + +OPERATION_DOCS: dict[str, OperationDoc] = { + 'adapter.get': OperationDoc( + domain='adapter', + label={'zh_Hans': '适配器详情', 'en_US': 'Get Adapter'}, + summary='Get configuration schema and requirements for an adapter.', + description='Retrieve configuration parameters and supported features for an adapter. Prerequisites: Call adapter.list to discover valid adapter_name values.', + risk='read', + exposure='all', + ), + 'adapter.list': OperationDoc( + domain='adapter', + label={'zh_Hans': '适配器列表', 'en_US': 'List Adapters'}, + summary='List available chat platform adapters in the workspace.', + description='List all supported IM platform adapters (e.g. Slack, Discord, OneBot, WeChat) and their availability status in the workspace.', + risk='read', + exposure='all', + ), + 'agent.create': OperationDoc( + domain='agent', + label={'zh_Hans': '创建智能体', 'en_US': 'Create Agent'}, + summary='Create a new autonomous AI agent in the workspace.', + description='Create and initialize a new AI agent with model, prompts, and tool configurations. Provide agent_data payload. Side effect: Creates a new agent entity.', + risk='write', + exposure='all', + ), + 'agent.debug': OperationDoc( + domain='agent', + label={'zh_Hans': '调试智能体', 'en_US': 'Debug Agent'}, + summary='Execute a test turn on an agent for debugging purposes.', + description='Send a test input payload to an agent to evaluate prompt execution and tool selection without connecting to chat channels. Prerequisites: Call agent.list to obtain agent_uuid. Side effect: Generates execution trace.', + risk='write', + exposure='all', + ), + 'agent.debug.stream': OperationDoc( + domain='agent', + label={'zh_Hans': '流式调试智能体', 'en_US': 'Stream Debug Agent'}, + summary='Stream execution tokens and events during agent debugging.', + description='Stream tokens and intermediate thoughts for an agent debug session. Prerequisites: Call agent.list to obtain agent_uuid. Streaming operation: Not callable by agents.', + risk='write', + exposure='none', + ), + 'agent.delete': OperationDoc( + domain='agent', + label={'zh_Hans': '删除智能体', 'en_US': 'Delete Agent'}, + summary='Delete an autonomous AI agent from the workspace.', + description='Permanently remove an AI agent and its configuration from the workspace. Prerequisites: Call agent.list to obtain agent_uuid. Side effect: Irreversible deletion of agent.', + risk='dangerous', + exposure='all', + ), + 'agent.get': OperationDoc( + domain='agent', + label={'zh_Hans': '智能体详情', 'en_US': 'Get Agent'}, + summary='Get full configuration and parameters for an AI agent.', + description='Retrieve full agent definition including system prompt, model configuration, and attached skills/tools. Prerequisites: Call agent.list to obtain agent_uuid.', + risk='read', + exposure='all', + ), + 'agent.list': OperationDoc( + domain='agent', + label={'zh_Hans': '智能体列表', 'en_US': 'List Agents'}, + summary='List all autonomous AI agents configured in the workspace.', + description='Retrieve configured AI agents in the workspace with model selection, prompt settings, and bound tools. Supports sort_by and sort_order.', + risk='read', + exposure='all', + ), + 'agent.metadata': OperationDoc( + domain='agent', + label={'zh_Hans': '智能体元数据', 'en_US': 'Agent Metadata'}, + summary='Get supported agent capabilities, model types, and schemas.', + description='Retrieve metadata schemas describing supported agent parameters, available memory modes, and execution strategies.', + risk='read', + exposure='all', + ), + 'agent.runs.events': OperationDoc( + domain='agent', + label={'zh_Hans': '运行事件流', 'en_US': 'Get Run Events'}, + summary='Fetch step-by-step trace events for an agent execution run.', + description='Retrieve incremental trace events, thoughts, and tool calls for a run. Prerequisites: Call agent.runs.list to obtain run_id and processor_id. Use after_sequence to stream.', + risk='read', + exposure='all', + ), + 'agent.runs.list': OperationDoc( + domain='agent', + label={'zh_Hans': '智能体运行列表', 'en_US': 'List Agent Runs'}, + summary='List historical execution runs for an agent or processor.', + description='Retrieve execution run records for a processor (agent or pipeline). Prerequisites: Call agent.list to find processor_id. Supports pagination with before_id.', + risk='read', + exposure='all', + ), + 'agent.update': OperationDoc( + domain='agent', + label={'zh_Hans': '更新智能体', 'en_US': 'Update Agent'}, + summary='Update configuration, model, or prompts of an agent.', + description='Update an agent definition, prompt templates, tool permissions, or model settings. Prerequisites: Call agent.list to obtain agent_uuid. Side effect: Modifies agent settings.', + risk='write', + exposure='all', + ), + 'bot.admins.add': OperationDoc( + domain='bot', + label={'zh_Hans': '添加机器人管理员', 'en_US': 'Add Bot Admin'}, + summary='Add an administrator user to a bot configuration.', + description='Grant administrative privileges for a bot to a platform user. Prerequisites: Call bot.list to obtain bot_uuid. Restricted to assistant. Side effect: Grants bot administration rights.', + risk='write', + exposure='assistant', + ), + 'bot.admins.delete': OperationDoc( + domain='bot', + label={'zh_Hans': '删除机器人管理员', 'en_US': 'Delete Bot Admin'}, + summary='Remove an administrator user from a bot.', + description='Revoke administrative privileges for a bot from a platform user. Prerequisites: Call bot.admins.list to obtain admin_id. Restricted to assistant. Side effect: Revokes bot administration rights.', + risk='dangerous', + exposure='assistant', + ), + 'bot.admins.list': OperationDoc( + domain='bot', + label={'zh_Hans': '机器人管理员列表', 'en_US': 'List Bot Admins'}, + summary='List platform users configured as administrators for a bot.', + description='Retrieve the list of designated administrators for a bot. Prerequisites: Call bot.list to obtain bot_uuid.', + risk='read', + exposure='all', + ), + 'bot.create': OperationDoc( + domain='bot', + label={'zh_Hans': '创建机器人', 'en_US': 'Create Bot'}, + summary='Create a new chat bot connected to an IM adapter.', + description='Create and configure a new chat bot in the workspace. Provide bot_data containing name, adapter settings, and optional pipeline binding. Side effect: Instantiates a new bot entity.', + risk='write', + exposure='all', + ), + 'bot.delete': OperationDoc( + domain='bot', + label={'zh_Hans': '删除机器人', 'en_US': 'Delete Bot'}, + summary='Delete a chat bot and remove its adapter connection.', + description='Permanently remove a chat bot from the workspace. Prerequisites: Call bot.list to obtain bot_uuid. Side effect: Irreversible removal of bot and its adapter credentials.', + risk='dangerous', + exposure='all', + ), + 'bot.get': OperationDoc( + domain='bot', + label={'zh_Hans': '机器人详情', 'en_US': 'Get Bot'}, + summary='Get detailed configuration and status for a specific bot.', + description='Retrieve full configuration, adapter parameters, and pipeline bindings for a bot. Prerequisites: Call bot.list to find bot_uuid. Optionally pass include_secret.', + risk='read', + exposure='all', + ), + 'bot.group_filter.apply': OperationDoc( + domain='bot', + label={'zh_Hans': '应用群组过滤', 'en_US': 'Apply Group Filter'}, + summary='Apply group filtering rules to enable or disable pipelines.', + description='Update group filtering rules for a bot to allow or restrict message handling. Prerequisites: Call bot.list to obtain bot_uuid. Side effect: Modifies group filter policy.', + risk='write', + exposure='all', + ), + 'bot.group_filter.preview': OperationDoc( + domain='bot', + label={'zh_Hans': '群组过滤预览', 'en_US': 'Preview Group Filter'}, + summary='Preview chat group filtering rules for a bot.', + description='Inspect effective group chat filter rules and determine which groups are allowed or blocked. Prerequisites: Call bot.list to obtain bot_uuid.', + risk='read', + exposure='all', + ), + 'bot.list': OperationDoc( + domain='bot', + label={'zh_Hans': '机器人列表', 'en_US': 'List Bots'}, + summary='List all configured chat bots in the workspace.', + description='Retrieve all configured chat bots in the workspace with basic settings, adapter types, and pipeline bindings. Set include_secret=True to include credentials.', + risk='read', + exposure='all', + ), + 'bot.logs': OperationDoc( + domain='bot', + label={'zh_Hans': '机器人运行日志', 'en_US': 'Bot Logs'}, + summary='Fetch runtime connection logs and events for a bot.', + description='Retrieve connection logs, heartbeat messages, and adapter events for a bot. Prerequisites: Call bot.list to obtain bot_uuid. Paginate with from_index and max_count.', + risk='read', + exposure='all', + ), + 'bot.message.send': OperationDoc( + domain='bot', + label={'zh_Hans': '发送机器人消息', 'en_US': 'Send Bot Message'}, + summary='Send an outbound message to a chat user or group via a bot.', + description='Send an outbound message to a target user or chat group via the specified bot. Prerequisites: Call bot.list to obtain bot_uuid. Side effect: Delivers external message.', + risk='dangerous', + exposure='all', + ), + 'bot.message.test': OperationDoc( + domain='bot', + label={'zh_Hans': '测试发送消息', 'en_US': 'Test Bot Message'}, + summary='Test bot messaging capability by sending a test message.', + description='Send a diagnostic test message through the bot to verify adapter credentials and connectivity. Prerequisites: Call bot.list to obtain bot_uuid. Side effect: Sends test message.', + risk='write', + exposure='all', + ), + 'bot.routes.preview': OperationDoc( + domain='bot', + label={'zh_Hans': '路由预览', 'en_US': 'Preview Routes'}, + summary='Preview message routing decisions for a simulated event.', + description='Simulate how incoming events and messages would be routed by a bot without executing handlers. Prerequisites: Call bot.list to obtain bot_uuid.', + risk='read', + exposure='all', + ), + 'bot.routes.status': OperationDoc( + domain='bot', + label={'zh_Hans': '路由状态', 'en_US': 'Routing Status'}, + summary='Get active message routing bindings and rules for a bot.', + description='Inspect message routing table, target pipelines, and active event handlers configured on a bot. Prerequisites: Call bot.list to obtain bot_uuid.', + risk='read', + exposure='all', + ), + 'bot.runtime.get': OperationDoc( + domain='bot', + label={'zh_Hans': '机器人运行时状态', 'en_US': 'Bot Runtime Status'}, + summary='Inspect live connection state and health of a bot.', + description='Inspect live runtime health, connection status, latency, and adapter heartbeat for a bot. Prerequisites: Call bot.list to obtain bot_uuid.', + risk='read', + exposure='all', + ), + 'bot.update': OperationDoc( + domain='bot', + label={'zh_Hans': '更新机器人', 'en_US': 'Update Bot'}, + summary='Update settings or pipeline bindings for an existing bot.', + description='Modify configuration, adapter parameters, or pipeline bindings for a bot. Prerequisites: Call bot.list to obtain bot_uuid. Side effect: Updates bot configuration.', + risk='write', + exposure='all', + ), + 'extension.list': OperationDoc( + domain='extension', + label={'zh_Hans': '扩展全览列表', 'en_US': 'List All Extensions'}, + summary='List all available plugins, MCP servers, and skills combined.', + description='Retrieve a unified list of all active extensions across plugins, MCP servers, and custom skills in the workspace.', + risk='read', + exposure='all', + ), + 'knowledge.base.create': OperationDoc( + domain='knowledge', + label={'zh_Hans': '创建知识库', 'en_US': 'Create Knowledge Base'}, + summary='Create a new knowledge base with storage and vector engine.', + description='Create and configure a new knowledge base. Specify vector engine, embedding model, and chunking strategy. Side effect: Allocates knowledge base storage.', + risk='write', + exposure='all', + ), + 'knowledge.base.delete': OperationDoc( + domain='knowledge', + label={'zh_Hans': '删除知识库', 'en_US': 'Delete Knowledge Base'}, + summary='Permanently delete a knowledge base and indexed documents.', + description='Delete a knowledge base and all associated vector embeddings and documents. Prerequisites: Call knowledge.base.list to obtain kb_uuid. Side effect: Irreversible removal of data.', + risk='dangerous', + exposure='all', + ), + 'knowledge.base.get': OperationDoc( + domain='knowledge', + label={'zh_Hans': '知识库详情', 'en_US': 'Get Knowledge Base'}, + summary='Get configuration and indexing status of a knowledge base.', + description='Retrieve detailed configuration of a knowledge base including storage engine, chunking parameters, and embedding model. Prerequisites: Call knowledge.base.list to obtain kb_uuid.', + risk='read', + exposure='all', + ), + 'knowledge.base.list': OperationDoc( + domain='knowledge', + label={'zh_Hans': '知识库列表', 'en_US': 'List Knowledge Bases'}, + summary='List all knowledge bases configured in the workspace.', + description='Retrieve all knowledge bases in the workspace with vector engine types, parser configurations, and document counts.', + risk='read', + exposure='all', + ), + 'knowledge.base.retrieve': OperationDoc( + domain='knowledge', + label={'zh_Hans': '检索知识库', 'en_US': 'Retrieve Knowledge Chunks'}, + summary='Search and retrieve relevant text chunks from knowledge base.', + description='Perform semantic vector and keyword search over a knowledge base to retrieve relevant text chunks and citation metadata. Prerequisites: Call knowledge.base.list to obtain kb_uuid.', + risk='read', + exposure='all', + ), + 'knowledge.base.update': OperationDoc( + domain='knowledge', + label={'zh_Hans': '更新知识库', 'en_US': 'Update Knowledge Base'}, + summary='Update configuration or description of a knowledge base.', + description='Modify metadata, description, or search parameters of a knowledge base. Prerequisites: Call knowledge.base.list to obtain kb_uuid. Side effect: Updates knowledge base settings.', + risk='write', + exposure='all', + ), + 'knowledge.engine.creation_schema': OperationDoc( + domain='knowledge', + label={'zh_Hans': '引擎创建配置结构', 'en_US': 'Engine Creation Schema'}, + summary='Get configuration schema required to create an engine.', + description='Retrieve input schema requirements for initializing a specific storage engine backend.', + risk='read', + exposure='all', + ), + 'knowledge.engine.list': OperationDoc( + domain='knowledge', + label={'zh_Hans': '知识引擎列表', 'en_US': 'List Knowledge Engines'}, + summary='List available storage and vector retrieval engine types.', + description='Retrieve supported vector database and search engine backends available in the deployment (e.g. pgvector, milvus, seekdb).', + risk='read', + exposure='all', + ), + 'knowledge.engine.retrieval_schema': OperationDoc( + domain='knowledge', + label={'zh_Hans': '引擎检索配置结构', 'en_US': 'Engine Retrieval Schema'}, + summary='Get parameter schema for retrieving from an engine.', + description='Retrieve query and retrieval parameter schema supported by a specific storage engine.', + risk='read', + exposure='all', + ), + 'knowledge.file.delete': OperationDoc( + domain='knowledge', + label={'zh_Hans': '删除知识库文件', 'en_US': 'Delete Knowledge File'}, + summary='Delete an indexed document from a knowledge base.', + description='Remove a document and its vector embeddings from a knowledge base. Prerequisites: Call knowledge.file.list to obtain filename and kb_uuid. Side effect: Irreversible document removal.', + risk='dangerous', + exposure='all', + ), + 'knowledge.file.list': OperationDoc( + domain='knowledge', + label={'zh_Hans': '知识库文件列表', 'en_US': 'List Knowledge Files'}, + summary='List all documents indexed within a knowledge base.', + description='List files and documents stored in a knowledge base with ingestion status, chunk counts, and error details. Prerequisites: Call knowledge.base.list to obtain kb_uuid.', + risk='read', + exposure='all', + ), + 'knowledge.file.store': OperationDoc( + domain='knowledge', + label={'zh_Hans': '导入知识库文件', 'en_US': 'Store Knowledge File'}, + summary='Index and store a document into a knowledge base.', + description='Ingest and index a document into the specified knowledge base. Triggers parsing, chunking, and embedding generation. Prerequisites: Call knowledge.base.list to obtain kb_uuid. Side effect: Stores document data.', + risk='write', + exposure='all', + ), + 'knowledge.parser.list': OperationDoc( + domain='knowledge', + label={'zh_Hans': '文档解析器列表', 'en_US': 'List Document Parsers'}, + summary='List supported document parser formats and capabilities.', + description='Retrieve supported file formats (PDF, Markdown, DOCX, HTML) and document parser implementations available for ingestion.', + risk='read', + exposure='all', + ), + 'mcp.resource.list': OperationDoc( + domain='mcp', + label={'zh_Hans': 'MCP资源列表', 'en_US': 'List MCP Resources'}, + summary='List all resources exposed by connected MCP servers.', + description='Retrieve resources (files, schemas, system prompts) provided by registered MCP servers. Optionally filter by server_name.', + risk='read', + exposure='all', + ), + 'mcp.resource.read': OperationDoc( + domain='mcp', + label={'zh_Hans': '读取MCP资源', 'en_US': 'Read MCP Resource'}, + summary='Read contents of a specific resource from an MCP server.', + description='Fetch textual or binary content of an MCP resource by URI. Prerequisites: Call mcp.resource.list to obtain valid uri and server_name.', + risk='read', + exposure='all', + ), + 'mcp.resource.templates': OperationDoc( + domain='mcp', + label={'zh_Hans': 'MCP资源模板列表', 'en_US': 'List MCP Resource Templates'}, + summary='List parameterized resource URI templates from MCP servers.', + description='Retrieve parameterized resource URI templates exposed by MCP servers to construct dynamic resource queries.', + risk='read', + exposure='all', + ), + 'mcp.server.create': OperationDoc( + domain='mcp', + label={'zh_Hans': '创建MCP服务', 'en_US': 'Create MCP Server'}, + summary='Configure and register a new MCP server connection.', + description='Register a new MCP server in the workspace. Provide server_data with transport type, command/URL, and environment. Side effect: Instantiates MCP server client.', + risk='write', + exposure='all', + ), + 'mcp.server.delete': OperationDoc( + domain='mcp', + label={'zh_Hans': '删除MCP服务', 'en_US': 'Delete MCP Server'}, + summary='Disconnect and delete an MCP server from the workspace.', + description='Remove an MCP server registration and terminate active subprocess or connection. Prerequisites: Call mcp.server.list to obtain server_name. Side effect: Deletes server registration.', + risk='dangerous', + exposure='all', + ), + 'mcp.server.get': OperationDoc( + domain='mcp', + label={'zh_Hans': 'MCP服务详情', 'en_US': 'Get MCP Server'}, + summary='Get configuration and parameters of a specific MCP server.', + description='Retrieve full configuration of an MCP server including transport command or SSE endpoint. Prerequisites: Call mcp.server.list to obtain server_name.', + risk='read', + exposure='all', + ), + 'mcp.server.list': OperationDoc( + domain='mcp', + label={'zh_Hans': 'MCP服务列表', 'en_US': 'List MCP Servers'}, + summary='List configured Model Context Protocol (MCP) servers.', + description='Retrieve all configured MCP servers in the workspace with connection types (stdio, sse), status, and capabilities.', + risk='read', + exposure='all', + ), + 'mcp.server.logs': OperationDoc( + domain='mcp', + label={'zh_Hans': 'MCP服务日志', 'en_US': 'MCP Server Logs'}, + summary='Retrieve communication and error logs for an MCP server.', + description='Fetch protocol exchange messages and error output for an active MCP server. Prerequisites: Call mcp.server.list to obtain server_name.', + risk='read', + exposure='all', + ), + 'mcp.server.runtime': OperationDoc( + domain='mcp', + label={'zh_Hans': 'MCP服务运行时状态', 'en_US': 'MCP Server Runtime'}, + summary='Inspect live health and session state of an MCP server.', + description='Inspect live process or connection health, heartbeat status, and error counters for an MCP server. Prerequisites: Call mcp.server.list to obtain server_name.', + risk='read', + exposure='all', + ), + 'mcp.server.test': OperationDoc( + domain='mcp', + label={'zh_Hans': '测试MCP服务连接', 'en_US': 'Test MCP Server Connection'}, + summary='Test connectivity and ping an MCP server configuration.', + description='Verify connection and protocol handshake with an MCP server without saving. Side effect: Initiates external network or process connection.', + risk='write', + exposure='all', + ), + 'mcp.server.update': OperationDoc( + domain='mcp', + label={'zh_Hans': '更新MCP服务', 'en_US': 'Update MCP Server'}, + summary='Update configuration and parameters of an MCP server.', + description='Modify connection parameters, environment variables, or transport settings of an MCP server. Prerequisites: Call mcp.server.list to obtain server_name. Side effect: Restarts MCP client.', + risk='write', + exposure='all', + ), + 'model.embedding.create': OperationDoc( + domain='model', + label={'zh_Hans': '创建嵌入模型', 'en_US': 'Create Embedding Model'}, + summary='Configure and add a new embedding model to the workspace.', + description='Add a new embedding model configuration with dimension and endpoint settings. Side effect: Creates model entity.', + risk='write', + exposure='all', + ), + 'model.embedding.delete': OperationDoc( + domain='model', + label={'zh_Hans': '删除嵌入模型', 'en_US': 'Delete Embedding Model'}, + summary='Delete an embedding model configuration from the workspace.', + description='Permanently remove an embedding model configuration. Prerequisites: Call model.embedding.list to obtain model_uuid. Side effect: Irreversible removal of model config.', + risk='dangerous', + exposure='all', + ), + 'model.embedding.get': OperationDoc( + domain='model', + label={'zh_Hans': '嵌入模型详情', 'en_US': 'Get Embedding Model'}, + summary='Get configuration and parameters of an embedding model.', + description='Retrieve complete configuration for an embedding model. Prerequisites: Call model.embedding.list to obtain model_uuid. Optionally pass include_secret.', + risk='read', + exposure='all', + ), + 'model.embedding.list': OperationDoc( + domain='model', + label={'zh_Hans': '嵌入模型列表', 'en_US': 'List Embedding Models'}, + summary='List all text embedding models configured in the workspace.', + description='Retrieve configured text embedding models with dimension and provider details. Pass include_secret=True to include credentials.', + risk='read', + exposure='all', + ), + 'model.embedding.list_by_provider': OperationDoc( + domain='model', + label={'zh_Hans': '按供应商列出嵌入模型', 'en_US': 'List Embeddings by Provider'}, + summary='List embedding models configured under a specific provider.', + description='Retrieve embedding models belonging to a specific provider. Prerequisites: Call provider.list to obtain provider_uuid.', + risk='read', + exposure='all', + ), + 'model.embedding.test': OperationDoc( + domain='model', + label={'zh_Hans': '测试嵌入模型', 'en_US': 'Test Embedding Model'}, + summary='Test vector generation and connectivity for embedding model.', + description='Send sample text to an embedding model to verify credentials and vector output. Prerequisites: Call model.embedding.list to obtain model_uuid. Side effect: Incurs model API call.', + risk='write', + exposure='all', + ), + 'model.embedding.update': OperationDoc( + domain='model', + label={'zh_Hans': '更新嵌入模型', 'en_US': 'Update Embedding Model'}, + summary='Update configuration and parameters of an embedding model.', + description='Modify settings or credentials of an embedding model. Prerequisites: Call model.embedding.list to obtain model_uuid. Side effect: Updates model config.', + risk='write', + exposure='all', + ), + 'model.llm.create': OperationDoc( + domain='model', + label={'zh_Hans': '创建大语言模型', 'en_US': 'Create LLM Model'}, + summary='Configure and add a new LLM model to the workspace.', + description='Add a new LLM model configuration to the workspace with context window and temperature settings. Side effect: Creates model entity.', + risk='write', + exposure='all', + ), + 'model.llm.default.get': OperationDoc( + domain='model', + label={'zh_Hans': '获取默认LLM模型', 'en_US': 'Get Default LLM Model'}, + summary='Get workspace default large language model configuration.', + description='Retrieve the default LLM model configured for new pipelines and agents in the workspace.', + risk='read', + exposure='all', + ), + 'model.llm.delete': OperationDoc( + domain='model', + label={'zh_Hans': '删除大语言模型', 'en_US': 'Delete LLM Model'}, + summary='Delete an LLM model configuration from the workspace.', + description='Permanently remove an LLM model from the workspace. Prerequisites: Call model.llm.list to obtain model_uuid. Side effect: Irreversible removal of model config.', + risk='dangerous', + exposure='all', + ), + 'model.llm.get': OperationDoc( + domain='model', + label={'zh_Hans': '大语言模型详情', 'en_US': 'Get LLM Model'}, + summary='Get configuration and parameters of a specific LLM model.', + description='Retrieve complete configuration for an LLM model. Prerequisites: Call model.llm.list to obtain model_uuid. Optionally pass include_secret.', + risk='read', + exposure='all', + ), + 'model.llm.list': OperationDoc( + domain='model', + label={'zh_Hans': '大语言模型列表', 'en_US': 'List LLM Models'}, + summary='List all configured large language models in the workspace.', + description='Retrieve all configured LLM models in the workspace, including context limits and capabilities. Pass include_secret=True to include credentials.', + risk='read', + exposure='all', + ), + 'model.llm.list_by_provider': OperationDoc( + domain='model', + label={'zh_Hans': '按供应商列出LLM模型', 'en_US': 'List LLMs by Provider'}, + summary='List LLM models configured under a specific model provider.', + description='Retrieve LLM models belonging to a specific provider. Prerequisites: Call provider.list to obtain provider_uuid.', + risk='read', + exposure='all', + ), + 'model.llm.starred.get': OperationDoc( + domain='model', + label={'zh_Hans': '获取标星LLM模型', 'en_US': 'Get Starred LLM Model'}, + summary='Get the starred favorite LLM model of the workspace.', + description='Retrieve the favorite/starred LLM model designated for quick selection in the workspace.', + risk='read', + exposure='all', + ), + 'model.llm.starred.set': OperationDoc( + domain='model', + label={'zh_Hans': '设置标星LLM模型', 'en_US': 'Set Starred LLM Model'}, + summary='Designate a specific LLM model as the starred favorite.', + description='Mark an LLM model as the workspace starred favorite model. Prerequisites: Call model.llm.list to obtain model_uuid. Side effect: Modifies workspace favorite model setting.', + risk='write', + exposure='all', + ), + 'model.llm.test': OperationDoc( + domain='model', + label={'zh_Hans': '测试大语言模型', 'en_US': 'Test LLM Model'}, + summary='Test connectivity and response generation for an LLM model.', + description='Send a test prompt to an LLM model to verify credentials and API availability. Prerequisites: Call model.llm.list to obtain model_uuid. Side effect: Incurs model API call.', + risk='write', + exposure='all', + ), + 'model.llm.update': OperationDoc( + domain='model', + label={'zh_Hans': '更新大语言模型', 'en_US': 'Update LLM Model'}, + summary='Update configuration and parameters of an LLM model.', + description='Modify settings, context parameters, or credentials of an LLM model. Prerequisites: Call model.llm.list to obtain model_uuid. Side effect: Updates model config.', + risk='write', + exposure='all', + ), + 'model.rerank.create': OperationDoc( + domain='model', + label={'zh_Hans': '创建重排模型', 'en_US': 'Create Rerank Model'}, + summary='Configure and add a new rerank model to the workspace.', + description='Add a new rerank model configuration to the workspace. Side effect: Creates model entity.', + risk='write', + exposure='all', + ), + 'model.rerank.delete': OperationDoc( + domain='model', + label={'zh_Hans': '删除重排模型', 'en_US': 'Delete Rerank Model'}, + summary='Delete a rerank model configuration from the workspace.', + description='Permanently remove a rerank model configuration. Prerequisites: Call model.rerank.list to obtain model_uuid. Side effect: Irreversible removal of model config.', + risk='dangerous', + exposure='all', + ), + 'model.rerank.get': OperationDoc( + domain='model', + label={'zh_Hans': '重排模型详情', 'en_US': 'Get Rerank Model'}, + summary='Get configuration and parameters of a rerank model.', + description='Retrieve complete configuration for a rerank model. Prerequisites: Call model.rerank.list to obtain model_uuid. Optionally pass include_secret.', + risk='read', + exposure='all', + ), + 'model.rerank.list': OperationDoc( + domain='model', + label={'zh_Hans': '重排模型列表', 'en_US': 'List Rerank Models'}, + summary='List all document reranking models in the workspace.', + description='Retrieve configured reranking models used in knowledge base retrieval. Pass include_secret=True to include credentials.', + risk='read', + exposure='all', + ), + 'model.rerank.list_by_provider': OperationDoc( + domain='model', + label={'zh_Hans': '按供应商列出重排模型', 'en_US': 'List Reranks by Provider'}, + summary='List rerank models configured under a specific provider.', + description='Retrieve rerank models belonging to a specific provider. Prerequisites: Call provider.list to obtain provider_uuid.', + risk='read', + exposure='all', + ), + 'model.rerank.test': OperationDoc( + domain='model', + label={'zh_Hans': '测试重排模型', 'en_US': 'Test Rerank Model'}, + summary='Test connectivity and scoring capability of a rerank model.', + description='Send sample documents to a rerank model to verify credentials and scoring. Prerequisites: Call model.rerank.list to obtain model_uuid. Side effect: Incurs model API call.', + risk='write', + exposure='all', + ), + 'model.rerank.update': OperationDoc( + domain='model', + label={'zh_Hans': '更新重排模型', 'en_US': 'Update Rerank Model'}, + summary='Update configuration and parameters of a rerank model.', + description='Modify settings or credentials of a rerank model. Prerequisites: Call model.rerank.list to obtain model_uuid. Side effect: Updates model config.', + risk='write', + exposure='all', + ), + 'monitoring.embedding_calls': OperationDoc( + domain='monitoring', + label={'zh_Hans': '嵌入模型调用统计', 'en_US': 'Embedding Call Metrics'}, + summary='Query embedding generation metrics and latency statistics.', + description='Retrieve embedding model call statistics and token counts, optionally filtered by knowledge_base_id and time range.', + risk='read', + exposure='all', + ), + 'monitoring.errors': OperationDoc( + domain='monitoring', + label={'zh_Hans': '错误日志', 'en_US': 'Error Logs'}, + summary='Query runtime errors and failures across bots and pipelines.', + description='Retrieve error logs and failed execution events. Filter by bot_ids, pipeline_ids, execution_statuses, and time range with limit and offset pagination.', + risk='read', + exposure='all', + ), + 'monitoring.execution.detail': OperationDoc( + domain='monitoring', + label={'zh_Hans': '执行详情', 'en_US': 'Execution Details'}, + summary='Get detailed traces and step execution events for a specific execution.', + description='Retrieve fine-grained execution trace events and step diagnostics. Prerequisites: Call monitoring.executions first to find the execution_id and source. Filter by section or page with offset and limit.', + risk='read', + exposure='all', + ), + 'monitoring.executions': OperationDoc( + domain='monitoring', + label={'zh_Hans': '执行记录列表', 'en_US': 'List Executions'}, + summary='Query execution history records across bots, pipelines, and agents.', + description='Query and list pipeline and agent execution runs with status and duration. Filter by bot_ids, pipeline_ids, agent_ids, execution statuses, and time range. Supports pagination with limit and offset.', + risk='read', + exposure='all', + ), + 'monitoring.feedback.list': OperationDoc( + domain='monitoring', + label={'zh_Hans': '用户反馈列表', 'en_US': 'List User Feedback'}, + summary='List user ratings and feedback records on bot responses.', + description='Query user feedback and satisfaction ratings on bot responses. Filter by bot_ids, pipeline_ids, feedback_type (upvote/downvote), and time range.', + risk='read', + exposure='all', + ), + 'monitoring.feedback.stats': OperationDoc( + domain='monitoring', + label={'zh_Hans': '用户反馈统计', 'en_US': 'Feedback Statistics'}, + summary='Get aggregated positive and negative user feedback metrics.', + description='Retrieve aggregated user feedback metrics, such as like/dislike ratios, over a specified time window for given bot_ids or pipeline_ids.', + risk='read', + exposure='all', + ), + 'monitoring.inflight': OperationDoc( + domain='monitoring', + label={'zh_Hans': '进行中任务监控', 'en_US': 'In-Flight Executions'}, + summary='Inspect currently active in-flight requests and pipeline runs.', + description='Retrieve real-time snapshot of active in-flight requests and currently executing pipeline steps across the workspace.', + risk='read', + exposure='all', + ), + 'monitoring.llm_calls': OperationDoc( + domain='monitoring', + label={'zh_Hans': '大模型调用统计', 'en_US': 'LLM Call Metrics'}, + summary='Query model invocation counts, latencies, and token stats.', + description='Query statistics on LLM invocations including latency distributions, token usage, and status codes. Filter by bot_ids, pipeline_ids, and time range.', + risk='read', + exposure='all', + ), + 'monitoring.message.detail': OperationDoc( + domain='monitoring', + label={'zh_Hans': '消息详情', 'en_US': 'Message Details'}, + summary='Retrieve full metadata and trace details for a single message.', + description='Fetch complete message content, routing trace, and execution context for a message. Prerequisites: Call monitoring.messages first to obtain the message_id.', + risk='read', + exposure='all', + ), + 'monitoring.messages': OperationDoc( + domain='monitoring', + label={'zh_Hans': '消息历史查询', 'en_US': 'Query Messages'}, + summary='Query processed chat messages across bot sessions.', + description='Retrieve processed inbound and outbound messages. Supports filtering by bot_ids, pipeline_ids, session_ids, and time range. Paginate with limit and offset.', + risk='read', + exposure='all', + ), + 'monitoring.overview': OperationDoc( + domain='monitoring', + label={'zh_Hans': '监控总览', 'en_US': 'Monitoring Overview'}, + summary='Get aggregated monitoring overview statistics for bots and pipelines.', + description='Retrieve high-level overview metrics including total message counts, active sessions, and errors across bots and pipelines. Supports optional filtering by bot_ids, pipeline_ids, time range (start_time, end_time), and execution status.', + risk='read', + exposure='all', + ), + 'monitoring.session.analysis': OperationDoc( + domain='monitoring', + label={'zh_Hans': '会话分析', 'en_US': 'Session Analysis'}, + summary='Analyze session metrics, duration, and token usage for a session.', + description='Retrieve detailed analytics for a chat session including message frequency, turn count, and token usage. Prerequisites: Call monitoring.sessions first to obtain session_id.', + risk='read', + exposure='all', + ), + 'monitoring.session.reset': OperationDoc( + domain='monitoring', + label={'zh_Hans': '重置会话', 'en_US': 'Reset Session'}, + summary='Reset a chat session and clear its context window.', + description='Clear context history and reset memory state for a given session. Prerequisites: Call monitoring.sessions to obtain session_id and bot_id. Side effect: Deletes stored session conversation state.', + risk='dangerous', + exposure='all', + ), + 'monitoring.sessions': OperationDoc( + domain='monitoring', + label={'zh_Hans': '会话列表', 'en_US': 'List Sessions'}, + summary='List active and historical chat sessions across bots.', + description='Query chat sessions filtered by bot_ids, pipeline_ids, active status, user query keyword, and time range. Paginate results with limit and offset.', + risk='read', + exposure='all', + ), + 'monitoring.tokens': OperationDoc( + domain='monitoring', + label={'zh_Hans': '代币消耗统计', 'en_US': 'Token Usage Statistics'}, + summary='Query token consumption metrics aggregated by time buckets.', + description='Retrieve prompt and completion token consumption aggregated across bots, pipelines, and models. Configure time bucket granularity (bucket) and time window (start_time, end_time).', + risk='read', + exposure='all', + ), + 'monitoring.tool_calls': OperationDoc( + domain='monitoring', + label={'zh_Hans': '工具调用统计', 'en_US': 'Tool Call Metrics'}, + summary='Query tool invocation history and execution performance.', + description='Retrieve tool and plugin function call events including execution duration and status. Filter by bot_ids, pipeline_ids, session_ids, and time range.', + risk='read', + exposure='all', + ), + 'pipeline.chat.broadcast': OperationDoc( + domain='pipeline', + label={'zh_Hans': '广播聊天消息', 'en_US': 'Broadcast Chat Message'}, + summary='Broadcast a message to all active pipeline chat clients.', + description='Broadcast a message payload to all connected test clients in the pipeline debug channel. Prerequisites: Call pipeline.list to obtain pipeline_uuid. Side effect: Sends message to active clients.', + risk='dangerous', + exposure='all', + ), + 'pipeline.chat.connections': OperationDoc( + domain='pipeline', + label={'zh_Hans': '流水线连接状态', 'en_US': 'Pipeline Connections'}, + summary='Inspect live websocket connection status for pipeline chat.', + description='Inspect active real-time preview websocket clients connected to the pipeline test interface. Prerequisites: Call pipeline.list to obtain pipeline_uuid.', + risk='read', + exposure='all', + ), + 'pipeline.chat.history': OperationDoc( + domain='pipeline', + label={'zh_Hans': '流水线聊天历史', 'en_US': 'Pipeline Chat History'}, + summary='Retrieve debug chat message history for a pipeline session.', + description='Fetch recent test messages and interaction logs for a pipeline web preview session. Prerequisites: Call pipeline.list to obtain pipeline_uuid.', + risk='read', + exposure='all', + ), + 'pipeline.chat.reset': OperationDoc( + domain='pipeline', + label={'zh_Hans': '重置聊天会话', 'en_US': 'Reset Chat Session'}, + summary='Clear memory and chat history for a pipeline debug session.', + description='Reset test chat memory and clear session state for pipeline preview. Prerequisites: Call pipeline.list to obtain pipeline_uuid. Side effect: Deletes stored preview chat context.', + risk='dangerous', + exposure='all', + ), + 'pipeline.copy': OperationDoc( + domain='pipeline', + label={'zh_Hans': '复制流水线', 'en_US': 'Copy Pipeline'}, + summary='Duplicate an existing pipeline to create a new copy.', + description='Clone an existing pipeline definition under a new identifier. Prerequisites: Call pipeline.list to obtain source pipeline_uuid. Side effect: Creates duplicate pipeline.', + risk='write', + exposure='all', + ), + 'pipeline.create': OperationDoc( + domain='pipeline', + label={'zh_Hans': '创建流水线', 'en_US': 'Create Pipeline'}, + summary='Create a new processing pipeline in the workspace.', + description='Create and configure a new message processing pipeline. Provide pipeline_data containing nodes and flow definition. Side effect: Creates a new pipeline entity.', + risk='write', + exposure='all', + ), + 'pipeline.defaults': OperationDoc( + domain='pipeline', + label={'zh_Hans': '流水线默认配置', 'en_US': 'Pipeline Defaults'}, + summary='Get template defaults and initial values for new pipelines.', + description='Retrieve default pipeline templates and starter configuration presets for creating standard processing workflows.', + risk='read', + exposure='all', + ), + 'pipeline.delete': OperationDoc( + domain='pipeline', + label={'zh_Hans': '删除流水线', 'en_US': 'Delete Pipeline'}, + summary='Permanently delete a pipeline from the workspace.', + description='Delete a processing pipeline and disconnect it from associated bots. Prerequisites: Call pipeline.list to obtain pipeline_uuid. Side effect: Irreversible removal of pipeline.', + risk='dangerous', + exposure='all', + ), + 'pipeline.extensions.get': OperationDoc( + domain='pipeline', + label={'zh_Hans': '获取流水线扩展', 'en_US': 'Get Pipeline Extensions'}, + summary='Get bound plugins, MCP servers, and tools for a pipeline.', + description='Inspect extensions, plugins, and MCP connections bound to a specific pipeline. Prerequisites: Call pipeline.list to obtain pipeline_uuid.', + risk='read', + exposure='all', + ), + 'pipeline.extensions.update': OperationDoc( + domain='pipeline', + label={'zh_Hans': '更新流水线扩展', 'en_US': 'Update Pipeline Extensions'}, + summary='Update bound plugins, MCP servers, and tools on a pipeline.', + description='Bind or unbind plugins, MCP servers, and tools to a pipeline. Prerequisites: Call pipeline.list to obtain pipeline_uuid. Side effect: Modifies pipeline tool attachments.', + risk='write', + exposure='all', + ), + 'pipeline.get': OperationDoc( + domain='pipeline', + label={'zh_Hans': '流水线详情', 'en_US': 'Get Pipeline'}, + summary='Get complete definition and node graph of a pipeline.', + description='Retrieve full pipeline configuration including components, flow nodes, and bound models/tools. Prerequisites: Call pipeline.list to obtain pipeline_uuid.', + risk='read', + exposure='all', + ), + 'pipeline.list': OperationDoc( + domain='pipeline', + label={'zh_Hans': '流水线列表', 'en_US': 'List Pipelines'}, + summary='List all message processing pipelines in the workspace.', + description='Retrieve all configured pipelines in the workspace, including node configurations and active routing states. Supports sort_by, sort_order, and include_secret.', + risk='read', + exposure='all', + ), + 'pipeline.metadata': OperationDoc( + domain='pipeline', + label={'zh_Hans': '流水线元数据', 'en_US': 'Pipeline Metadata'}, + summary='Get available component types and node specifications.', + description='Retrieve supported pipeline component types, node port contracts, and configuration parameter schemas.', + risk='read', + exposure='all', + ), + 'pipeline.migration.execute': OperationDoc( + domain='pipeline', + label={'zh_Hans': '执行流水线迁移', 'en_US': 'Execute Pipeline Migration'}, + summary='Migrate legacy pipeline configurations to current schema.', + description='Upgrade and migrate legacy pipeline structures in the workspace. Restricted to logged-in account users. Side effect: Modifies database pipeline entities permanently.', + risk='dangerous', + exposure='assistant', + ), + 'pipeline.migration.preview': OperationDoc( + domain='pipeline', + label={'zh_Hans': '流水线迁移预览', 'en_US': 'Preview Pipeline Migration'}, + summary='Preview legacy pipeline migration changes without applying.', + description='Simulate migration of legacy pipeline configurations to updated format. Restricted to logged-in account users. Prerequisites: Call pipeline.list to find target pipelines.', + risk='read', + exposure='assistant', + ), + 'pipeline.run': OperationDoc( + domain='pipeline', + label={'zh_Hans': '执行流水线', 'en_US': 'Run Pipeline'}, + summary='Execute a pipeline run with custom input data.', + description='Trigger an on-demand execution of a pipeline with provided payload. Prerequisites: Call pipeline.list to obtain pipeline_uuid. Side effect: Executes pipeline logic and consumes compute.', + risk='write', + exposure='all', + ), + 'pipeline.update': OperationDoc( + domain='pipeline', + label={'zh_Hans': '更新流水线', 'en_US': 'Update Pipeline'}, + summary='Update topology, nodes, or settings of a pipeline.', + description='Modify pipeline nodes, model assignments, tool attachments, or name. Prerequisites: Call pipeline.list to obtain pipeline_uuid. Side effect: Updates pipeline definition.', + risk='write', + exposure='all', + ), + 'plugin.asset': OperationDoc( + domain='plugin', + label={'zh_Hans': '插件静态资源', 'en_US': 'Plugin Asset'}, + summary='Retrieve a static asset file from an installed plugin.', + description='Return binary asset data from a plugin package directory. Binary response: Not callable by agents.', + risk='read', + exposure='none', + ), + 'plugin.config.get': OperationDoc( + domain='plugin', + label={'zh_Hans': '获取插件配置', 'en_US': 'Get Plugin Config'}, + summary='Get configured parameters and settings for a plugin.', + description='Retrieve current configuration values and schema for an installed plugin. Prerequisites: Call plugin.list to obtain author and plugin_name.', + risk='read', + exposure='all', + ), + 'plugin.config.update': OperationDoc( + domain='plugin', + label={'zh_Hans': '更新插件配置', 'en_US': 'Update Plugin Config'}, + summary='Update configuration parameters and options for a plugin.', + description='Update runtime configuration settings for an installed plugin. Prerequisites: Call plugin.list to obtain author and plugin_name. Restricted to assistant. Side effect: Restarts plugin with new configuration.', + risk='write', + exposure='assistant', + ), + 'plugin.config_file.delete': OperationDoc( + domain='plugin', + label={'zh_Hans': '删除插件配置文件', 'en_US': 'Delete Plugin Config File'}, + summary='Delete a configuration file associated with a plugin.', + description='Delete a configuration file or asset from a plugin directory. Prerequisites: Call plugin.list to obtain author and plugin_name. Restricted to assistant. Side effect: Deletes configuration file.', + risk='dangerous', + exposure='assistant', + ), + 'plugin.config_file.upload': OperationDoc( + domain='plugin', + label={'zh_Hans': '上传插件配置文件', 'en_US': 'Upload Plugin Config File'}, + summary='Upload a configuration file for an installed plugin.', + description='Upload a configuration file or credential bundle to a plugin directory. Requires file upload. Not callable by agents.', + risk='write', + exposure='none', + ), + 'plugin.debug_info': OperationDoc( + domain='plugin', + label={'zh_Hans': '插件调试信息', 'en_US': 'Plugin Debug Info'}, + summary='Inspect internal plugin runtime process state and memory.', + description='Inspect plugin container/process status, memory consumption, and active communication channels across the workspace.', + risk='read', + exposure='all', + ), + 'plugin.delete': OperationDoc( + domain='plugin', + label={'zh_Hans': '卸载插件', 'en_US': 'Uninstall Plugin'}, + summary='Uninstall and remove a plugin from the workspace.', + description='Completely uninstall a plugin, stop its runner container, and delete its files. Prerequisites: Call plugin.list to obtain author and plugin_name. Restricted to assistant. Side effect: Removes plugin completely.', + risk='dangerous', + exposure='assistant', + ), + 'plugin.get': OperationDoc( + domain='plugin', + label={'zh_Hans': '插件详情', 'en_US': 'Get Plugin'}, + summary='Get detailed metadata and manifest for an installed plugin.', + description='Retrieve manifest, permissions, and configuration options for an installed plugin. Prerequisites: Call plugin.list to obtain author and plugin_name.', + risk='read', + exposure='all', + ), + 'plugin.github.assets': OperationDoc( + domain='plugin', + label={'zh_Hans': 'GitHub发布包资源', 'en_US': 'Plugin GitHub Assets'}, + summary='List downloadable asset files for a GitHub release.', + description='List downloadable distribution packages for a GitHub release tag of a plugin.', + risk='read', + exposure='all', + ), + 'plugin.github.releases': OperationDoc( + domain='plugin', + label={'zh_Hans': 'GitHub发布版本', 'en_US': 'Plugin GitHub Releases'}, + summary='List releases of a plugin repository hosted on GitHub.', + description='Fetch available release versions and tags for a plugin from its GitHub repository URL.', + risk='read', + exposure='all', + ), + 'plugin.icon': OperationDoc( + domain='plugin', + label={'zh_Hans': '插件图标', 'en_US': 'Plugin Icon'}, + summary='Retrieve the display icon image of an installed plugin.', + description='Return binary image data for a plugin icon. Binary response: Not callable by agents.', + risk='read', + exposure='none', + ), + 'plugin.install.github': OperationDoc( + domain='plugin', + label={'zh_Hans': '从GitHub安装插件', 'en_US': 'Install Plugin from GitHub'}, + summary='Install a plugin package directly from a GitHub release.', + description='Download and install a plugin release asset directly from a GitHub repository. Restricted to assistant. Side effect: Installs executable code and starts container.', + risk='write', + exposure='assistant', + ), + 'plugin.install.local': OperationDoc( + domain='plugin', + label={'zh_Hans': '本地安装插件', 'en_US': 'Install Local Plugin'}, + summary='Install a plugin from an uploaded local archive file.', + description='Install a plugin from raw file bytes. Requires file upload. Not callable by agents.', + risk='write', + exposure='none', + ), + 'plugin.install.local.preview': OperationDoc( + domain='plugin', + label={'zh_Hans': '预览本地插件包', 'en_US': 'Preview Local Plugin'}, + summary='Preview manifest and files of a local plugin archive.', + description='Inspect metadata of a local plugin archive before installation. Requires file upload. Not callable by agents.', + risk='read', + exposure='none', + ), + 'plugin.install.marketplace': OperationDoc( + domain='plugin', + label={'zh_Hans': '从市场安装插件', 'en_US': 'Install Plugin from Marketplace'}, + summary='Install a certified plugin from the official marketplace.', + description='Download and install a plugin package from the LangBot Plugin Marketplace. Restricted to assistant. Side effect: Installs executable code and starts container.', + risk='write', + exposure='assistant', + ), + 'plugin.list': OperationDoc( + domain='plugin', + label={'zh_Hans': '插件列表', 'en_US': 'List Plugins'}, + summary='List all installed plugins and their running status.', + description='Retrieve all installed workspace plugins with version numbers, author details, enablement state, and registered capabilities.', + risk='read', + exposure='all', + ), + 'plugin.logs': OperationDoc( + domain='plugin', + label={'zh_Hans': '插件运行日志', 'en_US': 'Plugin Logs'}, + summary='Fetch runtime logs and error messages from a plugin.', + description='Retrieve stdout/stderr logs and diagnostic traces produced by a running plugin. Prerequisites: Call plugin.list to obtain author and plugin_name.', + risk='read', + exposure='all', + ), + 'plugin.page_action': OperationDoc( + domain='plugin', + label={'zh_Hans': '插件页面交互', 'en_US': 'Plugin Page Action'}, + summary='Invoke an interactive endpoint on a plugin custom web page.', + description='Forward HTTP requests to plugin custom UI page handlers. Browser UI dependent: Not callable by agents.', + risk='write', + exposure='none', + ), + 'plugin.readme': OperationDoc( + domain='plugin', + label={'zh_Hans': '插件说明文档', 'en_US': 'Plugin Readme'}, + summary='Get documentation and usage instructions for a plugin.', + description='Fetch the README documentation of an installed plugin in the requested language. Prerequisites: Call plugin.list to obtain author and plugin_name.', + risk='read', + exposure='all', + ), + 'plugin.upgrade': OperationDoc( + domain='plugin', + label={'zh_Hans': '升级插件', 'en_US': 'Upgrade Plugin'}, + summary='Upgrade an installed plugin to its latest release.', + description='Upgrade an installed plugin to the latest version available from its source. Prerequisites: Call plugin.list to obtain author and plugin_name. Restricted to assistant. Side effect: Replaces plugin binary.', + risk='write', + exposure='assistant', + ), + 'provider.codex.cancel': OperationDoc( + domain='provider', + label={'zh_Hans': '取消Codex授权', 'en_US': 'Cancel Codex Authorization'}, + summary='Cancel an active Codex OAuth authorization session.', + description='Abort an active Codex OAuth login attempt. Requires browser OAuth interaction: Not callable by agents.', + risk='write', + exposure='none', + ), + 'provider.codex.disconnect': OperationDoc( + domain='provider', + label={'zh_Hans': '断开Codex连接', 'en_US': 'Disconnect Codex'}, + summary='Disconnect and revoke Codex OAuth integration token.', + description='Revoke and remove stored OAuth credentials for Codex. Requires browser OAuth interaction: Not callable by agents.', + risk='write', + exposure='none', + ), + 'provider.codex.poll': OperationDoc( + domain='provider', + label={'zh_Hans': '轮询Codex授权结果', 'en_US': 'Poll Codex Authorization'}, + summary='Poll status of in-progress Codex OAuth authorization.', + description='Check completion of OAuth flow for Codex. Requires browser OAuth interaction: Not callable by agents.', + risk='write', + exposure='none', + ), + 'provider.codex.start': OperationDoc( + domain='provider', + label={'zh_Hans': '启动Codex授权', 'en_US': 'Start Codex Authorization'}, + summary='Initiate OAuth authorization flow for Codex provider.', + description='Start OAuth handshake for OpenAI Codex provider. Requires browser OAuth interaction: Not callable by agents.', + risk='write', + exposure='none', + ), + 'provider.codex.status': OperationDoc( + domain='provider', + label={'zh_Hans': 'Codex连接状态', 'en_US': 'Codex Connection Status'}, + summary='Inspect Codex provider OAuth connection and token validity.', + description='Inspect token state for Codex integration. Requires browser OAuth interaction: Not callable by agents.', + risk='read', + exposure='none', + ), + 'provider.create': OperationDoc( + domain='provider', + label={'zh_Hans': '创建供应商', 'en_US': 'Create Provider'}, + summary='Add a new model provider and credentials to the workspace.', + description='Register a new model provider with API key and base URL. Side effect: Creates provider entity.', + risk='write', + exposure='all', + ), + 'provider.delete': OperationDoc( + domain='provider', + label={'zh_Hans': '删除供应商', 'en_US': 'Delete Provider'}, + summary='Delete a model provider and its associated models.', + description='Remove a model provider from the workspace. Prerequisites: Call provider.list to obtain provider_uuid. Set cascade=True to delete associated models. Side effect: Deletes provider.', + risk='dangerous', + exposure='all', + ), + 'provider.get': OperationDoc( + domain='provider', + label={'zh_Hans': '供应商详情', 'en_US': 'Get Provider'}, + summary='Get configuration and credentials of a model provider.', + description='Retrieve detailed configuration for a model provider. Prerequisites: Call provider.list to obtain provider_uuid. Optionally pass include_secret.', + risk='read', + exposure='all', + ), + 'provider.list': OperationDoc( + domain='provider', + label={'zh_Hans': '供应商列表', 'en_US': 'List Providers'}, + summary='List all configured model providers in the workspace.', + description='Retrieve configured model providers (e.g. OpenAI, Anthropic, Ollama) and base URLs. Pass include_secret=True to include credentials.', + risk='read', + exposure='all', + ), + 'provider.models.count': OperationDoc( + domain='provider', + label={'zh_Hans': '供应商模型数量', 'en_US': 'Provider Models Count'}, + summary='Count models configured under a specific model provider.', + description='Count total LLM, embedding, and rerank models associated with a provider. Prerequisites: Call provider.list to obtain provider_uuid.', + risk='read', + exposure='all', + ), + 'provider.models.scan': OperationDoc( + domain='provider', + label={'zh_Hans': '扫描供应商可用模型', 'en_US': 'Scan Provider Models'}, + summary='Scan remote provider endpoint for available models.', + description='Query remote provider API to discover available models for importing. Prerequisites: Call provider.list to obtain provider_uuid. Side effect: Queries remote provider API.', + risk='write', + exposure='all', + ), + 'provider.update': OperationDoc( + domain='provider', + label={'zh_Hans': '更新供应商', 'en_US': 'Update Provider'}, + summary='Update credentials or base URL of a model provider.', + description='Modify provider settings, API keys, or custom base URLs. Prerequisites: Call provider.list to obtain provider_uuid. Side effect: Updates provider settings.', + risk='write', + exposure='all', + ), + 'requester.get': OperationDoc( + domain='requester', + label={'zh_Hans': '请求器详情', 'en_US': 'Get Requester'}, + summary='Get configuration and capabilities of an HTTP requester.', + description='Retrieve configuration details and capabilities of a requester. Prerequisites: Call requester.list to discover valid requester_name values.', + risk='read', + exposure='all', + ), + 'requester.list': OperationDoc( + domain='requester', + label={'zh_Hans': '请求器列表', 'en_US': 'List Requesters'}, + summary='List HTTP request client adapters used for model calls.', + description='Retrieve supported HTTP and API request client implementations (e.g. standard HTTP, streaming client, proxy clients).', + risk='read', + exposure='all', + ), + 'skill.create': OperationDoc( + domain='skill', + label={'zh_Hans': '创建技能', 'en_US': 'Create Skill'}, + summary='Create and register a new custom skill package.', + description='Create a new skill package with name, description, and initial script files. Side effect: Instantiates a new skill directory.', + risk='write', + exposure='all', + ), + 'skill.delete': OperationDoc( + domain='skill', + label={'zh_Hans': '删除技能', 'en_US': 'Delete Skill'}, + summary='Delete a custom skill and remove its code files.', + description='Permanently remove a skill and delete its associated script files. Prerequisites: Call skill.list to obtain skill_name. Side effect: Irreversible removal of skill.', + risk='dangerous', + exposure='all', + ), + 'skill.directory.import': OperationDoc( + domain='skill', + label={'zh_Hans': '导入技能目录', 'en_US': 'Import Skill Directory'}, + summary='Import a skill package from a server filesystem path.', + description='Import a skill directory from the host server filesystem into the workspace. Requires server filesystem access: Not callable by agents.', + risk='write', + exposure='none', + ), + 'skill.directory.scan': OperationDoc( + domain='skill', + label={'zh_Hans': '扫描技能目录', 'en_US': 'Scan Skill Directory'}, + summary='Scan a server filesystem directory for skill packages.', + description='Scan a host directory path for valid skill packages. Requires server filesystem access: Not callable by agents.', + risk='read', + exposure='none', + ), + 'skill.file.list': OperationDoc( + domain='skill', + label={'zh_Hans': '技能文件列表', 'en_US': 'List Skill Files'}, + summary='List files and directories within a skill package.', + description='Inspect files and subdirectories contained in a skill package. Prerequisites: Call skill.list to obtain skill_name.', + risk='read', + exposure='all', + ), + 'skill.file.read': OperationDoc( + domain='skill', + label={'zh_Hans': '读取技能文件', 'en_US': 'Read Skill File'}, + summary='Read the source code or content of a file in a skill.', + description='Retrieve content of a specific source code or config file inside a skill package. Prerequisites: Call skill.file.list to obtain path and skill_name.', + risk='read', + exposure='all', + ), + 'skill.file.write': OperationDoc( + domain='skill', + label={'zh_Hans': '写入技能文件', 'en_US': 'Write Skill File'}, + summary='Write or update a code file inside a skill package.', + description='Write or overwrite a source code file inside a skill package. Prerequisites: Call skill.list to obtain skill_name. Side effect: Overwrites skill file content.', + risk='write', + exposure='all', + ), + 'skill.get': OperationDoc( + domain='skill', + label={'zh_Hans': '技能详情', 'en_US': 'Get Skill'}, + summary='Get full manifest and metadata for a specific skill.', + description='Retrieve complete skill definition, parameter schema, and file structure. Prerequisites: Call skill.list to obtain skill_name.', + risk='read', + exposure='all', + ), + 'skill.github.install': OperationDoc( + domain='skill', + label={'zh_Hans': '从GitHub安装技能', 'en_US': 'Install Skill from GitHub'}, + summary='Install a custom skill package from a GitHub repository.', + description='Clone and install a skill package from GitHub into the workspace. Restricted to assistant. Side effect: Writes skill files and registers new tools.', + risk='write', + exposure='assistant', + ), + 'skill.github.preview': OperationDoc( + domain='skill', + label={'zh_Hans': '预览GitHub技能', 'en_US': 'Preview GitHub Skill'}, + summary='Preview a skill package from a GitHub repository.', + description='Inspect metadata and file contents of a skill hosted on GitHub before installing.', + risk='read', + exposure='all', + ), + 'skill.list': OperationDoc( + domain='skill', + label={'zh_Hans': '技能列表', 'en_US': 'List Skills'}, + summary='List all custom skills installed in the workspace.', + description='Retrieve all custom skill packages registered in the workspace, including descriptions, version tags, and entry points.', + risk='read', + exposure='all', + ), + 'skill.reload': OperationDoc( + domain='skill', + label={'zh_Hans': '重新加载技能', 'en_US': 'Reload Skills'}, + summary='Reload all skill packages and refresh runtime registries.', + description='Re-index skill files from disk and re-register executable tools in the workspace runtime. Side effect: Refreshes active skill execution cache.', + risk='write', + exposure='all', + ), + 'skill.update': OperationDoc( + domain='skill', + label={'zh_Hans': '更新技能', 'en_US': 'Update Skill'}, + summary='Update metadata or configuration of an existing skill.', + description='Update skill description, parameters, or settings. Prerequisites: Call skill.list to obtain skill_name. Side effect: Modifies skill definition.', + risk='write', + exposure='all', + ), + 'skill.zip.install': OperationDoc( + domain='skill', + label={'zh_Hans': '安装压缩包技能', 'en_US': 'Install Skill from Zip'}, + summary='Install a skill package from an uploaded zip archive.', + description='Extract and install a skill package from an uploaded zip file. Requires file upload: Not callable by agents.', + risk='write', + exposure='none', + ), + 'skill.zip.preview': OperationDoc( + domain='skill', + label={'zh_Hans': '预览压缩包技能', 'en_US': 'Preview Skill Zip'}, + summary='Preview contents of an uploaded skill zip archive.', + description='Inspect metadata of an uploaded skill zip archive before installation. Requires file upload: Not callable by agents.', + risk='read', + exposure='none', + ), + 'stats.basic': OperationDoc( + domain='stats', + label={'zh_Hans': '基础数据统计', 'en_US': 'Basic Statistics'}, + summary='Get workspace overview counters for bots, models, and pipelines.', + description='Retrieve aggregate workspace statistics including total bot count, active pipelines, configured models, and knowledge bases.', + risk='read', + exposure='all', + ), + 'tool.get': OperationDoc( + domain='tool', + label={'zh_Hans': '工具详情', 'en_US': 'Get Tool'}, + summary='Get parameter schema and description for a specific tool.', + description='Retrieve input schema, argument descriptions, and execution requirements for a tool. Prerequisites: Call tool.list to obtain tool_name and pipeline_uuid.', + risk='read', + exposure='all', + ), + 'tool.list': OperationDoc( + domain='tool', + label={'zh_Hans': '工具列表', 'en_US': 'List Tools'}, + summary='List all registered function tools available for execution.', + description='Retrieve all available executable function tools, including plugin actions, MCP tools, and skill functions. Optionally filter by pipeline_uuid.', + risk='read', + exposure='all', + ), +} + + +def get_operation_doc(operation_id: str, *, side_effect: bool = False) -> OperationDoc: + """Lookup operation documentation metadata, defaulting out-of-scope operations to exposure none.""" + doc = OPERATION_DOCS.get(operation_id) + if doc is not None: + return doc + domain = operation_id.split('.')[0] + domain_meta = DOMAINS.get(domain, {}) + label = domain_meta.get('label', {'zh_Hans': domain, 'en_US': domain.capitalize()}) + return OperationDoc( + domain=domain, + label=label, + summary='', + description='', + risk='write' if side_effect else 'read', + exposure='none', + ) diff --git a/src/langbot/pkg/api/application/service_operations.py b/src/langbot/pkg/api/application/service_operations.py index d09147b9c..e9c146ef1 100644 --- a/src/langbot/pkg/api/application/service_operations.py +++ b/src/langbot/pkg/api/application/service_operations.py @@ -759,6 +759,53 @@ _OUTPUT_TYPES = { _INTERNAL_PARAMETERS = {'preserve_uuid', 'default', 'on_result', 'for_inflight'} +_LIST_OPS_BY_ENTITY = { + 'pipeline': 'pipeline.list', + 'bot': 'bot.list', + 'agent': 'agent.list', + 'model': 'model.llm.list', + 'provider': 'provider.list', + 'kb': 'knowledge.base.list', + 'knowledge_base': 'knowledge.base.list', + 'adapter': 'adapter.list', + 'account': 'workspace.member.list', + 'workspace': 'workspace.current', + 'api_key': 'api_key.list', + 'webhook': 'webhook.list', + 'invitation': 'workspace.invitation.list', +} + + +def _field_description(name: str, operation_id: str) -> str | None: + if name == 'include_secret': + return 'Whether to include secret values (e.g. API keys or tokens) in the response' + if name in {'limit', 'max_count', 'max_entries'}: + return 'Maximum number of items to return in the response' + if name in {'offset', 'from_index'}: + return 'Number of items to skip before returning results' + if name == 'after_sequence': + return 'Sequence number to resume pagination after' + if name == 'before_id': + return 'Event or record ID to fetch items before' + if name in {'start_time', 'end_time'}: + return 'ISO 8601 timestamp or Unix epoch representing the time boundary' + if name in {'query', 'keyword', 'user_query'}: + return 'Search query string used to filter results' + if name.endswith('_uuid'): + entity = name[:-5] + list_op = _LIST_OPS_BY_ENTITY.get(entity, f'{entity}.list') + return f'UUID of the {entity.replace("_", " ")}; get it from {list_op}' + if name.endswith('_id') and not name.startswith('_'): + entity = name[:-3] + if entity in {'bot', 'pipeline', 'agent'}: + return f'ID of the {entity}; get it from {entity}.list' + if entity == 'run': + return 'ID of the execution run; get it from agent.runs.list' + if entity == 'session': + return 'Unique session identifier' + return None + + def _contract(operation_id, method): signature = inspect.signature(method) hints = typing.get_type_hints(method) @@ -782,6 +829,9 @@ def _contract(operation_id, method): constraints = {'ge': 0} elif annotation is str and (name.endswith(('_uuid', '_id')) or name in {'query', 'uri'}): constraints = {'min_length': 1} + desc = _field_description(name, operation_id) + if desc is not None: + constraints['description'] = desc fields[name] = (annotation, Field(default=default, **constraints)) model_name = ''.join(part.title() for part in operation_id.split('.')) + 'Input' model = create_model(model_name, __base__=Input, **fields)