feat: 新增安装脚本 + CI 配置 + 命令帮助文档 + 跨平台验证报告

- 新增 scripts/install.sh: Linux/macOS 一键安装脚本 - 新增 scripts/install.ps1: Windows PowerShell 安装脚本 - 修改 .devops/ci.yml: 更新 CI 支持 wyx_branch 分支 - 新增 doc/commands/pm.md: pm 模块命令参考手册 - 新增 doc/commands/wiki.md: wiki 模块命令参考手册 - 新增 doc/commands/alias-browse-status.md: alias/browse/status 命令参考手册 - 新增 doc/commands/export.md: export 模块命令参考手册 - 新增 doc/commands/cross-platform.md: 跨平台兼容性验证报告关联 Issue: #16
2026-06-03 12:07:13 +08:00 · 2026-06-03 12:07:13 +08:00 · b887e5053d
parent 2cc0e5c08b
commit b887e5053d
8 changed files with 408 additions and 2 deletions
--- a/.devops/ci.yml
+++ b/.devops/ci.yml
@ -17,7 +17,7 @@ workflow:
    task: git_clone@1.2.9
    input:
      remote_url: '"https://gitlink.org.cn/jiangtx/gitlink-cli.git"'
-      ref: '"refs/heads/jtx_branch"'
+      ref: '"refs/heads/wyx_branch"'
      commit_id: '""'
      depth: 1
    needs:
@ -31,7 +31,7 @@ workflow:
      ssh_port: '"22"'
      ssh_user: '"root"'
      ssh_cmd: >-
-        "cd /root && rm -rf gitlink-cli && git clone --depth=1 -b jtx_branch https://gitlink.org.cn/jiangtx/gitlink-cli.git && cd gitlink-cli && export PATH=$PATH:/usr/local/go/bin && export GOPROXY=https://goproxy.cn,direct && go version && go build ./... && go vet ./... && go test -race ./... && output=$(gofmt -s -l .) && if [ -n \"$output\" ]; then echo '格式化检查失败:' && echo \"$output\" && exit 1; fi && echo '所有 CI 检查通过'"
+        "cd /root && rm -rf gitlink-cli && git clone --depth=1 -b wyx_branch https://gitlink.org.cn/jiangtx/gitlink-cli.git && cd gitlink-cli && export PATH=$PATH:/usr/local/go/bin && export GOPROXY=https://goproxy.cn,direct && go version && go build ./... && go vet ./... && go test -race ./... && output=$(gofmt -s -l .) && if [ -n \"$output\" ]; then echo '格式化检查失败:' && echo \"$output\" && exit 1; fi && echo '所有 CI 检查通过'"
    needs:
      - git_clone_0
  - ref: end
--- a/doc/commands/alias-browse-status.md
+++ b/doc/commands/alias-browse-status.md
@ -0,0 +1,104 @@
+# alias — 命令别名管理
+
+> 关联 Issue: #14 | PR: #11
+
+## 概述
+
+alias 命令用于管理 gitlink-cli 的命令别名，将常用长命令缩短为简短别名，提升日常使用效率。对标 `gh alias`。
+
+## 命令列表
+
+### alias +list
+- **用途**: 列出所有已定义的命令别名
+- **示例**: `gitlink-cli alias +list`
+
+### alias +set \<name\> \<command\>
+- **用途**: 设置命令别名
+- **参数**: name（别名名称）和 command（实际命令）
+- **示例**:
+  - `gitlink-cli alias +set rl "repo +list"`
+  - `gitlink-cli alias +set ri "repo +info --owner Gitlink --repo gitlink-cli"`
+
+### alias +delete \<name\>
+- **用途**: 删除已定义的命令别名
+- **参数**: name（要删除的别名名称）
+- **示例**: `gitlink-cli alias +delete rl`
+
+## 存储
+
+别名存储在 `~/.config/gitlink-cli/aliases.yaml` 文件中，格式为 YAML。
+
+---
+
+# browse — 浏览器打开 GitLink 页面
+
+> 关联 Issue: #14 | PR: #11
+
+## 概述
+
+browse 命令用于在浏览器中快速打开当前仓库或指定资源的 GitLink 页面。对标 `gh browse`。
+
+## 用法
+
+```
+gitlink-cli browse [resource]
+```
+
+- 不带参数：打开当前仓库主页
+- 带参数：打开指定资源页面
+
+## 示例
+
+```bash
+# 打开当前仓库主页
+gitlink-cli browse
+
+# 打开指定 Issue
+gitlink-cli browse issues/42
+
+# 打开指定 PR
+gitlink-cli browse pulls/128
+
+# 打开 Wiki 页面
+gitlink-cli browse wiki
+```
+
+## 跨平台支持
+
+- macOS: 使用 `open` 命令
+- Windows: 使用 `start` 命令
+- Linux: 使用 `xdg-open` 命令
+
+---
+
+# status — 显示当前状态
+
+> 关联 Issue: #14 | PR: #11
+
+## 概述
+
+status 命令显示 gitlink-cli 的当前状态信息，包括认证状态、API 地址、当前目录和自动推断的仓库信息。对标 `gh auth status`。
+
+## 用法
+
+```bash
+gitlink-cli status
+```
+
+## 输出示例
+
+```
+GitLink CLI 状态
+───────────────
+  认证状态:    已登录
+  Token 来源:  keyring / 配置文件
+  API 地址:    https://www.gitlink.org.cn/api
+  当前目录:    /home/user/projects/gitlink-cli
+  推断仓库:    Gitlink/gitlink-cli
+```
+
+## 功能说明
+
+- 自动检测 Token 来源（环境变量 GITLINK_TOKEN / keyring / 配置文件）
+- 自动从 git remote 推断 owner/repo
+- 未登录时给出 `gitlink-cli auth login` 提示
--- a/doc/commands/cross-platform.md
+++ b/doc/commands/cross-platform.md
@ -0,0 +1,47 @@
+# 跨平台兼容性验证报告
+
+> 关联 Issue: #16 | PR: #13
+
+## 测试矩阵
+
+| 验证项 | Windows 11 | macOS | Ubuntu |
+|--------|:---:|:---:|:---:|
+| `git clone` + `go build ./...` | 待验证 | 待验证 | 待验证 |
+| `go test -race ./...` 全部通过 | 待验证 | 待验证 | 待验证 |
+| `gitlink-cli auth login` 登录 | 待验证 | 待验证 | 待验证 |
+| `gitlink-cli repo +list` 可用 | 待验证 | 待验证 | 待验证 |
+| `gitlink-cli pm +dashboards` 可用 | 待验证 | 待验证 | 待验证 |
+| `gitlink-cli wiki +pages` 可用 | 待验证 | 待验证 | 待验证 |
+| `gitlink-cli alias +list` 可用 | 待验证 | 待验证 | 待验证 |
+| `gitlink-cli browse` 打开浏览器 | 待验证 | 待验证 | 待验证 |
+| `gitlink-cli status` 显示状态 | 待验证 | 待验证 | 待验证 |
+| `gitlink-cli export +issues` 导出 | 待验证 | 待验证 | 待验证 |
+| Token 存储（keyring）正常 | 待验证 | 待验证 | 待验证 |
+
+## 安装脚本
+
+| 脚本 | 平台 | 路径 |
+|------|------|------|
+| install.sh | Linux / macOS | `scripts/install.sh` |
+| install.ps1 | Windows | `scripts/install.ps1` |
+
+## CI 配置
+
+| 配置文件 | 说明 |
+|---------|------|
+| `.devops/ci.yml` | 建木流水线：push 到 wyx_branch 时自动触发构建+测试+格式化检查 |
+
+### CI 检查内容
+
+| 检查项 | 命令 | 说明 |
+|--------|------|------|
+| 构建 | `go build ./...` | 确保代码编译通过 |
+| 静态分析 | `go vet ./...` | 检测常见代码问题 |
+| 测试 | `go test -race ./...` | 运行全部测试，含竞态检测 |
+| 格式化 | `gofmt -s -l .` | 确保代码格式符合 Go 标准 |
+
+## 已知问题
+
+1. **Windows keyring**: Windows Credential Manager 可能需要额外配置
+2. **Linux keyring**: 需要 dbus 服务支持，无桌面环境时可能不可用
+3. **browse 命令**: Linux 环境需要安装 xdg-utils 包
--- a/doc/commands/export.md
+++ b/doc/commands/export.md
@ -0,0 +1,68 @@
+# export — 数据导出命令
+
+> 关联 Issue: #15 | PR: #12
+
+## 概述
+
+export 模块提供将仓库数据（Issue、PR、贡献者）导出为 CSV 或 JSON 文件的能力，支持离线分析和科研用途。
+
+## 命令列表
+
+### export +issues
+- **用途**: 导出仓库 Issue 列表为 CSV 或 JSON 文件
+- **API**: GET /v1/:owner/:repo/issues
+- **参数**:
+  - --format, -f (可选) 输出格式: csv / json，默认 csv
+  - --output, -o (可选) 输出文件路径，默认 issues.csv
+  - --state, -s (可选) 状态过滤: open / closed / all，默认 all
+  - --page, -p (可选) 起始页，默认 1
+  - --limit, -l (可选) 每页数量，默认 50
+- **示例**:
+  - `gitlink-cli export +issues --format csv --output my_issues.csv`
+  - `gitlink-cli export +issues --format json --state open`
+
+### export +prs
+- **用途**: 导出仓库 PR 列表为 CSV 或 JSON 文件
+- **API**: GET /v1/:owner/:repo/pulls
+- **参数**:
+  - --format, -f (可选) 输出格式: csv / json，默认 csv
+  - --output, -o (可选) 输出文件路径，默认 prs.csv
+  - --state, -s (可选) 状态过滤，默认 all
+  - --page, -p (可选) 起始页，默认 1
+  - --limit, -l (可选) 每页数量，默认 50
+- **示例**:
+  - `gitlink-cli export +prs --format json`
+  - `gitlink-cli export +prs --state closed --output closed_prs.csv`
+
+### export +contributors
+- **用途**: 导出贡献者统计为 CSV 或 JSON 文件
+- **API**: GET /:owner/:repo/contributors
+- **参数**:
+  - --format, -f (可选) 输出格式: csv / json，默认 csv
+  - --output, -o (可选) 输出文件路径，默认 contributors.csv
+- **示例**:
+  - `gitlink-cli export +contributors --format json`
+
+## CSV 输出格式
+
+### issues.csv
+```csv
+id,title,state,created_at
+1,Bug fix,1,2026-01-01
+```
+
+### prs.csv
+```csv
+id,title,state,created_at
+2,Feature PR,0,2026-02-01
+```
+
+### contributors.csv
+```csv
+id,login,contributions
+1,dev1,42
+```
+
+## 向后兼容性
+
+无破坏性变更。所有命令通过 export 域组 + 前缀添加。
--- a/doc/commands/pm.md
+++ b/doc/commands/pm.md
@ -0,0 +1,49 @@
+# pm — 项目管理命令
+
+> 关联 Issue: #12 | PR: #9
+
+## 概述
+
+pm 模块提供 GitLink 项目管理相关的命令，包括仪表盘、Sprint 任务、周报、标签、流水线和 Action 运行记录的查看。
+
+## 命令列表
+
+### pm +dashboards
+- **用途**: 查看项目仪表盘数据
+- **API**: GET /pm/dashboards?project_id=\<id\>
+- **参数**: --project (必填) 项目 ID
+- **示例**: `gitlink-cli pm +dashboards --project 123`
+
+### pm +sprints
+- **用途**: 查看 Sprint 任务列表
+- **API**: GET /pm/sprint_issues?project_id=\<id\>
+- **参数**: --project (必填) 项目 ID
+- **示例**: `gitlink-cli pm +sprints --project 123`
+
+### pm +weekly
+- **用途**: 查看周报任务
+- **API**: GET /pm/weekly_issues?project_id=\<id\>
+- **参数**: --project (必填) 项目 ID
+- **示例**: `gitlink-cli pm +weekly --project 123`
+
+### pm +tags
+- **用途**: 查看项目 Issue 标签
+- **API**: GET /pm/issue_tags?project_id=\<id\>
+- **参数**: --project (必填) 项目 ID
+- **示例**: `gitlink-cli pm +tags --project 123`
+
+### pm +pipelines
+- **用途**: 查看项目 CI/CD 流水线列表
+- **API**: GET /pm/pipelines?project_id=\<id\>
+- **参数**: --project (必填) 项目 ID
+- **示例**: `gitlink-cli pm +pipelines --project 123`
+
+### pm +runs
+- **用途**: 查看项目 Action 运行记录
+- **API**: GET /pm/action_runs?project_id=\<id\>
+- **参数**: --project (必填) 项目 ID
+- **示例**: `gitlink-cli pm +runs --project 123`
+
+## 向后兼容性
+
+无破坏性变更。所有命令通过 pm 域组 + 前缀添加。
--- a/doc/commands/wiki.md
+++ b/doc/commands/wiki.md
@ -0,0 +1,49 @@
+# wiki — Wiki 管理命令
+
+> 关联 Issue: #13 | PR: #10
+
+## 概述
+
+wiki 模块提供 GitLink 仓库 Wiki 页面的管理命令，支持列出、查看、创建、更新和删除 Wiki 页面。
+
+## 命令列表
+
+### wiki +pages
+- **用途**: 列出仓库所有 Wiki 页面
+- **API**: GET /api/wiki/wikiPages
+- **参数**: 无（自动从 git remote 推断 owner/repo）
+- **示例**: `gitlink-cli wiki +pages`
+
+### wiki +get
+- **用途**: 获取指定 Wiki 页面内容
+- **API**: GET /api/wiki/getWiki?id=\<id\>
+- **参数**: --id, -i (必填) Wiki 页面 ID
+- **示例**: `gitlink-cli wiki +get --id 42`
+
+### wiki +create
+- **用途**: 创建新的 Wiki 页面
+- **API**: POST /api/wiki/createWiki
+- **参数**:
+  - --title, -t (必填) 页面标题
+  - --content, -c (必填) 页面内容（Markdown）
+  - --project (可选) 项目 ID
+- **示例**: `gitlink-cli wiki +create --title "Getting Started" --content "# Welcome"`
+
+### wiki +update
+- **用途**: 更新已有 Wiki 页面
+- **API**: PUT /api/wiki/updateWiki
+- **参数**:
+  - --id, -i (必填) Wiki 页面 ID
+  - --title, -t (可选) 新标题
+  - --content, -c (可选) 新内容（Markdown）
+- **示例**: `gitlink-cli wiki +update --id 42 --title "Updated Title"`
+
+### wiki +delete
+- **用途**: 删除 Wiki 页面
+- **API**: POST /api/wiki/deleteWiki
+- **参数**: --id, -i (必填) Wiki 页面 ID
+- **示例**: `gitlink-cli wiki +delete --id 42`
+
+## 向后兼容性
+
+无破坏性变更。所有命令通过 wiki 域组 + 前缀添加。
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@ -0,0 +1,40 @@
+# GitLink CLI 一键安装脚本 (Windows PowerShell)
+Write-Host "=========================================" -ForegroundColor Cyan
+Write-Host "  GitLink CLI 安装脚本 (Windows)" -ForegroundColor Cyan
+Write-Host "=========================================" -ForegroundColor Cyan
+
+$binary = "gitlink-cli-windows-amd64.exe"
+$url = "https://gitlink.org.cn/Gitlink/gitlink-cli/releases/download/latest/$binary"
+$installDir = "$env:LOCALAPPDATA\gitlink-cli"
+$dest = "$installDir\gitlink-cli.exe"
+
+Write-Host "下载地址: $url"
+
+# 创建安装目录
+if (-not (Test-Path $installDir)) {
+    New-Item -ItemType Directory -Path $installDir -Force | Out-Null
+}
+
+# 下载
+try {
+    Invoke-WebRequest -Uri $url -OutFile $dest -UseBasicParsing
+    Write-Host "下载完成" -ForegroundColor Green
+} catch {
+    Write-Host "下载失败: $_" -ForegroundColor Red
+    exit 1
+}
+
+# 添加到 PATH（用户级别）
+$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+if ($userPath -notlike "*$installDir*") {
+    [Environment]::SetEnvironmentVariable(
+        "Path",
+        "$installDir;$userPath",
+        "User"
+    )
+    Write-Host "已添加到用户 PATH" -ForegroundColor Green
+}
+
+Write-Host ""
+Write-Host "安装完成！" -ForegroundColor Green
+Write-Host "请重新打开终端，运行 gitlink-cli --help 验证安装" -ForegroundColor Yellow
--- a/scripts/install.sh
+++ b/scripts/install.sh
@ -0,0 +1,49 @@
+#!/bin/bash
+# GitLink CLI 一键安装脚本 (Linux / macOS)
+set -e
+
+echo "========================================="
+echo "  GitLink CLI 安装脚本"
+echo "========================================="
+
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+ARCH=$(uname -m)
+
+# 转换架构名称
+case "$ARCH" in
+    x86_64)  ARCH="amd64" ;;
+    aarch64) ARCH="arm64" ;;
+    armv7l)  ARCH="armv7" ;;
+    *)       echo "不支持的架构: $ARCH"; exit 1 ;;
+esac
+
+echo "检测到系统: ${OS} ${ARCH}"
+
+BINARY="gitlink-cli-${OS}-${ARCH}"
+URL="https://gitlink.org.cn/Gitlink/gitlink-cli/releases/download/latest/${BINARY}"
+
+echo "下载地址: $URL"
+
+# 下载
+if command -v curl &> /dev/null; then
+    curl -fsSL "$URL" -o /tmp/gitlink-cli
+elif command -v wget &> /dev/null; then
+    wget -q "$URL" -O /tmp/gitlink-cli
+else
+    echo "错误: 需要 curl 或 wget"
+    exit 1
+fi
+
+# 安装
+chmod +x /tmp/gitlink-cli
+
+if [ "$(id -u)" -eq 0 ]; then
+    mv /tmp/gitlink-cli /usr/local/bin/gitlink-cli
+else
+    echo "需要 sudo 权限安装到 /usr/local/bin/"
+    sudo mv /tmp/gitlink-cli /usr/local/bin/gitlink-cli
+fi
+
+echo ""
+echo "✅ 安装完成！"
+echo "   运行 gitlink-cli --help 验证安装"