blackaxgit/clx

# CLX - Claude Code 扩展 [](https://github.com/blackaxgit/clx/actions/workflows/ci.yml) [](https://mozilla.org/MPL/2.0/) [](#install-with-claude-code) 为 Claude Code 提供智能命令验证和上下文持久化。 ## 功能 - **命令验证** - 双层验证系统： - 第 0 层：快速的确定性白名单/黑名单规则（约 1ms） - 第 1 层：通过 Ollama 进行基于 LLM 的风险评估（约 100-300ms） - **上下文持久化** - 基于 SQLite 的存储，支持语义搜索： - 在上下文压缩前自动创建快照 - 用于语义召回的向量嵌入 - 会话历史和分析 - **自动召回** - 在每次提示时自动注入上下文： - 混合搜索：语义 (sqlite-vec) + FTS5 全文搜索 - 将相关的历史会话作为 `additionalContext` 注入 - 可配置的阈值、超时和结果限制 - 优雅降级：Ollama 宕机 → 回退到 FTS5 → 仅使用 orchestrator - **用户学习** - 适应您的工作流： - 跟踪已批准/拒绝的命令 - 根据使用模式自动生成规则 - **MCP 工具** - Claude 可以访问： - `clx_recall` - 搜索历史上下文 - `clx_remember` - 显式保存信息 - `clx_checkpoint` - 创建手动快照 - `clx_rules` - 管理验证规则 ## 快速安装 ### macOS (Homebrew) ``` brew tap blackaxgit/clx brew install clx ``` 这将安装 `clx`、`clx-hook` 和 `clx-mcp`。更新方式： ``` brew update && brew upgrade clx ``` ## 通过 Claude Code 安装 **1.** 确保 Ollama 正在运行： ``` ollama serve ``` **2.** 将以下内容粘贴到 Claude Code 中： ``` Install CLX from https://github.com/blackaxgit/clx: 1. Clone the repo and build: git clone https://github.com/blackaxgit/clx.git /tmp/clx && cd /tmp/clx && cargo build --release 2. Run the installer: ./target/release/clx install 3. Pull Ollama models: ollama pull qwen3:1.7b && ollama pull qwen3-embedding:0.6b 4. Add to PATH: echo 'export PATH="$HOME/.clx/bin:$PATH"' >> ~/.zshrc 5. Tell me to restart Claude Code when done ``` **3.** 重启 Claude Code。 **完成。** Hooks 将验证命令，上下文将被持久化，MCP 工具将可用。 ### 一行安装 (替代方案) ``` curl -fsSL https://raw.githubusercontent.com/blackaxgit/clx/main/install.sh | bash ``` ## 手动安装 **1. 安装前置条件：** ``` # Rust（如未安装） curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Ollama（如未安装）— 或从 https://ollama.com 下载 brew install ollama ollama serve # start the server ``` **2. 构建并安装 CLX：** ``` git clone https://github.com/blackaxgit/clx.git cd clx cargo build --release ./target/release/clx install ``` **3. 拉取所需的 Ollama 模型：** ``` ollama pull qwen3:1.7b ollama pull qwen3-embedding:0.6b ``` **4. 将 CLX 添加到您的 PATH 中：** ``` echo 'export PATH="$HOME/.clx/bin:$PATH"' >> ~/.zshrc source ~/.zshrc ``` **5. 重启 Claude Code**，然后验证： ``` clx dashboard ``` 您应该会看到包含会话历史和系统状态的交互式仪表板。 有关故障排除，请参阅 [INSTALL.md](INSTALL.md)。 ## 使用说明 ### CLI 命令 ``` # 检查状态 clx dashboard # 搜索上下文 clx recall "authentication bug" # 查看/编辑配置 clx config clx config edit # 管理规则 clx rules list clx rules allow "npm install *" clx rules deny "rm -rf /" # 检查系统健康状况 clx health # Colored table output clx health --json # Structured JSON output # 生成 shell completions (v0.2+) clx completions bash > ~/.clx-completion.bash clx completions zsh > ~/.clx-completion.zsh # 管理 embeddings (v0.2+) clx embeddings status # Check model and dimensions clx embeddings rebuild # Rebuild for model migration # 卸载 clx uninstall clx uninstall --purge # Also removes ~/.clx ``` ### 配置 编辑 `~/.clx/config.yaml`： ``` validator: enabled: true layer1_enabled: true # LLM validation layer1_timeout_ms: 30000 default_decision: "ask" # allow, deny, ask context: enabled: true auto_snapshot: true ollama: host: "http://127.0.0.1:11434" model: "qwen3:1.7b" embedding_model: "qwen3-embedding:0.6b" timeout_ms: 60000 user_learning: enabled: true auto_whitelist_threshold: 3 # Auto-add after N allows auto_blacklist_threshold: 2 # Auto-block after N denies logging: level: "info" file: "~/.clx/logs/clx.log" auto_recall: enabled: true max_results: 3 # Top-K results to inject similarity_threshold: 0.35 # Min relevance score (0.0-1.0) max_context_chars: 1000 # Max chars for recall context timeout_ms: 500 # Recall timeout per prompt fallback_to_fts: true # Use FTS5 if semantic fails include_key_facts: true # Include key facts in context min_prompt_len: 10 # Skip recall for short prompts ``` ### 自定义规则 编辑 `~/.clx/rules/default.yaml`： ``` whitelist: - pattern: "Bash(npm:test*)" description: "Allow npm test commands" - pattern: "Bash(cargo:build*)" description: "Allow cargo build" blacklist: - pattern: "Bash(rm:-rf /*)" description: "Block recursive delete from root" - pattern: "Bash(curl:*|bash)" description: "Block pipe to shell" ``` ### 自定义 LLM 提示词 编辑 `~/.clx/prompts/validator.txt` 以自定义风险评估。 ## 工作原理 ### 命令验证流程 ``` Claude requests command ↓ PreToolUse hook fires ↓ Layer 0: Check whitelist/blacklist ├─ Match whitelist → Allow ├─ Match blacklist → Deny └─ Unknown → Continue ↓ Layer 1: Ollama risk assessment ├─ Score 1-3 → Allow ├─ Score 4-7 → Ask user └─ Score 8-10 → Deny ↓ User confirms (if Ask) ↓ Command executes ↓ PostToolUse logs result ``` ### 上下文持久化流程 ``` PreCompact hook fires (before compression) ↓ Read transcript from JSONL file ↓ Generate summary via Ollama ↓ Store snapshot in SQLite ↓ Generate embedding for search ↓ Context available via clx_recall ``` ## 项目结构 ``` clx/ ├── crates/ │ ├── clx-core/ # Core library │ │ └── src/ │ │ ├── config.rs # Configuration management │ │ ├── storage/ # SQLite storage (sessions, snapshots, rules) │ │ ├── policy/ # Command validation (L0 rules + L1 LLM) │ │ ├── recall.rs # Hybrid search engine (semantic + FTS5) │ │ ├── ollama.rs # Ollama client │ │ └── embeddings.rs # Vector search │ ├── clx-hook/ # Hook handler binary │ ├── clx-mcp/ # MCP server binary │ └── clx/ # CLI binary + dashboard ├── scripts/ # Docker compose, service management, packaging ├── install.sh # Build-from-source installer ├── INSTALL.md # Installation guide └── CONTRIBUTING.md # Contribution guide ``` ## 开发 ``` # 构建 cargo build # 测试 cargo test # 运行并启用详细日志记录 RUST_LOG=debug ./target/debug/clx dashboard ``` ## 贡献 有关开发设置和指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 MPL-2.0

标签：AI风险缓解, Apex, Claude, Claude Code, CVE检测, DLL 劫持, Homebrew, LLM评估, MCP工具, Ollama, Rust, SOC Prime, SQLite, 上下文持久化, 可视化界面, 向量搜索, 命令行扩展, 命令验证, 大语言模型, 威胁情报, 安全防护, 开发工具, 开发者工具, 文本嵌入, 本地大模型, 机器学习, 白名单/黑名单, 网络流量审计, 自动化规则, 自适应学习, 语义搜索, 通知系统