上下文编码器后端
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分钟）
- 在（某处）获取免费的API密钥 smith.langchain.com 翻译为中文是：“史密斯的语言链网站”或根据具体语境可简化为“史密斯LangChain平台”。不过，通常网址的翻译或描述会保持原样，因为网址本身具有特定的指向性和识别性，直接使用原网址在中文环境中也是可以理解的。如果非要翻译，上述翻译是一种可能的表述方式
- 添加到您的
backend/.env:
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_pt_sua_chave_aqui
LANGCHAIN_PROJECT=context-coder-dev- 重启后端服务器
- 访问 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”或保持原样，因为文件名在中文语境下通常不翻译）
🎯 前端
前端已被移至单独的存储库：
📦（包裹/箱子） 上下文编码器前端
要使用完整应用程序，您需要：
- 运行这个后端
- 运行前端（独立仓库）
🐞 故障排除
错误：“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📚 额外文件
- QUICKSTART.md 翻译为中文是：快速入门指南.md（其中，“.md”表示这是一个Markdown格式的文件） - 完整快速指南
- LANGSMITH_INTEGRATION.md（文件名，可译为“LangSmith集成指南.md”或保持原文件名不变，具体取决于上下文和使用场景） - 使用 LangSmith 进行可观测性分析 🆕
- - 不使用 Docker 运行
- \
FRONTEND_MOVED.md\翻译为中文是：“前端已迁移.md”（注：\.md\是 Markdown 文件的扩展名，通常表示这是一个 Markdown 格式的文件） - 关于前端分离的信息 - 规格 - 项目的技术规格
🤝 贡献/助力
- 对项目进行分叉
- 创建一个分支（
git checkout -b feature/nova-feature) - 提交你的更改（
git commit -m 'Add: nova feature'） - 推送至分支（
git push origin feature/nova-feature) - 提交一个拉取请求（或合并请求）
📄 许可证
\[指定许可证\]
______________________________________________________________________
使用FastAPI、LangGraph和Gemini 2.5 Pro开发，满载❤️