智能体平台 CLI 使用指引

**智能体平台 CLI**（包名 tinet-agent-cli，命令 taco）是天润智能体平台的命令行编排层。

它让人类开发者，以及 **Cursor、Codex** 等 AI Agent，通过稳定、可机器解析的命令完成：

本页重点说明：**如何把智能体平台 CLI 集成到 AI Agent 工具中使用**。

使用中遇到任何问题，可通过 **智能体平台 CLI 使用问题反馈** 提交反馈。

---

1. 它解决什么问题？

在 AI 编程助手（Cursor、Codex 等）里，如果直接让模型「猜」平台 API，容易出现：

智能体平台 CLI 提供一层 **稳定的命令契约 + Skill 指引**，让 Agent：

1. 先发现当前平台支持的命令与场景 2. 按 schema 编辑本地 DSL 3. 用 --json --no-input 获得结构化输出，便于自动分支 4. 写操作通过 --yes 与用户二次确认后再执行

你可以把它理解为：**智能体平台的「官方 Agent 适配层」**。

---

2. 安装

2.1 配置公司内部 PyPI

参考：阿里云 PyPI 制品库使用指南

按文档配置 pip 的 index 与认证后，即可从内部源安装。

2.2 安装 CLI

pip3 install tinet-agent-cli

推荐使用 pipx 或独立虚拟环境，避免与系统 Python 包冲突。

2.3 确认安装成功

taco --version

若版本过低，后续连接平台时会提示执行 taco upgrade。

---

3. 首次登录

1. 浏览器访问 **智能体平台**，登录到**目标租户** 2. 打开开发者工具 **Console**，复制自动打印的 taco auth connect 命令 3. 在终端执行该命令，完成 CLI 与当前企业的绑定

验证当前登录企业：

taco auth status

输出中包含 **企业 ID**、**企业名称**、服务地址等信息。Agent 在开始任务前应先确认这些信息，避免在错误租户下操作。

---

4. 集成到 Cursor、Codex 中

4.1 安装 Skill

Skill 会告诉 Agent **何时、如何调用智能体平台 CLI**，避免即兴编造命令或参数。

# 安装到 Cursor
taco skills install --agent cursor --yes

# 安装到 Codex
taco skills install --agent codex --yes

安装后可检查：

taco skills status --agent cursor
taco skills status --agent codex

4.2 Agent 调用约定

集成到 Cursor / Codex 时，建议 Agent 遵循以下约定：

约定说明
发现优先任务开始前执行 `taco help -o json`，按场景读取 schema，不凭记忆拼命令
机器可读业务命令加 `--json --no-input`；成功结果读 stdout，失败读 stderr
错误分支根据 `error.code` 判断，不依赖中文 message 文本
不写 API优先通过 CLI 操作平台，不要绕过 CLI 直接调 HTTP
凭据安全refresh token、Provider 凭据、Workflow secret 不得写入对话、DSL 或 shell 参数

4.3 在 Cursor / Codex 中的典型协作方式

1. **确认租户**：先执行 taco auth status，向用户展示当前 **企业 ID / 企业名称** 2. **发现能力**：按 Skill 指引读取 scenario、schema、example 3. **本地编辑**：Agent 只改本地 DSL 文件，不手写服务端 ID 4. **调试运行**：用 agent run / workflow run 等只读或调试类命令验证 5. **写操作**：见下一节「关键环节二次确认」

---

5. 切换租户（运营交付）

> **不支持同时维护多个 profile。** CLI 本地只保存**一套**当前授权；切换租户时必须**重新授权**。

服务不同租户时的标准流程：

1. 浏览器重新访问智能体平台，**退出并登录到目标租户** 2. Console 复制新的 taco auth connect 命令，在终端**重新执行**（覆盖当前授权） 3. 执行 taco auth status，确认 **企业 ID / 企业名称** 已变为目标租户 4. 再让 Cursor / Codex 继续后续任务

**切勿**在未切换授权的情况下，对另一个租户执行发布、凭据写入等操作。

---

6. 关键环节：二次确认

发布应用、写入凭据、发布 Workflow 等**会改变平台状态**的操作，CLI 要求显式传入 --yes。 Agent **不得**自行添加 --yes，必须先向使用方二次确认。

6.1 确认时必须展示的信息

发起确认时，Agent 应向用户展示至少以下信息：

信息获取方式
企业 ID`taco auth status` → `enterprise_id`
企业名称`taco auth status` → `enterprise_name`
操作类型如「发布 Agent」「发布 Workflow」「写入 Provider 凭据」
操作对象如 app 名称 / app-id、Workflow 名称、Provider 名称
影响说明如「将覆盖线上配置」「将写入租户共享凭据」

示例确认话术：

> 即将在 **企业 8001678（8001678）** 下发布 Agent「客服助手」（app-id: xxx），此操作会更新线上配置。是否继续？

用户明确同意后，Agent 再在命令末尾加 --yes 执行。

6.2 需要二次确认的典型操作

操作命令示例说明
发布 Agent`taco agent publish --yes`更新线上 Agent 配置
发布 Workflow`taco workflow publish --yes`更新线上 Workflow
发布 Workflow Tool`taco workflow tool publish ... --yes`注册/更新工具
创建远端资源`taco agent create ... --yes`在平台新建应用
写入凭据`taco credential set ... --yes`写入租户共享凭据
写入 Secret`taco workflow secret set ... --yes`写入 Workflow 密钥

6.3 Agent 禁止事项

---

7. 版本升级

连接平台时若提示 CLI 版本过低：

taco upgrade

或由 Agent 在用户确认后代为执行。

---

8. 进一步阅读