LLM-dev-demo AGENTS.md

AGENTS.md

This file provides guidance to Qoder (qoder.com) when working with code in this repository.

仓库性质

这是一个 LLM 应用开发教学实验合集，不是单一应用：每个 demo 是自包含脚本，按学习路线递进（基础调用 → 结构化输出 → Function Calling → LangGraph → Agent Harness → MCP → RAG → Text2SQL → 完整项目）。根目录 实验手册.md 是面向学员的引导式手册，其中的命令均经实机验证——修改 demo 的用法、参数或依赖后，必须同步更新实验手册与相关 README，保持文档与代码一致。

环境与密钥约定

• 密钥一律走仓库根目录 .env（模板见 .env.example），切勿硬编码 API Key。关键变量：API_KEY / API_BASE（OpenAI 兼容端点）/ MODEL / EMBED_MODEL / DASHSCOPE_API_KEY。
• 所有脚本在启动时用 load_dotenv() 按相对路径显式加载根目录 .env（子目录脚本用 Path(__file__).resolve().parent.parent / ".env" 这类写法定位），新增脚本应保持此约定。
• 所有 demo 支持 --model / --api_key / --base_url 命令行参数覆盖默认值（默认平台为硅基流动）。切换平台示例：--base_url https://dashscope.aliyuncs.com/compatible-mode/v1 --api_key $DASHSCOPE_API_KEY。
• 企业专属实例的 Key 常有模型白名单，跑 demo 前先用 curl $API_BASE/models 探测可用模型。

依赖管理

根目录 requirements.txt 管理公共依赖；子项目独立依赖不得混入根 requirements，各自维护：

子项目	依赖位置	安装/运行
function_call_and_agent_demo/excel-process/	自己的 requirements.txt	streamlit run app.py（需本机有 Docker，llm-sandbox 基于容器）
function_call_and_agent_demo/agent_harness_demo/	自己的 requirements.txt（deepagents）	python agent_harness_demo.py
finance_doc_review/	pyproject.toml（uv）	uv venv .venv --python 3.12 && uv pip install -p .venv/bin/python -e .，然后 finance-doc-review samples/xxx.txt [--json]

版本约束用 >= 宽松策略，但 mcp[cli] 必须锁 <2：2.0 移除了 mcp.server.fastmcp 高层封装，MCP demo 依赖 1.x。

常用命令

# 根目录脚本（示例）
python first_llm_app.py
python structured_output_demo.py
python mini_rag_demo.py --query "..." --top_k 3     # --rebuild 强制重建向量索引
python text2sql_demo.py                              # 依赖根目录 Chinook.sqlite
python wiki_kb_agent_demo/kb_agent.py --once "问题"

# Function Calling / Agent
python function_call_and_agent_demo/demo-agent-with-tools-arg.py
python function_call_and_agent_demo/langgraph_demo/langgraph_agent_scaffold.py --query "..."
python function_call_and_agent_demo/mcp_server_demo.py     # MCP 服务端
python function_call_and_agent_demo/mcp_client_agent_demo.py  # MCP 客户端 agent

# Streamlit 应用
streamlit run function_call_and_agent_demo/excel-process/app.py