diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..4fbe1cf --- /dev/null +++ b/skills/README.md @@ -0,0 +1,343 @@ +# GitLink CLI Skills 指南 + +欢迎使用 GitLink CLI Skills！本指南帮助你快速上手和充分利用 gitlink-cli 的所有功能。 + +--- + +## 快速开始 + +### 1. 安装和认证 + +```bash +# 首次使用：登录 +gitlink-cli auth login + +# 验证登录状态 +gitlink-cli auth status +``` + +详见: [`gitlink-shared/examples/auth-workflow.md`](gitlink-shared/examples/auth-workflow.md) + +### 2. 查看可用命令 + +```bash +# 列出所有 Shortcuts +gitlink-cli --help + +# 查看特定命令帮助 +gitlink-cli repo --help +gitlink-cli issue --help +``` + +### 3. 使用 JSON 格式便于脚本处理 + +```bash +# 所有命令都支持 --format json +gitlink-cli user +me --format json +gitlink-cli repo +list --format json +``` + +--- + +## Skills 目录结构 + +``` +skills/ +├── README.md # 本文件 +├── gitlink-shared/ # 共享基础规则 +│ ├── SKILL.md # 认证、全局参数、安全规则 +│ ├── REFERENCE.md # API 详细参考 +│ ├── TROUBLESHOOTING.md # 常见问题排查 +│ └── examples/ +│ └── auth-workflow.md # 认证工作流示例 +├── gitlink-repo/ # 仓库管理 +│ ├── SKILL.md # 仓库操作指南 +│ ├── REFERENCE.md # 仓库 API 参考 +│ └── examples/ +│ └── repo-workflow.md # 仓库管理工作流 +├── gitlink-issue/ # Issue 管理 +│ ├── SKILL.md # Issue 操作指南 +│ ├── REFERENCE.md # Issue API 参考 +│ └── examples/ +│ └── issue-workflow.md # Issue 全流程工作流 +├── gitlink-pr/ # Pull Request +│ ├── SKILL.md # PR 操作指南 +│ └── REFERENCE.md # PR API 参考 +├── gitlink-branch/ # 分支管理 +│ └── SKILL.md # 分支操作指南 +├── gitlink-release/ # 版本发布 +│ ├── SKILL.md # Release 操作指南 +│ └── examples/ +│ └── release-workflow.md # Release 工作流 +├── gitlink-search/ # 搜索功能 +│ └── SKILL.md # 搜索操作指南 +├── gitlink-user/ # 用户管理 +│ └── SKILL.md # 用户操作指南 +├── gitlink-org/ # 组织管理 +│ └── SKILL.md # 组织操作指南 +├── gitlink-ci/ # CI/CD +│ └── SKILL.md # CI 操作指南 +├── gitlink-pm/ # 项目管理 +│ └── SKILL.md # PM 操作指南 +└── gitlink-workflow/ # AI 自动化工作流 + └── SKILL.md # 工作流模板 +``` + +--- + +## 所有 Skills 概览 + +### 核心 Skills + +| Skill | 说明 | 常用命令 | +|-------|------|----------| +| **gitlink-shared** | 认证、全局参数、API 参考 | `auth login`, `auth status` | +| **gitlink-repo** | 仓库管理 | `repo +list`, `repo +create`, `repo +info` | +| **gitlink-issue** | Issue 管理 | `issue +create`, `issue +list`, `issue +close` | +| **gitlink-pr** | Pull Request | `pr +list`, `pr +create`, `pr +merge` | +| **gitlink-branch** | 分支管理 | `branch +list`, `branch +create`, `branch +protect` | +| **gitlink-release** | 版本发布 | `release +list`, `release +create`, `release +view` | + +### 辅助 Skills + +| Skill | 说明 | 常用命令 | +|-------|------|----------| +| **gitlink-search** | 搜索功能 | `search +repos`, `search +users` | +| **gitlink-user** | 用户管理 | `user +me`, `user +info` | +| **gitlink-org** | 组织管理 | `org +list`, `org +info`, `org +members` | +| **gitlink-ci** | CI/CD | `ci +builds`, `ci +logs` | +| **gitlink-pm** | 项目管理 | 通过 Raw API 访问 | +| **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、Release Notes | + +--- + +## 使用指南 + +### 场景 1: 查看仓库信息 + +```bash +# 在仓库目录下自动解析 owner/repo +cd ~/my-project +gitlink-cli repo +info + +# 或显式指定 +gitlink-cli repo +info --owner wbtiger --repo gitlink-cli +``` + +详见: [`gitlink-repo/SKILL.md`](gitlink-repo/SKILL.md) + +### 场景 2: 创建和管理 Issue + +```bash +# 创建 Issue +gitlink-cli issue +create -t "Bug: 登录失败" -b "复现步骤..." + +# 查看 Issue +gitlink-cli issue +view -i 123 + +# 添加评论 +gitlink-cli issue +comment -i 123 -b "已修复" + +# 关闭 Issue +gitlink-cli issue +close -i 123 +``` + +详见: [`gitlink-issue/examples/issue-workflow.md`](gitlink-issue/examples/issue-workflow.md) + +### 场景 3: 管理分支和发布 + +```bash +# 创建分支 +gitlink-cli branch +create -n develop + +# 保护分支 +gitlink-cli branch +protect -n master + +# 创建 Release +gitlink-cli release +create -t v1.0.0 -n "v1.0.0 正式版" -b "更新内容..." + +# 查看 Release +gitlink-cli release +view -i +``` + +详见: [`gitlink-release/examples/release-workflow.md`](gitlink-release/examples/release-workflow.md) + +### 场景 4: 搜索和发现 + +```bash +# 搜索仓库 +gitlink-cli search +repos -k "machine learning" + +# 搜索用户 +gitlink-cli search +users -k "zhangsan" + +# 查看组织 +gitlink-cli org +list +gitlink-cli org +info -i Gitlink +``` + +详见: [`gitlink-search/SKILL.md`](gitlink-search/SKILL.md) + +--- + +## 文档导航 + +### 快速查找 + +- **我想了解认证**: [`gitlink-shared/SKILL.md`](gitlink-shared/SKILL.md) +- **我想查看 API 细节**: [`gitlink-shared/REFERENCE.md`](gitlink-shared/REFERENCE.md) +- **我遇到了错误**: [`gitlink-shared/TROUBLESHOOTING.md`](gitlink-shared/TROUBLESHOOTING.md) +- **我想看工作流示例**: 查看各 Skill 下的 `examples/` 目录 + +### 按功能分类 + +**仓库操作**: +- [`gitlink-repo/SKILL.md`](gitlink-repo/SKILL.md) - 仓库命令 +- [`gitlink-branch/SKILL.md`](gitlink-branch/SKILL.md) - 分支命令 +- [`gitlink-repo/examples/repo-workflow.md`](gitlink-repo/examples/repo-workflow.md) - 完整工作流 + +**Issue 和 PR**: +- [`gitlink-issue/SKILL.md`](gitlink-issue/SKILL.md) - Issue 命令 +- [`gitlink-pr/SKILL.md`](gitlink-pr/SKILL.md) - PR 命令 +- [`gitlink-issue/examples/issue-workflow.md`](gitlink-issue/examples/issue-workflow.md) - Issue 工作流 + +**发布和搜索**: +- [`gitlink-release/SKILL.md`](gitlink-release/SKILL.md) - Release 命令 +- [`gitlink-search/SKILL.md`](gitlink-search/SKILL.md) - 搜索命令 + +**组织和用户**: +- [`gitlink-org/SKILL.md`](gitlink-org/SKILL.md) - 组织命令 +- [`gitlink-user/SKILL.md`](gitlink-user/SKILL.md) - 用户命令 + +--- + +## 常见问题 + +### Q: 如何在脚本中使用 gitlink-cli？ + +A: 使用 `--format json` 获取结构化输出： + +```bash +gitlink-cli repo +list --format json | jq '.data.projects[] | .name' +``` + +### Q: 如何自动解析 owner/repo？ + +A: 在 git 仓库目录下运行命令，CLI 会自动从 `git remote origin` 解析： + +```bash +cd ~/my-project +gitlink-cli repo +info # 自动使用当前仓库 +``` + +### Q: Token 过期了怎么办？ + +A: 重新登录： + +```bash +gitlink-cli auth login +``` + +### Q: 如何查看完整的 API 参考？ + +A: 查看 [`gitlink-shared/REFERENCE.md`](gitlink-shared/REFERENCE.md) + +### Q: 遇到错误怎么办？ + +A: 查看 [`gitlink-shared/TROUBLESHOOTING.md`](gitlink-shared/TROUBLESHOOTING.md) + +--- + +## 三层命令体系 + +gitlink-cli 提供三层命令，满足不同需求： + +### Layer 1: Shortcuts（推荐） + +高级封装，语义清晰，适合日常使用： + +```bash +gitlink-cli repo +info +gitlink-cli issue +create -t "标题" +gitlink-cli pr +list +``` + +### Layer 2: Raw API + +原始 API 调用，覆盖所有端点： + +```bash +gitlink-cli api GET /users/me +gitlink-cli api POST /:owner/:repo/issues --body '{"subject":"..."}' +``` + +### Layer 3: 配置和认证 + +系统级命令： + +```bash +gitlink-cli auth login +gitlink-cli config set key value +``` + +--- + +## 输出格式 + +所有命令支持多种输出格式： + +```bash +# JSON（默认，推荐用于脚本） +gitlink-cli user +me --format json + +# Table（人类可读） +gitlink-cli branch +list --format table + +# YAML +gitlink-cli user +me --format yaml +``` + +--- + +## 全局参数 + +所有命令都支持这些参数： + +| 参数 | 说明 | +|------|------| +| `--owner` | 仓库所有者（可自动解析） | +| `--repo` | 仓库名称（可自动解析） | +| `--format` | 输出格式：json/table/yaml | +| `--debug` | 启用调试输出 | + +--- + +## 测试状态 + +✅ **生产就绪** (8.5/10) + +- 8/8 常用场景通过 +- 所有边界情况处理正确 +- 完整的文档和示例 + +详见: [`../doc/SKILLS_TEST_REPORT_2026-04-02.md`](../doc/SKILLS_TEST_REPORT_2026-04-02.md) + +--- + +## 获取帮助 + +- **命令帮助**: `gitlink-cli --help` +- **故障排查**: [`gitlink-shared/TROUBLESHOOTING.md`](gitlink-shared/TROUBLESHOOTING.md) +- **API 参考**: [`gitlink-shared/REFERENCE.md`](gitlink-shared/REFERENCE.md) +- **工作流示例**: 查看各 Skill 下的 `examples/` 目录 + +--- + +## 下一步 + +1. 阅读 [`gitlink-shared/SKILL.md`](gitlink-shared/SKILL.md) 了解基础 +2. 查看 [`gitlink-shared/examples/auth-workflow.md`](gitlink-shared/examples/auth-workflow.md) 完成认证 +3. 根据需求选择相应的 Skill 文档 +4. 参考 `examples/` 目录中的工作流示例 + +祝你使用愉快！🚀