AI导哈

代码上下文转换API

一个AI驱动的平台，将代码仓库上下文转换为可操作的技术规范。

  • by tperaro
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 tperaro/context-coder

使用说明

上下文编码器后端

Context-Coder的API后端——一个AI驱动的平台，将仓库上下文转化为可操作的技术规范。

🚀 技术栈

  • FastAPI 0.116.1+ - 现代的异步网络框架
  • LangGraph 0.6.0 - 带检查点的智能体编排
  • 双子座2.5专业版 - 通过Google Direct API使用LLM，OpenRouter作为备用方案
  • LangSmith - 代理的可观测性和调试（可选）
  • 模型上下文协议（MCP） - 在代码中使用语义搜索 zilliztech/claude-context
  • Python 3.11及以上版本 - 基础语言
  • 诗歌 - 依赖管理
  • Docker - 容器化

⚡ 快速入门

先决条件

  • Docker 和 Docker Compose 或者
  • 使用 Poetry 的 Python 3.11+
  • 所需的API密钥：
    • OpenRouter（适用于Gemini 2.5 Pro）
    • OpenAI（用于MCP的嵌入）
    • Zilliz Cloud（向量存储）

选项1：Docker（推荐）

# 1. Clone o repositório
git clone https://github.com/tperaro/context-coder.git
cd context-coder

# 2. Setup automático (cria .env e inicia)
./setup.sh

# OU manualmente:
cp backend/.env.example backend/.env
# Edite backend/.env com suas API keys
docker-compose up --build

# ✅ Acesse:
# API: http://localhost:8000
# Docs: http://localhost:8000/docs

选项2：本地（开发）

# 1. Entre na pasta backend
cd backend

# 2. Instale dependências
poetry install

# 3. Configure ambiente
cp .env.example .env
# Edite .env com suas API keys

# 4. Ative o ambiente virtual
poetry shell

# 5. Inicie o servidor
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# ✅ Acesse: http://localhost:8000/docs

📁 项目结构

context-coder/
├── backend/                 # Código-fonte do backend
│   ├── agent/              # LangGraph agent
│   │   ├── state.py        # AgentState TypedDict
│   │   ├── graph.py        # Construção do grafo
│   │   ├── nodes/          # Nós do grafo
│   │   ├── edges.py        # Lógica de roteamento
│   │   ├── checkpointing.py # SessionManager
│   │   └── prompts/        # Templates de prompts
│   ├── api/                # Endpoints FastAPI
│   │   ├── agent.py
│   │   ├── export.py
│   │   ├── github.py
│   │   └── repositories.py
│   ├── services/           # Serviços externos
│   │   ├── llm.py          # OpenRouter/Gemini
│   │   ├── mcp.py          # MCP integration
│   │   ├── export.py
│   │   └── github.py
│   ├── tests/              # Testes
│   ├── main.py             # Entry point
│   ├── pyproject.toml      # Poetry deps
│   ├── .env.example        # Template de config
│   └── Dockerfile
├── docs/                   # Documentação
│   ├── QUICKSTART.md
│   ├── RUN_WITHOUT_DOCKER.md
│   └── FRONTEND_MOVED.md
├── scripts/                # Scripts auxiliares
│   ├── setup-env.sh
│   ├── start.sh
│   └── fix-docker-context.sh
├── specs/                  # Especificações técnicas
├── docker-compose.yml      # Orquestração Docker
├── Makefile                # Comandos úteis
├── setup.sh                # Setup rápido
└── README.md               # Este arquivo

🌐 环境变量

复制 backend/.env.example para backend/.env 并配置：

# Google Gemini (Primary LLM)
GOOGLE_API_KEY=your-google-api-key-here
GOOGLE_MODEL=gemini-1.5-flash

# OpenRouter (Fallback LLM)
OPENROUTER_API_KEY=sk-or-v1-your-key-here
OPENROUTER_MODEL=google/gemini-flash-1.5

# OpenAI (Embeddings for MCP)
OPENAI_API_KEY=sk-your-openai-key-here

# Zilliz Cloud (Vector DB for MCP)
ZILLIZ_CLOUD_URI=https://your-instance.zilliz.cloud
ZILLIZ_CLOUD_API_KEY=your-zilliz-key-here

# Application
ENVIRONMENT=development
LOG_LEVEL=INFO
CORS_ORIGINS=http://localhost:5173

# LangSmith (Optional - Observability)
LANGCHAIN_TRACING_V2=false
LANGCHAIN_API_KEY=lsv2_pt_your-key-here
LANGCHAIN_PROJECT=context-coder-dev

# GitHub (Optional)
GITHUB_TOKEN=
GITHUB_ORG=your-org
GITHUB_PROJECT_NUMBER=1

在哪里获取密钥：

  • Google Gemini：https://aistudio.google.com/apikey（免费）
  • OpenRouter：https://openrouter.ai/keys
  • OpenAI：https://platform.openai.com/api-keys
  • Zilliz Cloud：https://cloud.zilliz.com/signup（免费层级）
  • LangSmith: https://smith.langchain.com/（免费 - 可选） 🆕 新的

🔧 有用的命令（Makefile）

make help          # Ver todos os comandos
make install       # Instalar dependências
make build         # Build Docker image
make up            # Iniciar serviços
make up-d          # Iniciar em background
make down          # Parar serviços
make logs          # Ver logs
make logs-backend  # Logs do backend
make test          # Executar testes
make shell-backend # Shell no container
make clean         # Limpar containers

🧪 测试（或“试验”）

# Com Docker
make test

# Ou localmente
cd backend
poetry run pytest
poetry run pytest tests/integration/ -v
poetry run pytest --cov=. --cov-report=html

📡 API 接口端点

该API的交互式文档可在此查看：

  • Swagger UIhttp://localhost:8000/docs 翻译为中文是：“http://本地主机:8000/文档”。不过，在实际语境中，我们通常不会直接翻译网址，而是会根据网址所指向的内容来描述其用途或功能。例如，这个网址可能是一个本地开发服务器上的API文档页面
  • ReDochttp://localhost:8000/redoc 翻译为中文是：“http://本地主机:8000/redoc” 或者更简洁地表达为“本地主机8000端口的redoc页面”。不过，在中文语境下，我们通常会说“访问本地8000端口的redoc文档界面”或者“打开本地8000端口的redoc页面”

主要终点：

  • POST /api/agent/invoke - 向代理发送消息
  • POST /api/agent/stream - 带流式传输的聊天（SSE）
  • GET /api/repositories - 列出存储库
  • POST /api/export/markdown - 导出规格
  • POST /api/github/create-card - 在GitHub Projects中创建卡片

📊 LangSmith - 可观测性（可选）

后端已与……集成 LangSmith 用于追踪和调试代理！

快速设置（5分钟）

  1. 在（某处）获取免费的API密钥 smith.langchain.com 翻译为中文是：“史密斯的语言链网站”或根据具体语境可简化为“史密斯LangChain平台”。不过，通常网址的翻译或描述会保持原样，因为网址本身具有特定的指向性和识别性，直接使用原网址在中文环境中也是可以理解的。如果非要翻译，上述翻译是一种可能的表述方式
  2. 添加到您的 backend/.env:
    LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_pt_sua_chave_aqui
LANGCHAIN_PROJECT=context-coder-dev
  3. 重启后端服务器
  4. 访问 smith.langchain.com（该网址本身在中文中不直接翻译，但可解释为：史密斯的语言链网站，或具体指某个与“史密斯”相关的“LangChain”项目/平台的网站，具体含义需根据上下文确定） 以查看实时痕迹！

你得到了什么？

  • 🔍（放大镜图标，通常表示搜索、查看细节或调查） 全程追踪 “de todas as execuções do agente” 翻译成中文是：“代理的所有执行”。不过，这里的“execuções”在葡萄牙语中通常指的是“执行”或“执行实例”，但根据上下文，可能需要更具体的翻译，比如“代理的所有操作”或“代理的所有执行任务”，以更准确地表达原句的意思。
  • 🐛 蝉（或虫子） 调试可视化 节点流（分析 → 搜索 → 大语言模型 → 更新）
  • 📈 指标 性能、延迟和成本
  • 标签 标签 为了组织痕迹（或轨迹）： agent， analysis， tech-debt等
  • 🔗（这个符号本身在中文中没有直接对应的翻译，它通常表示链接或连接。如果需要解释其含义，可以翻译为“链接”或“连接”） 可视化 AI的提示、回复和决策

被追踪的节点

所有主要节点都已配备工具（或：已进行仪表化）。

  • ✅ analyze_feature - 初步分析
  • ✅ search_codebase - 通过MCP搜索
  • ✅ llm_response - 生成响应
  • ✅ tech_debt_analysis - 技术债务分析
  • ✅ security_check - 安全检查清单
  • ✅ generate_diagram - 生成图表

📖（一本书的图标，常用于表示书籍或阅读相关内容） 完整文件： docs/LANGSMITH_INTEGRATION.md（文件名，可译为“文档/LANGSMITH集成指南.md”或保持原样，因为文件名在中文语境下通常不翻译）

🎯 前端

前端已被移至单独的存储库：

📦（包裹/箱子） 上下文编码器前端

要使用完整应用程序，您需要：

  1. 运行这个后端
  2. 运行前端（独立仓库）

🐞 故障排除

错误：“API密钥未找到”

检查文件是否 backend/.env 存在并且包含所有必要的密钥。

# Verificar se .env existe
ls -la backend/.env

# Copiar do exemplo se necessário
cp backend/.env.example backend/.env

错误：“端口8000已被占用”

# Matar processo na porta
lsof -ti:8000 | xargs kill -9

# Ou usar outra porta
uvicorn main:app --port 8001

错误：CORS（跨源资源共享）

确保 CORS_ORIGINS 不 backend/.env 包括前端URL：

CORS_ORIGINS=http://localhost:5173

📚 额外文件

🤝 贡献/助力

  1. 对项目进行分叉
  2. 创建一个分支（git checkout -b feature/nova-feature)
  3. 提交你的更改（git commit -m 'Add: nova feature'）
  4. 推送至分支（git push origin feature/nova-feature)
  5. 提交一个拉取请求（或合并请求）

📄 许可证

[指定许可证]

使用FastAPI、LangGraph和Gemini 2.5 Pro开发，满载❤️

相关 MCP