GitHub 平台类型

约 1848 字大约 6 分钟

2026-03-19

GitHub 平台数据模型、枚举、Sender 与事件数据类。

导入

from ncatbot.types.github import (
    # 枚举
    GitHubPostType, GitHubAction, GitHubIssueState, GitHubPRState,
    GitHubUserType, GitHubMergeMethod,
    # 事件内嵌模型
    GitHubRepo, GitHubCommit, GitHubRelease, GitHubReleaseAsset, GitHubForkee,
    # API 响应模型
    GitHubUserInfo, GitHubLabelInfo, GitHubBranchRef,
    GitHubIssueInfo, GitHubCommentInfo, GitHubPullRequestInfo,
    GitHubMergeResult, GitHubReleaseInfo, GitHubRepoInfo,
    # Sender
    GitHubSender,
    # 事件数据
    GitHubEventData, GitHubIssueEventData, GitHubIssueCommentEventData,
    GitHubPREventData, GitHubPRReviewCommentEventData, GitHubPushEventData,
    GitHubStarEventData, GitHubForkEventData, GitHubReleaseEventData,
)

# 跨平台附件模型
from ncatbot.types import Attachment

导入

from ncatbot.types import (
    Attachment, AttachmentKind, AttachmentList,
    ImageAttachment, VideoAttachment, AudioAttachment, FileAttachment,
)

枚举

GitHubPostType

值	说明
`ISSUE = "issue"`	Issue 事件
`PULL_REQUEST = "pull_request"`	PR 事件
`COMMENT = "comment"`	评论事件
`PUSH = "push"`	Push 事件
`STAR = "star"`	Star 事件
`FORK = "fork"`	Fork 事件
`RELEASE = "release"`	Release 事件

GitHubAction

值	说明
`OPENED = "opened"`	Issue/PR 创建
`EDITED = "edited"`	Issue/PR 编辑
`CLOSED = "closed"`	Issue/PR 关闭
`REOPENED = "reopened"`	Issue/PR 重开
`CREATED = "created"`	通用创建
`DELETED = "deleted"`	通用删除
`SUBMITTED = "submitted"`	Review 提交
`DISMISSED = "dismissed"`	Review 驳回
`PUBLISHED = "published"`	Release 发布
`SYNCHRONIZE = "synchronize"`	PR 同步更新
`MERGED = "merged"`	PR 合并
`LABELED = "labeled"`	添加标签
`UNLABELED = "unlabeled"`	移除标签
`ASSIGNED = "assigned"`	指派
`UNASSIGNED = "unassigned"`	取消指派
`REVIEW_REQUESTED = "review_requested"`	请求审查
`REVIEW_REQUEST_REMOVED = "review_request_removed"`	取消审查请求
`STARTED = "started"`	Star 开始

GitHubIssueState

值	说明
`OPEN = "open"`	打开
`CLOSED = "closed"`	关闭

GitHubPRState

值	说明
`OPEN = "open"`	打开
`CLOSED = "closed"`	关闭

GitHubUserType

值	说明
`USER = "User"`	普通用户
`BOT = "Bot"`	机器人
`ORGANIZATION = "Organization"`	组织

GitHubMergeMethod

值	说明
`MERGE = "merge"`	普通合并
`SQUASH = "squash"`	压缩合并
`REBASE = "rebase"`	变基合并

数据模型

所有 GitHub 模型继承自 GitHubModel(BaseModel)，具有以下通用特性：

extra="allow" — 容忍 GitHub API 返回的未声明字段
populate_by_name=True — 同时支持 alias 和字段原名
dict 兼容层 — model["key"]、model.get(key)、"key" in model

GitHubRepo

字段	类型	默认值	说明
`owner`	str	`""`	仓库所有者
`name`	str	`""`	仓库名
`full_name`	str	`""`	全名（`"owner/name"`）
`id`	str	`""`	仓库 ID
`html_url`	str \| None	None	网页 URL
`description`	str \| None	None	仓库描述
`private`	bool	False	是否私有
`default_branch`	str \| None	None	默认分支

GitHubCommit

字段	类型	默认值	说明
`sha`	str	`""`	Commit SHA
`message`	str	`""`	提交消息
`author_name`	str	`""`	作者名
`author_email`	str	`""`	作者邮箱
`url`	str \| None	None	Commit URL
`timestamp`	str \| None	None	时间戳
`added`	List[str]	`[]`	新增文件
`removed`	List[str]	`[]`	删除文件
`modified`	List[str]	`[]`	修改文件

GitHubRelease

字段	类型	默认值	说明
`id`	str	`""`	Release ID
`tag_name`	str	`""`	Tag 名称
`name`	str	`""`	Release 名称
`body`	str	`""`	发布说明
`prerelease`	bool	False	是否预发布
`draft`	bool	False	是否草稿
`html_url`	str \| None	None	网页 URL

GitHubReleaseAsset

字段	类型	默认值	说明
`id`	str	`""`	Asset ID
`name`	str	`""`	文件名
`content_type`	str	`""`	MIME 类型
`size`	int	0	文件大小（字节）
`download_count`	int	0	下载次数
`browser_download_url`	str	`""`	下载 URL
`created_at`	str \| None	None	创建时间

GitHubForkee

字段	类型	默认值	说明
`full_name`	str	`""`	Fork 后仓库全名
`html_url`	str \| None	None	网页 URL
`owner`	str	`""`	Fork 所有者
`description`	str \| None	None	描述

API 响应模型

API 方法返回的类型化模型（替代原来的 dict）。忠实映射 GitHub REST API 返回结构。

GitHubUserInfo

字段	类型	默认值	说明
`login`	str	`""`	GitHub 登录名
`id`	int	0	数字 ID
`avatar_url`	str \| None	None	头像 URL
`html_url`	str \| None	None	个人主页
`type`	str	`"User"`	用户类型
`name`	str \| None	None	显示名
`email`	str \| None	None	邮箱
`bio`	str \| None	None	简介
`public_repos`	int	0	公开仓库数

GitHubLabelInfo

字段	类型	默认值	说明
`id`	int	0	Label ID
`name`	str	`""`	标签名
`color`	str	`""`	颜色 (hex)
`description`	str \| None	None	描述

GitHubBranchRef

字段	类型	默认值	说明
`ref`	str	`""`	分支名
`sha`	str	`""`	Commit SHA
`label`	str	`""`	标签（如 `"user:branch"`）

GitHubIssueInfo

字段	类型	默认值	说明
`id`	int	0	Issue ID
`number`	int	0	Issue 编号
`title`	str	`""`	标题
`body`	str \| None	None	内容
`state`	str	`""`	状态
`html_url`	str \| None	None	网页 URL
`user`	GitHubUserInfo \| None	None	创建者
`labels`	List[GitHubLabelInfo]	`[]`	标签列表
`assignees`	List[GitHubUserInfo]	`[]`	负责人列表
`comments`	int	0	评论数
`created_at`	str \| None	None	创建时间
`updated_at`	str \| None	None	更新时间
`closed_at`	str \| None	None	关闭时间

GitHubCommentInfo

字段	类型	默认值	说明
`id`	int	0	评论 ID
`body`	str	`""`	评论内容
`user`	GitHubUserInfo \| None	None	评论者
`html_url`	str \| None	None	网页 URL
`created_at`	str \| None	None	创建时间
`updated_at`	str \| None	None	更新时间

GitHubPullRequestInfo

字段	类型	默认值	说明
`id`	int	0	PR ID
`number`	int	0	PR 编号
`title`	str	`""`	标题
`body`	str \| None	None	内容
`state`	str	`""`	状态
`html_url`	str \| None	None	网页 URL
`head`	GitHubBranchRef \| None	None	源分支
`base`	GitHubBranchRef \| None	None	目标分支
`user`	GitHubUserInfo \| None	None	创建者
`merged`	bool	False	是否已合并
`draft`	bool	False	是否草稿
`mergeable`	bool \| None	None	是否可合并
`created_at`	str \| None	None	创建时间
`updated_at`	str \| None	None	更新时间

GitHubMergeResult

字段	类型	默认值	说明
`sha`	str	`""`	合并提交 SHA
`merged`	bool	False	是否合并成功
`message`	str	`""`	合并消息

GitHubReleaseInfo

继承 GitHubRelease，补充 API 返回的完整字段。

字段	类型	默认值	说明
(继承 GitHubRelease 所有字段)
`author`	GitHubUserInfo \| None	None	发布者
`assets`	List[GitHubReleaseAsset]	`[]`	Asset 列表
`created_at`	str \| None	None	创建时间
`published_at`	str \| None	None	发布时间
`tarball_url`	str \| None	None	Tarball 下载 URL
`zipball_url`	str \| None	None	Zipball 下载 URL

GitHubRepoInfo

字段	类型	默认值	说明
`id`	int	0	仓库 ID
`name`	str	`""`	仓库名
`full_name`	str	`""`	全名
`owner`	GitHubUserInfo \| None	None	所有者
`private`	bool	False	是否私有
`html_url`	str \| None	None	网页 URL
`description`	str \| None	None	描述
`fork`	bool	False	是否 Fork
`default_branch`	str	`"main"`	默认分支
`language`	str \| None	None	主要语言
`stargazers_count`	int	0	Star 数
`forks_count`	int	0	Fork 数
`open_issues_count`	int	0	开放 Issue 数
`created_at`	str \| None	None	创建时间
`updated_at`	str \| None	None	更新时间

跨平台附件模型

AttachmentKind

值	说明
`IMAGE`	图片
`VIDEO`	视频
`AUDIO`	音频
`FILE`	文件
`OTHER`	其他

Attachment（基类）

from ncatbot.types import Attachment

字段	类型	默认值	说明
`name`	str	—	文件名
`url`	str	—	下载 URL
`size`	int \| None	None	文件大小（字节）
`content_type`	str \| None	None	MIME 类型
`kind`	AttachmentKind	`OTHER`	附件类型
`extra`	dict	`{}`	平台特有字段

方法	签名	说明
`download()`	`async download(dest: str \| Path, *, proxy: str \| None = None) -> Path`	下载到指定目录
`as_bytes()`	`async as_bytes(*, proxy: str \| None = None) -> bytes`	下载到内存
`to_segment()`	`to_segment() -> MessageSegment`	转为消息段（用 URL）
`to_local_segment()`	`async to_local_segment(cache_dir) -> MessageSegment`	先下载再转段

proxy 参数行为：显式传入代理地址时使用传入值；省略时自动读取主配置 http_proxy；配置也为空则直连。
⚠️ 网络提醒：从 GitHub 下载资源（包括通过 Attachment.download() / as_bytes() 隐式下载 Release Assets）时，国内网络可能无法直连。建议开发者在 config.yaml 中配置 http_proxy，或在下载前自行对 GitHub URL 添加镜像前缀（如 ghfast.top）以避免网络阻塞。参见 api.misc 提供的代理相关工具方法。

附件子类

子类	kind	特有字段	`to_segment()` 返回
`ImageAttachment`	`IMAGE`	`width: int?`, `height: int?`	`Image`
`VideoAttachment`	`VIDEO`	`duration: int?`	`Video`
`AudioAttachment`	`AUDIO`	`duration: int?`	`Record`
`FileAttachment`	`FILE`	—	`File`

list 子类，兼容 List[Attachment]。

方法	返回	说明
`images()`	`AttachmentList`	只含 ImageAttachment
`videos()`	`AttachmentList`	只含 VideoAttachment
`audios()`	`AttachmentList`	只含 AudioAttachment
`files()`	`AttachmentList`	只含 FileAttachment
`by_kind(*kinds)`	`AttachmentList`	按 kind 过滤
`by_content_type(pattern)`	`AttachmentList`	glob 过滤（如 `"image/*"`）
`first()`	`Attachment?`	第一个
`largest()`	`Attachment?`	size 最大
`smallest()`	`Attachment?`	size 最小
`download_all(dest)`	`async -> List[Path]`	批量下载

Sender

GitHubSender

继承自 BaseSender。

字段	类型	默认值	说明
`user_id`	str	`""`	数字 ID（继承）
`nickname`	str	`""`	昵称（继承）
`login`	str	`""`	GitHub 登录名
`avatar_url`	str \| None	None	头像 URL
`html_url`	str \| None	None	个人主页
`user_type`	GitHubUserType	`USER`	用户类型

事件数据模型

所有事件数据类继承自 GitHubEventData（BaseEventData 子类）。

GitHubEventData（基类）

字段	类型	说明
`platform`	str	固定 `"github"`
`action`	GitHubAction	Webhook action 字段
`repo`	GitHubRepo	仓库信息
`sender`	GitHubSender	操作者信息

事件数据类速查

数据类	post_type	核心字段
`GitHubIssueEventData`	`"issue"`	`issue_number`, `issue_title`, `issue_body`, `issue_state`, `labels`, `assignees`
`GitHubIssueCommentEventData`	`"comment"`	`comment_id`, `comment_body`, `issue_number`, `issue_title`
`GitHubPREventData`	`"pull_request"`	`pr_number`, `pr_title`, `pr_body`, `pr_state`, `head_ref`, `base_ref`, `merged`, `draft`
`GitHubPRReviewCommentEventData`	`"comment"`	`comment_id`, `comment_body`, `pr_number`, `diff_hunk`, `path`
`GitHubPushEventData`	`"push"`	`ref`, `before`, `after`, `commits`, `head_commit`, `pusher_name`
`GitHubStarEventData`	`"star"`	`starred_at`
`GitHubForkEventData`	`"fork"`	`forkee` (GitHubForkee)
`GitHubReleaseEventData`	`"release"`	`release` (GitHubRelease)

返回：类型参考首页 · 相关：GitHub 事件实体 · GitHub API

版权所有

版权归属：MI

许可证：署名 4.0 国际 (CC-BY-4.0)