Dingtalk Teambition Project

适用场景

✅ 适合使用本技能：

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

❌ 不适用场景：

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

获取 User 令牌：Teambition 开放平台

# 方式 1：环境变量 导出 TEAMBITION_USER_令牌="your_令牌"

# 方式 2：在 dingtalk-teambition/ 目录下创建 user-令牌.json # {"user令牌": "your_令牌"}

cd dingtalk-teambition && uv 同步

核心规则

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

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

from datetime 导入 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 执行人 查询_members.py --user-ids 批量查询 创建器Id 创建人 查询_members.py --user-ids 批量查询 involveMembers 参与人列表 查询_members.py --user-ids 批量查询 sprintId 所属迭代 查询_project_detAIl.py 获取迭代列表后匹配 stageId 所属任务列 任务详情中通常包含 stageName，否则需查项目工作流 projectId 所属项目 项目名通常已在上下文中，或用 查询_project_detAIl.py 查询 parentTaskId 父任务 查询_task_detAIl.py 获取父任务标题 展示任务列表/详情时的必要步骤： 收集所有任务中出现的各类 ID（去重） 批量查询对应的名称（人员用 查询_members.py，项目/迭代/任务用各自的查询脚本） 将 ID 替换为名称后再向用户展示 如果无法确定某个 ID 对应的名称，可展示为"未知"或保留该字段不展示，不要直接展示原始 ID # 按姓名搜索成员，获取 userId uv 运行 scripts/查询_members.py --keyword "张三" # 返回结果中匹配 userId，确认后用于展示或操作

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

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

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

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

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

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

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

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

文件上传流程：先用 上传_file.py 上传文件获取 file令牌，再用 创建_comment.py --file-令牌s <令牌> 将文件附加到评论；两步均走脚本，无需直接调 API

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

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

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

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

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

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

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

文件类型自定义字段上传：使用 上传_file_to_customfield.py 一站式上传文件到自定义字段：

uv 运行 scripts/上传_file_to_customfield.py \ --task-id '' \ --file-path '/path/to/file.pdf' \ --customfield-id '<字段ID>'

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

展示格式：文件名 示例：材料.md 若一个字段包含多个文件，每个文件单独渲染为一个链接 禁止只展示文件名而不附带链接

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

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

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

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

# 1. 从任务详情获取 sfcId（任务类型ID）和 projectId uv 运行 scripts/查询_task_detAIl.py --detAIl-level detAIled

# 2. 查询该任务类型可用的所有自定义字段 uv 运行 scripts/获取_custom_fields.py --sfc-id

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

脚本速查 脚本 用途 关键参数 查询_tasks.py 查询任务列表（TQL），默认返回：标题、状态、优先级、执行人ID、截止时间、备注、迭代、任务列、开始时间、进度、父任务ID --tql --page-size N --page-令牌 T --no-detAIls --extra-fields f1,f2 查询_task_detAIl.py 查询任务详情（支持批量） --detAIl-level simple|detAIled --extra-fields f1,f2 cr