workai

WorkAgent
AI 驱动的智能工作台平台 — 将大语言模型的推理能力与工具执行深度结合，实现对话式任务自动化

快速开始 • Core 引擎 • Server • Client • Skills • 架构文档

多数 AI 工具把对话当作一次性交互——提问、回答、结束。但真实的工作场景是迭代式的：你需要多步骤推理、工具调用、结果验证，然后基于新信息继续推进。

WorkAgent 的设计哲学：给 Agent 一个本地化的工作台，让任务自主完成。

• 本地优先：所有数据（对话、记忆、文件）存储在本地文件系统，数据主权完全可控
• TypeScript 全栈：前后端类型共享，Core 层框架无关，可被任意宿主集成
• 桌面 + Web 双形态：Electron 桌面端零依赖部署，Web 端支持团队协作

• ReAct 执行引擎 — 基于 Reasoning + Acting 循环的 Agent 核心，流式事件推送（thinking / streaming / tool_call / done），支持最大迭代限制、中断取消（AbortSignal）、Live Steering 实时转向
• 多模型支持 — Provider 抽象层统一 OpenAI / Anthropic Claude / Ollama 本地部署，运行时切换，自动重试 + 指数退避 + Fallback Provider 降级
• MCP 协议集成 — Model Context Protocol 客户端支持 stdio / http / sse 三种传输，远程工具即插即用，工具命名空间避免冲突，渐进式发现减少上下文占用
• Skill 技能系统 — Markdown 定义领域知识，YAML Front Matter 元数据 + 正文注入 System Prompt，三级路由（显式调用 / 关键词匹配 / LLM 智能路由），Skill 依赖声明与校验
• 连接器 (Connector) — MCP 服务器 + Skills 的分组管理层，manifest.json 为唯一事实源，支持 HTTP API / 数据库 / 文件系统 / 消息队列多种适配器，放入目录即可使用
• 多 Agent 协作 — AgentProfile 多角色配置，智能路由策略（简单查询自己处理，复杂任务委派专家），delegate_task 任务分发，Sidechain 隔离避免父级上下文膨胀，每个 Agent 独立的工具/Skill/MCP 资源隔离
• L0-L3 分层记忆 — L0 原始对话 → L1 原子事实提取 → L2 场景聚合 → L3 用户画像，智能召回引擎（关键词匹配 + 重要性加权 + 时效性衰减），上下文符号化压缩（OffloadStore）
• 脚本沙箱 — 进程级隔离环境，文件系统限制（路径穿越防护），沙箱专用命令黑名单，环境变量白名单过滤，run_script 工具支持 Python / Node.js / Shell
• 自动化任务 (Automation) — node-cron 定时调度，Agent 任务无人值守执行，独立沙箱隔离，全栈 CRUD + UI 管理
• 安全守卫 — 命令审查（正则/函数匹配 + 四级严重度），删除保护（rm → mv 回收站），凭证泄露检测（自动脱敏 API Key / Token / 私钥），Hooks 生命周期可扩展
• 渐进式工具发现 — MCP 工具仅以精简摘要注入上下文，Agent 通过 read_tool_doc 按需查阅完整 schema，显著减少 token 消耗
• 中间件 + Hooks 双层扩展 — 7 种 Hook 事件（before_tool / after_tool / before_ll_call / after_ll_call / on_iteration_start / on_error / on_complete）+ Middleware 结构化管道

graph TB
    subgraph "展示层"
        WebUI["Web UI<br/>Vue 3 SPA"]
        Electron["Electron<br/>Desktop App"]
    end

    subgraph "应用层"
        Server["Express Server<br/>REST API + WebSocket"]
        ElectronMain["Electron Main<br/>IPC Bridge"]
    end

    subgraph "Core 核心层"
        Engine["AgentEngine<br/>ReAct Loop"]
        LLM["LLM Provider<br/>OpenAI / Anthropic / Ollama"]
        Tool["ToolRegistry<br/>builtin + mcp + skill"]
        Skill["SkillManager<br/>+ SkillRouter"]
        MCP["MCP Client<br/>stdio / http / sse"]
        Security["SecurityGuard<br/>+ Sandbox"]
        Memory["Memory System<br/>L0-L3 Pipeline"]
    end

    WebUI -- "HTTP / SSE" --> Server
    Electron -- "IPC" --> ElectronMain
    Server --> Engine
    ElectronMain --> Engine
    Engine --> LLM
    Engine --> Tool
    Engine --> Skill
    Engine --> MCP
    Engine --> Security
    Engine --> Memory

• Core 层：框架无关的 Agent 执行引擎，不依赖 Express 或 Electron，可被任意宿主集成。详见 Core README
• Server 层：业务逻辑 + REST API + WebSocket，负责持久化、MCP 管理、连接器协调、自动化调度
• Client 层：Vue 3 SPA，通过 HTTP/SSE 消费 Agent 事件流，支持 i18n 国际化
• Electron 层：桌面形态，通过 IPC 直接调用服务端能力，终端通信走 IPC 而非 WebSocket

work_agent/
├── src/
│   ├── core/               # 核心引擎层（框架无关，可独立使用）
│   │   ├── agent/          #   AgentEngine — ReAct 执行循环
│   │   ├── llm/            #   LLM Provider 抽象（OpenAI/Anthropic/Ollama）
│   │   ├── context/        #   上下文管理 + 环境采集
│   │   ├── tool/           #   工具注册表 + DelegateTool
│   │   ├── skill/          #   Skill 管理 + 三级路由
│   │   ├── mcp/            #   MCP 客户端（stdio/http/sse + proxy）
│   │   ├── memory/         #   记忆系统（L1提取/L2场景/L3画像/召回/管道）
│   │   ├── security/       #   安全守卫（命令审查 + 凭证脱敏）
│   │   ├── sandbox/        #   沙箱类型定义 + 安全规则
│   │   ├── middleware/     #   中间件管道（Hook 的结构化增强层）
│   │   ├── hooks/          #   生命周期钩子（7 种事件）
│   │   └── utils/          #   Token 计数等工具
│   ├── server/             # 服务端（Express 路由 + 业务逻辑）
│   │   ├── routes/         #   REST API 路由（10 个模块）
│   │   ├── service/        #   业务服务（Agent/Chat/MCP/Connector/Automation...）
│   │   ├── connectors/     #   数据源适配器（HTTP/DB/FS/MQ/MCP）
│   │   ├── mcp/            #   MCP 扩展（ApiBridge + OpenAPI 导入）
│   │   ├── sandbox/        #   沙箱实现（LocalSandbox + Manager）
│   │   ├── tool/           #   内置工具 + 本地执行器
│   │   └── store/          #   JSON 文件持久化
│   └── client/             # 前端（Vue 3 SPA）
│       ├── views/          #   页面视图
│       ├── stores/         #   Pinia 状态管理
│       ├── service/        #   API 请求封装
│       ├── components/     #   通用 UI 组件
│       ├── adapter/        #   通信适配层
│       └── locales/        #   国际化 (zh-CN / en-US)
├── electron/               # Electron 桌面应用主进程
├── data/
│   ├── skills/             # 内置 Skill 文件（19 个领域知识包）
│   ├── connectors/         # 连接器包（每个含 manifest.json + skills/）
│   ├── sandboxes/          # 运行时沙箱目录
│   ├── offload/            # 上下文卸载存储
│   └── messages/           # 消息持久化
├── docs/                   # 架构文档
├── server.js               # 生产服务入口（Express + WebSocket）
├── bootstrap.js            # 生产环境启动脚本
└── vite.config.ts          # Vite 构建配置

• Node.js >= 22
• pnpm >= 9

pnpm install

# 启动 Vite 开发服务器（前端 + API 一体化）
pnpm dev

# 或启动 Electron 开发模式
pnpm electron:dev

开发服务器默认端口：9801

# 构建前端 + 编译服务端
pnpm build

# 启动生产服务
node bootstrap.js
# 或指定端口
node bootstrap.js --port 9802

# macOS
pnpm electron:build:mac

# Windows
pnpm electron:build:win

# Linux
pnpm electron:build:linux

Agent 通过 ReAct 循环完成任务：

用户消息 → Skill 路由 → 上下文构建 → LLM 推理(流式) → 工具调用 → 结果反馈 → 继续循环或结束

支持最大迭代限制（默认 15 轮）、中断取消（AbortSignal 双层控制）、Live Steering（运行中实时注入转向消息）、重试与降级（指数退避 + Fallback Provider）。

Skill 是 Markdown 格式的领域知识包，定义 Agent 在特定任务场景下的行为规范：

---
name: Docker 管理
description: 管理 Docker 容器和镜像
tags: [docker, container, 容器]
aliases: [容器管理, 镜像]
requires: [execute_command]
---

## 任务说明
你将帮助用户管理 Docker 环境...

Skill 内容注入到 System Prompt，SkillRouter 自动匹配用户意图（三级路由：显式调用 → 关键词匹配 → LLM 智能路由）。

内置 19 个 Skill 覆盖金融分析、文档生成、数据采集等场景。

连接器将外部数据能力以标准化方式注入到 Agent 工具链。以目录形式存在，manifest.json 为唯一事实源：

支持通过 MCP (Model Context Protocol) 连接外部工具服务：

• stdio：本地进程通信
• http / sse：远程 HTTP 服务
• 工具命名空间：mcp_[{connectorId}_]{serverName}_{toolName}，避免多服务器工具名冲突
• 渐进式发现：MCP 工具仅以摘要注入，Agent 按需查阅完整 schema

通过 AgentProfile 实现多角色配置，采用智能路由策略（Smart Routing）：

子 Agent 执行采用 Sidechain 隔离，仅回传最终结果 + 一行摘要，防止父级上下文膨胀。

服务端 API 统一挂载在 /api/work 路径下：

通过应用内 Settings 界面配置模型供应商（API Key、Base URL、模型选择等），支持多 Provider 配置和运行时切换。

• Core 模块导入：始终通过 ../core 统一入口导入，不直接引用内部路径
• TypeScript：全栈 TypeScript，服务端使用 tsconfig.server.json
• 代码风格：ESLint + Prettier，配置见 .eslintrc.json / .prettierrc.js
• 国际化：前端支持 zh-CN / en-US 双语

MIT