Metadata-Version: 2.4
Name: sd-helper-cli
Version: 0.1.7
Summary: CLI tool for Huawei Cloud Service Delivery Engineers
Project-URL: Homepage, https://github.com/xuopoj/sd-helper
Project-URL: Repository, https://github.com/xuopoj/sd-helper
Author-email: Sean <xuopoj@gmail.com>
License: MIT
Keywords: cli,cloud,huawei,llm,modelarts,service-delivery
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: textual>=0.80.0
Description-Content-Type: text/markdown

# sd-helper

华为云服务交付工程师的命令行工具，用于简化日常运维操作。

## 快速开始

安装后生成配置文件，填写凭据即可使用：

```bash
sd-helper init         # 生成 ~/.sd-helper.yaml
```

## 安装

**在线安装：**

```bash
pip install sd-helper-cli
```

**离线安装（服务器无外网）：**

在有网络的机器上下载依赖包：

```bash
# 默认 ARM64 / Python 3.9，可通过参数调整
bash scripts/download_wheels.sh
bash scripts/download_wheels.sh --platform manylinux2014_x86_64 --python-version 3.10

# 将生成的 sd-helper-offline.tar.gz 传输到服务器
scp sd-helper-offline.tar.gz user@server:/tmp/
```

在服务器上安装到 virtualenv：

```bash
bash install.sh --archive /tmp/sd-helper-offline.tar.gz
source ~/.venv/sd-helper/bin/activate
sd-helper --version
```

## 功能模块

### IAM 认证

```bash
# 配置凭据
sd-helper iam configure

# 获取 token
sd-helper iam token

# 查看已配置的 profile
sd-helper iam list-profiles

# 设置默认 profile
sd-helper iam set-default <profile>
```

### LLM 对话

与 ModelArts / 盘古大模型进行对话。

```bash
# 添加模型配置
sd-helper llm add <model-name> --endpoint <url> --type modelarts

# 查看已配置的模型
sd-helper llm list

# 单次对话
sd-helper llm chat "你好"

# 携带文件上下文
sd-helper llm chat -f code.py "解释这段代码"

# 视觉模型（图片输入）
sd-helper llm chat -i image.jpg "描述这张图片"

# 交互式对话（进入 TUI 界面）
sd-helper llm chat

# OCR：识别图片中的手写数字（短码 + 长码）
sd-helper llm ocr image.jpg
sd-helper llm ocr *.jpg
```

输出为 JSON 数组，每张图片对应一条记录：

```json
[
  {
    "short_code": "36 202",
    "long_code": "269202",
    "file": "image.jpg"
  }
]
```

OCR 提示词默认内置，也可在模型配置中自定义：

```yaml
llm:
  models:
    qwen3-vl-32b:
      endpoint: https://...
      type: vl
      ocr_prompt: "识别图片中的文字，只返回 JSON：{\"result\": \"...\"}"
```

### Nisco OCR

从 Nisco 系统下载图片并调用多模态大模型进行 OCR 识别，结果写入 Excel。

**下载图片并生成 Excel：**

```bash
# 下载指定日期范围内 result_sta=否 的记录，图片嵌入 Excel
sd-helper nisco ocr image-download --start 2026-03-01 --end 2026-03-02

# 指定输出文件和图片目录
sd-helper nisco ocr image-download --start 2026-03-01 --end 2026-03-31 -o march.xlsx -i ./march_images
```

生成的 Excel 包含所有原始字段，以及：
- `image_file_name` — 保存到磁盘的图片文件名
- `image` — 嵌入的图片预览（512px）

**对已下载的图片运行 OCR：**

```bash
# 使用默认模型和提示词
sd-helper nisco ocr run nisco_ocr.xlsx

# 指定模型
sd-helper nisco ocr run nisco_ocr.xlsx -m qwen3-vl-32b

# 自定义提示词
sd-helper nisco ocr run nisco_ocr.xlsx --prompt "识别图片中的炉号，只返回JSON: {\"result\": \"...\", \"reason\": \"...\"}"

# 从文件读取提示词
sd-helper nisco ocr run nisco_ocr.xlsx --prompt-file my_prompt.txt
```

OCR 结果写回原 Excel，新增三列：
- `ocr_raw` — 模型原始返回内容
- `ocr_result` — 解析后的识别结果
- `ocr_reason` — 模型说明

### Docker 镜像管理

批量加载并推送镜像到 SWR，支持断点续传。

**前提条件：** 环境已安装 docker，并完成 SWR 登录。

```bash
# 校验资产清单中的文件是否完整
sd-helper docker upload-images --config config.yaml --dir /path/to/files --validate

# 试运行（只打印命令，不执行）
sd-helper docker upload-images --config config.yaml --dir /path/to/files --dry-run

# 正式上传
sd-helper docker upload-images --config config.yaml --dir /path/to/files

# 重置所有进度（重新上传）
sd-helper docker upload-images --reset-all

# 重置指定镜像的进度
sd-helper docker upload-images --reset "name:tag"
```

配置文件示例（`config.yaml`）：

```yaml
assets_file: 资产清单.txt        # 资产清单文件，只处理其中的 镜像 分区

swr:
  endpoint: swr.cn-north-4.myhuaweicloud.com
  org: com-huaweicloud-dataengineering

cleanup_after_push: false        # 设为 true 可在推送后删除本地镜像
```

后台运行：

```bash
nohup sd-helper docker upload-images --config config.yaml --dir /path/to/files > upload.log 2>&1 &
echo $!                  # 记录 PID
tail -f upload.log        # 查看实时日志
cat .progress.json        # 查看每个镜像的上传状态
```

### 数据管理

离线收集和同步数据。

```bash
# 采集数据
sd-helper data collect --name <name>

# 查看已采集的数据
sd-helper data list

# 使用模板批量执行请求
sd-helper data run <template.yaml>
```

## 独立脚本

`scripts/upload_images.py` 是一个独立版本的镜像上传脚本，仅依赖 `pyyaml`，可直接复制到目标节点使用：

```bash
python upload_images.py --config config.yaml --dir /path/to/files
```

后台运行：

```bash
nohup python upload_images.py --config config.yaml --dir /path/to/files > upload.log 2>&1 &
echo $!                  # 记录 PID
tail -f upload.log        # 查看实时日志
cat .progress.json        # 查看每个镜像的上传状态
```