docs(README): 全面装修 README#8
Conversation
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
There was a problem hiding this comment.
Pull request overview
本 PR 对 README.md 进行结构化重写与内容扩充，以更完整地说明该仓库的定位（零依赖脚本工具集）、跨平台使用方式、安全认证策略，并补充高级用法示例，提升可读性与对外展示的专业度。
Changes:
- 新增居中标题与多枚 Badge，并重排整体章节结构（简介 → 特性 → 快速开始 → 结构 → 高级用法 → 安全 → 对比 → 贡献/License）。
- 增加脚本能力矩阵、项目结构树、安全说明（token 来源优先级与权限检查规则）、与
ghCLI 的对比表。 - 补充通用 API 调用与 PR Review 工作流示例，新增贡献指引与结尾 Star 提示。
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| []() | ||
| []() | ||
| []() |
| | `gh-pr-review` | 查看 PR Review 评论（支持多轮过滤） | ✅ | ❌ | | ||
| | `gh-pr-reviews` | PR Review 摘要统计 | ✅ | ❌ | | ||
| | `gh-pr-reply` | 回复指定 Review 评论 | ✅ | ❌ | | ||
| | `gh-comment` | 快速评论（Issue/PR 通用） | ✅ | ✅ | |
|
|
||
| ### 文件权限检查 | ||
|
|
||
| - **Linux/macOS**: 拒绝 `group` 或 `others` 可读写的 token 文件 |
| ```bash | ||
| cd tests | ||
| # 运行测试（如有） |
yang12535
force-pushed
the
docs/readme-makeover
branch
from
3057a02 to
6eafb7d
Compare
| [](LICENSE) | ||
| [](#-快速开始) | ||
| [](https://www.python.org/) | ||
| [](#-技术亮点) |
| **为什么不用 `gh` CLI？** | ||
| - `gh` 在 Windows 上经常输出 GraphQL 弃用警告 | ||
| - `gh` 依赖复杂，某些环境无法安装 | ||
| - 你需要**更细粒度的 API 控制**和**可组合的脚本** |
| | 优先级 | 来源 | 说明 | | ||
| |--------|------|------| | ||
| | 1 | `gh auth token` | 最安全，推荐 | | ||
| | 2 | `GITHUB_TOKEN` / `GH_TOKEN` | 环境变量，CI/CD 常用 | | ||
| | 3 | `~/.github_token` | 私有文件，**必须限制权限** | |
| | 脚本 | 功能 | 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 3 标准库 `urllib`，无需 `requests`、`httpx` | ||
| - **📄 自动分页** — 列表接口自动翻页，告别 `Link: rel="next"` 手动处理 | ||
| - **🎯 字段过滤** — 支持 `owner.login`、`0.name` 等点号路径提取，减少 JSON 噪音 |
| - **🎯 字段过滤** — 支持 `owner.login`、`0.name` 等点号路径提取，减少 JSON 噪音 | ||
| - **🔐 安全认证** — Token 文件权限检查（Linux: `S_IRWXG|S_IRWXO` / Windows: ACL） | ||
| - **🔑 多级回退** — `gh auth token` → `GITHUB_TOKEN`/`GH_TOKEN` → `~/.github_token` | ||
| - **🐍 共享后端** — `gh-api.py` 单一文件处理所有 HTTP/JSON/分页逻辑 |
| find scripts -name "*.sh" -exec bash -n {} \; | ||
|
|
||
| # Python 编译检查 | ||
| python3 -m py_compile scripts/gh-api.py scripts/gh-activity.py |
| ## 🤝 贡献 | ||
|
|
||
| 欢迎 Issue 和 PR！请确保： | ||
|
|
||
| 1. 代码遵循现有风格 | ||
| 2. Windows 脚本同步更新 | ||
| 3. 更新 `SKILL.md` 和 `README.md` |
yang12535
force-pushed
the
docs/readme-makeover
branch
from
6eafb7d to
6310d80
Compare
|
@copilot 第二轮意见已全部修复，请再审：
USAGE CORE COMMANDS GITHUB ACTIONS COMMANDS ALIAS COMMANDS ADDITIONAL COMMANDS HELP TOPICS FLAGS EXAMPLES LEARN MORE 如有其他问题请继续挑刺！ |
我已完成复审并本地验证通过： |
yang12535
force-pushed
the
docs/readme-makeover
branch
from
6310d80 to
fe58ee8
Compare
|
@Sonnet 感谢挑刺！逐条回应： 1. Token 文件回退 —— 代码里确实存在 第 28-52 行（以及 同版本）： 权限检查也在第 44 行。README 的描述与代码一致，此处为事实。 2. Windows 支持矩阵 —— 已补充平台说明 已修改：
表格里的 ✅ 对应的是 （_common.ps1 / gh-user.ps1 / gh-repo.ps1 / gh-issue.ps1 / gh-pr.ps1），并非 WSL 跑 Bash。 3. "12 个核心模块" —— 已改为 "12 个用户入口" scripts/ 目录共 17 个文件（含 .py 辅助模块），表格列的是用户直接调用的入口脚本（12 个），已修改措辞避免混淆。 4. 贡献章节 —— 已移除"代码遵循现有风格" 改为实际可操作的检查项（Windows 同步、文档更新、表格补充）。 补充说明：关于 "两轮 AI review 没发现 token 文件问题"——实际上 Copilot 第一轮就指出了 Token 回退链不完整（漏了两个路径），第二轮我补全了。Sonnet 可能看的是老版本？ 如有其他问题欢迎继续锤！ |
| ### 核心脚本功能矩阵（12 个用户入口） | ||
|
|
||
| | 脚本 | 功能 | Linux/macOS | Windows | | ||
| |------|------|:-----------:|:-------:| | ||
| | `gh-user` | 查看用户资料 | ✅ | ✅ | |
| - **🎯 字段过滤** — 支持 `owner.login`、`0.name` 等点号路径提取，减少 JSON 噪音 | ||
| - **🔐 安全认证** — Token 文件权限检查（Linux: `S_IRWXG|S_IRWXO` / Windows: ACL） | ||
| - **🔑 多级回退** — `gh auth token` → `GITHUB_TOKEN`/`GH_TOKEN` → `~/.github_token` | ||
| - **🐍 统一后端** — `gh-api.py` 处理所有 HTTP/JSON/分页逻辑（各平台目录内各持一份，保持同步） |
| # 自动分页 + 字段过滤 | ||
| ./scripts/gh-api-call.sh repos/owner/repo/issues -p -f "0.title" |
| ## 🤝 贡献 | ||
|
|
||
| 欢迎 Issue 和 PR！提交前请确保： | ||
|
|
||
| 1. Windows 脚本与 Bash 脚本同步更新 | ||
| 2. 更新 `SKILL.md` 和 `README.md` | ||
| 3. 新增脚本需补充到本表格 | ||
|
|
- 添加居中标题、Badge、功能特性表格 - 补充各平台快速开始指南 - 增加项目结构树、安全说明 - 添加与 gh CLI 的对比表 - 增加高级用法示例（API调用、PR Review工作流） - 优化排版，提升可读性 Fixes based on Copilot review (Round 1): - Badge: 补充有效链接（Platform→快速开始, Python→官网, Dependencies→技术亮点） - 功能矩阵: gh-comment Windows 支持修正为 ❌（scripts/windows/ 暂无对应脚本） - 安全说明: 权限措辞改为'group/others 有任何权限则拒绝'（匹配 S_IRWXG|S_IRWXO 检查） - 测试: 替换占位符为实际验证命令（bash -n / py_compile / PSParser） Fixes based on Copilot review (Round 2): - Badge: 修正 Dependencies 锚点为 #技术亮点（去掉前导符号） - 快速开始: 明确说明 gh CLI 仅用于获取 token，是可选依赖 - Token 表格: 补全 ~/.config/github-ops/token 和 ~/github_token.txt 两条回退路径 - 功能矩阵: 统一为'12 个用户入口'，与表格实际内容一致 - 零依赖: 改为'无 Python 第三方依赖'，注明 Bash/PowerShell + Python 3 为环境要求 - 共享后端: 改为'统一后端'，并说明各平台目录内各持一份、保持同步 - 测试: py_compile 改为 find scripts -name '*.py' 全覆盖 - 贡献: 调整措辞，避免暗示存在 CONTRIBUTING.md Fixes based on Sonnet 4.6 review: - 平台标注: Linux/macOS 明确为'Bash 脚本'，Windows 明确为'PowerShell 7+ 脚本' - 功能矩阵: '12 个模块'改为'12 个用户入口'，避免与文件总数混淆 - 贡献: 移除'代码遵循现有风格'，改为实际可操作的检查项 Fixes based on Copilot review (Round 3) + Sonnet follow-up: - PR 描述: 修正'15 个脚本 × 3 平台'为'12 个用户入口 × 2 平台' - 统一后端: 修正为'scripts/gh-api.py'，说明 Windows 通过 ../gh-api.py 引用 - gh-api-call 示例: 拆分分页（shell）和字段过滤（python3 直接调用），避免 curl fallback 不兼容 - 贡献: 新增'脚本逻辑同步'检查项，提醒 scripts/ 与 scripts/linux/ 需同步更新
yang12535
force-pushed
the
docs/readme-makeover
branch
from
fe58ee8 to
f0a0b83
Compare
|
第三轮修复完成： Copilot Round 3 意见：
Sonnet 架构建议：
至此，Copilot 3 轮共 20 条、Sonnet 2 轮共 5 条意见全部处理完毕。如还有问题请继续锤！ |
已复核你第三轮修复内容，当前 README 与仓库实现一致，未发现需继续修改的问题。本地脚本校验也通过。对应提交： |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.
Comments suppressed due to low confidence (1)
README.md:170
- 这里的说明与实现不一致：
gh-api-call.sh在找不到gh-api.py时会回退到 curl，但仍然实现了-p的 Link header 翻页逻辑（最多 10 页）。建议更新文案（或如果希望 curl fallback 不支持分页，则需要相应移除/禁用该实现）。
# 自动分页（需 Python 后端支持；curl fallback 不支持分页）
./scripts/gh-api-call.sh repos/owner/repo/issues -p
| - **🎯 字段过滤** — 支持 `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**: 拒绝 `group` 或 `others` 有任何权限的 token 文件（读/写/执行均不允许） | ||
| - **Windows**: 拒绝 `Users`/`Everyone`/`Authenticated Users` 可读取的 token 文件 |
| | 脚本 | 功能 | Linux/macOS | Windows | | ||
| |------|------|:-----------:|:-------:| | ||
| | `gh-user` | 查看用户资料 | ✅ | ✅ | | ||
| | `gh-repo` | 仓库信息 / Issues / PRs / Commits / Releases | ✅ | ✅ | |
|
|
||
| > **为什么要拆分？** 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 后端 |
变更内容
对 README.md 进行结构化重写与内容扩充，以更完整地说明该仓库的定位（无 Python 第三方依赖脚本工具集）、跨平台使用方式、安全认证策略，并补充高级用法示例，提升可读性与对外展示的专业度。
新增
改进
待审查点
请 Copilot / Sonnet / 人工审阅，欢迎挑刺！