事实核验：2026-08-26 · 状态：现行内容

记录仅说明核验时间与维护状态，不保证适用于所有环境；使用前请留意正文中的版本、适用条件与风险提示。

AI Agent 项目库导览

abstract 这套项目库解决什么问题

会调用模型、接一个向量库或画出 Agent 流程图，不等于能交付企业级系统。真正困难的是：输入数据能否被信任，指标口径是否唯一，用户是否只能看到有权看的内容，回答质量能否回归验证，成本与延迟是否可控，发生错误后能否还原完整轨迹。本项目库用三个可复刻项目，把这些横切能力放进同一套交付框架。

学习目标

完成三个项目后，你应该能够：

  1. 把模糊的“做一个智能助手”翻译成数据契约、权限边界、质量指标和验收门禁；
  2. 理解语义层为何是 Text-to-SQL 的确定性核心，而不是把全库 DDL 直接塞给模型；
  3. 把 RAG 从“文档切块与向量检索”升级为有责任人、版本、有效期和下线流程的知识产品；
  4. 设计覆盖单步、轨迹和端到端结果的评估集，并将坏案例转成回归资产；
  5. 用 Trace、Metric、Log 和审计记录解释一次 Agent 执行的质量、成本、性能与权限决策；
  6. 明确自动回答、澄清、拒绝、降级和人工接管的决策边界。

项目地图

项目 从什么问题出发 核心交付 重点能力
企业级 Text-to-SQL 助手 业务人员取数慢、同名指标答案不一致 语义查询助手、只读执行网关、评估集、审计看板 数据契约、语义层、行列权限、SQL 安全、成本
RAG 知识库治理 知识过期、来源不清、引用不可追溯 知识准入规范、摄取流水线、检索评估、生命周期治理 内容契约、ACL、版本、召回质量、删除传播
Agent 评估与可观测性 系统“能返回”却无法证明“返回得对” Trace 模型、分层 Eval、质量门禁、成本与告警闭环 轨迹评估、Guardrail、SLO、成本归因、复盘

统一可复刻结构

三个项目沿用现有项目库的复刻方式，但增加了 Agent 项目的六个必答问题：

  1. 项目背景与需求翻译：谁在什么决策中使用结果，错误会造成什么影响；
  2. 数据与知识契约：输入的所有者、模式、更新频率、敏感级别、有效期与兼容策略；
  3. 架构与权限边界：身份在哪里传递，权限在哪里裁决，工具能做什么、不能做什么；
  4. 实施与交付物：表、接口、配置、评估集、看板、运行手册和审计证据；
  5. 评估、成本与可观测性：正确性、拒答、延迟、Token、检索与工具调用如何归因；
  6. 上线、复盘与表达：灰度门禁、故障处置、简历表达和三分钟面试讲法。
flowchart LR
    A[业务问题] --> B[契约与语义]
    B --> C[权限与执行边界]
    C --> D[Agent工作流]
    D --> E[离线评估]
    E --> F[灰度上线]
    F --> G[在线观测]
    G --> H[坏案例回归]
    H --> B

统一项目资料包

每个项目都应在自己的仓库中保留以下材料，而不是只保留一段演示代码：

资料 最低内容 评审问题
problem-brief 用户、任务、风险、非目标 为什么必须用 Agent，而不是搜索、BI 或固定工作流？
contract 字段、口径、ACL、版本、SLA 上游变化时，谁收到通知，如何阻断不兼容变更？
eval-dataset 黄金样本、边界样本、拒答样本 数据是否覆盖真实分布和高风险长尾？
policy 工具白名单、资源上限、人工接管 哪些动作永远不能由模型自行决定？
observability Trace 字段、指标口径、告警规则 能否从一次错误回答追到模型、知识、工具和权限版本？
runbook 发布、回滚、降级、复盘 值班人员不读代码能否恢复服务？

warning 不要用“准确率”掩盖风险

Agent 的总体平均分可能很好，但仍可能在敏感数据、财务口径或删除请求上犯不可接受的错误。项目验收要同时看平均质量、关键场景通过率、拒答能力和最坏情况，并让高风险规则拥有一票否决权。

推荐复刻顺序

第一阶段：单域、只读、可回放

先选一个业务域、一组有明确责任人的数据或文档，只开放只读工具。完成身份透传、引用、Trace 和离线评估。此阶段不要追求自主规划，而要证明输入与输出都可解释。

第二阶段：建立门禁与成本基线

将黄金集接入发布流水线；按模型调用、检索、重排、数据库扫描和人工复核拆分成本；给延迟与预算设置分层阈值。先有基线，再谈优化，不用拍脑袋目标替代真实测量。

第三阶段：扩大覆盖并运营坏案例

新增业务域前先补契约、ACL 和评估样本。线上低评分、人工纠正、越权拦截和超预算轨迹进入待标注队列，经责任人确认后加入回归集。版本升级必须能重跑历史样本并比较差异。

决策边界

  • 适合做 Agent：任务需要在受控工具之间多步决策，且中间过程可记录、可校验、可中止。
  • 更适合固定工作流：路径稳定、规则清楚、失败代价高，模型没有必要决定下一步。
  • 更适合传统搜索或 BI：用户只需查已知文档或固定指标，没有复杂推理和工具编排。
  • 暂不自动化：权限无法可靠下推、来源没有责任人、没有可构建的验收集，或错误无法被及时发现。

练习与验收

任选一个项目完成复刻，并用以下问题进行答辩：

  1. 删除一个知识源或撤销一个用户权限后，缓存、索引和历史会话何时失效？
  2. 模型版本不变、结果却退化时，如何区分数据漂移、检索退化、工具失败和提示变更？
  3. 一次请求的成本由哪些步骤产生，能否按用户、业务域和成功任务归因？
  4. 哪些请求必须澄清，哪些必须拒绝，哪些可降级到模板或人工？
  5. 发布新版本前，什么指标未达标会阻断上线？谁有权批准例外？

相关知识