# 场景 2：科研热点追踪与知识图谱构建

> **执行方式：AI Agent 直接执行**（无脚本，需语义理解和关系推断）

## 目标

按关键词搜索 GitLink 上的科研仓库，AI 分析仓库内容后构建领域知识图谱，识别热点趋势，生成 JSON + HTML 力导向图可视化。

## 参数获取

向用户询问：
1. **关键词**（必需）：逗号分隔，如 "LLM,RAG,Agent"
2. **每个关键词搜索数**（可选，默认 5，最多 10）
3. **是否限制组织**（可选）

## Agent 执行步骤

### Step 1: 搜索仓库

对每个关键词调用：

```bash
gitlink-cli search +repos --keyword "<keyword>" --limit <N> --format json
```

合并所有结果，按 `full_name` 去重。同一仓库可能被多个关键词命中（说明领域关联强）。

API 返回结构：`{ok, data: {projects: [...]}}`

### Step 2: 获取每个仓库的深度数据

对每个仓库（上限 20 个）获取：

```bash
gitlink-cli repo +info --owner <o> --repo <r> --format json
gitlink-cli release +list --owner <o> --repo <r> --limit 3 --format json
gitlink-cli repo +members --owner <o> --repo <r> --limit 20 --format json
```

### Step 3: AI 语义分析（核心）

**不要机械匹配，需要 AI 理解：**

1. **领域主题提取**：阅读每个仓库的 description，从中提取真正的科研领域关键词（不是文件后缀或框架名），去重去噪
2. **仓库类型判断**：是论文复现代码 / 工具库 / 数据集 / 实验脚本 / 教学材料？
3. **趋势方向**：比较各仓库的最近更新时间、Issue 活跃度，判断 rising / stable / declining
4. **关系推断**：
   - `has_topic`：仓库 ↔ 领域主题
   - `related_to`：同一主题下的仓库对，证据写明共同主题
   - `contributes_to`：成员 ↔ 仓库
   - `similar_tech`：技术栈重叠的仓库对

### Step 4: 构建知识图谱 JSON

按以下结构输出到 `output/knowledge-graph-{date}.json`：

```json
{
  "metadata": {
    "generated_at": "<ISO时间>",
    "search_keywords": ["关键词列表"],
    "total_repos_scanned": <数字>,
    "total_contributors_found": <数字>,
    "total_edges_inferred": <数字>
  },
  "nodes": [
    {"id": "topic:<keyword>", "type": "topic", "label": "<关键词>", "category": 2, "symbolSize": 30},
    {"id": "repo:<owner>/<repo>", "type": "repo", "label": "<repo名>",
     "desc": "<描述截断100字>", "stars": <数字>, "language": "<语言>",
     "hotness": <评分>, "trend": "rising|stable|declining",
     "category": 0, "symbolSize": <15+hotness*0.5>},
    {"id": "contributor:<login>", "type": "contributor", "label": "<login>",
     "category": 1, "symbolSize": 20}
  ],
  "edges": [
    {"source": "repo:...", "target": "topic:...", "type": "has_topic", "weight": 1.0, "evidence": "关键词匹配"},
    {"source": "repo:...", "target": "repo:...", "type": "related_to", "weight": 0.5, "evidence": "共同主题: LLM"},
    {"source": "contributor:...", "target": "repo:...", "type": "contributes_to", "weight": 0.8}
  ]
}
```

### Step 5: 生成 HTML 可视化

使用 `workflows/templates/knowledge-graph.html` 模板，替换以下占位符：

| 占位符 | 内容 |
|--------|------|
| `{{REPORT_DATE}}` | 当前日期 |
| `{{KEYWORDS}}` | 搜索关键词串 |
| `{{TOTAL_REPOS}}` | 仓库节点数 |
| `{{TOTAL_CONTRIBUTORS}}` | 贡献者节点数 |
| `{{TOTAL_TOPICS}}` | 主题节点数 |
| `{{TOTAL_EDGES}}` | 关系边总数 |
| `{{GRAPH_NODES}}` | nodes JSON（紧凑格式） |
| `{{GRAPH_EDGES}}` | edges JSON（紧凑格式） |
| `{{TABLE_ROWS}}` | 热度排行 HTML `<tr>` 行 |
| `{{HOTTEST_REPO}}` | 热度最高的仓库名 |

模板路径：`skills/gitlink-research/workflows/templates/knowledge-graph.html`

### Step 6: 输出摘要

用中文展示：
- 搜索了哪些关键词，找到几个仓库
- 热度 Top 5 排行榜（仓库名 + 热度 + 语言 + 趋势方向）
- 知识图谱规模：节点数、关系边数
- 主要发现：这个领域的活跃度/主流技术/热门方向

## 热度估算逻辑

由于 API 不直接返回 30 天数据，用以下方式估算：

```
hotness = stars*0.15 + forks*0.10 + open_issues*0.20 + member_count*0.20
        + releases*0.15 + (recency_30d?100:recency_90d?50:10)*0.20
```

趋势：最近 30 天更新 → rising，30-90 天 → stable，>90 天 → declining

## 注意事项

- 温度由 AI 判断，不要机械套公式
- 边标签（evidence）要有意义，不能只是"共同主题"这种空泛表述
- 主题列表控制在 10 个以内，质量胜于数量
- 如果模板文件不存在，直接用内联 HTML 生成
