forked from Gitlink/gitlink-cli
Update documentation and user functionality
- Updated design documentation with latest features - Updated API reference documentation - Enhanced user shortcuts functionality - Added new gitlink-cli binary Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
狗gogo
parent
297a2ccbbe
commit
3edc27fac9
|
|
@ -40,29 +40,33 @@ gitlink-cli/
|
|||
│ ├── common/
|
||||
│ │ ├── types.go # Shortcut / Flag / RuntimeContext 定义
|
||||
│ │ └── runner.go # CallAPI / PaginateAll / ResolveOwnerRepo
|
||||
│ ├── repo/ # repo +create / +clone / +fork / +list / +info / +batch-create / +batch-update
|
||||
│ ├── issue/ # issue +list / +create / +view / +close / +comment / +batch-* (6 个批量命令)
|
||||
│ ├── repo/ # repo +create / +clone / +fork / +list / +info / +delete / +settings / +batch-create / +batch-update
|
||||
│ ├── issue/ # issue +list / +create / +view / +update / +close / +comment / +assign / +label / +batch-* (6 个批量命令)
|
||||
│ ├── wiki/ # wiki +list / +view / +create / +update / +delete
|
||||
│ ├── pr/ # pr +list / +create / +view / +merge / +review
|
||||
│ ├── release/ # release +list / +create / +download
|
||||
│ ├── branch/ # branch +list / +protect / +unprotect
|
||||
│ ├── org/ # org +list / +info / +members
|
||||
│ ├── pr/ # pr +list / +create / +view / +merge / +close / +review / +files / +diff
|
||||
│ ├── release/ # release +list / +create / +view / +delete / +download
|
||||
│ ├── branch/ # branch +list / +create / +delete / +protect / +unprotect
|
||||
│ ├── webhook/ # webhook +list / +create / +update / +delete / +test / +info
|
||||
│ ├── org/ # org +list / +info / +members / +create
|
||||
│ ├── user/ # user +me / +info
|
||||
│ ├── search/ # search +repos / +issues / +users
|
||||
│ ├── ci/ # ci +builds / +logs / +restart
|
||||
│ ├── ci/ # ci +builds / +logs / +restart / +stop
|
||||
│ └── register.go # 注册所有 shortcuts 到 cobra
|
||||
├── skills/
|
||||
│ ├── gitlink-shared/ # SKILL.md — 认证、全局参数、安全规则
|
||||
│ ├── gitlink-repo/ # SKILL.md + references/ — 仓库操作
|
||||
│ ├── gitlink-issue/ # SKILL.md + references/ — Issue 操作
|
||||
│ ├── gitlink-pr/ # SKILL.md + references/ — PR 操作
|
||||
│ ├── gitlink-release/ # SKILL.md + references/ — 发布管理
|
||||
│ ├── gitlink-branch/ # SKILL.md + references/ — 分支操作
|
||||
│ ├── gitlink-ci/ # SKILL.md + references/ — CI/CD 操作
|
||||
│ ├── gitlink-org/ # SKILL.md + references/ — 组织管理
|
||||
│ ├── gitlink-release/ # SKILL.md + references/ — 发布管理
|
||||
│ ├── gitlink-search/ # SKILL.md + references/ — 搜索
|
||||
│ ├── gitlink-user/ # SKILL.md + references/ — 用户管理
|
||||
│ ├── gitlink-pm/ # SKILL.md + references/ — 项目管理
|
||||
│ └── gitlink-workflow/ # SKILL.md — AI 自动化工作流（Issue 分类、PR Review 等）
|
||||
│ ├── gitlink-wiki/ # SKILL.md + references/ + examples/ — Wiki 操作
|
||||
│ ├── gitlink-webhook/ # SKILL.md + references/ + examples/ — Webhook 管理
|
||||
│ └── gitlink-workflow/ # SKILL.md + references/ + examples/ — AI 自动化工作流（Issue 分类、PR Review 等）
|
||||
├── go.mod
|
||||
├── go.sum
|
||||
├── Makefile
|
||||
|
|
@ -75,7 +79,7 @@ gitlink-cli/
|
|||
|
||||
### 2.1 Layer 1: Shortcuts（快捷命令，`+` 前缀）
|
||||
|
||||
面向高频场景的语义化封装，MVP 覆盖 ~43 个：
|
||||
面向高频场景的语义化封装，覆盖 13 个领域共 62 个命令：
|
||||
|
||||
| 领域 | Shortcuts | 数量 |
|
||||
|------|-----------|------|
|
||||
|
|
@ -88,6 +92,7 @@ gitlink-cli/
|
|||
| org | `+list` `+info` `+members` `+create` | 4 |
|
||||
| ci | `+builds` `+logs` `+restart` `+stop` | 4 |
|
||||
| user | `+me` `+info` | 2 |
|
||||
| webhook | `+list` `+create` `+update` `+delete` `+test` `+info` | 6 |
|
||||
|
||||
**Shortcut 声明式定义**：
|
||||
|
||||
|
|
@ -673,6 +678,13 @@ gitlink-cli
|
|||
├── user
|
||||
│ ├── +me # 当前用户
|
||||
│ └── +info # 用户详情
|
||||
├── webhook
|
||||
│ ├── +list # Webhook 列表
|
||||
│ ├── +create # 创建 Webhook
|
||||
│ ├── +update # 更新 Webhook
|
||||
│ ├── +delete # 删除 Webhook
|
||||
│ ├── +test # 测试 Webhook
|
||||
│ └── +info # Webhook 详情
|
||||
├── wiki
|
||||
│ ├── +list # Wiki 页面列表
|
||||
│ ├── +view # 查看 Wiki 页面
|
||||
|
|
@ -721,7 +733,8 @@ gitlink-cli
|
|||
| `shortcuts/common/runner.go` | RuntimeContext |
|
||||
| `shortcuts/repo/*.go` | 仓库 shortcuts（含 batch_create/batch_update） |
|
||||
| `shortcuts/issue/*.go` | Issue shortcuts（含 batch.go + batch_create.go 批量操作） |
|
||||
| `shortcuts/wiki/*.go` | Wiki shortcuts |
|
||||
| `shortcuts/wiki/*.go` | Wiki shortcuts（list, view, create, update, delete） |
|
||||
| `shortcuts/webhook/*.go` | Webhook shortcuts（list, create, update, delete, test, info） |
|
||||
| `shortcuts/pr/*.go` | PR shortcuts |
|
||||
| `shortcuts/register.go` | Shortcut 注册 |
|
||||
| `skills/gitlink-shared/SKILL.md` | 共享 Skill |
|
||||
|
|
|
|||
|
|
@ -23,6 +23,159 @@
|
|||
|
||||
- HTTP Authentication, scheme: bearer
|
||||
|
||||
---
|
||||
|
||||
# GitLink API 使用注意事项
|
||||
|
||||
> **重要提示**: 以下注意事项基于实际使用经验总结，使用GitLink API时请特别注意这些行为和限制。
|
||||
|
||||
## 已知问题和特殊行为
|
||||
|
||||
### API响应格式
|
||||
| 问题 | 说明 | 影响 | 解决方案 |
|
||||
|------|------|------|----------|
|
||||
| **双重错误码** | HTTP 200 + body.status 非200 | 错误判断复杂 | 需要检查HTTP状态码和body.status |
|
||||
| **错误格式不一致** | 有`{status, message}`也有`{code, msg}` | 错误解析困难 | 兼容处理两种格式 |
|
||||
| **静默失败** | 字段名错误可能返回200但不生效 | 调试困难 | 通过GET验证实际修改 |
|
||||
|
||||
### Issue API
|
||||
| API端点 | 问题 | 解决方案 | 状态 |
|
||||
|---------|------|----------|------|
|
||||
| Issue创建 | 必须包含`done_ratio: 0`，否则数据库报错 | 自动添加该字段 | ✅ shortcuts已处理 |
|
||||
| Issue更新 | 需保留`subject`/`description`，否则可能清空描述 | 先GET再提交，保留字段 | ⚠️ 需手动处理 |
|
||||
| Issue列表 | 分页参数可能不返回完整统计 | 客户端需分页处理 | ✅ 正常 |
|
||||
|
||||
### Release API
|
||||
| API端点 | 问题 | 解决方案 | 状态 |
|
||||
|---------|------|----------|------|
|
||||
| Release查看 | 需要`version_id`不能用`tag_name` | 使用`release +list`获取ID | ⚠️ 注意参数 |
|
||||
| Release删除 | 需要`version_id` | 使用`release +delete -i <version_id>` | ✅ shortcuts已处理 |
|
||||
|
||||
### 分支API
|
||||
| API端点 | 问题 | 解决方案 | 状态 |
|
||||
|---------|------|----------|------|
|
||||
| 分支操作 | 需要`/v1/`前缀 | 端点使用`/v1/:owner/:repo/branches` | ✅ shortcuts已处理 |
|
||||
| 分支删除 | `DELETE`分支API始终返回"分支不存在" | GitLink平台Bug，暂不支持 | ❌ API不可用 |
|
||||
|
||||
### 文件操作API
|
||||
| API端点 | 问题 | 解决方案 | 状态 |
|
||||
|---------|------|----------|------|
|
||||
| 创建文件 | `content`字段必须base64编码 | 不编码会返回"文件已存在"错误 | ⚠️ 需手动处理 |
|
||||
| 更新文件 | 需要`sha`参数，通过`sub_entries`获取 | 先GET获取SHA再PUT | ⚠️ 复杂操作 |
|
||||
|
||||
### Pull Request API
|
||||
| API端点 | 问题 | 解决方案 | 状态 |
|
||||
|---------|------|----------|------|
|
||||
| PR合并 | 需要`do`参数指定合并方式 | `pr +merge`已内置处理 | ✅ shortcuts已处理 |
|
||||
| PR列表 | `--state`参数只影响统计，列表可能包含所有状态 | 客户端需按`pull_request_status`过滤 | ⚠️ 需手动处理 |
|
||||
| PR创建 | 分支内容必须与目标分支不同 | 需要先有实际提交差异 | ⚠️ API限制 |
|
||||
|
||||
### Wiki API
|
||||
| API端点 | 问题 | 解决方案 | 状态 |
|
||||
|---------|------|----------|------|
|
||||
| Wiki域名 | 使用Gateway域名而非主域名 | Wiki使用独立client处理 | ✅ shortcuts已处理 |
|
||||
| Wiki内容 | base64编码传输 | CLI自动编解码 | ✅ shortcuts已处理 |
|
||||
| Wiki删除 | API只清空内容，不删除侧边栏条目 | GitLink平台限制 | ⚠️ 部分功能 |
|
||||
|
||||
### Webhook API
|
||||
| API端点 | 问题 | 解决方案 | 状态 |
|
||||
|---------|------|----------|------|
|
||||
| Webhook创建 | 需要完整的URL和事件配置 | 按文档格式提交 | ✅ shortcuts已处理 |
|
||||
| Webhook测试 | 测试推送可能延迟 | 等待异步处理 | ✅ shortcuts已处理 |
|
||||
|
||||
## 推荐使用方式
|
||||
|
||||
### 优先级顺序
|
||||
1. **Shortcuts** - 最简单，自动处理特殊情况
|
||||
```bash
|
||||
gitlink-cli issue +create -t "Bug" -b "详细描述"
|
||||
gitlink-cli wiki +create --title "Home" --content "# 欢迎"
|
||||
```
|
||||
|
||||
2. **Raw API** - Shortcuts未覆盖时使用
|
||||
```bash
|
||||
gitlink-cli api POST /:owner/:repo/issues --body '{"subject":"test","done_ratio":0}'
|
||||
```
|
||||
|
||||
3. **直接HTTP** - 仅用于调试或特殊需求
|
||||
```bash
|
||||
curl -X POST "https://www.gitlink.org.cn/api/:owner/:repo/issues.json?access_token=xxx"
|
||||
```
|
||||
|
||||
### 错误处理建议
|
||||
|
||||
**推荐错误处理流程**:
|
||||
1. 检查HTTP状态码
|
||||
2. 检查body中的status/code字段
|
||||
3. 验证实际修改是否生效（GET验证）
|
||||
4. 使用shortcuts避免直接处理复杂情况
|
||||
|
||||
**错误处理示例**:
|
||||
```python
|
||||
def check_gitlink_error(response):
|
||||
# 1. 检查HTTP状态码
|
||||
if response.status_code >= 400:
|
||||
return f"HTTP错误: {response.status_code}"
|
||||
|
||||
# 2. 检查body中的错误字段
|
||||
data = response.json()
|
||||
if 'status' in data and data['status'] != 200:
|
||||
return f"API错误: {data.get('message', '未知错误')}"
|
||||
if 'code' in data and data['code'] != 200:
|
||||
return f"Gateway错误: [{data['code']}] {data.get('msg', '未知错误')}"
|
||||
|
||||
# 3. 验证实际修改
|
||||
return None
|
||||
```
|
||||
|
||||
### 认证相关
|
||||
|
||||
**Token获取方式**:
|
||||
1. 用户名密码登录: `gitlink-cli auth login`
|
||||
2. 直接Token: `gitlink-cli auth login --token`
|
||||
3. 环境变量: `export GITLINK_TOKEN="your-token"`
|
||||
|
||||
**Token有效期**: 7天，过期需重新登录
|
||||
|
||||
**认证优先级**: 环境变量 > Keychain存储 > 交互式登录
|
||||
|
||||
### 请求限制
|
||||
|
||||
**速率限制**: GitLink API有基本的速率限制，建议：
|
||||
- 批量操作使用专门的batch命令
|
||||
- 避免短时间内大量请求
|
||||
- 使用`--dry-run`预览批量操作
|
||||
|
||||
**分页处理**: 大量数据建议：
|
||||
- 使用shortcuts的自动分页功能
|
||||
- 或者使用Raw API手动处理分页参数
|
||||
|
||||
## 开发建议
|
||||
|
||||
### 使用gitlink-cli的优势
|
||||
1. **自动处理特殊情况** - 如base64编码、双重错误码等
|
||||
2. **统一的错误处理** - 标准化的错误信息和建议
|
||||
3. **AI Agent友好** - 完整的Skills文档支持
|
||||
4. **跨平台支持** - macOS、Linux、Windows
|
||||
|
||||
### 调试技巧
|
||||
1. **使用`--debug`参数** 查看详细的请求响应
|
||||
```bash
|
||||
gitlink-cli --debug issue +list
|
||||
```
|
||||
|
||||
2. **使用`--format json`** 获取结构化输出
|
||||
```bash
|
||||
gitlink-cli --format json issue +list
|
||||
```
|
||||
|
||||
3. **使用`--dry-run`** 预览危险操作
|
||||
```bash
|
||||
gitlink-cli issue +batch-close --numbers 1,2,3 --dry-run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 附件
|
||||
|
||||
## POST 上传文件
|
||||
|
|
|
|||
Binary file not shown.
|
|
@ -30,7 +30,8 @@ func Shortcuts() []*common.Shortcut {
|
|||
if err != nil {
|
||||
return err
|
||||
}
|
||||
env, err := ctx.CallAPI("GET", fmt.Sprintf("/users/%s", login), nil)
|
||||
// Use relative path to avoid URL construction issues
|
||||
env, err := ctx.CallAPI("GET", fmt.Sprintf("users/%s", login), nil)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue