CLI Skill 使用指南
NadouPro CLI 功能介紹
本文面向使用 NadouPro CLI 的用戶和 Agent，介紹安裝、登入、模型發現、內容生成、任務交付、空間管理、本機媒體處理與 Canvas 操作。CLI 的具體能力會隨版本、帳號和場景變化，請以 nadou capability list --json、命令回傳結果和實際產物為準。
建議
安裝或升級後先執行 nadou version --json 和 nadou capability list --json，確認當前版本與可用能力。
注意
涉及寫入、生成、刪除或覆蓋的操作，遵循「一次提交、不自動重試、結果不確定時查詢原任務」的原則。不要分享或記錄 Cookie、token、Authorization 等登入憑證。
1. 快速開始
1.1 安裝
需要 Node.js 16 或更高版本。建議透過 npm 公共倉庫安裝：
一句話安裝指令：請幫我安裝 NadouPro CLI：npm install -g @iqiyi-intl-nadoupro/nadou-cli。安裝完成後可執行 nadou version --json 驗證。
npm exec --yes --registry=https://registry.npmjs.org/ --package=@iqiyi-intl-nadoupro/nadou-cli@latest -- nadou-install
nadou version --json
nadou skill install --json
nadou skill read --json也可以全域安裝：
npm install -g @iqiyi-intl-nadoupro/nadou-cli
nadou version --json目前支援 Windows x64、Linux x64/arm64、macOS x64/arm64。npm 會自動選擇對應平台的相依套件；如果安裝時關閉了 optional dependencies，請使用正常安裝方式重新安裝。
1.2 檢查更新並升級
nadou version --check --json
nadou update --json --no-interactive
nadou version --json升級完成後建議再次執行 nadou skill install --json，確保本機 Skill 與 CLI 版本保持一致。
1.3 設定並登入
登入會開啟系統瀏覽器中的國際版登入頁。點擊「Continue to international sign in」，再按頁面提供的方式完成國際站帳號登入。Profile 用於儲存空間、逾時等非敏感設定，登入工作階段儲存在本機系統憑證庫；國際版的本機設定和登入工作階段分別儲存，安裝國際版後需檢查國際版登入狀態。
nadou auth login --profile <profile>
nadou auth status --profile <profile> --json
nadou auth whoami --profile <profile> --json請將 <profile> 替換為本機實際使用的 Profile 名稱；如果使用預設 Profile，可按 CLI 提示省略該參數。不要手工複製、貼上或記錄 Cookie、token 和 Authorization。
伺服器模式登入
伺服器、容器或無圖形介面的環境可能無法開啟本機瀏覽器，也可能無法存取作業系統憑證庫。遇到此類環境時，使用獨立的伺服器模式登入：
nadou auth login --server --profile <profile>
nadou auth status --profile <profile> --json
nadou auth whoami --profile <profile> --jsonCLI 會在終端機輸出登入網址和驗證碼，並預設等待 10 分鐘。使用者可在任意裝置的瀏覽器中輸入驗證碼，完成登入並確認帳號；登入頁面也支援切換帳號。
此模式使用 CLI 私有檔案儲存憑證，讓不同 CLI 程序可以共用登入狀態。狀態目錄未持久保存時，容器銷毀後需要重新登入。此行為僅適用於明確指定 --server 的登入，其他登入方式仍使用系統憑證庫。
1.4 Agent 使用前檢查
Agent 工作階段與普通終端機可能使用不同的 PATH、設定目錄或系統憑證庫。遇到「命令找不到」「設定不可讀」或「身分校驗失敗」時，先重啟 Agent，再執行：
nadou version --jsonnadou auth status --profile <profile> --jsonnadou auth whoami --profile <profile> --json
只有確認登入狀態確實失效時，才重新登入。
如果傳回 CREDENTIAL_STORE_UNAVAILABLE，且目前伺服器或容器無法提供系統憑證庫，不要重複執行預設登入；應改用：
nadou auth login --server --profile <profile>2. 能力總覽與統一約定
2.1 命令面
| 能力域 | 主要命令 | 作用 |
|---|---|---|
| 系統與 Skill | version、update、config、doctor、skill、capability | 版本、設定、診斷、Skill 同步和能力發現 |
| 身分與空間 | auth、points、space | 登入、積分、空間、目錄和交付目標 |
| 模型與生成 | model、text、image、video、material | 模型發現、文字/圖片/影片任務和素材管理 |
| 任務與交付 | task、schedule、evidence | 估價、提交、觀察、下載、定時、報告和驗收證據 |
| Canvas | canvas | 畫布、Graph、節點、連線、Timeline 和成片匯出 |
| 本機媒體 | media | 處理本機檔案，不替代伺服器端生成任務 |
完整命令和當前開放範圍以 nadou capability list --json 為準；單項能力可用 nadou capability describe <command> --json 查看作用、限制、非同步性和參考命令。
2.2 輸出與全域參數
所有命令支援穩定的 --json 輸出；長時間觀察、事件流和遞迴目錄內容可使用 --jsonl。常用全域參數包括 --profile、--timeout、--trace-id、--no-interactive 和 --yes。
--json：回傳適合程式處理的結構化結果。--jsonl：按行輸出事件或遞迴結果，便於持續觀察。--no-interactive：關閉互動提示，不代表費用確認。--yes：確認刪除、覆蓋等破壞性操作，不代表費用授權。--trace-id：用於關聯一次工作流的排查資訊，不等同於任務 ID 或冪等鍵。
2.3 Profile、空間與專案邊界
Profile 儲存環境、閘道位址、逾時、認證模式、預設空間和預設模型等非敏感設定。空間、模型和 Canvas 上下文需要分別發現和選擇；切換空間不會隱式建立或還原其他專案綁定。
2.4 場景路由
| 場景 | 建議承載 | 執行要點 |
|---|---|---|
| 單個文字、圖片、影片或其他原子能力 | 原子任務 | 提交前確認參數、目標空間、權限和預計消耗。 |
| 多個素材、多個階段、角色一致性、MV、廣告或短片 | 目標空間/目錄 + Canvas | 先明確帳號、空間和目錄；完成劇本或分鏡後再進入高成本階段。 |
| 修改已有 Canvas | 讀取並修改原 Canvas | 寫入前讀取即時畫布，寫入後回讀複驗；覆蓋、刪除或衝突時先確認。 |
| 定時生成 | CLI 當前開放的定時模式 | 建立前確認時間、時區、帳號、空間和預計消耗。 |
用戶明確提到 NadouPro、文字、圖片、影片、素材、空間、畫布、節點、參考圖、首尾幀等場景時，優先使用納逗 Skill。當前 CLI 不支援的能力應明確說明，不要用相似能力代替。
3. 模型發現與內容生成
3.1 先發現模型和場景
nadou model list --type image --json
nadou model list --type video --json
nadou model family "<模型顯示名>" --json
nadou model scenarios "<model-id>" --json
nadou model get <model-id> --json
nadou model schema <model-id> --json
nadou model use image <image-model> --profile <profile>
nadou model use video <video-model> --profile <profile>模型顯示名、參數和可用場景由伺服器端目錄決定。不要在 Agent 或指令碼中猜測模型名；先讀取場景或 Schema，再提交匹配的參數。
3.2 生成能力與場景
| 命令 | 常見場景 | 關鍵輸入 |
|---|---|---|
nadou text | text2text、image_to_text | 提示詞、可選 HTTPS 參考圖 |
nadou image | text2img、image_ref、panorama、three_view、inpaint | 提示詞、參考圖、遮罩、比例、解析度、數量 |
nadou video | text2video、first_last_frame、multi_reference、video_edit、motion_control | 提示詞、時長、比例、解析度、參考影片/圖片/音訊 |
提示詞可透過 --prompt、--prompt-file 或 --stdin 提供，最大 1 MiB 且必須是有效 UTF-8。Agent 使用 --json、--jsonl 或 --no-interactive 時，應顯式指定提示詞來源；完成預覽和費用確認後，正式生成需帶 --submit。位置參數的適用條件以命令說明為準。--dry-run 只構造並校驗請求，不會提交任務；圖片和影片預設只提交不等待，使用 --wait 才會在同一條命令中觀察完成。
當前 CLI 沒有獨立的 AI 音訊生成命令。影片任務可以按場景使用參考音訊、音訊設定或保留原聲參數，但這不等同於獨立音訊生成。
3.3 費用、確認與交付
費用確認
可能產生費用的任務，建議按「dry-run → 查詢積分 → 估價 → 說明預計消耗並確認 → 正式提交」的順序執行。餘額顯示為空、無限或暫時無法確認時，也不能跳過估價、預算說明和最終確認。
對應命令通常為 nadou points summary、nadou task estimate 和 nadou task submit。估價不鎖定最終價格，提交前仍需按實際回傳結果確認。
獨立圖片/影片生成與產物交付是兩個階段。預設交付到個人根目錄；團隊空間、目錄以及複製或轉移策略需要顯式指定。CLI 不預設下載產物，也不預設執行本機媒體處理。
4. 任務、定時、交付與證據
4.1 任務生命週期
常用命令包括 task estimate、task submit、task status、task wait、task events、task outputs、task report、task history、task download、task download-batch 和 task terminate。
task events 可用於持續觀察；批次下載使用可復原的 manifest，適合長任務或多產物交付。提交寫操作不自動重試。行程中斷、網路逾時或回應無法解析時，先查詢原 task、request 或狀態記錄，不要建立新的提交再試。
4.2 定時任務
| 模式 | 適用方式 | 主要限制 |
|---|---|---|
server | 圖片/影片或部分 Canvas 節點生成 | 不承諾通用文字計畫、計畫管理或 DAG 編排。 |
local | 普通圖片/影片和獨立文字生成 | 不包含 Canvas、專案上下文或外部引用 URL。 |
定時能力需要顯式選擇 disabled、local 或 server，並使用 IANA 時區。建立前先確認時間、時區、帳號、空間和預計消耗，再按當前 capability 選擇模式。
範例：nadou schedule create --body-file request.json --scheduled-at <time> --timezone <iana-timezone> --max-points <已確認的積分上限>。具體支援範圍以命令回傳結果為準。
4.3 空間、目錄和素材
space current/list/use：檢視和切換空間。space directory create/list/contents：管理目錄和檢視內容；遞迴內容可使用--recursive --jsonl。space file rename：顯式重新命名檔案。space artifact deliver：將可信任務產物複製或轉移到目標空間或目錄。material upload：上傳本機素材，支援分片流程和可選浮水印參數。material delete：刪除素材；永久刪除需要顯式使用--permanent並確認。
上傳素材不等於交付任務產物，也不會自動建立 Canvas 節點。
4.4 驗收證據
evidence generation 可從已知 task ID 生成版本化本機證據；evidence delivery 可結合下載 manifest、媒體檔案、技術校驗結果和人工確認生成交付證據；evidence validate 只校驗證據結構、路徑、雜湊和引用，不會觸發重試、下載、交付或 Canvas 寫入。
技術校驗通過不等於創意品質審核。正式交付建議保留版本、task ID、脫敏 request ID、產物雜湊、媒體檢查結果和必要的人工確認，不要儲存 token、Cookie 或完整 Authorization。
4.5 Agent 互動、產物呈現與復原
提交前，如果帳號、空間、目錄或 Canvas 不唯一，必須先說明選項和預計儲存位置；如果模型參數、首尾幀角色或批次規模不明確，必須先補齊資訊；涉及批次、高成本、刪除、覆蓋、移動或協同衝突時，必須先說明影響並取得確認。
圖片：說明實際數量，回傳每個真實產物和空間路徑。
影片或其他媒體：回傳真實播放/下載入口和空間路徑；任務頁或縮圖不能代替最終產物。
文字：直接呈現正文；沒有儲存到空間時，明確說明原因。
複雜 Canvas：呈現最終產物、空間路徑、Canvas 名稱和真實入口，並區分已完成與未完成階段。
部分成功：先交付成功項，再分別列出失敗項和補做選項，不把整單偽裝成完全成功或完全失敗。
交付注意事項
空間路徑和真實產物入口是交付資訊的一部分。沒有伺服器端真實回傳值或沒有完成下載時，不要把本機路徑、任務頁或中間狀態稱為最終產物。
每個寫入或提交步驟只執行一次。逾時、網路異常或回應無法解析時，查詢原 task 或原操作狀態；不要更換冪等鍵、重複提交或因為暫時沒有結果而重新生成。生成失敗、版權限制或模型拒絕時，停止下游步驟；用戶取消時只執行一次取消並核對最終狀態。
5. 本機媒體處理
nadou media 只處理本機檔案，不呼叫網路生成服務，不修改輸入檔案，預設拒絕覆蓋已有輸出。支援檢查、標準化、拼接、合成、抽幀、技術校驗、字幕處理以及音訊影片混流等操作。
常用標準預設包括橫屏、直屏和正方形 1080p；常規輸出為 MP4/H.264、yuv420p、30fps、AAC-LC、48kHz、立體聲。verify 是技術檢查，報告中的 creative_review_required 仍表示需要人工審看。
本機媒體處理與 Canvas Timeline/成片匯出是兩套能力：前者處理本機檔案，後者讀寫 Canvas Graph 關聯的時間軸並執行伺服器端成片任務。
6. Canvas 管理與 Graph
6.1 操作原則
先用
canvas get讀取目標畫布的最新狀態。根據當前節點、連線和版面配置構造一次寫入。
寫入完成後再次讀取，確認節點、連線和產物狀態。
遇到鎖定、協同衝突、權限問題或結果不明確時停止繼續寫入，先檢視原操作狀態並說明影響。
CLI 會按節點類型校驗可寫欄位。用戶只需要關注命令、輸入、輸出、狀態和錯誤處理，不需要直接拼接服務位址、資源 URL 或任務狀態。
6.2 常用命令
| 類別 | 命令 |
|---|---|
| 生命週期 | canvas list/create/get/rename/move/delete/restore |
| 讀取 | canvas get、canvas node list、canvas assets list |
| Graph | canvas graph mutate |
| 節點 | canvas node list/create/patch/delete/estimate/generate/wait |
| 連線 | canvas edge connect/patch/delete |
| Timeline | canvas media timeline validate/write/read |
| 成片 | canvas media export prepare/submit/observe |
6.3 畫布、節點與素材
canvas list 用於發現當前可存取的畫布；canvas get 用於讀取即時 Graph；canvas node list 用於按類型檢視節點；canvas assets list 用於檢視歷史素材或產物投影。列表結果不應被當作寫入前的即時快照。
自訂媒體節點應使用公開的 Canvas 節點命令，並以素材 ID 等受支援欄位作為輸入。不要由 CLI 外部偽造 URL、metadata、回呼或任務狀態。畫布衝突、鎖定和部分失敗應按實際錯誤提示處理，不要建立替代節點掩蓋原問題。
6.4 Timeline 與成片
Timeline 檔案先執行離線校驗，再按當前 capability 選擇成片流程。Timeline 寫入、匯出準備、提交和觀察都是相互獨立的操作，每一步只執行一次；狀態查詢遇到處理中、未找到或未知結果時，只繼續查詢原操作，不切換路徑或重複提交。
真實成片是否可完成取決於有效的 Canvas 節點、Timeline、任務狀態和當前開放能力。發布或交付時應以實際命令回傳和最終產物為準。
7. 當前 CLI 的能力邊界
CLI 的開放面可能隨版本、帳號和場景變化。
產品頁面中的完整工作流不一定已透過 CLI 開放，例如導演臺、完整圖片編輯與標註、工作臺檔案管理、剪輯臺、音軌編輯和編劇助手。CLI 已提供 image-tool upscale 等部分圖片處理命令，具體範圍以當前命令說明和實際回傳為準。需要這些能力時，請直接使用產品入口，並以產品頁面和 CLI 當前 capability 為準。
8. 問題定位與回饋
8.1 常見問題
畫布節點查不到： 先用
canvas get取得即時 Graph，再確認畫布識別、節點類型、節點狀態和關聯 task 是否仍有效。生成命令在產生 task ID 之前退出： 表示任務尚未提交，不要描述為「生成失敗」，也不要重複提交。
已經拿到 task ID 後發生逾時： 繼續查詢原 task，不要重新生成。
Canvas 寫入結果不明確： 查詢原操作狀態，確認最終畫布狀態後再決定下一步。
Agent 看不到終端機登入狀態： 先重啟 Agent，檢查 PATH、設定目錄和系統憑證庫，再執行第 1.4 節的檢查命令。
8.2 回饋範本
回饋至少包含：執行命令、CLI 版本、作業系統和架構、使用的模型、Canvas 識別或 task ID、脫敏 request ID/trace ID、錯誤碼、最終狀態和真實產物 URL。
不要附帶 Cookie、token、Authorization、完整請求標頭、本機憑證或其他未脫敏的敏感資訊。
8.3 常見問答
為什麼 dry-run 之後還需要 estimate 和確認？
dry-run 只驗證請求結構和參數，不代表伺服器端估價、餘額判斷或最終提交。費用相關任務仍需查詢積分、估價、說明預算、取得確認並執行一次正式提交。
如何讓 Skill 與 CLI 保持一致？
升級 CLI 後同步執行 nadou skill install --json，並用 nadou capability list --json 判斷當前命令是否實際開放。Agent 執行時優先使用本機同步後的官方 Skill。
為什麼沒有看到最終產物？
先查詢原 task 的狀態和 outputs，再確認交付空間和目錄。不要因為入口延遲、暫時沒有縮圖或一次查詢失敗就重新提交任務。