invoking-github

调用 GitHub

通过 Claude.ai 聊天以编程方式与 GitHub 仓库交互：读取文件、提交更改、创建 PR，并在会话之间持久保存状态。

何时使用此技能

不需要用于：

• Claude Code 环境（使用原生 git 命令）
• 只读仓库访问（直接使用 GitHub UI 或 API）

快速入门

前提条件

创建 GitHub Personal Access Token 并将其添加到 Project Knowledge：

1. 前往 https://github.com/settings/tokens
2. 创建新令牌（classic 或 fine-grained）
3. 必需的权限范围：repo（仅限公共仓库时使用 public_repo）
4. 在 Claude.ai 中，将以下内容添加到 Project Knowledge：
   • 标题：GITHUB_API_KEY
   • 内容：你的令牌（例如，ghp_abc123...）

提交单个文件

from invoking_github import commit_file

result = commit_file(
    repo="username/repo-name",
    path="README.md",
    content="# Updated README\n\nNew content here...",
    branch="main",
    message="Update README with new instructions"
)

print(f"Committed: {result['commit_sha']}")

读取文件

from invoking_github import read_file

content = read_file(
    repo="username/repo-name",
    path="config.json",
    branch="main"
)

print(content)

批量提交（多个文件）

from invoking_github import commit_files

files = [
    {"path": "src/main.py", "content": "# Python code..."},
    {"path": "README.md", "content": "# Updated docs..."},
    {"path": "tests/test.py", "content": "# Tests..."}
]

result = commit_files(
    repo="username/repo-name",
    files=files,
    branch="feature-branch",
    message="Add new feature implementation",
    create_branch_from="main"  # Create branch if it doesn't exist
)

print(f"Committed {len(files)} files: {result['commit_sha']}")

创建拉取请求

from invoking_github import create_pull_request

pr = create_pull_request(
    repo="username/repo-name",
    head="feature-branch",
    base="main",
    title="Add new feature",
    body="## Changes\n- Implemented feature X\n- Updated docs\n- Added tests"
)

print(f"PR created: {pr['html_url']}")

核心函数

read_file()

从仓库读取文件：

read_file(
    repo: str,           # "owner/name"
    path: str,           # "path/to/file.py"
    branch: str = "main" # Branch name
) -> str

返回值：文件内容字符串 引发异常：文件不存在或访问被拒时引发 GitHubAPIError

commit_file()

提交单个文件（创建或更新）：

commit_file(
    repo: str,                      # "owner/name"
    path: str,                      # "path/to/file.py"
    content: str,                   # New file content
    branch: str,                    # Target branch
    message: str,                   # Commit message
    create_branch_from: str = None  # Create branch from this if doesn't exist
) -> dict

返回值：包含 commit_sha、branch、file_path 的字典 引发异常：发生冲突或身份验证失败时引发 GitHubAPIError

commit_files()

在单次提交中提交多个文件：

commit_files(
    repo: str,                      # "owner/name"
    files: list[dict],              # [{"path": "...", "content": "..."}]
    branch: str,                    # Target branch
    message: str,                   # Commit message
    create_branch_from: str = None  # Create branch from this if doesn't exist
) -> dict

返回值：包含 commit_sha、branch、files_committed 的字典 引发异常：发生失败时引发 GitHubAPIError

注意：使用 Git Trees API 提高效率——以原子方式提交所有文件。

create_pull_request()

创建拉取请求：

create_pull_request(
    repo: str,      # "owner/name"
    head: str,      # Source branch (your changes)
    base: str,      # Target branch (where to merge)
    title: str,     # PR title
    body: str = ""  # PR description (supports markdown)
) -> dict

返回值：包含 number、html_url、state 的字典 引发异常：分支无效或 PR 已存在时引发 GitHubAPIError

凭据配置

此技能需要 GitHub Personal Access Token。提供两种配置方式：

方法 1：Project Knowledge（推荐）

适用于 Claude.ai 聊天用户（移动端/网页端）：

1. 在 https://github.com/settings/tokens 创建令牌
2. 在 Claude.ai 的 Project 设置中 → 添加到 Project Knowledge
3. 创建标题为 GITHUB_API_KEY 的文档
4. 将令牌粘贴为内容

所需权限：

• Classic 令牌：repo 权限范围
• Fine-grained 令牌：仓库权限 → Contents（读/写）和 Pull requests（读/写）

方法 2：API Credentials 技能（备用）

也可以使用合并后的凭据文件：

1. 在 Project Knowledge 中创建 API_CREDENTIALS.json
2. 添加：{"github_api_key": "ghp_your-token-here"}

与 Iterating 技能集成

自动将 DEVLOG.md 持久保存到 GitHub，以便在不同会话之间保持连续性：

# In your DEVLOG update function
from invoking_github import commit_file
from pathlib import Path

def update_devlog_with_sync(data, repo="user/project", branch="devlog"):
    """Update DEVLOG.md locally and sync to GitHub"""

    # Update local DEVLOG
    update_devlog(data)  # Your existing function

    # Auto-sync to GitHub
    try:
        devlog_content = Path("DEVLOG.md").read_text()

        result = commit_file(
            repo=repo,
            path="DEVLOG.md",
            content=devlog_content,
            branch=branch,
            message=f"DEVLOG: {data['title']}",
            create_branch_from="main"
        )

        print(f"✓ DEVLOG synced to GitHub ({repo}:{branch})")
        return result

    except Exception as e:
        print(f"⚠ DEVLOG sync failed: {e}")
        # Continue anyway - local DEVLOG.md still updated
        return None

优点：

• 自动备份会话进度
• 可跨设备访问开发日志
• 记录决策和进度的 Git 历史
• 无需手动复制/粘贴到 Project Knowledge

完整模式请参阅 references/iterating-integration.md。

错误处理

所有函数都会引发带有说明性消息的 GitHubAPIError：

from invoking_github import commit_file, GitHubAPIError

try:
    result = commit_file(
        repo="user/repo",
        path="file.py",
        content="...",
        branch="main",
        message="Update"
    )
except GitHubAPIError as e:
    if e.status_code == 404:
        print("Repository or branch not found")
    elif e.status_code == 401:
        print("Authentication failed - check your token")
    elif e.status_code == 403:
        print("Access denied - check token permissions")
    elif e.status_code == 409:
        print("Conflict - file was modified since last read")
    else:
        print(f"GitHub API error: {e}")

常见错误：

• 404：找不到仓库、分支或文件
• 401/403：令牌无效或权限不足
• 409：合并冲突（文件被并发修改）
• 422：验证错误（分支名称无效等）
• 速率限制：请求过多（重试前请等待）

最佳实践

1. 使用描述性提交消息

   • 不佳："Update files"
   • 良好："Add authentication middleware and update user routes"

2. 尽可能批量提交

   • 对相关更改使用 commit_files()
   • 单次原子提交 = 更整洁的 git 历史记录

3. 创建功能分支

   • 不要直接提交到 main
   • 使用 create_branch_from="main" 参数
   • 创建 PR 以供审查

4. 安全管理令牌

   • 使用权限范围最小的 fine-grained 令牌
   • 设置过期日期
   • 定期轮换
   • 切勿将令牌提交到仓库

高级用法

条件提交

仅在文件内容发生更改时才提交：

from invoking_github import read_file, commit_file, GitHubAPIError

try:
    current_content = read_file(repo, path, branch)
    if current_content != new_content:
        commit_file(repo, path, new_content, branch, "Update file")
    else:
        print("No changes detected, skipping commit")
except GitHubAPIError as e:
    if e.status_code == 404:
        # File doesn't exist, create it
        commit_file(repo, path, new_content, branch, "Create file")
    else:
        raise

会话专属分支

使用唯一的分支名称避免冲突：

import datetime

session_id = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
branch_name = f"devlog-{session_id}"

commit_file(
    repo="user/project",
    path="DEVLOG.md",
    content=devlog_content,
    branch=branch_name,
    message="Session progress",
    create_branch_from="main"
)

多仓库工作流

跨多个仓库开展工作：

repos = ["user/frontend", "user/backend", "user/docs"]

for repo in repos:
    commit_file(
        repo=repo,
        path="VERSION",
        content="2.0.0\n",
        branch="release-2.0",
        message="Bump version to 2.0.0"
    )

限制

• 目标环境：仅限 Claude.ai 聊天（不包括 Claude Code）
• 无 OAuth：必须手动使用个人访问令牌
• 无 git 操作：仅使用 REST API（不支持 clone、pull、rebase 等）
• 文件大小：GitHub API 对单个文件的大小限制约为 100MB
• 速率限制：已认证用户每小时最多 5000 次请求
• 需要网络：所有操作都需要互联网连接

另请参阅

• references/credential-setup.md - 凭据设置分步指南
• references/iterating-integration.md - DEVLOG 自动同步模式
• references/troubleshooting.md - 常见问题和解决方案
• GitHub REST API 文档 - GitHub API 官方参考文档

令牌效率

此技能加载时约使用 800 个令牌，但可为无法原生访问 git 的 claude.ai 聊天环境提供必要的 GitHub 操作能力，并支持持久状态管理和跨会话工作流。