内容
# HUSK
适用于AI编码代理的原生可观察性和上下文工程。
从Claude Code（和其他代理）收集跟踪信息，将其存储为OTel跨度，运行trufflehog以查找泄露的机密，将成本和令牌使用情况按模型分解，并将会话压缩为知识，通过MCP注入到未来会话中。您可以通过Web UI查看任何会话中发生的事情。代理可以随时查询其自己的历史记录。
## 工作原理
```mermaid
graph LR
A[编码代理] -->|OTel跟踪信息| B[HUSK]
A -->|钩子| B
A <-->|MCP工具| B
B --> C[跟踪信息和跨度]
C --> D[知识管道]
D --> E[会话摘要]
E -->|上下文注入| A
C --> F[机密扫描器]
C --> G[使用情况分析]
```
HUSK接收遥测数据，将其存储为OTel格式的跟踪信息和跨度，然后运行三个管道：知识推导（将会话压缩为可搜索的记忆）、机密扫描（通过trufflehog标记泄露的凭证）和使用情况分析（成本、令牌、模型比较）。
```mermaid
graph TB
subgraph 采集
OTel[OTLP接收器]
Hooks[钩子端点]
API[自定义API]
end
subgraph 存储
SQLite[(SQLite)]
Postgres[(PostgreSQL)]
end
subgraph 智能
Knowledge[知识管道]
Secrets[机密扫描器]
Stats[使用情况分析]
Context[上下文引擎]
end
subgraph 接口
UI[Web仪表盘]
MCP[MCP工具]
Export[OTLP导出]
end
OTel --> SQLite
Hooks --> SQLite
API --> SQLite
OTel --> Postgres
SQLite --> Knowledge
SQLite --> Secrets
SQLite --> Stats
Knowledge --> Context
Context --> MCP
SQLite --> UI
SQLite --> MCP
SQLite --> Export
```
## 快速入门
```bash
git clone https://github.com/Saturate/HUSK.git
cd HUSK && bun install
# 完全本地，无需Docker，无需外部服务：
HUSK_EMBEDDINGS=transformers HUSK_STORAGE=sqlite-vec bun run server/src/index.ts
```
打开`http://localhost:3000/setup`以创建管理员账户。
### 连接Claude Code
HUSK接受Claude Code的原生OTel遥测数据。在您的Claude Code `settings.json`中添加：
```json
{
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:3000",
"OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf"
}
}
```
或通过Grafana Alloy路由到多个后端（HUSK + Grafana + Datadog + 支持OTLP的任意系统）。
对于MCP工具（搜索记忆、查询跟踪信息、压缩会话），请在`.mcp.json`中添加：
```json
{
"mcpServers": {
"husk": {
"type": "http",
"url": "http://localhost:3000/mcp",
"headers": { "Authorization": "Bearer husk_your-key" }
}
}
}
```
## 您将获得
**仪表盘**，包含成本卡、每日支出图表、项目分解、模型比较。
**会话跟踪**，包含可过滤的跟踪信息列表和跨度详情查看器，显示每个回合、工具调用和会话中的子代理。
**模型分析**，比较每个回合的令牌输出、每个回合的成本和模型家族的缓存命中率。（Opus 4.8每个回合输出的令牌是4.6的3倍。数据使这一点变得明显。）
**机密扫描**，由trufflehog提供支持。扫描跟踪信息数据中泄露的凭证，这些凭证是通过工具调用暴露给模型提供者的。在历史会话中找到真实的Storyblok和AbuseIPDB密钥泄漏。
**知识推导**，来自遥测数据。会话被压缩为结构化的摘要（询问了什么、做了什么、学到了什么、接下来是什么），并存储为可搜索的记忆。
**MCP工具**，代理可以在会话中使用：`cost_summary`、`tool_stats`、`get_trace_summary`、`get_trace_spans`、`compress_trace`、`scan_secrets`、`project_insights`。
## 架构
所有内容都可以通过提供者模式进行插拔：
| 层 | 选项 |
|---|---|
| **遥测数据存储** | SQLite（默认）、PostgreSQL |
| **遥测数据源** | OTLP接收器、自定义API、旧版钩子 |
| **嵌入** | Ollama、Transformers.js（本地）、OpenAI、Voyage、llama.cpp |
| **向量存储** | Qdrant、SQLite-vec（本地） |
| **压缩** | Anthropic、OpenRouter、Ollama |
| **图** | SQLite、Neo4j |
| **OTLP导出** | 可选的双重写入到任意OTLP后端 |
三种部署模式：
**独立**（本地SQLite，零配置）- 安装、运行、将Claude Code指向它。
**扇出目标**（在Alloy后面）- HUSK是除Grafana、Datadog等之外的OTLP目的地。
**Grafana支持**（未来）- HUSK从Tempo读取跟踪信息，仅拥有知识层。
## 配置
环境变量或`husk.toml`。环境变量优先级更高。
| 变量 | 默认值 | 功能 |
|---|---|---|
| `HUSK_TELEMETRY` | `sqlite` | 遥测后端（`sqlite`、`postgres`、`otlp`） |
| `HUSK_TELEMETRY_URL` | - | PostgreSQL连接字符串 |
| `HUSK_OTLP_AUTH` | `true` | 设置为`false`以启用本地OTLP无认证 |
| `HUSK_STORAGE` | `qdrant` | 向量后端（`qdrant`、`sqlite-vec`） |
| `HUSK_EMBEDDINGS` | `ollama` | 嵌入后端（`ollama`、`transformers`、`openai`、`voyage`） |
| `HUSK_COMPRESSION_MODE` | `client` | `client`（代理压缩）或`server`（自动） |
| `HUSK_PORT` | `3000` | 服务器端口 |
## 开发
```bash
bun install
cd server && bun run dev # 热重载
cd server && bun test # 312个测试
cd server && bun run check # 校验 + 格式化
cd server && bun run build:ui # 重建前端
```
## 许可证
MIT
