## 项目亮点
- **真正的多 AI 群聊**：一个房间可加入多个 AI 成员，成员不仅响应用户，也会结合上下文相互接话；调度器负责选择发言成员和顺序，避免机械式轮流回答。
- **可长期复用的聊天成员**：每个成员可独立配置名称、头像、角色设定、模型和行为参数，保存后可以反复加入不同房间，重启应用后仍会保留。
- **灵活的模型连接**：通过 OpenAI-compatible API 接入云端服务、兼容网关或本地模型，并允许不同成员使用不同连接和模型。
- **面向长期对话的上下文与记忆**：提供上下文预算、历史消息裁剪、成员记忆、房间记忆和相似度检索，避免长对话无限堆叠上下文。
- **本地优先与隐私保护**：房间、成员和消息默认保存在本机 SQLite；Windows 使用当前用户作用域 DPAPI 加密 API Key，日志、导出和错误信息执行敏感字段脱敏。
- **完整的数据管理能力**：支持备份、恢复、导入预览、事务化导入和导出，并覆盖头像、记忆、历史数据及卸载数据保留等生命周期场景。
- **可交付的 Windows 桌面应用**：Electron/React 前端与 FastAPI 后端独立开发、组合打包，后端由桌面进程监管，同时提供安装包和便携 ZIP。
- **可验证的工程体系**：前后端与共享协议分离，统一维护 OpenAPI、WebSocket 事件和 TypeScript 类型；仓库包含后端、协议、Electron 与 Playwright 测试，以及安全扫描、SBOM、第三方许可证清单和 GitHub CI。
## 前置条件
- Windows 10/11 与 PowerShell
- Python 3.12 或 3.13
- Node.js 20+ 与 npm
- 首次安装后约需 1 GB 空间（Electron、Playwright Chromium 和 Python 依赖）
## 安装
在仓库根目录执行：
```powershell
python -m venv backend\.venv
.\backend\.venv\Scripts\Activate.ps1
python -m pip install -e "backend[dev]"
cd packages\protocol
npm.cmd install
cd ..\..\frontend
npm.cmd install
npx.cmd playwright install chromium
cd ..
```
## 分别启动后端与前端
打开第一个 PowerShell，在仓库根目录启动后端：
```powershell
.\backend\.venv\Scripts\python.exe scripts\dev_backend.py
```
浏览器开发后端只监听本机专用端口 `18000`，默认地址为 `http://127.0.0.1:18000`。健康检查是 `http://127.0.0.1:18000/health`，交互式 API 文档是 `http://127.0.0.1:18000/docs`。如需覆盖端口，可在启动前设置 `MULTIAGENT_BACKEND_PORT`，并同步修改前端回退地址。
打开第二个 PowerShell，独立启动前端开发服务器：
```powershell
cd frontend
npm.cmd run dev
```
Vite 默认显示 `http://127.0.0.1:5173`，浏览器会通过内置的本地回退配置连接 `http://127.0.0.1:18000`。若页面显示“后端离线”，先确认第一个终端仍在运行且 `/health` 返回成功。Electron 打包会另外构建 `frontend/src/main/` 和 `frontend/src/preload/`；日常页面开发只需上述两个独立进程。前端代码和依赖始终留在 `frontend/`。
## 模型连接配置
全新工作区会自动打开首次使用引导，按“创建并测试模型连接 → 聊天成员 → 房间 → 第一条消息”展示真实配置进度。连接测试成功后才会进入下一步，首条消息发送成功才记录完成；“已完成”和“已跳过”分别保存在本机浏览器存储中。引导不会阻挡熟练用户，之后也可在“数据与设置”中重新打开。
新建连接时可选择三种可编辑预设：
- `自定义 OpenAI-compatible`：所有字段留给用户填写；
- `OpenAI API`：预填官方兼容地址和一个可修改的模型 ID，不包含 API Key；
- `本地 Ollama`：预填 `http://127.0.0.1:11434/v1` 和 `qwen2.5:7b`，API Key 可留空。
预设只是表单起点，不会锁定服务地址或模型名称，也不会静默发起外部请求。保存后仍应使用“测试连接”确认本机或远端服务确实可用。
启动产品后按以下 UI 顺序完成配置，无需手工调用 API：
1. 进入“模型连接”，点击“新建连接”，填写连接名称、OpenAI-compatible Base URL、API Key 和聊天模型名称并保存。Base URL 通常以 `/v1` 结尾。
2. 进入“聊天成员”，点击“新建成员”，选择刚保存的连接，确认模型 ID，填写成员名称和角色设定；需要时可上传头像，然后保存。
3. 进入“房间与聊天”，点击“新建房间”，填写房间名称并勾选至少一位已有成员。创建后，在输入框发送消息即可让该房间的成员参与对话。
房间默认最多 4 轮、每周期 2 位成员、单次生成 60 秒、8192 Token 和 1 USD 成本预算。这些值可在“房间设置 → 执行边界”编辑；“显式无限模式”必须主动勾选，暂停与停止始终可用。成本预算需要同时填写输入、输出的每 Token 单价；若供应商公布的是每百万 Token 价格，应先除以 `1,000,000`。两项单价留空时，成本会如实显示为未知且成本预算不生效，Token、轮次与超时边界仍然生效。
成员、房间和房间成员关系均保存在仓库本地 SQLite 中，停止并重新启动后端后仍会保留。连接表单字段含义如下：
- `provider_type`：提供商类型；当前兼容 OpenAI 的服务填写 `openai_compatible`；
- `default_model_id`：提供商实际支持的模型名；
- `embedding_model_id`：可选的向量模型名，仅在服务商支持 `/embeddings` 时填写；留空时明确回退到文本相似度；
- `base_url`：兼容 API 的根地址，必须包含 `http://` 或 `https://`；
- `api_key`：仅在创建或更新连接时提交。
产品表单中的“聊天模型名称”对应 API 的 `default_model_id`，“Embedding 模型名称”对应 `embedding_model_id`，两者不能混用。保存后可点击“测试连接”。测试失败时先检查 Base URL 是否重复包含 `/v1`、模型名是否存在、网络代理与额度是否正常。
Windows 桌面版使用当前 Windows 用户作用域 DPAPI 加密 API Key 后写入 SQLite，密文不能直接迁移给另一 Windows 用户。读取 API、日志、普通导出、备份、OpenAPI 响应定义、UI 响应和生成产物不会返回完整密钥。旧版明文记录仍可读取，编辑连接后会改写为 DPAPI 密文。非 Windows 开发环境仅在显式设置 `MULTIAGENT_ALLOW_PLAINTEXT_CREDENTIALS=1` 时允许保存密钥，该回退不适用于生产。不要把真实密钥写入仓库、截图、问题报告或命令行参数；发生泄露后应立即在提供商后台轮换。
## 常见启动检查
```powershell
# 后端是否在线
Invoke-RestMethod http://127.0.0.1:18000/health
# 后端测试（始终使用仓库虚拟环境）
.\backend\.venv\Scripts\python.exe -m pytest backend\tests -q
# 共享协议（在 packages/protocol 内）
npm.cmd run test
npm.cmd run typecheck
# 前端构建（在 frontend 内）
npm.cmd run build
```
端口被占用时，用 `Get-NetTCPConnection -LocalPort 18000` 或 `5173` 定位进程；导入错误通常表示虚拟环境未激活或后端依赖未安装；前端白屏时先查看浏览器/Electron 开发者工具，并确认 `npm.cmd install` 在 `frontend/` 内完成。
