安裝 Sanad
引導用戶從檢查到驗證的 Sanad 安裝或更新流程。 保持發行版用戶與開發者原始碼工作流程的分離。
安全規則
- 在進行任何變更前先檢查。將安裝、套件更換、服務註冊、應用程式啟動和 Git 更新視為需要用戶知情批准的變更操作。
- 絕不搜尋整個主目錄或磁碟來尋找檢出位置。僅檢查當前目錄、用戶提供的路徑以及標準的已安裝指令位置。當無法安全識別專案路徑時，詢問用戶。
- 除非用戶明確授權該特定操作，否則絕不覆寫、重置、清理、暫存、提交或丟棄骯髒的儲存庫。
- 絕不請求、引用、記錄或重建存取權杖、重新整理權杖、提供者憑證、簽署密鑰或用戶內容。僅針對用戶明確授權的代理操作遠端安裝，接受用戶完整的新增裝置命令（包含其短暫、一次性使用的建立權杖）。驗證官方引導程式，在不回顯、追蹤或將其持久化於專案工件的情況下傳輸它，並且絕不提取/重建其權杖。說明此同意涵蓋建立指令在聊天/工具歷史中的暴露，且產生的安裝程式指令可能使用權杖參數；不要聲稱零暴露。保持 SSH 傳輸參數無憑證。如果用戶不接受該暴露，讓他們直接執行或使用互動式入口網站登入。此例外絕不涵蓋持久性憑證。
- 僅使用官方 Sanad 來源：
- 儲存庫：
https://github.com/EastStarAI/sanad-agent - 發行版：
https://github.com/EastStarAI/sanad-agent/releases/latest - 安裝程式：
https://sanad.eaststarai.com/install.sh和https://sanad.eaststarai.com/install.ps1
- 儲存庫：
- 不要停用作業系統安全控制。在描述當前簽署或平台支援之前，閱讀最新的發行說明。
- 在安裝和更新期間保留 Sanad Home 和用戶工作區。
Google Cloud 快速路由
對於 Google Cloud / GCP / 免費雲端伺服器請求，請閱讀 references/google-cloud-free-tier.md 並按照該專門的發行版用戶路由進行，而不是重複下面的通用本地/原始碼問卷。它擁有先決條件、最多兩個初始問題、資源重用、合格的配置、即時配對和最小的內建驗證。保持上述安全規則。不要承諾無條件零帳單或重複現有的免費額度。
1. 檢查目標
確定指令將在用戶的當前機器還是遠端機器上執行。不要假設託管 Sanad 客戶端的機器就是應該託管 Sanad 代理的機器。
收集唯讀證據：
- 識別作業系統和架構。
- 檢查
sanad和sanad-dev是否在PATH上可解析。 - 在相關時檢查安裝程式擁有的可執行檔：
- macOS/Linux：
${SANAD_HOME:-$HOME/.sanad}/bin/sanad - Windows：
$env:SANAD_HOME\bin\sanad.exe，或$HOME\.sanad\bin\sanad.exe（當未設定SANAD_HOME時）。
- macOS/Linux：
- 如果當前或提供的目錄是 Git 檢出，檢查：
git rev-parse --show-toplevel、git remote -v、git status --short --branch和git worktree list。僅當其儲存庫身份與EastStarAI/sanad-agent相符或用戶確認是有意複刻時，才接受它為 Sanad 原始碼。 - 僅透過已解析的 Sanad 可執行檔查詢已安裝版本和服務狀態。不要僅僅因為
sanad不在PATH上而失敗。
在提出變更之前，總結現有狀態。
2. 選擇工作流程
如果用戶的請求已明確工作流程，則確認目標並繼續。否則呈現以下選項並詢問他們想要哪一個：
| 路徑 | 最佳適用情境 | 結果 | 權衡 |
|---|---|---|---|
| 發行版 / 用戶 | 一般日常使用 | 打包的客戶端和經過驗證的代理發行版 | 穩定且簡單；原始碼不可編輯 |
| 原始碼 / 開發者 | 貢獻、除錯或變更 Sanad | 透過 sanad-dev 執行的儲存庫檢出 | 可編輯和測試；需要開發工具和更多磁碟空間 |
對於發行版路徑，確定拓撲結構：
- 此桌面： 安裝 Sanad 客戶端；在本機執行會在同一台電腦上安裝並啟動相符的代理。
- 另一台電腦或伺服器： 將客戶端保留在桌面、行動裝置或網頁上，僅在目標機器上安裝 Sanad 代理。
- 僅客戶端： 安裝桌面/行動客戶端或使用網頁客戶端，而不在該裝置上安裝代理。
說明確切的動作、目標和服務影響。在下載、安裝、更換、註冊、啟動或重新啟動之前獲得批准。
3. 發行版 / 用戶路徑
安裝客戶端和本地代理
- 閱讀最新的官方發行版及其清單。僅選擇與確認的平台和架構相符的客戶端套件。
- 使用該發行版發布的校驗和、簽名和平台指南驗證工件。不要將舊版發行版的簽署狀態推廣到當前發行版。
- 使用正常的作業系統流程安裝客戶端。不要無聲繞過應用程式審查或安全提示。
- 要求用戶啟動 Sanad 客戶端並選擇在本機執行。說明客戶端會下載、驗證、註冊、啟動並連接到相符的本地代理；不需要 Sanad 帳戶和配對權杖。
- 在宣告成功之前，驗證客戶端可以連接到本地代理。
對於 Android、iOS 和 Web，請遵循當前發行說明中所述的可用性。這些平台提供介面，但不託管原生代理服務。
在另一台電腦或伺服器上安裝代理
提供兩個平等的選擇：
- 透過 Sanad 客戶端配對： 開啟設定，然後點選裝置旁的 + 以開啟新增裝置。讓用戶在目標機器上執行完整的生成命令 ，或接受他們完整的生成命令，以便在授權的遠端安裝中使用一次性建立權杖例外情況（如上所述）。絕不單獨詢問憑證或將命令回顯到報告中。
- 直接安裝代理： 選擇入口網站登入或僅本機模式，並在批准後執行相符的官方安裝程式。
對於由代理操作的 macOS/Linux 終端機，避免含糊的提示：
curl -fsSL https://sanad.eaststarai.com/install.sh | bash -s -- --login
當用戶明確選擇僅本機模式時，使用 --no-login 代替。
對於由代理操作的 Windows PowerShell 終端機：
& ([scriptblock]::Create((irm https://sanad.eaststarai.com/install.ps1))) -Login
當用戶明確選擇僅本機模式時，使用 -NoLogin 代替。以互動方式執行任一安裝程式的人類可以省略明確的登入選項並回答其提示。
入口網站登入可能需要用戶開啟 URL 或輸入代碼。暫停以等待該人類操作，不要暴露返回的憑證。安裝完成後，驗證已解析可執行檔的版本和 service status。當選擇了雲端連線時，從 Sanad 客戶端確認裝置。
更新套件化安裝
-
在變更之前檢查已安裝的客戶端和代理版本，並閱讀最新的發行說明。
-
透過其平台擁有的更新流程更新 Sanad 客戶端。不要用原始碼輸出替換打包的客戶端。
-
透過已解析的可執行檔更新獨立代理：
sanad update當
sanad不在PATH上時，使用完整的可執行檔路徑。如果更新程式報告restart_required，獲得批准並執行sanad service restart。 -
驗證最終版本、服務狀態、客戶端到代理的連接以及 Sanad Home 的保留。回報任何仍為手動的平台步驟。
4. 原始碼 / 開發者路徑
準備檢出
如果已存在相符的檢出，僅在報告其路徑、分支、工作樹、遠端和骯髒狀態後使用它。不要無聲複製重複項。
如果不存在檢出，提議一個目標並獲得批准，然後執行：
git clone https://github.com/EastStarAI/sanad-agent.git sanad-agent
cd sanad-agent
在進一步工作之前，閱讀儲存庫 AGENTS.md、docs/llms.txt 和最近的巢狀合約。對每個 Dart 或 Flutter 操作使用 FVM。
一次性安裝用戶範圍的開發命令。
在 macOS/Linux 上：
scripts/sanad-dev install
在 Windows PowerShell 上：
.\scripts\sanad-dev.ps1 install
然後在每個平台上執行配對的代理和客戶端：
sanad-dev run
僅當用戶明確想要僅本機開發時，才使用 sanad-dev run --no-cloud。使用 sanad-dev status 以及有限的 sanad-dev logs agent -n 50
和 sanad-dev logs client -n 50 呼叫進行驗證。絕不從 AI 工具呼叫使用日誌跟隨模式。
更新開發者檢出
- 檢查活動分支、上游、工作樹和骯髒檔案。
- 僅在確認了預期的遠端後才執行
git fetch。在整合之前說明傳入的提交。 - 對於在預期追蹤分支上的乾淨檢出，提議
git pull --ff-only。不要隱含地建立合併提交。 - 對於骯髒的檢出，停止並呈現保留選項。未經明確授權，不要暫存、提交、變基、切換、重置或丟棄。
- 在成功的原始碼更新後，重新執行平台特定的
sanad-dev install；然後使用sanad-dev run或用戶請求的有限驗證命令。 - 絕不要對原始碼/FVM 執行環境使用
sanad update；原始碼更新屬於 Git 和sanad-dev。
5. 報告結果
報告：
- 選定的工作流程和目標機器；
- 檢測到的和最終的版本；
- 客戶端、代理、儲存庫和服務狀態；
- 驗證命令和結果；
- 任何仍需要的使用者手動操作；
- 已變更的檔案、服務或 Git 狀態。
絕不能僅從下載或命令退出碼宣告成功。需要相關的服務或用戶端到代理的健康證據。除非用戶明確請求該單獨操作，否則不要提交、推送、發布或刪除用戶資料。