这是什么

一个完整闭环的知识库问答 Agent：用户在 Web 前台提问，Runtime 在服务端预算内编排模型采样与工具调用，从 pgvector 索引中做混合检索，最终产出每条引用都经过服务端校验的带证据回答——全过程持久化为可审计的 Run / Step 轨迹，并配有独立的运维控制台。

它不是又一个框架 Demo。所有编排（采样轮次、工具执行、上下文预算、终态提交、引用校验）都是显式 TypeScript 代码，这也是它作为 Agent 工程学习样本的价值：没有任何一步藏在黑盒里。

架构

flowchart LR
    Web[Vue 前台] -->|NDJSON 流| API[ChatController]
    Admin[运维控制台] --> AdminAPI[Admin API]
    API --> Runtime[Agent Runtime<br/>runTurnStream]
    Runtime --> Context[ModelContext<br/>token 预算 / 因果历史]
    Runtime --> Grounding[Grounding<br/>证据注册 / 引用校验]
    Runtime --> LLM[LLM Service] -->|SSE| DeepSeek([DeepSeek API])
    Runtime --> Tools[Tool 边界] --> Retrieval[混合检索<br/>lexical + vector RRF]
    Retrieval --> Gemini([Gemini Embedding])
    Retrieval --> DB[(PostgreSQL<br/>+ pgvector)]
    Runtime --> Recorder[Run / Step 记录] --> DB
    AdminAPI --> DB

一次带引用回答的完整生命周期：

用户提问
  -> 创建 AgentRun，解析模型与输入预算（本地 DeepSeek tokenizer 精确估算）
  -> 因果历史选择进入 ModelContext（COMPLETED-only、token 预算内）
  -> 模型采样（SSE 流式）
       -> 触发 retrieve_article_context 工具
       -> Gemini query embedding + pgvector 余弦检索 + lexical RRF 融合
       -> 证据注册：签发 Run 级不透明 citationKey，正文对模型扣留
  -> structured finalization：模型必须调用 submit_grounded_answer 提交答案与引用
  -> 服务端逐条校验 citationKey 与引用文本（fail-closed）
  -> Message / Grounding / Step / Run 单事务原子落库
  -> 前台渲染回答 + 可追溯的来源卡片

核心能力

工程原则

• 显式控制流 —— 编排逻辑就在 TypeScript 里，不藏在 workflow 引擎背后。
• 模型输出不可信 —— 工具名、参数、引用 key 全部先校验再执行，检索正文以 untrusted data 隔离注入。
• 分层消息模型 —— UI Message ≠ 模型输入 ≠ 运行事件 ≠ 持久化轨迹，各自独立契约。
• 预算而非上限 —— Provider 容量只是天花板，模型实际看到什么由应用策略决定。
• 终态所有权 —— 晚到的 Abort / deadline / DB 结果不能覆盖已确立的终态；COMMIT 结果不确定时如实暴露，不伪造成功。
• 证据驱动演进 —— 550+ 项测试（含真实 PostgreSQL / pgvector / SDK 传输层集成测试）先行，能力后加。

快速开始

要求：Node.js ^20.19.0 或 >=22.12.0、pnpm 10.32.1、Docker、一个 OpenAI-compatible 模型服务商的 API Key（DeepSeek 官方或中转站，启动后在管理台「模型接入」录入）、Gemini API Key（检索链路用）。

corepack enable
pnpm install
cp .env.example .env                                          # 填入 AGENT_SECRET_KEY / GEMINI_API_KEY，模型在管理台配置
docker compose up -d postgres                                 # 含 pgvector 的主库
pnpm prisma:generate
pnpm prisma:migrate
node --env-file=.env --import tsx apps/api/scripts/seed.ts    # 灌入 68 篇 Demo 文章（幂等）
pnpm --filter @agent/api index:articles -- --mode=incremental # 构建向量索引（调真实 Gemini）
pnpm dev

seed 与 index 是检索 / 引用链路可用的前提：跳过它们普通聊天仍可用，但 retrieve_article_context 会因缺少 active index 而 fail closed。自装 PostgreSQL 必须带 pgvector 扩展；从旧 postgres:16-alpine 卷升级时建议重置卷重建（musl→glibc collation 差异），开发数据可由 seed / index 完整重建。POSTGRES_DB 只在卷首次初始化时生效：沿用改名前（库名 agent_ai_seo）的已有卷时，.env 里的 DATABASE_URL 保留 agent_ai_seo，或重置卷按新库名 agent 重建。

完整环境变量见 .env.example；常用验证：pnpm typecheck、pnpm lint、API 按边界拆分的测试入口（如 pnpm --filter @agent/api test:tools，完整清单见 apps/api/package.json 的 test:* 脚本）、pnpm --filter @agent/ai test。

packages/ai 与 packages/contracts 以 dist 被 API 运行时消费，包括 tsx --test 跑的 test:* 脚本；pnpm dev 会在启动前构建，但 dev 的 tsc --watch 只重编 API 自身，不重建包的 dist（类型检查会随包源码更新，运行时加载的仍是旧 dist）。改过 packages/ai/src 或 packages/contracts/src 后手动重建：

pnpm --filter @agent/ai build
pnpm --filter @agent/contracts build

目录结构

apps/
  api/        NestJS API：Agent Runtime、Tool、检索与索引、Prisma 边界、LLM 门面与 DI 壳
  web/        Vue 3 对话前台（流式渲染 + 来源卡片）
  admin/      运维控制台（概览 / 会话记录 / Run Trace 与检索审计 / 模型接入）
packages/
  ai/         模型客户端、OpenAI-compatible 流适配、模型类型 / 错误 / profile（零 Nest、零 Prisma）
  contracts/  前后端共享协议与类型（编译期防漂移）
prisma/       PostgreSQL schema、pgvector migration 与 fixtures（seed 脚本在 apps/api/scripts/seed.ts）
docs/         路线图、任务归档、研究沉淀与工作日志

更多文档

阶段路线见 docs/roadmap.md，任务归档见 docs/tasks/，架构决策与推进记录见 docs/work-log.md。项目按 8 个阶段迭代完成：多轮流式对话 → 有界 Agent Loop → 上下文工程 → Grounded Retrieval，全部经 Issue / PR / 提交前 Review 与逐条验收收口。