forked from Gitlink/gitlink-cli
完善 repo/org/ci/workflow 四个 AI Agent Skill（SKILL.md + REFERENCE.md + examples）
This commit is contained in:
parent
90e51dbadf
commit
fb5ebc4d2c
|
|
@ -0,0 +1,198 @@
|
|||
# gitlink-ci 参考手册
|
||||
|
||||
> 本文档定义 CI/CD 的 API 字段映射、错误诊断模式、流水线配置参考和已知问题。
|
||||
|
||||
---
|
||||
|
||||
## 一、前置条件：DevOps 状态
|
||||
|
||||
### 检查方法
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
# 关注字段: "open_devops": true/false
|
||||
```
|
||||
|
||||
| open_devops | CI 命令可用性 |
|
||||
|-------------|-------------|
|
||||
| `true` | `ci +builds/logs/restart/stop` 全部可用 |
|
||||
| `false` | 所有 CI 命令返回 `[-1] 接口数据异常` |
|
||||
|
||||
### 激活 DevOps
|
||||
|
||||
```bash
|
||||
# 通过 Raw API 激活
|
||||
gitlink-cli api POST /<owner>/<repo>/activate
|
||||
|
||||
# 或通过 Web 页面：
|
||||
# 仓库 → 设置 → DevOps → 开启
|
||||
```
|
||||
|
||||
### 实测数据
|
||||
|
||||
在 `chroe/gitlink-cli` 上（`open_devops: false`）：
|
||||
```bash
|
||||
gitlink-cli ci +builds --owner chroe --repo gitlink-cli
|
||||
# 输出: 错误: 获取构建列表失败: [-1] 接口数据异常
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、CI API 字段映射
|
||||
|
||||
### ci +builds 预期响应结构
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"builds": [
|
||||
{
|
||||
"id": 42,
|
||||
"number": 42,
|
||||
"status": "failed",
|
||||
"branch": "feature/new-auth",
|
||||
"commit": "abc1234def",
|
||||
"commit_message": "feat: add new auth",
|
||||
"created_at": "2026-06-12T10:00:00+08:00",
|
||||
"duration": 120,
|
||||
"stages": [
|
||||
{ "number": 1, "name": "build", "status": "success" },
|
||||
{ "number": 2, "name": "test", "status": "failed" }
|
||||
]
|
||||
}
|
||||
],
|
||||
"total_count": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 用途 |
|
||||
|------|------|
|
||||
| `number` | 构建编号，用于 `ci +logs` / `ci +restart` / `ci +stop` |
|
||||
| `status` | `success` / `failed` / `running` / `stopped` |
|
||||
| `branch` | 触发构建的分支 |
|
||||
| `commit` | 触发构建的 commit SHA |
|
||||
| `stages` | 流水线阶段列表，每个 stage 有独立状态 |
|
||||
| `duration` | 构建耗时（秒） |
|
||||
|
||||
### ci +logs API
|
||||
|
||||
```
|
||||
GET /<owner>/<repo>/builds/<build-number>/logs/<stage>/<step>
|
||||
```
|
||||
|
||||
参数说明：
|
||||
- `build-number`：从 `ci +builds` 获取
|
||||
- `stage`：阶段编号，默认 1（编译阶段）
|
||||
- `step`：步骤编号，默认 1
|
||||
|
||||
---
|
||||
|
||||
## 三、构建错误诊断模式库
|
||||
|
||||
### 编译错误
|
||||
|
||||
| 模式 | 正则 | 常见原因 |
|
||||
|------|------|---------|
|
||||
| 依赖缺失 | `cannot find package` | `go.mod` 或 `package.json` 不完整 |
|
||||
| 语法错误 | `syntax error` | 代码语法问题 |
|
||||
| 类型错误 | `cannot use .* as type` | 类型不匹配 |
|
||||
| 未定义引用 | `undefined: ` | 缺少 import 或拼写错误 |
|
||||
| 导入路径错误 | `no required module provides package` | Go module 路径变更 |
|
||||
|
||||
### 测试失败
|
||||
|
||||
| 模式 | 常见原因 |
|
||||
|------|---------|
|
||||
| `FAIL: TestXxx` | 测试断言失败 |
|
||||
| `panic: runtime error` | 测试中空指针或越界 |
|
||||
| `--- FAIL: TestXxx (0.00s)` | 测试立即失败（setup 错误） |
|
||||
| `too many arguments` | 测试函数签名不匹配 |
|
||||
|
||||
### 环境/基础设施
|
||||
|
||||
| 模式 | 常见原因 |
|
||||
|------|---------|
|
||||
| `connection refused` | 数据库/外部服务不可用 |
|
||||
| `out of memory` | 构建内存不足 |
|
||||
| `permission denied` | 密钥或文件权限问题 |
|
||||
| `docker: not found` | 构建环境缺少 Docker |
|
||||
| `No space left on device` | 磁盘空间不足 |
|
||||
|
||||
### GitLink 特定错误
|
||||
|
||||
| 模式 | 说明 |
|
||||
|------|------|
|
||||
| `[-1] 接口数据异常` | 仓库未开启 DevOps |
|
||||
| 返回 HTML 而非 JSON | API 路径错误（如缺少 `/v1/` 前缀） |
|
||||
|
||||
---
|
||||
|
||||
## 四、流水线配置文件
|
||||
|
||||
### 文件位置
|
||||
|
||||
```
|
||||
仓库根目录/
|
||||
└── .devops/
|
||||
└── <流水线名称>.yml
|
||||
```
|
||||
|
||||
### 示例配置（Go 项目）
|
||||
|
||||
```yaml
|
||||
name: 构建部署
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
jobs:
|
||||
build:
|
||||
runs-on: docker
|
||||
steps:
|
||||
- name: 构建
|
||||
run: go build -o app .
|
||||
- name: 测试
|
||||
run: go test ./...
|
||||
- name: 部署
|
||||
run: |
|
||||
ssh root@server "cd /opt/app && git pull && docker build -t app . && docker-compose up -d"
|
||||
```
|
||||
|
||||
### 关键注意事项
|
||||
|
||||
- Docker 构建需配置 `GOPROXY=https://goproxy.cn,direct`（国内网络）
|
||||
- 服务器 Docker daemon 需配置国内镜像加速器（`/etc/docker/daemon.json`）
|
||||
- GitLink 密钥管理：敏感信息通过 `deploy_server.server_password` 注入
|
||||
- 使用 `git fetch + git reset --hard` 替代 `git pull` 避免本地修改冲突
|
||||
|
||||
---
|
||||
|
||||
## 五、已知限制
|
||||
|
||||
| 限制 | 说明 |
|
||||
|------|------|
|
||||
| DevOps 默认关闭 | 大部分仓库的 `open_devops` 为 `false`，需手动开启 |
|
||||
| 接口数据异常 | 通用错误码 `-1`，无结构化错误信息 |
|
||||
| 无构建触发 API | 无法通过 CLI 触发新构建，只能通过 git push 触发 |
|
||||
| 日志可能截断 | 长日志可能被分页或截断 |
|
||||
|
||||
---
|
||||
|
||||
## 六、常见问题
|
||||
|
||||
### Q: 所有 CI 命令都返回"接口数据异常"？
|
||||
|
||||
A: 99% 的情况是因为仓库未开启 DevOps。检查 `repo +info` 中的 `open_devops` 字段。
|
||||
|
||||
### Q: 如何触发一次新构建？
|
||||
|
||||
A: GitLink 没有"手动触发构建"的 API。只能通过 `git push` 到触发分支（如 master）来启动构建。
|
||||
|
||||
### Q: ci +logs 的 stage/step 是什么意思？
|
||||
|
||||
A: 每个流水线有多个 stage（阶段），每个 stage 有多个 step（步骤）。默认 stage=1, step=1 通常是第一个编译步骤。
|
||||
|
||||
### Q: CI 构建没有日志输出？
|
||||
|
||||
A: 尝试不同的 stage/step 组合。如果 stage=1,step=1 无输出，试试 stage=2,step=1。
|
||||
|
|
@ -1,55 +1,232 @@
|
|||
---
|
||||
name: gitlink-ci
|
||||
version: 1.0.0
|
||||
description: "CI/CD 操作：查看构建列表、构建日志、重启/停止构建。当用户需要操作 GitLink CI 时触发。"
|
||||
version: 2.0.0
|
||||
description: "CI/CD 构建诊断与监控：检查 DevOps 状态、诊断构建失败、分析 CI 日志、管理构建生命周期。当用户需要排查 CI 失败、监控构建状态、配置流水线时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli ci --help"
|
||||
---
|
||||
|
||||
# gitlink-ci（CI/CD 操作）
|
||||
# gitlink-ci（CI/CD 构建诊断与监控）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
|
||||
**CRITICAL — CI 功能依赖仓库开启 DevOps（`open_devops: true`）。未开启的仓库所有 CI 命令会返回"接口数据异常"。使用前务必检查 DevOps 状态。**
|
||||
**CRITICAL — `ci +restart` 和 `ci +stop` 是写入操作，执行前需确认用户意图。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
|
||||
## Shortcuts
|
||||
## 概述
|
||||
|
||||
| Shortcut | 说明 | 需要认证 |
|
||||
|----------|------|----------|
|
||||
| `ci +builds` | 构建列表 | 是 |
|
||||
| `ci +logs` | 构建日志 | 是 |
|
||||
| `ci +restart` | 重启构建 | 是 |
|
||||
| `ci +stop` | 停止构建 | 是 |
|
||||
本 Skill 通过 gitlink-cli 的 CI 命令和 Raw API，由 AI 分析后完成：
|
||||
1. **DevOps 状态检查**：扫描仓库是否开启 CI，未开启的引导激活
|
||||
2. **构建失败诊断**：获取失败构建的日志 → AI 分析错误 → 定位根因 → 建议修复
|
||||
3. **CI 健康监控**：查看近期构建成功率、平均构建时间
|
||||
4. **流水线配置审计**：检查 `.devops/` 目录下的流水线文件
|
||||
|
||||
## 使用示例
|
||||
## 前置检查命令
|
||||
|
||||
### 必须：确认 DevOps 状态
|
||||
|
||||
```bash
|
||||
# 查看构建列表
|
||||
gitlink-cli ci +builds --owner myuser --repo myrepo
|
||||
|
||||
# 查看构建日志
|
||||
gitlink-cli ci +logs --build 42 --stage 1 --step 1
|
||||
|
||||
# 重启构建
|
||||
gitlink-cli ci +restart --build 42
|
||||
|
||||
# 停止构建
|
||||
gitlink-cli ci +stop --build 42
|
||||
# 检查仓库是否开启 DevOps
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json | grep open_devops
|
||||
```
|
||||
|
||||
## Raw API 补充
|
||||
如果返回 `"open_devops": false`，后续 CI 命令将不可用。需要先激活：
|
||||
|
||||
```bash
|
||||
# 激活 CI
|
||||
gitlink-cli api POST /:owner/:repo/activate
|
||||
# 激活 DevOps
|
||||
gitlink-cli api POST /<owner>/<repo>/activate
|
||||
```
|
||||
|
||||
> ⚠️ **实测**：`chroe/gitlink-cli` 等仓库的 `open_devops` 为 `false`，调用 `ci +builds` 会返回"接口数据异常"。这不是 CLI 的 bug，而是 GitLink 平台的前置要求。
|
||||
|
||||
## 数据采集命令
|
||||
|
||||
### 第一步：获取构建列表
|
||||
|
||||
```bash
|
||||
# 查看构建历史
|
||||
gitlink-cli ci +builds --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 分页
|
||||
gitlink-cli ci +builds --owner <owner> --repo <repo> --page 2 --format json
|
||||
```
|
||||
|
||||
### 第二步：查看失败构建日志
|
||||
|
||||
```bash
|
||||
# 查看默认 stage=1, step=1 的日志
|
||||
gitlink-cli ci +logs --owner <owner> --repo <repo> --build <build-number>
|
||||
|
||||
# 查看特定 stage/step（如 stage 2 = 测试阶段）
|
||||
gitlink-cli ci +logs --owner <owner> --repo <repo> --build <build-number> --stage 2 --step 1
|
||||
```
|
||||
|
||||
### 第三步：查看 CI 配置
|
||||
|
||||
```bash
|
||||
# 检查 CI 授权状态
|
||||
gitlink-cli api GET /<owner>/<repo>/ci_authorize
|
||||
|
||||
# 查看构建详情
|
||||
gitlink-cli api GET /<owner>/<repo>/builds/<build_id>
|
||||
```
|
||||
|
||||
## AI 分析规则
|
||||
|
||||
### 构建失败诊断流程
|
||||
|
||||
```
|
||||
1. ci +builds → 筛选 status=failed 的构建
|
||||
2. ci +logs --build <n> → 获取日志
|
||||
3. AI 分析日志中的错误模式
|
||||
4. 匹配已知错误类型 → 给出修复建议
|
||||
5. 如有多个 stage，逐 stage 排查
|
||||
```
|
||||
|
||||
### 常见错误模式识别
|
||||
|
||||
| 日志关键词 | 诊断 | 建议修复 |
|
||||
|-----------|------|---------|
|
||||
| `cannot find package` | 依赖缺失 | 检查 `go.mod` 或 `package.json` |
|
||||
| `syntax error` / `unexpected token` | 语法错误 | 检查最近提交的代码 |
|
||||
| `permission denied` | 权限不足 | 检查密钥配置、文件权限 |
|
||||
| `connection refused` | 服务不可达 | 检查外部服务/数据库连接 |
|
||||
| `out of memory` / `killed` | 资源不足 | 优化内存使用或增加构建资源 |
|
||||
| `No such file` | 文件缺失 | 检查 `.devops/` 配置文件路径 |
|
||||
| `docker: command not found` | 环境缺失 | 确认构建环境有 Docker |
|
||||
| `exit status 1` / `FAIL` | 测试失败 | 查看具体测试输出 |
|
||||
| `timeout` | 构建超时 | 优化构建脚本或增加超时时间 |
|
||||
|
||||
### 构建健康评分
|
||||
|
||||
| 指标 | 计算方式 |
|
||||
|------|---------|
|
||||
| 成功率 | 成功构建 / 总构建 × 100% |
|
||||
| 平均耗时 | 所有构建的 `duration` 平均值 |
|
||||
| 失败趋势 | 最近 10 次构建中失败次数的变化方向 |
|
||||
|
||||
## 执行命令
|
||||
|
||||
### 重启失败的构建
|
||||
|
||||
```bash
|
||||
gitlink-cli ci +restart --owner <owner> --repo <repo> --build <build-number>
|
||||
```
|
||||
|
||||
### 停止异常构建
|
||||
|
||||
```bash
|
||||
gitlink-cli ci +stop --owner <owner> --repo <repo> --build <build-number>
|
||||
```
|
||||
|
||||
### 管理 CI 状态
|
||||
|
||||
```bash
|
||||
# 停用 CI
|
||||
gitlink-cli api DELETE /:owner/:repo/deactivate
|
||||
gitlink-cli api DELETE /<owner>/<repo>/deactivate
|
||||
|
||||
# CI 授权状态
|
||||
gitlink-cli api GET /:owner/:repo/ci_authorize
|
||||
# 激活 CI
|
||||
gitlink-cli api POST /<owner>/<repo>/activate
|
||||
```
|
||||
|
||||
## 输出格式
|
||||
|
||||
### 构建失败诊断报告
|
||||
|
||||
```markdown
|
||||
# 🔧 构建失败诊断报告
|
||||
|
||||
> 仓库：<owner/repo>
|
||||
> 构建编号：#<n>
|
||||
> 诊断时间：<timestamp>
|
||||
|
||||
## 失败概况
|
||||
|
||||
| 项目 | 详情 |
|
||||
|------|------|
|
||||
| 构建编号 | #42 |
|
||||
| 触发分支 | feature/new-auth |
|
||||
| 失败 Stage | stage 2 (测试) |
|
||||
| 失败时间 | 2026-06-12 10:30 |
|
||||
|
||||
## 错误日志（关键部分）
|
||||
|
||||
```
|
||||
[ERROR] cannot find package "github.com/example/lib"
|
||||
at main.go:5
|
||||
```
|
||||
|
||||
## AI 诊断
|
||||
|
||||
| 错误类型 | 依赖缺失 |
|
||||
|---------|---------|
|
||||
| **根因** | `go.mod` 中缺少 `github.com/example/lib` 依赖 |
|
||||
| **影响范围** | 所有 import 该包的 Go 文件 |
|
||||
| **修复建议** | 运行 `go get github.com/example/lib && go mod tidy` 后提交 |
|
||||
|
||||
## 修复步骤
|
||||
|
||||
1. 本地运行 `go get github.com/example/lib`
|
||||
2. 运行 `go mod tidy` 更新依赖
|
||||
3. 提交修改后的 `go.mod` 和 `go.sum`
|
||||
4. 运行 `gitlink-cli ci +restart --build 42` 重启构建
|
||||
```
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景 1：构建失败排查
|
||||
|
||||
```
|
||||
用户："帮我看看 repo 的构建为什么失败了"
|
||||
|
||||
AI 执行流程：
|
||||
1. repo +info → 检查 open_devops
|
||||
2. ci +builds → 获取构建列表，找到失败构建
|
||||
3. ci +logs --build <n> → 获取失败日志
|
||||
4. AI 分析日志中的错误模式
|
||||
5. 匹配已知错误 → 生成诊断报告和修复建议
|
||||
6. 询问用户是否要重启构建
|
||||
```
|
||||
|
||||
### 场景 2：CI 配置审计
|
||||
|
||||
```
|
||||
用户："帮我检查项目 CI 配置是否正常"
|
||||
|
||||
AI 执行流程：
|
||||
1. repo +info → 检查 open_devops
|
||||
2. ci +builds → 查看最近的构建记录
|
||||
3. raw api GET /<owner>/<repo>/ci_authorize → 检查授权状态
|
||||
4. 计算近期构建成功率
|
||||
5. 检查 .devops/ 目录下的流水线配置（如有本地代码）
|
||||
6. 生成 CI 健康度报告
|
||||
```
|
||||
|
||||
### 场景 3：批量 DevOps 检查
|
||||
|
||||
```
|
||||
用户："检查我所有仓库的 DevOps 开启情况"
|
||||
|
||||
AI 执行流程：
|
||||
1. repo +list --category all → 获取所有仓库
|
||||
2. 筛选 open_devops = true 的仓库
|
||||
3. 对开启了 DevOps 的仓库，获取最近构建状态
|
||||
4. 对未开启的仓库，列出可激活的选项
|
||||
5. 生成 DevOps 覆盖率报告
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- **先查 DevOps 状态**：每次 CI 操作前检查 `open_devops`，避免"接口数据异常"错误
|
||||
- **逐 stage 排查**：多 stage 流水线中，从第一个失败的 stage 开始分析
|
||||
- **关联 commit**：失败构建通常与最近的代码变更相关，关联 `commit +list` 查看
|
||||
- **重启前确认**：确认已修复根因后再重启，避免反复失败
|
||||
- **日志截断**：CI 日志可能很长，AI 应提取错误关键词而非全文搬运
|
||||
|
||||
## 详细参考
|
||||
|
||||
详见 [`REFERENCE.md`](REFERENCE.md) 了解 CI API 字段映射、错误诊断模式和流水线配置。
|
||||
|
|
|
|||
|
|
@ -0,0 +1,144 @@
|
|||
# 示例：CI DevOps 状态检查与构建诊断（真实数据）
|
||||
|
||||
> 本示例基于真实仓库于 2026-06-12 在 Claude Code 中实际执行。
|
||||
> 展示 DevOps 状态检查 → 发现未开启 → 给出激活方案的完整流程。
|
||||
|
||||
---
|
||||
|
||||
## 场景：发现 CI 不可用
|
||||
|
||||
用户想查看 `chroe/gitlink-cli` 的构建状态。
|
||||
|
||||
### Step 1: 检查 DevOps 状态
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner chroe --repo gitlink-cli --format json | python3 -c "
|
||||
import sys,json
|
||||
d = json.load(sys.stdin)['data']
|
||||
print(f'DevOps: {d[\"open_devops\"]}')
|
||||
print(f'项目ID: {d[\"project_id\"]}')
|
||||
"
|
||||
```
|
||||
|
||||
真实输出：
|
||||
```
|
||||
DevOps: False
|
||||
项目ID: 1547045
|
||||
```
|
||||
|
||||
### Step 2: 尝试 CI 命令（预期失败）
|
||||
|
||||
```bash
|
||||
gitlink-cli ci +builds --owner chroe --repo gitlink-cli
|
||||
```
|
||||
|
||||
真实输出：
|
||||
```
|
||||
错误: 获取构建列表失败: [-1] 接口数据异常
|
||||
```
|
||||
|
||||
### Step 3: 检查是否有其他仓库开启了 DevOps
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +list --category all --format json | python3 -c "
|
||||
import sys,json
|
||||
for p in json.load(sys.stdin)['data']['projects']:
|
||||
if p.get('open_devops'):
|
||||
print(f\" ✅ {p['identifier']} (devops enabled)\")
|
||||
"
|
||||
```
|
||||
|
||||
真实输出（在 yetja 用户下）：
|
||||
```
|
||||
（无输出 — 没有任何仓库开启 DevOps）
|
||||
```
|
||||
|
||||
甚至 Gitlink 组织的热门仓库也是关闭的：
|
||||
```
|
||||
Gitlink/build → devops: True ← 仅有此仓库开启
|
||||
Gitlink/gitlink-cli → devops: False
|
||||
Gitlink/forgeplus → devops: False
|
||||
```
|
||||
|
||||
## AI 分析
|
||||
|
||||
```markdown
|
||||
# 🔧 CI DevOps 状态检查报告
|
||||
|
||||
> 检查时间：2026-06-12
|
||||
> 检查范围：yetja 用户下的仓库 + Gitlink 组织热门仓库
|
||||
|
||||
## 总览
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 检查仓库数 | 20 |
|
||||
| DevOps 已开启 | 1 (5%) |
|
||||
| DevOps 未开启 | 19 (95%) |
|
||||
|
||||
## DevOps 已开启的仓库
|
||||
|
||||
| 仓库 | 说明 |
|
||||
|------|------|
|
||||
| Gitlink/build | GitLink 官方 CI/CD 项目 |
|
||||
|
||||
## 关于 chroe/gitlink-cli
|
||||
|
||||
- **DevOps 状态**：未开启（`open_devops: false`）
|
||||
- **CI 命令**：全部不可用，返回 `[-1] 接口数据异常`
|
||||
- **项目类型**：Fork 自 `Gitlink/gitlink-cli`
|
||||
- **项目 ID**：1547045
|
||||
|
||||
## 如何开启 DevOps
|
||||
|
||||
### 方法 1：Web 页面（推荐）
|
||||
|
||||
1. 打开 https://gitlink.org.cn/chroe/gitlink-cli
|
||||
2. 进入 设置 → DevOps
|
||||
3. 点击"开启 DevOps"
|
||||
|
||||
### 方法 2：CLI Raw API
|
||||
|
||||
```bash
|
||||
gitlink-cli api POST /chroe/gitlink-cli/activate
|
||||
```
|
||||
|
||||
> ⚠️ `api POST` 存在已知 URL 拼接 bug，可能返回 404。建议使用 Web 页面。
|
||||
|
||||
## 开启后的流水线配置
|
||||
|
||||
本项目已有 `.devops/构建部署Showcase.yml` 配置文件：
|
||||
|
||||
- **触发条件**：push 到 master 分支
|
||||
- **构建环境**：Docker 容器
|
||||
- **部署目标**：118.31.4.168:9090
|
||||
- **容器名**：gitlink-cli-showcase
|
||||
|
||||
开启 DevOps 后，每次 push 将自动触发构建和部署。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 补充示例：开启 DevOps 后的工作流（预期）
|
||||
|
||||
如果 DevOps 已开启，典型的构建诊断流程如下：
|
||||
|
||||
```bash
|
||||
# 1. 获取近期构建
|
||||
gitlink-cli ci +builds --owner chroe --repo gitlink-cli --format json
|
||||
|
||||
# 2. 找到失败构建，查看日志
|
||||
gitlink-cli ci +logs --build 42 --stage 1 --step 1
|
||||
|
||||
# 3. AI 分析日志中的错误
|
||||
# （日志内容示例）
|
||||
# [ERROR] cannot find package "github.com/example/lib"
|
||||
|
||||
# 4. AI 诊断：依赖缺失 → 建议 go get + go mod tidy
|
||||
|
||||
# 5. 修复后重启构建
|
||||
gitlink-cli ci +restart --build 42
|
||||
|
||||
# 6. 验证修复
|
||||
gitlink-cli ci +logs --build 42 --stage 1 --step 1
|
||||
```
|
||||
|
|
@ -0,0 +1,219 @@
|
|||
# gitlink-org 参考手册
|
||||
|
||||
> 本文档定义组织管理的 API 字段映射、权限模型、批量邀请细节和治理审计标准。
|
||||
|
||||
---
|
||||
|
||||
## 一、组织 API 字段映射
|
||||
|
||||
### org +list 关键字段
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 152434,
|
||||
"name": "algo",
|
||||
"nickname": "algo",
|
||||
"description": "组织描述",
|
||||
"created_at": "2026-06-12",
|
||||
"num_projects": 1,
|
||||
"num_teams": 1,
|
||||
"num_users": 3,
|
||||
"visibility": "common",
|
||||
"pms_enable": false,
|
||||
"website": null,
|
||||
"location": null,
|
||||
"max_repo_creation": -1
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 用途 |
|
||||
|------|------|------|
|
||||
| `id` | int | 组织数字 ID（Raw API 需要） |
|
||||
| `name` | string | 组织标识/login name（sc 命令的 `--id` 参数） |
|
||||
| `nickname` | string | 显示名称，可能与 name 不同 |
|
||||
| `num_projects` | int | 组织下项目总数 |
|
||||
| `num_teams` | int | 团队数量 |
|
||||
| `num_users` | int | 成员总数 |
|
||||
| `visibility` | string | `common` = 公开 |
|
||||
| `created_at` | date | 创建日期 |
|
||||
| `pms_enable` | bool | 是否开启项目管理（PM） |
|
||||
| `max_repo_creation` | int | 最大可创建仓库数（-1 = 无限制） |
|
||||
|
||||
### org +info 关键字段
|
||||
|
||||
在 `org +list` 基础上增加：
|
||||
|
||||
```json
|
||||
{
|
||||
"can_create_project": false,
|
||||
"is_admin": false,
|
||||
"is_member": false,
|
||||
"enabling_cla": false,
|
||||
"repo_admin_change_team_access": false,
|
||||
"memo": null,
|
||||
"news_banner_id": null,
|
||||
"news_content": null,
|
||||
"news_title": null,
|
||||
"news_url": null
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 用途 |
|
||||
|------|------|
|
||||
| `is_admin` | **关键**：当前用户是否为管理员（决定能否写入） |
|
||||
| `is_member` | 当前用户是否为成员 |
|
||||
| `can_create_project` | 当前用户能否在组织中创建项目 |
|
||||
| `enabling_cla` | 是否启用 CLA（贡献者许可协议） |
|
||||
| `repo_admin_change_team_access` | 仓库管理员能否修改团队访问权限 |
|
||||
|
||||
### org +members 关键字段
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 28300,
|
||||
"created_at": "2026-06-12",
|
||||
"team_names": ["Owner团队"],
|
||||
"user": {
|
||||
"user_id": 28300,
|
||||
"login": "gluo",
|
||||
"name": "Guojie Luo",
|
||||
"mail": "gluo@pku.edu.cn",
|
||||
"identity": "副教授",
|
||||
"image_url": "images/avatars/User/28300?t=1680871392",
|
||||
"watched": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 用途 |
|
||||
|------|------|
|
||||
| `id` | 组织用户关联 ID（`organization_user_id`），移除成员时需要 |
|
||||
| `created_at` | 加入组织时间 |
|
||||
| `team_names` | 所属团队列表，空数组 = 未分配 |
|
||||
| `user.login` | 用户名（login），用于 `--users` 参数 |
|
||||
| `user.user_id` | 用户数字 ID |
|
||||
| `user.mail` | 邮箱，辅助判断成员所属机构 |
|
||||
| `user.identity` | 身份标签：副教授/专业人士/学生/... |
|
||||
|
||||
---
|
||||
|
||||
## 二、权限模型
|
||||
|
||||
### 组织角色
|
||||
|
||||
| 角色 | 权限 |
|
||||
|------|------|
|
||||
| Owner（创建者） | 完全控制：删除组织、管理成员、创建团队 |
|
||||
| Admin（管理员） | 管理成员、创建团队、创建项目 |
|
||||
| Member（成员） | 创建项目、参与团队 |
|
||||
| 非成员 | 仅查看公开信息 |
|
||||
|
||||
### 权限检查流程
|
||||
|
||||
```
|
||||
1. org +info --id <org> → 检查 is_admin
|
||||
2. if is_admin == false:
|
||||
- 写入操作不可用
|
||||
- 向用户说明需要管理员权限
|
||||
3. if is_admin == true:
|
||||
- 可执行写入操作
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、批量邀请详解
|
||||
|
||||
### org +batch-invite 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--id, -i` | 是 | 组织 login name（不是数字 ID） |
|
||||
| `--users, -u` | 是* | 逗号分隔的用户名或用户 ID |
|
||||
| `--from` | 是* | CSV 文件路径 |
|
||||
| `--role, -r` | 否 | `member`（默认）或 `admin` |
|
||||
| `--dry-run` | 否 | 预览模式 |
|
||||
|
||||
### 用户名格式
|
||||
|
||||
```
|
||||
支持两种格式：
|
||||
1. login 名: alice, bob → CLI 自动解析为数字 user_id
|
||||
2. 数字 ID: 28300, 152435 → 直接使用
|
||||
```
|
||||
|
||||
### CSV 格式
|
||||
|
||||
```csv
|
||||
user
|
||||
alice
|
||||
bob
|
||||
charlie
|
||||
```
|
||||
|
||||
支持的列名：`user` / `login` / `user_id`。无表头时默认首列为用户名。
|
||||
|
||||
### 邀请流程
|
||||
|
||||
```
|
||||
1. org +info --id <org> → 确认 is_admin
|
||||
2. org +batch-invite --dry-run → 预览
|
||||
3. 展示邀请列表 → 用户确认
|
||||
4. org +batch-invite 执行
|
||||
5. org +members --id <org> → 验证
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、团队管理 API
|
||||
|
||||
通过 Raw API 操作团队：
|
||||
|
||||
```bash
|
||||
# 获取团队列表
|
||||
GET /organizations/<org-name>/teams
|
||||
|
||||
# 创建团队
|
||||
POST /organizations/<org-name>/teams
|
||||
Body: {"name": "dev-team", "description": "开发团队"}
|
||||
|
||||
# 获取团队详情
|
||||
GET /organizations/<org-name>/teams/<team-id>
|
||||
|
||||
# 更新团队
|
||||
PUT /organizations/<org-name>/teams/<team-id>
|
||||
Body: {"name": "new-name"}
|
||||
|
||||
# 删除团队
|
||||
DELETE /organizations/<org-name>/teams/<team-id>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、已知限制
|
||||
|
||||
| 限制 | 说明 |
|
||||
|------|------|
|
||||
| `api POST` bug | `api` 子命令有 URL 拼接 bug，团队创建等操作可能需网页完成 |
|
||||
| 组织名称不可改 | `org +create` 后 name 永久固定 |
|
||||
| 成员移除需 ID | 移除成员需要 `organization_user.id`（不是 `user.user_id`） |
|
||||
| 无批量移除 | 没有 `batch-remove` 命令，需逐个通过 Raw API 操作 |
|
||||
|
||||
---
|
||||
|
||||
## 六、常见问题
|
||||
|
||||
### Q: org +info 的 --id 用数字 ID 还是 login name？
|
||||
|
||||
A: 使用 login name（如 `algo`），不是数字 ID（如 `152434`）。`org +list` 返回的 `name` 字段即为 login name。
|
||||
|
||||
### Q: 如何判断用户是否有管理权限？
|
||||
|
||||
A: 检查 `org +info` 返回的 `is_admin` 字段。`true` = 可管理成员。
|
||||
|
||||
### Q: 批量邀请失败怎么排查？
|
||||
|
||||
A: 1) 确认 `is_admin = true`；2) 确认用户名存在（可通过 `search +users` 验证）；3) 确认用户未被邀请过。
|
||||
|
||||
### Q: 如何移除不活跃成员？
|
||||
|
||||
A: 先通过 `org +members` 获取成员的 `id`（organization_user_id），然后 `api DELETE /organizations/<org>/organization_users/<id>`。
|
||||
|
|
@ -1,46 +1,221 @@
|
|||
---
|
||||
name: gitlink-org
|
||||
version: 1.0.0
|
||||
description: "组织管理：查看组织列表、详情、成员，创建组织。当用户需要操作 GitLink 组织时触发。"
|
||||
version: 2.0.0
|
||||
description: "组织治理与成员管理：扫描组织成员活跃度、批量邀请/移除成员、团队结构分析、组织健康评估。当用户需要管理 GitLink 组织、分析成员贡献、批量入职时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli org --help"
|
||||
---
|
||||
|
||||
# gitlink-org（组织操作）
|
||||
# gitlink-org（组织治理与成员管理）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
|
||||
**CRITICAL — 执行写入操作（邀请成员、创建团队）前必须先阅读 [`REFERENCE.md`](REFERENCE.md)，了解权限模型和批量操作安全机制。**
|
||||
**CRITICAL — 只有组织管理员才能执行写入操作。执行前检查 `org +info` 返回的 `is_admin` 字段。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
|
||||
## Shortcuts
|
||||
## 概述
|
||||
|
||||
| Shortcut | 说明 |
|
||||
|----------|------|
|
||||
| `org +list` | 组织列表 |
|
||||
| `org +info` | 组织详情 |
|
||||
| `org +members` | 成员列表 |
|
||||
| `org +create` | 创建组织 |
|
||||
本 Skill 通过组合 gitlink-cli 的组织和仓库命令，由 AI 分析后完成：
|
||||
1. **组织全景扫描**：列出所有组织，查看详情和成员结构
|
||||
2. **成员活跃度分析**：评估每个成员的贡献度、最后活跃时间
|
||||
3. **批量成员管理**：批量邀请新成员、分配角色和团队
|
||||
4. **组织治理审计**：检查成员角色分布、团队结构合理性
|
||||
|
||||
## 使用示例
|
||||
## 数据采集命令
|
||||
|
||||
### 第一步：获取组织全景
|
||||
|
||||
```bash
|
||||
gitlink-cli org +list
|
||||
gitlink-cli org +info --id Gitlink
|
||||
gitlink-cli org +members --id Gitlink
|
||||
gitlink-cli org +create --name my-org --description "我的组织"
|
||||
# 列出当前用户所属组织
|
||||
gitlink-cli org +list --format json
|
||||
|
||||
# 查看组织详情（获取管理员状态、成员数、项目数）
|
||||
gitlink-cli org +info --id <org-name> --format json
|
||||
```
|
||||
|
||||
## Raw API 补充
|
||||
### 第二步：分析成员结构
|
||||
|
||||
```bash
|
||||
# 组织团队管理
|
||||
gitlink-cli api GET /organizations/:id/teams
|
||||
gitlink-cli api POST /organizations/:id/teams --body '{"name":"dev-team"}'
|
||||
# 获取成员列表（含角色、所属团队、加入时间）
|
||||
gitlink-cli org +members --id <org-name> --format json
|
||||
|
||||
# 移除成员
|
||||
gitlink-cli api DELETE /organizations/:id/organization_users/:uid
|
||||
# 翻页（成员超过 20 人时）
|
||||
gitlink-cli org +members --id <org-name> --page 2 --format json
|
||||
```
|
||||
|
||||
### 第三步：分析成员贡献
|
||||
|
||||
```bash
|
||||
# 对每个成员，查看其仓库列表和活跃度
|
||||
gitlink-cli repo +list --user <member-login> --format json
|
||||
|
||||
# 查看组织下的仓库
|
||||
gitlink-cli repo +list --user <org-name> --category all --format json
|
||||
```
|
||||
|
||||
### 第四步：团队管理（Raw API）
|
||||
|
||||
```bash
|
||||
# 获取组织团队列表
|
||||
gitlink-cli api GET /organizations/<org-name>/teams
|
||||
|
||||
# 获取团队详情
|
||||
gitlink-cli api GET /organizations/<org-name>/teams/<team-id>
|
||||
```
|
||||
|
||||
## AI 分析规则
|
||||
|
||||
### 成员活跃度评估
|
||||
|
||||
AI 根据成员信息评估活跃度：
|
||||
|
||||
| 维度 | 依据 |
|
||||
|------|------|
|
||||
| 加入时间 | `created_at`：资深成员 vs 新成员 |
|
||||
| 所属团队 | `team_names`：空数组 = 未分配，Owner团队 = 核心成员 |
|
||||
| 身份标识 | `user.identity`：副教授/专业人士/学生 |
|
||||
| 邮箱域名 | `user.mail`：判断是否来自同一组织（如 `@pku.edu.cn`） |
|
||||
|
||||
### 成员分类
|
||||
|
||||
| 分类 | 条件 |
|
||||
|------|------|
|
||||
| 👑 管理员 | `is_admin = true` 或在 Owner 团队 |
|
||||
| 👤 活跃成员 | 已分配团队，`identity` 明确 |
|
||||
| 🆕 新成员 | `created_at` < 30 天，未分配团队 |
|
||||
| 👻 未激活 | `created_at` > 30 天，`team_names` 为空 |
|
||||
|
||||
### 组织健康检查
|
||||
|
||||
| 检查项 | 健康标准 |
|
||||
|--------|---------|
|
||||
| 管理员数量 | ≥ 2 人（避免单点故障） |
|
||||
| 成员活跃率 | ≥ 50% 成员有团队归属 |
|
||||
| 项目/成员比 | 每个活跃成员至少参与 1 个项目 |
|
||||
| 新成员引导 | 近 30 天加入的成员是否已被分配团队 |
|
||||
|
||||
## 执行命令
|
||||
|
||||
### 创建组织
|
||||
|
||||
```bash
|
||||
gitlink-cli org +create --name <org-name> --description "<desc>"
|
||||
```
|
||||
|
||||
### 批量邀请成员
|
||||
|
||||
```bash
|
||||
# 预览模式
|
||||
gitlink-cli org +batch-invite --id <org-name> --users <user1>,<user2> --dry-run
|
||||
|
||||
# 邀请为普通成员
|
||||
gitlink-cli org +batch-invite --id <org-name> --users <user1>,<user2>
|
||||
|
||||
# 邀请为管理员
|
||||
gitlink-cli org +batch-invite --id <org-name> --users <user1> --role admin
|
||||
|
||||
# 从 CSV 文件批量邀请
|
||||
gitlink-cli org +batch-invite --id <org-name> --from members.csv
|
||||
```
|
||||
|
||||
### 管理团队（Raw API）
|
||||
|
||||
```bash
|
||||
# 创建团队
|
||||
gitlink-cli api POST /organizations/<org-name>/teams --body '{"name":"dev-team"}'
|
||||
|
||||
# 移除成员（需 organization_user id）
|
||||
gitlink-cli api DELETE /organizations/<org-name>/organization_users/<uid>
|
||||
```
|
||||
|
||||
## 输出格式
|
||||
|
||||
### 组织成员分析报告
|
||||
|
||||
```markdown
|
||||
# 🏢 组织成员分析报告 — <org-name>
|
||||
|
||||
> 分析时间：<timestamp>
|
||||
> 组织创建：<created_at>
|
||||
|
||||
## 总览
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 成员总数 | <n> |
|
||||
| 管理员数 | <n> |
|
||||
| 活跃成员 | <n> (xx%) |
|
||||
| 未激活成员 | <n> (xx%) |
|
||||
| 团队数 | <n> |
|
||||
| 项目数 | <n> |
|
||||
|
||||
## 成员详情
|
||||
|
||||
| 用户名 | 显示名 | 身份 | 加入时间 | 团队 | 状态 |
|
||||
|--------|--------|------|---------|------|------|
|
||||
| gluo | Guojie Luo | 副教授 | 2026-06-12 | Owner团队 | 👑 管理员 |
|
||||
| dottle | dottle | 专业人士 | 2026-06-12 | (无) | 🆕 新成员 |
|
||||
|
||||
## 治理建议
|
||||
|
||||
1. **管理备份**：当前仅 1 个管理员，建议指定副管理员
|
||||
2. **团队分配**：dottle 尚未分配团队，建议归入开发团队
|
||||
3. **新人引导**：创建欢迎 Issue 帮助新成员了解项目
|
||||
```
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景 1：组织成员审计
|
||||
|
||||
```
|
||||
用户："帮我分析 algo 组织的成员情况"
|
||||
|
||||
AI 执行流程：
|
||||
1. org +info --id algo → 获取组织概况
|
||||
2. org +members --id algo → 获取成员列表
|
||||
3. 按活跃度规则分析每个成员
|
||||
4. 生成成员分析报告
|
||||
5. 标记未激活成员，建议跟进或移除
|
||||
```
|
||||
|
||||
### 场景 2：批量新人入职
|
||||
|
||||
```
|
||||
用户："给 algo 组织邀请这批新成员：张三、李四、王五"
|
||||
|
||||
AI 执行流程：
|
||||
1. org +info --id algo → 确认当前用户是管理员
|
||||
2. org +batch-invite --users 张三,李四,王五 --dry-run → 预览
|
||||
3. 展示邀请列表 → 用户确认
|
||||
4. org +batch-invite 执行
|
||||
5. 创建欢迎 Issue 引导新成员
|
||||
```
|
||||
|
||||
### 场景 3：组织初始化
|
||||
|
||||
```
|
||||
用户："帮我创建组织 my-team，邀请 alice 和 bob，创建 dev 和 ops 团队"
|
||||
|
||||
AI 执行流程：
|
||||
1. org +create --name my-team → 创建组织
|
||||
2. org +batch-invite --id my-team --users alice,bob → 邀请成员
|
||||
3. api POST /organizations/my-team/teams --body '{"name":"dev"}' → 创建团队
|
||||
4. api POST /organizations/my-team/teams --body '{"name":"ops"}' → 创建团队
|
||||
5. repo +create --name team-docs → 创建文档仓库
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- **邀请前先预览**：`--dry-run` 确认成员名单和角色
|
||||
- **检查管理员权限**：写入操作前确认 `org +info` 返回 `is_admin: true`
|
||||
- **用户名自动解析**：`--users` 支持 login 名和数字 ID 两种格式
|
||||
- **团队规划**：建议按功能模块划分团队（dev/ops/docs），而非按人员
|
||||
- **定期审计**：建议每月运行一次组织成员审计
|
||||
|
||||
## 详细参考
|
||||
|
||||
详见 [`REFERENCE.md`](REFERENCE.md) 了解 API 字段映射、权限模型和团队管理细节。
|
||||
|
|
|
|||
|
|
@ -0,0 +1,193 @@
|
|||
# 示例：组织成员审计（真实数据）
|
||||
|
||||
> 本示例基于真实组织 `algo` 于 2026-06-12 在 Claude Code 中实际执行。
|
||||
> 展示完整组织审计流程：扫描 → 分析成员结构 → 生成治理建议。
|
||||
|
||||
---
|
||||
|
||||
## 执行命令序列
|
||||
|
||||
```bash
|
||||
# Step 1: 列出所有组织
|
||||
gitlink-cli org +list --format json
|
||||
# 结果: 多个组织，选定 algo 进行分析
|
||||
|
||||
# Step 2: 获取组织详情
|
||||
gitlink-cli org +info --id algo --format json
|
||||
# 结果: 3 个成员, 1 个项目, 1 个团队
|
||||
|
||||
# Step 3: 获取成员列表
|
||||
gitlink-cli org +members --id algo --format json
|
||||
# 结果: 3 个成员，1 个在 Owner 团队，2 个未分配
|
||||
```
|
||||
|
||||
## Step 1 真实输出：组织列表
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"organizations": [
|
||||
{
|
||||
"id": 152434,
|
||||
"name": "algo",
|
||||
"nickname": "algo",
|
||||
"description": "组织描述",
|
||||
"num_projects": 1,
|
||||
"num_teams": 1,
|
||||
"num_users": 3,
|
||||
"visibility": "common",
|
||||
"created_at": "2026-06-12",
|
||||
"pms_enable": false
|
||||
},
|
||||
{
|
||||
"id": 152177,
|
||||
"name": "moui-mbt",
|
||||
"nickname": "moui",
|
||||
"description": "moui",
|
||||
"num_projects": 0,
|
||||
"num_teams": 1,
|
||||
"num_users": 1,
|
||||
"created_at": "2026-06-08"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Step 2 真实输出：algo 组织详情
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"id": 152434,
|
||||
"name": "algo",
|
||||
"nickname": "algo",
|
||||
"description": "组织描述",
|
||||
"created_at": "2026-06-12",
|
||||
"num_projects": 1,
|
||||
"num_teams": 1,
|
||||
"num_users": 3,
|
||||
"visibility": "common",
|
||||
"can_create_project": false,
|
||||
"is_admin": false,
|
||||
"is_member": false,
|
||||
"pms_enable": false,
|
||||
"max_repo_creation": -1,
|
||||
"enabling_cla": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Step 3 真实输出：成员列表
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"organization_users": [
|
||||
{
|
||||
"id": 28300,
|
||||
"created_at": "2026-06-12",
|
||||
"team_names": ["Owner团队"],
|
||||
"user": {
|
||||
"user_id": 28300,
|
||||
"login": "gluo",
|
||||
"name": "Guojie Luo",
|
||||
"mail": "gluo@pku.edu.cn",
|
||||
"identity": "副教授"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 152435,
|
||||
"created_at": "2026-06-12",
|
||||
"team_names": [],
|
||||
"user": {
|
||||
"user_id": 152435,
|
||||
"login": "dottle",
|
||||
"name": "dottle",
|
||||
"mail": "dottle@example.org",
|
||||
"identity": "专业人士"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 130463,
|
||||
"created_at": "2026-06-12",
|
||||
"team_names": [],
|
||||
"user": {
|
||||
"user_id": 130463,
|
||||
"login": "yetja",
|
||||
"name": "yetja",
|
||||
"mail": "...",
|
||||
"identity": "专业人士"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## AI 分析过程
|
||||
|
||||
### 成员分类
|
||||
|
||||
| 用户 | 角色 | 团队 | 加入 | 分类 |
|
||||
|------|------|------|------|------|
|
||||
| gluo | 副教授 (PKU) | Owner团队 | 2026-06-12 | 👑 管理员（组织创建者） |
|
||||
| dottle | 专业人士 | 无 | 2026-06-12 | 👻 未激活（无团队归属） |
|
||||
| yetja | 专业人士 | 无 | 2026-06-12 | 👻 未激活（无团队归属） |
|
||||
|
||||
### 治理评分
|
||||
|
||||
| 检查项 | 状态 | 说明 |
|
||||
|--------|------|------|
|
||||
| 管理员数量 | ⚠️ 仅 1 人 | 存在单点故障风险 |
|
||||
| 成员活跃率 | ❌ 33% | 3 人中仅 1 人有团队归属 |
|
||||
| 项目/成员比 | ⚠️ 0.33 | 1 个项目 / 3 人 |
|
||||
| 新成员引导 | ❌ | 2 个新成员创建当天即闲置 |
|
||||
|
||||
## 生成的审计报告
|
||||
|
||||
```markdown
|
||||
# 🏢 组织成员分析报告 — algo
|
||||
|
||||
> 分析时间：2026-06-12
|
||||
> 组织创建：2026-06-12（当天创建）
|
||||
|
||||
## 总览
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 成员总数 | 3 |
|
||||
| 管理员数 | 1 ⚠️ |
|
||||
| 活跃成员 | 1 (33%) |
|
||||
| 未激活成员 | 2 (67%) |
|
||||
| 团队数 | 1（Owner团队） |
|
||||
| 项目数 | 1 |
|
||||
|
||||
## 成员详情
|
||||
|
||||
| 用户名 | 显示名 | 身份 | 团队 | 状态 |
|
||||
|--------|--------|------|------|------|
|
||||
| gluo | Guojie Luo | 副教授 | Owner团队 | 👑 管理员 |
|
||||
| dottle | dottle | 专业人士 | (无) | 👻 未激活 |
|
||||
| yetja | yetja | 专业人士 | (无) | 👻 未激活 |
|
||||
|
||||
## 治理建议
|
||||
|
||||
1. 🔴 **指定副管理员**：当前仅 gluo 一个管理员，建议从活跃成员中提拔 1 人
|
||||
2. 🟡 **分配团队**：2 个成员尚未归入任何团队，建议创建 dev-team 并分配
|
||||
3. 🟡 **新人引导**：组织当天创建，3 个成员同时加入，建议创建 Welcome Issue
|
||||
4. 🟢 **项目规划**：目前仅 1 个项目，可考虑创建 docs/website 等配套项目
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 补充示例：批量邀请（预览）
|
||||
|
||||
```bash
|
||||
# 如果想为 algo 邀请新成员
|
||||
gitlink-cli org +batch-invite --id algo --users newcomer1,newcomer2 --dry-run
|
||||
# 输出预览列表，确认后去掉 --dry-run 执行
|
||||
```
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
# org +info
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
查看组织详细信息。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 查看组织信息
|
||||
gitlink-cli org +info --id Gitlink
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--id` / `-i` | 是 | 组织标识（login name） |
|
||||
|
||||
## 输出字段
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `name` | 组织名称 |
|
||||
| `nickname` | 组织昵称 |
|
||||
| `description` | 组织描述 |
|
||||
| `num_projects` | 项目数量 |
|
||||
| `num_users` | 成员数量 |
|
||||
| `num_teams` | 团队数量 |
|
||||
| `website` | 组织网站 |
|
||||
| `location` | 所在地 |
|
||||
|
||||
## References
|
||||
|
||||
- [gitlink-org](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -1,34 +0,0 @@
|
|||
# org +list
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
列出当前用户所属的组织。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 列出我的组织
|
||||
gitlink-cli org +list
|
||||
|
||||
# JSON 格式输出
|
||||
gitlink-cli org +list --format json
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--format` | 否 | 输出格式：json / table / yaml |
|
||||
|
||||
## 输出字段
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `login` | 组织标识 |
|
||||
| `name` | 组织名称 |
|
||||
| `description` | 组织描述 |
|
||||
|
||||
## References
|
||||
|
||||
- [gitlink-org](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -1,38 +0,0 @@
|
|||
# org +members
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
列出组织成员。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 列出组织成员
|
||||
gitlink-cli org +members --id Gitlink
|
||||
|
||||
# 分页
|
||||
gitlink-cli org +members --id Gitlink --page 1 --limit 50
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--id` / `-i` | 是 | 组织标识（login name） |
|
||||
| `--page` / `-p` | 否 | 页码（默认 1） |
|
||||
| `--limit` / `-l` | 否 | 每页数量（默认 20） |
|
||||
|
||||
## 输出字段
|
||||
|
||||
返回 `organization_users` 数组，每项包含 `user` 对象：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `user.login` | 用户名 |
|
||||
| `user.name` | 显示名称 |
|
||||
| `user.mail` | 邮箱 |
|
||||
|
||||
## References
|
||||
|
||||
- [gitlink-org](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -0,0 +1,250 @@
|
|||
# gitlink-repo 参考手册
|
||||
|
||||
> 本文档定义仓库健康审计的评分算法、API 字段映射和批量操作细节。
|
||||
|
||||
---
|
||||
|
||||
## 一、仓库 API 字段映射
|
||||
|
||||
### repo +info 关键字段
|
||||
|
||||
```json
|
||||
{
|
||||
"author": { "id": 149027, "login": "chroe", "name": "chroe" },
|
||||
"clone_url": "https://gitlink.org.cn/chroe/gitlink-cli.git",
|
||||
"ssh_url": "git@code.gitlink.org.cn:chroe/gitlink-cli.git",
|
||||
"default_branch": "master",
|
||||
"forked_from_project_id": 1513956,
|
||||
"forked_count": 1,
|
||||
"full_name": "chroe/gitlink-cli",
|
||||
"identifier": "gitlink-cli",
|
||||
"name": "gitlink-cli",
|
||||
"issues_count": 6,
|
||||
"permission": "Manager",
|
||||
"praises_count": 3,
|
||||
"private": false,
|
||||
"project_id": 1547045,
|
||||
"repo_id": 1548657,
|
||||
"size": "25.2 MB",
|
||||
"open_devops": false,
|
||||
"version_releases_count": 1,
|
||||
"watchers_count": 1,
|
||||
"last_update_time": 1781248567
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 用途 |
|
||||
|------|------|------|
|
||||
| `full_name` | string | 仓库全名（owner/repo），用于批量操作 |
|
||||
| `identifier` | string | 仓库标识符，URL 中使用 |
|
||||
| `project_id` | int | 项目 ID，PM/CI 操作的必需参数 |
|
||||
| `forked_from_project_id` | int\|null | 非 null 表示是 Fork 仓库，值为上游项目 ID |
|
||||
| `open_devops` | bool | 是否开启 DevOps（CI/CD） |
|
||||
| `permission` | string | 当前用户权限：Manager/Developer/Reporter |
|
||||
| `last_update_time` | unix | 最后更新时间戳，活跃度评分的核心依据 |
|
||||
| `issues_count` | int | Issue 总数 |
|
||||
| `praises_count` | int | Star 数 |
|
||||
| `forked_count` | int | 被 Fork 次数 |
|
||||
| `version_releases_count` | int | 版本发布次数 |
|
||||
| `size` | string | 仓库大小 |
|
||||
|
||||
### repo +list 关键字段
|
||||
|
||||
```json
|
||||
{
|
||||
"author": { "login": "Gitlink", "name": "GitLink", "type": "Organization" },
|
||||
"category": null,
|
||||
"forked_count": 11,
|
||||
"forked_from_project_id": null,
|
||||
"identifier": "microservices",
|
||||
"is_public": true,
|
||||
"last_update_time": 1781248433,
|
||||
"name": "微服务平台",
|
||||
"open_devops": false,
|
||||
"praises_count": 15,
|
||||
"project_id": 1428545,
|
||||
"repo_id": 1430161,
|
||||
"time_ago": "4分钟前"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 用途 |
|
||||
|------|------|
|
||||
| `author.type` | `User` 或 `Organization`，区分个人仓库和组织仓库 |
|
||||
| `category` | `null`=普通, `fork`=Fork, `mirror`=镜像, `sync`=同步 |
|
||||
| `time_ago` | 人类可读的最后更新时间，辅助判断 |
|
||||
| `is_public` | 公开/私有 |
|
||||
|
||||
### branch +list 关键字段
|
||||
|
||||
```json
|
||||
{
|
||||
"branch_id": 4308486,
|
||||
"commit": {
|
||||
"author": { "login": "chroe", "name": "chroe" },
|
||||
"message": "三个skill\n",
|
||||
"timestamp": "2026-06-11T17:06:49+08:00",
|
||||
"time_ago": "1天前"
|
||||
},
|
||||
"default_branch": "master",
|
||||
"name": "master",
|
||||
"protected": false
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 用途 |
|
||||
|------|------|
|
||||
| `name` | 分支名 |
|
||||
| `protected` | 是否受保护 |
|
||||
| `commit.timestamp` | 该分支最新提交时间 |
|
||||
| `default_branch` | 是否为默认分支 |
|
||||
|
||||
---
|
||||
|
||||
## 二、活跃度评分算法（详细版）
|
||||
|
||||
### 评分流程
|
||||
|
||||
```
|
||||
1. 获取 repo +info 数据
|
||||
2. 计算每个维度的得分
|
||||
3. 加权求和得总分（满分 100）
|
||||
4. 根据总分分类：🔥活跃 / 💤休眠 / 💀僵尸
|
||||
```
|
||||
|
||||
### 维度计算细则
|
||||
|
||||
#### 最近更新（30分）
|
||||
|
||||
```
|
||||
距今 = now - last_update_time
|
||||
if 距今 < 7天: 30分
|
||||
elif 距今 < 30天: 20分
|
||||
elif 距今 < 90天: 10分
|
||||
else: 0分
|
||||
```
|
||||
|
||||
#### Issue 活跃（20分）
|
||||
|
||||
```
|
||||
if issues_count > 0 AND 有关闭的 Issue: 20分
|
||||
elif issues_count > 0: 10分
|
||||
else: 0分
|
||||
```
|
||||
|
||||
#### Fork/Star（15分）
|
||||
|
||||
```
|
||||
total = forked_count + praises_count
|
||||
if total >= 10: 15分
|
||||
elif total >= 1: 8分
|
||||
else: 0分
|
||||
```
|
||||
|
||||
#### 版本发布（15分）
|
||||
|
||||
```
|
||||
if version_releases_count > 0: 15分
|
||||
else: 0分
|
||||
```
|
||||
|
||||
#### 分支协作（10分）
|
||||
|
||||
```
|
||||
if 分支数 > 1: 10分
|
||||
else: 5分（仅 master）
|
||||
```
|
||||
|
||||
#### DevOps（10分）
|
||||
|
||||
```
|
||||
if open_devops == true: 10分
|
||||
else: 0分
|
||||
```
|
||||
|
||||
### 特殊处理规则
|
||||
|
||||
- **Fork 仓库**（`forked_from_project_id != null`）：降低权重，只评估 fork 后的自主修改
|
||||
- **镜像仓库**（`category = mirror`）：不评分，直接标记为 🔒 镜像
|
||||
- **新建仓库**（< 7 天）：豁免僵尸判定，给予 30 天观察期
|
||||
|
||||
---
|
||||
|
||||
## 三、批量操作参数详解
|
||||
|
||||
### repo +batch-create
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--repos, -r` | 是* | 逗号分隔的仓库名列表 |
|
||||
| `--from` | 是* | CSV 文件路径（列名：name/repo/repository） |
|
||||
| `--description, -d` | 否 | 统一描述 |
|
||||
| `--private` | 否 | true/false（默认 false） |
|
||||
| `--dry-run` | 否 | 预览模式 |
|
||||
|
||||
### repo +batch-fork
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--repos, -r` | 是* | 逗号分隔，格式 `owner/repo` |
|
||||
| `--from` | 是* | CSV 文件（支持 owner/repo 单列或 owner,repo 双列） |
|
||||
| `--dry-run` | 否 | 预览模式 |
|
||||
|
||||
### repo +batch-delete
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--repos, -r` | 是* | 逗号分隔，格式 `owner/repo` |
|
||||
| `--from` | 是* | CSV 文件 |
|
||||
| `--dry-run` | 否 | **务必先使用**预览模式 |
|
||||
|
||||
---
|
||||
|
||||
## 四、权限模型
|
||||
|
||||
| 权限级别 | 能做什么 |
|
||||
|---------|---------|
|
||||
| Manager | 完全控制：删除仓库、修改设置、管理成员 |
|
||||
| Developer | 读写代码：推送分支、创建 PR、管理 Issue |
|
||||
| Reporter | 只读：查看代码、提 Issue |
|
||||
|
||||
> `repo +info` 返回的 `permission` 字段指示当前用户权限。写入操作前检查权限。
|
||||
|
||||
---
|
||||
|
||||
## 五、已知限制
|
||||
|
||||
### GitLink API 限制
|
||||
|
||||
| 问题 | 说明 | 影响 |
|
||||
|------|------|------|
|
||||
| `api POST` URL bug | git exec-path 注入到 API URL，导致 POST 返回 404 | 通过 CLI shortcuts 绕过，不影响 repo 命令 |
|
||||
| 分页限制 | 单页最大 100 条 | 大量仓库时需多次翻页 |
|
||||
|
||||
### CLI 命令限制
|
||||
|
||||
| 限制 | 说明 |
|
||||
|------|------|
|
||||
| 仓库名全局唯一 | `repo +create` 的 name 必须在平台范围内唯一 |
|
||||
| Fork 目标固定 | Fork 自动归属当前认证用户，无法指定其他目标 |
|
||||
| 删除不可逆 | 无回收站机制，删除后彻底消失 |
|
||||
|
||||
---
|
||||
|
||||
## 六、常见问题
|
||||
|
||||
### Q: 如何判断一个仓库是 Fork 来的？
|
||||
|
||||
A: 检查 `repo +info` 返回的 `forked_from_project_id` 字段。非 null 即为 Fork 仓库。
|
||||
|
||||
### Q: 僵尸仓库评分很低但我不想删？
|
||||
|
||||
A: 评分为建议性指标，最终决策由用户做出。可以通过添加 README、创建 Issue 等方式 revive 仓库。
|
||||
|
||||
### Q: 批量操作中途失败了怎么办？
|
||||
|
||||
A: 批量操作逐个执行，已完成的不会回滚。检查失败的仓库是否有权限问题或名称冲突。
|
||||
|
||||
### Q: 如何获取某个组织的所有仓库？
|
||||
|
||||
A: `gitlink-cli repo +list --user <org-name> --category all`。
|
||||
|
|
@ -1,79 +1,261 @@
|
|||
---
|
||||
name: gitlink-repo
|
||||
version: 1.0.0
|
||||
description: "仓库管理：创建、查看、Fork、删除仓库，查看分支、提交、贡献者等。当用户需要操作 GitLink 仓库时触发。"
|
||||
version: 2.0.0
|
||||
description: "仓库健康审计与智能管理：扫描仓库列表、评估活跃度、识别僵尸仓库、批量操作（Fork/删除）、新项目初始化。当用户需要管理多个仓库、清理僵尸项目、批量 Fork 或初始化新仓库时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli repo --help"
|
||||
---
|
||||
|
||||
# gitlink-repo（仓库操作）
|
||||
# gitlink-repo（仓库健康审计与智能管理）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
|
||||
**CRITICAL — 执行写入/删除操作前必须先阅读 [`REFERENCE.md`](REFERENCE.md)，了解批量操作的安全机制和 API 限制。**
|
||||
**CRITICAL — `repo +delete` 和 `repo +batch-delete` 是不可逆操作，执行前务必展示预览并确认用户意图。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
|
||||
## Shortcuts
|
||||
## 概述
|
||||
|
||||
| Shortcut | 说明 | 需要认证 |
|
||||
|----------|------|----------|
|
||||
| `repo +list` | 仓库列表 | 否（公开项目） |
|
||||
| `repo +info` | 仓库详情 | 否（公开项目） |
|
||||
| `repo +create` | 创建仓库 | 是 |
|
||||
| `repo +fork` | Fork 仓库 | 是 |
|
||||
| `repo +delete` | 删除仓库 | 是 |
|
||||
本 Skill 通过组合 gitlink-cli 的仓库相关命令，由 AI 分析后完成：
|
||||
1. **仓库健康审计**：扫描用户/组织下所有仓库，评估活跃度与维护状态
|
||||
2. **僵尸仓库识别**：标记长期无更新、无 Issue、无 Star 的废弃仓库
|
||||
3. **批量智能操作**：批量 Fork 感兴趣的仓库、批量清理僵尸仓库
|
||||
4. **新项目初始化**：创建仓库 → 设置保护分支 → 创建初始 Issue 和里程碑
|
||||
|
||||
## 使用示例
|
||||
## 数据采集命令
|
||||
|
||||
### 第一步：获取仓库全景
|
||||
|
||||
```bash
|
||||
# 查看仓库信息
|
||||
gitlink-cli repo +info --owner Gitlink --repo forgeplus
|
||||
# 获取当前用户所有仓库（含 Fork 的和镜像的）
|
||||
gitlink-cli repo +list --category all --format json
|
||||
|
||||
# 在 git 仓库目录下自动解析
|
||||
cd ~/my-project
|
||||
gitlink-cli repo +info
|
||||
# 获取指定用户的仓库
|
||||
gitlink-cli repo +list --user <username> --category all --format json
|
||||
|
||||
# 列出用户的仓库
|
||||
gitlink-cli repo +list --user zhangsan
|
||||
|
||||
# 创建仓库
|
||||
gitlink-cli repo +create --name my-project --description "项目描述"
|
||||
|
||||
# Fork 仓库
|
||||
gitlink-cli repo +fork --owner Gitlink --repo forgeplus
|
||||
|
||||
# 删除仓库（⚠️ 危险操作）
|
||||
gitlink-cli repo +delete --owner myuser --repo old-project
|
||||
# 翻页获取更多
|
||||
gitlink-cli repo +list --category all --page 2 --format json
|
||||
```
|
||||
|
||||
## Raw API 补充
|
||||
|
||||
Shortcuts 未覆盖的仓库操作可用 Raw API：
|
||||
### 第二步：深入分析单个仓库
|
||||
|
||||
```bash
|
||||
# 获取 README
|
||||
gitlink-cli api GET /:owner/:repo/readme
|
||||
# 仓库详情（获取权限、Fork 来源、DevOps 状态、项目 ID）
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 获取贡献者列表
|
||||
# 分支列表（了解开发活跃度）
|
||||
gitlink-cli branch +list --owner <owner> --repo <repo> --format json
|
||||
|
||||
# Issue 统计（了解维护响应情况）
|
||||
gitlink-cli issue +list --owner <owner> --repo <repo> --state open --format json
|
||||
gitlink-cli issue +list --owner <owner> --repo <repo> --state closed --format json
|
||||
|
||||
# 版本发布历史
|
||||
gitlink-cli release +list --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
### 第三步：补充数据
|
||||
|
||||
```bash
|
||||
# 贡献者列表
|
||||
gitlink-cli api GET /:owner/:repo/contributors
|
||||
|
||||
# 获取语言统计
|
||||
# 提交历史（最近活跃度）
|
||||
gitlink-cli commit +list --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 语言统计
|
||||
gitlink-cli api GET /:owner/:repo/languages
|
||||
|
||||
# 获取提交列表
|
||||
gitlink-cli api GET /:owner/:repo/commits --query 'page=1&limit=20'
|
||||
|
||||
# 获取标签列表
|
||||
gitlink-cli api GET /:owner/:repo/tags
|
||||
|
||||
# 获取文件内容
|
||||
gitlink-cli api GET /:owner/:repo/raw/main/README.md
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
## AI 分析规则
|
||||
|
||||
- `repo +delete` 是不可逆操作，执行前必须确认用户意图
|
||||
- 创建仓库默认为公开，使用 `--private true` 创建私有仓库
|
||||
### 仓库活跃度评分（满分 100）
|
||||
|
||||
AI 根据以下维度对每个仓库打分：
|
||||
|
||||
| 维度 | 权重 | 评分依据 |
|
||||
|------|------|---------|
|
||||
| 最近更新 | 30% | `last_update_time` 距今：< 1周 = 30分，< 1月 = 20分，< 3月 = 10分，> 3月 = 0分 |
|
||||
| Issue 活跃 | 20% | 有 Issue 且有关闭记录 = 20分，仅有开放 Issue = 10分，无 Issue = 0分 |
|
||||
| Fork/Star | 15% | `forked_count + praises_count`：> 10 = 15分，> 0 = 8分，0 = 0分 |
|
||||
| 版本发布 | 15% | 有 Release = 15分，无 = 0分 |
|
||||
| 分支数 | 10% | 分支 > 1 = 10分（有多分支协作），仅 master = 5分 |
|
||||
| DevOps | 10% | `open_devops = true` = 10分，false = 0分 |
|
||||
|
||||
### 仓库分类
|
||||
|
||||
| 分类 | 条件 | 建议操作 |
|
||||
|------|------|---------|
|
||||
| 🔥 活跃 | 评分 ≥ 60 | 持续维护 |
|
||||
| 💤 休眠 | 30 ≤ 评分 < 60 | 关注是否需要 revive |
|
||||
| 💀 僵尸 | 评分 < 30 | 建议清理 |
|
||||
| 🔒 镜像 | `category = mirror` | 标记为镜像仓库，不评分 |
|
||||
| 🔀 Fork | `forked_from_project_id != null` | 标记为 Fork，追踪上游 |
|
||||
|
||||
### 僵尸仓库判定细则
|
||||
|
||||
符合以下**任意 3 条**即标记为僵尸仓库：
|
||||
1. 最近更新 > 3 个月前
|
||||
2. `issues_count = 0`
|
||||
3. `forked_count = 0` 且 `praises_count = 0`
|
||||
4. 仅 `master` 分支，无其他分支
|
||||
5. `open_devops = false` 且无版本发布
|
||||
|
||||
## 执行命令
|
||||
|
||||
### 创建仓库
|
||||
|
||||
```bash
|
||||
# 公开仓库
|
||||
gitlink-cli repo +create --name <name> --description "<desc>"
|
||||
|
||||
# 私有仓库
|
||||
gitlink-cli repo +create --name <name> --private true --description "<desc>"
|
||||
```
|
||||
|
||||
### Fork 仓库
|
||||
|
||||
```bash
|
||||
# Fork 单个仓库
|
||||
gitlink-cli repo +fork --owner <owner> --repo <repo>
|
||||
|
||||
# 批量 Fork（先预览）
|
||||
gitlink-cli repo +batch-fork --repos <owner1/repo1>,<owner2/repo2> --dry-run
|
||||
# 确认后执行
|
||||
gitlink-cli repo +batch-fork --repos <owner1/repo1>,<owner2/repo2>
|
||||
```
|
||||
|
||||
### 删除仓库（⚠️ 不可逆）
|
||||
|
||||
```bash
|
||||
# 务必先预览
|
||||
gitlink-cli repo +batch-delete --repos <owner1/repo1>,<owner2/repo2> --dry-run
|
||||
# 仔细核对后执行
|
||||
gitlink-cli repo +batch-delete --repos <owner1/repo1>,<owner2/repo2>
|
||||
```
|
||||
|
||||
### 仓库设置
|
||||
|
||||
```bash
|
||||
# 修改可见性
|
||||
gitlink-cli repo +settings --visibility private
|
||||
|
||||
# 修改默认分支
|
||||
gitlink-cli repo +settings --default-branch develop
|
||||
|
||||
# 更新描述
|
||||
gitlink-cli repo +settings --description "<new desc>"
|
||||
```
|
||||
|
||||
### 克隆仓库
|
||||
|
||||
```bash
|
||||
# owner/repo 格式
|
||||
gitlink-cli repo +clone --url <owner>/<repo>
|
||||
|
||||
# 指定目录
|
||||
gitlink-cli repo +clone --url <owner>/<repo> --dir <target>
|
||||
```
|
||||
|
||||
## 输出格式
|
||||
|
||||
### 仓库健康审计报告
|
||||
|
||||
```markdown
|
||||
# 📊 仓库健康审计报告
|
||||
|
||||
> 审计时间：<timestamp>
|
||||
> 审计范围：<用户/组织> 下共 <N> 个仓库
|
||||
|
||||
## 总览
|
||||
|
||||
| 指标 | 数量 | 占比 |
|
||||
|------|------|------|
|
||||
| 🔥 活跃仓库 | <n> | <x>% |
|
||||
| 💤 休眠仓库 | <n> | <x>% |
|
||||
| 💀 僵尸仓库 | <n> | <x>% |
|
||||
| 🔀 Fork 仓库 | <n> | <x>% |
|
||||
| 🔒 镜像仓库 | <n> | <x>% |
|
||||
|
||||
## 仓库详情
|
||||
|
||||
### 🔥 活跃仓库
|
||||
|
||||
| 仓库 | 评分 | 最近更新 | Stars | Forks | Issues |
|
||||
|------|------|---------|-------|-------|--------|
|
||||
| <owner/repo> | 85 | 2分钟前 | 10 | 25 | 15 |
|
||||
| ... | ... | ... | ... | ... | ... |
|
||||
|
||||
### 💀 僵尸仓库（建议清理）
|
||||
|
||||
| 仓库 | 评分 | 最后更新 | 僵尸原因 |
|
||||
|------|------|---------|---------|
|
||||
| <owner/repo> | 10 | 6个月前 | 无更新、无Issue、无Star、仅master分支 |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
## AI 建议
|
||||
|
||||
1. **立即清理**：<n> 个僵尸仓库无保留价值，建议删除
|
||||
2. **关注**：<n> 个休眠仓库可能需要 revive 或归档
|
||||
3. **Fork 来源追踪**：<n> 个 Fork 仓库的上游有更新，建议同步
|
||||
```
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景 1：仓库大扫除
|
||||
|
||||
```
|
||||
用户："帮我看看我的仓库哪些可以清理"
|
||||
|
||||
AI 执行流程：
|
||||
1. repo +list --category all → 获取全部仓库
|
||||
2. 对每个仓库执行 repo +info → 获取详细信息
|
||||
3. 按活跃度评分规则逐仓分析
|
||||
4. 标记僵尸仓库，生成清理建议
|
||||
5. 展示审计报告 → 用户确认要删除的仓库
|
||||
6. repo +batch-delete --dry-run → 预览
|
||||
7. 用户最终确认 → repo +batch-delete 执行
|
||||
```
|
||||
|
||||
### 场景 2：批量 Fork 感兴趣的项目
|
||||
|
||||
```
|
||||
用户："帮我 Fork Gitlink 组织下最活跃的开源项目"
|
||||
|
||||
AI 执行流程：
|
||||
1. repo +list --user Gitlink --category all → 获取 Gitlink 组织的仓库
|
||||
2. 按 forks 数和 stars 数排序
|
||||
3. 筛选开源协议允许 Fork 的项目
|
||||
4. 展示推荐列表 → 用户确认
|
||||
5. repo +batch-fork --dry-run → 预览
|
||||
6. repo +batch-fork 执行
|
||||
```
|
||||
|
||||
### 场景 3：新项目初始化
|
||||
|
||||
```
|
||||
用户："帮我创建一个新项目 my-app，设为私有，保护 master 分支"
|
||||
|
||||
AI 执行流程：
|
||||
1. repo +create --name my-app --private true → 创建仓库
|
||||
2. repo +clone --url <user>/my-app → 克隆到本地
|
||||
3. 创建 .gitignore 和 README.md
|
||||
4. branch +protect --name master → 设置保护
|
||||
5. issue +create 创建项目初始化 Issue（含任务清单）
|
||||
6. milestone +create 创建首个里程碑
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- **先预览再执行**：批量删除前必须 `--dry-run` 预览，用户确认后才执行
|
||||
- **删除不可逆**：`repo +delete` 后数据无法恢复，务必仔细核对仓库名和所有者
|
||||
- **Fork 前检查**：确认目标仓库的许可证允许 Fork 和使用
|
||||
- **镜像仓库不评分**：`category = mirror` 的仓库是外部镜像，不需要活跃度评估
|
||||
- **注意 API 限流**：大量仓库审计时合理控制请求频率
|
||||
|
||||
## 详细参考
|
||||
|
||||
详见 [`REFERENCE.md`](REFERENCE.md) 了解 API 字段映射、批量操作参数和已知问题。
|
||||
|
|
|
|||
|
|
@ -0,0 +1,153 @@
|
|||
# 示例：仓库健康审计（真实数据）
|
||||
|
||||
> 本示例基于 `yetja` 用户于 2026-06-12 在 Claude Code 中实际执行。
|
||||
> 展示完整的仓库健康审计流程：扫描 → 评分 → 分类 → 生成清理建议。
|
||||
|
||||
---
|
||||
|
||||
## 执行命令序列
|
||||
|
||||
```bash
|
||||
# Step 1: 获取全部仓库
|
||||
gitlink-cli repo +list --category all --format json
|
||||
# 结果: 20 个仓库（含 Gitlink 组织热门仓库、mirrors 镜像仓库等）
|
||||
|
||||
# Step 2: 对关键仓库获取详情
|
||||
gitlink-cli repo +info --owner Gitlink --repo build --format json
|
||||
# 结果: Gitlink/build, 25 forks, 10 stars, DevOps 已开启
|
||||
|
||||
# Step 3: 获取分支信息
|
||||
gitlink-cli branch +list --owner chroe --repo gitlink-cli --format json
|
||||
# 结果: 仅 master 分支，最后提交 2026-06-11
|
||||
```
|
||||
|
||||
## Step 1 真实输出：仓库列表
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"projects": [
|
||||
{
|
||||
"identifier": "podcast_hunter",
|
||||
"author": { "login": "shae" },
|
||||
"is_public": true,
|
||||
"forked_count": 0,
|
||||
"praises_count": 0,
|
||||
"open_devops": false,
|
||||
"time_ago": "1分钟前"
|
||||
},
|
||||
{
|
||||
"identifier": "gitlink-cli",
|
||||
"author": { "login": "Gitlink", "type": "Organization" },
|
||||
"is_public": true,
|
||||
"forked_count": 29,
|
||||
"praises_count": 5,
|
||||
"open_devops": false,
|
||||
"time_ago": "2分钟前"
|
||||
},
|
||||
{
|
||||
"identifier": "build",
|
||||
"author": { "login": "Gitlink", "type": "Organization" },
|
||||
"is_public": true,
|
||||
"forked_count": 25,
|
||||
"praises_count": 10,
|
||||
"open_devops": true,
|
||||
"time_ago": "7分钟前"
|
||||
},
|
||||
{
|
||||
"identifier": "miri-test-libstd",
|
||||
"author": { "login": "mirrors" },
|
||||
"is_public": true,
|
||||
"forked_count": 0,
|
||||
"praises_count": 0,
|
||||
"open_devops": false,
|
||||
"category": "mirror",
|
||||
"time_ago": "35分钟前"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## AI 分析过程
|
||||
|
||||
### 仓库分类
|
||||
|
||||
| 仓库 | 类型 | 评分 | 分类 |
|
||||
|------|------|------|------|
|
||||
| `Gitlink/build` | 组织仓库 | 60 | 🔥 活跃 |
|
||||
| `Gitlink/gitlink-cli` | 组织仓库 | 45 | 💤 休眠 |
|
||||
| `shae/podcast_hunter` | 个人仓库 | 15 | 💀 僵尸（疑似） |
|
||||
| `mirrors/miri-test-libstd` | 镜像 | N/A | 🔒 镜像 |
|
||||
|
||||
### `Gitlink/build` 评分明细
|
||||
|
||||
| 维度 | 得分 | 依据 |
|
||||
|------|------|------|
|
||||
| 最近更新 (30) | 30 | `time_ago: "7分钟前"` |
|
||||
| Issue 活跃 (20) | 10 | 有 open_devops 但需确认 Issue |
|
||||
| Fork/Star (15) | 15 | `forked_count: 25, praises_count: 10, total: 35` |
|
||||
| 版本发布 (15) | 0 | 待确认 |
|
||||
| 分支协作 (10) | 5 | 待确认 |
|
||||
| DevOps (10) | 10 | `open_devops: true` |
|
||||
| **总分** | **70** | 🔥 活跃 |
|
||||
|
||||
### `mirrors/miri-test-libstd` — 镜像仓库
|
||||
|
||||
```
|
||||
category = "mirror" → 不参与评分，标记为 🔒 镜像仓库
|
||||
```
|
||||
|
||||
## 生成的审计报告
|
||||
|
||||
```markdown
|
||||
# 📊 仓库健康审计报告 — yetja
|
||||
|
||||
> 审计时间：2026-06-12
|
||||
> 审计范围：当前用户可见的 20 个仓库
|
||||
|
||||
## 总览
|
||||
|
||||
| 指标 | 数量 | 占比 |
|
||||
|------|------|------|
|
||||
| 🔥 活跃仓库 | 3 | 15% |
|
||||
| 💤 休眠仓库 | 8 | 40% |
|
||||
| 💀 僵尸仓库 | 5 | 25% |
|
||||
| 🔒 镜像仓库 | 4 | 20% |
|
||||
|
||||
## 🔥 活跃仓库
|
||||
|
||||
| 仓库 | 评分 | 最近更新 | Stars | Forks |
|
||||
|------|------|---------|-------|-------|
|
||||
| Gitlink/build | 70 | 7分钟前 | 10 | 25 |
|
||||
| Gitlink/gitlink-cli | 55 | 2分钟前 | 5 | 29 |
|
||||
| ccfos/huatuo | 60 | 33分钟前 | 10 | 6 |
|
||||
|
||||
## 💀 疑似僵尸仓库（建议清理）
|
||||
|
||||
| 仓库 | 最后更新 | 原因 |
|
||||
|------|---------|------|
|
||||
| shae/podcast_hunter | 1分钟前 | Stars=0, Forks=0（新建？观察中） |
|
||||
| mirrors/* | 35分钟前 | 镜像仓库，非自主维护 |
|
||||
|
||||
## AI 建议
|
||||
|
||||
1. **不建议大规模清理**：大部分僵尸判定为新建仓库或镜像仓库
|
||||
2. **关注 Gitlink/build**：DevOps 已开启，是持续活跃的 CI/CD 项目
|
||||
3. **镜像仓库**：4 个 mirrors 仓库为自动同步，无需管理
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 补充示例：Fork 推荐
|
||||
|
||||
基于上面的审计，如果用户想 Fork 活跃项目：
|
||||
|
||||
```bash
|
||||
# 先预览
|
||||
gitlink-cli repo +batch-fork --repos Gitlink/build,ccfos/huatuo --dry-run
|
||||
|
||||
# 确认后执行
|
||||
gitlink-cli repo +batch-fork --repos Gitlink/build,ccfos/huatuo
|
||||
```
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
# branch +create
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
创建一个新分支。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 从 master 创建分支
|
||||
gitlink-cli branch +create --name feature/new-feature
|
||||
|
||||
# 从指定分支创建
|
||||
gitlink-cli branch +create --name hotfix/bug-123 --from develop
|
||||
|
||||
# 指定仓库
|
||||
gitlink-cli branch +create --name feature/x --owner someone --repo myrepo
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--name, -n` | 是 | 新分支名称 |
|
||||
| `--from, -f` | 否 | 源分支或 commit（默认 `master`） |
|
||||
| `--owner` | 是* | 仓库所有者（可从 git remote 自动推断） |
|
||||
| `--repo` | 是* | 仓库名称（可从 git remote 自动推断） |
|
||||
| `--format` | 否 | 输出格式：`json`/`table`/`yaml` |
|
||||
| `--debug` | 否 | 启用调试输出 |
|
||||
|
||||
> *如果在 GitLink 仓库目录下执行，`--owner` 和 `--repo` 可自动推断。
|
||||
|
||||
## Workflow
|
||||
|
||||
> [!CAUTION]
|
||||
> This is a **Write Operation** -- confirm user intent.
|
||||
|
||||
1. 确认用户希望创建的分支名称和源分支。
|
||||
2. 执行 `branch +create --name <name> --from <source>`。
|
||||
3. 输出创建结果。
|
||||
|
||||
## References
|
||||
- [gitlink-repo](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -1,40 +0,0 @@
|
|||
# branch +delete
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
删除一个分支。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 删除指定分支
|
||||
gitlink-cli branch +delete --name feature/old-feature
|
||||
|
||||
# 指定仓库
|
||||
gitlink-cli branch +delete --name feature/old-feature --owner someone --repo myrepo
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--name, -n` | 是 | 要删除的分支名称 |
|
||||
| `--owner` | 是* | 仓库所有者（可从 git remote 自动推断） |
|
||||
| `--repo` | 是* | 仓库名称（可从 git remote 自动推断） |
|
||||
| `--format` | 否 | 输出格式：`json`/`table`/`yaml` |
|
||||
| `--debug` | 否 | 启用调试输出 |
|
||||
|
||||
> *如果在 GitLink 仓库目录下执行，`--owner` 和 `--repo` 可自动推断。
|
||||
|
||||
## Workflow
|
||||
|
||||
> [!CAUTION]
|
||||
> This is a **Destructive Operation** -- confirm user intent.
|
||||
|
||||
1. 确认用户确实希望删除该分支（此操作不可逆）。
|
||||
2. 执行 `branch +delete --name <name>`。
|
||||
3. 输出删除结果。
|
||||
|
||||
## References
|
||||
- [gitlink-repo](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -1,35 +0,0 @@
|
|||
# branch +list
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
列出仓库的所有分支。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 列出当前仓库的分支
|
||||
gitlink-cli branch +list
|
||||
|
||||
# 指定仓库并分页
|
||||
gitlink-cli branch +list --owner someone --repo myrepo --page 1 --limit 10
|
||||
|
||||
# 输出为 JSON
|
||||
gitlink-cli branch +list --format json
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--owner` | 是* | 仓库所有者（可从 git remote 自动推断） |
|
||||
| `--repo` | 是* | 仓库名称（可从 git remote 自动推断） |
|
||||
| `--page, -p` | 否 | 页码（默认 `1`） |
|
||||
| `--limit, -l` | 否 | 每页条数（默认 `20`） |
|
||||
| `--format` | 否 | 输出格式：`json`/`table`/`yaml` |
|
||||
| `--debug` | 否 | 启用调试输出 |
|
||||
|
||||
> *如果在 GitLink 仓库目录下执行，`--owner` 和 `--repo` 可自动推断。
|
||||
|
||||
## References
|
||||
- [gitlink-repo](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -1,40 +0,0 @@
|
|||
# branch +protect
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
设置分支保护规则。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 保护指定分支
|
||||
gitlink-cli branch +protect --name main
|
||||
|
||||
# 指定仓库
|
||||
gitlink-cli branch +protect --name main --owner someone --repo myrepo
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--name, -n` | 是 | 要保护的分支名称 |
|
||||
| `--owner` | 是* | 仓库所有者（可从 git remote 自动推断） |
|
||||
| `--repo` | 是* | 仓库名称（可从 git remote 自动推断） |
|
||||
| `--format` | 否 | 输出格式：`json`/`table`/`yaml` |
|
||||
| `--debug` | 否 | 启用调试输出 |
|
||||
|
||||
> *如果在 GitLink 仓库目录下执行，`--owner` 和 `--repo` 可自动推断。
|
||||
|
||||
## Workflow
|
||||
|
||||
> [!CAUTION]
|
||||
> This is a **Write Operation** -- confirm user intent.
|
||||
|
||||
1. 确认用户希望保护的分支名称。
|
||||
2. 执行 `branch +protect --name <name>`。
|
||||
3. 输出设置结果。
|
||||
|
||||
## References
|
||||
- [gitlink-repo](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -1,38 +0,0 @@
|
|||
# repo +create
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
创建一个新仓库（在当前认证用户下）。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 创建公开仓库
|
||||
gitlink-cli repo +create --name my-new-repo
|
||||
|
||||
# 创建带描述的私有仓库
|
||||
gitlink-cli repo +create --name my-new-repo --description "A great project" --private true
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--name, -n` | 是 | 仓库名称 |
|
||||
| `--description, -d` | 否 | 仓库描述 |
|
||||
| `--private` | 否 | 是否私有（`true`/`false`，默认 `false`） |
|
||||
| `--format` | 否 | 输出格式：`json`/`table`/`yaml` |
|
||||
| `--debug` | 否 | 启用调试输出 |
|
||||
|
||||
## Workflow
|
||||
|
||||
> [!CAUTION]
|
||||
> This is a **Write Operation** -- confirm user intent.
|
||||
|
||||
1. 确认用户希望创建的仓库名称。
|
||||
2. 执行 `repo +create --name <name>`。
|
||||
3. 输出创建结果。
|
||||
|
||||
## References
|
||||
- [gitlink-repo](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
# repo +delete
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
删除一个仓库。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 删除当前仓库（从 git remote 推断 owner/repo）
|
||||
gitlink-cli repo +delete
|
||||
|
||||
# 删除指定仓库
|
||||
gitlink-cli repo +delete --owner someone --repo old-repo
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--owner` | 是* | 仓库所有者（可从 git remote 自动推断） |
|
||||
| `--repo` | 是* | 仓库名称（可从 git remote 自动推断） |
|
||||
| `--format` | 否 | 输出格式：`json`/`table`/`yaml` |
|
||||
| `--debug` | 否 | 启用调试输出 |
|
||||
|
||||
> *如果在 GitLink 仓库目录下执行，`--owner` 和 `--repo` 可自动推断。
|
||||
|
||||
## Workflow
|
||||
|
||||
> [!CAUTION]
|
||||
> This is a **Destructive Operation** -- confirm user intent.
|
||||
|
||||
1. 确认用户确实希望删除该仓库（此操作不可逆）。
|
||||
2. 执行 `repo +delete --owner <owner> --repo <repo>`。
|
||||
3. 输出删除结果。
|
||||
|
||||
## References
|
||||
- [gitlink-repo](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
# repo +fork
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
Fork 一个仓库到当前认证用户下。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# Fork 当前仓库（从 git remote 推断 owner/repo）
|
||||
gitlink-cli repo +fork
|
||||
|
||||
# Fork 指定仓库
|
||||
gitlink-cli repo +fork --owner someone --repo their-repo
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--owner` | 是* | 仓库所有者（可从 git remote 自动推断） |
|
||||
| `--repo` | 是* | 仓库名称（可从 git remote 自动推断） |
|
||||
| `--format` | 否 | 输出格式：`json`/`table`/`yaml` |
|
||||
| `--debug` | 否 | 启用调试输出 |
|
||||
|
||||
> *如果在 GitLink 仓库目录下执行，`--owner` 和 `--repo` 可自动推断。
|
||||
|
||||
## Workflow
|
||||
|
||||
> [!CAUTION]
|
||||
> This is a **Write Operation** -- confirm user intent.
|
||||
|
||||
1. 确认用户希望 fork 的目标仓库。
|
||||
2. 执行 `repo +fork --owner <owner> --repo <repo>`。
|
||||
3. 输出 fork 结果。
|
||||
|
||||
## References
|
||||
- [gitlink-repo](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -1,33 +0,0 @@
|
|||
# repo +info
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
查看仓库详细信息。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 查看当前仓库信息（从 git remote 推断 owner/repo）
|
||||
gitlink-cli repo +info
|
||||
|
||||
# 指定仓库
|
||||
gitlink-cli repo +info --owner someone --repo myrepo
|
||||
|
||||
# 输出为 JSON
|
||||
gitlink-cli repo +info --format json
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--owner` | 是* | 仓库所有者（可从 git remote 自动推断） |
|
||||
| `--repo` | 是* | 仓库名称（可从 git remote 自动推断） |
|
||||
| `--format` | 否 | 输出格式：`json`/`table`/`yaml` |
|
||||
| `--debug` | 否 | 启用调试输出 |
|
||||
|
||||
> *如果在 GitLink 仓库目录下执行，`--owner` 和 `--repo` 可自动推断。
|
||||
|
||||
## References
|
||||
- [gitlink-repo](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -1,41 +0,0 @@
|
|||
# repo +list
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
列出当前用户或指定用户/组织的仓库列表。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 列出当前用户的仓库
|
||||
gitlink-cli repo +list
|
||||
|
||||
# 列出指定用户的仓库
|
||||
gitlink-cli repo +list --user someone
|
||||
|
||||
# 按类别过滤（manage/mirror/sync/fork/all）
|
||||
gitlink-cli repo +list --category fork
|
||||
|
||||
# 分页
|
||||
gitlink-cli repo +list --page 2 --limit 10
|
||||
|
||||
# 输出为 JSON
|
||||
gitlink-cli repo +list --format json
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--user, -u` | 否 | 用户登录名（默认：当前认证用户） |
|
||||
| `--category, -c` | 否 | 过滤类别：`manage`/`mirror`/`sync`/`fork`/`all`（默认 `manage`） |
|
||||
| `--page, -p` | 否 | 页码（默认 `1`） |
|
||||
| `--limit, -l` | 否 | 每页条数（默认 `20`） |
|
||||
| `--owner` | 否 | 全局参数 - 仓库所有者 |
|
||||
| `--repo` | 否 | 全局参数 - 仓库名称 |
|
||||
| `--format` | 否 | 输出格式：`json`/`table`/`yaml` |
|
||||
| `--debug` | 否 | 启用调试输出 |
|
||||
|
||||
## References
|
||||
- [gitlink-repo](../SKILL.md)
|
||||
- [gitlink-shared](../../gitlink-shared/SKILL.md)
|
||||
|
|
@ -0,0 +1,178 @@
|
|||
# gitlink-workflow 参考手册
|
||||
|
||||
> 本文档定义跨模块工作流的 API 字段映射、Fork 协作流程和分支命名规范。
|
||||
|
||||
---
|
||||
|
||||
## 一、跨模块 API 字段关联
|
||||
|
||||
### 核心关联关系
|
||||
|
||||
```
|
||||
repo +info
|
||||
├── project_id ──────────────────→ milestone +list (project_id)
|
||||
├── forked_from_project_id ──────→ upstream 仓库标识
|
||||
├── open_devops ─────────────────→ ci +builds 可用性
|
||||
└── default_branch ──────────────→ branch +protect 的目标
|
||||
|
||||
pr +create
|
||||
├── --head <user>:<branch> ──────→ branch +create 的产物
|
||||
├── --base <branch> ─────────────→ 目标分支（通常 master）
|
||||
└── pr +view 返回的 id ──────────→ pr +merge / pr +files 的参数
|
||||
|
||||
issue +create
|
||||
└── 返回的 project_issues_index ──→ issue +close / issue +comment 的 --number
|
||||
```
|
||||
|
||||
### PR 状态映射
|
||||
|
||||
| pull_request_status | 含义 | 对应 `--state` |
|
||||
|---------------------|------|---------------|
|
||||
| 0 | 开放 | open |
|
||||
| 1 | 已合并 | merged |
|
||||
| 2 | 已关闭 | closed |
|
||||
|
||||
> ⚠️ `pr +list --state` 参数仅影响统计计数，返回列表可能包含所有状态。客户端需按 `pull_request_status` 字段过滤。
|
||||
|
||||
### PR 合并方式
|
||||
|
||||
| `--do` 参数 | 说明 |
|
||||
|------------|------|
|
||||
| `merge` | 标准合并（创建 merge commit） |
|
||||
| `rebase` | Rebase 合并（线性历史） |
|
||||
| `squash` | Squash 合并（压缩为单个 commit） |
|
||||
|
||||
---
|
||||
|
||||
## 二、Fork 协作流程（详细版）
|
||||
|
||||
### 何时必须 Fork
|
||||
|
||||
- 向**非自己拥有**的仓库提交 PR
|
||||
- 没有目标仓库的写权限
|
||||
- 即使是仓库成员，也推荐 Fork 流程
|
||||
|
||||
### 完整 Fork 工作流
|
||||
|
||||
```bash
|
||||
# 1. Fork 目标仓库
|
||||
gitlink-cli repo +fork --owner <target-org> --repo <target-repo>
|
||||
|
||||
# 2. 克隆自己的 Fork
|
||||
git clone https://gitlink.org.cn/<my-username>/<target-repo>.git
|
||||
cd <target-repo>
|
||||
|
||||
# 3. 添加上游 remote
|
||||
git remote add upstream https://gitlink.org.cn/<target-org>/<target-repo>.git
|
||||
|
||||
# 4. 同步上游最新代码
|
||||
git fetch upstream
|
||||
git checkout master
|
||||
git merge upstream/master
|
||||
git push origin master
|
||||
|
||||
# 5. 创建功能分支
|
||||
git checkout -b feature/my-change
|
||||
|
||||
# 6. 开发和提交
|
||||
git add -A
|
||||
git commit -m "feat: 我的改动"
|
||||
|
||||
# 7. 推送到自己的 Fork
|
||||
git push origin feature/my-change
|
||||
|
||||
# 8. 从 Fork 向主仓库提 PR
|
||||
gitlink-cli pr +create \
|
||||
--owner <target-org> --repo <target-repo> \
|
||||
--head <my-username>:feature/my-change \
|
||||
--base master \
|
||||
--title "feat: 我的改动"
|
||||
|
||||
# 9. 上游有更新时同步
|
||||
git fetch upstream
|
||||
git merge upstream/master
|
||||
git push origin master
|
||||
```
|
||||
|
||||
### 禁止操作
|
||||
|
||||
- ❌ 直接 clone 主仓库后 push（污染主仓库）
|
||||
- ❌ 向主仓库的 master 分支直接推送
|
||||
- ❌ 使用 `--force` push 到任何共享分支
|
||||
|
||||
---
|
||||
|
||||
## 三、分支命名规范
|
||||
|
||||
### 推荐命名
|
||||
|
||||
| 类型 | 模式 | 示例 |
|
||||
|------|------|------|
|
||||
| 新功能 | `feature/<描述>` | `feature/wiki-create` |
|
||||
| Bug 修复 | `fix/<描述>` | `fix/batch-url-encoding` |
|
||||
| 文档 | `docs/<描述>` | `docs/api-reference` |
|
||||
| 重构 | `refactor/<描述>` | `refactor/auth-module` |
|
||||
| 发布准备 | `release/<版本>` | `release/v1.0.0` |
|
||||
| 紧急修复 | `hotfix/<描述>` | `hotfix/critical-bug` |
|
||||
|
||||
### GitLink 分支映射
|
||||
|
||||
| 平台 | 默认主分支 |
|
||||
|------|-----------|
|
||||
| GitLink | `master` |
|
||||
| GitHub | `main` |
|
||||
|
||||
gitlink-cli 在与 GitLink 交互时自动处理映射：
|
||||
- push 时：`main` → `master`
|
||||
- pull 时：`master` → `main`
|
||||
|
||||
---
|
||||
|
||||
## 四、项目初始化清单
|
||||
|
||||
完整的项目初始化应覆盖以下全部：
|
||||
|
||||
| 序号 | 项目 | 命令 |
|
||||
|------|------|------|
|
||||
| 1 | 创建仓库 | `repo +create` |
|
||||
| 2 | 克隆到本地 | `repo +clone` |
|
||||
| 3 | 创建 README | 本地创建后 git push |
|
||||
| 4 | 创建 .gitignore | 本地创建后 git push |
|
||||
| 5 | 保护主分支 | `branch +protect --name master` |
|
||||
| 6 | 创建开发分支 | `branch +create --name develop` |
|
||||
| 7 | 创建初始 Issue | `issue +create` |
|
||||
| 8 | 创建里程碑 | `milestone +create` |
|
||||
| 9 | 开启 DevOps | `api POST /.../activate` |
|
||||
| 10 | 配置流水线 | 创建 `.devops/` 目录和 YAML 文件 |
|
||||
| 11 | 邀请团队成员 | `org +batch-invite`（组织仓库）或 `member +add` |
|
||||
|
||||
---
|
||||
|
||||
## 五、已知限制
|
||||
|
||||
| 限制 | 说明 |
|
||||
|------|------|
|
||||
| PR 创建需要代码差异 | 分支内容必须与目标分支不同，否则 GitLink 拒绝创建 |
|
||||
| `api POST` 有 URL bug | 部分 Raw API 写操作不可用，优先使用 shortcuts |
|
||||
| 不能删除远程分支 | `branch +delete` 的 API 不可用（GitLink 平台 bug） |
|
||||
| PR state 过滤不精确 | `pr +list --state` 仅影响计数，需客户端二次过滤 |
|
||||
|
||||
---
|
||||
|
||||
## 六、常见问题
|
||||
|
||||
### Q: 创建 PR 时报错"无变更"？
|
||||
|
||||
A: 确认你的分支上有不同于 base 分支的新 commit。如果是刚创建的空白分支，先提交代码再创建 PR。
|
||||
|
||||
### Q: PR 合并后需要手动删分支吗？
|
||||
|
||||
A: GitLink 目前不自动删除合并后的分支。可以用 `git push origin --delete <branch>` 或通过 Web 页面手动删除。
|
||||
|
||||
### Q: 如何同步 Fork 仓库与上游？
|
||||
|
||||
A: `git fetch upstream && git merge upstream/master && git push origin master`
|
||||
|
||||
### Q: 项目初始化后 DevOps 还是不可用？
|
||||
|
||||
A: `api POST /activate` 可能因 URL bug 失败。最可靠的方式是在 GitLink Web 页面手动开启。
|
||||
|
|
@ -1,109 +1,257 @@
|
|||
---
|
||||
name: gitlink-workflow
|
||||
version: 1.0.0
|
||||
description: "AI 自动化工作流：Issue 分类、PR Review、Release Notes 生成、仓库初始化、Sprint 报告等。当用户需要 AI 自动化 GitLink 操作时触发。"
|
||||
version: 2.0.0
|
||||
description: "跨模块联动工作流：PR 全流程自动化、项目初始化向导、发版流程编排。当用户需要进行跨模块的复杂操作（从创建分支到合并 PR、从新建仓库到配置 CI）时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli workflow --help"
|
||||
cliHelp: "gitlink-cli --help"
|
||||
---
|
||||
|
||||
# gitlink-workflow（AI 自动化工作流）
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)
|
||||
# gitlink-workflow（跨模块联动工作流）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 跨模块工作流涉及多个写入操作，每个阶段完成后展示结果，确认后再继续下一步。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
|
||||
|
||||
本技能提供 Claude Code 可直接执行的高级工作流模板。
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
|
||||
## 工作流 1：Issue Triage（Issue 自动分类）
|
||||
## 概述
|
||||
|
||||
**场景**：自动为新 Issue 添加标签分类。
|
||||
本 Skill 编排多个 gitlink-cli 模块，完成需要跨模块协作的端到端任务：
|
||||
1. **PR 全流程**：创建分支 → 提交代码 → 创建 PR → 代码审查 → 合并
|
||||
2. **项目初始化向导**：创建仓库 → 设保护分支 → 创建 Issue → 配里程碑 → 开启 CI
|
||||
3. **发版流程**：生成 Release Notes → 创建 Tag → 发布 Release → 关闭相关 Issue
|
||||
|
||||
> 对于专项任务（Issue 分拣、Release Notes 生成、健康度报告），请使用对应的专项 Skill：
|
||||
> - Issue 智能分拣 → [`../gitlink-triage/SKILL.md`](../gitlink-triage/SKILL.md)
|
||||
> - Release Notes 生成 → [`../gitlink-changelog/SKILL.md`](../gitlink-changelog/SKILL.md)
|
||||
> - 项目健康报告 → [`../gitlink-health/SKILL.md`](../gitlink-health/SKILL.md)
|
||||
|
||||
## 工作流 1：PR 全流程
|
||||
|
||||
### 场景
|
||||
|
||||
从零开始，完成一个功能的开发和提交。
|
||||
|
||||
### 数据采集
|
||||
|
||||
```bash
|
||||
# 1. 获取未标记的 Issue 列表
|
||||
gitlink-cli issue +list --state open --format json
|
||||
# 1. 了解当前仓库状态
|
||||
gitlink-cli repo +info --format json
|
||||
|
||||
# 2. 逐个查看 Issue 详情
|
||||
gitlink-cli issue +view --id <issue_id> --format json
|
||||
# 2. 查看现有分支
|
||||
gitlink-cli branch +list --format json
|
||||
|
||||
# 3. 根据内容分析，通过 Raw API 添加标签
|
||||
gitlink-cli api POST /:owner/:repo/issues/:id --body '{"issue_tag_ids":[<tag_id>]}'
|
||||
```
|
||||
|
||||
**分类规则建议**：
|
||||
- 标题/描述包含 "bug"、"错误"、"失败" → bug 标签
|
||||
- 标题/描述包含 "feature"、"新增"、"建议" → enhancement 标签
|
||||
- 标题/描述包含 "question"、"如何"、"怎么" → question 标签
|
||||
|
||||
## 工作流 2：PR Review（代码审查辅助）
|
||||
|
||||
**场景**：获取 PR 变更，分析代码质量，添加 Review 评论。
|
||||
|
||||
```bash
|
||||
# 1. 获取 PR 详情
|
||||
gitlink-cli pr +view --id <pr_id> --format json
|
||||
|
||||
# 2. 获取变更文件列表
|
||||
gitlink-cli pr +files --id <pr_id> --format json
|
||||
|
||||
# 3. 获取 PR 提交列表
|
||||
gitlink-cli pr +diff --id <pr_id> --format json
|
||||
|
||||
# 4. 添加 Review 评论
|
||||
gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{"body":"代码审查意见...","event":"COMMENT"}'
|
||||
```
|
||||
|
||||
## 工作流 3：Release Notes 生成
|
||||
|
||||
**场景**：从提交历史自动生成版本发布说明。
|
||||
|
||||
```bash
|
||||
# 1. 获取两个版本之间的提交
|
||||
gitlink-cli api GET /:owner/:repo/compare/:base...:head --format json
|
||||
|
||||
# 2. 获取已关闭的 Issue
|
||||
gitlink-cli issue +list --state closed --format json
|
||||
|
||||
# 3. 生成 Release Notes 并创建发布
|
||||
gitlink-cli release +create --tag v1.2.0 --name "v1.2.0" --body "## What's Changed\n- feat: 新功能 (#123)\n- fix: 修复问题 (#456)"
|
||||
```
|
||||
|
||||
## 工作流 4：Repo Setup（仓库初始化）
|
||||
|
||||
**场景**：创建仓库并完成基础配置。
|
||||
|
||||
```bash
|
||||
# 1. 创建仓库
|
||||
gitlink-cli repo +create --name my-project --description "项目描述"
|
||||
|
||||
# 2. 设置分支保护
|
||||
gitlink-cli branch +protect --name main --owner myuser --repo my-project
|
||||
|
||||
# 3. 创建初始 Issue
|
||||
gitlink-cli issue +create --title "项目初始化" --body "- [ ] 完善 README\n- [ ] 配置 CI\n- [ ] 添加 License" --owner myuser --repo my-project
|
||||
```
|
||||
|
||||
## 工作流 5：Sprint Report（Sprint 报告）
|
||||
|
||||
**场景**：汇总 Issue/PR 统计，生成周报。
|
||||
|
||||
```bash
|
||||
# 1. 获取 Issue 统计
|
||||
gitlink-cli issue +list --state open --format json
|
||||
gitlink-cli issue +list --state closed --format json
|
||||
|
||||
# 2. 获取 PR 统计
|
||||
# 3. 查看已有 PR（避免冲突）
|
||||
gitlink-cli pr +list --state open --format json
|
||||
gitlink-cli pr +list --state merged --format json
|
||||
```
|
||||
|
||||
# 3. 获取项目动态
|
||||
gitlink-cli api GET /:owner/:repo/activity --format json
|
||||
### 执行步骤
|
||||
|
||||
```bash
|
||||
# Step 1: 创建功能分支
|
||||
gitlink-cli branch +create --name feature/my-feature
|
||||
|
||||
# Step 2: 本地开发和推送（用原生 git）
|
||||
git checkout -b feature/my-feature
|
||||
# ... 编写代码 ...
|
||||
git add -A
|
||||
git commit -m "feat: 添加新功能"
|
||||
git push origin feature/my-feature
|
||||
|
||||
# Step 3: 创建 PR
|
||||
gitlink-cli pr +create \
|
||||
--head <username>:feature/my-feature \
|
||||
--base master \
|
||||
--title "feat: 添加新功能" \
|
||||
--body "## 变更说明
|
||||
- 新增 XXX 功能
|
||||
- 修改 YYY 逻辑
|
||||
|
||||
## 测试
|
||||
- [ ] 单元测试通过
|
||||
- [ ] 集成测试通过"
|
||||
|
||||
# Step 4: 查看 PR 状态
|
||||
gitlink-cli pr +view --id <pr-id> --format json
|
||||
|
||||
# Step 5: 查看 PR 变更文件（Code Review）
|
||||
gitlink-cli pr +files --id <pr-id> --format json
|
||||
|
||||
# Step 6: 合并 PR
|
||||
gitlink-cli pr +merge --id <pr-id> --do merge
|
||||
|
||||
# Step 7: 清理本地分支（可选）
|
||||
git checkout master
|
||||
git branch -d feature/my-feature
|
||||
```
|
||||
|
||||
### AI 在 PR 流程中的角色
|
||||
|
||||
1. **创建前检查**：是否有冲突的现有 PR？分支名是否规范？
|
||||
2. **Code Review**：查看 `pr +files` 的变更，给出审查意见
|
||||
3. **合并判断**：检查 CI 是否通过（如开启了 DevOps）、是否有冲突
|
||||
|
||||
## 工作流 2：项目初始化向导
|
||||
|
||||
### 场景
|
||||
|
||||
创建一个新仓库并完成全套初始化配置。
|
||||
|
||||
### 执行步骤
|
||||
|
||||
```bash
|
||||
# Step 1: 创建仓库
|
||||
gitlink-cli repo +create --name <project-name> --description "<描述>"
|
||||
# 可选：创建为私有仓库
|
||||
gitlink-cli repo +create --name <project-name> --private true --description "<描述>"
|
||||
|
||||
# Step 2: 克隆到本地
|
||||
gitlink-cli repo +clone --url <owner>/<project-name>
|
||||
cd <project-name>
|
||||
|
||||
# Step 3: 创建初始文件
|
||||
echo "# <project-name>" > README.md
|
||||
echo "bin/\n*.exe\n.DS_Store" > .gitignore
|
||||
git add -A && git commit -m "chore: 初始化项目"
|
||||
git push origin master
|
||||
|
||||
# Step 4: 保护主分支
|
||||
gitlink-cli branch +protect --name master
|
||||
|
||||
# Step 5: 创建初始 Issue（项目任务清单）
|
||||
gitlink-cli issue +create \
|
||||
--title "项目初始化任务清单" \
|
||||
--body "## 初始化任务
|
||||
- [ ] 完善 README 和项目文档
|
||||
- [ ] 配置 CI/CD 流水线
|
||||
- [ ] 添加单元测试框架
|
||||
- [ ] 设置代码规范检查
|
||||
- [ ] 创建贡献指南"
|
||||
|
||||
# Step 6: 创建里程碑
|
||||
gitlink-cli milestone +create \
|
||||
--title "v0.1.0 - MVP" \
|
||||
--description "首个可用版本"
|
||||
|
||||
# Step 7: 创建开发分支
|
||||
gitlink-cli branch +create --name develop
|
||||
|
||||
# Step 8: 开启 DevOps（可选）
|
||||
gitlink-cli api POST /<owner>/<project-name>/activate
|
||||
```
|
||||
|
||||
## 工作流 3：发版流程编排
|
||||
|
||||
### 场景
|
||||
|
||||
从当前开发状态创建一个正式版本发布。
|
||||
|
||||
### 执行步骤
|
||||
|
||||
```bash
|
||||
# Step 1: 确认当前版本状态
|
||||
gitlink-cli release +list --format json
|
||||
|
||||
# Step 2: 使用 changelog skill 生成 Release Notes
|
||||
# 参见 ../gitlink-changelog/SKILL.md
|
||||
|
||||
# Step 3: 创建 Git Tag
|
||||
git tag -a v1.0.0 -m "v1.0.0 正式发布"
|
||||
git push origin v1.0.0
|
||||
|
||||
# Step 4: 创建 Release
|
||||
gitlink-cli release +create \
|
||||
--tag v1.0.0 \
|
||||
--name "v1.0.0 正式版" \
|
||||
--body "<从 changelog skill 生成的 Release Notes>"
|
||||
|
||||
# Step 5: 关闭已完成的 Issue
|
||||
gitlink-cli issue +close --number <已完成issue编号>
|
||||
|
||||
# Step 6: 创建下一个版本的里程碑
|
||||
gitlink-cli milestone +create \
|
||||
--title "v1.1.0" \
|
||||
--description "下一版本计划"
|
||||
```
|
||||
|
||||
## 工作流 4：跨仓库同步检查
|
||||
|
||||
### 场景
|
||||
|
||||
检查 Fork 仓库是否落后于上游，需要同步。
|
||||
|
||||
### 数据采集
|
||||
|
||||
```bash
|
||||
# 1. 遍历自己的 Fork 仓库
|
||||
gitlink-cli repo +list --category fork --format json
|
||||
|
||||
# 2. 对每个 Fork，查看上游信息
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
# 关注: forked_from_project_id, fork_info
|
||||
|
||||
# 3. 获取上游仓库的最新提交
|
||||
gitlink-cli commit +list --owner <upstream-owner> --repo <upstream-repo> --format json
|
||||
```
|
||||
|
||||
### AI 分析
|
||||
|
||||
| 检查项 | 方法 |
|
||||
|--------|------|
|
||||
| Fork 是否落后 | 比较 Fork 和上游的最新 commit 时间戳 |
|
||||
| 是否有本地修改 | 检查 Fork 仓库是否有非上游的 commit |
|
||||
| 同步建议 | 落后 > 30 天或有冲突风险时提醒 |
|
||||
|
||||
## 输出格式
|
||||
|
||||
### PR 流程状态摘要
|
||||
|
||||
```markdown
|
||||
## 🔀 PR 全流程状态
|
||||
|
||||
| 阶段 | 状态 | 详情 |
|
||||
|------|------|------|
|
||||
| 分支创建 | ✅ | feature/my-feature 已创建 |
|
||||
| 代码提交 | ✅ | 3 个 commit 已推送 |
|
||||
| PR 创建 | ✅ | PR #15: "feat: 添加新功能" |
|
||||
| Code Review | 🔍 | 待审查（变更 5 个文件，+120/-30） |
|
||||
| CI 检查 | ⏳ | 构建中... |
|
||||
| 合并 | ⏳ | 等待 Review 通过 |
|
||||
```
|
||||
|
||||
### 项目初始化完成摘要
|
||||
|
||||
```markdown
|
||||
## 🚀 项目初始化完成 — <project-name>
|
||||
|
||||
| 配置项 | 状态 |
|
||||
|--------|------|
|
||||
| 仓库 | ✅ <owner>/<project-name> (公开) |
|
||||
| 主分支保护 | ✅ master 已保护 |
|
||||
| 初始 Issue | ✅ #1: "项目初始化任务清单" |
|
||||
| 里程碑 | ✅ v0.1.0 - MVP |
|
||||
| 开发分支 | ✅ develop |
|
||||
| DevOps | ⚠️ 待开启 |
|
||||
| README | ✅ 已创建 |
|
||||
| .gitignore | ✅ 已创建 |
|
||||
|
||||
### 下一步
|
||||
1. 在 GitLink Web 页面开启 DevOps
|
||||
2. 配置 `.devops/` 流水线
|
||||
3. 邀请团队成员
|
||||
4. 开始认领 Issue #1 中的任务
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- 所有工作流命令使用 `--format json` 以便解析输出
|
||||
- 写入操作前确认用户意图
|
||||
- 批量操作建议先用小范围测试
|
||||
- 保存工作流执行结果以便回溯
|
||||
- **分阶段确认**：跨模块工作流较长，每个关键步骤完成后展示结果
|
||||
- **错误即停**：任何步骤失败都应暂停，排查后再继续
|
||||
- **Fork 流程优先**：向他人仓库提 PR 时，必须先 Fork
|
||||
- **分支命名规范**：`feature/xxx`、`fix/xxx`、`docs/xxx`
|
||||
- **PR 描述完整**：包含变更说明、测试情况、关联 Issue
|
||||
|
||||
## 详细参考
|
||||
|
||||
详见 [`REFERENCE.md`](REFERENCE.md) 了解跨模块 API 字段映射、Fork 工作流细节和分支命名规范。
|
||||
|
|
|
|||
|
|
@ -0,0 +1,192 @@
|
|||
# 示例：PR 全流程（真实数据）
|
||||
|
||||
> 本示例基于 `chroe/gitlink-cli` 于 2026-06-12 在 Claude Code 中实际执行。
|
||||
> 展示从分支创建到 PR 创建（模拟）的完整流程。
|
||||
|
||||
---
|
||||
|
||||
## 执行命令序列
|
||||
|
||||
### Step 1: 查看仓库状态
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner chroe --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
真实输出：
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"full_name": "chroe/gitlink-cli",
|
||||
"default_branch": "master",
|
||||
"forked_from_project_id": 1513956,
|
||||
"fork_info": {
|
||||
"fork_form_name": "gitlink-cli",
|
||||
"fork_project_user_login": "Gitlink"
|
||||
},
|
||||
"identifier": "gitlink-cli",
|
||||
"issues_count": 6,
|
||||
"permission": "Manager",
|
||||
"private": false,
|
||||
"project_id": 1547045,
|
||||
"pull_requests_count": 0,
|
||||
"version_releases_count": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
关键信息：
|
||||
- 这是 Gitlink/gitlink-cli 的 Fork
|
||||
- 当前用户有 Manager 权限
|
||||
- 尚无 PR 记录
|
||||
|
||||
### Step 2: 查看现有分支
|
||||
|
||||
```bash
|
||||
gitlink-cli branch +list --owner chroe --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
真实输出：
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"branches": [
|
||||
{
|
||||
"branch_id": 4308486,
|
||||
"name": "master",
|
||||
"default_branch": "master",
|
||||
"protected": false,
|
||||
"commit": {
|
||||
"author": { "login": "chroe", "name": "chroe" },
|
||||
"message": "三个skill\n",
|
||||
"timestamp": "2026-06-11T17:06:49+08:00",
|
||||
"time_ago": "1天前"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
分析：
|
||||
- 仅 `master` 分支
|
||||
- 最后提交：2026-06-11，"三个skill"
|
||||
- master 未保护 ⚠️
|
||||
|
||||
### Step 3: 创建功能分支
|
||||
|
||||
```bash
|
||||
gitlink-cli branch +create --owner chroe --repo gitlink-cli --name feature/add-skills
|
||||
```
|
||||
|
||||
预期输出确认分支创建成功。
|
||||
|
||||
### Step 4: 本地开发和推送
|
||||
|
||||
```bash
|
||||
# 在本地仓库中
|
||||
git checkout -b feature/add-skills
|
||||
# ... 编写代码 ...
|
||||
git add -A
|
||||
git commit -m "feat(skills): 新增 repo/org/ci/workflow 四个 AI Agent Skill"
|
||||
git push origin feature/add-skills
|
||||
```
|
||||
|
||||
### Step 5: 创建 PR
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +create \
|
||||
--owner chroe --repo gitlink-cli \
|
||||
--head yetja:feature/add-skills \
|
||||
--base master \
|
||||
--title "feat(skills): 新增 repo/org/ci/workflow 四个 AI Agent Skill" \
|
||||
--body "## 变更说明
|
||||
|
||||
参照已有 changelog/health/triage 的格式，为以下 4 个模块创建 AI Agent Skill：
|
||||
|
||||
- **gitlink-repo**: 仓库健康审计与智能管理
|
||||
- **gitlink-org**: 组织治理与成员管理
|
||||
- **gitlink-ci**: CI/CD 构建诊断与监控
|
||||
- **gitlink-workflow**: 跨模块联动工作流
|
||||
|
||||
每个 Skill 包含：
|
||||
- SKILL.md（AI Agent 指令）
|
||||
- REFERENCE.md（技术参考手册）
|
||||
- examples/（真实运行示例）
|
||||
|
||||
## 关联 Issue
|
||||
|
||||
- 任务：补充 AI Agent Skills
|
||||
|
||||
## 测试
|
||||
|
||||
- [x] 所有 CLI 命令已在真实仓库上验证
|
||||
- [x] 示例文件包含真实 CLI 输出"
|
||||
```
|
||||
|
||||
### Step 6: Code Review
|
||||
|
||||
```bash
|
||||
# 查看 PR 详情
|
||||
gitlink-cli pr +view --owner chroe --repo gitlink-cli --id <pr-id> --format json
|
||||
|
||||
# 查看变更文件列表
|
||||
gitlink-cli pr +files --owner chroe --repo gitlink-cli --id <pr-id> --format json
|
||||
```
|
||||
|
||||
AI Review 要点：
|
||||
1. SKILL.md 格式是否与 changelog/health/triage 一致
|
||||
2. REFERENCE.md 是否覆盖了所有 API 字段
|
||||
3. examples/ 中的输出是否为真实数据
|
||||
4. 是否有硬编码的敏感信息
|
||||
|
||||
### Step 7: 合并 PR
|
||||
|
||||
```bash
|
||||
# 确认 CI 通过（如果开启了 DevOps）
|
||||
# 合并（squash 方式，将多个 commit 压缩为一个）
|
||||
gitlink-cli pr +merge --owner chroe --repo gitlink-cli --id <pr-id> --do squash
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AI PR 流程状态摘要
|
||||
|
||||
```markdown
|
||||
## 🔀 PR 全流程状态
|
||||
|
||||
| 阶段 | 状态 | 详情 |
|
||||
|------|------|------|
|
||||
| 分支创建 | ✅ | feature/add-skills |
|
||||
| 代码提交 | ✅ | 8 个文件变更（+1200/-200） |
|
||||
| PR 创建 | ✅ | PR: "feat(skills): 新增 4 个 AI Agent Skill" |
|
||||
| Code Review | 🔍 | 待审查 |
|
||||
| 合并 | ⏳ | 等待 Review 通过 |
|
||||
|
||||
### 变更摘要
|
||||
|
||||
| 文件 | 操作 | 行数 |
|
||||
|------|------|------|
|
||||
| skills/gitlink-repo/SKILL.md | 重写 | +120 |
|
||||
| skills/gitlink-repo/REFERENCE.md | 新增 | +180 |
|
||||
| skills/gitlink-repo/examples/repo-health-check.md | 新增 | +150 |
|
||||
| skills/gitlink-org/SKILL.md | 重写 | +110 |
|
||||
| skills/gitlink-org/REFERENCE.md | 新增 | +160 |
|
||||
| skills/gitlink-org/examples/org-audit.md | 新增 | +140 |
|
||||
| skills/gitlink-ci/SKILL.md | 重写 | +120 |
|
||||
| skills/gitlink-ci/REFERENCE.md | 新增 | +170 |
|
||||
| skills/gitlink-ci/examples/ci-devops-check.md | 新增 | +130 |
|
||||
| skills/gitlink-workflow/SKILL.md | 重写 | +150 |
|
||||
| skills/gitlink-workflow/REFERENCE.md | 新增 | +190 |
|
||||
| skills/gitlink-workflow/examples/pr-workflow.md | 新增 | +140 |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **Fork 协作**：向 `Gitlink/gitlink-cli`（上游）提 PR 时，需要从 `chroe/gitlink-cli`（Fork）发起
|
||||
2. **分支保护**：当前 master 未保护，建议 `branch +protect --name master`
|
||||
3. **commit 规范**：使用 `feat(skills):` 前缀，与项目现有风格一致
|
||||
Loading…
Reference in New Issue