# Tapd Workitem Sync

> Use when development requirements are confirmed and before implementation starts - ensures a TAPD work item exists for the work, creating one if needed.

- Skill: `tencentblueking/tapd-workitem-sync` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tencentblueking/tapd-workitem-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tencentblueking/tapd-workitem-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tencentblueking (https://skillmd.com/u/tencentblueking)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tencentblueking/tapd-workitem-sync

---


# TAPD 工作项同步

在用户确认开发需求后、开始开发前，确保 TAPD 当前空间中存在对应单据；若已存在则直接返回 ID，否则创建并返回 ID。

## 触发场景

- 用户确认了开发需求（或缺陷），即将开始实现
- 用户要求「创建 TAPD 需求」「同步到 TAPD」「确保有 TAPD 单据」
- 执行 writing-plans 或 executing-plans 前，需要关联 TAPD 单据

## 工作流程

```dot
digraph tapd_sync {
    "用户确认开发需求" [shape=ellipse];
    "获取 workspace_id" [shape=box];
    "提取搜索关键词" [shape=box];
    "查询需求/缺陷" [shape=box];
    "是否已存在?" [shape=diamond];
    "返回已有单据 ID" [shape=box];
    "获取最新迭代" [shape=box];
    "创建需求或缺陷" [shape=box];
    "返回新单据 ID" [shape=box];

    "用户确认开发需求" -> "获取 workspace_id";
    "获取 workspace_id" -> "提取搜索关键词";
    "提取搜索关键词" -> "查询需求/缺陷";
    "查询需求/缺陷" -> "是否已存在?";
    "是否已存在?" -> "返回已有单据 ID" [label="是"];
    "是否已存在?" -> "获取最新迭代" [label="否"];
    "获取最新迭代" -> "创建需求或缺陷";
    "创建需求或缺陷" -> "返回新单据 ID";
    "返回已有单据 ID" -> "开始开发" [style=dashed];
    "返回新单据 ID" -> "开始开发" [style=dashed];
}
```

### 1. 获取 workspace_id

- **用户指定**：若用户提供 `workspace_id` 或项目名，直接使用
- **项目推断**：bk-flow 项目对应 TAPD 空间 **BKFlow**，`workspace_id = 70120217`
- **未指定时**：调用 `get_user_participant_projects`，从返回列表中按项目名匹配

### 2. 提取搜索关键词

从开发需求中提取 2–5 个核心关键词，用于模糊匹配：

- 需求标题中的核心名词、动词
- 功能模块名、特性名
- 避免过短（如单字）或过长（整句）

示例：需求「构建研发 skills」→ 关键词 `构建研发skills` 或 `研发skills`

### 3. 查询是否已存在

**需求（stories）**：调用 `get_stories_or_tasks`：

```
workspace_id, options: { entity_type: "stories", name: "%关键词%", limit: 10 }
```

**缺陷（bugs）**：调用 `get_bug`：

```
workspace_id, options: { title: "%关键词%", limit: 10 }
```

**匹配逻辑**：遍历返回结果，若任一单据的 `name`（需求）或 `title`（缺陷）包含关键词，或关键词包含单据标题的核心部分，视为匹配。

### 4. 若已存在 → 返回单据 ID

- 使用**短 ID** 格式：完整 ID 形如 `1070120217131972327`，短 ID 为后 9 位 `131972327`
- 返回格式：`TAPD 单据 ID：131972327`
- 可附带链接：`https://tapd.woa.com/70120217/prong/stories/view/131972327`

### 5. 若不存在 → 创建单据

**获取最新迭代**：调用 `get_iterations`：

```
workspace_id, options: { status: "open", order: "enddate desc", limit: 5 }
```

取第一条（enddate 最晚的开放迭代）的 `id` 作为 `iteration_id`。

**创建需求**：调用 `create_story_or_task`：

```
workspace_id, name: "汇总后的需求标题", options: { entity_type: "stories", iteration_id, description }
```

**创建缺陷**：调用 `create_bug`：

```
workspace_id, title: "汇总后的缺陷标题", options: { iteration_id, description }
```

**汇总规则**：

- 需求：将开发需求要点归纳为 1–2 句标题 + 可选详细描述
- 缺陷：将问题现象、复现步骤、预期/实际结果归纳为标题 + 描述

### 6. 返回新单据 ID

- 从创建返回的 `data.Story.id` 或 `data.Bug.id` 提取短 ID
- 返回格式同上，并说明「已创建新需求/缺陷」

## 单据类型判断

- 用户明确说「缺陷」「bug」「问题」→ 创建缺陷
- 默认 → 创建需求（stories）

## 项目 workspace 映射

| 项目 | TAPD 空间名 | workspace_id |
|------|-------------|--------------|
| bk-flow | BKFlow | 70120217 |

其他项目可通过 `get_user_participant_projects` 查询。

## 输出格式

无论找到或新建，最终必须返回：

```
TAPD 单据 ID：{短ID}
```

可选：附上可点击的 TAPD 链接。

## 参考

- TAPD MCP 工具用法：见 [reference.md](reference.md)