Semantic Sift

🔍 Semantic-Sift

面向高保真 Agentic 工作流的推理优先中间件。

“节省 token，同时保留上下文——最大限度发挥推理能力，尽可能减少幻觉。”

Semantic-Sift 是一款本地 Model Context Protocol (MCP) 服务，充当原始数据与 AI 上下文窗口之间的智能“清理层”。

现代大模型虽然拥有超大的上下文窗口，但随着噪声增多，其推理准确性往往会下降。Semantic-Sift 使用 LLMLingua-2 将技术日志、长篇文档和聊天记录提炼为高密度上下文，从而解决这一问题。它将上下文窗口视为宝贵资源，以优化**信噪比（SNR）**为目标，让模型将更多时间用于推理，而非处理样板内容。

🧠 理念：双人工作室

Semantic-Sift 秉持双人工作室理念：工程的未来在于人类架构师与自主 AI 助手之间建立高保真的合作伙伴关系。通过处理原始数据摄取带来的阻碍，Sift 让这个“工作室”能够专注于构建系统，而不只是应用补丁。它充当认知过滤器，确保你和 Agent 都能基于最清晰、最相关的技术事实表述开展协作。

---

⚡ 快速开始（60 秒）

# 1. Install
pip install "semantic-sift[neural]"

# 2. Onboard your project (writes IDE hooks and opencode.json)
semantic-sift-onboard   # or: ask your AI "Run sift_onboard()"

# 3. Add to your MCP config (example: Cursor / Claude Desktop)
# { "mcpServers": { "semantic-sift": { "command": "semantic-sift" } } }

# 4. Warm up the model (optional — avoids first-call latency)
# Ask your AI: "Run sift_warmup()"

完整设置指南（venv 布局、IDE 配置矩阵、自主模式）：doc/INTEGRATION_ENCYCLOPEDIA.md

---

🏛️ 跨领域价值

Semantic-Sift 是一个战略层，旨在帮助四类关键专业角色管理注意力：

• **面向资深工程师：**采用双引擎方案（启发式筛选器 + 神经重排器）的本地优先、低延迟中间件。它会在时间戳、重复样板内容和冗余 JSON 进入传输链路前进行整理，从而降低延迟，并避免出现“迷失在中间”的推理失效。
• 面向项目经理：“上下文保险”。通过减少 30-70% 的 token 开销，Sift 可直接降低 API 成本，并减少混乱数据环境中模型幻觉导致的“重试循环”。
• **面向研究人员：**大规模保障数据完整性。支持 MarkItDown（通过 [multi-modal] 可选扩展），可将复杂的 .pdf、.docx 和 .xlsx 文件转换为结构化、精炼后的 Markdown，帮助快速综合大量技术代码库，同时保留关键语义锚点。
• **面向知识伙伴：**认知负荷管理。Sift 负责处理原始数据摄取带来的阻碍，让人机伙伴关系专注于高层战略和架构决策，而非手动整理数据。

---

💰 价值工程：运营与经济投资回报率

Semantic-Sift 提供双层价值。经济效益取决于你的计费方案，而运营效益适用于每一种专业工作流。

1. 经济 ROI（直接节省）

目标：按 Token 计费的 API 套餐用户（GPT-4o、Claude 3.5）。

• 保护钱包： Sift 充当本地过滤器，通常可将发送的 Token 量减少 30-70%。
• 复利效应： 在迭代式 Agent 循环中，这些节省会迅速累积。每个被精简的字符，都是留在你预算中的钱。

2. 运营 ROI（质量与性能）

目标：所有人（包括使用“无限”或按请求计费订阅的用户）。

• 精准聚焦： 即使上下文“无限”，大模型也会受到“中间迷失”综合征的影响。移除噪声后，你可以确保模型将全部推理能力集中在技术信号上，从而生成更高质量的代码并减少幻觉。
• 降低延迟： 提示词越短 =“首 Token 时间”（TTFT）越快。你可以减少等待“云端”处理模板内容的时间，更多地保持心流状态。
• 上下文保险： 防止复杂任务出现“超出上下文长度”错误。Sift 确保模型上下文上限的 100% 都用于承载信息，而非格式内容。

---

📚 文档总索引

所有技术细节、架构逻辑和集成指南均严格维护在 doc/ 目录中，以防信息因摘要而丢失。

• doc/INDEX.md：文档结构的导航路线图和唯一可信来源。
• doc/ARCHITECTURE.md：Sift Hook 拦截器、蒸馏内核（启发式/语义/排序引擎）和缓存的规范。
• doc/TOOL_REFERENCE.md：所有 FastMCP 工具（例如 sift_read_file、sift_logs、sift_chat、sift_rank）的完整操作手册。
• doc/INTEGRATION_ENCYCLOPEDIA.md：主兼容性映射、Hook 注入器逻辑、负载结构，以及用于连接 IDE（Cursor、Gemini、VS Code、OpenCode 等）的主配置矩阵。
• doc/TELEMETRY_SPEC.md：OpenTelemetry 跟踪、回声检测器（防止重复 Sift）、审计标头和隐私控制的设计。
• doc/ORCHESTRATION_BLUEPRINTS.md：面向 AI Agent 的可执行工作流，包括文件摄取决策树、多文档 RAG 和历史记录压缩。

---

🎯 高影响力用例

📚 知识猎手（研究人员与架构师）

• 痛点： 阅读 50 页的 PDF、复杂的 Word 规范或杂乱的文档网站。
• Sift 方案： 通过 [multi-modal] 可选扩展支持 MarkItDown，可原生摄取 .pdf、.docx 和 .xlsx。它能将企业“噪声”转换为结构化 Markdown，让你的 Agent 在单轮对话中综合处理多份 14MB 文档。

🛠️ 日志猎手（DevOps 与 SRE）

• 痛点： 从 100,000 行技术日志中找出单个错误。
• Sift 方案： 启发式筛选器可在毫秒内精简时间戳和模板内容。潜意识 Hook会自动重新排序结果，让你的 Agent 只看到最相关的数据块。

🧠 上下文策略师（AI 工程师）

• 痛点： 杂乱的数据流导致大模型产生幻觉、推理能力下降。
• Sift 方案： 在保留 95% 语义的同时提供高密度上下文，Sift 充当认知桥梁，确保大模型的注意力完全集中在信号上。

---

⚡ 性能等级

Semantic-Sift 提供两个性能等级。请根据使用场景选择：

	Python MCP 服务（pip install semantic-sift）	Rust CLI Sidecar（sift-core）
启发式日志筛选	✅ 约 500ms	✅ <1ms（原生）
神经语义筛选	✅ 约 500ms（PyTorch）	✅ 约 150ms（ONNX）
Python 依赖	必需	无
Rust 工具链	无需	无需（预构建）
交付方式	PyPI wheel（包含预构建的 sift-core）	随 wheel 一并提供；开发安装请使用 fetch_sift_core.py

PyPI wheel（pip install semantic-sift）：内置预编译的 sift-core 二进制文件，无需 Rust 工具链。

可编辑／开发安装（pip install -e .）：将跳过 Rust 编译步骤。运行一次以获取预构建的二进制文件：

python scripts/fetch_sift_core.py

可选 [native] 标记：对于需要显式标记的依赖管理工具，可使用 pip install semantic-sift[native] 这个无操作附加项（二进制文件始终包含在 wheel 中）。

---

🚀 快速开始

1. 安装

选项 A：快速安装（PyPI）

**ℹ️ 安装内容：**PyPI wheel 包含预编译的 sift-core Rust 二进制文件，无需 Rust 工具链。[neural] 附加项会安装 PyTorch（约 1.5 GB），以便使用 LLMLingua-2 进行大载荷回退处理；[multi-modal] 会安装 MarkItDown，用于摄取 PDF/DOCX/XLSX。由于 PyTorch 下载体积较大，首次安装预计需要几分钟。

uv venv
# Windows: .\.venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
uv pip install semantic-sift[neural,multi-modal]

选项 B：自主模式（推荐）

克隆仓库即可获取原生 Rust sidecar 源代码和基准测试：

**⚠️ 需要 Rust 编译器：**自主模式会从源代码构建 sift-core。运行下面的安装命令前，必须安装 Rust 编译器（rustup.rs）。如果不想安装 Rust，请改用选项 A（PyPI）。

git clone https://github.com/luismichio/semantic-sift.git
cd semantic-sift
# Use Python 3.12 for torch/CUDA compatibility
python3.12 -m venv venv312
# Windows:
.\venv312\Scripts\activate
# macOS/Linux:
# source venv312/bin/activate
uv pip install -e .[neural,multi-modal]

Windows 提示（uv 环境发现）：如果 uv 无法找到你的环境（错误：“No virtual environment found”），请显式指定解释器： uv pip install -e . --python venv312\Scripts\python.exe

注意：如果你使用的是 Context-Pipe 的自主双仓库模式，semantic-sift 会改为交叉安装到 context-pipe/venv 中（通过 uv pip install -e ../semantic-sift）。上面的 venv312 仅用于独立的 ML 运行时或直接运行 server.py。

🐍 Python 环境指南

为 MCP 配置选择正确的 Python 路径对稳定性至关重要：

设置类型	路径示例	优点	缺点
专用 Venv（Win）	.../semantic-sift/venv312/Scripts/python.exe	依赖隔离，不会发生 torch 版本冲突。	占用的磁盘空间稍多。
专用 Venv（Mac/Linux）	.../semantic-sift/venv312/bin/python	在 Unix 上同样具备隔离优势。	相同。
全局 Python	C:/Users/User/AppData/Local/.../python.exe	共享库，设置快速。	版本冲突风险高（例如 transformers 版本不匹配）。

建议：始终在 mcp_config.json 中使用专用 Venv 路径，确保筛选内核隔离且可靠。

**编排说明：**Semantic-Sift 是一个“智能内核”。对于复杂的多工具工作流，我们强烈建议安装 Context-Pipe。它是一个通用交换枢纽，可原生将数据路由到 Semantic-Sift，且不会阻塞 IDE。

开发工具（mypy、pytest）：

uv pip install -e .[dev]

可编辑安装的 Rust 二进制文件：pip install -e . 会跳过 Rust 编译步骤，因此 sift-core 不会出现在你的 PATH 中。无需从源代码编译，只需通过一条命令，从对应的 GitHub 发布版本中下载适用于你平台的预构建二进制文件：

python scripts/fetch_sift_core.py

该命令会将 sift-core[.exe] 直接放入当前活动环境的 Scripts/bin 目录。每次升级版本时都请重新运行。

2. 连接 MCP

重要：有关 Cursor、Gemini、OpenCode、VS Code 和 Claude 的确切配置路径，请参阅 主配置矩阵。

3. 自动引导

连接后，向 AI 助手询问：

“运行 sift_onboard() 来配置此项目。”

---

📊 遥测与管理命令

Semantic-Sift 在后台运行，但你随时可以审查其性能和节省的令牌，无需消耗大模型令牌。

• 终端 CLI：
  • 运行 semantic-sift-stats，打印令牌节省量、延迟和缓存命中的全局仪表板。
  • 运行 semantic-sift-onboard，在任意项目中手动初始化 Sift（支持 --env 和 --dry-run）。
• MCP 提示词：兼容的客户端（Claude Desktop、Cursor、Zed）会在其界面中显示 sift_dashboard 提示词（通常通过斜杠命令或按钮），以便立即将遥测统计信息注入聊天。
• OpenCode 与 Gemini CLI：sift_onboard() 工具会自动将原生 /sift-stats 和 /sift-onboard 自定义斜杠命令注入 IDE 配置。

---

🦀 原生 Rust Sidecar（Meechi 与桌面应用）

对于高性能、本地优先的应用（例如 Meechi），Semantic-Sift 提供原生 Rust 二进制文件（sift-core）。此 Sidecar 针对可移植性和速度进行了优化，且不依赖 Python。

🔀 混合引擎（semantic-sift-cli）

为兼顾两者优势，安装 Python 包后也会提供 semantic-sift-cli 命令。它充当一个智能路由器：

• 对于短任务（<30,000 字符），会立即调用低延迟 Rust sift-core（ONNX）。
• 对于超大型批处理任务，会动态加载高吞吐量 PyTorch 框架及 Flash Attention，以防止内存爆满。

功能对比

功能	Python MCP 服务	Rust Sift-Core（Sidecar）
启发式日志筛选	✅	✅（原生）
语义压缩	✅（PyTorch）	✅（ONNX）
多模态摄取	✅（通过 [multi-modal]）	❌（仅文本）
支持的格式	.pdf、.xlsx、.docx、.html、.txt	.txt、.log、.out（文本）
启动延迟	3-5 秒	~10ms
二进制文件大小	~1.5GB（含模型）	~15MB

注意：对于 Meechi 这类原生应用，我们建议采用分层摄取策略：使用应用前端（例如 pdf.js）提取文本，然后将文本传递给 Rust Sidecar，以进行高速语义筛选。

✨ 查看原生 Sidecar 演示

用法：

# Sift a log file instantly
cat app.log | sift-core logs

# Perform neural semantic compression
cat document.txt | sift-core semantic --model ./models/llmlingua2 --rate 0.4

---

🤖 面向 AI Agent：操作协议

如果你是正在阅读此代码库的 AI Agent（例如 Gemini CLI、Cursor、Claude Code），请遵循以下协议：

1. 初始化：调用 sift_onboard() 注册后台钩子。使用 sift_onboard(dry_run=True) 可预览所有计划执行的操作，而不写入任何文件。
2. 上下文建议：读取大型文件（>1,000 字符）前，调用 sift_analyze_file(path) 以确定噪声比例。
3. 必须进行筛选：如果噪声 > 15%，请在将数据纳入推理前，通过 sift_logs 或 sift_chat 处理。对于文档，请使用 sift_doc(text, rate=0.4)；调整 rate（0.1–0.9）可权衡压缩深度与保真度。
4. 排序：使用 sift_rank，为用户的提示词找出语义相关性最高的文本块。
5. 提取：提炼 PDF 或抓取的内容时，使用 sift_extraction(content, show_diff=True) 查看具体移除了哪些内容，并核验保真度。

---

🛡️ 安全与测试

Semantic-Sift 基于零漏洞基线构建：

• Pytest：启发式完整性测试通过率为 100%。
• Bandit（SAST）：针对 Python 模式进行自动化静态分析。
• Pip-Audit（SCA）：实时供应链监控，已知漏洞数为 0。

隐私与遥测控制：

• 设置 SIFT_TELEMETRY_OPTED_IN=true 以启用遥测（需主动选择；默认禁用）。
• 设置 SIFT_TELEMETRY_DISABLED=true（旧版紧急开关）以完全禁用遥测。
• 设置 SIFT_TELEMETRY_TTL_DAYS=90（默认值），以控制在 .pipe_telemetry.json 中保留会话历史的天数，超期条目会被清除。
• 设置 SIFT_TELEMETRY_URL=https://your-endpoint，将元数据脉冲发送到你自己的端点。
• 设置 SIFT_PULSE_RATE_LIMIT_S=10（默认值），以控制异步遥测脉冲频率。

安全控制：

• 设置 SIFT_ALLOW_GLOBAL_READS=true，允许 sift_read_file / sift_analyze_file 读取工作区根目录之外的文件（默认启用路径遍历防护）。

性能控制：

• 设置 SIFT_HOOK_TIMEOUT_MS=3000，在触发启发式回退前限制钩子的语义处理延迟。
• 设置 SIFT_MODEL_READY_WAIT_MS=1200，控制返回启发式模式输出前等待语义模型预热的时间。
• 设置 SIFT_COMPACTION_FIDELITY_THRESHOLD=0.3（默认值），控制词汇重叠阈值；低于该阈值时会发出低保真压缩警告。
• 设置 SIFT_RANK_TOP_N=3（默认值），以设置服务器范围内 sift_rank 在未显式传入 top_n 时返回的默认结果数。

钩子日志控制：

• 设置 SIFT_LOG_FILE 以覆盖钩子日志路径（默认值：.gemini/sift_debug.log）。
• 设置 SIFT_LOG_LEVEL（DEBUG、INFO、WARNING、ERROR）以控制钩子日志详细程度。

完整安全策略请参阅 SECURITY.md。

遥测架构和端点详情请参阅 doc/TELEMETRY_SPEC.md。

---

🔗 生态系统（Studio of Two）

Semantic-Sift 是 Studio of Two 基础设施的旗舰成员，旨在与以下项目实现高保真协同：

• Context-Pipe：用于上下文工程的通用交换中心。Sift 提供智能能力，Context-Pipe 则提供编排能力。我们强烈建议使用 Context-Pipe，将 Sift 节点与脱敏、搜索和多模态摄取工具串联起来。

---

⚖️ 许可

Semantic-Sift 根据 Apache License 2.0 授权。详情请参阅 LICENSE.md。

🤝 贡献

Semantic-Sift 是开源的，但不接受贡献。

为维护 “Studio of Two” 严格的架构愿景，并将维护开销降至绝对为零，本仓库不接受外部拉取请求。我们鼓励你根据宽松的 Apache 2.0 许可证使用、嵌入和分叉代码，但请勿提交新功能或错误修复的 PR。详情请参阅 CONTRIBUTING.md。