Steventsang18/rupoo

# Rupoo — AI 驱动的终端助手 [中文版本](README_CN.md) | English Rupoo 是一个基于终端的 AI 助手，拥有原生 REPL 界面，支持代码块渲染、Markdown 渲染、主题切换，以及 Claude Code 风格的工具调用展示 —— 由三模式 agent 引擎（Chat + Plan + Loop）驱动。 ``` Version: 0.6.3 Language: Rust 2021 Lines: ~65,000 Tests: 373 ✅ Interface: Native REPL LLM: Anthropic / OpenAI / DeepSeek / Ollama DB: SQLite (FTS5) Memory: Hybrid Search (FTS5 + Vector) Safety: path_jail sandbox + SSRF protection + MCP auth + command blocklist hardening ``` ## ✨ 功能 | 功能 | 描述 | |---------|-------------| | **原生 REPL** | 流畅滚动，调整大小安全，无帧缓冲区 | | **代码块渲染** | Markdown pipeline 渲染代码块（主题颜色由主题系统控制） | | **Markdown 渲染** | 表格、引用、任务列表、代码块、链接 | | **主题系统** | `/theme dark\|light\|monokai` 支持持久化存储 | | **聊天气泡** | 用户右对齐 (▸)，AI 左对齐 (◂) | | **工具卡片** | Claude Code 风格的工具调用折叠卡片 | | **思维链** | 流式加载动画 + AI 推理气泡 | | **历史搜索** | `Ctrl+R` 增量搜索（1000 条记录） | | **三模式 Agent** | Chat 模式 + Plan 模式 + Loop 模式 | | **Loop 工程** | 自适应迭代执行：执行 → 评估 → 纠正 → 循环 | | **递归分解** | 自动将复杂目标拆解为独立子任务 | | **7 种步骤类型** | Think、ToolCall、WaitForInput、Exec、HttpRequest、BrowserAction、Finish | | **长期记忆** | SQLite FTS5 全文搜索 + 向量语义搜索 | | **混合搜索** | 结合 FTS5 关键词匹配 + 向量语义理解 | | **记忆开关** | 使用 `/memory on/off` 启用/禁用记忆 | | **深度搜索开关** | 使用 `/deep on/off` 启用/禁用混合搜索 | | **技能系统** | 基于 JSON 的技能，具备自动学习能力 | | **崩溃恢复** | 带有事务原子性的心跳检查点 | | **五层 Pipeline** | 包含认知层 → 规划层 → 监督层 → 执行层 → 记忆层的编排器 | | **基于 Trait 的架构** | 所有核心层均由 trait 定义，便于模拟测试和替换 provider | | **认知引擎** | 基于 LLM 的目标解析，带有安全边界检测和任务分解功能 | | **三层监督** | 合规检查器 → 置信度检查器 → 断路器串行拦截 | | **记忆系统桥接** | 统一的 `MemorySystem` trait，将传统存储与新架构桥接 | | **IM 频道集成** | 支持飞书 / 钉钉频道，通过 WebSocket 保持长连接 | ## 🔌 频道集成 Rupoo 可以在终端 CLI 旁作为 IM 机器人运行，支持飞书和钉钉。 ``` # 一键配置（自动验证 + 写入 config） rupoo feishu # Setup Feishu channel rupoo dingtalk # Setup DingTalk channel rupoo channels # List configured channels # 启动服务 rupoo serve # Foreground rupoo serve -d # Background daemon rupoo serve-stop # Stop daemon rupoo serve-status # Check daemon status ``` ### 频道功能 | 功能 | 描述 | |---------|-------------| | **WebSocket 长连接** | 通过长连接进行实时事件订阅 | | **自动重连** | 指数退避（2s → 最长 60s） | | **会话持久化** | 为每个发送者缓存 LRU 会话历史 | | **System Prompt 隔离** | 在 config.toml 中使用 `[agents.feishu]` / `[agents.dingtalk]` 配置 | | **斜杠命令** | `/new`、`/help`、`/status`、`/search ` | | **记忆来源标记** | CLI 记忆 (`source=agent`) 与频道记忆 (`source=channel`) 隔离 | | **跨源记忆查询** | `/search` 可跨所有记忆来源进行搜索 | | **丰富的回应表情** | 🔨 表示代码任务，👀 表示聊天，✅ 表示完成 | | **优雅关闭** | SIGTERM/SIGINT 会等待正在进行的任务完成 | | **守护进程模式** | 带有 PID 管理的后台进程 | ## 🚀 快速开始 ### 使用官方安装脚本安装（推荐） 一行安装脚本会下载最新的 release 版本，验证其 SHA-256 校验和，并将 `rupoo` 安装到您本地的 bin 目录： ``` # macOS / Linux curl -fsSL https://raw.githubusercontent.com/Steventsang18/rupoo/master/scripts/install.sh | sh # Windows (PowerShell 5.1+) powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/Steventsang18/rupoo/master/scripts/install.ps1 | iex" ``` 选项：`sh install.sh -v 0.6.3`（指定版本），`sh install.sh -d /opt/bin`（自定义目录）。 ### 下载预编译二进制文件 从[最新发布版本](https://github.com/Steventsang18/rupoo/releases/latest)下载适用于您平台的压缩包： | 平台 | 下载 | |----------|----------| | 🍎 **macOS Apple Silicon** (M1/M2/M3/M4) | `rupoo-v0.6.3-aarch64-apple-darwin.tar.gz` | | 🍎 **macOS Intel** | `rupoo-v0.6.3-x86_64-apple-darwin.tar.gz` | | 🐧 **Linux x86_64** | `rupoo-v0.6.3-x86_64-unknown-linux-gnu.tar.gz` | | 🐧 **Linux ARM64** (Raspberry Pi, AWS Graviton) | `rupoo-v0.6.3-aarch64-unknown-linux-gnu.tar.gz` | | 🪟 **Windows x86_64** | `rupoo-v0.6.3-x86_64-pc-windows-msvc.zip` | #### macOS ``` # 将 替换为你的平台 archive tar xzf rupoo-v0.6.3-aarch64-apple-darwin.tar.gz mv rupoo /usr/local/bin/ # 验证 rupoo --help ``` #### Linux ``` # x86_64 tar xzf rupoo-v0.6.3-x86_64-unknown-linux-gnu.tar.gz sudo mv rupoo /usr/local/bin/ # ARM64（例如 Raspberry Pi） tar xzf rupoo-v0.6.3-aarch64-unknown-linux-gnu.tar.gz sudo mv rupoo /usr/local/bin/ ``` #### Windows 1. 下载 `rupoo-v0.6.3-x86_64-pc-windows-msvc.zip` 2. 解压压缩包 3. 将 `rupoo.exe` 移动到您 `PATH` 中的目录（例如 `C:\Windows\System32\`，或创建一个自定义路径） 4. 打开一个新终端并运行 `rupoo --help` ### 从源码安装 ``` # 前提条件：Rust toolchain (https://rustup.rs) cargo install --path src-agent # 或者直接运行 cargo run --release ``` ### 配置 LLM ``` # Anthropic Claude rupoo config set api_key.anthropic sk-ant-xxx rupoo config set model.anthropic claude-sonnet-4-20250514 # OpenAI / DeepSeek rupoo config set api_key.openai sk-xxx rupoo config set model.openai deepseek-chat rupoo config set base_url.openai https://api.deepseek.com/v1 # Ollama（无需 API key） rupoo config set active_provider ollama rupoo config set model.ollama llama3 ``` ### 启动 ``` # 交互式 REPL（默认） rupoo ``` ## 🎯 v0.5.0 新特性 — 五层 Pipeline 架构 v0.5.0 引入了重大的架构 overhaul：一个正式的五层 pipeline，用定义明确、可独立测试的层取代了单体 agent 核心。 ### 五层编排器 ``` User Input │ ├─ Layer 1: Cognitive Engine ── parse goal, safety check, decompose ├─ Layer 2: Planner ── generate alternatives, score, select best ├─ Layer 3: Supervisor ── 3-gate intercept (compliance → confidence → circuit-breaker) ├─ Layer 4: Execution Engine ── validate input, run steps, detect replan └─ Layer 5: Memory System ── short-term / long-term / episodic recall ``` ### 基于 Trait 的架构 每一层都由 trait 定义，从而能够进行 mock 测试并在未来替换 provider： - **`CognitiveEngine`** — 将原始指令解析为 `AgentGoal`，检测安全边界违规情况，并分解复杂目标 - **`Planner`** — 生成替代执行计划，并根据成功概率/成本/风险进行评分 - **`Supervisor`** — 三门串行拦截：ComplianceChecker → ConfidenceChecker → CircuitBreaker - **`ExecutionEngine`** — 步骤验证，带有类型感知的参数检查和重新规划触发器 - **`MemorySystem`** — 统一 short-term、long-term 和 episodic 存储的 trait，支持混合召回 ### Supervisor 三门保护 ``` Action → Gate 1: Compliance (forbidden-command filter) → Gate 2: Confidence (semantic confidence threshold) → Gate 3: Circuit Breaker (failure-rate threshold) → Approved / Blocked ``` ### 记忆系统桥接 `MemorySystemBridge` 将旧版 `MemoryStore` 封装在新的 `MemorySystem` trait 之后，在提供向后兼容性的同时启用统一的召回路径。 ### 质量与安全 - **380 个单元测试** + **5 个集成测试**（orchestrator ×4，smoke ×1） - **Clippy 无警告** — 所有 target 均无警告 - **代码清理**：修复了内存泄漏（vector store `remove()`），占位符实现会发出运行时警告，项目全局应用了 `clippy --fix` - **安全对齐**：`SafetyContext` 现在会读取配置文件的默认值，并与运行时规则合并 ## 🎯 v0.6.0 新特性 — 优化与加固 v0.6.0 旨在解决两大技术债务 —— 安全边界和代码重复 —— 并增加了多项鲁棒性/用户体验改进（详见 `OPTIMIZATION-SUMMARY.md`）。 ### 统一的工具系统（最大的债务） - 添加了一个单独的 `rupoo_tools!` 宏作为**唯一的工具注册表**；`rig_tools.rs` / `mcp.rs` / `llm/providers.rs` 全部复用它，消除了三重定义。 - Provider agent 现在一致地包含了以前缺失的 `run_tests` / `check_output` / `diff_check` 工具。 ### 安全加固 - **MCP Server 认证**：通过 `RUPOO_MCP_TOKEN` 进行可选的 token 检查；未设置时向后兼容，但配置后 `initialize` 必须携带匹配的 `authToken`。 - **命令黑名单加固**：通过 PATH 解析真实的可执行文件名，并检测 `env` / `command` 包装器以阻止绕过。 - **SSRF 加固**：增加了 IPv6 本地链路地址拦截。 ### 性能与鲁棒性 - **频道会话 Token 预算**：每个会话的历史记录上限为 8000 个 token，以防止 context 膨胀；超大的单条消息会自动截断。 - **execute_nl 超时**：整个聊天轮次使用 `tokio::time::timeout` 封装（默认 600 秒，可通过 `chat_timeout_secs` 调整），以防止 agent 无限期挂起。 - 会话克隆的复杂度从 O(n²) 优化至 O(n)；飞书/钉钉共享全局 HTTP 连接池；飞书事件去重现在使用有界的 `LruCache`。 ### UX 与清理 - **TUI 消息时间戳**：用户/系统/错误气泡以及工作模式下的助手消息会显示 `[HH:MM:SS]`。 - 移除了未使用的 `syntect` 死代码依赖。 ### Ratatui 人性化伴侣 TUI（默认渲染器） 默认的 REPL 现在通过 **ratatui** 渲染为单列、IM 风格的聊天流 —— 表面极简，内在人性化。设置 `RUPOO_TUI=0`（或 `false`/`off`/`no`）可回退到经典的原始终端输出。 - **单列信息流** —— 不断向下增长的聊天流，顶部有细状态栏，底部有一行输入框。 - **内联人性化** —— AI 思考显示为柔和的斜体块，工具活动显示为内联的 `⏺` 行，阶段提示出现在流中；没有单独的面板。 - **IM 风格滚动** —— `follow` 固定到最新消息；`↑`/`↓` 平滑滚动，`PageUp`/`PageDown` 翻页滚动，`Ctrl+P`/`Ctrl+N` 调出历史记录，支持鼠标滚轮滚动。 - **实时运行状态面板** —— 右下角紧凑的面板会汇总活动工具（`⏺ 读取文件 2 · 网络搜索 1`）；按 `]` 可展开为一个微型活动日志，该日志在工作流结束时冻结。 - **对中断友好** —— `Esc` / `Ctrl-C` 可优雅地取消正在运行的轮次而不会退出。 所有渲染器行为均由 ratatui 快照测试覆盖 (`cargo test --bin rupoo`)。 ## 🎯 v0.4.0 新特性 ### 记忆系统 ``` # 查看 memory 状态 /memory # 启用/禁用 memory /memory on /memory off # 列出最近的 memory /memory list # 搜索 memory /memory search ``` ### 深度搜索（混合搜索） 深度搜索将 FTS5 全文搜索与向量语义搜索相结合，以提升相关性。 ``` # 检查 deep search 状态 /deep # 启用 deep search（FTS5 + Vector） /deep on # 禁用 deep search（仅 FTS5） /deep off ``` #### 混合搜索的工作原理 ``` User Query │ ├──► FTS5 Search (keyword matching) │ │ Fast, exact keyword matches │ └──► Vector Search (semantic understanding) │ Understands intent and meaning Combined Results (RRF ranking) ``` ## ⌨️ 快捷键 | 按键 | 操作 | |-----|--------| | `Enter` | 发送消息 | | `↑` / `↓` | 滚动聊天流（平滑） | | `PageUp` / `PageDown` | 滚动聊天流（翻页） | | `Ctrl+P` / `Ctrl+N` | 调出上 / 下一条输入历史 | | `]` | 切换运行状态面板 | | `Ctrl+R` | 增量搜索 | | `Ctrl+C` / `Esc` | 取消正在运行的操作 | | `Ctrl+D` | 退出 | | `Ctrl+L` | 清屏 | | `Tab` | 自动补全命令 | ## 📝 REPL 命令 | 命令 | 描述 | |---------|-------------| | `/new` | 新建对话 | | `/model` | 切换 LLM 模型 | | `/plan` | 进入 Plan 模式 | | `/loop ` | 启动自适应迭代循环 | | `/loop status ` | 显示循环状态 | | `/loop list` | 列出所有循环 | | `/loop pause\|resume\|cancel` | 管理正在运行的循环 | | `/memory` | 记忆管理 | | `/memory on/off` | 启用/禁用记忆 | | `/memory list` | 列出最近的记忆 | | `/memory ` | 搜索记忆 | | `/deep` | 深度搜索状态 | | `/deep on/off` | 启用/禁用混合搜索 | | `/theme dark\|light\|monokai` | 切换主题 | | `?` 或 `/help` | 显示帮助 | ## 🔧 CLI 命令 ``` rupoo [OPTIONS] [COMMAND] ``` | 命令 | 描述 | |---------|-------------| | _(无)_ | 启动交互式 REPL | | `demo` | 运行内置演示 | | `status` | 系统状态概览 | | `model [show\|list\|set]` | 管理 LLM provider | | `session [list\|show\|resume\|delete]` | 管理 plan | | `loops [start\|status\|list\|pause\|resume\|cancel]` | Loop 工程 | | `skills [list\|show\|install-builtin]` | 技能管理 | | `config [set\|get\|list]` | 配置管理 | | `git [status\|commit\|pr]` | Git 集成 | | `doctor [--fix]` | 诊断问题 | | `logs [--follow]` | 查看运行时日志 | | `mcp-server` | 启动 MCP 协议服务器 | ## 🔒 安全 | 保护措施 | 实现 | |------------|----------------| | 命令黑名单 | 拦截 20+ 个危险命令 | | 路径沙箱 | `path_jail` 防止路径遍历 | | SSRF 防护 | 拦截 localhost、内部 IP 和 IPv6 本地链路 | | MCP Server 认证 | 可选的 `RUPOO_MCP_TOKEN` token 验证 | | 命令黑名单加固 | 通过 PATH 解析真实二进制文件；检测 `env`/`command` 包装器 | | 超时保护 | 命令/HTTP/浏览器限制为 30 秒；聊天轮次超时为 600 秒 | | 环境净化 | 仅保留安全的环境变量 | | 输出截断 | 限制命令输出和文件读取 | ## 🏗️ 构建 ``` # Development build cargo build # Release build（推荐） cargo build --release # 支持 GUI cargo build --release --features gui ``` ## 🧪 测试 ``` # 运行所有测试 cargo test # 运行并输出详细日志 cargo test -- --nocapture # 运行特定测试 cargo test test_name # 运行 benchmark cargo bench ``` ## 📊 架构 ``` User Layer: ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Chat │ │ Plan │ │ Loop │ │ Commands │ │ Skills │ │ Mode │ │ Mode │ │ Mode │ │ System │ │ System │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ ┌────────┴─────────────┴─────────────┴─────────────┴─────────────┴────────┐ │ Orchestrator │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ Layer 1: CognitiveEngine (parse → safety-scan → decompose) │ │ │ │ Layer 2: Planner (generate → score → select) │ │ │ │ Layer 3: Supervisor (compliance → confidence → breaker) │ │ │ │ Layer 4: ExecutionEngine (validate → execute → replan) │ │ │ │ Layer 5: MemorySystem (short-term / long-term / episodic) │ │ │ └──────────────────────────────────────────────────────────────────┘ │ └───────────────────────────────┬──────────────────────────────────────────┘ │ ┌───────────────────────────────▼──────────────────────────────────────────┐ │ Agent Core Layer │ │ ┌──────────┐ ┌──────────────┐ ┌────────────────┐ ┌──────────────────┐ │ │ │ Agent │ │ LoopEngine │ │ MemorySystem │ │ LLM Gateway │ │ │ │ (bridge) │ │ (chat+plan) │ │ Bridge + Store │ │ (multi-provider) │ │ │ └──────────┘ └──────────────┘ └────────────────┘ └──────────────────┘ │ └──────────────────────────────────────────────────────────────────────────┘ ``` ## 📈 性能 | 指标 | 目标 | 状态 | |--------|--------|--------| | 冷启动 | < 2 秒 | ✅ | | LLM 调用延迟 | < 10 秒 | ✅ | | 工具执行超时 | < 5 秒 | ✅ | | 记忆搜索响应 | < 100 毫秒 | ✅ | | 信号压缩 | < 50 毫秒 | ✅ | ## 📚 文档 - [用户指南](docs/USER_GUIDE.md) - 全面的用户文档 - [性能](docs/PERFORMANCE.md) - 性能优化详情 - [CONTRIBUTING.md](CONTRIBUTING.md) - 贡献指南 ## 📝 更新日志 请查看 [CHANGELOG.md](CHANGELOG.md) 获取详细的版本历史。 ## 🤝 贡献 欢迎贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ## 📄 许可证 MIT 许可证 - 详情请见 [LICENSE](LICENSE)。 ## 🙏 致谢 - [rig-core](https://github.com/gregpr07/rig) - LLM agent 框架 - [rustyline](https://github.com/kknghk/rustyline) - Readline 实现

标签：AI助手, AI风险缓解, DLL 劫持, LLM, Petitpotam, Rust, Unmanaged PE, 可视化界面, 大语言模型, 本地REPL, 网络流量审计, 通知系统