最小可验证包模板
最小可验证包不是完整源码，也不是商业交付物。它的目标是证明一个 AI Agent（人工智能体）项目有清晰的输入、输出、字段契约、失败样例、测试和评估证据。
读者做作品集时，不要只放截图。截图只能证明“看起来像完成了”，最小可验证包要证明“这个流程可以被检查、复现和追问”。
本书配套的 6 个最小包
本书的 6 个作品集项目都配了 examples/ 教学工程包。它们不是完整商业源码，而是给读者对照的“证据包样板”：先证明字段、流程、失败和评估闭环，再考虑接真实模型、真实工具或真实数据。
| 作品集项目 | 工程包 | 先证明的能力 |
|---|---|---|
| 企业知识库 RAG 问答系统 | examples/rag-knowledge-base-qa/ | 有证据回答、无证据拒答、过期资料拦截。 |
| 智能客服 Agent 工作台 | examples/customer-service-agent-workbench/ | 知识回复带引用、权益类问题转人工、缺上下文先澄清。 |
| MCP 与 Tool Calling 业务工具调用平台 | examples/mcp-tool-calling-platform/ | 只读工具执行、高风险写入确认、幂等回放。 |
| 多智能体任务协作系统 | examples/multi-agent-collaboration-system/ | 状态图完成任务、写入工具转人工、步数预算停止。 |
| 经营数据分析与报表解读 Agent | examples/business-data-analysis-report-agent/ | 报告绑定已审核指标、未知指标拒绝、高风险动作复核。 |
| CHGEO GEO 可见性分析平台 | examples/chgeo-geo-visibility-platform/ | 结论绑定证据、发布请求过门禁、无证据拒绝结论。 |
运行命令和边界说明放在每个项目页的 “最小可验证包” 区块、最小工程包运行指南，以及对应 examples/ 目录的 README 里。
一个最小包应该包含什么
| 材料 | 必须回答的问题 | 合格标准 |
|---|---|---|
| 项目说明 | 这个项目解决什么业务问题？ | 一句话定位、目标用户、输入、输出和禁止承诺。 |
| 样例数据 | 系统用什么输入演示？ | 至少 3 条成功样例、3 条失败样例、1 条高风险样例。 |
| 字段契约 | 系统之间传什么？ | 请求、响应、状态、日志和评估字段都能解释。 |
| Mock 结果 | 不接真实系统时怎么演示？ | 工具返回、模型输出和异常分支都有固定样例。 |
| 验收脚本 | 怎么证明没有退化？ | 有可重复运行的检查命令或手工验收表。 |
| 评估记录 | 输出质量怎么判断？ | 有黄金问题、回归用例、评分维度和失败分类。 |
| 面试讲法 | 怎么把证据讲给面试官？ | 有 10 秒定位、90 秒讲解和风险边界说明。 |
推荐目录结构
project-name/
README.md
data/
sample_requests.jsonl
sample_documents/
regression_cases.jsonl
schemas/
request.schema.json
response.schema.json
log.schema.json
.env.example
outputs/
baseline_response.json
failure_examples.json
tests/
test_contract.py
test_regression.py
reports/
eval_summary.md
这只是推荐结构。你可以用别的技术栈，但不能缺少“样例、契约、失败、验收、讲法”这五类证据。.env.example 只写 Mock-first 配置和假数据路径，不写真实 API Key（接口密钥）、Cookie（浏览器登录凭据）或生产账号。
README 应该怎么写
| 区块 | 写法 |
|---|---|
| 项目一句话 | 用业务语言说明场景，不用堆模型名。 |
| 当前状态 | 明确写“教学用 Mock-first 最小包”“未接真实生产系统”。 |
| 如何演示 | 写清输入哪个样例、期望看到什么输出。 |
| 如何验收 | 写清检查命令、验收表或人工检查步骤。 |
| 失败样例 | 展示缺资料、权限不足、工具失败和高风险转人工。 |
| 风险边界 | 明确不自动付款、不自动删除、不自动发布、不访问真实隐私数据。 |
| 面试讲法 | 准备 90 秒说明，能讲清业务目标、工程边界和证据。 |
最小包证明什么，不证明什么
| 能证明 | 不能证明 |
|---|---|
| 你理解业务输入输出。 | 真实客户已经上线使用。 |
| 你能设计字段契约和日志。 | 模型在所有真实场景都准确。 |
| 你考虑了失败、权限和转人工。 | 已经具备完整权限中心和生产运维。 |
| 你能用样例做回归检查。 | 已经完成商业级 SLA（服务等级协议）。 |
面试时可以说：“这是教学用最小可验证包，用来证明字段、流程、失败和评估闭环。它不是完整商业源码，也没有接入真实客户系统。”
自查清单
| 检查项 | 通过标准 |
|---|---|
| 是否有成功样例 | 至少 3 条，并能解释输出字段。 |
| 是否有失败样例 | 至少覆盖缺资料、权限不足和工具失败。 |
| 是否有高风险样例 | 涉及退款、付款、删除、发布、隐私时必须转人工。 |
| 是否有字段契约 | 输入、输出、状态、日志字段都稳定。 |
| 是否有验收方式 | 能运行测试，或能按表格逐项检查。 |
| 是否有面试讲法 | 能讲清“已实现、Mock-first、未接真实能力”。 |
和作品集的关系
一个作品集项目至少要有一份最小可验证包。页面负责展示项目价值，最小包负责提供证据。没有最小包的作品集，面试时很容易变成“我做了一个页面”。