核心理念：Agent = LLM（大脑） + Tools（双手） + Memory（记忆） + Loop（循环）
小玉 Agent 是一个从零构建的通用型 AI Agent 框架。核心能力通过 DIP（依赖倒置）抽象解耦各层，支持会话持久化恢复、SSE 流式对话、双通道（FTS5 + 向量）记忆检索、三阶段上下文压缩、请求级 trace_id 串联，并配套完整的测试与容器化部署。
将 Agent 核心能力封装成一个可通过标准后端服务访问、追踪、测试和部署的系统。
- 会话持久化 —
SQLiteSessionStore落库全量对话历史，进程重启后会话可续接（DIP：SessionStoreProtocol +NullSessionStore惰性回退） - SSE 流式对话 —
/chat/stream逐 token 推送，桥接同步 agent 循环到异步 SSE - 双通道记忆检索 — FTS5 全文（jieba 分词）+ ChromaDB 向量，RRF 融合排序
- 三阶段上下文压缩 — tool_pruner → head_tail_guard → summary_generator，阈值全收口到
AgentConfig - 请求级 trace_id —
contextvars隔离，中间件注入 + 日志串联，响应头回写X-Trace-Id - 健康检查 —
/health检查 LLM 配置 / memory 目录 / session DB，degraded 仍 200 避免 LB 摘流 - RAG 评估脚手架 — Recall@k / Precision@k / MRR + 离线标注数据集，可纳入 CI 监控检索退化
- DIP 防腐层 —
ToolResultSink/ToolHookBus/LLMCompleter/MemorySourceProtocol，tools/memory 层不逆向 import core
| 文档 | 说明 |
|---|---|
| 00-架构原则与DIP设计 | 分层架构、DIP Protocol 矩阵、Null 回退模式 |
| 01-项目目标与架构说明 | 项目定位、系统架构 |
| 02-核心模块说明 | 各模块功能和接口 |
| 03-API设计说明 | RESTful + SSE + WebSocket 接口 |
| 04-数据库设计说明 | memories.db + sessions.db 双库方案 |
| 05-状态管理设计 | 会话、任务状态、持久化 |
| 06-Agent执行流程详解 | 完整执行流程 |
| 07-工具调用设计 | 工具系统设计 |
| 08-死循环防护策略 | MAX_TURNS 防护 |
| 09-可观测性设计 | 统一日志、trace_id、监控 |
| 10-RAG评估方法 | 检索效果评估 |
| 11-测试说明 | 测试用例 |
| 12-Docker启动说明 | 容器化部署 |
| 13-CI-CD说明 | GitHub Actions |
| 14-失败case分析 | 问题与解决方案 |
| 15-需求覆盖自检 | Agent 服务化改造需求逐项核对 |
| Loop Engineering 设计 | 可验证目标 + 独立评估者 + 自动收敛设计文档 |
| 已完成归档 | 已修复问题 / 升级决议 / 优化记录 |
| 文档 | 说明 |
|---|---|
| Docker部署测试报告 | 公司要求覆盖 80% |
| CI/CD测试报告 | 公司要求覆盖 70% |
需要 Python ≥ 3.10
# 安装依赖
pip install -r requirements.txt
# 配置环境变量
cp .env.example .env
# 编辑 .env 填入 API 密钥
# 运行 API 服务
python api.py
# 或运行 CLI 交互
python main.py# 构建镜像
docker build -t xiaoyu-agent .
# 运行容器
docker run -d -p 8000:8000 -e API_KEY=*** xiaoyu-agent
# 或使用 docker-compose
docker-compose up -d健康检查：curl http://localhost:8000/health
# 运行所有测试（pytest-asyncio auto 模式）
python -m pytest tests/ -v
# 指定模块
python -m pytest tests/test_session_store.py tests/test_api_streaming.py -v
# 生成覆盖率报告
python -m pytest tests/ --cov=agent --cov-report=html测试基础设施：pyproject.toml（asyncio_mode=auto）+ conftest.py（tmp_session_db / tmp_memory_dir 共享 fixture）。
小玉的agent/
├── agent.py # Agent 核心(主循环 + 会话持久化)
├── api.py # FastAPI 服务(REST + SSE + WebSocket + health + trace)
├── main.py # CLI 交互入口
├── config.py # AgentConfig 集中配置
├── core/ # 核心层
│ ├── session_store.py # SessionStore Protocol + SQLite/Null 实现
│ ├── trace.py # contextvars trace_id
│ ├── unified_logger.py # 统一 JSON Lines 日志
│ ├── llm_client.py # LLM 调用(OpenAI 兼容)
│ ├── context/ # 三阶段上下文压缩管线
│ ├── loop/ # Loop Engineering(分类器+评估器+质量标准+风格规范)
│ ├── hooks/ # 钩子系统
│ ├── *_adapter.py # DIP 防腐层(Sink/HookBus/LLMCompleter)
│ ├── tool_registry.py # 工具注册表
│ └── task_manager.py # 任务取消管理
├── tools/ # 功能层(工具 + 权限 + 钩子协议)
├── memory/ # 记忆系统(5 子模块 + RAG 评估)
├── ui/ # 终端 UI(Rich 渲染 + 动画)
├── prompts/ # 系统提示词
├── tests/ # 测试用例(详见 docs/11-测试说明.md)
├── docs/ # 项目文档
├── data/ # 运行时库 sessions.db / cache_stats.db(不入库)
├── Dockerfile # Docker 配置(HEALTHCHECK → /health)
├── docker-compose.yml # Docker 编排
└── .github/workflows/ # CI/CD 配置
- 2026-06-22: 文档时效性修订 — 两篇测试报告(CICD/Docker)按真实 ci.yml/Dockerfile 重写(修测试数 59→353、健康检查
/→/health、补 ruff/e2e/codecov、API 版本 1.0.0→1.2);docs/12 Docker 说明修健康检查/compose version/环境变量/删占位实现清单;docs/07 工具清单补全(9 个工具);docs/08 修 MAX_TURNS 5→20 + 补 guardrail_hooks 三类循环检测;docs/14 失败case 由编造通用案例改为指向 DONE.md 真实归档的索引;统一文档标题编号;清理根目录练手代码(calculator.py 等);.gitignore加 .DS_Store - 2026-06-21: 发布前体检与修正 — 涂掉 plan 文档里的真实 API key(改占位符);Python 版本基线对齐(代码支持 ≥3.10,ruff target 从 py313 修正为 py310);同步 README/docs 测试数至 353;修正 docs/05 持久化自相矛盾;补全 docs/02 工具清单;
.env.example补关键配置项 - 2026-06-19: Loop Engineering 收尾整理 — 接线死配置
LOOP_EVAL_MODEL(评估者/分类器切视觉模型做 UI 类 loop 视觉审查)+LOOP_CLASSIFY_TIMEOUT(分类器超时降级 chitchat),修掉「配了不生效」;e2e 验证脚本入库(文案/闲聊/UI 三条路径真实跑通,含参照图视觉对比);审查确认零硬编码/评估者无工具结构性分离 - 2026-06-19: Loop Engineering 落地 — 分类器(闲聊/loop 判定,产出可验证质量标准)+ 独立评估者(带视觉无工具,对照质量标准+参照图判收敛,feedback 塞回精修)+ image2 生图工具 + 静态风格规范库(.claude/rules/);闲聊路径零侵入,LOOP_ENABLED 可一键回退(9 tasks, TDD)
- 2026-06-19: 记忆系统两阶段优化 — 捕获（"记住X"解析修复 + 每 N 轮异步触发提取）+ 合并（FTS5 兜底去重 / VectorStore 降级告警 / LLM 按长度阈值整理成一句）（8 tasks, TDD）
- 2026-06-19: 文档重组 — 拆分 ISSUES.md（仅留未决问题）+ 新增
docs/DONE.md（已完成归档）+ 新增docs/15-需求覆盖自检.md（服务化改造需求逐项核对） - 2026-06-18: 阶段1 服务化能力补齐 — 会话持久化 DIP、trace_id 串联、/health、SSE 流式、RAG 评估脚手架、统一日志修复（4 commits）
- 2026-06-18: 阶段0 上下文压缩管线重构 + DIP 解耦 + 配置收口（508127e）
- 2026-06-14: 添加 Docker 部署支持
- 2026-06-14: 添加 CI/CD 配置
- 2026-06-14: 优化 MAX_TURNS 配置（5→20）
作者：肖亮（小玉 Agent） 最后更新：2026-06-22