gitlink-cli/doc/shortcut-implementation-report.md

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 替代，自动识别所有变更

演示指令

# 列出 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 指定语言）。

演示指令

# 创建代码片段（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 筛选	查看某次投递的请求体、响应状态等

演示指令

# 查看投递历史（原有命令不变）
./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

---

测试

# 运行全部 Shortcut 测试
cd E:/gitlink-cli/gitlink-cli
go test ./shortcuts/... -count=1