# https://github.com/marmyx77/omni-ai-mcp 项目说明书

生成时间：2026-07-05 17:54:17 UTC

## 目录

- [项目概览、特性与快速上手](#page-1)
- [核心架构、服务层与安全模型](#page-2)
- [MCP 工具集与 AI 集成细节](#page-3)
- [部署、配置、环境变量与常见故障](#page-4)

<a id='page-1'></a>

## 项目概览、特性与快速上手

### 相关页面

相关主题：[核心架构、服务层与安全模型](#page-2), [部署、配置、环境变量与常见故障](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/marmyx77/omni-ai-mcp/blob/main/README.md)
- [pyproject.toml](https://github.com/marmyx77/omni-ai-mcp/blob/main/pyproject.toml)
- [requirements.txt](https://github.com/marmyx77/omni-ai-mcp/blob/main/requirements.txt)
- [manifest.json](https://github.com/marmyx77/omni-ai-mcp/blob/main/manifest.json)
- [setup.sh](https://github.com/marmyx77/omni-ai-mcp/blob/main/setup.sh)
</details>

# 项目概览、特性与快速上手

## 项目概述

`omni-ai-mcp` 是一个基于 **Model Context Protocol (MCP)** 构建的 AI 工具集成项目，旨在为大语言模型（LLM）客户端提供标准化的上下文交互能力。项目通过 MCP 协议暴露工具与资源，使支持 MCP 的客户端（如 Claude Desktop、其他兼容 MCP 的智能体）能够发现、调用并与之通信 资料来源：[README.md:1-20]()。

项目的核心定位是一个 **MCP Server**：它遵循 MCP 规范，对外提供一组可调用的工具（tools）和资源（resources），从而将本地能力（例如文件解析、配置读取、AI 服务调用等）暴露给上游 AI 客户端。`pyproject.toml` 中将项目名声明为 `omni-ai-mcp`，并通过 Python entry points 的方式注册可执行入口，使得 `mcp[cli]` 子命令可以直接驱动该服务器 资料来源：[pyproject.toml:1-30]()。

从依赖配置来看，项目至少依赖 `mcp[cli]`（MCP 官方命令行与运行时支持）以及 `defusedxml`（安全的 XML 解析库，用于防止 XXE 等注入风险）资料来源：[pyproject.toml:20-40]()。这两项依赖在 `requirements.txt` 中存在遗漏，是当前社区已知的一个安装层面的 Bug 资料来源：[requirements.txt:1-15]()。

## 主要特性

下表汇总了项目的核心特性、依赖项及其来源，便于快速对照。

| 特性 / 组件 | 说明 | 主要来源文件 |
|---|---|---|
| MCP 协议兼容 | 作为 MCP Server 向客户端暴露工具与资源 | `pyproject.toml`, `manifest.json` |
| CLI 启动支持 | 通过 `mcp[cli]` 提供命令行入口 | `pyproject.toml` |
| 安全 XML 解析 | 使用 `defusedxml` 处理不可信 XML 输入 | `pyproject.toml` |
| 一键安装脚本 | `setup.sh` 自动化环境准备 | `setup.sh` |
| 依赖清单 | `requirements.txt` 记录运行依赖 | `requirements.txt` |

项目通过 `manifest.json` 声明其能力清单（capabilities），例如所支持的 tool 名称、参数 schema 等元数据，从而让客户端无需硬编码即可动态发现可用能力 资料来源：[manifest.json:1-30]()。

## 快速上手

### 环境准备

推荐使用 Python 3.10+ 环境，并通过项目根目录下的 `setup.sh` 完成一键初始化。该脚本通常会创建虚拟环境、安装依赖并执行必要的预检查 资料来源：[setup.sh:1-25]()。

```bash
# 克隆仓库
git clone https://github.com/marmyx77/omni-ai-mcp.git
cd omni-ai-mcp

# 执行一键安装
bash setup.sh
```

### 安装依赖（注意社区已知问题）

如果使用 `pip install -r requirements.txt` 方式直接安装，可能会遇到 **依赖缺失** 的问题：`requirements.txt` 缺少 `mcp[cli]` 与 `defusedxml`，而这两项在 `pyproject.toml` 中是明确声明的 资料来源：[requirements.txt:1-15]() 资料来源：[pyproject.toml:20-40]()。

社区 Issue #1 报告了该 Bug，并指出这会导致通过 `requirements.txt` 路径安装的用户无法获取 MCP 运行时 资料来源：[requirements.txt:1-15]()。推荐的两种解决方式：

1. **以 `pyproject.toml` 为准安装**：
   ```bash
   pip install -e .
   ```
   这种方式会依据 `pyproject.toml` 解析完整依赖列表，避免遗漏 资料来源：[pyproject.toml:1-40]()。

2. **手动补齐缺失依赖**：
   ```bash
   pip install mcp[cli] defusedxml
   ```
   补齐后再进行功能验证 资料来源：[requirements.txt:1-15]()。

### 启动 MCP Server

在依赖正确安装后，可通过 `mcp` CLI 启动服务器，使客户端能够通过 stdio 或配置的传输层与之通信 资料来源：[pyproject.toml:10-30]()。

## 架构与数据流

```mermaid
flowchart LR
    A[AI 客户端<br/>如 Claude Desktop] -- MCP 协议 --> B[omni-ai-mcp Server]
    B -- 读取 capabilities --> M[manifest.json]
    B -- 解析 XML 输入 --> D[defusedxml]
    B -- 暴露 tools/resources --> A
    S[setup.sh] --> B
    P[pyproject.toml / requirements.txt] --> B
```

上图展示了典型的交互链路：AI 客户端通过 MCP 协议发现 `omni-ai-mcp` 暴露的能力（参考 `manifest.json`），发起工具调用；服务器在处理过程中使用 `defusedxml` 安全地解析 XML 类输入；安装阶段由 `setup.sh` 与依赖清单共同完成环境准备 资料来源：[manifest.json:1-30]() 资料来源：[pyproject.toml:20-40]() 资料来源：[setup.sh:1-25]()。

## 已知问题与注意事项

- **依赖不同步**：`requirements.txt` 与 `pyproject.toml` 存在不一致，导致 `pip install -r requirements.txt` 缺少 `mcp[cli]` 与 `defusedxml`。建议优先使用 `pip install -e .` 资料来源：[requirements.txt:1-15]() 资料来源：[pyproject.toml:20-40]()。
- **安全解析**：所有外部 XML 输入都应经由 `defusedxml` 处理，避免在 MCP 工具链路中引入 XXE 风险 资料来源：[pyproject.toml:20-40]()。
- **能力发现**：客户端通过 `manifest.json` 中的声明来动态发现可用工具，修改该文件后需重启 Server 以使变更生效 资料来源：[manifest.json:1-30]()。

---

<a id='page-2'></a>

## 核心架构、服务层与安全模型

### 相关页面

相关主题：[项目概览、特性与快速上手](#page-1), [MCP 工具集与 AI 集成细节](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [app/server.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/server.py)
- [app/core/config.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/core/config.py)
- [app/core/security.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/core/security.py)
- [app/core/logging.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/core/logging.py)
- [app/services/gemini.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/services/gemini.py)
- [app/services/openrouter.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/services/openrouter.py)
- [pyproject.toml](https://github.com/marmyx77/omni-ai-mcp/blob/main/pyproject.toml)
</details>

# 核心架构、服务层与安全模型

## 系统总体架构

`omni-ai-mcp` 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的多模型 AI 代理服务器。它通过标准化的 MCP 接口向客户端（如 Claude Desktop、其他 MCP Host）暴露可被发现的工具（`tools`）与资源（`resources`），并在后端聚合多种大模型服务（至少包括 Google Gemini 与 OpenRouter）。

代码采用清晰的分层架构：

- **入口层** `app/server.py`：构建 `FastMCP` 实例，注册所有可被外部调用的工具函数。
- **核心层** `app/core/`：横切关注点——配置加载、输入清洗与日志。
- **服务层** `app/services/`：每个外部 AI 提供方对应一个独立适配器模块。

资料来源：[app/server.py:1-50]()、[pyproject.toml:1-30]()

## 核心模块

### 配置管理 (`app/core/config.py`)

配置模块集中读取环境变量并暴露一个类型化的 `Settings` 对象，避免在业务代码中散落 `os.getenv` 调用。其职责包括：

- 加载各提供方 API 密钥（如 `GEMINI_API_KEY`、`OPENROUTER_API_KEY`）。
- 加载运行期参数（日志级别、HTTP 超时、并发上限等）。
- 在启动期对必填项进行校验，缺失时快速失败而非延后崩溃。

该层是后续服务层与安全层读取凭据的唯一来源，从而避免密钥硬编码到 service 模块。

资料来源：[app/core/config.py:1-60]()

### 安全模型 (`app/core/security.py`)

安全模块承担输入清洗与凭据保护的双重职责，是整个系统的"防御边界"：

- **输入清洗**：由于 `pyproject.toml` 显式引入 `defusedxml`（参见社区 [Issue #1](https://github.com/marmyx77/omni-ai-mcp/issues/1)），该模块在解析或拼接用户提供的内容时禁用了危险的 XML 外部实体加载，缓解 XXE 与注入风险。
- **凭据隔离**：API 密钥通过配置层注入，service 模块只在内存中临时持有，请求结束即释放，不会被序列化到日志或响应中。

资料来源：[app/core/security.py:1-80]()、[pyproject.toml:1-30]()

### 日志 (`app/core/logging.py`)

日志模块提供统一的日志记录接口，便于在 MCP 长连接与多次工具调用场景下追踪请求链路。该模块被 `server.py` 与 `services/*` 共同引用，避免各模块自行配置 `logging.basicConfig` 带来的格式不一致。

资料来源：[app/core/logging.py:1-40]()

## 服务层 (`app/services/`)

服务层采用"适配器"风格，每个 AI 提供方对应一个独立文件：

- `app/services/gemini.py`：封装 Google Gemini API 的鉴权头构造、HTTP 请求与响应解析。
- `app/services/openrouter.py`：封装 OpenRouter 统一网关，遵循 OpenAI 兼容协议。

这种设计带来两个关键收益：

1. **可替换性**：新增模型只需新增一个 service 文件，`server.py` 无需改动。
2. **关注点分离**：`server.py` 只声明"暴露哪些 MCP 工具"，具体调用细节全部下放到 service。

资料来源：[app/services/gemini.py:1-40]()、[app/services/openrouter.py:1-40]()

## MCP 请求生命周期

`app/server.py` 使用 `mcp[cli]` 提供的 `FastMCP` 类构建服务器实例（`mcp[cli]` 是 [Issue #1](https://github.com/marmyx77/omni-ai-mcp/issues/1) 强调的必需依赖）。一次典型的 `tools/call` 流程如下：

```mermaid
sequenceDiagram
    participant C as MCP 客户端
    participant S as app/server.py
    participant Sec as core/security.py
    participant Sv as services/*
    participant A as AI 提供方

    C->>S: tools/call(tool_name, args)
    S->>Sec: 校验/清洗入参
    Sec-->>S: 标准化参数
    S->>Sv: 调用对应 service
    Sv->>A: HTTP 请求(携带 API Key)
    A-->>Sv: 模型响应
    Sv-->>S: 标准化结果
    S-->>C: MCP 响应
```

如果 `defusedxml` 缺失，`security.py` 在导入阶段即会失败，整个服务器无法启动——这正是社区报告 `requirements.txt` 缺依赖会导致安装后立即崩溃的原因。

资料来源：[app/server.py:1-80]()、[app/core/security.py:1-80]()

## 已知问题与依赖一致性

[Issue #1](https://github.com/marmyx77/omni-ai-mcp/issues/1) 指出 `requirements.txt` 与 `pyproject.toml` 不同步：前者缺少 `mcp[cli]` 与 `defusedxml`。在按照本架构部署时建议：

- 优先以 `pyproject.toml` 为准（`pip install -e .` 或 `uv sync`）。
- 若必须使用 `requirements.txt`，需手动补齐上述两项，否则 `server.py` 在导入阶段即终止。

资料来源：[pyproject.toml:1-30]()

---

<a id='page-3'></a>

## MCP 工具集与 AI 集成细节

### 相关页面

相关主题：[核心架构、服务层与安全模型](#page-2), [部署、配置、环境变量与常见故障](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [app/tools/registry.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/tools/registry.py)
- [app/tools/text/ask_gemini.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/tools/text/ask_gemini.py)
- [app/tools/text/ask_model.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/tools/text/ask_model.py)
- [app/tools/text/brainstorm.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/tools/text/brainstorm.py)
- [app/tools/text/challenge.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/tools/text/challenge.py)
- [app/tools/text/code_review.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/tools/text/code_review.py)
- [pyproject.toml](https://github.com/marmyx77/omni-ai-mcp/blob/main/pyproject.toml)
- [requirements.txt](https://github.com/marmyx77/omni-ai-mcp/blob/main/requirements.txt)
</details>

# MCP 工具集与 AI 集成细节

## 1. 概述与设计目标

omni-ai-mcp 是一个基于 Model Context Protocol (MCP) 的工具服务器项目，通过标准化接口将多种 AI 能力暴露给上游 Agent（如 Claude、IDE 插件等）。整个项目以「工具集 (tools)」为最小功能单元，每个工具在收到 MCP 请求时被注册、调用并返回结果。`app/tools/registry.py` 充当统一的中枢：它将所有工具按名称收集、校验 Schema，并以可枚举的形式提供给 MCP Server，以便客户端能够通过 `tools/list` 协议发现它们 资料来源：[app/tools/registry.py:1-80]()。

文本类工具位于 `app/tools/text/` 子目录下，包含六个独立模块：`ask_gemini.py`、`ask_model.py`、`brainstorm.py`、`challenge.py`、`code_review.py`。它们共享相同的输入/输出约定，便于在 registry 中按统一范式注册 资料来源：[app/tools/text/ask_model.py:1-40]()。

## 2. 工具注册中心 (Registry)

`registry.py` 的核心职责是动态发现与绑定工具。一般而言，模块会提供一个 `register()` 或 `get_tools()` 之类的工厂函数，在 MCP Server 启动时被遍历调用。每个工具对象需要实现 `name`、`description` 和 `input_schema` 三个标准属性，以便 MCP 协议序列化。

| 阶段 | 行为 |
|------|------|
| 启动 | 扫描 `app/tools/**/*.py`，收集可调用对象 |
| 注册 | 写入全局字典，键为工具名，值为处理函数 |
| 调用 | MCP Server 根据客户端请求匹配键，路由至对应函数 |
| 返回 | 将结果封装为 `TextContent` 或结构化对象 |

这种「注册即插拔」的范式允许新增工具时无需修改主程序，只需将新文件放入 `app/tools/` 即可被自动发现 资料来源：[app/tools/registry.py:30-120]()。

## 3. 文本工具与 AI 集成

### 3.1 通用模型调用：`ask_model.py`

该模块是抽象的「问 AI」入口。它接收用户的自然语言 prompt，可选择注入上下文（如文件内容、剪贴板文本），再委托给底层 LLM 客户端。模块通常会封装重试、超时与速率限制逻辑，对外只暴露简短的同步函数签名 资料来源：[app/tools/text/ask_model.py:20-90]()。

### 3.2 Gemini 专用通道：`ask_gemini.py`

相较于通用 `ask_model.py`，`ask_gemini.py` 专门调用 Google Gemini API。它复用 `ask_model` 的输入范式，但底层使用 Gemini SDK 以利用其特有的系统指令、多模态能力等优势。这种「通用-专用」分层设计使得切换模型实现时只需替换具体模块 资料来源：[app/tools/text/ask_gemini.py:1-60]()。

### 3.3 高阶认知任务

`brainstorm.py` 与 `challenge.py` 属于同一类「思维类工具」：
- `brainstorm.py`：根据用户给定的议题生成多角度设想列表，适合做发散思考。
- `challenge.py`：对用户论点进行反方辩论，用以暴露盲点。

两者都通过预设的系统提示词 (system prompt) 引导模型扮演特定角色，本质上是 `ask_model.py` 的语义包装 资料来源：[app/tools/text/brainstorm.py:15-70]()、资料来源：[app/tools/text/challenge.py:15-70]()。

### 3.4 代码审查工具

`code_review.py` 接受源代码片段或差异 (diff)，输出结构化评审意见。它会在内部构造系统提示，要求模型从可读性、性能、安全性等维度分析，并返回 Markdown 格式的审查报告，便于 MCP 客户端直接渲染 资料来源：[app/tools/text/code_review.py:1-80]()。

## 4. 依赖与运行时配置

项目使用 `pyproject.toml` 声明现代打包配置，并同时保留 `requirements.txt` 供老式部署。然而社区报告了一个已确认的 Bug（参见 [Issue #1](https://github.com/marmyx77/omni-ai-mcp/issues/1)）：`requirements.txt` 缺少 `mcp[cli]` 与 `defusedxml` 两个关键依赖，导致通过 `pip install -r requirements.txt` 安装时会失败 资料来源：[requirements.txt:1-30]()。

修复建议是使 `requirements.txt` 与 `pyproject.toml` 严格对齐，至少包含以下核心依赖：`mcp[cli]`（提供 CLI 入口与 stdio 传输）、`defusedxml`（安全解析 MCP 消息中的 XML 内容） 资料来源：[pyproject.toml:1-50]()。

```mermaid
flowchart LR
    A[MCP Client] -->|tools/list| B[registry.py]
    A -->|tools/call| B
    B --> C[ask_model]
    B --> D[ask_gemini]
    B --> E[brainstorm]
    B --> F[challenge]
    B --> G[code_review]
    C & D & E & F & G --> H[LLM Provider]
    H --> C & D & E & F & G
```

## 5. 小结

omni-ai-mcp 通过标准化的工具注册模式，将 Gemini 调用、通用模型调用以及多种思维类任务统一暴露给 MCP 客户端。`registry.py` 负责发现与路由，`app/tools/text/` 下的模块则按职责分离。维护者应特别留意 `requirements.txt` 与 `pyproject.toml` 的同步问题，以避免部署中断。

---

<a id='page-4'></a>

## 部署、配置、环境变量与常见故障

### 相关页面

相关主题：[项目概览、特性与快速上手](#page-1), [MCP 工具集与 AI 集成细节](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [requirements.txt](https://github.com/marmyx77/omni-ai-mcp/blob/main/requirements.txt)
- [pyproject.toml](https://github.com/marmyx77/omni-ai-mcp/blob/main/pyproject.toml)
- [Dockerfile](https://github.com/marmyx77/omni-ai-mcp/blob/main/Dockerfile)
- [docker-compose.yml](https://github.com/marmyx77/omni-ai-mcp/blob/main/docker-compose.yml)
- [run.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/run.py)
- [app/cli.py](https://github.com/marmyx77/omni-ai-mcp/blob/main/app/cli.py)
- [README.md](https://github.com/marmyx77/omni-ai-mcp/blob/main/README.md)
</details>

# 部署、配置、环境变量与常见故障

本文档面向运维与集成人员，介绍 `omni-ai-mcp`（基于 Model Context Protocol 的多 AI 后端聚合服务器）的部署方式、配置加载逻辑、运行时环境变量以及已知的常见故障与修复方法。

## 1. 安装与依赖管理

### 1.1 通过 `pip` 与 `pyproject.toml` 安装（推荐）

项目的核心元数据与依赖列表集中在 `pyproject.toml` 中，涵盖了运行 MCP 服务所需的运行时依赖、可选功能分组（如 CLI、文档解析等）以及打包配置。建议优先使用以下方式安装，以避免依赖漂移：

```bash
pip install -e .
```

资料来源：[pyproject.toml:1-80]()

### 1.2 通过 `requirements.txt` 安装的注意事项

`requirements.txt` 是为 CI 与轻量化场景准备的快照文件。**社区已有反馈指出该文件历史上存在与 `pyproject.toml` 不一致的问题**，例如缺失 `mcp[cli]` 的 CLI 扩展以及 XML 解析安全补丁依赖 `defusedxml`，导致 `pip install -r requirements.txt` 在干净环境下失败。

在 issue #1 中报告的对比示意如下：

| 依赖项 | pyproject.toml | requirements.txt |
|--------|----------------|------------------|
| `mcp[cli]` | ✅ | ❌（历史版本缺失） |
| `defusedxml` | ✅ | ❌（历史版本缺失） |

资料来源：[requirements.txt:1-40]()、[pyproject.toml:1-80]()、[issues/1]()

> **建议**：遇到 `ModuleNotFoundError: No module named 'mcp.cli'` 或 XML 解析相关警告时，请改用 `pip install -e .`，或参考 `pyproject.toml` 手动补齐缺失条目后再安装。

## 2. 环境变量与配置加载

项目通过标准的环境变量加载机制为不同的 AI 后端（OpenAI、Anthropic、Gemini、Ollama 等）提供 API 密钥、端点地址与超时配置。CLI 入口在启动前会读取这些变量并注入到运行时上下文。

### 2.1 入口与配置注入流程

```
启动 run.py → app/cli.py 解析参数 → 加载 .env / 系统环境变量 → 构造 MCP Server → stdio 监听
```

资料来源：[run.py:1-60]()、[app/cli.py:1-120]()

### 2.2 常用变量（参考命名）

- `OPENAI_API_KEY`、`OPENAI_BASE_URL`
- `ANTHROPIC_API_KEY`
- `GEMINI_API_KEY` / `GOOGLE_API_KEY`
- `OLLAMA_HOST`（默认 `http://localhost:11434`）
- `OMNI_LOG_LEVEL`（`DEBUG` / `INFO` / `WARNING`）
- `OMNI_TIMEOUT`、`OMNI_MAX_TOKENS`

具体的变量名与默认值以 `app/cli.py` 中的读取逻辑为准。资料来源：[app/cli.py:40-120]()。

## 3. Docker 化部署

### 3.1 单容器方式

`Dockerfile` 基于官方 Python 镜像构建，将源码复制到容器内并设置默认启动命令。典型使用方式：

```bash
docker build -t omni-ai-mcp .
docker run -i --rm \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  omni-ai-mcp
```

资料来源：[Dockerfile:1-60]()

> MCP 协议通常通过 **stdio** 通信，因此容器必须以 `-i`（交互模式）启动，且一般不直接暴露端口。

### 3.2 使用 docker-compose

`docker-compose.yml` 提供了更便捷的多服务编排能力，可与本地 Ollama 服务或反向代理共同启动。常见字段包括 `environment`、`stdin_open`、`tty` 等，必须保持为 `true` 以保证 stdio 通道畅通。资料来源：[docker-compose.yml:1-40]()。

## 4. 常见故障与排查

| 现象 | 可能原因 | 修复建议 |
|------|----------|----------|
| `pip install -r requirements.txt` 安装失败 | `requirements.txt` 缺失可选依赖（如 `mcp[cli]`、`defusedxml`） | 改用 `pip install -e .`，或同步补齐 `requirements.txt` |
| 启动报 `ModuleNotFoundError: mcp.cli` | 未安装 CLI 扩展 | 安装 `mcp[cli]` 或使用 editable 模式 |
| Docker 容器启动后无响应 | 缺少 `-i` 或 `stdin_open: true` | 添加交互参数，确保 stdio 通道连通 |
| 调用某 AI 后端返回 401/403 | 未注入对应 API Key | 检查 `.env` 文件并重启容器 |
| 本地 Ollama 调用超时 | `OLLAMA_HOST` 未配置或服务未启动 | 设置 `OLLAMA_HOST=http://host.docker.internal:11434` 并确认 Ollama 监听 `0.0.0.0` |
| 日志无输出 / 输出过于冗长 | `OMNI_LOG_LEVEL` 未设置 | 显式设置 `OMNI_LOG_LEVEL=INFO` |

资料来源：[requirements.txt:1-40]()、[Dockerfile:1-60]()、[docker-compose.yml:1-40]()、[app/cli.py:40-120]()、[run.py:1-60]()

## 5. 最佳实践小结

1. **优先使用 `pip install -e .`** 而非 `requirements.txt`，避免依赖漂移。资料来源：[pyproject.toml:1-80]()。
2. **将密钥放入 `.env` 或 Docker secret**，不要硬编码在镜像中。资料来源：[Dockerfile:1-60]()。
3. **MCP 通信使用 stdio**，因此 Docker 必须保留交互通道；不要使用 `docker run -d`。资料来源：[docker-compose.yml:1-40]()。
4. **升级前对照 `pyproject.toml` 检查 `requirements.txt`**，参考 issue #1 的修复 PR。资料来源：[issues/1]()。
5. **多后端调试时开启 `OMNI_LOG_LEVEL=DEBUG`**，便于追踪路由与重试逻辑。资料来源：[app/cli.py:40-120]()。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：marmyx77/omni-ai-mcp

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: requirements.txt missing dependencies (mcp[cli], defusedxml)。

## 1. 安装坑 · 来源证据：Bug: requirements.txt missing dependencies (mcp[cli], defusedxml)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: requirements.txt missing dependencies (mcp[cli], defusedxml)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/marmyx77/omni-ai-mcp/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/marmyx77/omni-ai-mcp | host_targets=mcp_host, claude_code, claude, chatgpt

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/marmyx77/omni-ai-mcp | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/marmyx77/omni-ai-mcp | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/marmyx77/omni-ai-mcp | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/marmyx77/omni-ai-mcp | no_demo; severity=medium

## 7. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/marmyx77/omni-ai-mcp | issue_or_pr_quality=unknown

## 8. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/marmyx77/omni-ai-mcp | release_recency=unknown

<!-- canonical_name: marmyx77/omni-ai-mcp; human_manual_source: deepwiki_human_wiki -->