gitlink-cli/skills/gitlink-user/REFERENCE.md

gitlink-user 参考手册

本文档定义用户相关命令的 API 字段映射和注意事项。

---

一、user +me 返回字段

{
  "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 返回字段

{
  "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：搜索用户

gitlink-cli api GET /users/list --query 'search=chroe'

返回用户列表，用于通过用户名查找 user_id：

{
  "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。