---
name: gitlink-onboard
version: 2.0.0
description: "新人引导：通过 AI 语义分析识别适合新手的 Good First Issue，调用 CLI 添加引导评论。当用户需要识别新手友好 issue 并欢迎新贡献者时触发。"
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli onboard --help"
---

# gitlink-onboard（新人引导）

**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 写入/删除操作前，务必先确认用户意图。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**

> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)

## 运行模式

| 模式 | 说明 | 需要认证 |
|------|------|----------|
| AI 分析模式（推荐） | AI 读取所有 open issue，通过语义分析识别 Good First Issue，展示结果后由用户选择并调用 CLI | 是 |
| 直接模式 | 用户已明确指定 issue 编号，直接调用 `onboard +welcome --issues` | 是 |
| 标签模式（旧） | 通过 `--tag` 参数按标签过滤 | 是 |

## AI 分析模式工作流（5 步）

当用户说 "帮我识别新人友好 issue" / "good first issue" / "欢迎新人" 等触发词时，
执行以下 5 步流程：

### 第 1 步：获取所有 Open Issue

```bash
gitlink-cli issue +list --state open --limit 100 --format json
```

解析 JSON 输出，提取每个 issue 的 `project_issues_index`（编号）和 `subject`（标题）。

### 第 2 步：逐一获取详情

对每个 issue 调用：

```bash
gitlink-cli issue +view --number N --format json
```

提取：标题、描述（body/description）、标签列表。

如果 issue 数量较多（>20），分批处理，每批 10-15 个，先分析标题再决定是否需要完整详情。

### 第 3 步：AI 语义分析

基于 LLM 对 issue 内容的理解，判断是否适合新手。**不使用硬编码规则**，而是基于语义理解。

**正面信号（适合新手）：**
- 标题清晰，范围明确
- 简单修复类任务（拼写错误、文档补充、配置调整）
- 分离了多个子任务的复杂大 issue 的子任务
- 涉及单个文件或少量文件的修改
- 维护者明确标注了实现方向

**负面信号（不适合新手）：**
- 涉及架构重构或核心模块改动
- 需要数据库迁移或复杂 SQL 变更
- 安全相关修复
- 需要同时修改多个模块
- 缺乏上下文说明，需求模糊
- 已有大量评论讨论但无共识
- 需要深入了解项目内部逻辑

分析每个 issue 后归类为：

| 分类 | 说明 |
|------|------|
| `good-first-issue` | 明确适合新手，范围小、有清晰实现路径 |
| `maybe` | 部分条件符合，但有不确定因素 |
| `not-recommended` | 不适合新手 |

### 第 4 步：展示结果并确认

以表格形式呈现分析结果：

| # | 标题 | 判断 | 理由 |
|---|------|------|------|
| 3 | Fix typo in README | good-first-issue | 文档类、单文件、无依赖 |
| 7 | Add input validation | good-first-issue | 边界清晰、常见模式 |
| 12 | Refactor auth module | not-recommended | 核心安全模块、影响面广 |
| 15 | Update API docs | good-first-issue | 文档补充、无风险 |

然后询问用户选择：

> 共识别 N 个候选 issue。请选择操作：
> A. 为所有 `good-first-issue` 添加引导评论
> B. 手动指定（输入 issue 编号，逗号分隔）
> C. 取消

### 第 5 步：调用 CLI 添加评论

根据用户选择，生成并执行命令：

```bash
# 选项 A
gitlink-cli onboard +welcome --issues "3,7,15"

# 选项 B（用户输入 "7,15"）
gitlink-cli onboard +welcome --issues "7,15"
```

建议首次使用 `--dry-run` 预览：

```bash
gitlink-cli onboard +welcome --issues "3,7,15" --dry-run
```

## 直接模式：手动指定 Issue

用户已知 issue 编号时直接调用：

```bash
# 为指定 issue 添加引导评论
gitlink-cli onboard +welcome --issues "5,8,12"

# 预览模式
gitlink-cli onboard +welcome --issues "5,8,12" --dry-run

# 自定义欢迎消息
gitlink-cli onboard +welcome --issues "5" --template "欢迎新人！请先阅读 README。"
```

## CLI 工作原理

`onboard +welcome` 命令的两种路径：

1. **`--issues` 路径（优先）**：直接获取指定编号的 issue，跳过标签解析
2. **`--tag` 路径（向后兼容）**：按标签名过滤 issue

两个路径共享：
- 每个 issue 检查是否已有引导评论（通过 `<!-- gitlink-cli:onboard -->` 标记）
- `--dry-run` 逐条确认
- 重复运行不重复添加评论
- 自定义 `--template`（`{login}` 替换为仓库所有者）

## 注意事项

- `--issues` 和 `--tag` 同时指定时，`--issues` 优先生效
- 需要仓库管理员或 write 权限
- 建议 AI 分析前先了解项目领域和技术栈，提高判断准确度
- AI 分析基于 LLM 语义理解，不是硬编码规则——做判断时给出明确的正面/负面理由

## 相关命令

| 命令 | 说明 |
|------|------|
| `gitlink-cli issue +list --state open --format json` | 获取所有 open issue |
| `gitlink-cli issue +view --number N --format json` | 查看 issue 详情 |
| `gitlink-cli onboard +welcome --issues "N"` | 为指定 issue 添加引导评论 |
