入门
在使用之前我需要什么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;ashmanages only its own marked entries.一次性的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 安全公告私下报告。