>_ 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了解当前后端先决条件、支持的平台和选项。

项目源码指南