智几 MetisAI

English | 简体中文

智几 是产品中文名，MetisAI 是英文名，也可写作 Metis AI。它是一个本地优先、开源开放的智能体工作平台：同一套核心能力既可以作为个人桌面客户端使用，也可以作为机构内部智能体平台部署、改造和二次开发。

智几 MetisAI 的目标是让用户在一个工作台里完成智能体创建、模型接入、对话协作、文件处理、代码执行、网页检索、文档生成、任务调度、微信连接和能力扩展。它不是一个能力固定的单点工具，而是一个可以通过 Tool 和 Skill 持续进化的智能体引擎。

• 本地优先，开源开放：默认支持本地工作区、SQLite、Electron 桌面端和浏览器访问，方便个人本地使用，也方便机构在内网和自有模型环境中部署。
• C/S 与 B/S 双形态：既可以打包为 Windows/macOS 桌面客户端，也可以通过 FastAPI 后端和 React 前端组成 Web 平台。
• 智能体工作台：管理项目、智能体、会话、文件资产、模型配置、工具配置、定时任务和运行结果。
• 模型可自定义接入：通过大模型配置接入文本生成、图像识别、图像生成等能力，不绑定单一模型生态。
• 工具系统可扩展：内置文件读写、Shell、Python、pip、网页搜索/抓取、图片生成、图片分析等工具，也可以封装任意 API、脚本或内部系统为新工具。
• Skill 进化机制：通过 skills/ 中的 skill.md 组织提示词、流程、脚本、模板和参考资料，把复杂工作流沉淀为可复用能力。
• 记忆与上下文管理：支持用户画像、核心记忆、长期记忆和上下文压缩，帮助长任务持续推进。
• 安全策略：提供路径、命令、URL、敏感信息脱敏和工具安全策略，适合在本地与机构环境中逐步收紧权限。
• 典型办公与研究场景：覆盖 Excel/PDF/PPT 处理、市场研究、代码开发、金融投资分析、自动化监控和报告生成。
• 微信连接与任务调度：保留微信扫码绑定、消息连接和定时任务能力，方便把智能体延伸到日常入口。

本项目既支持下载源代码后自行 build 和安装，也支持直接安装桌面客户端。客户端安装包、源码下载入口和更多项目信息可访问 www.jixunet.com 获取。

推荐先用 Docker Compose 体验双容器模式：后端使用 FastAPI + SQLite，前端使用 Vite 构建后的 Web 服务。

docker compose up -d

启动后访问：

• 前端：http://localhost:3000
• 后端 API：http://localhost:27345/metisai

生产或共享环境请显式设置设备激活 token 密钥：

METIS_INVITE_TOKEN_SECRET=<your-secret> docker compose up -d

运行数据会写入 Docker volume metisai-data，对应容器内目录 /home/metisai/.local/share/MetisAI，用于持久化 SQLite 数据库、工作区、日志、上传文件、运行时 Skill 和工具产物。

如果希望使用单容器模式，可以基于根目录 Dockerfile 构建镜像。该模式会把前端构建产物复制到后端镜像中，由单个容器提供服务：

docker build -t metisai .
docker run -d --name metisai \
  -p 27345:27345 \
  -v metisai-data:/home/metisai/.local/share/MetisAI \
  -e METIS_INVITE_TOKEN_SECRET=<your-secret> \
  metisai

单容器模式启动后访问 http://localhost:27345/metisai。

环境要求：

• Python 3.10+
• Node.js 20+
• pnpm 10+

安装依赖：

pnpm run setup

该命令会安装前端/Electron 依赖，并创建 .venv 后安装 requirements.txt、requirements_2c.txt 中的 Python 依赖。

如果系统默认 python 指向 Python 2，或 Node、pnpm、Python 不在 PATH 中，可以显式指定可执行文件路径。macOS / Linux 示例：

METIS_NODE_BIN=/path/to/node \
METIS_PNPM_BIN=/path/to/pnpm \
METIS_PYTHON_BIN=/path/to/python3 \
METIS_PYTHON_VENV=/path/to/.venv \
pnpm run setup

Windows PowerShell 示例：

$env:METIS_NODE_BIN="C:\Program Files\nodejs\node.exe"
$env:METIS_PNPM_BIN="C:\Users\<you>\AppData\Roaming\npm\pnpm.cmd"
$env:METIS_PYTHON_BIN="C:\Users\<you>\AppData\Local\Programs\Python\Python312\python.exe"
$env:METIS_PYTHON_VENV="C:\projects\metisai-main\.venv"
pnpm run setup

常用情况下只需要指定 Python 3 路径即可：

METIS_PYTHON_BIN=/opt/homebrew/bin/python3 pnpm run setup

$env:METIS_PYTHON_BIN="C:\Users\<you>\AppData\Local\Programs\Python\Python312\python.exe"
pnpm run setup

相关环境变量：

• METIS_NODE_BIN：用于执行 setup 脚本的 Node.js 可执行文件，默认使用当前 node。
• METIS_PNPM_BIN：用于安装前端/Electron 依赖的 pnpm 可执行文件，默认使用 pnpm。
• METIS_PYTHON_BIN：用于创建 .venv 的 Python 3 可执行文件。脚本会拒绝 Python 2。
• METIS_PYTHON_VENV：虚拟环境目录，默认是项目根目录下的 .venv。

常用启动命令：

pnpm run dev
pnpm run backend:start
pnpm run frontend:dev

默认地址：

• 后端 API：http://localhost:27345/metisai
• 前端开发服务：http://localhost:3000

构建前端并以 Electron 方式启动：

pnpm run desktop:start

按平台打包：

pnpm run build:mac
pnpm run build:win

打包脚本会使用 scripts/package-desktop.cjs 和 electron/electron-builder.yml。后端 PyInstaller 默认使用项目目录下的 .venv 作为 Python 环境；如果需要指定其他 Python 解释器或虚拟环境路径，可以传入 --python：

pnpm run build:mac -- --python /path/to/python
pnpm run build:win -- --python C:\path\to\python.exe

也可以使用环境变量指定同一参数：

METIS_PYTHON_BIN=/path/to/python pnpm run build:mac

指定路径可以是 Python 可执行文件，也可以是虚拟环境目录。打包脚本会先确保该环境已安装 requirements.txt、requirements_2c.txt 和 PyInstaller 所需依赖，避免打包产物启动后缺少 fastapi、uvicorn 等模块。

智几 MetisAI 支持三种配置方式。推荐普通用户优先使用前端页面配置；文件和环境变量方式更适合开发、部署和自动化环境。

启动应用后，在前端进入工具配置页面，为内置工具填写 API Key、Base URL、模型名、超时时间、代理地址等外部参数。

• 配置会保存到数据库中，后续工具调用会自动读取。
• 只有工具参数 schema 中标记了 tool_config=True 的字段会出现在工具配置页面。
• 业务参数仍由智能体根据用户问题生成，例如文件路径、查询词、城市名；外部配置参数由系统注入，例如 API Key、模型、代理。
• 敏感字段会掩码展示，避免在页面中直接暴露完整密钥。
• 配置修改后通常无需重启，下一轮工具调用即可生效。

大模型能力建议在前端的大模型配置页面完成，例如文本生成、图像识别、图像生成等模型配置。

适合源码开发、服务器部署和需要把非敏感配置固化到文件中的场景。

cp config/config.example.toml config/config.toml
cp .env.example .env

然后按需修改：

• config/config.toml：配置端口、数据库类型、网页搜索/抓取、图片生成、视觉模型、工具安全策略、pip 源等。
• .env：配置 API Key、Token、数据库密码等敏感信息，例如 BAIDU_API_KEY、FIRECRAWL_API_KEY、METIS_IMAGE_API_KEY、METIS_VISION_API_KEY、DB_PWD、METIS_INVITE_TOKEN_SECRET。

config/config.toml 和 .env 已在 .gitignore 中忽略。仍然请确认不要把 .env、真实 Token、数据库文件、日志或本地工作区产物上传到 GitHub。

适合 Docker、CI/CD、PaaS、Kubernetes 和机构内部部署。config/config.toml 中形如 ${ENV_NAME:default} 的配置会优先读取同名环境变量；许多内置工具也会直接读取环境变量。

示例：

export BAIDU_API_KEY=<your-baidu-api-key>
export METIS_IMAGE_API_KEY=<your-image-api-key>
export METIS_VISION_API_KEY=<your-vision-api-key>
export METIS_INVITE_TOKEN_SECRET=<your-secret>
pnpm run backend:start

如果同时使用多种方式，建议遵循：前端工具配置用于工具默认参数，.env 或环境变量用于敏感密钥，config/config.toml 用于可审计的非敏感运行配置。

内置工具位于 metis/tool/built_in，统一返回结构化结果，并受安全策略、路径策略和敏感信息脱敏约束。

• read / write / edit：文件读取、写入和编辑。
• shell：系统命令执行。
• py_exec：Python 代码和脚本执行。
• pip_install：Python 包安装、检查和导出。
• web_tool：网页搜索、网页抓取和 URL 文件下载。
• gen_image：图片生成。
• analyze_image：图片理解、OCR 和视觉问答。
• Office/PDF converters：文档读取和 Markdown 转换能力。

更多说明见 内置工具文档 和 新建工具开发指南。

当前有效 Skill 位于 skills/：

• research：联网检索、事实核验和研究报告。
• ppt：从 Markdown、PDF、DOCX、URL 或主题生成 PPTX。
• excel：Excel 读取、生成、编辑、分析和公式重算。
• pdf：PDF 读取、生成、合并、拆分、提取和 OCR 辅助。
• evaluation：测试集生成、智能体评测、批改和报告。
• investment-analysis：通过 Tushare MCP 获取 A 股/港股/美股/期货/基金/债券/宏观等金融数据，支持行情查询、财务分析、多条件选股、技术分析和策略回测；需要用户配置自己的 Tushare API token。
• py-develop：Python 脚本开发、运行、调试、绘图和数据处理。
• evolution：MetisAI Skill 创建、升级、审查和优化。

详细说明见 Skills 说明。

本地运行时，应用数据默认存放在用户目录下的 MetisAI 应用数据目录，可通过 METISAI_DATA_DIR 覆盖。

• Windows：%LOCALAPPDATA%\MetisAI
• macOS / Linux：~/.local/share/MetisAI

SQLite 数据库、上传文件、工作区文件、会话记录、日志、工具产物、运行时自定义工具和运行时 Skill 会按配置写入该目录。开发调试时建议使用独立的 METISAI_DATA_DIR，避免污染正式数据。

中文 README 只链接中文文档：

• 内置工具文档
• 新建工具开发指南
• Skills 说明
• Metis Memory 实现机制
• Agent System Prompt 来源、加载方式和加载时点
• 贡献指南
• 安全政策
• 行为准则
• 第三方软件声明

前端类型检查：

pnpm run frontend:check

Python 测试可使用项目虚拟环境运行：

.venv/bin/python -m pytest

部分测试依赖外部服务、模型 API Key 或特定本地环境，运行前请先检查 .env、config/config.toml 和本地数据目录。

欢迎围绕通用智能体、工具系统、Skill、记忆、安全策略、桌面端和部署体验提交问题与改进。开始贡献前请先阅读 贡献指南 和 安全政策。