DooTask Tools

一个用于与 DooTask 系统交互的 Python 客户端库，提供了完整的 API 封装和类型支持。支持用户管理、消息通信、项目管理、任务协作等功能。

安装

pip install dootask-tools

快速开始

from dootask import DooTaskClient

# 创建客户端
client = DooTaskClient(
    token="your_token_here",
    # server="https://your-dootask-server.com",  # 不传时默认 http://nginx
    timeout=30,
)

# 获取用户信息
user = client.get_user_info()
print(f"用户: {user.nickname}")

说明：server 参数默认值为 http://nginx，一般用于在 Docker / K8s 等环境中通过服务名 nginx 访问 DooTask 主程序，在这种部署方式下生产环境可以不显式传入 server。

主要功能示例

发送消息

from dootask import SendMessageRequest, SendMessageToUserRequest

# 发送消息到指定对话
client.send_message(SendMessageRequest(
    dialog_id=123,
    text="Hello, World!",
    text_type="md"
))

# 发送消息到用户
client.send_message_to_user(SendMessageToUserRequest(
    userid=456,
    text="私信内容",
    text_type="md"
))

项目和任务管理

from dootask import CreateProjectRequest, CreateTaskRequest, UpdateTaskRequest

# 创建项目
project = client.create_project(CreateProjectRequest(
    name="新项目",
    desc="项目描述",
    columns="待办,进行中,已完成"
))

# 创建任务
task = client.create_task(CreateTaskRequest(
    project_id=project.id,
    name="新任务",
    content="任务内容",
    owner=[123]
))

# 更新任务
updated_task = client.update_task(UpdateTaskRequest(
    task_id=task.id,
    name="更新后的任务名",
    content="更新后的内容"
))

群组管理

from dootask import CreateGroupRequest, AddGroupUserRequest

# 创建群组
group = client.create_group(CreateGroupRequest(
    chat_name="新群组",
    userids=[123, 456, 789]
))

# 添加群成员
client.add_group_user(AddGroupUserRequest(
    dialog_id=group.id,
    userids=[999]
))

应用菜单角标

from dootask import DooTaskClient

# appid/secret 缺省取环境变量 APP_ID / APP_SECRET（插件容器内置），也可显式传入
client = DooTaskClient(token="YOUR_TOKEN", appid="APP_ID", secret="APP_SECRET")

# 给单个用户的第一个菜单设置数字角标
client.set_app_badge(123, count=5)

# 给多个用户的指定菜单设置小红点
client.set_app_badge([123, 456], dot=True, menu_key="tasks")

# 清除角标（count=0 且 dot=False）
client.set_app_badge(123, menu_key="tasks")

API 方法列表

基础方法

用户相关接口

机器人相关接口

消息相关接口

对话相关接口

群组相关接口

项目管理相关接口

任务列表相关接口

任务相关接口

系统相关接口

应用角标相关接口

主要数据类型

基础类型

• Response[T] - 基础响应结构
• ResponsePaginate[T] - 分页响应结构

用户相关

• UserInfo - 用户信息
• UserBasic - 用户基础信息
• Department - 部门信息

消息相关

• SendMessageRequest - 发送消息请求
• DialogMessage - 对话消息
• DialogMessageListResponse - 消息列表响应
• MessageSearchItem - 消息搜索结果项
• TodoItem - 消息待办记录

对话相关

• DialogInfo - 对话信息
• DialogMember - 对话成员

项目和任务相关

• Project - 项目信息
• ProjectColumn - 项目列表
• ProjectTask - 项目任务
• TaskFile - 任务文件
• TaskContent - 任务内容

系统相关

• SystemSettings - 系统设置
• VersionInfo - 版本信息

异常处理

from dootask import (
    DooTaskException,
    DooTaskAPIException,
    DooTaskHTTPException,
    DooTaskAuthException,
    DooTaskPermissionException
)

try:
    user = client.get_user_info()
except DooTaskAuthException:
    print("认证失败，请检查 token")
except DooTaskPermissionException:
    print("权限不足")
except DooTaskAPIException as e:
    print(f"API 错误: {e}")
except DooTaskHTTPException as e:
    print(f"网络错误: {e}")
except DooTaskException as e:
    print(f"其他错误: {e}")

缓存机制

客户端内置用户信息缓存机制，默认缓存时间为10分钟：

# 强制刷新缓存
user = client.get_user_info(no_cache=True)

# 使用缓存（默认）
user = client.get_user_info()

许可证

MIT License