gitlink-cli/PROJECT_STATUS.md

# 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`，结构固定：

```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`：
```go
import "github.com/gitlink-org/gitlink-cli/shortcuts/<name>"
// 在 RegisterAll() 中添加:
// "<name>": <name>.Shortcuts(),
// descriptions["<name>"] = "Description",
```

### 单元测试模式（httptest mock）

```go
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 自动清理流程
1. 删除 wiki 页面（DELETE）
2. 等待 2 秒（让 GitLink 完成异步 sidebar 重建）
3. 获取 `_Sidebar` 内容
4. 移除已删页面的 `[[PageName]]` 链接
5. 更新 `_Sidebar`

---

## 五、开发踩坑记录

### 修改 CLI 代码后必须同时重建 showcase
showcase 通过 `findCLIBinary()` 在运行时查找 `gitlink-cli.exe`。每次修改 CLI 代码后需要：
```bash
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`）。

---

## 七、已完成工作

### ✅ 子任务一完成项
- [x] 基础命令框架（auth/api/config/version）
- [x] 17 个 Shortcut 模块（82+ 命令），其中 wiki 为新增
- [x] 12 个 AI Agent Skills
- [x] Showcase Dashboard 在线展示
- [x] GitHub CI/CD（release + npm publish）
- [x] GitLink DevOps 流水线（push 自动部署）
- [x] 单元测试（wiki 12个 + 其他模块）
- [x] client.DoRaw 方法（不带 .json 后缀的原始 API 调用）
- [x] 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命令)、流水线部署 |

---

## 九、快速开始

```bash
# 构建
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
```