instance-repo 1.0.8__tar.gz → 1.0.9.dev0__tar.gz

{instance_repo-1.0.8 → instance_repo-1.0.9.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.0.8
+Version: 1.0.9.dev0
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{instance_repo-1.0.8 → instance_repo-1.0.9.dev0}/instance_repo/__init__.py

@@ -18,7 +18,7 @@ from .errors import (
     TransportError,
 )
 
-__version__ = "1.0.8"
+__version__ = "1.0.9.dev0"
 
 __all__ = [
     "Repo", "load_instances",

{instance_repo-1.0.8 → instance_repo-1.0.9.dev0}/instance_repo/cli.py

@@ -60,8 +60,8 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--no-image", action="store_true")
     p.add_argument("--overwrite", action="store_true")
     p.add_argument("--no-register", action="store_true",
-                   help="跳过 DB 写入（register/commit），只传 OSS，之后由 ingest 扫描入库；"
-                        "apiserver 未实现实例写端点时必须用它")
+                   help="只传 OSS 不写库（默认上传后自动 ingest 写库；"
+                        "置上则跳过 ingest，之后自行 ingest 扫描入库）")
     p.add_argument("--no-verify", action="store_true",
                    help="跳过上传后的回读校验（默认校验 OSS 对象/ACR 镜像确已落库）")
 
@@ -76,7 +76,7 @@ def build_parser() -> argparse.ArgumentParser:
     pm.add_argument("--no-image", action="store_true")
     pm.add_argument("--overwrite", action="store_true")
     pm.add_argument("--register", action="store_true",
-                    help="走 register/commit 三段式写 DB（缺省不写，留给 ingest 扫描入库）")
+                    help="整批上传完成后一次 ingest 写库（缺省只传 OSS，不写库）")
     pm.add_argument("--no-verify", action="store_true")
     pm.add_argument("--concurrency", type=int, default=8)
     pm.add_argument("--continue-on-error", action="store_true",
@@ -109,6 +109,20 @@ def build_parser() -> argparse.ArgumentParser:
     lst.add_argument("--version", default=None)
     lst.add_argument("--split", default=None,
                      help="按 split 过滤；缺省为跨 split 检索")
+    # 1.0.10：分页/模糊搜索/过滤模式。任一给定 → 走 list_paged 单页语义；
+    # 都没给时仍走 list 自动翻页取全量（向后兼容）。
+    lst.add_argument("--q", default=None,
+                     help="instance_id 子串模糊搜索（不区分大小写；给定即单页模式）")
+    lst.add_argument("--instance-id", default=None, dest="instance_id",
+                     help="instance_id 精确等值（给定即单页模式）")
+    lst.add_argument("--tags", default=None,
+                     help="k1:v1,k2:v2 等值过滤（key 含 ./$ 服务端拒绝；给定即单页模式）")
+    lst.add_argument("--difficulty", choices=["easy", "medium", "hard"], default=None,
+                     help="按难度过滤（给定即单页模式）")
+    lst.add_argument("--page", type=int, default=1,
+                     help="分页页码（默认 1；与 --q/--tags/--difficulty 配合生效）")
+    lst.add_argument("--page-size", type=int, default=50, dest="page_size",
+                     help="分页大小（默认 50；服务端上限 200）")
 
     pl = sub.add_parser("pull", help="拉取并解包（digest 校验）")
     pl.add_argument("ref", nargs="?",
@@ -272,7 +286,8 @@ def build_parser() -> argparse.ArgumentParser:
 
     ver = sub.add_parser("version", help="版本管理（create/list/status/update/set-run-type）")
     ver.add_argument("action",
-                     choices=["create", "list", "status", "update", "set-run-type"])
+                     choices=["create", "list", "status", "update",
+                              "set-run-type", "get"])
     ver.add_argument("ref", nargs="?",
                      help="create/list: {L1}/{L2}；"
                           "status/update/set-run-type: {L1}/{L2}/{version}"
@@ -285,12 +300,86 @@ def build_parser() -> argparse.ArgumentParser:
                      help="create 用：oss://{bucket}/{prefix}")
     ver.add_argument("--storage-type", choices=["oss"], default="oss")
     ver.add_argument("--splits", default=None, help="逗号分隔 split 名")
+    ver.add_argument("--split", default=None,
+                     help="status 用：查 split 级真实记录（split_first 发布状态/目标路径）")
     ver.add_argument("--status", choices=_STATUS_CHOICES, default=None,
                      help="update 用：版本状态流转")
     ver.add_argument("--run-type", choices=["train", "eval"], default=None,
                      help="version 级用途标签")
     ver.add_argument("--split-run-types", default=None,
                      help="split 级打标，格式 name=train,name2=eval（与 --run-type 互斥）")
+    ver.add_argument("--environment", default=None,
+                     help="get 用：覆盖 profile 派生的 environment（pre/online）")
+
+    # ── 1.0.10 控制面管理子命令 ─────────────────────────────────────────────────
+    sp = sub.add_parser("split", help="split 记录管理（list/get/set-run-type）")
+    sp.add_argument("action", choices=["list", "get", "set-run-type"])
+    sp.add_argument("ref", nargs="?",
+                    help="list: {L1}/{L2}；get/set-run-type: {L1}/{L2}/{split}"
+                         "（或用 --dataset/--split）")
+    sp.add_argument("--dataset", default=None, help="{L1}/{L2}")
+    sp.add_argument("--split", default=None,
+                    help="目标 split 名（get/set-run-type 用）")
+    sp.add_argument("--version", default=None,
+                    help="list 按 version 精确过滤；get 可选定位版本")
+    sp.add_argument("--scope", choices=["unversioned", "exact", "all"], default=None,
+                    help="list 跨版本策略：缺省无 version → all（SDK 取全量哲学），"
+                         "有 version 省略（服务端只接受 exact）")
+    sp.add_argument("--status", choices=_STATUS_CHOICES, default=None,
+                    help="list 按状态过滤")
+    sp.add_argument("--run-type", choices=["train", "eval", ""], default=None,
+                    dest="run_type",
+                    help="set-run-type 用：train/eval 或空串清除")
+    sp.add_argument("--page", type=int, default=1)
+    sp.add_argument("--page-size", type=int, default=50, dest="page_size")
+
+    ds = sub.add_parser("dataset",
+                        help="数据集/基准/工作流管理（list/get/update/access/"
+                             "revoke/benchmarks/workflows）")
+    ds.add_argument("action",
+                    choices=["list", "get", "update", "access", "revoke",
+                             "benchmarks", "workflows"])
+    ds.add_argument("ref", nargs="?", metavar="dataset",
+                    help="list/get/update/access/revoke: {L1}/{L2}；"
+                         "benchmarks: source_id（get）；workflows: wf-id（get）")
+    ds.add_argument("--dataset", default=None, help="{L1}/{L2}")
+    ds.add_argument("--q", default=None,
+                    help="list/benchmarks 模糊搜索；list 对 name+display_name，"
+                         "benchmarks 对 name")
+    ds.add_argument("--status", default=None,
+                    help="list/benchmarks 过滤；workflows 过滤"
+                         "（pending/running/awaiting_approval/succeeded/failed/canceled）")
+    ds.add_argument("--visibility", default=None,
+                    help="list 逗号分隔过滤（public/private）")
+    ds.add_argument("--owned-by-me", action="store_true", dest="owned_by_me",
+                    help="list 按 owner=caller 过滤")
+    ds.add_argument("--sort-by", choices=["updated_at", "dataset_name"],
+                    default=None, dest="sort_by")
+    ds.add_argument("--order", choices=["asc", "desc"], default=None)
+    ds.add_argument("--include-deprecated", action="store_true",
+                    dest="include_deprecated")
+    ds.add_argument("--environment", default=None,
+                    help="get/update 覆盖 profile 派生的 environment")
+    ds.add_argument("--metadata-model", choices=["split_first", "version_first"],
+                    default=None, dest="metadata_model")
+    # update 用（至少一项）
+    ds.add_argument("--display-name", default=None, dest="display_name")
+    ds.add_argument("--description", default=None)
+    ds.add_argument("--benchmark-id", default=None, dest="benchmark_id")
+    ds.add_argument("--owner-team-id", default=None, dest="owner_team_id")
+    ds.add_argument("--default-scaffold", default=None, dest="default_scaffold")
+    # access/revoke 用
+    ds.add_argument("--principal", default=None, help="工号或 user_group id")
+    ds.add_argument("--role", choices=["reader", "writer", "admin"], default=None)
+    ds.add_argument("--principal-type", choices=["user", "user_group"],
+                    default="user", dest="principal_type")
+    # benchmarks/workflows 用
+    ds.add_argument("--is-core", action="store_true", dest="is_core")
+    ds.add_argument("--source", default=None, help="benchmarks source 精确过滤")
+    ds.add_argument("--kind", default=None, help="workflows kind 过滤")
+    ds.add_argument("--creator", default=None, help="workflows creator 过滤")
+    ds.add_argument("--page", type=int, default=1)
+    ds.add_argument("--page-size", type=int, default=20, dest="page_size")
     return ap
 
 
@@ -301,6 +390,36 @@ def _split_ref(ref: str, parts: int) -> list[str]:
     return segs
 
 
+def _page_count(res) -> int:
+    """分页结果的总页数（total<0 表示服务端无分页信封 → 1）。"""
+    if getattr(res, "total", -1) < 0 or not getattr(res, "page_size", 0):
+        return 1
+    return max(1, (res.total + res.page_size - 1) // res.page_size)
+
+
+def _split_instance_count(split) -> int:
+    """取 split 的实例计数：优先 manifest.instance_count，回落 0。"""
+    m = getattr(split, "manifest", None)
+    if m is not None:
+        c = getattr(m, "instance_count", None)
+        if isinstance(c, int):
+            return c
+    return 0
+
+
+def _resolve_split_ref(args) -> tuple[str, str]:
+    """定位 dataset + split：位置 ref（{L1}/{L2}/{split}）或 --dataset/--split。"""
+    if args.dataset:
+        if not args.split:
+            raise SystemExit("给定 --dataset 时 split 需要 --split")
+        return args.dataset, args.split
+    if args.ref:
+        segs = _split_ref(args.ref, 3)
+        return f"{segs[0]}/{segs[1]}", segs[2]
+    raise SystemExit("split get/set-run-type 需要 {L1}/{L2}/{split} 或 "
+                     "--dataset/--split")
+
+
 def _split_dataset(dataset: str) -> list[str]:
     """校验 dataset 为 ``{L1}/{L2}`` 两段式。
 
@@ -454,6 +573,11 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
                                verify=not args.no_verify)
         print(f"{res.instance_id} uploaded={res.uploaded} "
               f"image_pushed={res.image_pushed}", file=out)
+        if res.ingest:
+            stats = res.ingest.get("stats", {}) or {}
+            print(f"ingest {res.ingest.get('ingest_id')} "
+                  f"status={res.ingest.get('status')} "
+                  f"instances={stats.get('instance_count')}", file=out)
         return 0
 
     if args.cmd == "push-many":
@@ -505,6 +629,29 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
 
     if args.cmd == "list":
         dataset, version, _ = _resolve_target(args, 3)
+        # 1.0.10：任一过滤/分页 flag 给定 → 走 list_paged 单页；否则仍走
+        # list 自动翻页取全量（向后兼容）。
+        paged = any([args.q, args.instance_id, args.tags, args.difficulty,
+                     args.page != 1, args.page_size != 50])
+        if paged:
+            tags_dict = None
+            if args.tags:
+                tags_dict = {}
+                for pair in args.tags.split(","):
+                    if ":" not in pair:
+                        raise SystemExit(f"--tags expects k1:v1,k2:v2, got {args.tags!r}")
+                    k, v = pair.split(":", 1)
+                    tags_dict[k] = v
+            res = r.instances.list_paged(dataset, args.version, split=args.split,
+                                         q=args.q, instance_id=args.instance_id,
+                                         tags=tags_dict, difficulty=args.difficulty,
+                                         page=args.page, page_size=args.page_size)
+            for inst in res.items:
+                print(f"{inst.instance_id}\t{inst.difficulty}\t{inst.docker_image}",
+                      file=out)
+            print(f"page={res.page}/{(res.total+res.page_size-1)//res.page_size if res.total>0 else 1} "
+                  f"total={res.total} has_more={res.has_more}", file=out)
+            return 0
         for inst in r.instances.list(dataset, version, args.split):
             print(f"{inst.instance_id}\t{inst.difficulty}\t{inst.docker_image}", file=out)
         return 0
@@ -711,7 +858,34 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
             return 0
         dataset, version, _ = _resolve_target(args, 3)
         if args.action == "status":
-            print(r.versions.status(dataset, version), file=out)
+            if args.split:
+                sp = r.versions.split_detail(dataset, version, args.split)
+                print(f"{sp.get('name', args.split)}\t{sp.get('status', '')}\t"
+                      f"{sp.get('storage_path', '')}\t"
+                      f"published_at={sp.get('published_at') or ''}", file=out)
+            else:
+                print(r.versions.status(dataset, version), file=out)
+            return 0
+        if args.action == "get":
+            # 1.0.10：取版本完整详情（splits 明细 + manifest + 时间戳）。
+            # split_first 分支时服务端聚合 legacy 投影。
+            dv = r.versions.get(dataset, version, environment=args.environment)
+            print(f"version\t{dv.get('version','')}\tstatus={dv.get('status','')}"
+                  f"\tstorage_path={dv.get('storage_path','')}", file=out)
+            print(f"published_at={dv.get('published_at') or ''}"
+                  f"\tlast_ingested_at={dv.get('last_ingested_at') or ''}",
+                  file=out)
+            print(f"dataset_version_id={dv.get('dataset_version_id','')}",
+                  file=out)
+            splits = dv.get("splits") or []
+            for s in splits:
+                print(f"  split\t{s.get('name','')}\tstatus={s.get('status','')}"
+                      f"\toss_prefix={s.get('oss_prefix','')}"
+                      f"\tinstance_count={s.get('instance_count') or 0}", file=out)
+            manifest = dv.get("manifest") or {}
+            print(f"manifest\tinstance_count={manifest.get('instance_count') or 0}"
+                  f"\tfile_count={manifest.get('file_count') or 0}"
+                  f"\tsize_bytes={manifest.get('size_bytes') or 0}", file=out)
             return 0
         if args.action == "set-run-type":
             r.versions.set_run_type(dataset, version,
@@ -727,6 +901,152 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
         print(f"updated {dataset}/{version}", file=out)
         return 0
 
+    # ── 1.0.10 控制面管理子命令 dispatch ────────────────────────────────────────
+    if args.cmd == "split":
+        if args.action == "list":
+            dataset = (args.dataset or args.ref or "").strip()
+            if not dataset:
+                raise SystemExit("split list 需要 --dataset 或位置 ref（{L1}/{L2}）")
+            res = r.splits.list(dataset,
+                                version=args.version, version_scope=args.scope,
+                                status=args.status,
+                                page=args.page, page_size=args.page_size)
+            for s in res.items:
+                print(f"{s.name}\tversion={s.version or ''}\tstatus={s.status}"
+                      f"\trun_type={s.run_type or ''}\t"
+                      f"instance_count={_split_instance_count(s)}", file=out)
+            print(f"page={res.page}/{_page_count(res)} total={res.total}", file=out)
+            return 0
+        # get / set-run-type：需要定位到具体 split
+        dataset, split_name = _resolve_split_ref(args)
+        if args.action == "get":
+            sp = r.splits.get(dataset, split_name, version=args.version)
+            if sp is None:
+                raise SystemExit(f"split {dataset}/{split_name} not found")
+            print(f"split\t{sp.name}\tversion={sp.version or ''}"
+                  f"\tstatus={sp.status}\trun_type={sp.run_type or ''}", file=out)
+            print(f"storage_path={sp.storage_path}", file=out)
+            print(f"published_at={sp.published_at or ''}"
+                  f"\tlast_ingested_at={sp.last_ingested_at or ''}", file=out)
+            print(f"instance_count={_split_instance_count(sp)}", file=out)
+            return 0
+        # set-run-type
+        if args.run_type is None:
+            raise SystemExit("split set-run-type 需要 --run-type（train/eval/''）")
+        r.splits.update(dataset, split_name,
+                        version=args.version, run_type=args.run_type)
+        print(f"split {dataset}/{split_name} run_type={args.run_type or '(cleared)'}",
+              file=out)
+        return 0
+
+    if args.cmd == "dataset":
+        if args.action == "list":
+            res = r.datasets.list_paged(
+                q=args.q, visibility=args.visibility,
+                owned_by_me=args.owned_by_me or None,
+                sort_by=args.sort_by, order=args.order,
+                include_deprecated=args.include_deprecated or None,
+                environment=args.environment,
+                metadata_model=args.metadata_model,
+                page=args.page, page_size=args.page_size)
+            for ds in res.items:
+                print(f"{ds.dataset_name}\tvisibility={ds.visibility}"
+                      f"\tversion_count={ds.version_count}"
+                      f"\tsplit_count={ds.split_count}"
+                      f"\tlatest={ds.latest_version or ''}", file=out)
+            print(f"page={res.page}/{_page_count(res)} total={res.total}", file=out)
+            return 0
+        # 其余动作需要 dataset 名（位置 ref 或 --dataset）
+        dataset = (args.dataset or args.ref or "").strip()
+        if args.action in ("get", "update", "access", "revoke") and not dataset:
+            raise SystemExit(f"dataset {args.action} 需要 --dataset 或位置 ref")
+        if args.action == "get":
+            d = r.datasets.get_detail(dataset, environment=args.environment,
+                                      metadata_model=args.metadata_model)
+            print(f"dataset\t{d.dataset_name}\tid={d.dataset_id}"
+                  f"\tvisibility={d.visibility}", file=out)
+            print(f"version_count={d.version_count}\tsplit_count={d.split_count}"
+                  f"\tlatest={d.latest_version or ''}", file=out)
+            print(f"instance_count={d.stats.instance_count}"
+                  f"\tfile_count={d.stats.file_count}"
+                  f"\tsize_bytes={d.stats.size_bytes}", file=out)
+            return 0
+        if args.action == "update":
+            kwargs = {}
+            if args.display_name is not None:
+                kwargs["display_name"] = args.display_name
+            if args.description is not None:
+                kwargs["description"] = args.description
+            if args.visibility is not None:
+                kwargs["visibility"] = args.visibility
+            if args.benchmark_id is not None:
+                kwargs["benchmark_id"] = args.benchmark_id
+            if args.owner_team_id is not None:
+                kwargs["owner_team_id"] = args.owner_team_id
+            if args.default_scaffold is not None:
+                kwargs["default_scaffold"] = args.default_scaffold
+            if not kwargs:
+                raise SystemExit(
+                    "dataset update 至少给一个：--display-name / --description / "
+                    "--visibility / --benchmark-id / --owner-team-id / "
+                    "--default-scaffold")
+            r.datasets.update(dataset, **kwargs)
+            print(f"updated {dataset}", file=out)
+            return 0
+        if args.action in ("access", "revoke"):
+            if args.action == "access":
+                res = r.datasets.list_access(dataset,
+                                             page=args.page, page_size=args.page_size)
+                for rb in res.items:
+                    print(f"{rb.principal_type}\t{rb.principal_id}\t{rb.role_id}"
+                          f"\tadded_by={rb.added_by}\tadded_at={rb.added_at}",
+                          file=out)
+                print(f"page={res.page}/{_page_count(res)} total={res.total}",
+                      file=out)
+                return 0
+            if not (args.principal and args.role):
+                raise SystemExit("dataset revoke 需要 --principal + --role")
+            r.datasets.revoke(dataset, args.principal, args.role,
+                              principal_type=args.principal_type)
+            print(f"revoked {args.principal} ({args.principal_type}) "
+                  f"{args.role} from {dataset}", file=out)
+            return 0
+        if args.action == "benchmarks":
+            if args.ref and not args.q:
+                b = r.benchmarks.get(args.ref)
+                if b is None:
+                    raise SystemExit(f"benchmark {args.ref} not found")
+                print(f"benchmark\t{b.source_id}\tname={b.name}"
+                      f"\tteacher_directions={','.join(b.teacher_directions)}"
+                      f"\tis_core={b.is_core}", file=out)
+                return 0
+            res = r.benchmarks.list(
+                q=args.q, source=args.source, is_core=args.is_core or None,
+                page=args.page, page_size=args.page_size)
+            for b in res.items:
+                print(f"{b.source_id}\tname={b.name}\tis_core={b.is_core}"
+                      f"\tdirections={','.join(b.teacher_directions)}", file=out)
+            print(f"page={res.page}/{_page_count(res)} total={res.total}", file=out)
+            return 0
+        # workflows
+        if args.ref:
+            wf = r.workflows.get(args.ref)
+            print(f"workflow\t{wf.id}\tkind={wf.kind}\tstatus={wf.status}"
+                  f"\tcurrent_step={wf.current_step}", file=out)
+            if wf.approval:
+                print(f"approval\tprovider={wf.approval.provider}"
+                      f"\tticket={wf.approval.ticket_link}"
+                      f"\tstatus={wf.approval.status}", file=out)
+            return 0
+        res = r.workflows.list(
+            kind=args.kind, status=args.status, creator=args.creator,
+            page=args.page, page_size=args.page_size)
+        for wf in res.items:
+            print(f"{wf.id}\tkind={wf.kind}\tstatus={wf.status}"
+                  f"\tcurrent_step={wf.current_step}", file=out)
+        print(f"page={res.page}/{_page_count(res)} total={res.total}", file=out)
+        return 0
+
     return 2  # pragma: no cover - argparse 已保证 cmd 合法
 
 

instance_repo-1.0.9.dev0/instance_repo/clients/__init__.py

@@ -0,0 +1,12 @@
+"""clients — 各资源客户端 + config。"""
+from .config import Profile, load_profile
+from .datasets import DatasetsClient
+from .versions import VersionsClient
+from .instances import InstancesClient
+from .splits import SplitsClient
+from .benchmarks import BenchmarksClient
+from .workflows import WorkflowsClient
+
+__all__ = ["Profile", "load_profile", "DatasetsClient", "VersionsClient",
+           "InstancesClient", "SplitsClient", "BenchmarksClient",
+           "WorkflowsClient"]

instance_repo-1.0.9.dev0/instance_repo/clients/benchmarks.py

@@ -0,0 +1,57 @@
+"""clients/benchmarks.py — benchmark 目录查询（→ apiserver /apis/v1/benchmarks）。
+
+服务端契约（meta_handler / meta_service 实测）：
+* ``GET /benchmarks``：分页信封（默认 page=1/page_size=20，上限 200）；
+  ``q`` 对 name 模糊匹配（不区分大小写子串）；``is_core`` 布尔（非法值服务端
+  静默忽略，SDK 不做额外校验）；``source`` 精确。按 updated_at 倒序。
+* ``GET /benchmarks/{source_id}``：点查；不存在 404。认证可选（combinedAuthOptional）。
+
+主键是 ``source_id``（无独立 id 字段）。claim 弹窗的 Benchmark 候选即
+``list(q=...)``；控制台"Benchmark maintainer is not allowed"的禁用态是**前端
+逻辑**（apiserver 无 enabled/allowed 字段），SDK 不模拟——调用方按自身权限过滤。
+"""
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from ..errors import TransportError
+from ..models import Benchmark, PagedResult
+
+
+class BenchmarksClient:
+    _BASE = "/apis/v1/benchmarks"
+
+    def __init__(self, transport) -> None:
+        self._t = transport
+
+    def list(self, *, q: str | None = None, is_core: bool | None = None,
+             source: str | None = None, page: int = 1,
+             page_size: int = 20) -> PagedResult:
+        """benchmark 分页列表（单页）。``q`` 模糊搜索 name（不区分大小写子串）。"""
+        params: list[tuple[str, str]] = []
+        if (q or "").strip():
+            params.append(("q", q.strip()))
+        if is_core is not None:
+            params.append(("is_core", "true" if is_core else "false"))
+        if (source or "").strip():
+            params.append(("source", source.strip()))
+        params.append(("page", str(int(page))))
+        params.append(("page_size", str(int(page_size))))
+        query = "&".join(f"{k}={quote(v, safe='')}" for k, v in params)
+        data, pagination = self._t.request_with_meta("GET", f"{self._BASE}?{query}")
+        rows = data if isinstance(data, list) else (
+            data.get("benchmarks", []) if isinstance(data, dict) else [])
+        items = [Benchmark.from_dict(r) for r in rows if isinstance(r, dict)]
+        return PagedResult.from_response(items, pagination, int(page), int(page_size))
+
+    def get(self, source_id: str) -> Benchmark | None:
+        """按 source_id 点查；不存在返回 None（"没有"不是错误）。"""
+        if not (source_id or "").strip():
+            raise ValueError("source_id is required")
+        try:
+            data = self._t.get(f"{self._BASE}/{quote(source_id.strip(), safe='')}")
+        except TransportError as e:
+            if e.status == 404:
+                return None
+            raise
+        return Benchmark.from_dict(data) if isinstance(data, dict) else None