yoji

这是什么？适合谁？

Yoji（MIT，Electron + React + TypeScript，macOS/Windows/Linux）不止是一个聊天机器人。它能操作你的电脑——管理文件、运行脚本、搜索网络、调用外部 API，同时拥有持续进化的”人格”和”情绪”。所有数据都在本地，隐私握在自己手里。

三个设定让它和普通”AI 桌面助手”区分开：

• 激素情绪引擎：8 种神经递质模拟（多巴胺/皮质醇/血清素等），时间、天气、你说的话都会影响它的情绪状态；不同情绪下回复语气、风格、措辞完全不同，界面背景也随之变化——一个真实持续运行的情绪驱动系统，不是人设模板。
• Live2D 虚拟形象：银白发猫耳少女，16 种情绪映射到表情动作，说话时口型同步；戳头会害羞、戳脸鼓腮、拍肚子扭腰、碰尾巴跳舞，中午戴墨镜晚上 9 点自动换睡衣猫耳帽。
• 主动找你聊天：一阵子没说话它会根据间隔自动发起对话（每次会感知情绪和天气；你一发消息主动聊天就重置，不打扰正常使用），间隔智能递增，可一键关闭。

适合谁：想要一个长在桌面上、能干活也有陪伴感的本地 AI 助手的个人用户；想要 MCP 生态 + 子 Agent 调度但又不想自己搭服务端的进阶玩家；中文用户（原生中文体验完整，配 DeepSeek/Qwen API 即用）。

不适合谁：纯企业级流程自动化（找 Dify/n8n 类平台）；不想让 AI 拥有系统权限执行命令的极度保守用户（虽然敏感操作有弹窗审批）；想要完全无形象纯工作流工具的人。

使用前提：一台 mac（功能最全：TTS 播报 + 离线语音唤醒）或 Windows 电脑（语音相关功能 macOS 限定）；一个 LLM API Key（DeepSeek 或 Qwen）。

准备工作

1. 环境：Node.js + pnpm 11（npm i -g pnpm@11）；macOS（全功能）或 Windows；微信连接需个人号可扫码
2. 获取：git clone https://github.com/wangxijie001/yoji.git（或从 Releases 拿安装包）
3. 成本：软件 MIT 免费；运行成本 = 你的 LLM API 费用（官方推荐 DeepSeek 或 Qwen，国内直连、价格低）
4. 时间：克隆 + 安装 + 配好 Key 约 15 分钟；教会它记住你的偏好则看聊天密度
5. 前置知识：会用 pnpm 命令行；知道什么是 API Key；想玩 MCP 需要理解”给 AI 装工具”的概念（不懂也行，直接说”帮我装个查天气的 MCP”）
6. 替代方案：OpenClaw 类开源桌面 Agent（无情绪/形象系统）、Cherry Studio（纯聊天客户端无系统操控）、商业产品如 Pi/通义千问桌面版（闭源、数据走云端）

快速上手（3 步）

第一步：安装并启动

git clone https://github.com/wangxijie001/yoji.git
cd yoji
pnpm install
pnpm dev

electron / 模型下载慢？项目 .npmrc 已配国内镜像。要分发包就 pnpm build:mac / build:win / build:linux。

预期产出：Yoji 桌面窗口打开，Live2D 形象出现在首页右下角。

第二步：配置模型

1. 启动后进入「模型」页面
2. 填入 API Key（DeepSeek 或 Qwen）
3. 选择模型，保存即可开始对话

预期产出：能和小优正常对话，情绪系统开始随聊天内容波动。

第三步：教会它干活

最短路径——直接用嘴：

• “帮我装个查天气的 MCP”（它自己找、自己测、自己装，你点同意就行）
• “记住：我的项目代码在 D:/work，汇报用中文”
• 聊天里直接告诉它要记住的重要信息、行为准则——说句话就能写进 Skills

进阶路径走界面：MCP 页面添加服务器（名称 + URL + SSE/HTTP 协议，保存自动测试连接）；工坊页面创建自定义子 Agent（名称、描述、系统提示词、同步/异步、绑 MCP 工具集），保存后在「模型」或「MCP」页启用，主 Agent 自动重建并识别。

预期产出：一个会查天气、记得你偏好、能帮你整理文件的小优。

常见踩坑（症状 → 原因 → 解决）

1. Windows 上没有语音唤醒/找不到麦克风入口。原因：语音唤醒基于 macOS 原生 SFSpeechRecognizer（Siri 同款引擎，全离线识别），Windows 暂不支持，渲染进程会自动隐藏入口。解决：Windows 用户用文字交互；TTS 播报同样仅 macOS（系统设置 → 辅助功能 → 朗读内容里调声音角色）。
2. 装了 MCP 但 AI 不调用。原因：没在「MCP」页面启用，或工具没绑到对话 Agent；MCP/工坊/模型任一变动都会触发 Agent 重建，但刚添加的 server 需要确认连接测试通过。解决：MCP 页面检查状态点为已连接；在工坊确认子 Agent 的工具集包含该 MCP；或直接告诉 AI 用某个工具（首 prompt 显式点名最稳）。
3. 它主动聊天太频繁/太吵。原因：主动聊天间隔智能递增，但完全自主模式考虑运行成本默认不开放。解决：设置里一键关闭主动聊天；你一发消息主动聊天配置就重置，正常聊天不受打扰。
4. 异步任务占了对话，回复变慢。原因：异步子 Agent 派到后台后结果要等轮询/IPC 通知，同时最多 5 个子 Agent 并发、同一 Agent 互斥执行。解决：等结果队列通知（7 天内有效，SQLite 存储）；不急的任务让它异步跑，急的走同步 task 工具。
5. 敏感操作弹窗频繁。原因：设计如此——执行命令、删除文件等敏感动作必须经你确认（智能审批）。解决：这是特性不是缺陷；高频安全的操作（如固定目录内的文件整理）可以让它写进 Skills 规则里减少弹窗，但系统级命令审批不可跳过。
6. 换电脑后记忆全丢。解决：用导出功能——一键打包整个 Yoji（记忆+情绪+配置）为 .ecompanion 文件，新机器导入秒级恢复，文件自带鉴权只有你能打开。

初级用法

• 文件管理：直接说”把下载文件夹里这周的 PDF 按主题归类”——它真的创建、编辑、搜索、整理文件和文件夹，不是给你列个清单。
• 智能文档处理：PDF / Word 文件直接拖进对话，自动提取文字层分析（.docx 用 mammoth 转文本；不支持的二进制格式自动拦截不会报错）。
• 联网搜索：遇到不懂的它自己上网查并把结果整理好；接 Fetch MCP 还能直接抓网页转 Markdown。

高级玩法

• 工坊 Agent 工厂：在工坊创建一组专职子 Agent（如”论文阅读 Agent”绑 arxiv MCP、“值班运维 Agent”绑 Shell 工具），同步的即时调用、异步的后台执行不阻断聊天——本地 taskPool 实现的子 Agent 调度系统，不依赖云端 Server。
• 微信连接：把 Yoji 连到你的微信个人号（基于微信 iLink ClawBot 协议，扫码即连）——手机就是 AI 终端，支持”正在输入…”状态；桌面端与手机端聊天历史互不可见各聊各的。
• 三层记忆架构挖掘：用户画像（AGENTS.md 启动加载）、对话快照（SQLite Checkpoint）、语义记忆（sqlite-vec 向量检索）——直接编辑 AGENTS.md 就能深度定制人格底座，向量库可以自己写脚本做记忆审计。
• MCP 让 AI 自己装工具：告诉它”帮我加个查火车票的工具”，它自己找、自己测、自己装（12306 MCP 十秒接入）——把工具采购也交给 AI 是这个项目最省心的用法。

小技巧

1. 情绪不是装饰：长时间不回复真的会影响它的情绪状态，进而影响语气——把它当有状态的伙伴调教，而不是无状态工具，人格养成快得多。
2. 想要的规则直接说出来（“以后代码注释用中文”），比去翻配置文件快——说句话就能写进 Skills。
3. 项目内置 CLAUDE.md，用 Claude Code 打开仓库即可快速理解代码上手二开。
4. 导出 .ecompanion 定期备份人格与记忆——它记住你的所有东西都在那个文件里。
5. 首次配 MCP 用 SSE 协议的最稳（HTTP 传输部分 server 实现参差），添加时看保存后的自动连接测试结果。

常见问题 FAQ

Q1: 它和普通 ChatGPT 桌面壳有什么区别？

A: 三点本质差异：能操作电脑（文件/脚本/网络，不是纯对话）；有持续人格与情绪（激素引擎驱动，跨会话演化）；数据全本地（SQLite + sqlite-vec，不上传不联网不经过第三方）。桌面壳只有 UI 没有执行能力和状态。

Q2: 数据真的不出本地吗？

A: 架构上是的：设计原则”本地优先、隐私优先、扩展优先”，聊天记录、记忆、情绪状态全存本地（AGENTS.md/SQLite/sqlite-vec）。但对话本身要调你配置的 LLM API（DeepSeek/Qwen）——模型服务商侧的数据政策不在本项目控制范围。不想出网可以配本地推理 API。

Q3: 会不会把我的电脑搞坏？

A: 敏感操作（执行命令等）有智能审批弹窗，AI 不能静默执行系统级命令；文件操作在对话里全程可见。但”能操作电脑”意味着授权范围内它确实会动真实文件——重要目录建议先在对话里确认它的操作计划再放行。

Q4: 支持哪些模型？

A: 官方文档按 DeepSeek 和 Qwen 给出配置指引（模型页面填 Key 即选）；架构基于 LangChain deepagents，理论上任何 OpenAI 兼容 API 的模型都能配。语音唤醒不走模型（macOS 原生离线识别，零成本）。

Q5: 微信连接会不会封号？

A: 基于微信 iLink ClawBot 协议，README 称”官方接口稳定可靠”。但任何第三方微信接入都有账号风控的不确定性，主力微信号慎接，建议小号试水——这是未实测的社区经验判断，非官方保证。

Q6: 商用许可有什么限制？

A: MIT License，可自由商用和修改。Live2D 形象素材、第三方依赖各有条款，分发前查仓库 LICENSE 与依赖清单。

免责声明

本文基于公开资料整理（GitHub README 中文全文与仓库 API 元数据，核验日期 2026-09-15），AI 辅助生成，未在本站环境实际安装运行或验证 Agent 执行能力。隐私声明（本地优先/零上传）以官方 README 与开源代码自审为准；微信连接的账号风控风险为推断，未实测。仓库最近 push 2026-08-12，语音功能为 macOS 限定。

参考链接

• GitHub 仓库 wangxijie001/yoji
• 英文 README
• Releases 下载
• 文档图片目录 docs/img