7.4 KiB

Raw 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 等 82+ 命令
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)
    // 断言
}

三、已实现的 17 个 Shortcut 模块（82+ 命令）

模块	命令数	文件	测试
repo	6	shortcuts/repo/	✅
issue	12	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	4	shortcuts/org/	✅
search	3	shortcuts/search/	✅
user	2	shortcuts/user/	✅
wiki 🆕	5	shortcuts/wiki/	✅ 12个测试

四、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。

六、CI/CD 流水线

部署架构

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

流水线文件

.devops/构建部署Showcase.yml — GitLink DevOps 流水线（push 自动触发）
showcase/Dockerfile — 多阶段 Docker 构建（Go 编译 + Alpine 运行）
showcase/pipeline.yml — 同上（副本）

服务器信息

IP: 118.31.4.168
用户: root
部署路径: /opt/gitlink-cli
容器名: gitlink-cli-showcase
端口: 9090
访问地址: http://118.31.4.168:9090

GitLink 密钥配置

在 GitLink 项目 DevOps 设置中配置：

deploy_server.server_password = 服务器密码

Docker 构建注意

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

七、已完成工作

✅ 子任务一完成项

基础命令框架（auth/api/config/version）
17 个 Shortcut 模块（82+ 命令），其中 wiki 为新增
12 个 AI Agent Skills
Showcase Dashboard 在线展示
GitHub CI/CD（release + npm publish）
GitLink DevOps 流水线（push 自动部署）
单元测试（wiki 12个 + 其他模块）
client.DoRaw 方法（不带 .json 后缀的原始 API 调用）
batch 批量操作（batch-close/assign/label/milestone）

待写文档 📄

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

八、小组分工

角色	负责人	负责内容
组长 A	—	commit(4命令)、milestone(6)、webhook(6)、label(4)、Showcase
同学 B	—	file(5)、member(4)、watch(3)、star(3)
同学 C	—	批量操作增强(batch-assign/label/milestone)、table 输出优化、测试覆盖
全员	—	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

7.4 KiB Raw Blame History Unescape Escape