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":["python3","uv"]},"primaryEnv":"TEAMBITION_USER_TOKEN","install":[{"id":"python-brew","kind":"brew","formula":"python","bins":["python3"],"label":"Install Python (brew)"},{"id":"uv-brew","kind":"brew","formula":"uv","bins":["uv"],"label":"Install uv (brew)"}]}}

适用场景

✅ 适合使用本技能：

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

❌ 不适用场景：

• 操作非 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

   # 按姓名搜索成员，获取 userId
   uv run scripts/query_members.py --keyword "张三"
   # 返回结果中匹配 userId，确认后用于展示或操作
   
   # 批量按用户ID查询成员（推荐用于ID转换）
   uv run scripts/query_members.py --user-ids "id1,id2,id3"
   

4. 优先级：数值含义为 0=紧急 1=高 2=中 3=低，但企业通常会自定义优先级名称，脚本输出的 priorityLabel 仅为系统默认值，不代表该企业的真实配置。

   • 展示优先级名称前必须先查询企业配置，查询链路：
     1. 从任务详情获取 projectId
     2. uv run scripts/query_project_detail.py <projectId> --extra-fields organizationId 获取 organizationId
     3. uv run scripts/get_priority_list.py <organizationId> 获取企业真实优先级列表
   • 返回结果中每条优先级包含 priority（数值）和 name（企业自定义名称），以此覆盖默认 label 后再展示
   • 更新优先级前同样需要先查询，将用户描述的优先级名称与企业配置匹配后，再用对应的 priority 数值调用更新接口

5. 归档 vs 删除：归档任务会移入回收站，不在正常列表显示，可通过 --restore 恢复；归档不等于删除

6. 动态 vs 进展：动态（activity）是系统自动记录的操作历史（状态变更、字段修改等）；进展（trace）是用户手动填写的阶段性状态更新

7. 迭代操作顺序：先用 --action create --project-id <id> --name <名> 创建迭代获取 sprint-id，再用 --action start --project-id <id> --sprint-id <id> 开始，完成后用 --action complete --project-id <id> --sprint-id <id>；start/complete 都需要同时传 --project-id 和 --sprint-id

8. 状态查询优先：更新任务状态时，优先使用 get_task_statuses.py <taskId> 直接查询该任务的工作流状态列表，无需先获取 projectId；只有创建任务需要初始状态时才用 get_taskflow_statuses.py

9. 按需读文档：TQL 语法 → references/tql.md；进展/评论/动态/归档 → references/task-ops.md；错误处理 → references/error-handling.md

10. 带文件创建评论：使用 create_comment.py --file-paths <路径> 直接上传并附加文件到评论，支持多文件（逗号分隔）

11. ID 链接渲染：当回复中涉及任务 ID 或项目 ID 时，必须将其渲染为可点击的链接，格式如下：

    • 任务链接：https://www.teambition.com/task/{taskId}
    • 项目链接：https://www.teambition.com/project/{projectId}

12. 任务的 content = 标题：API 返回的 content 字段就是任务的标题，向用户展示时统一使用"标题"而非"内容"，避免混淆；create_task.py 和 update_task.py 都统一使用 --title 参数

13. 空字段隐藏：展示任务或项目信息时，值为空、null、0、false 或空数组的字段应当隐藏，不向用户展示，只展示有实际值的字段。例如：

    • 进度为 0 → 不展示进度
    • 截止时间为 null → 不展示截止时间
    • 备注为空字符串 → 不展示备注
    • 迭代为 null → 不展示迭代
    • 标签为空数组 → 不展示标签
    • 此规则适用于所有可选字段，保持信息展示简洁

14. 自定义字段更新格式：使用 --customfields 更新任务自定义字段时，不同类型有不同格式：

    # 日期类型（date）：value 是数组，包含带 title 的对象，日期格式为 ISO 8601
    uv run scripts/update_task.py --task-id 'xxx' \
      --customfields '[{"customfieldId": "字段ID", "value": [{"title": "2026-03-16T00:00:00.000Z"}]}]'
    # 文本类型（text）：value 是数组，包含带 title 的对象
    uv run scripts/update_task.py --task-id 'xxx' \
      --customfields '[{"customfieldId": "字段ID", "value": [{"title": "文本内容"}]}]'
    # 单选类型（select）：value 是数组，包含带 id 的选项对象
    uv run scripts/update_task.py --task-id 'xxx' \
      --customfields '[{"customfieldId": "字段ID", "value": [{"id": "选项ID"}]}]'
    

15. 文件类型自定义字段上传：使用 upload_file_to_customfield.py --file-paths 一站式上传一个或多个文件到自定义字段：

    # 上传单个文件
    uv run scripts/upload_file_to_customfield.py \
      --task-id '<taskId>' \
      --file-paths '/path/to/file.pdf' \
      --customfield-id '<字段ID>'
    
    # 上传多个文件（逗号分隔）
    uv run scripts/upload_file_to_customfield.py \
      --task-id '<taskId>' \
      --file-paths '/path/a.pdf,/path/b.png' \
      --customfield-id '<字段ID>'
    

16. 自定义字段文件类型展示：自定义字段中类型为 work（文件附件）的字段，展示时必须将文件名渲染为可点击的下载链接，使用字段值中的 downloadUrl 字段作为链接地址，格式如下：

    • 展示格式：[文件名](downloadUrl)
    • 示例：[材料.md](https://xxx.com/...)
    • 若一个字段包含多个文件，每个文件单独渲染为一个链接
    • 禁止只展示文件名而不附带链接

17. 批量任务表格输出：当查询返回多个任务（2个及以上）时，默认使用表格形式展示，表格列应包含：标题、状态、优先级、执行人、截止时间。单行任务仍使用文本段落形式展示，保持信息清晰易读。

18. 破坏性操作需确认：执行归档任务（archive_task.py）、删除等不可逆或影响较大的操作前，必须先向用户确认，展示操作对象（任务标题/ID）和操作类型，获得明确同意后再执行。例如：

    • "确认归档任务「完成需求文档」(ID: xxx)吗？归档后可从回收站恢复。"
    • "确认删除该评论吗？删除后无法恢复。"

19. 空字段不返回：API 查询任务详情时，值为空的自定义字段不会被返回。如果一个文件类型字段从未被赋值过，customfields 数组中不会包含该字段。要查看任务可填写的所有自定义字段，需要：

    # 1. 从任务详情获取 sfcId（任务类型ID）和 projectId
    uv run scripts/query_task_detail.py <taskId> --detail-level detailed
    
    # 2. 查询该任务类型可用的所有自定义字段
    uv run scripts/get_custom_fields.py <projectId> --sfc-id <sfcId>
    

    返回结果中 type 为 work 的字段就是文件类型字段

20. 任务类型感知：创建任务时，根据用户描述的关键词自动推断任务类型，不要默认创建普通任务：

    • 用户说"需求"/"功能"/"feature" → 用 --name 需求 搜索匹配的任务类型
    • 用户说"缺陷"/"bug"/"问题" → 用 --name 缺陷 搜索匹配的任务类型
    • 用户说"任务"或未明确指定 → 用 --name 任务 搜索，或使用项目默认类型
    • 操作流程：
      1. 确定 projectId 后，先执行 uv run scripts/get_scenario_types.py <projectId> --name <关键词> 查询匹配的任务类型
      2. 若找到唯一匹配，直接使用其 id 作为 --scenariofieldconfig-id 参数
      3. 若找到多个匹配，选择名称最接近用户意图的一个
      4. 若未找到匹配，不传 --scenariofieldconfig-id，使用项目默认类型

21. 项目智能推断：创建任务时，若用户未指定项目，不要随机选择项目，按以下流程处理：

    1. 执行 uv run scripts/query_projects.py --tql "involveMembers = me()" 查询用户参与的项目
    2. 若只有 1 个项目，自动使用该项目，并告知用户
    3. 若有 多个项目，展示项目列表（名称+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 <姓名> --user-ids <ID1,ID2,...>
get_task_statuses.py <taskId>	查询任务工作流状态列表（推荐）	--name <关键词>
get_taskflow_statuses.py <projectId>	获取项目工作流状态（创建任务时用）	--only-start --name <关键词>
get_custom_fields.py <projectId>	获取项目自定义字段配置	--cf-ids <IDs> --sfc-id <ID>
get_scenario_types.py <projectId>	获取项目任务类型列表	--name <关键词> --sfc-ids <IDs>
get_priority_list.py <organizationId>	获取企业优先级配置	—
get_current_user.py	获取当前登录用户信息（userId、name、email 等）	—
create_trace.py	添加任务进展	--task-id <id> --title <标题> --status <1-3>
upload_file_to_customfield.py	上传文件到自定义字段（支持多文件）	--task-id <id> --file-paths <路径> --customfield-id <id>
archive_task.py	归档/恢复任务	--task-id <id> [--restore]
query_task_activity.py	查询任务动态	--task-id <id> --actions comment
manage_sprint.py	迭代管理	--action list|create|start|complete --project-id <id> --sprint-id <id> --name <名>

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"