toko

AI agent 初始化與內建 skill

把一段 prompt 貼給 AI agent(例如 Claude Code、Codex),它就會安裝 toko CLI,並學會用 CLI 查訂單、跑報表或協助串接。

什麼時候用

  • 想用自然語言請 agent 查資料,例如「整理這週待付款的訂單」。
  • 工程師要請 agent 寫串接程式或架自建官網。

agent 以你的員工帳號操作,能做的事不會超過你的角色權限。

事前準備

  • 公司已開通「API 與自動化」模組。到後台 →「公司設定」→「方案模組」確認。自建前台另需「自建前台」模組。
  • 你有後台員工帳號,並已綁定兩步驟驗證。
  • 執行 agent 的電腦能安裝 Node.js 22 以上。

初始化 prompt

在要使用 toko 的專案目錄開啟 agent,貼上:

text
請在目前專案初始化 toko CLI 與內建 agent skill。

1. 檢查 Node.js,需為 22 以上。沿用專案指定的 CLI 版本與套件管理工具。
   若沒有固定版本,使用 npm i -g @toko-cloud/cli 安裝或更新正式版 CLI。
   若有固定版本,使用 npm i -g @toko-cloud/cli@<固定版本>。
   若缺少 Node.js,先依目前環境可用的方式安裝。需要人工權限時,說明具體限制。
2. 執行 toko --version 與 toko skill install --json。
   確認專案的 .agents/skills/toko/SKILL.md 與 .claude/skills/toko/SKILL.md 都已建立。
   兩份入口都指向 CLI 內建指引。
   如果已有使用者自訂的同名 skill,保留內容並回報衝突。
3. 執行 toko skill show,依任務讀取 tenant、staff-api 或 storefront 主題。
   確認 skill 入口與指令都可使用,再回報 CLI 版本、入口位置及驗證結果。
4. 若我已提供租戶網址,設定對應 target;正式環境加 --production。
   執行 whoami 確認身分。需要登入時,執行 login --no-browser,提供核准網址與驗證碼,等待我核准。
   沒有租戶網址時,先完成工具初始化。不要猜測租戶或索取密碼與 token。

先完成初始化。依我後續的任務範圍執行操作,不額外修改正式資料。

agent 要登入時,會給你一個核准網址與驗證碼。用後台員工帳號在瀏覽器開啟網址,重新驗證身分後按「授權」。核准過的登入可以在後台 →「公司設定」→「開發者」→「CLI 登入」查看與撤銷。

三種使用情境

任務agent 讀的指引主題參考
查訂單、出團、報表與營運操作tenantCLI 參考、營運自動化
員工 API 串接與無人值守服務staff-api員工 API、OpenAPI
自建官網、行程與日誌展示storefront自建前台、前台 OpenAPI

可以這樣交辦:

  • 「使用 toko skill,查詢待付款的訂單,整理筆數與待追蹤項目。」
  • 「依員工 OpenAPI 建立唯讀訂單同步服務,先使用假資料驗證。」
  • 「依前台 OpenAPI 顯示行程與梯次,將報名按鈕連到報名網址。」

Skill 如何保持更新

skill 的完整內容跟著 CLI 一起發版。專案裡只放兩份精簡入口,入口叫 agent 去讀目前 CLI 版本的指引。更新 CLI 後,指引自動跟著更新;固定版本的專案則沿用該版本的指引。

›skill 入口的建立與指令

專案會建立 .agents/skills/toko/SKILL.md 與 .claude/skills/toko/SKILL.md。兩份入口都讓 agent 執行 toko skill show 讀取目前 CLI 的內容,例如 toko skill show --topic tenant。

  • 互動執行一般命令成功後,CLI 會檢查兩份入口。缺少時建立,由 CLI 管理的舊入口則更新。
  • 一處衝突或無法寫入時,另一處仍會獨立處理。明確安裝若有任何失敗,回傳非零 exit code。
  • 既有自訂內容與符號連結會保留,並提示處理。JSON、CI 與輸出轉向模式不會自動寫入專案。
  • 入口中的 toko-managed-skill 註記代表由 CLI 管理。要自行維護入口,移除這項註記,CLI 就會保留自訂內容。
  • 自動建立失敗不影響原命令。可用下列指令明確建立:
bash
toko skill install --json
toko skill install --project /path/to/project --json

CLI 優先使用目前目錄所屬的 Git 專案;沒有 Git 專案時,使用目前目錄。在家目錄或檔案系統根目錄時,用 --project 指定位置。建立後,重新載入 agent 的 skill 清單。

問題回報與功能需求

CLI 可以幫你開一則 GitHub issue,回報問題或提出功能需求。回報公開在 cli-feedback,GitHub 帳號名稱會公開顯示,不是匿名回報。

  • CLI 先顯示草稿,你確認後才開啟 GitHub,再補充內容並送出。
  • 自動附帶的資料只有 CLI 版本、作業系統、命令名稱、HTTP 狀態與錯誤分類。不附帶參數值、公司設定、憑證或請求內容。
  • 補充重現步驟時用假資料,不要貼真實個資、公司網址或未檢查的 log。
›回報指令與自動提示
bash
toko feedback bug
toko feedback feature
toko feedback bug --no-browser
toko feedback feature --json
  • bug 範本自動加上 bug label,功能需求範本自動加上 enhancement label。
  • 互動模式遇到 HTTP 5xx 或 TypeError、RangeError、SyntaxError 時,會提供 bug 草稿。一般參數、登入與權限錯誤不自動詢問。
  • 取消或回報失敗都保留原命令的錯誤與 exit code。
  • --no-browser、--json、CI 與非互動模式只輸出草稿,不開啟瀏覽器。草稿的 status: "draft" 不代表已建立 issue。

檢查新版

CLI 每天最多自動檢查一次新版,有新版時只提醒,不會自動升級。固定版本的自動化流程,請先驗證新版再調整版本。

›版本檢查指令與規則
bash
toko version check --json
toko version check --channel latest --json
  • 互動終端的自動檢查最多等待一秒,失敗時不影響原命令,提醒只寫到 stderr。
  • JSON、CI、輸出轉向、help、skill、feedback 與版本查詢命令不觸發自動檢查。
  • 手動查詢最多等待五秒,不需要 target 或登入。正式版省略 --channel 時查詢 latest 通道。
  • 結果包含目前版本、通道版本、updateAvailable、runCommand 與全域安裝用的 updateCommand。
  • 檢查只讀公開 npm 資料。

相關指南

Command Palette

Search for a command to run...