From 28db64531b08653e6cfb9a2df1432b7ad6803848 Mon Sep 17 00:00:00 2001
From: Ct201314 <1195214305@qq.com>
Date: Sat, 6 Jun 2026 00:14:46 +0800
Subject: [PATCH] feat(skills): add gitlink-newcomer skill

---
 skills/gitlink-newcomer/SKILL.md              | 112 ++++++++++++++++++
 .../references/api-reference.md               |  64 ++++++++++
 skills/gitlink-newcomer/references/scoring.md |  42 +++++++
 3 files changed, 218 insertions(+)
 create mode 100644 skills/gitlink-newcomer/SKILL.md
 create mode 100644 skills/gitlink-newcomer/references/api-reference.md
 create mode 100644 skills/gitlink-newcomer/references/scoring.md

diff --git a/skills/gitlink-newcomer/SKILL.md b/skills/gitlink-newcomer/SKILL.md
new file mode 100644
index 0000000..fadabe0
--- /dev/null
+++ b/skills/gitlink-newcomer/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: gitlink-newcomer
+version: 1.0.0
+description: "新人引导：识别 good-first-issue、评估上手难度与友好度、为候选 Issue 生成个性化引导评论、产出新手任务看板，降低新贡献者参与门槛。当用户提到「适合新人的 Issue」「good first issue」「新手任务」「引导新贡献者」「降低参与门槛」「new contributor」时触发。"
+metadata:
+  requires:
+    bins: ["gitlink-cli"]
+    optional_bins: ["python"]
+  cliHelp: "gitlink-cli issue --help"
+---
+
+# gitlink-newcomer（新人引导）
+
+**CRITICAL — 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
+**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
+**CRITICAL — 发布引导评论属于写操作，执行前必须征得用户确认。本技能默认只生成评论内容，不自动发布。**
+
+> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证与全局参数。
+
+## 何时使用本技能
+
+- 维护者想为新贡献者整理一份「适合上手的 Issue」清单
+- 用户问「这个项目有哪些 good first issue / 新手任务」
+- 想为某个简单 Issue 自动生成欢迎与引导评论，降低新人门槛
+- 需要评估某个 Issue 对新手的友好程度
+
+## 何时不使用
+
+- 只是普通地列出全部 Issue → 用 `gitlink-issue`
+- 复杂的项目健康度/协作分析 → 用 `gitlink-health` / `gitlink-insight`
+
+## 能力概览
+
+| 能力 | 说明 |
+|------|------|
+| good-first-issue 识别 | 综合标签、标题/正文关键词、描述长度、讨论热度等多信号识别 |
+| 友好度评分 | 为每个 Issue 输出 0-100 的新手友好度分与难度等级（入门/较易/中等/进阶） |
+| 个性化引导 | 为候选 Issue 生成包含上手步骤、Fork/PR 流程的欢迎评论 |
+| 新手任务看板 | 汇总候选 Issue 为 Markdown 看板，可贴到 Wiki 或 README |
+
+## 工作流 1：生成新手任务看板
+
+### 方式 A：用配套脚本（推荐，一步到位）
+
+```bash
+# 扫描仓库 Issue，输出新手任务看板（Markdown）
+python scripts/newcomer.py --owner Gitlink --repo gitlink-cli
+
+# 输出 JSON 供 Agent 进一步处理（含每个候选的引导文案）
+python scripts/newcomer.py --owner Gitlink --repo gitlink-cli --format json
+
+# 写入文件
+python scripts/newcomer.py --owner Gitlink --repo gitlink-cli --output board.md
+```
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `--owner` | string | 是* | 仓库所有者（*或用 `--slug`） |
+| `--repo` | string | 是* | 仓库名称 |
+| `--slug` | string | 否 | `owner/repo` 或完整 URL，替代 owner/repo |
+| `--issue` | int | 否 | 只为指定 Issue 编号（web 序号）生成引导 |
+| `--limit` | int | 否 | 扫描 Issue 数量上限，默认 50 |
+| `--format` | string | 否 | `markdown`（默认）或 `json` |
+| `--output` | string | 否 | 输出文件路径，缺省打印到标准输出 |
+
+### 方式 B：用 gitlink-cli 命令手动采集
+
+当无法运行脚本时，Agent 可用以下命令采集数据后自行分析：
+
+```bash
+# 1. 获取开放 Issue 列表
+gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state open --format json
+
+# 2. 查看某个 Issue 详情（--number 用 web 序号，不是全局 id）
+gitlink-cli issue +view --owner Gitlink --repo gitlink-cli --number 12 --format json
+
+# 3. 查看仓库标签，确认是否有 good first issue 类标签
+gitlink-cli label +list --owner Gitlink --repo gitlink-cli --format json
+```
+
+识别规则建议：
+- 带 `good first issue` / `beginner` / `新手` 等标签 → 强新手信号
+- 标题/正文含 `typo` / `docs` / `文档` / `test` / `翻译` 等 → 易上手信号
+- 含 `refactor` / `架构` / `并发` / `性能` 等 → 高难度信号
+
+## 工作流 2：为单个 Issue 生成引导评论
+
+```bash
+# 生成引导文案（不发布）
+python scripts/newcomer.py --owner Gitlink --repo gitlink-cli --issue 12
+
+# 确认文案后，由用户决定是否发布为评论（写操作，需确认）
+gitlink-cli issue +comment --owner Gitlink --repo gitlink-cli --number 12 -b "<引导文案>"
+```
+
+## API 注意事项
+
+- **ID 混淆**：GitLink 的 Issue 列表接口（`issue +list`）通常只返回全局数据库 `id`，不含 web 序号。发评论 / 关联 Issue 时，`issue +comment` 的 `--number` 需要 web 序号（URL 中显示的编号），不要把全局 id 当 web 序号用。
+- **写操作确认**：`issue +comment` 会真实发布评论，执行前务必向用户确认内容与目标 Issue。
+- 数据采集全程只读，脚本默认不发布任何内容。
+
+## 输出示例
+
+参见 [`examples/`](examples/) 目录下的真实运行产物（新手看板、单 Issue 引导）。
+
+## References
+
+- [api-reference.md](references/api-reference.md) — 采集的接口、字段与 ID 混淆说明
+- [scoring.md](references/scoring.md) — 新手友好度评分规则与信号词表
+- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证、全局参数、安全规则
diff --git a/skills/gitlink-newcomer/references/api-reference.md b/skills/gitlink-newcomer/references/api-reference.md
new file mode 100644
index 0000000..1e37d2e
--- /dev/null
+++ b/skills/gitlink-newcomer/references/api-reference.md
@@ -0,0 +1,64 @@
+# gitlink-newcomer API 参考
+
+> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本技能识别 good-first-issue 所依赖的 GitLink 接口与字段。数据采集全程只读。
+
+## 采集的接口
+
+### Issue 列表
+
+```
+GET /:owner/:repo/issues.json?page={page}&limit={limit}
+# 或经 gitlink-cli：
+gitlink-cli issue +list --owner <owner> --repo <repo> --state open --format json
+```
+
+返回的 `issues[]` 中本技能使用的字段：
+
+| 字段 | 说明 | 用途 |
+|------|------|------|
+| `id` | 全局数据库 ID | 去重、展示（**非** web 序号） |
+| `name` / `subject` | Issue 标题 | 关键词分析、展示 |
+| `description` | 正文 | 关键词分析、长度评估 |
+| `issue_tags` / `labels` | 标签 | good-first-issue 标签信号 |
+| `comment_journals_count` / `journals_count` | 评论数 | 讨论热度评估 |
+| `author_login` / `author_name` | 作者 | 展示 |
+
+### Issue 详情（单个）
+
+```
+GET /:owner/:repo/issues/{number}.json
+# 或：
+gitlink-cli issue +view --owner <owner> --repo <repo> --number {number} --format json
+```
+
+`{number}` 为 web 序号（URL 中的编号）。详情接口可拿到更完整的字段。
+
+## ID 混淆（重要）
+
+GitLink 存在两种 ID：
+
+| 名称 | 来源 | 用途 |
+|------|------|------|
+| 全局数据库 `id` | Issue 列表接口 | 仅去重 / 内部引用 |
+| web 序号（`project_issues_index` / `number`） | 单 Issue 详情、web URL | 发评论、PR 关联、`issue +comment --number` |
+
+本技能的处理：
+- 列表接口只返回全局 `id` 时，看板以 `id:xxx` 形式标注，**不**伪装成 web 序号；
+- 生成引导评论时，若无可靠 web 序号则用 Issue 标题引用，避免误导；
+- 发布评论用 `gitlink-cli issue +comment --number <web序号>`。
+
+## 写操作
+
+发布引导评论是写操作：
+
+```
+gitlink-cli issue +comment --owner <owner> --repo <repo> --number <web序号> -b "<引导文案>"
+```
+
+执行前必须征得用户确认；本技能默认只生成文案，不自动发布。
+
+## 错误处理
+
+沿用 gitlink-shared 的错误码（401 重新登录 / 403 权限 / 404 检查 owner/repo）。采集失败时脚本返回非零退出码并打印原因。
diff --git a/skills/gitlink-newcomer/references/scoring.md b/skills/gitlink-newcomer/references/scoring.md
new file mode 100644
index 0000000..9971e5a
--- /dev/null
+++ b/skills/gitlink-newcomer/references/scoring.md
@@ -0,0 +1,42 @@
+# 新手友好度评分规则
+
+本技能用一套可解释的规则为每个 Issue 打出 0-100 的新手友好度分，不依赖大模型。
+
+## 评分模型
+
+基准分 **50**，在此基础上根据信号加减：
+
+| 信号 | 分值 | 说明 |
+|------|:----:|------|
+| 命中新手友好标签 | +35 | `good first issue` / `beginner` / `新手` / `easy` 等 |
+| 命中高难度标签 | -30 | `hard` / `complex` / `advanced` / `困难` 等 |
+| 命中易上手关键词 | +7/词（上限 +20） | `typo` / `docs` / `文档` / `test` / `翻译` 等 |
+| 命中高难度关键词 | -10/词（上限 -25） | `refactor` / `架构` / `并发` / `性能` / `安全` 等 |
+| 描述长度适中（30-600） | +5 | 适中描述更易上手 |
+| 描述过长（>1500） | -8 | 往往较复杂 |
+| 讨论过多（评论 >15） | -8 | 可能存在分歧 |
+
+最终分数裁剪到 [0, 100]。
+
+## 难度等级
+
+| 友好度分 | 难度等级 |
+|:--------:|:--------:|
+| ≥ 75 | 入门 |
+| 55 - 74 | 较易 |
+| 40 - 54 | 中等 |
+| < 40 | 进阶 |
+
+友好度 ≥ 55 的 Issue 被列为新手候选（`is_good_first = true`）。
+
+## 信号词表（节选）
+
+**新手友好标签**：good first issue、good-first-issue、first-timers-only、beginner、beginner-friendly、easy、starter、新手、新手友好、入门、简单
+
+**易上手关键词**：typo、document、docs、readme、comment、translation、rename、format、lint、test、example、i18n、文档、注释、拼写、翻译、示例、格式
+
+**高难度关键词**：refactor、architecture、performance、concurrency、race、security、deadlock、memory leak、breaking change、重构、架构、性能、并发、安全、死锁、内存
+
+## 可调整性
+
+词表与阈值集中在 `scripts/newcomer.py` 顶部常量（`GOOD_FIRST_LABELS` / `EASY_KEYWORDS` / `HARD_KEYWORDS` / `HARD_LABELS`），可按项目习惯调整。