bug-ops/zeph

Zeph 是一个 Rust AI 代理，围绕一个核心原则构建：**上下文窗口中的每一个 token 都必须物有所值**。技能通过语义检索获取，工具输出在注入前经过过滤，上下文在压力下自动压缩 —— 从而在您现有的硬件上保持低成本和快速响应。 ``` curl -fsSL https://github.com/bug-ops/zeph/releases/latest/download/install.sh | sh zeph init # interactive setup wizard zeph migrate-config --config config.toml --diff # check for new options after upgrade zeph # start the agent ``` ## 快速开始 **本地 (Ollama)** — 无需云账号： ``` ollama pull qwen3:8b && ollama pull qwen3-embedding zeph init && zeph ``` **云端 (Claude 或 OpenAI)**： ``` export ZEPH_CLAUDE_API_KEY=sk-ant-... # or ZEPH_OPENAI_API_KEY zeph init && zeph ``` **混合模式** — 默认 Ollama，云端作为回退： ``` export ZEPH_CLAUDE_API_KEY=sk-ant-... # 在 `zeph init` 中选择 "router"，或复制下面的 hybrid recipe zeph ``` ## 功能概览 | 功能 | 描述 | |---|---| | **混合推理** | Ollama、Claude、OpenAI、Google Gemini、任何 OpenAI 兼容 API，或通过 Candle (GGUF) 完全本地运行。Gemini 支持 SSE 流式传输、思维部分展示（Gemini 2.5）以及流式 `functionCall` 部分。多模型编排器支持回退链、EMA 延迟路由，以及用于平衡探索/利用的自适应 Thompson Sampling 模型选择。级联路由支持 `cost_tiers` 用于显式的最便宜优先提供商排序，以及 `ClassifierMode::Judge` 用于 LLM 评分的查询路由。Claude 扩展上下文（`--extended-context` 标志或 `enable_extended_context = true`）启用 1M token 窗口，并在 TUI 中显示 `[1M CTX]` 标题标记；自动发出成本警告。内置定价包含 gpt-5 和 gpt-5-mini。[→ Providers](https://bug-ops.github.io/zeph/concepts/providers.html) | | **技能优先架构** | YAML+Markdown 技能文件，配备 BM25+cosine 混合检索。贝叶斯重排序、4 级信任模型，以及自学习进化 —— 技能从实际使用中不断改进。Agent-as-a-Judge 反馈检测配合自适应 regex/LLM 混合分析。`load_skill` 工具允许 LLM 按需获取活跃 TOP-N 集合之外任何技能的完整内容。[→ Skills](https://bug-ops.github.io/zeph/concepts/skills.html) · [→ Self-learning](https://bug-ops.github.io/zeph/advanced/self-learning.html) | | **上下文工程** | 语义技能选择、命令感知输出过滤器、带有延迟应用的工具对摘要（急切预计算、延迟应用以稳定 Claude API prompt cache 前缀）、主动上下文压缩（反应式 + 主动式策略），以及反应式中向外压缩，确保窗口在任何负载下都保持高效。三层压缩流水线：70% 上下文使用率时应用延迟摘要 → 80% 时修剪 → 溢出时 LLM 压缩。大型工具输出存储在 SQLite（而非磁盘）中，通过原生 `read_overflow` 工具按需注入，消除绝对路径泄露并支持对话删除时自动清理。**失败驱动的压缩准则** (ACON)：每次硬压缩后，代理会监控响应中的上下文丢失信号；确认的失败对训练一个 LLM 生成的 `` 块，注入到未来的每个压缩 prompt 中。`--debug-dump [PATH]` 将每个 LLM 请求、响应和原始工具输出写入编号文件用于上下文调试；`--dump-format `（或运行时 `/dump-format`）切换输出格式 —— `trace` 发出 OpenTelemetry 兼容的 OTLP JSON，具有 session → iteration → LLM-call/tool-call/memory-search 的 span 层级结构。[→ Context](https://bug-ops.github.io/zeph/advanced/context.html) · [→ Debug Dump](https://bug-ops.github.io/zeph/advanced/debug-dump.html) | | **语义记忆** | SQLite + Qdrant 配合 MMR 重排序、时间衰减、查询感知记忆路由（keyword/semantic/hybrid/episodic）、跨会话召回、隐式纠正检测和凭据清洗。可选 **图谱记忆** 增加实体关系追踪，支持 FTS5 加速的实体搜索、用于多跳推理的 BFS 遍历、双时态边版本控制（`valid_from`/`valid_to`）及时间点历史查询（`/graph history `）、可配置的 `temporal_decay_rate` 用于新近度加权评分，以及基于嵌入的实体解析用于语义去重。**A-MEM 动态笔记链接** 在每次图谱写入时创建即发即弃的相似性边（`[memory.graph.note_linking]`）。后台 LLM 提取在每个轮次即发即弃运行；图谱事实与语义召回一起注入上下文窗口。[→ Memory](https://bug-ops.github.io/zeph/concepts/memory.html) · [→ Graph Memory](https://bug-ops.github.io/zeph/concepts/graph-memory.html) | | **IDE 集成 (ACP)** | Stdio、HTTP+SSE 或 WebSocket 传输。多会话隔离，每会话独立对话历史和 SQLite 持久化。会话模式、实时工具流式传输、LSP 诊断注入、文件跟踪、用量报告。支持 Zed、Helix、VS Code。[→ ACP](https://bug-ops.github.io/zeph/advanced/acp.html) | | **多通道 I/O** | CLI、Telegram、TUI 仪表板 —— 全部支持流式传输。支持语音和视觉输入。[→ Channels](https://bug-ops.github.io/zeph/advanced/channels.html) | | **MCP & A2A** | MCP 客户端，完全向模型暴露工具。所有 MCP 工具定义在注册时及每次 `tools/list_changed` 刷新时都会被清洗 —— 17 种注入检测模式、Unicode Cf 类别剥离，以及 1024 字节的描述上限，防止通过恶意服务器元数据进行 prompt 注入。将 [mcpls](https://github.com/bug-ops/mcpls) 配置为 MCP 服务器可获得编译器级代码智能：悬停、定义、引用、诊断、调用层次结构，以及通过 rust-analyzer、pyright、gopls 和 30 多个其他 LSP 服务器进行安全重命名。A2A 代理到代理协议用于多代理编排。[→ MCP](https://bug-ops.github.io/zeph/guides/mcp.html) · [→ LSP](https://bug-ops.github.io/zeph/guides/lsp.html) · [→ A2A](https://bug-ops.github.io/zeph/advanced/a2a.html) | | **LSP 上下文注入** | 工具调用后自动将 LSP 派生的上下文注入代理 —— 无需显式调用工具。三个钩子：`write_file` 后的诊断（编译器错误作为下一轮上下文显示）、`read_file` 后的悬停信息（通过 tree-sitter 多语言预过滤器为关键符号预获取：Rust、Python、JS、TS、Go），以及 `rename_symbol` 前的引用列表（显示所有调用点）。通过现有的 mcpls MCP 服务器运行，在 mcpls 不可用时优雅降级。每轮强制执行 token 预算。由 `lsp-context` feature flag 启用（包含在 `full` 中）。[→ LSP Context Injection](https://bug-ops.github.io/zeph/concepts/lsp-context-injection.html) | | **子代理** | 生成具有范围限定工具、技能和零信任秘密委托的隔离代理 —— 定义为 Markdown 文件。4 级解析优先级（CLI > project > user > config），`permission_mode`（`default`/`accept_edits`/`dont_ask`/`bypass_permissions`/`plan`），细粒度 `tools.except` 拒绝列表，`background` 即发即弃执行，`max_turns` 限制，持久记忆范围（`user`/`project`/`local`）及 MEMORY.md 注入，持久 JSONL 转录存储及 `/agent resume` 用于继续已完成的会话，以及生命周期钩子（配置层的 `SubagentStart`/`SubagentStop`，每个代理的 `PreToolUse`/`PostToolUse` 及管道分隔匹配器）。通过 `zeph agents list|show|create|edit|delete`（CLI）或 TUI 中的交互式代理面板管理定义。[→ Sub-agents](https://bug-ops.github.io/zeph/advanced/sub-agents.html) | | **指令文件** | 在项目根目录放置 `zeph.md`（或 `CLAUDE.md` / `AGENTS.md`）。Zeph 自动检测并将其注入每个系统 prompt —— 项目规则、约定和领域知识自动应用。更改通过文件系统监视实时获取（500 毫秒防抖）—— 无需重启。[→ Instruction Files](https://bug-ops.github.io/zeph/concepts/instruction-files.html) | | **深度防御** | Shell 沙箱、SSRF 防护、技能信任隔离、秘密归零、审计日志、全工作区 `unsafe_code = "deny"`。不可信内容隔离：所有工具结果、网页抓取输出、MCP 响应、A2A 消息和记忆检索都经过 `ContentSanitizer` 流水线，在进入 LLM 上下文前进行截断、控制字符剥离、17 种注入模式检测，并用 spotlighting XML 分隔符包裹内容。可选 **隔离摘要器**（双 LLM 模式）将高风险源通过隔离的、无工具的 LLM 提取调用路由，以防御间接 prompt 注入。**渗透防护** 阻止 markdown 图像像素跟踪，验证工具调用 URL 是否匹配标记的不可信源，并抑制标记为注入内容的记忆写入。**OWASP AI Agent Security 2026** 加固：**PiiFilter**（`[security.pii_filter]`）在 LLM 注入和调试转储前清洗工具输出中的电子邮件、电话、SSN、信用卡和自定义模式（零分配 `Cow` 快速路径，可选）；**MemoryWriteValidator**（`[security.memory_validation]`）对 `memory_save` 和图谱提取强制执行大小上限、禁止子串模式、实体/边数量限制和实体名称 PII 扫描（默认启用）；**ToolRateLimiter**（`[security.rate_limit]`）应用滑动窗口每类别（shell/web/memory/mcp/other）限制及熔断器冷却 —— `check_batch()` 在并行分发前原子预留槽位以防止绕过（可选）。TUI 安全面板配备实时事件源、SEC 状态栏指示器和 `security:events` 命令面板条目。[→ Security](https://bug-ops.github.io/zeph/reference/security.html) · [→ Untrusted Content Isolation](https://bug-ops.github.io/zeph/reference/security/untrusted-content-isolation.html) | | **文档 RAG** | `zeph ingest ` 将 `.txt`、`.md`、`.pdf` 索引到 Qdrant。相关块在每个轮次自动浮现。[→ Document loaders](https://bug-ops.github.io/zeph/advanced/document-loaders.html) | | **代码索引与仓库地图** | 通过 tree-sitter ts-query 始终开启基于 AST 的代码索引。从 Rust、Python、JavaScript、TypeScript 和 Go 提取结构化符号（名称、类型、可见性、行号）。生成简洁的仓库地图注入每个 LLM 请求，无论提供商或 Qdrant 可用性如何。对索引符号和块进行语义代码搜索。通过文件系统监视进行增量重索引。 | | **任务编排** | 基于 DAG 的任务图支持依赖跟踪、并行执行、可配置失败策略（abort/retry/skip/ask）、超时强制和 SQLite 持久化。通过 `Planner` trait 进行 LLM 驱动的目标分解，输出结构化结果。基于 Tick 的 `DagScheduler` 执行引擎采用命令模式，`AgentRouter` trait 用于任务到代理路由，跨任务上下文注入集成 `ContentSanitizer`，以及陈旧事件防护。LLM 支持的结果聚合（`Aggregator` trait, `LlmAggregator`）将完成的任务输出合成为单个连贯响应，具有每任务 token 预算和原始拼接回退。`/plan` CLI 命令：`/plan `（分解 + 确认 + 执行）、`/plan status`、`/plan list`、`/plan cancel`、`/plan confirm`、`/plan resume [id]`（恢复暂停的 Ask-strategy 图）、`/plan retry [id]`（重新运行失败任务）。TUI 计划视图侧边面板（按 `p`）显示实时任务状态，每行带有旋转器和状态颜色；提供五个 `plan:*` 命令面板条目。`MetricsSnapshot` 中跟踪 `OrchestrationMetrics`。[→ Orchestration](https://bug-ops.github.io/zeph/concepts/task-orchestration.html) | | **基准测试与评估** | TOML 基准数据集配合 LLM-as-Judge 评分。针对 `BenchmarkSet` 运行任何被测模型，通过单独的评判模型并行评分响应并输出结构化 JSON（`JudgeOutput` schema），收集汇总的 `EvalReport` 指标（分、p50/p95 延迟、每案例 token 跟踪）。通过原子 token 计数器、基于信号量的并发和用于被测响应隔离的 XML 边界标签强制执行预算。由 `experiments` feature flag 启用（包含在 `full` 中）。 | | **守护进程与调度器** | HTTP webhook 网关支持 bearer 认证。基于 Cron 的周期性任务和一次性延迟任务，支持 SQLite 持久化 —— 使用内置 `scheduler` 技能通过自然语言在运行时添加、更新或取消任务。实验会话可通过 `TaskKind::Experiment` 按 cron 计划运行，结合 `scheduler` 和 `experiments` feature flags。后台模式。[→ Daemon](https://bug-ops.github.io/zeph/advanced/daemon.html) | | **自我实验** | 自主 LLM 配置实验引擎（灵感来自 [autoresearch](https://github.com/karpathy/autoresearch)）。参数变异引擎采用可插拔策略（网格扫描、随机采样、邻域搜索）逐一探索 temperature、top-p、top-k、frequency/presence penalty，通过 LLM-as-judge 评分评估每个变体，保留超过可配置阈值的改进。`SearchSpace` 定义每参数范围和步长；`ConfigSnapshot` 捕获完整 LLM 配置以实现可复现回滚。通过 cron 配合 `ExperimentSchedule` 配置进行计划运行。CLI 标志：`--experiment-run`（运行单次实验会话并退出）、`--experiment-report`（打印结果摘要并退出）。TUI `/experiment` 命令：`start`、`stop`、`status`、`report`、`best`。通过 `zeph init` 向导进行交互式设置。由 `experiments` feature flag 启用（可选，包含在 `full` 中）。 | | **配置迁移** | `zeph migrate-config [--config PATH] [--in-place] [--diff]` — 版本升级后升级现有配置文件。缺失的部分以注释块形式追加并附带文档；现有值从不被触碰。输出是幂等的，可在应用前通过 `--diff` 预览。[→ Migrate Config](https://bug-ops.github.io/zeph/guides/migrate-config.html) | | **单一二进制** | 约 15 MB，无运行时依赖，约 50 毫秒启动，约 20 MB 空闲内存。 | 可选功能按用例分组：`desktop`（TUI + scheduler）、`ide`（ACP + LSP）、`server`（gateway + A2A + otel）、`chat`（Discord + Slack）、`ml`（Candle + PDF + STT）。使用 `--features full` 获取除硬件特定 GPU 标志外的所有功能。参见 [Feature Flags](https://bug-ops.github.io/zeph/reference/feature-flags.html)。 ``` ┌─ Skills (3/12) ────────────────────┐┌─ MCP Tools ─────────────────────────┐ │ web-search [████████░░] 82% (117)││ - filesystem/read_file │ │ git-commit [███████░░░] 73% (42)││ - filesystem/write_file │ │ code-review [████░░░░░░] 41% (8)││ - github/create_pr │ └────────────────────────────────────┘└─────────────────────────────────────┘ ```

## 文档 完整文档 —— 安装、配置、指南和架构参考 —— 位于 **[bug-ops.github.io/zeph](/>)**。 Zeph 的设计借鉴了广泛的已发表研究：并行工具执行（[LLMCompiler, ICML 2024](https://arxiv.org/abs/2312.04511)）、失败驱动的上下文压缩（[ACON, ICLR 2026](https://arxiv.org/abs/2510.00615)）、时态知识图谱（[Zep/Graphiti, 2025](https://arxiv.org/abs/2501.13956)）、代理记忆链接（[A-MEM, NeurIPS 2025](https://arxiv.org/abs/2502.12110)）、观察掩码和基于 schema 的摘要（[Manus, 2025](https://rlancemartin.github.io/2025/10/15/manus/)）等。塑造 Zeph 的论文、博客文章和规范的完整列表位于 **[References & Inspirations](/>)**。 ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。发现漏洞？使用 [GitHub Security Advisories](https://github.com/bug-ops/zeph/security/advisories/new)。 ## 许可证 [MIT](LICENSE)

标签：AI安全, AI风险缓解, Chat Copilot, Claude, CVE检测, DLL 劫持, Gemini, GGUF, LLM评估, MCP, Ollama, OpenAI, Rust, 上下文管理, 内存规避, 单二进制, 可视化界面, 大语言模型, 实时告警, 开源, 技能学习, 时序图记忆, 本地部署, 混合推理, 网络流量审计, 网络调试, 自动化, 语义检索, 资源优化, 通知系统