MCP 完整接入参考

Arkme MCP Server 面向 MCP Host、SDK 和插件开发者。本文包含连接方式、工具选择规则、参数示例和全部 Tool 参考。直接把文档交给 Agent 使用时，提供更紧凑的 MCP Agent 使用指南。

连接 MCP Server

在 开发者控制台 创建 API Key，并在 MCP Host 中配置 Server URL 与认证 Header。Host 连接后通过标准 MCP tools/list 发现当前 Tool，通过 tools/call 调用。运行时 tools/list 返回的名称、描述、Input Schema、Output Schema 和 annotations 是机器合同。

成功的 Tool 调用同时返回 structuredContent 和等价 JSON 文本；Agent 应优先读取 structuredContent。Server 无状态，不分配 MCP-Session-Id，也不提供 resources、prompts、sampling 或 tasks。

Tool 目录

账号

• get_current_user_profile — 获取当前用户资料
• get_current_user_account_bindings — 获取账号绑定状态

人物

• resolve_people — 解析人物

聊天

• list_chat_conversations — 列出可读会话
• query_chat_conversations — 查询聊天会话
• resolve_chat_conversations — 解析可读会话
• list_chat_members — 列出会话成员
• search_chat_messages — 搜索聊天消息
• query_chat_messages — 查询聊天消息
• batch_get_chat_messages — 批量读取聊天消息
• read_chat_message_context — 读取消息上下文
• resolve_chat_targets — 解析消息发送目标
• create_private_chats — 创建真人私聊
• send_chat_messages — 批量发送聊天消息
• query_group_message_moderation_targets — 查询群消息治理对象
• withdraw_group_messages — 批量撤回群消息
• batch_get_group_members — 批量读取群成员状态
• remove_group_members — 批量移出群成员
• set_group_join_restrictions — 批量设置入群限制
• list_group_join_restrictions — 列出群入群限制

微信导入

• query_wechat_import_conversations — 查询微信导入会话
• resolve_wechat_import_conversations — 解析微信导入会话
• batch_get_wechat_import_conversations — 批量读取微信导入会话
• query_wechat_import_messages — 查询微信导入消息
• batch_get_wechat_import_messages — 批量读取微信导入消息
• list_wechat_group_members — 列出微信导入群成员

录音

• query_recordings — 查询录音
• resolve_recording_speakers — 解析录音说话人
• batch_get_recordings — 批量读取录音
• query_recording_transcript — 查询录音转写
• query_recording_summaries — 查询录音总结与时间线
• read_recording_summary — 读取录音总结与时间线

通话

• query_calls — 查询通话
• batch_get_calls — 批量读取通话
• query_call_transcript — 查询通话转写

记录

• list_record_containers — 列出记录主题
• resolve_record_containers — 解析记录主题
• query_record_timeline — 查询记录时间线
• search_records — 搜索记录
• batch_get_records — 批量读取记录
• create_records — 批量创建记录
• update_records — 批量更新记录
• move_records — 批量移动记录
• delete_records — 批量删除记录

安排

• query_arrangements — 查询安排
• batch_get_arrangements — 批量读取安排
• create_arrangements — 批量创建安排
• update_arrangements — 批量更新安排
• transition_arrangements — 批量流转安排状态
• delete_arrangements — 批量删除安排

团队

• remove_team_members — 移除团队成员
• list_my_teams — 列出我的团队
• resolve_my_teams — 解析我的团队
• list_team_members — 列出团队成员
• create_teams — 创建团队
• join_teams_by_jotmo_id — 按即我号加入团队

世界

• query_world_records — 查询世界动态
• batch_get_world_records — 读取世界发布快照
• query_world_replies — 查询世界评论
• publish_world_records — 发布快记到世界
• unpublish_world_records — 撤回世界发布
• query_world_candidates — 查询已有世界候选
• get_world_interaction_summary — 读取世界互动摘要
• mark_world_interactions_viewed — 标记世界互动已查看

机器人

• query_bots — 查询本人机器人
• batch_get_bots — 读取机器人资料
• create_bots — 创建机器人
• update_bot_profiles — 更新机器人资料
• delete_bots — 删除机器人
• list_group_bot_bindings — 列举机器人群绑定
• install_group_bots — 安装群机器人
• remove_group_bots — 移除群机器人
• set_group_bot_context_permissions — 设置机器人群读取授权
• resolve_bot_conversations — 定位机器人专属会话
• query_bot_conversation_messages — 查询机器人会话历史
• query_bot_request_result — 查询机器人请求结果
• send_bot_requests — 向机器人发送用户请求
• publish_bot_messages — 以机器人身份发布消息
• get_bot_webhook_security — 读取机器人 Webhook 安全设置
• set_bot_webhook_security — 设置机器人 Webhook 安全规则

标识与组合规则

不同标识不可互换。topic_uid 只表示个人主题；即我聊天使用 chat_session_uid，微信导入会话使用 conversation_uid。团队与群的成员关系独立；user_ref 可跨能力复用，成员权限由目标团队或群分别判断。持有标识不代表拥有读取权限。

speaker_index 和 sender_index 分别是本页 speakers 和 senders 的零基索引，不是人物标识，不可跨页或跨业务复用。只有返回了 user_ref 才可将该引用用于人物关联；不能仅按显示名合并身份，通话的 participant_side 也不代表参与人本人。微信导入群成员是导入快照中的当前名单，不是历史发言人集合或微信实时成员。

读取范围与完整性

录音查询的 order 缺省 asc，desc 从最新录音开始；最新指录音开始时间，不是上传或修改时间。时间条件按录音重叠范围筛选，有人物条件时要求该人物在范围内有有效话语。转写查询不继承列表筛选；省略时间窗时读取整条录音，显式传入 start_at/end_at 时，按重叠选择完整原句话语，不做字级时间裁剪。

已有稳定标识时可直接读取所需正文，无须先读取概览。录音和通话的批量读取返回概览或状态，转写正文由各自的转写查询分页返回。

已确认的即我账号使用 user_ref：录音对应 speaker_user_refs，通话对应 participant_user_refs，微信导入会话对应 participant_user_ref。录音与通话多目标取并集。微信无已绑定私聊时返回空，不代表没有相关微信数据；可按用户给出的微信名称解析候选，不推断账号绑定。录音标记名称使用说话人解析，微信备注名、昵称或群名使用微信导入会话解析；名称不自动合并身份。

解析与人物筛选均读取当前可见状态，不创建人物、会话或绑定。页间标记或绑定变化可能改变结果，需要一致重读时从第一页重新查询。空页仍应检查 has_more，扫描未结束不能断言不存在目标。

时间字段的单位、上下界是否包含、默认范围和排序以各能力字段合同为准，不跨业务套用。微信导入会话按最新消息时间筛选，消息按发送时间筛选；分析某段时间内的全部历史消息时，不要用同一时间窗预先排除会话，应不带时间条件枚举会话，再逐个查询目标时间范围内的消息。

需要覆盖整个查询范围时，按该能力的分页字段逐页读取，直到 has_more=false，不能按本页条数判断是否结束。使用不透明游标时，将返回的 next_page_cursor 原样传回 page_cursor，保持账号、能力、对象和筛选条件不变；limit 只控制单页大小，可以调整。每页处理后累计中间结果，需要引用时保留业务标识与原文定位信息。

分页结束只表示本次可读结果已读完，不保证业务数据完整。返回 found=false 表示当前不可读，不能推断对象不存在或已删除；转写还需判断 transcript_state，群成员还需判断 roster_state。媒体元数据也不等于可下载的媒体正文。

录音转写的 bounded 模式不通过继续分页补回截断句尾；需完整原话时改用 text_mode=full，从首页重新读取。full 模式按 utterance_index 和字符坐标拼接同一句的续片，不跨录音或结果快照复用话语序号；坐标以 Unicode code point 计数。truncated=true 表示当前项不是整句，不等于续读后仍缺正文。确认片段连续覆盖 text_total_length，并检查 transcript_state。通话转写及其他正文或名单仍按各自的截断合同处理，不能套用录音 full 模式或假定分页能补回截断内容。

录音总结是自动生成的参考内容；核对原话时读取转写，不必先读取或等待总结。已有 summary_uid 可直接读正文；需要选择版本时按覆盖时间查询。读取时先检查 found 和 content_state，仅 ready 返回正文，JSON 分片须拼齐后解析。查询和读取均不触发生成。

组合示例（非穷举）

下列示例用于说明 Tool 之间的数据依赖，不定义固定工作流。已有所需稳定标识时，可直接从消费该标识的 Tool 开始。

• 从世界内容联系作者（batch_get_world_records → create_private_chats → send_chat_messages）：使用内容返回的作者用户引用明确创建真人私聊，再按用户意图发送消息；创建私聊不会自动加联系人或发送内容。
• 安装并调用群机器人（(query_bots / create_bots) → list_group_bot_bindings → install_group_bots → set_group_bot_context_permissions → send_chat_messages）：指定真实群和 Bot UID；安装不隐式开放群成员或历史读取。仅在需要时显式授予上下文权限，发送时以 bot_mentions 指定 Bot 身份、提及原文与必要的出现次序。
• 向 OpenClaw 提问并读取回答（query_bots → send_bot_requests → query_bot_request_result）：选择本人的 OpenClaw Bot，重试使用原幂等键、正文和消息时间。发送成功表示投递受理，回答异步产生，不把受理当成执行完成。
• 群主移除他人的群机器人（list_group_bot_bindings → remove_group_bots）：使用明确的 Bot UID 和本群 chat_session_uid 精确读取绑定，再携带当前 revision 移除。群主只能读取本群的该绑定，不能列举该 Bot 的其他群或读取其私有资料。
• 以 Webhook Bot 发群通知（list_group_bot_bindings → publish_bot_messages）：明确选择一个已安装群；使用绑定本次目标和正文的幂等键，不默认向全部群或专属会话广播。此工具与向 OpenClaw 发送请求不同。
• 发布本人快记到世界（(batch_get_records / batch_get_world_records) → publish_world_records）：读取源 Record 当前版本和 World 当前写入水位；只有用户明确要求公开时发布。两种版本不可互换；评论还需显式指定父动态。
• 查看世界互动（get_world_interaction_summary → query_world_replies → mark_world_interactions_viewed）：查询不改变未读；只有明确需要确认查看时，提交实际展示过的摘要序号，不用更晚捕获的序号代替。
• 群成员治理（batch_get_group_members → (remove_group_members / set_group_join_restrictions)）：已有明确目标时可直接写，无须先读取成员状态；移出、未来入群限制和消息撤回分别成立。remove 的 prevent_rejoin=true 才原子同时限制；false 不清除原限制。结果未知时核对当前成员状态，重新入群后需重新确认移出意图。
• 清理明确发送者的群消息（query_group_message_moderation_targets → withdraw_group_messages）：按明确发送者和可选时间分页定位，再把群 UID 与 sequence 分批撤回；已有坐标可直接写。空页检查 has_more，固定上界不是快照，晚到提交需重新扫描。不删除 Record 正文，也不隐式移出发送者。
• 读取最新或最早录音的内容（query_recordings → query_recording_transcript）：按录音开始时间选择 order=desc（最新）或 asc（最早），可设置 limit=1；空页仍检查 has_more。定位后直接读取转写，没有正文时如实说明，不以另一条有正文的录音替代。
• 查询与已确认账号有关的录音、通话或微信私聊（resolve_people → (query_recordings / query_calls / query_wechat_import_conversations)）：按业务分别使用 speaker_user_refs、participant_user_refs 或 participant_user_ref。录音与通话的多目标筛选为任一目标匹配。微信只读取当前账号已绑定该人的导入私聊；没有绑定时返回空，不能据此断言没有相关微信数据，可再按用户提供的微信名称解析候选。
• 按非账号标记人查录音（resolve_recording_speakers → query_recordings → query_recording_transcript）：选择正式说话人候选后，把 speaker_uid 放入 speaker_uids 查询录音，再读取转写。同名标记不自动合并；若已确认其 user_ref，可按该引用展开所有关联标记。
• 按微信联系人或群名查历史消息（resolve_wechat_import_conversations → query_wechat_import_messages）：先按备注名、昵称或群名取得候选，选择 conversation_uid 后在消息查询中设置目标时间范围。不要把微信名称或会话 UID 当作即我账号标识。
• 给一个人发消息（resolve_people → resolve_chat_targets → send_chat_messages）：先取得 user_ref，再用它定位可发送的 chat_session_uid，最后发送消息。
• 读取与一个人共同参与的对话（resolve_people → (list_chat_conversations / query_chat_conversations) → query_chat_messages）：先取得 user_ref，将它作为 participant_user_ref 传给会话列举或会话时间查询，再用返回的 chat_session_uid 读取消息；参与人筛选不是消息发送人筛选。
• 按会话名称读取消息（resolve_chat_conversations → query_chat_messages）：先解析会话名称，再用选中的 chat_session_uid 读取消息。
• 分析一段时间内的聊天（(list_chat_conversations / resolve_chat_conversations / query_chat_conversations) → query_chat_messages）：先列举、解析或复用已有会话标识，再按消息时间范围分页读取；只有按会话当前最新消息时间筛选活跃会话时才使用会话时间查询。
• 按内容定位聊天并核实完整正文（search_chat_messages → batch_get_chat_messages）：先在已知可读会话中取得命中证据，再用命中的 chat_session_uid + sequence 精确读取当前完整消息。
• 分析一条消息附近的对话（search_chat_messages → read_chat_message_context）：先取得消息定位坐标，再读取同一会话内围绕该坐标的上下文窗口。
• 分析微信导入的历史对话（query_wechat_import_conversations → query_wechat_import_messages）：已有 conversation_uid 时直接读取消息。分析某段时间内的全部历史消息时，先不带时间条件分页枚举会话，再在消息查询中传入目标时间范围；会话查询的时间条件只筛选最新消息时间，不能代替消息时间筛选。需要导入快照中的当前群成员时单独调用成员列举工具，不把它当作历史发言人名单或微信实时成员。
• 分析一段录音的内容（(query_recordings / batch_get_recordings) → query_recording_transcript）：未知录音时按时间浏览，已有 recording_uid 时可直接读取转写。需要限定时段时显式传 start_at/end_at，不继承列表筛选；需完整原话时使用 text_mode=full，按话语与字符坐标拼接并检查 transcript_state。
• 参考录音日总结或时间线（query_recording_summaries → read_recording_summary）：按覆盖时间查找并选择所需版本；已有 summary_uid 时直接读正文。先检查 found 和 content_state，ready 时分页读取并拼接；JSON 拼齐后解析。总结未就绪时可直接读取转写。
• 分析一次通话的内容（(query_calls / batch_get_calls) → query_call_transcript）：先按结构化条件浏览通话或精确确认已知通话，再用 call_uid 分页读取规范转写；participant_side 不是具体用户身份。
• 在个人主题下创建记录或安排（(list_record_containers / resolve_record_containers) → (create_records / create_arrangements)）：浏览主题结构时列举容器，按名称定位时解析容器；取得 topic_uid 后再创建业务事实。
• 修改或删除记录、安排（batch_get_records / batch_get_arrangements）：先按业务类型精确读取当前版本、状态或容器，再从已发现的能力中选择对应写 Tool，并传入观察到的并发控制值。
• 移除团队成员（(list_my_teams / resolve_my_teams) → list_team_members → remove_team_members）：从团队查询结果取得 team_ref，从成员列表取得目标 user_ref；仅团队所有者可按用户明确意图移除其他成员，team_ref 不能用 chat_session_uid 替代，团队成员关系与群成员关系独立。
• 查看团队成员（(list_my_teams / resolve_my_teams) → list_team_members）：先列举或解析当前账号已有团队以取得 team_ref，再读取团队成员；团队名称不能代替引用。

已有任务所需的公开标识或消息坐标时，直接传给消费 Tool，不重复调用产生它们的解析、列举、查询或搜索 Tool。需要复核当前状态或并发控制值时仍应使用精确读取 Tool；需要正文时选择返回正文的能力，概览与摘要不能代替正文。

解析 Tool 返回当前页候选和 has_more。确认候选唯一时可直接使用其标识，但本页只有一项且 has_more=true 不能据此认定全局唯一；存在多个候选时应根据用户提供的上下文选择，无法可靠区分时让用户确认；has_more=true 时原样传回 next_page_cursor 继续查询。继续分页时保持决定结果集的筛选条件不变；limit 只控制单页大小，可以调整。不得仅凭名称猜测。

写 Tool 结果未知时只能使用完全相同的业务参数重试；Tool 包含 idempotency_key 时，同一业务意图必须复用原值。expected_version 冲突时先重新读取当前事实，再决定新的写入意图。

字段表中的嵌套字段仅在其父对象存在时适用。

账号

get_current_user_profile

返回当前账号的 user_ref、昵称、即我号和创建时间。

参数

无字段，请求体使用 {}。

arguments 示例

{}

返回字段

structuredContent 示例

{
  "user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "nickname": "小明",
  "jotmo_id": "xiaoming",
  "created_at": 1700000000000
}

get_current_user_account_bindings

需要判断当前账号是否绑定 phone、email、wechat、apple、google 或 huawei 登录方式时调用。只返回绑定布尔值。

参数

无字段，请求体使用 {}。

arguments 示例

{}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "provider": "phone",
      "bound": true
    },
    {
      "provider": "email",
      "bound": false
    },
    {
      "provider": "wechat",
      "bound": true
    },
    {
      "provider": "apple",
      "bound": false
    },
    {
      "provider": "google",
      "bound": false
    },
    {
      "provider": "huawei",
      "bound": false
    }
  ]
}

人物

resolve_people

按昵称、联系人备注、即我号或“我/本人”查找业务可见人物；选择候选后直接使用 user_ref。

参数

arguments 示例

{
  "items": [
    {
      "item_id": "person-1",
      "query": "小明",
      "limit": 5
    }
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "item_id": "person-1",
      "candidates": [
        {
          "user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
          "display_name": "小明",
          "jotmo_id": "xiaoming",
          "relationships": [
            "contact",
            "private_chat"
          ]
        }
      ],
      "has_more": false
    }
  ]
}

聊天

list_chat_conversations

需要浏览当前账号可读取的联系人、私聊或群聊时调用；participant_user_ref 可筛选某个人当前参与的会话。pending 结果只表示可读取，不应直接交给发送工具。

参数

枚举值说明

arguments 示例

{
  "scopes": [
    "private_chat",
    "group_chat"
  ],
  "limit": 50
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "chat_session_uid": "chat-session-1",
      "kind": "direct",
      "scopes": [
        "private_chat"
      ],
      "display_name": "小明"
    }
  ],
  "has_more": false
}

query_chat_conversations

需要按最新消息时间范围查找会话时调用；“最近”通过 last_message_from 表达，participant_user_ref 可筛选某个人当前参与的会话。取得 chat_session_uid 后再用 query_chat_messages 查询消息内容。继续翻页时保持筛选条件不变并原样传入 next_page_cursor。

参数

枚举值说明

arguments 示例

{
  "scopes": [
    "private_chat",
    "group_chat"
  ],
  "last_message_from": 1700000000000,
  "limit": 20
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "chat_session_uid": "chat-session-1",
      "kind": "direct",
      "scopes": [
        "private_chat"
      ],
      "display_name": "小明",
      "last_message_at": 1700001000000
    }
  ],
  "has_more": false
}

resolve_chat_conversations

按名称或描述查询当前账号可读的会话候选。需要更多候选时原样传回 next_page_cursor；选定后直接把候选的 chat_session_uid 交给读取能力。

参数

枚举值说明

arguments 示例

{
  "items": [
    {
      "item_id": "conversation-1",
      "query": "项目讨论群",
      "scopes": [
        "group_chat"
      ],
      "limit": 5
    }
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "item_id": "conversation-1",
      "candidates": [
        {
          "chat_session_uid": "chat-session-2",
          "kind": "group",
          "scopes": [
            "group_chat"
          ],
          "display_name": "项目讨论群"
        }
      ],
      "has_more": false
    }
  ]
}

list_chat_members

已有 chat_session_uid、需要知道当前有效真人成员及其 user_ref 时调用。继续翻页时原样使用 next_page_cursor。

参数

arguments 示例

{
  "chat_session_uid": "chat-session-1",
  "limit": 50
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "display_name": "小明",
      "role": "participant",
      "joined_at": 1699990000000
    }
  ],
  "has_more": false
}

search_chat_messages

已有一个或多个 chat_session_uid、需要按关键词定位消息时调用。可用 sender_user_refs 和消息时间收窄；命中后可把 chat_session_uid 与 sequence 交给批量精确读取或上下文能力。

参数

arguments 示例

{
  "keyword": "同步进度",
  "chat_session_uids": [
    "chat-session-1"
  ],
  "limit": 20
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "chat_session_uid": "chat-session-1",
      "sequence": 42,
      "sender_kind": "user",
      "sender_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "sender_name": "小明",
      "message_at": 1700001000000,
      "matched_fields": [
        "body"
      ],
      "snippet": "周五下午三点同步进度"
    }
  ],
  "has_more": false
}

query_chat_messages

读取已知会话在指定时间范围内的消息；可按人物筛选。每组 messages 的 sender_index 指向同组 senders；继续翻页时原样使用 next_page_cursor。

参数

枚举值说明

arguments 示例

{
  "chat_session_uids": [
    "chat-session-1"
  ],
  "start_at": 1700000000000,
  "end_at": 1700086400000,
  "order": "session_time_asc",
  "limit": 100
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "chat_session_uid": "chat-session-1",
      "senders": [
        {
          "sender_kind": "user",
          "sender_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
          "sender_name": "小明"
        }
      ],
      "messages": [
        {
          "sequence": 42,
          "sender_index": 0,
          "message_at": 1700001000000,
          "record_state": "available",
          "text_content": "周五下午三点同步进度"
        }
      ]
    }
  ],
  "has_more": false
}

batch_get_chat_messages

已有 chat_session_uid 与 sequence、需要精确读取消息当前完整文本时调用。lookup_status 与 message.record_state 是不同事实，应分别判断。

参数

arguments 示例

{
  "items": [
    {
      "item_id": "message-1",
      "chat_session_uid": "chat-session-1",
      "sequence": 42
    }
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "item_id": "message-1",
      "lookup_status": "found",
      "message": {
        "chat_session_uid": "chat-session-1",
        "sequence": 42,
        "sender_kind": "user",
        "sender_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
        "sender_name": "小明",
        "message_at": 1700001000000,
        "record_state": "available",
        "record_uid": "record-1",
        "record_version": 1,
        "mutable": true,
        "text_content": "周五下午三点同步进度"
      }
    }
  ]
}

read_chat_message_context

已有同一会话内的 sequence、需要理解其前后内容时调用；sequences 必须属于同一 chat_session_uid，messages 的 sender_index 指向 senders。

参数

arguments 示例

{
  "chat_session_uid": "chat-session-1",
  "sequences": [
    42
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "chat_session_uid": "chat-session-1",
  "senders": [
    {
      "sender_kind": "user",
      "sender_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "sender_name": "小明"
    }
  ],
  "messages": [
    {
      "sequence": 42,
      "sender_index": 0,
      "message_at": 1700001000000,
      "record_state": "available",
      "text_content": "周五下午三点同步进度"
    }
  ],
  "anchor_sequences": [
    42
  ]
}

resolve_chat_targets

按名称或 resolve_people 返回的 user_ref 查询当前可发送的 direct 或 group 会话候选。选定后把候选的 chat_session_uid 交给 send_chat_messages。

参数

枚举值说明

arguments 示例

{
  "items": [
    {
      "item_id": "target-1",
      "target_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "scopes": [
        "private_chat"
      ],
      "limit": 5
    }
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "item_id": "target-1",
      "candidates": [
        {
          "chat_session_uid": "chat-session-1",
          "kind": "direct",
          "scopes": [
            "private_chat"
          ],
          "display_name": "小明",
          "participant_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
        }
      ],
      "has_more": false
    }
  ]
}

create_private_chats

用户明确要求联系指定真人时，创建或取得双方唯一私聊。输入公开用户引用；不加联系人、不发送消息、不打开 UI。Bot 专属会话由 Bot 工具定位。

参数

arguments 示例

{
  "items": [
    {
      "item_id": "one",
      "target_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "idempotency_key": "private-1"
    }
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "item_id": "one",
      "target_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "chat_session_uid": "chat-1",
      "status": "succeeded"
    }
  ]
}

send_chat_messages

用户明确要求发送消息且目标已由 resolve_chat_targets 确认后调用。每项使用独立 idempotency_key；结果未知时只可用完全相同的参数重试。

参数

arguments 示例

{
  "items": [
    {
      "item_id": "message-1",
      "idempotency_key": "send.project-sync.001",
      "chat_session_uid": "chat-session-1",
      "text_content": "周五下午三点同步进度",
      "send_at": 1700001000000
    }
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "item_id": "message-1",
      "chat_session_uid": "chat-session-1",
      "record_uid": "record-1",
      "sequence": 42,
      "target_kind": "direct",
      "target_name": "小明"
    }
  ]
}

query_group_message_moderation_targets

当前有效群主按真人发送者和可选时间分页读取消息坐标与治理状态，不返回正文；空页仍检查 has_more。upper_sequence 是扫描上界，不是快照。

参数

arguments 示例

{
  "chat_session_uid": "019d8590-ebb4-7232-90f2-000000000481",
  "sender_user_refs": [
    "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
  ],
  "limit": 100
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "sequence": 1201,
      "sender_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "message_at": 1700000000000,
      "withdrawal_state": "active",
      "eligible": true
    }
  ],
  "upper_sequence": 1201,
  "has_more": false
}

withdraw_group_messages

用户明确要求撤回他人群消息时，直接传 chat_session_uid 与 sequence；不要求额外解析。原群时间线与群内搜索不再展示；本人个人搜索保留记录且不展示该群来源。不删除原始记录，不移出发送者。结果未知时同参数重试。

参数

arguments 示例

{
  "items": [
    {
      "item_id": "message-1",
      "chat_session_uid": "019d8590-ebb4-7232-90f2-000000000481",
      "sequence": 1201
    }
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "item_id": "message-1",
      "chat_session_uid": "019d8590-ebb4-7232-90f2-000000000481",
      "sequence": 1201,
      "status": "succeeded",
      "changed": true,
      "withdrawn_at": 1700000100000
    }
  ]
}

batch_get_group_members

当前有效群主按已知 user_ref 精确读取当前或历史成员状态；已知必要事实时无需重复读取。

参数

arguments 示例

{
  "items": [
    {
      "item_id": "member-1",
      "chat_session_uid": "019d8590-ebb4-7232-90f2-000000000481",
      "target_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
    }
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "item_id": "member-1",
      "chat_session_uid": "019d8590-ebb4-7232-90f2-000000000481",
      "target_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "found": true,
      "member": {
        "membership_status": "removed",
        "role": "participant",
        "joined_at": 1700000000000,
        "join_restricted": true
      }
    }
  ]
}

remove_group_members

用户明确要求移出时使用；prevent_rejoin=true 原子移出并限制，false 不解除已有限制。结果未知时先核对当前成员状态；重新入群后需重新确认操作意图。

参数

arguments 示例

{
  "items": [
    {
      "item_id": "member-1",
      "chat_session_uid": "019d8590-ebb4-7232-90f2-000000000481",
      "target_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "prevent_rejoin": true
    }
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "item_id": "member-1",
      "chat_session_uid": "019d8590-ebb4-7232-90f2-000000000481",
      "target_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "status": "succeeded",
      "member": {
        "membership_status": "removed",
        "role": "participant",
        "joined_at": 1700000000000,
        "join_restricted": true
      }
    }
  ]
}

set_group_join_restrictions

用户明确要求时设置 restricted=true 或解除 false；既不移出当前成员，也不自动拉人入群。结果未知时核对当前限制状态。

参数

arguments 示例

{
  "items": [
    {
      "item_id": "member-1",
      "chat_session_uid": "019d8590-ebb4-7232-90f2-000000000481",
      "target_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "restricted": true
    }
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "item_id": "member-1",
      "chat_session_uid": "019d8590-ebb4-7232-90f2-000000000481",
      "target_user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "status": "succeeded",
      "member": {
        "membership_status": "removed",
        "role": "participant",
        "joined_at": 1700000000000,
        "join_restricted": true
      }
    }
  ]
}

list_group_join_restrictions

当前有效群主分页读取受限制人物的 user_ref 和限制设置时间。已知目标时可直接调用设置能力。

参数

arguments 示例

{
  "chat_session_uid": "019d8590-ebb4-7232-90f2-000000000481",
  "limit": 30
}

返回字段

structuredContent 示例

{
  "items": [
    {
      "user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "display_name": "群内小王",
      "restricted_at": 1700000100000
    }
  ],
  "has_more": false
}

微信导入

query_wechat_import_conversations

分页浏览导入的微信私聊或群聊；已确认账号可传 participant_user_ref 查询已绑定的私聊，无绑定返回空，可再按微信名称解析候选。取得 conversation_uid 后读取消息或群成员。时间条件只筛选最新消息时间；查某段时间的全部历史消息时应不带时间条件枚举会话，再按消息时间查询。

参数

arguments 示例

{
  "start_at": 1700000000000,
  "end_at": 1700086400000,
  "limit": 20
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "conversation_uid": "wechat-session-1",
      "kind": "group",
      "display_name": "项目讨论群",
      "message_count": 328,
      "voice_count": 12,
      "image_count": 24,
      "emoji_count": 8,
      "video_count": 2,
      "first_sent_at": 1699000000000,
      "last_sent_at": 1700001000000,
      "imported_at": 1700080000000,
      "version": 1700080000000
    }
  ],
  "has_more": false
}

resolve_wechat_import_conversations

用户按微信备注名、昵称或群名指定对话时，先取 conversation_uid 候选再读消息。kind 可限定 direct 或 group。不得把名称认定为即我账号绑定；has_more 为 true 时继续扫描，不能仅凭本页判断唯一或不存在。

参数

枚举值说明

arguments 示例

{
  "items": [
    {
      "item_id": "wechat-1",
      "query": "项目群",
      "kind": "group",
      "limit": 5
    }
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "item_id": "wechat-1",
      "candidates": [
        {
          "conversation_uid": "wechat-conversation-1",
          "kind": "group",
          "display_name": "项目群"
        }
      ],
      "has_more": false
    }
  ]
}

batch_get_wechat_import_conversations

已有 conversation_uid、需要确认会话仍可见并读取当前统计和展示快照时调用。

参数

arguments 示例

{
  "conversation_uids": [
    "wechat-session-1"
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "conversation_uid": "wechat-session-1",
      "found": true,
      "conversation": {
        "conversation_uid": "wechat-session-1",
        "kind": "group",
        "display_name": "项目讨论群",
        "message_count": 328,
        "voice_count": 12,
        "image_count": 24,
        "emoji_count": 8,
        "video_count": 2,
        "first_sent_at": 1699000000000,
        "last_sent_at": 1700001000000,
        "imported_at": 1700080000000,
        "version": 1700080000000
      }
    }
  ]
}

query_wechat_import_messages

已有微信导入 conversation_uid、需要按时间或类型读取消息时调用。sender_index 指向本页 senders。

参数

枚举值说明

arguments 示例

{
  "conversation_uid": "wechat-session-1",
  "kinds": [
    "text",
    "voice"
  ],
  "limit": 20
}

返回字段

枚举值说明

structuredContent 示例

{
  "conversation_uid": "wechat-session-1",
  "found": true,
  "senders": [
    {
      "display_name": "小明",
      "is_self": false
    }
  ],
  "items": [
    {
      "message_uid": "64b64c2f9b8c1a2d3e4f5679",
      "sender_index": 0,
      "sent_at": 1700001000000,
      "kind": "text",
      "text_content": "周五同步项目进度",
      "content_truncated": false,
      "has_media": false
    }
  ],
  "has_more": false
}

batch_get_wechat_import_messages

已有 message_uid、需要精确取得当前正文、发送人和媒体元数据时调用；不会返回媒体存储路径。

参数

arguments 示例

{
  "message_uids": [
    "64b64c2f9b8c1a2d3e4f5679"
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "message_uid": "64b64c2f9b8c1a2d3e4f5679",
      "found": true,
      "message": {
        "message_uid": "64b64c2f9b8c1a2d3e4f5679",
        "conversation_uid": "wechat-session-1",
        "sender": {
          "display_name": "小明",
          "is_self": false
        },
        "sent_at": 1700001000000,
        "kind": "text",
        "text_content": "周五同步项目进度",
        "content_truncated": false,
        "has_media": false
      }
    }
  ]
}

list_wechat_group_members

已有群聊 conversation_uid 时分页读取导入快照中的当前群成员，先判断 roster_state；不是微信实时成员或历史发言人集合。

参数

arguments 示例

{
  "conversation_uid": "wechat-session-1",
  "limit": 20
}

返回字段

枚举值说明

structuredContent 示例

{
  "conversation_uid": "wechat-session-1",
  "roster_state": "available",
  "items": [
    {
      "display_name": "小明",
      "is_friend": true,
      "is_self": false
    }
  ],
  "has_more": false
}

录音

query_recordings

按时间及已确认说话人查录音，人物条件取并集。最新用 order=desc，最早用 asc，可设 limit=1；按录音开始时间排序。空页仍检查 has_more。用 recording_uid 按需读转写，不搜索正文。

参数

枚举值说明

arguments 示例

{
  "start_at": 1700000000000,
  "end_at": 1700086400000,
  "limit": 20
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "recording_uid": "64b64c2f9b8c1a2d3e4f5678",
      "name": "项目访谈",
      "start_at": 1700001000000,
      "end_at": 1700002800000,
      "duration_ms": 1800000,
      "source": "long",
      "ingest_origin": "user_client",
      "sealed": true,
      "transcript_state": "ready",
      "version": 2
    }
  ],
  "has_more": false
}

resolve_recording_speakers

用户指定录音中的标记人但没有已确认 user_ref 时，按名称取得 speaker_uid 候选。不得合并同名标记；has_more 为 true 时继续扫描，不能仅凭本页判断唯一或不存在。选定后用 query_recordings，再读转写。

参数

arguments 示例

{
  "items": [
    {
      "item_id": "speaker-1",
      "query": "张三",
      "limit": 5
    }
  ]
}

返回字段

structuredContent 示例

{
  "items": [
    {
      "item_id": "speaker-1",
      "candidates": [
        {
          "speaker_uid": "64b64c2f9b8c1a2d3e4f5679",
          "display_name": "张三"
        }
      ],
      "has_more": false
    }
  ]
}

batch_get_recordings

已有 recording_uid、需要确认录音是否仍可见并读取当前元数据或转写状态时调用。

参数

arguments 示例

{
  "recording_uids": [
    "64b64c2f9b8c1a2d3e4f5678"
  ]
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "recording_uid": "64b64c2f9b8c1a2d3e4f5678",
      "found": true,
      "recording": {
        "recording_uid": "64b64c2f9b8c1a2d3e4f5678",
        "name": "项目访谈",
        "start_at": 1700001000000,
        "end_at": 1700002800000,
        "duration_ms": 1800000,
        "source": "long",
        "ingest_origin": "user_client",
        "sealed": true,
        "transcript_state": "ready",
        "version": 2
      }
    }
  ]
}

query_recording_transcript

已有 recording_uid 时可直接分页读取正文，无须先读概览或业务总结；需要限定时段时显式传入时间窗，不继承列表筛选。核对完整原话可用 text_mode=full 按字符坐标续读；speaker_index 仅指向本页 speakers。完整性需结合 transcript_state 和 truncated 判断。

参数

枚举值说明

arguments 示例

{
  "recording_uid": "64b64c2f9b8c1a2d3e4f5678",
  "start_at": 1700001000000,
  "end_at": 1700002800000,
  "text_mode": "full",
  "limit": 100
}

返回字段

枚举值说明

structuredContent 示例

{
  "recording_uid": "64b64c2f9b8c1a2d3e4f5678",
  "found": true,
  "transcript_state": "ready",
  "speakers": [
    {
      "kind": "user",
      "display_name": "我",
      "user_ref": "usr_v1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
    }
  ],
  "utterances": [
    {
      "start_offset_ms": 1000,
      "end_offset_ms": 3200,
      "speaker_index": 0,
      "text": "我们先确认下周的计划",
      "truncated": false,
      "utterance_index": 0,
      "text_start_offset": 0,
      "text_end_offset": 10,
      "text_total_length": 10
    }
  ],
  "has_more": false
}

query_recording_summaries

需要参考某个时段的录音自动总结时，查询已保存的日总结和时间线版本；不触发生成。按需选取 summary_uid，用 read_recording_summary 读取正文。

参数

枚举值说明

arguments 示例

{
  "start_at": 1699977600000,
  "end_at": 1700064000000,
  "limit": 20
}

返回字段

枚举值说明

structuredContent 示例

{
  "items": [
    {
      "summary_uid": "64b64c2f9b8c1a2d3e4f5681",
      "kind": "daily_summary",
      "content_origin": "business_recording_summary",
      "generation_state": "completed",
      "start_at": 1699977600000,
      "end_at": 1700064000000,
      "day_start_at": 1699977600000,
      "created_at": 1700064000000,
      "updated_at": 1700064100000
    }
  ],
  "has_more": false
}

read_recording_summary

已有 summary_uid 时直接读取原文。先检查 found 和 content_state；ready 时按游标续读，JSON 须拼齐后解析。内容为自动总结，核对原话时读取录音转写。

参数

arguments 示例

{
  "summary_uid": "64b64c2f9b8c1a2d3e4f5681",
  "limit": 10000
}

返回字段

枚举值说明

structuredContent 示例

{
  "summary_uid": "64b64c2f9b8c1a2d3e4f5681",
  "found": true,
  "summary": {
    "summary_uid": "64b64c2f9b8c1a2d3e4f5681",
    "kind": "daily_summary",
    "content_origin": "business_recording_summary",
    "generation_state": "completed",
    "start_at": 1699977600000,
    "end_at": 1700064000000,
    "day_start_at": 1699977600000,
    "created_at": 1700064000000,
    "updated_at": 1700064100000
  },
  "content_state": "ready",
  "format": "markdown",
  "text": "确认下周计划",
  "text_start_offset": 0,
  "text_end_offset": 6,
  "text_total_length": 6,
  "has_more": false
}

通话

query_calls

需要按时间、方向、接通结果、会话或人物浏览通话时调用；该工具不做关键词搜索。

参数

枚举值说明

arguments 示例

{
  "start_at": 1700000000000,
  "end_at": 1700086400000,
  "directions": [
    "outgoing"
  ],
  "limit": 20
}

返回字段

枚举值说明