forked from Gitlink/gitlink-cli
365 lines
12 KiB
Markdown
365 lines
12 KiB
Markdown
# GitLink CLI Skills 指南
|
||
|
||
[](https://www.gitlink.org.cn/wbtiger/gitlink-cli)
|
||
|
||
欢迎使用 GitLink CLI Skills！本指南帮助你快速上手和充分利用 gitlink-cli 的所有功能。
|
||
|
||
## 📚 Skills 是什么？
|
||
|
||
Skills 是为 Claude Code 和其他 AI 代理设计的结构化知识库，包含：
|
||
|
||
- **SKILL.md** — 命令参考和使用指南
|
||
- **REFERENCE.md** — API 详细参考和参数说明
|
||
- **TROUBLESHOOTING.md** — 常见问题和解决方案
|
||
- **examples/** — 真实工作流示例
|
||
|
||
AI 代理通过 Skills 可以自动化操作 GitLink 平台，无需手动查阅文档。
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 安装和认证
|
||
|
||
```bash
|
||
# 首次使用：登录
|
||
gitlink-cli auth login
|
||
|
||
# 验证登录状态
|
||
gitlink-cli auth status
|
||
|
||
# 查看当前用户
|
||
gitlink-cli user +me
|
||
```
|
||
|
||
详见: [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
|
||
gitlink-cli pr --help
|
||
```
|
||
|
||
### 3. 使用 JSON 格式便于脚本处理
|
||
|
||
```bash
|
||
# 所有命令都支持 --format json
|
||
gitlink-cli user +me --format json
|
||
gitlink-cli repo +list --format json
|
||
gitlink-cli issue +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 参考
|
||
│ └── examples/
|
||
│ └── pr-workflow.md # PR 工作流
|
||
├── gitlink-member/ # 仓库成员管理
|
||
│ └── SKILL.md # 成员与邀请链接操作指南
|
||
├── gitlink-branch/ # 分支管理
|
||
│ ├── SKILL.md # 分支操作指南
|
||
│ └── examples/
|
||
│ └── branch-workflow.md # 分支工作流
|
||
├── gitlink-release/ # 版本发布
|
||
│ ├── SKILL.md # Release 操作指南
|
||
│ ├── REFERENCE.md # Release API 参考
|
||
│ └── examples/
|
||
│ └── release-workflow.md # Release 工作流
|
||
├── gitlink-search/ # 搜索功能
|
||
│ ├── SKILL.md # 搜索操作指南
|
||
│ └── examples/
|
||
│ └── search-workflow.md # 搜索工作流
|
||
├── gitlink-user/ # 用户管理
|
||
│ └── SKILL.md # 用户操作指南
|
||
├── gitlink-org/ # 组织管理
|
||
│ ├── SKILL.md # 组织操作指南
|
||
│ └── examples/
|
||
│ └── org-workflow.md # 组织工作流
|
||
├── gitlink-ci/ # CI/CD
|
||
│ ├── SKILL.md # CI 操作指南
|
||
│ └── examples/
|
||
│ └── ci-workflow.md # CI 工作流
|
||
├── gitlink-pipeline/ # 流水线工作流
|
||
│ └── SKILL.md # Pipeline 操作指南
|
||
├── gitlink-pm/ # 项目管理
|
||
│ └── SKILL.md # PM 操作指南
|
||
├── gitlink-health/ # 项目健康度分析
|
||
│ ├── SKILL.md # 健康度分析指南
|
||
│ ├── data/
|
||
│ │ ├── .gitignore # 忽略 *.db 文件
|
||
│ │ └── .gitkeep # 占位文件
|
||
│ ├── references/
|
||
│ │ └── queries.md # SQL 查询参考
|
||
│ └── asset/
|
||
│ └── health_report_template.md # 报告模板
|
||
└── gitlink-workflow/ # AI 自动化工作流
|
||
└── SKILL.md # 工作流模板（Issue 分类、PR Review、Release Notes）
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 所有 Skills 概览
|
||
|
||
### 核心 Skills
|
||
|
||
| Skill | 说明 | 常用命令 |
|
||
|-------|------|----------|
|
||
| **gitlink-shared** | 认证、全局参数、API 参考、安全规则、分支约定 | `auth login`, `auth status` |
|
||
| **gitlink-repo** | 仓库管理与洞察 | `repo +list`, `repo +info`, `repo +languages`, `repo +contributors`, `repo +code-stats`, `repo +follow`, `repo +like` |
|
||
| **gitlink-issue** | Issue 管理 | `issue +create`, `issue +list`, `issue +view`, `issue +close`, `issue +batch-close` |
|
||
| **gitlink-pr** | Pull Request | `pr +list`, `pr +create`, `pr +view`, `pr +merge`, `pr +versions`, `pr +version-diff`, `pr +reviews`, `pr +review` |
|
||
| **gitlink-member** | 仓库成员管理 | `member +list`, `member +add`, `member +batch-add`, `member +role`, `member +invite-link` |
|
||
| **gitlink-branch** | 分支管理 | `branch +list`, `branch +create`, `branch +delete`, `branch +protect` |
|
||
| **gitlink-release** | 版本发布 | `release +list`, `release +create`, `release +edit`, `release +update`, `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-pipeline** | 流水线工作流 | `pipeline +runs`, `pipeline +run`, `pipeline +logs` |
|
||
| **gitlink-pm** | 项目管理 | 通过 Raw API 访问 |
|
||
| **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、Release Notes |
|
||
| **gitlink-health** | 开源项目健康度 | 详情见SKILL.md |
|
||
| **gitlink-research-profile** | 科研主体画像（人/团队） | `profile +ability`, `profile +major`, `profile +role` |
|
||
|
||
---
|
||
|
||
## 🎯 使用场景
|
||
|
||
### 场景 1：查看仓库信息
|
||
|
||
```bash
|
||
# 在仓库目录下自动解析 owner/repo
|
||
cd ~/my-project
|
||
gitlink-cli repo +info
|
||
|
||
# 或显式指定
|
||
gitlink-cli repo +info --owner wbtiger --repo gitlink-cli
|
||
```
|
||
|
||
详见: [gitlink-repo/examples/repo-workflow.md](gitlink-repo/examples/repo-workflow.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
|
||
|
||
# 预览批量关闭 Issue
|
||
gitlink-cli issue +batch-close --numbers 123,124 --dry-run
|
||
```
|
||
|
||
详见: [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 <version_id>
|
||
```
|
||
|
||
详见: [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/examples/search-workflow.md](gitlink-search/examples/search-workflow.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-pipeline/SKILL.md](gitlink-pipeline/SKILL.md) - Pipeline 命令
|
||
- [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)
|
||
|
||
---
|
||
|
||
## 🤖 AI Agent 使用
|
||
|
||
Claude Code 和其他 AI 代理可以直接使用这些 Skills 自动化操作 GitLink 平台：
|
||
|
||
```
|
||
用户: "帮我在 GitLink 上创建一个 Issue"
|
||
↓
|
||
AI 代理读取 gitlink-issue/SKILL.md
|
||
↓
|
||
AI 代理执行: gitlink-cli issue +create -t "..." -b "..."
|
||
↓
|
||
完成！
|
||
```
|
||
|
||
AI 代理可以：
|
||
- ✅ 自动创建和管理 Issue
|
||
- ✅ 自动创建和合并 PR
|
||
- ✅ 自动发布 Release
|
||
- ✅ 自动分类 Issue
|
||
- ✅ 自动生成 Release Notes
|
||
- ✅ 自动执行代码审查
|
||
|
||
---
|
||
|
||
## 📊 测试状态
|
||
|
||
✅ **生产就绪** (8.5/10)
|
||
|
||
- 8/8 常用场景通过
|
||
- 所有边界情况处理正确
|
||
- 完整的文档和示例
|
||
|
||
详见: [../doc/SKILLS_TEST_REPORT_2026-04-02.md](../doc/SKILLS_TEST_REPORT_2026-04-02.md)
|
||
|
||
---
|
||
|
||
## 🔗 相关资源
|
||
|
||
- [主项目 README](../README.md) - gitlink-cli 项目说明
|
||
- [设计文档](../doc/design.md) - 架构设计和开发计划
|
||
- [测试报告](../doc/SKILLS_TEST_REPORT_2026-04-02.md) - 功能测试报告
|
||
- [代码同步方案](../doc/CODE_SYNC_STRATEGY_FINAL.md) - GitHub ↔ GitLink 同步设计
|
||
- [gitlink-bisync](https://www.gitlink.org.cn/wbtiger/gitlink-bisync) - 代码双向同步系统
|
||
|
||
---
|
||
|
||
## 📞 获取帮助
|
||
|
||
- **命令帮助**: `gitlink-cli <command> --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/` 目录中的工作流示例
|
||
5. 使用 AI 代理自动化你的工作流
|
||
|
||
祝你使用愉快！🚀
|