diff --git a/scripts/setup-skills.sh b/scripts/setup-skills.sh new file mode 100755 index 0000000..b74b2ee --- /dev/null +++ b/scripts/setup-skills.sh @@ -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." diff --git a/skills/README.md b/skills/README.md index dd23cd9..967a46a 100644 --- a/skills/README.md +++ b/skills/README.md @@ -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) diff --git a/skills/gitlink-issue/examples/issue-workflow.md b/skills/gitlink-issue/examples/issue-workflow.md new file mode 100644 index 0000000..b194427 --- /dev/null +++ b/skills/gitlink-issue/examples/issue-workflow.md @@ -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 健康度 diff --git a/skills/gitlink-pm/REFERENCE.md b/skills/gitlink-pm/REFERENCE.md new file mode 100644 index 0000000..d272091 --- /dev/null +++ b/skills/gitlink-pm/REFERENCE.md @@ -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 --repo --format json +# "project_id": 1547045 +``` diff --git a/skills/gitlink-pm/SKILL.md b/skills/gitlink-pm/SKILL.md index f5333ed..aa72d21 100644 --- a/skills/gitlink-pm/SKILL.md +++ b/skills/gitlink-pm/SKILL.md @@ -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 +``` + +### 标签管理（所有项目可用） + +```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 --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=' # Sprint Issue 列表 -gitlink-cli api GET /pm/sprint_issues --query 'project_id=123' +gitlink-cli api GET /pm/sprint_issues --query 'project_id=' # 周报 -gitlink-cli api GET /pm/weekly_issues --query 'project_id=123' +gitlink-cli api GET /pm/weekly_issues --query 'project_id=' # Issue 标签 -gitlink-cli api GET /pm/issue_tags --query 'project_id=123' +gitlink-cli api GET /pm/issue_tags --query 'project_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) 了解字段映射 diff --git a/skills/gitlink-pm/examples/pm-workflow.md b/skills/gitlink-pm/examples/pm-workflow.md new file mode 100644 index 0000000..12715db --- /dev/null +++ b/skills/gitlink-pm/examples/pm-workflow.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. 定期关闭已完成的里程碑 diff --git a/skills/gitlink-pr/examples/pr-workflow.md b/skills/gitlink-pr/examples/pr-workflow.md new file mode 100644 index 0000000..0ac0133 --- /dev/null +++ b/skills/gitlink-pr/examples/pr-workflow.md @@ -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` diff --git a/skills/gitlink-search/REFERENCE.md b/skills/gitlink-search/REFERENCE.md new file mode 100644 index 0000000..38a5184 --- /dev/null +++ b/skills/gitlink-search/REFERENCE.md @@ -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 | 否 | 返回数量限制 | diff --git a/skills/gitlink-search/SKILL.md b/skills/gitlink-search/SKILL.md index da2397b..f0c6bb1 100644 --- a/skills/gitlink-search/SKILL.md +++ b/skills/gitlink-search/SKILL.md @@ -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) 了解返回字段 diff --git a/skills/gitlink-search/examples/search-workflow.md b/skills/gitlink-search/examples/search-workflow.md new file mode 100644 index 0000000..1a17bd1 --- /dev/null +++ b/skills/gitlink-search/examples/search-workflow.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` | diff --git a/skills/gitlink-user/REFERENCE.md b/skills/gitlink-user/REFERENCE.md new file mode 100644 index 0000000..509fa04 --- /dev/null +++ b/skills/gitlink-user/REFERENCE.md @@ -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='` → `data.users[0].id`（查他人） + +### Q: 为什么 Raw API 的 /users/:id/headmaps 返回 HTML？ + +A: headmaps 和 statistics 是前端页面路由，不是 API 端点。用户相关可用的 API 端点只有 `/users/list` 和 `/users/:id`。 diff --git a/skills/gitlink-user/SKILL.md b/skills/gitlink-user/SKILL.md index 0d1aa4f..759a517 100644 --- a/skills/gitlink-user/SKILL.md +++ b/skills/gitlink-user/SKILL.md @@ -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) 了解完整的字段映射 diff --git a/skills/gitlink-user/examples/user-workflow.md b/skills/gitlink-user/examples/user-workflow.md new file mode 100644 index 0000000..3db9f4f --- /dev/null +++ b/skills/gitlink-user/examples/user-workflow.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 ` | +| 获取 user_id 用于 member/batch 操作 | `api GET /users/list --query 'search='` |