4.8 KiB

Raw Blame History

name	version	description
gitlink-shared	1.0.0	gitlink-cli 共享基础：认证登录、全局参数、错误处理、安全规则。当用户首次使用 gitlink-cli、遇到认证错误、权限不足时触发。

gitlink-cli 共享规则

本技能指导你如何通过 gitlink-cli 操作 GitLink 平台资源。

认证

登录方式

# 方式 1：用户名密码登录（交互式）
gitlink-cli auth login

# 方式 2：粘贴已有 Token
gitlink-cli auth login --token

# 查看登录状态
gitlink-cli auth status

# 退出登录
gitlink-cli auth logout

Token 说明

GitLink Token 有效期 7 天，过期需重新登录
Token 存储在 OS Keychain（macOS Keychain / Linux Secret Service / Windows Credential Manager）
Fallback 存储：~/.config/gitlink-cli/credentials

认证错误处理

遇到 401 错误时：

# 引导用户重新登录
gitlink-cli auth login

遇到 403 错误时：

确认用户是否有对应资源的权限
确认 owner/repo 是否正确

全局参数

参数	说明
`--owner`	仓库所有者（可从 git remote 自动解析）
`--repo`	仓库名称（可从 git remote 自动解析）
`--format`	输出格式：json / table / yaml（AI 场景建议 json）
`--debug`	启用调试输出

上下文自动解析

在 git 仓库目录下，--owner 和 --repo 可自动从 git remote origin 解析：

HTTPS: https://www.gitlink.org.cn/owner/repo.git
SSH: git@www.gitlink.org.cn:owner/repo.git

输出格式

所有命令输出遵循统一 Envelope 格式：

{
  "ok": true,
  "data": { ... },
  "meta": { "page": 1, "limit": 20, "total_count": 100 }
}

错误格式：

{
  "ok": false,
  "error": { "code": 401, "message": "请登录后再操作", "suggestion": "请先运行 gitlink-cli auth login 登录" }
}

AI 场景建议：始终使用 --format json 以便解析输出。

三层命令体系

层级	格式	示例	适用场景
Shortcuts	`gitlink-cli <domain> +<verb>`	`gitlink-cli repo +info`	高频操作，推荐优先使用
Raw API	`gitlink-cli api <METHOD> <PATH>`	`gitlink-cli api GET /users/me`	Shortcuts 未覆盖的接口

GitLink API 注意事项

以下是实际测试中发现的 API 行为特殊性，使用时务必注意：

问题	说明	影响
Issue 创建需要 `done_ratio`	创建 Issue 时必须包含 `done_ratio: 0`，否则数据库报错	`issue +create` 已内置处理
Issue 更新需要 `subject`	任何 Issue 更新（包括只改状态）都必须带上 `subject` 字段	`issue +close` 已内置处理，Raw API 需手动处理
Release 查看需要 `version_id`	`release +view` 必须用 `version_id`（从 `release +list` 获取），不能用 tag_name	tag_name 会返回 HTML 页面
分支操作需要 `/v1/` 前缀	分支的 create/delete/list 端点使用 `/v1/:owner/:repo/branches`	已内置处理
Branch 删除 API 不可用	`DELETE /v1/:owner/:repo/branches/:name` 始终返回"分支不存在"	GitLink 平台 Bug，暂时无法通过 API 删除分支
Release 删除 API 不可用	`DELETE /:owner/:repo/releases/:id` 返回"版本不存在"	GitLink 平台 Bug
Create File API 异常	`POST /:owner/:repo/create_file` 在新分支上也返回"文件已存在"	GitLink 平台 Bug
PR 创建需要代码差异	分支内容必须与目标分支不同，否则拒绝创建	需要先在分支上有实际提交

分支约定

GitLink 和 GitHub 使用不同的主分支名称：

平台	主分支	说明
GitHub	`main`	GitHub 默认主分支
GitLink	`master`	GitLink 默认主分支

自动分支映射：

gitlink-cli 在与 GitLink 交互时会自动处理分支映射：

当 push 到 GitLink 时，自动将 main 映射到 master
当从 GitLink pull 时，自动将 master 映射到 main

本地 Git 操作：

如果直接使用 git push 命令，需要手动指定分支映射：

# 在本地 main 分支工作
git checkout main
git commit -m "feat: new feature"

# 直接 push 到 GitLink 的 master 分支
git push gitlink main:master
# 或配置 git remote 的 push refspec
git config remote.gitlink.push refs/heads/main:refs/heads/master
git push gitlink

使用 gitlink-cli：

# 在本地 main 分支工作
git checkout main
git commit -m "feat: new feature"

# Push 到 GitLink 时自动映射到 master
gitlink-cli repo +push
# 实际推送到 GitLink 的 master 分支

安全规则

禁止输出 Token 到终端明文
写入/删除操作前必须确认用户意图
危险操作（删除仓库、删除分支等）需二次确认

4.8 KiB Raw Blame History Unescape Escape