Teambition 任务操作：创建任务、读取任务、评论任务、搜索任务
Teambition 任务操作：创建任务（提单）、读取任务内容、评论任务、按任意条件搜索任务。
config.yaml 中已配置 teambition 段（app_id、app_secret、tenant_id），由 Bot 侧代理持有，工具无需访问凭据project_id — 项目 ID所有 TB API 调用通过 Bot 侧代理自动完成身份验证。operator_id 由代理根据当前用户的钉钉身份自动注入，无需手动传入（传入也会被忽略）。
所有命令都需要必填参数 --project-id（tenant_id 从 config 读取，operator_id 由代理自动注入）。
# 创建任务（指定迭代）
python3 tools/tb_task.py \
--project-id "<项目ID>" \
--title "<任务标题>" \
--note "<任务备注>" \
--priority 0 \
--sprint-id "<迭代ID>"
# 创建任务（不指定迭代）
python3 tools/tb_task.py --project-id "<项目>" \
--title "<任务标题>"
# 读取任务详情和备注内容
python3 tools/tb_task.py --project-id "<项目>" \
--read-task "<任务ID>"
# 评论任务
python3 tools/tb_task.py --project-id "<项目>" \
--comment-task "<任务ID>" --comment "<评论内容>"
# 列出项目自定义字段定义（cf_id → 字段名 + 选项）
python3 tools/tb_task.py \
--operator-id "<操作者>" --project-id "<项目>" \
--list-customfields
# 列出项目下所有任务类型（用于获取 sfc-id）
python3 tools/tb_task.py --project-id "<项目>" \
--list-task-types
# 列出项目下所有任务分组（用于获取 tasklist-id）
python3 tools/tb_task.py --project-id "<项目>" \
--list-task-groups
# 列出所有迭代（用于选择 sprint_id）
python3 tools/tb_task.py --project-id "<项目>" \
--list-sprints
# 列出已知成员（ding_id → 姓名映射，来自 users.json）
python3 tools/tb_task.py --project-id "<项目>" \
--list-members
# 列出所有工作流状态（用于获取 tfs_id，按状态搜索时需要）
python3 tools/tb_task.py --project-id "<项目>" \
--list-statuses
# 查询指定迭代任务列表（sprint-id 必填）
python3 tools/tb_task.py --project-id "<项目>" \
--sprint-tasks --sprint-id "<迭代ID>"
# 通用搜索：按 TQL 查询全项目任务
python3 tools/tb_task.py --project-id "<项目>" \
--search-tasks 'tfsId = "<状态ID>"'
| 参数 | 说明 |
|---|---|
--project-id | 目标项目 ID |
| 参数 | 必填 | 说明 |
|---|---|---|
--title | 创建时必填 | 任务标题（最多 500 字符） |
--note | 否 | 任务备注（支持 markdown） |
--priority | 否 | 0=普通（默认）/ 1=紧急 / 2=非常紧急 |
--sprint-id | --sprint-tasks 时必填 | 迭代 ID（可通过 --list-sprints 查询） |
--tasklist-id | 否 | 任务分组 ID（可通过 --list-task-groups 查询） |
--executor-id | 否 | 执行者 TB 用户 ID（直接指定） |
--executor-ding-id | 否 | 执行者钉钉 staff_id（自动转换为 TB userId） |
--sfc-id | 否 | scenariofieldconfig_id（任务类型，可通过 --list-task-types 查询） |
--customfields | 否 | 自定义字段 JSON，如 [{"cf_id":"x","value_title":"y"}] |
--images | 否 | 附件图片路径（空格分隔多个） |
--read-task | 否 | 读取任务详情（传入任务 ID） |
--comment-task | 否 | 给任务添加评论（传入任务 ID，需配合 --comment） |
--comment | 否 | 评论内容（与 --comment-task 配合，支持 markdown） |
--list-customfields | 否 | 列出项目自定义字段定义（cf_id + 字段名 + 选项值） |
--list-task-types | 否 | 列出项目下所有任务类型（scenariofieldconfig） |
--list-task-groups | 否 | 列出项目下所有任务分组 |
--list-sprints | 否 | 列出所有迭代（含状态） |
--list-members | 否 | 列出已知成员（ding_id + 姓名，来自 users.json） |
--list-statuses | 否 | 列出所有工作流状态（tfs_id + 名称 + 所属工作流） |
--sprint-tasks | 否 | 输出迭代内所有任务列表 |
--search-tasks | 否 | 通用搜索，传入 TQL 查询语句（搜索全项目） |
--search-tasks 接受 TQL 表达式，支持按任意条件搜索全项目任务。
| 字段 | 运算符 | 示例 | 说明 |
|---|---|---|---|
tfsId | = | tfsId = "xxx" | 按工作流状态 ID 筛选 |
_sprintId | = | _sprintId = "xxx" | 按迭代 ID 筛选 |
isDone | = | isDone = false | 按完成状态 |
priority | = | priority = 2 | 按优先级（0/1/2） |
executorId | = | executorId = "xxx" | 按执行者 |
content | ~ | content ~ "关键词" | 按标题模糊搜索 |
用 AND 连接多个条件：
isDone = false AND priority = 2
tfsId = "xxx" AND executorId = "yyy"
按自定义字段统计任务的流程：
customfields 已自动解析 cf_name（如"优先级（P）"、"缺陷分类"）--list-customfields按执行人分类任务的流程：
executor_name 字段会自动填充（仅限 users.json 中已登记的用户）--list-members 获取所有已知 ding_id→姓名按状态查任务的流程：
--list-statuses 查询所有状态，找到目标状态的 tfs_id--search-tasks 'tfsId = "<tfs_id>"' 搜索| 条件 | 优先级 |
|---|---|
| 全服影响 / 持续报错 / 核心功能异常 | 2（非常紧急） |
| 部分玩家受影响 / 非核心功能 | 1（紧急） |
| 低频 / 边缘场景 / 已有临时方案 | 0（普通） |
创建任务成功时 stdout 输出 JSON：
{
"task_id": "xxx",
"task_url": "https://www.teambition.com/project/{project_id}/sprint/section/{sprint_id}/task/{task_id}",
"content": "任务标题",
"is_done": false,
"executor": "tb_user_id 或 unassigned",
"attachments": 0
}
--read-task 输出：
{
"task_id": "xxx",
"task_url": "https://www.teambition.com/project/{project_id}/task/{task_id}",
"content": "任务标题",
"is_done": false,
"priority": "紧急",
"note_html": "<p>富文本 HTML</p>",
"note_text": "纯文本内容"
}
--comment-task 输出：
{
"comment_id": "xxx",
"task_id": "xxx",
"task_url": "...",
"operator_id": "评论者 TB 用户 ID"
}
--search-tasks / --sprint-tasks 输出：
{
"total": 35,
"tasks": [
{
"id": "xxx",
"content": "任务标题",
"is_done": false,
"priority": 1,
"priority_label": "紧急",
"status": "修复中",
"status_kind": "进行中",
"executor_id": "tb_user_id",
"executor_ding_id": "staff_id",
"executor_name": "张三",
"creator_id": "tb_user_id",
"creator_ding_id": "staff_id",
"creator_name": "李四",
"involve_members": [
{"tb_user_id": "tb_uid_1", "ding_id": "staff_id_1", "name": "李四"},
{"tb_user_id": "tb_uid_2", "ding_id": "staff_id_2", "name": ""}
],
"customfields": [
{"cf_id": "xxx", "cf_name": "优先级（P）", "type": "dropDown", "values": ["P1"]},
{"cf_id": "yyy", "cf_name": "缺陷分类", "type": "commongroup", "values": ["弟子系统"]}
],
"parent_task_id": "",
"progress": 0,
"updated": "2026-04-10T08:00:00Z",
"created": "2026-04-01T10:00:00Z",
"accomplish_time": ""
}
]
}
过程日志输出到 stderr，可忽略。
# 查询迭代列表
python3 tools/tb_task.py --project-id "proj789" --list-sprints
# 查询所有工作流状态
python3 tools/tb_task.py --project-id "proj789" --list-statuses
# 按状态搜索全项目任务
python3 tools/tb_task.py --project-id "proj789" \
--search-tasks 'tfsId = "66b9819c1e9f89fed73ae0d3"'
# 按状态 + 未完成组合搜索
python3 tools/tb_task.py --project-id "proj789" \
--search-tasks 'tfsId = "xxx" AND isDone = false'
# 按标题关键词搜索
python3 tools/tb_task.py --project-id "proj789" \
--search-tasks 'content ~ "登录"'
# 创建任务到指定迭代
python3 tools/tb_task.py --project-id "proj789" \
--title "商店道具数量显示为0" \
--priority 1 \
--sprint-id "sprint_abc123"
# 读取任务
python3 tools/tb_task.py --project-id "proj789" \
--read-task "680b3a0bfb04be42d58a3ce1"
# 评论任务
python3 tools/tb_task.py --project-id "proj789" \
--comment-task "680b3a0bfb04be42d58a3ce1" \
--comment "已排查，根因是配表缺失。"