从一次工具调用，到一段有记忆的工作流。
基于 LangGraph 的个人 Agent 工作台，把文件、Shell、子 Agent、多模态与日常小工具接到同一条执行链上。
能力地图 · 架构设计 · 快速开始 · 知识库检索 · 开发与验证
项目起点：这是我第一个认真做的小项目。参考其他开源 Agent 框架，在 AI 辅助理解的过程中自己梳理代码逻辑，逐步做成可以复用的个人工作流。它既服务于日常任务，也保留了一点 QQ 机器人和 TTS 的娱乐性。
Tool Use → Subagent → Context Engineering → Conversation Store → CLI / API / Desktop
| 能力模块 | 已实现的闭环 | 对应实现 |
|---|---|---|
| 工具执行 · ReAct | 模型决策 → 文件读取 / 目录查询 / 文本搜索 / Shell → 工具结果 → 后续决策 | tool_agent_graph、tools |
| 子 Agent · Task Delegation | 主 Agent 拆出任务，向子 Agent 注入模型、工作目录、工具集与上下文预算，回收结构化结果 | Agenttool、sub_agent_graph |
| 上下文 · Context Engineering | 工具返回裁剪 + 历史摘要；模型上下文超限后执行三级递进压缩重试，异步调用支持取消 | context |
| 对话存储 · SQL Event Log | Session → Run → 完整消息事件 → 上下文投影；SQLite / PostgreSQL 双后端，完成轮次进入后续上下文 | conversation_store、runner |
| 检索 · Hybrid RAG | 文档切片 → 并发 Embedding → pgvector；向量召回与 BM25 通过 RRF 融合，提供 Hit@K / MRR 评估 | rag、evals |
| 工作台 · Desktop & API | Electron + React 连接本地 FastAPI，SSE 展示运行事件；管理会话、模型、工作目录与取消操作 | desktop、api |
| 多模态与场景 Graph | 图像理解、QQ 群历史检索与角色对话、TTS 工作流；通过 Skill 描述复用搜索与语音等能力 | Imageread、graphs、skills |
| 可观测性 · Tracing | 可选 Phoenix / OpenInference 追踪，使用 HTTP/protobuf 批量上报 | observability |
工具注册表包含文件、搜索、Python、Shell、图像、记忆和 Skill 等模块；每个 Graph 显式选择自己的工具与 Skill 集合。QQ 机器人的 NoneBot 宿主位于独立项目，TTS、搜索和本地模型也需要各自的服务配置。
flowchart TB
CLI["CLI · 多轮对话"] --> Runner["ToolAgentRunner · 统一运行协调器"]
GUI["Electron + React"] --> API["FastAPI · HTTP / SSE"]
API --> Runner
Runner --> Graph["受管 Graph · Tool Agent / TTS"]
Graph --> Model["模型客户端 · Qwen / DeepSeek"]
Model --> Tools["文件 / Grep / Shell / 图像 / 子 Agent"]
Tools --> Model
Context["上下文管理 · 裁剪 / 摘要 / 压缩重试"] -.-> Graph
Skills["SKILL.md · 搜索 / 语音 / 场景说明"] -.-> Graph
Runner --> Events["SQL · Sessions / Runs / Events / Context"]
Events --> Runner
RagCLI["RAG CLI: Ingest / Search / Evaluate"] --> RAG["Knowledge Base: pgvector + BM25 + RRF"]
classDef entry fill:#E1ECF8,stroke:#7A9BC1,color:#244D77
classDef engine fill:#F6E5E4,stroke:#C89999,color:#573B45
classDef storage fill:#E1EFE7,stroke:#87AD96,color:#315F4C
class CLI,GUI,API,RagCLI entry
class Runner,Graph,Model,Tools,Context,Skills engine
class Events,RAG storage
| 存储层 | 内容与职责 |
|---|---|
conversation_sessions |
长期会话标识与下一轮编号 |
conversation_runs |
每次请求的运行状态：running → completed / cancelled / failed / interrupted |
conversation_events |
按消息 ID 幂等追加的完整消息，作为永久对话事实源 |
conversation_context |
已完成轮次的模型上下文投影与压缩状态 |
outputs/gui_state.sqlite |
GUI 标题、模型、工作目录等会话元数据 |
普通 CLI、Tool Agent API 和 GUI 的受管 Graph 以 checkpointer=None 执行。取消、失败和中断的事件会保留，但不进入后续模型上下文或 GUI 正式历史。本地单实例启动时，遗留的 running Run 会被标记为 interrupted。
旧 LangGraph checkpoint 作为历史来源保留，不会自动迁移到新的对话库，也不提供任务执行到一半的自动续跑。
当前安装与桌面启动脚本面向 Windows，需要 Python 3.12、Node.js LTS 和 npm。本地虚拟环境固定在项目根目录 .venv。
.\setup.ps1
# 首次配置时执行；已有 .env 请直接编辑，保留原配置
Copy-Item .env.example .env也可以双击 setup.bat。安装脚本会创建 .venv 并安装 Python 与桌面端依赖。
手动安装的等价命令
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements-LLMv1.txt
npm install --prefix desktop模型 Profile 在 config/user_config.json 中定义，通过 base_url_env 和 api_key_env 读取 .env。例如，CLI 默认使用 deepseekv4-flash：
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_API_KEY=填入你的API密钥
# 本地对话持久化；普通聊天无需 PostgreSQL 或 Embedding 服务
LLM_GRAPH_DATABASE_URL=sqlite:///outputs/conversations/conversation.sqlite3也可以选择已配置的 Qwen Profile。本项目负责模型调用；本地 Qwen 的 OpenAI 兼容推理服务需要另行启动。模型名称应与实际服务提供的名称一致，密钥保存在个人 .env 中。
切换 PostgreSQL 或兼容旧配置
LLM_GRAPH_DATABASE_URL=postgresql://user:password@127.0.0.1:5434/database?sslmode=disableLLM_GRAPH_DATABASE_URL 留空时兼容旧 LLM_GRAPH_CHECKPOINT_* 后端选择；SQLite 对话仍使用独立的 outputs/conversations/conversation.sqlite3。旧 checkpoint 与新业务库的历史不会自动互通。
终端对话
.\.venv\Scripts\python.exe tool_agent_chat.py| 命令 | 用途 |
|---|---|
/help |
查看交互帮助 |
/thread |
显示当前会话 ID |
/new |
创建空白会话 |
/save |
导出到 outputs/cli_session_snapshot.json |
/exit 或 /quit |
退出 |
指定模型与工作目录，或通过同一个业务库中的会话 ID 继续对话：
.\.venv\Scripts\python.exe tool_agent_chat.py `
--profile deepseekv4-flash `
--vision-profile qwen3-vl `
--working-dir .
# 将示例 ID 替换为 /thread 显示的实际值
.\.venv\Scripts\python.exe tool_agent_chat.py --thread-id your-session-idWindows 桌面工作台
.\start_gui.ps1也可以双击 start_gui.bat，或执行 npm run dev --prefix desktop。Electron 会启动项目内的 Python 后端，使用随机本地端口与临时访问令牌连接 FastAPI。
桌面会话可选择已注册的 Tool Agent / TTS Graph；有消息后锁定 Graph。同一会话一次运行一个任务，不同会话可同时运行。永久删除会清除业务消息与 GUI 元数据。
单独启动 API / 指定其他 Python 环境
# 默认 http://127.0.0.1:8100；/health 为健康检查，/docs 查看接口
.\.venv\Scripts\python.exe -m src.api.run_chat_api
# GUI 临时使用另一套 Python 3.12 环境
$env:LLM_GRAPH_PYTHON = "C:\path\to\venv\Scripts\python.exe"
.\start_gui.ps1Text → Chunking → Concurrent Embedding → PostgreSQL / pgvector → Vector + BM25 → RRF → Evaluation
RAG 是独立的知识库链路，需要 PostgreSQL + pgvector 和兼容 OpenAI 的 Embedding 服务。当前示例使用 qwen3-embedding-0.6b、1024 维；模型服务输出与数据库向量列必须保持一致。
RAG_POSTGRES_URL=postgresql://user:password@127.0.0.1:5434/database?sslmode=disable
RAG_EMBEDDING_BASE_URL=http://127.0.0.1:8001/v1
RAG_EMBEDDING_API_KEY=填入你的Embedding服务密钥
RAG_EMBEDDING_MODEL=qwen3-embedding-0.6b
RAG_EMBEDDING_DIMENSIONS=1024服务和表结构准备好后，在项目根目录运行：
# 以 README 作为入库示例
.\.venv\Scripts\python.exe -m src.rag.ingest_cli README.md `
--tenant-id study --document-id readme
# 混合检索
.\.venv\Scripts\python.exe -m src.rag.hybrid_search_cli "如何启动桌面工作台" `
--tenant-id study --top-k 5
# 按用例比较纯向量与混合检索；先入库用例所依赖的文档
.\.venv\Scripts\python.exe -m src.rag.evaluate_cli --top-k 3评估用例保存在 evals/rag_cases.json，输出 Hit@1、Hit@K、MRR。BM25 当前逐次加载租户文档块并构建索引，适合小规模个人知识库。PostgreSQL 与 Embedding 服务需单独准备。
LLM-Graph/
├── tool_agent_chat.py # CLI 入口
├── config/ # 模型 Profile、提示词与生成参数
├── src/
│ ├── graphs/ # Tool Agent、子 Agent、QQ、TTS 等 Graph
│ ├── tools/ # 工具实现、参数 Schema、注册与提示词
│ ├── context/ # 工作目录、项目指令、Skill 与上下文压缩
│ ├── services/ # 统一 SQL 对话运行协调器
│ ├── persistence/ # 业务存储、消息编解码与旧 checkpoint 适配
│ ├── rag/ # 入库、检索与评估
│ ├── api/ # FastAPI、GUI 会话与 SSE 运行接口
│ └── observability/ # 可选 Phoenix tracing
├── desktop/ # Electron + React + TypeScript
├── skills/ # 搜索、语音、场景任务等 Skill
├── tests/ # Python 测试
├── evals/ # 检索评估用例
└── outputs/ # 本地数据库、导出与运行产物
新增工具：使用脚手架生成 InputSchema / execute / prompt.md，实现后在 registry.py 注册，再加入所需 Graph 的工具列表。
.\.venv\Scripts\python.exe -m src.tools.create_tool my_tool --execution async新增 Graph：参考 tool_agent_graph.build_graph() 保留通用状态与工具链；接入 CLI / GUI 的受管执行时，在 MANAGED_GRAPH_BUILDERS 中注册，由 Runner 管理 SQL 状态。
新增 Skill：在 skills/<name>/SKILL.md 编写名称、描述和任务说明，再按 Graph 的 Skill 列表启用。Skill 描述与脚本、服务依赖需要配套提供。
.\.venv\Scripts\python.exe -m pytest tests -q
npm test --prefix desktop
npm run build --prefix desktop最近一次本机验证 · 2026-10-15 · a41e310
| 检查范围 | 结果 |
|---|---|
| 真实 DeepSeek Tool Agent | 文件工具调用、第二轮记忆、SQL 历史保存通过 |
| 临时 SQLite + API 冒烟测试 | 生命周期、鉴权、会话管理、SSE、历史与归档限制通过；模型输出使用模拟数据 |
| 桌面端 | TypeScript 检查与构建通过，19 个测试通过 |
| Python 测试 | 排除迁移测试后，63 通过、4 个 PostgreSQL 测试跳过、1 失败 |
| 本机 RAG 服务 | PostgreSQL 连接超时，Embedding 服务不可连接；未完成端到端验证 |
当前仓库有两处已知测试问题：
tests/test_checkpoint_migration.py引用了尚未提交的scripts/migrate_checkpoint_conversations.py，导致完整测试收集失败。迁移旧历史前需要先补齐脚本；旧数据不会随应用启动自动搬迁。tests/test_shell_tool.py对报错行号的断言期待第 4 行，当前实际为第 7 行。
可先排除缺失脚本对应的测试运行其余用例，Shell 行号断言仍会失败：
.\.venv\Scripts\python.exe -m pytest tests -q --ignore=tests/test_checkpoint_migration.py以上为该版本的本机验证记录，不代表所有模型或外部服务的兼容结果。
- 补齐旧 checkpoint 到 SQL 对话库的迁移脚本与验证。
- 完善 Skill 接入与外部服务的复现说明。
- 继续探索桌面操作和游戏等场景工作流。
从“能回答”做到“能调用工具”，再做到“下一轮还记得自己做过什么”。这个项目会继续围绕实际用得上的小任务演进。
MIT License · Built for learning, everyday workflows, and a little fun.