跳到主要内容

最小工程包运行指南

本页面向已经拿到配套工程目录的读者。只在线阅读网页时，先看每个作品集项目页的 “最小可验证包” 区块；在本地有 examples/ 目录后，再按本页运行。

这些工程包是 Mock-first（模拟优先）的教学证据包。它们不调用真实 LLM（大语言模型）、不连接真实业务系统、不保存 API Key（接口密钥）或客户资料。运行它们的目标不是证明“项目已经上线”，而是证明字段契约、失败分支、测试、评估和日志闭环存在。

运行前先确认什么​

检查项合格状态
目录位置命令在项目根目录运行，能看到 examples/ 和 package.json。
Python（编程语言）建议 Python 3.10 或更高版本。
Node.js（JavaScript 运行环境）用于执行根目录里的 npm run test:examples 聚合命令。
网络依赖首次安装 Python 依赖时可能需要访问包管理源。
密钥配置不需要 API Key、Cookie（浏览器登录凭据）、Token（访问令牌）或真实账号。

推荐运行顺序​

第一次验证时，不要一上来跑全部包。建议先选一个最贴近自己目标岗位的项目，跑通后再扩展。

目标推荐先跑原因
想准备 RAG（检索增强生成）岗位追问examples/rag-knowledge-base-qa/最容易被追问引用、拒答、资料版本和评估。
想做商业落地作品集examples/customer-service-agent-workbench/能讲清知识库、业务工具、转人工和质检。
想强调后端和工具治理examples/mcp-tool-calling-platform/能讲 schema（结构定义）、权限、审批、幂等和审计。
想展示进阶 Agent 架构examples/multi-agent-collaboration-system/能讲状态图、角色分工、停止条件和人工接管。
想证明业务分析能力examples/business-data-analysis-report-agent/能讲指标口径、事实约束、报告和复核。
想讲真实项目复盘examples/chgeo-geo-visibility-platform/能训练证据链、发布门禁和状态边界表达。

单个工程包怎么跑​

下面以 RAG（检索增强生成）工程包为例。其他工程包只需要替换目录名。

cd examples\rag-knowledge-base-qa
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe scripts\run_eval.py

如果你使用 macOS（苹果电脑操作系统）或 Linux（开源操作系统），虚拟环境命令通常改成：

cd examples/rag-knowledge-base-qa
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[test]"
python -m pytest
python scripts/run_eval.py

在根目录跑全部包​

如果已经确认 Python 依赖都安装好，可以在项目根目录运行全部 examples 门禁：

cmd /c npm run test:examples

这个命令会依次执行 6 个工程包的 pytest（测试框架）和 eval（评估）脚本。它适合做最终回归，不适合第一次排错。

每个包要看哪些文件​

文件或目录读者要看什么
README.md项目边界、目录、运行方式和验收标准。
.env.exampleMock-first 配置边界；确认不需要真实密钥、Cookie 或生产账号。
schemas.py输入、输出、状态、质量标记和日志字段是否清楚。
workflow.py成功、失败、拒绝、转人工或门禁是怎么走的。
fixtures/requests/样例输入是否覆盖正常、失败和高风险情况。
fixtures/responses/样例输出能否支撑面试讲法。
fixtures/traces/日志里能否复盘关键决策。
tests/pytest 是否覆盖底线行为。
eval/dataset、rubric 和 baseline 是否能解释质量判断。

每个包的 pytest 还会检查 fixtures/requests/sample_request.json、fixtures/responses/sample_response.json 和核心资料文件是否能通过对应的 Pydantic（数据校验库）模型。也就是说，样例不是只给读者看的截图材料，而是会被自动门禁校验的契约样本。

跑通后应该怎么讲​

面试或作品集展示时，不要只说“测试通过”。推荐按下面顺序讲：

  1. 这个包证明哪条业务底线。
  2. 输入字段和输出字段是什么。
  3. 成功样例如何通过。
  4. 失败样例为什么被拒绝、澄清、转人工或门禁拦截。
  5. pytest 检查了哪些不可退化行为。
  6. eval baseline 说明了什么，不说明什么。
  7. 如果接真实模型、真实工具或真实数据，还要补哪些门禁。

常见失败怎么处理​

现象常见原因处理方式
python 命令找不到Python 没安装或没进 PATH（环境变量路径）先确认 Python 版本，再重新打开终端。
pytest 找不到没安装 [test] 依赖在对应工程包目录重新执行 python -m pip install -e ".[test]"。
eval 结果不通过baseline、dataset 或 workflow 被改动后没有同步先看失败样例，不要直接改 baseline 掩盖问题。
日志里没有关键决策workflow 没记录 trace 事件补 trace 事件，再补测试覆盖。
想接真实模型最小包本来不接真实模型先补密钥隔离、成本限流、失败回退和安全门禁。

相关入口​