核心用法
Local ContextBridge 是一款面向 AI 代理的本地文档搜索与上下文管理技能，核心功能包括：
1. 文档检索：支持 Word、Excel、PDF、Markdown 等格式的全文索引与语义搜索，通过 search_documents() 方法实现相关性排序（返回 score 与内容片段）。
2. 目录监控：使用 add_watch_directory() 设定监控路径，自动增量索引新文件，支持多目录管理。
3. 双模式部署：
4. 环境自动检测：detect_environment() 自动识别本地服务可用性，智能选择最优部署模式。
- 嵌入式模式（Embedded）：内置 ChromaDB，零外部依赖，适合单机/开发场景，内存占用 200-500MB。
- 外部模式（External）：复用现有 QMD（Quantum Metadata Database）与 OpenViking 服务，支持命名空间隔离（
contextbridge_docs集合），适合企业多应用共享架构。
显著优点
- 隐私优先：所有文档本地处理，不上传外部云服务，满足敏感数据合规需求。
- 零配置开箱：
cbridge init一键完成环境检测、依赖安装与服务配置，降低技术门槛。 - 生态兼容：与 OpenClaw 框架深度集成，支持 JSON-RPC over WebSocket 协议，可直接通过
/local-context-bridge search命令调用。 - 灵活可扩展：命名空间隔离机制避免与其他应用冲突；支持通过环境变量与 YAML 配置精细调整。
潜在缺点与局限性
- 依赖管理风险：首次使用自动安装
cbridge-agent==1.0.0，虽版本固定，但仍需信任 PyPI 包完整性；企业环境建议离线审计后手动安装。 - 外部模式依赖：若选择 External 模式，需自行维护 QMD/OpenViking 服务健康，网络或服务故障将导致检索中断。
- 索引性能瓶颈：初始索引 1000 文档需 1-5 分钟，大规模文档集（万级+）可能产生显著 IO 与内存压力，未明确提及分布式索引支持。
- 格式支持局限：仅支持 Office 与文本类格式，图片型 PDF、扫描件 OCR 能力未提及；复杂表格结构（如 Excel 嵌套公式）的语义提取质量未知。
- 权限要求较宽：需
file_read/write、process_execution、network_access等权限，在最小权限原则环境中需额外评估。
适合人群
- 隐私敏感型用户：法律、医疗、金融领域从业者，需本地化处理机密文档。
- OpenClaw 生态开发者：希望为 AI 代理扩展 RAG（检索增强生成）能力的工程师。
- 企业 IT 管理员：已部署 QMD/OpenViking 基础设施，需统一文档检索中台。
常规风险
| 风险类型 | 说明 |
|---------|------|
| 供应链安全 | 自动下载 PyPI 包，存在恶意代码注入或依赖劫持风险，建议审查 `~/.cbridge/setup.log` 并启用私有 PyPI 镜像。 |
| 本地文件泄露 | 虽不上云，但索引文件存储于 `~/.cbridge/workspace/`，多用户系统需确保目录权限（`chmod 700`）。 |
| 服务暴露 | External 模式探测 `localhost:9090/8080`，若主机存在其他恶意服务冒用端口，可能导致误连；建议显式配置端点而非自动探测。 |
| 审计可追溯性 | 虽记录 setup.log，但运行时检索行为无显式审计日志，合规场景需自行扩展日志模块。 |