WorkWit-AI-Agent

English |

WorkWit - Enterprise AI Office Assistant

An enterprise-oriented, privately deployable AI Agent platform. The backend is built on FastAPI + SQLite, and the frontend is a zero-dependency, vanilla-JS single-page application. The whole stack is deployed with one command via Docker Compose.

It is far more than a "contract-review gadget" - it is a unified office-agent foundation that integrates multi-model inference, extensible Skills, Tools, MCP connectors, sandboxed execution, multi-tenant access control, scheduled automation, and long-term memory. Office scenarios such as contract review and resume screening work out of the box, and new capabilities can be continuously extended through "skills + tools".

---

Why WorkWit

WorkWit is a self-hosted, enterprise-grade AI Agent platform built to make an organization's office work smarter - without giving up control of your data.

• Fully open source and self-hosted (MIT). No subscription, no per-seat fees, no vendor lock-in. Run it on your own infrastructure; your data never leaves your servers.
• Built for organizations, not just individuals. Real multi-tenant RBAC (Organization / Department / User) with a single source of truth for permission bits (FEATURE_REGISTRY).
• Office scenarios out of the box. Contract review (with Party A / Party B stance) and resume screening (job-profile matching score) ship as built-in modules - no assembly required.
• Trivial to deploy and audit. One docker compose up, a single backend container, SQLite storage, and a zero-dependency frontend. No build step; easy to read, fork, and harden.
• Unified capability catalog. Skills, tools, and MCP connectors are merged into one catalog and kept in sync automatically, so adding a capability is one registration, not three integrations.
• Safe by default. User-supplied code runs in a restricted sandbox (AST scan + CPU/memory/process/timeout limits + privilege drop); secrets stay in .env / data/ that are git-ignored.
• Extensible by design. 40+ built-in skills, a Skills Marketplace, a Tool Library, and the MCP connector framework let you grow capabilities continuously.

Core Features

• General-purpose Agent core: a ReAct (plan-act) loop supporting tool calls, streaming SSE output, and automatic decomposition/execution of multi-step tasks. The model proactively warns when it "claims a file was generated" but never actually invoked a tool (hallucination guard).
• Skills Marketplace: file-based skills (SKILL.md), with 40+ built-in skills (PPT generation, Word typesetting, WeChat official-account / Xiaohongshu writing, contract/legal, research reports, map compliance, 3D/video, Tencent Docs, and more). Supports versioning, rollback, visibility control, and install/uninstall.
• Tool Library: built-in tools (web search, web fetch, charts, email, text-to-image/video, PPT/Word generation, contract risk analysis, and more) + user-defined tools (sandboxed execution) + external MCP connectors.
• MCP Connector Framework: connect to standard MCP servers via data/mcp.json (supporting both streamable-http and stdio transports); external tools are auto-synced into the unified capability catalog.
• Sandboxed Execution: user-uploaded Python code runs in a restricted subprocess (AST static scanning + CPU/memory/process/timeout limits + privilege drop + module and file guards).
• Multi-tenancy and RBAC: a three-tier structure of Organization / Department / User, with fine-grained feature permission bits (FEATURE_REGISTRY); admins can centrally manage models, navigation, SMTP, MCP, and more.
• Multi-model Access: OpenAI-compatible interfaces, with four roles - chat / vision / embed / rerank. Can connect directly to vLLM / Ollama, or use LiteLLM as a unified gateway (a reference litellm_config.yaml is included).
• Automation: a background scheduler supports scheduled / recurring tasks.
• Long-term Memory and Conversation History: user-level long-term memory and cross-session history retrieval.
• Office scenarios out of the box: contract review (selectable stance), resume screening (job-profile matching score), and more.

---

Tech Stack

Layer	Choice
Backend	FastAPI (async), SQLite, Uvicorn
Frontend	Vanilla HTML/JS SPA (backend/static/index.html, zero build dependencies)
Model Access	OpenAI-compatible API (direct or via LiteLLM gateway)
Deployment	Docker Compose (single backend container, port 4001:8000)
Execution Isolation	subprocess sandbox (resource limits + AST scanning)

---

Directory Structure

workwit/
├── docker-compose.yml        # one-command deploy (backend service only)
├── litellm_config.yaml       # optional: reference config for the LiteLLM model gateway
├── .env.example              # env var template (copy to .env and fill in real values)
├── README.md
├── data/                     # runtime data (git-ignored, auto-generated on container start)
│   ├── app.db                #   SQLite main DB (auto-creates tables + seed data on first start)
│   ├── artifacts/            #   output dir for agent-generated artifacts
│   ├── uploads/              #   user uploads
│   ├── system_assets/        #   system assets
│   └── mcp.json              #   MCP connector config (may contain tokens - do not commit)
└── backend/
    ├── Dockerfile
    ├── requirements.txt
    ├── app.py                # FastAPI entrypoint, registers business routers
    ├── db.py                 # data layer + permission-bit registry (single source of truth)
    ├── auth.py               # login / permission gate
    ├── core.py               # business core (contract review / resume screening / artifact extraction)
    ├── agent.py              # ReAct agent loop (async generator, yields events one by one)
    ├── agent_endpoints.py    # agent API (planning / automation / memory / chat)
    ├── tools_build.py        # session tool assembly (DB def -> handler binding, MCP/sandbox branches)
    ├── tools_handlers.py     # tool handler implementations
    ├── llm_adapter.py        # multi-model client & capability wrapper
    ├── mcp_client.py         # MCP connector framework (streamable-http / stdio)
    ├── sandbox.py            # user-code sandbox execution (AST scanning + resource limits)
    ├── automation_runner.py  # scheduled automation runner
    ├── admin.py              # admin endpoints (models/orgs/depts/users/logs)
    ├── mgmt_endpoints.py     # admin endpoints (skills/tools/nav/system)
    ├── resume.py             # resume screening endpoints
    ├── search.py             # web search / web fetch
    ├── mailer.py             # email sending (SMTP)
    ├── builtin_skills/       # 40+ built-in skills (one SKILL.md each)
    ├── builtin_tools/        # built-in tool implementations
    └── static/               # frontend SPA (index.html)

---

Quick Start

Prerequisites

• A Linux server (Ubuntu 22.04 recommended) with Docker (including the docker compose plugin) installed.
• 4 OpenAI-compatible model endpoints (address + key) for chat / vision / embed / rerank. These can be local inference services (vLLM / Ollama) or fronted by a LiteLLM gateway.

Deployment Steps

# 1) Install Docker (if not already installed)
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# verify after re-logging into the terminal: sudo docker run hello-world

# 2) Upload this repo to the server, e.g. ~/workwit
git clone <your-repo-url> ~/workwit
cd ~/workwit

# 3) Fill in the model config
cp .env.example .env
nano .env     # set the 4 MODEL_*_BASE / MODEL_*_KEY pairs to real addresses and keys
# BASE = model service address, e.g. http://192.168.1.50:8000/v1

# 4) Start
docker compose up -d --build
docker compose logs -f backend   # watch for errors

After startup, open http://<server-ip>:4001 in a browser. Default admin account: admin / admin123 (change it in production - entry: "System Management -> User Management").

If you want to aggregate multiple model backends with LiteLLM, you can spin up a LiteLLM container yourself referencing litellm_config.yaml and point the MODEL_*_BASE values in .env to it; docker-compose.yml currently only orchestrates the single backend service.

Upgrade / Rebuild

After code changes:

docker compose up -d --build

---

Configuration (.env)

Variable	Description
MODEL_30B_BASE / MODEL_30B_KEY	OpenAI-compatible address and key for the main inference model (chat role)
MODEL_VLM_BASE / MODEL_VLM_KEY	Address and key for the multimodal model (vision role)
MODEL_EMBED_BASE / MODEL_EMBED_KEY	Address and key for the embedding model (embed role)
MODEL_RERANK_BASE / MODEL_RERANK_KEY	Address and key for the rerank model (rerank role)

On first start the 4 models are written to app.db as seed data from .env; afterwards the database is the source of truth and can be adjusted under "System Management -> Model Configuration".

Other overridable env vars (for ops tuning): DB_PATH, SKILL_CPU_SEC, SKILL_MEM_MB, SKILL_NPROC, SKILL_TIMEOUT, SKILL_ARTIFACT_ROOT, MCP_CONFIG_PATH.

---

Feature Modules

• Contract Review: upload txt / docx / pdf, select your stance (Party A / Party B), and get structured risk points and revision suggestions (with truncated-JSON repair fallback when parsing fails).
• Resume Screening: upload a resume + a job profile, and get the candidate's key fields, a match score, and a recommendation.
• Agent: issue tasks in natural language; it auto-plans and invokes skills / tools to complete them. Supports sketch planning, user clarification, and sub-agent delegation.
• Skills Marketplace / Tool Library: view, enable, and manage skills and tools; supports creating user-private skills and tools (sandboxed execution).
• Automation: configure scheduled / recurring tasks, executed by the background scheduler.
• My Memory / Conversation History: user-level long-term memory and cross-session retrieval.
• System Management: models, organizations, departments, users, permissions, logs, SMTP, MCP, navigation, and basic info.

---

Security Notes

• Secret isolation: .env (contains model keys) and data/ (contains the runtime DB and MCP tokens) are git-ignored - do not commit them to the repo.
• Sandbox: user-defined code runs in a restricted subprocess, with AST static scanning, CPU / memory / process / timeout limits, privilege drop to nobody, and module and file-access guards.
• Permissions: feature-level RBAC; admins are allowed by default, regular users get least-privilege permission bits; adding a new nav/feature only requires registering one line in db.FEATURE_REGISTRY and it takes effect automatically.
• Production recommendations: change the default admin password; enable HTTPS (reverse proxy); keep sensitive config such as MCP tokens in data/mcp.json (not in the repo).

---

Contributing

Issues / PRs are welcome. Before submitting, please ensure:

1. The .gitignore rules are applied and .env / data/ are not accidentally committed;
2. If a new feature introduces a nav entry, register its permission bit in backend/db.py's FEATURE_REGISTRY;
3. New built-in skills go under backend/builtin_skills/<name>/SKILL.md, following the existing when_to_use semantic-field convention.

---

License

This project is licensed under the MIT License. For other licenses (e.g., Apache-2.0, or proprietary/closed-source), please specify separately.

---

Roadmap (optional directions)

• Visualization and monitoring for sub-agent orchestration;
• More built-in skills / tools (spreadsheets, databases, BI, and more);
• Multi-instance horizontal scaling (currently single-DB; DB persistence and hot-cache extension points are already reserved);
• Frontend build tooling (currently zero-de

中文版 |

企业 AI 办公智慧助手（WorkWit）

一个面向企业的、可私有化部署的 AI Agent（智能体）平台。后端基于 FastAPI + SQLite，前端是一个零依赖的原生 JS 单页应用，整体用 Docker Compose 一键部署。

它不只是一个「合同审核小工具」——而是一个把 多模型推理、可扩展技能（Skills）、工具（Tools）、MCP 连接器、沙箱执行、多租户权限、定时自动化、长期记忆 整合在一起的统一办公智能体底座。开箱内置合同审核、简历筛选等办公场景，也支持通过「技能 + 工具」不断扩展新能力。

---

为什么选 WorkWit

WorkWit 是一个私有化、企业级的 AI 智能体平台，目标是让组织的办公更高效，同时不交出数据的控制权。

• 完全开源 + 私有化部署（MIT）。 无订阅、无按席位收费、无厂商锁定。部署在你自己的服务器上，数据始终留在你自己的基础设施内。
• 为组织而生，而非仅面向个人。 真正的多租户 RBAC（组织 / 部门 / 用户），权限位集中登记于 FEATURE_REGISTRY 单一真相源。
• 办公能力开箱即用。 合同审核（支持甲方 / 乙方立场）与简历筛选（岗位画像匹配评分）作为内置模块随平台提供，无需自己拼装。
• 部署与审计极简。 一条 docker compose up、单个后端容器、SQLite 存储、零依赖前端 —— 无构建步骤，易于阅读、fork 与加固。
• 统一能力目录。 技能、工具与 MCP 连接器合并为一张目录并自动同步，新增一项能力只需一次登记，而非三次集成。
• 默认安全。 用户代码在受限沙箱中执行（静态扫描 + 资源限额 + 降权），密钥留在 .env / data/（已被 .gitignore 忽略）。
• 为扩展而生。 40+ 内置技能 + 技能广场 + 工具库 + MCP 连接器框架，让能力可持续生长。

✨ 核心特性

• 通用 Agent 内核：ReAct（规划—执行）循环，支持工具调用、流式 SSE 输出、多步任务自动拆解与执行；模型「声称已生成文件」但实际未调用工具时会主动提示（防幻觉）。
• 技能广场（Skills）：文件化的技能（SKILL.md），内置 40+ 技能（PPT 生成、Word 排版、公众号/小红书写作、合同/法务、研报、地图合规、3D/视频、文档等）；支持版本管理、回滚、可见性控制、安装/卸载。
• 工具库（Tools）：内置工具（联网搜索、网页抓取、图表、邮件、文生图/视频、PPT/Word 生成、合同风险分析等）+ 用户自定义工具（沙箱执行）+ 外部 MCP 连接器。
• MCP 连接器框架：通过 data/mcp.json 接入标准 MCP 服务（支持 streamable-http 与 stdio 两种传输），外部工具自动同步进统一能力目录。
• 沙箱执行：用户上传的 Python 代码在受限子进程中运行（AST 静态扫描 + CPU/内存/进程/超时限额 + 降权 + 模块与文件护栏）。
• 多租户 & RBAC：组织 / 部门 / 用户三级结构，细粒度功能权限位（FEATURE_REGISTRY），管理员可集中管控模型、导航、SMTP、MCP 等。
• 多模型接入：面向 OpenAI 兼容接口，区分 chat / vision / embed / rerank 四种角色；可直连 vLLM / Ollama，或用 LiteLLM 做统一网关（仓库附 litellm_config.yaml 参考配置）。
• 自动化（Automations）：后台调度器支持定时 / 周期性任务。
• 长期记忆 & 历史对话：用户级长期记忆、跨会话历史检索。
• 办公场景开箱即用：合同审核（可选立场）、简历筛选（岗位画像匹配评分）等。

---

🧱 技术栈

层	选型
后端	FastAPI（异步）、SQLite、Uvicorn
前端	原生 HTML/JS 单页（backend/static/index.html，零构建依赖）
模型接入	OpenAI 兼容 API（直连或经 LiteLLM 网关）
部署	Docker Compose（单后端容器，端口 4001:8000）
执行隔离	subprocess 沙箱（资源限额 + AST 扫描）

---

📂 目录结构

workwit/
├── docker-compose.yml        # 一键部署（仅 backend 一个服务）
├── litellm_config.yaml       # 可选：LiteLLM 模型网关参考配置
├── .env.example              # 环境变量模板（复制为 .env 后填入真实值）
├── README.md
├── data/                     # 运行时数据（已被 .gitignore 忽略，容器启动后自动生成）
│   ├── app.db                #   SQLite 主库（首次启动自动建表 + 种子数据）
│   ├── artifacts/            #   智能体生成的产物落盘目录
│   ├── uploads/              #   用户上传文件
│   ├── system_assets/        #   系统资源
│   └── mcp.json              #   MCP 连接器配置（可含令牌，勿提交）
└── backend/
    ├── Dockerfile
    ├── requirements.txt
    ├── app.py                # FastAPI 入口，注册各业务路由
    ├── db.py                 # 数据层 + 权限位注册表（单一真相源）
    ├── auth.py               # 登录 / 权限门禁
    ├── core.py               # 业务核心（合同审核 / 简历筛选 / 产物提取）
    ├── agent.py              # ReAct 智能体循环（异步生成器，逐事件 yield）
    ├── agent_endpoints.py    # 智能体 API（规划 / 自动化 / 记忆 / 对话）
    ├── tools_build.py        # 会话工具装配（DB 定义 → handler 绑定，MCP/沙箱分支）
    ├── tools_handlers.py     # 工具 handler 实现
    ├── llm_adapter.py        # 多模型客户端与能力封装
    ├── mcp_client.py         # MCP 连接器框架（streamable-http / stdio）
    ├── sandbox.py            # 用户代码沙箱执行（AST 扫描 + 资源限额）
    ├── automation_runner.py  # 定时自动化调度器
    ├── admin.py              # 管理后台端点（模型/组织/部门/用户/日志）
    ├── mgmt_endpoints.py     # 管理后台端点（技能/工具/导航/系统）
    ├── resume.py             # 简历筛选端点
    ├── search.py             # 联网搜索 / 网页抓取
    ├── mailer.py             # 邮件发送（SMTP）
    ├── builtin_skills/       # 40+ 内置技能（每个一个 SKILL.md）
    ├── builtin_tools/        # 内置工具实现
    └── static/               # 前端单页（index.html）

---

🚀 快速开始

前置条件

• 一台 Linux 服务器（推荐 Ubuntu 22.04）并已安装 Docker（含 docker compose 插件）。
• 4 个 OpenAI 兼容模型端点的 地址与密钥（chat / vision / embed / rerank）。可以是本地推理服务（vLLM / Ollama），也可以前置 LiteLLM 网关。

部署步骤

# 1) 安装 Docker（若未安装）
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# 重新登录终端后验证：sudo docker run hello-world

# 2) 把本仓库传到服务器，例如 ~/workwit
git clone <your-repo-url> ~/workwit
cd ~/workwit

# 3) 填写模型配置
cp .env.example .env
nano .env     # 把 4 组 MODEL_*_BASE / MODEL_*_KEY 改成真实地址和密钥
# BASE 填模型服务地址，例如 http://192.168.1.50:8000/v1

# 4) 启动
docker compose up -d --build
docker compose logs -f backend   # 观察有无报错

启动后浏览器访问 http://服务器IP:4001。默认管理员账号：admin / admin123（生产环境务必修改，入口在「系统管理 → 用户管理」）。

若想用 LiteLLM 统一聚合多个模型后端，可参考 litellm_config.yaml 自行起一个 LiteLLM 容器，并把 .env 里的 MODEL_*_BASE 指向它；docker-compose.yml 当前只编排 backend 一个服务。

升级 / 重建

代码改动后：

docker compose up -d --build

---

⚙️ 配置说明（.env）

变量	说明
MODEL_30B_BASE / MODEL_30B_KEY	主推理模型（chat 角色）的 OpenAI 兼容地址与密钥
MODEL_VLM_BASE / MODEL_VLM_KEY	多模态模型（vision 角色）地址与密钥
MODEL_EMBED_BASE / MODEL_EMBED_KEY	嵌入模型（embed 角色）地址与密钥
MODEL_RERANK_BASE / MODEL_RERANK_KEY	重排序模型（rerank 角色）地址与密钥

首次启动会按 .env 把 4 个模型写入 app.db 作为种子；之后以数据库为准，可在「系统管理 → 模型配置」里调整。

其他可覆盖的环境变量（运维调参）：DB_PATH、SKILL_CPU_SEC、SKILL_MEM_MB、SKILL_NPROC、SKILL_TIMEOUT、SKILL_ARTIFACT_ROOT、MCP_CONFIG_PATH。

---

🧩 功能模块

• 合同审核：上传 txt / docx / pdf，选择我方立场（甲方 / 乙方），输出结构化的风险点与修改建议（JSON 解析失败时具备截断修复兜底）。
• 简历筛选：上传简历 + 岗位画像，输出候选人关键字段、匹配评分与推荐结论。
• 智能体（Agent）：自然语言下达任务，自动规划并调用技能 / 工具完成；支持草图规划、用户澄清、子 Agent 委派。
• 技能广场 / 工具库：查看、启用、管理技能与工具；支持创建用户私有技能与工具（沙箱执行）。
• 自动化：配置定时 / 周期任务，由后台调度器执行。
• 我的记忆 / 历史对话：用户级长期记忆与跨会话检索。
• 系统管理：模型、组织、部门、用户、权限、日志、SMTP、MCP、导航、基础信息。

---

🔒 安全说明

• 密钥隔离：.env（含模型密钥）与 data/（含运行库、MCP 令牌）已被 .gitignore 忽略，请勿提交到仓库。
• 沙箱：用户自定义代码在受限子进程中执行，含 AST 静态扫描、CPU / 内存 / 进程 / 超时限额、降权到 nobody、模块与文件访问护栏。
• 权限：功能级 RBAC，管理员默认放行，普通用户按权限位最小授权；新增导航/功能只需在 db.FEATURE_REGISTRY 注册一行即自动生效。
• 生产建议：修改默认管理员密码；启用 HTTPS（反向代理）；MCP 令牌等敏感配置放在 data/mcp.json（不入库）。

---

🤝 贡献

欢迎 Issue / PR。提交前请确保：

1. 已执行 .gitignore 规则，未误提交 .env / data/；
2. 新功能若引入导航入口，请在 backend/db.py 的 FEATURE_REGISTRY 登记权限位；
3. 新增内置技能放到 backend/builtin_skills/<name>/SKILL.md，遵循现有 when_to_use 语义字段约定。

---

📜 许可证

本项目采用 MIT License。如需其他许可证（如 Apache-2.0、或私有闭源），请另行说明。

---

🗺️ 路线图（可选方向）

• 子 Agent 编排的可视化与监控；
• 更多内置技能 / 工具（表格、数据库、BI 等）；
• 多实例横向扩展（当前为单库，已预留 DB 持久化与热缓存扩展点）；
• 前端构建工具化（当前为零依赖原生 JS）。