diff --git a/README.md b/README.md index 3e6cc29..8a566ea 100644 --- a/README.md +++ b/README.md @@ -5,93 +5,16 @@ [![Go Version](https://img.shields.io/badge/Go-1.26%2B-blue.svg)](https://golang.org) [![npm version](https://img.shields.io/npm/v/@gitlink-ai/cli.svg)](https://www.npmjs.com/package/@gitlink-ai/cli) -The official [GitLink](https://www.gitlink.org.cn) CLI tool — built for humans and AI Agents. Supports **macOS, Linux, and Windows**. Covers repository management, issue tracking, pull requests, webhooks, member collaboration, CI/CD, and AI-powered workflows, with 40+ commands and AI Agent [Skills](./skills/README.md). +The official [GitLink](https://www.gitlink.org.cn) CLI tool — built for humans and AI Agents. Supports **macOS, Linux, and Windows**. Covers repository management, issue tracking, pull requests, CI/CD, and AI-powered workflows, with 40+ commands and 13 AI Agent [Skills](./skills/). **[中文文档](./README.zh-CN.md)** [Install](#installation--quick-start) · [AI Agent Skills](#ai-agent-skills) · [Auth](#configure--use) · [Commands](#usage-examples) · [Contributing](#related-projects) -## Contributors - -
-
- wangyue111 -
wangyue111 -
-
- wbtiger -
wbtiger -
-
- Mengz -
Mengz -
-
- yangsai -
yangsai -
-
- mengcheng -
mengcheng -
-
- muel -
muel -
-
- Leo77 -
Leo77 -
-
- yingjie -
yingjie -
-
- topshare -
topshare -
-
- dtwdtw -
dtwdtw -
-
- recorder -
recorder -
-
- puygob236 -
puygob236 -
-
- co63oc -
co63oc -
-
- lindiwen23 -
lindiwen23 -
-
- ohanabi -
ohanabi -
-
- jiangtx -
jiangtx -
-
- luwanzhou -
luwanzhou -
-
- whale_hihihi -
whale_hihihi -
-
- ## Why gitlink-cli? -- **Agent-Native Design** — Structured [Skills](./skills/README.md) out of the box, compatible with Claude Code, OpenClaw, and other AI platforms — Agents can operate GitLink with zero extra setup -- **Wide Coverage** — Repository, Issue, PR, Webhook, Member, Branch, Release, CI, Pipeline, Org, Search, and User workflows are covered by high-level commands +- **Agent-Native Design** — 13 structured [Skills](./skills/) out of the box, compatible with Claude Code, OpenClaw, and other AI platforms — Agents can operate GitLink with zero extra setup +- **Wide Coverage** — Repository, Issue, PR, Branch, Release, CI, Org, Search, User — all core domains covered - **AI-Friendly & Optimized** — Every command is tested with real Agents, featuring concise parameters, smart defaults, and structured output - **Cross-Platform** — Runs on macOS, Linux, and Windows (x64/arm64), install via `npm install -g @gitlink-ai/cli` in one command, binary auto-downloaded - **Open Source, Zero Barriers** — MulanPSL-2.0 license, ready to use, just `npm install` @@ -103,24 +26,15 @@ The official [GitLink](https://www.gitlink.org.cn) CLI tool — built for humans | Category | Capabilities | |----------|-------------| -| 📦 Repo | List, create, fork, delete repositories, view repo info, insights, and interactions | -| 🐛 Issue | Create, update, close, batch close/update/delete, comment on issues | -| 🔖 Label | Create, list, update, delete issue labels | +| 📦 Repo | List, create, fork, delete repositories, view repo info | +| 🐛 Issue | Create, update, close, batch close, comment on issues | | 🔀 PR | Create, merge, review pull requests, view changed files | -| 👥 Member | List, add, remove repository members, change roles, create and accept invite links | | 🌿 Branch | Create, delete, list, protect, unprotect branches | -| 🏷️ Tag | List, search, view, and delete Git tags | -| 🏷️ Release | Create, edit, update, view, delete releases | +| 🏷️ Release | Create, view, delete releases | | 🏢 Org | Manage organizations, members, teams | | 🔧 CI | View builds, logs, CI/CD operations | -| ⚙️ Pipeline | Run, inspect, enable, disable, delete pipeline workflows and logs | -| 🔔 Webhook | Manage repo webhooks and test deliveries | -| 📖 Wiki | List, view, create, update, and delete wiki pages | -| 🔔 Notification | List, read, and delete user messages | | 🔍 Search | Search repositories, users | -| 📊 Dataset | Query research datasets by project | | 👤 User | View user profiles and info | -| 📊 Profile | User ability, role, major, activity, and contribution statistics | | 📋 PM | Sprint management, kanban boards, weekly reports | | 🤖 Workflow | AI-powered issue triage, PR review, release notes | @@ -141,7 +55,7 @@ The official [GitLink](https://www.gitlink.org.cn) CLI tool — built for humans **From npm (recommended):** ```bash -# One command: installs CLI binary + AI Agent Skills +# One command: installs CLI binary + all 13 AI Agent Skills npm install -g @gitlink-ai/cli ``` @@ -222,36 +136,6 @@ gitlink-cli repo +list # View repository info gitlink-cli repo +info --owner Gitlink --repo forgeplus -# Read repository README -gitlink-cli repo +readme --owner Gitlink --repo forgeplus --ref master - -# List repository files at root or a directory -gitlink-cli repo +tree --owner Gitlink --repo forgeplus --ref master -gitlink-cli repo +tree --owner Gitlink --repo forgeplus --path src --ref main - -# Show language breakdown -gitlink-cli repo +languages --owner Gitlink --repo forgeplus - -# List contributors -gitlink-cli repo +contributors --owner Gitlink --repo forgeplus - -# Show contributor code-line stats for a branch, tag, or commit -gitlink-cli repo +contributor-stats --owner Gitlink --repo forgeplus --ref master --pass-year 1 - -# Show repository code stats -gitlink-cli repo +code-stats --owner Gitlink --repo forgeplus --ref master - -# List watchers and stargazers in a time range -gitlink-cli repo +watchers --owner Gitlink --repo forgeplus --start-at 1714521600 --end-at 1717200000 -gitlink-cli repo +stargazers --owner Gitlink --repo forgeplus --start-at 1714521600 --end-at 1717200000 - -# Preview and apply repository interaction actions -gitlink-cli repo +follow --owner Gitlink --repo forgeplus --dry-run -gitlink-cli repo +follow --owner Gitlink --repo forgeplus -gitlink-cli repo +unfollow --owner Gitlink --repo forgeplus --project-id 123 -gitlink-cli repo +like --owner Gitlink --repo forgeplus -gitlink-cli repo +unlike --owner Gitlink --repo forgeplus --project-id 123 - # Create a repository gitlink-cli repo +create -n my-project -d "Project description" @@ -259,86 +143,6 @@ gitlink-cli repo +create -n my-project -d "Project description" gitlink-cli repo +fork --owner Gitlink --repo forgeplus ``` -### Webhook Management - -```bash -# List webhooks -gitlink-cli webhook +list --owner Gitlink --repo forgeplus - -# Create a webhook -gitlink-cli webhook +create --owner Gitlink --repo forgeplus \ - --url https://example.com/hook --events push,create - -# Test a webhook -gitlink-cli webhook +test --owner Gitlink --repo forgeplus --id 68 - -# View webhook delivery tasks -gitlink-cli webhook +tasks --owner Gitlink --repo forgeplus --id 68 -``` - -### Wiki Management - -```bash -# List wiki pages (table of contents) -gitlink-cli wiki +list --owner Gitlink --repo forgeplus --project-id 12345 - -# View a wiki page by page name -gitlink-cli wiki +view --owner Gitlink --repo forgeplus --project-id 12345 -n home - -# Create a wiki page -gitlink-cli wiki +create --owner Gitlink --repo forgeplus --project-id 12345 \ - -n getting-started -t "Getting Started" -c "# Getting Started Guide" - -# Update a wiki page title and/or content -gitlink-cli wiki +update --owner Gitlink --repo forgeplus --project-id 12345 -n home -t "New Title" -gitlink-cli wiki +update --owner Gitlink --repo forgeplus --project-id 12345 -n home -c "# Updated content" -gitlink-cli wiki +update --owner Gitlink --repo forgeplus --project-id 12345 -n home -t "New Title" -c "New content" - -# Delete a wiki page -gitlink-cli wiki +delete --owner Gitlink --repo forgeplus --project-id 12345 -n old-page -``` - -### Notifications - -```bash -# List current user's unread notifications -gitlink-cli notification +list --type notification --status unread - -# List @me messages for an explicit user -gitlink-cli notification +list --user Mengz --type atme - -# Mark messages as read -gitlink-cli notification +read --type atme --ids 101,102 - -# Mark all unread notifications as read -gitlink-cli notification +read --type notification --ids -1 - -# Delete messages -gitlink-cli notification +delete --type notification --ids 101,102 -``` - -### Member Management - -```bash -# List repository members -gitlink-cli member +list --owner Gitlink --repo forgeplus - -# Add a member -gitlink-cli member +add --owner Gitlink --repo forgeplus --user-id 101 - -# Preview batch add without changing data -gitlink-cli member +batch-add --owner Gitlink --repo forgeplus --user-ids 101,102 --dry-run - -# Batch add members from a CSV file -gitlink-cli member +batch-add --owner Gitlink --repo forgeplus --from members.csv - -# Change a member role -gitlink-cli member +role --owner Gitlink --repo forgeplus --user-id 101 --role Developer - -# Create an invite link -gitlink-cli member +invite-link --owner Gitlink --repo forgeplus --role developer --apply true -``` - ### Issue Management ```bash @@ -348,15 +152,9 @@ gitlink-cli issue +list --owner Gitlink --repo forgeplus # Create an issue gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: Login failed" -b "Steps to reproduce..." -# Create an issue with metadata -gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: Login failed" --priority-id 3 --tag-ids 4,5 --assigner-ids 7 - # View an issue gitlink-cli issue +view --owner Gitlink --repo forgeplus -i 123 -# Update issue metadata -gitlink-cli issue +update --owner Gitlink --repo forgeplus --number 123 --priority-id 4 --branch bugfix/login --due-date 2026-06-15 - # Close an issue gitlink-cli issue +close --owner Gitlink --repo forgeplus -i 123 @@ -366,55 +164,8 @@ gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --numbers 123,12 # Batch close issues from a CSV file gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --from issues.csv -# Preview batch metadata update by API issue IDs -# Note: --ids uses API issue IDs, not web URL issue numbers. -gitlink-cli issue +batch-update --owner Gitlink --repo forgeplus --ids 101,102 --status-id 3 --priority-id 2 --dry-run - -# Destructive batch delete requires both dry-run first and --yes for real execution -gitlink-cli issue +batch-delete --owner Gitlink --repo forgeplus --ids 101,102 --dry-run -gitlink-cli issue +batch-delete --owner Gitlink --repo forgeplus --ids 101,102 --yes - # Add a comment gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 -b "Fixed" - -# List issue assigners -gitlink-cli issue +assigners --owner Gitlink --repo forgeplus - -# List issue authors -gitlink-cli issue +authors --owner Gitlink --repo forgeplus - -# List issue priorities -gitlink-cli issue +priorities --owner Gitlink --repo forgeplus - -# List issue tags -gitlink-cli issue +tags --owner Gitlink --repo forgeplus --only-name - -# List issue statuses -gitlink-cli issue +statuses --owner Gitlink --repo forgeplus -``` - -`issue +view`, `issue +update`, `issue +close`, and `issue +comment` prefer -`--number` / `-n` for the issue number shown in the web URL. `--id` / `-i` -is accepted as a compatibility alias for the same web issue number, not the -global database ID. - -### Label Management - -```bash -# List issue labels -gitlink-cli label +list --owner Gitlink --repo forgeplus - -# Filter labels by keyword -gitlink-cli label +list --owner Gitlink --repo forgeplus -k bug - -# Create a label (color defaults to #1E90FF) -gitlink-cli label +create --owner Gitlink --repo forgeplus -n bug -d "Something is broken" -c "#FF0000" - -# Update a label (unspecified fields are preserved) -gitlink-cli label +update --owner Gitlink --repo forgeplus -i 42 -c "#00FF00" - -# Delete a label -gitlink-cli label +delete --owner Gitlink --repo forgeplus -i 42 ``` ### Pull Requests @@ -429,34 +180,14 @@ gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: Search feature # Create a PR (from a fork) gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: New feature" --head your_username/forgeplus:feature/my-feature --base master -# The fork form auto-resolves GitLink fork metadata -# so you do not need to pass merge_user_login or fork_project_id yourself -gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "fix: CLI bug" --head your_username/forgeplus:fix/bug --base master - # View a PR gitlink-cli pr +view --owner Gitlink --repo forgeplus -i 42 # Merge a PR gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42 -# Reopen a closed PR -gitlink-cli pr +reopen --owner Gitlink --repo forgeplus -i 42 - # View changed files gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42 - -# List PR patchset versions -gitlink-cli pr +versions --owner Gitlink --repo forgeplus -i 42 - -# View a patchset version diff -gitlink-cli pr +version-diff --owner Gitlink --repo forgeplus -i 42 --version-id 16040 - -# List PR reviews -gitlink-cli pr +reviews --owner Gitlink --repo forgeplus -i 42 - -# Create a PR review (with dry-run preview) -gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM" --dry-run -gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM" ``` ### Branch Management @@ -478,40 +209,17 @@ gitlink-cli branch +protect --name main gitlink-cli branch +unprotect --name main ``` -### Tag Management - -```bash -# List tags with commit details -gitlink-cli tag +list --owner Gitlink --repo forgeplus --page 1 --limit 20 - -# List tag names without pagination -gitlink-cli tag +names --owner Gitlink --repo forgeplus -k v1 - -# View a tag -gitlink-cli tag +view --owner Gitlink --repo forgeplus --name v1.0.0 - -# Delete a tag -gitlink-cli tag +delete --owner Gitlink --repo forgeplus --name release/v1.0.0 -``` - ### Release Management ```bash # List releases gitlink-cli release +list --owner Gitlink --repo forgeplus -# Create a release with release notes and optional assets -gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 Stable" -b "Changelog..." --attachment-ids 12,34 +# Create a release +gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 Stable" -b "Changelog..." # View a release gitlink-cli release +view --owner Gitlink --repo forgeplus -i - -# Get edit data and update while preserving unspecified fields -gitlink-cli release +edit --owner Gitlink --repo forgeplus -i -gitlink-cli release +update --owner Gitlink --repo forgeplus -i -b "Updated changelog" --dry-run - -# Preview release deletion before executing it -gitlink-cli release +delete --owner Gitlink --repo forgeplus -i --dry-run ``` ### CI/CD Operations @@ -527,38 +235,6 @@ gitlink-cli ci +log --owner Gitlink --repo forgeplus -i gitlink-cli ci +restart --owner Gitlink --repo forgeplus -i ``` -### Pipeline Operations - -```bash -# List platform pipelines -gitlink-cli pipeline +list --owner-id 123 --page 1 --limit 20 - -# List repository pipeline runs -gitlink-cli pipeline +runs --owner Gitlink --repo forgeplus --ref master --workflow build.yml - -# Start a pipeline workflow, previewing the request first -gitlink-cli pipeline +run --owner Gitlink --repo forgeplus --ref master --workflow build.yml --dry-run - -# Inspect pipeline details and logs -gitlink-cli pipeline +view --owner Gitlink --repo forgeplus --id 7 -gitlink-cli pipeline +logs --owner Gitlink --repo forgeplus --run-id 99 --id 7 --index 43 -gitlink-cli pipeline +results --owner Gitlink --repo forgeplus --run-id 99 - -# Toggle or delete pipeline workflows, previewing destructive writes first -gitlink-cli pipeline +disable --owner Gitlink --repo forgeplus --id 7 --workflow build.yml --dry-run -gitlink-cli pipeline +delete --owner Gitlink --repo forgeplus --id 7 --dry-run -``` - -### Ignore File Templates - -```bash -# List all available .gitignore templates -gitlink-cli ignore +list - -# Filter templates by name -gitlink-cli ignore +list --name Go -``` - ### Search ```bash @@ -569,154 +245,6 @@ gitlink-cli search +repos -k "machine learning" gitlink-cli search +users -k "zhangsan" ``` -### User Profile - -`profile` surfaces GitLink's native user statistics (ability, role, major, activity, -contribution). When `--user` is omitted it defaults to the authenticated user. - -```bash -# Development ability scores + language breakdown -gitlink-cli profile +ability --user zhangsan - -# Role positioning / major (discipline) categories -gitlink-cli profile +role --user zhangsan -gitlink-cli profile +major --user zhangsan - -# Ability within a time window (Unix timestamps) -gitlink-cli profile +ability --user zhangsan --start-time 1704067200 --end-time 1735689600 - -# Recent activity (issues / PRs / commits per day) for the current user -gitlink-cli profile +activity - -# Contribution heatmap for a given year -gitlink-cli profile +contribution --user zhangsan --year 2025 -``` - -### Workflow Agent Commands - -`workflow` provides rule-based repository analysis for maintainers and AI Agents. It currently supports: - -- `workflow +triage` -- `workflow +health` -- `workflow +pr-summary` -- `workflow +repo-report` - -`workflow +pr-summary` defaults to `table` when `--format` is omitted. -`workflow +repo-report` defaults to `markdown` when `--format` is omitted. - -Examples: - -```bash -# Triage with local parameters -gitlink-cli workflow +triage --title "Install failed on Windows" --body "go install failed with error" --format table - -# Triage with JSON output -gitlink-cli workflow +triage --title "Token leaked in logs" --body "The access token appears in command output" --format json - -# Triage with Chinese markdown output -gitlink-cli workflow +triage \ - --title "安装失败，无法登录" \ - --body "运行命令时报错" \ - --lang zh-CN \ - --format markdown - -# Triage from a local JSON file -gitlink-cli workflow +triage --from shortcuts/workflow/testdata/issue_bug.json --format json - -# Triage by read-only GitLink fetch -gitlink-cli workflow +triage --owner Gitlink --repo gitlink-cli --state open --limit 5 --format table - -# Health for a healthy repository -gitlink-cli workflow +health \ - --repository Gitlink/gitlink-cli \ - --open-issues 3 \ - --open-prs 1 \ - --has-readme \ - --has-license \ - --has-contributing \ - --agent-readiness-known \ - --agent-readiness-score 9 \ - --format table - -# Health for a risky repository -gitlink-cli workflow +health \ - --repository demo/repo \ - --open-issues 60 \ - --stale-issues 25 \ - --open-prs 12 \ - --stale-prs 6 \ - --recent-activity-known \ - --recent-activity-days 120 \ - --release-known=false \ - --format json - -# Health with Chinese markdown output -gitlink-cli workflow +health \ - --repository Gitlink/gitlink-cli \ - --open-issues 3 \ - --open-prs 1 \ - --has-readme \ - --has-license \ - --has-contributing \ - --lang zh-CN \ - --format markdown - -# Health by read-only GitLink fetch -gitlink-cli workflow +health --owner Gitlink --repo gitlink-cli --stale-days 30 --format table - -# PR review summary by read-only GitLink fetch -gitlink-cli workflow +pr-summary --owner Gitlink --repo gitlink-cli --number 1 --format markdown - -# PR review summary from a local JSON file -gitlink-cli workflow +pr-summary --from shortcuts/workflow/testdata/pr_summary.json --format json - -# Repository workflow report by read-only GitLink fetch -gitlink-cli workflow +repo-report --owner Gitlink --repo gitlink-cli --format markdown - -# Repository workflow report from a local JSON file -gitlink-cli workflow +repo-report --from shortcuts/workflow/testdata/repo_report.json --format json -``` - -Output formats: - -- `json` for scripts and AI Agents -- `table` for terminal review -- `markdown` for Issue comments, PR comments, release notes, and competition write-ups - -Safety: - -- Current workflow commands use local analysis by default and can also read GitLink data in read-only fetch mode. -- They do not modify remote GitLink data. -- They do not depend on LLM APIs. -- `workflow +pr-summary` does not comment, approve, reject, or merge pull requests. -- `workflow +repo-report` aggregates health, issue triage, and PR review summary signals without remote writes. - -### Dataset - -`dataset` manages and queries GitLink research datasets (title, description, -paper content, license, owning project). - -```bash -# List datasets for one or more projects (by numeric project ID) -gitlink-cli dataset +list --ids 5988 - -# View a repository's dataset and attachments -gitlink-cli dataset +view --owner Gitlink --repo forgeplus - -# Create / update a repository's dataset (preview first with --dry-run) -gitlink-cli dataset +create --owner me --repo proj -t "My dataset" -d "..." --license-id 359 --dry-run -gitlink-cli dataset +update --owner me --repo proj -t "My dataset" -d "updated" - -# Delete a dataset attachment (destructive: preview, then confirm with --yes) -gitlink-cli dataset +delete-attachment --owner me --repo proj --uuid --dry-run -gitlink-cli dataset +delete-attachment --owner me --repo proj --uuid --yes -``` - -> Note: `dataset +list` (platform dataset query) is verified on production -> gitlink.org.cn. The per-repo `+view`/`+create`/`+update` routes follow the -> published OpenAPI contract but are not yet deployed on production (they return -> 404 there); they will work once the platform enables them. - ### Raw API For endpoints not covered by shortcuts, use the Raw API directly: @@ -728,12 +256,6 @@ gitlink-cli api GET /users/me # POST request gitlink-cli api POST /Gitlink/forgeplus/issues --body '{"subject":"test","description":"..."}' -# POST request with body from a file -gitlink-cli api POST /Gitlink/forgeplus/issues --body-file issue.json - -# POST request with body from stdin -Get-Content issue.json | gitlink-cli api POST /Gitlink/forgeplus/issues --body-stdin - # With query parameters gitlink-cli api GET /Gitlink/forgeplus/commits --query 'page=1&limit=5' ``` @@ -744,7 +266,7 @@ gitlink-cli api GET /Gitlink/forgeplus/commits --query 'page=1&limit=5' |-----------|-------------|---------| | `--owner` | Repository owner | `--owner Gitlink` | | `--repo` | Repository name | `--repo forgeplus` | -| `--format` | Output format (json/table/yaml; workflow also supports markdown) | `--format json` | +| `--format` | Output format (json/table/yaml) | `--format json` | | `--debug` | Enable debug output | `--debug` | **Automatic context resolution:** When running inside a git repository, `--owner` and `--repo` are automatically resolved from `git remote origin`. @@ -771,29 +293,25 @@ git push gitlink ## AI Agent Skills -The `skills/` directory contains Agent Skill files for AI-automated GitLink operations. +The `skills/` directory contains 13 Agent Skill files for AI-automated GitLink operations. -See [skills/README.md](./skills/README.md) for details. +See [skills/README.md](skills/README.md) for details. | Skill | Description | |-------|-------------| | `gitlink-shared` | Authentication, global parameters, safety rules, API notes | -| `gitlink-repo` | Repository operations (create, view, delete, fork, insights, etc.) | -| `gitlink-issue` | Issue operations (create, update, close, batch update/delete, comment, etc.) | +| `gitlink-repo` | Repository operations (create, view, delete, fork, etc.) | +| `gitlink-issue` | Issue operations (create, update, close, comment, etc.) | | `gitlink-pr` | Pull request operations (create, merge, review, etc.) | -| `gitlink-member` | Repository member and invite link management | | `gitlink-branch` | Branch management (create, delete, list, protect, unprotect) | -| `gitlink-tag` | Git tag operations (list, search, view, delete) | -| `gitlink-release` | Release management (create, edit, update, view, delete, etc.) | +| `gitlink-release` | Release management (create, view, delete, etc.) | | `gitlink-ci` | CI/CD operations (builds, logs, etc.) | -| `gitlink-pipeline` | Pipeline workflow operations (runs, logs, enable, disable, delete, etc.) | -| `gitlink-notification` | User messages (list, mark read, delete) | | `gitlink-search` | Search (repositories, users, etc.) | | `gitlink-org` | Organization management (members, teams, etc.) | | `gitlink-user` | User management (profile info, etc.) | | `gitlink-pm` | Project management (sprints, kanban, weekly reports, etc.) | | `gitlink-workflow` | AI-powered workflows (issue triage, PR review, release notes, etc.) | -| `gitlink-health` | Project health analysis (PR/Issue metrics aggregation, health reports) | +| `gitlink-maintainer-copilot` | Maintainer dashboard, evidence pack, governance playbooks, and confirmed governance Issue creation | ## Project Structure @@ -816,12 +334,10 @@ gitlink-cli/ │ ├── repo/ # Repository shortcuts │ ├── issue/ # Issue shortcuts │ ├── pr/ # PR shortcuts -│ ├── member/ # Repository member shortcuts │ ├── branch/ # Branch shortcuts │ ├── release/ # Release shortcuts │ ├── org/ # Organization shortcuts │ ├── ci/ # CI shortcuts -│ ├── pipeline/ # Pipeline shortcuts │ ├── search/ # Search shortcuts │ ├── user/ # User shortcuts │ └── register.go # Registration entry point @@ -845,7 +361,7 @@ gitlink-cli/ ## Documentation -- [Skills Guide](./skills/README.md) — AI Agent Skills detailed documentation +- [Skills Guide](skills/README.md) — AI Agent Skills detailed documentation - [Design Document](doc/design.md) — Architecture design and development plan ## FAQ @@ -900,9 +416,7 @@ Reinstall first: npm install -g @gitlink-ai/cli ``` -If the error persists, check whether the release page contains the asset for your platform, -for example `gitlink-cli__windows_amd64.zip` on Windows x64. -You can also download the binary manually from the release page or build from source with `go install .`. +If the error persists, check whether the release page contains the asset for your platform, for example `gitlink-cli__windows_amd64.zip` on Windows x64. You can also download the binary manually from the release page or build from source with `go install .`. ### Q: Where are credentials stored on Windows? @@ -910,7 +424,7 @@ gitlink-cli uses Windows Credential Manager for secure token storage. If Credent ### Q: Where can I find the full API reference? -See [skills/gitlink-shared/references/api-reference.md](./skills/gitlink-shared/references/api-reference.md). +See [skills/gitlink-shared/references/api-reference.md](skills/gitlink-shared/references/api-reference.md). ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index 2ef6256..612e033 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -5,93 +5,16 @@ [![Go Version](https://img.shields.io/badge/Go-1.26%2B-blue.svg)](https://golang.org) [![npm version](https://img.shields.io/npm/v/@gitlink-ai/cli.svg)](https://www.npmjs.com/package/@gitlink-ai/cli) -[GitLink（确实开源）](https://www.gitlink.org.cn) 官方 CLI 工具 — 为人类和 AI Agent 双重设计。支持 **macOS、Linux、Windows**，覆盖仓库管理、Issue 追踪、Pull Request、Webhook、成员协作、CI/CD 和 AI 自动化工作流，包含 40+ 命令和 AI Agent [Skills](./skills/README.md)。 +[GitLink（确实开源）](https://www.gitlink.org.cn) 官方 CLI 工具 — 为人类和 AI Agent 双重设计。支持 **macOS、Linux、Windows**，覆盖仓库管理、Issue 追踪、Pull Request、CI/CD 和 AI 自动化工作流，包含 40+ 命令和 13 个 AI Agent [Skills](./skills/)。 **[English](./README.md)** [安装](#安装与快速上手) · [AI Agent Skills](#ai-agent-skills) · [认证](#配置与使用) · [命令](#使用示例) · [贡献](#相关项目) -## 贡献者 - -
-
- wangyue111 -
wangyue111 -
-
- wbtiger -
wbtiger -
-
- Mengz -
Mengz -
-
- yangsai -
yangsai -
-
- mengcheng -
mengcheng -
-
- muel -
muel -
-
- Leo77 -
Leo77 -
-
- yingjie -
yingjie -
-
- topshare -
topshare -
-
- dtwdtw -
dtwdtw -
-
- recorder -
recorder -
-
- puygob236 -
puygob236 -
-
- co63oc -
co63oc -
-
- lindiwen23 -
lindiwen23 -
-
- ohanabi -
ohanabi -
-
- jiangtx -
jiangtx -
-
- luwanzhou -
luwanzhou -
- -
- ## 为什么选择 gitlink-cli？ -- **Agent-Native 设计** — 开箱即用结构化 [Skills](./skills/README.md)，兼容 Claude Code — Agent 零配置即可操作 GitLink -- **广泛覆盖** — 仓库、Issue、PR、Webhook、成员、分支、Release、CI、Pipeline、组织、搜索、用户等常用工作流均提供高层命令 +- **Agent-Native 设计** — 开箱即用 13 个结构化 [Skills](./skills/)，兼容 Claude Code — Agent 零配置即可操作 GitLink +- **广泛覆盖** — 仓库、Issue、PR、分支、Release、CI、组织、搜索、用户 — 核心功能全覆盖 - **AI 友好 & 优化** — 每条命令都经过真实 Agent 测试，简洁参数、智能默认值、结构化输出 - **跨平台** — macOS、Linux、Windows (x64/arm64) 全支持，`npm` 一条命令安装 - **开源零门槛** — 木兰宽松许可证第2版（MulanPSL-2.0），`npm install` 即用 @@ -103,23 +26,15 @@ | 分类 | 能力 | |------|------| -| 📦 仓库 | 列出、创建、Fork、删除仓库，查看仓库信息、洞察数据和互动状态 | -| 🐛 Issue | 创建、更新、关闭、批量关闭/更新/删除、评论 Issue | -| 🔖 标签 | 创建、列出、更新、删除 Issue 标签 | +| 📦 仓库 | 列出、创建、Fork、删除仓库，查看仓库信息 | +| 🐛 Issue | 创建、更新、关闭、批量关闭、评论 Issue | | 🔀 PR | 创建、合并、Review Pull Request，查看变更文件 | -| 👥 成员 | 列出、添加、移除仓库成员，调整角色，生成和接受邀请链接 | | 🌿 分支 | 创建、删除、保护分支 | -| 🏷️ 标签 | 列出、搜索、查看、删除 Git 标签 | -| 🏷️ 发布 | 创建、编辑、更新、查看、删除 Release | +| 🏷️ 发布 | 创建、查看、删除 Release | | 🏢 组织 | 管理组织、成员、团队 | | 🔧 CI | 查看构建、日志、CI/CD 操作 | -| ⚙️ Pipeline | 运行、查看、启停、删除流水线工作流并查询日志 | -| 📖 Wiki | 列出、查看、创建、更新、删除 Wiki 页面 | -| 🔔 通知 | 列出、已读、删除用户消息 | | 🔍 搜索 | 搜索仓库、用户 | -| 📊 数据集 | 按项目查询科研数据集 | | 👤 用户 | 查看用户资料和信息 | -| 📊 画像 | 用户开发能力、角色定位、专业定位、近期活动、贡献热力图统计 | | 📋 项目管理 | Sprint 管理、看板、周报 | | 🤖 工作流 | AI 驱动的 Issue 分类、PR Review、Release Notes | @@ -233,36 +148,6 @@ gitlink-cli repo +list # 查看仓库信息 gitlink-cli repo +info --owner Gitlink --repo forgeplus -# 读取仓库 README -gitlink-cli repo +readme --owner Gitlink --repo forgeplus --ref master - -# 列出仓库根目录或指定目录文件 -gitlink-cli repo +tree --owner Gitlink --repo forgeplus --ref master -gitlink-cli repo +tree --owner Gitlink --repo forgeplus --path src --ref main - -# 查看语言占比 -gitlink-cli repo +languages --owner Gitlink --repo forgeplus - -# 列出贡献者 -gitlink-cli repo +contributors --owner Gitlink --repo forgeplus - -# 查看分支、标签或提交的贡献者代码行统计 -gitlink-cli repo +contributor-stats --owner Gitlink --repo forgeplus --ref master --pass-year 1 - -# 查看仓库代码统计 -gitlink-cli repo +code-stats --owner Gitlink --repo forgeplus --ref master - -# 按时间范围查看关注者和点赞者 -gitlink-cli repo +watchers --owner Gitlink --repo forgeplus --start-at 1714521600 --end-at 1717200000 -gitlink-cli repo +stargazers --owner Gitlink --repo forgeplus --start-at 1714521600 --end-at 1717200000 - -# 预览并执行仓库互动操作 -gitlink-cli repo +follow --owner Gitlink --repo forgeplus --dry-run -gitlink-cli repo +follow --owner Gitlink --repo forgeplus -gitlink-cli repo +unfollow --owner Gitlink --repo forgeplus --project-id 123 -gitlink-cli repo +like --owner Gitlink --repo forgeplus -gitlink-cli repo +unlike --owner Gitlink --repo forgeplus --project-id 123 - # 创建仓库 gitlink-cli repo +create -n my-project -d "项目描述" @@ -270,86 +155,6 @@ gitlink-cli repo +create -n my-project -d "项目描述" gitlink-cli repo +fork --owner Gitlink --repo forgeplus ``` -### Webhook 管理 - -```bash -# 列出 webhook -gitlink-cli webhook +list --owner Gitlink --repo forgeplus - -# 创建 webhook -gitlink-cli webhook +create --owner Gitlink --repo forgeplus \ - --url https://example.com/hook --events push,create - -# 测试 webhook -gitlink-cli webhook +test --owner Gitlink --repo forgeplus --id 68 - -# 查看 webhook 投递任务 -gitlink-cli webhook +tasks --owner Gitlink --repo forgeplus --id 68 -``` - -### Wiki 管理 - -```bash -# 列出 Wiki 页面（目录结构） -gitlink-cli wiki +list --owner Gitlink --repo forgeplus --project-id 12345 - -# 查看 Wiki 页面 -gitlink-cli wiki +view --owner Gitlink --repo forgeplus --project-id 12345 -n home - -# 创建 Wiki 页面 -gitlink-cli wiki +create --owner Gitlink --repo forgeplus --project-id 12345 \ - -n getting-started -t "快速开始" -c "# 快速开始指南" - -# 更新 Wiki 页面标题和/或内容 -gitlink-cli wiki +update --owner Gitlink --repo forgeplus --project-id 12345 -n home -t "新标题" -gitlink-cli wiki +update --owner Gitlink --repo forgeplus --project-id 12345 -n home -c "# 更新后的内容" -gitlink-cli wiki +update --owner Gitlink --repo forgeplus --project-id 12345 -n home -t "新标题" -c "新内容" - -# 删除 Wiki 页面 -gitlink-cli wiki +delete --owner Gitlink --repo forgeplus --project-id 12345 -n old-page -``` - -### 通知管理 - -```bash -# 列出当前用户未读系统消息 -gitlink-cli notification +list --type notification --status unread - -# 列出指定用户的 @我消息 -gitlink-cli notification +list --user Mengz --type atme - -# 标记消息为已读 -gitlink-cli notification +read --type atme --ids 101,102 - -# 将全部未读系统消息标记为已读 -gitlink-cli notification +read --type notification --ids -1 - -# 删除消息 -gitlink-cli notification +delete --type notification --ids 101,102 -``` - -### 成员管理 - -```bash -# 列出仓库成员 -gitlink-cli member +list --owner Gitlink --repo forgeplus - -# 添加成员 -gitlink-cli member +add --owner Gitlink --repo forgeplus --user-id 101 - -# 预览批量添加成员，不修改数据 -gitlink-cli member +batch-add --owner Gitlink --repo forgeplus --user-ids 101,102 --dry-run - -# 从 CSV 文件批量添加成员 -gitlink-cli member +batch-add --owner Gitlink --repo forgeplus --from members.csv - -# 调整成员权限 -gitlink-cli member +role --owner Gitlink --repo forgeplus --user-id 101 --role Developer - -# 生成邀请链接 -gitlink-cli member +invite-link --owner Gitlink --repo forgeplus --role developer --apply true -``` - ### Issue 管理 ```bash @@ -359,15 +164,9 @@ gitlink-cli issue +list --owner Gitlink --repo forgeplus # 创建 Issue gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: 登录失败" -b "复现步骤..." -# 创建带元数据的 Issue -gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: 登录失败" --priority-id 3 --tag-ids 4,5 --assigner-ids 7 - # 查看 Issue gitlink-cli issue +view --owner Gitlink --repo forgeplus -i 123 -# 更新 Issue 元数据 -gitlink-cli issue +update --owner Gitlink --repo forgeplus --number 123 --priority-id 4 --branch bugfix/login --due-date 2026-06-15 - # 关闭 Issue gitlink-cli issue +close --owner Gitlink --repo forgeplus -i 123 @@ -377,54 +176,8 @@ gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --numbers 123,12 # 从 CSV 文件批量关闭 Issue gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --from issues.csv -# 按 API issue id 预览批量更新元数据 -# 注意：--ids 是 API issue id，不是网页 URL 中的 Issue 编号。 -gitlink-cli issue +batch-update --owner Gitlink --repo forgeplus --ids 101,102 --status-id 3 --priority-id 2 --dry-run - -# 危险批量删除必须先 dry-run，真实执行还要显式 --yes -gitlink-cli issue +batch-delete --owner Gitlink --repo forgeplus --ids 101,102 --dry-run -gitlink-cli issue +batch-delete --owner Gitlink --repo forgeplus --ids 101,102 --yes - # 添加评论 gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 -b "已修复" - -# 列出 Issue 负责人 -gitlink-cli issue +assigners --owner Gitlink --repo forgeplus - -# 列出 Issue 发布人 -gitlink-cli issue +authors --owner Gitlink --repo forgeplus - -# 列出 Issue 优先级 -gitlink-cli issue +priorities --owner Gitlink --repo forgeplus - -# 列出 Issue 标签 -gitlink-cli issue +tags --owner Gitlink --repo forgeplus --only-name - -# 列出 Issue 状态 -gitlink-cli issue +statuses --owner Gitlink --repo forgeplus -``` - -`issue +view`、`issue +update`、`issue +close` 和 `issue +comment` 推荐使用 -`--number` / `-n` 传网页 URL 中的 Issue 编号。`--id` / `-i` 是同一网页 Issue -编号的兼容别名，不是数据库内部 ID。 - -### 标签管理 - -```bash -# 列出 Issue 标签 -gitlink-cli label +list --owner Gitlink --repo forgeplus - -# 按关键词筛选标签 -gitlink-cli label +list --owner Gitlink --repo forgeplus -k bug - -# 创建标签（颜色默认 #1E90FF） -gitlink-cli label +create --owner Gitlink --repo forgeplus -n bug -d "功能缺陷" -c "#FF0000" - -# 更新标签（未指定的字段会被保留） -gitlink-cli label +update --owner Gitlink --repo forgeplus -i 42 -c "#00FF00" - -# 删除标签 -gitlink-cli label +delete --owner Gitlink --repo forgeplus -i 42 ``` ### Pull Request @@ -439,50 +192,14 @@ gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: 搜索功能" # 创建 PR（从 Fork 仓库） gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: 新功能" --head your_username/forgeplus:feature/my-feature --base master -# Fork 写法会自动补齐 GitLink 所需的 fork 元数据 -# 不需要再手动传 merge_user_login 或 fork_project_id -gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "fix: CLI bug" --head your_username/forgeplus:fix/bug --base master - # 查看 PR gitlink-cli pr +view --owner Gitlink --repo forgeplus -i 42 # 合并 PR gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42 -# 重开已关闭的 PR -gitlink-cli pr +reopen --owner Gitlink --repo forgeplus -i 42 - # 查看 PR 变更文件 gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42 - -# 查看 PR patchset/version 列表 -gitlink-cli pr +versions --owner Gitlink --repo forgeplus -i 42 - -# 查看指定 patchset/version diff -gitlink-cli pr +version-diff --owner Gitlink --repo forgeplus -i 42 --version-id 16040 - -# 查看 PR 审查记录 -gitlink-cli pr +reviews --owner Gitlink --repo forgeplus -i 42 - -# 创建 PR 审查（支持 dry-run 预览） -gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM" --dry-run -gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM" -``` - -### 标签管理 - -```bash -# 列出标签及提交详情 -gitlink-cli tag +list --owner Gitlink --repo forgeplus --page 1 --limit 20 - -# 无分页列出标签名称 -gitlink-cli tag +names --owner Gitlink --repo forgeplus -k v1 - -# 查看标签详情 -gitlink-cli tag +view --owner Gitlink --repo forgeplus --name v1.0.0 - -# 删除标签 -gitlink-cli tag +delete --owner Gitlink --repo forgeplus --name release/v1.0.0 ``` ### 发布管理 @@ -491,50 +208,11 @@ gitlink-cli tag +delete --owner Gitlink --repo forgeplus --name release/v1.0.0 # 列出 Release gitlink-cli release +list --owner Gitlink --repo forgeplus -# 创建 Release，可附带附件 ID -gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 正式版" -b "更新内容..." --attachment-ids 12,34 +# 创建 Release +gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 正式版" -b "更新内容..." # 查看 Release gitlink-cli release +view --owner Gitlink --repo forgeplus -i - -# 获取编辑数据并保留未传字段更新 -gitlink-cli release +edit --owner Gitlink --repo forgeplus -i -gitlink-cli release +update --owner Gitlink --repo forgeplus -i -b "更新后的内容" --dry-run - -# 删除前先预览请求 -gitlink-cli release +delete --owner Gitlink --repo forgeplus -i --dry-run -``` - -### 流水线管理 - -```bash -# 列出平台流水线 -gitlink-cli pipeline +list --owner-id 123 --page 1 --limit 20 - -# 列出仓库流水线运行记录 -gitlink-cli pipeline +runs --owner Gitlink --repo forgeplus --ref master --workflow build.yml - -# 运行流水线工作流，先用 dry-run 预览请求 -gitlink-cli pipeline +run --owner Gitlink --repo forgeplus --ref master --workflow build.yml --dry-run - -# 查看流水线详情、日志和运行结果 -gitlink-cli pipeline +view --owner Gitlink --repo forgeplus --id 7 -gitlink-cli pipeline +logs --owner Gitlink --repo forgeplus --run-id 99 --id 7 --index 43 -gitlink-cli pipeline +results --owner Gitlink --repo forgeplus --run-id 99 - -# 启停或删除流水线工作流，写入/删除前先预览 -gitlink-cli pipeline +disable --owner Gitlink --repo forgeplus --id 7 --workflow build.yml --dry-run -gitlink-cli pipeline +delete --owner Gitlink --repo forgeplus --id 7 --dry-run -``` - -### 忽略文件模板 - -```bash -# 列出所有可用的 .gitignore 模板 -gitlink-cli ignore +list - -# 按名称筛选模板 -gitlink-cli ignore +list --name Go ``` ### 搜索 @@ -547,50 +225,6 @@ gitlink-cli search +repos -k "machine learning" gitlink-cli search +users -k "zhangsan" ``` -### 用户画像 - -`profile` 暴露 GitLink 原生的用户画像统计（开发能力、角色定位、专业定位、近期活动、贡献热力图）。 -省略 `--user` 时默认使用当前认证用户。 - -```bash -# 开发能力评分 + 语言分布 -gitlink-cli profile +ability --user zhangsan - -# 角色定位 / 专业（学科）定位 -gitlink-cli profile +role --user zhangsan -gitlink-cli profile +major --user zhangsan - -# 指定时间范围的开发能力（Unix 时间戳） -gitlink-cli profile +ability --user zhangsan --start-time 1704067200 --end-time 1735689600 - -# 当前用户的近期活动（每日 疑修 / 合并请求 / 提交） -gitlink-cli profile +activity - -# 指定年份的贡献热力图 -gitlink-cli profile +contribution --user zhangsan --year 2025 -``` - -### 数据集 - -`dataset` 管理并查询 GitLink 科研数据集（标题、描述、论文内容、许可证、所属项目）。 - -```bash -# 按数字项目 ID 列出一个或多个项目的数据集 -gitlink-cli dataset +list --ids 5988 - -# 查看仓库的数据集及其附件 -gitlink-cli dataset +view --owner Gitlink --repo forgeplus - -# 创建 / 更新仓库数据集（先用 --dry-run 预览） -gitlink-cli dataset +create --owner me --repo proj -t "我的数据集" -d "..." --license-id 359 --dry-run -gitlink-cli dataset +update --owner me --repo proj -t "我的数据集" -d "更新" - -# 删除数据集附件（破坏性：先预览，再用 --yes 确认） -gitlink-cli dataset +delete-attachment --owner me --repo proj --uuid --dry-run -gitlink-cli dataset +delete-attachment --owner me --repo proj --uuid --yes -``` - -> 注意：`dataset +list`（平台数据集查询）已在生产 gitlink.org.cn 验证可用。按仓库的 `+view`/`+create`/`+update` 遵循已发布的 OpenAPI 契约，但生产环境尚未部署（当前返回 404），待平台上线后即可生效。 ### Raw API Shortcuts 未覆盖的接口可通过 Raw API 直接调用： @@ -602,12 +236,6 @@ gitlink-cli api GET /users/me # POST 请求 gitlink-cli api POST /Gitlink/forgeplus/issues --body '{"subject":"test","description":"..."}' -# 从文件读取 JSON body -gitlink-cli api POST /Gitlink/forgeplus/issues --body-file issue.json - -# 从 stdin 读取 JSON body -Get-Content issue.json | gitlink-cli api POST /Gitlink/forgeplus/issues --body-stdin - # 带查询参数 gitlink-cli api GET /Gitlink/forgeplus/commits --query 'page=1&limit=5' ``` @@ -645,27 +273,24 @@ git push gitlink ## AI Agent Skills -`skills/` 目录包含 Claude Code Agent Skill 文件，支持 AI 自动化操作 GitLink 平台。 +`skills/` 目录包含 13 个 Claude Code Agent Skill 文件，支持 AI 自动化操作 GitLink 平台。 -详见 [skills/README.md](./skills/README.md) +详见 [skills/README.md](skills/README.md) | Skill | 说明 | |-------|------| | `gitlink-shared` | 认证、全局参数、安全规则、API 注意事项 | -| `gitlink-repo` | 仓库操作（创建、查看、删除、Fork、洞察数据等） | -| `gitlink-issue` | Issue 操作（创建、更新、关闭、批量更新/删除、评论等） | +| `gitlink-repo` | 仓库操作（创建、查看、删除、Fork 等） | +| `gitlink-issue` | Issue 操作（创建、更新、关闭、评论等） | | `gitlink-pr` | Pull Request 操作（创建、合并、Review 等） | -| `gitlink-member` | 仓库成员与邀请链接管理 | -| `gitlink-tag` | Git 标签管理（列表、搜索、查看、删除） | -| `gitlink-release` | 发布管理（创建、编辑、更新、查看、删除等） | +| `gitlink-release` | 发布管理（创建、查看、删除等） | | `gitlink-org` | 组织管理（成员、团队等） | | `gitlink-ci` | CI/CD 操作（构建、日志等） | -| `gitlink-pipeline` | 流水线工作流操作（运行、日志、启停、删除等） | -| `gitlink-notification` | 用户消息（列表、标记已读、删除） | | `gitlink-search` | 搜索功能（仓库、用户等） | | `gitlink-user` | 用户管理（个人信息等） | | `gitlink-pm` | 项目管理（Sprint、看板、周报等） | | `gitlink-workflow` | AI 自动化工作流（Issue 分类、PR Review、Release Notes 等） | +| `gitlink-maintainer-copilot` | 维护者驾驶舱、证据包、治理剧本和确认后创建治理 Issue | ## 项目结构 @@ -688,12 +313,10 @@ gitlink-cli/ │ ├── repo/ # 仓库 shortcuts │ ├── issue/ # Issue shortcuts │ ├── pr/ # PR shortcuts -│ ├── member/ # 仓库成员 shortcuts │ ├── branch/ # 分支 shortcuts │ ├── release/ # Release shortcuts │ ├── org/ # 组织 shortcuts │ ├── ci/ # CI shortcuts -│ ├── pipeline/ # Pipeline shortcuts │ ├── search/ # 搜索 shortcuts │ ├── user/ # 用户 shortcuts │ └── register.go # 注册入口 @@ -717,7 +340,7 @@ gitlink-cli/ ## 文档 -- [Skills 使用指南](./skills/README.md) — AI Agent Skills 详细说明 +- [Skills 使用指南](skills/README.md) — AI Agent Skills 详细说明 - [设计文档](doc/design.md) — 架构设计和开发计划 ## 常见问题 @@ -780,7 +403,7 @@ gitlink-cli 使用 Windows Credential Manager 安全存储 Token。如果 Creden ### Q: 如何查看完整的 API 参考？ -查看 [skills/gitlink-shared/references/api-reference.md](./skills/gitlink-shared/references/api-reference.md) +查看 [skills/gitlink-shared/references/api-reference.md](skills/gitlink-shared/references/api-reference.md) ## 许可证 diff --git a/npm/package.json b/npm/package.json index 3f37a7c..1fcc3a8 100644 --- a/npm/package.json +++ b/npm/package.json @@ -8,7 +8,7 @@ }, "scripts": { "postinstall": "node scripts/install.js", - "test": "node test/install.test.js && node test/cli.test.js" + "test": "node test/install.test.js && node test/cli.test.js && node test/skills.test.js" }, "keywords": [ "gitlink", diff --git a/npm/test/skills.test.js b/npm/test/skills.test.js new file mode 100644 index 0000000..f2310b2 --- /dev/null +++ b/npm/test/skills.test.js @@ -0,0 +1,106 @@ +"use strict"; + +const assert = require("assert"); +const fs = require("fs"); +const path = require("path"); + +const skillsDir = path.resolve(__dirname, "..", "..", "skills"); + +const requiredSkillFiles = { + "gitlink-maintainer-copilot": [ + "SKILL.md", + "references/evidence-pack.md", + "references/playbooks.md", + "references/governance-issue-template.md", + "examples/maintainer-copilot-workflow.md", + "examples/sample-dashboard-report.md", + ], +}; + +function readText(file) { + return fs.readFileSync(file, "utf8"); +} + +function parseFrontmatter(markdown, file) { + const match = markdown.match(/^---\n([\s\S]*?)\n---\n/); + assert.ok(match, `${file} must start with YAML frontmatter`); + + const fields = {}; + for (const line of match[1].split("\n")) { + const fieldMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/); + if (fieldMatch) { + fields[fieldMatch[1]] = fieldMatch[2].replace(/^["']|["']$/g, ""); + } + } + return fields; +} + +function markdownFiles(root) { + const files = []; + for (const entry of fs.readdirSync(root, { withFileTypes: true })) { + const fullPath = path.join(root, entry.name); + if (entry.isDirectory()) { + files.push(...markdownFiles(fullPath)); + } else if (entry.isFile() && entry.name.endsWith(".md")) { + files.push(fullPath); + } + } + return files; +} + +function localMarkdownLinks(markdown) { + const links = []; + const linkPattern = /\[[^\]]+\]\(([^)]+)\)/g; + let match; + while ((match = linkPattern.exec(markdown)) !== null) { + const target = match[1].trim(); + if ( + target.startsWith("http://") || + target.startsWith("https://") || + target.startsWith("#") || + target.startsWith("mailto:") + ) { + continue; + } + links.push(target.split("#")[0]); + } + return links.filter(Boolean); +} + +for (const [skillName, files] of Object.entries(requiredSkillFiles)) { + for (const file of files) { + assert.ok( + fs.existsSync(path.join(skillsDir, skillName, file)), + `${skillName} must include ${file}` + ); + } +} + +const skillDirs = fs + .readdirSync(skillsDir, { withFileTypes: true }) + .filter((entry) => entry.isDirectory() && entry.name.startsWith("gitlink-")) + .map((entry) => entry.name) + .sort(); + +const names = new Set(); + +for (const dirName of skillDirs) { + const skillFile = path.join(skillsDir, dirName, "SKILL.md"); + assert.ok(fs.existsSync(skillFile), `${dirName} must include SKILL.md`); + + const frontmatter = parseFrontmatter(readText(skillFile), skillFile); + assert.equal(frontmatter.name, dirName, `${dirName} frontmatter name must match directory`); + assert.ok(frontmatter.description, `${dirName} must include description`); + assert.ok(!names.has(frontmatter.name), `${frontmatter.name} must be unique`); + names.add(frontmatter.name); +} + +for (const file of markdownFiles(skillsDir)) { + const markdown = readText(file); + for (const link of localMarkdownLinks(markdown)) { + const targetPath = path.resolve(path.dirname(file), link); + assert.ok(fs.existsSync(targetPath), `${file} links to missing file: ${link}`); + } +} + +console.log("skills structure tests passed"); diff --git a/skills/README.md b/skills/README.md index 22e1b19..f808dda 100644 --- a/skills/README.md +++ b/skills/README.md @@ -64,62 +64,41 @@ skills/ ├── README.md # 本文件 ├── gitlink-shared/ # 共享基础规则 │ ├── SKILL.md # 认证、全局参数、安全规则、分支约定 -│ └── references/ -│ ├── api-reference.md # API 详细参考、错误处理 -│ ├── raw-api-batch.md # 批量 Raw API 调用参考 -│ └── troubleshooting.md # 常见问题排查 +│ └── references/ # API 参考、错误处理 ├── gitlink-repo/ # 仓库管理 │ ├── SKILL.md # 仓库操作指南 -│ └── references/ # 仓库命令参考文档 +│ └── references/ # 仓库 API 参考 ├── gitlink-issue/ # Issue 管理 │ ├── SKILL.md # Issue 操作指南 -│ └── references/ # Issue 命令参考文档 +│ └── references/ # Issue API 参考 ├── gitlink-pr/ # Pull Request │ ├── SKILL.md # PR 操作指南 -│ └── references/ # PR 命令参考文档 -├── gitlink-member/ # 仓库成员管理 -│ └── SKILL.md # 成员与邀请链接操作指南 +│ └── references/ # PR API 参考 ├── gitlink-branch/ # 分支管理 │ ├── SKILL.md # 分支操作指南 │ └── examples/ │ └── branch-workflow.md # 分支工作流 -├── gitlink-tag/ # Git 标签管理 -│ └── SKILL.md # 标签操作指南 ├── gitlink-release/ # 版本发布 │ ├── SKILL.md # Release 操作指南 -│ └── references/ # Release 命令参考文档 -├── gitlink-release-auto/ # 自动化 Release 管理 -│ └── SKILL.md # 自动发版、版本号推荐、Release Notes 生成 +│ └── references/ # Release API 参考 ├── gitlink-search/ # 搜索功能 │ ├── SKILL.md # 搜索操作指南 -│ └── references/ # 搜索命令参考文档 +│ └── references/ # 搜索参考 ├── gitlink-user/ # 用户管理 -│ ├── SKILL.md # 用户操作指南 -│ └── references/ # 用户命令参考文档 +│ └── SKILL.md # 用户操作指南 ├── gitlink-org/ # 组织管理 │ ├── SKILL.md # 组织操作指南 -│ └── references/ # 组织命令参考文档 +│ └── references/ # 组织参考 ├── gitlink-ci/ # CI/CD │ └── SKILL.md # CI 操作指南 -├── gitlink-pipeline/ # 流水线工作流 -│ └── SKILL.md # Pipeline 操作指南 -├── gitlink-wiki/ # Wiki 页面管理 -│ └── SKILL.md # Wiki 操作指南 -├── gitlink-notification/ # 用户消息 -│ └── SKILL.md # 消息查询、已读和删除指南 ├── gitlink-pm/ # 项目管理 │ └── SKILL.md # PM 操作指南 -├── gitlink-health/ # 项目健康度分析 -│ ├── SKILL.md # 健康度分析指南 -│ ├── data/ -│ │ ├── .gitignore # 忽略 *.db 文件 -│ │ └── .gitkeep # 占位文件 -│ ├── references/ -│ │ └── queries.md # SQL 查询参考 -│ └── asset/ -│ └── health_report_template.md # 报告模板 -└── gitlink-workflow/ # AI 自动化工作流 - └── SKILL.md # 工作流模板（Issue 分类、PR Review、Release Notes） +├── gitlink-workflow/ # AI 自动化工作流 +│ └── SKILL.md # 工作流模板（Issue 分类、PR Review、Release Notes） +└── gitlink-maintainer-copilot/ # 维护者驾驶舱 + ├── SKILL.md # 证据包、治理剧本、写入确认 + ├── references/ # 证据包、剧本、治理 Issue 模板 + └── examples/ # 演示流程和样例报告 ``` --- @@ -131,13 +110,11 @@ skills/ | Skill | 说明 | 常用命令 | |-------|------|----------| | **gitlink-shared** | 认证、全局参数、API 参考、安全规则、分支约定 | `auth login`, `auth status` | -| **gitlink-repo** | 仓库管理与洞察 | `repo +list`, `repo +info`, `repo +languages`, `repo +contributors`, `repo +code-stats`, `repo +follow`, `repo +like`, `repo +units`, `repo +set-units` | -| **gitlink-issue** | Issue 管理 | `issue +create`, `issue +list`, `issue +view`, `issue +close`, `issue +batch-close`, `issue +batch-update`, `issue +batch-delete` | -| **gitlink-pr** | Pull Request | `pr +list`, `pr +create`, `pr +view`, `pr +merge`, `pr +versions`, `pr +version-diff`, `pr +reviews`, `pr +review` | -| **gitlink-member** | 仓库成员管理 | `member +list`, `member +add`, `member +batch-add`, `member +role`, `member +invite-link` | +| **gitlink-repo** | 仓库管理 | `repo +list`, `repo +create`, `repo +info`, `repo +fork` | +| **gitlink-issue** | Issue 管理 | `issue +create`, `issue +list`, `issue +view`, `issue +close`, `issue +batch-close` | +| **gitlink-pr** | Pull Request | `pr +list`, `pr +create`, `pr +view`, `pr +merge`, `pr +review` | | **gitlink-branch** | 分支管理 | `branch +list`, `branch +create`, `branch +delete`, `branch +protect` | -| **gitlink-tag** | Git 标签管理 | `tag +list`, `tag +names`, `tag +view`, `tag +delete` | -| **gitlink-release** | 版本发布 | `release +list`, `release +create`, `release +edit`, `release +update`, `release +view` | +| **gitlink-release** | 版本发布 | `release +list`, `release +create`, `release +view` | ### 辅助 Skills @@ -147,12 +124,9 @@ skills/ | **gitlink-user** | 用户管理 | `user +me`, `user +info` | | **gitlink-org** | 组织管理 | `org +list`, `org +info`, `org +members` | | **gitlink-ci** | CI/CD | `ci +builds`, `ci +logs` | -| **gitlink-pipeline** | 流水线工作流 | `pipeline +runs`, `pipeline +run`, `pipeline +logs` | -| **gitlink-wiki** | Wiki 页面管理 | `wiki +list`, `wiki +view`, `wiki +create`, `wiki +update`, `wiki +delete` | -| **gitlink-notification** | 用户消息 | `notification +list`, `notification +read`, `notification +delete` | | **gitlink-pm** | 项目管理 | 通过 Raw API 访问 | | **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、Release Notes | -| **gitlink-health** | 开源项目健康度 | 详情见SKILL.md | +| **gitlink-maintainer-copilot** | 维护者驾驶舱 | 证据包、治理剧本、确认后创建治理 Issue | --- @@ -178,13 +152,13 @@ gitlink-cli repo +info --owner wbtiger --repo gitlink-cli gitlink-cli issue +create -t "Bug: 登录失败" -b "复现步骤..." # 查看 Issue -gitlink-cli issue +view -i 123 +gitlink-cli issue +view -n 123 # 添加评论 gitlink-cli issue +comment -i 123 -b "已修复" # 关闭 Issue -gitlink-cli issue +close -i 123 +gitlink-cli issue +close -n 123 # 预览批量关闭 Issue gitlink-cli issue +batch-close --numbers 123,124 --dry-run @@ -226,6 +200,17 @@ gitlink-cli org +info -i Gitlink 详见: [gitlink-search/SKILL.md](gitlink-search/SKILL.md) +### 场景 5：生成维护者驾驶舱 + +```bash +# Agent 会先只读采集证据，再输出治理计划 +gitlink-cli repo +info --owner Gitlink --repo gitlink-cli --format json +gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state open --format json +gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state open --format json +``` + +详见: [gitlink-maintainer-copilot/SKILL.md](gitlink-maintainer-copilot/SKILL.md) + --- ## 📚 文档导航 @@ -242,22 +227,23 @@ gitlink-cli org +info -i Gitlink **仓库操作**: - [gitlink-repo/SKILL.md](gitlink-repo/SKILL.md) - 仓库命令 - [gitlink-branch/SKILL.md](gitlink-branch/SKILL.md) - 分支命令 -- [gitlink-repo/SKILL.md](gitlink-repo/SKILL.md) - 完整工作流 **Issue 和 PR**: - [gitlink-issue/SKILL.md](gitlink-issue/SKILL.md) - Issue 命令 - [gitlink-pr/SKILL.md](gitlink-pr/SKILL.md) - PR 命令 -- [gitlink-issue/SKILL.md](gitlink-issue/SKILL.md) - Issue 工作流 **发布和搜索**: - [gitlink-release/SKILL.md](gitlink-release/SKILL.md) - Release 命令 -- [gitlink-pipeline/SKILL.md](gitlink-pipeline/SKILL.md) - Pipeline 命令 - [gitlink-search/SKILL.md](gitlink-search/SKILL.md) - 搜索命令 **组织和用户**: - [gitlink-org/SKILL.md](gitlink-org/SKILL.md) - 组织命令 - [gitlink-user/SKILL.md](gitlink-user/SKILL.md) - 用户命令 +**维护者驾驶舱**: +- [gitlink-maintainer-copilot/SKILL.md](gitlink-maintainer-copilot/SKILL.md) - 维护者诊断 +- [gitlink-maintainer-copilot/examples/maintainer-copilot-workflow.md](gitlink-maintainer-copilot/examples/maintainer-copilot-workflow.md) - 演示流程 + --- ## ❓ 常见问题 @@ -318,6 +304,7 @@ AI 代理可以： - ✅ 自动分类 Issue - ✅ 自动生成 Release Notes - ✅ 自动执行代码审查 +- ✅ 自动生成维护者驾驶舱和治理 Issue 草稿 --- @@ -329,7 +316,7 @@ AI 代理可以： - 所有边界情况处理正确 - 完整的文档和示例 -详见: [../doc/design.md](../doc/design.md) +可通过 `cd npm && npm test` 验证 Skill 结构和安装脚本。 --- @@ -337,7 +324,6 @@ AI 代理可以： - [主项目 README](../README.md) - gitlink-cli 项目说明 - [设计文档](../doc/design.md) - 架构设计和开发计划 -- [API 参考文档](../doc/gitlink_api_reference.md) - GitLink API 参考文档 - [gitlink-bisync](https://www.gitlink.org.cn/wbtiger/gitlink-bisync) - 代码双向同步系统 --- diff --git a/skills/gitlink-maintainer-copilot/SKILL.md b/skills/gitlink-maintainer-copilot/SKILL.md new file mode 100644 index 0000000..f9da63a --- /dev/null +++ b/skills/gitlink-maintainer-copilot/SKILL.md @@ -0,0 +1,143 @@ +--- +name: gitlink-maintainer-copilot +version: 1.0.0 +description: "Use when a maintainer wants a GitLink project diagnosis, governance plan, contributor-readiness check, or a confirmed governance Issue for a repository." +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli --help" +--- + +# gitlink-maintainer-copilot + +**CRITICAL - 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理、JSON 输出和 GitLink 工具边界。** +**CRITICAL - 默认只读。只有用户明确确认后，才允许创建治理 Issue 或发表评论。** +**CRITICAL - 所有结论必须绑定证据；无法采集的数据必须标记为“数据缺失”，不得猜测。** + +## 目标 + +本 Skill 帮助 Agent 把 GitLink 仓库数据转化为维护者可执行的驾驶舱： + +- Maintainer Evidence Pack：采集仓库、Issue、PR、Commit、贡献者、Release、CI、README 等证据。 +- Playbook Diagnosis：根据证据匹配维护剧本，解释风险来源。 +- 30/60/90 天治理计划：把风险变成可执行任务。 +- Governance Issue Draft：生成可确认落地的治理 Issue 草稿。 + +详细规则见： + +- [`references/evidence-pack.md`](references/evidence-pack.md) +- [`references/playbooks.md`](references/playbooks.md) +- [`references/governance-issue-template.md`](references/governance-issue-template.md) + +## 适用场景 + +当用户提出以下需求时使用本 Skill： + +- “帮我分析这个 GitLink 仓库是否健康” +- “给项目做维护者驾驶舱” +- “找出 Issue/PR 堵塞点” +- “给开源项目生成治理计划” +- “帮我创建一个项目治理 Issue” +- “比赛演示需要一个可落地的 GitLink Skill” + +不要用于： + +- 单纯查看某个 Issue、PR、Release 的详情；改用对应领域 Skill。 +- 直接批量修改 Issue、关闭 PR、删除资源。 +- GitHub/GitLab 仓库；本 Skill 只面向 GitLink。 + +## 工作流 + +### 1. 建立上下文 + +1. 阅读 `gitlink-shared`。 +2. 确认 `owner` 和 `repo`。如果当前目录是 GitLink 仓库，可以依赖 `gitlink-cli` 自动从 remote 解析。 +3. 说明默认只读，并告诉用户写入治理 Issue 前会二次确认。 + +### 2. 采集证据 + +优先使用 Shortcuts，所有命令都加 `--format json`。 + +```bash +gitlink-cli repo +info --owner --repo --format json +gitlink-cli issue +list --owner --repo --state open --limit 100 --format json +gitlink-cli issue +list --owner --repo --state closed --limit 100 --format json +gitlink-cli pr +list --owner --repo --state open --limit 100 --format json +gitlink-cli pr +list --owner --repo --state merged --limit 100 --format json +gitlink-cli pr +list --owner --repo --state closed --limit 100 --format json +gitlink-cli release +list --owner --repo --format json +gitlink-cli ci +builds --owner --repo --format json +``` + +Shortcuts 未覆盖时使用 Raw API： + +```bash +gitlink-cli api GET /v1///commits --query 'page=1&limit=100' --format json +gitlink-cli api GET /v1///contributors/stat --format json +gitlink-cli api GET ///languages --format json +gitlink-cli api GET ///readme --format json +``` + +如果某个命令失败，不要中断整个诊断。记录： + +- 命令 +- 失败原因 +- 该缺失会影响哪些判断 + +### 3. 生成 Evidence Pack + +按 [`references/evidence-pack.md`](references/evidence-pack.md) 汇总证据。每条结论都必须能追溯到至少一个证据项。 + +证据引用格式： + +```text +[E3: open_prs] open PR count = 8, oldest updated_at = 2026-03-10 +``` + +### 4. 匹配治理剧本 + +按 [`references/playbooks.md`](references/playbooks.md) 选择 1-3 个剧本。优先选择证据最充分、对维护者最有行动价值的剧本。 + +输出时必须包含： + +- 匹配剧本名称 +- 触发证据 +- 风险等级：High / Medium / Low +- 本周可执行动作 +- 30/60/90 天治理计划 + +### 5. 生成驾驶舱报告 + +报告必须包含： + +1. 项目维护状态总览 +2. Evidence Pack 摘要 +3. 3-5 个关键风险 +4. 匹配到的治理剧本 +5. 30/60/90 天治理计划 +6. Governance Issue 草稿 +7. 数据缺失和可信度说明 + +参考 [`examples/sample-dashboard-report.md`](examples/sample-dashboard-report.md)。 + +### 6. 写入确认闸门 + +默认不要写入 GitLink。只有当用户明确说“创建治理 Issue”“发布这个 Issue”“确认写入”等同义指令后，才可以执行写入。 + +写入前必须展示将执行的命令和完整 Issue 内容： + +```bash +gitlink-cli issue +create --owner --repo \ + --title "" \ + --body "" +``` + +用户确认后只创建一个治理 Issue。不要批量创建 Issue，不要关闭 Issue，不要评论 PR，除非用户另行明确要求。 + +## 输出准则 + +- 用中文输出，保留 Evidence Pack、Playbook、Governance Issue 等少量英文术语。 +- 风险判断要克制：有证据就判断，无证据就标注缺失。 +- 建议必须能被维护者执行，避免“加强管理”“优化流程”这类空话。 +- 治理任务要有验收标准，例如“关闭或回复 10 个超过 14 天未更新的 Issue”。 +- 如果仓库是新项目或数据量很少，报告重点转为“治理基线补齐”，不要给出虚假的趋势分析。 diff --git a/skills/gitlink-maintainer-copilot/examples/maintainer-copilot-workflow.md b/skills/gitlink-maintainer-copilot/examples/maintainer-copilot-workflow.md new file mode 100644 index 0000000..71f8e1b --- /dev/null +++ b/skills/gitlink-maintainer-copilot/examples/maintainer-copilot-workflow.md @@ -0,0 +1,85 @@ +# Maintainer Copilot Workflow + +本示例展示 Agent 如何使用 `gitlink-maintainer-copilot` 生成维护者驾驶舱，并在用户确认后创建治理 Issue。 + +## 1. 用户请求 + +```text +帮我给 Gitlink/gitlink-cli 生成一个维护者驾驶舱，并准备一个可落地的治理 Issue。 +``` + +## 2. Agent 声明只读采集 + +```text +我会先使用 gitlink-cli 只读采集仓库、Issue、PR、Release、CI、Commit 和贡献者数据。不会写入 GitLink；如果需要创建治理 Issue，我会先展示完整草稿并等待你确认。 +``` + +## 3. 采集证据 + +```bash +gitlink-cli repo +info --owner Gitlink --repo gitlink-cli --format json +gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state open --limit 100 --format json +gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state closed --limit 100 --format json +gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state open --limit 100 --format json +gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state merged --limit 100 --format json +gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state closed --limit 100 --format json +gitlink-cli release +list --owner Gitlink --repo gitlink-cli --format json +gitlink-cli ci +builds --owner Gitlink --repo gitlink-cli --format json +gitlink-cli api GET /v1/Gitlink/gitlink-cli/commits --query 'page=1&limit=100' --format json +gitlink-cli api GET /v1/Gitlink/gitlink-cli/contributors/stat --format json +gitlink-cli api GET /Gitlink/gitlink-cli/languages --format json +gitlink-cli api GET /Gitlink/gitlink-cli/readme --format json +``` + +## 4. 输出驾驶舱报告 + +报告结构： + +```markdown +# GitLink Maintainer Copilot Report + +## 维护状态总览 +... + +## Evidence Pack +... + +## 关键风险 +... + +## 匹配 Playbooks +... + +## 30/60/90 天治理计划 +... + +## Governance Issue 草稿 +... + +## 数据缺失与可信度 +... +``` + +完整样例见 [`sample-dashboard-report.md`](sample-dashboard-report.md)。 + +## 5. 请求写入确认 + +Agent 展示完整治理 Issue 草稿后询问： + +```text +以上是将创建的治理 Issue 内容。请明确回复“确认创建治理 Issue”，我才会执行写入。 +``` + +## 6. 用户确认后创建 Issue + +```bash +gitlink-cli issue +create --owner Gitlink --repo gitlink-cli \ + --title "chore: 建立 gitlink-cli 项目维护治理计划" \ + --body "<完整治理 Issue 正文>" +``` + +## 7. 完成后回报 + +```text +治理 Issue 已创建。后续维护者可以按 30/60/90 天计划逐项勾选，并在下次运行 Maintainer Copilot 时对比进度。 +``` diff --git a/skills/gitlink-maintainer-copilot/examples/sample-dashboard-report.md b/skills/gitlink-maintainer-copilot/examples/sample-dashboard-report.md new file mode 100644 index 0000000..109c479 --- /dev/null +++ b/skills/gitlink-maintainer-copilot/examples/sample-dashboard-report.md @@ -0,0 +1,126 @@ +# GitLink Maintainer Copilot Report + +> 样例报告使用模拟数据，适合比赛 README、截图或录屏展示。真实执行时必须使用 `gitlink-cli` 采集 Evidence Pack。 + +## 维护状态总览 + +项目：`Gitlink/gitlink-cli` + +总体判断：维护状态为 **Medium Risk**。项目已有清晰 CLI 能力和 Agent Skills 基础，但 PR 响应、Release 节奏和新人引导材料需要进一步稳定。 + +可信度：High。已采集仓库详情、Issue、PR、Release、Commit、贡献者和 README 数据；CI 数据缺失。 + +## Evidence Pack + +| 编号 | 摘要 | +|---|---| +| E1 repo_profile | 仓库有 README、默认分支为 `master`，License 存在，watchers=42，forked=18 | +| E2 open_issues | open Issue 16 个，其中 5 个超过 14 天未更新 | +| E3 closed_issues | 最近关闭 Issue 22 个，说明仍有维护活动 | +| E4 open_prs | open PR 7 个，其中 3 个超过 7 天未更新 | +| E5 merged_prs | 最近合并 PR 11 个，主要集中在 CLI bugfix 和文档 | +| E7 releases | 最近 Release 距今 45 天 | +| E8 ci_builds | 数据缺失，无法判断 CI 稳定性 | +| E9 commits | 最近 100 个提交中包含 18 个 fix、9 个 docs、6 个 feat | +| E10 contributors | 贡献者 6 人，前 2 名贡献占比约 76% | +| E12 readme | README 有安装说明，但贡献入口和新人任务入口不明显 | + +## 关键风险 + +1. **PR 堵塞风险中等**：[E4] open PR 7 个，3 个超过 7 天未更新，可能降低外部贡献者反馈体验。 +2. **新人转化不足**：[E12] README 缺少明确新人入口；[E2] open Issue 中可领取任务标识不足。 +3. **Release 节奏不稳定**：[E7] 最近 Release 距今 45 天；[E9] 已累计多项 fix/feat/docs 变更。 +4. **贡献者集中度偏高**：[E10] 前 2 名贡献占比约 76%，存在维护者负载集中风险。 +5. **CI 可信度缺失**：[E8] 未采集到 CI 数据，无法确认基础自动化质量。 + +## 匹配 Playbooks + +### P2 PR 堵塞清理 + +触发证据：[E4] open PR 7 个，其中 3 个超过 7 天未更新。 + +本周动作： + +- 对所有 open PR 留下最新维护者反馈。 +- 将 PR 分为“可合并 / 需要修改 / 已过期”三组。 +- 优先处理文档和低风险 bugfix PR。 + +### P3 新人友好改造 + +触发证据：[E12] README 新人入口不足；[E2] open Issue 缺少可领取标识。 + +本周动作： + +- 在 README 增加“首次贡献”小节。 +- 选择 3 个低风险 Issue 补充复现步骤和验收标准。 +- 给新人任务添加清晰标签或标题前缀。 + +### P4 Release 稳定化 + +触发证据：[E7] Release 间隔较长；[E9] 最近已有多项用户可见变更。 + +本周动作： + +- 生成下一版 Release Notes 草稿。 +- 将最近合并变更归类为 Added / Fixed / Docs。 +- 确认 CI 或手工验证结果后再发布。 + +## 30/60/90 天治理计划 + +30 天： + +- [ ] 所有 open PR 都有维护者反馈，超过 14 天未更新的 PR 降到 0。 +- [ ] README 增加首次贡献入口和本地运行最短路径。 +- [ ] 建立下一个 Release 的变更清单草稿。 + +60 天： + +- [ ] 固化 PR 评审 SLA，例如 7 天内首次响应。 +- [ ] 整理 3-5 个适合新人领取的 Issue。 +- [ ] 补齐 Issue/PR 模板，降低沟通成本。 + +90 天： + +- [ ] 形成每月维护节奏，固定回顾 Issue、PR、Release 状态。 +- [ ] 将基础检查纳入 CI 或公开验证说明。 +- [ ] 复盘新人 Issue 的领取和合并情况。 + +## Governance Issue 草稿 + +标题： + +```text +chore: 建立 gitlink-cli 项目维护治理计划 +``` + +正文摘要： + +```markdown +## 背景 + +本 Issue 由 GitLink Maintainer Copilot 根据仓库数据生成，用于跟踪项目维护治理动作。 + +## 诊断结论 + +风险等级：Medium + +匹配治理剧本： + +- P2 PR 堵塞清理：[E4] open PR 7 个，3 个超过 7 天未更新。 +- P3 新人友好改造：[E12] README 新人入口不足。 +- P4 Release 稳定化：[E7] Release 距今 45 天。 + +## 本周建议动作 + +- [ ] 回复所有超过 7 天未更新的 open PR。 +- [ ] 补 README 首次贡献入口。 +- [ ] 生成下一版 Release Notes 草稿。 +``` + +## 数据缺失与可信度 + +| 缺失项 | 影响 | 建议 | +|---|---|---| +| E8 ci_builds | 无法判断 CI 稳定性 | 维护者可补充 CI 权限或手工验证记录 | + +确认写入前，Agent 必须展示完整 Issue 正文并等待用户明确确认。 diff --git a/skills/gitlink-maintainer-copilot/references/evidence-pack.md b/skills/gitlink-maintainer-copilot/references/evidence-pack.md new file mode 100644 index 0000000..487f61f --- /dev/null +++ b/skills/gitlink-maintainer-copilot/references/evidence-pack.md @@ -0,0 +1,63 @@ +# Maintainer Evidence Pack + +Evidence Pack 是维护者驾驶舱的证据层。Agent 必须先采集证据，再给诊断和建议。 + +## 采集原则 + +- 优先只读命令。 +- 每条诊断至少引用一个证据编号。 +- 采集失败时记录缺失，不猜测。 +- 同一个指标来自多个命令时，以更具体的数据为准，并说明来源。 + +## 证据清单 + +| 编号 | 名称 | 命令 | 主要字段 | 用途 | +|---|---|---|---|---| +| E1 | repo_profile | `gitlink-cli repo +info --format json` | `full_name`, `description`, `default_branch`, `license_name`, `watchers_count`, `forked_count`, `issues_count`, `pull_requests_count`, `empty` | 判断基础治理、项目吸引力、默认分支和公开信息 | +| E2 | open_issues | `gitlink-cli issue +list --state open --limit 100 --format json` | `subject`, `project_issues_index`, `created_at`, `updated_at`, `status_name`, `priority_name`, `assigners`, `tags`, `comment_journals_count` | 判断 Issue 积压、无人响应、分类质量 | +| E3 | closed_issues | `gitlink-cli issue +list --state closed --limit 100 --format json` | 同 E2 | 判断处理节奏、关闭质量、近期维护痕迹 | +| E4 | open_prs | `gitlink-cli pr +list --state open --limit 100 --format json` | `title`, `pull_request_number`, `created_at`, `updated_at`, `pull_request_status`, `user`, `head`, `base` | 判断 PR 堵塞、评审延迟、分支目标 | +| E5 | merged_prs | `gitlink-cli pr +list --state merged --limit 100 --format json` | 同 E4 | 判断合并效率、近期协作活跃度 | +| E6 | closed_prs | `gitlink-cli pr +list --state closed --limit 100 --format json` | 同 E4 | 判断拒绝/关闭模式 | +| E7 | releases | `gitlink-cli release +list --format json` | `name`, `tag_name`, `created_at`, `description`, `version_id` | 判断发布成熟度 | +| E8 | ci_builds | `gitlink-cli ci +builds --format json` | `id`, `status`, `created_at`, `duration`, `branch`, `commit` | 判断自动化质量 | +| E9 | commits | `gitlink-cli api GET /v1///commits --query 'page=1&limit=100' --format json` | `sha`, `commit_message`, `commit_time`, `author`, `files` | 判断近期活跃、提交分布和变更主题 | +| E10 | contributors | `gitlink-cli api GET /v1///contributors/stat --format json` | `total_count`, `contributors[].login`, `contributions`, `additions`, `deletions` | 判断贡献者集中度和协作风险 | +| E11 | languages | `gitlink-cli api GET ///languages --format json` | language map | 判断技术栈和 README/CI 建议 | +| E12 | readme | `gitlink-cli api GET ///readme --format json` | `content`, `encoding`, `sha` | 判断新手上手信息 | + +## 缺失数据处理 + +记录格式： + +```markdown +| 缺失项 | 命令 | 影响 | 后续建议 | +|---|---|---|---| +| E8 ci_builds | `gitlink-cli ci +builds ...` | 无法判断 CI 稳定性 | 在报告中把 CI 结论标为“未验证” | +``` + +常见处理： + +- `401`：提示用户运行 `gitlink-cli auth login`，继续公开数据诊断。 +- `403`：说明权限不足，避免输出内部治理判断。 +- `404`：确认 owner/repo 是否正确。 +- 空数组：这不是失败。应解读为“当前样本为空”，例如暂无 Release 或暂无 open PR。 + +## 证据引用格式 + +在报告中使用紧凑引用： + +```markdown +- PR 堵塞风险高：[E4] open PR 8 个，其中 3 个超过 14 天未更新。 +- 发布成熟度不足：[E7] 未发现 Release；[E9] 最近 100 个提交中已有 12 个 feat/fix 变更。 +``` + +## 可信度等级 + +| 等级 | 条件 | +|---|---| +| High | E1-E7 至少 6 项可用，且 E9 或 E10 至少 1 项可用 | +| Medium | E1-E7 至少 4 项可用 | +| Low | 少于 4 项可用，或关键数据仅来自单一来源 | + +可信度低时，输出应以“建议先补齐数据采集/权限”为主。 diff --git a/skills/gitlink-maintainer-copilot/references/governance-issue-template.md b/skills/gitlink-maintainer-copilot/references/governance-issue-template.md new file mode 100644 index 0000000..828b063 --- /dev/null +++ b/skills/gitlink-maintainer-copilot/references/governance-issue-template.md @@ -0,0 +1,94 @@ +# Governance Issue Template + +创建治理 Issue 前，必须先把完整草稿展示给用户并获得明确确认。 + +## 标题模板 + +```text +chore: 建立 项目维护治理计划 +``` + +## 正文模板 + +```markdown +## 背景 + +本 Issue 由 GitLink Maintainer Copilot 根据仓库公开/授权数据生成，用于跟踪项目维护治理动作。 + +## Evidence Pack + +- [E1: repo_profile] <仓库基础信息摘要> +- [E2: open_issues] +- [E4: open_prs] +- [E7: releases] +- [E9: commits] <提交活跃摘要> +- [E10: contributors] <贡献者摘要> + +数据缺失： + +- <如无缺失，写“无关键缺失”。> + +## 诊断结论 + +风险等级： + +匹配治理剧本： + +- ：<触发证据> + +关键风险： + +1. <风险 1，引用证据> +2. <风险 2，引用证据> +3. <风险 3，引用证据> + +## 30/60/90 天计划 + +30 天： + +- [ ] <任务，含验收标准> +- [ ] <任务，含验收标准> + +60 天： + +- [ ] <任务，含验收标准> +- [ ] <任务，含验收标准> + +90 天： + +- [ ] <任务，含验收标准> +- [ ] <任务，含验收标准> + +## 本周建议动作 + +- [ ] <最小可执行动作 1> +- [ ] <最小可执行动作 2> +- [ ] <最小可执行动作 3> + +## 验收标准 + +- <可验证标准 1> +- <可验证标准 2> +- <可验证标准 3> + +--- + +生成方式：GitLink Maintainer Copilot Skill +``` + +## 写入命令 + +用户确认后执行： + +```bash +gitlink-cli issue +create --owner --repo \ + --title "chore: 建立 项目维护治理计划" \ + --body "<上方正文>" +``` + +## 禁止事项 + +- 不要批量创建多个治理 Issue。 +- 不要在未确认前执行写入。 +- 不要把 Token、私有邮箱、调试日志放入 Issue 正文。 +- 不要把缺失数据写成确定结论。 diff --git a/skills/gitlink-maintainer-copilot/references/playbooks.md b/skills/gitlink-maintainer-copilot/references/playbooks.md new file mode 100644 index 0000000..29be607 --- /dev/null +++ b/skills/gitlink-maintainer-copilot/references/playbooks.md @@ -0,0 +1,166 @@ +# Maintainer Playbooks + +Playbook 是把 Evidence Pack 转成治理动作的规则库。Agent 应选择 1-3 个最相关剧本。 + +## P1 低活跃恢复 + +触发条件： + +- [E9] 最近 30 天提交很少或没有提交。 +- [E2] open Issue 有新增但缺少回复。 +- [E10] 贡献者集中在 1-2 人。 + +风险信号： + +- 项目对外仍有关注、Fork 或 Issue，但维护节奏下降。 +- 新贡献者不知道项目是否还接受贡献。 + +本周动作： + +- 回复所有超过 14 天未更新的 open Issue。 +- 创建“维护状态说明”Issue，说明当前优先级和可接受贡献范围。 +- 标记 2-3 个适合外部贡献者的小任务。 + +30/60/90 天计划： + +- 30 天：清理过期 Issue，保留可复现、可行动的问题。 +- 60 天：补 README 的安装、运行、贡献入口。 +- 90 天：建立每月一次的维护节奏，发布一个小版本或维护公告。 + +验收标准： + +- open Issue 中超过 14 天未回复的数量减少 70%。 +- 至少 3 个 Issue 有明确下一步。 +- README 有贡献入口或维护状态说明。 + +## P2 PR 堵塞清理 + +触发条件： + +- [E4] open PR 数量较多。 +- [E4] 存在超过 7 天未更新或未评审的 PR。 +- [E5] merged PR 样本少于 open PR 样本。 + +风险信号： + +- 贡献者提交后长期没有反馈。 +- PR 无法合并导致贡献热情下降。 + +本周动作： + +- 按“可合并 / 需要修改 / 已过期”三类整理 open PR。 +- 对每个超过 7 天未更新的 PR 留下明确反馈。 +- 优先合并低风险文档、测试、修复类 PR。 + +30/60/90 天计划： + +- 30 天：把 open PR 降到可管理数量。 +- 60 天：建立 PR 模板和评审 SLA。 +- 90 天：把常见检查迁移到 CI，减少人工评审负担。 + +验收标准： + +- 所有 open PR 都有最新维护者反馈。 +- 超过 14 天未更新的 open PR 数量降到 0 或给出关闭理由。 +- 新 PR 平均首次响应时间少于 7 天。 + +## P3 新人友好改造 + +触发条件： + +- [E12] README 缺少安装、运行、测试、贡献指南中的任意两项。 +- [E2] open Issue 缺少标签或优先级。 +- [E10] 贡献者数量少，但项目仍有 Issue 或关注。 + +风险信号： + +- 潜在贡献者无法判断从哪里开始。 +- Issue 内容对新人不可执行。 + +本周动作： + +- 在 README 补充最短运行路径。 +- 给 2-5 个简单 Issue 加上“good first issue”或等价说明。 +- 为新人任务补充复现步骤、预期行为和验收标准。 + +30/60/90 天计划： + +- 30 天：补齐 README、CONTRIBUTING 或 Issue 模板。 +- 60 天：形成新人任务池。 +- 90 天：复盘新人贡献转化，保留有效标签和模板。 + +验收标准： + +- README 包含安装、运行、测试、贡献四个入口。 +- 至少 3 个 Issue 可被新人独立领取。 +- 新 Issue 模板能引导用户提供复现信息。 + +## P4 Release 稳定化 + +触发条件： + +- [E7] 没有 Release，或最近 Release 距今较久。 +- [E9] 最近提交包含多项功能或修复。 +- [E5] 已合并 PR 有明显用户可见变更。 + +风险信号： + +- 用户无法判断可用版本。 +- 变更沉淀在提交记录中，没有形成版本说明。 + +本周动作： + +- 生成下一版 Release Notes 草稿。 +- 梳理已合并变更为 `Added / Fixed / Changed / Docs`。 +- 明确是否需要补充测试或 CI 后再发布。 + +30/60/90 天计划： + +- 30 天：发布一个维护版本或明确下个版本计划。 +- 60 天：固定 Release Notes 模板。 +- 90 天：把 Release 与里程碑、Issue、PR 建立关联。 + +验收标准： + +- 至少有一个可追溯 Release 或版本计划。 +- Release Notes 能关联主要 Issue/PR/Commit。 +- 用户能从 README 找到最新稳定版本。 + +## P5 基础治理补齐 + +触发条件： + +- [E1] `license_name` 为空。 +- [E1] description 为空或项目元信息不足。 +- [E8] CI 数据缺失或持续失败。 +- [E12] README 缺失或内容过短。 + +风险信号： + +- 项目难以被搜索、复用、评审或贡献。 +- 比赛/开源收录时材料不完整。 + +本周动作： + +- 补项目描述、License、README 快速开始。 +- 确认默认分支和基础 CI 状态。 +- 建立一个“项目治理基线”Issue 追踪补齐事项。 + +30/60/90 天计划： + +- 30 天：补齐 README、License、基础元信息。 +- 60 天：补 Issue/PR 模板和贡献说明。 +- 90 天：形成版本发布、CI、维护响应的固定节奏。 + +验收标准： + +- 仓库详情中项目描述、License、README 均可见。 +- CI 至少覆盖构建或测试中的一项。 +- 维护者能用一个治理 Issue 跟踪剩余事项。 + +## 选择规则 + +- High 风险剧本优先。 +- 同类风险只选择一个主剧本，避免输出重复建议。 +- 如果数据样本少，优先选择 P5 基础治理补齐。 +- 如果用户明确关注新人、Release 或 PR，则用户目标优先于自动排序。