otto
/
gitlink-cli
forked from Gitlink/gitlink-cli
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

merge into: otto:master
Branches Tags
otto:master
otto:pr-real-test-1775055754
otto:pr-test-1775052802
otto:delete-test-simple
otto:pr-test-1775050014
otto:scenario1-test-1775029495
otto:test-del-branch
otto:testbranch
Gitlink:master
Gitlink:chore/add-contributors-luwanzhou-whale
Gitlink:fix/pr-review-journal-sync
Gitlink:test/slash-1778992192
Gitlink:main
Gitlink:test/branch-skill-1778991125
Gitlink:test/unprotect-1778991372
Gitlink:v0.1.14
Gitlink:v0.0.1-test-del
Gitlink:v0.1.0-skill-test
Gitlink:v0.1.10
Gitlink:v0.1.11
Gitlink:v0.1.12
Gitlink:v0.1.13
Gitlink:v0.1.17
Gitlink:v0.1.18
Gitlink:v0.1.8
Gitlink:v0.1.9
Gitlink:v0.2.0
...
pull from: otto:pr-real-test-1775055754
Branches Tags
otto:master
otto:pr-real-test-1775055754
otto:pr-test-1775052802
otto:delete-test-simple
otto:pr-test-1775050014
otto:scenario1-test-1775029495
otto:test-del-branch
otto:testbranch
Gitlink:master
Gitlink:chore/add-contributors-luwanzhou-whale
Gitlink:fix/pr-review-journal-sync
Gitlink:test/slash-1778992192
Gitlink:main
Gitlink:test/branch-skill-1778991125
Gitlink:test/unprotect-1778991372
Gitlink:v0.1.14
Gitlink:v0.0.1-test-del
Gitlink:v0.1.0-skill-test
Gitlink:v0.1.10
Gitlink:v0.1.11
Gitlink:v0.1.12
Gitlink:v0.1.13
Gitlink:v0.1.17
Gitlink:v0.1.18
Gitlink:v0.1.8
Gitlink:v0.1.9
Gitlink:v0.2.0

No commits in common. "master" and "pr-real-test-1775055754" have entirely different histories.
master ... pr-real-te

26 changed files with 120 additions and 3425 deletions
Show Stats Expand all files Collapse all files

7
.gitignore vendored
View File

@ -13,10 +13,3 @@ Thumbs.db
# Go
vendor/
# npm packaging
npm/bin/gitlink-cli
npm/*.tgz
npm/README.md
npm/skills/
dist/

399
README.md
View File

@ -1,356 +1,167 @@
# gitlink-cli
[![GitLink](https://img.shields.io/badge/GitLink-Gitlink%2Fgitlink--cli-green)](https://www.gitlink.org.cn/Gitlink/gitlink-cli)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
[![Go Version](https://img.shields.io/badge/Go-1.21%2B-blue.svg)](https://golang.org)
[![npm version](https://img.shields.io/npm/v/@gitlink-ai/cli.svg)](https://www.npmjs.com/package/@gitlink-ai/cli)
GitLink CLI — 面向 [GitLink（确实开源）](https://www.gitlink.org.cn) 平台的命令行工具。
The official [GitLink（确实开源）](https://www.gitlink.org.cn) CLI tool — built for humans and AI Agents. Covers repository management, issue tracking, pull requests, CI/CD, and AI-powered workflows, with 40+ commands and 11 AI Agent [Skills](./skills/).
gitlink-cli 采用业界主流的分层 CLI 架构设计，提供 Shortcuts（快捷命令）、Raw API（原始调用）两层命令体系，覆盖仓库管理、Issue 跟踪、Pull Request、CI/CD、组织管理等全流程操作，并内置 AI Agent Skills 支持 Claude Code 自动化。
[Install](#installation--quick-start) · [AI Agent Skills](#ai-agent-skills) · [Auth](#首次使用) · [Commands](#使用示例) · [Contributing](#相关项目)
## 特性
## Why gitlink-cli?
- **三层命令体系**：Shortcuts（`+` 前缀高频命令）→ Raw API（覆盖全部 490+ 端点）
- **Git Remote 自动解析**：在 git 仓库目录下自动推断 `owner/repo`
- **统一输出格式**：JSON / Table / YAML，标准 Envelope 结构
- **OS Keychain 存储**：Token 安全存储于系统密钥链
- **AI Agent Skills**：11 个 SKILL.md 文件，5 个自动化工作流模板
- **Agent-Native Design** — 11 structured [Skills](./skills/) out of the box, compatible with Claude Code — Agents can operate GitLink with zero extra setup
- **Wide Coverage** — Repository, Issue, PR, Branch, Release, CI, Org, Search, User — all core domains covered
- **AI-Friendly & Optimized** — Every command is tested with real Agents, featuring concise parameters, smart defaults, and structured output
- **Open Source, Zero Barriers** — Apache 2.0 license, ready to use, just `npm install`
- **Up and Running in 3 Minutes** — Interactive login, from install to first API call in just 3 steps
- **Secure & Controllable** — OS-native keychain credential storage, auto git remote context resolution
- **Three-Layer Architecture** — Shortcuts (human & AI friendly) → Raw API (full coverage) → Config (configuration management)
## 安装
## Features
| Category | Capabilities |
|----------|-------------|
| 📦 Repo | List, create, fork, delete repositories, view repo info |
| 🐛 Issue | Create, update, close, comment on issues |
| 🔀 PR | Create, merge, review pull requests, view changed files |
| 🌿 Branch | Create, delete, protect branches |
| 🏷️ Release | Create, view, delete releases |
| 🏢 Org | Manage organizations, members, teams |
| 🔧 CI | View builds, logs, CI/CD operations |
| 🔍 Search | Search repositories, users |
| 👤 User | View user profiles and info |
| 🤖 Workflow | AI-powered issue triage, PR review, release notes |
## Installation & Quick Start
### Requirements
Before you start, make sure you have:
- Node.js 14+ (`npm`/`npx`) — for npm installation
- Go 1.21+ — only required for building from source
### Quick Start (Human Users)
> **Note for AI assistants:** If you are an AI Agent helping the user with installation, jump directly to [Quick Start (AI Agent)](#quick-start-ai-agent), which contains all the steps you need to complete.
#### Install
Choose **one** of the following methods:
**Option 1 — From npm (recommended):**
### 从源码构建
```bash
# Install CLI
npm install -g @gitlink-ai/cli
# Install CLI SKILL (required)
npx skills add "$(npm root -g)/@gitlink-ai/cli/skills" -y -g
```
**Option 2 — From source:**
Requires Go 1.21+.
```bash
git clone https://www.gitlink.org.cn/Gitlink/gitlink-cli.git
git clone https://github.com/FlagosEvangelist/gitlink-cli.git
cd gitlink-cli
make build
# 二进制文件生成在当前目录: ./gitlink-cli
```
### 安装到 PATH
```bash
make install
# Install CLI SKILL (required)
npx skills add ./skills -y -g
# 安装到 $GOPATH/bin
```
#### Configure & Use
**依赖**：Go 1.21+
## 快速开始
```bash
# 1. Configure (one-time, interactive guided setup)
# 1. 初始化配置
gitlink-cli config init
# 2. Log in
# 2. 登录
gitlink-cli auth login
# 3. Start using
gitlink-cli repo +list
```
### Quick Start (AI Agent)
> The following steps are for AI Agents. Some steps require the user to complete actions in a browser.
**Step 1 — Install**
```bash
# Install CLI
npm install -g @gitlink-ai/cli
# Install CLI SKILL (required)
npx skills add "$(npm root -g)/@gitlink-ai/cli/skills" -y -g
```
**Step 2 — Configure**
```bash
gitlink-cli config init
```
**Step 3 — Login**
```bash
gitlink-cli auth login
```
**Step 4 — Verify**
```bash
# 3. 查看当前用户
gitlink-cli user +me
```
## 使用示例
### 仓库操作
```bash
# 列出仓库
gitlink-cli repo +list
# 查看仓库信息
# 4. 查看仓库信息
gitlink-cli repo +info --owner Gitlink --repo forgeplus
# 创建仓库
gitlink-cli repo +create -n my-project -d "项目描述"
# Fork 仓库
gitlink-cli repo +fork --owner Gitlink --repo forgeplus
# 5. 在 git 仓库目录下自动解析 owner/repo
cd ~/my-gitlink-project
gitlink-cli issue +list
```
### Issue 管理
## 命令概览
```
gitlink-cli
├── auth login / logout / status
├── config init / set / get / list
├── repo +list / +info / +create / +fork / +delete
├── issue +list / +create / +view / +update / +close / +comment
├── pr +list / +create / +view / +merge / +close / +files / +diff
├── release +list / +create / +view / +delete
├── branch +list / +create / +delete / +protect / +unprotect
├── org +list / +info / +members / +create
├── ci +builds / +logs / +restart / +stop
├── user +me / +info
├── search +repos / +users
├── api GET / POST / PUT / DELETE（原始 API 调用）
└── version
```
## Shortcuts 示例
```bash
# 列出 Issue
gitlink-cli issue +list --owner Gitlink --repo forgeplus
# 仓库
gitlink-cli repo +info --owner Gitlink --repo forgeplus
gitlink-cli repo +create --name my-project --description "新项目"
# 创建 Issue
gitlink-cli issue +create -t "Bug: 登录失败" -b "复现步骤..."
# Issue
gitlink-cli issue +create --title "Bug: 登录失败" --body "复现步骤..."
gitlink-cli issue +close --id 123
# 查看 Issue
gitlink-cli issue +view -i 123
# Pull Request
gitlink-cli pr +create --title "feat: 搜索功能" --head feature/search --base master
gitlink-cli pr +merge --id 42
# 关闭 Issue
gitlink-cli issue +close -i 123
# Release
gitlink-cli release +create --tag v1.0.0 --name "v1.0.0" --body "首个正式版本"
# 添加评论
gitlink-cli issue +comment -i 123 -b "已修复"
# 搜索
gitlink-cli search +repos --keyword "machine learning"
```
### Pull Request
```bash
# 列出 PR
gitlink-cli pr +list --owner Gitlink --repo forgeplus
# 创建 PR
gitlink-cli pr +create -t "feat: 搜索功能" --head feature/search --base master
# 查看 PR
gitlink-cli pr +view -i 42
# 合并 PR
gitlink-cli pr +merge -i 42
# 查看 PR 变更文件
gitlink-cli pr +files -i 42
```
### 发布管理
```bash
# 列出 Release
gitlink-cli release +list --owner Gitlink --repo forgeplus
# 创建 Release
gitlink-cli release +create -t v1.0.0 -n "v1.0.0 正式版" -b "更新内容..."
# 查看 Release
gitlink-cli release +view -i <version_id>
```
### 搜索
```bash
# 搜索仓库
gitlink-cli search +repos -k "machine learning"
# 搜索用户
gitlink-cli search +users -k "zhangsan"
```
### Raw API
## Raw API
Shortcuts 未覆盖的接口可通过 Raw API 直接调用：
```bash
# GET 请求
gitlink-cli api GET /users/me
# POST 请求
gitlink-cli api POST /Gitlink/forgeplus/issues --body '{"subject":"test","description":"..."}'
# 带查询参数
gitlink-cli api GET /Gitlink/forgeplus/commits --query 'page=1&limit=5'
gitlink-cli api POST /Gitlink/forgeplus/issues --body '{"subject":"test","description":"..."}'
```
## 全局参数
| 参数 | 说明 | 示例 |
|------|------|------|
| `--owner` | 仓库所有者 | `--owner Gitlink` |
| `--repo` | 仓库名称 | `--repo forgeplus` |
| `--format` | 输出格式（json/table/yaml） | `--format json` |
| `--debug` | 启用调试输出 | `--debug` |
**自动上下文解析**：在 git 仓库目录下，`--owner` 和 `--repo` 会自动从 `git remote origin` 解析。
## 分支约定
gitlink-cli 支持 GitHub 和 GitLink 的代码双向同步：
| 平台 | 主分支 |
|------|--------|
| GitHub | `main` |
| GitLink | `master` |
**本地 push 到 GitLink**：
```bash
# 方式 1：使用 git 命令
git push gitlink main:master
# 方式 2：配置 git remote
git config remote.gitlink.push refs/heads/main:refs/heads/master
git push gitlink
```
| 参数 | 说明 |
|------|------|
| `--owner` | 仓库所有者（可从 git remote 自动解析） |
| `--repo` | 仓库名称（可从 git remote 自动解析） |
| `--format` | 输出格式：`json` / `table` / `yaml` |
| `--debug` | 启用调试输出 |
## AI Agent Skills
`skills/` 目录包含 11 个 Claude Code Agent Skill 文件，支持 AI 自动化操作 GitLink 平台。
详见 [skills/README.md](skills/README.md)
`skills/` 目录包含 11 个 Claude Code Agent Skill 文件，支持 AI 自动化操作 GitLink 平台：
| Skill | 说明 |
|-------|------|
| `gitlink-shared` | 认证、全局参数、安全规则、API 注意事项 |
| `gitlink-repo` | 仓库操作（创建、查看、删除、Fork 等） |
| `gitlink-issue` | Issue 操作（创建、更新、关闭、评论等） |
| `gitlink-pr` | Pull Request 操作（创建、合并、Review 等） |
| `gitlink-branch` | 分支管理（创建、删除、保护等） |
| `gitlink-release` | 发布管理（创建、查看、删除等） |
| `gitlink-org` | 组织管理（成员、团队等） |
| `gitlink-ci` | CI/CD 操作（构建、日志等） |
| `gitlink-search` | 搜索功能（仓库、用户等） |
| `gitlink-user` | 用户管理（个人信息等） |
| `gitlink-workflow` | AI 自动化工作流（Issue 分类、PR Review、Release Notes 等） |
| `gitlink-shared` | 认证、全局参数、安全规则 |
| `gitlink-repo` | 仓库操作 |
| `gitlink-issue` | Issue 操作 |
| `gitlink-pr` | Pull Request 操作 |
| `gitlink-ci` | CI/CD 操作 |
| `gitlink-org` | 组织管理 |
| `gitlink-release` | 发布管理 |
| `gitlink-search` | 搜索 |
| `gitlink-user` | 用户管理 |
| `gitlink-pm` | 项目管理 |
| `gitlink-workflow` | AI 自动化工作流（Issue Triage、PR Review、Release Notes 等） |
## 项目结构
```
gitlink-cli/
├── cmd/ # Cobra 命令定义
│ ├── root.go # 根命令 + 全局 flags
│ ├── auth/ # 认证命令
│ ├── api/ # Raw API 命令
│ ├── config/ # 配置命令
│ └── cmdutil/ # 全局工具
├── internal/ # 内部包
│ ├── auth/ # 登录、Token 存储、Transport
│ ├── client/ # HTTP 客户端 + 分页
│ ├── config/ # 配置文件管理
│ ├── context/ # git remote 解析
│ └── output/ # Envelope + Formatter
├── shortcuts/ # Shortcut 实现
│ ├── common/ # 框架（types, runner）
│ ├── repo/ # 仓库 shortcuts
│ ├── issue/ # Issue shortcuts
│ ├── pr/ # PR shortcuts
│ ├── branch/ # 分支 shortcuts
│ ├── release/ # Release shortcuts
│ ├── org/ # 组织 shortcuts
│ ├── ci/ # CI shortcuts
│ ├── search/ # 搜索 shortcuts
│ ├── user/ # 用户 shortcuts
│ └── register.go # 注册入口
├── skills/ # AI Agent Skills
│ ├── README.md # Skills 使用指南
│ ├── gitlink-shared/ # 共享规则
│ ├── gitlink-repo/ # 仓库 Skill
│ ├── gitlink-issue/ # Issue Skill
│ ├── gitlink-pr/ # PR Skill
│ └── ...
├── doc/ # 设计文档
│ ├── SKILLS_TEST_REPORT_2026-04-02.md
│ ├── CODE_SYNC_STRATEGY_FINAL.md
│ └── ...
├── cmd/ # Cobra 命令定义
│ ├── root.go # 根命令 + 全局 flags
│ ├── auth/ # auth login/logout/status
│ ├── api/ # Raw API 层
│ ├── config/ # config init/set/get/list
│ └── cmdutil/ # 全局变量
├── internal/ # 内部包
│ ├── auth/ # 登录、Token 存储、Transport
│ ├── client/ # HTTP 客户端 + 分页
│ ├── config/ # 配置文件管理
│ ├── context/ # git remote 解析
│ └── output/ # Envelope + Formatter
├── shortcuts/ # Shortcut 实现
│ ├── common/ # 框架（types, runner）
│ ├── repo/issue/pr/... # 各领域 shortcuts
│ └── register.go # 注册入口
├── skills/ # AI Agent Skills
│ └── gitlink-*/SKILL.md
├── doc/ # 设计文档
├── main.go
├── Makefile
├── go.mod
└── README.md
└── go.mod
```
## 文档
## 设计文档
- [Skills 使用指南](skills/README.md) - AI Agent Skills 详细说明
- [设计文档](doc/design.md) - 架构设计和开发计划
- [测试报告](doc/SKILLS_TEST_REPORT_2026-04-02.md) - 功能测试报告
- [代码同步方案](doc/CODE_SYNC_STRATEGY_FINAL.md) - GitHub ↔ GitLink 同步设计
详见 [doc/design.md](doc/design.md) — 包含完整的架构设计、三层命令体系、认证方案、API 客户端、AI Skills 设计和开发计划。
## 常见问题
### 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-gitlink-project
gitlink-cli issue +list # 自动使用当前仓库
```
### Q: Token 过期了怎么办？
A: 重新登录：
```bash
gitlink-cli auth login
```
### Q: 如何查看完整的 API 参考？
A: 查看 [skills/gitlink-shared/REFERENCE.md](skills/gitlink-shared/REFERENCE.md)
## 相关项目
- [gitlink-bisync](https://www.gitlink.org.cn/wbtiger/gitlink-bisync) - GitHub ↔ GitLink 代码双向同步系统
## 许可证
## License
[Apache License 2.0](LICENSE)

482
doc/CODE_SYNC_STRATEGY.md
View File

@ -1,482 +0,0 @@
# GitLink-GitHub 代码双向同步方案
**版本**: v1.0
**日期**: 2026-04-02
**状态**: 已确认
---
## 1 概述
实现 GitHub（主仓）和 GitLink（镜像仓）的代码双向同步，确保两个平台的代码始终一致。通过 Git hooks 在关键操作点进行同步检查，自动解决冲突或提示用户手动处理。
### 1.1 核心原则
- **GitHub 为主仓**：GitHub 是代码的唯一真实来源
- **GitLink 为镜像仓**：GitLink 作为备份和协作平台
- **Hook 控制在 GitLink**：所有同步逻辑通过 GitLink 本地 hooks 实现
- **GitHub 完全被动**：GitHub 不需要任何 hook 操作
- **冲突自动解决**：优先自动 rebase 解决，无法解决时提示用户
---
## 2 同步触发点
### 2.1 四个关键触发点
| 触发点 | Hook | 检查内容 | 动作 |
|--------|------|---------|------|
| **直接 commit** | `pre-commit` | GitLink HEAD vs GitHub HEAD | 不同步则阻止 commit |
| **直接 push** | `pre-push` | GitLink HEAD vs GitHub HEAD | 不同步则阻止 push |
| **创建 PR** | Webhook | 拉取最新 GitHub 代码 | 自动 rebase 到最新 GitHub 代码 |
| **Merge PR** | Webhook | 拉取最新 GitHub 代码 + 自动 rebase | 解决冲突后 merge，并推送到 GitHub |
### 2.2 触发点详解
#### 2.2.1 Pre-commit Hook（直接 commit）
**场景**：用户在 GitLink 本地修改代码后执行 `git commit`
**流程**：
```
1. 用户执行: git commit -m "..."
2. pre-commit hook 触发
3. 检查: GitLink HEAD == GitHub HEAD?
- 是 → 允许 commit
- 否 → 阻止 commit，提示用户执行 rebase
```
**实现**：
```bash
#!/bin/bash
# .git/hooks/pre-commit
GITHUB_HEAD=$(git ls-remote https://github.com/owner/repo HEAD | awk '{print $1}')
GITLINK_HEAD=$(git rev-parse HEAD)
if [ "$GITHUB_HEAD" != "$GITLINK_HEAD" ]; then
echo "❌ Error: GitLink HEAD 不同步 GitHub"
echo "请执行: git fetch github && git rebase github/main"
exit 1
fi
exit 0
```
#### 2.2.2 Pre-push Hook（直接 push）
**场景**：用户在 GitLink 本地修改代码后执行 `git push`
**流程**：
```
1. 用户执行: git push origin main
2. pre-push hook 触发
3. 检查: GitLink HEAD == GitHub HEAD?
- 是 → 允许 push
- 否 → 阻止 push，提示用户执行 rebase
```
**实现**：
```bash
#!/bin/bash
# .git/hooks/pre-push
GITHUB_HEAD=$(git ls-remote https://github.com/owner/repo HEAD | awk '{print $1}')
GITLINK_HEAD=$(git rev-parse HEAD)
if [ "$GITHUB_HEAD" != "$GITLINK_HEAD" ]; then
echo "❌ Error: GitLink HEAD 不同步 GitHub"
echo "请执行: git fetch github && git rebase github/main"
exit 1
fi
exit 0
```
#### 2.2.3 创建 PR 时同步（Webhook）
**场景**：用户在 GitLink 创建 PR
**流程**：
```
1. 用户在 GitLink 创建 PR: feature → main
2. GitLink webhook 触发
3. 拉取最新 GitHub 代码到 GitLink
4. 自动 rebase PR 分支到最新 GitHub main
5. 如果冲突可自动解决 → 直接解决
6. 如果冲突无法自动解决 → 提示用户手动解决
```
**实现逻辑**：
```
POST /webhook/pr-created
├─ 获取 PR 信息 (source_branch, target_branch)
├─ git fetch github main
├─ git checkout source_branch
├─ git rebase github/main
│ ├─ 冲突可解决 → 自动解决 + git rebase --continue
│ └─ 冲突无法解决 → 提示用户，PR 标记为 "需要手动 rebase"
└─ 更新 PR 状态
```
#### 2.2.4 Merge PR 时同步（Webhook）
**场景**：用户在 GitLink 合并 PR
**流程**：
```
1. 用户在 GitLink 点击 "Merge PR"
2. GitLink webhook 触发
3. 拉取最新 GitHub 代码到 GitLink
4. 自动 rebase PR 分支到最新 GitHub main
5. 如果冲突可自动解决 → 直接解决 + merge
6. 如果冲突无法自动解决 → 停止 merge，提示用户
7. Merge 成功后，自动 push 到 GitHub
```
**实现逻辑**：
```
POST /webhook/pr-merge
├─ 获取 PR 信息 (source_branch, target_branch)
├─ git fetch github main
├─ git checkout source_branch
├─ git rebase github/main
│ ├─ 冲突可解决 → 自动解决 + git rebase --continue
│ └─ 冲突无法解决 → 停止 merge，返回错误
├─ git checkout target_branch
├─ git merge source_branch
├─ git push github target_branch
└─ 更新 PR 状态为 "已合并"
```
---
## 3 冲突处理策略
### 3.1 冲突类型与解决方案
| 冲突类型 | 原因 | 解决方案 |
|---------|------|--------|
| **文件内容冲突** | 同一文件同一行被修改 | 自动 rebase（Git 尝试自动合并） |
| **文件删除冲突** | 一边删除，一边修改 | 提示用户手动选择 |
| **文件重命名冲突** | 同一文件被重命名为不同名称 | 提示用户手动选择 |
| **二进制文件冲突** | 二进制文件被修改 | 提示用户手动选择 |
### 3.2 自动解决策略
**可自动解决的冲突**：
- 不同文件的修改
- 同一文件不同行的修改
- 简单的文本冲突（Git 能自动合并）
**实现**：
```bash
git rebase github/main --no-edit
# 如果有冲突，尝试自动解决
if [ $? -ne 0 ]; then
# 尝试使用 ours 或 theirs 策略
git rebase --continue --strategy=recursive -X ours
fi
```
### 3.3 无法自动解决时的处理
**流程**：
```
1. Rebase 失败，存在冲突
2. 返回错误信息给用户
3. PR 标记为 "冲突" 状态
4. 用户本地手动解决冲突
5. 用户执行: git rebase --continue
6. 用户 push 到 GitLink
7. Pre-push hook 检查 → 通过
8. 用户重新点击 "Merge PR"
```
---
## 4 实现架构
### 4.1 组件清单
| 组件 | 位置 | 职责 |
|------|------|------|
| **Pre-commit Hook** | `.git/hooks/pre-commit` | 检查 commit 前的同步状态 |
| **Pre-push Hook** | `.git/hooks/pre-push` | 检查 push 前的同步状态 |
| **PR Created Webhook** | GitLink 服务端 | 创建 PR 时自动 rebase |
| **PR Merged Webhook** | GitLink 服务端 | Merge PR 时自动 rebase + push GitHub |
| **Sync CLI Command** | `gitlink-cli sync` | 手动触发同步（可选） |
### 4.2 数据流
```
GitHub (主仓)
↓ (git fetch)
GitLink 本地仓库
├─ pre-commit hook (检查同步)
├─ pre-push hook (检查同步)
└─ webhook (创建/合并 PR 时自动 rebase)
↓ (git push)
GitLink 远程仓库
↓ (webhook)
GitHub (推送更新)
```
---
## 5 用户工作流
### 5.1 场景 1：直接 commit 到 GitLink
```bash
# 1. 用户在 GitLink 本地修改代码
cd gitlink-cli
echo "new code" >> file.txt
# 2. 执行 commit
git commit -m "feat: add new feature"
# 3. Pre-commit hook 检查
# ✅ 如果 HEAD 同步 → commit 成功
# ❌ 如果 HEAD 不同步 → commit 失败，提示 rebase
# 4. 如果失败，用户手动 rebase
git fetch github
git rebase github/main
# 5. 重新 commit
git commit -m "feat: add new feature"
```
### 5.2 场景 2：创建 PR
```bash
# 1. 用户创建 feature 分支
git checkout -b feature/new-feature
# 2. 修改代码并 commit
git commit -m "feat: implement feature"
# 3. Push 到 GitLink
git push origin feature/new-feature
# 4. 在 GitLink 创建 PR: feature/new-feature → main
# GitLink webhook 自动触发：
# - 拉取最新 GitHub 代码
# - 自动 rebase feature 分支到最新 GitHub main
# - 如果冲突可解决 → 自动解决
# - 如果冲突无法解决 → PR 标记为 "需要手动 rebase"
```
### 5.3 场景 3：Merge PR
```bash
# 1. 用户在 GitLink 点击 "Merge PR"
# GitLink webhook 自动触发：
# - 拉取最新 GitHub 代码
# - 自动 rebase PR 分支到最新 GitHub main
# - 如果冲突可解决 → 自动解决 + merge
# - 如果冲突无法解决 → merge 失败，提示用户
# 2. Merge 成功后，自动 push 到 GitHub
# GitHub 代码自动更新
```
### 5.4 场景 4：直接 push 到 GitLink
```bash
# 1. 用户本地修改代码并 commit
git commit -m "fix: bug fix"
# 2. 执行 push
git push origin main
# 3. Pre-push hook 检查
# ✅ 如果 HEAD 同步 → push 成功
# ❌ 如果 HEAD 不同步 → push 失败，提示 rebase
# 4. 如果失败，用户手动 rebase
git fetch github
git rebase github/main
git push origin main
```
---
## 6 配置与部署
### 6.1 Hook 安装
在 gitlink-cli 项目中创建 hooks：
```bash
# 创建 hooks 目录
mkdir -p .githooks
# 创建 pre-commit hook
cat > .githooks/pre-commit << 'EOF'
#!/bin/bash
GITHUB_HEAD=$(git ls-remote https://github.com/owner/repo HEAD | awk '{print $1}')
GITLINK_HEAD=$(git rev-parse HEAD)
if [ "$GITHUB_HEAD" != "$GITLINK_HEAD" ]; then
echo "❌ Error: GitLink HEAD 不同步 GitHub"
echo "请执行: git fetch github && git rebase github/main"
exit 1
fi
exit 0
EOF
# 创建 pre-push hook
cat > .githooks/pre-push << 'EOF'
#!/bin/bash
GITHUB_HEAD=$(git ls-remote https://github.com/owner/repo HEAD | awk '{print $1}')
GITLINK_HEAD=$(git rev-parse HEAD)
if [ "$GITHUB_HEAD" != "$GITLINK_HEAD" ]; then
echo "❌ Error: GitLink HEAD 不同步 GitHub"
echo "请执行: git fetch github && git rebase github/main"
exit 1
fi
exit 0
EOF
# 设置权限
chmod +x .githooks/pre-commit .githooks/pre-push
# 配置 Git 使用这些 hooks
git config core.hooksPath .githooks
```
### 6.2 Webhook 配置
在 GitLink 项目设置中配置 webhooks：
**PR Created Webhook**：
- URL: `https://your-server/webhook/pr-created`
- 事件: Pull Request Created
- 负载: PR 信息（source_branch, target_branch, pr_id）
**PR Merged Webhook**：
- URL: `https://your-server/webhook/pr-merged`
- 事件: Pull Request Merged
- 负载: PR 信息（source_branch, target_branch, pr_id）
---
## 7 风险与缓解
### 7.1 潜在风险
| 风险 | 影响 | 缓解措施 |
|------|------|--------|
| **Rebase 失败** | PR 无法合并 | 提示用户手动解决，PR 标记为冲突 |
| **GitHub 网络不可达** | Hook 超时 | 设置超时时间，失败时提示用户 |
| **Webhook 失败** | 同步不及时 | 重试机制 + 手动同步命令 |
| **并发 merge** | 数据不一致 | 使用分布式锁或队列 |
### 7.2 缓解方案
**Hook 超时处理**：
```bash
timeout 5 git ls-remote https://github.com/owner/repo HEAD
if [ $? -eq 124 ]; then
echo "⚠️ Warning: GitHub 网络超时，跳过同步检查"
exit 0 # 允许操作继续
fi
```
**Webhook 重试**：
```
失败 → 等待 5 秒 → 重试
失败 → 等待 10 秒 → 重试
失败 → 等待 30 秒 → 重试
失败 → 记录日志，通知管理员
```
---
## 8 手动同步命令（可选）
提供 CLI 命令供用户手动触发同步：
```bash
# 手动同步 GitLink 到最新 GitHub 代码
gitlink-cli sync --from github --to gitlink
# 手动同步 GitHub 到最新 GitLink 代码（不推荐）
gitlink-cli sync --from gitlink --to github
# 查看同步状态
gitlink-cli sync status
```
---
## 9 验证与测试
### 9.1 测试场景
| 场景 | 预期结果 | 验证方法 |
|------|---------|--------|
| GitHub 有新代码，GitLink 直接 commit | Commit 失败，提示 rebase | 执行 commit，检查错误信息 |
| GitHub 有新代码，GitLink 直接 push | Push 失败，提示 rebase | 执行 push，检查错误信息 |
| 创建 PR 时 GitHub 有新代码 | 自动 rebase，PR 创建成功 | 创建 PR，检查 PR 状态 |
| Merge PR 时 GitHub 有新代码 | 自动 rebase + merge，推送 GitHub | Merge PR，检查 GitHub 代码 |
| 冲突无法自动解决 | PR 标记为<E8AEB0><E4B8BA>突，提示用户 | 创建冲突 PR，检查状态 |
### 9.2 测试命令
```bash
# 1. 测试 pre-commit hook
git commit -m "test"
# 2. 测试 pre-push hook
git push origin main
# 3. 测试 PR 创建同步
# 在 GitLink 创建 PR，检查是否自动 rebase
# 4. 测试 PR 合并同步
# 在 GitLink 合并 PR，检查 GitHub 是否更新
```
---
## 10 后续优化
### 10.1 短期（1-2 周）
- [ ] 实现 pre-commit 和 pre-push hooks
- [ ] 实现 PR Created 和 PR Merged webhooks
- [ ] 编写测试用例
- [ ] 文档完善
### 10.2 中期（2-4 周）
- [ ] 实现手动同步 CLI 命令
- [ ] 添加同步状态监控
- [ ] 优化冲突自动解决策略
- [ ] 添加日志和告警
### 10.3 长期（1 个月+）
- [ ] Issue 和 PR 元数据同步
- [ ] 评论和 Review 同步
- [ ] 自动化测试和 CI/CD 集成
- [ ] 性能优化和扩展性改进
---
## 11 总结
本方案通过 **Git hooks + Webhooks** 的组合，实现了 GitHub 和 GitLink 的代码双向同步。核心特点：
✅ **GitHub 为主仓**：确保代码唯一真实来源
✅ **自动冲突解决**：优先自动 rebase，无法解决时提示用户
✅ **多触发点**：commit、push、PR 创建、PR 合并都有同步检查
✅ **用户友好**：清晰的错误提示和恢复指导
✅ **低风险**：失败时提示用户，不会自动破坏代码
---
**审批人**: [待确认]
**实施日期**: [待定]
**联系人**: [待定]

373
doc/CODE_SYNC_STRATEGY_FINAL.md
View File

@ -1,373 +0,0 @@
# GitLink-GitHub 代码双向同步方案（最终版）
**版本**: v2.0（最终确认）
**日期**: 2026-04-02
**状态**: 已确认，可实施
---
## 1 核心原则
- **GitHub 为主仓**：GitHub 是代码的唯一真实来源
- **GitLink 为镜像仓**：GitLink 作为备份和协作平台
- **所有操作在 GitLink 服务端**：无需用户本地配置
- **Main 分支保护**：只能通过 PR merge，禁止直接 push
- **关键点同步**：PR create/patch/merge 时自动同步 GitHub
---
## 2 同步触发点
### 2.1 三个关键触发点
| 触发点 | 事件 | 操作 |
|--------|------|------|
| **PR Create** | 用户创建 PR | fetch GitHub + rebase |
| **PR Patch** | 用户修改 PR（push 新 commit） | fetch GitHub + rebase |
| **PR Merge** | 用户点击 merge | fetch GitHub + rebase + merge + push GitHub |
### 2.2 详细流程
#### 2.2.1 PR Create 时同步
**触发**：用户在 GitLink 创建 PR（feature → main）
**流程**：
```
1. GitLink webhook 接收 PR created 事件
2. 执行：
├─ git fetch github main
├─ git checkout feature_branch
├─ git rebase github/main
├─ 检查是否有冲突
│ ├─ 有冲突 → PR 标记为 "需要 rebase"
│ │ 返回错误信息给用户
│ └─ 无冲突 → PR 状态正常，可以 merge
└─ 完成
```
**用户体验**：
- 如果无冲突：PR 创建成功，可以 merge
- 如果有冲突：PR 创建成功，但标记为冲突，提示用户本地解决冲突后重新 push
#### 2.2.2 PR Patch 时同步
**触发**：用户修改 PR（在 feature 分支上新增 commit 并 push）
**流程**：
```
1. GitLink webhook 接收 PR updated 事件
2. 执行：
├─ git fetch github main
├─ git checkout feature_branch
├─ git rebase github/main
├─ 检查是否有冲突
│ ├─ 有冲突 → PR 标记为 "需要 rebase"
│ │ 返回错误信息给用户
│ └─ 无冲突 → PR 状态正常，可以 merge
└─ 完成
```
**用户体验**：
- 每次 push 新 commit 时，自动检查是否与 GitHub 最新代码冲突
- 如果有冲突，立即提示用户
#### 2.2.3 PR Merge 时同步
**触发**：用户在 GitLink 点击 "Merge PR"
**流程**：
```
1. GitLink webhook 接收 PR merged 事件
2. 执行（事务性操作）：
├─ git fetch github main
├─ git checkout feature_branch
├─ git rebase github/main
├─ 检查是否有冲突
│ ├─ 有冲突 → merge 失败
│ │ 返回错误信息给用户
│ │ PR 状态回滚到 "open"
│ └─ 无冲突 → 继续
├─ git checkout main
├─ git merge feature_branch
├─ git push github main
├─ 检查 push 是否成功
│ ├─ 失败 → merge 失败，回滚
│ └─ 成功 → merge 成功，PR 标记为 "merged"
└─ 完成
```
**用户体验**：
- 点击 merge 后，自动完成所有同步操作
- 如果有冲突或 push 失败，立即反馈给用户
- 成功后，GitHub 和 GitLink 代码自动同步
---
## 3 Main 分支保护
### 3.1 保护规则
| 规则 | 说明 |
|------|------|
| 禁止直接 push | 用户不能直接 push 到 main 分支 |
| 只能 PR merge | main 分支只能通过 PR merge 更新 |
| 禁止 force push | GitLink 禁止所有 force push 操作 |
### 3.2 实现
在 GitLink 服务端配置分支保护：
```
项目设置 → 分支保护
├─ 分支名称: main
├─ 禁止直接 push: ✅
├─ 禁止 force push: ✅
└─ 只能通过 PR merge: ✅
```
---
## 4 用户工作流
### 4.1 场景 1：创建 PR
```bash
# 1. 用户在本地创建 feature 分支
git checkout -b feature/new-feature
# 2. 修改代码并 commit
git commit -m "feat: implement feature"
# 3. Push 到 GitLink
git push origin feature/new-feature
# 4. 在 GitLink 创建 PR: feature/new-feature → main
# GitLink webhook 自动触发：
# - fetch github main
# - rebase feature 到 github/main
# - 如果无冲突 → PR 创建成功
# - 如果有冲突 → PR 标记为 "需要 rebase"，提示用户
```
### 4.2 场景 2：修改 PR（Patch）
```bash
# 1. 用户在 feature 分支继续修改
git add .
git commit -m "fix: address review comments"
# 2. Push 到 GitLink
git push origin feature/new-feature
# 3. GitLink webhook 自动触发：
# - fetch github main
# - rebase feature 到 github/main
# - 如果无冲突 → PR 更新成功
# - 如果有冲突 → PR 标记为 "需要 rebase"，提示用户
```
### 4.3 场景 3：Merge PR
```bash
# 1. 用户在 GitLink 点击 "Merge PR"
# GitLink webhook 自动触发：
# - fetch github main
# - rebase feature 到 github/main
# - merge feature 到 main
# - push 到 github main
# - 如果无冲突 → merge 成功，GitHub 自动更新
# - 如果有冲突 → merge 失败，提示用户
```
### 4.4 场景 4：直接 Push（不允许）
```bash
# 用户尝试直接 push 到 main
git push origin main
# GitLink 拒绝：
# ❌ Error: 禁止直接 push 到 main 分支
# 请通过 PR merge 提交代码
```
---
## 5 冲突处理
### 5.1 冲突检测
在 PR create/patch/merge 时，GitLink 自动检查是否有冲突：
```bash
git rebase github/main
# 如果有冲突，rebase 会失败
if [ $? -ne 0 ]; then
# 有冲突
return error "冲突检测"
fi
```
### 5.2 冲突提示
当检测到冲突时，返回给用户：
```json
{
"ok": false,
"error": {
"code": "CONFLICT",
"message": "PR 与 GitHub 最新代码有冲突",
"details": {
"conflicted_files": ["file1.js", "file2.js"],
"suggestion": "请在本地解决冲突后重新 push"
}
}
}
```
### 5.3 用户解决冲突
```bash
# 1. 用户本地拉取最新代码
git fetch origin
git fetch github
# 2. 本地 rebase 到 github/main
git rebase github/main
# 3. 手动解决冲突
# 编辑冲突文件，解决冲突
# 4. 继续 rebase
git add .
git rebase --continue
# 5. 强制推送到 GitLink（覆盖之前的 commit）
git push origin feature/new-feature --force-with-lease
# 6. GitLink 再次检查冲突
# 如果无冲突 → PR 更新成功
```
---
## 6 错误处理
### 6.1 常见错误
| 错误 | 原因 | 解决方案 |
|------|------|--------|
| 冲突 | PR 与 GitHub 最新代码冲突 | 本地解决冲突后重新 push |
| Push 失败 | GitHub 网络问题 | 重试或联系管理员 |
| Merge 失败 | 冲突或权限问题 | 检查冲突或权限 |
### 6.2 错误恢复
**如果 PR merge 失败**：
```
1. GitLink 自动回滚 merge 操作
2. PR 状态回到 "open"
3. 用户收到错误提示
4. 用户解决问题后重新 merge
```
---
## 7 实现清单
### 7.1 GitLink 服务端
- [ ] 配置 main 分支保护（禁止直接 push、禁止 force push）
- [ ] 实现 PR created webhook
- [ ] fetch github main
- [ ] rebase feature 到 github/main
- [ ] 检查冲突，标记 PR 状态
- [ ] 实现 PR updated webhook
- [ ] fetch github main
- [ ] rebase feature 到 github/main
- [ ] 检查冲突，标记 PR 状态
- [ ] 实现 PR merged webhook（事务性操作）
- [ ] fetch github main
- [ ] rebase feature 到 github/main
- [ ] merge feature 到 main
- [ ] push 到 github main
- [ ] 失败时回滚
### 7.2 错误提示
- [ ] 冲突时返回详细错误信息
- [ ] 包含冲突文件列表
- [ ] 包含解决方案建议
### 7.3 文档
- [ ] 更新 README，说明 main 分支保护规则
- [ ] 编写用户指南，说明 PR 工作流
- [ ] 编写故障排查指南
---
## 8 验证与测试
### 8.1 测试场景
| 场景 | 预期结果 |
|------|---------|
| 创建无冲突 PR | PR 创建成功 |
| 创建有冲突 PR | PR 标记为冲突，提示用户 |
| Patch 无冲突 | PR 更新成功 |
| Patch 有冲突 | PR 标记为冲突，提示用户 |
| Merge 无冲突 | Merge 成功，GitHub 自动更新 |
| Merge 有冲突 | Merge 失败，PR 回滚到 open |
| 直接 push main | 拒绝，提示只能 PR merge |
| Force push | 拒绝，提示禁止 force push |
### 8.2 测试命令
```bash
# 1. 创建 PR
git checkout -b feature/test
echo "test" >> file.txt
git commit -m "test"
git push origin feature/test
# 在 GitLink 创建 PR
# 2. 修改 PR
echo "test2" >> file.txt
git commit -m "test2"
git push origin feature/test
# 3. Merge PR
# 在 GitLink 点击 merge
# 4. 验证 GitHub 是否更新
git log --oneline # 检查 GitHub 是否有新 commit
```
---
## 9 总结
**方案特点**：
✅ **简洁**：只在 PR create/patch/merge 时同步
✅ **安全**：main 分支保护，禁止直接 push
✅ **可靠**：事务性 merge，失败自动回滚
✅ **用户友好**：清晰的错误提示和恢复指导
✅ **无需本地配置**：所有操作在 GitLink 服务端
**预期效果**：
- GitHub 和 GitLink 代码始终一致
- 用户只需正常 git 操作
- 冲突自动检测，提示用户解决
- 代码质量有保证（PR review + merge）
---
**审批**：已确认
**实施日期**：待定
**联系人**：待定

595
doc/CODE_SYNC_STRATEGY_REVIEW.md
View File

@ -1,595 +0,0 @@
# 代码同步方案 - 深度审视与优化
**审视日期**: 2026-04-02
**审视范围**: 用户场景、漏洞、优化点
---
## 1 发现的关键漏洞
### 1.1 漏洞 1：GitHub 直接 push 无法同步到 GitLink
**问题描述**：
- 用户在 GitHub 直接 push 代码（不通过 GitLink）
- GitLink 本地仓库不知道 GitHub 有新代码
- 下次用户在 GitLink 操作时，HEAD 已经不同步，但用户不知道
**场景**：
```
1. 用户在 GitHub Web UI 直接修改文件并 commit
2. 或用户在另一台机器 push 到 GitHub
3. GitLink 本地仓库 HEAD 仍指向旧代码
4. 用户在 GitLink 执行 commit/push 时，pre-commit/pre-push hook 才发现不同步
5. 用户被迫 rebase，但此时可能已经做了本地修改
```
**影响**：
- 用户体验差：突然被告知需要 rebase
- 可能丢失本地修改：如果用户强制操作
**优化方案**：
- 添加 **post-checkout hook**：每次切换分支时检查 GitHub 是否有新代码
- 添加 **post-merge hook**：每次 merge 后检查 GitHub 是否有新代码
- 提供 **定时同步任务**：每 N 分钟自动检查一次 GitHub 是否有新代码
---
### 1.2 漏洞 2：Force Push 绕过 Hook
**问题描述**：
- 用户可以使用 `git push --force` 绕过 pre-push hook
- 这会导致 GitLink 和 GitHub 代码不一致
**场景**：
```bash
git push origin main --force # 绕过 pre-push hook
```
**影响**：
- 破坏同步机制
- 可能覆盖他人代码
**优化方案**：
- 在 pre-push hook 中检查 `--force` 标志，直接拒绝
- 或在 GitLink 服务端配置分支保护，禁止 force push
---
### 1.3 漏洞 3：多分支场景处理不清
**问题描述**：
- 方案只考虑了 `main` 分支的同步
- 用户可能在多个分支上工作（develop、feature 等）
- 不同分支的同步策略不同
**场景**：
```
1. 用户在 feature 分支工作
2. GitHub 的 main 分支有新代码
3. 用户在 feature 分支 commit，pre-commit hook 检查 main 分支
4. 但用户实际在 feature 分支，不需要同步 main
```
**影响**：
- Hook 逻辑不清：应该检查当前分支还是 main 分支？
- 可能误报或漏报
**优化方案**：
- **明确分支同步策略**：
- `main` 分支：必须与 GitHub main 同步
- `develop` 分支：必须与 GitHub develop 同步
- `feature/*` 分支：只需与本地 main 同步（可选）
- Hook 根据当前分支选择对应的检查策略
---
### 1.4 漏洞 4：Rebase 冲突后的恢复流程不清
**问题描述**：
- 用户执行 `git rebase github/main` 后，如果有冲突
- 用户手动解决冲突后，需要 `git rebase --continue`
- 但方案没有明确说明这个流程
**场景**：
```bash
git rebase github/main
# 冲突！
# 用户手动解决冲突
git add .
git rebase --continue
# 现在可以 commit 了
```
**影响**：
- 用户可能不知道如何恢复
- 可能导致 rebase 中止或错误操作
**优化方案**：
- 在 hook 失败时提供详细的恢复指导
- 提供 `gitlink-cli sync --resolve` 命令自动处理恢复流程
---
### 1.5 漏洞 5：Webhook 失败时的数据一致性问题
**问题描述**：
- PR 在 GitLink 成功 merge，但 webhook 推送到 GitHub 失败
- GitLink 和 GitHub 代码不一致，且无法自动恢复
**场景**：
```
1. 用户在 GitLink merge PR
2. GitLink 本地 merge 成功
3. Webhook 尝试 push 到 GitHub，但网络失败
4. GitLink 已 merge，GitHub 未更新
5. 下次用户操作时，发现不一致
```
**影响**：
- 数据不一致
- 需要手动干预恢复
**优化方案**：
- **事务性操作**：merge 和 push 作为一个原子操作
- **重试机制**：webhook 失败时自动重试（指数退避）
- **死信队列**：重试失败后放入队列，定期重试
- **监控告警**：同步失<EFBFBD><EFBFBD><EFBFBD>时立即告警
---
### 1.6 漏洞 6：并发操作导致的竞态条件
**问题描述**：
- 多个用户同时在 GitLink 和 GitHub 操作
- 可能导致竞态条件和数据不一致
**场景**：
```
时间线：
T1: 用户 A 在 GitLink merge PR1
T2: 用户 B 在 GitHub push 代码
T3: 用户 A 的 webhook 尝试 push 到 GitHub
T4: 冲突！GitHub 已有用户 B 的代码
```
**影响**：
- Push 失败
- 需要手动解决
**优化方案**：
- **分布式锁**：merge 时加锁，防止并发
- **版本控制**：记录每次同步的版本号
- **冲突检测**：push 前检查 GitHub 是否有新代码
---
### 1.7 漏洞 7：Tag 和 Release 的同步
**问题描述**：
- 方案只考虑了代码同步
- 没有考虑 tag 和 release 的同步
**场景**：
```
1. 用户在 GitLink 创建 release v1.0.0
2. GitHub 没有对应的 tag 和 release
3. 两个平台的版本信息不一致
```
**影响**：
- 版本管理混乱
- 用户困惑
**优化方案**：
- 添加 release 同步逻辑
- 创建 release 时自动同步到 GitHub
---
## 2 用户场景分析
### 2.1 场景 1：多设备开发
**用户行为**：
```
设备 A（GitLink）→ commit → push GitLink
设备 B（GitHub）→ commit → push GitHub
设备 A（GitLink）→ commit → 发现不同步
```
**当<><E5BD93>方案的问题**：
- 设备 A 在 commit 时才发现不同步
- 此时已经做了本地修改，需要 rebase
**优化**：
- 添加 post-checkout hook，切换分支时检查同步状态
- 提示用户 GitHub 有新代码，建议 rebase
---
### 2.2 场景 2：紧急修复
**用户行为**：
```
1. 用户在 GitHub 直接修复 bug（通过 Web UI）
2. 用户回到 GitLink，继续开发
3. 用户 commit，发现需要 rebase
```
**当前方案的问题**：
- 用户体验差，被迫中断开发流程
**优化**：
- 提供 `gitlink-cli sync` 命令，用户可主动同步
- 在 IDE 中集成同步提示
---
### 2.3 场景 3：大型团队协作
**用户行为**：
```
1. 多个开发者同时在 GitLink 和 GitHub 操作
2. PR 频繁创建和合并
3. 代码冲突频繁
```
**当前方案的问题**：
- 没有考虑并发控制
- 可能导致数据不一致
**优化**：
- 添加分布式锁
- 添加冲突检测和自动解决
---
### 2.4 场景 4：离线开发
**用户行为**：
```
1. 用户离线开发，多次 commit
2. 用户上线后，尝试 push
3. 发现 GitHub 有新代码，需要 rebase
```
**当前方案的问题**：
- 用户需要 rebase 多次 commit
- 可能很复杂
**优化**：
- 提供 `gitlink-cli sync --squash` 命令，合并 commit 后再 rebase
- 简化恢复流程
---
## 3 优化建议
### 3.1 优化 1：完善 Hook 体系
**添加的 Hooks**：
| Hook | 触发时机 | 职责 |
|------|---------|------|
| `pre-commit` | commit 前 | 检查 HEAD 同步 |
| `pre-push` | push 前 | 检查 HEAD 同步 |
| `post-checkout` | 切换分支后 | 检查 GitHub 是否有新代码，提示用户 |
| `post-merge` | merge 后 | 检查 GitHub 是否有新代码，提示用户 |
**实现**：
```bash
# post-checkout hook
#!/bin/bash
GITHUB_HEAD=$(git ls-remote https://github.com/owner/repo HEAD | awk '{print $1}')
GITLINK_HEAD=$(git rev-parse HEAD)
if [ "$GITHUB_HEAD" != "$GITLINK_HEAD" ]; then
echo "ℹ️ Info: GitHub 有新代码，建议执行: git fetch github && git rebase github/main"
fi
```
---
### 3.2 优化 2：明确分支同步策略
**分支分类**：
| 分支类型 | 同步策略 | 说明 |
|---------|--------|------|
| `main` | 必须同步 | 主分支，必须与 GitHub 同步 |
| `develop` | 必须同步 | 开发分支，必须与 GitHub 同步 |
| `feature/*` | 可选同步 | 功能分支，可选与 main 同步 |
| `hotfix/*` | 必须同步 | 紧急修复，必须与 GitHub 同步 |
**Hook 实现**：
```bash
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
case $CURRENT_BRANCH in
main|develop|hotfix/*)
# 必<><E5BF85>同步
check_sync_required
;;
feature/*)
# 可选同步
check_sync_optional
;;
esac
```
---
### 3.3 优化 3：添加主动同步命令
**新增命令**：
```bash
# 检查同步状态
gitlink-cli sync status
# 主动同步（拉取 GitHub 最新代码）
gitlink-cli sync pull
# 主动同步并 rebase（如果有冲突）
gitlink-cli sync pull --rebase
# 自动解决冲突并继续
gitlink-cli sync resolve
# 查看同步日志
gitlink-cli sync logs
```
---
### 3.4 优化 4：添加事务性 Merge
**改进 Merge 流程**：
```
1. 开始事务
2. 拉取最新 GitHub 代码
3. Rebase PR 分支
4. Merge 到 main
5. Push 到 GitHub
6. 提交事务
7. 如果任何步骤失败，回滚事务
```
**实现**：
```bash
# 伪代码
begin_transaction()
try:
git fetch github
git rebase github/main
git merge source_branch
git push github main
commit_transaction()
except:
rollback_transaction()
raise error
```
---
### 3.5 优化 5：添加冲突检测和自动解决
**冲突检测**：
```bash
# 检查是否有冲突
git diff --name-only --diff-filter=U
# 如果有冲突，尝试自动解决
if [ -n "$(git diff --name-only --diff-filter=U)" ]; then
# 尝试使用 ours 策略
git checkout --ours .
git add .
git rebase --continue
fi
```
---
### 3.6 优化 6：添加监控和告警
**监控指标**：
| 指标 | 告警条件 |
|------|---------|
| Webhook 失败率 | > 5% |
| Sync 延迟 | > 5 分钟 |
| 冲突率 | > 10% |
| 数据不一致 | 任何检测到 |
**实现**：
```bash
# 记录同步日志
log_sync_event(
event_type: "merge",
status: "success|failure",
duration: 1.5s,
conflict_count: 0,
timestamp: 2026-04-02T10:30:00Z
)
# 定期检查指标
if webhook_failure_rate > 0.05:
alert("Webhook 失败率过高")
```
---
### 3.7 优化 7：添加用户指导和恢复工具
**改进错误提示**：
```bash
# 当前
❌ Error: GitLink HEAD 不同步 GitHub
请执行: git fetch github && git rebase github/main
# 优化后
❌ Error: GitLink HEAD 不同步 GitHub
原因：GitHub 有新代码，GitLink 本地未同步
解决方案：
1. 拉取最新代码: git fetch github
2. Rebase 到最新: git rebase github/main
3. 如果有冲突，手动解决后执行: git rebase --continue
4. 重新 commit: git commit -m "..."
或使用自动恢复命令：
gitlink-cli sync resolve
需要帮助？查看文档：https://docs.gitlink.org.cn/sync
```
---
### 3.8 优化 8：添加 Force Push 保护
**在 pre-push hook 中检查**：
```bash
# 检查是否使用了 --force
if [[ "$@" == *"--force"* ]] || [[ "$@" == *"-f"* ]]; then
echo "❌ Error: 禁止使用 force push"
echo "如果需要强制推送，请联系管理员"
exit 1
fi
```
---
## 4 修订后的方案架构
### 4.1 完整的 Hook 体系
```
用户操作
├─ git checkout branch
│ └─ post-checkout hook
│ └─ 检查 GitHub 是否有新代码（提示，不阻止）
├─ git commit
│ └─ pre-commit hook
│ └─ 检查 HEAD 是否同步（阻止）
├─ git push
│ └─ pre-push hook
│ ├─ 检查 --force 标志（阻止）
│ └─ 检查 HEAD 是否同步（阻止）
└─ git merge
└─ post-merge hook
└─ 检查 GitHub 是否有新代码（提示，不阻止）
```
### 4.2 完整的 Webhook 体系
```
GitLink 事件
├─ PR Created
│ └─ 拉取 GitHub 最新代码
│ └─ 自动 rebase
│ └─ 如果冲突无法解决，标记为 "需要手动 rebase"
├─ PR Merged
│ └─ 开始事务
│ └─ 拉取 GitHub 最新代码
│ └─ 自动 rebase
│ └─ Merge 到 main
│ └─ Push 到 GitHub
│ └─ 提交事务（或回滚）
└─ Release Created
└─ 同步 tag 和 release 到 GitHub
```
### 4.3 完整的 CLI 命令体系
```
gitlink-cli sync
├─ status # 查看同步状态
├─ pull # 拉取 GitHub 最新代码
├─ pull --rebase # 拉取并 rebase
├─ resolve # 自动解决冲突
├─ logs # 查看同步日志
└─ force-push # 强制推送（需要管理员权限）
```
---
## 5 风险评估
### 5.1 修复前的风险
| 风险 | 严重性 | 修复方案 |
|------|--------|--------|
| GitHub 直接 push 无法同步 | 高 | post-checkout hook |
| Force push 绕过 hook | 高 | pre-push hook 检查 |
| 多分支场景处理不清 | 中 | 明确分支同步策略 |
| Rebase 冲突恢复流程不清 | 中 | 提供自动恢复命令 |
| Webhook 失败导致不一致 | 高 | 事务性操作 + 重试机制 |
| 并发操作竞态条件 | 中 | 分布式锁 |
| Tag/Release 不同步 | 低 | 添加 release 同步 |
### 5.2 修复后的风险
| 风险 | 严重性 | 剩余风险 |
|------|--------|---------|
| GitHub 直接 push 无法同步 | 低 | 用户需要主动切换分支触发 hook |
| Force push 绕过 hook | 低 | 管理员可能需要强制推送 |
| 多分支场景处理不清 | 低 | 分支策略需要文档说明 |
| Rebase 冲突恢复流程不清 | 低 | 用户需要学习新命令 |
| Webhook 失败导致不一致 | 低 | 网络故障可能导致延迟 |
| 并发操作竞态条件 | 低 | 分布式锁可能有性能开销 |
| Tag/Release 不同步 | 低 | 需要额外实现 |
---
## 6 实施优先级
### 6.1 第一阶段（必须）
- [ ] 完善 pre-commit 和 pre-push hooks
- [ ] 添加 post-checkout hook
- [ ] 实现 PR Merged webhook 的事务性操作
- [ ] 添加 force push 保护
### 6.2 第二阶段（重要）
- [ ] 添加 `gitlink-cli sync` 命令
- [ ] 实现冲突自动解决
- [ ] 添加监控和告警
- [ ] 完善错误提示和恢复指导
### 6.3 第三阶段（可选）
- [ ] 添加分布式锁
- [ ] 实现 release 同步
- [ ] 添加 IDE 集成
- [ ] 性能优化
---
## 7 总结
**原方案的主要漏洞**：
1. GitHub 直接 push 无法同步
2. Force push 绕过 hook
3. 多分支场景处理不清
4. Webhook 失败导致不一致
5. 并发操作竞态条件
**修订后的方案**：
- 添加 post-checkout 和 post-merge hooks
- 明确分支同步策略
- 实现事务性 merge
- 添加主动同步命令
- 添加监控和告警
**预期效果**：
- ✅ 代码同步更可靠
- ✅ 用户体验更好
- ✅ 故障恢复更快
- ✅ 数据一致性更强

107
doc/SKILLS_TEST_REPORT_2026-04-02.md
View File

@ -1,107 +0,0 @@
# GitLink Skills 整体测试报告
**测试日期**: 2026-04-02
**测试范围**: 8 个常用场景 + 边界情况 + 输出格式
---
## 测试结果总结
✅ **所有场景通过** (8/8)
| 场景 | 命令 | 结果 | 备注 |
|------|------|------|------|
| 认证 | `auth status` | ✅ | 正常登录 |
| 用户 | `user +me` | ✅ | 获取当前用户 |
| 搜索仓库 | `search +repos` | ✅ | 找到 2 个仓库 |
| 搜索用户 | `search +users` | ✅ | 找到 24 个用户 |
| 组织列表 | `org +list` | ✅ | 找到 2 个组织 |
| 组织详情 | `org +info` | ✅ | Gitlink 组织 54 个项目 |
| 组织成员 | `org +members` | ✅ | 列出成员 |
| 仓库操作 | `repo +list/+info` | ✅ | 正常工作 |
| 分支操作 | `branch +list` | ✅ | 列出 3 个分支 |
| Issue 操作 | `issue +list` | ✅ | 找到 1 个 Issue |
---
## 边界情况测试
| 测试 | 结果 | 说明 |
|------|------|------|
| 无效 owner/repo | ✅ | 返回 404 错误 |
| 无效 Issue ID | ✅ | 返回 404 错误 |
| 搜索空结果 | ✅ | 返回空数组 |
| 分页 | ✅ | 正常工作 |
| Release 列表 | ✅ | 返回空列表 |
| PR 列表 | ✅ | 返回空列表 |
---
## 输出格式测试
| 格式 | 结果 | 说明 |
|------|------|------|
| JSON | ✅ | 有效 JSON，包含 ok/data 字段 |
| Table | ✅ | 正常渲染表格 |
| YAML | ✅ | 正常转换 |
| 默认 | ✅ | 默认为 JSON 格式 |
---
## 发现的问题
### 问题 1: Table 格式中 branches 字段显示不完整
**症状**: `branch +list --format table` 时，branches 字段显示为截断的 JSON 字符串
**原因**: Table 格式化器对嵌套对象的处理不够友好
**影响**: 低（用户通常用 JSON 格式）
**建议**: 改进 Table 格式化器对复杂数据的处理
---
## Skills 文档评估
✅ **SKILL.md** - 清晰的命令参考
✅ **REFERENCE.md** - 详细的 API 参考
✅ **TROUBLESHOOTING.md** - 常见问题排查
✅ **examples/** - 真实工作流示例
**改进建议**:
1. 为每个 Shortcut 添加返回值说明
2. 添加更多错误场景的处理示例
3. 为 Raw API 添加更多使用示例
---
## 总体评分
| 维度 | 评分 | 说明 |
|------|------|------|
| 功能完整性 | 9/10 | 核心功能完整，PR 创建有限制 |
| 文档质量 | 8/10 | 文档详细，但可增加更多示例 |
| 错误处理 | 8/10 | 错误提示清晰，但某些 API Bug 无法处理 |
| 易用性 | 9/10 | 命令直观，自动上下文解析好用 |
**总体**: ✅ **生产就绪** (8.5/10)
---
## 建议优化项
### 短期（立即）
1. ✅ 已完成：Skills 文档重构
2. ✅ 已完成：添加工作流示例
3. ✅ 已完成：添加故障排查指南
### 中期（1-2 周）
1. 改进 Table 格式化器
2. 为 Raw API 添加更多示例
3. 添加 CI/CD 工作流示例
### 长期（1 个月+）
1. 联系 GitLink 修复 5 个 API Bug
2. 添加 AI 自动化工作流模板
3. 建立 Skills 版本管理机制

143
doc/TEST_REPORT_2026-04-01.md
View File

@ -24,9 +24,7 @@
## 发现的 Bug 及修复
**总计**: 7 个 Bug (2 个 CLI Bug 已修复 + 5 个 GitLink API Bug 未修复)
### Bug #1: Issue 创建失败 - done_ratio 字段缺失 (CLI Bug - 已修复)
### Bug #1: Issue 创建失败 - done_ratio 字段缺失
**症状**:
```
@ -50,7 +48,7 @@ body := map[string]interface{}{
---
### Bug #2: Issue 关闭失败 - 标题字段缺失 (CLI Bug - 已修复)
### Bug #2: Issue 关闭失败 - 标题字段缺失
**症状**:
```
@ -80,7 +78,7 @@ body := map[string]interface{}{
---
### Bug #3: Branch 删除失败 - API 返回"分支不存在" (GitLink API Bug)
### Bug #3: Branch 删除失败 - API 返回"分支不存在"
**症状**:
```
@ -99,7 +97,7 @@ body := map[string]interface{}{
- ❌ `/v1/:owner/:repo/branches/:name.json` (DELETE) - 返回 404
- ❌ `/:owner/:repo/branches/:name.json` (DELETE) - 返回 404
**根本原因**: GitLink API Bug - DELETE 端点实现有问题
**根本原因**: 未知 - 可能是 GitLink API 的 Bug 或权限问题
**当前状态**: ⚠️ 未修复，需要与 GitLink 团队确认
@ -107,107 +105,6 @@ body := map[string]interface{}{
---
### Bug #4: Release 删除失败 - API 返回"版本不存在" (GitLink API Bug)
**症状**:
```
[-1] 版本不存在
```
**现象**:
- release +create 成功创建 Release
- release +list 可以列出该 Release (version_id=1752)
- release +delete 返回"版本不存在"错误
**根本原因**: GitLink API Bug - DELETE 端点实现有问题或权限限制
**当前状态**: ⚠️ 未修复，需要与 GitLink 团队确认
**影响范围**: release +delete shortcut
---
### Bug #5: Release 查看返回 HTML (GitLink API Bug)
**症状**:
```
返回完整 HTML 页面而非 JSON
```
**现象**:
- `GET /api/{owner}/{repo}/releases/{tag_name}` 返回 HTML
- `GET /api/{owner}/{repo}/releases/{version_id}` 返回正确的 JSON
**根本原因**: GitLink API 的 tag_name 路由指向 Web 页面而非 API
**当前状态**: ✅ 已规避 - 使用 version_id 代替 tag_name
**影响范围**: release +view shortcut (已通过使用 version_id 规避)
---
### Bug #6: Create File API 返回"文件已存在"
**症状**:
```
[-1] {filename}文件已存在，不能重复创建!
```
**现象**:
- 在新创建的分支上调用 create_file
- 即使文件不存在也返回"文件已存在"错误
**测试**:
```bash
# 创建新分支
branch +create -n pr-real-test-1775055754 # ✅ 成功
# 在新分支上创建文件
api POST "/wbtiger/gitlink-cli/create_file" --body '{
"filepath": "NEW_FILE.md",
"content": "test",
"branch": "pr-real-test-1775055754"
}'
# ❌ 返回: "NEW_FILE.md文件已存在，不能重复创建!"
```
**根本原因**: GitLink API Bug - create_file 端点<E7ABAF><E782B9><EFBFBD>辑错误
**当前状态**: ⚠️ 未修复，无法通过 API 创建文件
**影响范围**: 无法通过 API 在分支上创建代码变更，导致 PR 创建失败
---
### Bug #7: Update File API 缺少 SHA 参数说明
**症状**:
```
[-1] 验证失败: Sha不能为空字符
```
**现象**:
- 调用 update_file 返回"Sha不能为空"错误
- API 文档未说明需要 SHA 参数
**测试**:
```bash
api PUT "/wbtiger/gitlink-cli/update_file" --body '{
"filepath": "README.md",
"content": "updated",
"branch": "pr-real-test-1775055754"
}'
# ❌ 返回: "验证失败: Sha不能为空字符"
```
**根本原因**: GitLink API 文档不完整，缺少必需参数说明
**当前状态**: ⚠️ 未修复，无法通过 API 更新文件
**影响范围**: 无法通过 API 修改文件内容
---
## 场景测试详情
### 场景 1: 仓库管理流程
@ -288,7 +185,7 @@ api PUT "/wbtiger/gitlink-cli/update_file" --body '{
## API 行为发现
### 1. Release 端点需要 version_id (API 设计问题)
### 1. Release 端点需要 version_id
**发现**: `release +view` 使用 tag_name 返回 HTML 页面，需要用 version_id
@ -304,7 +201,7 @@ release +view -i 1752 # 返回 JSON
---
### 2. Branch 列表返回 JSON 字符串 (格式化问题)
### 2. Branch 列表返回 JSON 字符串
**发现**: `branch +list` 返回的 data 是 JSON 字符串而非解析后的对象
@ -317,11 +214,9 @@ release +view -i 1752 # 返回 JSON
**影响**: 格式化输出时需要额外处理
**建议**: 在 client.go 中处理 JSON 字符串自动解析
---
### 3. Issue 更新需要 subject 字段 (API 设计问题)
### 3. Issue 更新需要 subject 字段
**发现**: 任何 Issue 更新操作都需要包含 subject 字段，即使只更新状态
@ -338,11 +233,9 @@ body := map[string]interface{}{
}
```
**建议**: 更新 SKILL.md 文档说明必需字段
---
### 4. PR 创建需要实际代码变更 (API 设计限制)
### 4. PR 创建需要实际代码变更
**发现**: GitLink API 检查分支内容，如果与目标分支相同则拒绝创建 PR
@ -350,25 +243,7 @@ body := map[string]interface{}{
[-1] 分支内容相同，无需创建合并请求
```
**影响**: 无法通过 API 创建文件导致无法完整测试 PR 工作流
**建议**: 文档说明此限制，建议用户在本地创建代码变更后推送
---
### 5. Update File API 需要 SHA 参数 (文档不完整)
**发现**: update_file 需要 SHA 参数但文档未说明
```bash
# ❌ 返回: "验证失败: Sha不能为空字符"
api PUT "/wbtiger/gitlink-cli/update_file" --body '{
"filepath": "README.md",
"content": "updated"
}'
```
**建议**: 联系 GitLink 团队补充文档或提供 SHA 获取方式
**建议**: 测试 PR 功能时需要在分支中进行实际代码提交
---

8
internal/client/client.go
View File

@ -132,14 +132,6 @@ func (c *Client) Do(method, path string, body interface{}, query url.Values) (*o
}
}
// Auto-parse JSON string data (GitLink API quirk: some endpoints return data as JSON string)
if dataStr, ok := raw["data"].(string); ok {
var parsedData interface{}
if err := json.Unmarshal([]byte(dataStr), &parsedData); err == nil {
raw["data"] = json.RawMessage(dataStr)
}
}
// Build meta from pagination info
var meta *output.Meta
if tc, ok := raw["total_count"]; ok {

14
internal/output/formatter.go
View File

@ -71,10 +71,6 @@ func printTable(w io.Writer, envelope *Envelope) error {
case []interface{}:
return printSliceTable(w, data)
case map[string]interface{}:
// For maps with nested structures, prefer JSON
if hasComplexValues(data) {
return printJSON(w, envelope)
}
return printMapTable(w, data)
default:
// Fallback to JSON
@ -82,16 +78,6 @@ func printTable(w io.Writer, envelope *Envelope) error {
}
}
func hasComplexValues(m map[string]interface{}) bool {
for _, v := range m {
switch v.(type) {
case map[string]interface{}, []interface{}:
return true
}
}
return false
}
func printSliceTable(w io.Writer, items []interface{}) error {
if len(items) == 0 {
fmt.Fprintln(w, "No results")

21
npm/bin/cli.js
View File

@ -1,21 +0,0 @@
#!/usr/bin/env node
"use strict";
const path = require("path");
const { execFileSync } = require("child_process");
const binaryPath = path.join(__dirname, "gitlink-cli");
try {
execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
} catch (err) {
if (err.status !== undefined) {
process.exit(err.status);
}
console.error(`Failed to run gitlink-cli: ${err.message}`);
console.error(
"Binary may not be installed. Try reinstalling: npm install -g @gitlink-ai/cli"
);
process.exit(1);
}

42
npm/package.json
View File

@ -1,42 +0,0 @@
{
"name": "@gitlink-ai/cli",
"version": "0.1.1",
"description": "GitLink 平台官方命令行工具 — 代码托管、协作开发和自动化",
"bin": {
"gitlink-cli": "bin/cli.js"
},
"scripts": {
"postinstall": "node scripts/install.js"
},
"keywords": [
"gitlink",
"cli",
"git",
"devops",
"code-hosting"
],
"author": "GitLink <support@gitlink.org.cn>",
"license": "Apache-2.0",
"homepage": "https://www.gitlink.org.cn/Gitlink/gitlink-cli",
"repository": {
"type": "git",
"url": "https://www.gitlink.org.cn/Gitlink/gitlink-cli.git"
},
"os": [
"darwin",
"linux"
],
"cpu": [
"x64",
"arm64"
],
"files": [
"bin/",
"scripts/",
"skills/",
"README.md"
],
"engines": {
"node": ">=14"
}
}

242
npm/scripts/install.js
View File

@ -1,242 +0,0 @@
#!/usr/bin/env node
"use strict";
const os = require("os");
const path = require("path");
const fs = require("fs");
const https = require("https");
const http = require("http");
const { execSync } = require("child_process");
const PACKAGE = require("../package.json");
const VERSION = PACKAGE.version;
const BINARY_NAME = "gitlink-cli";
// GitLink release download base URL
// Format: https://www.gitlink.org.cn/Gitlink/gitlink-cli/releases
// Attachment download: https://www.gitlink.org.cn/api/attachments/{attachment_id}
const RELEASE_BASE = "https://www.gitlink.org.cn";
const REPO_OWNER = "Gitlink";
const REPO_NAME = "gitlink-cli";
function getPlatformInfo() {
const platform = os.platform();
const arch = os.arch();
const platformMap = {
darwin: "darwin",
linux: "linux",
};
const archMap = {
x64: "amd64",
arm64: "arm64",
};
const goPlatform = platformMap[platform];
const goArch = archMap[arch];
if (!goPlatform || !goArch) {
throw new Error(
`Unsupported platform: ${platform}-${arch}. ` +
`Supported: darwin-x64, darwin-arm64, linux-x64, linux-arm64`
);
}
return { platform: goPlatform, arch: goArch };
}
function getBinaryName(platform) {
return BINARY_NAME;
}
function getArchiveName(platform, arch) {
return `${BINARY_NAME}_${VERSION}_${platform}_${arch}.tar.gz`;
}
function fetch(url, options = {}) {
return new Promise((resolve, reject) => {
const maxRedirects = options.maxRedirects || 5;
let redirectCount = 0;
function doRequest(currentUrl) {
const mod = currentUrl.startsWith("https") ? https : http;
const req = mod.get(currentUrl, (res) => {
// Follow redirects
if (
(res.statusCode === 301 ||
res.statusCode === 302 ||
res.statusCode === 307 ||
res.statusCode === 308) &&
res.headers.location
) {
redirectCount++;
if (redirectCount > maxRedirects) {
reject(new Error(`Too many redirects (max ${maxRedirects})`));
return;
}
let redirectUrl = res.headers.location;
if (redirectUrl.startsWith("/")) {
const parsed = new URL(currentUrl);
redirectUrl = `${parsed.protocol}//${parsed.host}${redirectUrl}`;
}
doRequest(redirectUrl);
return;
}
if (res.statusCode !== 200) {
reject(
new Error(`HTTP ${res.statusCode} when downloading ${currentUrl}`)
);
return;
}
if (options.json) {
let body = "";
res.on("data", (chunk) => (body += chunk));
res.on("end", () => {
try {
resolve(JSON.parse(body));
} catch (e) {
reject(new Error(`Failed to parse JSON: ${e.message}`));
}
});
} else {
const chunks = [];
res.on("data", (chunk) => chunks.push(chunk));
res.on("end", () => resolve(Buffer.concat(chunks)));
}
});
req.on("error", reject);
req.setTimeout(60000, () => {
req.destroy();
reject(new Error("Request timed out"));
});
}
doRequest(url);
});
}
async function findReleaseAsset(platform, arch) {
const archiveName = getArchiveName(platform, arch);
// Try fetching release info from GitLink API
const apiUrl = `${RELEASE_BASE}/api/${REPO_OWNER}/${REPO_NAME}/releases.json`;
console.log(`Fetching release info from ${apiUrl}`);
try {
const releases = await fetch(apiUrl, { json: true });
// Find the release matching our version
let release = null;
const tagName = `v${VERSION}`;
if (Array.isArray(releases)) {
release = releases.find(
(r) => r.tag_name === tagName || r.tag_name === VERSION
);
if (!release && releases.length > 0) {
// Fall back to latest release
release = releases[0];
}
} else if (releases && releases.releases) {
const list = releases.releases;
release = list.find(
(r) => r.tag_name === tagName || r.tag_name === VERSION
);
if (!release && list.length > 0) {
release = list[0];
}
}
if (release && release.attachments) {
const asset = release.attachments.find(
(a) => a.title === archiveName || a.filename === archiveName
);
if (asset) {
// Return the download URL for this attachment
const downloadUrl = asset.url || `${RELEASE_BASE}/api/attachments/${asset.id}`;
return downloadUrl;
}
}
} catch (e) {
console.log(`Warning: Could not fetch release info: ${e.message}`);
}
// Fallback: try direct download URL pattern
return `${RELEASE_BASE}/api/${REPO_OWNER}/${REPO_NAME}/releases/${tagName}/assets/${archiveName}`;
}
async function downloadAndExtract(url, destDir) {
console.log(`Downloading ${BINARY_NAME} from ${url}...`);
const data = await fetch(url);
const tarballPath = path.join(destDir, "download.tar.gz");
fs.writeFileSync(tarballPath, data);
console.log(`Downloaded ${(data.length / 1024 / 1024).toFixed(1)} MB`);
// Extract using tar
execSync(`tar -xzf "${tarballPath}" -C "${destDir}"`, { stdio: "pipe" });
fs.unlinkSync(tarballPath);
// Find the binary in extracted files
const binaryName = getBinaryName();
const binaryPath = path.join(destDir, binaryName);
if (!fs.existsSync(binaryPath)) {
// It might be in a subdirectory
const files = fs.readdirSync(destDir);
for (const file of files) {
const subPath = path.join(destDir, file, binaryName);
if (fs.existsSync(subPath)) {
fs.renameSync(subPath, binaryPath);
break;
}
}
}
if (!fs.existsSync(binaryPath)) {
throw new Error(`Binary "${binaryName}" not found after extraction`);
}
// Make executable
fs.chmodSync(binaryPath, 0o755);
console.log(`Installed ${BINARY_NAME} to ${binaryPath}`);
}
async function main() {
try {
const { platform, arch } = getPlatformInfo();
console.log(`Platform: ${platform}-${arch}`);
const binDir = path.join(__dirname, "..", "bin");
if (!fs.existsSync(binDir)) {
fs.mkdirSync(binDir, { recursive: true });
}
const binaryPath = path.join(binDir, getBinaryName());
// If binary already exists (pre-packed), skip download
if (fs.existsSync(binaryPath)) {
console.log(`${BINARY_NAME} binary already exists, skipping download.`);
return;
}
const downloadUrl = await findReleaseAsset(platform, arch);
await downloadAndExtract(downloadUrl, binDir);
} catch (err) {
console.error(`\nFailed to install ${BINARY_NAME}: ${err.message}`);
console.error(
`\nYou can install manually:\n` +
` 1. Download from https://www.gitlink.org.cn/${REPO_OWNER}/${REPO_NAME}/releases\n` +
` 2. Extract and place the binary in your PATH\n` +
` 3. Or build from source: git clone && make build\n`
);
process.exit(1);
}
}
main();

80
scripts/build-npm.sh
View File

@ -1,80 +0,0 @@
#!/bin/bash
# Build multi-platform binaries and package for npm
set -e
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
NPM_DIR="$PROJECT_DIR/npm"
DIST_DIR="$PROJECT_DIR/dist"
# Read version from npm/package.json
VERSION=$(node -p "require('$NPM_DIR/package.json').version")
MODULE="github.com/gitlink-org/gitlink-cli"
LDFLAGS="-s -w -X '${MODULE}/cmd.Version=${VERSION}'"
BINARY="gitlink-cli"
echo "=== Building gitlink-cli v${VERSION} ==="
# Clean
rm -rf "$DIST_DIR"
mkdir -p "$DIST_DIR"
# Platforms to build: GOOS/GOARCH
PLATFORMS=(
"darwin/amd64"
"darwin/arm64"
"linux/amd64"
"linux/arm64"
)
cd "$PROJECT_DIR"
for PLATFORM in "${PLATFORMS[@]}"; do
GOOS="${PLATFORM%/*}"
GOARCH="${PLATFORM#*/}"
OUTPUT_NAME="${BINARY}"
echo "Building ${GOOS}/${GOARCH}..."
ARCHIVE_DIR="${DIST_DIR}/${BINARY}_${VERSION}_${GOOS}_${GOARCH}"
mkdir -p "$ARCHIVE_DIR"
CGO_ENABLED=0 GOOS="$GOOS" GOARCH="$GOARCH" \
go build -ldflags "$LDFLAGS" -o "${ARCHIVE_DIR}/${OUTPUT_NAME}" .
# Create tar.gz archive
ARCHIVE_NAME="${BINARY}_${VERSION}_${GOOS}_${GOARCH}.tar.gz"
(cd "$DIST_DIR" && tar -czf "$ARCHIVE_NAME" -C "${ARCHIVE_DIR}" "$OUTPUT_NAME")
echo " -> dist/${ARCHIVE_NAME}"
rm -rf "$ARCHIVE_DIR"
done
echo ""
echo "=== Build complete ==="
echo "Archives in dist/:"
ls -lh "$DIST_DIR"/*.tar.gz
echo ""
echo "=== Packaging npm ==="
# Copy README and skills to npm dir
cp "$PROJECT_DIR/README.md" "$NPM_DIR/README.md"
rm -rf "$NPM_DIR/skills"
cp -r "$PROJECT_DIR/skills" "$NPM_DIR/skills"
# Ensure bin dir exists and wrapper is executable
chmod +x "$NPM_DIR/bin/gitlink-cli"
echo ""
echo "=== Done ==="
echo ""
echo "Next steps:"
echo " 1. Upload dist/*.tar.gz to GitLink Release v${VERSION}"
echo " URL: https://www.gitlink.org.cn/Gitlink/gitlink-cli/releases"
echo ""
echo " 2. Publish npm package:"
echo " cd npm && npm publish --access public"
echo ""
echo " Or for local-packed npm (includes binary for current platform):"
echo " ./scripts/pack-local.sh"

39
scripts/pack-local.sh
View File

@ -1,39 +0,0 @@
#!/bin/bash
# Pack npm package with the binary for the current platform pre-included.
# This way npm install does NOT need to download anything.
set -e
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
NPM_DIR="$PROJECT_DIR/npm"
MODULE="github.com/gitlink-org/gitlink-cli"
VERSION=$(node -p "require('$NPM_DIR/package.json').version")
LDFLAGS="-s -w -X '${MODULE}/cmd.Version=${VERSION}'"
BINARY="gitlink-cli"
echo "=== Building gitlink-cli for current platform ==="
cd "$PROJECT_DIR"
# Build for current platform
CGO_ENABLED=0 go build -ldflags "$LDFLAGS" -o "$NPM_DIR/bin/${BINARY}" .
chmod +x "$NPM_DIR/bin/${BINARY}"
cp "$PROJECT_DIR/README.md" "$NPM_DIR/README.md"
# Copy skills directory
rm -rf "$NPM_DIR/skills"
cp -r "$PROJECT_DIR/skills" "$NPM_DIR/skills"
echo "Binary size: $(du -h "$NPM_DIR/bin/${BINARY}" | cut -f1)"
echo ""
echo "=== Creating npm tarball ==="
cd "$NPM_DIR"
npm pack
echo ""
echo "=== Done ==="
echo "To install locally: npm install -g gitlink-ai-cli-${VERSION}.tgz"
echo "To publish: cd npm && npm publish --access public"

2
shortcuts/branch/branch.go
View File

@ -23,7 +23,7 @@ func Shortcuts() []*common.Shortcut {
q := url.Values{}
q.Set("page", ctx.Arg("page"))
q.Set("limit", ctx.Arg("limit"))
env, err := ctx.CallAPIWithQuery("GET", "/v1"+ctx.RepoPath()+"/branches", q)
env, err := ctx.CallAPIWithQuery("GET", ctx.RepoPath()+"/branches", q)
if err != nil {
return err
}

343
skills/README.md
View File

@ -1,343 +0,0 @@
# GitLink CLI Skills 指南
[![GitLink](https://img.shields.io/badge/GitLink-wbtiger%2Fgitlink--cli-green)](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-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-pm/ # 项目管理
│ └── SKILL.md # PM 操作指南
└── 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 +create`, `repo +info`, `repo +fork` |
| **gitlink-issue** | Issue 管理 | `issue +create`, `issue +list`, `issue +view`, `issue +close` |
| **gitlink-pr** | Pull Request | `pr +list`, `pr +create`, `pr +view`, `pr +merge`, `pr +review` |
| **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/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
```
详见: [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-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 代理自动化你的工作流
祝你使用愉快！🚀

9
skills/gitlink-issue/SKILL.md
View File

@ -62,11 +62,4 @@ gitlink-cli api POST /issues/:issue_id/claims
| `--body` | `description` | Issue 描述 |
| `--assignee` | `assigned_to_id` | 指派人 ID |
| `--milestone` | `fixed_version_id` | 里程碑 ID |
| `--state` | `status_id` | 状态（5=关闭） |
## API 注意事项
- **创建 Issue 时必须包含 `done_ratio: 0`**，否则数据库报错（CLI 已自动处理）
- **更新/关闭 Issue 时必须包含 `subject` 字段**，即使只修改状态（CLI 已自动处理）
- 使用 Raw API 操作 Issue 时需手动添加这些字段
- Issue 评论路径为 `/issues/:id/journals`（不带 owner/repo 前缀）
| `--state` | `status_id` | 状态 |

80
skills/gitlink-issue/examples/issue-workflow.md
View File

@ -1,80 +0,0 @@
# Issue 全流程工作流
## 场景：创建、更新、评论、关闭 Issue
### 步骤 1：创建 Issue
```bash
gitlink-cli issue +create \
--owner wbtiger \
--repo gitlink-cli \
-t "Bug: 登录失败" \
-b "复现步骤：
1. 打开登录页面
2. 输入错误密码
3. 点击登录
预期：显示错误提示
实际：页面崩溃"
```
**返回**:
```json
{
"ok": true,
"data": {
"id": 140801,
"message": "创建成功",
"status": 0
}
}
```
### 步骤 2：查看 Issue 详情
```bash
gitlink-cli issue +view --owner wbtiger --repo gitlink-cli -i 140801
```
### 步骤 3：添加评论
```bash
gitlink-cli issue +comment \
--owner wbtiger \
--repo gitlink-cli \
-i 140801 \
-b "已在本地复现，正在调查"
```
### 步骤 4：更新 Issue
```bash
gitlink-cli issue +update \
--owner wbtiger \
--repo gitlink-cli \
-i 140801 \
-t "Bug: 登录失败 - 已定位到 auth.js 第 42 行"
```
### 步骤 5：关闭 Issue
```bash
gitlink-cli issue +close --owner wbtiger --repo gitlink-cli -i 140801
```
## 测试验证
✅ 已验证的工作流（2026-04-01）:
- issue +create: 成功（需要 done_ratio=0）
- issue +view: 成功
- issue +update: 成功
- issue +comment: 成功
- issue +close: 成功（需要 subject 字段）
## 常见错误
| 错误 | 原因 | 解决 |
|------|------|------|
| "标题不能为空" | 关闭 Issue 时缺少 subject | CLI 已自动处理 |
| "Mysql2::Error: done_ratio cannot be null" | 创建 Issue 时缺少 done_ratio | CLI 已自动处理 |
| 401 错误 | Token 过期 | 运行 `gitlink-cli auth login` |

3
skills/gitlink-pr/SKILL.md
View File

@ -59,6 +59,3 @@ gitlink-cli api GET /:owner/:repo/pulls/get_branches
- GitLink 的默认分支通常是 `master`（非 `main`），创建 PR 时注意 `--base` 参数
- 合并 PR 前建议先用 `pr +view` 确认状态
- **PR 创建要求源分支与目标分支有实际代码差异**，否则返回"分支内容相同，无需创建合并请求"
- PR 查看需要使用 `pull_request_id`（从 `pr +list` 返回），而非列表中的 `id` 字段
- `pr +diff` 实际调用 `/pulls/:id/files` 端点，返回变更文件列表（非 unified diff）

17
skills/gitlink-release/SKILL.md
View File

@ -26,18 +26,9 @@ gitlink-cli release +list --owner Gitlink --repo forgeplus
# 创建发布
gitlink-cli release +create --tag v1.0.0 --name "v1.0.0 正式版" --body "## 更新内容\n- 新增搜索功能\n- 修复登录 Bug" --target master
# 查看发布详情（⚠️ 必须使用 version_id，不能用 tag_name）
# 先用 release +list 获取 version_id
gitlink-cli release +list --owner myuser --repo myrepo --format json
# 从返回的 releases 数组中取 version_id 字段
gitlink-cli release +view --id <version_id>
# 查看发布详情
gitlink-cli release +view --id 1
# 删除发布（⚠️ 当前 GitLink API 有 Bug，可能返回"版本不存在"）
gitlink-cli release +delete --id <version_id>
# 删除发布
gitlink-cli release +delete --id 1
```
## API 注意事项
- **`release +view` 必须使用 `version_id`**（从 `release +list` 返回结果中获取），使用 tag_name 会返回 HTML 页面而非 JSON
- **`release +delete` 当前不可用**，GitLink API 始终返回"版本不存在"（平台 Bug）
- Release 列表中的 `id` 字段可能为 null，应使用 `version_id` 字段

91
skills/gitlink-release/examples/release-workflow.md
View File

@ -1,91 +0,0 @@
# Release 管理工作流
## 场景：创建、查看、删除发布
### 步骤 1：创建 Release
```bash
gitlink-cli release +create \
--owner wbtiger \
--repo gitlink-cli \
-t "v0.1.0-cli-test" \
-n "CLI Test Release v0.1.0" \
-b "## 更新内容
- 修复 Issue 创建 done_ratio 字段
- 修复 Issue 关闭 subject 字段
- 优化 branch +list 端点"
```
**返回**:
```json
{
"ok": true,
"data": {
"message": "发布成功",
"status": 0
}
}
```
### 步骤 2：列出 Release
```bash
gitlink-cli release +list --owner wbtiger --repo gitlink-cli
```
**返回**:
```json
{
"ok": true,
"data": {
"releases": [
{
"name": "CLI Test Release v0.1.0",
"tag_name": "v0.1.0-cli-test",
"version_id": 1752,
"body": "## 更新内容...",
"created_at": "2026-04-01 21:32"
}
]
}
}
```
### 步骤 3：查看 Release 详情
```bash
# ⚠️ 必须使用 version_id，不能用 tag_name
gitlink-cli release +view --owner wbtiger --repo gitlink-cli -i 1752
```
### 步骤 4：删除 Release
```bash
# ⚠️ 当前 GitLink API 有 Bug，可能返回"版本不存在"
gitlink-cli release +delete --owner wbtiger --repo gitlink-cli -i 1752
```
## 测试验证
✅ 已验证的工作流（2026-04-01）:
- release +create: 成功
- release +list: 成功
- release +view: 成功（使用 version_id）
❌ 已知问题:
- release +delete: API 返回"版本不存在"（GitLink Bug）
- release +view 用 tag_name: 返回 HTML 页面而非 JSON
## 常见错误
| 错误 | 原因 | 解决 |
|------|------|------|
| 返回 HTML 页面 | release +view 用了 tag_name | 使用 version_id 代替 |
| "版本不存在" | release +delete 调用 GitLink API Bug | 暂无解决方案 |
| 404 错误 | release 不存在 | 检查 version_id 是否正确 |
## 最佳实践
1. 总是先用 `release +list` 获取 version_id
2. 使用 version_id 而非 tag_name 进行查看操作
3. Release 删除功能暂不可用，建议通过 Web UI 删除

91
skills/gitlink-repo/examples/repo-workflow.md
View File

@ -1,91 +0,0 @@
# 仓库管理工作流
## 场景：完整的仓库管理流程
### 步骤 1：创建仓库
```bash
gitlink-cli repo +create \
--name my-project \
--description "我的项目" \
--private false
```
### 步骤 2：创建分支
```bash
gitlink-cli branch +create \
--owner wbtiger \
--repo my-project \
-n develop
```
### 步骤 3：列出分支
```bash
gitlink-cli branch +list --owner wbtiger --repo my-project
```
**返回**:
```json
{
"ok": true,
"data": {
"branches": [
{
"name": "master",
"commit": { ... }
},
{
"name": "develop",
"commit": { ... }
}
]
}
}
```
### 步骤 4：保护分支
```bash
gitlink-cli branch +protect \
--owner wbtiger \
--repo my-project \
-n master
```
### 步骤 5：取消保护
```bash
gitlink-cli branch +unprotect \
--owner wbtiger \
--repo my-project \
-n master
```
### 步骤 6：删除仓库
```bash
gitlink-cli repo +delete --owner wbtiger --repo my-project
```
## 测试验证
✅ 已验证的工作流（2026-04-01）:
- repo +create: 成功
- branch +create: 成功
- branch +list: 成功（使用 /v1/ 端点）
- branch +protect: 成功
- branch +unprotect: 成功
- repo +delete: 成功
❌ 已知问题:
- branch +delete: API 返回"分支不存在"（GitLink Bug）
## 常见错误
| 错误 | 原因 | 解决 |
|------|------|------|
| "分支不存在" | branch +delete 调用 GitLink API Bug | 暂无解决方案 |
| 403 权限不足 | 无仓库管理权限 | 确认账户权限 |
| 404 仓库不存在 | owner/repo 错误 | 检查参数 |

75
skills/gitlink-shared/REFERENCE.md
View File

@ -1,75 +0,0 @@
# GitLink API 参考
## 认证端点
| 端点 | 方法 | 说明 |
|------|------|------|
| `/accounts/login` | POST | 用户名密码登录 |
| `/users/me` | GET | 获取当前用户信息 |
## 全局参数
| 参数 | 位置 | 说明 |
|------|------|------|
| `access_token` | Query | OAuth2 Token（自动注入） |
| `page` | Query | 分页页码（默认 1） |
| `limit` | Query | 每页条数（默认 20） |
## 响应格式
**成功响应**:
```json
{
"ok": true,
"data": { ... },
"meta": { "page": 1, "limit": 20, "total_count": 100 }
}
```
**错误响应**:
```json
{
"ok": false,
"error": {
"code": 401,
"message": "无效token",
"suggestion": "请先运行 gitlink-cli auth login 登录"
}
}
```
## 常见错误码
| 错误码 | 含义 | 解决方案 |
|--------|------|----------|
| 401 | 未认证 | 运行 `gitlink-cli auth login` |
| 403 | 权限不足 | 确认账户权限或联系项目管理员 |
| 404 | 资源不存在 | 检查 owner/repo/id 是否正确 |
| 422 | 参数校验失败 | 检查请求参数 |
| -1 | GitLink 业务错误 | 查看 message 字段获取详情 |
## API 特殊性
### 必需字段
| 操作 | 必需字段 | 说明 |
|------|----------|------|
| Issue 创建 | `done_ratio: 0` | 数据库约束 |
| Issue 更新 | `subject` | 即使只改状态也需要 |
| Release 查看 | `version_id` | 不能用 tag_name |
### 端点前缀
| 操作 | 前缀 | 示例 |
|------|------|------|
| 分支操作 | `/v1/` | `/v1/:owner/:repo/branches` |
| Issue 评论 | 无 | `/issues/:id/journals` |
| 仓库操作 | 无 | `/:owner/:repo/info` |
### 已知 Bug
| Bug | 影响 | 状态 |
|-----|------|------|
| Branch 删除返回"不存在" | 无法删除分支 | 待 GitLink 修复 |
| Release 删除返回"不存在" | 无法删除发布 | 待 GitLink 修复 |
| Create File 返回"已存在" | 无法通过 API 创建文件 | 待 GitLink 修复 |

58
skills/gitlink-shared/SKILL.md
View File

@ -88,64 +88,6 @@ gitlink-cli auth login
| 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` 命令，需要手动指定分支映射：
```bash
# 在本地 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**：
```bash
# 在本地 main 分支工作
git checkout main
git commit -m "feat: new feature"
# Push 到 GitLink 时自动映射到 master
gitlink-cli repo +push
# 实际推送到 GitLink 的 master 分支
```
## 安全规则
- **禁止输出 Token** 到终端明文

167
skills/gitlink-shared/TROUBLESHOOTING.md
View File

@ -1,167 +0,0 @@
# 常见问题排查
## 认证问题
### Q: 遇到 401 错误
**症状**: `[-1] 无效token` 或 `[-1] 请登录后再操作`
**原因**:
- Token 过期（7 天有效期）
- Token 存储损坏
- 网络问题导致 Token 未正确注入
**解决**:
```bash
# 重新登录
gitlink-cli auth login
# 或使用新 Token
gitlink-cli auth login --token
```
---
## 权限问题
### Q: 遇到 403 错误
**症状**: `[-1] 您没有权限进行该操作`
**原因**:
- 无仓库管理权限
- 无 Issue 编辑权限
- 无分支删除权限
**解决**:
```bash
# 检查当前用户权限
gitlink-cli user +me
# 确认仓库所有者
gitlink-cli repo +info --owner xxx --repo yyy
# 联系项目管理员申请权限
```
---
## Issue 操作问题
### Q: Issue 创建失败 - "Mysql2::Error: done_ratio cannot be null"
**原因**: 使用 Raw API 创建 Issue 时缺少 `done_ratio` 字段
**解决**:
```bash
# 使用 issue +create shortcut（已自动处理）
gitlink-cli issue +create -t "标题" -b "描述"
# 或使用 Raw API 时添加 done_ratio
gitlink-cli api POST /:owner/:repo/issues --body '{
"subject": "标题",
"description": "描述",
"done_ratio": 0
}'
```
### Q: Issue 关闭失败 - "验证失败: 标题不能为空"
**原因**: 更新 Issue 时缺少 `subject` 字段
**解决**:
```bash
# 使用 issue +close shortcut（已自动处理）
gitlink-cli issue +close -i 123
# 或使用 Raw API 时添加 subject
gitlink-cli api PUT /:owner/:repo/issues/123 --body '{
"subject": "当前标题",
"status_id": 5
}'
```
---
## Release 操作问题
### Q: Release 查看返回 HTML 页面
**原因**: 使用了 tag_name 而非 version_id
**解决**:
```bash
# 先获取 version_id
gitlink-cli release +list --format json
# 从返回结果中找到 version_id 字段
# 使用 version_id 查看
gitlink-cli release +view -i <version_id>
```
---
## 分支操作问题
### Q: Branch 删除失败 - "分支不存在"
**原因**: GitLink API Bug - DELETE 端点实现有问题
**解决**:
```bash
# 暂无 CLI 解决方案
# 建议通过 Web UI 删除分支
# 或联系 GitLink 团队修复 API
```
---
## 网络问题
### Q: 请求超时或连接失败
**症状**: `request failed: context deadline exceeded`
**原因**:
- 网络连接不稳定
- GitLink 服务器响应慢
- 防火墙阻止
**解决**:
```bash
# 检查网络连接
ping www.gitlink.org.cn
# 启用调试模式查看详细信息
gitlink-cli user +me --debug
# 重试操作
```
---
## 调试技巧
### 启用调试输出
```bash
gitlink-cli <command> --debug
```
### 查看完整 API 请求
```bash
gitlink-cli api GET /users/me --debug
```
### 检查认证状态
```bash
gitlink-cli auth status
```
### 验证 API 连接
```bash
gitlink-cli user +me
```

57
skills/gitlink-shared/examples/auth-workflow.md
View File

@ -1,57 +0,0 @@
# 认证工作流
## 场景：首次使用 gitlink-cli
### 步骤 1：登录
```bash
gitlink-cli auth login
# 交互式输入用户名和密码
# Token 自动存储到 OS Keychain
```
### 步骤 2：验证登录
```bash
gitlink-cli auth status
# 输出：✓ Logged in as wbtiger
```
### 步骤 3：测试 API 访问
```bash
gitlink-cli user +me
# 返回当前用户信息
```
## 场景：Token 过期重新登录
```bash
# 遇到 401 错误时
gitlink-cli auth login
# 或使用已有 Token
gitlink-cli auth login --token
# 粘贴 Token 后回车
```
## 场景：切换账户
```bash
# 登出当前账户
gitlink-cli auth logout
# 登录新账户
gitlink-cli auth login
```
## 常见问题
**Q: Token 存储在哪里？**
A: OS Keychain（macOS）/ Secret Service（Linux）/ Credential Manager（Windows）
**Q: Token 有效期多长？**
A: 7 天，过期需重新登录
**Q: 如何使用已有 Token？**
A: 运行 `gitlink-cli auth login --token`，粘贴 Token 后回车