TCSK GitLab VSCode 扩展

这是一个用于 VSCode 的 GitLab 集成扩展，提供了完整的 GitLab 工作流支持，包括合并请求（MR）管理、代码审查、分支管理以及与天元平台的深度集成。

📋 功能列表

1. 合并请求（MR）管理

1.1 创建合并请求

• 天元项目模式：针对天元平台集成的项目，提供智能化的 MR 创建流程
• 自定义模式：支持手动选择源分支和目标分支创建 MR
• AI 生成标题和描述：基于提交记录使用 LLM 自动生成 MR 标题和描述
• WIP 标记：支持创建 Work In Progress 状态的 MR
• 审核人分配：支持指定多个审核人，并自动发送微信通知

1.2 MR 列表查看

• 自定义查询：支持配置多个自定义查询视图
• MR 状态筛选：按状态（opened/closed/all）筛选
• 范围筛选：支持 assigned_to_me、created_by_me、all 等范围
• 多维度筛选：支持按作者、审核人、标签、里程碑等筛选

1.3 MR 详情查看

• 代码差异查看：查看 MR 的文件变更和代码差异
• 提交记录查看：查看 MR 相关的提交历史
• 评论系统：支持在代码行上添加评论、编辑评论、删除评论
• 线程管理：支持解决/取消解决评论线程

2. 分支管理

2.1 创建分支

• 基于需求创建分支：从天元平台选择需求，自动创建对应分支
• 分支命名规范：
  • 项目迭代需求：dev_{sprintId}_{issueId}
  • 紧急发布需求：hotfix_{issueId}
  • 普通需求：dev_{issueId}
• 自动切换分支：创建分支后自动切换到新分支

2.2 分支切换

• 一键切换分支：快速切换项目分支
• 分支选择器：可视化选择要切换的分支
• 自动拉取：切换前自动拉取远程分支

2.3 同步主线分支

• 智能同步：根据分支规则自动识别需要同步的主线分支
• 确认机制：同步前显示确认对话框

3. 代码审查

3.1 代码差异查看

• 文件级别差异：查看 MR 中所有变更的文件
• 行级别差异：查看具体的代码变更内容
• 提交级别差异：查看提交记录的详细信息

3.2 评论功能

• 行内评论：在代码行上添加评论
• 评论编辑：支持编辑已发布的评论
• 评论删除：支持删除自己的评论
• 线程解决：标记评论线程为已解决/未解决

3.3 图片审查

• 图片预览：支持查看 MR 中的图片变更
• 图片对比：对比图片的前后版本

4. 天元平台集成

4.1 需求管理

• 需求列表查询：获取与当前用户相关的需求列表
  • 接口：/sup/getMyIssues
  • 筛选条件：已评审到测试完成状态的需求
• 需求状态查询：查询需求的当前状态
• 需求链接跳转：快速跳转到天元平台查看需求详情

4.2 分支规则管理

• 获取合并目标分支：根据源分支自动获取目标分支
  • 接口：/sup/getMergeToGitBranch
  • 参数：branchName（源分支名）、appName（项目名）、operator（操作人）
  • 返回：mergeTo（目标分支）、syncFlag（同步标志）、mergeRequestReviewerList（审核人列表）、issueId（需求ID）
• 分支同步规则：查询分支的同步来源分支
  • 接口：/sup/findSyncFromGitBranch
• 创建分支：在天元平台创建 Git 分支
  • 接口：/sup/createGitBranch
  • 参数：username、sprintId、issueId、branchType、appName

4.3 MR 记录

• 记录 MR 日志：创建 MR 时记录到天元平台
  • 接口：/sup/recordGitBranchMergeLog
  • 记录内容：项目名、源分支、目标分支、MR 状态、MR ID、需求 ID、合并人、合并时间

5. Git 操作

5.1 基础操作

• 拉取代码：一键拉取当前分支的最新代码
• 查看提交记录：查看分支的提交历史
• 查看文件变更：查看工作区的文件变更

5.2 项目信息

• 项目识别：自动识别当前打开的 GitLab 项目
• 远程仓库解析：解析 Git 远程仓库地址
• 分支信息：获取当前分支和所有分支信息

6. 通知与集成

6.1 微信通知

• MR 创建通知：创建 MR 时自动发送微信消息给审核人
• 消息内容：项目名、MR 标题、源分支、目标分支、发起人

6.2 状态栏

• 当前分支显示：在状态栏显示当前 Git 分支
• 项目信息：显示当前项目信息

7. AI 功能

7.1 LLM 集成

• 生成 MR 标题：基于提交记录使用 LLM 生成 MR 标题和描述
• 代码解释：使用 AI 解释代码逻辑
• 文档生成：使用 AI 生成代码文档

7.2 Chat 参与者

• GitLab Chat：提供 GitLab 相关的 AI 助手
• 文档 Chat：提供项目文档查询的 AI 助手

8. 其他功能

8.1 账户管理

• 多账户支持：支持配置多个 GitLab 账户
• Token 管理：管理 GitLab Personal Access Token
• 账户切换：快速切换不同的 GitLab 账户

8.2 配置管理

• 自定义查询配置：配置自定义的 MR/Issue 查询视图
• 超时配置：配置 API 请求超时时间
• 天元平台地址配置：配置天元平台的访问地址

🔍 核心实现逻辑

创建 MR 时的分支规范校验

天元项目模式

1. 分支名格式校验

   // 位置：webview/src/pages/create/tianyuancreate.tsx
   // 校验逻辑：检查当前分支是否以 dev_ 开头
   if (branch && branch.startsWith('dev_')) {
     getTargetBranch(branch, baseInfo?.projectName || '');
   } else {
     setDisabled(true); // 禁用创建按钮
   }
   

2. 调用天元接口获取目标分支

   // 位置：src/webview/CreatePanel.ts
   async getTargetBranch(args) {
     return await tyFetch.post('/sup/getMergeToGitBranch', {
       branchName: args.branchName,
       appName: args.projectName,
       operator: accountManager.user?.getUserName(),
     });
   }
   

   接口返回数据结构：

   interface IMergeToBranch {
     mergeTo: string; // 目标分支名
     syncFlag: string; // 同步标志（"是"/"否"）
     mergeRequestReviewerList: {
       // 审核人列表
       loginName: string;
       realName: string;
       gitlabUId: string;
     }[];
     issueId: string; // 需求ID
   }
   

3. 同步标志校验

   // 位置：webview/src/pages/create/tianyuancreate.tsx
   if (targetBranch.syncFlag === '是') {
     setForbid(true); // 禁止创建MR，显示"分支非法，不允许创建合并请求"
   }
   

4. 需求ID提取

   // 位置：webview/src/pages/create/tianyuancreate.tsx
   const branchSplits = baseInfo?.branch?.split('_') || [];
   const issueId = branchSplits[branchSplits.length - 1];
   // 用于生成需求链接和记录MR日志
   

5. 创建MR并记录日志

   // 位置：src/webview/CreatePanel.ts
   async createMergeRequest(args) {
     // 1. 调用GitLab API创建MR
     const res = await this.getGitLabServer().createMergeRequest(
       this.projectInRepository?.project?.restId as number,
       args.createParams as ICreateRequestParams
     );
   
     // 2. 如果有需求ID，记录到天元平台
     if (args.issueId) {
       await this.tyLog({
         appName: this.getProjectName(),
         sourceBranch: args.createParams.source_branch,
         targetBranch: args.createParams.target_branch,
         MRStatus: MRStatus.CREATED,
         MRId: res.id,
         issueId: args.issueId,
         mergeUser: accountManager.user?.getUserName() || '',
         mergeTime: res.created_at,
       });
     }
   
     // 3. 发送微信通知给审核人
     if (args.assigneeNames?.length) {
       await this.getWechatMessage(...);
     }
   }
   

自定义模式

• 用户手动选择源分支和目标分支
• 手动选择审核人
• 不进行分支规范校验
• 不记录到天元平台

需求状态查询实现

获取需求列表

1. 接口调用

   // 位置：src/webview/CreateBranch.ts
   async getMyIssueList() {
     return await tyFetch.post('/sup/getMyIssues', {
       username: this.getGitUserName(),
     });
   }
   

2. 需求数据结构

   interface IIssue {
     id: number; // 需求ID
     title: string; // 需求标题
     trackerName: string; // 需求类型（技术需求/紧急发布需求/普通需求/项目迭代需求）
     sprintId: string; // 迭代ID（如果有）
   }
   

3. 需求筛选

   • 仅展示与当前用户相关的需求
   • 状态范围：已评审到测试完成状态的需求
   • 支持按标题、ID、类型进行搜索过滤

4. 分支名生成规则

   // 位置：webview/src/pages/createBranch/_compontent/issue-table.tsx
   const branchName = useMemo(() => {
     if (checked && issues.length) {
       const issue = issues.find((value) => value.id === checked);
       if (issue) {
         const { trackerName, sprintId, id } = issue;
         if (sprintId) {
           // 项目迭代需求
           return `dev_${sprintId}_${id}`;
         }
         if (trackerName.includes('紧急')) {
           // 紧急发布需求
           return `hotfix_${id}`;
         }
         // 普通需求/技术需求
         return `dev_${id}`;
       }
     }
     return '';
   }, [issues, checked]);
   

创建分支流程

1. 调用天元接口创建分支

   // 位置：src/webview/CreateBranch.ts
   const data = await tyFetch.post<{ branch: string }>('/sup/createGitBranch', {
     username: this.getGitUserName(),
     sprintId,
     issueId,
     branchType, // '开发'/'紧急'/'项目迭代'
     appName: projectName,
   });
   

2. 本地Git操作

   // 尝试直接checkout
   try {
     await raw.checkout(branchName);
   } catch (error) {
     // 如果分支不存在，先fetch然后创建本地分支
     await raw.fetch();
     await execPromise(
       `git checkout -b ${branchName} origin/${branchName}`,
       path.dirname(this.path)
     );
   }
   
   // 设置上游分支
   try {
     await execPromise(`git config --get branch.${branchName}.remote`, ...);
   } catch (error) {
     execPromise(`git branch --set-upstream-to=origin/${branchName}`, ...);
   }
   

远程接口调用架构

请求封装

1. OFetch 类

   // 位置：src/services/fetch/index.ts
   export class OFetch {
     private baseUrl: string;
     serverBiz: ServerBiz;
   
     // 统一处理响应
     async bizResponse(ctx: any, next: FetchMiddleType) {
       const { code, message, success, errmsg } = ctx.res;
       if (code === '0000' || success) {
         ctx.res = ctx.res.data || ctx.res.result;
       } else {
         vscode.window.showErrorMessage(message);
         throw {
           type: errorEnum.common,
           message: message || errmsg || '请求失败',
         };
       }
       return next();
     }
   }
   

2. 天元平台请求实例

   export const tyFetch = new OFetch(
     settingManager.tianyuanhost.getSettingVal() as string
   );
   

3. 中间件机制

   • hostUrlMiddle：设置请求基础URL
   • headerMiddle：设置请求头（Content-Type: application/json）
   • bizResponse：统一处理业务响应，提取 data/result 字段

主要天元接口

🏗️ 项目结构

src/
├── gitlab/
│   ├── git/              # Git操作相关
│   │   ├── account-manager.ts      # 账户管理
│   │   ├── git-branch.ts           # 分支操作
│   │   ├── git-repository.ts       # 仓库操作
│   │   └── ...
│   ├── gitlab/           # GitLab API相关
│   │   ├── gitlab-service.ts      # GitLab服务封装
│   │   ├── graphql/               # GraphQL API
│   │   └── ...
│   └── tianyuan/         # 天元平台集成
│       └── index.ts              # 天元接口封装
├── services/             # 服务层
│   ├── fetch/            # HTTP请求封装
│   └── ...
├── vscode/               # VSCode扩展相关
│   ├── command/          # 命令定义和处理
│   ├── provider/        # 数据提供者（TreeView等）
│   ├── webview/          # Webview管理
│   └── ...
└── webview/              # Webview面板
    ├── CreatePanel.ts    # 创建MR面板
    ├── CreateBranch.ts   # 创建分支面板
    └── ...

🔧 配置说明

天元平台地址配置

{
  "tcskgitlab.tianyuanhost": "https://unite.itcjf.com"
}

超时配置

{
  "tcskgitlab.timeoutNum": 30000 // 单位：毫秒，最小值20000
}

自定义查询配置

支持配置多个自定义查询视图，用于筛选和展示 MR/Issue。详细配置项见 package.json 中的 contributes.configuration。

📝 使用示例

创建MR（天元项目）

1. 确保当前分支以 dev_ 开头
2. 执行命令：gl.showMrCreate 或点击侧边栏的创建MR按钮
3. 系统自动调用天元接口获取目标分支和审核人
4. 填写标题和描述（可选AI生成）
5. 选择审核人
6. 点击创建，系统会：
   • 调用GitLab API创建MR
   • 记录MR日志到天元平台
   • 发送微信通知给审核人

创建分支

1. 执行命令：gl.openCreateBranchPage
2. 系统调用天元接口获取需求列表
3. 选择需求，系统根据需求类型生成分支名
4. 点击创建分支，系统会：
   • 调用天元接口创建分支
   • 在本地Git仓库checkout到新分支
   • 设置上游分支

同步主线分支

1. 执行命令：gl.pullRelease
2. 系统调用天元接口查找需要同步的主线分支
3. 确认后自动执行 git fetch 和 git merge

🔐 认证

• GitLab认证：使用 Personal Access Token
• 天元认证：通过SSO单点登录，支持天元登录命令 gl.tianyuanlogin

📚 相关文档

• 架构分析
• 开发文档

📄 License

MIT