Cyrene-Agent

Cyrene-Agent 是一个以《崩坏：星穹铁道》昔涟为核心角色的 Windows Live2D AI 桌面伴侣。

基于 Electron + TypeScript 开发的桌面端 Live2D 智能对话 Agent。
项目围绕昔涟（Cyrene）的角色设定，结合自研 CyreneHarness 引擎与 DMAE 记忆引擎，
将角色化聊天、个性化记忆、语音交互、工具调用与多平台接入整合在同一个桌面 Agent 中，
支持日常聊天（Chat）、辅助工作（Work）、代码协作（Code）、学习陪伴（Learn）四种对话模式。

✨ 速览

• 🌸 趣味桌面陪伴 — Live2D 角色常驻桌面，支持表情、动作、状态、心情、气泡互动、智能表情包与多套界面主题
• 💬 日常聊天（Chat） — 专注角色化交流，结合会话历史、用户风格与长期记忆自然回应，不暴露任何工具
• 🛠️ 辅助工作（Work） — 通用任务会话，支持联网搜索、右侧浏览器操作、文件处理、文档生成与生活服务等工具的串联调用
• 💻 代码协作（Code） — 绑定可信代码目录，提供 LSP 语义查询与受限的读写改命令执行，安全边界由权限审批统一把关
• 📚 学习陪伴（Learn） — 绑定 Obsidian Vault，陪伴用户理解材料、整理笔记、生成练习与维护进度
• 🧠 个性化记忆 — 用户wiki/summary/embedding三种记忆模式，结合 DMAE Worldbook 与条目生命周期管理，沉淀长期互动
• 🔊 语音交互 — 集成 TTS、ASR 与语音通话，让昔涟能够听见并回应用户
• 🧰 丰富工具生态 — 覆盖联网搜索、文件处理、文档生成、生活服务、音乐与 MCP 扩展
• 🔌 多模型厂商适配 — 针对不同厂商提供分级 Structured Output 与 Function Calling 兼容方案；当前型号、能力范围和核验状态见模型适配清单
• 🧩 插件系统 — 本地插件包扩展 AI 工具、聊天渠道、自有窗口与语音输入，配套 npm SDK 与开发指南
• 📱 多平台接入 — 支持桌面端、飞书、微信 iLink 与 QQ（NapCat / OneBot 11），共享角色能力与对话体验
• 🌙 主动聊天 — 根据时间、状态与用户偏好主动发起交流，并支持多渠道定向投递

⚙️ CyreneHarness 核心引擎

Work / Code / Learn 等需要工具调用的会话模式，全部跑在 CyreneHarness 之上。 源码：src/main/orchestrator/harness/cyrene-harness.ts

CyreneHarness 是 Cyrene Agent 的核心 Agent Loop，负责把模型决策、工具执行、副作用记账与状态恢复串成一个可中断、可恢复、可回放的连续循环。

会话轨迹由 CTA（Canonical Transcript Architecture） 承载：canonical journal 是唯一权威源， 模型上下文、UI 投影与渠道消息全部从 transcript 派生；压缩摘要以 checkpoint 形式持久化， 热日志归档到 segments/，支持跨进程崩溃恢复与编辑 / 重新生成回溯。 源码：src/main/orchestrator/conversation-*.ts（store / journal-service / compactor / projection 等）

关键设计：

• 连续的 while + Function Calling 循环 — 每轮调用 LLM，按其返回的 toolCalls 进入工具派发，无 toolCalls 时由模型主动结束当前 turn。
• assistantMessage 必写回 — 每轮模型返回的 assistant 消息必须无条件 push 进 messages，否则下一轮模型会看不到自己上一步的回复，loop 立即崩。
• Ask 互斥路径 — ask_user / confirm_uncertain_effect 是用户等待类内置工具，必须独占本轮：其余同轮工具全部以 not_executed 协议结果写回，并 discardProgressBuffer() 丢弃进度文本。
• 四态 outcome 与 uncertainEffects 拦截 — 工具结果分为 success / failure / unknown / not_executed。当 unknown 且 sideEffect === non_idempotent 时，副作用会被记入 state.uncertainEffects，并 halted = true 暂停本轮后续同类调用，防止自动重放危险副作用。
• 失败重试 — 工具失败时根据 classifyToolResultError + resolveSideEffect 决定是否重试；sleepWithJitter 退避可被 AbortSignal 中断。
• 保守并行调度 — 默认串行，仅"显式声明并发安全的纯读工具"可并行（默认上限 4）；结果始终按模型原始 tool-call 顺序提交；halt / error / cancel 时已执行结果不丢弃，出错槽位以合成失败结果闭合 transcript。
• 双时钟超时 — 执行计时与用户等待计时分离：ask_user 等待用户期间暂停执行计时，用户思考多久都不消耗任务超时预算。
• 双层压缩（Mid-loop + Journal Compaction） — harness 每轮开始时根据 token 预算判断是否需要压缩上下文，超阈值时复用 LLM 做历史摘要，保留 todo 与已确定结果，压缩后 checkpoint 失败立即熔断；构建上下文超预算时再触发 journal 级压缩——摘要以 compaction checkpoint 持久化进 transcript，热日志归档至 segments/，二次压缩保留前次摘要，编辑 / 重新生成不能跨压缩边界回溯。
• 前缀缓存体系 — 稳定前缀分层（stablePrefix / sessionPrefix / mode），Todo 等易变状态禁止进入前缀；工具清单在 run 期间冻结；动态事实一次性物化进 transcript 而非每轮拼接；cacheEpoch 缓存周期跨压缩 / 恢复推进；Kimi prompt_cache_key 等厂商缓存 hints 在请求层统一注入。
• 工具输出双级截断 — 大输出落盘存储（ToolOutputRef），模型消息只保留 preview；需要完整内容时由模型调用内置 read_tool_result 按需回读，大幅降低上下文占用。
• 上下文容量快照 — 每轮请求前与终态各发一次 context_usage 快照事件，驱动 UI 上下文环实时显示。
• 截断可见化 — 输出命中模型长度上限（finishReason = length）时在回复尾部追加提示，不静默截断。
• 流式优先与降级 — 仅在零增量且供应商明确不支持 stream + tools 时降级非流式，绝不重放半截流；token 用量记账区分缓存命中。
• 全程 signal-aware — 几乎每个 await 都用 raceWithSignal 包裹，signal.aborted 时返回 cancelled()（finalAnswer = ''，不发 final_answer 事件）。
• 每轮 checkpoint — 通过 onCheckpoint 把 messages + state + rounds 持久化，跨进程崩溃后可恢复；恢复时崩溃孤儿工具按运行状态归为 unknown（而非误判 not_executed），避免重放外部副作用。

4 种终止状态：

主流程示意：

（示意图：① 初始化 → ② 主循环 → ③ LLM → ④ 工具调度 → ⑤ 状态账本 → ⑥ 终态结算）

🚀 快速开始

前置条件

• Windows 10 / 11 64 位
• Node.js 24 LTS、pnpm 10.33.0（首次可运行 npm install --global pnpm@10.33.0 安装）
• Rust stable + Visual Studio 2022 Build Tools（源码构建截图功能必需；Build Tools 勾选「使用 C++ 的桌面开发」工作负载即可）

飞书、微信 iLink、nut-js 键鼠自动化及原生截图功能依赖 Windows 环境。

如果直接安装 Releases 中的打包版本，无需另外安装 Rust 和 Visual Studio Build Tools。

1. 克隆并安装依赖

git clone https://github.com/Playa-Cyrene/Cyrene-Agent.git
# 或 Gitee（国内镜像）：git clone https://gitee.com/playa0/cyrene-agent.git
cd Cyrene-Agent
pnpm install --frozen-lockfile

首次安装会下载 Electron、Pixi.js、Live2D 等相关依赖，具体耗时取决于网络环境。

2. 构建并启动

首次从源码运行时，需要先构建 Rust 原生截图助手：

pnpm run build:screenshot-helper
pnpm run build
pnpm start

[!IMPORTANT]

原生截图助手不会以 .exe 形式提交到 Git 仓库，因此首次克隆后必须执行一次 pnpm run build:screenshot-helper。

Windows 用户也可以直接双击项目根目录的 setup.bat 完成依赖安装、构建和全局命令链接，之后双击 start.bat 即可启动。运行前需安装 pnpm 10.33.0。

开发模式：

pnpm run build:screenshot-helper
pnpm run dev

构建 Windows 可分发版本（自动构建 Electron 应用和 Rust 截图助手）：

pnpm run package:win:dir

3. 安装 BGE-M3

Cyrene 无需本地大语言模型即可正常聊天，但建议安装 BGE-M3 Embedding 模型：

前往 Releases 下载 BGE-M3

[!IMPORTANT]

未安装 BGE-M3 不会影响基础聊天，依赖 Embedding 的增强功能会自动关闭或降级。

4. 命令行入口（可选）

项目附带 cyrene 命令行入口，执行 pnpm run build:cli && pnpm link --global 后即可在任意目录使用，提供 version、run 等子命令，详见 cyrene --help。

pnpm run build 已包含 build:cli，但 pnpm link --global 仍需单独运行。正式安装版的 cyrene desktop 入口将在 1.x 提供。

🔑 配置 API Key

应用启动后，点击系统托盘图标 → 打开设置，完成以下基础配置：

1. 🔑 模型设置：选择 LLM 厂商预设，填写 API Key、Base URL 与模型名称。
   这是 Cyrene 正常聊天和运行 Agent 的必要配置。

2. 🎙️ TTS 设置（可选）：选择 Mossland、MiniMax、MiMo、GPT-SoVITS 或自定义云端语音合成服务。

3. 🎧 ASR 设置（可选）：如需使用语音通话，可配置阿里云实时 ASR 的 AppKey 与 AccessKey，或填写 Mossland 共用 API Key、MiniMax ASR API Key。

4. 📱 外部渠道（可选）：根据需要连接飞书或微信 iLink，在手机端与 Cyrene 对话。

5. 🎵 音乐（可选）：配置网易云音乐 OpenAPI 凭据后可启用音乐工具；播放器已内置，无需安装网易云客户端。

相关配置会保存在应用的 <userData>/ 目录中，修改后通常无需重启应用。

✨ 功能

核心功能

🌸 桌面陪伴

• Live2D 桌面角色 — 基于 pixi-live2d-display 与 Cubism Core 渲染，支持桌面置顶、鼠标交互、自然待机与嘴型同步。
• 表情与动作联动 — 根据对话内容触发表情、动作、状态、心情与桌面气泡，让角色反馈不只停留在文字层面。
• 智能表情包 — 内置贴纸面板，并可通过语义匹配自动选择符合当前语境的表情包。
• 多窗口交互 — 桌宠、聊天、设置、任务、通话和贴纸管理等界面相互独立，又共享统一运行状态。
• 个性化外观 — 支持界面主题、聊天样式与字体选择。

🎨 主题外观

Cyrene 提供亮 / 暗两套界面主题，覆盖聊天、设置等主要界面：

🌙 暗色主题

☀️ 亮色主题

💬 日常聊天（Chat）

• 独立角色聊天流程 — Chat 模式专注于角色化交流，不暴露、不调用也不执行任何工具。
• 人格化回复 — 结合昔涟角色设定、近期会话、社交上下文、用户风格与个性化记忆生成回复。
• 多会话历史 — 不同会话独立保存，可自动生成标题、排序和重命名。
• 多端聊天风格 — 桌面聊天、手机渠道和语音通话可使用不同的表达风格。
• 回复分段 — 可选择「全部分段 / 仅 Chat 分段 / 关闭」，长回复能够按语义拆分为多个聊天气泡。

下面各会话模式是 Harness 的"消费者"：

🛠️ 辅助工作（Work）

• CyreneHarness 主循环驱动 — 单条消息进入 CyreneHarness 的 while 循环：每轮调用 LLM → 写回 assistant 消息 → 派发工具 → 写回 tool result → 检查不确定副作用 → 继续或结束。预处理器（CITA 上下文理解）在 Harness 入口前完成；循环内每轮携带精简执行人设（prompts/cyrene_harness.md，只约束表达风格、不污染工具参数，冲突时按「任务正确性 > 信息清晰 > 昔涟风格」取舍）；完整人设层（Soul）在 Harness 出口后生成回复文本。
• 工具自由串联 — 支持联网搜索、网页读取、文件读写、文档生成、生活服务等工具按需组合调用；模型可自行决定下一个工具，无需预先编排流程。
• 人设与流程并存 — 在保留昔涟人格回复的同时承载工具调用。
• 右侧浏览器控制 — Cyrene 可以在应用内打开网址、读取页面元素，并按需点击、填写普通文本、滚动或截图检查。浏览器页面始终显示在右侧面板，操作结果可直接观察；控制权在同一对话的多轮消息间保持，任务完成后由 Cyrene 显式退出。页面内容只作为网页数据处理，密码、验证码与支付信息由用户亲自输入。

💻 代码协作（Code）

• 在 Work 基础上叠加代码专属工具 — 复用 CyreneHarness 主循环，额外注册代码专用工具集（读写改、命令执行、LSP 查询等）；工具执行前由权限审批（checkPermission）过滤不安全调用，Execution Policy 决定是否需要用户二次确认。
• 绑定可信工作目录 — 所有读写、命令执行与 LSP 查询必须落在用户预先绑定的目录内；模型无法指定或切换工作目录，越权访问（包括 .. 与符号链接逃逸）会被直接拒绝。
• 代码语义查询（LSP） — Code 模式可在已绑定工作目录中查询定义、引用、悬停、符号与诊断；不会修改文件。
• 外部服务由用户管理 — Cyrene 只提供 LSP 客户端，不随应用捆绑、下载、升级或静默安装语言服务器；请自行安装所需服务，也可以明确要求昔涟通过现有、受权限控制的工具协助安装。
• 安全边界 — 语言服务进程以 stdio: "pipe" 启动，shell: false，cwd 强制为绑定工作目录；模型不能指定命令、服务 ID 或工作目录。

内置支持的语言 — TypeScript / JavaScript / JSON、Python、Go、Rust、C / C++、Java、C#、PHP、Ruby、Kotlin、Lua、Vue、YAML（13 种，详见 src/main/lsp/server-catalog.ts）。

启动顺序 — 先按命令是否为绝对路径定位，否则在工作区 node_modules/.bin 中查找，最后回退到系统 PATH 逐目录遍历（Windows 还会按 PATHEXT 追加 .exe / .cmd 等扩展名）。

安装与排障 — 常见服务如 typescript-language-server、pyright-langserver、gopls、rust-analyzer、clangd、jdtls、OmniSharp、intelephense、ruby-lsp、kotlin-language-server、lua-language-server、vue-language-server、yaml-language-server；Windows 可用 where pyright-langserver，macOS/Linux 可用 which pyright-langserver 检查是否可发现。

自定义服务命令 — 在应用数据目录的 general-settings.json 中配置 lspServerOverrides，只覆盖 builtin 服务的 command / args / `exte