你的 AI 记忆。在你的机器上，由你掌控。
exxperts 为你提供具有受控、批准门控记忆的持久 AI 房间：Agent 能够在跨会话中记住你以及你的工作，并且每一次记忆写入都需要你的批准。所有操作均在本地运行并保留：房间、记忆、知识库、artifacts 以及使用数据都是你磁盘上的文件。
## 为什么选择 exxperts
- **由你掌控的记忆。** 房间能够在跨会话中记住决策、偏好和上下文，但每一次记忆写入都必须经过你控制的批准门控。没有任何隐秘的画像构建。
- **本地优先，可验证。** 房间、记忆、知识库、artifacts 以及 token 使用记录均以纯文本文件的形式存放在 `~/.exxperts` 下。你可以读取、备份或删除其中的所有内容。没有任何遥测：唯一的网络流量来自于你的主动使用，即调用你的模型提供商、你启用的网络搜索以及你添加的任何 MCP 连接器。
- **是一个 agentic runtime，而非简单的聊天外壳。** 房间在限定于各个界面的权限模型下使用精心挑选的工具（知识库、artifacts、本地网络搜索、MCP 连接器）。房间永远不会获得不受限制的 shell 访问权限。
- **一个产品，两个界面。** Web 应用程序和 CLI/TUI 共享相同的房间、记忆和凭证存储；你可以自由地在它们之间切换。
如果你了解 [Open WebUI](https://github.com/open-webui/open-webui) 或 [AnythingLLM](https://github.com/Mintplex-Labs/anything-llm)：它们都是非常出色的本地聊天/RAG 前端。exxperts 则截然不同：它是一个专注于持久化、受控记忆和可审计 Agent 行为的本地 agentic runtime，而不是针对你的文档进行的简单聊天。
## 一个产品，两个界面
| 界面 | 启动方式 | 你将获得什么 |
| --- | --- | --- |
| **Web 应用程序** | `exxperts web` | 包含记忆、知识库、artifacts、网络搜索、批准机制以及钱包的房间。 |
| **CLI / TUI** | `exxperts cli` | 在你的终端中运行相同的房间，可从你希望作为工作区的文件夹启动。 |
Web 应用程序是完整的产品：AI 设置、记忆审查与批准、钱包、连接器和技能都位于其中。CLI/TUI 则专注于房间本身。直接运行 `exxperts` 会打开一个用于选择这两个界面的选择器（推荐使用 Web 应用程序）。产品/应用程序状态保存在本地的 `~/.exxperts/app`（在 Windows 上为 `%USERPROFILE%\.exxperts`）；内嵌 runtime 的提供商/授权/模型/会话状态保存在 `~/.exxperts/agent` 下。
## 产品功能
- 本地 Web 工作区，包含落地页、持久房间、批准机制和钱包。
- 仅限房间的 CLI/TUI，共享相同的房间 runtime 和治理机制。
- 通过 Web UI 创建的用户自定义技能。
- 批准门控的记忆、知识库写入以及 Markdown/HTML artifacts。
- Markdown/Obsidian 知识库工具和本地网络搜索。
- 通过单一代理工具在 Web 端和 CLI 端使用的 MCP 连接器。自带你的服务器；详情请参阅 [`docs/mcp.md`](docs/mcp.md)。
- 基于 `~/.exxperts/app/usage.jsonl` 的本地 token/费用钱包。
## 快速开始
前置条件：[Node.js](https://nodejs.org) 20.6+ 和 npm。**在 Windows 上，请在克隆之前应用 [Windows 快速入门](#windows-quickstart) 中的两个 Git 设置。**
```
git clone https://github.com/EXXETA/exxperts.git
cd exxperts
npm install
npm run install:global # builds, packs, and installs the exxperts commands (all platforms)
```
有两点需要注意：`npm install` 还会下载无头 Chromium（约 150 MB，仅需下载一次；可以使用 `EXXETA_SKIP_BROWSER_INSTALL=1 npm install` 跳过），并且 `install:global` 会在将 `@exxeta/exxperts-app` 安装到你的全局 npm prefix 之前构建整个应用程序，因此请耐心等待几分钟。
然后，在任何 shell 中运行：
```
exxperts web # the web app: rooms, memory, wallet (current folder does not matter)
cd /path/to/your/project
exxperts cli # the same rooms in your terminal, with this folder as the workspace
```
首次运行：在 Web 应用程序中打开 **AI 设置** 并登录你的提供商（Claude 和 ChatGPT 订阅支持一键登录；API 密钥和兼容 OpenAI 的网关也可以使用；详情请参阅[模型/提供商设置](#modelprovider-setup)）。遇到问题了吗？在 repo 根目录运行 `npm run doctor` 会检查每一层并打印修复方法。
新来此项目？[`docs/quickstart.md`](docs/quickstart.md) 会在大约五分钟内带你走完全部流程：安装、连接你的 AI、创建第一个房间、写入第一段记忆。要了解该产品是什么以及各部分如何相互配合，请阅读 [`docs/how-exxperts-works.md`](docs/how-exxperts-works.md)。
### 更新
在任何平台上都一样，在 repo 文件夹中执行：
```
git pull
npm install # in case dependencies changed
npm run install:global # rebuilds and reinstalls the global commands
```
全局的 `exxperts` 命令随后将运行新版本。如果在更新后或任何时候出现异常，请在 repo 文件夹中运行 `npm run doctor`。想直接从克隆的代码进行开发而不是使用全局安装？请使用 `git pull && npm install && npm run build` 进行更新。
## Windows 快速入门
Windows 全面支持 Web 应用程序和 CLI/TUI。要求如下：
1. **Git for Windows ≥ 2.40** (https://gitforwindows.org)。**必须使用 Git Bash**：Agent 的 shell 工具通过 `bash.exe` 运行命令，系统会自动在标准的 Git for Windows 安装路径 (`C:\Program Files\Git\bin\bash.exe`) 或 `PATH` 中查找它。
2. **Node.js 20.6+（推荐使用 LTS 版本）和 npm** (https://nodejs.org)。
3. 建议使用 **Windows Terminal** 来运行 CLI/TUI（尚未对旧版 conhost 进行测试）。
在克隆之前进行的一次性 Git 设置（长路径非常重要，因为 `node_modules` 树会超过 260 个字符的 `MAX_PATH` 限制）：
```
git config --global core.longpaths true
git config --global core.autocrlf false # the repo's .gitattributes manages line endings
```
然后从 PowerShell 或 Git Bash 进行安装，使用与其他地方相同的命令：
```
git clone https://github.com/EXXETA/exxperts.git
cd exxperts
npm install
npm run install:global
```
并从任何 shell 运行：
```
exxperts web # web app
exxperts cli # CLI/TUI, run from the folder you want as workspace
```
网络搜索在 Windows 上同样可用：安装 Docker Desktop，然后从任何 shell 中运行一次 `node scripts\searxng.mjs start`。详情请参阅 [`docs/web-search.md`](docs/web-search.md)。
想直接从克隆的代码进行开发而不进行全局安装？请使用不依赖 shell 的形式：`node bin\exxperts-web.cjs`、`node bin\exxperts-cli.cjs` 以及 `node scripts\exxeta-web.mjs`（带有服务器和 Vite UI 的开发版 Web 应用程序）。`scripts/` 中的 bash 启动脚本也可以在 Git Bash 中运行。
## 实现完整功能所需安装的内容
一切都在本地运行。完整功能分为四层；仅第一层是必须的：
1. **核心应用程序**：Node.js 20.6+ 和 npm，然后按照上面的快速入门步骤操作。
2. **无头 Chromium（约 150 MB，一次性下载）**：在 `npm install` 期间自动下载；它允许房间直观地查看其编写的 HTML 幻灯片并读取由 JavaScript 渲染的页面。如果无法运行下载，可以稍后使用 `npx playwright install chromium` 启用它（或者在安装期间使用 `EXXETA_SKIP_BROWSER_INSTALL=1 npm install` 跳过它）。
3. **网络搜索**：一个容器引擎加上一条一次性设置命令。请参阅[网络搜索（可选）](#web-search-optional)。
4. **模型身份验证**：提供商登录或 API 密钥。请参阅[模型/提供商设置](#modelprovider-setup)。
**请在 repo 根目录使用 `npm run doctor` 验证任何设置**：它会检查上述所有内容，以及 MCP 配置并确保出站 Web 获取的内容能够正确解码（企业的 TLS 检查代理可能会损坏响应），并且会针对任何缺失的内容打印修复方案。
`install:global` 封装了 `npm run build && npm pack && npm install -g
`；手动步骤以及通过 `npm exec` 进行的单次运行（无需全局安装）已记录在 [`docs/packaging-local.md`](docs/packaging-local.md) 中。如果 macOS 返回 `EACCES`，请使用用户级别的 npm prefix 而不是 `sudo`；相关内容也在该文档中有说明。如果较新的 npm 提示安装脚本已被阻止 (`allow-scripts`)，应用程序仍然可以正常工作。被阻止的步骤是 Chromium 下载（可随时通过 `npx playwright install chromium` 恢复）以及装饰性的 MCP 页面品牌展示。
## 网络搜索（可选）
网络搜索在发布时处于**禁用**状态，它完全通过 SearXNG 容器在本地运行：无需 API 密钥，无需第三方搜索 SaaS。注意：你的搜索**查询**仍然会发送到公共搜索引擎，因此请避免搜索机密的客户或内部内容。
要启用它：安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/) 或（在 macOS 上更轻量的）[OrbStack](https://orbstack.dev)，然后从 repo 目录中运行一次性设置命令并重启应用程序：
```
./scripts/searxng start # macOS / Linux / Git Bash
node scripts\searxng.mjs start # Windows (PowerShell or cmd)
```
设置详情、如何在重启后保持运行、状态/停止命令以及 Windows 相关说明：[`docs/web-search.md`](docs/web-search.md)。
## 模型/提供商设置
房间在做出响应之前，需要已登录的模型提供商。请选择最适合你的方式。
对于订阅提供商（Claude、ChatGPT Plus/Pro），启动 Web 应用程序，打开 **AI 设置**，然后点击该提供商配置卡片上的 **登录 →** 按钮。提供商登录页面将在浏览器中打开，凭证将保留在本地凭证存储中。
对于兼容 OpenAI 的网关（例如，公司的 LiteLLM 或 vLLM 代理），所有操作都在 Web 应用程序中完成：打开 **AI 设置** → **添加其他提供商** → **设置网关**，输入 base URL 和你的网关路由的模型 ID，选择学习/审查记忆模型，然后在该网关的配置行中粘贴你的 token。如果你喜欢，终端向导依然可用：
```
exxperts web
exxperts setup openai-compatible
```
在从 repo 克隆运行时，请使用相应的开发设置命令，而不是任何全局安装的命令：
```
./scripts/exxperts-web
./scripts/exxperts-cli setup openai-compatible
```
runtime 支持的任何其他提供商（Google Gemini、Groq、Mistral、DeepSeek、OpenRouter、xAI 等约 25 家）都可以从 Web 应用程序中添加：打开 **AI 设置** 并使用 **添加其他提供商**，然后如果提供商支持，可使用订阅登录，或者粘贴 API 密钥。登录后，请批准该提供商可以使用的模型：即房间中可用的模型，加上一个用于运行学习与审查记忆的模型（系统会提供一个默认建议）。批准操作会创建该提供商的 AI 配置；如果没有此步骤，虽然提供商已登录，但无法在房间中使用。
在从克隆运行时，存在于你的 shell 或 repo `.env` 文件中的提供商 API 密钥也同样有效：
```
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
```
订阅/OAuth 登录也可以从终端进行：运行 `exxperts cli`，然后输入 `/login`。它提供了与 Web 应用程序相同的提供商列表，包括 API 密钥输入。Web 应用程序和 CLI/TUI 共享同一个本地 runtime 凭证存储，因此通过任一路径登录都会对两者生效。为新增提供商批准模型需在 Web 应用程序的 **AI 设置** 中进行。
## 从 repo 开发
```
npm install
npm run build
npm run doctor # verify the setup
./scripts/exxperts-web # dev web app from this clone
./scripts/exxperts-cli # dev Exxperts CLI/TUI from this clone
```
打包不会改变正常的开发流程。在编辑代码时请继续使用 repo 脚本；只有在需要验证已安装产品的行为时，才执行重新打包/重新安装 (`npm run install:global`)。在 Windows 上，请使用 [Windows 快速入门](#windows-quickstart) 中提到的等效 `node` 命令。
## 当前限制
- 以基于 repo 构建的 npm 包形式分发；目前尚无原生安装程序。
- 目前还没有托管的多用户/SSO/RBAC 版本；exxperts 目前是一款单用户的本地产品。
## 更多文档
- [`docs/README.md`](docs/README.md)：带有受众和状态标签的官方文档索引。
- [`docs/quickstart.md`](标签：AI代理, MITM代理, 人工智能, 本地优先, 桌面应用, 特征检测, 用户模式Hook绕过, 网络安全, 自动化攻击, 记忆管理, 请求拦截, 隐私保护
