feat(skills): add gitlink-newcomer skill
This commit is contained in:
parent
b45241dcda
commit
28db64531b
|
|
@ -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) — 认证、全局参数、安全规则
|
||||
|
|
@ -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）。采集失败时脚本返回非零退出码并打印原因。
|
||||
|
|
@ -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`），可按项目习惯调整。
|
||||
Loading…
Reference in New Issue