tars-cli 1.1.0

tars 平台命令行工具

tars-cli

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

安装

pip install tars-cli

安装验证

$ tars --version
tars-cli 1.1.0

升级

pip install --upgrade tars-cli

环境要求

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

快速开始

# 登录
$ 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>

命令测试结果

认证

用户名密码登录

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

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

API 密钥登录

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

$ 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 覆盖。

$ 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

模板下载

$ 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 生成 & 管理

$ 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 生成 & 管理

$ 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>         │
└────────────────────────────────────┴──────────┴────────┴────────────────────┘

发布数据集版本

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

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

$ 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 评估

$ 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 评估

$ 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>

查看评估状态

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

安全评估

--agent-name 和 --skill-name 二选一，必须指定其中一个。支持智能推荐漏洞、创建评估任务、查看报告和诊断建议。

完整流程（推荐）

# 1. 智能推荐漏洞（基于攻击面分析自动匹配）
$ tars security recommend <plugin_id> --version-id <ver> --agent-name <name>

# 2. 创建并执行评估（使用推荐结果）
$ tars security create <plugin_id> --version-id <ver> --agent-name <name> --from-recommend --run
任务已创建: <assessment_id>
  completed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:05:32

📎 Web 查看: <server_url>/plugins/<plugin_id>/security/<assessment_id>
assessment_id: <assessment_id>
status: completed
risk_level: high
message: 安全评估完成

# 3. 查看评估报告
$ tars security report <assessment_id>

# 4. 获取修复建议（P0/P1/P2 分级）
$ tars security diagnosis <assessment_id>

手动指定漏洞

$ tars security create <plugin_id> --version-id <ver> --agent-name <name> \
    --vuln-ids VULN-001,VULN-002 --attacks-per-vuln 3 --run

CI/CD 集成（CVSS 阈值卡点）

tars -o json security create $PLUGIN_ID --version-id $VERSION_ID \
    --agent-name $AGENT_NAME --from-recommend --run --cvss-threshold 7.0
# 退出码: 0=通过（CVSS<阈值）, 1=不通过（CVSS>=阈值）, 2=执行错误

其他命令

命令	用途
tars security list <plugin_id>	列出评估任务（支持 --status, --target-name 过滤）
tars security run <assessment_id>	执行已创建的评估任务
tars security cancel <assessment_id>	取消运行中的任务
tars security delete <assessment_id>	删除任务
tars security results <assessment_id>	获取结果明细（支持 --status, --vuln-name 过滤）
tars security vulns	查询漏洞库（支持 --category, --tag, --search）
tars security vulns show <vuln_id>	查看单个漏洞详情
tars security attack-methods	查询攻击方法库
tars security attacks --vuln-ids <ids>	预览攻击方法匹配
tars security tags	获取 Tags 字典
tars security config	获取安全评估全局配置

APO 优化

APO（Automatic Prompt Optimization）基于评估结果自动优化 Agent/Skill 的 Prompt，提升通过率。需先完成评估任务。

一步到位（推荐）

# 评估完成后触发优化并自动应用
$ tars optimize run <task_id> --apply
优化任务已触发: <optimization_id>
  completed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:02:18

optimization_id: <optimization_id>
status: applied
pass_rate_improvement: +12.5%
new_version_id: <new_version_id>
message: 优化已应用，新版本已创建

带阈值卡点

# 通过率提升不足 10% 则不应用
$ tars optimize run <task_id> --apply --pass-rate-threshold 0.1
# 退出码: 0=应用成功, 1=收益不足未应用, 2=执行错误

分步操作

# 触发优化，等待完成
$ tars optimize run <task_id>

# 查看优化状态
$ tars optimize status <task_id>

# 查看优化方案详情
$ tars optimize show <optimization_id>

# 手动应用优化结果（创建新版本）
$ tars optimize apply <optimization_id>

全局选项

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

CI/CD 集成

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/ 目录。

# 第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 功能）