ark-utils-cli 0.3.0__py3-none-any.whl

ark_cli/__init__.py

@@ -0,0 +1,3 @@
+"""火山引擎命令行工具"""
+
+__version__ = "0.3.0"

ark_cli/cli.py

@@ -0,0 +1,268 @@
+"""命令行入口"""
+
+import argparse
+import sys
+
+from ark_cli import __version__
+
+
+def handle_tos(args):
+    """处理 TOS 相关命令"""
+    from ark_cli.tos_client import TosClient
+
+    try:
+        client = TosClient()
+    except ValueError as e:
+        print(f"错误: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.action == "upload":
+        if not all([args.bucket, args.input, args.output]):
+            print("错误: upload 操作需要 -bucket, -i, -o 参数", file=sys.stderr)
+            sys.exit(1)
+
+        try:
+            url = client.upload(args.bucket, args.input, args.output)
+            print(url)
+        except FileNotFoundError as e:
+            print(f"错误: {e}", file=sys.stderr)
+            sys.exit(1)
+        except Exception as e:
+            print(f"上传失败: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.action == "ls":
+        if not args.bucket:
+            print("错误: ls 操作需要 -bucket 参数", file=sys.stderr)
+            sys.exit(1)
+
+        try:
+            prefix = args.input or ""
+            # TOS 对象 key 不以 / 开头，/ 表示根目录
+            if prefix == "/":
+                prefix = ""
+            # 移除开头的 /
+            prefix = prefix.lstrip("/")
+            items = client.list_objects(args.bucket, prefix=prefix)
+
+            if not items:
+                print("(空)")
+                return
+
+            # 格式化输出
+            for item in items:
+                if item["type"] == "dir":
+                    print(f"{'DIR':<10} {'-':<20} {item['key']}")
+                else:
+                    size_str = _format_size(item["size"])
+                    print(f"{size_str:<10} {item['last_modified']:<20} {item['key']}")
+        except Exception as e:
+            print(f"列表失败: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.action == "geturl":
+        if not all([args.bucket, args.input]):
+            print("错误: geturl 操作需要 -bucket, -i 参数", file=sys.stderr)
+            sys.exit(1)
+
+        try:
+            url = client.get_url(args.bucket, args.input)
+            print(url)
+        except Exception as e:
+            print(f"获取链接失败: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.action == "lsb":
+        try:
+            items = client.list_buckets()
+
+            if not items:
+                print("(空)")
+                return
+
+            for item in items:
+                print(f"{item['creation_date']:<20} {item['name']}")
+        except Exception as e:
+            print(f"列表失败: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.action == "rm":
+        if not all([args.bucket, args.input]):
+            print("错误: rm 操作需要 -bucket, -i 参数", file=sys.stderr)
+            sys.exit(1)
+
+        try:
+            client.delete(args.bucket, args.input)
+            print(f"已删除: {args.input}")
+        except Exception as e:
+            print(f"删除失败: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.action == "stats":
+        if not args.bucket:
+            print("错误: stats 操作需要 -bucket 参数", file=sys.stderr)
+            sys.exit(1)
+
+        try:
+            info = client.stats(args.bucket)
+            print(f"Bucket:      {info['name']}")
+            print(f"Location:    {info['location']}")
+            print(f"Created:     {info['creation_date']}")
+            print(f"Storage:     {info['storage_class']}")
+            print(f"Redundancy:  {info['az_redundancy']}")
+            print(f"Versioning:  {info['versioning']}")
+            print(f"Endpoint:    {info['extranet_endpoint']}")
+        except Exception as e:
+            print(f"获取统计失败: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    else:
+        print(f"错误: 不支持的操作: {args.action}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _format_size(size: int) -> str:
+    """格式化文件大小"""
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        if size < 1024:
+            return f"{size:.1f}{unit}" if unit != "B" else f"{size}{unit}"
+        size /= 1024
+    return f"{size:.1f}PB"
+
+
+def handle_model(args):
+    """处理大模型相关命令"""
+    from ark_cli.model_client import ModelClient
+
+    if not all([args.model, args.content]):
+        print("错误: model 产品需要 -m 和 -c 参数", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        client = ModelClient()
+        result = client.chat(args.model, args.content)
+        print(result.content)
+        print()
+        print(f"[耗时: {result.duration_ms}ms | tokens: {result.input_tokens} in / {result.output_tokens} out]")
+    except ValueError as e:
+        print(f"错误: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"调用失败: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def handle_search(args):
+    """处理联网搜索命令"""
+    from ark_cli.search_client import SearchClient
+
+    if not args.query:
+        print("错误: search 产品需要 -q 参数", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        client = SearchClient()
+        result = client.search(
+            query=args.query,
+            count=args.count or 10,
+            time_range=args.time_range,
+        )
+
+        if not result.results:
+            print("未找到相关结果")
+            return
+
+        for i, item in enumerate(result.results, 1):
+            print(f"[{i}] {item.title}")
+            print(f"    {item.site_name} | {item.publish_time[:10] if item.publish_time else '-'}")
+            print(f"    {item.url}")
+            if item.snippet:
+                # 截取摘要前 150 字符
+                snippet = item.snippet[:150] + "..." if len(item.snippet) > 150 else item.snippet
+                print(f"    {snippet}")
+            print()
+
+        print(f"[共 {result.result_count} 条结果 | 耗时: {result.duration_ms}ms]")
+
+    except ValueError as e:
+        print(f"错误: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"搜索失败: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="ark-cli",
+        description=f"火山引擎命令行工具 v{__version__} - 让人类和 AI Agent 都能在终端中操作火山引擎",
+    )
+    parser.add_argument(
+        "-v", "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-p", "--product",
+        choices=["tos", "model", "search"],
+        help="产品名称",
+    )
+    parser.add_argument(
+        "-a", "--action",
+        choices=["upload", "ls", "lsb", "geturl", "rm", "stats"],
+        help="操作类型",
+    )
+    parser.add_argument(
+        "-bucket",
+        help="bucket 名称",
+    )
+    parser.add_argument(
+        "-i", "--input",
+        help="路径（本地文件或云上对象 key）",
+    )
+    parser.add_argument(
+        "-o", "--output",
+        help="云上对象 key（仅 upload 使用）",
+    )
+    parser.add_argument(
+        "-m", "--model",
+        help="模型名称 (例如: doubao-seed-2-0-mini-260215)",
+    )
+    parser.add_argument(
+        "-c", "--content",
+        help="对话内容",
+    )
+    parser.add_argument(
+        "-q", "--query",
+        help="搜索关键词",
+    )
+    parser.add_argument(
+        "--count",
+        type=int,
+        default=10,
+        help="搜索返回条数 (默认: 10, 最多: 50)",
+    )
+    parser.add_argument(
+        "--time-range",
+        choices=["OneDay", "OneWeek", "OneMonth", "OneYear"],
+        default="OneWeek",
+        help="搜索时间范围 (默认: OneWeek)",
+    )
+
+    args = parser.parse_args()
+
+    if args.product == "tos":
+        handle_tos(args)
+    elif args.product == "model":
+        handle_model(args)
+    elif args.product == "search":
+        handle_search(args)
+    elif args.product:
+        print(f"错误: 不支持的产品: {args.product}", file=sys.stderr)
+        sys.exit(1)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

ark_cli/model_client.py

@@ -0,0 +1,90 @@
+"""大模型客户端"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.request
+import urllib.error
+from dataclasses import dataclass
+
+
+@dataclass
+class ChatResult:
+    """对话结果"""
+
+    content: str
+    duration_ms: int
+    input_tokens: int
+    output_tokens: int
+
+    def __str__(self) -> str:
+        return self.content
+
+
+class ModelClient:
+    """火山引擎大模型客户端"""
+
+    DEFAULT_ENDPOINT = "https://ark.cn-beijing.volces.com/api/v3/chat/completions"
+
+    def __init__(self, api_key: str | None = None, endpoint: str | None = None):
+        self.api_key = api_key or os.environ.get("ARK_API_KEY")
+        self.endpoint = endpoint or os.environ.get("ARK_ENDPOINT") or self.DEFAULT_ENDPOINT
+
+        if not self.api_key:
+            raise ValueError("缺少配置，请设置环境变量: ARK_API_KEY")
+
+    def chat(self, model: str, content: str) -> ChatResult:
+        """进行一轮对话
+
+        Args:
+            model: 模型名称
+            content: 用户输入内容
+
+        Returns:
+            ChatResult 包含回复内容、耗时和 token 使用量
+        """
+        data = {
+            "model": model,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": content,
+                        }
+                    ],
+                }
+            ],
+        }
+
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+        }
+
+        req = urllib.request.Request(
+            self.endpoint,
+            data=json.dumps(data).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+
+        try:
+            start_time = time.time()
+            with urllib.request.urlopen(req) as response:
+                result = json.loads(response.read().decode("utf-8"))
+            duration_ms = int((time.time() - start_time) * 1000)
+
+            usage = result.get("usage", {})
+            return ChatResult(
+                content=result["choices"][0]["message"]["content"],
+                duration_ms=duration_ms,
+                input_tokens=usage.get("prompt_tokens", 0),
+                output_tokens=usage.get("completion_tokens", 0),
+            )
+        except urllib.error.HTTPError as e:
+            error_body = e.read().decode("utf-8")
+            raise RuntimeError(f"API 调用失败 ({e.code}): {error_body}")

ark_cli/search_client.py

@@ -0,0 +1,126 @@
+"""联网搜索客户端"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.request
+import urllib.error
+from dataclasses import dataclass
+
+
+@dataclass
+class SearchResult:
+    """搜索结果项"""
+
+    title: str
+    site_name: str
+    url: str
+    snippet: str
+    publish_time: str
+
+
+@dataclass
+class SearchResponse:
+    """搜索响应"""
+
+    results: list[SearchResult]
+    result_count: int
+    duration_ms: int
+    query: str
+
+
+class SearchClient:
+    """火山引擎联网搜索客户端"""
+
+    DEFAULT_ENDPOINT = "https://open.feedcoopapi.com/search_api/web_search"
+
+    def __init__(self, api_key: str | None = None, endpoint: str | None = None):
+        self.api_key = api_key or os.environ.get("SEARCH_API_KEY")
+        self.endpoint = endpoint or os.environ.get("SEARCH_ENDPOINT") or self.DEFAULT_ENDPOINT
+
+        if not self.api_key:
+            raise ValueError("缺少配置，请设置环境变量: SEARCH_API_KEY")
+
+    def search(
+        self,
+        query: str,
+        search_type: str = "web",
+        count: int = 10,
+        time_range: str = "OneWeek",
+    ) -> SearchResponse:
+        """执行搜索
+
+        Args:
+            query: 搜索关键词 (1-100字符)
+            search_type: 搜索类型 (web/web_summary/image)
+            count: 返回条数 (最多50条，默认10条)
+            time_range: 时间范围 (OneDay/OneWeek/OneMonth/OneYear)
+
+        Returns:
+            SearchResponse 包含搜索结果列表和统计信息
+        """
+        data: dict = {
+            "Query": query,
+            "SearchType": search_type,
+            "Count": count,
+            "Filter": {
+                "NeedUrl": True,
+                "AuthInfoLevel": 1,
+                "NeedContent": True
+            },
+        }
+
+        data["TimeRange"] = time_range
+
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+        }
+
+        req = urllib.request.Request(
+            self.endpoint,
+            data=json.dumps(data).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+
+        try:
+            start_time = time.time()
+            with urllib.request.urlopen(req) as response:
+                result = json.loads(response.read().decode("utf-8"))
+            duration_ms = int((time.time() - start_time) * 1000)
+
+            # 检查错误
+            if "ResponseMetadata" in result:
+                metadata = result["ResponseMetadata"]
+                if "Error" in metadata:
+                    error = metadata["Error"]
+                    raise RuntimeError(f"API 错误 ({error.get('CodeN', 'unknown')}): {error.get('Message', 'unknown error')}")
+
+            # 解析结果
+            api_result = result.get("Result", {})
+            web_results = api_result.get("WebResults", []) or []
+            search_context = api_result.get("SearchContext", {})
+
+            results = []
+            for item in web_results:
+                results.append(SearchResult(
+                    title=item.get("Title", ""),
+                    site_name=item.get("SiteName", ""),
+                    url=item.get("Url", ""),
+                    snippet=item.get("Snippet", ""),
+                    publish_time=item.get("PublishTime", ""),
+                ))
+
+            return SearchResponse(
+                results=results,
+                result_count=api_result.get("ResultCount", 0),
+                duration_ms=duration_ms,
+                query=search_context.get("OriginQuery", query),
+            )
+
+        except urllib.error.HTTPError as e:
+            error_body = e.read().decode("utf-8")
+            raise RuntimeError(f"API 调用失败 ({e.code}): {error_body}")

ark_cli/tos_client.py

@@ -0,0 +1,185 @@
+"""TOS 对象存储客户端"""
+
+from __future__ import annotations
+
+import os
+
+import tos
+
+
+class TosClient:
+    """火山引擎 TOS 对象存储客户端"""
+
+    DEFAULT_ENDPOINT = "tos-cn-beijing.volces.com"
+    DEFAULT_REGION = "cn-beijing"
+
+    def __init__(
+        self,
+        ak: str | None = None,
+        sk: str | None = None,
+        endpoint: str | None = None,
+        region: str | None = None,
+    ):
+        self.ak = ak or os.environ.get("TOS_ACCESS_KEY")
+        self.sk = sk or os.environ.get("TOS_SECRET_KEY")
+        self.endpoint = endpoint or os.environ.get("TOS_ENDPOINT") or self.DEFAULT_ENDPOINT
+        self.region = region or os.environ.get("TOS_REGION") or self.DEFAULT_REGION
+
+        if not all([self.ak, self.sk]):
+            raise ValueError(
+                "缺少 TOS 配置，请设置环境变量: TOS_ACCESS_KEY, TOS_SECRET_KEY"
+            )
+
+        self.client = tos.TosClientV2(
+            ak=self.ak,
+            sk=self.sk,
+            endpoint=self.endpoint,
+            region=self.region,
+        )
+
+    def upload(self, bucket: str, local_path: str, object_key: str, expires: int = 86400) -> str:
+        """上传文件到 TOS
+
+        Args:
+            bucket: bucket 名称
+            local_path: 本地文件路径
+            object_key: 云上对象 key
+            expires: 临时链接过期时间（秒），默认 24 小时
+
+        Returns:
+            带签名的临时访问链接
+        """
+        if not os.path.exists(local_path):
+            raise FileNotFoundError(f"文件不存在: {local_path}")
+
+        self.client.put_object_from_file(bucket, object_key, local_path)
+
+        # 生成预签名临时链接
+        result = self.client.pre_signed_url(
+            http_method=tos.HttpMethodType.Http_Method_Get,
+            bucket=bucket,
+            key=object_key,
+            expires=expires,
+        )
+
+        return result.signed_url
+
+    def list_objects(self, bucket: str, prefix: str = "", max_keys: int = 1000) -> list[dict]:
+        """列出指定路径下的文件
+
+        Args:
+            bucket: bucket 名称
+            prefix: 路径前缀
+            max_keys: 最大返回数量
+
+        Returns:
+            文件列表，每个元素包含 key, size, last_modified
+        """
+        result = self.client.list_objects(
+            bucket,
+            prefix=prefix,
+            max_keys=max_keys,
+            delimiter="/",
+        )
+
+        items = []
+
+        # 添加目录（common_prefixes）
+        for cp in result.common_prefixes:
+            items.append({
+                "key": cp.prefix,
+                "size": "-",
+                "last_modified": "-",
+                "type": "dir",
+            })
+
+        # 添加文件
+        for obj in result.contents:
+            # 跳过与 prefix 完全相同的项（目录本身）
+            if obj.key == prefix:
+                continue
+            items.append({
+                "key": obj.key,
+                "size": obj.size,
+                "last_modified": obj.last_modified.strftime("%Y-%m-%d %H:%M:%S"),
+                "type": "file",
+            })
+
+        return items
+
+    def get_url(self, bucket: str, object_key: str, expires: int = 86400) -> str:
+        """获取对象的临时访问链接
+
+        Args:
+            bucket: bucket 名称
+            object_key: 云上对象 key
+            expires: 临时链接过期时间（秒），默认 24 小时
+
+        Returns:
+            带签名的临时访问链接
+        """
+        result = self.client.pre_signed_url(
+            http_method=tos.HttpMethodType.Http_Method_Get,
+            bucket=bucket,
+            key=object_key,
+            expires=expires,
+        )
+
+        return result.signed_url
+
+    def list_buckets(self) -> list[dict]:
+        """列出所有 bucket
+
+        Returns:
+            bucket 列表，每个元素包含 name, creation_date
+        """
+        result = self.client.list_buckets()
+
+        items = []
+        for bucket in result.buckets:
+            creation_date = bucket.creation_date
+            # 兼容 datetime 对象和字符串
+            if hasattr(creation_date, "strftime"):
+                creation_date = creation_date.strftime("%Y-%m-%d %H:%M:%S")
+            items.append({
+                "name": bucket.name,
+                "creation_date": creation_date,
+            })
+
+        return items
+
+    def delete(self, bucket: str, object_key: str) -> None:
+        """删除对象
+
+        Args:
+            bucket: bucket 名称
+            object_key: 云上对象 key
+        """
+        self.client.delete_object(bucket, object_key)
+
+    def stats(self, bucket: str) -> dict:
+        """获取 bucket 元数据
+
+        Args:
+            bucket: bucket 名称
+
+        Returns:
+            包含 bucket 元数据的字典
+        """
+        result = self.client.get_bucket_info(bucket)
+        info = result.bucket_info
+
+        creation_date = info.creation_date
+        if hasattr(creation_date, "strftime"):
+            creation_date = creation_date.strftime("%Y-%m-%d %H:%M:%S")
+
+        return {
+            "name": info.name,
+            "location": info.location,
+            "creation_date": creation_date,
+            "storage_class": str(info.storage_class).replace("StorageClassType.", ""),
+            "az_redundancy": str(info.az_redundancy).replace("AzRedundancyType.", ""),
+            "versioning": str(info.versioning).replace("VersioningStatusType.", ""),
+            "extranet_endpoint": info.extranet_endpoint,
+            "intranet_endpoint": info.intranet_endpoint,
+        }

ark_utils_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: ark-utils-cli
+Version: 0.3.0
+Summary: 火山引擎命令行工具 - 让人类和 AI Agent 都能在终端中操作火山引擎
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: tos>=2.9.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <h1 align="center">ark-cli</h1>
+</p>
+
+<p align="center">
+  火山引擎命令行工具 — 让人类和 AI Agent 都能在终端中操作火山引擎
+</p>
+
+<p align="center">
+  <a href="https://github.com/cnwarden/ark-cli/releases"><img src="https://img.shields.io/github/v/release/cnwarden/ark-cli?style=for-the-badge&color=FF6A00" alt="Release" /></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.9+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python" /></a>
+  <a href="https://github.com/cnwarden/ark-cli/stargazers"><img src="https://img.shields.io/github/stars/cnwarden/ark-cli?style=for-the-badge&color=f5a623" alt="Stars" /></a>
+  <a href="https://github.com/cnwarden/ark-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-teal.svg?style=for-the-badge" alt="License" /></a>
+</p>
+
+<p align="center">
+  <a href="#ark-cli-是什么">介绍</a> · <a href="#核心能力">核心能力</a> · <a href="#快速开始">快速开始</a> · <a href="#命令参考">命令参考</a> · <a href="#贡献">贡献</a>
+</p>
+
+---
+
+## ark-cli 是什么
+
+ark-cli 是火山引擎的命令行工具，将 TOS 对象存储、大模型服务、联网搜索等操作封装为简洁的命令行接口。
+
+### 为什么选择 ark-cli
+
+- **开箱即用** — 默认配置北京区域，最少只需 2 个环境变量即可开始使用
+- **AI Agent 友好** — 命令设计简洁，输出格式规范，便于 AI Agent 解析调用
+- **临时链接** — 上传文件自动返回 24 小时有效的签名 URL
+- **轻量依赖** — 基于 Python，使用 uv 包管理，安装简单
+
+## 核心能力
+
+| 模块 | 能力 |
+|------|------|
+| **TOS 对象存储** | 文件上传、列表、删除、临时链接生成、Bucket 统计 |
+| **大模型服务** | 单轮对话、Token 用量统计、耗时统计 |
+| **联网搜索** | 网页搜索、结果摘要、时间范围过滤 |
+
+## 快速开始
+
+### 安装
+
+**从源码安装**
+
+```bash
+git clone https://github.com/cnwarden/ark-cli.git
+cd ark-cli
+uv sync
+```
+
+**从 Release 下载**
+
+从 [Releases](https://github.com/cnwarden/ark-cli/releases/latest) 页面下载最新的 wheel 包：
+
+```bash
+pip install ark_cli-*.whl
+```
+
+### 配置凭证
+
+```bash
+# TOS 对象存储（必需）
+export TOS_ACCESS_KEY="your-access-key"
+export TOS_SECRET_KEY="your-secret-key"
+
+# TOS 可选配置（默认北京区域）
+export TOS_ENDPOINT="tos-cn-beijing.volces.com"
+export TOS_REGION="cn-beijing"
+
+# 大模型服务（使用 model 功能时必需）
+export ARK_API_KEY="your-api-key"
+
+# 联网搜索（使用 search 功能时必需）
+export SEARCH_API_KEY="your-search-api-key"
+```
+
+### 验证安装
+
+```bash
+ark-cli -v
+```
+
+## 命令参考
+
+```
+ark-cli [-p PRODUCT] [-a ACTION] [OPTIONS]
+
+Products:
+  tos       TOS 对象存储操作
+  model     大模型对话
+  search    联网搜索
+
+TOS Actions:
+  upload    上传文件
+  ls        列出文件
+  lsb       列出 Bucket
+  geturl    获取临时链接
+  rm        删除文件
+  stats     Bucket 统计信息
+
+Model Options:
+  -m        模型名称（例如: doubao-seed-2-0-mini-260215）
+  -c        对话内容
+
+Search Options:
+  -q        搜索关键词
+  --count   返回条数（默认: 10, 最多: 50）
+```
+
+<details>
+<summary>TOS 对象存储</summary>
+
+```bash
+# 上传文件（返回 24 小时有效的签名链接）
+ark-cli -p tos -a upload -bucket my-bucket -i ./test.txt -o data/test.txt
+
+# 列出 Bucket
+ark-cli -p tos -a lsb
+
+# 列出文件
+ark-cli -p tos -a ls -bucket my-bucket
+ark-cli -p tos -a ls -bucket my-bucket -i data/
+
+# 获取临时链接
+ark-cli -p tos -a geturl -bucket my-bucket -i data/test.txt
+
+# 删除文件
+ark-cli -p tos -a rm -bucket my-bucket -i data/test.txt
+
+# Bucket 统计信息
+ark-cli -p tos -a stats -bucket my-bucket
+```
+
+**输出示例**
+
+列出文件：
+```
+DIR        -                    data/subdir/
+1.2KB      2024-03-30 10:00:00  data/test.txt
+256B       2024-03-30 09:30:00  data/config.json
+```
+
+Bucket 统计：
+```
+Bucket:      my-bucket
+Location:    cn-beijing
+Created:     2025-05-12 12:29:06
+Storage:     Storage_Class_Standard
+Redundancy:  Az_Redundancy_Single_Az
+Versioning:  Versioning_Unknown
+Endpoint:    tos-cn-beijing.volces.com
+```
+
+</details>
+
+<details>
+<summary>大模型对话</summary>
+
+```bash
+# 单轮对话
+ark-cli -p model -m doubao-seed-2-0-mini-260215 -c "你好，请介绍一下你自己"
+```
+
+**输出示例**
+```
+嗨！👋 你好呀~ 请问有什么我可以帮你的吗？
+
+[耗时: 5991ms | tokens: 50 in / 371 out]
+```
+
+</details>
+
+<details>
+<summary>联网搜索</summary>
+
+```bash
+# 基础搜索
+ark-cli -p search -q "火山引擎"
+
+# 指定返回条数
+ark-cli -p search -q "Python 教程" --count 5
+```
+
+**输出示例**
+```
+[1] 火山引擎官网 - 字节跳动旗下云服务平台
+    火山引擎 | 2025-03-30
+    https://www.volcengine.com/
+    火山引擎是字节跳动旗下的云服务平台，提供云计算、大数据、人工智能等服务...
+
+[2] 火山引擎开放平台 - 开发者文档
+    火山引擎 | 2025-03-28
+    https://www.volcengine.com/docs
+    火山引擎开放平台提供丰富的 API 和 SDK，帮助开发者快速接入...
+
+[共 10 条结果 | 耗时: 372ms]
+```
+
+</details>
+
+## 技术栈
+
+| 组件 | 选型 | 说明 |
+|------|------|------|
+| 语言 | [Python](https://www.python.org/) 3.9+ | |
+| 包管理 | [uv](https://github.com/astral-sh/uv) | 快速的 Python 包管理器 |
+| TOS SDK | [tos](https://github.com/volcengine/ve-tos-python-sdk) | 火山引擎 TOS 官方 SDK |
+| 构建工具 | [hatchling](https://hatch.pypa.io/) | Python 构建后端 |
+
+## 项目结构
+
+```
+ark-cli/
+├── ark_cli/
+│   ├── __init__.py          # 版本定义
+│   ├── cli.py                # CLI 入口
+│   ├── tos_client.py         # TOS 客户端封装
+│   ├── model_client.py       # 大模型客户端
+│   └── search_client.py      # 联网搜索客户端
+├── pyproject.toml            # 项目配置
+├── Makefile                  # 构建脚本
+└── README.md
+```
+
+## 开发
+
+```bash
+# 克隆项目
+git clone https://github.com/cnwarden/ark-cli.git
+cd ark-cli
+
+# 安装依赖
+uv sync
+
+# 运行
+uv run ark-cli -v
+
+# 构建
+uv build
+
+# 发布到 TOS
+make publish
+```
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+1. Fork 本仓库
+2. 创建特性分支：`git checkout -b feature/amazing-feature`
+3. 提交更改：`git commit -m 'feat: add amazing feature'`
+4. 推送分支：`git push origin feature/amazing-feature`
+5. 提交 Pull Request
+
+提交信息请遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范。
+
+## License
+
+[MIT](LICENSE)
+
+## 相关链接
+
+- [火山引擎控制台](https://console.volcengine.com/) — 获取 Access Key
+- [TOS 文档](https://www.volcengine.com/docs/6349) — 对象存储文档
+- [方舟大模型](https://www.volcengine.com/docs/82379) — 大模型服务文档
+- [联网搜索 API](https://www.volcengine.com/docs/87772/2272953) — 联网搜索文档

ark_utils_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ark_cli/__init__.py,sha256=6_kreJnX_xCuH6ty5hsJsg-F9qVjFq8xlYradAAfV-Q,57
+ark_cli/cli.py,sha256=xGkp4w06N66b8LLwzXcn2dNPSa4szwIhXMUYd6Kf660,8124
+ark_cli/model_client.py,sha256=77EQLnYbFMazcZRG8TwGSNgRDeYORyebU3r38ipaF4I,2563
+ark_cli/search_client.py,sha256=J8gncQMCG_16AmVvWvLCd7WFNV7OqN489Mw7AAhUhAM,3759
+ark_cli/tos_client.py,sha256=VxhM_oqTCqZ7KqC7eEvL2qjhK1TtImsQsu41PJhi4Rc,5606
+ark_utils_cli-0.3.0.dist-info/METADATA,sha256=kMbbgXD2mVqPInGOG2ZiS5rDG7aITUmwRbWTlsb3EtQ,7355
+ark_utils_cli-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ark_utils_cli-0.3.0.dist-info/entry_points.txt,sha256=s-b0LrOd_0hzcpUfTy8ungGP0QLOhL75R6sAzpLfcyg,45
+ark_utils_cli-0.3.0.dist-info/licenses/LICENSE,sha256=hpECGeLwcNtHJ51vjSm_gU6DL7LfCLnpUkA5n8MDIXs,1065
+ark_utils_cli-0.3.0.dist-info/RECORD,,

ark_utils_cli-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ark_utils_cli-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ark-cli = ark_cli.cli:main

ark_utils_cli-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cnwarden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.