STRUCTURE.md

项目目录与文件说明

本文是仓库的文件索引。它回答两个问题：第一次进入项目应该看什么，以及每个受版本控制的文件分别负责什么。

先按需求找入口

你想做什么	建议先看
了解项目目标和七篇教程路线	README.md
用最短路径安装并运行	QUICKSTART.md
从头学习某一章	对应的 tutorial-0x-*.md
直接阅读或运行代码	examples/0x-*/ 下的示例
不调用真实 LLM，先验证本地环境	verify_setup.py、test_local.py、test_tutorial_*.py
学习评估、Trace、指标和回归门禁	tutorial-06-evaluation-and-observability.md、examples/06-evaluation/
启动 API 服务或部署到容器/Kubernetes	examples/07-production/README.md
查看每章实际交付和验证结果	TUTORIAL_*_COMPLETION_REPORT.md
参与开源协作或报告安全问题	CONTRIBUTING.md、SECURITY.md

整体结构

python-to-agent/
|-- .github/workflows/ci.yml       # GitHub Actions 持续集成
|-- examples/                      # 七章配套示例代码
|   |-- 01-basic-chat/
|   |-- 02-tool-calling/
|   |-- 03-rag/
|   |-- 04-agent-workflow/
|   |-- 05-langchain-practice/
|   |-- 06-evaluation/
|   `-- 07-production/
|-- tutorial-01-*.md               # 教程 01-07 正文
|-- ...
|-- tutorial-07-*.md
|-- test_local.py                  # 教程 01 的离线基础验证
|-- test_tutorial_02.py            # 教程 02-07 的配套验证
|-- ...
|-- test_tutorial_07.py
|-- README.md                      # 项目首页
|-- QUICKSTART.md                  # 快速开始
|-- STRUCTURE.md                   # 本文件
`-- requirements.txt              # 全项目 Python 依赖

目录命名保持一一对应：tutorial-06-*.md 是第 6 章正文，examples/06-evaluation/ 是第 6 章代码，test_tutorial_06.py 是第 6 章验证脚本。

根目录文档

文件	用途
README.md	GitHub 项目首页，说明项目定位、教程路线、技术栈、快速运行方式和学习检查点。新读者从这里开始。
QUICKSTART.md	5 分钟快速入门，集中列出环境检查、依赖安装、API Key 配置和首个示例的运行命令。
STRUCTURE.md	当前文件，提供完整目录导航和逐文件用途说明。
PROJECT_STATUS.md	项目阶段状态、已完成内容和最初的能力检查记录。适合了解项目演进，不作为最新运行手册。
PROJECT_SUMMARY.txt	教程 01 完成时留下的早期项目快照，里面的文件数量和统计是历史数据；当前结构以本文和 README 为准。
COMPARISON_WITH_JAVA.md	对比 Python 与 Java 在 Agent 开发中的框架、代码风格、异步模型和依赖管理差异。
CHANGELOG.md	按版本记录各教程、示例和验证能力的新增与变更。
TUTORIAL_02_SUMMARY.md	教程 02 的实施总结，记录 Tool Calling 章节的产物和设计要点。
TUTORIAL_02_COMPLETION_REPORT.md	教程 02 的完成清单与验证结果。
TUTORIAL_03_COMPLETION_REPORT.md	教程 03 的完成清单与验证结果。
TUTORIAL_04_COMPLETION_REPORT.md	教程 04 的完成清单与验证结果。
TUTORIAL_05_COMPLETION_REPORT.md	教程 05 的完成清单与验证结果。
TUTORIAL_06_COMPLETION_REPORT.md	教程 06 的完成清单与验证结果。
TUTORIAL_07_COMPLETION_REPORT.md	教程 07 的完成清单与验证结果。
CONTRIBUTING.md	开源贡献指南，说明开发流程、验证命令、代码规范和 Pull Request 要求。
SECURITY.md	安全策略，说明漏洞报告渠道、报告内容和支持范围。安全问题不要直接提交公开 Issue。
LICENSE	MIT 开源许可证，规定项目的使用、修改和再分发条件。

教程正文

教程正文负责解释概念、设计决策和完整实践路径；同编号的 examples/ 目录负责给出可运行代码。

文件	主要内容
tutorial-01-llm-api-and-prompt.md	LLM API、Token、参数、流式输出、结构化输出和 Prompt Engineering 基础。
tutorial-02-tool-calling.md	工具定义、JSON Schema、参数校验、风险分级、人工审批和客服 Agent。
tutorial-03-rag.md	Embedding、文档切分、向量数据库、检索、引用溯源和完整 RAG 系统。
tutorial-04-agent-orchestration.md	ReAct、Plan-and-Execute、LangGraph 状态机、持久化和 Human-in-the-loop。
tutorial-05-langchain-practice.md	LCEL、Runnable、会话历史、Callback/Trace、自定义 Retriever 和 Parser。
tutorial-06-evaluation-and-observability.md	评估数据集、业务切片、确定性指标、LLM-as-a-Judge、Trace、监控和发布门禁。
tutorial-07-production-deployment.md	配置与生命周期、异步并发、重试/熔断/背压、SSE、FastAPI、容量规划和部署。

教程 01：基础对话

目录：examples/01-basic-chat/

文件	用途
simple_chat.py	最小可用的 LLM 对话示例，演示加载环境变量、创建客户端、发送消息和读取 Token 用量。
stream_chat.py	演示流式响应，包含直接打印和回调处理两种消费方式。
structured_output.py	用 JSON Mode 和 Schema/Function Calling 抽取订单意图，并使用 Pydantic 校验结果。
cost_calculator.py	统计 Token、按模型单价估算调用成本，并比较不同模型的预算。价格表是教学示例，实际使用前需核对供应商最新价格。

对应验证：test_local.py。

教程 02：工具调用

目录：examples/02-tool-calling/

文件	用途
README.md	本章代码的运行顺序、依赖、API Key 要求和预期输出。
01_basic_tool.py	从普通 Python 函数到 Tool Calling 的最小闭环，演示工具 Schema、模型选择工具和回传执行结果。
02_param_validation.py	使用 Pydantic 对天气、订单等工具参数做类型、格式和业务规则校验。
03_human_approval.py	给工具操作划分风险等级，高风险操作进入人工确认，展示安全控制边界。
04_customer_service_agent.py	综合案例：客服 Agent 调用订单、物流等业务工具并处理多步请求。

对应验证：test_tutorial_02.py。

教程 03：RAG

目录：examples/03-rag/

文件	用途
README.md	本章五个示例的学习顺序、环境要求和运行方法。
01_basic_embedding.py	生成文本向量、计算相似度，帮助理解语义检索的基础数据形态。
02_document_chunking.py	定义文档块模型并比较固定长度、递归等切分策略。
03_vector_database.py	初始化 Chroma、写入向量、执行相似度检索和管理持久化数据。
04_complete_rag_system.py	串联文档、切分、Embedding、检索、上下文组装、回答和引用的完整 RAG 流程。
05_advanced_rag.py	演示更高级的检索策略，如查询改写、混合检索、重排和结果融合。

对应验证：test_tutorial_03.py。

教程 04：Agent 工作流

目录：examples/04-agent-workflow/

文件	用途
README.md	本章工作流示例的运行方式和从简单循环到完整工单系统的学习顺序。
01_react_agent.py	实现 ReAct 的 Thought/Action/Observation 控制循环、工具注册、停止条件和 Trace。
02_plan_execute.py	把任务拆成计划步骤，逐步执行、记录结果，并在失败时调整执行过程。
03_langgraph_state_machine.py	用 LangGraph 表达工单的节点、条件分支、循环和终止状态。
04_persistence_human_in_loop.py	演示状态持久化、暂停与恢复，以及高风险操作的人工审批。
05_ticket_workflow.py	综合案例：校验、分类、优先级、自动处理、升级和通知组成的工单 Agent。

对应验证：test_tutorial_04.py。

教程 05：LangChain 实践

目录：examples/05-langchain-practice/

文件	用途
README.md	本章 LCEL、History、Callback 和自定义组件示例的运行说明。
01_lcel_runnable.py	展示 Runnable 的顺序、并行、分支和回退组合，以及 LCEL 数据流。
02_conversation_history.py	按 session_id 隔离多轮对话历史，并展示本地实现与 LangChain 实现。
03_callbacks_and_tracing.py	用 Callback 记录节点开始、结束、耗时和错误，形成可检查的 Trace。
04_custom_components.py	实现本地关键词 Retriever 和结构化输出 Parser，说明如何接入自定义组件。
05_customer_service_chain.py	综合案例：把历史、检索、订单识别和回答生成组合成多轮客服 Chain。

对应验证：test_tutorial_05.py。

教程 06：评估与可观测性

目录：examples/06-evaluation/

文件	用途
README.md	本章评估代码的执行顺序、指标含义和离线验证方式。
evaluation_core.py	共享核心模型：评估样本、Agent 输出、数据集清单、评估报告和离线规则 Agent。其他评估示例会复用它。
evaluation_metrics.py	共享确定性指标：文本规范化、关键词召回、集合精确率/召回率和单样本评分。
observability.py	共享可观测性组件：敏感数据脱敏、Span/Trace 收集、请求观测和窗口指标。
01_dataset_and_slices.py	校验评估集 Schema，读写 JSONL，并按标签切分关键业务场景。
02_deterministic_evaluation.py	执行确定性评估并输出意图、事实、引用、工具和任务成功率报告。
03_llm_as_judge.py	定义结构化裁判协议、Prompt、结果解析和离线 Fake Judge，用于校准 LLM 裁判流程。
04_tracing_and_monitoring.py	把 Agent 执行接入 Trace 和指标窗口，计算请求量、错误率、延迟并生成告警。
05_regression_gate.py	对比基线与候选版本，检查总体及关键切片退化，给出是否允许发布的结论。

对应验证：test_tutorial_06.py。

教程 07：生产部署

目录：examples/07-production/

示例与共享模块

文件	用途
README.md	生产示例总入口，列出本地运行、FastAPI、Docker、Compose、Kubernetes 和验证命令。
production_core.py	生产核心：环境配置、Secret 校验、请求/响应模型、异步 Agent 和应用资源生命周期。
resilience.py	韧性组件：并发门、deadline、重试、指数退避、熔断和幂等冲突处理。
production_service.py	服务层：统一调用核心 Agent，管理指标、超时、错误映射和幂等结果。
streaming_sse_adapter.py	把异步 Agent 事件编码为 SSE，处理心跳、客户端断开和任务取消。
01_config_and_lifecycle.py	演示从环境变量加载配置，以及应用资源启动和优雅关闭。
02_async_concurrency.py	演示异步重试、并发限制、背压和熔断器状态变化。
03_streaming_sse.py	演示 SSE 事件流、心跳和断连取消，不需要先启动 Web 服务。
04_fastapi_service.py	FastAPI 应用入口，提供认证、中间件、错误响应、同步/SSE 接口及存活/就绪检查。
05_deployment_and_capacity.py	使用到达率、延迟和目标利用率估算并发需求与推荐副本数。

部署文件

文件	用途
.dockerignore	排除缓存、虚拟环境、Git 元数据和本地 Secret，缩小 Docker 构建上下文。
requirements-production.txt	生产镜像所需的精简依赖，和全教程依赖分开管理。
Dockerfile	构建非 root 用户运行的 FastAPI 镜像，并配置健康检查和启动命令。
compose.yaml	本地用 Docker Compose 启动服务，注入配置并执行健康检查。
deploy/kubernetes.yaml	Kubernetes 的 ConfigMap、Secret 占位、Deployment、Service、探针、资源限制和 HPA 示例。

对应验证：test_tutorial_07.py。

验证与测试脚本

这些脚本直接用 Python 运行，不依赖额外的测试命令封装；CI 也执行同一组脚本。

文件	用途
verify_setup.py	检查 Python 版本、核心依赖和可选 API Key 是否已正确配置。
test_local.py	教程 01 的离线基础验证，覆盖 Token、Pydantic、成本和消息结构。
test_tutorial_02.py	验证工具 Schema、参数校验、安全审批和客服工具调用。
test_tutorial_03.py	验证文档切分、向量检索和 RAG 关键流程；需要外部服务的部分按环境处理。
test_tutorial_04.py	离线验证 ReAct、计划执行、LangGraph 状态机、持久化和工单工作流。
test_tutorial_05.py	离线验证 LCEL、会话隔离、Callback、自定义组件和客服 Chain。
test_tutorial_06.py	离线验证数据集、指标、裁判、Trace、监控和回归门禁。
test_tutorial_07.py	验证生产配置、异步韧性、SSE、FastAPI、容量规划和部署清单。

仓库与环境配置

文件	用途
.env.example	可提交的环境变量模板，只保留变量名和占位值。真实 Key 应写入本地 .env，不要提交。
.gitignore	排除 .env、虚拟环境、Python 缓存、测试缓存、IDE 配置和本地 Agent 配置。
.gitattributes	固定文本文件的换行和属性，减少 Windows/Linux 协作时的无意义差异。
.github/workflows/ci.yml	GitHub Actions 工作流：安装依赖、编译 Python 文件并执行全部验证脚本。
requirements.txt	教程 01-07 的完整 Python 依赖清单，适合本地学习和 CI。生产镜像使用更小的 requirements-production.txt。

阅读和运行约定

1. 编号文件按顺序学习，例如先运行 01_dataset_and_slices.py，再运行 02_deterministic_evaluation.py。
2. 没有编号的 Python 文件通常是共享模块，由同目录的编号示例和测试脚本导入，不必优先单独运行。
3. 每章目录里的 README.md 更偏向“怎么运行”，根目录的 tutorial-*.md 更偏向“为什么这样设计”。
4. TUTORIAL_*_COMPLETION_REPORT.md 和 PROJECT_SUMMARY.txt 是项目建设记录，不是学习主线。
5. .env、虚拟环境和运行生成的缓存不会进入 Git；.env.example 才是应提交的配置模板。