# 天天基金 ttskill CLI 安装指南

本文档用于正式环境，帮助 Agent 在用户电脑上安装并启用天天基金 `ttskill` CLI 基础能力。

`ttskill` 是 CLI 登录型 Skill 的本地基础包，负责基础包安装、业务 Skill 包同步、扫码登录、本机签名调用等通用能力。当前正式环境可用业务包以业务 Skill 包列表接口返回为准。

## 使用边界

- 不需要配置 `TTFUND_APIKEY`。
- 不要使用 `X-API-Key` 调用 CLI 登录型能力。
- 用户只需要完成扫码或确认授权。
- Agent 应主动安装基础包、写入长期可见 `ttskill` 入口、同步业务 Skill 包、刷新路由内容，并在需要时主动拉起 `ttskill login`。
- 当前正式环境业务包主要是账户查询、持仓查询等授权查询能力，不包含交易能力。

## 1. 判断平台和架构

请按当前电脑系统自动判断参数：

| 系统 | platform | arch |
| --- | --- | --- |
| Windows x64 | `win32` | `x64` |
| macOS Apple Silicon | `darwin` | `arm64` |
| macOS Intel | `darwin` | `x64` |
| Linux x64 | `linux` | `x64` |

## 2. 安装 ttskill 基础包

如果本机还没有 `ttskill`，请调用正式环境基础包解析接口获取最新安装包：

```text
https://skills.tiantianfunds.com/ai-smart-skill-service/openapi/base-package/resolve?platform=<platform>&arch=<arch>&env=prod
```

读取响应中的：

```text
data.download_url
```

下载并安装基础包。

## 3. 写入 Agent 长期可见 ttskill 入口

基础包安装完成后，Agent 应执行：

```bash
ttskill agent-entry bootstrap --env prod
```

将命令输出的 Markdown 写入当前 Agent 的长期可见 Skill 目录。该入口用于新对话识别 `ttskill`，并引导 Agent 通过 `ttskill agent-entry show` 读取由 `ttskill-cli` 自动维护的最新路由内容。

该入口只作为稳定引导，不写死具体分类和业务包路径。

## 4. 同步业务 Skill 包

基础包安装完成后，请调用正式环境业务 Skill 包列表接口：

```text
https://skills.tiantianfunds.com/ai-smart-skill-service/openapi/skill-package/list?env=prod
```

读取响应中的：

```text
data.items
```

```text
item.urls.download
```

安装或更新业务 Skill 包。

全部业务 Skill 包安装或更新完成后，必须确保：

```bash
ttskill skill list --json
```

能够看到已安装或更新后的业务 Skill 包。

## 5. 刷新 ttskill 路由

业务 Skill 包全部安装或更新完成后，Agent 应执行：

```bash
ttskill agent-entry refresh --env prod
```

该命令会读取最新分类路由映射和本机已安装业务 Skill 包信息，生成或刷新由 `ttskill-cli` 维护的路由内容。

如需查看路由内容，执行：

```bash
ttskill agent-entry show
```

分类只用于理解和路由，不是可调用 Skill；最终必须选择具体原子 `skill_id`。不要把分类名称当作 Skill 调用，也不要把业务包本体复制到 Agent 目录。

## 6. 登录授权

业务包安装完成后，请主动执行：

```bash
ttskill login
```

由用户在打开的页面里扫码或确认授权。不要只提示用户“自行登录”，应由 Agent 主动拉起登录流程。

## 7. 调用方式

登录完成后，CLI 登录型能力请使用：

```bash
ttskill invoke
```

发起 CLI 登录态调用。

调用时请求体必须包含：

```json
{
  "skill_id": "业务 Skill ID",
  "_skill_version": "当前安装版本"
}
```

## 8. 异常处理

- 如果本机没有 `ttskill`：先安装基础包。
- 如果业务包不存在或版本落后：重新调用业务 Skill 包列表接口并安装更新。
- 如果长期可见 `ttskill` 入口缺失：重新执行 `ttskill agent-entry bootstrap --env prod`，并将输出写入当前 Agent 的长期可见 Skill 目录。
- 如果路由内容缺失或过期：重新执行 `ttskill agent-entry refresh --env prod`。
- 如果返回 `cli_login_required`、登录态失效或 token 失效：主动重新执行 `ttskill login`。
- 如果用户未完成扫码授权：停在可恢复位置，等待用户完成授权。