Tapd需求单自动创建分支拉流水线 Skill

一、技能概述与价值

1.1 技能定位

这是一个专为Q音iOS团队设计的自动化工具，旨在解决日常开发中的重复性工作：

• 痛点：每次处理新需求时，需要手动创建分支、配置流水线、添加权限
• 方案：通过自动化工具实现一键完成全流程
• 价值：单个需求节省15-20分钟，降低人工操作错误率

1.2 核心功能矩阵

1
2
3
4
5
6
7
8
9
10
11

┌─────────────┬─────────────────────────────┬─────────────────┐
│ 阶段         │ 功能模块                    │ 传统耗时        │
├─────────────┼─────────────────────────────┼─────────────────┤
│ 需求获取     │ TAPD自动登录与信息提取      │ 3-5分钟         │
├─────────────┼─────────────────────────────┼─────────────────┤
│ 代码管理     │ 工蜂分支自动创建            │ 2-3分钟         │
├─────────────┼─────────────────────────────┼─────────────────┤
│ 流水线配置   │ 蓝盾流水线创建与配置        │ 5-8分钟         │
├─────────────┼─────────────────────────────┼─────────────────┤
│ 权限管理     │ 自动添加相关人员权限        │ 2-3分钟         │
└─────────────┴─────────────────────────────┴─────────────────┘

二、技术选型：为什么选择Playwright？

2.1 Playwright核心优势

graph TD    A[Playwright技术选型] --> B[多浏览器支持]    A --> C[自动化能力]    A --> D[调试工具]    A --> E[跨平台兼容]        B --> B1[Chromium]    B --> B2[Firefox]    B --> B3[WebKit]        C --> C1[页面自动化]    C --> C2[网络拦截]    C --> C3[文件操作]        D --> D1[代码生成器]    D --> D2[调试器]    D --> D3[追踪查看器]        E --> E1[Windows]    E --> E2[macOS]    E --> E3[Linux]

2.2 与传统方案的对比

2.3 在我们的场景中的实际优势

1. 可靠的选择器系统：支持文本、CSS、XPath等多种定位方式
2. 自动等待机制：内置智能等待，减少时序问题
3. 网络拦截能力：可以模拟各种网络条件
4. 截图与录屏：方便调试和记录问题
5. 并行执行：支持多页面同时操作

三、核心流程架构

3.1 整体流程图

flowchart TD    Start([输入TAPD链接]) --> Auth[登录TAPD]    Auth --> Info[提取需求信息]        Info --> Branch[生成分支名]    Info --> Version[确定版本号]        Branch --> CreateBranch[创建Git分支]    Version --> CreateBranch        CreateBranch --> DevOps{DevOps创建}        DevOps --> |成功| Perm[添加权限]    DevOps --> |失败| Retry[重试机制]    Retry --> DevOps        Perm --> Result[输出结果]    Retry --> |超过重试次数| Skip[跳过DevOps]    Skip --> Result        Result --> End([流程结束])        subgraph "关键决策点"        Branch        Version        DevOps    end        subgraph "容错处理"        Retry        Skip    end

3.2 各阶段详细流程

3.2.1 登录与信息提取阶段

sequenceDiagram    participant User as 用户    participant Script as 自动化脚本    participant TAPD as TAPD系统    participant Git as 工蜂系统        User->>Script: 提供TAPD链接    Script->>TAPD: 访问登录页面    TAPD-->>Script: 返回登录页    Script->>TAPD: 模拟点击登录    TAPD-->>Script: 登录成功    Script->>TAPD: 访问需求详情页    TAPD-->>Script: 返回页面内容        par 并行提取        Script->>TAPD: 提取需求ID        Script->>TAPD: 提取标题        Script->>TAPD: 提取相关人员        Script->>TAPD: 提取版本分类    end        Script->>Git: 获取最新开发分支    Git-->>Script: 返回分支列表    Script-->>User: 返回完整信息

四、关键技术实现详解

4.1 智能分支名生成策略

4.1.1 分支名生成流程图

flowchart TD    Start([开始生成分支名]) --> Extract[提取需求标题]    Extract --> AI{DeepSeek可用?}    AI -->|是| DeepSeek[调用AI生成]    AI -->|否| Translate[Google翻译]    DeepSeek --> ProcessAI[AI处理]    ProcessAI --> FormatAI[格式化]    Translate --> ProcessTrans[翻译处理]    ProcessTrans --> FormatTrans[格式化]    FormatAI --> Rules[应用命名规则]    FormatTrans --> Rules    Rules --> Validate[验证分支名]    Validate -->|合法| Return[返回分支名]    Validate -->|非法| Adjust[调整命名]    Adjust --> Validate    Return --> End([完成])    subgraph NamingRules[命名规则]        R1[小写字母]        R2[驼峰式]        R3[最多3个单词]        R4[长度小于等于30字符]    end

4.1.2 实现策略对比

4.1.3 代码实现关键点

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// 1. 优先使用AI生成
async function callDeepSeek(prompt) {
  const fullPrompt = `${prompt}\n\n要求：
  1. 只能包含英文单词
  2. 使用驼峰命名（camelCase）
  3. 最多三个单词
  4. 只返回分支名，不要任何解释`;
  
  // API调用逻辑...
}

// 2. 备用翻译方案
async function translateToBranchName(chineseText) {
  // Google翻译API调用
  // 清理和格式化逻辑...
}

// 3. 最终分支名组合
const branchName = `feature/${tapdId}-${generatedName}`;

4.2 版本号确定机制

4.2.1 版本号确定流程图

flowchart TD    Start([开始确定版本号]) --> Input{有输入版本?}        Input --> |是| UseInput[使用输入版本]    Input --> |否| CheckTAPD[检查TAPD分类]        CheckTAPD --> FoundTAPD{TAPD有版本?}    FoundTAPD --> |是| ParseTAPD[解析TAPD版本]    FoundTAPD --> |否| CheckGit[查询工蜂最新]        ParseTAPD --> NormalizeTAPD[标准化版本号]        CheckGit --> FoundGit{工蜂有版本?}    FoundGit --> |是| ParseGit[解析工蜂版本]    FoundGit --> |否| UseDefault[使用默认版本]        ParseGit --> NormalizeGit[标准化版本号]    UseDefault --> Default[20.0.0]        NormalizeTAPD --> Validate[验证版本格式]    NormalizeGit --> Validate    UseInput --> Validate        Validate --> |有效| Return[返回版本号]    Validate --> |无效| Fallback[使用默认]        Fallback --> Return    Return --> End([完成])

4.2.2 版本源优先级

1

优先级1: 用户手动输入 → 优先级2: TAPD分类字段 → 优先级3: 工蜂最新分支 → 优先级4: 默认20.0.0

4.2.3 版本标准化处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// 统一版本格式为 x.x.x
function parseAndNormalizeVersion(text) {
  const patterns = [
    /(\d+\.\d+\.\d+)/,  // 匹配 20.1.5
    /(\d+\.\d+)/        // 匹配 20.2
  ];
  
  for (const pattern of patterns) {
    const match = text.match(pattern);
    if (match) {
      const parts = match[1].split('.');
      // 补全为三位版本号
      while (parts.length < 3) {
        parts.push('0');
      }
      return parts.join('.');
    }
  }
  return null;
}

4.3 蓝盾流水线创建容错方案

4.3.1 蓝盾问题解决流程图

flowchart TD    Start([开始创建流水线]) --> Try[尝试创建]    Try --> Success{创建成功?}    Success -->|是| Perm[继续添加权限]    Success -->|否| Diagnose[诊断问题]    Diagnose --> CheckMemory{内存不足?}    CheckMemory -->|是| FreeMem[释放内存]    CheckMemory -->|否| CheckBrowser{浏览器崩溃?}    CheckBrowser -->|是| Restart[重启浏览器]    CheckBrowser -->|否| CheckNet{网络问题?}    CheckNet -->|是| WaitNet[等待重试]    CheckNet -->|否| Unknown[未知错误]    FreeMem --> Retry[重试创建]    Restart --> Retry    WaitNet --> Retry    Unknown --> Skip[跳过此步骤]    Retry --> Attempt{第几次尝试?}    Attempt -->|小于等于3次| Try    Attempt -->|大于3次| Manual[建议手动创建]    Manual --> Skip    Perm --> End([完成])    Skip --> End

4.3.2 常见问题及解决方案

4.3.3 代码中的重试机制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// 重试逻辑实现
const maxRetries = 3;
const retryDelay = 5000; // 5秒延迟

for (let attempt = 1; attempt <= maxRetries; attempt++) {
  try {
    // 尝试创建流水线
    devopsUrl = await createDevopsPipeline(page, devVer, prdName, branchName);
    break; // 成功则跳出循环
  } catch (error) {
    if (attempt < maxRetries) {
      Logger.warn(`第 ${attempt}/${maxRetries} 次失败，${retryDelay/1000}秒后重试`);
      
      // 创建新页面实例，避免状态污染
      page = await context.newPage();
      page.setDefaultTimeout(CONFIG.timeout.page);
      
      // 延迟后重试
      await new Promise(resolve => setTimeout(resolve, retryDelay));
    } else {
      Logger.warn(`已重试 ${maxRetries} 次，跳过此步骤`);
      Logger.info('请手动创建 DevOps 流水线');
    }
  }
}

4.3.4 内存优化配置

1
2
3
4
5
6
7
8
9
10
11
12
13

// Playwright启动配置优化
browser = await chromium.launch({
  headless: false,
  slowMo: 500, // 放慢操作速度，便于观察
  args: [
    '--disable-gpu',           // 禁用GPU加速
    '--disable-dev-shm-usage', // 避免/dev/shm内存问题
    '--no-sandbox',           // 禁用沙箱（谨慎使用）
    '--disable-setuid-sandbox',
    '--disable-accelerated-2d-canvas',
    '--disable-web-security'  // 仅测试环境使用
  ]
});

4.4 权限用户识别机制

4.4.1 权限识别流程图

flowchart TD    Start([开始识别权限用户]) --> Parse[解析需求页面]        Parse --> Designer{有设计师?}    Designer --> |有| GetDesigner[获取设计师信息]    Designer --> |无| SkipDesigner[跳过设计师]        Parse --> PM{有产品经理?}    PM --> |有| GetPM[获取产品经理信息]    PM --> |无| SkipPM[跳过产品经理]        Parse --> CC{有抄送人?}    CC --> |有| GetCC[获取抄送人信息]    CC --> |无| SkipCC[跳过抄送人]        GetDesigner --> Combine[合并用户列表]    GetPM --> Combine    GetCC --> Combine        SkipDesigner --> Combine    SkipPM --> Combine    SkipCC --> Combine        Combine --> Filter[过滤空值]    Filter --> Format[格式化为字符串]    Format --> Apply[应用到权限配置]        Apply --> End([完成权限识别])

4.4.2 权限字段映射表

4.4.3 代码实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// 获取字段值的通用函数
async function getFieldValue(page, fieldName) {
  try {
    // 定位包含特定字段名的容器
    const container = page.locator('.entity-detail-right-col').filter({
      has: page.locator(`span:text-is("${fieldName}")`)
    });
    
    const count = await container.count();
    if (count === 0) {
      Logger.warn(`未找到字段: ${fieldName}`);
      return null;
    }
    
    // 提取字段值（通常字段名在第一行，值在第二行）
    const fullText = await container.first().innerText();
    const lines = fullText.split('\n');
    const value = lines[1]?.trim() || null;
    
    Logger.data(fieldName, value || '空');
    return value === '-' ? null : value; // 处理空值标记
  } catch (error) {
    Logger.error(`获取 ${fieldName} 失败: ${error.message}`);
    return null;
  }
}

// 收集所有相关人员
const designer = await getFieldValue(page, '设计师');
const producer = await getFieldValue(page, '产品经理');
const copyTo = await getFieldValue(page, '抄送人');

// 合并并去重
const devNames = [designer, producer, copyTo]
  .filter(Boolean) // 移除null/undefined
  .join(','); // 拼接为逗号分隔的字符串

4.4.4 权限配置最佳实践

1. 最少权限原则：只添加必要的人员
2. 角色分离：区分执行者和查看者
3. 定期清理：建议定期审查权限列表
4. 审计日志：记录所有权限变更操作

五、完整执行流程示例

5.1 成功执行时间线

1
2
3
4
5
6
7
8
9

00:00 - 输入TAPD链接，启动脚本
00:05 - 自动登录TAPD成功
00:15 - 获取需求信息完成（标题、ID、相关人员）
00:25 - 生成分支名：feature/20420710-userLoginOptimization
00:35 - 确定版本号：20.1.0
00:45 - 创建工蜂分支成功
01:15 - 创建蓝盾流水线成功
01:30 - 添加权限完成（设计师：张三，产品经理：李四）
01:35 - 输出完整结果，流程结束

5.2 错误处理时间线

1
2
3
4
5
6
7
8
9
10
11
12

00:00 - 输入TAPD链接，启动脚本
00:05 - 自动登录TAPD成功
00:15 - 获取需求信息完成
00:25 - 生成分支名成功
00:35 - 确定版本号成功
00:45 - 创建工蜂分支成功
01:00 - 第一次创建蓝盾失败（内存不足）
01:05 - 释放内存，重启浏览器实例
01:10 - 第二次尝试创建蓝盾
01:25 - 第二次创建成功
01:40 - 添加权限完成
01:45 - 输出结果（包含重试记录）

六、部署与集成建议

6.1 环境要求

• Node.js ≥ 14.0.0
• Playwright 浏览器环境
• 网络访问权限（TAPD、工蜂、蓝盾）
• 足够的系统内存（建议≥8GB）

6.2 安装步骤

1
2
3
4
5
6
7
8
9
10
11
12
13

# 1. 克隆代码库
git clone <repository-url>
cd qqmusic-ios-tapd-automation-skill

# 2. 安装依赖
npm install

# 3. 安装Playwright浏览器
npx playwright install chromium

# 4. 配置环境变量（可选）
export TAPD_USERNAME=your_username
export TAPD_PASSWORD=your_password

6.3 集成到CI/CD

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# GitLab CI示例
stages:
  - automation

tapd-automation:
  stage: automation
  script:
    - npm install
    - npx playwright install chromium
    - node scripts/tapd-story-automation.js $TAPD_URL $VERSION
  artifacts:
    paths:
      - logs/
      - screenshots/
  only:
    - triggers

七、总结与展望

7.1 当前成果

• ✅ 全流程自动化：从需求到部署的完整闭环
• ✅ 智能决策：AI辅助分支命名，多源版本确定
• ✅ 健壮性：完善的错误处理和重试机制
• ✅ 可维护性：模块化设计，易于扩展

7.2 未来规划

1. 更多平台支持：扩展Android、Web端自动化
2. 智能分析：基于历史数据的复杂度预测
3. 集成扩展：与更多内部系统对接
4. 可视化界面：提供Web管理界面
5. 性能优化：并行处理多个需求

7.3 经验总结

1. 选择合适的工具：Playwright在Web自动化领域表现出色
2. 设计容错机制：重试、降级、跳过等策略很重要
3. 保持代码可读性：良好的日志和注释便于维护
4. 持续优化：根据实际使用反馈不断改进

技术栈: Node.js + Playwright + DeepSeek API + Google Translate API
适用场景: iOS团队需求处理自动化

通过这个自动化技能，我们成功将平均需求处理时间从20分钟+降低到2分钟以内，同时减少了人为操作错误，提升了团队的整体开发效率。