vococo

基于 Claude 订阅 的个人 AI 助理，单用户、常驻、语音优先、多渠道共用一个大脑。

截图

聊天 · 工具调用	工作台
语音对话	定时任务

完整需求与验收标准见 REQUIREMENTS.md。

特性

• 多渠道，一个会话 — TUI / CLI / Web（自建 PWA，手机浏览器直达）；全端共享同一主会话
• Web 自建 UI — 多会话侧边栏、工具调用卡片、模型面板 + 限额环、设置页全在线改
• 语音优先 — 按住说话（STT）、TTS 朗读、Omni 实时免提通话（可打断）
• 后台任务引擎 — 语音派活 / cron / 独立新会话共用一套引擎，任务跑在独立 git worktree
• 长期记忆 — 启动注入 ~/AI_BRAIN；save_memory 沉淀、recall_past 召回，纯 Markdown
• 多供应商热切换 — DeepSeek / Kimi / 任意 Anthropic 兼容中转，设置页添加即生效
• 运行数据面板 — 设置页「数据」:工作强度日历、各模型用量与花费、缓存命中/工具成功率，逐个会话可下钻
• 安全模型 + 自我运维 — 危险三档闸、手机审批；vococo doctor 自检、restart_self 安全重启、看门狗防假死

架构

vococo/__main__.py     CLI 入口:tui / chat / serve / cron / doctor
core/                  agent 循环(claude-agent-sdk)· client 保温池 · prompt 组装
                       · 每会话 git worktree 隔离 · 后台任务引擎(task_runner)
gateway/               平台内核(命令注册表 / converse / 会话路由)
  ├─ adapters/web        自建 PWA(SSE 流式 / 多会话 / 设置页)
  ├─ adapters/web_push   VAPID Web Push 系统通知
  ├─ settings_store.py   设置页存储(供应商/模型/skill/MCP/effort)
  └─ stats.py            运行数据面板:日志增量 ETL(stats.db)+ 用量/花费/会话聚合
cron/                  cron / interval / once 调度 + 自动化建议(consent-first)
memory/                SQLite 会话库(state.db)+ 检索 + 图片/音频附件
tools/                 内置 MCP server(记忆/定时/发消息/自我重启…)
                       + danger.py(灾难拦截 + 审批闸 PreToolUse hook)
tui/                   rich/prompt_toolkit 流式 TUI(工具过程 + Markdown)
voice/                 语音:STT 转写 · TTS 朗读 · Omni 免提实时通话
plugin/                内置 skill 插件(只给 vococo 自己用,如 vococo-web-publish)
deploy/                run.sh 守护循环(崩溃自启)/ stop / restart / launchd

入口

vococo            # 默认进 TUI
vococo chat       # 纯文本对话(调试 fallback)
vococo serve      # 常驻:Web + 调度器(heartbeat/主动推送)
vococo cron       # 列出定时任务
vococo doctor     # 自检:配置/认证/DB/AI_BRAIN/进程

Web 入口:serve 时设 WEB_ENABLED=1 即在同进程起网页服务(默认只听 127.0.0.1:8848),
配合 Cloudflare Tunnel / Tailscale 暴露到公网即得手机 PWA(走公网必设 WEB_AUTH_TOKEN)。

快捷命令(TUI/Web 通用)

/new 开新会话(旧史保留) · /clear 清屏+开新 · /model [名] 切模型 · /history 看历史 · /status 会话信息 · /suggest 看/接受自动化建议 · /help

多供应商切换

想用 DeepSeek / Kimi 或任意第三方 Anthropic 兼容中转:在 Web 设置页的「模型」
管理界面直接添加(base_url + key + model),每轮自动生效,无需重启;会话里
/model <模型名> 可临时覆盖。只用第三方时,.env 里的订阅 token 可留空。
认证细节见 REQUIREMENTS.md §6。

常驻(macOS)

deploy/*.sh 目前假设 macOS + zsh。Linux 用户请照 deploy/run.sh 的思路自行写
systemd unit;核心就是把 uv run vococo serve 跑成常驻进程。

bash deploy/run.sh     # 后台启动(登录 shell,推荐)
bash deploy/stop.sh    # 停止
tail -f data/logs/vococo.out.log   # 看日志

⚠️ 不要把项目放在 iCloud 同步的 ~/Desktop/~/Documents 下——常驻进程
open() 这些文件会被 File Provider 阻塞。放 ~/Repos 等纯本地目录。

⚠️ launchd 直接拉起在某些 Mac 上会卡死:launchd 会话上下文不完整,
agent 派生的 claude 子进程会同步阻塞冻住事件循环。所以用 deploy/run.sh
(登录 shell)而非 deploy/launchd.sh。开机自启可把 run.sh 加为登录项
(系统设置 → 通用 → 登录项),它运行在完整 GUI 登录会话里,不受此限。

定时主动推送

编辑 data/cron_jobs.json(模板见 deploy/cron_jobs.sample.json),把任务 enabled 设 true,
serve 进程每 30s 检查到期任务并推送结果。支持 cron / interval / once 三种调度。
默认是需要分析/决策的 Agent 任务;固定脚本可设 mode: "script" 和 command,直接执行、不进
Agent。脚本末行输出 ##CRON_SIGNAL:0## 时原样展示结果、零 LLM 调用;输出
##CRON_SIGNAL:1## 时才按可选 summarize_prompt 做一次轻量总结。
也可以直接对它说「每天早上 8 点给我发 XX」——它会用 add_cron_job 建好等你确认。

快速开始

前置:Python ≥ 3.11、uv、一份 Claude Pro/Max 订阅
(或任意 Anthropic 兼容的第三方端点,见「多供应商切换」)。平台:macOS / Linux
已验证;Windows 未测(常驻脚本走 zsh + launchd,仅 macOS)。

# 1) 装依赖(uv 推荐;也可 python -m venv + pip install -e .)
uv sync --extra dev

# 2) 配认证(需 Claude Pro/Max 订阅)
claude setup-token            # 生成 sk-ant-oat01-... 令牌
cp .env.example .env          # 把令牌填进 .env 的 CLAUDE_CODE_OAUTH_TOKEN

# 3) 自检 + 开聊
uv run vococo doctor   # 检查配置 / 激活供应商
uv run vococo chat

配置

全部配置走项目根的 .env(从 .env.example 复制,已 gitignore)。最常用的几项:

其余变量(安全闸、语音、Web Push、多供应商…)在 .env.example 里逐条有注释。

设计要点

设计原则、非目标红线、与原版 Hermes 的差异对照见 REQUIREMENTS.md
§1–§5;术语与安全模型见 CONTEXT.md / SECURITY.md。

⚠️ 订阅令牌只配个人自用;商用/对外必须改回 API key 按量计费。

许可

MIT。这是个人自用助理框架,fork 后请生成属于自己的凭据
(Claude / VAPID),别把 .env、data/ 提交进仓库(默认已 gitignore)。