forked from Gitlink/gitlink-cli
完善 issue/pr/search/user/pm 五个 Skill，新增 Claude Code 启用脚本
- issue/pr：补充真实数据 examples（PR #1 全流程、6 个 Issue） - search/user/pm：重写 SKILL.md v2.0.0 + 新增 REFERENCE.md + examples - 新增 scripts/setup-skills.sh：把 skills/gitlink-* 链接到 ~/.claude/skills/， 使 Claude Code 可通过 Skill 工具直接调用（Windows junction / Unix symlink） - README 增补「在 Claude Code 中通过 Skill 工具调用」一节 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Martin
parent
5bec1e5bf1
commit
cd2cb11aad
|
|
@ -0,0 +1,79 @@
|
|||
#!/bin/bash
|
||||
# Link skills/gitlink-* into ~/.claude/skills/ so Claude Code can load and
|
||||
# invoke them through the Skill tool (e.g. `Skill gitlink-issue`).
|
||||
#
|
||||
# Cross-platform:
|
||||
# - Windows (Git Bash / MSYS): directory junction (mklink /J, no admin needed)
|
||||
# - macOS / Linux: symlink
|
||||
#
|
||||
# Links point at the in-repo skills/ directory, so updating the repo keeps the
|
||||
# Skill content in sync. The script is idempotent and safe to re-run.
|
||||
#
|
||||
# CRITICAL (Windows): an existing link is removed with `rmdir` (no /s), never
|
||||
# `rm -rf` — `rm -rf` would follow the junction and DELETE THE SOURCE FILES.
|
||||
|
||||
set -e
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
SRC="$PROJECT_DIR/skills"
|
||||
DST="$HOME/.claude/skills"
|
||||
|
||||
# --- collect gitlink-* skills ---
|
||||
shopt -s nullglob
|
||||
SKILLS=("$SRC"/gitlink-*/)
|
||||
shopt -u nullglob
|
||||
if [ ${#SKILLS[@]} -eq 0 ]; then
|
||||
echo "No gitlink-* skills found under $SRC" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
mkdir -p "$DST"
|
||||
|
||||
# --- detect platform ---
|
||||
case "$(uname -s)" in
|
||||
MINGW*|MSYS*|CYGWIN*) PLATFORM=windows ;;
|
||||
*) PLATFORM=unix ;;
|
||||
esac
|
||||
|
||||
OK=0
|
||||
FAIL=0
|
||||
|
||||
for skill in "${SKILLS[@]}"; do
|
||||
skill="${skill%/}" # strip trailing slash for clean paths
|
||||
name="$(basename "$skill")"
|
||||
link="$DST/$name"
|
||||
|
||||
if [ "$PLATFORM" = "windows" ]; then
|
||||
win_link="$(cygpath -w "$link")"
|
||||
win_src="$(cygpath -w "$skill")"
|
||||
|
||||
if [ -e "$link" ] || [ -L "$link" ]; then
|
||||
# rmdir (no /s) removes only the junction/symlink, never the target.
|
||||
if ! cmd //c rmdir "$win_link" >/dev/null 2>&1; then
|
||||
echo "SKIP $name (existing path is not a link — left untouched)"
|
||||
FAIL=$((FAIL+1)); continue
|
||||
fi
|
||||
fi
|
||||
|
||||
if powershell -NoProfile -Command \
|
||||
"New-Item -ItemType Junction -Path '$win_link' -Target '$win_src' -ErrorAction Stop" \
|
||||
>/dev/null 2>&1; then
|
||||
echo "OK $name"; OK=$((OK+1))
|
||||
else
|
||||
echo "FAIL $name"; FAIL=$((FAIL+1))
|
||||
fi
|
||||
else
|
||||
# ln -sfn replaces an existing symlink safely (does not follow it).
|
||||
if ln -sfn "$skill" "$link"; then
|
||||
echo "OK $name"; OK=$((OK+1))
|
||||
else
|
||||
echo "FAIL $name"; FAIL=$((FAIL+1))
|
||||
fi
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "Done: $OK linked, $FAIL failed."
|
||||
echo "Target: $DST"
|
||||
echo "Skills are now invocable via the Claude Code Skill tool."
|
||||
|
|
@ -328,6 +328,23 @@ AI 代理可以：
|
|||
|
||||
---
|
||||
|
||||
## 🤖 在 Claude Code 中通过 Skill 工具调用
|
||||
|
||||
默认情况下，这些 Skill 以**文档驱动**方式使用：AI 代理读取 `SKILL.md` 后执行 `gitlink-cli` 命令（见上文流程图）。
|
||||
|
||||
若希望像标准 Skill 一样，由 Claude Code 的 **Skill 工具**直接加载并调用（例如 `Skill gitlink-issue`），需要把 `skills/gitlink-*` 链接到 Claude Code 扫描的 `~/.claude/skills/` 目录。
|
||||
|
||||
仓库提供一键脚本，自动检测平台并创建链接（**Windows 用目录联接 junction，无需管理员权限；macOS/Linux 用 symlink**），均指向仓库内的 `skills/`，更新仓库后内容自动同步：
|
||||
|
||||
```bash
|
||||
# 在仓库根目录执行（Windows 需 Git Bash 或 WSL）
|
||||
bash scripts/setup-skills.sh
|
||||
```
|
||||
|
||||
执行后即可在 Claude Code 中通过 Skill 工具调用任意 `gitlink-*` Skill。脚本可重复执行，会安全更新已有链接——移除时只删 junction/symlink 本身，**不会影响 `skills/` 下的源文件**。
|
||||
|
||||
---
|
||||
|
||||
## 📊 测试状态
|
||||
|
||||
✅ **生产就绪** (8.5/10)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,163 @@
|
|||
# 示例：Issue 全流程管理（真实数据）
|
||||
|
||||
> 本示例基于 `chroe/gitlink-cli` 项目于 2026-06-13 在 Claude Code 中实际执行。
|
||||
> 展示完整的 Issue 管理流程：列出 → 查看详情 → 添加评论 → 关闭。
|
||||
|
||||
---
|
||||
|
||||
## 场景：项目维护者日常 Issue 处理
|
||||
|
||||
### Step 1：查看全部 Issue
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +list --owner chroe --repo gitlink-cli --state open --format json
|
||||
```
|
||||
|
||||
**真实输出摘要（2026-06-13 验证，全部已关闭）：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"opened_count": 0,
|
||||
"closed_count": 6,
|
||||
"total_count": 6,
|
||||
"issues": [
|
||||
{
|
||||
"project_issues_index": 6,
|
||||
"subject": "安装模块改进：CI版本修复、FreeBSD渠道、Windows凭据路径、去除重复文件",
|
||||
"author": { "login": "caoweiqiong", "name": "CWQ" },
|
||||
"status": { "id": 5, "name": "关闭" },
|
||||
"created_at": "2026-06-03 21:03"
|
||||
},
|
||||
{
|
||||
"project_issues_index": 5,
|
||||
"subject": "feat: 新增 file/member/watch/star 四大 Shortcut 模块（15 个命令）",
|
||||
"author": { "login": "caoweiqiong", "name": "CWQ" },
|
||||
"status": { "id": 5, "name": "关闭" },
|
||||
"created_at": "2026-05-31 08:55"
|
||||
},
|
||||
{
|
||||
"project_issues_index": 4,
|
||||
"subject": "增加milestone/webhook/label/commit Shortcut模块（共20条命令）",
|
||||
"author": { "login": "chroe", "name": "chroe" },
|
||||
"status": { "id": 5, "name": "关闭" },
|
||||
"created_at": "2026-05-28 14:36"
|
||||
},
|
||||
{
|
||||
"project_issues_index": 3,
|
||||
"subject": "table 输出格式优化",
|
||||
"author": { "login": "yetja", "name": "yetja" },
|
||||
"status": { "id": 5, "name": "关闭" },
|
||||
"comment_journals_count": 4,
|
||||
"created_at": "2026-05-26 15:08"
|
||||
},
|
||||
{
|
||||
"project_issues_index": 2,
|
||||
"subject": "新增批量 Issue 操作命令（batch-assign，batch-label，batch-milestone）",
|
||||
"author": { "login": "yetja", "name": "yetja" },
|
||||
"status": { "id": 5, "name": "关闭" },
|
||||
"comment_journals_count": 4,
|
||||
"created_at": "2026-05-25 11:01"
|
||||
},
|
||||
{
|
||||
"project_issues_index": 1,
|
||||
"subject": "test",
|
||||
"author": { "login": "yetja", "name": "yetja" },
|
||||
"status": { "id": 5, "name": "关闭" },
|
||||
"comment_journals_count": 8,
|
||||
"created_at": "2026-05-22 11:48"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**分析：** 6 个 Issue 全部已关闭（关闭率 100%）。#1-3 由 yetja 创建，#4 由 chroe 创建，#5-6 由 CWQ 创建。
|
||||
|
||||
### Step 2：查看已关闭 Issue（了解处理模式）
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +list --owner chroe --repo gitlink-cli --state closed --format json
|
||||
```
|
||||
|
||||
返回结果与 Step 1 相同（所有 6 个 Issue 均已关闭）。#1-3 有 4-8 条评论互动，#4-6 无评论。
|
||||
|
||||
### Step 3：查看 Issue 详情（含评论）
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +view --owner chroe --repo gitlink-cli --number 3 --format json
|
||||
```
|
||||
|
||||
**真实输出摘要：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"id": 142892,
|
||||
"project_issues_index": 3,
|
||||
"subject": "table 输出格式优化",
|
||||
"description": "改进已有的 table 输出，让 list 命令用 `--format table` 时显示更美观",
|
||||
"status": { "id": 5, "name": "关闭" },
|
||||
"priority": { "id": 2, "name": "正常" },
|
||||
"author": { "login": "yetja", "name": "yetja" },
|
||||
"assigners": [{ "login": "yetja", "name": "yetja" }],
|
||||
"tags": [{ "id": 323830, "name": "功能", "color": "#ee955a" }],
|
||||
"created_at": "2026-05-26 15:08",
|
||||
"updated_at": "2026-06-08 12:30",
|
||||
"due_date": "2026-06-08",
|
||||
"comment_journals_count": 4,
|
||||
"participants": [
|
||||
{ "login": "yetja", "name": "yetja" },
|
||||
{ "login": "chroe", "name": "chroe" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4：获取 Issue 评论（Raw API）
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET /v1/chroe/gitlink-cli/issues/3/journals
|
||||
```
|
||||
|
||||
评论列表用于了解 Issue 讨论进展，计算首次响应时间。
|
||||
|
||||
### Step 5：添加评论并关闭 Issue
|
||||
|
||||
```bash
|
||||
# 对开放 Issue 添加处理评论
|
||||
gitlink-cli issue +comment --owner chroe --repo gitlink-cli --number 5 --body "已确认收到，将在下一迭代处理"
|
||||
|
||||
# 关闭已完成的 Issue
|
||||
gitlink-cli issue +close --owner chroe --repo gitlink-cli --number 5
|
||||
```
|
||||
|
||||
### Step 6：批量操作（预览模式）
|
||||
|
||||
```bash
|
||||
# 预览批量关闭（不实际执行）
|
||||
gitlink-cli issue +batch-close --owner chroe --repo gitlink-cli --numbers 4,5,6 --dry-run
|
||||
|
||||
# 确认后执行
|
||||
gitlink-cli issue +batch-close --owner chroe --repo gitlink-cli --numbers 4,5,6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键发现
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 总 Issue 数 | 6 |
|
||||
| 开放 / 关闭 | 0 / 6 |
|
||||
| 关闭率 | 100% |
|
||||
| 平均评论数（#1-3） | 5.3 条 |
|
||||
| 平均解决周期（#1-3） | ~10.7 天 |
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. `--number` 参数是网页 URL 中的序号（`project_issues_index`），不是数据库内部 ID
|
||||
2. 已关闭 Issue 仍有评论互动，说明团队有 Issue 跟进习惯
|
||||
3. 开放 Issue 均无评论，建议及时响应以改善 Issue 健康度
|
||||
|
|
@ -0,0 +1,123 @@
|
|||
# gitlink-pm 参考手册
|
||||
|
||||
> 本文档定义项目管理相关命令的字段映射和 API 说明。
|
||||
|
||||
---
|
||||
|
||||
## 一、里程碑 API 字段
|
||||
|
||||
### milestone +list 返回字段
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"total_count": 4,
|
||||
"opening_milestone_count": 4,
|
||||
"closed_milestone_count": 0,
|
||||
"milestones": [
|
||||
{
|
||||
"id": 2761,
|
||||
"name": "v2.0",
|
||||
"description": "新里程碑",
|
||||
"effective_date": "2026-07-01",
|
||||
"status": "open",
|
||||
"issues_count": 0,
|
||||
"close_issues_count": 0,
|
||||
"opened_issues_count": 0,
|
||||
"percent": 0,
|
||||
"created_at": "2026-05-28 17:07",
|
||||
"updated_on": "2026-05-28 17:07"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | int | 里程碑 ID（创建 Issue 时传给 `--milestone`） |
|
||||
| `name` | string | 里程碑名称 |
|
||||
| `description` | string/null | 里程碑描述 |
|
||||
| `effective_date` | string/null | 截止日期 |
|
||||
| `status` | string | "open" 或 "closed" |
|
||||
| `issues_count` | int | 关联的 Issue 总数 |
|
||||
| `close_issues_count` | int | 已关闭 Issue 数 |
|
||||
| `opened_issues_count` | int | 开放 Issue 数 |
|
||||
| `percent` | int | 完成百分比 |
|
||||
|
||||
### 标签 API 字段
|
||||
|
||||
### label +list 返回字段
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"total_count": 13,
|
||||
"issue_tags": [
|
||||
{
|
||||
"id": 323830,
|
||||
"name": "功能",
|
||||
"color": "#ee955a",
|
||||
"description": "表示新功能申请",
|
||||
"issues_count": 0,
|
||||
"created_at": "2026-05-21 16:54"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | int | 标签 ID |
|
||||
| `name` | string | 标签名称 |
|
||||
| `color` | string | 标签颜色（Hex） |
|
||||
| `description` | string | 标签说明 |
|
||||
| `issues_count` | int | 关联的 Issue 数 |
|
||||
|
||||
---
|
||||
|
||||
## 二、PM 模块 API 端点
|
||||
|
||||
> 以下端点需要项目开启 DevOps/PM 模块（`open_devops: true`）。
|
||||
|
||||
| 端点 | 方法 | 说明 |
|
||||
|------|------|------|
|
||||
| `/pm/dashboards` | GET | 项目看板 |
|
||||
| `/pm/sprint_issues` | GET | Sprint Issue 列表 |
|
||||
| `/pm/weekly_issues` | GET | 周报 Issue |
|
||||
| `/pm/issue_tags` | GET | PM Issue 标签 |
|
||||
| `/pm/pipelines` | GET | 流水线列表 |
|
||||
| `/pm/action_runs` | GET | Action 运行记录 |
|
||||
|
||||
所有 PM 端点都需要 `project_id` 参数：
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET /pm/dashboards --query 'project_id=1547045'
|
||||
```
|
||||
|
||||
### 未开启 PM 模块的表现
|
||||
|
||||
如果项目未开启 PM 模块，API 返回 HTML 页面而非 JSON，这是正常的——说明该功能未激活。
|
||||
|
||||
---
|
||||
|
||||
## 三、轻量项目管理替代方案
|
||||
|
||||
未开启 PM 的项目，可用 milestone + label + issue 组合：
|
||||
|
||||
| PM 功能 | 替代方案 |
|
||||
|---------|---------|
|
||||
| Sprint | `milestone +create` 创建 Sprint 命名的里程碑 |
|
||||
| 看板 | `issue +list --state open` + 标签过滤 |
|
||||
| 标签分类 | `label +create` + `issue +update --label` |
|
||||
| 进度跟踪 | `milestone +list` 查看 percent 字段 |
|
||||
|
||||
## 四、获取 project_id
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
# "project_id": 1547045
|
||||
```
|
||||
|
|
@ -1,46 +1,85 @@
|
|||
---
|
||||
name: gitlink-pm
|
||||
version: 1.0.0
|
||||
description: "项目管理（PM）：Sprint、看板、周报等项目管理功能。当用户需要使用 GitLink PM 功能时触发。"
|
||||
version: 2.0.0
|
||||
description: "项目管理（PM）：里程碑、看板、周报等项目管理功能。当用户需要使用 GitLink 项目管理功能、Sprint 管理或里程碑跟踪时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli pm --help"
|
||||
cliHelp: "gitlink-cli --help"
|
||||
---
|
||||
|
||||
# gitlink-pm（项目管理）
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
|
||||
|
||||
GitLink PM 模块提供敏捷项目管理能力，目前通过 Raw API 访问。
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
|
||||
## API 端点
|
||||
## 概述
|
||||
|
||||
> 前缀：`/api/pm`
|
||||
本 Skill 提供 GitLink 项目管理能力，主要通过两种方式：
|
||||
1. **Shortcut 命令**：里程碑（milestone）和标签（label）管理，所有项目均可用
|
||||
2. **Raw API（PM 模块）**：看板、Sprint、周报等高级功能，需要项目开启 PM 模块（`open_devops: true`）
|
||||
|
||||
## 可用命令
|
||||
|
||||
### 里程碑管理（所有项目可用）
|
||||
|
||||
```bash
|
||||
# 列出里程碑
|
||||
gitlink-cli milestone +list --owner chroe --repo gitlink-cli --format json
|
||||
|
||||
# 创建里程碑
|
||||
gitlink-cli milestone +create --owner chroe --repo gitlink-cli --name "Sprint 3" --due-date "2026-07-01"
|
||||
|
||||
# 查看里程碑详情
|
||||
gitlink-cli milestone +view --owner chroe --repo gitlink-cli --id <milestone_id>
|
||||
```
|
||||
|
||||
### 标签管理（所有项目可用）
|
||||
|
||||
```bash
|
||||
# 列出标签
|
||||
gitlink-cli label +list --owner chroe --repo gitlink-cli --format json
|
||||
|
||||
# 创建标签
|
||||
gitlink-cli label +create --owner chroe --repo gitlink-cli --name "bug" --color "#ff0000"
|
||||
```
|
||||
|
||||
### PM 模块（需要开启 DevOps）
|
||||
|
||||
> ⚠️ 以下 API 需要项目开启 PM 模块。未开启时返回 HTML 页面而非 JSON。
|
||||
|
||||
```bash
|
||||
# 检查项目是否开启 PM 模块
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
# 查看返回中 "open_devops": true/false
|
||||
|
||||
# 看板
|
||||
gitlink-cli api GET /pm/dashboards --query 'project_id=123'
|
||||
gitlink-cli api GET /pm/dashboards --query 'project_id=<id>'
|
||||
|
||||
# Sprint Issue 列表
|
||||
gitlink-cli api GET /pm/sprint_issues --query 'project_id=123'
|
||||
gitlink-cli api GET /pm/sprint_issues --query 'project_id=<id>'
|
||||
|
||||
# 周报
|
||||
gitlink-cli api GET /pm/weekly_issues --query 'project_id=123'
|
||||
gitlink-cli api GET /pm/weekly_issues --query 'project_id=<id>'
|
||||
|
||||
# Issue 标签
|
||||
gitlink-cli api GET /pm/issue_tags --query 'project_id=123'
|
||||
gitlink-cli api GET /pm/issue_tags --query 'project_id=<id>'
|
||||
```
|
||||
|
||||
# 流水线
|
||||
gitlink-cli api GET /pm/pipelines --query 'project_id=123'
|
||||
## 获取 project_id
|
||||
|
||||
# Action 运行记录
|
||||
gitlink-cli api GET /pm/action_runs --query 'project_id=123'
|
||||
PM 模块需要数字 `project_id`，而非 owner/repo 格式：
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner chroe --repo gitlink-cli --format json
|
||||
# 返回 "project_id": 1547045
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- PM 接口需要项目 ID（`project_id`），可通过 `repo +info` 获取
|
||||
- PM 功能需要项目开启 PM 模块
|
||||
- PM 模块端点（`/pm/*`）需要在项目设置中开启 DevOps/PM 功能
|
||||
- 未开启 PM 的项目应使用 milestone + label + issue 组合实现轻量项目管理
|
||||
- `project_id` 是数字 ID，与 `repo_id` 不同
|
||||
- 详见 [`REFERENCE.md`](REFERENCE.md) 了解字段映射
|
||||
|
|
|
|||
|
|
@ -0,0 +1,132 @@
|
|||
# 示例：项目管理流程（真实数据）
|
||||
|
||||
> 本示例基于 `chroe/gitlink-cli` 项目于 2026-06-13 在 Claude Code 中实际执行。
|
||||
> 展示轻量项目管理流程：里程碑 → 标签 → Issue 关联。
|
||||
> 注：chroe/gitlink-cli 未开启 PM 模块（`open_devops: false`），因此使用 milestone + label 替代。
|
||||
|
||||
---
|
||||
|
||||
## 场景：项目维护者查看项目管理状态
|
||||
|
||||
### Step 1：检查项目是否开启 PM 模块
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner chroe --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
**关键字段：**
|
||||
|
||||
```json
|
||||
{
|
||||
"open_devops": false,
|
||||
"project_id": 1547045
|
||||
}
|
||||
```
|
||||
|
||||
**结论：** PM 模块未开启，使用 milestone + label 进行轻量管理。
|
||||
|
||||
### Step 2：查看里程碑
|
||||
|
||||
```bash
|
||||
gitlink-cli milestone +list --owner chroe --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
**真实输出：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"total_count": 1,
|
||||
"opening_milestone_count": 1,
|
||||
"closed_milestone_count": 0,
|
||||
"milestones": [
|
||||
{
|
||||
"id": 2761,
|
||||
"name": "v2.0",
|
||||
"description": "新里程碑",
|
||||
"effective_date": "2026-07-01",
|
||||
"status": "open",
|
||||
"issues_count": 0,
|
||||
"percent": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**分析：** 仅剩 1 个活跃里程碑 `v2.0`（截止日期 2026-07-01），无 Issue 关联。测试用里程碑已清理。
|
||||
|
||||
### Step 3：查看标签分类
|
||||
|
||||
```bash
|
||||
gitlink-cli label +list --owner chroe --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
**真实输出摘要：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"total_count": 13,
|
||||
"issue_tags": [
|
||||
{ "id": 323829, "name": "缺陷", "color": "#d92d4c", "description": "表示存在意外问题或错误" },
|
||||
{ "id": 323830, "name": "功能", "color": "#ee955a", "description": "表示新功能申请" },
|
||||
{ "id": 323831, "name": "疑问", "color": "#2d6ddc", "description": "表示存在疑惑" },
|
||||
{ "id": 323832, "name": "支持", "color": "#019549", "description": "表示特定功能或特定需求" },
|
||||
{ "id": 323833, "name": "任务", "color": "#c1a30d", "description": "表示需要分配的任务" },
|
||||
{ "id": 323837, "name": "测试", "color": "#2897b9", "description": "表示需要测试的需求" },
|
||||
{ "id": 323838, "name": "重复", "color": "#bb5332", "description": "表示已存在类似的疑修" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**分析：** 项目有 13 个标签，覆盖缺陷/功能/疑问/支持/任务/文档/测试/重复等分类，但当前无 Issue 使用标签。
|
||||
|
||||
### Step 4：验证 PM API（确认不可用）
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET /pm/dashboards --query 'project_id=1547045'
|
||||
```
|
||||
|
||||
**结果：** 返回 HTML 页面（而非 JSON），确认 PM 模块未激活。
|
||||
|
||||
### Step 5：轻量管理实践
|
||||
|
||||
```bash
|
||||
# 创建新里程碑用于 Sprint
|
||||
gitlink-cli milestone +create --owner chroe --repo gitlink-cli \
|
||||
--name "Sprint-3" --due-date "2026-06-30"
|
||||
|
||||
# 创建标签
|
||||
gitlink-cli label +create --owner chroe --repo gitlink-cli \
|
||||
--name "good-first-issue" --color "#7057ff"
|
||||
|
||||
# 创建 Issue 并关联里程碑
|
||||
gitlink-cli issue +create --owner chroe --repo gitlink-cli \
|
||||
--title "新人任务：修复 README 拼写错误" \
|
||||
--body "适合首次贡献者，修改 README.md 中的拼写错误"
|
||||
|
||||
# 查看进度
|
||||
gitlink-cli milestone +list --owner chroe --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 轻量管理 vs PM 模块对比
|
||||
|
||||
| 功能 | 轻量管理（所有项目） | PM 模块（需开启） |
|
||||
|------|---------------------|-------------------|
|
||||
| Sprint | milestone 命名 | `/pm/sprint_issues` |
|
||||
| 看板 | issue +list + label | `/pm/dashboards` |
|
||||
| 标签分类 | label +create | `/pm/issue_tags` |
|
||||
| 周报 | issue +list + 时间筛选 | `/pm/weekly_issues` |
|
||||
| 进度 | milestone percent | 看板视图 |
|
||||
|
||||
## 改进建议
|
||||
|
||||
1. 将现有 Issue 关联到对应里程碑（目前 4 个里程碑均无 Issue）
|
||||
2. 为开放 Issue 打标签（#4 #5 #6 均未使用标签）
|
||||
3. 定期关闭已完成的里程碑
|
||||
|
|
@ -0,0 +1,205 @@
|
|||
# 示例：Pull Request 完整生命周期（真实数据）
|
||||
|
||||
> 本示例基于 `chroe/gitlink-cli` 项目于 2026-06-13 在 Claude Code 中实际执行。
|
||||
> 展示完整的 PR 工作流：创建分支 → 推送 → 创建 PR → 查看详情 → 评论 → 合并。
|
||||
|
||||
---
|
||||
|
||||
## Step 1：创建特性分支并提交
|
||||
|
||||
```bash
|
||||
# 从最新 master 创建分支
|
||||
git checkout -b test/pr-workflow-demo
|
||||
|
||||
# 做一个小改动
|
||||
echo "> This line is for PR workflow testing." >> README.md
|
||||
git add README.md
|
||||
git commit -m "test: PR workflow demo for skill documentation"
|
||||
```
|
||||
|
||||
### Step 2：推送分支到远程
|
||||
|
||||
```bash
|
||||
git push origin test/pr-workflow-demo
|
||||
```
|
||||
|
||||
### Step 3：创建 PR
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +create \
|
||||
--owner chroe --repo gitlink-cli \
|
||||
--title "test: PR workflow demo for skill documentation" \
|
||||
--body "## 目的\n\n创建测试 PR，用于 gitlink-pr Skill 的 examples 文档编写。\n\n## 改动\n\n在 README.md 末尾添加一行测试文本。" \
|
||||
--head test/pr-workflow-demo \
|
||||
--base master \
|
||||
--format json
|
||||
```
|
||||
|
||||
**真实输出：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"id": 144232,
|
||||
"pull_request_number": 1,
|
||||
"pull_request_id": 15694,
|
||||
"name": "test: PR workflow demo for skill documentation",
|
||||
"pull_request_status": 0,
|
||||
"pull_request_staus": "open",
|
||||
"pull_request_base": "master",
|
||||
"pull_request_head": "test/pr-workflow-demo",
|
||||
"author_login": "caoweiqiong",
|
||||
"author_name": "CWQ",
|
||||
"pr_time": "1分钟前"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**关键字段：**
|
||||
- `pull_request_number`: 1 — 即网页 URL 中的序号（`/pulls/1`）
|
||||
- `pull_request_status`: 0=Open, 1=Merged, 2=Closed
|
||||
|
||||
### Step 4：查看 PR 详情
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +view --owner chroe --repo gitlink-cli --id 1 --format json
|
||||
```
|
||||
|
||||
**真实输出摘要：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"author": {
|
||||
"id": 141645,
|
||||
"login": "caoweiqiong",
|
||||
"name": "CWQ"
|
||||
},
|
||||
"commits_count": 1,
|
||||
"files_count": 1,
|
||||
"comments_count": 0,
|
||||
"issue": {
|
||||
"subject": "test: PR workflow demo for skill documentation",
|
||||
"description": "## 目的\n\n创建测试 PR...",
|
||||
"created_at": "2026-06-13 10:15",
|
||||
"issue_status": "新增"
|
||||
},
|
||||
"pull_request": {
|
||||
"base": "master",
|
||||
"head": "test/pr-workflow-demo",
|
||||
"mergeable": true,
|
||||
"merged": false,
|
||||
"merged_at": null,
|
||||
"merge_commit_sha": null,
|
||||
"pull_request_staus": "open",
|
||||
"status": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5：查看变更文件
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +files --owner chroe --repo gitlink-cli --id 1
|
||||
```
|
||||
|
||||
**真实输出摘要：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"total_addition": 2,
|
||||
"total_deletion": 0,
|
||||
"files_count": 1,
|
||||
"files": [
|
||||
{
|
||||
"name": "README.md",
|
||||
"addition": 2,
|
||||
"deletion": 0,
|
||||
"sha": "60cb293913b8051cd9456457d93165ac1b2ff3ce"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 6：添加评论
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +comment --owner chroe --repo gitlink-cli --id 1 \
|
||||
--body "LGTM — 测试 PR，准备合并以采集 Skill 文档所需的真实数据。"
|
||||
```
|
||||
|
||||
**真实输出：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"id": 475956,
|
||||
"notes": "LGTM — 测试 PR，准备合并以采集 Skill 文档所需的真实数据。",
|
||||
"created_at": "2026-06-13 10:15",
|
||||
"user": { "login": "caoweiqiong", "name": "CWQ" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 7：合并 PR
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +merge --owner chroe --repo gitlink-cli --id 1
|
||||
```
|
||||
|
||||
**真实输出：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"message": "合并成功",
|
||||
"status": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 8：确认合并后状态
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +view --owner chroe --repo gitlink-cli --id 1 --format json
|
||||
```
|
||||
|
||||
**合并后关键字段变化：**
|
||||
|
||||
```json
|
||||
{
|
||||
"pull_request": {
|
||||
"merged": true,
|
||||
"merged_at": "2026-06-13T10:17:07+08:00",
|
||||
"merge_commit_sha": "5bec1e5bf140915162baa65f3fb3a53f725e7c0c",
|
||||
"pull_request_staus": "merged",
|
||||
"status": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PR 状态值映射
|
||||
|
||||
| `pull_request_status` | `pull_request_staus` | 含义 |
|
||||
|:---:|---|---|
|
||||
| 0 | open | 开放中 |
|
||||
| 1 | merged | 已合并 |
|
||||
| 2 | closed | 已关闭（未合并） |
|
||||
|
||||
## 关键注意事项
|
||||
|
||||
1. **`--id` 参数**：使用 `pull_request_number`（网页 URL `/pulls/N` 中的序号），不是数据库内部 ID
|
||||
2. **`--head` 格式**：同仓库内直接用分支名（如 `test/pr-workflow-demo`）；跨仓库 Fork PR 用 `用户名:分支名`
|
||||
3. **`--base` 默认分支**：GitLink 通常用 `master`，不是 `main`
|
||||
4. **PR 必须有代码差异**：源分支和目标分支内容相同时无法创建
|
||||
5. **合并前建议**：先用 `pr +view` 确认 `mergeable: true`
|
||||
|
|
@ -0,0 +1,88 @@
|
|||
# gitlink-search 参考手册
|
||||
|
||||
> 本文档定义搜索相关命令的 API 字段映射。
|
||||
|
||||
---
|
||||
|
||||
## 一、search +repos 返回字段
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"projects": [
|
||||
{
|
||||
"id": 1513956,
|
||||
"identifier": "gitlink-cli",
|
||||
"name": "gitlink-cli",
|
||||
"description": "GitLink CLI - GitLink 平台命令行工具",
|
||||
"author": {
|
||||
"login": "Gitlink",
|
||||
"name": "GitLink",
|
||||
"type": "Organization"
|
||||
},
|
||||
"language": { "id": 19, "name": "Go" },
|
||||
"forked_count": 31,
|
||||
"praises_count": 5,
|
||||
"visits": 2155,
|
||||
"is_public": true,
|
||||
"time_ago": "12小时前",
|
||||
"platform": "forge",
|
||||
"open_devops": false
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | int | 项目全局 ID（用于 Raw API） |
|
||||
| `identifier` | string | 仓库标识（即 repo 名） |
|
||||
| `name` | string | 仓库名 |
|
||||
| `description` | string | 项目描述 |
|
||||
| `author.login` | string | 所有者 login |
|
||||
| `author.type` | string | "User" 或 "Organization" |
|
||||
| `language.name` | string | 主要编程语言 |
|
||||
| `forked_count` | int | Fork 数 |
|
||||
| `praises_count` | int | Star/点赞数 |
|
||||
| `visits` | int | 访问量 |
|
||||
| `is_public` | bool | 是否公开 |
|
||||
| `time_ago` | string | 最后更新时间（相对） |
|
||||
|
||||
## 二、search +users 返回字段
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"total_count": 1,
|
||||
"users": [
|
||||
{
|
||||
"user_id": 149027,
|
||||
"login": "chroe",
|
||||
"username": "chroe",
|
||||
"image_url": "system/lets/letter_avatars/2/C/142_140_188/120.png",
|
||||
"profile_completed": false
|
||||
}
|
||||
]
|
||||
},
|
||||
"meta": {
|
||||
"total_count": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `user_id` | int | 用户全局 ID |
|
||||
| `login` | string | 登录名 |
|
||||
| `username` | string | 显示名 |
|
||||
| `profile_completed` | bool | 是否完善个人资料 |
|
||||
|
||||
## 三、参数说明
|
||||
|
||||
| 参数 | 命令 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `--keyword` / `-k` | +repos, +users | 是 | 搜索关键词 |
|
||||
| `--limit` | +repos | 否 | 返回数量限制 |
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: gitlink-search
|
||||
version: 1.0.0
|
||||
description: "搜索：搜索仓库和用户。当用户需要在 GitLink 上搜索资源时触发。"
|
||||
version: 2.0.0
|
||||
description: "搜索：搜索仓库和用户。当用户需要在 GitLink 上搜索项目、发现用户或查找资源时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
|
|
@ -11,24 +11,61 @@ metadata:
|
|||
# gitlink-search（搜索操作）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
|
||||
**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) 了解认证和全局参数。
|
||||
|
||||
## 概述
|
||||
|
||||
本 Skill 提供 GitLink 平台的全局搜索能力，主要用于：
|
||||
1. **仓库搜索**：按关键词搜索公开仓库，了解项目热度
|
||||
2. **用户搜索**：按用户名查找用户，获取 user_id
|
||||
3. **资源发现**：在开始协作前搜索相关项目和参与者
|
||||
|
||||
## Shortcuts
|
||||
|
||||
| Shortcut | 说明 |
|
||||
|----------|------|
|
||||
| `search +repos` | 搜索仓库 |
|
||||
| `search +users` | 搜索用户 |
|
||||
| Shortcut | 说明 | 需要认证 |
|
||||
|----------|------|----------|
|
||||
| `search +repos` | 搜索仓库 | 否 |
|
||||
| `search +users` | 搜索用户 | 否 |
|
||||
|
||||
## 数据采集命令
|
||||
|
||||
### 搜索仓库
|
||||
|
||||
```bash
|
||||
# 按关键词搜索仓库
|
||||
gitlink-cli search +repos --keyword "gitlink" --limit 10 --format json
|
||||
|
||||
# 搜索特定语言的仓库
|
||||
gitlink-cli search +repos --keyword "machine learning" --limit 5 --format json
|
||||
```
|
||||
|
||||
### 搜索用户
|
||||
|
||||
```bash
|
||||
# 按用户名搜索
|
||||
gitlink-cli search +users --keyword "chroe" --format json
|
||||
```
|
||||
|
||||
## 使用示例
|
||||
|
||||
```bash
|
||||
# 搜索仓库
|
||||
gitlink-cli search +repos --keyword "machine learning" --limit 10
|
||||
# 搜索仓库（限制返回数量）
|
||||
gitlink-cli search +repos --keyword "gitlink" --limit 5 --format json
|
||||
|
||||
# 搜索用户
|
||||
gitlink-cli search +users --keyword "zhangsan"
|
||||
gitlink-cli search +users --keyword "zhangsan" --format json
|
||||
|
||||
# 搜索后进一步查看详情
|
||||
gitlink-cli repo +info --owner Gitlink --repo gitlink-cli --format json
|
||||
gitlink-cli user +info --login chroe --format json
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 搜索不需要认证（公开资源）
|
||||
- `--keyword` 为必填参数
|
||||
- `--limit` 控制返回数量，默认值较大时建议显式指定
|
||||
- 搜索结果中的 `id` 是项目/用户的全局 ID，不是 owner/repo 格式
|
||||
- 详见 [`REFERENCE.md`](REFERENCE.md) 了解返回字段
|
||||
|
|
|
|||
|
|
@ -0,0 +1,93 @@
|
|||
# 示例：搜索仓库和用户（真实数据）
|
||||
|
||||
> 本示例于 2026-06-13 在 Claude Code 中实际执行。
|
||||
> 展示搜索仓库和用户的完整流程，以及如何基于搜索结果深入查看。
|
||||
|
||||
---
|
||||
|
||||
## 场景：在 GitLink 上搜索 gitlink-cli 项目和相关用户
|
||||
|
||||
### Step 1：搜索仓库
|
||||
|
||||
```bash
|
||||
gitlink-cli search +repos --keyword "gitlink" --limit 5 --format json
|
||||
```
|
||||
|
||||
**真实输出摘要：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"projects": [
|
||||
{
|
||||
"id": 1513956,
|
||||
"identifier": "gitlink-cli",
|
||||
"name": "gitlink-cli",
|
||||
"description": "GitLink CLI - GitLink 平台命令行工具",
|
||||
"author": {
|
||||
"login": "Gitlink",
|
||||
"name": "GitLink",
|
||||
"type": "Organization"
|
||||
},
|
||||
"language": { "name": "Go" },
|
||||
"forked_count": 31,
|
||||
"praises_count": 5,
|
||||
"visits": 2155,
|
||||
"is_public": true,
|
||||
"time_ago": "12小时前"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**发现：** Gitlink/gitlink-cli 是原始仓库，有 31 个 Fork、5 个 Star、2155 次访问。
|
||||
|
||||
### Step 2：搜索用户
|
||||
|
||||
```bash
|
||||
gitlink-cli search +users --keyword "chroe" --format json
|
||||
```
|
||||
|
||||
**真实输出：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"total_count": 1,
|
||||
"users": [
|
||||
{
|
||||
"user_id": 149027,
|
||||
"login": "chroe",
|
||||
"username": "chroe",
|
||||
"image_url": "system/lets/letter_avatars/2/C/142_140_188/120.png",
|
||||
"profile_completed": false
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**确认：** chroe 的 user_id 为 149027。
|
||||
|
||||
### Step 3：基于搜索结果深入查看
|
||||
|
||||
```bash
|
||||
# 查看搜索到的仓库详情
|
||||
gitlink-cli repo +info --owner Gitlink --repo gitlink-cli --format json
|
||||
|
||||
# 查看搜索到的用户详情
|
||||
gitlink-cli user +info --login chroe --format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 典型搜索场景
|
||||
|
||||
| 场景 | 命令 |
|
||||
|------|------|
|
||||
| 查找同类项目 | `search +repos --keyword "cli"` |
|
||||
| 查找特定用户 | `search +users --keyword "chroe"` |
|
||||
| 寻找协作项目 | `search +repos --keyword "gitlink" --limit 10` |
|
||||
|
|
@ -0,0 +1,107 @@
|
|||
# gitlink-user 参考手册
|
||||
|
||||
> 本文档定义用户相关命令的 API 字段映射和注意事项。
|
||||
|
||||
---
|
||||
|
||||
## 一、user +me 返回字段
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"user_id": 141645,
|
||||
"login": "caoweiqiong",
|
||||
"username": "CWQ",
|
||||
"email": "caoweiqiong@example.org",
|
||||
"phone": "18627370661",
|
||||
"admin": false,
|
||||
"image_url": "system/lets/letter_avatars/2/C/223_176_135/120.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `user_id` | int | 用户唯一 ID（用于批量操作中传参） |
|
||||
| `login` | string | 登录名（URL 路径中的标识） |
|
||||
| `username` | string | 显示名 |
|
||||
| `email` | string | 注册邮箱（仅本人可见） |
|
||||
| `phone` | string | 手机号（仅本人可见） |
|
||||
| `admin` | bool | 是否为平台管理员 |
|
||||
| `image_url` | string | 头像 URL |
|
||||
|
||||
## 二、user +info 返回字段
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"user_id": 149027,
|
||||
"login": "chroe",
|
||||
"name": "chroe",
|
||||
"real_name": "chroe",
|
||||
"user_identity": "专业人士",
|
||||
"created_time": "2026-04-30 11:41",
|
||||
"common_projects_count": 5,
|
||||
"user_projects_count": 5,
|
||||
"mirror_projects_count": 0,
|
||||
"user_org_count": 0,
|
||||
"watched_count": 0,
|
||||
"watching_count": 0,
|
||||
"description": null,
|
||||
"image_url": "system/lets/letter_avatars/2/C/142_140_188/120.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `user_id` | int | 用户唯一 ID |
|
||||
| `login` | string | 登录名 |
|
||||
| `name` | string | 显示名 |
|
||||
| `real_name` | string | 真实姓名 |
|
||||
| `user_identity` | string | 身份标识（"专业人士"、"开发者"等） |
|
||||
| `created_time` | string | 注册时间 |
|
||||
| `common_projects_count` | int | 参与的项目数 |
|
||||
| `user_projects_count` | int | 自己创建的项目数 |
|
||||
| `mirror_projects_count` | int | 镜像项目数 |
|
||||
| `user_org_count` | int | 所属组织数 |
|
||||
| `watched_count` | int | 被关注数 |
|
||||
| `watching_count` | int | 正在关注数 |
|
||||
| `description` | string/null | 个人简介 |
|
||||
|
||||
## 三、Raw API：搜索用户
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET /users/list --query 'search=chroe'
|
||||
```
|
||||
|
||||
返回用户列表，用于通过用户名查找 user_id：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"users": [
|
||||
{
|
||||
"id": 149027,
|
||||
"login": "chroe",
|
||||
"name": "chroe"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 四、常见问题
|
||||
|
||||
### Q: 如何获取 user_id？
|
||||
|
||||
A: 两种方式：
|
||||
1. `user +me --format json` → `data.user_id`（查自己）
|
||||
2. `api GET /users/list --query 'search=<login>'` → `data.users[0].id`（查他人）
|
||||
|
||||
### Q: 为什么 Raw API 的 /users/:id/headmaps 返回 HTML？
|
||||
|
||||
A: headmaps 和 statistics 是前端页面路由，不是 API 端点。用户相关可用的 API 端点只有 `/users/list` 和 `/users/:id`。
|
||||
|
|
@ -1,47 +1,76 @@
|
|||
---
|
||||
name: gitlink-user
|
||||
version: 1.0.0
|
||||
description: "用户操作：查看当前用户、用户详情。当用户需要查看 GitLink 用户信息时触发。"
|
||||
version: 2.0.0
|
||||
description: "用户信息查询：查看当前登录用户、查询用户详情、获取用户项目统计。当用户需要查看 GitLink 用户信息、验证认证状态或查询其他用户时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli user --help"
|
||||
---
|
||||
|
||||
# gitlink-user（用户操作）
|
||||
# gitlink-user（用户信息查询）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
|
||||
**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) 了解认证和全局参数。
|
||||
|
||||
## 概述
|
||||
|
||||
本 Skill 提供用户信息查询能力，主要用于：
|
||||
1. **认证验证**：通过 `user +me` 确认当前登录状态和用户身份
|
||||
2. **用户画像**：查询任意公开用户的详情（项目数、身份、注册时间等）
|
||||
3. **用户 ID 解析**：在批量操作中需要 user_id 时，通过 login 查询获取
|
||||
|
||||
## 数据采集命令
|
||||
|
||||
### 查看当前登录用户
|
||||
|
||||
```bash
|
||||
# 获取当前认证用户信息（需要登录）
|
||||
gitlink-cli user +me --format json
|
||||
```
|
||||
|
||||
### 查看指定用户详情
|
||||
|
||||
```bash
|
||||
# 通过 login 查询用户详情
|
||||
gitlink-cli user +info --login chroe --format json
|
||||
```
|
||||
|
||||
### Raw API 补充
|
||||
|
||||
```bash
|
||||
# 搜索用户（按用户名模糊匹配，返回含 user_id）
|
||||
gitlink-cli api GET /users/list --query 'search=chroe'
|
||||
|
||||
# 获取用户项目列表
|
||||
gitlink-cli api GET /users/:user_id/projects --query 'page=1&limit=10'
|
||||
```
|
||||
|
||||
## Shortcuts
|
||||
|
||||
| Shortcut | 说明 | 需要认证 |
|
||||
|----------|------|----------|
|
||||
| `user +me` | 当前登录用户 | 是 |
|
||||
| `user +info` | 查看用户详情 | 否 |
|
||||
| `user +info` | 查看用户详情 | 否（公开用户） |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```bash
|
||||
# 查看当前用户
|
||||
# 查看当前登录用户
|
||||
gitlink-cli user +me
|
||||
|
||||
# 查看其他用户
|
||||
gitlink-cli user +info --login zhangsan
|
||||
# 查看 chroe 用户详情
|
||||
gitlink-cli user +info --login chroe
|
||||
|
||||
# 搜索用户（获取 user_id 用于批量操作）
|
||||
gitlink-cli api GET /users/list --query 'search=chroe'
|
||||
```
|
||||
|
||||
## Raw API 补充
|
||||
## 注意事项
|
||||
|
||||
```bash
|
||||
# 用户贡献热力图
|
||||
gitlink-cli api GET /users/:user_id/headmaps
|
||||
|
||||
# 用户统计
|
||||
gitlink-cli api GET /users/:user_id/statistics
|
||||
|
||||
# 用户项目动态
|
||||
gitlink-cli api GET /users/:user_id/project_trends
|
||||
```
|
||||
- `user +me` 需要先 `auth login`，否则返回未认证错误
|
||||
- `user +info --login` 传入的是用户 login（URL 中的路径），不是 user_id
|
||||
- 部分用户信息字段（如 email）仅对本人可见
|
||||
- 详见 [`REFERENCE.md`](REFERENCE.md) 了解完整的字段映射
|
||||
|
|
|
|||
|
|
@ -0,0 +1,85 @@
|
|||
# 示例：用户信息查询（真实数据）
|
||||
|
||||
> 本示例基于 `chroe/gitlink-cli` 项目于 2026-06-13 在 Claude Code 中实际执行。
|
||||
> 展示用户信息查询的完整流程：认证验证 → 查看自己 → 查看他人 → 搜索用户 ID。
|
||||
|
||||
---
|
||||
|
||||
## 场景：项目维护者确认身份并查询团队成员信息
|
||||
|
||||
### Step 1：确认当前登录状态
|
||||
|
||||
```bash
|
||||
gitlink-cli user +me --format json
|
||||
```
|
||||
|
||||
**真实输出：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"user_id": 141645,
|
||||
"login": "caoweiqiong",
|
||||
"username": "CWQ",
|
||||
"email": "caoweiqiong@example.org",
|
||||
"phone": "18627370661",
|
||||
"admin": false,
|
||||
"image_url": "system/lets/letter_avatars/2/C/223_176_135/120.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**确认：** 当前以 `caoweiqiong`（CWQ）登录，user_id 为 141645。
|
||||
|
||||
### Step 2：查询项目维护者详情
|
||||
|
||||
```bash
|
||||
gitlink-cli user +info --login chroe --format json
|
||||
```
|
||||
|
||||
**真实输出：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"user_id": 149027,
|
||||
"login": "chroe",
|
||||
"name": "chroe",
|
||||
"real_name": "chroe",
|
||||
"user_identity": "专业人士",
|
||||
"created_time": "2026-04-30 11:41",
|
||||
"common_projects_count": 5,
|
||||
"user_projects_count": 5,
|
||||
"mirror_projects_count": 0,
|
||||
"user_org_count": 0,
|
||||
"watched_count": 0,
|
||||
"watching_count": 0,
|
||||
"description": null,
|
||||
"image_url": "system/lets/letter_avatars/2/C/142_140_188/120.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**分析：** chroe 的 user_id 为 149027，拥有 5 个项目，注册于 2026-04-30。
|
||||
|
||||
### Step 3：搜索用户（获取 user_id 用于批量操作）
|
||||
|
||||
在执行 `member +add` 等需要 user_id 的操作前，先搜索获取：
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET /users/list --query 'search=chroe'
|
||||
```
|
||||
|
||||
返回匹配用户的列表，从中提取 `id` 字段即可用于其他命令。
|
||||
|
||||
---
|
||||
|
||||
## 典型用途
|
||||
|
||||
| 场景 | 命令 |
|
||||
|------|------|
|
||||
| 验证认证是否生效 | `user +me` |
|
||||
| 查看团队成员信息 | `user +info --login <login>` |
|
||||
| 获取 user_id 用于 member/batch 操作 | `api GET /users/list --query 'search=<login>'` |
|
||||
Loading…
Reference in New Issue