forked from Gitlink/gitlink-cli
128 lines
5.3 KiB
Markdown
128 lines
5.3 KiB
Markdown
# Shortcut 命令实现报告
|
||
|
||
## 总体设计模式
|
||
|
||
三个 Shortcut 组（`wiki`、`snippet`、`hook-runner`）虽然功能不同，但整体架构遵循一致的设计模式：
|
||
|
||
1. **命令注册**：每个 Shortcut 组通过 `Shortcuts()` 函数返回 `[]*common.Shortcut`，在 `shortcuts/register.go` 中统一挂载到 cobra 根命令
|
||
2. **上下文注入**：通过 `RuntimeContext` 提供 API 客户端、owner/repo 解析、输出格式化等基础设施
|
||
3. **owner/repo 解析**：每个命令先调用 `ctx.ResolveOwnerRepo()` 从 flags 或 git remote 自动解析
|
||
4. **数据访问**：读操作用公开方式（无需认证），写操作用 Token 认证
|
||
5. **输出格式**：统一支持 `json` / `table` 格式，通过 `ctx.Output()` / `ctx.OutputData()` 输出
|
||
6. **错误处理**：参数校验置前（必填 flag 检查），API 错误直接传播
|
||
|
||
> **注意**：以下所有演示命令假设在 `gitlink-cli` 仓库目录下运行。`--owner` 和 `--repo` 参数会自动从 Git remote 解析，无需手动传入。
|
||
|
||
---
|
||
|
||
## 1. Wiki 管理（`wiki`）
|
||
|
||
### 实现思路
|
||
|
||
GitLink 的 Wiki 本质是一个**独立的 Git 仓库**（`https://gitlink.org.cn/{owner}/{repo}.wiki.git`），每个页面是一个 `.md` 文件，侧边栏由 `_Sidebar.md` 控制。
|
||
|
||
| 操作 | 方式 | 认证 |
|
||
|------|------|------|
|
||
| 读（list/view） | `git clone` 到临时目录，读取文件 | ❌ 公开仓库，无需认证 |
|
||
| 写（create/update/delete） | `git clone` → 修改文件 → `git commit/push` | ✅ Personal Access Token |
|
||
|
||
删除时额外删除 `_Sidebar.md`，让 GitLink 网页端自动从文件列表重建侧边栏，防止残留引用。
|
||
|
||
### 遇到的问题
|
||
|
||
| 问题 | 原因 | 解决方案 |
|
||
|------|------|---------|
|
||
| 修改 `_Sidebar.md` 内容导致网页渲染崩溃 | `_Sidebar.md` 的编码/格式与 GitLink 网页端的预期不一致 | 不修改内容，直接删除文件，让 GitLink 自动重建 |
|
||
| `git add _Sidebar.md` 文件不存在时报错 | `_Sidebar.md` 尚未被网页端生成时不存在 | 用 `git add -A` 替代，自动识别所有变更 |
|
||
|
||
### 演示指令
|
||
|
||
```powershell
|
||
# 列出 Wiki 页面（Git 克隆 → 读取目录 → 输出）
|
||
./gitlink-cli.exe wiki +list --format table
|
||
|
||
# 查看 Wiki 页面内容（Git 克隆 → 读取文件内容 + Git log）
|
||
./gitlink-cli.exe wiki +view --page-name "Wiki测试" --format json
|
||
|
||
# 创建 Wiki 页面（Git 克隆 → 写 .md 文件 → git add/commit/push）
|
||
./gitlink-cli.exe wiki +create --page-name "demo" --title "Demo" --content "Hello World" --message "创建Wiki页面"
|
||
|
||
# 更新 Wiki 页面（Git 克隆 → 修改文件 → git add/commit/push）
|
||
./gitlink-cli.exe wiki +update --page-name "demo" --title "Updated" --content "New content"
|
||
|
||
# 删除 Wiki 页面（Git 克隆 → 删文件+删_Sidebar.md → git add -A/commit/push）
|
||
./gitlink-cli.exe wiki +delete --page-name "demo"
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 代码片段（`snippet`）
|
||
|
||
### 实现思路
|
||
|
||
代码片段存放在项目仓库的 `snippets/` 目录下，每个片段是一个文件，读操作用 Git 克隆，写操作用文件 API。
|
||
|
||
| 操作 | 方式 | 说明 |
|
||
|------|------|------|
|
||
| 列出片段 | `git clone` → 读取 `snippets/` 目录 | 读操作无需认证 |
|
||
| 查看片段 | `git clone` → 读取指定文件内容 | 读操作无需认证 |
|
||
| 创建片段 | `POST /{owner}/{repo}/create_file` API | 写操作需 Token |
|
||
| 删除片段 | `git hash-object` 获取 SHA → `DELETE /delete_file` API | 先获取文件 SHA 再删除 |
|
||
|
||
创建时自动用代码块语法包裹内容（支持 `--language` 指定语言）。
|
||
|
||
### 演示指令
|
||
|
||
```powershell
|
||
# 创建代码片段（POST 文件 API → 写入 snippets/ 目录）
|
||
./gitlink-cli.exe snippet +create --name "hello.py" --content 'print("Hello World!")' --language python --message "添加Python示例"
|
||
|
||
# 列出代码片段（Git 克隆 → 读取 snippets/ 目录 → 输出）
|
||
./gitlink-cli.exe snippet +list --format table
|
||
|
||
# 查看代码片段（Git 克隆 → 读取指定文件内容 → 输出）
|
||
./gitlink-cli.exe snippet +view --name "hello.py"
|
||
|
||
# 删除代码片段（Git 获取 SHA → DELETE 文件 API）
|
||
./gitlink-cli.exe snippet +delete --name "hello.py"
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Webhook 投递监控（`webhook`）
|
||
|
||
> 以下功能已合并到 `webhook` 命令组中，`hook-runner` 已删除。
|
||
|
||
### 实现思路
|
||
|
||
Webhook 每次触发事件（push、Issue 操作、PR 操作等）时，GitLink 会向配置的 URL 发送 HTTP 请求，这个过程称为"投递"。通过 Webhook 历史推送列表 API 获取投递记录。
|
||
|
||
| 命令 | API 路径 | 说明 |
|
||
|------|---------|------|
|
||
| `webhook +tasks` | `GET /v1/{owner}/{repo}/webhooks/{id}/hooktasks` | 查看投递历史（原有命令，保持不变） |
|
||
| `webhook +failed` | 从投递列表中过滤失败项 | 仅查看投递失败的记录 |
|
||
| `webhook +task-view` | 从投递列表中按 ID 筛选 | 查看某次投递的请求体、响应状态等 |
|
||
|
||
### 演示指令
|
||
|
||
```powershell
|
||
# 查看投递历史（原有命令不变）
|
||
./gitlink-cli.exe webhook +tasks --id 51102
|
||
|
||
# 查看投递失败的记录
|
||
./gitlink-cli.exe webhook +failed --id 51102
|
||
|
||
# 查看某次投递的详细内容
|
||
./gitlink-cli.exe webhook +task-view --id 51102 --task-id 4775684
|
||
```
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
```powershell
|
||
# 运行全部 Shortcut 测试
|
||
cd E:/gitlink-cli/gitlink-cli
|
||
go test ./shortcuts/... -count=1
|
||
```
|