9.9 KiB

Raw Permalink Blame History

GitLink-CLI 项目状态总结

最后更新：2026-06-03 仓库：D:\自用\self\word\大三下\软件演化\gitlink-cli 远程：https://gitlink.org.cn/chroe/gitlink-cli.git

一、课程任务背景

课程：《软件演化与运维》课程实践 进阶任务：GitLink 智能化能力提升项目 当前阶段：子任务一 — 增加和完善 GitLink-CLI 能力（50%，截止 6月4日）

子任务一交付要求

向 gitlink-cli 主仓库提交 PR（可多个）
每个 PR 包含：功能代码 + 单元测试 + 命令帮助文档更新
提供变更说明文档
撰写《软件分析及建模报告》、《新需求构思报告》、《变更影响分析及测试报告》

二、技术栈与架构

语言：Go 1.26.1
CLI 框架：spf13/cobra
密钥存储：zalando/go-keyring（OS keychain + 文件 fallback）
配置：gopkg.in/yaml.v3，存放于 ~/.config/gitlink-cli/config.yaml
三层命令架构：
1. 基础命令（cmd/）：auth, api, config, version
2. Shortcut 命令（shortcuts/）：repo +list, issue +create 等 94 个命令
3. Raw API：api GET /path

Shortcut 模块开发模式

每个模块位于 shortcuts/<name>/<name>.go，结构固定：

package <name>

import "github.com/gitlink-org/gitlink-cli/shortcuts/common"

func Shortcuts() []*common.Shortcut {
    return []*common.Shortcut{
        {
            Name:        "list",
            Description: "Description here",
            Flags: []common.Flag{
                {Name: "page", Short: "p", Usage: "Page number", Default: "1"},
            },
            Run: func(ctx *common.RuntimeContext) error {
                if err := ctx.ResolveOwnerRepo(); err != nil { return err }
                env, err := ctx.CallAPI("GET", ctx.RepoPath()+"/something", nil)
                if err != nil { return err }
                return ctx.Output(env)
            },
        },
    }
}

注册到 shortcuts/register.go：

import "github.com/gitlink-org/gitlink-cli/shortcuts/<name>"
// 在 RegisterAll() 中添加:
// "<name>": <name>.Shortcuts(),
// descriptions["<name>"] = "Description",

单元测试模式（httptest mock）

func TestXxx(t *testing.T) {
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 校验 method/path/query，返回 mock JSON
    }))
    defer server.Close()

    ctx := &common.RuntimeContext{
        Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL},
        Owner: "owner", Repo: "repo", Format: "json", Args: args,
    }
    err := findShortcut(t, "list").Run(ctx)
    // 断言
}

三、已实现的 18 个 Shortcut 模块（94 个命令）

模块	命令数	文件	测试
repo	9（含 batch-delete/fork）	shortcuts/repo/	✅
issue	12（含 batch-close/assign/label/milestone）	shortcuts/issue/	✅
pr	9	shortcuts/pr/	✅
release	5	shortcuts/release/	✅
branch	5	shortcuts/branch/	✅
ci	4	shortcuts/ci/	✅
commit	4	shortcuts/commit/	✅
file	5	shortcuts/file/	✅
member	4	shortcuts/member/	✅
star	3	shortcuts/star/	✅
watch	3	shortcuts/watch/	✅
label	4	shortcuts/label/	✅
milestone	6	shortcuts/milestone/	✅
webhook	6	shortcuts/webhook/	✅
org	5（含 batch-invite）	shortcuts/org/	✅
search	3	shortcuts/search/	✅
user	2	shortcuts/user/	✅
wiki 🆕	5	shortcuts/wiki/	✅ 12个测试

批量操作汇总（7个）

批量命令	所属模块	输入方式	预览模式
batch-close	issue	--numbers 逗号 / --from CSV	--dry-run
batch-assign	issue	同上	--dry-run
batch-label	issue	同上	--dry-run
batch-milestone	issue	同上	--dry-run
batch-delete	repo	--repos owner/repo 列表 / --from CSV	--dry-run
batch-fork	repo	同上	--dry-run
batch-invite	org	--users 用户名列表 / --from CSV	--dry-run

四、Wiki 模块开发记录

Wiki API 关键发现

发现	说明
API 域名	`gateway.gitlink.org.cn` 而非 `www.gitlink.org.cn`
API 路径	`/wiki/open/...`（有 `/open/` 中间段）
无 `.json` 后缀	Gateway 不接受 `.json`，需要 `client.DoRaw()`
Sidebar 名称	`_Sidebar`（大写 S），非小写 `_sidebar`
projectId 字段	仓库返回 `project_id` 而非 `id`
create/update 需要 `title`	API 必填字段
delete 异步重建 sidebar	需延迟 2 秒后再清理 sidebar
`data.data` 格式	`DoRaw` 返回 dict 而非 string，解析需兼容

delete 命令的 sidebar 自动清理流程

删除 wiki 页面（DELETE）
等待 2 秒（让 GitLink 完成异步 sidebar 重建）
获取 _Sidebar 内容
移除已删页面的 [[PageName]] 链接
更新 _Sidebar

五、开发踩坑记录

修改 CLI 代码后必须同时重建 showcase

showcase 通过 findCLIBinary() 在运行时查找 gitlink-cli.exe。每次修改 CLI 代码后需要：

cd gitlink-cli
go build -o gitlink-cli.exe .          # 重建 CLI
cd showcase && go build -o showcase.exe .  # 重建 showcase（更新嵌入的 HTML）
# 然后重启 showcase.exe

如果只重建 showcase 不重建 CLI，showcase 用的还是旧版二进制。

Showcase 参数传递坑

showcase 后端曾用 strings.Split(args, " ") 按空格切割参数，导致 "Hello Wiki!" 被截断为 "Hello"。修复：前端给含空格的值加引号，后端用支持引号解析的 parseShellArgs() 替代简单 Split。

Showcase 布尔参数坑（已修复）

Cobra 的 BoolP 标志：--dry-run false（空格分隔）会被解析为 --dry-run=true + 多余参数 "false"。所以批量操作 --dry-run false 实际上是在预览模式下运行，不会真正执行。修复：布尔参数改用 <select> 下拉框，JS 只在选"是"时才传 --flag，选"否"时不传。

Showcase 重复参数坑（已修复）

服务器后端自动添加 --owner chroe --repo gitlink-cli。如果前端卡片也传 --owner/--repo，会导致参数重复。修复：watch +watchers 和 star +stars 移除了多余的 owner/repo 输入框。

Showcase null 显示（已修复）

CLI 命令返回空数据时，前端显示 "null"。修复：JS 层对 null/空对象/空字符串统一显示"操作完成，无返回数据"。

六、CI/CD 流水线

部署架构

代码 push → GitLink 触发流水线 → SSH 到服务器 → git fetch + reset → docker build → 重启容器

流水线文件

.devops/构建部署Showcase.yml — GitLink DevOps 流水线（push 自动触发）

流水线关键配置

使用 git fetch + git reset --hard origin/master 避免 git pull 的本地修改冲突
使用 docker build --no-cache 确保每次用最新代码构建
容器启动时注入 -e GITLINK_TOKEN=cookie:autologin_trustie=... 解决认证问题
GitLink 密钥管理：deploy_server.server_password = 服务器密码

服务器信息

IP: 118.31.4.168
用户: root
部署路径: /opt/gitlink-cli
容器名: gitlink-cli-showcase
端口: 9090
访问地址: http://118.31.4.168:9090
Showcase 展示模块数: 12 个模块卡片（milestone/webhook/label/commit/wiki/file/member/watch/star/issue批量/repo批量/org批量）

Docker 构建注意

Dockerfile 已配置 ENV GOPROXY=https://goproxy.cn,direct，解决国内网络 Go 模块下载问题。服务器 Docker daemon 已配置国内镜像加速器（/etc/docker/daemon.json）。

七、已完成工作

✅ 子任务一完成项

基础命令框架（auth/api/config/version）
18 个 Shortcut 模块（94 个命令），其中 wiki 为新增
7 个批量操作命令（batch-close/assign/label/milestone/delete/fork/invite）
12 个 AI Agent Skills
Showcase Dashboard 在线展示（12 个模块卡片，支持真实运行）
GitHub CI/CD（release + npm publish + FreeBSD 支持）
GitLink DevOps 流水线（push 自动部署，已配置密钥，正常运行）
单元测试（wiki 12个 + 其他模块 47+）
client.DoRaw 方法（不带 .json 后缀的原始 API 调用）
Showcase 布尔参数/重复参数/null显示修复

待写文档 📄

《软件分析及建模报告》
《新需求构思报告》
《变更影响分析及测试报告》

八、小组分工

角色	负责人	负责内容
组长 A	—	commit(4命令)、milestone(6)、webhook(6)、label(4)、Showcase
同学 B	—	file(5)、member(4)、watch(3)、star(3)
同学 C	—	批量操作增强(batch-assign/label/milestone/delete/fork/invite)、table 输出优化、测试覆盖、FreeBSD构建
全员	—	wiki(5命令)、流水线部署

九、快速开始

# 构建
cd gitlink-cli && make build

# 运行测试
go test ./shortcuts/... -v

# 登录
./gitlink-cli auth login

# 使用示例
./gitlink-cli repo +list --owner gitlink
./gitlink-cli issue +list --owner gitlink --repo gitlink-cli
./gitlink-cli wiki +list --owner chroe --repo gitlink_help_center

十、当前进度 & 下一步

已完成 ✅

全部 18 个 Shortcut 模块 + 94 个命令
7 个批量操作命令
Showcase 展示页（12 个模块，可在线运行）
GitLink DevOps 流水线（push 自动部署）
单元测试 47+ 个
Showcase 各种 bug 修复（布尔参数、null 显示、重复参数、member ID 提示）

下一步 📋

向 gitlink-cli 主仓库提交 PR
撰写《软件分析及建模报告》
撰写《新需求构思报告》
撰写《变更影响分析及测试报告》
变更说明文档

9.9 KiB Raw Permalink Blame History Unescape Escape