13 KiB

Raw Blame History

gitlink-cli 项目指南

项目背景

本项目是《软件演化与运维》（2026 春）课程的进阶实践任务：GitLink 智能化能力提升项目。

GitLink CLI 是 GitLink 平台的命令行工具，采用 Go 语言开发（cobra 框架），提供 40+ 命令覆盖仓库管理、Issue 跟踪、PR 协作、CI/CD 等场景，并内置 AI Agent Skills 体系，兼容 Claude Code 等主流 Agent 平台。

仓库：https://gitlink.org.cn/gitlink/gitlink-cli（本仓库 fork 自 z2_cc/gitlink-cli）
Skills 开发指南：skills/README.md
API 文档：https://s.apifox.cn/da30afb0-9d2e-429b-a4bc-a83209e06021
CLI 设计文档：doc/design.md

进阶任务包含四个子任务（已全部完成），另加 DevOps 流水线：

子任务	定位	占比	技术栈
子任务一	扩展 CLI 能力	50%	Go
子任务二	编写 Skills	20%	Markdown + CLI
子任务三	端到端工作流	20%	Shell + Skills 编排
子任务四	科研辅助（加分项）	额外加分	Markdown + CLI
DevOps	CI/CD 流水线	10%	YAML

🧭 操作中心（交互式菜单）

触发方式（任一即可）：

输入 /gitlink（斜杠命令，最推荐），可附带参数：/gitlink 代码审查、/gitlink https://gitlink.org.cn/z2_cc/gitlink-cli
直接说「常用操作」、「常用操作以及场景」、「列出操作」、「gitlink 菜单」

触发后按 .claude/commands/gitlink.md 的流程：先列出全部 16 项操作（单项操作 / 分析与成长 / 端到端自动化 / 科研辅助），再用原生上下方向键菜单让用户选择，或接收一个 GitLink 仓库网址直接对其操作，最后调用对应已实现的 skill 执行（写操作默认 dry-run）。操作 → skill 映射见该命令文件。

技术架构

gitlink-cli/
├── main.go                  # 入口
├── cmd/                     # CLI 命令定义（cobra）
│   ├── root.go              # 根命令，注册所有 shortcuts
│   ├── api/api.go           # raw API 调用：gitlink api <METHOD> <PATH>
│   ├── auth/                # 认证：login/logout/status/refresh
│   ├── config/              # 配置管理
│   └── interactive/         # 交互式 REPL（bubbletea TUI）
├── shortcuts/               # 23 个命令组（repo/issue/pr/release/ci/…）
│   ├── register.go          # RegisterAll() 注册入口
│   ├── common/              # 共享类型 + 批量操作框架（batch.go）
│   └── {group}/             # 每个命令组一个目录
├── internal/                # 核心包
│   ├── auth/                # 登录、token 存储、HTTP 传输
│   ├── client/              # API 客户端（auto-.json、分页、错误映射）
│   ├── config/              # 配置文件管理
│   ├── context/             # 自动解析 owner/repo（从 git remote）
│   └── output/              # 格式化输出（json/table/yaml）
├── skills/                  # 32 个 Skill 定义（SKILL.md + examples/ + scripts/）
├── .claude/skills/          # Claude Code 使用的符号链接 → ../../skills/{name}
├── .devops/                 # GitLink DevOps 流水线（3 个 YAML）
├── doc/                     # 设计文档、交接文档、架构图
└── my_docs/                 # 工作文档、总结、计划

子任务一：CLI 能力扩展（Go）

定位：为 gitlink-cli 增加新功能、优化现有功能。所有改动在 cmd/、shortcuts/、internal/ 中。

已完成（P1-P4）

优先级	内容	关键文件
P1 Bug 修复（3 项）	`--label` 参数未发送、硬编码 `master` 默认分支、`pr +diff`/`+files` 重复	`shortcuts/issue/`, `shortcuts/common/`, `shortcuts/pr/`
P2 参数补全（10 项）	补全 `--milestone`/`--assignee`/`--priority`/`--sort` 等 CLI 参数与 API 的映射	`shortcuts/issue/`, `shortcuts/pr/`, `shortcuts/release/`
P3 批量操作（9 个命令）	通用批量框架 + issue/PR/collaborator/branch 批量命令，支持 `--dry-run`/`--yes`/CSV 输入	`shortcuts/common/batch.go`
P4 体验优化	40+ 命令帮助文档、破坏性操作确认提示、API 错误友好建议	`shortcuts/*/`, `internal/client/`

交互式 REPL

cmd/interactive/ 提供基于 bubbletea 的 TUI：命令面板（模糊搜索）→ 参数表单 → 输出查看器。支持 / 前缀打开面板。

后续可完善方向

补全 GitLink OpenAPI 中尚未封装的 Raw API
新增 Shortcut 命令组（如看板增强）
跨平台兼容性和安装体验优化
单元测试覆盖

子任务二：Skills 开发（Markdown + CLI）

定位：基于 gitlink-cli 开发 AI Agent Skill。核心交付物是 SKILL.md + 使用示例 + Agent 平台验证。

Skills 规范

每个 Skill 位于 skills/{name}/，包含：

SKILL.md：YAML 前-matter（name、description、triggers）+ 使用说明
examples/：Agent 对话记录或运行示例
scripts/（可选）：可执行脚本

已完成的 Skills（32 个）

平台基础操作（原始 11 个 + 扩展）： gitlink-repo gitlink-issue gitlink-pr gitlink-release gitlink-branch gitlink-org gitlink-user gitlink-search gitlink-ci gitlink-webhook gitlink-wiki gitlink-snippet gitlink-pm

智能化 Skills（子任务二核心交付）： gitlink-code-review gitlink-pr-deep-review gitlink-issue-triage gitlink-release-auto gitlink-project-health gitlink-insight gitlink-commit-quality gitlink-compliance gitlink-duplicate-detector gitlink-newcomer-guide

工作流 Skills（子任务三）： gitlink-community-ops gitlink-quality-gate gitlink-workflow

科研 Skills（子任务四）： gitlink-research-insight gitlink-research-hotspot gitlink-research-matching gitlink-research-progress gitlink-research-compliance

共享基础： gitlink-shared（认证、全局参数、安全规则）

后续可完善方向

为现有 Skill 补充更多 Agent 平台验证（OpenClaw、Cursor）
优化 Skill 触发词准确性
增加 Skill 使用示例的覆盖度

子任务三：端到端自动化工作流（Shell + Skills 编排）

定位：组合 gitlink-cli 命令和 Skills，完成可复现的端到端自动化场景。每个工作流串联 ≥3 个步骤。

场景 A：社区运营自动化

skills/gitlink-community-ops/ — 三阶段流水线：

Issue 分拣（关键词分析 → 建议标签）
社区周报（Issue/PR/Commit/Milestone 统计）
Release Notes 生成（Conventional Commits 分类）

关键文件：community-ops-full.sh（全流程编排）、health-analyze.js、release-analyze.js

场景 B：代码质量看门人

skills/gitlink-quality-gate/ — 四阶段门禁：

PR 采集 → 2. 深度审查 → 3. CI 检查 → 4. 评分决策（≥70 分 + CI 通过 → 建议合并）

评分模型：CodeReview(40%) + CI(30%) + 设计一致性(30%)

关键文件：quality-gate-full.sh（全流程编排）

DevOps 流水线

.devops/ 目录下 3 个 YAML 配置，均配置在 z2_cc/gitlink-cli：

构建流水线.yml：push 触发 Go 构建 + 版本校验
社区运营流水线.yml：定时触发社区运营全流程
代码质量门禁流水线.yml：PR 触发质量门禁

后续可完善方向

贡献者成长体系（追踪→排行→徽章）
多仓库协同场景
项目一键初始化工作流
工作流的错误恢复和通知机制

子任务四：科研辅助（Markdown + CLI，加分项）

定位：依托 gitlink-cli 数据获取与 AI Agent 能力，为科研场景提供智能化辅助。设计原则：evidence-oriented（证据驱动）、read-only（只读不写）、delegation pattern（委托已有 Skill）、pure remote analysis（纯远程分析）。

已完成的 5 个科研 Skill

Skill	功能	关键文件
`gitlink-research-insight`	仓库级科研项目洞悉：8 维数据采集 + 4 维 AI 分析（成熟度/文档/贡献模式/社区健康），输出结构化评分报告	`scripts/research-insight-full.sh`、`scripts/analyze.js`
`gitlink-research-hotspot`	科研热点追踪：多关键词搜索 → 实体提取 → 关系图构建 → Mermaid.js 知识图谱 + 交互式 HTML 可视化	`scripts/hotspot-tracker-full.sh`、`scripts/kg-to-html.js`
`gitlink-research-matching`	科研协作智能匹配：4 角色推断（数据/算法/工程/评估）→ 人员-任务匹配 → 资源探测 → 综合建议报告	`examples/matching-run.md`（已验证于 `Gitlink/forgeplus`）
`gitlink-research-progress`	科研进度跟踪与预警：6 维风险信号（停滞 Issue/高优无人/零回复/积压趋势/提交突变/里程碑 DDL），100 分制风险评分	已验证于 `forgeplus`/`gitlink-cli`/`FairMOT`
`gitlink-research-compliance`	科研合规与复现性检查：数据可用性/环境可复现/结果可验证 4 维评估	`examples/reproducibility-check.md`（已验证于 `ifzhang/FairMOT`）

共享工具

skills/gitlink-shared/scripts/ 提供 detect-cli.sh（CLI 版本检测）和 md-to-html.js（报告转交互式 HTML）。

后续可完善方向

增加更多科研仓库验证案例
知识图谱的交互式探索能力
科研主体画像功能
创新启发式推荐

Skill 触发映射

当用户提及以下内容时，优先调用对应 Skill（而非手动执行命令）：

平台操作

Issue 管理 → gitlink-issue
PR 管理 → gitlink-pr
Release / 发版 / changelog → gitlink-release 或 gitlink-release-auto
仓库管理 → gitlink-repo
分支管理 → gitlink-branch
组织管理 → gitlink-org
CI/CD → gitlink-ci
Wiki → gitlink-wiki
代码片段 → gitlink-snippet
Webhook → gitlink-webhook
搜索 → gitlink-search

智能化与自动化

代码审查 / PR Review → gitlink-code-review 或 gitlink-pr-deep-review
Issue 分拣 / 分类 / Triage → gitlink-issue-triage
项目健康度 / 周报 → gitlink-project-health 或 gitlink-insight
新人引导 / good-first-issue → gitlink-newcomer-guide
重复 Issue 检测 → gitlink-duplicate-detector
许可证合规检查 → gitlink-compliance
提交质量检查 → gitlink-commit-quality
项目管理 / Sprint / 看板 → gitlink-pm

工作流（子任务三）

社区运营自动化 / 周报生成 → gitlink-community-ops
代码质量门禁 / PR 自动门禁 → gitlink-quality-gate
工作流模板参考 → gitlink-workflow

科研辅助（子任务四）

科研项目洞悉 / 成熟度评估 / 仓库洞察 → gitlink-research-insight
科研热点追踪 / 知识图谱 / 研究趋势 → gitlink-research-hotspot
科研协作匹配 / 角色推断 → gitlink-research-matching
科研进度跟踪 / 风险预警 → gitlink-research-progress
科研合规检查 / 复现性评估 → gitlink-research-compliance

工作流扩展（子任务五）

项目一键初始化 / 创建仓库 / 生成 README/LICENSE/CI / 初始 Issue 和里程碑 → 调用 gitlink-project-bootstrap skill
多仓库协同 / 跨仓库 Issue 追踪 / PR 状态看板 / Release 协调发布 → 调用 gitlink-multi-repo-coordination skill（通过 REPOS="owner/repo,..." 指定多仓库）
贡献者成长体系 / 贡献排行 / 成长段位 / 自动颁发徽章 → 调用 gitlink-contributor-growth skill

开发约定

命令使用

所有 GitLink API 操作使用 gitlink-cli 命令，不得直接调用 REST API
使用 Skill 前先阅读对应 SKILL.md 和 skills/gitlink-shared/SKILL.md 了解认证与已知限制
命令输出优先使用 --format json 获取结构化数据

构建与测试

make build          # 编译到 bin/gitlink-cli
make install        # 安装到 $GOPATH/bin
go test ./...       # 运行所有测试

添加新 Skill

在 skills/ 下创建目录（如 skills/gitlink-xxx/）
编写 SKILL.md（参考 skills/README.md 规范）
在 .claude/skills/ 创建符号链接：ln -s ../../skills/gitlink-xxx gitlink-xxx
更新本文件的 Skill 映射表

关键参考文档

doc/design.md — CLI 设计文档
doc/sub-task34-交接文档.md — 子任务三、四交接文档
my_docs/summary.md — 子任务一 P1-P4 改进总结
skills/README.md — Skills 开发规范
skills/gitlink-shared/SKILL.md — 共享基础（认证、安全规则）

13 KiB Raw Blame History Unescape Escape

gitlink-cli 项目指南

项目背景

🧭 操作中心（交互式菜单）

技术架构

子任务一：CLI 能力扩展（Go）

已完成（P1-P4）

交互式 REPL

后续可完善方向

子任务二：Skills 开发（Markdown + CLI）

Skills 规范

已完成的 Skills（32 个）

后续可完善方向

子任务三：端到端自动化工作流（Shell + Skills 编排）

场景 A：社区运营自动化

场景 B：代码质量看门人

DevOps 流水线

后续可完善方向

子任务四：科研辅助（Markdown + CLI，加分项）

已完成的 5 个科研 Skill

共享工具

后续可完善方向

Skill 触发映射

平台操作

智能化与自动化

工作流（子任务三）

科研辅助（子任务四）

工作流扩展（子任务五）

开发约定

命令使用

构建与测试

添加新 Skill

关键参考文档

13 KiB

Raw Blame History