规格驱动的代理式Web启动器(Copilot + Ollama RAG)
确定性、人为触发的规格(spec)工作流程,专为……定制 GitHub Copilot (聊天) 和一个 本地RAG(检索增强生成) 栈(stack)
- 后端: FastAPI
- RAG:(通常指)检索增强生成(Retrieval-Augmented Generation) Ollama(生成+嵌入)+ ChromaDB(本地向量存储)
- 前端: React(Vite)
- 测试: Pytest(后端),Vitest + RTL(前端)
快速入门(本地)```bash
curl -fsSL https://ollama.com/install.sh | sh # or follow mac/win installer
ollama pull llama3.1:8b
ollama pull nomic-embed-text
1. 后端:```bash
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload
- 前端:```bash
cd ../frontend
npm install
npm run dev
1. 在另一个终端中为RAG(检索增强生成)输入文档:```bash
cd backend && source .venv/bin/activate
python -m app.rag.ingest ../rag/docs
- 通过API提出问题:```bash
curl -s localhost:8000/api/rag/query -X POST -H "Content-Type: application/json" -d '{"question":"What is this project about?"}'
> **决定论与审计:** 步骤已被锁定 `/specs/STEP_*.md`所有与Copilot一起使用的提示都应复制到 `/docs/PROMPTS.md` 并总结在 `/docs/AI_ACTIVITY_LOG.md`。
## 代理工作流(确定性工具运行器)```bash
# RAG-answer workflow (no MCP)
cd backend && source .venv/bin/activate
python -m orchestrator.runner --workflow orchestrator/workflows/rag_answer.yaml
## MCP server demo (read-only files)
# Dry-run to validate steps
python -m orchestrator.runner --workflow orchestrator/workflows/fs_read_example.yaml --dry-run
# Execute (runner starts the MCP server command from the workflow)
python -m orchestrator.runner --workflow orchestrator/workflows/fs_read_example.yaml
MCP Python SDK 提供了工具/资源/提示;请参阅其快速入门和概念部分(您将在示例服务器中看到相同的构造)。
对于更多服务器(如GitHub、Slack等),请浏览官方示例和服务器注册表,以集成已知可靠的工具。
可重用的代理规范与模板
A) 工具规范(请放入/docs/TOOLS_SPEC.md或/tools/specs/*.yaml)```yaml
name: rag.query
version: 1.0.0
summary: Ask the local RAG API a question and return answer + sources.
input_schema:
type: object
required: [question]
properties:
question: { type: string, minLength: 3, maxLength: 2000 }
output_schema:
type: object
required: [answer, sources]
properties:
answer: { type: string }
sources:
type: array
items:
type: object
required: [path, chunk_index]
properties:
path: { type: string }
chunk_index: { type: integer, minimum: 0 }
side_effects: network
security:
auth: none (local)
errors:
- code: RAG_EMPTY
when: no docs in store
- code: RAG_FAILURE
when: vector search or generation fails
### B) 工作流YAML(每一步使用一个工具,避免意外)```yaml
name: rag.answer
steps:
- use: rag.query
with:
question: "What is this project about?"
With MCP tools (strict allow-list)
name: fs_read_example
mcp:
- server: fileserver
command: "uv run python mcp_servers/fileserver/server.py"
tools_allowlist: ["fs.list_dir", "fs.read_text"]
steps:
- use: mcp:fs.list_dir
with: { path: "./docs" }
- use: mcp:fs.read_text
with: { path: "./docs/AGENT_ARCHITECTURE.md" }
该运行器验证输入,编写后端代码/运行/_.jsonl 文件格式,如果工具未被列入允许列表或输入不符合模式,则停止执行。
此试剂盒中的MCP
-
服务器:mcp_servers/fileserver/server.py —— 这是一个只读的FastMCP服务器,配备了两个安全工具:fs.list_dir(列出目录)和fs.read_text(读取文本,仅限cap+UTF-8编码)。
-
客户端:backend/orchestrator/mcp_client.py —— 通过标准输入输出连接,列出工具,并调用工作流中允许使用的工具。
-
文档:MCP_OVERVIEW.md 解释了安全态势 + 参考资料。
SDK(软件开发工具包)& 规范: Python SDK实现了“工具/资源/提示”以及全面的协议支持(stdio/SSE/HTTP)。如需在此演示之外进行扩展,请参阅快速入门指南和规范以获取确切的架构/字段信息。
兼容性说明: OpenAI的代理SDK(软件开发工具包)和“连接器/MCP(机器控制协议)”文档描述了导入工具定义时的互操作性和成本语义。如果您/当您将这些工具集成到托管代理框架中时,这些信息将非常有用。
有益的解释(基于检索增强生成技术+自主选择)
-
为什么选择本地RAG(检索增强生成)? 隐私+速度。使用Ollama同时处理嵌入和生成,以避免不匹配带来的麻烦;使用Chroma作为无需操作的本地向量数据库。
-
为什么采用分步锁定的工作流程? 零“隐性”自主权 = 避免范围蔓延。你掌控计划;执行者只需执行并记录。
-
何时应选择MCP而非本地工具?
-
MCP:当你需要一个标准的、可发现的工具界面,或者想要重用一个已知的服务器(文件系统、GitHub、搜索等)时。
-
本地工具:当事物与特定项目相关,或者你不需要进行发现/传输时使用。
重要的安全与防偏移护栏
-
最小权限原则:仅暴露所需内容;优先选择只读模式(此工具包的示例服务器为只读模式)。
-
白名单:每个MCP工具调用都必须在tools_allowlist中列出名称。
-
速率限制:如果封装远程API,请为每种工具添加配额。
-
清理日志:运行程序记录输入/输出(生产环境中进行截断/个人信息去标识化处理)。
-
保持最新状态:关注协议和服务器的更新(例如,文件服务器的安全修复)并确保您的SDK保持最新版本。
Copilot 提示片段(粘贴这些)
-
仅使用脚手架
“仅根据/specs/STEP_0X_*.md生成框架代码。不包含业务逻辑。输出文件路径和内容。” -
测试先行
“为(某个功能/模块)编写失败的测试用例 不要执行代码。以“STOP – 测试按设计失败”结尾。”
“做出最小的改动以使这些测试通过。不要添加新功能。”
-
工具规格
“创建/tools/specs/使用 /docs/TOOLS_SPEC.md 生成 .yaml 文件(输入/输出模式 + 错误代码)。“ -
MCP服务器
“为(某应用/系统)搭建一个只读的FastMCP服务器 ,包含README文件,并且路径/大小有限制。”
