ZIAForge 使用者指南

入門步驟

ZIAForge 將討論、規劃、執行與驗證整合在單一任務中。針對 Git 專案請選擇 Code，針對普通資料夾中的文件、研究與其他成果請選擇 Work。

建議先從獨立專案中的小任務開始。若選擇原生 CLI，請先在終端機中安裝並使用其自有帳戶登入。或者，也可以設定 API 連線。CLI 訂閱與付費 API 是分開的連線方式；ZIAForge 不會為您登入，也不會在兩者之間轉移額度。

1. 開啟「設定」並檢查工作區資料夾與語言。「關於」會顯示正在執行的組建之確切識別資訊。
2. 若為 Code，請在側邊欄中新增 Git 存放庫。若為 Work，請在建立任務時選擇獨立的資料夾。
3. 儲存包含 CLI、模型、推理工作量與存取層級的預設集。您也可以直接選擇「自訂」而無需儲存預設集。
4. 建立任務，選擇其路線、角色以及手動或自動推進。在「開始」之前檢視所選項目。

相關指示: 專案概觀 · 提供者相容性.

安裝正確的桌面套件

請依據您的作業系統與 CPU 架構選擇套件：x64 或 arm64。組建管線可產出 macOS DMG/ZIP、Windows NSIS 安裝程式/ZIP，以及 Linux DEB/RPM/AppImage/tar.gz/ZIP 格式。產生的檔案或跨平台組建並不能證明其安裝程式與原生 UI 在您的電腦上測試通過；請參閱該版本的驗證記錄。

使用 Electron 44 的 macOS 組建需要 macOS 13 或更新版本。在 Apple Silicon 上請使用 arm64 套件，Intel 請使用 x64 套件。在取代前請完全結束舊版應用程式。預覽套件可能未經簽署且未公證；切勿將開發構件誤認為已簽署的正式發布版本。

Windows 需要隨附的 Electron 版本所支援的作業系統，且 Git 需可在 PATH 中使用。請選擇相符的架構。未簽署的預覽版不具備 Authenticode 憑證。可攜式 ZIP 必須保留完整的應用程式目錄與執行階段檔案，而不僅僅是其可執行檔。

Linux 需要相容的圖形桌面、Electron 所需的系統函式庫，以及 Git。若要使用加密控制憑證，請提供可正常運作的 Secret Service（例如 gnome-libsecret 或 KWallet）；不安全的 basic_text 後端不予接受。無周邊/容器冒煙測試證據不能證明適用於每個桌面或發行版。

使用 apt install ./file.deb 安裝 DEB，或透過您發行版的套件管理員安裝 RPM。AppImage 需要執行權限與適當的 FUSE 支援；在支援的環境下，--appimage-extract-and-run 是另一種選擇。解壓縮 tar.gz 與 ZIP 套件時需包含其所有執行階段檔案。取代套件時，請區分使用者資料與應用程式檔案。

若要從原始碼建置，請使用 Node 24、Git 與 npm ci，包含標準的 Electron 安裝程式。原生重新建置需要平台工具：macOS 上的 Xcode 命令列工具；Windows 上的 MSVC C++、Windows SDK 與 Python；Linux 上的編譯器、make、Python、pkg-config 及必要的封裝工具。請遵循 PLATFORM_BUILDS.md 以取得確切指令與目前的平台限制。

發行版本號由中央統一保留，產出物不可變更。CI 驗證組建並非正式發布的安裝程式。原始碼封存包含原始碼、lockfile、說明文件與指令稿；排除依賴項、憑證、使用者設定檔與私人研究資料。切勿從成功的 x64 組建推斷原生 ARM 或 Windows 驗證亦已通過。

相關指示: 平台套件、先決條件與驗證限制 · 組建身分與版本發布檢查.

Code：五種路線

Auto 會評估範疇：簡單的問題可能直接以回答結束，而較大的任務則需要準備。「修復錯誤」會調查原因並準備修正方案。「規格優先」從技術解決方案開始；「需求優先」則從需求與驗收條件開始。

「多模型」在探索、設計、實作與審查中使用獨立的上下文。路線名稱並不要求使用不同的提供者：每個角色都會使用您選擇的預設集或自訂設定。

工作樹（Worktree）可隔離任務的 Git 變更。「分支」則在選取的簽出目錄中運作。開始前請檢查專案、分支與模型；任務描述不會同時傳送至一般聊天。

對於尚未釐清產品或技術抉擇的想法，請使用「需求優先」，並在討論中奠定基礎。Auto 會對請求進行分類；它不是立即實作每個簡短詞句的指令。「儲存草稿」會保留請求而不聯絡模型；「開始」則會儲存並啟動一次受管流程。一至四個任務副本具有獨立的建立 ID 與角色設定。

相關指示: Code 工作流程約定 · Code 提示詞設定檔.

Forge 討論區

「開始」會開啟中央討論區。您可以自然回覆、提出反問、新增限制條件並討論技術抉擇。對話與問題會留在任務中。

傳送文字並不代表接受文件或授權新的實作計畫。執行期間提出的釐清會先暫停受管對話輪次，並重新檢視受影響的範疇。在已接受的步驟內回答問題則可讓該步驟繼續進行。

若要刻意重新檢視基礎架構，請選取「需求」、「規格」或「計畫」。新版本需要對相依的決策重新進行接受程序。已完成的步驟及其佐證會保留；已被取代的未完成階段則保留在歷史記錄中。

受管階段工作階段不同於自由聊天。請使用 Forge 討論，而不要直接向工作流程擁有的工作階段傳送手動提示詞。

相關指示: Forge 討論約定.

文件與決策

開啟文件、檢查其版本，並在需要時進行編輯。透過討論送出編輯會產生新版本；報告與經過驗證的結果不會事後被改寫。

在接受提議的計畫之前，請編輯順序、指示、驗收條件與驗證指令。請僅授權您理解的具體指令：它們會在任務資料夾中執行。「多模型」會提議一個涵蓋整個任務的實作步驟，並在文件與指示中提供詳細資訊。

「核准」是一項獨立且深思熟慮的決定。Auto 不會跳過提問，也不會略過對需求、規格與計畫的接受手續。外部變更過的文件無法重複使用舊的核准。

準備檔案會以成果構件（artifacts）的形式呈現。其版本、產生階段與雜湊值將其與某一結果綁定。Code 文件保存在工作樹之外，不會自動加入 Commit 中。

在接受之前，請同時檢查文件與顯示的決定。接受會綁定目前的關卡 ID、計畫修訂版以及保留的文件雜湊值。當範圍或佐證有誤時，請提出變更請求。若某項決定已失效，請在做出新選擇前重新載入儲存的狀態；已變更的檔案無法以舊版本予以接受。

相關指示: 工作流程關卡與文件版本.

執行與審查

待辦事項顯示實際步驟、目前嘗試次數、驗證與審查結果。代理人回報「完成」並不代表該步驟已完成：計畫所要求的佐證必須存在。

手動模式會在符合條件的步驟之間暫停。Auto 會推進已驗證的步驟並允許有上限的重試。「在此之後停止」一律會建立檢查點。「暫停」會停止工作流程的進行中作業；關閉面板並不會使其停止。

獨立審查者會使用包含檔案與驗證結果的獨立上下文。每項必要的阻礙性發現都必須予以解決；多位審查者無法透過投票表決撤銷阻礙性錯誤。

在「多模型」中，修正發現需要明確的決定。修正不會靜默啟動另一輪審查：「重新審查」會開啟全新的一輪週期。審查意見可以要求協調員重新考慮，而無須重複進行實作。

已完成的步驟無法被靜默編輯。在採用 TDD 時，紅燈（Red）必須確實因預期原因而失敗，隨後綠燈（Green）必須通過。設有上限的嘗試次數可防止無止境的重試。

在「設定」→「審查團隊」中儲存獨立的 CLI/API 審查者，然後在 Code 或 Work 中選取該團隊。審查者會平行運作，隨後由團隊的報告架構師接續處理。您也可以在未儲存團隊的情況下設定獨立審查者。報告架構師僅會收到匿名結構化報告，沒有專案檔案或工具的存取權限；此隔離機制目前需要 Claude Code 或 API。

每個實作步驟都需要可執行的檢查、必要的獨立審查，或兩者兼具。準備階段則保留經過驗證的結果與構件收據；這並不代表已執行過實作測試。只有在確認實際結束狀態以及所擁有的處理程序已清理完畢後，指令才算成功。TDD 的紅燈檢查在實作與綠燈驗證之前必須正常失敗；缺少可執行檔或逾時並不是有效的紅燈結果。

預設的斷路器會在單一步驟連續失敗三次或累計失敗五十次後停止。中斷會消耗一次嘗試次數，但本身不算作失敗的嘗試。限制與已完成的佐證在重啟後仍會保留；「重試」不會將其重設。在授權另一次嘗試前，請先閱讀保留的失敗記錄。

相關指示: 驗證與審查.

平行審查團隊與報告架構師

開啟「設定」→「審查團隊」並儲存團隊。新增具有各自 CLI 或 API、模型、推理工作量與專業分工的獨立審查者，然後選擇報告架構師。在任務的審查設定中選取該團隊。執行者預設集也可以被審查者使用，且「自訂」仍然可用；獨立角色仍保有各自的上下文。

審查者會針對相同的任務佐證平行運作。每一份必要的報告、錯誤與判定都會被保留。架構師接收匿名編號的報告，其中不含審查者名稱、模型或提供者身分、原始任務內容、存放庫存取權限或工具。它會比對報告並傳回單一結構化判定；它不會進行全新的原始碼審查。

阻礙性發現或必要審查者的拒絕無法透過多數決或架構師偏好來豁免。報告缺失或格式錯誤會阻礙核准。在接受或授權修正之前，請檢查個別發現與彙整決定。儲存的團隊在執行期間會被解析並凍結；編輯其預設集不會改寫已完成的佐證。

僅限報告的架構師目前使用受支援的 Claude 或 API 無工具設定。Codex 與 Antigravity 仍可作為審查者，但在存在經過驗證的無工具約定之前，將被拒絕擔任此隔離架構師角色。單憑「無工具」的提示詞是不夠的。

相關指示: 具型別的團隊設定 · 審查彙整.

代理人專業分工與提示詞策略

模型是執行引擎；專業分工則是指示設定檔。選擇「無」表示不增加專業分工、「標準」使用預設指南、Auto 使用相關的內建指南，或「手動」使用選取的指南與您自己的有限指示。預設集可保留此選擇。

原始目錄涵蓋一般程式設計、架構、安全性、可靠性、效能、測試以及介面易用性。Auto 使用可用的任務/步驟文字來選取指南；它不會私下呼叫其他模型，也不保證專業水準。在接受實作計畫之前，可以檢查並變更規劃建議。

審查專業分工有助於引導注意力，但絕不能取代獨立佐證、存取限制或結構化判定。請將自訂指示視為任務範疇的一部分：切勿使用它們來繞過文件接受、工具策略、身分驗證或審查者失敗。

相關指示: 原始提示詞目錄.

Work：從問題到文件

Work 不需要 Git。「預設」會建立獨立的任務資料夾；「自訂」則透過原生選擇器選取現有資料夾。「儲存草稿」會儲存設定而不進行推論；「開始」會執行第一階段。

Auto 會直接回答或提議包含實際待辦事項的合適計畫。「腦力激盪」會在您選擇更多想法或評估之前建立 ideas.md。「研究」會保留 findings.md、來源與限制。「撰寫」從意圖出發，並在有助益時從 outline.md 推進至說明性文件或 draft.md；修訂版會保留先前的版本。

透過原生選擇器選取檔案輸入項目，並使用 @ 進行參照。應用程式會將其複製為不可變的任務輸入，並在執行前驗證其身分。「預設」會建立應用程式擁有的任務資料夾；「自訂」資料夾存取權限是儲存的擁有者授權。已儲存但未開始的草稿可以變更其資料夾。

可建立 1–4 個具有獨立執行者設定的副本。使用重疊資料夾的任務無法同時寫入。此協調機制適用於 ZIAForge 的作業，不適用於任意外部程式。

「深度腦力激盪」預設為三位獨立工作者，最多支援八位。選取其順序與設定，包括在不同上下文中重複使用預設集。工作者的提問會保留其來源；格式錯誤的報告可獲得一次格式修復嘗試。部分失敗會保持可見，而不會被包裝為一致通過。

「深度」會將保留的工作者報告合併至 brainstorm_report.md 中，且一律會要求使用者做出決定。小幅度的後續微調會透過協調員修訂報告；重大變更則會針對已凍結的工作者啟動新一輪流程。成果構件會保留其版本。

解析後的角色會在建立任務或明確儲存草稿時凍結。在首次調用後，僅能變更自動/手動推進；若要使用不同的角色或模型設定，請建立新任務。編輯全域預設集不會靜默變更後續階段。

手動模式會在符合條件的階段之間暫停，包括實質性的「撰寫」大綱。Auto 可以繼續推進該大綱。即使在 Auto 模式下，提問、提議的可執行計畫、「腦力激盪」方向與「深度」報告審查仍然屬於明確的決定。單憑引用文獻並不能證明進行過網頁瀏覽，單憑保留二進位檔案本身也不能證明其已正確轉譯。

相關指示: Work 模式與決策.

預設集、模型與存取權限

預設集儲存了 CLI/API、模型、推理工作量與權限。聊天頁尾包含預設集、CLI、模型與選項區段。「自訂」可在沒有預設集的情況下運作；「建立預設集」會儲存目前選取的內容。

目錄來自所選取已安裝的 CLI 或 API（在支援的情況下）。「重新整理」會更新清單而不變更目前的選取項目。若無法使用探索功能，請輸入明確的模型 ID；提供者仍必須支援該模型。推理等級取決於模型與 CLI。提供者預設值與明確的 none 標記不同。

僅在後端確認後套用變更。在進行中的輪次或非空佇列期間，切換會受到限制。草稿與可見歷史記錄會保留，但變更提供者不會轉移其私有的內部狀態。

在 Forge 中，角色標籤十分重要：準備工作可以使用獨立的規劃者（Planner）。頁尾可變更顯示的角色；審查者與協助者則在工作流程設定中選取。已通過驗證的實作策略可能會被鎖定。

各提供者的權限各有不同。在介面卡支援的情況下提供「唯讀」與「工作區寫入」。Antigravity 使用原生 CLI 設定或明確選取的完整存取權限。完整存取權限並不是沙盒。

專業分工增加的是提示詞指引，而非另一個模型或權限。預設集與角色支援「無」、「標準」、Auto 與「手動」。Auto 從步驟文字中選取設定檔，無須額外的模型呼叫；「手動」最多可接受四個專業領域與自訂指示。規劃者提議的分派可在接受計畫之前進行編輯。

手動輸入的模型 ID 或推論工作量仍屬於您的選擇，但提供者可能會予以拒絕。編輯全域預設集不會溯及既往地變更執行中的聊天或已接受的計畫。若要刻意變更閒置的對話，請使用其自身的設定控制項並等待確認。已停用的選項應視為功能限制或生命週期限制，切勿透過編輯已儲存的 JSON 來繞過。

相關指示: 提供者功能支援.

聊天、「停止」與佇列

開啟的分頁、「最近」與草稿皆屬於同一個任務。關閉分頁會將其從「開啟」中移除，但會保留在「最近」中，且不會停止其提供者處理程序或受管工作流程。您可以從歷史記錄選單搜尋歷史記錄、重新開啟聊天或關閉所有附加分頁。

「停止」會中斷目前的對話輪次。在下一次「傳送」前請等待停止程序完成：收到中斷確認並不代表處理程序已結束。在此期間您可以輸入下一份草稿。

在一般聊天中，「加入佇列」會將稍後的請求與目前的草稿分開儲存。「暫停佇列」會暫停進一步的投遞。「停止」與「結束」會暫停佇列。重新啟動後，請先「繼續」，然後再明確「繼續佇列」。

「不確定」代表投遞狀態未知。此類訊息不會自動重新傳送：請檢查歷史記錄，視情況複製文字，並關閉佇列項目。再次傳送屬於全新且刻意發起的請求。

受管階段聊天使用其自有的工作流程，而非一般佇列。「跟隨階段」會顯示目前階段；手動選取其他分頁會停止跟隨。CLI 記錄會獨立於回應之外顯示診斷資訊。

Markdown 回應會呈現標題、清單、表格、連結與圍欄程式碼區塊。工具卡片與 CLI 診斷資訊保持與答案分離。只有在提供者實際提供時，才會顯示模型回報的思考過程與 Token 指標；請勿從動畫推斷私有推理或使用量。

在遇到不確定的傳送或佇列確認後，請檢查歷史記錄，且僅在系統提供選項時重試同一個保留的請求。收到佇列收據代表儲存系統已接受該項目，並不代表推論已完成。僅能以明確駁回的方式移除不確定的佇列項目；這無法撤回已投遞的提示詞。

相關指示: 持久訊息佇列.

檔案、Git 與完成

「檔案」顯示任務資料夾。可將結果與需求進行比對、開啟文件並檢視差異。保留二進位檔案並不代表其在目標應用程式中能正確呈現。

Git 提供狀態、變更與操作，並記錄執行結果。提交（Commit）、合併與推送預設為手動操作；自動操作則是針對完全驗證計畫的獨立選項。

切勿在驗證與發布之間變更工作檔案：核准是與確切位元組綁定的。衝突、推送失敗以及未知的操作結果都會阻礙進度，直到做出明確決定為止。Auto 不會靜默授權發布。

Work 不會建立任何 Git 分支，也沒有 Git 定稿作業。請從選取的資料夾中保留所需的文件，包含版本與來源。

檔案編輯器依副檔名提供語法醒目提示、搜尋與取代、還原記錄、自動換行以及個別分頁草稿。儲存時會保留受支援的 UTF-8/UTF-16 編碼，並拒絕外部修改衝突。其他編碼與二進位內容需要使用外部編輯器。未儲存的草稿會阻止應用程式「結束」，直到擁有者儲存或捨棄它們為止。

完整語法醒目提示支援至多 8 MiB。較大的文字檔會在 256 KiB 的視窗中開啟；8–64 MiB 可以明確完整載入而不啟用語法醒目提示。超過 64 MiB 則使用視窗化編輯與有限次的下一個相符項目搜尋。這是一種有限的大檔案模式，並非等同於 Sublime Text 處理任意龐大文件的能力。

「開啟資料夾」使用目前任務或分支/工作樹的上下文，而非靜默僅開啟原始存放庫。檔案資料列可顯示該檔案的父目錄。路徑由後端依據已註冊的任務授權進行驗證。二進位檔案不可作為純文字編輯；請使用其目標檢視器並保留原始位元組。

移除工作樹是一項獨立且設有防護的動作。在移除工作樹之前，請先結束附加的結構化工作階段與終端機，包括閒置的工作階段。請檢查儲存的 Git 結果與復原狀態；刪除任務記錄並不能取代安全保留未認可的工作。

相關指示: 具型別的編輯器約定 · Git 策略.

API 連線

「連線」可新增明確選取的 OpenAI 相容端點。請輸入名稱、基本 URL、模型以及金鑰（若需要）。許多伺服器要求基本 URL 以 /v1 結尾；請參閱您的端點說明文件。

除 loopback HTTP 外，皆強制要求 HTTPS。請使用未在 URL 中嵌入憑證的純端點。金鑰使用受支援的 OS 加密技術，且不會回傳給 UI。變更端點需要重新輸入其金鑰。將金鑰欄位留白會保留已儲存的金鑰；「移除儲存的金鑰」則會明確予以清除。

API 呼叫不會使用 CLI 訂閱。工具與模型與原生工作階段不同，且成功發現模型並不證明具備推論能力。只有在提供者實際回傳 Token 使用量時才會顯示該數據。

請將憑證保存在「連線」中，而非任務敘述或預設集指示中。唯讀審查者僅會收到其獲准的 API 檔案工具；報告架構師則沒有任何工具。不受支援的工具呼叫會被拒絕，而不會靜默執行。各伺服器的推論參數、工具支援與模型清單各有不同；請將錯誤與您端點自身的約定進行比對。

相關指示: API 連線.

設定、語言與安全重設

一般設定可選取工作區、介面語言與預設值。「連線」用於管理 API 端點。「預設集」與「審查團隊」可保留角色設定。「遠端控制」用於管理本機憑證、伺服器範圍與擁有者權限；「更新」用於管理發布來源/通道。「關於」會顯示確切執行中的組建資訊。

介面語言獨立於提示語言與文件審核狀態。產品名稱、命令 ID、副檔名、提供者模型 ID 與使用者建立的名稱仍維持識別碼形式。當有最新的翻譯可用時，「說明」會遵循所選的介面語言；機器翻譯會加上標籤，而英文始終作為權威參考來源。

「儲存」會套用顯示的設定。資料庫重設或恢復原廠設定可能會移除應用程式中繼資料；在刻意使用重設之前，請保留檔案與經過測試的備份。這些操作屬於本地擁有者的行為。請勿將其當作調查失敗工作流程或損毀記錄的捷徑。

相關指示: 本地化指示 · 資料復原.

向說明助理提問

開啟「說明」，在其助理面板中選擇已儲存的已連線預設組態，即可詢問有關 ZIAForge 的問題。回答會使用目前的權威英文指南與您選取的介面語言。章節參考按鈕可開啟相關的指南主題，方便您將說明與參考資料進行比對。

此助理會保留一個獨立的私人對話，最多可儲存 100 條記錄與 3 MiB。請輸入最多 12,000 個字元的問題；「傳送」會提出問題，「停止」會取消目前的回答同時保留您的問題，「清除」則會移除此說明對話。您未傳送的草稿與預設組態選擇在同一個應用程式工作階段中關閉或重新開啟「說明」時仍會保留，但草稿不會儲存至磁碟。助理不會傳送應用程式命令、變更工作流程或接受關卡。其建議並非對任務、帳號或外部連線的即時驗證。

Claude Code 與 API 說明工作階段會強制執行受支援的無工具原則。原生 Codex 與 Antigravity 說明工作階段則需要現有的本地擁有者原生電腦權限。若該權限已停用，應用程式會說明必備先決條件，而非直接選擇其他提供者。只有擁有者才能在本地控制設定中啟用它；助理本身無法自行啟用。

Codex 說明使用唯讀沙盒並會拒絕工具核准請求。Antigravity 使用 plan 模式及其原生沙盒旗標。這些原生模式並非作業系統隔離的通則保證。來源指南雜湊值標識了用於回答的參考來源；產生的說明仍可能有誤，因此在採取行動前請檢查其連結的章節。當舊回答的來源指南版本與目前指南不同時，將會被標記。

相關指示: 權威指南與翻譯維護 · 應用程式助理與權限.

助理與 Telegram

助理使用選定的預設組態與相同的應用程式控制 API。檢查狀態的權限與執行操作的權限是分開的。請檢查命令與結果：助理的文字陳述並非操作已完成的證明。

Telegram 僅能由本地擁有者啟用，並需具備現有的 Bot Token 與數字格式的擁有者 ID。控制權僅限於該擁有者的私人聊天。未設定或處於非活動狀態的機器人不得接收應用程式訊息。

請勿將 Bot Token 貼入一般聊天中。設定此整合並不代表具備 Telegram 連線能力，亦不會自動建立機器人。螢幕截圖與回覆可能包含私人的工作區資料。

選擇助理預設組態，並獨立於檢查權限之外授予應用程式操作權限。Codex 與 Antigravity 助理執行需要擁有者的原生權限；它們不會被靜默替換為無工具的 API 或 Claude 工作階段。螢幕截圖可在助理對話中顯示，但目前的模型輸入不包含影像分析。請勿僅因助理顯示了影像就認定其已對影像進行視覺檢查。

助理可透過具型別的工具檢查摘要、任務、聊天、工作流程狀態、處理序上下文與應用程式視窗。它可以變更允許的一般設定並啟動獲授權的應用程式操作。它不能授予原生權限、洩漏儲存的憑證、遠端變更根工作區授權，或僅為了方便而核准 Forge 關卡。

相關指示: 應用程式控制協定.

操作您的私人 Telegram 機器人

建立或取得您自己的機器人，開啟其私人聊天，並在本地控制設定中輸入其 Token 與您的數字 Telegram 使用者 ID。僅在您希望應用程式連線時才啟用此整合。擁有者 ID 是使用者識別碼，而非使用者名稱或機器人 ID。系統僅接受在該私人聊天中來自該使用者的訊息。

使用 /start、/menu 或 /status 可總覽執行中版本、專案/任務數量以及任務狀態。各按鈕可開啟專案、任務、螢幕截圖、說明與語言。清單每頁顯示八個項目，並提供返回、重新整理、首頁與上一頁/下一頁的導覽功能。專案按鈕可篩選任務清單。任務卡片在有相關資訊時會顯示其儲存的工作流程進度、模型/預設組態與待處理的問題。

開啟任務的「聊天」可預覽已開啟/最近的對話與工作流程階段聊天。每個預覽最多顯示最近的六則使用者/助理訊息，每則明顯截短至 200 個字元。私有推理過程不會顯示。讀取歷程記錄不會啟動提供者。預覽為唯讀狀態：一般文字與 /ask TEXT 仍是對應用程式助理發問，絕不會隱式發送給您正在檢視的任務聊天。

「執行 / 繼續」會重新讀取目前的 Code 或 Work 工作流程，並啟動符合資格的已儲存工作流程。「暫停」會請求將其暫停。兩者均不代表接受需求、規格、計畫、審核結果或提問；待決定的項目會阻止「執行」。請在應用程式中作出決策，或使用帶有確切當前關卡與修訂版本且經明確授權的具型別命令。

使用「語言」或 /language 可透過原生名稱選取 56 種介面語言中的任一種。這只會為此機器人與擁有者保留偏好設定。「使用應用程式語言」會清除該偏好設定。這既不會變更應用程式的語言，也不會改變存取權限；既有的訊息不會自動重新發送。

導覽通常會更新同一個已發布的選單訊息。按鈕具有不透明識別碼，會在 15 分鐘後過期且僅能使用一次；更換卡片會使舊按鈕失效。過期、已使用、訊息不符以及先前處理序的按鈕均無法執行操作。確定無法編輯的訊息可替換為新卡片；未知的網路錯誤不會作為新訊息重試。

啟用時，輪詢器會捨棄先前的積壓工作，並在發送前記錄更新的接受狀態，以便中斷的命令不會在重新啟動時自動重播。這可防止重播；但並不保證執行完成。在發生錯誤後刻意發出新工作前，請檢查狀態/上下文。系統不會自動發送任務狀態通知。

明確命令仍然可用：/projects、/tasks、/task TASK_ID、/run TASK_ID、/pause TASK_ID、/screenshot 與 /ask TEXT。/new {JSON} 透過具型別的 createTask 建立任務；/command {JSON} 發送明確的目錄命令。引數結構請參閱即時目錄。此處套用與應用程式中相同的後端授權與資料夾授權。

應用程式絕不會將儲存的 Bot Token 數值傳送給助理。然而，螢幕截圖、摘要與對話文字仍可能包含私人的專案資訊。若機器人或擁有者帳號不再值得信任，請在本地停止此整合。向機器人提供者輪替外洩的 Token，然後更新本地的加密設定。

相關指示: 私人機器人與命令.

僅限擁有者的原生電腦權限

原生電腦存取權限預設為停用。只有擁有者能在本地「設定」→「遠端控制」中將其啟用。助理以及 HTTP/MCP/Telegram 命令無法為其自身啟用此旗標。若操作遭到拒絕，助理應描述該設定並由擁有者自行決定。

在明確啟用後，computer.run 接受可執行檔、引數陣列以及選填的絕對工作目錄。它不使用 Shell 插值，有 30 秒限制，並將輸出限制在 1 MiB 以內。若提供不存在或無效的目錄將會被拒絕；省略 cwd 則會使用應用程式所擁有的設定目錄，而非 HOME。結束應用程式會取消執行中由其擁有的命令，並等待其處理序清理完成。

應用程式讀取/操作範圍與原生存取權限是分開的決策。工作樹並不能限制不受限提供者的檔案系統存取權。任務完成後若不再需要，請撤銷原生存取權限，並請檢查命令收據，切勿將助理的文字陳述視為證明。

相關指示: 僅限擁有者控制協定.

瀏覽器與遠端執行個體

本地擁有者可啟用伺服器並選擇其位址、連接埠與權限範圍：read 用於檢查，operate 則可用於執行操作。預設的 127.0.0.1 位址僅能在此電腦上使用。0.0.0.0 會在網路介面上進行監聽；啟用前請仔細檢查網路存取權限。

瀏覽器在透過 Token 登入後會開啟相同的介面。請勿在公開連結或螢幕截圖中包含 Token。僅靠 HTTP 本身無法加密傳輸；在不受信任的網路上請務必使用受保護的通道。

擁有者可透過 URL 與 Token 設定其他執行個體。後端會代理請求；這不會將它們的專案複製到本地機器上。在每次執行操作前，請檢查選取的執行個體。

具型別的命令與事件承載著應用程式控制權。read 權限範圍並未授權修改任務。原生電腦控制是分開的本地擁有者選擇，且預設為停用。

要透過瀏覽器、Telegram 與外部代理進行控制，應用程式必須保持執行狀態。每個執行個體都有其獨立的私人設定檔、任務狀態、Token 與伺服器連接埠。請勿在獨立的執行個體之間同時重複使用同一個設定檔。瀏覽器事件與命令回應的作用範圍僅限於所選的執行個體；切換 UI 不會遷移檔案或複製原生登入狀態。

相關指示: HTTP 與執行個體控制.

OpenClaw、Hermes 與其他外部代理

請使用經過驗證的應用程式控制 API 或隨附的 MCP stdio 橋接器。在本地啟用伺服器，選擇 read 或 operate 權限範圍，並使用該執行個體的 URL 與 Token 設定每個用戶端。需要 Node.js 22 或更新版本以執行獨立的 MCP 橋接器；Electron 應用程式不會為您安裝代理用戶端。瀏覽器 URL 並非 Streamable HTTP MCP 端點：請將其作為 ZIAFORGE_URL 提供給 stdio 橋接器。

此橋接器公開了 ziaforge_status、ziaforge_commands、ziaforge_command 與 ziaforge_screenshot。請先從狀態與即時命令目錄開始，然後讀取所選任務的 system.context。具型別的命令遵循與本地 UI 相同的修訂版本、關卡、任務資料夾與清理檢查。

即時命令目錄包含 documentation.guide（權威英文指南）及其原始路徑與 sourceSha256。內部應用程式架構師透過其工具接收相同的參考資料。這讓各個代理能獲得完整的產品上下文而無需依賴舊筆記；說明文件絕不會授予存取權限，亦不可替代目前的人工作成之決策。

代理應根據簡短的人類構想來討論需求、技術決策與規劃。它們必須保留明確的人工關卡、選定的模型、手動/Auto 原則以及所需的審核。它們不得捏造核准、以新的 ID 重新重播不確定的命令，或在未具備擁有者意圖的情況下發布 Git 變更。

為多個安裝環境設定多個具名 MCP 伺服器。切換執行個體屬於路由決策，而非同步機制。OpenClaw 與 Hermes 的設定範例位於 AGENT_CONTROL.md 中；必須針對所安裝的用戶端版本檢查特定用戶端的設定與相容性。

外層 requestId 快取僅在應用程式執行期間對有限數量的請求進行重複資料刪除。具持久性的操作使用各自的識別碼：用於建立任務的 createRequestId、用於工作流程決策的 commandId、用於訊息的 clientMessageId 以及用於 operationId 的 Git 變更操作。在收到未知的確認後，請保留原始識別碼與有效酬載；在刻意發出新工作之前，請先讀取已儲存的狀態。

相關指示: MCP 用戶端說明.

本地 CLI 與自動化限制

ziaf 發送器控制著相同的執行中應用程式與已儲存的工作流程。從原始碼出發，請使用 npm run ziaf -- list、npm run ziaf -- status --task TASK_ID --json、npm run ziaf -- start --task TASK_ID 或 npm run ziaf -- pause --task TASK_ID。成功的 Start 確認並不代表任務已完成。

--until-success 會刻意為已儲存的工作流程啟用 Auto，但提問、審核、驗收關卡、限制與檢查點仍然適用。Ctrl+C 會結束觀察中的發送器；它並不會隱式停止應用程式工作流程。有關結束代碼、本地端點與設定檔處理方式，請參閱 CLI.md。

「自動化」介面目前僅儲存顯示定義與本地執行計數器。它不是經過認證的週期性排程器，亦無法證明背景模型輪次已執行。如需實際執行，請使用已儲存的工作流程控制項、ziaf 或經過驗證的 API 並檢查其收據。請勿將示範面板誤認為無人值守的排程機制。

相關指示: 發送器命令.

版本與更新

「關於」顯示確切執行的版本。公開更新需要受信任的 GitHub 發布存放庫以及穩定或預覽通道。檢查、下載與安裝各有獨立的狀態；出現錯誤並不代表更新已安裝。

自動安裝僅適用於經過簽署的 macOS 發布版本。未簽署的開發組建不會透過此機制自動安裝。如需手動替換，請完全結束目前的應用程式並使用經查證的成品。

自動檢查在啟用時會立即執行，之後每六小時執行一次。

穩定版不包含預覽版本；預覽版則一併允許開發版本。檢查成功僅代表確認了可用的發布中繼資料。下載與安裝需要平台封裝包與設定好的發布摘要來源。Linux DEB 發送採用獨立的安裝程式路徑；請勿假設 DEB 會由 macOS 更新機制自動升級。

相關指示: 發布準備狀態.

重新啟動與復原

在 macOS 上，請使用結束 / ⌘Q 進行完全關閉。僅關閉視窗可能仍會讓應用程式在背景執行。更換應用程式前，請完全退出舊版本。

啟動後，請選擇相同的任務。歷程記錄與草稿將會恢復。「繼續」會還原原生/本地上下文，但不會傳送草稿、取消暫停佇列或授權重複執行不明操作。

若出現「復原」畫面，請勿手動編輯 JSON。請檢查受影響的文件類型，保留原始檔案並選取經過驗證的備份。還原較舊的佇列會將其項目標記為不確定。

當傳遞狀態不明時，受管理的工作流程可能需要明確的權限以建立全新上下文。早期的工作與失敗的嘗試將被保留；明確的拒絕比虛構的成功更安全。

請在關閉所有應用程式執行個體的情況下備份任務檔案與應用程式設定檔。單純複製資料夾並不等同於經過測試的還原。若復原程序要求您選取經過驗證的備份，請一併保留受損的確切檔案。還原較舊的工作流程或佇列並不代表授權重播不確定的推論或 Git 操作。

相關指示: 復原協定.

疑難排解

找不到 CLI：請在一般終端機中檢查其安裝狀態與版本，然後重新啟動 ZIAForge。可執行檔存在並不代表您已登入。請使用提供者自有的登入機制。

模型無法使用或授權失敗：請重新整理探索狀態，選取可用的 ID，並檢查您的帳號與配額限制。在檢查歷程記錄之前，請勿重複發出不確定的請求。

工作流程停止：請開啟當前階段、提問、驗證收據或 CLI 記錄。針對具體原因進行解決：未回答的問題、命令、資料夾權限或嘗試次數上限。「繼續」無法將失敗的檢查轉化為成功。

資料夾遺失或已被替換：請還原對原始資料夾的存取權或建立新任務。應用程式不得從 HOME 繼續執行。若觀察到其他 cwd，請停止該輪次並保留診斷資訊。

若要回報問題，請附上「關於」中的版本、路由、CLI/模型、預期與實際行為、螢幕截圖以及安全的記錄摘要。請移除機密、個人內容與無法公開的路徑。

遠端頁面無法使用：請確認擁有者已啟用伺服器，檢查監聽位址與連接埠，然後使用正確的執行個體 Token 進行驗證。401 表示身分驗證問題；遭拒絕的變更操作可能是由於 read 權限範圍或僅限擁有者的控制項。變更 Token 會關閉現有的瀏覽器用戶端。請勿將獨立的 DevTools 檢查連接埠公開為遠端應用程式控制端點。

編輯器儲存遭拒：請保留草稿，檢查磁碟上的當前檔案，並解決外部變更衝突。請勿透過重寫應用程式中繼資料來繞過比對。若無法完整載入大檔案，請使用受支援的視窗編輯/搜尋功能或外部編輯器。

Telegram 無法使用：請在本地確認 Bot Token、數字格式的擁有者、私人聊天以及狀態。相互競爭的 Webhook 或輪詢器可能會阻止輪詢；ZIAForge 不會自動刪除 Webhook 或接管其他輪詢器。在不明邊界遭拒或中斷的命令不會自動重播。

相關指示: 測試與診斷.

回報問題與檢查實證

請從「關於」記錄確切執行的組建版本、OS/架構、任務模式、選取的提供者/模型，以及重現問題的步驟。請描述預期結果與觀察到的結果。請附上安全的螢幕截圖與相關保留的命令或驗證收據，而非整個私人設定檔。

CLI 記錄、事件日誌、模型對話記錄、瀏覽器追蹤與螢幕截圖可能會暴露原始碼、個人路徑或 Token。在分享前請檢查並遮蔽敏感資訊。盡力而為的記錄遮蔽機制並不保證螢幕截圖或封存檔即可公開發布。

對貢獻者而言，qa:doctor 會讀取環境/組建識別資訊；qa:inspect 會開啟帶有提供者虛設常式（stub）的隔離設定檔。測試載具（fixture）在不連繫模型的情況下證明已測試的應用程式路徑。即時推論、Telegram 連線能力、原生 Linux 桌面、簽署與封裝成品的檢查均為獨立的實證。請參閱 TESTING.md 以取得可重現的命令與清理步驟。

相關指示: 實證命令.

本地資料與邊界

專案、歷程記錄、計畫、文件與診斷資料可能包含隱私文字。切勿將設定檔、原始擷取內容、金鑰或包含原始碼的完整記錄對外公開。

在 Linux 上，儲存 API、控制權、Telegram 與執行個體認證憑證需要解鎖的 GNOME Secret Service 或 KWallet；在缺乏受支援的密鑰存放區時，ZIAForge 會拒絕儲存這些密鑰，而非退回使用 Electron 的 basic_text 機制。

本地儲存並不代表請求只會留在您的電腦上：所選的 CLI/API 會將請求傳送給其提供者。工作資料夾與處理序監督並不等同於 OS 隔離。請仔細檢查所選的權限。

請區分實證類型：測試載具（fixture）在沒有模型的情況下測試應用程式；原生即時環境則使用真實的 CLI/帳號進行演練；封裝檢查則對特定成品進行認證。通過其中一項並不保證其他項目的有效性。

應用程式範圍、工作樹與唯讀提示詞與作業系統的強制隔離不同。Antigravity 審核員/輔助原則是偵測收集到的工作區實證中的變更，而非強制執行檔案系統的唯讀存取。原生電腦控制是在一般應用程式工具邊界之外執行擁有者授權的程式；當不再需要時，請將其關閉。

相關指示: 出處與發布.

理解與修改此開源專案

請先閱讀 AGENTS.md 與 CONTRIBUTING.md，然後參閱 PROJECT_MAP.md 以了解目前的原始碼邊界。實作的具型別協定與目前的工作流程/提供者文件規範了系統行為。CONCEPT.md 與 ARCHITECTURE.md 中以終端機為主的內容保留了歷史設計意圖，切勿誤認為當前發行版本的規範。

英文說明來源為 docs/help/en.json。請勿手動編輯產生的 USER_GUIDE.md 或 website/guide.html。請修改權威章節，更新受影響的協定，並執行 node scripts/help/generate.cjs。應用程式內的「說明」讀取相同的來源。請對照實際實作審核新增內容，包括限制、權限與不受支援的路徑。

56 個介面語言地區在 docs/help/locales.json 中各自擁有獨立的說明狀態。缺少或不完整的說明會退回使用英文。完整的機器翻譯內文會標註標籤並繫結至英文來源雜湊值，且不聲明經過人工審核。經人工審核的翻譯還會記錄其審核者。每份翻譯都必須保留章節 ID、操作、檔案/命令識別碼以及技術限制，使用正確的文字方向，並在英文來源變更時進行更新。

在發布前，請執行 node scripts/help/generate.cjs --check 以偵測過期的產出內容、無效的語系架構或損壞的本地協定連結。UI 翻譯檢查與應用程式行為檢查仍然分開進行。HELP_MAINTENANCE.md 提供了貢獻者與 AI 的更新程序；說明文件絕不能聲稱通過未曾執行的測試。

相關指示: 目前專案架構圖 · 說明文件維護 · 貢獻者指示 · 代理指示.