workai

v0.1.3

Published

20 days ago

WorkAI - AI-powered workbench platform

0High
0Medium
0Low

jiamao

核心特点

本地优先 — 对话、记忆、文件全部存储在本地，数据主权完全可控
三端覆盖 — Web / Electron 桌面 / workai CLI，同一套 Core 引擎
ReAct 执行引擎 — 思考→工具调用→观察循环，支持流式输出、中断取消、实时转向
多模态输入 — 支持图片（Vision 模型）、PDF、文档上传，拖拽/粘贴/选择多种方式
多模型切换 — OpenAI / Anthropic Claude / Ollama 本地部署，运行时热切换，自动重试降级
MCP 协议集成 — stdio / http / sse 三种传输，工具即插即用，渐进式发现节省 token
Skill 技能系统 — Markdown 定义领域知识，三级路由自动匹配用户意图
多 Agent 协作 — 智能路由：简单任务自己处理，复杂任务委派专家，Sidechain 隔离防止上下文膨胀
A2A 协议互操作 — 标准 Agent Card 发现 + JSON-RPC 分发，支持 SSE 流式，可作为 Server 暴露能力或 Client 调用远程 Agent
L0-L3 分层记忆 — 原始对话→原子事实→场景聚合→用户画像，智能召回
对话历史持久化 — JSONL append-only 持久化，服务重启后自动恢复 Agent 上下文
消息编辑与分支 — 支持编辑消息重新生成、重新生成 AI 回复、对话分支
Token 成本追踪 — 内置模型定价表，用量仪表盘可视化，预算控制（warn/abort）
对话搜索与导出 — 全局搜索对话内容，导出为 Markdown/JSON/Text
声明式 Agent 定义 — .agents/*.md YAML front matter 定义 Agent 配置
Anthropic Prompt 缓存 — cache_control 断点优化降低 API 成本
SSE 断流中断检测 — 连接中断自动提示 + "继续对话"恢复按钮
非破坏性上下文投影 — Context Collapse 折叠旧消息为摘要，原始历史完整保留
工作空间笔记 — agent.md 持久化笔记，对话时自动注入为 Agent 上下文
快捷命令系统 — /help /clear /export /model /agent 斜杠命令 + Tab 补全
语音输入/输出 — 浏览器 Web Speech API 语音转文字 + AI 回复语音播报
知识库 RAG — 文档上传、分块、embedding 检索，对话时自动注入相关知识
消息渠道集成 — 飞书/钉钉/企微 Webhook 接入，IM 渠道使用 Agent
模板市场 — 预制 Agent/Connector/Skill 模板，一键安装
备份与迁移 — data/ 目录一键打包备份，支持下载和恢复
通知与告警 — 任务完成/异常/预算超限自动通知，支持 Webhook/邮件/IM
邮件发送 — 支持 SMTP 和 Exchange (Microsoft 365 Graph API) 双模式，Agent 可发邮件通知/报告/摘要
HTTP API 调用 — http_request 工具支持 GET/POST/PUT/DELETE/PATCH 任意 REST API
日历/日程 — create_event/list_events 工具，iCal 文件生成 + 下载
IM 消息接入 Agent — 飞书/钉钉/企微消息自动转发给 Agent 引擎处理
Git 操作 — git_status/git_diff/git_commit/git_log 工具，Agent 可直接操作 Git 仓库
代码搜索 — search_code 工具，正则 + glob 模式搜索代码库
精确文件编辑 — edit_file 工具，搜索替换式编辑（非全量覆写）
浏览器自动化 — browser_navigate 工具，Playwright 无头浏览器截图 + 内容提取
安全守卫 — 命令审查、删除保护、凭证自动脱敏、沙箱路径隔离
远程任务中止 — 浏览器关闭后可远程中止 Agent 执行，防止资源浪费

Quick Start

安装

WorkAI 支持两种安装模式：基础安装（仅 Web 应用）和 完整安装（包括客户端构建）。

基础安装（推荐，仅 Web 应用）

适用于不需要构建客户端的场景，安装速度更快：

pnpm i              # 仅安装基础依赖，跳过 Electron
pnpm dev            # 启动 Vite 开发服务器（端口 9801）

完整安装（包括客户端构建）

适用于需要构建 Windows/macOS/Linux 客户端的场景：

# 设置国内镜像（可选，解决网络问题）
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

# 安装基础依赖
pnpm i

# 安装 Electron 及相关依赖
pnpm run install:electron

# 或使用一键安装脚本
pnpm run install:all

开发模式

pnpm dev            # Vite 开发服务器（端口 9801）
pnpm electron:dev   # Electron 开发模式（需先安装 Electron）

生产构建

pnpm build          # 构建前端 + 编译服务端
node server.js      # 启动生产服务
# 或
workai server       # 通过 CLI 启动

客户端构建

安装 Electron 后，可以构建各平台客户端：

pnpm electron:build:win      # 构建 Windows 客户端
pnpm electron:build:mac      # 构建 macOS 客户端
pnpm electron:build:linux    # 构建 Linux 客户端

提示：Electron 已配置为可选依赖，默认安装不会包含它。如需构建客户端，请先运行 pnpm run install:electron 安装 Electron。

全局安装（CLI）

npm install -g workai

workai              # 启动服务
workai chat         # 交互式对话
workai doctor       # 环境检查

CLI 命令

workai                              启动服务
workai chat [message]               交互式对话 / 发送消息
workai "message"                    快捷发送

workai status                       服务状态
workai stop                         停止服务
workai logs [-f] [-n <lines>]       查看日志

workai use <name>                   切换工作空间（不存在则创建）
workai ls                           列出工作空间
workai rm <name>                    删除工作空间

workai doctor                       环境诊断

所有执行命令第一行输出当前工作空间：⌂ 工作空间: default

详细命令说明、选项、工作空间规则见使用文档。

A2A 协议（Agent-to-Agent）

WorkAgent 实现了 A2A 协议，既可以作为 A2A Server 将本地 Specialist 能力暴露给外部 Agent 调用，也可以作为 A2A Client 发现并调用远程 A2A Agent。

作为 A2A Server（被其他 Agent 调用）

启动 WorkAgent 后，自动在根路径提供两个标准端点：

| 端点 | 说明 | |------|------| | GET /.well-known/agent.json | Agent Card 发现（描述能力、技能列表） | | POST /a2a | JSON-RPC 2.0 分发入口 |

支持的 JSON-RPC 方法：

| 方法 | 说明 | |------|------| | tasks/send | 同步执行任务，返回完整 Task 结果 | | tasks/sendSubscribe | 流式执行任务，通过 SSE 逐步推送进度和结果 | | tasks/get | 查询任务状态 | | tasks/cancel | 取消正在执行的任务 |

调用方配置与使用

1. 发现 Agent（获取 Agent Card）

GET http://<workagent-host>:<port>/.well-known/agent.json

返回示例：

{
  "name": "WorkAgent",
  "description": "AI-powered intelligent workspace with specialist agents...",
  "url": "http://<workagent-host>:<port>/a2a",
  "version": "1.0.0",
  "capabilities": { "streaming": true, "pushNotifications": false },
  "skills": [
    { "id": "specialist_1", "name": "Research Agent", "description": "..." }
  ],
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"]
}

Agent Card 中的 url 字段即为 JSON-RPC 请求地址。skills 列表展示了所有可用的 Specialist 能力。

2. 同步调用（tasks/send）

curl -X POST http://<workagent-host>:<port>/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "tasks/send",
    "params": {
      "id": "task-001",
      "message": {
        "kind": "message",
        "role": "user",
        "messageId": "msg-001",
        "parts": [{ "kind": "text", "text": "帮我分析一下最近的市场趋势" }]
      },
      "metadata": {
        "skillId": "specialist_1"
      }
    }
  }'

params.message.parts — 用户输入内容（支持多段文本）
params.metadata.skillId — 可选，指定调用哪个 Specialist（对应 Agent Card 中 skills[].id），不指定时使用默认 Specialist
params.id — 可选，任务 ID，不指定则自动生成
params.contextId — 可选，上下文 ID，用于关联多轮对话

3. 流式调用（tasks/sendSubscribe）

curl -X POST http://<workagent-host>:<port>/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-002",
    "method": "tasks/sendSubscribe",
    "params": {
      "message": {
        "kind": "message",
        "role": "user",
        "messageId": "msg-002",
        "parts": [{ "kind": "text", "text": "生成一份行业研究报告" }]
      }
    }
  }'

响应为 SSE 事件流（Content-Type: text/event-stream），逐条推送 status-update 事件：

data: {"kind":"status-update","taskId":"...","status":{"state":"working"},"final":false}

data: {"kind":"status-update","taskId":"...","status":{"state":"completed","message":{...}},"final":true}

4. 在代码中使用（任意 A2A 兼容客户端）

任何实现了 A2A 协议的客户端库均可接入，核心流程：

1. GET /.well-known/agent.json  → 获取 Agent Card
2. POST card.url                → 发送 JSON-RPC 请求
3. 解析 Task.status.message    → 获取 Agent 回复

作为 A2A Client（调用远程 Agent）

WorkAgent 可以发现并调用其他实现了 A2A 协议的远程 Agent，将其能力纳入本地多 Agent 协作体系。

管理 API（挂载在 /api/work/a2a）：

| 接口 | 说明 | |------|------| | GET /api/work/a2a/remotes | 列出已配置的远程 A2A Agent | | POST /api/work/a2a/remotes | 添加远程 Agent（自动发现 Agent Card） | | DELETE /api/work/a2a/remotes/:id | 移除远程 Agent | | POST /api/work/a2a/discover | 预览远程 Agent Card（不保存） |

添加远程 Agent 示例：

# 先预览远程 Agent 的能力
curl -X POST http://localhost:9801/api/work/a2a/discover \
  -H "Content-Type: application/json" \
  -d '{ "url": "http://remote-agent:8080/.well-known/agent.json" }'

# 确认添加
curl -X POST http://localhost:9801/api/work/a2a/remotes \
  -H "Content-Type: application/json" \
  -d '{ "url": "http://remote-agent:8080/.well-known/agent.json", "name": "远程分析Agent" }'

添加后，远程 Agent 会自动注册到本地 delegate_task 工具中。当主 Agent 判断任务适合委派时，可将任务分发给远程 Agent 执行，与本地 Specialist 无缝协作。

数据存储： 远程 Agent 配置持久化在 data/a2a-remotes.json。

Architecture

workai/
├── bin/workai.js           # CLI 入口
├── packages/agent-core/    # Core 引擎（独立 npm 包）
├── src/server/             # Express 服务端
│   ├── routes/a2a.routes.ts      # A2A 协议 & 管理路由
│   └── service/a2a-*.service.ts  # A2A Server/Client 服务
├── src/client/             # Vue 3 前端
├── data/                   # 运行时数据（自动创建）
├── docs/                   # 文档
└── server.js               # 生产服务入口

Documentation

| 文档 | 说明 | |------|------| | USAGE.md | 使用文档（CLI 命令、工作空间、环境变量、API、配置） | | FEATURE_ROADMAP.md | 功能补齐路线图（Core/App 分层归属、实施进度） | | ARCHITECTURE.md | 架构设计（分层模型、请求链路） | | CORE_ARCHITECTURE.md | Core 核心层接口规范 | | AGENT_CORE_MIGRATION.md | agent-core 下沉能力在 WorkAgent 中的迁移边界与步骤 | | ENGINE.md | Agent 执行引擎 | | TOOL.md | 工具体系 | | SKILL.md | Skill 技能系统 | | MCP.md | MCP 协议集成 | | MULTI_AGENT.md | 多 Agent 协作 | | A2A 协议 | Agent-to-Agent 互操作（Server / Client） | | SANDBOX.md | 脚本沙箱 | | SECURITY.md | 安全守卫 | | IMPROVEMENT_ROADMAP.md | 改进路线图（Claude Code / LangAlpha 对标分析） | | CLAUDE_CODE_COMPARISON.md | Claude Code 架构对比分析 | | LANGALPHA_COMPARISON.md | LangAlpha 全方位对比分析 |

License

MIT