diff --git a/doc/design.md b/doc/design.md index 07768035..d6f79822 100644 --- a/doc/design.md +++ b/doc/design.md @@ -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 | diff --git a/doc/gitlink_api_reference.md b/doc/gitlink_api_reference.md index 968ace49..2a1d40bc 100644 --- a/doc/gitlink_api_reference.md +++ b/doc/gitlink_api_reference.md @@ -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 ` | ✅ 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 上传文件 diff --git a/gitlink-cli b/gitlink-cli new file mode 100644 index 00000000..1cceae36 Binary files /dev/null and b/gitlink-cli differ diff --git a/shortcuts/user/user.go b/shortcuts/user/user.go index cfcaa2a7..506986c5 100644 --- a/shortcuts/user/user.go +++ b/shortcuts/user/user.go @@ -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 }