类class agentscope.app.channel

DingTalkChannel

class DingTalkChannel(ChannelBase)

源码Source agentscope/app/channel/_dingtalk/_channel.py:83–1237

DingTalk 渠道，把智能体接入外部消息渠道与企业平台。位于 agentscope.app.channel 包，继承自 ChannelBase。核心成员包括 start_listening、aclose、send_response、chat_kind、chat_name、list_bot_chats。

DingTalk enterprise application robot channel. Declared in agentscope.app.channel. Extends ChannelBase.

嵌套类摘要Nested Class Summary

类Class	类型Kind	说明Description
`Credentials`	类class	凭证，把智能体接入外部消息渠道与企业平台。 DingTalk application credentials.
`Config`	类class	配置，保存相关配置项。 DingTalk platform options.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(channel_id: str, credentials: 'DingTalkChannel.Credentials', config: 'DingTalkChannel.Config') -> None`	构建DingTalk 渠道来自已校验设置。 Build a DingTalk channel from validated settings.

属性摘要Property Summary

属性Property	说明Description
`channel_id`	获取渠道标识。 The unique channel instance identifier.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`channel_type`	—	渠道类型字段。	`'dingtalk'`
`display_name`	—	展示名称字段。	`'DingTalk'`
`description`	—	`description` 字段。	`'Enterprise robot for DingTalk groups and direct messages.'`
`icon_url`	—	`icon_url` 字段。	`'https://www.google.com/s2/favicons?domain=dingtalk.com&sz=128'`
`platform_bot_id_field`	—	`platform_bot_id_field` 字段。	`'client_id'`
`capabilities`	—	能力字段。	`ChannelCapability(text=True, markdown=True, image=True, file=True, interactive=True, streaming=False, max_message_length=_MAX_LEN, wiki=True)`

方法摘要Method Summary

方法Method	说明Description
`async def start_listening(emit: Callable[[ChannelEvent \| ChannelConfirmationResultEvent], Awaitable[None]]) -> None`async	启动 `start_listening`。 Start the DingTalk Stream connection until cancelled.
`async def aclose() -> None`async	返回 `aclose` 结果。 Close an HTTP client opened outside the connection loop.
`async def send_response(event:` `ChannelEvent, events: AsyncIterator[dict]) -> None`async	发送响应。 Send an Agent reply using an optional DingTalk AI Card stream.
`async def chat_kind(chat_id: str) ->` `ChatKind \| None`async	设置聊天种类。 Return the audience kind encoded in a DingTalk chat id.
`async def chat_name(chat_id: str) -> str`async	设置聊天名称。 Return a cached inbound conversation title.
`async def list_bot_chats() -> list[dict]`async	列出 `list_bot_chats`。 List conversations observed by this robot process.
`async def list_tools(workspace: 'WorkspaceBase', channel_user_id: str \| None = None) -> list['ToolBase']`async	列出当前连接可用的工具。 Expose DingTalk tools to the agent.
`async def search_users(query: str, limit: int = 20) -> list[dict[str, Any]]`async	搜索用户。 Search users visible to the DingTalk application.
`async def list_wiki_spaces(channel_user_id: str, limit: int, next_token: str \| None = None) -> WikiPage[WikiSpace]`async	列出 `list_wiki_spaces`。 List the DingTalk knowledge bases one user can read.
`async def list_wiki_nodes(channel_user_id: str, parent_node_id: str, limit: int, next_token: str \| None = None) -> Wiki…`async	列出 `list_wiki_nodes`。 List the children of one DingTalk knowledge node.
`async def read_wiki_document(channel_user_id: str, node_id: str, start_index: int, max_blocks: int) -> WikiDocument \| N…`async	执行 `read_wiki_document` 方法。 Read a bounded block range of one DingTalk document.
`async def send_message_to(target: str, text: str) -> bool`async	发送消息到。 Send Markdown text to an encoded DingTalk target.
`async def send_file_to(target: str, data: bytes, file_name: str) -> bool`async	发送文件到。 Upload and send a workspace file to a DingTalk target.
`async def send_image_to(target: str, data: bytes, file_name: str) -> bool`async	发送图像到。 Upload and send a workspace image to a DingTalk target.

构造器详情Constructor Detail

DingTalkChannel

def __init__(channel_id: str, credentials: 'DingTalkChannel.Credentials', config: 'DingTalkChannel.Config') -> None

构建DingTalk 渠道来自已校验设置。

Build a DingTalk channel from validated settings.

参数Parameters

名称Name	类型Type	说明Description
`channel_id`	str	渠道标识（类型 `str`）。This channel instance's unique id.
`credentials`	'DingTalkChannel.Credentials'	凭证（类型 `'DingTalkChannel.Credentials'`）。DingTalk Client ID and Client Secret.
`config`	'DingTalkChannel.Config'	配置对象（类型 `'DingTalkChannel.Config'`）。Channel display and routing options.

源码Source agentscope/app/channel/_dingtalk/_channel.py:166–201

属性详情Attribute Detail

channel_type

 = 'dingtalk'

渠道类型字段。

The channel type field.

源码Source agentscope/app/channel/_dingtalk/_channel.py:86

display_name

 = 'DingTalk'

展示名称字段。

The display name field.

源码Source agentscope/app/channel/_dingtalk/_channel.py:87

description

 = 'Enterprise robot for DingTalk groups and direct messages.'

description 字段。

The description field.

源码Source agentscope/app/channel/_dingtalk/_channel.py:88

icon_url

 = 'https://www.google.com/s2/favicons?domain=dingtalk.com&sz=128'

icon_url 字段。

The icon url field.

源码Source agentscope/app/channel/_dingtalk/_channel.py:89

platform_bot_id_field

 = 'client_id'

platform_bot_id_field 字段。

The platform bot id field field.

源码Source agentscope/app/channel/_dingtalk/_channel.py:90

capabilities

 = ChannelCapability(text=True, markdown=True, image=True, file=True, interactive=True, streaming=False, max_message_length=_MAX_LEN, wiki=True)

能力字段。

The capabilities field.

源码Source agentscope/app/channel/_dingtalk/_channel.py:155

属性详情Property Detail

channel_id

def channel_id() -> str

获取渠道标识。

The unique channel instance identifier.

返回Returns str

返回字符串结果。Returns a string.

源码Source agentscope/app/channel/_dingtalk/_channel.py:204–206

方法详情Method Detail

start_listening

async def start_listening(emit: Callable[[ChannelEvent | ChannelConfirmationResultEvent], Awaitable[None]]) -> None

async

启动 start_listening。

The official SDK performs reconnects.

参数Parameters

名称Name	类型Type	说明Description
`emit`	Callable[[ChannelEvent \| ChannelConfirmationResultEvent], Awaitable[None]]	发出（类型 `Callable[[ChannelEvent \| ChannelConfirmationResultEvent], Awaitable[None]]`）。Gateway callback for normalised inbound events.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/app/channel/_dingtalk/_channel.py:208–273

aclose

async def aclose() -> None

async

返回 aclose 结果。

Close an HTTP client opened outside the connection loop.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/app/channel/_dingtalk/_channel.py:294–299

send_response

async def send_response(event: ChannelEvent, events: AsyncIterator[dict]) -> None

async

发送响应。

Without a streaming-card template the complete reply is sent as one or more Markdown messages.

参数Parameters

名称Name	类型Type	说明Description
`event`	ChannelEvent	DingTalk 回复目标。The DingTalk reply target.
`events`	AsyncIterator[dict]	事件列表（类型 `AsyncIterator[dict]`）。The run's streamed Agent events.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/app/channel/_dingtalk/_channel.py:301–397

chat_kind

async def chat_kind(chat_id: str) -> ChatKind | None

async

设置聊天种类。

Return the audience kind encoded in a DingTalk chat id.

参数Parameters

名称Name	类型Type	说明Description
`chat_id`	str	聊天标识（类型 `str`）。`group: ` or `user: `.

返回Returns ChatKind | None

返回ChatKind|None。`ChatKind | None`: Group, private, or `None` for an unknown

源码Source agentscope/app/channel/_dingtalk/_channel.py:471–486

chat_name

async def chat_name(chat_id: str) -> str

async

设置聊天名称。

Return a cached inbound conversation title.

参数Parameters

名称Name	类型Type	说明Description
`chat_id`	str	已编码 DingTalk 聊天标识。The encoded DingTalk chat id.

返回Returns str

返回字符串结果。`str`: The title supplied by DingTalk, or an empty string.

源码Source agentscope/app/channel/_dingtalk/_channel.py:488–497

list_bot_chats

async def list_bot_chats() -> list[dict]

async

列出 list_bot_chats。

DingTalk does not expose an application-robot equivalent of Feishu's bot-chat enumeration API.

返回Returns list[dict]

返回dict列表。`list[dict]`: Known encoded targets, names, and chat types.

源码Source agentscope/app/channel/_dingtalk/_channel.py:499–518

list_tools

async def list_tools(workspace: 'WorkspaceBase', channel_user_id: str | None = None) -> list['ToolBase']

async

列出当前连接可用的工具。

Expose DingTalk tools to the agent.

参数Parameters

名称Name	类型Type	说明Description
`workspace`	'WorkspaceBase'	工作区（类型 `'WorkspaceBase'`）。Calling session workspace whose backend is used for file reads.
`channel_user_id`默认default `None`	str \| None	渠道用户标识（类型 `str \| None`）。The DingTalk user the session acts as, passed through to the inherited wiki tools.

返回Returns list['ToolBase']

返回'ToolBase'列表。`list[ToolBase]`: DingTalk agent tools.

源码Source agentscope/app/channel/_dingtalk/_channel.py:520–551

search_users

async def search_users(query: str, limit: int = 20) -> list[dict[str, Any]]

async

搜索用户。

Search users visible to the DingTalk application.

参数Parameters

名称Name	类型Type	说明Description
`query`	str	查询文本（类型 `str`）。User-name search term.
`limit`默认default `20`	int	数量上限（类型 `int`）。Maximum number of results.

返回Returns list[dict[str, Any]]

返回dict[str,任意]列表。`list[dict[str, Any]]`: Basic visible user profiles.

源码Source agentscope/app/channel/_dingtalk/_channel.py:553–567

list_wiki_spaces

async def list_wiki_spaces(channel_user_id: str, limit: int, next_token: str | None = None) -> WikiPage[WikiSpace]

async

列出 list_wiki_spaces。

List the DingTalk knowledge bases one user can read.

参数Parameters

名称Name	类型Type	说明Description
`channel_user_id`	str	渠道用户标识（类型 `str`）。Staff id from the inbound event.
`limit`	int	数量上限（类型 `int`）。Maximum spaces to return.
`next_token`默认default `None`	str \| None	下一个令牌（类型 `str \| None`）。Token from a previous page.

返回Returns WikiPage[WikiSpace]

返回WikiPage[WikiSpace]。`WikiPage[WikiSpace]`: One page of knowledge bases.

异常Raises

可能抛出 `Exception`。`RuntimeError`: If DingTalk rejects the lookup.

源码Source agentscope/app/channel/_dingtalk/_channel.py:569–606

list_wiki_nodes

async def list_wiki_nodes(channel_user_id: str, parent_node_id: str, limit: int, next_token: str | None = None) -> WikiPage[WikiNode]

async

列出 list_wiki_nodes。

List the children of one DingTalk knowledge node.

参数Parameters

名称Name	类型Type	说明Description
`channel_user_id`	str	渠道用户标识（类型 `str`）。Staff id from the inbound event.
`parent_node_id`	str	父级节点标识（类型 `str`）。Knowledge-base root or folder node id.
`limit`	int	数量上限（类型 `int`）。Maximum children to return.
`next_token`默认default `None`	str \| None	下一个令牌（类型 `str \| None`）。Token from a previous page.

返回Returns WikiPage[WikiNode]

返回WikiPage[WikiNode]。`WikiPage[WikiNode]`: One page of child entries.

异常Raises

可能抛出 `Exception`。`RuntimeError`: If DingTalk rejects the lookup.

源码Source agentscope/app/channel/_dingtalk/_channel.py:608–642

read_wiki_document

async def read_wiki_document(channel_user_id: str, node_id: str, start_index: int, max_blocks: int) -> WikiDocument | None

async

执行 read_wiki_document 方法。

Read a bounded block range of one DingTalk document.

参数Parameters

名称Name	类型Type	说明Description
`channel_user_id`	str	渠道用户标识（类型 `str`）。Staff id from the inbound event.
`node_id`	str	节点标识（类型 `str`）。Wiki node id, which is also the document key.
`start_index`	int	启动索引（类型 `int`）。First block index to read.
`max_blocks`	int	最大 blocks（类型 `int`）。Maximum blocks to read.

返回Returns WikiDocument | None

返回WikiDocument|None。`WikiDocument | None`: The range read, or `None` when the

异常Raises

可能抛出 `Exception`。`RuntimeError`: If DingTalk rejects the lookup.

源码Source agentscope/app/channel/_dingtalk/_channel.py:644–685

send_message_to

async def send_message_to(target: str, text: str) -> bool

async

发送消息到。

Send Markdown text to an encoded DingTalk target.

参数Parameters

名称Name	类型Type	说明Description
`target`	str	目标（类型 `str`）。Target from a discovery tool.
`text`	str	文本（类型 `str`）。Markdown-formatted message body.

返回Returns bool

返回布尔值，表示判断结果。`bool`: Whether DingTalk accepted the message.

源码Source agentscope/app/channel/_dingtalk/_channel.py:687–697

send_file_to

async def send_file_to(target: str, data: bytes, file_name: str) -> bool

async

发送文件到。

Upload and send a workspace file to a DingTalk target.

参数Parameters

名称Name	类型Type	说明Description
`target`	str	目标（类型 `str`）。Target from a discovery tool.
`data`	bytes	数据（类型 `bytes`）。File bytes.
`file_name`	str	文件名称（类型 `str`）。Display filename.

返回Returns bool

返回布尔值，表示判断结果。`bool`: Whether DingTalk accepted the file.

源码Source agentscope/app/channel/_dingtalk/_channel.py:699–723

send_image_to

async def send_image_to(target: str, data: bytes, file_name: str) -> bool

async

发送图像到。

Upload and send a workspace image to a DingTalk target.

参数Parameters

名称Name	类型Type	说明Description
`target`	str	目标（类型 `str`）。Target from a discovery tool.
`data`	bytes	数据（类型 `bytes`）。Image bytes.
`file_name`	str	文件名称（类型 `str`）。Image filename used for MIME detection.