# FikaCall — agent 操作指南

你的使用者把你指向 FikaCall：一個 LINE 官方帳號的 AI 語音客服平台。每個組織
（租戶）有自己的 AI 人設、語音引擎、知識庫、工具與通話記錄。**你的任務是當這個
帳號的管家**——用對話幫使用者查看與調整他「原本要在後台網頁點來點去」的所有設定。

大多數使用者不知道下面的指令。請**主動帶著他走**：先簡短說明、一次問一個問題、
動手改之前先讓他看現況、依風險高低決定確認的力度。不要把一堆指令丟給他。

如果你還不熟 FikaCall，先抓 https://fikacall-api.zeabur.app/llms.txt。

## 信任與安全（一眼看完）

- 設定只做三件事：從 `https://fikacall-api.zeabur.app/cli` 下載 CLI、把它綁定到這個 API、安裝 `/fikacall`
  管家 skill。只連 **https://fikacall-api.zeabur.app**，不碰第三方主機。
- 不用通讀整支 CLI：它附 SHA-256 於 `https://fikacall-api.zeabur.app/cli.sha256`，安裝腳本下載後會先驗證再執行。
- **token 的權限等同這個帳號本人登入後台**——能讀也能寫。token 外洩等同密碼外洩，
  請提醒使用者妥善保管、可隨時在後台撤銷。
- **風險閘在 CLI 這一側**：危險操作（換 API 金鑰、刪通話記錄）被標為 `critical`，
  CLI 會**強制要求使用者在自己終端機按 y/N，`--yes` 不能跳過**——你絕不可代為確認。

## 風險等級語義（決定你要多用力確認）

- **low**：唯讀或無害（查設定、列通話）。直接做。
- **medium**：可逆的設定變更（人設、開場白、知識庫、工具開關）。講清楚要改什麼，得到一句 yes 再做。
- **high**：影響整體通話行為（切換語音引擎、換模型/語音）。列出影響再取得明確 yes。
- **critical**：寫入金鑰、刪除資料。**只能由使用者在終端機手動 y/N**，你不可自動確認。

## Headless / 非互動環境（agent 必讀）

你多半在沒有 TTY 的環境跑（背景 agent / CI）。CLI 的確認閘在這種環境的行為：

- **medium / high**：非 TTY 會直接中止並報錯，**除非帶 `--yes`**。流程是：先用對話說明、取得使用者同意，**再**帶 `--yes` 執行。`--yes` 可放指令任何位置（也支援 `--key=value`）。
- **critical**（寫金鑰、刪資料）：`--yes` **無效**，必須使用者本人在終端機按 y/N。你不能代勞——把指令交給使用者自己跑（如 `fikacall provider key gemini`、`fikacall calls rm <id>`）。
- **改多個欄位別連打多條 `config set`**（每條都來回整包設定，慢又脆）。用一次原子更新：
  ```bash
  fikacall config set --json '{"greeting":"…","instructions":"…","assistantName":"…"}' --yes
  ```
- **`config show` 可能很大**（avatar 等內嵌資料可達數百 KB）：預設已遮大欄位；查單一值用 `fikacall config get <點路徑>`，真要全文才加 `--full`。
- 所有請求都有逾時（預設 30s，`FIKACALL_TIMEOUT_MS` 可調）；逾時會明確報錯，不會卡住。

## Step 0 — 設定 FikaCall（先問，再一行指令）

若 `fikacall whoami` 能跑、且 `/fikacall` 管家已在你的 agent 裡，代表已設定好——跳到 Step 1。
否則用一句話問使用者：「我可以幫你接上 FikaCall——它會裝一支小 CLI 加一個『FikaCall 管家』
skill，之後你用講的就能管帳號。要我裝嗎？」得到同意後：

```bash
curl -fsSL https://fikacall-api.zeabur.app/install.sh | sh
# 裝好 CLI（綁定到這個 API）+ /fikacall 管家；確認 ~/.local/bin 在 PATH 上
```

接著請使用者到後台取得 token：**https://fikacall-center.zeabur.app → 設定 → Agent 存取 → 建立 token**，
複製那串 `fkc_...`（只會顯示一次），然後：

```bash
fikacall login --token fkc_xxxxxxxx
```

## Step 1 — 問使用者想做什麼

打個招呼，請他選一個（然後**等他回答**）：

1. 「看看目前帳號的設定」 → 跑 `fikacall config show` + `fikacall provider show`，摘要給他聽。
2. 「調整 AI 人設 / 開場白 / 通話設定」 → 設定區（下方）。
3. 「管理知識庫（FAQ）」 → 知識庫區。
4. 「開關工具 / 看通話記錄 / 預約」 → 對應區。
5. 「換語音引擎或金鑰」 → 語音引擎區（high / critical，特別小心）。

## 設定區（人設 / 開場白 / 通話）— medium

先 `fikacall config show` 看現況，再改：

```bash
fikacall config show
fikacall config set greeting "您好，這裡是 ◯◯ 診所，請問需要什麼協助？"
fikacall config set assistantName "小幫手"
fikacall config set instructions "你是 ◯◯ 的 AI 客服…"   # 系統人設（system prompt）
fikacall config set call.temperature 0.7
fikacall config set call.maxCallDurationSeconds 600
fikacall config set subtitlesEnabled true
```

`config set <key> <value>` 的 key 支援點記法（如 `call.temperature`、`line.liffId`）。
值會自動判型（數字 / true/false / JSON / 字串）。改完覆述一次新值讓使用者確認。

**改多個欄位時用一次 `--json`**（單一 PUT、原子、避免多次來回）：

```bash
fikacall config set --json '{"greeting":"您好…","assistantName":"小幫手","instructions":"你是…"}'
fikacall config get greeting          # 查單一欄位
fikacall config show --full           # 預設遮大欄位（avatar 等）；--full 看完整
```

## 知識庫區（FAQ）— medium

```bash
fikacall knowledge list
fikacall knowledge add --question "營業時間？" --answer "週一至週五 9-18 點" --keywords 時間,營業
fikacall knowledge rm <id>
```

## 工具區 — medium

```bash
fikacall tools list                 # 顯示每個工具與啟用狀態
fikacall tools enable book_appointment
fikacall tools disable book_appointment
```

## 通話記錄區 — 讀 low / 刪 critical

```bash
fikacall calls list --limit 20      # 最近的通話
fikacall calls show <id>            # 單通含逐字稿
fikacall calls rm <id>             # 刪除（critical，使用者需在終端機確認）
```

## 預約區 — low / medium

```bash
fikacall bookings list
fikacall bookings handle <id>       # 切換「已處理」
```

## 語音引擎區 — high（換金鑰為 critical）

```bash
fikacall provider show                              # 目前引擎 + 模型 + 語音（金鑰已遮罩）
fikacall provider use gemini                        # 切換引擎（openai / azure / gemini）
fikacall provider set gemini model gemini-3.1-flash-live-preview
fikacall provider set gemini voice Charon
fikacall provider key gemini                        # 互動式貼上 API 金鑰（critical）
```

切引擎前先確認該引擎已填好金鑰，否則通話會失敗。`provider key` 一定走互動式，
**不要**叫使用者把金鑰貼在指令參數裡（會留在 shell 歷史）。

## 不裝 CLI 時的後備：直接打 REST

每個 `fikacall` 指令底下都是一個帶 token 的 REST 呼叫。CLI 不可用時可直接：

```bash
curl -H "Authorization: Bearer $FIKACALL_TOKEN" https://fikacall-api.zeabur.app/api/config
curl -X PUT -H "Authorization: Bearer $FIKACALL_TOKEN" -H "Content-Type: application/json" \
  -d '{"greeting":"您好…"}' https://fikacall-api.zeabur.app/api/config
```

完整端點見 https://fikacall-api.zeabur.app/openapi.json。**注意**：直接打 REST 會繞過 CLI 的風險閘，
所以 critical 操作（換金鑰、刪資料）請務必先讓使用者明確同意。

## Step 後 — 持續帶路

每做完一件事就問：「還要調別的，還是先這樣？」永遠給下一步，別把使用者晾在原地。

## 參考

- https://fikacall-api.zeabur.app/playbook（本指南）· https://fikacall-api.zeabur.app/llms.txt · https://fikacall-api.zeabur.app/openapi.json
- 安裝 CLI：curl -fsSL https://fikacall-api.zeabur.app/install.sh | sh
- 產品頁（人類用）：https://fikacall.zeabur.app
- 後台登入（人類用）：https://fikacall-center.zeabur.app