dingtalk-tb-ai-skill
SKILL.md
适用场景
✅ 适合使用本技能：
- 查询我的待办任务、今天/本周到期的任务、逾期任务
- 创建、更新、归档任务
- 更新任务状态、优先级、执行人、备注
- 管理任务进展、评论（支持 @提及）、动态
- 上传文件到任务
- 查询项目列表、项目详情
- 查询企业成员
- 管理迭代（创建/开始/完成）
❌ 不适用场景：
- 操作非 Teambition 平台（Jira、Asana 等）
- Git 操作或代码管理 → 直接使用
git - 管理脚本未覆盖的 Teambition 组织/管理员设置
环境准备
获取 User Token：Teambition 开放平台
# 方式 1：环境变量
export TB_USER_TOKEN="your_token"
# 方式 2：在 dingtalk-tb-ai-skill/ 目录下创建 user-token.json
# {"userToken": "your_token"}
cd dingtalk-tb-ai-skill && uv sync
核心规则
-
me()：TQL 中查询"我的"任务/项目，必须用executorId = me()，禁止硬编码用户 ID -
时区：
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 -
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>获取父任务标题 - 展示任务列表/详情时的必要步骤：
- 收集所有任务中出现的各类 ID（去重）
- 批量查询对应的名称（人员用
query_members.py，项目/迭代/任务用各自的查询脚本） - 将 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" - 需要转换的常见 ID 字段：
-
优先级：数值含义为
0=紧急 1=高 2=中 3=低，但企业通常会自定义优先级名称，脚本输出的priorityLabel仅为系统默认值，不代表该企业的真实配置。- 展示优先级名称前必须先查询企业配置，查询链路：
- 从任务详情获取
projectId uv run scripts/query_project_detail.py <projectId> --extra-fields organizationId获取organizationIduv run scripts/get_priority_list.py <organizationId>获取企业真实优先级列表
- 从任务详情获取
- 返回结果中每条优先级包含
priority（数值）和name（企业自定义名称），以此覆盖默认 label 后再展示 - 更新优先级前同样需要先查询，将用户描述的优先级名称与企业配置匹配后，再用对应的
priority数值调用更新接口
- 展示优先级名称前必须先查询企业配置，查询链路：
-
归档 vs 删除：归档任务会移入回收站，不在正常列表显示，可通过
--restore恢复；归档不等于删除 -
动态 vs 进展：动态（activity）是系统自动记录的操作历史（状态变更、字段修改等）；进展（trace）是用户手动填写的阶段性状态更新
-
迭代操作顺序：先用
--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 -
状态查询优先：更新任务状态时，优先使用
get_task_statuses.py <taskId>直接查询该任务的工作流状态列表，无需先获取 projectId；只有创建任务需要初始状态时才用get_taskflow_statuses.py -
按需读文档：TQL 语法 →
references/tql.md；进展/评论/动态/归档 →references/task-ops.md；错误处理 →references/error-handling.md -
文件上传流程：先用
upload_file.py上传文件获取fileToken，再用create_comment.py --file-tokens <token>将文件附加到评论；两步均走脚本，无需直接调 API -
ID 链接渲染：当回复中涉及任务 ID 或项目 ID 时，必须将其渲染为可点击的链接，格式如下：
- 任务链接：
https://www.teambition.com/task/{taskId} - 项目链接：
https://www.teambition.com/project/{projectId}
- 任务链接：
-
任务的 content = 标题：API 返回的
content字段就是任务的标题，向用户展示时统一使用"标题"而非"内容"，避免混淆；create_task.py用--title，update_task.py用--content，两者语义一致 -
空字段隐藏：展示任务或项目信息时，值为空、null、0、false 或空数组的字段应当隐藏，不向用户展示，只展示有实际值的字段。例如：
- 进度为 0 → 不展示进度
- 截止时间为 null → 不展示截止时间
- 备注为空字符串 → 不展示备注
- 迭代为 null → 不展示迭代
- 标签为空数组 → 不展示标签
- 此规则适用于所有可选字段，保持信息展示简洁
-
自定义字段更新格式：使用
--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"}]}]'注意：查询时字段 ID 为
cfId，更新时字段 ID 为customfieldId（不同！） -
自定义字段文件类型展示：自定义字段中类型为
work（文件附件）的字段，展示时必须将文件名渲染为可点击的下载链接，使用字段值中的downloadUrl字段作为链接地址，格式如下：- 展示格式：
[文件名](downloadUrl) - 示例：
[面圣材料.md](https://tb-oss-test.oss-cn-shanghai.aliyuncs.com/...) - 若一个字段包含多个文件，每个文件单独渲染为一个链接
- 禁止只展示文件名而不附带链接
- 展示格式：
脚本速查
| 脚本 | 用途 | 关键参数 |
|---|---|---|
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>（必需）--content --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-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> |
查询任务工作流状态列表（推荐） | --q <关键词> |
get_taskflow_statuses.py <projectId> |
获取项目工作流状态（创建任务时用） | --only-start --q <关键词> |
get_custom_fields.py <projectId> |
获取项目自定义字段配置 | --cf-ids <IDs> --sfc-id <ID> |
get_scenario_types.py <projectId> |
获取项目任务类型列表 | --q <关键词> --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.py |
上传文件，返回 fileToken |
--file-path <路径> --scope task:<id> --category attachment |
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' --content '新标题' --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'
文件上传
# 第一步：上传文件，获取 fileToken
uv run scripts/upload_file.py \
--file-path '/path/to/doc.pdf' \
--scope 'task:<taskId>' \
--category attachment
# 第二步：将 fileToken 附加到评论
uv run scripts/create_comment.py \
--task-id 'xxx' \
--content '附件已上传，请查收' \
--file-tokens 'token1'
分页查询
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 20
# 下一页（使用上次输出中的 nextPageToken）
uv run scripts/query_tasks.py --tql "executorId = me()" --page-size 20 --page-token "上次返回的TOKEN"
Weekly Installs
6
Repository
teambition/tb-skillsGitHub Stars
3
First Seen
8 days ago
Security Audits
Installed on
openclaw5
gemini-cli4
github-copilot4
codex4
kimi-cli4
cursor4