Wps Collab

金山协作 SKILL

快速开始

import sys, os
sys.path.insert(0, os.path.join(os.getenv('SKILL_PATH'), 'wps-collab', 'scripts'))
import wps_collab

start_time / end_time 参数统一接受 ISO 字符串（如 "2026-03-23T00:00:00+08:00"）。

聊天

wps_collab.im_recent_chats(page_size=50, filter_unread=False, filter_mention_me=False, page_token=None, start_time=None, end_time=None)

获取最近会话列表（含未读数）

返回值

{
    "success": True/False,
    "data": {
        "chats": [
            {"id": "会话ID", "name": "会话名称", "type": "p2p/group", "unread_count": 0}
        ],
        "count": 3,
        "total_unread": 5,
        "next_page_token": ""
    },
    "message": "获取到 3 个会话，共 5 条未读"
}

调用示例

result = wps_collab.im_recent_chats(filter_unread=True)
print(result)

wps_collab.im_get_history(chat_id, page_size=20, page_token=None, start_time=None, end_time=None)

获取指定会话历史消息

返回值

{
    "success": True/False,
    "data": {
        "messages": [{"id": "消息ID", "text": "[2026-03-23 10:00:00] 张三: 你好"}],
        "count": 20,
        "next_page_token": ""
    },
    "message": "获取到 20 条消息"
}

调用示例

result = wps_collab.im_get_history(chat_id="oc_xxx", page_size=20, start_time="2026-03-23T00:00:00+08:00")
print(result)

wps_collab.im_get_chat_members(chat_id)

获取指定会话的全部成员列表

返回值

{
    "success": True/False,
    "data": {
        "members": [{"id": "用户ID", "name": "张三"}],
        "count": 5
    },
    "message": "获取到 5 位成员"
}

调用示例

result = wps_collab.im_get_chat_members(chat_id="xxx")
print(result)

wps_collab.im_recall(chat_id, message_id)

撤回指定会话中的某条消息

返回值

{
    "success": True/False,
    "message": "消息撤回成功",
    "error": "错误信息（成功时不含此字段）"
}

调用示例

result = wps_collab.im_recall(chat_id="xxx", message_id="yyy")
print(result)

wps_collab.im_send_me(promo_text, text=None, file_id=None, image_paths=None, blocks=None)

向当前登录用户自己发送消息

返回值

{
    "success": True/False,
    "message": "消息发送成功",
    "preview": "发送内容的前200个字符（成功时返回）",
    "saved_path": "完整内容保存的本地文件路径（仅当内容超过200字符时返回）",
    "error": "错误信息（成功时不含此字段）"
}

调用示例

result = wps_collab.im_send_me(promo_text="", text="给自己的备忘")
print(result)

wps_collab.im_send(chat_id, promo_text, text=None, file_id=None, mentions=None, image_paths=None, blocks=None)

向指定会话发送消息，支持文本、单/多图片、云文档的自由组合

mentions 位置控制：

• 若 text / blocks 中包含 @用户ID 或 @all / @所有人 占位符，@ 标记会原地替换为有效的 @ 通知（可出现在消息任意位置）
• 若 text / blocks 中不包含占位符，则 @ 标记自动追加到消息末尾
• 占位符中的用户 ID 必须与 mentions 列表中的值一致

注意：使用 promo_text 参数时，若用户未指定消息后缀 / 签名，需读取用户记忆中「# --- 发送消息 ---」下的「用户发消息时常用后缀 / 签名(该字段仅供用户通过协作发送消息时使用)：」字段；若用户主动指定，则需将其更新记录到用户记忆中。

返回值

{
    "success": True/False,
    "message": "消息发送成功",
    "preview": "发送内容的前200个字符（成功时返回）",
    "saved_path": "完整内容保存的本地文件路径（仅当内容超过200字符时返回）",
    "error": "错误信息（成功时不含此字段）"
}

调用示例

# @在末尾
result = wps_collab.im_send(chat_id="oc_xxx", text="你好", mentions=["17650706"], promo_text="")

# @在任意位置（占位符方式）
result = wps_collab.im_send(
    chat_id="oc_xxx",
    text="@17650706 @1714485616 晚上去干嘛",
    mentions=["17650706", "1714485616"],
    promo_text="来自灵犀claw"
)
print(result)

wps_collab.search_chats(page_size, keyword, page_token=None)

按会话名称关键字搜索单聊/群聊

返回值

{
    "success": True/False,
    "data": {
        "items": [{"id": "会话ID", "name": "会话名称"}],
        "count": 2,
        "next_page_token": ""
    },
    "message": "搜索到 2 个会话"
}

调用示例

result = wps_collab.search_chats(page_size=20, keyword="项目讨论")
print(result)

wps_collab.search_messages(page_size, keyword=None, chat_id_list=None, sender_id_list=None, start_time=None, end_time=None, filter_chat_type_list=None, with_sender_details=True, page_token=None)

搜索消息内容（keyword / chat_id_list / sender_id_list / 时间范围 四选一必填）

返回值

{
    "success": True/False,
    "data": {
        "items": [
            {
                "message": {"id": "消息ID", "type": "text/rich_text/...", "content": {...}, "ctime": "发送时间", "sender": {"id": "发送者ID", "name": "发送者姓名", ...}},
                "chat": {"id": "会话ID", "name": "会话名称", "type": "p2p/group"}
            }
        ],
        "count": 5,
        "next_page_token": ""
    },
    "message": "搜索到 5 条消息"
}

调用示例

# 按关键字搜索
result = wps_collab.search_messages(page_size=20, keyword="项目进度")

# 按发送者搜索（"张三发了什么"）
result = wps_collab.search_messages(page_size=20, sender_id_list=["17650706"])

# 组合搜索
result = wps_collab.search_messages(page_size=10, keyword="周报", sender_id_list=["17650706"], filter_chat_type_list=["group"])
print(result)

wps_collab.im_create_chat(account_id_list, chat_type="group", name=None)

创建会话

返回值

{
    "success": True/False,
    "data": {"chat_id": "oc_xxx", "name": "项目讨论群", "type": "group"},
    "message": "会话创建成功"
}

调用示例

result = wps_collab.im_create_chat(
    account_id_list=["111", "222", "333"],
    name="项目讨论群",
)
print(result)

身份

wps_collab.get_me()

获取当前登录用户的完整信息

返回值

{
    "success": True/False,
    "data": {
        "id": "用户ID",
        "user_name": "用户名",
        "name": "姓名",
        "email": "邮箱",
        "phone": "手机号",
        "avatar": "头像URL",
        "dept": {"id": "部门ID", "name": "部门名称"}
    },
    "message": "获取当前用户信息成功"
}

调用示例

result = wps_collab.get_me()
print(result)

wps_collab.get_user(user_id)

获取指定用户详细信息

返回值

{
    "success": True/False,
    "data": {"id": "用户ID", "user_name": "张三", "email": "zhangsan@wps.cn", "phone": "138xxxx"},
    "message": "获取用户信息成功"
}

调用示例

result = wps_collab.get_user(user_id="123456")
print(result)

wps_collab.search_user(keyword, page_size, status=None, page_token=None)

搜索企业用户（按姓名/邮箱/手机/登录名）

返回值

{
    "success": True/False,
    "data": {
        "items": [{"id": "用户ID", "user_name": "张三", "email": "zhangsan@wps.cn", "phone": "138xxxx"}],
        "count": 1,
        "next_page_token": ""
    },
    "message": "搜索到 1 个用户"
}

调用示例

result = wps_collab.search_user(keyword="张三", page_size=20)
print(result)

日程

event_id 从列表结果中获取。

wps_collab.list_events_single_calendar(start_time=None, end_time=None, page_size=None, page_token=None)

查询日历日程列表（区间≤31天）。

返回值

{
    "success": True/False,
    "data": {
        "events": ["[2026-03-01 10:00 ~ 11:00] 团队周会（ID: 125744232，状态: normal）"],
        "count": 5,
        "next_page_token": ""
    },
    "message": "查询到 5 个日程"
}

result = wps_collab.list_events_single_calendar(
    start_time="2026-03-01T00:00:00+08:00",
    end_time="2026-03-31T23:59:59+08:00"
)
print(result)

wps_collab.get_event(event_id)

查询单个日程详情。

返回值

{
    "success": True/False,
    "data": {
        "id": "日程ID",
        "summary": "标题",
        "description": "备注",
        "start_time": "2026-04-01 10:00 (北京时间)",
        "end_time": "2026-04-01 11:00 (北京时间)",
        "organizer_user_id": "...",
        "status": "normal/cancelled",
        "locations": ["会议室名称"],
        "online_meeting_url": "https://...",
        "recurrence": {},
        "recurring_event_id": ""
    },
    "message": "查询日程成功"
}

result = wps_collab.get_event(event_id="125744232")
print(result)

wps_collab.create_event(body=None)

创建日程（仅新建，不处理参与者，邀请参与者须在创建后单独调用 batch_create_event_attendee）。

返回值

{
    "success": True/False,
    "data": {"id": "新日程ID", ...},
    "message": "创建日程成功"
}

result = wps_collab.create_event(body={
    "summary": "团队周会",
    "start_time": {"dateTime": "2026-03-15T10:00:00+08:00"},
    "end_time":   {"dateTime": "2026-03-15T11:00:00+08:00"},
})
print(result)

wps_collab.delete_event(event_id)

删除日程。

返回值

{"success": True/False, "data": {}, "message": "删除日程成功"}

result = wps_collab.delete_event(event_id="125744232")
print(result)

wps_collab.list_event_attendees(event_id, page_size=100, page_token=None)

获取日程参与者列表。

返回值

{
    "success": True/False,
    "data": {
        "attendees": ["张三（已接受）", "李四（未响应）"],
        "count": 2,
        "next_page_token": ""
    },
    "message": "获取到 2 个参与者"
}

result = wps_collab.list_event_attendees(event_id="125744232")
print(result)

wps_collab.batch_create_event_attendee(event_id, attendees)

向已有日程批量添加参与者。

返回值

{
    "success": True/False,
    "data": {"items": [{"id": "...", "user_id": "...", "name": "...", "response_status": "not_responded"}]},
    "message": "添加日程参与者成功"
}

result = wps_collab.batch_create_event_attendee(
    event_id="125744232",
    attendees=[{"type": "user", "user_id": "uid_aaa"}]
)
print(result)

wps_collab.batch_delete_event_attendee(event_id, attendee_ids)

批量删除日程参与者。

返回值

{"success": True/False, "data": {}, "message": "删除日程参与者成功"}

result = wps_collab.batch_delete_event_attendee(
    event_id="125744232",
    attendee_ids=["att_aaa"]
)
print(result)

wps_collab.list_free_busy(start_time, end_time, user_ids)

查询用户忙闲

返回值

{
    "success": True/False,
    "data": {
        "items": [
            {
                "user_id": "用户ID",
                "busy_times": [{"start": "2026-03-15T10:00:00+08:00", "end": "2026-03-15T11:00:00+08:00"}]
            }
        ]
    },
    "message": "查询忙闲成功"
}

result = wps_collab.list_free_busy(
    start_time="2026-03-15T09:00:00+08:00",
    end_time="2026-03-15T18:00:00+08:00",
    user_ids=["uid_aaa", "uid_bbb"]
)
print(result)

邮件

wps_collab.list_mail_messages_in_folder(page_size, start_time=None, end_time=None, page_token=None)

获取指定邮箱目录的邮件列表

返回值

{
    "success": True/False,
    "data": {
        "items": [
            {
                "id": "邮件ID",
                "folder_id": "目录ID",
                "subject": "邮件主题",
                "from": {"name": "发件人", "email_address": "xxx@wps.cn"},
                "is_read": True,
                "ctime": "发送时间",
                "has_attachments": False,
                "body_preview": "正文预览"
            }
        ],
        "count": 10,
        "next_page_token": ""
    },
    "message": "获取到 10 封邮件"
}

调用示例

result = wps_collab.list_mail_messages_in_folder(page_size=20)
print(result)

wps_collab.get_mail_message(message_id)

获取指定邮件完整内容

返回值

{
    "success": True/False,
    "data": {
        "body_text": "纯文本正文（推荐用此字段，body 字段为原始 HTML）",
        "subject": "邮件主题",
        "from": {"name": "发件人", "email_address": "xxx@wps.cn"},
        "to_recipients": [{"name": "收件人", "email_address": "..."}],
        "ctime": "发送时间",
        "attachments": []
    },
    "message": "获取邮件成功"
}

调用示例

result = wps_collab.get_mail_message(message_id="msg_xxx")
print(result)

wps_collab.search_mail_messages(keyword, type_, start_time=None, end_time=None, page_size=None, page_token=None)

搜索邮件

返回值

{
    "success": True/False,
    "data": {
        "items": [{"id": "邮件ID", "folder_id": "...", "subject": "主题", "from": {...}, "is_read": True, "ctime": "...", "has_attachments": False, "body_preview": "..."}],
        "count": 5,
        "next_page_token": ""
    },
    "message": "搜索到 5 封邮件"
}

调用示例

result = wps_collab.search_mail_messages(keyword="绩效考核", type_="subject")
print(result)

wps_collab.send_mail(subject, to_recipients, body, cc_recipients=None, bcc_recipients=None,attachment_files=None, attachment_urls=None)

发送邮件

不可重复调用：若返回"草稿已创建但发送失败"，请重试发送，切勿重新调用 send_mail()。

返回值

{
    "success": True/False,
    "data": {"message_id": "已发送邮件ID"},
    "message": "邮件发送成功",
    "error": "错误描述（失败时含此字段）"
}

调用示例

result = wps_collab.send_mail(
    subject="邮件主题",
    to_recipients=[{"name": "张三", "email_address": "zhangsan@wps.cn"}],
    body="正文内容",
    attachment_files=["/tmp/report.pdf"]
)
print(result)

AI 知识库

wps_collab.recall_rank(query, topk=5, start_time=None, end_time=None)

在全部可访问知识库中按问题召回相关文档片段。

返回值

{
    "success": True/False,
    "data": {
        "chunks": [
            {
                "file_name": "文件名",
                "ref_score": 0.9123,
                "content": "召回片段正文（最长 500 字符）",
                "link_url": "https://365.kdocs.cn/l/xxx",
                "file_id": "末段文件ID"
            }
        ],
        "count": 3,
        "scanned_drives": 50,
        "failed_batches": 2
    },
    "message": "召回到 3 条片段（共扫描 50 个知识库，2 个批次失败跳过）"
}

调用示例

result = wps_collab.recall_rank(
    "产品发布流程",
    topk=5,
    start_time="2025-01-01T00:00:00+08:00",
    end_time="2026-04-01T00:00:00+08:00",
)
print(result)

会议纪要

wps_collab.get_meeting_summary(event_id)

获取指定日程对应会议的 AI 总结详情

返回值

{
    "success": True/False,
    "data": {
        "title": "会议标题",
        "content": "发言人A: 内容...",    # 最多 1000 字符
        "saved_path": "/path/to/file.md"  # 仅内容超 1000 字符时存在
    },
    "message": "获取会议「xxx」AI 总结成功"
}

调用示例

result = wps_collab.get_meeting_summary(event_id="127181701")
print(result)

错误处理