xanstomper/PuppyPatch
GitHub: xanstomper/PuppyPatch
一款红队安全测试 AI 代理工具，在终端中整合了大量安全测试技术与引擎，辅助红队人员高效执行安全评估。
Stars: 0 | Forks: 0
# Crush
{ pkgs = import {}; }).repos.charmbracelet.crush'
```
### 通过 NUR 使用 NixOS 和 Home Manager 模块
Crush 通过 NUR 提供 NixOS 和 Home Manager 模块。
你可以通过从 NUR 导入这些模块，直接在你的 flake 中使用它们。由于它会自动检测当前是 home manager 还是 nixos 环境，因此你可以使用完全相同的导入方式 :)
```
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
nur.url = "github:nix-community/NUR";
};
outputs = { self, nixpkgs, nur, ... }: {
nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
nur.modules.nixos.default
nur.repos.charmbracelet.modules.crush
{
programs.crush = {
enable = true;
settings = {
providers = {
openai = {
id = "openai";
name = "OpenAI";
base_url = "https://api.openai.com/v1";
type = "openai";
api_key = "sk-fake123456789abcdef...";
models = [
{
id = "gpt-4";
name = "GPT-4";
}
];
};
};
lsp = {
go = { command = "gopls"; enabled = true; };
nix = { command = "nil"; enabled = true; };
};
options = {
context_paths = [ "/etc/nixos/configuration.nix" ];
tui = { compact_mode = true; };
debug = false;
};
};
};
}
];
};
};
}
```
或者，下载它：
- [安装包][releases] 提供 Debian 和 RPM 格式
- [二进制文件][releases] 支持 Linux、macOS、Windows、FreeBSD、OpenBSD 和 NetBSD
或者直接使用 Go 安装：
```
go install github.com/charmbracelet/crush@latest
```
## 快速上手
最快的上手方式是获取你首选提供商（例如 Anthropic、OpenAI、Groq、OpenRouter 或 Vercel AI Gateway）的 API key，然后直接启动
Crush。系统会提示你输入 API key。
不过，你也可以为首选的提供商设置环境变量。
| 环境变量 | 提供商 |
| --------------------------- | -------------------------------------------------- |
| `HYPER_API_KEY` | Charm Hyper |
| `ANTHROPIC_API_KEY` | Anthropic |
| `OPENAI_API_KEY` | OpenAI |
| `VERCEL_API_KEY` | Vercel AI Gateway |
| `GEMINI_API_KEY` | Google Gemini |
| `SYNTHETIC_API_KEY` | Synthetic |
| `ZAI_API_KEY` | Z.ai |
| `MINIMAX_API_KEY` | MiniMax |
| `HF_TOKEN` | Hugging Face Inference |
| `CEREBRAS_API_KEY` | Cerebras |
| `OPENROUTER_API_KEY` | OpenRouter |
| `IONET_API_KEY` | io.net |
| `ALIBABA_SINGAPORE_API_KEY` | Alibaba (Singapore) |
| `GROQ_API_KEY` | Groq |
| `AVIAN_API_KEY` | Avian |
| `OPENCODE_API_KEY` | OpenCode Zen & Go |
| `VERTEXAI_PROJECT` | Google Cloud VertexAI (Gemini) |
| `VERTEXAI_LOCATION` | Google Cloud VertexAI (Gemini) |
| `AWS_ACCESS_KEY_ID` | Amazon Bedrock (Claude) |
| `AWS_SECRET_ACCESS_KEY` | Amazon Bedrock (Claude) |
| `AWS_REGION` | Amazon Bedrock (Claude) |
| `AWS_PROFILE` | Amazon Bedrock (Custom Profile) |
| `AWS_BEARER_TOKEN_BEDROCK` | Amazon Bedrock |
| `AZURE_OPENAI_API_ENDPOINT` | Azure OpenAI models |
| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |
| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |
### 订阅
如果你更喜欢基于订阅的使用方式，以下是一些在 Crush 中运行良好的计划：
- [Synthetic](https://synthetic.new/pricing)
- [GLM Coding Plan](https://z.ai/subscribe)
- [Kimi Code](https://www.kimi.com/membership/pricing)
- [MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan)
### 顺便一提
你想在 Crush 中看到哪个提供商？现有的模型需要更新吗？
Crush 的默认模型列表在 [Catwalk](https://github.com/charmbracelet/catwalk) 中进行管理，这是一个社区支持的开源 Crush 兼容模型仓库，欢迎大家踊跃贡献。
## 配置
Crush 无需任何配置即可出色运行。不过，如果你确实需要或想要自定义 Crush，可以将配置添加到项目本地或全局，优先级如下：
1. `.crush.json`
2. `crush.json`
3. `$HOME/.config/crush/crush.json`
配置本身以 JSON 对象的形式存储：
```
{
"this-setting": { "this": "that" },
"that-setting": ["ceci", "cela"]
}
```
另外需要注意的是，Crush 还会将应用程序状态等临时数据存储在以下额外位置：
```
# Unix
$HOME/.local/share/crush/crush.json
# Windows
%LOCALAPPDATA%\crush\crush.json
```
### LSPs
Crush 可以像你一样使用 LSP 获取额外的上下文，以帮助其做出决策。可以像这样手动添加 LSP：
```
{
"$schema": "https://charm.land/crush.json",
"lsp": {
"go": {
"command": "gopls",
"env": {
"GOTOOLCHAIN": "go1.24.5"
}
},
"typescript": {
"command": "typescript-language-server",
"args": ["--stdio"]
},
"nix": {
"command": "nil"
}
}
}
```
### MCPs
Crush 还通过三种传输类型支持 Model Context Protocol (MCP) 服务器：用于命令行服务器的 `stdio`、用于 HTTP 端点的 `http`，以及用于 Server-Sent Events 的 `sse`。
Shell 风格的值展开（`$VAR`、`${VAR:-default}`、`$(command)`、引号、嵌套）可在 `command`、`args`、`env`、`headers` 和 `url` 中使用，因此基于文件的秘密可以直接开箱即用。你可以使用像 `"$TOKEN"` 或 `"$(cat /path/to/secret/token)"` 这样的值。展开操作通过 Crush 的内嵌 shell 运行，因此相同的语法在所有受支持的系统（包括 Windows）上都能工作。默认情况下，未设置的变量会展开为空字符串，这与 bash 的行为一致。对于必需的凭据，请使用 `${VAR:?message}`，这样在加载时如果变量未设置，会通过抛出 `message` 产生明确的报错，而不是静默解析为空：
```
{ "api_key": "${CODEBERG_TOKEN:?set CODEBERG_TOKEN}" }
```
值解析为空字符串的 Headers（无论是 MCP `headers` 还是提供程序的 `extra_headers`）都将从发出的请求中剔除，而不是作为 `Header:` 发送。这使得像 `"OpenAI-Organization": "$OPENAI_ORG_ID"` 这样基于环境变量的可选 headers 在变量未设置时保持干净。
提供程序的 `extra_body` 是一个不进行展开的 JSON passthrough；请将基于环境变量的值放在 `extra_headers` 或提供程序的 `api_key` / `base_url` 中，这些字段都会进行展开。
```
{
"$schema": "https://charm.land/crush.json",
"mcp": {
"filesystem": {
"type": "stdio",
"command": "node",
"args": ["/path/to/mcp-server.js"],
"timeout": 120,
"disabled": false,
"disabled_tools": ["some-tool-name"],
"env": {
"NODE_ENV": "production"
}
},
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"timeout": 120,
"disabled": false,
"disabled_tools": ["create_issue", "create_pull_request"],
"headers": {
"Authorization": "Bearer $GH_PAT"
}
},
"streaming-service": {
"type": "sse",
"url": "https://example.com/mcp/sse",
"timeout": 120,
"disabled": false,
"headers": {
"API-Key": "$(echo $API_KEY)"
}
}
}
}
```
### Hooks
Crush 已初步支持 hooks。有关详细信息，请参阅 [hook 指南](./docs/hooks/)。
### 跨客户端共享工作区
当 Crush 针对共享后端运行时（例如两个 TUI 与同一个 `crush serve` 通信），客户端会被分组到以其解析的 `--cwd` 为键的**工作区**中。两个具有相同 `--cwd` 的客户端将加入同一个底层工作区，因此它们共享会话列表、消息历史记录、权限队列、LSP 和 MCP 状态。
加入是隐式的：将第二个客户端指向同一个工作目录会将其附加到现有工作区。但是，默认情况下，每次新的调用都会在各自全新的会话中启动。要接手另一个客户端已经打开的对话，请使用会话管理器（会话选择器）并选择它。会话在那里会展示两个信号：
- 当该会话正在进行 agent turn 时，会设置 `IsBusy`。
- `AttachedClients` 报告当前正在查看它的客户端数量。
非零的 `AttachedClients`（通常与 `IsBusy` 结合使用）是一个信号，表明会话正在另一个客户端上“进行中”，加入它将实时镜像该视图。
创建工作区的第一个客户端会固定其进程范围的标志。特别是，`--yolo` 和 `--debug` 遵循**先到先得**规则：稍后到达相同 `--cwd` 且这些标志具有不同值的客户端不会更改正在运行的工作区。调试日志会记录这种不匹配，并且工作区将保留其创建时的标志。
只要至少有一个客户端在其上打开了 SSE 事件流，工作区就会一直存在。当最后一个流断开连接时，工作区将被销毁。在 `POST /v1/workspaces` 之后有一个短暂的宽限期，因此创建了工作区但尚未打开其事件流的客户端不会在附加之前就被清理掉。
### 全局上下文文件
Crush 会自动包含两个用于跨项目说明的文件。
- `~/.config/crush/CRUSH.md`：可能会让其他 agentic 编码工具产生混淆的 Crush 专属规则。如果你只使用 Crush，这是你唯一需要编辑的文件。
- `~/.config/AGENTS.md`：其他编码工具可能会读取的通用说明。避免在此处提及 Crush 特有的功能或工作流。只有当你使用多个 agentic 编码工具并希望在它们之间共享说明时，你可能才会关心这个文件。
你可以在配置中使用 `global_context_paths` 选项自定义这些路径：
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"global_context_paths": [
"~/path/to/custom/context/file.md",
"/full/path/to/folder/of/files/" // recursively load all .md files in folder
]
}
}
```
### 忽略文件
默认情况下，Crush 会遵循 `.gitignore` 文件，但你也可以创建一个 `.crushignore` 文件，以指定 Crush 应忽略的其他文件和目录。这对于排除那些你希望纳入版本控制但不希望 Crush 在提供上下文时考虑的文件非常有用。
`.crushignore` 文件使用与 `.gitignore` 相同的语法，可以放置在项目的根目录或子目录中。
### 允许工具
默认情况下，Crush 在运行 tool 调用之前会征求你的许可。如果你愿意，可以允许工具在执行时不提示权限。请谨慎使用此功能。
```
{
"$schema": "https://charm.land/crush.json",
"permissions": {
"allowed_tools": [
"view",
"ls",
"grep",
"edit",
"mcp_context7_get-library-doc"
]
}
}
```
你也可以通过在运行 Crush 时加上 `--yolo` 标志来完全跳过所有的权限提示。使用此功能时请务必格外小心。
### 禁用内置工具
如果你想完全阻止 Crush 使用某些内置工具，可以通过 `options.disabled_tools` 列表禁用它们。被禁用的工具将对 agent 完全隐藏。
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"disabled_tools": ["bash", "sourcegraph"]
}
}
```
要禁用来自 MCP 服务器的工具，请参阅 [MCP 配置部分](#mcps)。
### 禁用技能
如果你想完全阻止 Crush 使用某些技能，可以通过 `options.disabled_skills` 列表禁用它们。被禁用的技能会对 agent 隐藏，包括内置技能和从磁盘发现的技能。
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"disabled_skills": ["crush-config"]
}
}
```
### Agent 技能
Crush 支持 [Agent Skills](https://agentskills.io) 开放标准，通过可重用的技能包扩展 agent 的能力。技能是包含 `SKILL.md` 说明文件的文件夹，Crush 可以按需发现并激活它们。
我们寻找技能的全局路径包括：
* `$CRUSH_SKILLS_DIR`
* `$XDG_CONFIG_HOME/agents/skills` 或 `~/.config/agents/skills/`
* `$XDG_CONFIG_HOME/crush/skills` 或 `~/.config/crush/skills/`
* `~/.agents/skills/`
* `~/.claude/skills/`
* 在 Windows 上，我们_还会_查看
* `%LOCALAPPDATA%\agents\skills\` 或 `%USERPROFILE%\AppData\Local\agents\skills\`
* `%LOCALAPPDATA%\crush\skills\` 或 `%USERPROFILE%\AppData\Local\crush\skills\`
* 通过 `options.skills_paths` 配置的额外路径
除此之外，我们_还会_从你项目中的以下相对路径加载技能：
* `.agents/skills`
* `.crush/skills`
* `.claude/skills`
* `.cursor/skills`
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"skills_paths": [
"~/.config/crush/skills", // Windows: "%LOCALAPPDATA%\\crush\\skills",
"./project-skills",
],
},
}
```
你可以通过 [anthropics/skills](https://github.com/anthropics/skills) 中的示例技能快速上手：
```
# Unix
mkdir -p ~/.config/crush/skills
cd ~/.config/crush/skills
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . && rm -rf _temp
```
```
# Windows (PowerShell)
mkdir -Force "$env:LOCALAPPDATA\crush\skills"
cd "$env:LOCALAPPDATA\crush\skills"
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . ; rm -r -force _temp
```
#### 用户可调用的技能
技能可以被设置为从命令面板（Ctrl+P）作为命令调用。在技能 YAML frontmatter 中添加 `user-invocable: true`：
```
---
name: my-skill
description: A skill that can be invoked as a command.
user-invocable: true
---
```
用户可调用的技能将带有 `user:` 或 `project:` 前缀出现在命令面板中：
- 来自全局目录的技能显示为 `user:skill-name`
- 来自项目目录的技能显示为 `project:skill-name`
被调用时，该技能的指令会被加载到对话上下文中。
为了防止模型自动触发某个技能（同时仍允许用户调用），请添加 `disable-model-invocation: true`：
```
---
name: my-skill
description: Only invocable by users, not the model.
user-invocable: true
disable-model-invocation: true
---
```
带有 `disable-model-invocation` 的技能不会出现在模型的可用技能列表中，但仍可以由用户手动调用。
### 桌面通知
当 tool 调用需要权限以及 agent 完成其回合时，Crush 会发送桌面通知。它们仅会在终端窗口未获得焦点_且_你的终端支持报告焦点状态时发送。
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"disable_notifications": false, // default
},
}
```
要在配置中禁用桌面通知，请将 `disable_notifications` 设置为 `true`。在 macOS 上，由于平台限制，通知目前缺少图标。
### 初始化
当你初始化项目时，Crush 会分析你的代码库并创建一个上下文文件，帮助它在未来的会话中更高效地工作。
默认情况下，此文件命名为 `AGENTS.md`，但你可以使用 `initialize_as` 选项自定义名称和位置：
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"initialize_as": "AGENTS.md"
}
}
```
如果你偏好不同的命名约定，或者希望将文件放在特定目录（例如 `CRUSH.md` 或 `docs/LLMs.md`），这会非常有用。Crush 会将在初始化过程中发现的项目特定上下文（如构建命令、代码模式和约定）填充到该文件中。
### 归属设置
默认情况下，Crush 会将其创建的 Git commits 和 pull requests 的归属信息添加进去。你可以使用 `attribution` 选项自定义此行为：
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"attribution": {
"trailer_style": "co-authored-by",
"generated_with": true
}
}
}
```
- `trailer_style`：控制添加到 commit 消息中的归属 trailer（默认值：`assisted-by`）
- `assisted-by`：按照[约定](https://docs.kernel.org/process/coding-assistants.html#attribution)添加 `Assisted-by: Crush:[ModelID]`
- `co-authored-by`：添加 `Co-Authored-By: Crush `
- `none`：无归属 trailer
- `generated_with`：当为 true（默认值）时，将 `💘 Generated with Crush` 行添加到 commit 消息和 PR 描述中
### 自定义提供商
Crush 支持为兼容 OpenAI 和兼容 Anthropic 的 API 进行自定义提供商配置。
#### 兼容 OpenAI 的 API
这是一个使用 Deepseek（兼容 OpenAI API）的示例配置。不要忘记在你的环境中设置 `DEEPSEEK_API_KEY`。
```
{
"$schema": "https://charm.land/crush.json",
"providers": {
"deepseek": {
"type": "openai-compat",
"base_url": "https://api.deepseek.com/v1",
"api_key": "$DEEPSEEK_API_KEY",
"models": [
{
"id": "deepseek-chat",
"name": "Deepseek V3",
"cost_per_1m_in": 0.27,
"cost_per_1m_out": 1.1,
"cost_per_1m_in_cached": 0.07,
"cost_per_1m_out_cached": 1.1,
"context_window": 64000,
"default_max_tokens": 5000
}
]
}
}
}
```
#### 兼容 Anthropic 的 API
自定义兼容 Anthropic 的提供商遵循以下格式：
```
{
"$schema": "https://charm.land/crush.json",
"providers": {
"custom-anthropic": {
"type": "anthropic",
"base_url": "https://api.anthropic.com/v1",
"api_key": "$ANTHROPIC_API_KEY",
"extra_headers": {
"anthropic-version": "2023-06-01"
},
"models": [
{
"id": "claude-sonnet-4-20250514",
"name": "Claude Sonnet 4",
"cost_per_1m_in": 3,
"cost_per_1m_out": 15,
"cost_per_1m_in_cached": 3.75,
"cost_per_1m_out_cached": 0.3,
"context_window": 200000,
"default_max_tokens": 50000,
"can_reason": true,
"supports_attachments": true
}
]
}
}
}
```
### Amazon Bedrock
Crush 目前支持通过 Bedrock 运行 Anthropic 模型，但禁用了缓存。
- 当你配置好 AWS（例如执行 `aws configure`）后，Bedrock 提供商就会出现
- Crush 还期望设置了 `AWS_REGION` 或 `AWS_DEFAULT_REGION`
- 要使用特定的 AWS profile，请在你的环境中设置 `AWS_PROFILE`，例如 `AWS_PROFILE=myprofile crush`
- 除了使用 `aws configure` 之外，你也可以直接设置 `AWS_BEARER_TOKEN_BEDROCK`
### Vertex AI Platform
当设置了 `VERTEXAI_PROJECT` 和 `VERTEXAI_LOCATION` 后，Vertex AI 将出现在可用提供商列表中。你还需要完成身份验证：
```
gcloud auth application-default login
```
要将特定模型添加到配置中，请按以下方式配置：
```
{
"$schema": "https://charm.land/crush.json",
"providers": {
"vertexai": {
"models": [
{
"id": "claude-sonnet-4@20250514",
"name": "VertexAI Sonnet 4",
"cost_per_1m_in": 3,
"cost_per_1m_out": 15,
"cost_per_1m_in_cached": 3.75,
"cost_per_1m_out_cached": 0.3,
"context_window": 200000,
"default_max_tokens": 50000,
"can_reason": true,
"supports_attachments": true
}
]
}
}
}
```
### 本地模型
Crush 可以自动发现来自本地提供商的模型。添加一个 `type` 设置为 `omlx`、`lmstudio`、`litellm` 或 `ollama` 的自定义提供商，并省略模型列表。Crush 将自动填充模型列表。
```
{
"providers": {
"ollama": {
"name": "Ollama",
"base_url": "http://localhost:11434/v1/",
"type": "ollama"
}
}
}
```
#### 手动模型配置
你仍然可以显式列出模型。用户定义的模型始终优先于发现的模型，并且你设置的任何字段都不会被自动发现所覆盖。如果任何 `openai-compat` 提供商的模型列表为空，或者如果你传入了 `"discover_models": true`，自动发现将会运行，并将找到的模型与你手动配置的模型合并。
```
{
"providers": {
"ollama": {
"name": "Ollama",
"base_url": "http://localhost:11434/v1/",
"type": "ollama",
"models": [
{
"name": "Qwen 3 30B",
"id": "qwen3:30b",
"context_window": 256000,
"default_max_tokens": 20000
}
],
"discover_models": true
}
}
}
```
## 日志记录
有时你需要查看日志。幸运的是，Crush 会记录各种各样的内容。日志存储在相对于项目的 `./.crush/logs/crush.log` 中。
CLI 还包含一些辅助命令，以便更轻松地查看最近的日志：
```
# 打印最后 1000 行
crush logs
# 打印最后 500 行
crush logs --tail 500
# 实时追踪日志
crush logs --follow
```
想要更多日志？在运行 `crush` 时带上 `--debug` 标志，或者在配置中启用它：
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"debug": true,
"debug_lsp": true
}
}
```
## 提供商自动更新
默认情况下，Crush 会自动从 [Catwalk](https://github.com/charmbracelet/catwalk)（开源 Crush 提供商数据库）检查最新的提供商和模型列表。这意味着当有新的提供商和模型可用，或者模型元数据发生更改时，Crush 会自动更新你的本地配置。
### 禁用提供商自动更新
对于网络访问受限，或更喜欢在气隙环境中工作的用户来说，这可能不是你想要的，因此可以禁用此功能。
要禁用自动提供商更新，请在你的 `crush.json` 配置中设置 `disable_provider_auto_update`：
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"disable_provider_auto_update": true
}
}
```
或者设置 `CRUSH_DISABLE_PROVIDER_AUTO_UPDATE` 环境变量：
```
export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1
```
### 手动更新提供商
可以使用 `crush update-providers` 命令手动更新提供商：
```
# 从 Catwalk 远程更新 providers。
crush update-providers
# 从自定义 Catwalk base URL 更新 providers。
crush update-providers https://example.com/
# 从本地文件更新 providers。
crush update-providers /path/to/local-providers.json
# 将 providers 重置为 embedded 版本，该版本在构建时 embedded 于 crush 中。
crush update-providers embedded
# 了解更多信息：
crush update-providers --help
```
## 指标
Crush 会记录匿名的使用指标（绑定到特定设备的哈希值），维护者依靠这些指标来确定开发和支持的优先级。这些指标仅包含使用元数据；绝对不会收集 prompts 和响应。
有关收集内容的详细信息，请参阅源代码（[这里](https://github.com/charmbracelet/crush/tree/main/internal/event)和[这里](https://github.com/charmbracelet/crush/blob/main/internal/llm/agent/event.go)）。
你可以通过在环境中设置以下变量，随时选择退出指标收集：
```
export CRUSH_DISABLE_METRICS=1
```
或者在你的配置中设置以下内容：
```
{
"options": {
"disable_metrics": true
}
}
```
Crush 还遵循可以通过 `export DO_NOT_TRACK=1` 启用的 [`DO_NOT_TRACK`](https://donottrack.sh/) 约定。
## 问答
### 为什么剪贴板复制和粘贴不起作用？
在类 Unix 环境中，可能需要安装额外的工具。
| 环境 | 工具 |
| ------------------- | ------------------------ |
| Windows | 原生支持 |
| macOS | 原生支持 |
| Linux/BSD + Wayland | `wl-copy` 和 `wl-paste` |
| Linux/BSD + X11 | `xclip` 或 `xsel` |
## 贡献
请参阅[贡献指南](https://github.com/charmbracelet/crush?tab=contributing-ov-file#contributing)。
## 你觉得怎么样？
我们很乐意听听你对此项目的想法。需要帮助？包在我们身上。你可以通过以下方式找到我们：
- [Twitter](https://twitter.com/charmcli)
- [Slack][slack]
- [Discord][discord]
- [The Fediverse](https://mastodon.social/@charmcli)
- [Bluesky](https://bsky.app/profile/charm.land)
## 许可证
[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE.md)
[Charm](https://charm.land) 的一部分。
Charm热爱开源 • Charm loves open source
你的编程新搭档，现已登陆你最喜欢的终端。
将你的工具、代码和工作流，接入到你选择的 LLM 中。
终端里的编程新搭档，
无缝接入你的工具、代码与工作流，全面兼容主流 LLM 模型。
Nix (NUR)
Crush 可通过官方 Charm [NUR](https://github.com/nix-community/NUR) 中的 `nur.repos.charmbracelet.crush` 获取，这是在 Nix 中获取 Crush 的最新方法。 你也可以通过 NUR 使用 `nix-shell` 试用 Crush： ``` # 添加 NUR channel。 nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur nix-channel --update # 在 Nix shell 中获取 Crush。 nix-shell -p '(importDebian/Ubuntu
``` sudo mkdir -p /etc/apt/keyrings curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list sudo apt update && sudo apt install crush ```Fedora/RHEL
``` echo '[charm] name=Charm baseurl=https://repo.charm.sh/yum/ enabled=1 gpgcheck=1 gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo sudo yum install crush ```
## 配置
Crush 无需任何配置即可出色运行。不过，如果你确实需要或想要自定义 Crush，可以将配置添加到项目本地或全局，优先级如下：
1. `.crush.json`
2. `crush.json`
3. `$HOME/.config/crush/crush.json`
配置本身以 JSON 对象的形式存储：
```
{
"this-setting": { "this": "that" },
"that-setting": ["ceci", "cela"]
}
```
另外需要注意的是，Crush 还会将应用程序状态等临时数据存储在以下额外位置：
```
# Unix
$HOME/.local/share/crush/crush.json
# Windows
%LOCALAPPDATA%\crush\crush.json
```
### LSPs
Crush 可以像你一样使用 LSP 获取额外的上下文，以帮助其做出决策。可以像这样手动添加 LSP：
```
{
"$schema": "https://charm.land/crush.json",
"lsp": {
"go": {
"command": "gopls",
"env": {
"GOTOOLCHAIN": "go1.24.5"
}
},
"typescript": {
"command": "typescript-language-server",
"args": ["--stdio"]
},
"nix": {
"command": "nil"
}
}
}
```
### MCPs
Crush 还通过三种传输类型支持 Model Context Protocol (MCP) 服务器：用于命令行服务器的 `stdio`、用于 HTTP 端点的 `http`，以及用于 Server-Sent Events 的 `sse`。
Shell 风格的值展开（`$VAR`、`${VAR:-default}`、`$(command)`、引号、嵌套）可在 `command`、`args`、`env`、`headers` 和 `url` 中使用，因此基于文件的秘密可以直接开箱即用。你可以使用像 `"$TOKEN"` 或 `"$(cat /path/to/secret/token)"` 这样的值。展开操作通过 Crush 的内嵌 shell 运行，因此相同的语法在所有受支持的系统（包括 Windows）上都能工作。默认情况下，未设置的变量会展开为空字符串，这与 bash 的行为一致。对于必需的凭据，请使用 `${VAR:?message}`，这样在加载时如果变量未设置，会通过抛出 `message` 产生明确的报错，而不是静默解析为空：
```
{ "api_key": "${CODEBERG_TOKEN:?set CODEBERG_TOKEN}" }
```
值解析为空字符串的 Headers（无论是 MCP `headers` 还是提供程序的 `extra_headers`）都将从发出的请求中剔除，而不是作为 `Header:` 发送。这使得像 `"OpenAI-Organization": "$OPENAI_ORG_ID"` 这样基于环境变量的可选 headers 在变量未设置时保持干净。
提供程序的 `extra_body` 是一个不进行展开的 JSON passthrough；请将基于环境变量的值放在 `extra_headers` 或提供程序的 `api_key` / `base_url` 中，这些字段都会进行展开。
```
{
"$schema": "https://charm.land/crush.json",
"mcp": {
"filesystem": {
"type": "stdio",
"command": "node",
"args": ["/path/to/mcp-server.js"],
"timeout": 120,
"disabled": false,
"disabled_tools": ["some-tool-name"],
"env": {
"NODE_ENV": "production"
}
},
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"timeout": 120,
"disabled": false,
"disabled_tools": ["create_issue", "create_pull_request"],
"headers": {
"Authorization": "Bearer $GH_PAT"
}
},
"streaming-service": {
"type": "sse",
"url": "https://example.com/mcp/sse",
"timeout": 120,
"disabled": false,
"headers": {
"API-Key": "$(echo $API_KEY)"
}
}
}
}
```
### Hooks
Crush 已初步支持 hooks。有关详细信息，请参阅 [hook 指南](./docs/hooks/)。
### 跨客户端共享工作区
当 Crush 针对共享后端运行时（例如两个 TUI 与同一个 `crush serve` 通信），客户端会被分组到以其解析的 `--cwd` 为键的**工作区**中。两个具有相同 `--cwd` 的客户端将加入同一个底层工作区，因此它们共享会话列表、消息历史记录、权限队列、LSP 和 MCP 状态。
加入是隐式的：将第二个客户端指向同一个工作目录会将其附加到现有工作区。但是，默认情况下，每次新的调用都会在各自全新的会话中启动。要接手另一个客户端已经打开的对话，请使用会话管理器（会话选择器）并选择它。会话在那里会展示两个信号：
- 当该会话正在进行 agent turn 时，会设置 `IsBusy`。
- `AttachedClients` 报告当前正在查看它的客户端数量。
非零的 `AttachedClients`（通常与 `IsBusy` 结合使用）是一个信号，表明会话正在另一个客户端上“进行中”，加入它将实时镜像该视图。
创建工作区的第一个客户端会固定其进程范围的标志。特别是，`--yolo` 和 `--debug` 遵循**先到先得**规则：稍后到达相同 `--cwd` 且这些标志具有不同值的客户端不会更改正在运行的工作区。调试日志会记录这种不匹配，并且工作区将保留其创建时的标志。
只要至少有一个客户端在其上打开了 SSE 事件流，工作区就会一直存在。当最后一个流断开连接时，工作区将被销毁。在 `POST /v1/workspaces` 之后有一个短暂的宽限期，因此创建了工作区但尚未打开其事件流的客户端不会在附加之前就被清理掉。
### 全局上下文文件
Crush 会自动包含两个用于跨项目说明的文件。
- `~/.config/crush/CRUSH.md`：可能会让其他 agentic 编码工具产生混淆的 Crush 专属规则。如果你只使用 Crush，这是你唯一需要编辑的文件。
- `~/.config/AGENTS.md`：其他编码工具可能会读取的通用说明。避免在此处提及 Crush 特有的功能或工作流。只有当你使用多个 agentic 编码工具并希望在它们之间共享说明时，你可能才会关心这个文件。
你可以在配置中使用 `global_context_paths` 选项自定义这些路径：
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"global_context_paths": [
"~/path/to/custom/context/file.md",
"/full/path/to/folder/of/files/" // recursively load all .md files in folder
]
}
}
```
### 忽略文件
默认情况下，Crush 会遵循 `.gitignore` 文件，但你也可以创建一个 `.crushignore` 文件，以指定 Crush 应忽略的其他文件和目录。这对于排除那些你希望纳入版本控制但不希望 Crush 在提供上下文时考虑的文件非常有用。
`.crushignore` 文件使用与 `.gitignore` 相同的语法，可以放置在项目的根目录或子目录中。
### 允许工具
默认情况下，Crush 在运行 tool 调用之前会征求你的许可。如果你愿意，可以允许工具在执行时不提示权限。请谨慎使用此功能。
```
{
"$schema": "https://charm.land/crush.json",
"permissions": {
"allowed_tools": [
"view",
"ls",
"grep",
"edit",
"mcp_context7_get-library-doc"
]
}
}
```
你也可以通过在运行 Crush 时加上 `--yolo` 标志来完全跳过所有的权限提示。使用此功能时请务必格外小心。
### 禁用内置工具
如果你想完全阻止 Crush 使用某些内置工具，可以通过 `options.disabled_tools` 列表禁用它们。被禁用的工具将对 agent 完全隐藏。
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"disabled_tools": ["bash", "sourcegraph"]
}
}
```
要禁用来自 MCP 服务器的工具，请参阅 [MCP 配置部分](#mcps)。
### 禁用技能
如果你想完全阻止 Crush 使用某些技能，可以通过 `options.disabled_skills` 列表禁用它们。被禁用的技能会对 agent 隐藏，包括内置技能和从磁盘发现的技能。
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"disabled_skills": ["crush-config"]
}
}
```
### Agent 技能
Crush 支持 [Agent Skills](https://agentskills.io) 开放标准，通过可重用的技能包扩展 agent 的能力。技能是包含 `SKILL.md` 说明文件的文件夹，Crush 可以按需发现并激活它们。
我们寻找技能的全局路径包括：
* `$CRUSH_SKILLS_DIR`
* `$XDG_CONFIG_HOME/agents/skills` 或 `~/.config/agents/skills/`
* `$XDG_CONFIG_HOME/crush/skills` 或 `~/.config/crush/skills/`
* `~/.agents/skills/`
* `~/.claude/skills/`
* 在 Windows 上，我们_还会_查看
* `%LOCALAPPDATA%\agents\skills\` 或 `%USERPROFILE%\AppData\Local\agents\skills\`
* `%LOCALAPPDATA%\crush\skills\` 或 `%USERPROFILE%\AppData\Local\crush\skills\`
* 通过 `options.skills_paths` 配置的额外路径
除此之外，我们_还会_从你项目中的以下相对路径加载技能：
* `.agents/skills`
* `.crush/skills`
* `.claude/skills`
* `.cursor/skills`
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"skills_paths": [
"~/.config/crush/skills", // Windows: "%LOCALAPPDATA%\\crush\\skills",
"./project-skills",
],
},
}
```
你可以通过 [anthropics/skills](https://github.com/anthropics/skills) 中的示例技能快速上手：
```
# Unix
mkdir -p ~/.config/crush/skills
cd ~/.config/crush/skills
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . && rm -rf _temp
```
```
# Windows (PowerShell)
mkdir -Force "$env:LOCALAPPDATA\crush\skills"
cd "$env:LOCALAPPDATA\crush\skills"
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . ; rm -r -force _temp
```
#### 用户可调用的技能
技能可以被设置为从命令面板（Ctrl+P）作为命令调用。在技能 YAML frontmatter 中添加 `user-invocable: true`：
```
---
name: my-skill
description: A skill that can be invoked as a command.
user-invocable: true
---
```
用户可调用的技能将带有 `user:` 或 `project:` 前缀出现在命令面板中：
- 来自全局目录的技能显示为 `user:skill-name`
- 来自项目目录的技能显示为 `project:skill-name`
被调用时，该技能的指令会被加载到对话上下文中。
为了防止模型自动触发某个技能（同时仍允许用户调用），请添加 `disable-model-invocation: true`：
```
---
name: my-skill
description: Only invocable by users, not the model.
user-invocable: true
disable-model-invocation: true
---
```
带有 `disable-model-invocation` 的技能不会出现在模型的可用技能列表中，但仍可以由用户手动调用。
### 桌面通知
当 tool 调用需要权限以及 agent 完成其回合时，Crush 会发送桌面通知。它们仅会在终端窗口未获得焦点_且_你的终端支持报告焦点状态时发送。
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"disable_notifications": false, // default
},
}
```
要在配置中禁用桌面通知，请将 `disable_notifications` 设置为 `true`。在 macOS 上，由于平台限制，通知目前缺少图标。
### 初始化
当你初始化项目时，Crush 会分析你的代码库并创建一个上下文文件，帮助它在未来的会话中更高效地工作。
默认情况下，此文件命名为 `AGENTS.md`，但你可以使用 `initialize_as` 选项自定义名称和位置：
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"initialize_as": "AGENTS.md"
}
}
```
如果你偏好不同的命名约定，或者希望将文件放在特定目录（例如 `CRUSH.md` 或 `docs/LLMs.md`），这会非常有用。Crush 会将在初始化过程中发现的项目特定上下文（如构建命令、代码模式和约定）填充到该文件中。
### 归属设置
默认情况下，Crush 会将其创建的 Git commits 和 pull requests 的归属信息添加进去。你可以使用 `attribution` 选项自定义此行为：
```
{
"$schema": "https://charm.land/crush.json",
"options": {
"attribution": {
"trailer_style": "co-authored-by",
"generated_with": true
}
}
}
```
- `trailer_style`：控制添加到 commit 消息中的归属 trailer（默认值：`assisted-by`）
- `assisted-by`：按照[约定](https://docs.kernel.org/process/coding-assistants.html#attribution)添加 `Assisted-by: Crush:[ModelID]`
- `co-authored-by`：添加 `Co-Authored-By: Crush
Charm热爱开源 • Charm loves open source
标签：AI智能体, C2, EVTX分析, LLM集成, 发包工具, 域名收集, 安全测试, 攻击性安全, 日志审计, 终端TUI