dingtalk-teambition

name	dingtalk-teambition
description	Use for anything related to Teambition tasks and projects. Triggers on: checking my todos, what tasks are due today or this week, create a task, update task status or priority or assignee or note, mark task as done, query overdue tasks, search tasks by keyword, view task details, upload file to task, check team members, query project list, add task comment with @mention, track task progress. NOT for: non-Teambition platforms or Git operations.
version	1.0.0
metadata	{"openclaw":{"requires":{"bins":"[Truncated]"},"primaryEnv":"TEAMBITION_USER_TOKEN","install":["[Truncated]","[Truncated]"]}}

适用场景

✅ 适合使用本技能：

• 查询我的待办任务、今天/本周到期的任务、逾期任务
• 创建、更新、归档任务
• 更新任务状态、优先级、执行人、备注
• 管理任务进展、评论（支持 @提及）、动态
• 上传文件到任务
• 查询项目列表、项目详情
• 查询企业成员
• 管理迭代（创建/开始/完成）

❌ 不适用场景：

• 操作非 Teambition 平台（Jira、Asana 等）
• Git 操作或代码管理 → 直接使用 git
• 管理脚本未覆盖的 Teambition 组织/管理员设置

---

环境准备

获取 User Token：Teambition UserToken自助申请

# 方式 1：环境变量
export TEAMBITION_USER_TOKEN="your_token"

# 方式 2：在 dingtalk-teambition/ 目录下创建 user-token.json
# {"userToken": "your_token"}

cd dingtalk-teambition && uv sync

---

核心规则

1. me()：TQL 中查询"我的"任务/项目，必须用 executorId = me()，禁止硬编码用户 ID

2. 时区：create_task.py / update_task.py / manage_sprint.py 已内置东八区→UTC 转换，直接传本地时间即可；不要手动传 UTC 时间（会被再次转换导致偏差）。转换逻辑参考：

   from datetime import datetime, timedelta
   user_date = "2026-03-15"
   dt = datetime.strptime(user_date, "%Y-%m-%d") - timedelta(hours=8)
   iso_date = dt.strftime("%Y-%m-%dT%H:%M:%S.000Z")
   # 结果：2026-03-14T16:00:00.000Z
   

3. ID→名称：API 返回的各类 ID 字段均为原始 ID 字符串，展示给用户前必须转换为可读名称，禁止直接展示原始 ID。

   • 需要转换的常见 ID 字段：

     字段	含义	转换方式
     executorId	执行人	query_members.py --user-ids <ID> 批量查询
     creatorId	创建人	query_members.py --user-ids <ID> 批量查询
     involveMembers	参与人列表	query_members.py --user-ids <ID1,ID2,...> 批量查询
     sprintId	所属迭代	query_project_detail.py <projectId> 获取迭代列表后匹配
     stageId	所属任务列	任务详情中通常包含 stageName，否则需查项目工作流
     projectId	所属项目	项目名通常已在上下文中，或用 query_project_detail.py 查询
     parentTaskId	父任务	query_task_detail.py <parentTaskId> 获取父任务标题

   • 展示任务列表/详情时的必要步骤：
     1. 收集所有任务中出现的各类 ID（去重）
     2. 批量查询对应的名称（人员用 query_members.py，项目/迭代/任务用各自的查询脚本）
     3. 将 ID 替换为名称后再向用户展示
   • 如果无法确定某个 ID 对应的名称，可展示为"未知"或保留该字段不展示，不要直接展示原始 ID

---

脚本速查

脚本	用途	关键参数
query_tasks.py	查询任务列表（TQL），默认返回：标题、状态、优先级、执行人ID、截止时间、备注、迭代、任务列、开始时间、进度、父任务ID	--tql <TQL> --page-size N --page-token T --no-details --extra-fields f1,f2
query_task_detail.py <id1,id2>	查询任务详情（支持批量）	--detail-level simple|detailed --extra-fields f1,f2
create_task.py	创建任务	--title <标题>（必需）--project-id --executor-id --due-date --priority
update_task.py	更新任务（多字段并行）	--task-id <id>（必需）--title --executor-id --due-date --note --priority --taskflowstatus-id
update_task_priority.py	单独更新优先级（更新前必须先用 get_priority_list.py 查企业配置）	--task-id <id> --priority <0-3>
create_comment.py	创建评论（支持直接上传文件）	--task-id <id> --content <内容> --mention <姓名> --mention-id <userId> --file-paths <路径> --file-tokens <token>
query_projects.py	查询项目列表（TQL）	--tql <TQL> --page-size N --page-token T --no-details --include-template
query_project_detail.py <id>	查询项目详情（支持批量）	--detail-level simple|detailed --extra-fields f1,f2
query_members.py	搜索成员（支持批量ID查询）	--keyword <姓名>

query_task_detail.py 参数说明

参数	类型	必需	说明
任务ID	字符串	是	任务 ID，逗号分隔支持批量
--detail-level	字符串	否	simple（默认）或 detailed
--extra-fields	字符串	否	simple 模式下额外包含的字段，逗号分隔

simple（默认） 包含字段：

字段	说明
id	任务 ID
content	任务标题
isDone	是否完成
executorId	执行人 ID
projectId	项目 ID
dueDate	截止时间
priority	优先级（0=紧急，1=高，2=中，3=低）
created	创建时间
updated	更新时间
note	备注

detailed 额外包含：sprintId（迭代 ID）stageId（任务列 ID）startDate（开始时间）progress（进度）parentTaskId（父任务 ID）及自定义字段等 30+ 字段

query_project_detail.py 参数说明

参数	类型	必需	说明
项目ID	字符串	是	项目 ID，逗号分隔支持批量
--detail-level	字符串	否	simple（默认）或 detailed
--extra-fields	字符串	否	simple 模式下额外包含的字段，逗号分隔

simple（默认） 包含字段：

字段	说明
id	项目 ID
name	项目名称
description	项目描述
visibility	可见性（public/private）
isTemplate	是否是模板项目
creatorId	创建人 ID
isArchived	是否在回收站
isSuspended	是否已归档
created	创建时间
updated	更新时间

detailed 额外包含：logo（项目 LOGO）organizationId（企业 ID）uniqueIdPrefix（任务 ID 前缀）startDate（开始时间）endDate（结束时间）等 20+ 字段

---

TQL 快速参考

任务 TQL 常用场景

场景	TQL
我的待办任务	executorId = me() AND isDone = false
我的逾期任务	executorId = me() AND isDone = false AND dueDate < startOf(d)
今天截止的任务	executorId = me() AND dueDate >= startOf(d) AND dueDate <= endOf(d)
本周截止的任务	executorId = me() AND dueDate >= startOf(w) AND dueDate <= endOf(w)
即将逾期（未来3天）	executorId = me() AND isDone = false AND dueDate >= startOf(d) AND dueDate <= endOf(d, 3d)
过去7天更新的任务	executorId = me() AND updated >= startOf(d, -7d)
高优先级未完成	priority = 0 AND isDone = false
标题模糊搜索	title ~ '关键词'
全文搜索（标题+备注）	text ~ '关键词'
指定项目的任务	projectId = 'xxx'

完整 TQL 语法（字段、运算符、时间函数）→ references/tql.md

项目 TQL 常用场景

场景	TQL
我参与的项目	involveMembers = me()
我创建的项目	creatorId = me()
按名称搜索	nameText ~ '关键词'
已归档的项目	isSuspended = true
今天更新的项目	updated >= startOf(d) AND updated <= endOf(d)
今天创建的项目	created >= startOf(d) AND created <= endOf(d)
本周创建的项目	created >= startOf(w) AND created <= endOf(w)
本月创建的项目	created >= startOf(M) AND created <= endOf(M)
过去7天创建的项目	created >= startOf(d, -7d)
指定日期范围创建	created >= '2026-03-01T00:00:00.000Z' AND created <= '2026-03-31T23:59:59.999Z'

⚠️ 项目没有截止时间（dueDate）字段，只有 created 和 updated。

完整项目 TQL → references/project-tql.md

---

常用命令示例

查询任务

# 我的待办任务
uv run scripts/query_tasks.py --tql "executorId = me() AND isDone = false"
# 注意：返回的 executorId 是原始 ID，需批量调用 query_members.py --user-ids 转换为姓名后展示

# 我的逾期任务，按截止时间升序
uv run scripts/query_tasks.py --tql "executorId = me() AND isDone = false AND dueDate < startOf(d) ORDER BY dueDate ASC"
# 返回的 executorId 需批量转换为姓名：uv run scripts/query_members.py --user-ids "<id1,id2,...>"

# 本周截止的任务
uv run scripts/query_tasks.py --tql "executorId = me() AND dueDate >= startOf(w) AND dueDate <= endOf(w)"

# 标题搜索
uv run scripts/query_tasks.py --tql "title ~ '需求'"

# 查询任务详情（simple 默认，含 note）
uv run scripts/query_task_detail.py <taskId>

# 查询详细信息（含自定义字段等）
uv run scripts/query_task_detail.py <taskId> --detail-level detailed

# 批量查询多个任务
uv run scripts/query_task_detail.py id1,id2,id3

创建任务

# 基本创建
uv run scripts/create_task.py --project-id 'xxx' --title '完成需求文档'

# 完整参数创建
uv run scripts/create_task.py \
  --project-id 'xxx' \
  --title '实现登录模块' \
  --executor-id 'uid' \
  --due-date '2026-04-01' \
  --priority 1 \
  --note '参考设计稿'

更新任务

# 更新标题和优先级（多字段并行执行）
uv run scripts/update_task.py --task-id 'xxx' --title '新标题' --priority 0

# 更新截止日期和执行人
uv run scripts/update_task.py --task-id 'xxx' --due-date '2026-04-01' --executor-id 'uid'

# 更新任务状态（先查询状态 ID）
uv run scripts/get_task_statuses.py <taskId>
uv run scripts/update_task.py --task-id 'xxx' --taskflowstatus-id '状态ID'

# 单独更新优先级
uv run scripts/update_task_priority.py --task-id 'xxx' --priority 0

查询项目

# 我参与的项目
uv run scripts/query_projects.py --tql "involveMembers = me()"

# 按名称搜索
uv run scripts/query_projects.py --tql "nameText ~ '产品开发'"

# 查询项目详情
uv run scripts/query_project_detail.py <projectId>

# 获取 organizationId（用于查询优先级配置）
uv run scripts/query_project_detail.py <projectId> --extra-fields organizationId

查询成员和当前用户

# 按姓名搜索成员
uv run scripts/query_members.py --keyword '张三'

# 批量按用户ID查询成员（推荐用于ID转换）
uv run scripts/query_members.py --user-ids "id1,id2,id3"

# 获取当前登录用户信息（userId、name、email 等）
uv run scripts/get_current_user.py

创建评论（含 @提及）

# 创建评论并 @张三（--mention 接受姓名，脚本自动查询 userId）
uv run scripts/create_comment.py \
  --task-id 'xxx' \
  --content '请张三确认一下' \
  --mention '张三'

# @多人（逗号分隔）
uv run scripts/create_comment.py \
  --task-id 'xxx' \
  --content '请张三和李四评审' \
  --mention '张三,李四'

# 已知 userId 时可直接用 --mention-id
uv run scripts/create_comment.py \
  --task-id 'xxx' \
  --content '已更新' \
  --mention-id '61cad8021deea2ac89a4cbf3'

带文件创建评论

# 带单个文件创建评论（自动上传并附加）
uv run scripts/create_comment.py \
  --task-id 'xxx' \
  --content '附件请查收' \
  --file-paths '/path/to/doc.pdf'

# 带多个文件创建评论（逗号分隔）
uv run scripts/create_comment.py \
  --task-id 'xxx' \
  --content '附件请查收' \
  --file-paths '/path/a.pdf,/path/b.png'

# 同时使用文件路径和已有 token（混合使用）
uv run scripts/create_comment.py \
  --task-id 'xxx' \
  --content '附件请查收' \
  --file-paths '/path/to/new.pdf' \
  --file-tokens 'existing_token1,existing_token2'

带文件更新文件字段

# 上传单个文件到自定义字段
uv run scripts/upload_file_to_customfield.py \
  --task-id 'xxx' \
  --file-paths '/path/to/document.pdf' \
  --customfield-id 'yyy'

# 上传多个文件到自定义字段（逗号分隔）
uv run scripts/upload_file_to_customfield.py \
  --task-id 'xxx' \
  --file-paths '/path/a.pdf,/path/b.png,/path/c.docx' \
  --customfield-id 'yyy'

---

分页查询

query_tasks.py 和 query_projects.py 均支持分页：

参数	说明
--page-size <N>	每页记录数（默认由 API 决定）
--page-token <T>	传入上次返回的 nextPageToken 获取下一页

# 第一页
uv run scripts/query_tasks.py --tql "executorId = me()" --page-size 50

# 下一页（使用上次输出中的 nextPageToken）
uv run scripts/query_tasks.py --tql "executorId = me()" --page-size 50 --page-token "上次返回的TOKEN"