Metadata-Version: 2.4
Name: tinet-agent-cli
Version: 0.1.1
Summary: Tinet Agent CLI Orchestrator
Requires-Python: >=3.12
Requires-Dist: filelock<4.0.0,>=3.32.5
Requires-Dist: httpx>=0.27.0
Requires-Dist: jsonschema<5.0.0,>=4.23.0
Requires-Dist: pyyaml<7.0.0,>=6.0.2
Requires-Dist: typer<0.27.0,>=0.26.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# TACO：天润智能体平台 CLI

TACO（Tinet Agent CLI Orchestrator）是天润智能体平台的命令行工具，面向开发者、
自动化流水线，以及 Cursor、Codex、Claude Code 等 AI Agent。

TACO 将平台能力组织成稳定、可发现的参数化命令，既支持面向人的终端输出，
也支持面向程序的 JSON 输出。

## 主要能力

- 使用 Profile 管理和切换多个企业环境
- 查询、创建和管理智能体应用，包括从应用模板创建应用
- 拉取、校验、调试和发布智能体 DSL
- 管理 Workflow、Chatflow、模型、分类和智能体工具
- 查询智能体会话、消息和节点追踪记录
- 通过参数化命令管理智能知识库、目录、问答、文档和附件
- 为 AI Agent 和 CI 提供可机读的命令与参数契约

## 安装

TACO 需要 Python 3.12 或更高版本。推荐使用 `pipx` 安装：

```bash
pipx install tinet-agent-cli
taco --version
```

也可以使用 `pip`：

```bash
python -m pip install tinet-agent-cli
taco --version
```

## 命令结构

TACO 的一级命令如下：

| 命令 | 用途 |
| --- | --- |
| `taco profile` | 查看 Zenava/TACO Profile，并管理 TACO Profile |
| `taco agent` | 智能体管理 |
| `taco aikb` | 智能知识库管理 |
| `taco help` | 以文本或 JSON 输出 CLI 命令契约 |

查看任意层级的帮助：

```bash
taco --help
taco agent --help
taco aikb --help
taco aikb faq create --help
```

`--profile`、`--json` 和 `--no-input` 是全局选项，建议放在一级命令之前：

```bash
taco --profile clink-bj --json --no-input agent app list
```

## 配置授权

使用前需要准备开发者中心的 AccessKeyId 和 AccessKeySecret，并为接口密钥分配
“智能体 > CLI 授权”权限。

CLINK2 endpoint 示例：

- 北京平台：`https://api-bj.clink.cn`
- 上海平台：`https://api-sh.clink.cn`

创建或修改 TACO Profile：

```bash
TACO_ACCESS_KEY_SECRET='<access-key-secret>' taco profile set \
  --name clink-bj \
  --endpoint https://api-bj.clink.cn \
  --access-key-id '<access-key-id>'
```

Profile 会在首次需要 access token 时自动完成授权。列出可用 Profile：

```bash
taco profile list
taco --json profile list
```

`profile list` 同时展示 Zenava 和 TACO 配置，并对 AccessKeySecret 和 access token
脱敏。未指定 `--profile` 时，TACO 优先使用有效的 Zenava current Profile，再降级
使用 TACO current Profile。

管理 TACO Profile：

```bash
taco profile use clink-bj
taco profile delete <profile-name>
```

多企业或多环境场景可以为单次命令指定 Profile：

```bash
taco --profile clink-sh agent app list
```

## 智能体管理

### 应用与模板

```bash
taco agent app list --limit 20
taco --json agent app get <app-id>
taco agent app tag list --keyword 客服
taco agent app template list
taco agent app template create <template-app-id> --name <new-app-name> --yes
```

通过模板创建应用时，不传 `--name` 会沿用模板名称。

### 智能体 DSL

```bash
taco agent create \
  --name <agent-name> \
  --category <category-code> \
  --output agent.json \
  --yes

taco agent pull <app-id> --output agent.json
taco agent validate --dsl agent.json
taco agent run <app-id> --dsl agent.json --query '<question>'
taco agent publish <app-id> --dsl agent.json --keep-dsl --yes
```

使用以下命令发现可用的分类、模型、示例、场景和 Schema：

```bash
taco agent category list
taco agent model list
taco agent example list
taco agent scenario list
taco agent schema list
```

Workflow、Chatflow 和工具能力可通过子命令继续发现：

```bash
taco agent workflow --help
taco agent chatflow --help
taco agent tool --help
```

### 会话记录

```bash
taco agent conversation list \
  --app-id <app-id> \
  --created-at-start <unix-seconds> \
  --created-at-end <unix-seconds>

taco agent conversation message list \
  --app-id <app-id> \
  --conversation-id <conversation-id> \
  --conversation-created-at <unix-seconds>

taco agent conversation trace list \
  --app-id <app-id> \
  --conversation-id <conversation-id> \
  --conversation-created-at <unix-seconds> \
  --message-id <message-id>
```

## 智能知识库管理

AIKB 接口按业务领域组织成参数化命令：

| 命令组 | 用途 |
| --- | --- |
| `repository` | 查询公共、个人知识库及知识库详情 |
| `directory` | 查询、创建、修改、移动和删除目录 |
| `faq` | 查询、创建、修改和删除问答知识 |
| `file` | 查询、上传、创建和删除文档知识 |
| `recycle-bin` | 查询知识库回收站 |
| `knowledge` | 知识搜索与会话问答 |
| `media` | 获取文档或问答附件的预览、下载地址 |
| `attachment` | 获取附件 OSS 表单上传地址及签名 |

查询知识库和目录：

```bash
taco aikb repository list-public
taco aikb repository list-private
taco aikb directory list --repository-id <repository-id> --type FAQ
```

管理问答知识：

```bash
taco aikb faq list --repository-id <repository-id> --limit 20
taco aikb faq create \
  --repository-id <repository-id> \
  --directory-id <directory-id> \
  --question '<question>' \
  --answers '[{"content":"<answer>","type":"text"}]' \
  --auto-online \
  --yes
```

上传本地文档时，TACO 会先获取临时地址，再上传文件：

```bash
taco aikb file upload --file ./manual.pdf --yes
```

上传成功后，使用返回的 `fileKey` 创建文档知识：

```bash
taco aikb file create \
  --repository-id <repository-id> \
  --directory-id <directory-id> \
  --file-name manual.pdf \
  --file-key <file-key> \
  --auto-online \
  --yes
```

搜索和问答：

```bash
taco aikb knowledge search --keyword '<keyword>' --limit 10
taco aikb knowledge assistant \
  --username <username> \
  --content '<question>' \
  --yes
```

其他 AIKB 命令可继续通过帮助发现：

```bash
taco aikb recycle-bin --help
taco aikb media --help
taco aikb attachment --help
```

## 提供给 AI Agent 和 CI 使用

推荐使用 `--json --no-input` 获取稳定的机器可读输出，并禁用交互输入：

```bash
taco --json --no-input profile list
taco --profile clink-bj --json --no-input agent app list --limit 10
taco --profile clink-bj --json --no-input aikb repository list-public
```

AI Agent 可以先读取完整命令树和参数契约，再选择合适的具体命令：

```bash
taco help -o json
```

对远程资源的创建、修改、删除、上传和发布操作，先确认当前 Profile、
目标资源和变更范围，再显式传入 `--yes`。

## 安全提示

- 不要把 AccessKeySecret 或 access token 写入代码、DSL、日志和对话内容。
- 优先通过隐藏输入、环境变量或 CI 密钥管理提供 AccessKeySecret。
- 多企业操作前检查当前 Profile，防止将资源写入错误企业。
- 自动化程序应同时判断进程退出码及 JSON 输出中的 `ok` 和 `error.code`。
