# 端到端工作流说明文档

> 子任务三 · 5 个端到端自动化场景
> 最后更新：2026-07-07

## 一、总体架构

### 1.1 设计理念

5 个端到端场景统一采用"三阶段脚本 + JS 分析引擎 + DevOps 流水线"架构：

```
┌─────────────────────────────────────────────────────────┐
│                    DevOps 流水线层                        │
│   (4 条建木 YAML · push/定时/手动触发)                 │
├─────────────────────────────────────────────────────────┤
│                    端到端编排层                           │
│  community-ops / quality-gate / project-bootstrap /     │
│  multi-repo-coordination / contributor-growth           │
│  (各 *-full.sh 串联三阶段)                               │
├─────────────────────────────────────────────────────────┤
│           Phase 1          Phase 2          Phase 3     │
│         (01-*.sh)        (02-*.sh)        (03-*.sh)     │
│         数据采集         分析处理          执行/输出      │
├─────────────────────────────────────────────────────────┤
│                    JS 分析引擎层                          │
│  health-analyze / dashboard-gen / growth-analyze /      │
│  skeleton-gen / scoring-engine                           │
│  (10 个 JS 引擎 · 2568 行)                               │
├─────────────────────────────────────────────────────────┤
│                    CLI 命令层                             │
│  gitlink-cli (24 命令组 · 17,005 行 Go)                  │
│  → GitLink API                                           │
└─────────────────────────────────────────────────────────┘
```

### 1.2 通用设计原则

| 原则 | 说明 |
|------|------|
| 三阶段原子化 | 每阶段可单独运行，失败不影响前一阶段成果 |
| DRY_RUN 安全 | 默认 DRY_RUN=true，只打印不实际执行写操作 |
| CLI 版本检测 | detect-cli.sh 自动检测 CLI 是否安装及版本兼容 |
| JSON 中间产物 | 阶段间通过 _output/*.json 传递数据，可调试可复现 |
| 优雅降级 | 离线/未认证时写空 JSON，仍生成报告 |

## 二、场景一：社区运营自动化

### 2.1 架构图

```
community-ops-full.sh z2_cc gitlink-cli
│
├── Phase 1: Issue 自动分拣 (01-triage-issues.sh)
│   ├── gitlink-cli issue +list --state all
│   ├── 按关键词分类（bug/feature/question/docs）
│   └── 输出: _output/triage-report.json
│
├── Phase 2: 社区周报生成 (02-generate-weekly.sh)
│   ├── 采集: issues / prs / commits / contributors
│   ├── health-analyze.js 4 维评分
│   │   ├── Issue 关闭率 (30%)
│   │   ├── PR 合并率 (25%)
│   │   ├── 贡献者活跃度 (25%)
│   │   └── 响应速度 (20%)
│   └── 输出: _output/weekly-health-report.html
│
└── Phase 3: Release Notes (03-generate-release.sh)
    ├── gitlink-cli commit +list --limit 100
    ├── 按 Conventional Commits 分类
    └── 输出: _output/release-notes-v0.1.0.html
```

### 2.2 关键数据

| 指标 | 实测值 |
|------|--------|
| Issue 总数 | 21（17 打开/4 关闭） |
| 关闭率 | 19% |
| 综合评分 | 3.5/10 |
| 提交分类 | 22 新功能 / 15 Bug / 8 文档 |
| 贡献者 | 7 人 |

### 2.3 对应文件

- `skills/gitlink-community-ops/SKILL.md` — 设计规格
- `skills/gitlink-community-ops/scripts/community-ops-full.sh` — 串联脚本
- `skills/gitlink-community-ops/scripts/health-analyze.js` — 分析引擎

## 三、场景二：代码质量门禁

### 3.1 架构图

```
quality-gate-full.sh z2_cc gitlink-cli
│
├── Phase 1: PR 采集 (01-collect-prs.sh)
│   ├── gitlink-cli pr +list --state open
│   └── 逐个采集详情+变更文件
│
├── Phase 2: 深度审查 (02-deep-review.sh)
│   ├── 委托 pr-deep-review Skill
│   ├── Critical / Warning / Suggestion 三级
│   └── CodeReview 评分: 100 - Critical×20 - Warning×10 - Suggestion×3
│
├── Phase 3: 本地 CI 检查 (03-local-ci-check.sh)
│   ├── 本地 go build 编译验证
│   ├── 测试覆盖率
│   └── CI 评分: 全通过=100, 有失败=0（一票否决）
│
└── Phase 4: 门禁决策 (04-gate-decision.sh)
    ├── 质量总分 = CodeReview×40% + CI×30% + 设计一致性×30%
    ├── ≥70 + CI 通过 → 自动合并
    └── <70 → 修改建议
```

### 3.2 评分模型

| 维度 | 权重 | 评分规则 |
|------|------|----------|
| CodeReview | 40% | 起始 100，Critical -20 / Warning -10 / Suggestion -3 |
| CI 状态 | 30% | 全通过=100，有失败=0（一票否决） |
| 设计一致性 | 30% | PR 描述与代码变更匹配度 |

### 3.3 对应文件

- `skills/gitlink-quality-gate/SKILL.md`
- `skills/gitlink-quality-gate/scripts/quality-gate-full.sh`（80 行）
- `skills/gitlink-quality-gate/scripts/03-local-ci-check.sh` — 本地 CI 检查

## 四、场景三：项目一键初始化

### 4.1 架构图

```
project-bootstrap-full.sh
│
├── Phase 1: 解析需求 + 创建仓库 (01-parse-and-create-repo.sh)
│   ├── AI 从 PROJECT_DESC 提取 name/desc/lang/license
│   ├── 输出: _output/project-spec.json
│   └── gitlink-cli repo +create
│
├── Phase 2: 生成项目骨架 (02-generate-skeleton.sh)
│   ├── skeleton-gen.js 按语言生成模板
│   │   ├── README.md
│   │   ├── LICENSE (MIT/Apache/GPL)
│   │   ├── .gitignore (Go/Python/JS 差异化)
│   │   └── CI 配置 (建木 YAML)
│   └── gitlink-cli file +batch 推送
│
└── Phase 3: Issue + 里程碑 (03-create-issues-milestones.sh)
    ├── gitlink-cli milestone +create v0.1.0
    ├── gitlink-cli label +create (good-first-issue/enhancement/bug)
    └── gitlink-cli issue +create × 3
```

### 4.2 对应文件

- `skills/gitlink-project-bootstrap/SKILL.md`
- `skills/gitlink-project-bootstrap/scripts/project-bootstrap-full.sh`（61 行）
- `skills/gitlink-project-bootstrap/scripts/skeleton-gen.js` — 骨架生成引擎
- `.devops/项目初始化流水线.yml`（手动触发）

## 五、场景四：多仓库协同

### 5.1 架构图

```
multi-repo-full.sh
│ REPOS="z2_cc/gitlink-cli,z2_cc/gitlink-bisync"
│
├── Phase 1: 统一 Issue 追踪 (01-unified-issue-tracker.sh)
│   ├── 遍历 REPOS 采集 open Issue
│   ├── 标题相似度匹配 (Jaccard >0.5)
│   └── 识别跨仓库关联 Issue
│
├── Phase 2: PR 看板 (02-pr-dashboard.sh)
│   ├── 采集 open/merged PR
│   ├── 识别长期未合并 PR (>30天)
│   └── dashboard-gen.js 生成看板
│
└── Phase 3: Release 协调 (03-release-coordination.sh)
    ├── 汇总各仓库最新版本号+发布日期
    ├── 版本对齐分析 (哪个落后)
    └── 协调发布建议
```

### 5.2 对应文件

- `skills/gitlink-multi-repo-coordination/SKILL.md`
- `skills/gitlink-multi-repo-coordination/scripts/multi-repo-full.sh`（70 行）
- `skills/gitlink-multi-repo-coordination/scripts/dashboard-gen.js` — 看板引擎
- `.devops/多仓库协同流水线.yml`（手动触发）

## 六、场景五：贡献者成长体系

### 6.1 架构图

```
contributor-growth-full.sh z2_cc gitlink-cli
│
├── Phase 1: 贡献活动追踪 (01-track-activity.sh)
│   ├── contributors-stat 代码统计
│   ├── commit 近期提交 (按 author 聚合)
│   ├── pr 已合并 (按 user 聚合)
│   └── issue 已关闭 (按 assignee 聚合)
│
├── Phase 2: 排行 + 段位 (02-rank-and-tier.sh)
│   ├── growth-analyze.js 计算成长分
│   │   成长分 = commits×1 + mergedPR×5 + closedIssue×3 + (首次?+10)
│   ├── 排名排序
│   └── 段位划分: 🌱新芽(0-9) → 🌿新星(10-29) → 🌳中坚(30-79) → 🏆核心(80+)
│
└── Phase 3: 自动颁发徽章 (03-award-badges.sh)
    ├── 达段位 → 创建致谢 Issue
    ├── 颁发徽章评论
    └── 新人发 good-first-issue 引导
```

### 6.2 成长分计算示例

| 贡献者 | commits | mergedPR | closedIssue | 首次 | 成长分 | 段位 |
|--------|---------|----------|-------------|------|--------|------|
| alice | 25 | 8 | 4 | 否 | 25+40+12=77 | 🌳 中坚 |
| bob | 6 | 2 | 1 | 否 | 6+10+3=19 | 🌿 新星 |
| carol | 3 | 1 | 0 | 是 | 3+5+0+10=18 | 🌿 新星 |

### 6.3 对应文件

- `skills/gitlink-contributor-growth/SKILL.md`
- `skills/gitlink-contributor-growth/scripts/contributor-growth-full.sh`（56 行）
- `skills/gitlink-contributor-growth/scripts/growth-analyze.js` — 分析引擎
- `.devops/贡献者成长体系流水线.yml`（定时触发）

## 七、DevOps 流水线总览

| 流水线 | 触发方式 | 对应场景 | 文件 |
|--------|----------|----------|------|
| 构建流水线 | push | CLI 编译验证 | 构建流水线.yml |
| 项目初始化 | 手动 | 场景三 | 项目初始化流水线.yml |
| 多仓库协同 | 手动 | 场景四 | 多仓库协同流水线.yml |
| 贡献者成长 | 定时 | 场景五 | 贡献者成长体系流水线.yml |

社区运营（场景一）和代码质量门禁（场景二）通过手动执行脚本运行，未接入 DevOps 流水线。所有流水线配置 DRY_RUN 默认安全模式，SSH 密钥用 `((work_together.ssh_key))` 密文引用，可在 GitLink DevOps 平台一键复现。

— 文档完 —
