工具目錄

下表與 MCP 伺服器實際提供的工具同步產生。標示「僅限管理員」的工具，一般帳號呼叫會回傳權限錯誤。

目前共 44 個工具。

工具	說明	必填參數	類型
get_task 獲取任務狀態	讀取非同步任務狀態。status=2000 表示成功，5xxx 表示失敗，其餘狀態仍在處理中。工具會在服務端最多等待約 25 秒；terminal=false 時稍後再次呼叫，禁止高頻輪詢。任務結束後返回全部圖片、影片或音訊輸出。	id	唯讀
list_models 列出底層模型	列出底層 models 集合中的模型及供應商配置，供 get_model_params 查詢引數。generate_media 選擇模型時不要直接使用這裡的 ID，應呼叫 list_model_aliases 獲取模型別名。	—	唯讀
get_model_params 獲取模型引數	讀取一個底層模型的基礎和高階引數定義，例如畫幅、時長、幀數與尺寸。modelId 必須來自 list_models；填寫 generate_media 前可用它確認模型的特殊輸入要求。	modelId	唯讀
list_model_aliases 列出模型別名	列出 model_aliases 單一事實源。generate_media 的 modelId 和工作流節點的 model 都必須使用這裡返回的別名 ID；請結合 mcp_description、型別、費用與最大參考圖數量選擇，不要按列表順序猜測。	—	唯讀
list_characters 列出角色	列出當前使用者擁有的角色，返回角色 ID、名稱、描述、角色圖片和狀態。需要更新角色、創作章節或繫結生成圖片時先用此工具確認角色 ID。	—	唯讀
list_locations 列出場景	列出當前使用者擁有的場景資產，用於在連續創作中保持地點外觀一致。	—	唯讀
create_character 建立角色文件	先建立不缺欄位的完整無圖角色文件，不呼叫媒體生成模型。呼叫前必須先詢問使用者語言偏好，並用 language 明確記錄；name、persona 內的全部文本及必填的 opening_suggestions 必須使用該語言。greeting 可自由書寫，也可選用 *旁白* 格式區分旁白與對白，服務端不強制格式。建立成功後先展示角色欄位，再呼叫 generate_media 生成候選圖並等待使用者確認；不要在建立角色前預先生圖。display_image_url 僅為舊客戶端相容欄位，新流程不應在本次呼叫中填寫。character_id、user_id 與計數器由服務端生成。	name persona is_minor audience visibility category_ids tags language	寫入／刪除
update_character 更新角色欄位	按部分更新語義修改當前使用者擁有的角色業務欄位：只覆蓋明確提供的欄位，未提供的欄位保持不變。支援人設、基礎文本、策展資訊、內容分級、展示圖和階段頭像；greeting 可自由書寫，也可選用 *旁白* 格式區分旁白與對白，服務端不強制格式。角色 ID 僅用於定位文件，user_id、狀態、計數器等系統欄位不可修改。所有角色圖片 URL 都必須屬於當前 R2_CDN_URL，否則整次更新會在任何寫入前被拒絕。使用者首次確認候選圖後，無論候選 URL 是否已經公開，都必須先呼叫一次 upload_image，並在同一次 update_character 中把 upload_image 返回的 URL 寫入 display_image_url、source_image_url 和 stage_avatars.acquaintance[0]；後續階段圖每次更新都要提交包含已有圖片的完整 stage_avatars 結構。更新文本前先讀取角色並保持原有語言，除非使用者明確要求翻譯。	id	寫入／刪除
create_story_chapter 建立故事章節	為當前使用者擁有的角色建立故事章節；這就是角色故事的生成落庫工具，不再另設 generate_character_story。標題和正文會經過內容稽核。可設定閱讀順序、關係階段門檻、解鎖規則、複合條件、場景頭和劇情節拍；劇情節拍可標 track: side 作為角色主動提出的支線約定（必須帶角色口吻的 promise），與主線並行、錯過不懲罰，獎勵只給劇情與關係；整條故事至少保留一個免費或禮物點數章節。	characterId title content	寫入／刪除
update_story_chapter 更新故事章節	按部分更新語義修改已有故事章節；這就是角色故事的更新工具，不再另設 update_character_story。只覆蓋明確提供的欄位，condition 傳 null 可移除複合門檻；修改標題或正文會重新執行內容稽核。劇情節拍同樣支援 track: side 支線約定（帶角色口吻的 promise，與主線並行、錯過不懲罰）。	chapterId	寫入／刪除
list_story_chapters 列出故事章節	以作者視角列出一個角色的全部章節及完整正文、順序和解鎖條件。編輯章節前先讀取當前值，以便提交準確的部分更新。	characterId	唯讀
propose_story_outline 檢查故事大綱	在寫章節正文前提交整條故事的章節門檻與產出關係，靜態檢查無法產出的標記、順序倒置和付費死路。此工具不呼叫模型、不扣積分；檢查通過後再用 create_story_chapter 寫入正文。	chapters	唯讀
check_character_script 檢查角色劇本	靜態檢查已儲存角色劇本中的不可達章節、無法滿足的標記或物品門檻、迴圈依賴和純付費路徑。不呼叫模型、不扣積分，適合每次編輯後執行。	characterId	唯讀
simulate_playthrough 模擬故事通關	用四種確定性玩家行為模擬角色故事，報告回合數、被強制推進的劇情節拍和關係值變化；支線約定（track: side）與主線並行模擬，到期未達成記為錯過（missedBeatIds），不會被強制推進、也不算卡關。用於判斷故事實際遊玩節奏；不呼叫模型、不扣積分。	characterId	唯讀
delete_story_chapter 刪除故事章節	永久刪除作者自己的故事章節，操作不可撤銷。讀者已經解鎖的章節不能刪除；刪除後若只剩積分付費章節也會被拒絕。	chapterId	寫入／刪除
upsert_character_event 建立或更新角色事件	建立或部分更新角色主動觸發的劇情事件。新事件需要標題、開場文本和觸發條件；事件對每位讀者最多觸發一次，且角色不得借事件推銷積分、訂閱或折扣。	eventId characterId	寫入／刪除
list_character_events 列出角色事件	列出作者角色的全部事件，包括已停用事件及其觸發條件、開場文本、優先順序和啟用狀態。	characterId	唯讀
delete_character_event 刪除角色事件	永久刪除角色事件，操作不可撤銷。通常應優先用 isActive=false 停用，以免重新建立同一事件後對讀者再次觸發。	eventId	寫入／刪除
upsert_character_post 建立或更新角色動態	建立或部分更新角色時間線動態。新動態必須提供正文；正文會經過內容稽核，且不得推銷積分、訂閱、升級或折扣。隱藏動態時優先設定 visibility=hidden。	postId characterId	寫入／刪除
list_character_posts 列出角色動態	列出作者角色最近的時間線動態，包括隱藏項。更新動態前先讀取當前內容。	characterId	唯讀
delete_character_post 刪除角色動態	永久刪除角色動態，操作不可撤銷，相關評論會失去目標。通常應優先將 visibility 設為 hidden。	postId	寫入／刪除
upsert_character_npc 建立或更新配角	建立或部分更新角色身邊的配角資料卡。新配角必須提供名稱和關係；每個主角色最多 30 個配角，可用 chapterIds 標記其出現章節。	npcId characterId	寫入／刪除
list_character_npcs 列出配角	列出一個角色的全部配角資料卡，包括已停用項。更新配角前先讀取當前內容。	characterId	唯讀
delete_character_npc 刪除配角	永久刪除配角資料卡，操作不可撤銷。通常應優先用 isActive=false 停用，以保留章節關聯。	npcId	寫入／刪除
create_location 建立場景	根據文字描述建立場景資產，並非同步生成場景圖與六格分鏡圖。會扣除積分，失敗自動退款；返回 taskId 後使用 get_task 獲取結果。	name description	寫入／刪除
get_character 獲取角色詳情	按角色 ID 獲取當前使用者擁有的完整角色資料，包括 persona、策展資訊、內容分級、display_image_url、source_image_url、reference_sheet_url 與五階段頭像。建立或更新角色後應呼叫此工具，把結果列印給使用者審閱，再詢問是否修改欄位、修改圖片或新增故事。	id	唯讀
get_location 獲取場景詳情	按場景 ID 獲取場景圖、分鏡圖、狀態和其他完整資料。	id	唯讀
list_creations 列出生成記錄	按時間倒序列出當前使用者的單步生成記錄，包括型別、提示詞、輸出 URL 和狀態，可用於複用已經完成的圖片或影片。	—	唯讀
list_categories 列出角色分類	列出平臺當前啟用的角色分類及 category_id。建立或更新角色的 category_ids 前先呼叫此工具，禁止猜測分類 ID。	—	唯讀
get_credit_balance 獲取積分餘額	讀取當前使用者可用積分及訂閱資訊。可用總額為 daily_credit、subscription_credit 與 onetime_purchase_credit 之和。	—	唯讀
upload_image 上傳圖片	把本地 base64 圖片或遠端圖片轉存到 Hanakoi 公開儲存並返回當前 R2_CDN_URL 下的穩定 URL。管理員給出參考圖時先呼叫本工具，再把返回 URL 放入 generate_media.imageUrls 執行圖生圖；建立角色時運營確認候選圖後也必須呼叫本工具一次，即使候選圖已有公開 URL，隨後只能用本工具返回的 URL 更新角色文件。支援 jpeg、png、webp、gif，單張上限 10MB。	—	寫入／刪除
upload_audio 上傳音訊	把本地 base64 音訊或遠端音訊轉存到 Hanakoi 公開儲存並返回穩定 URL。支援 mp3、wav、ogg、webm、m4a、aac、flac，單檔案上限 50MB。	—	寫入／刪除
upload_video 上傳影片	把本地 base64 影片或遠端影片轉存到 Hanakoi 公開儲存並返回穩定 URL。支援 mp4、webm、mov、avi、mkv、m4v，單檔案上限 200MB。	—	寫入／刪除
generate_media 生成圖片、影片或音訊	執行一次圖片、影片或音訊生成，也是角色影像生成和抽卡的唯一工具。先用 list_model_aliases 選擇別名；外部參考圖先經 upload_image 轉為穩定 URL；純文字生圖使用 text_to_image，階段頭像使用 image_to_image，並把角色的 source_image_url 放入 imageUrls。任務會扣積分，失敗自動退款；返回 taskId 後用 get_task 獲取成品。角色候選圖完成後必須向用戶展示圖片或 URL，並等待明確確認，不能自動繫結；使用者不滿意時先收集風格、外觀、服裝或構圖修改意見再重生成。	modelId modelType	寫入／刪除
create_music 創作音樂	根據創意或完整歌詞非同步生成原創歌曲，可用於後續角色歌曲。任務會扣積分，失敗自動退款；角色聊天內生成完成後會自動投遞到會話，外部呼叫可用 get_task 查詢。	—	寫入／刪除
start_companion_test_run 發起測試會話多輪實跑	僅限管理員（許可權碼 admin.harness-config）。為呼叫者本人建立一個隱藏且隱身的測試會話，按 turns 順序對指定角色發起真實對話：立即返回 runId 與 sessionId，不等待模型；每一輪由上一輪生成完成的事件驅動下一輪，任一輪失敗即終止。每輪都是一次真實模型呼叫，會產生模型費用，費用由平臺承擔（billing_owner=platform），不扣管理員積分；最多 10 輪，每輪 ≤ 2000 字元。測試會話使用獨立記憶池，不計入社群統計、熱度、角色 KPI 與每日指標；內容安全、age-gate 與稽核照常生效。之後用 get_companion_test_run 讀取結果，不要高頻輪詢。	characterId turns	寫入／刪除
get_companion_test_run 讀取測試會話實跑結果	僅限管理員（許可權碼 admin.harness-config）。只讀返回測試執行的狀態（queued / running / completed / failed）、逐輪 generationId、終態、角色回覆、快捷回覆及來源、turn trace 摘要（擴充套件產出與觸發、重複檢測、取樣、快捷回覆補全、請求形態修復）、最後的會話狀態欄位與平臺承擔的費用匯總。非發起者的管理員讀取會寫入管理員審計日誌。	runId	唯讀
list_companion_llm_calls 查詢原始模型呼叫日誌	僅限管理員（許可權碼 admin.llm-call-logs）。按 sessionId 或 generationId 分頁讀取角色聊天實際發給模型的請求與 Provider 原始響應 / 錯誤（憑據與隱藏推理已脫敏）。除角色回覆外，同一會話內的 judge、快捷回覆補全、關係評估、上下文壓縮等非回覆呼叫也可讀，每條帶 purpose 區分，可用 purpose 入參只看某一類；回覆呼叫額外返回 wireBody（與 Provider 實發 body 同源，含取樣欄位）。每次讀取前先寫入管理員審計日誌，審計寫入失敗則拒絕讀取；日誌來源為 Cloud Logging，未配置時返回不可用。翻頁時透傳上一頁的 nextCursor、queryFrom、queryTo。	—	唯讀
preview_companion_request 預覽角色聊天請求	管理員專用（需 admin.harness-config 許可權）：給定角色、聊天模型、合成歷史與本輪訊息，返回生產執行器會發給模型的完整請求體（與實發 body 同構，不含憑據）及組裝明細：system 分段、本輪上下文落點、各上下文擴充套件的注入與觸發判定、宏、請求形態修正、取樣引數與工具列表。不呼叫模型、不寫庫、不讀取任何真實會話；記憶預設為空，可用 sessionState.memory 注入合成記憶。	characterId userMessage	唯讀
run_companion_eval 發起角色陪伴評測	僅限管理員（許可權碼 admin.harness-config）。對指定角色跑一組評測場景（scenarioIds 或 tags 二選一，都省略則跑整個場景庫）：每個場景為呼叫者本人建一個隱藏且隱身的測試會話，由模擬使用者按場景劇本與角色真實對話（第 1 輪也由模擬使用者生成，逐字臺詞原樣傳送），每一輪由上一輪生成完成的事件驅動下一輪，使用者離開或到達輪數上限（每場景最多 30 輪）即結束，隨後由 Claude 行為評審逐輪與整會話打分（每項須附角色原文引文）並做 P0 配置保真 lint。立即返回 evalId，不等待任何模型；之後用 get_companion_eval 讀取，不要高頻輪詢。所有模型呼叫（角色回覆、模擬使用者、評審）都會產生模型費用，費用由平臺承擔（billing_owner=platform），不扣管理員積分；測試會話使用獨立記憶池，不計入社群統計、熱度、角色 KPI 與每日指標；內容安全、age-gate 與稽核照常生效。	characterId	寫入／刪除
get_companion_eval 讀取角色陪伴評測結果	僅限管理員（許可權碼 admin.harness-config）。只讀返回評測狀態（running / completed / failed）與進度、每個場景的測試會話 id、逐輪對話、評分卡（逐輪 + 整會話、每維度 1–5 分與證據引文、rubric 版本、套路句重複統計）、跨場景維度均值、P0 保真 lint 報告（呼叫日誌不可用時標 unavailable）、角色 prompt rev 與 harness settings rev，以及平臺承擔的成本彙總。原始模型交換可用 list_companion_llm_calls 按 sessionId 讀取。非發起者的管理員讀取會先寫入管理員審計日誌，審計寫入失敗則拒絕讀取。	evalId	唯讀
compare_companion_eval 對比兩次角色陪伴評測	僅限管理員（許可權碼 admin.harness-config）。對比同一場景集在兩個 revision 上的評測（baseEvalId = 基線，candidateEvalId = 候選）：輸出逐維度與逐場景差值、顯著退步項（維度均值下降超過閾值，閾值可配置，預設 0.5 分）及兩側證據引文；合規維度只要候選側有任何一次失敗即判退步。rubric 版本或場景版本不同的評分卡不可直接對比，直接報錯。只讀；非發起者讀取會寫入管理員審計日誌。	baseEvalId candidateEvalId	唯讀
get_prompt_texts 讀取平臺提示詞文字	僅限管理員（許可權碼 admin.harness-config）。只讀返回平臺提示詞文字包的當前版本（rev、全部鍵的文字、更新時間與更新人）、歷史版本摘要（rev、時間、更新人，最多 20 版）與鍵目錄（鍵、分組、名稱、text / lines 型別）。釋出前先呼叫本工具取得 current.rev，作為 update_prompt_texts 的 expectedRev。	—	唯讀
update_prompt_texts 釋出平臺提示詞文字	僅限管理員（許可權碼 admin.harness-config）。與後臺「提示詞文字」頁同一服務：只替換給出的鍵、其餘鍵保持不變，釋出為新 revision（rev + 1）；舊版本進入歷史，可在後臺回滾；寫入管理員審計。expectedRev 與當前不一致時拒絕（REVISION_CONFLICT），未知鍵拒絕（INVALID_ARGUMENT）；尚未初始化時拒絕，請先在後臺開啟提示詞文字頁完成初始化。釋出後約 5 分鐘內生效（快取），影響平臺上所有使用這些鍵的角色請求。	expectedRev texts	寫入／刪除