dingtalk-tb-ai-skill

name	dingtalk-tb-ai-skill
description	Teambition project management via Python scripts: projects, tasks, task traces, comments, files, members. Use when: (1) querying/creating/updating tasks or projects, (2) managing task progress and comments, (3) uploading files to tasks, (4) querying team members. NOT for: non-Teambition platforms, direct API calls without scripts, or operations not covered by available scripts.

Teambition Skill

通过 Python 脚本（uv run）管理 Teambition 项目、任务和团队协作。

适用场景

✅ 适合使用本技能：

• 通过 TQL 查询项目、任务或任务详情
• 创建、更新或归档任务
• 管理任务进展、评论和动态
• 上传文件到任务
• 查询企业成员或当前用户信息
• 更新任务优先级和状态

不适用场景

❌ 不要使用本技能：

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

环境准备

# 安装依赖
cd dingtalk-tb-ai-skill && uv sync

Token 配置

从 Teambition 开放平台 获取 Token，然后通过以下任一方式配置：

# 方式 1：环境变量
export TB_USER_TOKEN="your_token_here"

# 方式 2：Claw 配置文件（~/.openclaw/openclaw.json）
 { "skills": { "entries": { "dingtalk-tb-ai-skill": { "enabled": true, "env": { "TB_USER_TOKEN": "your_token" } } } } }

任务查询完整指南

使用 TQL（任务查询语言）查询 Teambition 任务，支持分页，默认自动获取简单详情。

查询任务列表

uv run scripts/query-tasks.py [选项]

参数说明：

参数	类型	必需	说明
--tql	字符串	否	任务查询语言，用于筛选任务
--page-size	整数	否	每页大小，默认由 API 决定
--page-token	字符串	否	分页令牌，用于获取下一页
--no-details	布尔	否	不自动获取任务详情（默认会自动获取简单详情）

TQL 快速参考

场景	TQL 表达式
我的待办任务	executorId = me() AND isDone = false
我的已完成任务	executorId = me() AND isDone = true
我的逾期任务	executorId = me() AND isDone = false AND dueDate < startOf(d)
本周任务	dueDate <= endOf(w) AND dueDate >= startOf(w)
今天到期的任务	dueDate <= endOf(d) AND dueDate >= startOf(d)
高优先级任务	priority = 0
某项目的任务	projectId = '项目ID'
查询标题包含关键词的任务	title ~ '关键词'
本周创建的任务	created <= endOf(w) AND created >= startOf(w)
过去7天更新的任务	updated >= startOf(d, -7d)

完整 TQL 参考：请查看 任务 TQL 参考文档

常用查询示例

# 查询我的待办任务
uv run scripts/query-tasks.py --tql "executorId = me() AND isDone = false"

# 查询特定项目的任务
uv run scripts/query-tasks.py --tql "projectId = '项目ID'"

# 本周创建的任务，按创建时间降序
uv run scripts/query-tasks.py --tql "created <= endOf(w) AND created >= startOf(w) ORDER BY created DESC"

# 过去 7 天更新过的我的任务，按更新时间降序
uv run scripts/query-tasks.py --tql "executorId = me() AND updated >= startOf(d, -7d) ORDER BY updated DESC"

# 我的逾期未完成任务，按截止时间升序
uv run scripts/query-tasks.py --tql "executorId = me() AND isDone = false AND dueDate < startOf(d) ORDER BY dueDate ASC"

# 查询标题包含关键词的任务
uv run scripts/query-tasks.py --tql "title ~ '需求'"

# 只查询任务ID，不获取详情
uv run scripts/query-tasks.py --no-details

# 组合使用多个参数
uv run scripts/query-tasks.py --tql "executorId = me() AND isDone = false" --page-size 20

查询任务详情

根据任务 ID 查询任务的详细信息，支持简单和详细两种信息级别。

uv run scripts/query-tasks-detail.py <任务ID> [选项]

参数说明：

参数	类型	必需	说明
任务ID	字符串	是	任务 ID 集合，使用逗号分隔
--detail-level	字符串	否	详细程度：simple（默认）或 detailed
--extra-fields	字符串	否	简单模式下额外包含的字段，逗号分隔

简单信息（simple，默认）包含字段：

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

详细信息（detailed） 额外包含：note（备注）、sprintId（迭代 ID）、stageId（任务列 ID）、startDate（开始时间）、progress（进度）、parentTaskId（父任务 ID）、自定义字段等 30+ 个字段。

# 查询单个任务（简单信息）
uv run scripts/query-tasks-detail.py 67ec9b8c3c6130ac88605c3e

# 查询详细信息
uv run scripts/query-tasks-detail.py 67ec9b8c3c6130ac88605c3e --detail-level detailed

更多任务管理功能（归档、恢复、评论、动态、进展等）请查看 任务管理完整文档

---

项目查询完整指南

使用 TQL（项目查询语言）查询 Teambition 项目，支持分页，默认自动获取简单详情。

查询项目列表

uv run scripts/query-projects.py [选项]

参数说明：

参数	类型	必需	说明
--tql	字符串	否	项目查询语言，用于筛选项目
--page-size	整数	否	每页大小，默认由 API 决定
--page-token	字符串	否	分页令牌，用于获取下一页
--include-template	布尔	否	是否包含模板项目，默认不包含
--no-details	布尔	否	不自动获取项目详情

TQL 快速参考

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

完整 TQL 参考：请查看 项目 TQL 参考文档

注意：项目没有截止时间（dueDate）字段，只有创建时间（created）和更新时间（updated）。

常用查询示例

# 查询我创建的项目
uv run scripts/query-projects.py --tql "creatorId = me()"

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

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

# 本周创建的项目，按创建时间降序
uv run scripts/query-projects.py --tql "created <= endOf(w) AND created >= startOf(w) ORDER BY created DESC"

# 今天更新过的项目，按更新时间降序
uv run scripts/query-projects.py --tql "updated <= endOf(d) AND updated >= startOf(d) ORDER BY updated DESC"

# 过去 7 天创建的我参与的非模板项目
uv run scripts/query-projects.py --tql "isTemplate = false AND involveMembers = me() AND created >= startOf(d, -7d) ORDER BY created DESC"

# 查询已归档的项目
uv run scripts/query-projects.py --tql "isSuspended = true"

# 查询本月创建且我参与的项目
uv run scripts/query-projects.py --tql "created >= startOf(M) AND involveMembers = me()"

查询项目详情

根据项目 ID 查询项目的详细信息，支持简单和详细两种信息级别。

uv run scripts/query-projects-detail.py <项目ID> [选项]

参数说明：

参数	类型	必需	说明
项目ID	字符串	是	项目 ID 集合，使用逗号分隔
--detail-level	字符串	否	详细程度：simple（默认）或 detailed
--extra-fields	字符串	否	简单模式下额外包含的字段，逗号分隔

简单信息（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+ 个字段。

# 查询单个项目（简单信息）
uv run scripts/query-projects-detail.py 67ec9b8c3c6130ac88605c3e

# 查询详细信息
uv run scripts/query-projects-detail.py 67ec9b8c3c6130ac88605c3e --detail-level detailed

# 查询多个项目
uv run scripts/query-projects-detail.py 67ec9b8c3c6130ac88605c3e,67ec9b8c3c6130ac88605c3f

更多项目管理功能请查看 项目管理完整文档

---

常用命令

用户与成员

# 获取当前用户信息
uv run scripts/get-current-user.py

# 按关键字或 ID 搜索成员
uv run scripts/query-members.py --keyword "张三"

任务 — 创建

# 基本创建
uv run scripts/create-task.py \
  --project-id "项目ID" \
  --content "任务标题"

# 完整参数创建
uv run scripts/create-task.py \
  --project-id "项目ID" \
  --content "任务标题" \
  --executor-id "执行者ID" \
  --start-date "2026-03-15" \
  --due-date "2026-03-20" \
  --priority "1" \
  --note "任务描述"

任务 — 更新

# 更新任务状态
uv run scripts/update-task-status.py --task-id "任务ID" --status-id "状态ID"

# 更新优先级（0=紧急, 1=高, 2=中, 3=低）
uv run scripts/user-update-task-priority.py --task-id "任务ID" --priority "0"

# 更新任务备注
uv run scripts/update-task-note.py --task-id "任务ID" --note "更新后的备注"

任务 — 归档与恢复

# 归档任务（移入回收站）
uv run scripts/call-user-api.py PUT "v3/task/任务ID/archive"

# 恢复任务
uv run scripts/call-user-api.py POST "v3/task/任务ID/restore" '{}'

任务评论与动态

# 创建评论（支持附件和 @提及）
uv run scripts/call-user-api.py POST "v3/task/任务ID/comment" '{"content": "评论内容"}'

# 查询任务动态
uv run scripts/call-user-api.py GET "v3/task/任务ID/activity/list"

任务进展

# 获取任务进展列表
uv run scripts/call-user-api.py GET "v3/task/任务ID/traces"

# 创建任务进展
uv run scripts/call-user-api.py POST "v3/task/任务ID/trace/create" '{"title":"已完成需求分析","content":""}'

文件上传

# 上传文件到任务
uv run scripts/upload-file.py --task-id "任务ID" --file-path "/path/to/file"

分页查询

大多数查询命令支持分页：

• --page-size：每页记录数（默认 30，最大 100）
• --page-token：传入上次返回的 nextPageToken 获取下一页

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

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

日期时区转换

日期需从东八区（用户输入）转换为 UTC（API 格式）：

• 用户输入：2026-03-15（东八区）
• API 格式：2026-03-14T16:00:00.000Z（UTC，减去 8 小时）

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

参考文档

• 创建任务 — 任务创建完整指南（字段映射、自定义字段、辅助脚本）
• 更新任务 — 更新任务各字段详细指南（并行更新、自定义字段）
• 用户与成员 — 获取当前用户信息、查询企业成员
• 优先级 — 查询企业优先级配置、更新任务优先级
• 任务管理 — 任务查询和管理完整参考（归档、恢复、评论、动态、进展）
• 项目管理 — 项目查询完整参考（TQL 筛选、详情级别）
• 任务进展 — 进展跟踪（获取/创建进展、状态标记）
• 文件上传 — 上传文件到任务或项目
• TQL 参考 — 任务查询语言完整语法
• 项目 TQL — 项目查询语言完整语法
• 最佳实践 — 使用约束与最佳实践
• 错误处理 — 常见错误及解决方案

注意事项

• 运行脚本前先 cd dingtalk-tb-ai-skill
• 在 TQL 中使用 me() 表示当前认证用户
• 使用不熟悉的字段前先查阅参考文档，不要猜测参数名
• 优先级值：0=紧急、1=高、2=中、3=低
• 创建任务时日期转为 UTC，查询展示时转回东八区
• 首次操作建议在测试项目中验证