>_ ash

貢獻·建置·調試

開發人員指南

有關設定結帳、選擇產生目標、了解發佈建構器、診斷執行階段日誌以及在 Tart VM 中測試本機包安裝的實用指南。

設定開發者工具鏈

該專案使用 Go 作為 CLI 和代理，以及本機插件工具鍊和網站品質工具。在 macOS 上，make config使用自製軟體；在 Debian 或 Ubuntu 上它使用 apt。它安裝 Go、Node.js/npm、Python、uv、Rust/Cargo 以及該專案的 lint 和安全工具。儲存庫的 Go 模組指定建置所需的 Go 版本。

make config

打包 macOS 安裝程式也使用 Apple 的 Xcode 命令列工具。打包Linux.deb和.rpm工件需要 Ruby，fpm和 RPM 打包實用程式。安裝腳本安裝了常見的先決條件，但發布版本可能仍需要特定於平台的打包工具。

有關首次設定詳細資訊和貢獻期望，請參閱貢獻.md。

日常開發工作流程

對於正常的程式碼更改，請在迭代時執行重點測試，然後在完成之前執行儲存庫所需的 lint 和測試閘：

go test ./internal/app -run 'TestName'
make check-static
make check-security
make test

大多數 Make 目標使用scripts/dev/run-quiet.sh：成功的步驟印製一份簡明的ok行，而失敗的步驟則列印捕獲的輸出。目標前綴為V=1在運行時串流其完整輸出：

make V=1 lint
make V=1 test
make V=1 verify

V=1控制 Make 的安靜包裝器。它是獨立於ASH_VERBOSE，這使得運行時診斷成為可能Ash程式.

訂定目標參考

make pre-push
針對即將推送的確切提交執行靜態檢查、安全與相依性掃描、密鑰掃描和測試。make config會安裝存放庫管理的掛鉤。本機掛鉤可以略過，並非伺服器強制檢查。
make lint
檢查本地化目錄、網站安裝程式的 shell 語法、工作流程 YAML、Python lint/格式、Markdown、外掛程式 lint 和 Go lint。
make test
建置並測試本機插件，然後運行go test ./...。
make verify-ci
在建立 nightly 標籤前執行 pre-push 檢查。由標籤觸發的成品 CI 不會重複來源程式碼檢查。
make verify
運行完整的本地品質門：lint、測試、競賽測試、覆蓋、審查、靜態分析、安全性、秘密掃描、模糊測試和基準測試。
make test-race
使用競賽偵測器執行 Go 測試。
make test-cover
寫coverage.out並檢查總數COVERAGE_MIN（預設為 60%）。
make test-fuzz
運行應用程式模糊測試FUZZ_TIME（預設 10 秒）。
make security
執行 gosec、govulncheck 以及 npm、Cargo 和 Python 相依性稽核。
make build
運行 lint 和測試、建置和安裝本機插件以及構建ash加ash-broker在下面~/.local/bin。
make install
運行測試、lint、gosec和插件建置/安裝，建置兩個二進位文件，然後運行ash install --shell bash --shell-integration --overwrite。當您打算更新本地 Bash 整合時使用它。
make plugins-build,plugins-test,plugins-lint
建置、測試或檢查每個插件internal/app/ash_bootstrap/plugins_src。make plugins-clean刪除本機插件建置輸出。
make site-locales
產生翻譯頁面並刷新網站地圖。使用make site-locales SITE_LOCALES="zh-TW lb_LU"選擇區域設定。

make all運行verify進而install。完整的目標配方和可重寫變數位於產生檔案。

插件建構器

外掛程式是具有獨立於語言的契約的獨立可執行檔。外掛程式Makefiles選擇每個外掛程式的工具鏈；預設情況下，本地建置以主機為目標。發佈建置通行證PLUGIN_TARGET_GOOS和PLUGIN_TARGET_GOARCH因此 Rust 和其他非 Go 外掛程式二進位與發布工件相符。

使用make plugins-build將它們建構成bin/plugins,make plugins-test運行他們的測試，並且make plugins-install將它們複製到使用者插件目錄中。請參閱原生插件合約在新增或更改外掛程式之前。

發佈建置器和工件

品質檢查後，GitHub 在 Linux 上執行 make release-artifacts。一個 Ubuntu 工作交叉編譯供 Homebrew 使用的 Intel 與 Apple Silicon macOS 封存檔，不使用 macOS 執行器，也不產生 .pkg 安裝套件。macOS 目標（包括本機建置）排除所有 Rust 外掛程式，包括 flip_a_coin。Linux 與 FreeBSD 繼續包含 Rust 外掛程式。

CI 驗證 macOS 封存檔內容與 Mach-O 架構，但不執行其二進位檔案。Linux 與 FreeBSD 保留解壓縮封存檔的執行測試；不會安裝套件或設定 shell 整合。在 Linux 上建置 macOS：make release-artifacts RELEASE_TARGET_OSES=darwin RELEASE_TARGET_ARCHES="amd64 arm64" RELEASE_MACOS_PKG=0 RELEASE_VERSION=v1.2.3。make release 仍在 macOS 上建立本機 .pkg，不會向 CI 傳遞本機二進位檔案。

對於本機工件構建，請明確指定目標作業系統、架構和版本：

make release-artifacts \
  RELEASE_TARGET_OSES=linux \
  RELEASE_TARGET_ARCHES="arm64 amd64" \
  RELEASE_VERSION=v1.2.3

release-artifacts建置並驗證該目標支援的格式。預設值是主機作業系統（auto) 以及兩者amd64 arm64; FreeBSD 發佈僅限於amd64。文物被埋沒dist/release。對於單一二進位/插件構建，請使用make release-build-one RELEASE_GOOS=linux RELEASE_ARCH=arm64 RELEASE_VERSION=v1.2.3。

make version運行發布檢查並建立工件而不發布它們。相比之下，make release是一個發布工作流程：它需要 macOS、乾淨的工作樹和配置的 Git 身分、產生發行說明、建立/推送發行參考以及監視 GitHub 工作流程。它的預設管道是beta；選擇穩定或每晚CHANNEL=stable或者CHANNEL=nightly。產生的發行說明需要ASH_AI_ENDPOINT和ASH_AI_MODEL，除非附有註釋RELEASE_NOTES_INPUT。

閱讀發布工作流程和發布秘密指南在發布之前。

詳細的運行時日誌記錄

ASH_VERBOSE啟用結構化 JSON 偵錯日誌記錄並在先前列印執行儀表板Ash退出。接受的值為1,y,yes,true,on， 和debug，不區分大小寫。儀表板總結了階段時間、工具呼叫計數、可用令牌總數以及總實時時間。

ASH_VERBOSE=1 ash "investigate this error"

ASH_VERBOSE=1 \
ASH_LOG_FILE="$HOME/.local/state/ash/debug.jsonl" \
ASH_LOG_MAX_BYTES=10485760 \
ash "investigate this error"

什麼時候ASH_LOG_FILE設定後，詳細 JSON 日誌記錄將寫入該路徑；父目錄是根據需要建立的。ASH_LOG_MAX_BYTES控制旋轉並預設為1048576位元組 (1 MiB)。如果沒有顯式日誌文件，偵錯輸出將使用進程診斷編寫器。將日誌保密並在共享之前進行審查。

這與Make不同V=1： 使用V=1查看建置/測試命令輸出和ASH_VERBOSE=1診斷Ash運行時調用。

尋找日誌記錄的來源

每個 Ash 日誌記錄呼叫都有一個唯一的 EID 欄位。從 JSON 記錄中複製 EID 並在 Go 原始碼中搜尋其文字以找到呼叫網站：

rg '"EID", "EpbG2YtZ"' internal/

例如，來源呼叫將訊息和 EID 與結構化上下文一起記錄。 EID 是日誌位置的穩定識別碼：請勿翻譯、重新命名或重複使用它們。調試記錄器及其旋轉行為是在內部/應用程式/debuglog.go。

使用 vm.sh 測試本機軟體套件安裝

scripts/vm.sh 偵測主機作業系統並選擇虛擬機器後端：Apple Silicon macOS 上的 Tart 或 x86_64 Linux 上的 QEMU/KVM。两个后端都可以在 Ubuntu/Debian 上测试 APT，在 Fedora/Rocky Linux 上测试 DNF。 macOS 上的 Tart 还可以测试 macOS Homebrew 包； Linux 主机无法运行 macOS 来宾，因此无法测试该路径。

macOS 主機先決條件

使用運行 macOS 13 或更高版本的 Apple Silicon Mac，安裝了 Tart，可以透過網路存取 VM 映像和 Ash 儲存庫，並為 VM 提供足夠的磁碟空間。如果需要，使用 Homebrew 安装 Tart：

brew install openai/tools/tart

Linux 主機先決條件

使用啟用硬體虛擬化且具有讀寫權限的 x86_64 Linux 主機/dev/kvm（通常透過加入kvm群組並重新登入）。安裝 QEMU/KVM、cloud-image-utilscloud-localds、curl、OpenSSH 用戶端工具和 Python 3。範例包命令：

# Debian or Ubuntu
sudo apt-get install qemu-system-x86 qemu-utils cloud-image-utils curl openssh-client python3

# Fedora or Rocky Linux
sudo dnf install qemu-kvm qemu-img cloud-utils curl openssh-clients python3

Linux 後端使用 QEMU/KVM 和 cloud-init 啟動 x86_64 Ubuntu、Debian、Fedora 或 Rocky 雲端映像。它使用 QEMU 用戶模式網絡，並將 SSH 轉發到本地主機；不需要 libvirt 網路設定。它不運行 macOS 來賓，不在 macOS 上測試 Homebrew，目前需要 x86_64 Linux 主機。 Arch 和 FreeBSD 不是支援的目標。

運行包測試

自動模式是預設模式，並在測試後刪除虛擬機器。預設平台跟隨主機：macOS 選擇macos,Linux選擇ubuntu。明確選擇另一個支援的平台和模式。套餐通路預設為beta;使用--channel nightly,--channel beta， 或者--channel release選擇一個。--channel stable是一個別名release。

scripts/vm.sh --platform macos --mode interactive
scripts/vm.sh --platform ubuntu --channel nightly --mode automated
scripts/vm.sh --platform debian --mode interactive
scripts/vm.sh --platform fedora --mode automated
scripts/vm.sh --platform rocky --mode interactive

互動模式可使已安裝的虛擬機器保持運作以進行手動測試。在 macOS 上，在終端機中執行列印的 tart exec -it 命令以開啟來賓 shell。退出該 shell 會使虛擬機器繼續運作；關閉來賓或從主機停止它。若要停止並刪除保留的 Tart VM，請使用：

tart stop VM_NAME && tart delete VM_NAME

在 Linux 上，該腳本列印 SSH 命令和停止命令；停止虛擬機器並刪除其狀態：

scripts/vm.sh --stop VM_NAME

自動模式執行安裝和 shell 設定煙霧檢查，然後停止並刪除虛擬機器。下載的基礎鏡像仍然被快取。派圖可以改變ASH_TEST_VM_IMAGE; Linux 雲端影像 URL 可以覆蓋ASH_TEST_QEMU_IMAGE。 Linux 鏡像快取在${XDG_CACHE_HOME:-~/.cache}/ash/vm-images，互動式 VM 磁碟和 SSH 金鑰保存在${XDG_STATE_HOME:-~/.local/state}/ash/vm。放ASH_TEST_VM_CACHE_DIR或者ASH_TEST_VM_STATE_DIR更改這些位置。

為了讓訪客連接到與主機相同的AI服務，請匯出所需的ASH_AI_*運行腳本之前的變量，例如ASH_AI_ENDPOINT,ASH_AI_MODEL，並且，當需要時，ASH_AI_AUTH_TOKEN。導出的值轉送給客人；未匯出的 shell 變數則不然。互動式虛擬機器將這些憑證保留在來賓設定檔中的模式0600; Linux VM 磁碟未加密，因此請保護狀態目錄並在完成後停止/刪除 VM。

看scripts/vm.sh --help了解當前後端先決條件、支援的平台和選項。

專案原始碼指南