From 21ebb2f89c08855134f9ba15d2ed1065b3652e6d Mon Sep 17 00:00:00 2001 From: NeeNe <26158277@qq.com> Date: Mon, 8 Jun 2026 12:13:28 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E6=89=93=E7=A3=A8=E4=BB=93=E5=BA=93?= =?UTF-8?q?=E6=96=87=E4=BB=B6=E6=A0=91=E5=91=BD=E4=BB=A4=E4=BA=A4=E4=BB=98?= =?UTF-8?q?=E8=B4=A8=E9=87=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/changes/repo-tree-shortcut.md | 71 +++++++++++++++++-------------- shortcuts/repo/repo.go | 4 +- shortcuts/repo/repo_test.go | 32 +++++++++++++- 3 files changed, 72 insertions(+), 35 deletions(-) diff --git a/doc/changes/repo-tree-shortcut.md b/doc/changes/repo-tree-shortcut.md index 85c3ee7..ea1f66d 100644 --- a/doc/changes/repo-tree-shortcut.md +++ b/doc/changes/repo-tree-shortcut.md @@ -1,60 +1,65 @@ -# Repo Tree Shortcut +# repo +tree 仓库文件树查询命令 -## Summary +## 背景 -Adds `gitlink-cli repo +tree` so users and AI Agents can list repository files and directories without manually calling the Raw API. +`gitlink-cli repo` 已经提供仓库详情、README、语言统计和贡献者查询能力，但缺少直接查看仓库目录结构的 Shortcut。用户或 AI Agent 如果要判断仓库中是否存在 README、LICENSE、依赖清单、测试目录、文档目录等文件，过去需要手动调用 Raw API `/sub_entries`。 -## Command +本次变更把仓库文件树查询封装为 `repo +tree`，降低普通用户和自动化工作流的使用门槛。 -| Command | Purpose | -|---------|---------| -| `gitlink-cli repo +tree` | List repository files and directories at the repository root or a specified path | +## 变更内容 -## Usage +- 新增 `gitlink-cli repo +tree` Shortcut。 +- 调用 `GET /{owner}/{repo}/sub_entries` 获取仓库根目录或指定目录下的文件和子目录。 +- 支持 `--path, -p` 指定目录路径；不传时查询仓库根目录。 +- 支持 `--ref, -r` 指定分支、标签或提交引用；默认值为 `master`。 +- 复用现有仓库上下文解析、API 调用和统一输出格式。 +- 补充中英文 i18n 文案，避免新增命令帮助信息硬编码。 + +## 命令示例 ```bash -# List repository root entries +# 查看仓库根目录 gitlink-cli repo +tree --owner Gitlink --repo forgeplus --ref master -# List entries under a directory +# 查看指定目录 gitlink-cli repo +tree --owner Gitlink --repo forgeplus --path src --ref main -# AI Agent usage with structured output +# Agent 场景建议使用 JSON 输出 gitlink-cli repo +tree --owner Gitlink --repo forgeplus --format json ``` -## Behavior +## 参数说明 -- Calls `GET /{owner}/{repo}/sub_entries`. -- Maps `--path, -p` to the `filepath` query parameter. -- Maps `--ref, -r` to the `ref` query parameter. -- Defaults `--ref` to `master` when omitted. -- Reuses existing repository context resolution and output formatting. +| 参数 | 必填 | 说明 | +|------|------|------| +| `--path, -p` | 否 | 要查看的目录路径，不传时查询仓库根目录 | +| `--ref, -r` | 否 | 分支、标签或提交引用，默认 `master` | +| `--owner` | 否 | 全局参数，仓库所有者，可从 git remote 自动解析 | +| `--repo` | 否 | 全局参数，仓库名称，可从 git remote 自动解析 | +| `--format` | 否 | 全局参数，输出格式：`json`、`table` 或 `yaml` | -## Tests +## 测试覆盖 -Unit tests cover: +单元测试覆盖以下内容： -- root directory listing with the default `master` ref; -- directory listing with explicit `--path` and `--ref`; -- endpoint path and query parameter mapping. +- 根目录查询默认使用 `master`。 +- 根目录查询不发送空 `filepath` 参数。 +- 指定 `--path` 和 `--ref` 时正确映射到 `filepath` 与 `ref` 查询参数。 +- `repo +tree` 的命令说明和 `--path/-p`、`--ref/-r` 参数注册完整。 -Validation command: +验证命令： ```bash make test ``` -## 中文说明 +## 交付要求核对 -### 变更内容 +- 功能代码：`shortcuts/repo/repo.go` +- 单元测试：`shortcuts/repo/repo_test.go` +- 命令帮助文档：`README.md`、`README.zh-CN.md`、`skills/gitlink-repo/SKILL.md`、`skills/gitlink-repo/references/gitlink-repo-tree.md` +- 变更说明文档：`doc/changes/repo-tree-shortcut.md` -- 新增 `repo +tree` 仓库文件树查询命令。 -- 支持查看仓库根目录或指定目录下的文件和子目录。 -- 支持通过 `--ref` 指定分支、标签或提交引用。 -- 更新 README、README.zh-CN、设计文档和 `gitlink-repo` Skill 文档。 -- 新增 `gitlink-repo` Skill 参考文档，便于 Agent 在项目结构检查、复现性检查和合规检查中复用。 +## 兼容性 -### 验证 - -- `make test` +该变更只新增 Shortcut、单元测试和文档，不修改已有命令参数或输出结构。根目录查询时不再发送空 `filepath` 查询参数，语义更清晰，对现有功能无破坏性影响。 diff --git a/shortcuts/repo/repo.go b/shortcuts/repo/repo.go index 90924b5..06774a6 100644 --- a/shortcuts/repo/repo.go +++ b/shortcuts/repo/repo.go @@ -97,7 +97,9 @@ func Shortcuts(translators ...*i18n.Translator) []*common.Shortcut { if ref == "" { ref = "master" } - q.Set("filepath", ctx.Arg("path")) + if path := ctx.Arg("path"); path != "" { + q.Set("filepath", path) + } q.Set("ref", ref) env, err := ctx.CallAPIWithQuery("GET", ctx.RepoPath()+"/sub_entries", q) if err != nil { diff --git a/shortcuts/repo/repo_test.go b/shortcuts/repo/repo_test.go index 38f8ab0..5c5f34b 100644 --- a/shortcuts/repo/repo_test.go +++ b/shortcuts/repo/repo_test.go @@ -155,7 +155,9 @@ func TestRepoReadmeUsesRepositoryReadmeEndpoint(t *testing.T) { func TestRepoTreeListsRootOnDefaultRef(t *testing.T) { server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { assertRequest(t, r, "GET", "/owner/repo/sub_entries.json") - assertEqual(t, r.URL.Query().Get("filepath"), "") + if _, ok := r.URL.Query()["filepath"]; ok { + t.Fatalf("did not expect filepath query for repository root, got %q", r.URL.Query().Get("filepath")) + } assertEqual(t, r.URL.Query().Get("ref"), "master") writeJSON(t, w, map[string]interface{}{ "entries": []map[string]interface{}{ @@ -188,6 +190,34 @@ func TestRepoTreeUsesPathAndRef(t *testing.T) { } } +func TestRepoTreeShortcutRegistersHelpFlags(t *testing.T) { + tree := findShortcut(t, "tree") + if tree.Description == "" { + t.Fatal("tree shortcut description is empty") + } + + flags := map[string]common.Flag{} + for _, flag := range tree.Flags { + flags[flag.Name] = flag + } + + pathFlag, ok := flags["path"] + if !ok { + t.Fatal("tree shortcut missing path flag") + } + if pathFlag.Short != "p" || pathFlag.Usage == "" { + t.Fatalf("unexpected path flag: %+v", pathFlag) + } + + refFlag, ok := flags["ref"] + if !ok { + t.Fatal("tree shortcut missing ref flag") + } + if refFlag.Short != "r" || refFlag.Default != "master" || refFlag.Usage == "" { + t.Fatalf("unexpected ref flag: %+v", refFlag) + } +} + func TestRepoLanguagesUsesLanguagesEndpoint(t *testing.T) { server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { assertRequest(t, r, "GET", "/owner/repo/languages.json")