Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

DesktopAssistant(小助)

小助

面向个人学习的桌面 AI 助手。与以"代完成任务"为目标的主流 coding agent(Codex、Claude Code、OpenCode 等)不同,本项目的定位是长期陪伴式学习辅助:系统不代替用户完成工作,而是负责把安排落到日历上、记录进度并在该提醒的时候提醒,并通过持久化的记忆结构维持对用户长期状态的认知。

想读懂代码结构?先看 docs/tour.md(代码地图 / 三条主线 / 中间件速查 / 术语表 / 阅读路线)。

核心设计要点:

  • 长期记忆:对话历史经压缩后沉淀为 SQLite 分层摘要记忆树(memory tree)。记忆容量近似无限,且随对话持续更新——系统能够回忆起数周前的对话内容,并据此维持一致的交互人设。
  • 记忆驱动的提示词演化:系统提示词保持极简,人设信息不预先写死,而是在对话过程中通过摘要机制(用户画像、偏好、目标等结构化字段)逐步累积与完善。
  • 本地优先的感知能力:语音合成(TTS)、语音识别(ASR)、图像文字识别(OCR)全部基于开源模型本地推理,离线可用;支持文档挂载、屏幕内容识别与网页检索,用于理解用户当前所处的情境。
  • 桌面形态:Electron 悬浮球常驻桌面,支持单击/长按/拖拽等交互,后端(Python + LangChain,LangGraph 化 ReAct 循环)由前端自动拉起。

系统架构

后端(Python, http://127.0.0.1:18771)
  server.py        ThreadingHTTPServer + JSON 端点(/chat /dequeue /settings /tts/* …)
  session.py       PlannerSession:并发控制、调度线程、事件队列、免打扰
  agent.py         create_agent 构建(LangGraph,无 checkpointer)
  middleware.py    业务中间件链(免打扰/计划快照/玩家优先/记忆压缩/调用上限)
  tools.py         工具注册(19 个 function calling,见下文)
  tts.py / asr.py / ocr.py   本地语音合成 / 识别 / 图像文字识别
  memory/          SQLite 分层摘要记忆树
  store/           日历库(SQLite,CalendarDb)
前端(Electron)
  main.js          主进程:悬浮球窗口 + 面板窗口、托盘、HTTP 代理
  renderer/        悬浮球(bubble)与面板(index)页面、设置窗口

上下文管理:压缩与分层记忆树

大模型上下文窗口有界,而长期对话的需求是无限的。本项目以「压缩 + 分层摘要树」在二者之间建立平衡:

  • 触发条件:原始对话累积至阈值(默认 60 条)时,最早 40 条被压缩为一个叶子节点(node0_xxx)写入记忆树,上下文窗口回收至最近 20 条,生成成本保持恒定;
  • 层级结构:某层节点数量达到阈值(默认 8 个)时,前 4 个合并为上层节点(node1_xxx),逐层向上(4 合 1),直至根节点(node2_xxx)。节点携带摘要、用户画像、时间范围与全局序号区间;
  • 缓冲区状态:只有"最近一次压缩后尚未被进一步合并"的节点保留在上下文(buffer)中;被合并节点从 buffer 移除,永久沉淀于记忆树。

记忆树结构 + Buffer state

压缩中的未来信息校正

常规摘要式压缩将待压缩片段孤立地提交给模型,摘要无法反映该片段之后发生的事实变更(如用户推翻的决策、已完成的安排)。本项目压缩时,待压缩片段原样包裹于指令中,追加到完整原始上下文的末尾——模型可见被压缩区域之后(相对该区域而言属于"未来")的全部消息,摘要据此获得事后校正能力:

  • 后续对话否定的决策不会残留于摘要;
  • 安排的终态(完成/变更)被纳入摘要而非停留在中途;
  • 跨片段因果得以保持。

每一层摘要因此可视为"知情回顾"(informed retrospective),而非"截稿快照"(point-in-time snapshot)。

上下文复杂度的稳定性

压缩机制使上下文规模随对话轮数增长保持有界:

上下文随对话轮数增长(压缩前峰值 vs 记忆保留)

未引入记忆树时,上下文随轮数线性增长直至窗口上限(信息截断/遗忘);引入后,上下文维持于稳定水位,10,000 轮对话不越界:

长对话对比:传统上下文膨胀 vs 恒定水位

工具接口(function calling)

系统注册 13 个工具,由 LLM 在 ReAct 循环中自主调用:

工具 功能
list_schedule 按日期范围查日历(日程/待办,含时刻、状态、id)
add_schedule 加日程/待办;带 time 则到点自动提醒,带 repeat 则按每天/每周/工作日重复
update_schedule 改期 / 改时刻 / 改内容 / 标完成(whole_series 可作用于整个重复系列)
cancel_schedule 取消(默认只取消这一次;whole_series 取消今后各期)
heartbeat 用户嘱托的定时/巡检:设/改下一次唤醒(seconds 最短 1 分钟/minutes 最大 720 分钟),cancel=true 取消
continue_speaking 长回复分段:调用后暂停片刻再继续(可被用户立即打断)
explore_memory_tree 按需展开记忆树任意节点(历史回溯)
list_dir / read_file 文档浏览 / 读取(PDF/Word/文本自动解析)
capture_screen 屏幕截图 + OCR 文字识别
web_search / fetch_web 网页检索与内容抓取

功能特性

能力 说明
日历 日程/待办唯一入口:对话里加(add_schedule)或在日历页直接编辑;带时刻的项到点由调度线程提醒
重复安排 repeat=每天/每周/工作日;按规则生成实体行(1 年),并每小时滚动续期,不会到期默默消失
循环模型 create_agent 原生多轮 ReAct:一轮对话里模型可连续「调工具 → 看结果 → 再调工具」,不再返回工具调用即结束本轮
心跳 纯定时器(按需设置,非每轮必经):有未来要主动做的事才设;空闲时决定下一次何时醒来
议程快照 每轮注入 [当前议程](今天+未来 7 天,重复项折叠成一行),指纹去重不重复占 token
主动回访 调度线程:到点提醒(用户排的日程)、逾期项每日提醒、心跳自主唤醒三路独立触发
分段说话 continue_speaking:分点输出时分段暂停(可打断)
启动静默 启动 2 分钟宽限期;到期心跳顺延到宽限期后补触发
长期记忆 超阈值自动压缩入记忆树,explore_memory_tree 回溯
语音播报 本地 TTS:自动朗读 / 消息喇叭按钮 / 103 音色 / 开关与试听
语音输入 悬浮球长按 / 输入框 🎤,本地识别填入输入框
快速输入 悬浮球模式按 Alt+J(可改)在球旁弹出输入框:Enter 发送 / Esc 收起 / 带待发送文件
待处理提醒 需要审批/提问时悬浮球黄灯呼吸 + 球旁卡片,可就地授权或回答(也可展开面板)
子代理 White 主助手可派发独立后台任务;独立标签页/结果卡;同工作区文件硬限制、无命令;完成后通知主助手验收
气泡时长 悬浮球旁气泡停留时间,设置页可调(默认 30 秒)
文件/感知 拖拽挂载(PDF/Word/文本 + OCR)、截屏、网页搜索

使用的开源模型

语音与视觉能力基于开源模型本地推理(数据不出本机)。语音识别与图片识别模型首次使用时自动下载;语音合成模型需按下方命令手动下载至缓存目录(~/.cache/planner_tts),此后离线可用:

模型 用途 说明
Kokoro-82M-v1.1-zh 语音合成(TTS) 82M 参数,ONNX 推理(无 torch),100+ 中英文音色;配合 misaki 音素管线
SenseVoiceSmall 语音识别(ASR) 多语言识别,ONNX 版经 funasr-onnx 加载
RapidOCR 图像文字识别(OCR) PaddleOCR 的 ONNX 移植版(约 15MB)

各模型许可证以对应项目仓库为准。语音输入/识别/OCR 全程本地处理;仅对话内容发送至所配置的 LLM API。

环境要求

依赖 版本 说明
Python ≥ 3.10 建议 3.11/3.12(3.13 可用,部分依赖版本受限)
Node.js ≥ 18 前端(Electron);仅运行后端可省略
操作系统 Windows 已适配 Windows(透明悬浮窗/托盘);其他平台未验证

LLM 需为 OpenAI 兼容端点(默认 DeepSeek)。语音/OCR 能力全部本地推理,无需外部服务。

安装前确认 python --version 与 node --version 可正常执行。

安装与配置

1. 安装后端依赖

# 仓库根目录
python -m pip install -e .

2. 配置 LLM API

在仓库根目录创建 .env(已加入 .gitignore):

LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx   # 必填
LLM_BASE_URL=https://api.deepseek.com # 可选
PLANNER_LLM_MODEL=deepseek-flash      # 可选(默认即 deepseek-flash)

亦可直接设置同名系统环境变量。

3. 启动

方式一(推荐):仅启动前端,后端自动拉起:

cd frontend
npm install        # 首次
npm start

方式二:分别启动。先起后端:

python -m planner   # 监听 http://127.0.0.1:18771

再于另一终端启动前端(后端已运行则直接复用):

cd frontend
npm install
npm start

Mock 模式(脚本化假 LLM,不消耗 API 额度,可演示日历与心跳全流程):

set PLANNER_MOCK_LLM=1
python -m planner

语音合成模型(Kokoro-82M-zh,约 320MB,仅需下载一次):

pip install "huggingface_hub[cli]"
hf download onnx-community/Kokoro-82M-v1.1-zh-ONNX --include "model.onnx" "voices/*" "tokenizer.json" --local-dir "%USERPROFILE%\.cache\planner_tts\models\onnx-community--Kokoro-82M-v1.1-zh-ONNX\snapshots\master"

4. 验证

  • 访问 http://127.0.0.1:18771/init,返回 {"ok": true, "mode": "llm"} 即后端就绪;
  • 悬浮球:单击查看最近回复;长按语音输入;拖拽文件挂载后随消息发送。

配置项(环境变量)

变量 默认 说明
PLANNER_PORT 18771 后端监听端口
PLANNER_MOCK_LLM 关 =1 使用脚本化假 LLM
PLANNER_DATA_ROOT data/ 运行时数据目录
PLANNER_PYTHON python 前端拉起后端所用解释器
XIAOB_SHARED_ENV 无 共享 .env 路径(多项目复用 LLM 配置)
PLANNER_HEARTBEAT_MIN_SECONDS / MAX_MINUTES 0.1 / 720 心跳间隔护栏(连续干活 0.1 秒 ~ 空闲 12 小时)
PLANNER_TTS_ENGINE local cloud 时改用 DashScope 云合成

数据存储

data/
  planner.db        日历(calendar_items,WAL)
  memory_tree.db    记忆树节点 + 对话 buffer(WAL)
  logs/planner.log  运行日志(RotatingFileHandler)

数据重置:停止进程后删除 data/ 目录即可(日历、记忆、日志全部清空)。

测试

python -m pytest tests -v

覆盖:记忆树存储、日历库 CRUD、agent 生成管线(mock 驱动日历闭环)、心跳护栏与启动静默、免打扰、buffer 重启恢复、HTTP 端点集成、语音合成/识别、事件消费。全部测试以 mock LLM + tmp_path 隔离,不调用真实 API、不写入真实数据。

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages