Github Oss Ops

GitHub 开源项目运营

开源发布后的项目"AI 客服"：自动扫描 Issue/PR，智能分类、生成回复草稿、辅助审查、管理过期项、输出运营报告。

核心理念

• 读写分离：公开信息读取、分析和草稿可直接进行；评论、标签、关闭、合并、推送、设置和发布等外部写操作必须明确目标与内容，并在执行前获得批准
• 维护者视角：帮助个人维护者或小型团队高效管理项目，降低维护负担
• 渐进式运营：不需要一次配置全部，按需使用各功能模块
• 与 github-oss-prep 配合：oss-prep 负责发布，本技能负责发布后的日常运营
• 凭据零采集：不要求用户把 Token 发到聊天，不搜索用户目录或配置文件提取凭据，不打印、记录或写入凭据
• 能力发现优先：根据当前平台实际提供的 GitHub 连接、MCP、CLI 或 API 能力选择路径，不假定某个工具名永久存在

---

前置条件

公开仓库的只读扫描不要求认证。只有读取私有数据或执行写操作时才需要 GitHub 授权。

按以下优先级使用当前环境已经提供的能力：

1. 平台官方 GitHub 连接器或 GitHub 官方远程 MCP（OAuth）：由受信任界面完成授权。
2. 已认证的 GitHub CLI：先运行 gh auth status；未登录时让用户在受信任终端完成 gh auth login --web。
3. GitHub 官方本地 MCP Server：适合需要本地宿主或受控 toolsets 的环境。
4. Fine-grained PAT：仅在用户明确选择时使用，限定仓库、最小权限并设置有效期，由受信任的密码输入或环境管理接收。
5. 公开 REST API / 网页：作为只读或人工交接回退。

不得从用户主目录、编辑器配置、MCP JSON、Shell 历史或进程环境中主动寻找 Token；不得输出 Token 值。不得把 Classic PAT 描述为默认或最简单的推荐方案。

授权方式、最小权限、能力探测和回退流程见 [references/github-access-guide.md](references/github-access-guide.md)。

---

工作流程

Step 1: 确认目标仓库
    ↓
Step 2: 扫描（Issue/PR 状态概览）
    ↓
Step 3: Issue 分流（分类 + 标记 + 优先级评估）
    ↓
Step 4: 智能回复（生成回复草稿 → 用户确认 → 发送）
    ↓
Step 5: PR 审查辅助（读改动 + 生成审查意见）
    ↓
Step 6: 版本管理（PR 合并后 → semver 版本更新 → Release）
    ↓
Step 7: 过期管理（Stale Issue/PR 处理）
    ↓
Step 8: 运营报告（统计 + 健康评估 + 建议）
    ↓
Step 9: 自动化配置（按需生成 GitHub Actions 模板）

> 每一步都是独立可用的。用户可能只需要"帮我看看有没有新 Issue"（Step 2-3），不需要走完全流程。

---

Step 1: 确认目标仓库

如果用户没有指定仓库名，通过以下方式确认：

1. 检查当前工作目录是否是 git 仓库（git remote -v）
2. 如果是，提取 owner/repo 信息
3. 如果不是，询问用户要管理哪个仓库

确认仓库后，记录 owner/repo、默认分支、可见性和当前用户权限。若是公开仓库，先完成无需认证的只读工作；若是私有仓库，说明本技能仍可使用，但它不属于公开开源运营场景，且必须通过受信任连接获得授权。

---

Step 2: 扫描项目状态

2.1 获取 Issue/PR 概览

通过 MCP 工具或 API 获取以下数据：

| 数据 | 获取方式 | |------|----------| | 未关闭的 Issue 列表 | list_issues（state: open）或 GET /repos/{owner}/{repo}/issues | | 未关闭的 PR 列表 | list_pull_requests（state: open）或 GET /repos/{owner}/{repo}/pulls | | 最近 7 天的新 Issue | 按 created_at 过滤 | | 最近 7 天的新 PR | 按 created_at 过滤 | | 需要回复的 Issue | 无维护者评论的 open Issue |

2.2 输出状态摘要

## 仓库状态概览 — {owner}/{repo}

### 数据总览
- 未关闭 Issue：N 个（其中 N 个待分流）
- 未关闭 PR：N 个（其中 N 个待审查）
- 最近 7 天新增：N 个 Issue，N 个 PR

### 需要关注
- [ ] N 个 Issue 没有任何标签（待分流）
- [ ] N 个 Issue 超过 7 天未回复
- [ ] N 个 PR 等待审查

2.3 检查已有标签体系

读取仓库现有标签（GET /repos/{owner}/{repo}/labels），判断是否需要建立或优化标签体系。如果标签混乱或缺失，建议进入 Step 8 先配置标签体系。

---

Step 3: Issue 分流

> 核心操作：读取每个未分流的 Issue → 分类 → 建议标签和优先级 → 展示给用户确认 → 执行标记。

3.1 分类规则

读取 Issue 的标题和正文，根据以下信号判断类型：

| 信号 | 分类 | 建议标签 | |------|------|----------| | 提到"bug""错误""crash""不工作""无法" | Bug | type:bug | | 提到"建议""希望""能不能""feature" | 功能请求 | type:enhancement | | 提到"怎么""如何""请问""求助" | 使用问题 | type:question | | 提到"文档""README""说明" | 文档改进 | type:documentation | | 提到"漏洞""安全""security""vulnerability""XSS""SQL注入" | 安全漏洞 | type:security + priority:P0 | | 提到"重构""refactor""优化代码结构" | 重构 | type:refactor | | 提到"性能""慢""卡顿""performance""优化速度" | 性能问题 | type:performance | | 信息不足，无法判断 | 需要更多信息 | status:needs-info |

3.2 安全漏洞特殊处理

安全漏洞 Issue 不走常规分流流程，需要特殊处理：

1. 标记 type:security + priority:P0
2. 不在公开评论中确认或讨论漏洞细节
3. 引导提交者使用 GitHub Private Vulnerability Reporting
4. 关闭公开 Issue（或转为私密）
5. 在 Security Advisory 中跟踪

> 详细的安全漏洞处理流程和垃圾 Issue 处理见 references/triage-workflow.md。

3.3 优先级评估

| 优先级 | 判断标准 | 建议标签 | |--------|----------|----------| | P0 紧急 | 影响核心功能、安全漏洞、数据丢失 | priority:P0 | | P1 重要 | 影响较多用户、有明确的修复方案 | priority:P1 | | P2 一般 | 小问题、体验优化、不紧急 | priority:P2 | | P3 低 | 锦上添花、小众需求 | priority:P3 |

3.4 重复检测

对每个新 Issue，在已有 Issue 中搜索相似标题和关键词。如果发现疑似重复：

• 标出疑似重复的 Issue 编号
• 建议关闭并引用原始 Issue

3.5 分流结果展示

逐个 Issue 展示分析结果：

### Issue #{number}: {title}
- 提交者：@{user}（首次贡献 / 活跃贡献者）
- 分类：Bug / 功能请求 / 使用问题 / 文档 / 需要更多信息
- 建议优先级：P1
- 建议标签：type:bug, priority:P1
- 疑似重复：无 / 可能是 #{other_number} 的重复
- 建议操作：标记标签 + 回复 / 关闭 / 转 Discussion

用户确认后，调用 issue_write 添加标签，或调用 add_issue_comment 添加回复。

> 详细的标签体系、分流决策树和边界情况处理见 references/triage-workflow.md。

---

Step 4: 智能回复

> 核心原则：生成回复草稿 → 展示给用户 → 用户确认或修改 → 才调用 add_issue_comment 发送。

4.1 回复场景判断

| Issue 类型 | 回复策略 | |------------|----------| | Bug（可复现） | 确认问题 + 说明下一步（已在修复 / 需要更多信息） | | Bug（不可复现） | 请求环境信息（OS、版本、复现步骤） | | 功能请求（合理） | 感谢建议 + 评估可行性 + 标记 help wanted 或加入计划 | | 功能请求（不合适） | 礼貌拒绝 + 说明原因（不在项目范围内） | | 使用问题 | 给出解答 + 引导到文档或 Discussion | | 重复 Issue | 引用原始 Issue + 关闭 | | 安全漏洞 | 引导使用 Private Vulnerability Reporting + 关闭公开 Issue | | 首次贡献者 | 额外感谢 + 引导到 CONTRIBUTING.md |

4.2 回复语言

• Issue 是中文 → 用中文回复
• Issue 是英文 → 用英文回复
• Issue 混合语言 → 用主要语言回复

4.3 回复质量要求

• 语气友好、专业，不居高临下
• 给出具体的下一步（不是"我们看看"）
• 引用具体的文档或 Issue 编号
• 首次贡献者要额外表示欢迎

> 各场景的完整回复模板见 references/response-templates.md。

---

Step 5: PR 审查辅助

5.1 PR 改动分析

对每个待审查的 PR：

1. 读取 PR 描述和关联的 Issue
2. 通过 pull_request_read（method: get_files）获取改动文件列表
3. 检查 CI/CD 状态（通过 pull_request_read（method: get_status）或 API 获取检查结果）
4. 检查可合并状态（mergeable / mergeable_state）
5. 分析改动类型（bug fix / feature / docs / refactor）
6. 检查常见质量问题（硬编码、缺少测试、破坏性变更）

5.2 生成审查意见

输出审查摘要供维护者参考：

### PR #{number}: {title}
- 提交者：@{user}（首次贡献 / 活跃贡献者）
- 关联 Issue：#{number} / 无
- 改动范围：N 个文件，+X / -Y 行
- 改动类型：Bug Fix / Feature / Docs / Refactor
- CI/CD 状态：✅ 全部通过 / ❌ 有失败 / ⏳ 进行中
- 可合并状态：✅ 无冲突 / ⚠️ 有冲突 / 🔒 被阻塞

#### 自动检查
- [ ] CI/CD 检查是否全部通过
- [ ] 是否包含测试（如适用）
- [ ] 是否有破坏性变更
- [ ] 是否更新了文档（如适用）
- [ ] 代码风格是否一致
- [ ] CODEOWNERS 审查是否完成（如配置了 CODEOWNERS）

#### 建议
- [列出具体建议]

#### 建议操作
- 批准并合并 / 需要修改 / 拒绝（说明原因）

用户确认后，调用 pull_request_review_write 提交审查，或 merge_pull_request 合并。

> PR 审查的详细检查清单和常见问题见 references/pr-review-guide.md。

---

Step 6: 版本管理（PR 合并后）

> 触发时机：PR 合并后，或用户主动要求发版时执行。此步骤为可选步骤。

6.1 判断版本变更类型

根据合并的 PR 类型，按 semver 规则建议版本段：

| PR 改动类型 | semver 版本段 | 示例 | |------------|--------------|------| | Bug Fix（type:bug） | patch（x.x.+1） | 1.2.3 → 1.2.4 | | 功能新增（type:enhancement） | minor（x.+1.0） | 1.2.3 → 1.3.0 | | 破坏性变更（breaking change） | major（+1.0.0） | 1.2.3 → 2.0.0 | | 文档/重构/性能（无 API 变更） | patch（x.x.+1） | 1.2.3 → 1.2.4 | | 安全修复（type:security） | patch 或 minor | 视影响范围决定 |

6.2 读取当前版本

自动检测项目的版本文件和当前版本号：

| 项目类型 | 版本文件 | |----------|----------| | Node.js / npm | package.json → version 字段 | | Python | pyproject.toml → version 或 __init__.py → __version__ | | Rust | Cargo.toml → version 字段 | | Go | go.mod 无版本，通过 git tag 管理 | | Java | pom.xml → ` 或 build.gradle → version | | 通用 | git tag（v..*`） |

6.3 生成版本更新方案

### 版本更新建议

- 当前版本：v1.2.3
- 合并的 PR：
  - #42 fix: 修复登录超时问题（patch）
  - #45 feat: 新增导出功能（minor）
- 建议新版本：v1.3.0（取最高版本段）
- 版本文件：`package.json`

### Changelog 草稿

## v1.3.0 (2026-06-20)

### Features
- 新增导出功能 (#45) by @contributor

### Bug Fixes
- 修复登录超时问题 (#42) by @contributor

6.4 执行版本更新

用户确认后，按顺序执行：

1. 更新版本文件（通过 create_or_update_file 推送）
2. 更新所有版本号声明位置（见下方同步清单）
3. 创建 git tag（通过 API 或本地 git tag）
4. 创建 GitHub Release（通过 API，附上 changelog）

6.5 版本号同步清单

版本号必须在以下所有位置保持一致，漏一个就会让用户看到不一致的版本号：

| # | 位置 | 具体内容 | 作用 | |---|------|----------|------| | 1 | 版本文件 | package.json / pyproject.toml / Cargo.toml 等 | 包管理器识别 | | 2 | README 徽章 | shields.io 版本徽章（如 version-1.1.0-green） | 项目首页展示 | | 3 | SKILL.md frontmatter | version: 1.1.0（如果是 Skill 项目） | Agent 识别用 | | 4 | Git tag | git tag -a v1.1.0 | GitHub Tags 页面 | | 5 | GitHub Release | 基于 tag 创建 | Releases 正式发布页 |

> tag 和 Release 是两回事：tag 只是指针，Release 是带说明的发布页面。两者都需要创建。

> 详细的 semver 规则、多语言版本文件模板、GitHub Release 创建流程和 changelog 规范见 references/release-workflow.md。

---

Step 7: 过期管理

7.1 识别过期 Issue/PR

筛选条件（可调整）：

| 类型 | 判定标准 | 对应自动化参数 | |------|----------|----------------| | 过期 Issue | open 状态 + 30 天无活动 | days-before-issue-stale: 30 | | 等待反馈的 Issue | 标记 status:needs-info + 14 天无回复 | 需单独配置（见下方说明） | | 过期 PR | open 状态 + 30 天无活动 | days-before-pr-stale: 30 | | 使用问题 | 标记 type:question + 7 天无回复 | 需单独配置（见下方说明） |

> 手动 vs 自动化的差异：actions/stale 默认对所有 Issue 使用统一的时间参数。如需按类型差异化处理（如使用问题 7 天、等待反馈 14 天），有两种方案： > 1. 多工作流方案：为不同类型配置独立的 stale 工作流，通过 only-issue-types 或标签过滤 > 2. 简化方案：统一使用 30+14 天，手动处理特殊类型（本技能默认推荐）

7.2 处理策略

| 类型 | 建议操作 | |------|----------| | 过期 Bug | 提醒维护者关注，不自动关闭 | | 过期功能请求 | 提醒 + 询问是否仍需要 | | 过期使用问题 | 提醒一次，再过 7 天关闭，标记 resolution:no-response | | 等待反馈无回复 | 提醒一次，再过 14 天关闭，标记 resolution:no-response | | 过期 PR | 提醒提交者更新，或建议维护者接管 |

所有操作都先展示给用户确认，不自动关闭任何 Issue。

7.3 关闭时的规范

关闭 Issue 时，评论中说明关闭原因，并附上：

• 如问题已解决：引用修复的 commit 或 PR
• 如无法复现：说明已尝试的环境
• 如无回复：说明曾多次提醒

---

Step 8: 运营报告

8.1 报告数据

通过 API 统计以下指标：

| 指标 | 说明 | |------|------| | 新 Issue 数 | 报告周期内新增 | | 关闭 Issue 数 | 报告周期内关闭 | | 平均响应时间 | 从 Issue 创建到首次维护者回复的时间 | | 平均解决时间 | 从 Issue 创建到关闭的时间（MTTR） | | Issue 关闭率 | 关闭数 / 新增数（衡量积压趋势） | | 新 PR 数 | 报告周期内新增 | | 合并 PR 数 | 报告周期内合并 | | PR 合并率 | 合并数 / 新增数 | | 未关闭 Issue 总数 | 当前积压 | | 贡献者数 | 报告周期内有贡献的人数 | | 首次贡献者数 | 报告周期内首次贡献的人数 | | Star/Fork 变化 | 报告周期内的增长 |

8.2 报告模板

## 运营报告 — {owner}/{repo}
报告周期：{start_date} ~ {end_date}

### 数据概览
| 指标 | 本期 | 上期 | 变化 |
|------|------|------|------|
| 新 Issue | N | N | +X% |
| 关闭 Issue | N | N | -X% |
| Issue 关闭率 | X% | X% | +X% |
| 平均响应时间 | Xh | Xh | 改善/恶化 |
| 平均解决时间 | Xd | Xd | 改善/恶化 |
| 新 PR | N | N | +X% |
| 合并 PR | N | N | -X% |
| PR 合并率 | X% | X% | +X% |
| 首次贡献者 | N | N | +X% |
| Star | +N | +N | +X% |

### 健康评估
- Issue 响应时间：良好（3天）
- Issue 积压：健康（30）
- PR 积压：健康（15）
- Issue 关闭率：健康（>80%）/ 一般（50-80%）/ 需改进（ 按需为用户的项目生成 GitHub Actions 工作流文件，减少手动重复操作。

### 9.1 可配置的自动化

| 自动化 | 功能 | 生成文件 |
|--------|------|----------|
| Stale Bot | 自动标记/关闭过期 Issue | `.github/workflows/stale.yml` |
| Issue Labeler | 根据 Issue 内容自动添加标签 | `.github/workflows/labeler.yml` + `.github/labeler.yml` |
| Welcome Bot | 欢迎首次贡献者 | `.github/workflows/welcome.yml` |
| Auto-assign | 自动分配 Issue/PR 给维护者 | `.github/workflows/auto-assign.yml` |
| Dependabot | 依赖安全更新和版本更新 | `.github/dependabot.yml` |
| CODEOWNERS | 按文件路径自动请求审查 | `.github/CODEOWNERS` |

### 9.2 配置流程

1. 询问用户需要哪些自动化
2. 根据项目类型和现有配置生成适合的参数
3. 展示生成的 YAML 文件内容
4. 用户确认后，写入项目目录或推送到仓库

> 完整的 GitHub Actions YAML 模板和参数说明见 `references/automation-templates.md`。

### 9.3 标签体系初始化

如果项目缺少标准标签体系，建议先创建以下基础标签：

| 标签 | 颜色 | 用途 |
|------|------|------|
| `type:bug` | 红色 | Bug 报告 |
| `type:enhancement` | 蓝色 | 功能请求 |
| `type:question` | 紫色 | 使用问题 |
| `type:documentation` | 浅蓝 | 文档改进 |
| `type:refactor` | 浅黄 | 代码重构 |
| `type:performance` | 黄色 | 性能问题 |
| `type:security` | 深红 | 安全漏洞 |
| `priority:P0` ~ `P3` | 橙→灰 | 优先级 |
| `status:needs-triage` | 深黄 | 待分流 |
| `status:needs-info` | 黄色 | 需要更多信息 |
| `status:confirmed` | 绿色 | Bug 已确认 |
| `status:in-progress` | 蓝色 | 正在处理 |
| `status:blocked` | 橙色 | 被阻塞 |
| `status:stale` | 灰色 | 过期（Stale Bot 标记） |
| `good first issue` | 绿色 | 适合新手 |
| `help wanted` | 绿色 | 欢迎贡献 |
| `resolution:duplicate` | 灰色 | 重复 Issue |
| `resolution:wontfix` | 灰色 | 不修复 |
| `resolution:no-response` | 灰色 | 无回复关闭 |
| `resolution:invalid` | 灰色 | 无效 Issue |

通过 API 批量创建标签：`POST /repos/{owner}/{repo}/labels`。

> 完整的标签体系说明（含颜色色值）和批量创建脚本见 `references/triage-workflow.md`。

---

## 异常处理

| 情况 | 处理 |
|------|------|
| 仓库不存在或无权限 | 提示用户确认仓库名和 Token 权限 |
| 没有未关闭的 Issue | 输出"一切正常"，不生成多余报告 |
| Issue 数量超过 100 | 分批处理，优先处理最近的 |
| API 速率限制 | 等待或提示用户稍后重试（已认证 5000 次/小时，未认证 60 次/小时） |
| MCP 工具不可用 | 继续完成公开只读分析；写操作回退到已认证的 `gh`、受信任连接或人工交接 |
| Docker 未运行 | 优先使用官方远程 MCP/OAuth、`gh` 或网页，不把 Docker 作为阻塞条件 |
| Windows PowerShell 环境 | curl 示例中 `$GITHUB_TOKEN` 需改为 `$env:GITHUB_TOKEN`，行续接符 `\` 改为 `` ` `` |
| Fine-grained PAT 权限不足 | 提示用户检查 PAT 的仓库范围和权限级别（Issues/PR 需 Read and write） |
| 用户取消操作 | 不执行任何已准备好的操作 |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hyt315](https://github.com/hyt315)
- **Source:** [hyt315/github-oss-ops](https://github.com/hyt315/github-oss-ops)
- **License:** MIT

Install and usage instructions live in the source repository linked above.