>_ ash

用户命令·ash(1)

ash文档

用于命令未找到工作流程的实用 shell 助手。此页面是可安装的网络版本ash(1)手册页。

在 Debian 或 Ubuntu 上安装

请参阅APT安装指南有关先决条件、签名密钥、存储库设置、通道、更新和删除的信息。

在 Fedora 或 RHEL 兼容的 Linux 上安装

请参阅DNF安装指南用于先决条件、元数据验证、存储库设置、通道、更新和删除。

在 Arch Linux 上安装

请参阅吃豆人安装指南用于先决条件、密钥验证、存储库设置、通道、更新和删除。

概要

ash [text ...]
ash install [--shell bash|zsh] [--dry-run] [--overwrite]
ash mcp add <url> [--no-browser]
ash snooze [duration|off]
ash update [--version vX.Y.Z] [--yes|--skip-customized]

描述

ash向配置的 AI 端点发送提示文本并打印助理响应。当没有提供位置文本时，ash从非交互式标准输入读取提示文本。

这install子命令安装托管资产。仅当您明确请求时才会更改 Shell 启动文件--shell-integration; bash 使用~/.bashrc,zsh 使用~/.zshrc，和鱼使用$XDG_CONFIG_HOME/fish/config.fish。

与人工智能提供商的连接通过本地代理共享。代理故障会退回到直接 HTTPS。

AI可以使用systemd来安排后台任务。这些工作可以是重复性工作，也可以是一次性工作。默认情况下，计划作业使用直接 HTTPS。

ash以下是 XDG 基本目录：配置和持久工作区文件$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）。代理套接字使用$XDG_RUNTIME_DIR/ash具有状态目录后备。显式 XDG 路径必须是绝对路径。

工具、脚本、文件、管道和子输出是不受信任的数据，不得覆盖系统或用户指令。当启用任意 Python 或 shell 执行时，工具执行功能不是沙箱。默认情况下，Python 是启用的，所以要小心。

远程 MCP 服务器

MCP（模型上下文协议）服务器提供 AI 模型可以调用的工具。Ash支持远程 Streamable HTTP MCP 服务器并保持其客户端会话ash-broker穿过Ash在同一个 shell 中调用。

通过运行注册受信任的服务器ash mcp add <url>从互动的Ashshell，或者将其 URL 添加到$XDG_CONFIG_HOME/ash/.ash_allow（默认~/.config/ash/.ash_allow）。默认情况下不启用远程服务器。

当 GUI 可用时，OAuth 授权将在桌面浏览器中打开。如果浏览器打不开，Ash打印可复制的授权 URL 并在终端中等待。使用ash mcp add <url> --no-browser始终使用此终端流。手动URL授权仍然需要同一主机上的浏览器；它不是无浏览器的 OAuth 流程。

URL 行开头为http://或者https://是 MCP 注册，而不是 shell 命令。方案的识别不区分大小写。Ash从修剪后的 URL 文本上的 SHA-256 的前 8 个小写十六进制字符派生服务器的本地名称。除localhost开发外都需要HTTPS；带有嵌入凭据、查询字符串或片段的 URL 将被拒绝。对于直接 OAuth 连接，发现仅允许确切注册的 MCP 机构使用非公共 IP 地址；其他 OAuth 主机仍然受到非公共地址阻止。配置的出口代理负责过滤其目标地址。更改将在下一次读取Ash要求。

MCP 注册保持启用状态ASH_STRICT=1。返回的工具输出仍然被视为不可信的证据。仅注册您信任的服务器：他们的工具可能代表您执行操作。对于 OAuth 保护的服务器，Ash当 GUI 可用时打开浏览器，同时代理处理回调和令牌。凭证使用操作系统凭证管理器（如果可用）或由用户提供的随机 32 字节保护的加密文件ASH_MCP_CREDENTIAL_KEY在$XDG_DATA_HOME/ash/mcp/。

如果MCP初始化失败，Ash无需远程 MCP 工具即可继续请求。交互式运行打印警告；非交互式运行会悄悄失败。计划作业没有每交互式 shell 代理，因此无法使用远程 MCP 工具。依赖于 MCP 的计划提示可能仍会运行，但可能会在没有请求的 MCP 操作或数据的情况下完成。不要安排需要 MCP 的提示。

请参阅MCP常见问题解答快速概览和设置说明。

命令

ash [--attach path]... [text ...]
运行单个助理请求。--attach将文件（图像或文档）附加到请求中；可重复的。尺寸限制于ASH_ATTACHMENT_MAX_BYTES目前仅通过网络发送给 OpenAI 兼容的提供商。
ash mcp add <url> [--no-browser]
连接并注册有效的远程 MCP 服务器.ash_allow。在桌面浏览器中打开 OAuth 授权（如果可用）；回退到终端中的可复制 URL。--no-browser始终使用终端流。
ash install [--shell bash|zsh|fish] [--shell-integration|--disable-shell-integration] [--dry-run]
默认情况下安装资产而不更改 shell 启动文件。--shell-integration选择添加/更新托管块；--disable-shell-integration仅删除该块并保留周围的用户内容。交互时，安装自动配置ASH_AI_ENDPOINT,ASH_AI_MODEL， 和ASH_AI_AUTH_TOKEN需要时，在显示提供程序菜单之前首选现有提供程序密钥或本地端点。
ash snooze [duration|off]
暂停自动 shell 提示处理。默认值为五分钟。持续时间使用 Go 语法，例如30s,5m， 或者1h。使用off立即恢复。
ash update [--version vX.Y.Z] [--yes|--skip-customized]
下载适用于当前架构的最新稳定 macOS、Linux 或 FreeBSD 版本并将其安装到~/.local/bin/ash。发布需要 Sigstore 验证和 SHA-256 验证。

环境

ASH_AI_AUTH_TOKEN
可选的不记名令牌。对于除 AWS Bedrock 之外的云终端节点而言是必需的。专用/LAN 地址和.local主机名被视为非云，除非ASH_STRICT=1。
ASH_AI_CACHE
可选的提供者本机缓存切换。支持时默认启用；接受1,true,yes,on,enabled,0,false,no,off， 或者disabled（不区分大小写）。
ASH_AI_ENDPOINT
聊天 API 端点所需的基本 URL。
ASH_AI_MODEL
发送到端点的所需模型名称。
ASH_AI_PROVIDER
可选的提供商覆盖。未设置时，ash从端点检测提供者。
ASH_AI_TIMEOUT
可选的请求超时。默认：3m。
ASH_ALWAYS_OPENAI_API
可选测试切换。当类似 true 时，路由ollama通过 OpenAI 兼容的 SDK 适配器而不是手动实现来提供程序。接受与以下相同的布尔值ASH_AI_CACHE。默认值：打开。
ASH_ATTACHMENT_MAX_BYTES
通过以下方式传递的文件的可选最大大小（以字节为单位）--attach。默认：10485760（10 MiB）。
ASH_HISTORY_MAX
每个键可选的最大历史消息数。默认：40。
ASH_LOG_FILE
启用详细日志记录时可选的调试日志路径。
ASH_LOG_MAX_BYTES
旋转前可选的最大日志大小。默认：1048576。
ASH_MAX_AGENTS
一个父进程生成的可选最大子代理数。默认：6。
ASH_MAX_TOOL_ITERS
可选的最大 AI 工具调用循环迭代。默认：16。
ASH_RELEVANCE_WINDOW
执行状态中包含可选的最近工具观察结果。默认：4。
ASH_RETRY_BASE_DELAY
可选的重试退避基本延迟。默认：250ms。
ASH_RETRY_MAX_ATTEMPTS
可选的可重试请求尝试。默认：3。
ASH_SCHEDULED_TASK
使用的内部调度程序标志ash- 托管调用。
ASH_STREAM
可选切换。当 true-like 时，流式传输来自其适配器支持它的提供者的响应（当前仅限 OpenAI）。接受与以下相同的布尔值ASH_AI_CACHE。默认值：打开。
ASH_TASK_MAX
从请求派生的执行任务的可选上限。默认：6。
ASH_TASK_STALL_ROUNDS
可选的助理在停车前进行失速轮巡。默认：2。
ASH_ALLOW
可选的以逗号分隔的可执行白名单run_unix_command。否则$XDG_CONFIG_HOME/ash/.ash_allow（默认~/.config/ash/.ash_allow）被使用；此覆盖不会扩展内部Ash代币。
ASH_DENY
可选的以逗号分隔的拒绝列表，用于显式阻止命令、工具和插件。否则$XDG_CONFIG_HOME/ash/.ash_deny（默认~/.config/ash/.ash_deny）被使用。
ASH_TOOL_OUTPUT_MAX
可选的最大捕获工具输出（以字节为单位）。默认：8192。
ASH_TOOL_TIMEOUT
可选的本地工具命令超时。默认：15s。
ASH_VERBOSE
可选的调试日志记录和执行仪表板。值如1,true,on， 和debug启用它。
ASH_SESSION_ID
Ash持久历史记录和日志命名的会话标识符。缺席时生成；无效的显式值将被拒绝。通用的SESSION_ID被忽略。

明确的数字和持续时间设置经过验证。整数限制必须为正，除了ASH_MAX_TOOL_ITERS，可能为零。 AI/工具超时必须是正值；重试延迟可能为零但不是负值。持续时间使用 Go 语法，例如30s,5m， 或者1h。格式错误或超出范围的值会产生配置错误，而不是默默地使用默认值。

文件

  • $XDG_CONFIG_HOME/ash/（默认~/.config/ash/）—规范的提示、策略和持久工作区文件。
  • $XDG_DATA_HOME/ash/（默认~/.local/share/ash/）—捆绑的工具、插件、语言包和 MCP 凭证。
  • $XDG_STATE_HOME/ash/（默认~/.local/state/ash/）—历史记录、暂存、日志和暂停状态。
  • $XDG_CACHE_HOME/ash/（默认~/.cache/ash/）—可重新生成的缓存文件。

退出状态

ash 成功时返回 0。当配置、网络请求或工具执行失败时，它返回非零。

示例

echo "summarize this directory" | ash
ash install --shell bash
ash install --shell zsh --dry-run

参见

bash(1),zsh(1),man(1)

来源：文档/ash.1·自述文件·安全政策