chatgh

chatgh 是 ChatArch 的 GitHub CLI 与 Python API 包，承载从 chattool gh 迁移出的 PR、CI、Actions run/job logs、仓库权限和 token 配置能力。新脚本和文档应直接使用 chatgh；chattool gh 只作为 ChatTool 侧兼容入口。

安装

pip install chatgh
# 开发态
pip install -e ".[dev]"

配置模型

默认行为：

• repo：优先使用显式 --repo owner/repo，未传时从当前 git remote 推断。
• token：优先使用显式 --token，其次读取当前仓库 .git/config 中 repo-local HTTPS auth header，再回退 typed env 里的 GITHUB_ACCESS_TOKEN。
• 输出：默认是人类可读格式；支持 --json FIELDS 的命令会按字段投影输出官方 gh 风格 JSON，--json-output 保留为完整 payload JSON dump，适合脚本消费。

Token 来源

Token 解析顺序稳定为：

1. 显式 --token。
2. 当前仓库 .git/config 中的 repo-local HTTPS auth header，路径为规范化后的 https://github.com/owner/repo.git。
3. typed env 中的 GITHUB_ACCESS_TOKEN。

可以用 chatenv 查看或配置 typed env：

chatenv init -t gh
chatenv cat -t gh

安装 chatgh 后，它会通过 chatenv.configs entry point 注册 GitHubConfig，所以 chatenv list 会出现 [GitHub] 分组，-t gh / -t github 可以解析到同一份 GitHub typed env。

ghp_xxx / github_pat_xxx 都是 GitHub Personal Access Token。通常 clone/fetch/push 至少需要 contents 读写权限；PR 评论、合并和 Actions 读取按仓库策略补充对应权限。

仓库推断

未传 --repo 时，chatgh 会检查当前仓库 remote，并优先使用 origin，再尝试其它 remote。支持：

• https://github.com/octocat/Hello-World.git
• https://github.com/octocat/Hello-World
• git@github.com:octocat/Hello-World.git
• ssh://git@github.com/octocat/Hello-World.git

写入 repo-local HTTPS auth header 时，path 会规范化为 https://github.com/octocat/Hello-World.git。

CLI 入口

chatgh --help
chatgh pr --help
chatgh repo --help
chatgh invitation --help
chatgh project --help
chatgh run --help
chatgh repo-perms --help
chatgh set-token --help

命令树：

• chatgh pr list/create/view/comment/edit/checks/merge：已有 PR 基础流程；merge 默认 --check，不能当 dry-run。
• chatgh pr status/diff/close/reopen/review/ready/update-branch：本轮补齐的常见 lifecycle/review 命令；写操作复用 ChatGH token resolution，且不会打印 token。
• chatgh repo list/create/fork/protection：已有仓库列表、创建、fork、保护规则检查。
• chatgh repo view/clone/sync/edit：本轮补齐的常见 repo 命令；clone/sync 对本地 git 副作用保持显式、保守，不覆盖已有非空目录。
• chatgh invitation list/accept/decline：查看和处理当前账号收到的 GitHub repository invitations；对齐 GitHub REST API 的 authenticated user invitation 能力。
• chatgh project list/view/create/edit/close/delete/copy 与 chatgh project item ...、chatgh project field ...、link/unlink/mark-template：GitHub Projects v2 命令面。官方 gh project 只作为能力参考；ChatGH 打开 item 和 field 子树，不保留 item-add / field-list 扁平兼容入口。鉴权、JSON 输出、安全门和 Python API 走 ChatGH 自有规范。
• chatgh run view/logs：查看 workflow run 和 job logs。
• chatgh run list/watch/rerun/cancel/download：本轮补齐的 Actions run 运维命令；watch 有 timeout，rerun/cancel 属于远端 mutation。
• chatgh repo-perms：查看 token 权限和派生 capabilities。
• chatgh set-token：为当前 GitHub 仓库配置 repo 级 HTTPS token。

常用流程

Repo view / clone / sync / edit

chatgh repo view ChatArch/ChatGH --json-output
chatgh repo clone ChatArch/ChatGH ./ChatGH-copy
chatgh repo sync --repo ChatArch/ChatGH --branch master --remote origin --json-output
chatgh repo edit ChatArch/ChatGH --description "GitHub helpers" --json-output
chatgh repo edit ChatArch/ChatGH --visibility private --accept-visibility-change-consequences --json-output

repo clone 会拒绝覆盖已有非空目录；repo sync 默认使用 git pull --ff-only。repo edit 当前只支持 description、homepage、default-branch 和 visibility 小子集；设置 --visibility 时必须显式传 --accept-visibility-change-consequences。

Repository invitations

chatgh invitation list
chatgh invitation list --json-output
chatgh invitation accept 325100806 --json-output
chatgh invitation decline 325100806 --json-output

invitation 使用当前 ChatGH token resolution 逻辑读取 authenticated user 的 repository invitations。accept 和 decline 是远端写操作，只按 invitation id 执行，不自动猜测或批量处理邀请。

GitHub Projects

chatgh project list --owner ChatArch --json-output
chatgh project view 3 --owner ChatArch --json-output
chatgh project create --owner ChatArch --title "Roadmap" --json-output
chatgh project item add 3 --owner ChatArch --content-id ISSUE_OR_PR_NODE_ID --json-output
chatgh project item edit 3 --owner ChatArch --id PROJECT_ITEM_ID --field-id FIELD_ID --text "In progress" --json-output
chatgh project field list 3 --owner ChatArch --json-output

project 命令树不复刻官方 gh project 扁平形态。ChatGH 将 Project 本体、item、field 分开组织：project item add/edit/list/... 与 project field list/create/delete 是主入口，不保留 item-add / field-list 兼容别名。ChatGH 不使用官方 gh auth，继续使用 --token / repo-local token / ChatEnv GITHUB_ACCESS_TOKEN；写操作保留 ChatGH 安全门；每个 CLI 背后有可 import 的 chatgh.github.projects Python API。project 所有可恢复缺参路径遵守 ChatStyle：默认可自动补问，CHATARCH_AUTO_PROMPT=off 可让机器调用缺参时报错，-i 强制交互，-I 禁止交互。project item edit 对 GitHub Projects v2 的字段值类型做展开参数（--text、--number、--date、--single-select-option-id、--iteration-id、--clear）。

PR lifecycle / review

chatgh pr status --repo ChatArch/ChatGH --json-output
chatgh pr diff 14 --repo ChatArch/ChatGH
chatgh pr close 14 --repo ChatArch/ChatGH --comment "Superseded" --json-output
chatgh pr reopen 14 --repo ChatArch/ChatGH --json-output
chatgh pr review 14 --repo ChatArch/ChatGH --approve --body-file review.md
chatgh pr ready 14 --repo ChatArch/ChatGH --json-output
chatgh pr update-branch 14 --repo ChatArch/ChatGH --expected-head-sha SHA --json-output

close/reopen/review/ready/update-branch 都是远端写操作；执行前应确认目标 PR。

创建 PR

chatgh pr create --repo octocat/Hello-World --base main --head rex/feature --title "Add feature" --body-file pr-body.md
chatgh pr create --repo octocat/Hello-World --base main --head rex/feature --title "Add feature" --body "Short body" --json-output

pr create 会使用当前 ChatGH token resolution 逻辑，不会打印 token。缺少 base/head/title 时，可在交互终端自动补问；非交互可用 -I 明确失败。

查看 PR

chatgh pr list --repo octocat/Hello-World --state open --limit 20
chatgh pr view 123 --repo octocat/Hello-World
chatgh pr view 123 --repo octocat/Hello-World --json-output

pr view 输出会包含：

• PR number、title、state、author、URL。
• base/head branch。
• mergeable 和 mergeable_state。
• created/updated/merged timestamps。

查看 CI

chatgh pr checks 123 --repo octocat/Hello-World
chatgh pr checks 123 --repo octocat/Hello-World --json-output

pr checks 按 PR head commit 汇总三层信息：

• combined status
• check runs
• workflow runs

当前公开 CLI 不提供 --wait / --interval / --timeout 参数；需要等待终态时，在外层流程中轮询 chatgh pr checks。

如果 GitHub token 无权读取 check-runs API，命令会把 check-runs 错误放进 payload，同时仍尽量展示 combined status 和 workflow runs。

查看 Actions run 和 job logs

chatgh run list --repo octocat/Hello-World --limit 20
chatgh run watch 123456789 --repo octocat/Hello-World --timeout 600
chatgh run rerun 123456789 --repo octocat/Hello-World --json-output
chatgh run cancel 123456789 --repo octocat/Hello-World --json-output
chatgh run download 123456789 --repo octocat/Hello-World --dir ./artifacts

chatgh run view --repo octocat/Hello-World --run-id 123456789
chatgh run view --repo octocat/Hello-World --run-id 123456789 --json-output

chatgh run logs --repo octocat/Hello-World --job-id 987654321
chatgh run logs --repo octocat/Hello-World --job-id 987654321 --tail 0
chatgh run logs --repo octocat/Hello-World --job-id 987654321 --tail 200 --output job.log

run logs 默认只输出尾部日志；--tail 0 输出完整日志；--output 会把完整日志写入文件，终端仍显示 tail。

评论、合并和编辑 PR

chatgh pr comment 123 --repo octocat/Hello-World --body-file review-note.md
chatgh pr edit 123 --repo octocat/Hello-World --title "New title" --body-file pr-body.md
chatgh pr merge 123 --repo octocat/Hello-World --method squash --check

pr merge 默认使用 --method squash 和 --check，会在合并前读取 PR checks 并拒绝非绿色状态。合并仍然是高风险远程 mutation，实际执行前应先确认 PR 状态和用户授权。

Fork 仓库

# gh-like 形态
chatgh repo fork octocat/Hello-World --org ChatArch
chatgh repo fork octocat/Hello-World --org ChatArch --fork-name hello-world-copy --default-branch-only

# ChatGH 显式/自动化形态
chatgh repo fork --source octocat/Hello-World --owner ChatArch
chatgh repo fork --source octocat/Hello-World --owner ChatArch --name hello-world-copy --default-branch-only
chatgh repo fork --source octocat/Hello-World --owner ChatArch --if-exists use --json-output

repo fork 通过 GitHub Fork API 创建目标仓库；目标仓库名默认沿用 source repo 名。它兼容官方 gh repo fork [<repository>] --org ... --fork-name ... 的常见形态，同时保留 ChatGH 的显式 --source/--owner/--name 和 --json-output/--if-exists use 自动化扩展。目标为 organization 时会传递 GitHub API 的 organization 字段；目标为 user account 时，--owner 必须匹配当前认证用户。--if-exists use 只会复用已存在且匹配 source 的 fork，避免把同名非匹配仓库误当成功结果。

查看仓库保护规则

chatgh repo protection --repo octocat/Hello-World
chatgh repo protection --repo octocat/Hello-World --json-output
chatgh repo protection --owner octocat --limit 50 --jobs 8
chatgh repo protection --owner octocat --limit 50 --jobs 8 --json-output

repo protection 会展示默认分支、是否 protected、classic branch protection 细节（例如是否要求 PR、review 数量、是否允许 force push / deletion），以及 GitHub 可读取时的 repository ruleset 摘要。部分 private 仓库可能因为 GitHub plan/visibility 限制读取 rulesets 返回错误；命令会在 JSON 里保留该错误，同时尽量展示 branch protection 状态。owner inventory 模式会先列仓库，再用 --jobs 并发检查每个仓库，输出顺序保持稳定。

配置和检查 token

chatgh repo-perms --repo octocat/Hello-World --json-output
chatgh repo-perms --repo octocat/Hello-World --full-json

chatgh set-token --token "$GITHUB_ACCESS_TOKEN"
chatgh set-token --token "$GITHUB_ACCESS_TOKEN" --save-env

repo-perms 会展示：

• token 来源和 mask 后的 token。
• GitHub 返回的 permissions。
• 派生 capabilities：can_read_pr、can_comment_pr、can_merge_pr、can_view_checks、can_view_actions。

set-token 只在当前目录能识别 GitHub remote 时生效。默认只写入当前仓库自己的 .git/config：

[http "https://github.com/octocat/Hello-World.git"]
    extraHeader = Authorization: Basic <base64(x-access-token:TOKEN)>

不要把 token 写进 remote URL，也不要把 raw extraHeader 输出到日志。传 --save-env 时会同步写入 typed env 的 GITHUB_ACCESS_TOKEN。

交互模式

所有缺少可恢复关键参数的命令都走 chatstyle：

• 默认模式：终端可交互且缺参时自动补问。
• CHATARCH_AUTO_PROMPT=0/false/no/off：关闭默认自动补问，缺参时直接报错，适合机器/CI 调用。
• -i/--interactive：强制进入补问流程，即使 CHATARCH_AUTO_PROMPT=off 也会尝试交互。
• -I/--no-interactive：完全禁用补问，缺参时直接报错。

token 类输入使用 password prompt，不会明文回显。

推荐的 PR/CI 工作流

在创建 PR、汇报“CI 是否通过”或准备 merge 前，先同步最新 base：

git fetch origin main

然后确认：

• chatgh pr view / chatgh pr checks 显示 mergeable 不是 False，mergeable_state 不是 dirty。
• 本地基于最新 base 做过 merge 或 rebase 演练，并在该结果上跑过最相关测试。
• CI 需要终态时，在外层流程中轮询 chatgh pr checks，不要只看一次快照。

Python API

from chatgh.github.client import GitHubClient

client = GitHubClient(user_name="octocat", token="ghp_...")
prs = client.get_pull_requests("Hello-World")
view = client.get_pr_view("octocat/Hello-World", 1)
checks = client.get_pr_checks("octocat/Hello-World", 1)

底层模块也可按需导入：

• chatgh.github.api：token、仓库解析、git credential 和 REST 请求基础能力。
• chatgh.github.commands：CLI 使用的业务流程函数。
• chatgh.github.requests：PR/checks/actions payload 构造。
• chatgh.github.render：人类可读输出、merge blocker 和 tail helper。

与 ChatTool 的关系

chattool gh 的长期实现已迁移到 chatgh。ChatTool 可以保留薄 wrapper 兼容旧命令，但不应继续维护一份 forked GitHub 实现。ChatTool 内涉及 GitHub token/remote 的辅助逻辑也应导入 chatgh.github.api。

开发参考

扩展 chatgh 时应先看项目内接口规范：docs/gh-interface-alignment.md。常见 GitHub 能力要先参考官方 GitHub CLI gh 的命令形态和帮助文本；如果官方已有能力，优先兼容其命名、位置参数和常见 alias，再结合 ChatGH 的鉴权、JSON、安全门和 Python API 落地；如果官方没有，才设计 ChatGH-native surface。官方 gh 只作接口参考，不作为运行依赖、CI/ops fallback 或真实操作路径。

扩展时也要查官方 API 文档：

• GitHub REST API: https://docs.github.com/en/rest
• Pull requests API: https://docs.github.com/en/rest/pulls/pulls
• Check runs API: https://docs.github.com/en/rest/checks/runs
• Workflow runs API: https://docs.github.com/en/rest/actions/workflow-runs
• Workflow jobs API: https://docs.github.com/en/rest/actions/workflow-jobs
• Commit statuses API: https://docs.github.com/en/rest/commits/statuses
• PyGithub: https://pygithub.readthedocs.io/

本地验证：

python -m pytest -q
python -m build
mkdocs build --strict

默认测试使用 mock/fake payload 和临时目录，不调用真实 GitHub API，也不会污染真实 git credential 或 env 配置。