开源客户端仓库。项目包含浏览器前端、Electron 桌面壳、本地 Node API、Agent 编排、本地 SQLite 记忆和多模态工具入口。
这个仓库不包含任何私有运行环境资产，例如 .env、本地数据库、生成输出、API Key、访问令牌、账号数据或商业授权数据。
架构故事导览：
docs/architecture-story.md
docs/agent-roles-storyboard.md
详细技术架构：
docs/architecture.md
StepFun / OpenAI-compatible 接入说明：
docs/stepfun-api.md
| 模块 | 内容 |
|---|---|
| UI | 浏览器前端和 Electron 桌面壳 |
| Local API | 本地 Node.js API |
| Agent | 路由、文本、图片、语音、记忆和安全编排 |
| Storage | 本地 SQLite 记忆与角色配置 |
| Tools | 图片、语音、声音克隆工具入口 |
| Model Config | 自部署模型配置，以及可选的远程模型接口地址 |
开源客户端只定义本地运行逻辑和模型调用接口。任何远程用户体系、支付、用量策略、密钥保管或管理能力，都属于部署方自己的服务边界，不是本开源仓库的一部分。
用户
-> Browser / Electron UI
-> 本地 Node API
-> src/orchestrator
-> routerAgent
-> textAgent
-> imageAgent
-> voiceAgent
-> memoryAgent
-> safetyAgent
-> 本地 SQLite
-> 模型通道
-> 自部署模型 API
-> 或部署方提供的远程模型接口
一句话分工：
客户端负责体验、角色、记忆、Agent 编排和本地数据。
模型通道负责把 Chat / Image / TTS / Voice Clone 请求交给用户配置的模型服务。
完整说明见 Agent 职责故事板。
展开 10 张 Agent 职责图
适合希望自己管理模型供应商、API Key 和调用成本的用户。
COMPANION_SELF_HOSTED=1
STEPFUN_BASE_URL=https://api.stepfun.com/step_plan/v1
STEPFUN_MODEL=step-3.7-flash
STEP_API_KEY=your-api-key
STEPFUN_IMAGE_MODEL=step-image-edit-2
STEPFUN_AUDIO_MODEL=stepaudio-2.5-tts客户端也可以连接部署方提供的远程模型接口。公开仓库只保留客户端侧配置和接口约定，不包含该远程服务的实现、管理界面、数据库或运维配置。
COMPANION_OFFICIAL_BASE_URL=https://your-remote-model-api.example.com
COMPANION_OFFICIAL_MODEL=step-3.7-flash未配置可用模型通道时，客户端仍可运行本地界面、角色、记忆和部分无模型能力。是否允许公共免费体验由本地配置控制：
COMPANION_PUBLIC_FREE_ACCESS=0
COMPANION_FREE_DAILY_CHAT_LIMIT=10Windows 发行版在：
release/2link：虚拟角色智能体 0.1.0.exe
普通用户双击 exe 即可使用，无需运行 npm start 或手动打开 localhost。
cd open-source-client
npm install
npm start打开：
http://localhost:5177
桌面预览：
npm run desktopnpm test当前测试覆盖：
- Agent 路由规划。
- 图片/语音能力开关。
- 危机场景语音抑制。
- Voice Agent 情绪识别。
- RAG 中文召回基础逻辑。
server.js 本地 API 入口
public/app.js 前端主逻辑
src/orchestrator/ Agent 编排层
src/orchestrator/memoryPolicy.js CRAG 召回评分与证据质量策略
src/agent.js 文本 Agent 核心逻辑
src/modelPolicy.js 模型请求参数与生成策略抽象层
src/db.js SQLite 数据与记忆层
src/config.js 模型配置与模式选择
src/tools/imageGeneration.js 图片工具
src/tools/speechSynthesis.js 语音工具
tests/ 最小测试
docs/architecture.md 技术架构文档
docs/architecture-story.md 架构故事导览
docs/agent-roles-storyboard.md Agent 职责故事板
docs/response-style-api.md 回复风格调节接口
docs/response-style-desktop-alignment.md 电脑端回复方式对齐说明
客户端配置文件：
open-source-client/.env
常用配置：
PORT=5177
COMPANION_HOST=127.0.0.1
COMPANION_SELF_HOSTED=0
COMPANION_PUBLIC_FREE_ACCESS=0
COMPANION_FREE_DAILY_CHAT_LIMIT=10
COMPANION_COMPRESSION_WINDOW=100部署环境建议使用项目级 .env 管理配置，避免依赖 PowerShell 全局 $env:。
- 保持全仓 Markdown、配置模板和示例资产使用 UTF-8 编码。
- 拆分
server.js到routes/、services/、gateways/、policies/。 - 完善模型网关 mock、自部署模型测试和端到端 smoke test。
- 优化首次启动引导和错误提示。
AGPL-3.0-only.