# 子任务三 & 子任务四 — 工作交接文档

> 最后更新：2026-06-30
> 提交记录：`378d8f1` — 46 files changed, 5493 insertions
> Issue：[#19](https://gitlink.org.cn/z2_cc/gitlink-cli/issues/19) / [#20](https://gitlink.org.cn/z2_cc/gitlink-cli/issues/20)

---

## 一、总体架构

```
e:/gitlink-cli/gitlink-cli/
├── skills/
│   ├── gitlink-community-ops/        # 子任务三 - 场景A
│   ├── gitlink-quality-gate/         # 子任务三 - 场景B
│   ├── gitlink-research-insight/     # 子任务四 - 模块C
│   ├── gitlink-research-hotspot/     # 子任务四 - 模块D
│   └── gitlink-shared/scripts/      # 共享工具
│       ├── detect-cli.sh            # CLI 版本自动检测
│       └── md-to-html.js            # Markdown→HTML 转换器
├── doc/
│   ├── sub-task3-scenario-a/        # 场景A 架构图+报告
│   ├── sub-task3-scenario-b/        # 场景B 架构图+报告
│   ├── sub-task4-module-c/          # 模块C 架构图+报告
│   └── sub-task4-module-d/          # 模块D 架构图+报告
├── .devops/
│   ├── 构建流水线.yml               # 原有（修改）
│   ├── 社区运营流水线.yml            # 新增
│   └── 代码质量门禁流水线.yml        # 新增
└── CLAUDE.md                        # 修改（新增 skill 映射）
```

---

## 二、子任务三：端到端自动化工作流

### 场景A：社区运营自动化

**三阶段流水线：** Issue 分拣 → 社区周报 → Release Notes

| 文件 | 作用 |
|------|------|
| `skills/gitlink-community-ops/SKILL.md` | Skill 定义，引用 issue-triage/project-health/release-auto |
| `examples/community-ops-workflow.md` | 端到端工作流示例 |
| `scripts/01-issue-triage.sh` | Phase 1：采集 Issue → 关键词权重分析 → 建议标签 |
| `scripts/02-weekly-health-report.sh` | Phase 2：采集 Issue/PR/Commit/Milestone → 生成周报 |
| `scripts/03-auto-release-notes.sh` | Phase 3：获取提交历史 → 分类 → 生成 Release Notes |
| `scripts/community-ops-full.sh` | 全流程编排（依次调用三阶段） |
| `scripts/health-analyze.js` | 周报数据分析引擎（计算关闭率/评分/改进建议） |
| `scripts/release-analyze.js` | Release Notes 分析引擎（按 Conventional Commits 分类） |

**运行方式：**
```bash
cd e:/gitlink-cli/gitlink-cli
DRY_RUN=true bash skills/gitlink-community-ops/scripts/community-ops-full.sh z2_cc gitlink-cli
```

### 场景B：代码质量看门人

**四阶段门禁：** PR 采集 → 深度审查 → CI 检查 → 质量评分决策

| 文件 | 作用 |
|------|------|
| `skills/gitlink-quality-gate/SKILL.md` | Skill 定义 |
| `examples/quality-gate-workflow.md` | 工作流示例 |
| `scripts/01-collect-prs.sh` | Phase 1：列出待审 PR |
| `scripts/02-deep-review.sh` | Phase 2：获取 PR 详情/文件/diff/评审历史 |
| `scripts/03-ci-check.sh` | Phase 3：检查 CI 构建状态 |
| `scripts/04-quality-gate-decision.sh` | Phase 4：计算评分 → 自动合并/给修改建议 |
| `scripts/quality-gate-full.sh` | 全流程编排（遍历所有待审 PR） |

**评分模型：**
```
质量总分 = CodeReview×40% + CI状态×30% + 设计一致性×30%
门槛：≥70 分且 CI 通过 → 自动合并
```

**运行方式：**
```bash
DRY_RUN=true bash skills/gitlink-quality-gate/scripts/quality-gate-full.sh z2_cc gitlink-cli
```

---

## 三、子任务四：应用 GitLink 辅助科研

### 模块C：科研项目洞悉

**流程：** 8 维数据采集 → 4 维度评分 → 结构化报告

| 文件 | 作用 |
|------|------|
| `skills/gitlink-research-insight/SKILL.md` | Skill 定义 |
| `examples/research-insight-workflow.md` | 工作流示例 |
| `scripts/01-collect-repo-data.sh` | 采集 repo/commit/issue/pr/collaborator/topics/languages |
| `scripts/02-analyze-contributions.sh` | 调用 analyze.js 计算评分 |
| `scripts/analyze.js` | **数据分析引擎**：读取 JSON → 计算成熟度/文档/贡献/社区评分 → 生成报告 |
| `scripts/research-insight-full.sh` | 全流程编排 |

**评分维度：**
- 成熟度（25%）：年龄 + Star + Fork + 更新频率
- 文档质量（20%）：README + License + CI
- 贡献模式（30%）：贡献者数 + 提交频率
- 社区健康度（25%）：Issue 关闭率 + PR 合并率

**运行方式：**
```bash
bash skills/gitlink-research-insight/scripts/research-insight-full.sh z2_cc gitlink-cli
```

### 模块D：热点追踪与知识图谱

**流程：** 多关键词搜索 → 数据丰富 → 知识图谱 → 趋势报告

| 文件 | 作用 |
|------|------|
| `skills/gitlink-research-hotspot/SKILL.md` | Skill 定义 |
| `examples/hotspot-workflow.md` | 工作流示例 |
| `scripts/01-search-repos.sh` | 多关键词搜索 + 去重 + 数据丰富 |
| `scripts/02-build-knowledge-graph.sh` | 调用 hotspot-analyze.js + kg-to-html.js |
| `scripts/hotspot-analyze.js` | **数据分析引擎**：提取实体关系，生成知识图谱和趋势报告 |
| `scripts/kg-to-html.js` | **交互式可视化**：生成可缩放/拖拽/高亮的 HTML 图谱 |
| `scripts/hotspot-tracker-full.sh` | 全流程编排 |

**运行方式：**
```bash
bash skills/gitlink-research-hotspot/scripts/hotspot-tracker-full.sh "machine learning" "深度学习" "自然语言处理"
```

---

## 四、共享工具

| 文件 | 作用 |
|------|------|
| `skills/gitlink-shared/scripts/detect-cli.sh` | **CLI 版本检测**：优先使用本地编译版本（支持 commit +list 等完整命令），回退系统 PATH 版本 |
| `skills/gitlink-shared/scripts/md-to-html.js` | **报告可视化**：将任意 Markdown 报告转为带评分环、表格着色、响应式布局的 HTML 页面 |

---

## 五、报告文档

| 文档路径 | 内容 |
|----------|------|
| `doc/sub-task3-scenario-a/架构图` | Mermaid 社区运营流程 |
| `doc/sub-task3-scenario-a/新需求构思报告` | 需求背景、详述、技术方案、风险评估 |
| `doc/sub-task3-scenario-a/变更影响分析及测试报告` | 变更范围、测试计划、风险、结论 |
| `doc/sub-task3-scenario-b/架构图` | Mermaid 质量门禁流程 + 评分模型 |
| `doc/sub-task3-scenario-b/新需求构思报告` | 同上 |
| `doc/sub-task3-scenario-b/变更影响分析及测试报告` | 同上 |
| `doc/sub-task4-module-c/架构图` | 科研洞察四层架构 |
| `doc/sub-task4-module-c/research-insight-report` | 洞察报告模板 |
| `doc/sub-task4-module-d/架构图` | 热点追踪三层架构 |
| `doc/sub-task4-module-d/hotspot-trend-report` | 趋势报告模板 |
| `doc/sub-task4-module-d/knowledge-graph` | 知识图谱说明 |

---

## 六、DevOps 流水线

| 文件 | 触发 | 功能 |
|------|------|------|
| `.devops/构建流水线.yml` | Push 触发 | Go 编译验证 |
| `.devops/社区运营流水线.yml` | 定时触发 | SSH 执行 community-ops-full.sh |
| `.devops/代码质量门禁流水线.yml` | PR 事件 | SSH 执行 quality-gate-full.sh |

> ⚠️ 需要到 GitLink 仓库开启 DevOps 引擎并配置 SSH 密钥才能运行

---

## 七、常见问题

### Q1：如何让 commit +list 等命令可用？
当前系统 PATH 的 npm 版 CLI 不包含全部命令。脚本已自动检测本地编译版本，只需编译即可：
```bash
cd e:/gitlink-cli/gitlink-cli && go build -o gitlink-cli.exe .
```

### Q2：脚本默认会修改数据吗？
**不会。** 所有写操作（issue +update / pr +merge / release +create）默认受 `DRY_RUN=true` 保护。
需要实际执行时：
```bash
DRY_RUN=false bash scripts/xxx.sh <owner> <repo>
```

### Q3：输出文件在哪？
所有脚本的输出保存在各自 `scripts/_output/` 目录下，包含 JSON 数据、Markdown 报告和 HTML 可视化。
`.gitignore` 已忽略 `_output/` 目录。

### Q4：如何查看可视化报告？
```bash
# 科研洞察报告
explorer "skills/gitlink-research-insight/scripts/_output/research-insight-report.html"

# 社区周报
explorer "skills/gitlink-community-ops/scripts/_output/weekly-health-report.html"

# Release Notes
explorer "skills/gitlink-community-ops/scripts/_output/release-notes-v0.1.0.html"

# 知识图谱（交互式）
explorer "skills/gitlink-research-hotspot/scripts/_output/knowledge-graph-machine learning.html"

# 热点趋势报告
explorer "skills/gitlink-research-hotspot/scripts/_output/hotspot-trend-report-machine learning.html"
```

---

## 八、文件清单（46 个文件）

### 新增文件（44 个）
```
skills/gitlink-community-ops/
├── SKILL.md
├── examples/community-ops-workflow.md
└── scripts/
    ├── 01-issue-triage.sh
    ├── 02-weekly-health-report.sh
    ├── 03-auto-release-notes.sh
    ├── community-ops-full.sh
    ├── health-analyze.js
    └── release-analyze.js

skills/gitlink-quality-gate/
├── SKILL.md
├── examples/quality-gate-workflow.md
└── scripts/
    ├── 01-collect-prs.sh
    ├── 02-deep-review.sh
    ├── 03-ci-check.sh
    ├── 04-quality-gate-decision.sh
    └── quality-gate-full.sh

skills/gitlink-research-insight/
├── SKILL.md
├── examples/research-insight-workflow.md
└── scripts/
    ├── 01-collect-repo-data.sh
    ├── 02-analyze-contributions.sh
    ├── analyze.js
    └── research-insight-full.sh

skills/gitlink-research-hotspot/
├── SKILL.md
├── examples/hotspot-workflow.md
└── scripts/
    ├── 01-search-repos.sh
    ├── 02-build-knowledge-graph.sh
    ├── hotspot-analyze.js
    ├── hotspot-tracker-full.sh
    └── kg-to-html.js

skills/gitlink-shared/scripts/
├── detect-cli.sh
└── md-to-html.js

doc/
├── sub-task3-scenario-a/
│   ├── architecture-diagram.md
│   ├── 新需求构思报告.md
│   └── 变更影响分析及测试报告.md
├── sub-task3-scenario-b/
│   ├── architecture-diagram.md
│   ├── 新需求构思报告.md
│   └── 变更影响分析及测试报告.md
├── sub-task4-module-c/
│   ├── architecture-diagram.md
│   └── research-insight-report.md
├── sub-task4-module-d/
│   ├── architecture-diagram.md
│   ├── hotspot-trend-report.md
│   └── knowledge-graph.md
└── sub-task34-交接文档.md              ← 本文件

.devops/
├── 社区运营流水线.yml
└── 代码质量门禁流水线.yml
```

### 修改文件（2 个）
```
.gitignore      — 添加 _output/ .cli-bin/ *.json 忽略规则
CLAUDE.md       — 添加 4 个新 skill 映射
```

---

*如有疑问，查看 Issue #19（子任务三）和 #20（子任务四）*
