Metadata-Version: 2.4
Name: chatgh
Version: 0.2.10
Summary: GitHub CLI and Python helpers for ChatArch
Author-email: ChatArch <1073853456@qq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ChatArch/ChatGH
Project-URL: Repository, https://github.com/ChatArch/ChatGH
Project-URL: Documentation, https://arch.gh.wzhecnu.cn/ChatGH/
Keywords: chatgh,chatarch,cli
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: chatstyle<0.2.0,>=0.1.0
Requires-Dist: chatenv<0.3.0,>=0.2.0
Requires-Dist: PyGithub>=2.0
Requires-Dist: requests>=2.0
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: tomli; python_version < "3.11" and extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs<2.0,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<9.7,>=9.5; extra == "docs"
Requires-Dist: mkdocs-static-i18n<2.0,>=1.2; extra == "docs"
Requires-Dist: mike<3.0,>=2.0; extra == "docs"
Dynamic: license-file

# chatgh

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

## 安装

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

## 配置模型

默认行为：

- `repo`：优先使用显式 `--repo owner/repo`，未传时从当前 git remote 推断。
- `token`：优先使用显式 `--token`，其次读取当前仓库 `.git/config` 中仓库本地 HTTPS 授权头，再回退类型化环境配置里的 `GITHUB_ACCESS_TOKEN`。
- 输出：默认是人类可读格式；支持 `--json FIELDS` 的命令会按字段投影输出官方 `gh` 风格 JSON，`--json-output` 保留为完整载荷 JSON，适合脚本消费。

### 令牌来源

令牌解析顺序稳定为：

1. 显式 `--token`。
2. 当前仓库 `.git/config` 中的仓库本地 HTTPS 授权头，路径为规范化后的 `https://github.com/owner/repo.git`。
3. 类型化环境配置中的 `GITHUB_ACCESS_TOKEN`。

可以用 `chatenv` 查看或配置类型化环境配置：

```bash
chatenv init -t gh
chatenv cat -t gh
```

安装 `chatgh` 后，它会通过 `chatenv.configs` 入口点注册 `GitHubConfig`，所以 `chatenv list` 会出现 `[GitHub]` 分组，`-t gh` / `-t github` 可以解析到同一份 GitHub 类型化环境配置。

`ghp_xxx` / `github_pat_xxx` 都是 GitHub 个人访问令牌。通常 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`

写入仓库本地 HTTPS 授权头时，路径会规范化为 `https://github.com/octocat/Hello-World.git`。

## 命令入口

文档导航：

- 文档站点：`https://arch.gh.wzhecnu.cn/ChatGH/`，在 `mkdocs.yml` 的 `site_url` 中维护。
- 文档语言：使用 `mkdocs-static-i18n` 的后缀模式；中文是默认站点，英文镜像文件使用 `.en.md` 后缀并生成到 `/en/`，不要在 `nav` 里把中英文拆成两套入口。
- `docs/interface-tree.md`：当前 CLI 树、目标方向、职责和 CLI -> Python API 映射，按 ChatTea / ChatZulip 的接口树风格维护。
- `docs/gh-interface-alignment.md`：官方 `gh` 对齐原则、分层和测试要求。
- `docs/agent-definition.md`：ChatGH 机器人定义、manifest、流程、权限和运行时边界。
- `docs/agent-task-bot-alignment.md`：官方 `gh agent-task`、`gh skill`、GitHub Apps、webhook 和机器人探索，以及 ChatGH 的代理任务与机器人方向。

```bash
chatgh --help
chatgh --tree
chatgh pr --help
chatgh repo --help
chatgh invitation --help
chatgh project --help
chatgh run --help
chatgh repo-perms --help
chatgh set-token --help
```

命令树（`chatgh --tree` 可从已注册 Click 命令实时生成完整树）：

- `chatgh --tree`：输出当前注册命令树、参数/选项签名和一行用途说明，用作验收/readback。
- `chatgh pr list/create/view/comment/edit/checks/merge`：已有 PR 基础流程；`merge` 默认 `--check`，不能当 dry-run。
- `chatgh pr status/diff/close/reopen/review/ready/update-branch`：常见 PR 生命周期和评审命令；写操作复用 ChatGH 令牌解析，且不会打印 token。
- `chatgh repo list/create/fork/transfer/protection`：已有仓库列表、创建、fork、所有权迁移、保护规则检查。
- `chatgh repo view/clone/sync/edit`：常见 repo 命令；`clone/sync` 对本地 git 副作用保持显式、保守，不覆盖已有非空目录。
- `chatgh invitation list/accept/decline`：查看和处理当前账号收到的 GitHub 仓库邀请；对齐 GitHub REST API 的认证用户邀请能力。
- `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`：查看令牌权限和派生能力。
- `chatgh set-token`：为当前 GitHub 仓库配置仓库级 HTTPS 令牌。

## 常用流程

### 查看、克隆、同步和编辑仓库

```bash
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`。

### 仓库邀请

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

`invitation` 使用当前 ChatGH 令牌解析逻辑读取认证用户收到的仓库邀请。`accept` 和 `decline` 是远端写操作，只按邀请 ID 执行，不自动猜测或批量处理邀请。

### GitHub 项目

```bash
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 生命周期和评审

```bash
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

```bash
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。缺少 `base/head/title` 时，可在交互终端自动补问；非交互可用 `-I` 明确失败。

### 查看 PR

```bash
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`。
- 创建、更新和合并时间戳。

### 查看 CI

```bash
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 run
- workflow run

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

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

### 查看 Actions 运行和作业日志

```bash
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

```bash
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 并拒绝非绿色状态。合并仍然是高风险远端变更，实际执行前应先确认 PR 状态和用户授权。

### 创建 fork

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

### 迁移仓库所有权

```bash
chatgh repo transfer ChatArch/ExampleRepo --owner OmniCAS --dry-run --json-output
chatgh repo transfer ChatArch/ExampleRepo --owner OmniCAS --accept-transfer-consequences --json-output
```

`repo transfer` 调用 GitHub Repository Transfer API，把仓库所有权转移到目标 user/org；这不同于 `repo fork`，会保留 issue、PR、stars、settings 等仓库身份，并由 GitHub 处理 redirect。命令默认建议先 `--dry-run` 检查 source 权限和目标同名仓库是否已存在；真正执行必须显式传 `--accept-transfer-consequences`，因为 transfer 会影响访问权限、webhook、secrets、GitHub Pages 和自动化。转移到组织时可重复传 `--team-id` 让 GitHub 在转移后给指定 team 授权。

### 查看仓库保护规则

```bash
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` 并发检查每个仓库，输出顺序保持稳定。

### 配置和检查令牌

```bash
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` 会展示：

- 令牌来源和脱敏后的令牌。
- GitHub 返回的 `permissions`。
- 派生能力：`can_read_pr`、`can_comment_pr`、`can_merge_pr`、`can_view_checks`、`can_view_actions`。

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

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

不要把 token 写进 remote URL，也不要把原始 `extraHeader` 输出到日志。传 `--save-env` 时会同步写入类型化环境配置的 `GITHUB_ACCESS_TOKEN`。

## 交互模式

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

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

令牌类输入使用密码式补问，不会明文回显。

## 推荐的 PR/CI 工作流

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

```bash
git fetch origin main
```

然后确认：

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

## Python API

```python
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`：令牌、仓库解析、git credential 和 REST 请求基础能力。
- `chatgh.github.commands`：CLI 使用的业务流程函数。
- `chatgh.github.requests`：PR/checks/actions 载荷构造。
- `chatgh.github.render`：人类可读输出、合并阻断信息和尾部日志辅助函数。

## 与 ChatTool 的关系

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

## 开发参考

扩展 `chatgh` 时应先看项目内接口规范：`docs/interface-tree.md`、`docs/gh-interface-alignment.md`、`docs/agent-definition.md` 和 `docs/agent-task-bot-alignment.md`。常见 GitHub 能力要先参考官方 GitHub CLI `gh` 的命令形态和帮助文本；如果官方已有能力，优先兼容其命名、位置参数和常见 alias，再结合 ChatGH 的鉴权、JSON、安全门和 Python API 落地；如果官方没有，才设计 ChatGH 原生命令面。官方 `gh` 只作接口参考，不作为运行依赖、CI/ops fallback 或真实操作路径。Agent/bot 相关能力还必须明确区分 GitHub 托管 Copilot / CAPI 代理任务与 ChatGH 自托管事件到运行器桥接。

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

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

本地验证：

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

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