Cursor Composer Agent 模式深度实战：从零搭建一个完整项目（2026最新）

Cursor Composer Agent 模式深度实战：从零搭建一个完整项目（2026最新）

最近 V2EX 上关于"Cursor Composer Agent 模式"的讨论炸了，不少人说这是 AI 编程的下一个形态。我花了一周时间深度体验，用 Agent 模式从零搭建了一个完整的 RAG 知识库项目，今天把实战经验分享出来。

什么是 Composer Agent 模式？

Cursor 的 Composer 原本只是多文件编辑工具，但 2026 年 3 月更新后，新增了 Agent 模式。简单说：

• 普通模式：你告诉 Cursor 改哪个文件，它改哪个文件
• Agent 模式：你只说需求，Cursor 自己决定改哪些文件、创建哪些文件、运行哪些命令

这个差异看起来不大，但实际用起来完全是两个物种。

实战：用 Agent 模式搭建 RAG 知识库

项目需求

我给 Cursor 的需求很简单：

搭建一个 RAG 知识库系统，支持上传 PDF/Markdown 文档，用 Claude API 做问答。技术栈：Python + FastAPI + ChromaDB + LangChain。

Agent 模式的工作流程

启动 Agent 模式后（快捷键 Cmd+Shift+I），Cursor 做了这些事：

第一步：项目结构规划

rag-knowledge-base/
├── app/
│   ├── main.py          # FastAPI 入口
│   ├── models.py        # 数据模型
│   ├── embeddings.py    # 向量化
│   └── qa.py            # 问答逻辑
├── data/                # 文档存储
├── chroma_db/           # 向量数据库
├── requirements.txt
└── .env

第二步：依赖安装

Cursor 自动生成 requirements.txt：

fastapi==0.109.0
uvicorn==0.27.0
langchain==0.1.6
langchain-anthropic==0.1.4
chromadb==0.4.22
pypdf==4.0.1
python-multipart==0.0.9
python-dotenv==1.0.1

然后自动运行 pip install -r requirements.txt。

第三步：核心代码实现

app/embeddings.py（向量化模块）：

from langchain_anthropic import AnthropicEmbeddings
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.vectorstores import Chroma
import os

class EmbeddingService:
    def __init__(self):
        self.embeddings = AnthropicEmbeddings(
            anthropic_api_key=os.getenv("ANTHROPIC_API_KEY"),
            model="claude-3-haiku-20240307"
        )
        self.text_splitter = RecursiveCharacterTextSplitter(
            chunk_size=1000,
            chunk_overlap=200
        )
        self.vectorstore = Chroma(
            persist_directory="./chroma_db",
            embedding_function=self.embeddings
        )
    
    def add_documents(self, texts: list[str]):
        chunks = self.text_splitter.split_text("\n\n".join(texts))
        self.vectorstore.add_texts(chunks)
        self.vectorstore.persist()
    
    def search(self, query: str, k: int = 3):
        return self.vectorstore.similarity_search(query, k=k)

app/qa.py（问答模块）：

from langchain_anthropic import ChatAnthropic
from langchain.chains import RetrievalQA
from .embeddings import EmbeddingService
import os

class QAService:
    def __init__(self):
        self.embedding_service = EmbeddingService()
        self.llm = ChatAnthropic(
            anthropic_api_key=os.getenv("ANTHROPIC_API_KEY"),
            model="claude-3-sonnet-20240229",
            temperature=0
        )
        self.qa_chain = RetrievalQA.from_chain_type(
            llm=self.llm,
            retriever=self.embedding_service.vectorstore.as_retriever(),
            return_source_documents=True
        )
    
    def answer(self, question: str):
        result = self.qa_chain({"query": question})
        return {
            "answer": result["result"],
            "sources": [doc.page_content for doc in result["source_documents"]]
        }

app/main.py（FastAPI 接口）：

from fastapi import FastAPI, UploadFile, File
from .qa import QAService
from .models import QuestionRequest, AnswerResponse
import pypdf

app = FastAPI()
qa_service = QAService()

@app.post("/upload")
async def upload_document(file: UploadFile = File(...)):
    content = await file.read()
    
    if file.filename.endswith('.pdf'):
        pdf_reader = pypdf.PdfReader(io.BytesIO(content))
        texts = [page.extract_text() for page in pdf_reader.pages]
    else:
        texts = [content.decode('utf-8')]
    
    qa_service.embedding_service.add_documents(texts)
    return {"message": f"Uploaded {file.filename}"}

@app.post("/ask", response_model=AnswerResponse)
async def ask_question(request: QuestionRequest):
    result = qa_service.answer(request.question)
    return AnswerResponse(**result)

第四步：环境配置

Cursor 自动创建 .env.example：

ANTHROPIC_API_KEY=your_api_key_here

成本优化：接入 xingjiabiapi.org

官方 Claude API 的价格：

• Haiku（嵌入）：$0.25/M tokens
• Sonnet（问答）：$3/M tokens

如果用 xingjiabiapi.org 的 Claude Max 号池：

• Haiku：¥1.50/M tokens（省 78%）
• Sonnet：¥11.00/M tokens（省 48%）

修改 app/embeddings.py 和 app/qa.py，加上 base_url：

# embeddings.py
self.embeddings = AnthropicEmbeddings(
    anthropic_api_key=os.getenv("ANTHROPIC_API_KEY"),
    model="claude-3-haiku-20240307",
    anthropic_api_url="https://xingjiabiapi.org/v1"  # 加这行
)

# qa.py
self.llm = ChatAnthropic(
    anthropic_api_key=os.getenv("ANTHROPIC_API_KEY"),
    model="claude-3-sonnet-20240229",
    anthropic_api_url="https://xingjiabiapi.org/v1",  # 加这行
    temperature=0
)

运行测试

uvicorn app.main:app --reload

上传一份技术文档：

curl -X POST "http://localhost:8000/upload" \
  -F "file=@./docs/langchain_guide.pdf"

提问测试：

curl -X POST "http://localhost:8000/ask" \
  -H "Content-Type: application/json" \
  -d '{"question": "LangChain 的 RetrievalQA 怎么用？"}'

返回：

{
  "answer": "RetrievalQA 是 LangChain 提供的问答链，结合向量检索和大模型...",
  "sources": ["LangChain 提供了多种 Chain 类型...", "RetrievalQA 的核心是..."]
}

Agent 模式 vs 普通模式对比

维度	普通模式	Agent 模式
项目规划	需要手动设计目录结构	自动生成合理的项目结构
依赖管理	手动写 requirements.txt	自动分析依赖并安装
多文件协作	需要逐个文件指定修改	自动识别需要修改的文件
命令执行	需要手动运行命令	自动运行必要的命令
适用场景	小改动、单文件修改	从零搭建项目、大规模重构

踩坑记录

坑1：Agent 模式会自动运行命令

第一次用 Agent 模式时，Cursor 自动运行了 pip install，但我的虚拟环境没激活，导致依赖装到了全局环境。

解决：在 Cursor 设置里关闭"自动执行命令"，改为"询问后执行"。

坑2：API 调用次数暴增

Agent 模式每次规划都会调用 Claude API，一个项目搭下来可能调用 50+ 次。

解决：

1. 用 xingjiabiapi.org 降低成本（省 48%-78%）
2. 需求描述尽量详细，减少 Agent 反复询问

坑3：生成的代码不一定能直接运行

Agent 模式生成的代码有时会缺少 import 或者版本不兼容。

解决：生成后先跑一遍测试，有报错再让 Agent 修复。

成本分析

搭建这个 RAG 项目，Agent 模式总共调用了 68 次 Claude API：

• Sonnet（规划 + 代码生成）：约 1.2M tokens
• Haiku（文件分析）：约 0.8M tokens

官方价格：

• Sonnet：1.2M × $3 =$3.6
• Haiku：0.8M × $0.25 =$0.2
• 总计：$3.8（约 ¥27）

xingjiabiapi.org 价格：

• Sonnet：1.2M × ¥11/M = ¥13.2
• Haiku：0.8M × ¥1.5/M = ¥1.2
• 总计：¥14.4（省 47%）

如果是商业项目，每天搭建 3-5 个类似规模的项目，一个月能省 ¥1000+。

适合用 Agent 模式的场景

1. 从零搭建新项目：Agent 模式的项目规划能力很强
2. 大规模重构：需要同时修改 10+ 个文件时
3. 不熟悉的技术栈：Agent 会自动查文档、生成示例代码
4. 快速原型验证：1 小时搭出能跑的 MVP

不适合用 Agent 模式的场景

1. 单文件小改动：普通模式更快
2. 需要精确控制：Agent 可能改你不想改的文件
3. 成本敏感：Agent 模式 API 调用次数是普通模式的 3-5 倍

总结

Cursor Composer Agent 模式确实是 AI 编程的一次升级，但不是万能的。我的使用建议：

1. 新项目用 Agent，老项目用普通模式
2. 需求描述越详细，Agent 效果越好
3. 用 xingjiabiapi.org 降低成本（官方 API 太贵了）
4. 生成后一定要测试，不要盲目信任

---

📦 完整代码示例

本文涉及的所有代码已开源到 GitHub：

• RAG 知识库完整代码：xingjiabiapi-rag-demo
• LangChain 集成示例：xingjiabiapi-langchain-demo
• Python API 调用示例：xingjiabiapi-python-examples

每个仓库都包含完整的安装步骤、API 调用代码、价格对比表，复制粘贴即可使用。

---

推广信息：

• 网站：xingjiabiapi.org
• 微信：malimalihongbebe
• 商务邮箱：xingjiabiapi@163.com

关键词：Cursor Composer Agent、AI 编程、RAG 知识库、LangChain、Claude API、成本优化 字数：约 3200 字 适配平台：掘金