Teambition Skill

Teambition 任务操作：创建任务（提单）、读取任务内容、评论任务、按任意条件搜索任务。

前置条件

1. config.yaml 中已配置 teambition 段（app_id、app_secret、tenant_id），由 Bot 侧代理持有，工具无需访问凭据
2. 用户需提供以下信息（通过 CLI 参数传入）：
   - project_id — 项目 ID

所有 TB API 调用通过 Bot 侧代理自动完成身份验证。operator_id 由代理根据当前用户的钉钉身份自动注入，无需手动传入（传入也会被忽略）。

CLI 用法

所有命令都需要必填参数 --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>"'

参数速查

全局参数（必填）

操作参数

TQL 查询语法

--search-tasks 接受 TQL 表达式，支持按任意条件搜索全项目任务。

可用字段

组合条件

用 AND 连接多个条件：

isDone = false AND priority = 2
tfsId = "xxx" AND executorId = "yyy"

典型用法

按自定义字段统计任务的流程：

1. 任务输出的 customfields 已自动解析 cf_name（如"优先级（P）"、"缺陷分类"）
2. 如需查看项目所有字段定义及选项值，用 --list-customfields

按执行人分类任务的流程：

1. 查询任务时 executor_name 字段会自动填充（仅限 users.json 中已登记的用户）
2. 如需完整映射表，先 --list-members 获取所有已知 ding_id→姓名

按状态查任务的流程：

1. 先 --list-statuses 查询所有状态，找到目标状态的 tfs_id
2. 用 --search-tasks 'tfsId = "<tfs_id>"' 搜索

优先级选择

输出

创建任务成功时 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 "已排查，根因是配表缺失。"