gitlink-cli/skills/gitlink-onboard/SKILL.md

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

gitlink-onboard（新人引导）

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

前置条件： 先阅读 ../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

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

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

第 2 步：逐一获取详情

对每个 issue 调用：

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 添加评论

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

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

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

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

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

直接模式：手动指定 Issue

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

# 为指定 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 添加引导评论