入門
在使用之前我需要什麼ash？
你需要ash可執行檔、AI 端點和模型名稱。跑步ash install自動配置這些：它使用已設定的雲端提供者 API 金鑰或找到時正在運行的本機推理伺服器，否則它會顯示編號的提供者選單並提示輸入 API 金鑰，然後讓您從端點的模型清單中選擇模型。您也可以設定ASH_AI_ENDPOINT和ASH_AI_MODEL手動。本地端點（例如 Ollama）可以使用http://localhost:11434，以及 LAN 主機，例如http://brain.local:11434或者私人 IP 也被視為本地 IP（除非ASH_STRICT=1）；雲端點必須使用 HTTPS，並且通常需要ASH_AI_AUTH_TOKEN。 Shell 整合是可選的：您可以隨時運行ash "your question"直接地。
哪裡有ash安裝，如何檢查我的 shell 是否可以找到它？
經過驗證的安裝人員地點ash在~/.local/bin/ash。將該目錄新增至您的PATH使用 shell 的正常配置；ash install除非您通過，否則不會編輯 shell 啟動文件--shell-integration。打開一個新終端，然後運行command -v ash確認。自更新程序将其替换二进制文件安装到相同的用户本地位置。安裝程式需要 Sigstorecosign驗證簽名的校驗和清單。
我該如何使用ash不改變我的外殼？
直接傳遞引用的提示：ash "how do I find large files?"。沒有任何爭論，ash也接受非互動式標準輸入提示，例如git diff | ash。當您學習時，直接使用是最不令人驚訝的選擇ash或編寫腳本。
為什麼會ash說我的AI配置不完整？
檢查一下ASH_AI_ENDPOINT和ASH_AI_MODEL在環境中非空ash運行。對於雲端主機名，也設定ASH_AI_AUTH_TOKEN當提供者要求時。跑步printf '%s\n' "$ASH_AI_ENDPOINT" "$ASH_AI_MODEL"確認前兩個值存在，但不將身份驗證令牌列印到終端記錄或共用日誌中。
安裝和更新
做ash在 Windows 11 上工作嗎？
不是原生的。ash支援 macOS、Linux 和 FreeBSD 上的 bash、zsh 和 Fish；沒有 PowerShell 安裝目標。使用 WSL 獲得支援的 Linux 體驗。
我該如何安裝ash在適用於 Linux 的 Windows 子系統 (WSL) 中？
遵循Linux安裝說明在您的 WSL 发行版中，更喜欢其包管理器。然後配置提供者並可選擇啟用 Bash 集成。沒有本機 Windows 安裝程式。
我該如何更新ash到最新的發行版本？
使用 Homebrew/APT/DNF/Pacman 安裝的所屬套件管理器。ash update僅適用於穩定版本安裝~/.local/bin;它验证 Sigstore 签名的清单和存档摘要，并拒绝失败的签名。本机 .pkg 和自定义目录安装需要其原始安装程序/手动替换。看更新和頻道訂閱適用於發布版、測試版和夜間版。
我跑了ash install。為什麼這個終端沒有任何變化？
預設情況下停用 Shell 整合。要啟用它，請運行ash install --shell bash --shell-integration（或選擇zsh或者fish）；它不會重寫已經運行的 shell 進程。開啟新終端或重新載入選定的啟動檔。跑步ash install --shell bash --disable-shell-integration刪除Ash的託管區塊，同時保留周圍的內容。
未知命令仍然顯示“未找到”。如何解決 shell 整合問題？
首先確認您啟用了 shell 集成ash install --shell bash --shell-integration（替換你的shell），然後運行command -v ash;該鉤子無法呼叫 shell 找不到的二進位。重新載入或重新啟動 shell 並檢查其啟動檔案是否包含>>> ash install >>>管理區塊。終於跑了ash snooze off，因為暫停會故意將未知命令留下為正常的「未找到」失敗。
文件有什麼作用ash install更改，我可以預覽嗎？
它管理下的配置$XDG_CONFIG_HOME/ash(預設~/.config/ash），數據下$XDG_DATA_HOME/ash(預設~/.local/share/ash），說明下$XDG_STATE_HOME/ash(預設~/.local/state/ash），並緩存在$XDG_CACHE_HOME/ash(預設~/.cache/ash）。啟動文件僅更改--shell-integration。使用ash install --shell bash --shell-integration --dry-run预览； dry-run 不写入文件。重新運行安裝是冪等的；使用--overwrite僅當您想要刷新託管引導程式檔案時。
做ash支持魚嗎？
是的。跑步ash install --shell fish --shell-integration選擇加入。ash新增一個託管區塊$XDG_CONFIG_HOME/fish/config.fish， 或者~/.config/fish/config.fish當 XDG_CONFIG_HOME 未設定時。魚類用途fish_command_not_found，因此未解析的命令到達ash及其原始論據。
為什麼不小寫test和type在魚？
Fish 將這些小寫名稱保留為基本內建函數，並且不允許函數取代它們。使用Test ...或者Type ...表達ash意圖或調用ash "..."直接地。其他相容的碰撞包裝器仍然可用。
ksh93呢？
shell 整合不支援 ksh93。它是FPATH行為只能載入以未知命令命名的檔案；它沒有可以安全實作的通用命令未找到回調ash提示路由或代理生命週期。
人工智慧與連接
做ash包括人工智慧嗎？
不。ash是您設定的 AI 端點的用戶端。放ASH_AI_ENDPOINT和ASH_AI_MODEL;ash支援本地 Ollama 和其他本地 OpenAI 相容伺服器（LM Studio、llama.cpp、MLX、LocalAI、vLLM、text- Generation-webui、Jan、GPT4All），並從端點偵測支援的雲端供應商適配器，並帶有可選的ASH_AI_PROVIDER覆蓋。
什麼是 MCP 伺服器？如何添加？
MCP（模型上下文協定）伺服器公開 AI 模型可以呼叫的工具，例如搜尋、分析或特定於服務的操作。預設情況下不啟用遠端伺服器。若要新增受信任的 Streamable HTTP MCP 伺服器，請使用ash mcp add <url>或將其 URL 新增至自己的行中$XDG_CONFIG_HOME/ash/.ash_allow(預設~/.config/ash/.ash_allow）。Ash透過其代理進行連接並向模型提供伺服器的工具。僅使用您信任的伺服器：他們的工具可能代表您執行操作。除本機主機開發伺服器外，都需要 HTTPS。如果MCP初始化失敗，ash無需遠端 MCP 工具即可繼續：它在互動式會話中發出警告，並在非互動式會話中保持靜默。
排程作業可以使用 MCP 伺服器嗎？
不可以。排程作業和其他非互動式作業不會繼承互動式 shell 的代理，因此遠端 MCP 工具不可用。Ash仍然在沒有 MCP 工具的情況下運行提示並抑制這種預期的初始化失敗。因此，依賴 MCP 的提示可能會在沒有請求的資料或操作的情況下完成。不要安排需要 MCP 的提示。
MCP 何時工作ASH_STRICT=1？
是的。 HTTP(S) URL 行明確註冊 MCP 伺服器，且不被視為 shell 執行檔。嚴格模式不會停用已設定的 MCP 伺服器。仍然適用Ash對傳回的工具內容的不可信輸出保護。
MCP OAuth 如何運作以及憑證儲存在哪裡？
對於受 OAuth 保護的伺服器，Ash當 GUI 可用時，在桌面瀏覽器中開啟授權頁面；如果無法開啟瀏覽器，則會列印 URL 以在同一主機上的瀏覽器中手動授權。使用ash mcp add <url> --no-browser始終使用終端流。對於直接 OAuth 連接，發現僅允許確切註冊的 MCP 機構使用非公共 IP 位址；其他 OAuth 主機仍然受到非公共位址封鎖。配置的出口代理負責過濾其目標位址。代理程式處理回呼、令牌交換、刷新和持久性 MCP 會話。憑證可用時儲存在作業系統憑證管理員中。如果不可用，請使用隨機 32 位元組配置加密檔案後備ASH_MCP_CREDENTIAL_KEY;Ash從不儲存密鑰本身。
在哪裡可以找到最受歡迎的雲端 AI 提供者的 AUTH_KEY？
ash用途ASH_AI_AUTH_TOKEN其可選的不記名令牌；它不建立或分發提供者金鑰。在您的提供者帳戶中建立金鑰，例如開放人工智慧,人擇,谷歌人工智慧工作室,Azure 開放人工智慧,米斯特拉爾,連貫,格羅克,人工智慧,深度搜尋,一起人工智慧,開放路由器,抱臉， 或者奧拉馬，然後將其匯出為提供者的環境變數（或設定ASH_AI_AUTH_TOKEN直接地）。ash install自動偵測受支援的特定於提供者的環境變數。雲端終端節點必須使用 HTTPS 並需要令牌（AWS Bedrock 除外）；私有/LAN 位址和.local主機名被視為本機主機名，除非ASH_STRICT=1已設定。
做ash每次都開啟新連線？
不適用於正常的互動式 Unix shell 使用。 Bash、zsh 和 Fish 為每個 shell 會話啟動一個代理，透過私有 Unix 套接字與其通信，並重複使用其有限的 HTTP 連接池。經紀商在不活動後退出；計劃作業使用直接請求而不是持久的 shell 代理。
Fish 使用經紀人嗎？
是的。 Fish 包装器启动并重用与 bash 和 zsh 相同的每会话代理，在ash請求，並使代理設定保持安靜。
如果請求速度緩慢、不可用或我改變了主意，會發生什麼情況？
按Ctrl-C取消飛行中的請求。預設AI請求超時時間為三分鐘；放ASH_AI_TIMEOUT， 例如ASH_AI_TIMEOUT=90s，更改它。ash預設情況下，可重試 AI 故障最多重試 3 次，並具有短的有界退避；調整該行為ASH_RETRY_MAX_ATTEMPTS,ASH_RETRY_BASE_DELAY， 和ASH_RETRY_MAX_DELAY。
安全與控制
我如何鎖定ash為了更安全，這會產生什麼影響？
縮小可執行白名單的範圍，支援只讀工具，並且不要添加特權或破壞性命令。放ASH_STRICT=1封鎖來自不受信任的工具、檔案、腳本、管道和子代理程式輸出的已識別提示注入模式。這也可以隱藏類似於注入嘗試的合法文字。允許清單是執行邊界，而不是沙箱：ash並且允許的工具仍然可以像您一樣運行。
能ash運行破壞性命令，例如rm？
不適用於已安裝的預設白名單。它明確建議反對rm,mv,dd,chmod,chown,kill， 和sudo。如果添加其中之一，ash可以在您的許可下請求；仔細審查該決定。
如何更改命令ash是否允許執行？
編輯$XDG_CONFIG_HOME/ash/.ash_allow(預設~/.config/ash/.ash_allow）並列出裸可執行檔名稱，每行一個或以逗號分隔。它是獨立的$TOOLS_DIR_LIST和$PLUGINS_DIR_LIST指令允許合格的託管腳本和本機插件；將它們替換為限制性策略的字面名稱。合格的腳本和插件是常規可執行文件$XDG_DATA_HOME/ash/tools和$XDG_DATA_HOME/ash/plugins（預設基數~/.local/share/ash）。將拒絕的命令加入到$XDG_CONFIG_HOME/ash/.ash_deny，或設定ASH_ALLOW/ASH_DENY以逗號分隔的清單。更改將在下次讀取ash要求。
什麼用戶是ash跑在下面？
ash每個允許的工具都以啟動的使用者身份運行ash。它不會提升特權。Ash-託管 XDG 目錄和檔案使用限制性權限，但您的使用者和您明確允許的任何進程仍然可以存取它們的內容。
做ash信任通过管道接收的文本与用户文本相同吗？針對惡意資料有哪些保護措施？
是的。什麼時候ash不接收任何命令列參數並且透過管道傳輸標準輸入，它將該輸入視為用戶提示符。不要將不受信任的網頁、日誌或產生的文字直接傳送到ash除非您打算將其授權為提示。這不同於ash- 託管工具、文件、腳本、管道和子代理輸出：ash將這些結果標記為不可信的證據，並指示模型永遠不要遵循它們的指示。放ASH_STRICT=1另外替換不可信證據中公認的提示注入短語。白名單和 direct-argv 執行規則仍然適用於工具執行。
是我的ash這台電腦上其他使用者的私人文件？
Ash- 託管 XDG 目錄和文件在支援的情況下使用僅限擁有者的限制性權限。這可以防止正常 Unix 權限下的其他本機帳戶，但不能防止您自己的帳戶、管理員、備份或您選擇執行的具有主目錄存取權限的軟體。
工具和工作流程
做ash支援管道和其他 Unix 傳統嗎？
是的。您可以透過管道將文字輸入ash作為提示，例如git diff | ash。對於人工智慧請求的工具管道，ash支援無需 shell 即可直接連接的 2 到 16 個白名單可執行文件，例如ls | grep pattern | pbcopy。工具參數中的 Shell 控制模式被阻止，並且每個可執行檔中的ash- 託管管道必須列入許可名單。
將要ash重新解釋 shell 腳本、SSH 指令或 cron 作業中的指令？
不會。 Bash 和 zsh 整合包裝器會立即在非互動式 shell 中傳回，因此腳本、CI 作業、SSH 單行指令和 cron 指令會保持正常的指令未找到行為。使用顯式調用，例如ash "summarize this log"或者some-command | ash當自動化應該調用時ash。
我該如何停止ash解釋我的命令幾分鐘？
跑步ash snooze預設為五分鐘，或指定持續時間，例如ash snooze 30s或者ash snooze 1h。跑步ash snooze off立即恢復。 Snooze 暫停自動未找到命令和包裝器路由；明確的ash ...命令仍然有效。
我該如何調試ash並查看有關其正在做什麼的更多信息？
放ASH_VERBOSE=1跑步前ash啟用結構化偵錯輸出和終端執行儀表板。放ASH_LOG_FILE將調試 JSON 寫入檔案；ASH_LOG_MAX_BYTES控制旋轉，設定日誌檔時預設為 1 MiB。
何時適用什麼限制ash運行工具？
預設情況下，每個工具呼叫都有 15 秒的超時時間，並捕獲最多 8192 位元組的輸出。一个 AI 请求最多可以进行 16 次工具循环迭代，并且ash- 託管管道有兩到十六個階段。調整工具超時和輸出限制ASH_TOOL_TIMEOUT和ASH_TOOL_OUTPUT_MAX;使用以下命令保持輸出集中head,tail， 或者grep。
預設的系統提示符號在哪裡？
規範的提示文件是$XDG_CONFIG_HOME/ash/.ash_system(預設~/.config/ash/.ash_system），運行時從捆綁的預設安裝ash install。 old 下的現有文件~/.ash工作區不會自動遷移或讀取。普通的$VARIABLE價值觀是從環境中擴展出來的，但是$TOOLS_DIR_LIST,$PLUGINS_DIR_LIST， 和$IF_PYTHON_AVAILABLE保留內部Ash替代品，絕不是環境衍生的。
我自己的腳本和本機插件應該放在哪裡ash作為工具來呼叫？
將用戶Python腳本放入$XDG_DATA_HOME/ash/tools/和本機二進位插件$XDG_DATA_HOME/ash/plugins/（預設基數~/.local/share/ash）。確保它們是可執行的，並將裸可執行名稱添加到$XDG_CONFIG_HOME/ash/.ash_allow（或依賴$TOOLS_DIR_LIST/$PLUGINS_DIR_LIST）。Ash不會為允許的 Unix 命令和插件呼叫 shell。
工具或外掛程式的最佳實踐是什麼，以便人工智慧了解其目的和用途？
遵循原生插件合約：公開可預測的 CLI 選項，實施--help,--version，以及版本化 JSON--ai-docs元數據，並描述輸入/輸出模式和故障行為。發出緊湊的結構化 JSONstatus字段和可操作的錯誤詳細信息，而不是與數據混合的散文。保持输出有限，验证输入，设置网络超时，并使工具可以安全地重复调用。將其裸檔名添加到$XDG_CONFIG_HOME/ash/.ash_allow;ash僅當它被列入白名單且未列出時才能執行$XDG_CONFIG_HOME/ash/.ash_deny。
提供的工具腳本和原生插件有哪些？
安裝的引導Python腳本是headlines.py,wikipedia.py， 和yfinance.py在$XDG_DATA_HOME/ash/tools/。提供的本機插件是what_time_is_it（去），flip_a_coin（鐵鏽），以及calculator（打字稿）在$XDG_DATA_HOME/ash/plugins/。
Rust 外掛程式（包括 flip_a_coin）僅隨 Linux 與 FreeBSD 提供。macOS 建置包含 what_time_is_it 與 calculator，但排除 Rust 外掛程式。
為什麼 macOS 缺少 Rust 外掛程式，如何手動建置並安裝？
macOS 不隨附 flip_a_coin 等 Rust 外掛程式，以便在 Linux 上交叉編譯兩種架構，不使用 macOS 執行器，降低 CI 成本。這不是相容性限制。Homebrew 仍提供 Go 與 TypeScript 外掛程式；Linux 與 FreeBSD 仍包含 Rust 外掛程式。
在 Mac 上安裝 Xcode 命令列工具（如有需要，執行 xcode-select --install），並透過 rustup 安裝 Rust。在要建立原始碼副本的位置執行以下命令。外掛程式自己的 Makefile 會為本機架構建置，並直接安裝至使用者外掛程式目錄，無需 sudo。
git clone https://github.com/Jonconradt/ash.git
cd ash
rustup toolchain install 1.99.0 --profile minimal
plugin_dir="${XDG_DATA_HOME:-$HOME/.local/share}/ash/plugins"
make -C internal/app/ash_bootstrap/plugins_src/flip_a_coin build BUILD_DIR="$plugin_dir"
"$plugin_dir/flip_a_coin" --version
"$plugin_dir/flip_a_coin" --ai-docs請使用外掛程式自己的 Makefile，而不是會在 macOS 跳過 Rust 的頂層 make plugins-build。在 ${XDG_CONFIG_HOME:-$HOME/.config}/ash/.ash_allow 中保留 $PLUGINS_DIR_LIST 或加入名稱 flip_a_coin，並確保它不在 .ash_deny 中。重新呼叫 ash 即可發現外掛程式。直接執行 "$plugin_dir/flip_a_coin" 可在沒有 AI 供應商的情況下測試。
能ash呼叫子代理？
是的。父代理可以使用run_sub_agent完成一項專注的、獨立的任務。子級繼承工作目錄、配置、工具和作業系統權限，傳回有界結果，無法建立另一個子級。預設最大值是每個父運行六個子代理，可以使用以下命令進行更改ASH_MAX_AGENTS。
能ash生成記憶體檔案來追蹤複雜的任務以及它在會話中學到了什麼？
是的。它可以在下面寫入持久性工作區文件$XDG_CONFIG_HOME/ash(預設~/.config/ash），在其工作區清單和會話範圍的臨時文件中進行跟踪$XDG_STATE_HOME/ash/scratch/<session-id>/（預設基數~/.local/state/ash）。 Scratch 是可選的：將其用於可重複使用腳本、中間資料、累積的發現或可修改的工件（當它們增加價值時）。它的工具是read_scratch_file,write_scratch_file,append_scratch_file,replace_scratch_file,edit_scratch_file， 和list_scratch_files。積極的Ash代理程式使用作業系統鎖定來保護其會話。解鎖的目錄被清除Ash僅在超過 48 小時且 24 小時內未訪問過後才退出；崩潰遺留的鎖定檔案不會阻止以後的清理。使用持久工作區文件來保存您想要保留的資訊。
能ash安排稍後的工作？
是的，透過其人工智慧工具。在 macOS 上，一次性調度使用每位用戶launchd啟動代理並需要launchctl。在 Linux 上，您的用戶支援循環計劃crontab;ash仅管理其自己的标记条目。一次性的launchd調度程式在 Linux 上不可用，因此請使用 cron 條目或其他 Linux 排程器來執行一次性 Linux 作業。計劃運行接收有限的環境並使用直接 HTTPS 而不是互動式 shell 代理，因此請確保所需的 AI 配置可用於排程作業。他們無法使用遠端 MCP 工具；Ash在沒有它們的情況下運行，並且不會在非互動式會話中發出警告。不要安排需要 MCP 的提示。
會話和存儲
歷史記錄或日誌檔案在哪裡ash？
對話歷史記錄以 JSON 形式儲存在$XDG_STATE_HOME/ash/history/(預設~/.local/state/ash/history/）。計劃的歷史記錄和調試日誌儲存在同一狀態目錄下。您可以選擇另一個調試日誌路徑ASH_LOG_FILE。
歷史文件保留多久？
ash在正常應用程式清理期間刪除超過 14 天的歷史 JSON 文件，清理預算為 300 毫秒，因此退出不會延遲。最近訊息視窗是獨立的：預設每個對話最多保留 40 個訊息，並且可以使用以下命令進行更改ASH_HISTORY_MAX。
如何清理對話或重新開始？
歷史記錄由會話 ID 和 AI 端點/模型金鑰分隔。為新的會話 ID 啟動新的終端會話，或刪除下面的相關 JSON 文件$XDG_STATE_HOME/ash/history/(預設~/.local/state/ash/history/）當您故意想要丟棄本地對話歷史記錄時。刪除歷史檔案不會撤銷提供者金鑰或刪除提供者端資料；與提供者單獨管理這些內容。
什麼是ASH_SESSION_ID它是在哪裡生成的？
它是Ash-擁有的每個會話標識符，用於分隔歷史記錄、暫存空間、代理套接字和計劃日誌名稱。託管 shell 環境在 shell 啟動時建立一個環境，並在重新取得資源時保留它；Ash為沒有 shell 提供的值的呼叫建立一個。一個通用的SESSION_ID被忽略。
我可以提供我自己的嗎ASH_SESSION_ID？
是的。Ash驗證顯式 ID 並拒絕無效值，而不是默默地替換它們。有效 ID 最多 128 個字符，並使用字母、數字、底線、連字符以及一個可選的子會話點後綴。不要使用不受信任或共享的值：衝突結合了會話歷史記錄和運行時狀態。
支持和社區
如何提交錯誤？
在以下位置開啟問題github.com/Jonconradt/ash/issues與ash版本或提交、您的作業系統和 shell、與已刪除機密的問題相關的配置、可重現的步驟以及觀察到的結果。對於安全漏洞，請勿公開發布問題；透過電子郵件或 GitHub 安全公告私下報告。