自托管 · Self-hosted v0.1.0

把 AI Agent
跑在自己的基础设施上

ZhiWu（知吾）是一个面向企业与个人的一站式 AI Agent 工作台：可配置的 LangGraph 智能体、 企业知识库 RAG、以 SKILL.md 为载体的技能体系、MCP 工具扩展，以及隔离在独立容器里的安全沙箱代码执行。 数据、模型密钥与执行环境全部留在你的机器上。

五分钟跑起来 看架构 API / CLI
Python 3.13 FastAPI LangGraph 1.x ARQ + Redis Milvus Vue 3
四个进程，一个平台
# 1 · API 进程（FastAPI，26 个路由挂 /api） $ uv run python server/src/server/main.py INFO Uvicorn running on 0.0.0.0:5050 # 2 · ARQ Worker（队列执行 + 事件流发布） $ uv run python server/src/server/worker_main.py START process_agent_run · process_task concurrency=ARQ_MAX_JOBS=10 # 3 · 沙箱 Provisioner（docker / kubernetes / memory） $ docker compose -f docker/sandbox_provisioner/docker-compose.yml up -d READY provisioner on :8002 → sandbox on :8080 # 4 · Web 工作台（Vue 3 + Vite） $ pnpm --dir web dev VITE ready at http://127.0.0.1:5173
12层 Agent 中间件栈
26个 REST/SSE 路由模块
6种 OCR 解析引擎
5个内置 Skill
3类沙箱 backend
15篇已核对设计文档
Core Capabilities

五条主线，构成一个完整的 Agent 平台

不是把模型 API 包一层壳，而是把"排队 → 执行 → 审批 → 观测 → 恢复"整条链路做成可运维的产品能力。

◆队列化 Agent 运行

LangGraph 1.x + deepagents 构建 ReAct 循环，12 层中间件覆盖文件系统、技能、记忆、摘要、Token 用量与人工审批。Run 走 Redis 队列抢占租约，SSE 断线可续传。

▤企业知识库 RAG

文档入库经统一 Markdown 中间表示，6 种 OCR 引擎可切换；分块 6 套 preset；Milvus 每 KB 一个 collection，支持向量 / BM25 / hybrid 加权融合 + rerank + Neo4j 图谱召回。

✦Skills 技能体系

以 SKILL.md 为载体的指令包，支持内置同步、上传与远程安装。按用户授权生成只读投影，模型读取 SKILL.md 才激活，依赖工具与 MCP 按需放开。

⌘MCP 工具扩展

作为 MCP Client 接入外部工具服务，内置 mcp-server-chart 图表能力；服务级与工具级双层开关，配置以数据库为准，进程内按 slug:config_hash 缓存工具。

▣安全沙箱执行

Agent 的文件与命令执行不落在宿主进程，而是每个 runtime scope 一个沙箱容器（HTTP :8080），由独立 Provisioner 服务供给，路径守卫 + 保活 + 反代三件套。

⌁API · SSE · CLI

统一 /api 前缀，JWT 与 zhiwukey_ API Key 双通道鉴权。官方 zhiwu 命令行客户端复用同一套接口，把平台能力交给终端与脚本。
Tech Stack

技术选型偏保守：
可运维、可替换、可自托管

全异步 Python 后端 + 消息队列解耦执行，存储各司其职：事务、向量、图、对象、队列各有各的位置，没有"一个大数据库装所有"。

  • 后端：Python ≥ 3.13、FastAPI、SQLAlchemy + asyncpg、ARQ（Redis）任务队列
  • Agent 框架：LangGraph 1.x、langchain 1.x、deepagents 中间件体系
  • 数据层：PostgreSQL（业务 + checkpoint）、Milvus、Neo4j、MinIO、Redis
  • 前端：Vue 3 + Vite + Pinia + ant-design-vue
  • 可观测：trace_id 贯穿日志、Langfuse 追踪、Run 计时与审计消息
  • 沙箱：独立 Provisioner 服务（FastAPI），可对接 Docker 或 Kubernetes
查看完整架构 →
使用者
Web 用户 / 管理员工作台、知识库、Agent 配置
CLI / 外部 Agentzhiwu 命令 · API Key
前端
单页应用 :5173Vue 3 + Viteproxy /api → :5050
后端进程
FastAPI API :505026 个路由统一挂 /api
ARQ Workerprocess_agent_run / process_task
zhiwu 核心库agents · knowledge · models · services
执行侧
Sandbox Provisioner :8002docker / kubernetes / memory
沙箱容器 :8080每 runtime scope 一个
MCP Serversstdio / sse / streamable_http
数据与外部服务
PostgreSQL业务表 + LangGraph checkpoint
RedisARQ 队列 + Run 事件 Stream
Milvus向量 + BM25 稀疏
Neo4j知识图谱
MinIO文档 / 附件 / 产物
模型供应商SiliconFlow · OpenAI 兼容 · Anthropic · Gemini

图为 ZhiWu 系统上下文简化视图，与 docs/diagrams/architecture.mmd 一致。详细版见架构页。

Run Lifecycle

一次对话如何变成可审计的执行

Request 是用户意图，Run 是业务执行，Attempt 是一次占有事实。三张表把"提交—抢占—收敛"拆开，所以幂等、重试和崩溃恢复都有明确的落点。

提交 · POST /api/agent/runs

写入 agent_run_requests（request_id 为幂等键）与 agent_runs(pending)，同线程已有活跃 Run 时按 queue_policy 排队 / 拒绝 / steer。

入队 · ARQ

API 只做 enqueue_job，立即返回 201 + run_id；重活完全交给 Worker，API 层无状态可水平扩。

抢占 · 租约 CAS

Worker 用 owner token CAS 抢占执行权并创建 Attempt，心跳续租；租约过期的 Attempt 记 lease_expired，Run 可被其他 Worker 接管。

执行 · 中间件栈

每 Run 独享 CompositeBackend 与图实例；模型推理 ↔ 工具调用循环，文件与命令走沙箱，知识检索走 Milvus/Neo4j，外部能力走 MCP。

流式 · Redis Stream → SSE

ChunkedEventWriter 攒批 XADD，前端 SSE 支持 Last-Event-ID / after_seq 断点续传。

收敛 · 终态以 DB 为准

正常结束 completed；敏感工具触发 interrupted，审批后以 run_type=resume 从 checkpoint 续跑；取消走 Redis 信号 + PG 双轨。

agent_run_requests.status
queued→ dispatched· rejected cancelled failed
agent_runs.status
pending→ running⇄ interrupted· cancel_requested→ completed failed cancelled
agent_run_attempts.outcome
open（心跳续租）→ completed retry_released lease_expired failed
i
单写者保证。部分唯一索引 uq_agent_runs_one_active_per_thread 让同一 (uid, agent_slug, thread) 只能有一个非终态 Run，多 Worker 实例并发消费天然安全。
Quick Start

本地跑起来

先把 PostgreSQL / Redis / MinIO / Milvus / Neo4j 五个依赖服务准备好，并填写 backend/.env（三项密钥各 ≥ 32 字符，启动时会硬校验）。

backend/
cd backend
uv sync --all-groups
uv run python server/src/server/main.py      # API :5050
uv run python server/src/server/worker_main.py   # ARQ Worker（另开终端）
!
注意：仓库内只有 docker/sandbox_provisioner/ 两套 compose 清单，平台整体编排（api / worker / web / storage-migrator 镜像）在部署侧仓库，不存在一条"一键 docker compose up 起全栈"的命令。schema 迁移代码在仓内（python -m zhiwu.storage_migration），需部署方自行写成一次性 Job。
Documentation

仓内文档：15 篇全部经过代码核对

每篇文档头部标注状态、适用版本与来源文件，正文关键结论后带 文件#行号 证据，末尾保留「已确认结论」与「待确认问题」两节。

00 · 概述

背景目标、核心概念术语表、功能列表、目录树

01 · 架构

系统上下文、组件职责、数据流、部署拓扑

02 · Agent 执行

Run 生命周期、中间件栈、记忆、状态机、时序

03 · RAG 管线

离线摄取、在线检索、图谱、评估指标

04 · Skills

SKILL.md 规范、投影、生命周期、内置清单

05 · MCP

Client/Server、Transport、工具清单与时序

06 · API

REST/SSE 接口清单、鉴权与示例

07 · 数据模型

PG 表、ER 关系、Redis/MinIO/Neo4j/Milvus

08 · 配置

环境变量按域清单、system_options、优先级

09 · 部署

本地、Compose、健康检查、扩缩容

10 · 可观测

trace_id 日志、Langfuse、审计、Run 计时

11 · 安全

认证授权、RBAC、审批、沙箱边界、密钥

12 · 开发指南

环境搭建、测试、扩展 Agent/Skill/RAG/MCP

13 · FAQ

常见故障与排查路径

14 · CLI

命令 → 能力标志 → 端点映射

ADR 0001

总体架构决策记录
This Site

本站：纯静态，Pages 与 Workers 都能托管

站点是 site/ 目录下的原生 HTML/CSS/JS，没有构建步骤、没有外部 CDN 依赖，因此 Cloudflare Pages（静态托管）和 Cloudflare Workers（Static Assets 绑定）都可以直接承载同一份产物。

  • Pages：产出目录设为 site，无需 build command；_headers 已配好缓存与安全头
  • Workers：site/wrangler.jsonc 已声明 assets 绑定，Worker 负责 SPA 回退与 /api/health
  • 内置 7 张 Mermaid 图源文件对应的信息图已改写为纯 CSS，避免运行时依赖
部署到 Cloudflare
cd site

# 方式一 · Cloudflare Pages（纯静态，推荐）
npx wrangler pages deploy . --project-name=zhiwu-site

# 方式二 · Cloudflare Workers + Static Assets
npm install
npx wrangler deploy

# 本地预览（两种方式都不需要构建）
python3 -m http.server 8788

详细步骤、自定义域名与两个项目的差异见「部署与配置」页。