Unified AI System

Unified AI System: Gateway de IA Auto-hospedado e Servidor MCP

Gateway de IA de código aberto para aprimoramento determinístico de prompts, execução governada e verificação reproduzível.

English | zh-CN | Site do Projeto

O Unified AI System transforma uma solicitação bruta em um prompt estruturado e revisável antes da execução. Ele oferece às equipes uma superfície auto-hospedada para SDKs compatíveis com OpenAI, MCP, A2A, CLI e HTTP, mantendo as chamadas de provedor explícitas — com o conjunto de recursos que você esperaria de um gateway de LLM comercial: chaves virtuais com orçamentos de tokens, cache de respostas exato e semântico, governança reversa de MCP com geração REST→MCP e observabilidade de produção.

Experimente Antes de Instalar

_{A solicitação original permanece visível. O aprimorador local adiciona requisitos de execução, requisitos de saída e critérios de conclusão.}

Abra um exemplo de codificação pronto para execução no Prompt Lab do navegador

O link carrega uma solicitação real e renderiza o prompt aprimorado localmente. Nenhuma conta, chave de API ou chamada de provedor é necessária.

Execute a mesma prova contra o contêiner publicado:

docker run --rm ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.5.0 pnpm gateway demo "Build a small API for my team" --enhance --profile coding --evidence

As evidências confirmam que a solicitação original foi preservada, o resultado é determinístico e providerCalled=false. Codex, VS Code, Claude Code, Gemini CLI, OpenCode, Cursor, Cline, Continue e clientes stdio genéricos podem alcançar o mesmo gateway por meio de doze ferramentas MCP governadas. A compilação de origem também fornece um endpoint MCP Streamable HTTP testado por protocolo para clientes que se conectam por URL.

Útil em um fluxo de trabalho real? Dê uma estrela no repositório ou compartilhe um resultado reproduzível.

O Gateway em Resumo

_{Os clientes mantêm seus protocolos nativos; o gateway adiciona chaves, orçamentos, cache e auditoria. Doze ferramentas MCP governadas são inspecionáveis a partir de qualquer cliente MCP.}

Escolha Seu Primeiro Caminho

Seu objetivo	Comece aqui	O que você obtém
Experimente antes de instalar	Prompt Lab do navegador	Uma prévia local e determinística sem conta ou chave de API.
Verifique o runtime publicado	Demonstração Docker de 60 segundos	Uma execução descartável com provedor fictício, com evidências visíveis e limpeza.
Conecte um cliente agente	Início rápido com Codex e MCP	Um contêiner MCP fixado e doze ferramentas inspecionáveis.
Escolha um caminho de cliente	Matriz de compatibilidade MCP	Comandos de instalação, primeiras verificações e limites honestos de evidências.
Integre com um aplicativo	Guia de aprimoramento de prompt	Caminhos para CLI, HTTP, SDK, curl, Python e JavaScript.
Mantenha um cliente OpenAI existente	API compatível com OpenAI	Aponte baseURL para /v1 para Chat Completions, ferramentas de função, Responses, streaming e descoberta de modelos.
Conecte outro agente	Gateway A2A v1.0	Descubra um Agent Card e execute tarefas rastreadas com provedor fictício via JSON-RPC.
Verifique a certificação de runtime do cliente	Certificação de runtime do cliente	Estado atual do catálogo baseado em evidências: 52 verificados, 2,084 com evidência manual pendente e 0 falhas em 2,136 entradas únicas.
Execute a certificação convencional uma a uma	Certificação de runtime do cliente	Execute node tools/verify-client-runtimes-serial.mjs --client tag:mainstream para relatórios sequenciais e estados explícitos de evidência manual.
Execute a cobertura global de protocolo	Certificação de runtime do cliente	Execute node tools/run-global-client-discovery.mjs --source-manifest docs/client-runtime-catalog-sources-worldwide.json --execute --serial --max 0.
Execute a certificação global estrita	Certificação de runtime do cliente	Adicione --require-manual-evidence --manual-evidence docs/client-runtime-evidence.example.json para falhar na ausência de prova manual.
Inspecione o contrato de aprimoramento	Avaliação sem credenciais	Oito casos representativos para perfis, idiomas, sinais, determinismo e zero chamadas de provedor.
Diagnostique um problema na primeira execução	Matriz de solução de problemas	Verificações específicas de shell sem expor credenciais.
Verifique um cliente MCP	Relatório de cliente MCP	Registre uma execução do Codex, Cursor, Cline ou stdio genérico com um pequeno conjunto de evidências.
Contribua ou relate uma execução	Relatório de uso ou boa primeira issue #106	Um caminho de feedback reproduzível para usuários e mantenedores.

Recursos do Gateway

Tudo abaixo é executado a partir do mesmo processo auto-hospedado — opcional e com provedor fictício em primeiro lugar, para que você possa experimentar todos os recursos com zero credenciais:

Recurso	O que você obtém	Documentação
APIs compatíveis com OpenAI + Anthropic	/v1/chat/completions (streaming SSE, ferramentas), /v1/messages com streaming nativo Anthropic, a API Responses e descoberta de modelos — mantenha seu SDK existente, altere apenas a URL base.	API compatível com OpenAI
Chaves virtuais + orçamentos	Emita chaves uai- com orçamentos periódicos de tokens (janelas diárias/mensais), limites de solicitação por chave, alertas de orçamento flexível, atribuição de gastos e revogação instantânea. Os consumidores nunca detêm chaves de provedor.	Chaves virtuais
Cache de resposta — exato + semântico	Cache de caminho quente com escopo de locatário, com reprodução byte-idêntica de JSON/SSE, uma camada semântica opcional para solicitações parafraseadas, limites de TTL e tamanho, e trilha de auditoria completa.	Cache de resposta
Governança reversa de MCP	Agregue servidores MCP upstream (Streamable HTTP e stdio) atrás de uma superfície autenticada, auditada e com lista de permissões — além de REST→MCP: qualquer especificação OpenAPI 3 se torna ferramentas MCP governadas.	Governança reversa de MCP
Observabilidade	Métricas Prometheus específicas de chat em /metrics — tokens por modelo, taxas de acerto de cache, histogramas de TTFT, rejeições de chave virtual — além de uma exportação opcional para Langfuse.	Observabilidade
Recuperação vetorial	Um provedor de embeddings determinístico sem credenciais e o armazenamento vetorial SQLite ativam RAG mode: "vector" com isolamento estrito de locatário.	Provedores e conhecimento
Governança de provedores	Uma matriz de lista de permissões de três portões para provedores reais, um armazenamento de credenciais em runtime (SHA-256 em repouso), proteções de custo de solicitação, disjuntores e cadeias de fallback.	Habilitação de provedores
Governança empresarial + exercícios de segurança	Autenticação JWT, RBAC, isolamento de locatário com cadeias de hash de auditoria — verificado por uma regressão de segurança ao vivo repetível com 16 ataques.	Exercício de segurança

Por Que as Pessoas Usam

• Aprimoramento de prompt para colegas que não escrevem prompts perfeitos.
• Verificação de clone limpo sem credenciais ou configuração oculta.
• Exemplos HTTP sem provedor para curl e a biblioteca padrão do Python.
• Pontos de entrada para OpenAI SDK, CLI, API HTTP, SDK compartilhado, MCP, Codex, Cursor, Cline e Continue.
• Limites claros: sem alegação de AGI, sem alegação de L5, sem comportamento silencioso de provedor.
• Integração protocolo-primeiro: qualquer cliente MCP, A2A ou HTTP compatível com OpenAI pode ser integrado por meio de um caminho curto de configuração + relatório reproduzível; priorizamos verificação em vez de alegações de marketing.

Experimente em 60 Segundos

Verifique o projeto sem fazer login:

docker run --rm ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.5.0 pnpm gateway demo

Comportamento esperado:

• execução local com provedor fictício
• execution: fake visível
• saída determinística
• nenhuma chave de API ou conta necessária
• o contêiner sai automaticamente

Prévia de aprimoramento de linguagem natural com um comando:

docker run --rm ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.5.0 \
  pnpm gateway demo "Build a small API for my team" --enhance --profile coding --evidence

Isso inicia um gateway isolado com provedor fictício, aprimora a solicitação localmente, imprime o prompt estruturado e faz a limpeza sem uma chave de API.

Você também pode canalizar uma solicitação diretamente para a imagem publicada sem clonar o repositório:

printf '%s' "Plan a launch for a small API" \
  | docker run --rm -i ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.5.0 \
      pnpm --silent gateway demo --enhance --profile planning --language en --json

Equivalente no PowerShell para um arquivo de solicitação:

Get-Content .\request.txt -Raw |
  docker run --rm -i ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.5.0 `
    pnpm --silent gateway demo --enhance --profile planning --language en --json

O contêiner ainda usa o caminho descartável do provedor fictício e sai após o resultado ser impresso.

Use --language zh-CN ou --language en quando a saída do aprimoramento deve seguir um idioma explícito em vez de detecção automática.

Exemplo de aprimoramento de prompt:

Inicie o gateway primeiro (a partir de um checkout da fonte):

pnpm gateway serve

Em seguida, em outro terminal:

pnpm gateway enhance "Build a small API for my team" --profile coding
pnpm gateway chat "Build a small API for my team" --enhance --profile coding

A CLI também aceita uma solicitação do stdin, o que é útil para pipelines de shell e arquivos de texto:

printf '%s' "Plan a launch for a small API" \
  | pnpm gateway enhance --profile planning --language en
cat request.txt | pnpm gateway enhance --profile auto --json

Usuários do PowerShell podem canalizar o mesmo caminho com Get-Content .\request.txt -Raw.

SDKs OpenAI Existentes

Inicie o gateway de origem com pnpm gateway serve, depois mantenha seu cliente OpenAI existente e altere apenas sua URL base:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:3100/v1",
  apiKey: process.env.PME_AUTH_TOKEN || "local-development",
});

const result = await client.chat.completions.create({
  model: "local-fake-model",
  messages: [{ role: "user", content: "Build a small API for my team" }],
});

console.log(result.choices[0].message.content);

O portão sem credenciais verifica esse caminho com o SDK oficial do OpenAI JavaScript 7.4.0. Com o gateway de origem em execução, reproduza com:

node docs/examples/openai-sdk-chat.mjs

A camada de compatibilidade focada suporta conclusões de texto, streaming, listagem de modelos e aprimoramento local opcional de prompt. Consulte o guia de API compatível com OpenAI para Python, campos suportados, comportamento de autenticação e limitações explícitas.

Prefere Node.js? O exemplo sem dependências verifica a resposta sem provedor antes de imprimir o JSON aprimorado:

node docs/examples/prompt-enhancement.mjs "Help me plan a small API for my team" --profile planning --language en

Prefere Go? O exemplo da biblioteca padrão verifica a prontidão sem provedor e imprime evidências JSON antes de mostrar o prompt aprimorado:

go run docs/examples/prompt-enhancement.go "Help me plan a small API for my team" --profile planning --language en

Para um passo a passo de aprimoramento de prompt sem clone, inicie a imagem do gateway publicada e siga o exemplo curl sem provedor:

read -rsp "Enter a random gateway token (32+ characters): " PME_AUTH_TOKEN
printf '\n'
export PME_AUTH_TOKEN
docker run --rm --publish 127.0.0.1:3100:3100 \
  --env AI_GATEWAY_SERVICE_HOST=0.0.0.0 \
  --env AI_GATEWAY_PROVIDER_MODE=fake \
  --env AI_GATEWAY_REAL_PROVIDER_ENABLED=false \
  --env PME_ENTERPRISE_AUTH_ENABLED=true \
  --env PME_AUTH_TOKEN \
  ghcr.io/happy520ai/unified-ai-system/ai-gateway-service:0.5.0

Mantenha esse processo em execução enquanto envia a solicitação curl. A resposta inclui metadata.providerCalled=false. Para um stream HTTP sem credenciais, use o exemplo curl SSE para inspecionar os eventos start, chunk e done com executionMode=fake. O gateway recusa escuta não-loopback quando a autenticação está desabilitada; consulte o relatório crítico de endurecimento da cadeia de ataques.

Como Usar

Fluxo de Trabalho no Terminal

Após pnpm install:

pnpm gateway serve
pnpm gateway status
pnpm gateway doctor
pnpm gateway chat "Hello from Unified AI System"

MCP / Codex / Cursor / Cline

Comando MCP publicado:

codex mcp add unified-ai-system -- docker run --rm -i ghcr.io/happy520ai/unified-ai-system/mcp-server:0.5.0

Reinicie o Codex, execute /mcp verbose para verificar as doze ferramentas e, em seguida, siga o quickstart do Codex MCP em 60 segundos para uma primeira chamada segura de aprimoramento de prompt e comando de remoção.

Para clientes MCP que se conectam por URL, a compilação a partir do código-fonte fornece um endpoint HTTP Streamable somente em loopback:

pnpm mcp:http
# http://127.0.0.1:3210/mcp

Consulte o guia do servidor MCP para autenticação de bind remoto e o limite da versão publicada.

Habilidade de Agente Instalável

codex plugin marketplace add happy520ai/unified-ai-system --ref master
npx skills add happy520ai/unified-ai-system --skill unified-ai-gateway --agent codex --copy --yes

O plugin fixa a imagem MCP v0.4.9 imutável revisada e a inicia sem rede de contêiner ou capacidades Linux.

Hub de habilidades: https://skills.sh/happy520ai/unified-ai-system/unified-ai-gateway

Para trabalho local com código-fonte:

git clone https://github.com/happy520ai/unified-ai-system.git
cd unified-ai-system
corepack enable
corepack prepare pnpm@9.15.4 --activate
pnpm install --frozen-lockfile
pnpm verify:public-clone
pnpm gateway demo

Para um workspace em nuvem preparado, use GitHub Codespaces. Veja o valor primeiro:

pnpm gateway demo "Build a small API for my team" --enhance --profile coding --evidence

Para a verificação completa de clone sem credenciais, execute pnpm verify:public-clone após a demonstração. O devcontainer do repositório mantém o caminho padrão livre de provedores. A disponibilidade e os limites de uso do Codespaces são controlados pelo GitHub.

Docker Compose

Para um checkout do código-fonte, inicie o gateway com uma verificação de prontidão:

docker compose up --build -d
docker compose ps
curl http://127.0.0.1:3100/health/check

O serviço se torna healthy somente após /health/check responder com sucesso. Quando terminar, pare-o com:

docker compose down

O arquivo Compose trata .env como opcional e deixa o comportamento do provedor explícito; o caminho padrão de provedor falso sem credenciais permanece o padrão.

Compartilhe um Resultado Verificado

Se o projeto ajudar no seu fluxo de trabalho, execute um caminho reproduzível, dê uma estrela no repositório e compartilhe o menor resultado útil por meio do Relatório de Uso estruturado.

Para um pacote CLI pronto para revisão, acrescente --evidence à demonstração aprimorada:

pnpm gateway demo "Build a small API for my team" --enhance --profile coding --evidence

Revise a solicitação original e a saída antes de compartilhar o JSON gerado. O pacote também registra detectedSignals e a contagem de itens para cada entrada de compiledSections, para que um revisor possa ver quais sinais de solicitação foram transportados para o prompt estruturado sem ler logs internos.

Para o Prompt Lab no navegador, use a ação Copy evidence ou Download evidence, e cole ou anexe o JSON no campo opcional de evidência do Prompt Lab do mesmo relatório. Use Copy share link quando quiser que outro navegador reproduza a mesma entrada local, perfil e idioma; revise o prompt primeiro porque o fragmento de URL contém o texto de entrada.

Próximos Passos

• Documentação para configuração, CLI, aprimoramento de prompt e provedores.
• Quickstart do Codex MCP para a integração mais rápida de ferramentas de agente; o guia de código-fonte é mantido no repositório.
• Guia de contribuição para mudanças focadas e verificação segura.
• Modelo de Relatório de Uso para feedback reproduzível.
• Cite este projeto, Roadmap e Suporte.

Limites Honestos

Separamos o que é verificado do que não é afirmado:

• Clone limpo + caminho de provedor falso: Sim
• API pública hospedada: Não
• Execução real de provedor por padrão: Não, deve ser explicitamente habilitada
• UI de chat no navegador neste repositório: Não (CLI/API/MCP são de primeira classe)
• Pronto para produção / AGI / L5: Não afirmado

Chamadas reais de provedor são desabilitadas por padrão. Configure com segurança via .env.example e docs/providers.md.

Verifique o Projeto

pnpm check
pnpm test
pnpm check:public
pnpm verify:public-clone
pnpm verify:mcp

CI em master executa verificações Linux, testes de fumaça de inicialização de contêiner, descoberta MCP e verificações de limpeza de processos.

Links do Projeto

• Entrada no Registro Oficial MCP
• Versão v0.4.9
• README do servidor Codex MCP
• Roadmap
• Visão
• Suporte

Histórico de Estrelas

Se o gateway economizar uma migração de proxy ou uma tarde de limpeza de prompt, uma estrela ajuda mais pessoas a encontrá-lo.