# Release Notes — gitlink-cli

> 官方 [GitLink](https://www.gitlink.org.cn) 命令行工具，面向人类用户和 AI Agent。
> 支持 macOS、Linux 和 Windows，覆盖仓库管理、Issue 跟踪、Pull Request、Webhook、CI/CD 及 AI 驱动的工作流。

---

## v0.2.0 (2026-06-17) — 交互式 REPL 与输出大重构

### 里程碑亮点

- ✨ **交互式 REPL 模式**：新增基于 Bubble Tea TUI 框架的命令面板、参数表单与滚动视口
- 📊 **输出系统重构**：统一表格渲染，终结 JSON 回退；支持嵌套对象层级展开、值截断、动态列合并
- 🌏 **全命令中文覆盖**：全部 25+ 命令组的子命令描述、参数注释、帮助文本完成中文化
- 🐛 **P1-P4 缺陷修复**：修复 16 项实测发现的问题，涉及 collaborator、branch、file、tag、interactive 等多个模块
- 🧩 **3 个新 AI Agent Skill**：issue-triage、project-health、newcomer-guide
- 🧪 **大规模测试**：新增交互模式冒烟测试、output 表格渲染单元测试、hook-runner 测试等

### 新增功能

#### 交互式 REPL (Bubble Tea TUI)

- **命令面板** (`/` 快捷键唤起)：实时搜索 80+ 命令，支持模糊匹配
- **参数表单**：选中命令后自动弹出表单填写 flags，支持必填/可选参数
- **滚动视口**：长输出支持上下滚动浏览，不再截断
- **默认 table 输出**：REPL 中统一使用表格格式，告别 JSON 裸输出
- **Ctrl+C/Esc**：正确的退出与返回行为
- **Smoke Test**：所有注册命令执行不 panic 的自动化验证

#### 输出系统重构

- **`printSliceTable` 增强**：表头取自所有行的字段并集，不再仅依赖第一行
- **嵌套 Map 详情视图**：单对象详情（如 `tag +view`、`repo +info`）渲染为可读层级表格，`└` 缩进展开子字段，不再回退 JSON
- **原生 Map Slice 表格化**：`[]map[string]string` 等本地构造数据也渲染为表格，不再显示 `[N items]`
- **值截断与列限制**：超长值（URL、SHA、commit message）自动截断，核心列优先固定
- **已废弃**：`hasOnlyNestedMaps` JSON 回退逻辑移除

#### Skill 与 Workflow

- 新增 3 个 AI Agent Skill：
  - `gitlink-issue-triage` — Issue 分类与优先级评估
  - `gitlink-project-health` — 项目健康度洞察
  - `gitlink-newcomer-guide` — 新贡献者引导
- `gitlink-webhook` Skill：新增 `+failed`、`+task-view` 命令
- 新增 `gitlink-wiki`、`gitlink-snippet` Skill
- 新增 Workflow 自动化示例：issue-triage、project-health、newcomer-guide

#### 命令增强

- **Webhook**：`+failed` 查看失败投递、`+task-view` 支持 UUID/数字 ID 双查询、`--limit` 分页支持
- **Shortcuts**：导出 `GetAllShortcuts` / `GetDescriptions` 供交互模式消费

### Bug 修复

| 模块 | 问题 | 修复 |
|------|------|------|
| **collaborator** | `change-role`/`batch-role` 请求体格式错误导致"未找到用户" | 改为 `{user_id: 整数, role: string}` 格式；自动解析用户名到数字 ID |
| **branch** | protect/unprotect 接口路径误加 `/v1` 导致 404 | 走无 `/v1` 老接口 |
| **branch** | `+list` 字段过多导致表格不稳定 | 投影到核心列：name/protected/last_commit/commit_time |
| **file** | `+get` 端点调用了错误 API | 改为 `/entries` 提取单文件元信息 |
| **file** | `+tree --recursive` 参数被 API 拒绝 | 移除无效 flag |
| **file** | `+create`/`+update`/`+delete` 缺少必需参数 | 补 `--new-branch`、`--sha` 改为必填 |
| **file** | `+replace` 端点已废弃 | 移除该命令 |
| **tag** | `+view` 调用了不存在端点导致"标签不存在" | 改用列表过滤，新增 `findTagByName` |
| **interactive** | 带可选参数的命令跳过表单直接执行 | 改为"有任何 flag 都弹表单" |
| **interactive** | nil Client 导致 panic | `NewRuntimeContext` 初始化 |
| **interactive** | `/` 键响应延迟 | 立即响应而非等待后续输入 |
| **output** | 原生 `[]map[string]string` 不识别为表格 | reflect 统一处理 |
| **output** | 单对象嵌套 Map 回退 JSON | 层级表格展开 |

### 文档与国际化

- **全部 25+ 命令组描述中文化**：repo / pr / issue / branch / tag / file / wiki / webhook / snippet / user / org / ci / search / label / milestone / release / commit / collaborator / attachment / dataset / template / util / sshkey / shortcut / interactive
- **Shortcuts 模块详细中文注释**：参数映射（CLI→API）、批处理模式、设计决策
- **P1-P4 缺陷中文标记**：issue +create --label 遗漏、hardcoded 'master' 等已知问题文档化
- **交互模式设计文档**：实现计划 + 命令面板设计规格

### 基础设施

- **依赖**：引入 `bubbletea`、`bubbles`、`huh` TUI 框架
- **CI**：DevOps 流水线（构建+验证）
- **测试**：interactive smoke test、output 表格渲染回归测试、tag `+view` 单元测试、hook-runner 单元测试

### 贡献者

自 v0.1.18 以来的贡献者（按字母顺序）：

2403_89190320, Leo77, Mengz, Tiger, s2_cc, wangyue789, wqer, yangsai01, 刘焱, 赵昌

---

## v0.1.18 (2026-05-19) — Webhook 集成与 Skills 扩展

> 这也是 v0.2.0 之前带交互式 REPL 内测功能的过渡版本。

### 核心变更

- **交互模式 MVP**：首次合入 Bubble Tea REPL 基础框架（命令执行器 + flag 解析 + TUI 入口），但随后回退（`Revert "Add TUI foundation"`），留待 v0.2.0 正式发布
- **npm 安装**：修复 Windows 二进制缺失问题，改进安装后诊断

---

## v0.1.17 (2026-05-17) — Skills 生态与包管理器支持

### 新功能

- **3 个新 Skill**：`gitlink-code-review`（代码审查）、`gitlink-insight`（仓库洞察）、`gitlink-compliance`（合规检查）
- **2 个自动化 Skill**：`gitlink-release-auto`（自动发版）、`gitlink-commit-quality`（提交信息规范检查）
- **包管理器支持**：Homebrew（macOS/Linux）、Scoop（Windows）、Chocolatey（Windows）
- **CI**：GitHub Release 工作流与 npm 自动发布
- **npm 安装增强**：校验和验证、错误消息改进、版本检查

### 命令增强

- **PR**：新增 `+review` 审查快捷、`+patchset` 补丁集版本切换
- **PR**：`+comment` 评论 CRUD
- **Issue**：`+batch-close` 批量关闭（dry-run 支持）
- **PR/Issue**：统一使用 project-level 编号替代数据库 ID

### Bug 修复

- **Issue**: `+list` 输出使用项目级 Issue 编号
- **PR**: 统一使用 `pull_request_number` 替代 `pull_request_id`
- **Issue**: `update` 时保留描述字段
- **npm**: Windows 二进制缺失导致静默退出

### 文档

- Skills REFERENCE.md 参考文档
- README 更新至 v0.1.17（12 Skills、npm 一键安装）
- Fork-based PR 工作流指南
- Skill 工具边界规则（防止在 GitLink 上误用 gh/hub）

---

## v0.1.14 (2026-05-17) — 全 API 覆盖里程碑

### 新功能

- **40+ 新命令 shortcut**：
  - **Repo**：22 个新 shortcut（settings/stats/social/transfer/invite/migrate/topics）
  - **User**：22 个新 shortcut（messages/stats/transfers/settings/feedback）
  - **PR**：comments CRUD、commits、reopen、update
  - **Issue**：comments CRUD、delete、batch-update、batch-destroy
  - **Branch**：all/default/restore；**Release**：edit/update
  - **协作**：org team-projects；**File**：batch/entries/replace
  - **CI 流水线**、**Wiki 导入/导出**、**Repo 加入/退出/迁移/话题**
  - **Util**、**Dataset**、**Template**、**Attachment** 快捷组
  - **代码片段管理**：`snippet +list/+view/+create/+delete`
  - **看板**：`board +view/+columns/+move`
- **OAuth2 认证**、**颜色检测与 CJK 宽度支持**
- **Wiki 命令改用 Git 操作**：`+list/+view/+create/+update/+delete` 重构为 Git-based

### 跨平台

- **Windows (x64/arm64)** 完整支持
- 终端颜色自动检测与中文字符宽度适配

### Skills

- **6 个新 Skills**：`gitlink-repo`、`gitlink-issue`、`gitlink-pr`、`gitlink-ci`、`gitlink-search`、`gitlink-workflow`
- **Skill 架构升级**：Anthropic Agent Skills 标准
- **pm / org / user / release / branch** 等 Skill 持续完善

### 基础设施

- npm 包 `@gitlink-ai/cli` 分发上线
- `GITLINK_TOKEN` 环境变量支持非交互式认证
- `gitlink-cli-install-skills` 跨平台安装命令

### 项目健康

- 新增 CONTRIBUTORS 章节展示项目贡献者
- 许可证切换至 MulanPSL-2.0（木兰宽松许可证）
- README 中英双语

---

## v0.1.8 ~ v0.1.13 (2026-04-07 ~ 2026-04-15) — 功能夯实

### v0.1.13 (2026-04-15)

- **npm 安装方案**：修复 GitHub Release asset 匹配回退与相对 URL 拼接问题
- 改进 release 创建时默认 `target_commitish=master`
- Issue 创建默认 `priority_id=2`

### v0.1.12 (2026-04-15)

- Webhook 快捷命令组正式合入
- `hook-runner` 集成为 `webhook` 子命令
- 新增 `--limit` 标志与 UUID 显示改进

### v0.1.11 (2026-04-08)

- **PR 审查**：`+review` 审查提交
- **PR 补丁集**：`+patchset-versions` 版本切换
- 3 个新 Skills：`gitlink-code-review`、`gitlink-insight`、`gitlink-compliance`

### v0.1.10 (2026-04-08)

- 2 个自动化 Skill：`gitlink-release-auto`、`gitlink-commit-quality`
- Webhook 端点测试修复

### v0.1.9 (2026-04-07)

- **Webhook shortcut 组**正式版
- Skills 文档完善

### v0.1.8 (2026-04-07)

- **Branch Skill**：`gitlink-branch` 保护分支管理
- PR `+comment` 快捷
- Issue `+batch-close` 批量关闭
- Issue v1 API 迁移，使用 `project_issues_index` 替代数据库 ID
- 修复 Issue 描述 update 丢失问题

---

## v0.1.0-skill-test (2026-04-04) — Skill 概念验证

- Skill PR 全流程测试
- 首个 Skill 原型验证
- PR 创建、合入工作流测试

---

## v0.0.1-test-del / initial (2026-04-03) — 项目初始化

- `github.com/gitlink-org/gitlink-cli` 项目启动
- 基础 CLI 框架（Cobra）
- 初始命令：auth、repo、issue、pr
- npm 分发基础 (`@gitlink-ai/cli`)
- Cookie-based 登录与 token 认证

---

## 统计一览

| 版本 | 日期 | 新增文件 | 代码变更 | 贡献者 |
|------|------|----------|----------|--------|
| init → v0.1.8 | 2026-04 | ~30 | ~8k | 5 |
| v0.1.8 → v0.1.14 | 2026-04~05 | ~60 | ~15k | 8 |
| v0.1.14 → v0.1.18 | 2026-05 | ~22 | +514/-1015 | 4 |
| v0.1.18 → v0.2.0 | 2026-05~06 | 114 | +24531/-324 | 10 |

## Skills 一览

| Skill | 用途 | 引入版本 |
|-------|------|----------|
| `gitlink-repo` | 仓库管理 | v0.1.14 |
| `gitlink-issue` | Issue 跟踪 | v0.1.14 |
| `gitlink-pr` | Pull Request 管理 | v0.1.14 |
| `gitlink-ci` | CI/CD 流水线 | v0.1.14 |
| `gitlink-search` | 全局搜索 | v0.1.14 |
| `gitlink-workflow` | 工作流自动化 | v0.1.14 |
| `gitlink-branch` | 保护分支管理 | v0.1.8 |
| `gitlink-pm` | 项目管理 | v0.1.14 |
| `gitlink-org` | 组织管理 | v0.1.14 |
| `gitlink-user` | 用户管理 | v0.1.14 |
| `gitlink-release` | 发布管理 | v0.1.14 |
| `gitlink-code-review` | 代码审查 | v0.1.11 |
| `gitlink-insight` | 仓库洞察 | v0.1.11 |
| `gitlink-compliance` | 合规检查 | v0.1.11 |
| `gitlink-release-auto` | 自动发版 | v0.1.10 |
| `gitlink-commit-quality` | 提交信息规范 | v0.1.10 |
| `gitlink-webhook` | Webhook 管理 | v0.1.9 |
| `gitlink-wiki` | Wiki 管理 | v0.2.0 |
| `gitlink-snippet` | 代码片段管理 | v0.2.0 |
| `gitlink-issue-triage` | Issue 分类与优先级 | v0.2.0 |
| `gitlink-project-health` | 项目健康度 | v0.2.0 |
| `gitlink-newcomer-guide` | 新贡献者引导 | v0.2.0 |
| `gitlink-shared` | 共享工具库 | v0.2.0 |
| `gitlink-workflow` | 工作流定义 | v0.2.0 |

---

## 升级指南

### v0.1.x → v0.2.0

- **交互模式**：运行 `gitlink-cli interactive` 或 `gitlink-cli tui` 进入 REPL
- **输出格式**：v0.2.0 默认输出格式为 table，如需 JSON 请使用 `--output json` 或 `--json`
- **File 命令**：`+replace` 已移除，请改用 `+create`/`+update`
- **Tag 命令**：`+view` 行为变更（从单端点改为列表过滤），功能一致

### 首次安装

```bash
# npm (推荐)
npm install -g @gitlink-ai/cli

# macOS (Homebrew)
brew tap gitlink-ai/tap
brew install gitlink-cli

# Windows (Scoop)
scoop bucket add gitlink https://github.com/gitlink-ai/scoop-bucket
scoop install gitlink-cli

# Windows (Chocolatey)
choco install gitlink-cli
```

---

> 完整的提交历史请参阅 [CHANGELOG](./changes/) 目录。
> 
> 如发现任何问题，欢迎在 [GitLink Issues](https://www.gitlink.org.cn/Gitlink/gitlink-cli/issues) 反馈。
