Hinto CLI 技能
此技能涵蓋所有 Hinto 終端機工作流程：安裝、認證、每個命令群組、非同步任務處理以及命令串接。
安裝
此技能驅動 hinto CLI。
套件名稱： 命令是
hinto，但 npm 套件是@hintoai/cli。 請勿猜測@hinto/cli或hinto——這些套件不存在，會回傳 404。 一律安裝、升級和參考套件為@hintoai/cli。
在執行任何命令前，請確認 CLI 已安裝——如果 hinto 不在 PATH 中，請先安裝：
# 全域安裝 CLI
npm install -g @hintoai/cli
# 驗證
hinto --version
若要升級至最新版本，請執行：
npm install -g @hintoai/cli@latest
然後進行認證（請參閱下方）。如果 hinto 命令因「找不到命令」而失敗，請重新執行上述安裝步驟。
安裝此技能本身（適用於任何代理程式）是透過通用技能 CLI 完成的：
npx skills add hintoai/hinto-cli
認證
如何取得 API 金鑰
API 金鑰是每個專案（而非整個帳戶）——每個金鑰僅限於一個專案，而 CLI 會根據金鑰所屬的專案執行操作。若要建立：
- 在 Hinto 應用程式 (
https://app.hintoai.com) 中開啟專案。 - 按一下 設定（頂端列）以開啟專案設定。
- 前往 API 金鑰與 Webhook → API 金鑰 標籤。
- 按一下 新增 API 金鑰 並複製產生的金鑰。
設定金鑰
優先使用環境變數——它適用於 CI 並會覆蓋設定檔：
export HINTO_API_KEY=hinto_...
對於互動式/本機使用，請執行 init 一次：
hinto init --key hinto_...
# 寫入 ~/.hinto/config.json — 權限 600
若要指定測試版或自託管執行個體，請使用 --api-url：
hinto init --key hinto_... --api-url https://staging.hintoai.com
# 或每個指令使用：
hinto articles list --api-url https://staging.hintoai.com
全域旗標
這些旗標適用於每個命令：
| 旗標 | 用途 |
|---|---|
--json | 輸出原始 JSON 到 stdout——在串接命令或剖析輸出時使用 |
--api-url <url> | 覆蓋基礎 URL（測試版、自託管） |
工作風格
當此技能啟用時：
- 透過 Bash 執行命令——直接執行
hinto命令，而非僅描述它們。 - 串接時使用
--json——透過管道傳遞或剖析 JSON 輸出，以提供給下一個命令。 - 對非同步任務使用
--wait——僅generate start和generate structure支援。不使用--wait時，這些命令會立即回傳一個jobId。publish now、publish republish和project retranslate一律是非同步的（沒有--wait）——請手動輪詢：hinto generate status <jobId>。 - 先檢查認證——如果命令回傳
UNAUTHORIZED，請驗證是否已設定HINTO_API_KEY或是否已執行hinto init。 - 旋轉動畫會輸出到 stderr——即使使用
--wait，stdout 仍保持乾淨以供透過管道傳遞。
互動模式：
- 詢問 vs. 自動——只有當有真正的選擇（2 個以上選項）時，才提示使用者。對於 0–1 個選項，直接繼續進行並說明使用了什麼。
- 確認破壞性動作——在
articles delete和publish unpublish之前，請與使用者確認，並清楚說明將移除或離線的內容。切勿進行試探性執行。 - 輸出規範——結束每項任務時提供：執行的命令 + 結果、任何非同步工作（未等候）的
jobId、連結（如有editUrl/previewUrl），以及下一個驗證步驟。
導航 — 從這裡開始
先執行這些命令，以掌握金鑰目標專案的基本資訊（金鑰是每個專案——你只操作一個）：
hinto project get --json # 名稱、類型、是否已發佈、自訂網域
hinto project structure --json # 資料夾 + 文章樹狀結構
hinto publish status --json # 是否已上線，以及網址為何
如果結果不符合使用者預期，表示金鑰很可能目標是另一個專案——使用者必須提供正確的金鑰；你無法切換專案。
範圍
每個 API 金鑰都附帶範圍。當缺少範圍時，操作會失敗並回傳 INSUFFICIENT_SCOPE (403)：
| 範圍 | 允許的操作 |
|---|---|
read | 取得 / 列出 / 狀態 / 結構 / 語言 / 版本 / 翻譯 |
write | 建立 / 更新 / 刪除 / 移動 / 複製 / 還原 / 新增語言 |
generate | 開始產生 / 結構、重新產生、重新翻譯、觸發翻譯 |
publish | 立即發佈 / 重新發佈 / 取消發佈 |
復原：告訴使用者缺少哪個範圍——必須在應用程式 UI 中建立具有該範圍的新金鑰。
ID 與狀態注意事項
- 文章和資料夾 ID 是整數；任務 ID 是 uuid。
slug和previewUrl在發佈之前為 null（對於不在目前發佈快照中的文章也是如此）。- 影片必須**
ready** 才能執行generate start/generate structure。 generate structure會產生空的預留文章，而非完整文章——請參閱references/product-behavior.md。- 速率限制：每金鑰每分鐘 60 個請求（
RATE_LIMITED429 → 等待Retry-After）。產生可能會回傳QUOTA_EXCEEDED。
CLI 無法做到的事（僅限應用程式 UI）
請勿為這些功能發明命令——它們位於 Hinto 網頁應用程式中：
- 建立專案或 API 金鑰
- 工作區 / 帳務管理
- 品牌設定以及未由已記錄命令公開的發佈設定編輯
核心工作流程：上傳 → 產生 → 發佈
# 1. 上傳本機影片檔案
hinto videos upload --file ./video.mp4 --json
# → { "videoId": "..." }
# 或從 URL 匯入（回傳一個 Job 物件 — 輪詢直到完成以取得 videoId）
hinto videos import --url https://example.com/video.mp4 --json
# → { "jobId": "...", "type": "import_video_url", "status": "pending", "output": null, ... }
# 然後輪詢：hinto generate status <jobId> — 完成的 output 包含 videoId
# 2. 等待影片準備就緒
hinto videos status <videoId> --json
# → { "videoId": "...", "status": "ready", ... }
# 3. 列出可用的範本
hinto templates article --json
# 4. 產生文章並等待完成
hinto generate start --video <videoId> --template <templateId> --wait --json
# 4b. 提供使用者新文章的連結（editUrl 始終存在；發佈後才有 previewUrl）
hinto articles get <articleId> --json # → 包含 editUrl + previewUrl
# 5. 發佈專案（非同步 — 立即回傳 jobId）
hinto publish now --json
# → { "jobId": "...", "type": "publish", "status": "pending", ... }
# 輪詢：hinto generate status <jobId>
分類路由
針對相關的命令群組，請閱讀參考檔案：
| 任務 | 參考檔案 |
|---|---|
| 上傳、匯入、管理影片 | references/videos.md |
| 建立、編輯、移動、翻譯文章 | references/articles.md |
| 建立和組織資料夾 | references/folders.md |
| 從影片產生文章或結構 | references/generate.md |
| 專案資訊、結構樹、語言 | references/project.md |
| 發佈、重新發佈、取消發佈 | references/publish.md |
| 瀏覽可用的範本 | references/templates.md |
| 匯出文章、資料夾或整個專案 | references/export.md |
| 將影片轉換為內容（單篇文章 vs. 結構） | references/content-from-video.md |
| 常見任務食譜（上傳→產生→發佈、編輯→重新發佈、新增圖片） | references/recipes.md |
| 產品行為（版本控制/還原、預留文章/自動產生、圖片、翻譯） | references/product-behavior.md |
輸出檢查清單
提供給使用者：
- 執行的命令及其輸出
- 如果操作是非同步且未使用
--wait，則提供jobId - 下一個驗證步驟（例如
hinto videos status <id>、hinto generate status <jobId>） - 任何影響結果的範圍或認證注意事項