docs(README): 全面装修 README

README.md

@@ -1,73 +1,285 @@
-# GitHub 运维工具集
+<div align="center">
 
-一组轻量级的脚本，用于调用 GitHub REST API。
+# 🛠️ GitHub Ops
 
-现已按平台拆分 —— 因为 **Windows 不是 Unix**。
+**轻量级 GitHub 运维工具集 — 零依赖、跨平台、AI 友好**
 
-## 简介
+[![License](https://img.shields.io/badge/License-CC%20BY%204.0-orange.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-blue.svg)](#-快速开始)
+[![Python](https://img.shields.io/badge/Python-3.8%2B-green.svg)](https://www.python.org/)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-None-brightgreen.svg)](#技术亮点)
 
-**作者：** [yang12535](https://github.com/yang12535)
+</div>
 
-本项目提供了一套依赖极简的工具集，覆盖日常 GitHub 工作流：
+---
 
-- **直接调用 API**：通过 Python（`urllib`）或 `curl`，无需笨重的 SDK。
-- **认证方式**：优先使用 `gh auth token`，也可通过 `GITHUB_TOKEN` / `GH_TOKEN` 环境变量回退。
-- **快捷脚本**：查看仓库、议题、PR、评论、活动流、通知，以及 Git 同步辅助。
+## 📖 简介
 
-所有脚本力求可读、可组合、易扩展。
+一组**零第三方依赖**的脚本工具，通过 GitHub REST API 直接操作仓库、Issue、PR、评论等，覆盖日常 GitHub 工作流。
 
-## 平台划分
+**为什么不用 `gh` CLI？**
+- `gh` 在 Windows 上经常输出 GraphQL 弃用警告
+- `gh` 依赖复杂，某些环境无法安装
+- 你需要**更细粒度的 API 控制**和**可组合的脚本**
 
-| 平台 | 目录 | 运行环境 | 说明 |
-|---|---|---|---|
-| **Linux / macOS** | `scripts/linux/` | Bash + Python 3 | 原版技术栈，需要 `python3` |
-| **Windows** | `scripts/windows/` | PowerShell 7+ | 薄包装层 → `scripts/gh-api.py`，需要 Python 3.8+ |
-| **旧版（通用）** | `scripts/` | Bash + Python 3 | 保留向后兼容 |
+> 💡 **注意**：下文推荐用 `gh auth login` 获取 token，但 `gh` CLI 本身是**可选的**。不安装时，可用环境变量或 token 文件完成认证。
 
-> **为什么要拆分？** Windows 实验环境的 Python 安装路径往往不标准（比如 `D:\python313\python`），而且 `gh` CLI 经常输出 GraphQL 弃用警告。PowerShell 包装层原生处理 Windows 路径，然后把所有 HTTP/JSON/分页逻辑委托给共享的 Python 后端（`scripts/gh-api.py`）。所有平台均需要 Python 3.8+。
+**设计哲学**：
+- **薄包装层** — Bash/PowerShell 只做参数解析，HTTP/JSON/分页逻辑全部委托给共享 Python 后端
+- **失败即指令** — 遇到缺失依赖时，输出清晰的修复指令，不猜测、不静默失败
+- **AI 原生** — 完整的 `SKILL.md` 供 AI Agent 直接消费
 
-## 快速开始
+---
 
-### Linux / macOS
+## ✨ 功能特性
+
+### 核心脚本功能矩阵（12 个用户入口）
+
+| 脚本 | 功能 | Linux/macOS | Windows |
+|------|------|:-----------:|:-------:|
+| `gh-user` | 查看用户资料 | ✅ | ✅ |
+| `gh-repo` | 仓库信息 / Issues / PRs / Commits / Releases | ✅ | ✅ |
+| `gh-issue` | 创建 / 关闭 / 重开 / 评论 Issue | ✅ | ✅ |
+| `gh-pr` | 创建 / 合并 / 评论 PR | ✅ | ✅ |
+| `gh-pr-review` | 查看 PR Review 评论（支持多轮过滤） | ✅ | ❌ |
+| `gh-pr-reviews` | PR Review 摘要统计 | ✅ | ❌ |
+| `gh-pr-reply` | 回复指定 Review 评论 | ✅ | ❌ |
+| `gh-comment` | 快速评论（Issue/PR 通用） | ✅ | ❌ |
+| `gh-activity` | 用户活动流查询（支持事件过滤） | ✅ | ❌ |
+| `gh-notify` | 查看 / 标记已读通知 | ✅ | ❌ |
+| `gh-push` / `gh-pull` | Git 同步辅助 | ✅ | ❌ |
+| `gh-api-call` | 通用 API 调用（任意端点） | ✅ | ❌ |
+
+### 技术亮点
+
+- **🚀 无 Python 第三方依赖** — 仅用标准库 `urllib`，无需 `requests`、`httpx`（需 Bash/PowerShell + Python 3）
+- **📄 自动分页** — 列表接口自动翻页，告别 `Link: rel="next"` 手动处理
+- **🎯 字段过滤** — 支持 `owner.login`、`0.name` 等点号路径提取，减少 JSON 噪音
+- **🔐 安全认证** — Token 文件权限检查（Linux: `S_IRWXG|S_IRWXO` / Windows: ACL）
+- **🔑 多级回退** — `gh auth token` → `GITHUB_TOKEN`/`GH_TOKEN` → `~/.github_token`
+- **🐍 统一后端** — `scripts/gh-api.py` 处理所有 HTTP/JSON/分页逻辑，各平台包装器统一引用（Windows 通过 `../gh-api.py` 引用）
+
+---
+
+## 🚀 快速开始
+
+### 环境要求
+
+- **Linux / macOS**: Bash + Python 3.8+
+- **Windows**: PowerShell 7+ + Python 3.8+
+
+### 1. 克隆仓库
 
 ```bash
-# 用户资料
-scripts/linux/gh-user.sh
+git clone https://github.com/yang12535/github-ops.git
+cd github-ops
+```
 
-# 仓库信息
-scripts/linux/gh-repo.sh owner/repo view
+### 2. 配置认证（三选一）
 
-# 列出开放议题
-scripts/linux/gh-issue.sh owner/repo list
+**方式 A — 推荐**：使用 GitHub CLI
+```bash
+gh auth login
+```
+
+**方式 B**：环境变量
+```bash
+export GITHUB_TOKEN="ghp_xxxxxxxx"
 ```
 
-### Windows（PowerShell）
+**方式 C**：私有 token 文件
+```bash
+echo "ghp_xxxxxxxx" > ~/.github_token
+chmod 600 ~/.github_token
+```
+
+### 3. 跑起来！
+
+**Linux / macOS**（Bash 脚本）
+```bash
+# 查看当前用户
+./scripts/linux/gh-user.sh
+
+# 查看仓库信息
+./scripts/linux/gh-repo.sh yang12535/github-ops view
+
+# 列出开放 Issues
+./scripts/linux/gh-issue.sh yang12535/github-ops list
+
+# 查看最近活动
+./scripts/linux/gh-activity.sh yang12535 10
+```
 
+**Windows**（PowerShell 7+ 脚本）
 ```powershell
-# 用户资料
-scripts/windows/gh-user.ps1
+# 查看当前用户
+./scripts/windows/gh-user.ps1
+
+# 查看仓库信息
+./scripts/windows/gh-repo.ps1 yang12535/github-ops view
+
+# 列出开放 PRs
+./scripts/windows/gh-pr.ps1 yang12535/github-ops list
+```
+
+---
+
+## 📁 项目结构
+
+```
+github-ops/
+├── scripts/                  # 旧版通用脚本（向后兼容）
+│   ├── gh-api.py            # 🐍 核心 API 引擎（分页/字段过滤/认证）
+│   ├── gh-user.sh           # 用户资料查询
+│   ├── gh-repo.sh           # 仓库操作
+│   ├── gh-issue.sh          # Issue 管理
+│   ├── gh-pr.sh             # PR 管理
+│   ├── gh-pr-review.sh      # PR Review 评论查看
+│   ├── gh-comment.sh        # 通用评论
+│   ├── gh-activity.py       # 活动流查询
+│   └── ...
+├── scripts/linux/           # Linux / macOS 平台脚本
+├── scripts/windows/         # Windows PowerShell 脚本
+│   ├── _common.ps1          # 认证 + API 调用共享模块
+│   ├── gh-user.ps1
+│   ├── gh-repo.ps1
+│   ├── gh-issue.ps1
+│   └── gh-pr.ps1
+├── tests/                   # 测试用例
+├── SKILL.md                 # 🤖 AI Agent 使用文档
+├── README.md                # 本文档
+├── CHANGELOG.md             # 更新日志
+└── LICENSE                  # CC BY 4.0
+```
+
+---
+
+## 🔧 高级用法
+
+### 通用 API 调用
+
+```bash
+# GET 请求
+./scripts/gh-api-call.sh user
 
-# 仓库信息
-scripts/windows/gh-repo.ps1 owner/repo view
+# POST 请求创建 Issue
+./scripts/gh-api-call.sh repos/owner/repo/issues -X POST \
+  -d '{"title":"bug","body":"something broke"}'
 
-# 列出开放 PR
-scripts/windows/gh-pr.ps1 owner/repo list
+# 自动分页（需 Python 后端支持；curl fallback 不支持分页）
+./scripts/gh-api-call.sh repos/owner/repo/issues -p
 
-# 创建 PR
-scripts/windows/gh-pr.ps1 owner/repo create "标题" "head-branch" "main" --body "PR 描述"
+# 字段过滤（直接调用 Python 后端）
+python3 scripts/gh-api.py repos/owner/repo/issues -p -f "0.title"
 ```
 
-完整命令参考与高级用法请见 `SKILL.md`。
+### Python 底层引擎
 
-## 许可证
+```bash
+# 查询并提取字段
+python3 scripts/gh-api.py repos/owner/repo -f owner.login
+
+# 自动分页获取所有 Issues
+python3 scripts/gh-api.py repos/owner/repo/issues -p -c
+
+# PATCH 更新 Issue
+python3 scripts/gh-api.py -X PATCH -d '{"state":"closed"}' \
+  repos/owner/repo/issues/1
+```
+
+### PR Review 工作流
+
+```bash
+# 查看最新一轮 Review 评论
+./scripts/gh-pr-review.sh owner/repo 8 --latest
+
+# 查看全部 Review 轮次摘要
+./scripts/gh-pr-reviews.sh owner/repo 8
+
+# 回复指定评论
+./scripts/gh-pr-reply.sh owner/repo 8 12345678 "Fixed in commit abc"
+```
+
+---
+
+## 🔐 安全说明
+
+### Token 存储
+
+| 优先级 | 来源 | 说明 |
+|--------|------|------|
+| 1 | `gh auth token` | 最安全，推荐（`gh` CLI 可选） |
+| 2 | `GITHUB_TOKEN` / `GH_TOKEN` | 环境变量，CI/CD 常用 |
+| 3 | `~/.github_token` | 私有文件，**必须限制权限** |
+| 4 | `~/.config/github-ops/token` | 备选私有文件 |
+| 5 | `~/github_token.txt` | 备选私有文件（向后兼容） |
+
+### 文件权限检查
+
+- **Linux/macOS**: 拒绝 `group` 或 `others` 有任何权限的 token 文件（读/写/执行均不允许）
+- **Windows**: 拒绝 `Users`/`Everyone`/`Authenticated Users` 可读取的 token 文件
+
+```bash
+# 正确示例
+chmod 600 ~/.github_token
+```
+
+---
+
+## 🆚 与 `gh` CLI 对比
+
+| 能力 | `gh` CLI | github-ops |
+|------|:--------:|:----------:|
+| 安装依赖 | 需要安装 `gh` | 只需 Python 3 |
+| Windows 兼容性 | GraphQL 警告 | 原生 PowerShell |
+| 脚本组合 | 受限 | 完全可组合 |
+| API 粒度 | 高层封装 | 直接访问 REST API |
+| AI Agent 消费 | 无结构化文档 | 完整 `SKILL.md` |
+| 字段过滤 | ❌ | ✅ 点号路径 |
+| 自动分页 | 部分支持 | ✅ 完整支持 |
+
+---
+
+## 🧪 测试与验证
+
+```bash
+# Shell 脚本语法检查
+find scripts -name "*.sh" -exec bash -n {} \;
+
+# Python 编译检查（含 scripts/ 与 scripts/linux/）
+find scripts -name "*.py" -exec python3 -m py_compile {} \;
+
+# PowerShell 语法检查（Windows）
+Get-ChildItem scripts/windows -Filter "*.ps1" | ForEach-Object {
+    $null = [System.Management.Automation.PSParser]::Tokenize(
+        (Get-Content $_.FullName -Raw), [ref]$null
+    )
+}
+```
+
+---
+
+## 🤝 贡献
+
+欢迎 Issue 和 PR！提交前请确保：
+
+1. **脚本逻辑同步**：修改 `scripts/` 或 `scripts/linux/` 下的 `.py` 逻辑时，需同步更新另一份副本（当前为复制关系，未来可考虑 symlink）
+2. Windows 脚本与 Bash 脚本同步更新
+3. 更新 `SKILL.md` 和 `README.md`
+4. 新增脚本需补充到本表格
+
+---
+
+## 📜 License
 
 本作品采用 [Creative Commons Attribution 4.0 International License](LICENSE) 授权。
 
-您可以：
+您可以自由地共享和改编，只需适当署名。
+
+---
 
-- **共享** — 以任何媒介或格式复制、 redistribute 本材料
-- **改编** — 再混音、转换、基于本材料进行创作，包括商业用途
+<div align="center">
 
-需遵守以下条款：
+**⭐ 如果这个项目对你有帮助，请点个 Star！**
 
-- **署名** — 您必须给出适当的署名，提供许可证链接，并注明是否做了修改。
+</div>