# 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`](.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/` — 三阶段流水线：
1. Issue 分拣（关键词分析 → 建议标签）
2. 社区周报（Issue/PR/Commit/Milestone 统计）
3. Release Notes 生成（Conventional Commits 分类）

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

### 场景 B：代码质量看门人

`skills/gitlink-quality-gate/` — 四阶段门禁：
1. 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` 获取结构化数据

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

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

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