Metadata-Version: 2.4
Name: tars-cli
Version: 1.0.1
Summary: tars 平台命令行工具
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: platformdirs>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"

# tars-cli

tars 平台命令行工具，支持插件导入、数据集管理、评估执行和报告导出。

## 安装

```bash
pip install tars-cli
```

### 安装验证

```bash
$ tars --version
tars-cli 1.0.0
```

### 升级

```bash
pip install --upgrade tars-cli
```

### 环境要求

- Python >= 3.11
- 依赖：typer >= 0.12, httpx >= 0.27, rich >= 13.0, pyyaml >= 6.0, platformdirs >= 4.0

## 快速开始

```bash
# 登录
$ tars auth login -s <server_url>

# 导入插件
$ tars plugin import <git_url_or_file_path>

# 生成数据集
$ tars dataset generate <plugin_id> --agent-name <name> --conversation-type single_turn

# 发布数据集
$ tars dataset publish <version_id>

# 执行评估
$ tars eval run <plugin_id> --agent-name <name> --dataset-version <version_id>

# 导出报告
$ tars plugin export-report <plugin_id>
```

## 命令测试结果

### 认证

#### 用户名密码登录

```bash
$ tars auth login -s <server_url>
登录 tars 平台
用户名: admin
密码: ********
✓ 登录成功
  服务器: <server_url>
  用户: admin

$ tars auth logout
✓ 已登出，本地凭证已清除
```

#### API 密钥登录

适用于 CLI 和 CI/CD 场景。先在 Web 端「个人设置 → API 密钥」中创建密钥，然后使用 `--token` 参数登录：

```bash
$ tars auth login -s <server_url> --token trs_xxxxxxxxxxxx
✓ 登录成功
  服务器: <server_url>
```

> **注意**: API 密钥明文只展示一次，创建后请立即复制保存。密钥不会过期，无需刷新。

### 插件管理

> Git 导入可选参数：`--branch`（分支，默认 main）、`--path`（子目录路径）、`--auth-type`（认证方式：none/token/ssh-key）、`--auth-token`（认证凭证）。本地文件导入支持 `--overwrite` 覆盖。

```bash
$ tars plugin import <git_url>
✓ 插件验证通过
✓ Plugin 导入成功

$ tars plugin import <git_url> --branch <branch> --path <subpath> --auth-type token --auth-token <token>
✓ 插件验证通过
✓ Plugin 导入成功

$ tars plugin import /path/to/plugin.zip --overwrite
✓ 插件验证通过
✓ Plugin 导入成功（已覆盖）

$ tars plugin export-report <plugin_id>
message: 报告导出成功
path: /path/to/report_<plugin_id>_<timestamp>.html
```

### 模板下载

```bash
$ tars template download plan -f yaml
✓ 模板下载成功
  文件: plan-template.yaml

$ tars template download testcase-single
✓ 模板下载成功
  文件: testcase-single-template.yaml

$ tars template download testcase-multi
✓ 模板下载成功
  文件: testcase-multi-template.yaml
```

### 数据集管理

> `--agent-name` 和 `--skill-name` 二选一，必须指定其中一个。`publish` 仅需版本 ID，无需指定目标。
>
> `--conversation-type`（简写 `-t`）支持 `single_turn`（默认）和 `multi_turn`，用于指定会话类型。

#### 按 Agent 生成 & 管理

```bash
$ tars dataset generate <plugin_id> --agent-name <name> --conversation-type single_turn
  completed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:03:56
  completed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:04:47

📎 Web 查看: <server_url>/plugins/<plugin_id>/golden-set/<version_id>
version_id: <version_id>
status: draft
case_count:
message: 数据集生成完成
👉 下一步: tars dataset publish <version_id>

$ tars dataset list <plugin_id> --agent-name <name> --conversation-type single_turn
              数据集版本列表
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ 版本 ID                            ┃ 状态     ┃ 用例数 ┃ 创建时间           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ <version_id>                       │ published│ N      │ <datetime>         │
│ <version_id>                       │ draft    │ N      │ <datetime>         │
└────────────────────────────────────┴──────────┴────────┴────────────────────┘
```

#### 按 Skill 生成 & 管理

```bash
$ tars dataset generate <plugin_id> --skill-name <name> --conversation-type multi_turn
  completed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:03:56
  completed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:04:47

📎 Web 查看: <server_url>/plugins/<plugin_id>/golden-set/<version_id>
version_id: <version_id>
status: draft
case_count:
message: 数据集生成完成
👉 下一步: tars dataset publish <version_id>

$ tars dataset list <plugin_id> --skill-name <name> --conversation-type multi_turn
              数据集版本列表
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ 版本 ID                            ┃ 状态     ┃ 用例数 ┃ 创建时间           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ <version_id>                       │ published│ N      │ <datetime>         │
└────────────────────────────────────┴──────────┴────────┴────────────────────┘
```

#### 发布数据集版本

```bash
$ tars dataset publish <version_id>
version_id: <version_id>
status: published
message: 发布成功
```

#### 手动上传评估计划和测试用例

```bash
$ tars dataset upload <plugin_id> --agent-name <name> --conversation-type single_turn --plan plan.yaml --cases cases.yaml
成功导入 <N> 条用例

📎 Web 查看: <server_url>/plugins/<plugin_id>/golden-set/<version_id>
version_id: <version_id>
status: published
message: 数据集上传并发布成功
👉 下一步: tars eval run <plugin_id> --agent-name <name> --dataset-version <version_id>
```

### 评估

> `--agent-name` 和 `--skill-name` 二选一，可不传。`eval status` 仅需任务 ID。

#### 按 Agent 评估

```bash
$ tars eval run <plugin_id> --agent-name <name> --dataset-version <version_id>
任务已创建: <task_id>
  completed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:07:13

📎 Web 查看: <server_url>/plugins/<plugin_id>/evaluation/<task_id>
task_id: <task_id>
status: completed
score: <score>
pass_rate: <rate>
message: 评估完成
  └─ 评估结论:
    1. [P0][L1] 失败模式名称
       缺陷表现: 缺陷表现描述
       代表案例: case_id_1, case_id_2
       根因分析: 根因分析描述
       优化建议: 优化建议描述
    2. [P1][L2] 失败模式名称
       缺陷表现: 缺陷表现描述
       代表案例: case_id_1, case_id_2
       根因分析: 根因分析描述
       优化建议: 优化建议描述
👉 完整报告: tars plugin export-report <plugin_id>
```

#### 按 Skill 评估

```bash
$ tars eval run <plugin_id> --skill-name <name> --dataset-version <version_id>
任务已创建: <task_id>
  completed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:07:13

📎 Web 查看: <server_url>/plugins/<plugin_id>/evaluation/<task_id>
task_id: <task_id>
status: completed
score: <score>
pass_rate: <rate>
message: 评估完成
  └─ 评估结论:
    1. [P0][L1] 失败模式名称
       缺陷表现: 缺陷表现描述
       代表案例: case_id_1, case_id_2
       根因分析: 根因分析描述
       优化建议: 优化建议描述
    2. [P1][L2] 失败模式名称
       缺陷表现: 缺陷表现描述
       代表案例: case_id_1, case_id_2
       根因分析: 根因分析描述
       优化建议: 优化建议描述
👉 完整报告: tars plugin export-report <plugin_id>
```

#### 查看评估状态

```bash
$ tars eval status <task_id>
task_id: <task_id>
status: completed
overall_score: <score>
total_cases: <N>
passed_cases: <N>
failed_cases: <N>
```

## 全局选项

| 选项 | 说明 |
|------|------|
| `-o, --output FORMAT` | 输出格式：`table`（默认）/ `json` / `yaml` |
| `-q, --quiet` | 安静模式 |
| `--verbose` | 打印 HTTP 请求日志 |
| `--server URL` | 覆盖服务地址（优先级：`--server` > `TARS_SERVER_URL` 环境变量 > 默认 `http://localhost:8001`） |
| `-V, --version` | 查看版本 |

## CI/CD 集成

```bash
export TARS_ACCESS_TOKEN=<token>
export TARS_SERVER_URL=<server_url>

tars -o json -q eval run <plugin_id> \
  --agent-name <name> \
  --dataset-version <version_id>
```

> **注意**: 全局选项（`-o`、`-q`、`--verbose`、`--server`）必须放在子命令之前，否则会报错。`TARS_ACCESS_TOKEN` 一旦设置，优先级高于本地凭证文件，token 过期后需手动更新环境变量或 `unset TARS_ACCESS_TOKEN` 回退到文件凭证。

## 退出码

| 退出码 | 含义 |
|--------|------|
| 0 | 成功 |
| 2 | 执行错误（网络、参数、认证等） |

## Claude Code 集成

tars-cli 提供了 Claude Code Plugin（技能说明书），安装后可在 Claude Code 中使用自然语言调用 tars 命令（如"帮我评估 xxx 插件"），无需记忆 CLI 参数。

### 安装

tars-cli 的 Skill 作为独立 Plugin 分发，与 pip 包完全解耦。Plugin 源码位于仓库 `apps/plugins/tars-cli/` 目录。

```bash
# 第1步：安装 CLI 命令
pip install tars-cli

# 第2步：从 GitLab 仓库下载 skill 文件到全局 skill 目录
cd /tmp
git -c http.sslVerify=false clone --depth 1 --sparse https://git.easyops.local/anyclouds/tars-p.git /tmp/tars-plugin
cd /tmp/tars-plugin && git sparse-checkout set apps/plugins/tars-cli
mkdir -p ~/.claude/skills && cp -r apps/plugins/tars-cli/skills/tars-cli ~/.claude/skills/tars-cli
rm -rf /tmp/tars-plugin
```

> 也可直接从 GitLab 网页下载 `apps/plugins/tars-cli/skills/tars-cli` 目录后手动放置到 `~/.claude/skills/tars-cli`。

安装后的目录结构：

```
~/.claude/skills/tars-cli/
├── SKILL.md              # Skill 主文件（命令映射 + 执行流程）
└── references/
    ├── auth.md            # 登录/登出流程
    └── workflows.md       # 完整评估工作流 + 错误处理
```

已有同名 skill 时直接覆盖即可更新。

### 支持的自然语言指令

| 示例 | 实际执行的命令 |
|------|---------------|
| "登录 tars" | `tars auth login` |
| "导入插件 https://github.com/xxx/xxx.git" | `tars plugin import <git_url>` |
| "帮我评估 xxx 插件" | 完整评估流程（生成数据集 → 发布 → 运行评估 → 导出报告） |
| "生成数据集" | `tars dataset generate ...` |
| "查看评估状态" | `tars eval status ...` |
| "下载模板" | `tars template download ...` |
| "导出报告" | `tars plugin export-report ...` |

### 前置条件

- 已安装 tars-cli：`pip install tars-cli`
- 已安装 tars-cli skill：从 GitLab 仓库下载到 `~/.claude/skills/tars-cli`
- 已登录：`tars auth login -s <server_url>`
- Claude Code 版本 >= 1.0（支持 Skill 功能）
