# PromptX 工作流架构完全指南

## 📚 目录

1. [架构概览](#架构概览)
2. [核心设计理念](#核心设计理念)
3. [工作流组件详解](#工作流组件详解)
4. [标签驱动系统](#标签驱动系统)
5. [分支策略与版本管理](#分支策略与版本管理)
6. [实际使用场景](#实际使用场景)
7. [最佳实践](#最佳实践)
8. [故障排除](#故障排除)

## 架构概览

PromptX 采用了**标签驱动的自动化工作流架构**，通过 PR 标签作为指令触发不同的自动化流程。这种设计让开发流程既灵活又可控。

### 🏗️ 整体架构图

```mermaid
graph TB
    subgraph "开发者操作"
        A[创建 PR] --> B[添加标签]
    end
    
    subgraph "GitHub Actions 工作流"
        B --> C{Label Processor}
        C --> D[Changeset 处理]
        C --> E[测试配置]
        C --> F[合并策略]
        C --> G[发布配置]
    end
    
    subgraph "版本管理"
        D --> H[Version Manager]
        H --> I[消费 Changesets]
        I --> J[更新版本号]
        J --> K[生成 CHANGELOG]
    end
    
    subgraph "发布流程"
        K --> L[NPM Publisher]
        L --> M{分支判断}
        M --> N[dev tag]
        M --> O[alpha tag]
        M --> P[beta tag]
        M --> Q[latest tag]
    end
    
    subgraph "分支流转"
        R[develop] --> S[test]
        S --> T[staging]
        T --> U[main]
    end
    
    style C fill:#f9f,stroke:#333,stroke-width:4px
    style H fill:#bbf,stroke:#333,stroke-width:2px
    style L fill:#bfb,stroke:#333,stroke-width:2px
```

## 核心设计理念

### 1. 🏷️ 标签即指令 (Labels as Commands)

我们将 PR 标签设计为可执行的指令，每个标签都能触发特定的自动化操作：

```yaml
标签格式: action/parameter
示例:
  - changeset/minor     # 创建 minor 版本的 changeset
  - publish/beta        # 设置发布到 beta 标签
  - test/extended       # 运行扩展测试
  - merge/squash        # 使用 squash 合并
```

### 2. 📦 单点版本提升 (Single Version Bump Point)

版本号只在 `develop` 分支提升，其他分支通过平移获得相同版本：

```mermaid
graph LR
    A[develop<br/>v1.2.3 → v1.3.0] -->|平移| B[test<br/>v1.3.0]
    B -->|平移| C[staging<br/>v1.3.0]
    C -->|平移| D[main<br/>v1.3.0]
    
    style A fill:#f96,stroke:#333,stroke-width:2px
```

### 3. 🔄 渐进式发布 (Progressive Publishing)

通过分支自动映射到 NPM 标签，实现渐进式发布：

```
develop → dev tag      # 开发版本
test → alpha tag       # 内测版本
staging → beta tag     # 公测版本
main → latest tag      # 正式版本
```

## 工作流组件详解

### 📋 Label Processor (标签处理器)

**文件**: `.github/workflows/label-processor.yml`

标签处理器是整个系统的入口，负责解析标签并执行相应操作。

#### 工作原理

```mermaid
sequenceDiagram
    participant Dev as 开发者
    participant PR as Pull Request
    participant LP as Label Processor
    participant Action as 具体操作
    
    Dev->>PR: 添加标签 "changeset/minor"
    PR->>LP: 触发 labeled 事件
    LP->>LP: 解析标签<br/>action=changeset<br/>param=minor
    LP->>Action: 执行 changeset 创建
    Action->>PR: 提交 changeset 文件
    Action->>PR: 添加评论通知
```

#### 支持的标签操作

##### 1. Changeset 操作 (`changeset/*`)

创建版本变更记录：

```bash
changeset/patch   # 补丁版本 (1.0.0 → 1.0.1)
changeset/minor   # 次要版本 (1.0.0 → 1.1.0)
changeset/major   # 主要版本 (1.0.0 → 2.0.0)
changeset/none    # 不需要版本变更
```

**执行流程**：
1. 从 PR 描述中提取 User Impact 部分
2. 生成 changeset 文件名（基于 PR 号和标题）
3. 创建 changeset 文件并提交到 PR 分支
4. 自动添加贡献者信息

##### 2. 测试配置 (`test/*`)

配置测试执行策略：

```bash
test/skip-e2e     # 跳过端到端测试
test/extended     # 运行扩展测试套件
test/performance  # 运行性能测试
```

##### 3. 合并策略 (`merge/*`)

设置 PR 合并方式：

```bash
merge/squash      # Squash 合并（压缩提交）
merge/rebase      # Rebase 合并（变基）
merge/merge       # 创建合并提交
merge/auto        # 自动合并（通过检查后）
```

##### 4. 发布配置 (`publish/*`)

控制合并后的发布行为：

```bash
publish/dev       # 发布到 dev 标签
publish/alpha     # 发布到 alpha 标签
publish/beta      # 发布到 beta 标签
publish/latest    # 发布到 latest 标签
publish/hold      # 暂不发布
```

### 🔢 Version Manager (版本管理器)

**文件**: `.github/workflows/version-manager.yml`

版本管理器负责处理版本提升和分支同步。

#### 主要功能

##### 1. 准备发布 (`prepare-release`)

```mermaid
flowchart TD
    A[检查 changesets] --> B{有待处理的?}
    B -->|是| C[创建版本分支]
    C --> D[消费 changesets]
    D --> E[更新 package.json]
    E --> F[生成 CHANGELOG]
    F --> G[创建 PR]
    B -->|否| H[退出]
```

**使用场景**：
- 准备新版本发布
- 批量处理积累的 changesets
- 生成版本变更记录

##### 2. 分支同步 (`sync-branches`)

```mermaid
graph TD
    A[获取 develop 版本] --> B[检查 test 分支]
    B --> C{版本一致?}
    C -->|否| D[合并 develop → test]
    C -->|是| E[检查 staging 分支]
    E --> F{版本一致?}
    F -->|否| G[合并 test → staging]
    F -->|是| H[检查 main 分支]
    H --> I{版本一致?}
    I -->|否| J[合并 staging → main]
    I -->|是| K[完成]
```

**使用场景**：
- 版本发布后同步到各环境
- 修复分支版本不一致问题
- 批量更新所有分支

##### 3. 检查 Changesets (`check-changesets`)

显示当前待处理的 changesets 和预期的版本影响。

### 📦 NPM Publisher (发布器)

**文件**: `.github/workflows/npm-publisher.yml`

自动化 NPM 包发布流程。

#### 发布流程

```mermaid
flowchart TD
    A[推送到分支] --> B{哪个分支?}
    B -->|develop| C[准备发布 dev]
    B -->|test| D[准备发布 alpha]
    B -->|staging| E[准备发布 beta]
    B -->|main| F[准备发布 latest]
    
    C --> G{develop 分支?}
    G -->|是| H[消费 changesets]
    G -->|否| I[跳过版本更新]
    
    H --> J[更新版本号]
    I --> K[构建包]
    J --> K
    
    K --> L[发布到 NPM]
    L --> M{main 分支?}
    M -->|是| N[创建 GitHub Release]
    M -->|否| O[完成]
    N --> O
```

#### 特殊功能

##### 1. 干运行模式 (Dry Run)

手动触发时可选择干运行，模拟发布过程但不实际发布：

```yaml
workflow_dispatch:
  inputs:
    dry_run: true
```

##### 2. 快照版本 (Snapshot)

发布带时间戳的快照版本：

```bash
1.2.3 → 1.2.3-snapshot.20240115120000
```

##### 3. 自动版本消费

只在 `develop` 分支自动消费 changesets，避免版本号在多个分支重复提升。

## 标签驱动系统

### 🎯 设计原则

1. **语义化命名**：使用 `/` 分隔动作和参数
2. **即时反馈**：每个操作都有明确的反馈（评论或状态更新）
3. **幂等性**：重复添加相同标签不会产生副作用
4. **可追溯**：所有操作都有日志记录

### 🔄 标签生命周期

```mermaid
stateDiagram-v2
    [*] --> 添加标签
    添加标签 --> 触发工作流
    触发工作流 --> 解析标签
    解析标签 --> 执行操作
    执行操作 --> 成功: 操作成功
    执行操作 --> 失败: 操作失败
    成功 --> 添加成功评论
    失败 --> 添加错误评论
    添加成功评论 --> [*]
    添加错误评论 --> [*]
```

## 分支策略与版本管理

### 📊 分支流转策略

```mermaid
gitGraph
    commit id: "Initial"
    branch develop
    checkout develop
    commit id: "Base"
    
    branch feature/issue-1
    checkout feature/issue-1
    commit id: "Implementation"
    
    checkout develop
    merge feature/issue-1 tag: "PR merged"
    commit id: "v1.1.0"
    
    branch test
    checkout test
    merge develop tag: "v1.1.0-alpha"
    
    branch staging
    checkout staging
    merge test tag: "v1.1.0-beta"
    
    checkout main
    merge staging tag: "v1.1.0"
```

### 🔖 版本号管理规则

1. **版本提升时机**：
   - 只在 `develop` 分支消费 changesets
   - 通过 Version Manager 手动触发
   - 或在 PR 合并时自动处理

2. **版本同步机制**：
   - 使用 `sync-branches` 操作平移版本
   - 保持所有分支版本号一致
   - 通过 NPM 标签区分不同环境

3. **版本号格式**：
   ```
   主版本.次版本.补丁版本[-预发布标识.序号]
   1.2.3-alpha.1
   1.2.3-beta.2
   1.2.3
   ```

## 实际使用场景

### 场景 1：开发新功能

```mermaid
sequenceDiagram
    participant Dev as 开发者
    participant GH as GitHub
    participant WF as 工作流
    participant NPM as NPM Registry
    
    Note over Dev: 1. 创建功能分支
    Dev->>GH: 创建 PR (feature/issue-123)
    
    Note over Dev: 2. 开发完成后
    Dev->>GH: 添加标签 "changeset/minor"
    GH->>WF: 触发 Label Processor
    WF->>GH: 创建 changeset 文件
    
    Note over Dev: 3. 代码审查通过
    Dev->>GH: 合并 PR 到 develop
    GH->>WF: 触发 NPM Publisher
    WF->>WF: 消费 changesets
    WF->>WF: 更新版本 1.2.0 → 1.3.0
    WF->>NPM: 发布 1.3.0 到 dev 标签
    
    Note over Dev: 4. 测试通过后
    Dev->>GH: 运行 sync-branches
    GH->>WF: 同步版本到 test/staging/main
    WF->>NPM: 逐步发布到 alpha/beta/latest
```

### 场景 2：紧急修复

```bash
# 1. 创建修复分支
git checkout -b fix/issue-456

# 2. 提交修复并创建 PR
git push origin fix/issue-456

# 3. 在 PR 上添加标签
- changeset/patch    # 补丁版本
- test/skip-e2e      # 跳过 E2E 测试加快流程
- merge/auto         # 自动合并

# 4. 合并后自动发布
```

### 场景 3：预发布测试

```yaml
# 手动触发发布到特定标签
workflow: NPM Publisher
inputs:
  publish_tag: alpha
  dry_run: false

# 或通过标签控制
PR 标签: publish/alpha
```

## 最佳实践

### ✅ 推荐做法

1. **尽早添加 changeset 标签**
   - 在 PR 创建后立即添加，避免遗忘
   - 使用 `changeset/none` 明确标记不需要版本变更的 PR

2. **合理使用版本类型**
   ```
   major: 破坏性变更，API 不兼容
   minor: 新功能，向后兼容
   patch: 问题修复，性能优化
   ```

3. **利用自动化减少手动操作**
   - 使用 `merge/auto` 自动合并
   - 配置 `publish/*` 标签控制发布流程

4. **保持分支清洁**
   - 定期运行 `sync-branches` 保持版本一致
   - 及时清理已合并的功能分支

### ❌ 避免事项

1. **不要手动修改版本号**
   - 始终通过 changesets 管理版本
   - 避免直接编辑 package.json

2. **不要在非 develop 分支创建 changesets**
   - Changesets 应该随 PR 创建
   - 通过标签系统自动生成

3. **不要跳过测试环境**
   - 遵循 dev → alpha → beta → latest 的发布流程
   - 紧急情况使用 hotfix 分支

## 故障排除

### 常见问题

#### 1. Changeset 创建失败

**症状**：添加 `changeset/*` 标签后没有生成文件

**可能原因**：
- PR 分支保护规则阻止推送
- GitHub Token 权限不足
- Changeset 已经存在

**解决方案**：
```bash
# 检查工作流日志
GitHub Actions → Label Processor → 查看具体错误

# 手动创建 changeset
npx changeset add
```

#### 2. 版本同步失败

**症状**：分支版本号不一致

**解决方案**：
```bash
# 手动触发同步
workflow_dispatch:
  workflow: Version Manager
  action: sync-branches
```

#### 3. 发布失败

**症状**：代码合并但包未发布

**检查清单**：
- [ ] NPM_TOKEN 是否配置正确
- [ ] package.json 中的包名是否正确
- [ ] 是否有网络连接问题
- [ ] NPM Registry 是否正常

### 🔍 调试技巧

1. **查看工作流日志**
   ```
   Actions → 选择工作流 → 查看运行详情
   ```

2. **本地测试工作流**
   ```bash
   # 使用 act 工具本地运行
   act -j process-label
   ```

3. **验证标签解析**
   ```bash
   # 测试标签格式
   echo "changeset/minor" | cut -d'/' -f1  # changeset
   echo "changeset/minor" | cut -d'/' -f2  # minor
   ```

## 附录

### 环境变量配置

```yaml
必需的 Secrets:
  GITHUB_TOKEN: 默认提供
  NPM_TOKEN: npm发布凭证

可选配置:
  SKIP_CHANGELOG: 跳过changelog生成
  AUTO_MERGE_ENABLED: 启用自动合并
```

### 相关文件

```
.github/
├── workflows/
│   ├── label-processor.yml    # 标签处理器
│   ├── version-manager.yml    # 版本管理
│   ├── npm-publisher.yml      # NPM发布
│   ├── branch-validator.yml   # 分支验证
│   ├── auto-merge.yml         # 自动合并
│   └── ci.yml                 # 持续集成
├── .changeset/
│   ├── config.json            # Changeset配置
│   └── README.md              # Changeset说明
```

### 命令速查

```bash
# 添加 changeset
npx changeset add

# 消费 changesets（更新版本）
npx changeset version

# 发布包
npx changeset publish

# 查看 changeset 状态
npx changeset status

# 手动同步分支
gh workflow run version-manager.yml -f action=sync-branches
```

---

## 总结

PromptX 的工作流系统通过**标签驱动**的设计理念，实现了：

1. 🎯 **精确控制**：每个操作都可以通过标签精确控制
2. 🔄 **自动化流程**：减少手动操作，提高效率
3. 📊 **版本一致性**：单点版本提升，多分支同步
4. 🚀 **渐进式发布**：从开发到生产的平滑过渡

这套系统让我们能够在保持灵活性的同时，确保发布流程的稳定性和可预测性。通过合理使用标签系统，开发者可以轻松管理从开发到发布的整个生命周期。