# simple-agent

**Repository Path**: mada/si

## Basic Information

- **Project Name**: simple-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Jarvis

Jarvis 是一个面向 macOS 的桌面语音输入与语音助手工作台，基于 `Electron + Vue + TypeScript + Python worker` 实现。项目目标不是做一个单点“语音转文字”工具，而是把语音输入、语音助手、划词朗读、记忆、历史与多模型接入统一到同一个可控的桌面容器里。

当前代码已经覆盖这些核心能力：

- 统一全局快捷键
  - 短按：语音输入
  - 长按：语音助手
  - 如果当前应用里有选中文本，则同一快捷键优先触发划词朗读
- 本地语音识别
  - 默认使用 `SenseVoice Small`
  - 自动创建 Python 虚拟环境、安装依赖、下载模型、启动本地服务
- 可选流式语音识别
  - 支持接入豆包流式 ASR
  - 在“语音输入”模式下支持实时回填
- 文本生成与改写
  - 支持 `OpenAI 兼容环境变量`、`Ollama`、`通义千问`
  - 语音助手会把转写结果交给所选大模型生成最终输出
- 语音朗读
  - 支持豆包单向流式 TTS
  - 支持本地 `Qwen3-TTS` 作为备选
- 记忆与历史
  - 内置“用户词典”和“个人记忆”
  - 支持自定义记忆条目
  - 记录输出、时长、字数、Token 等历史信息

## 文档导航

如果你想快速把控项目，建议从这些文档开始：

- [文档总览](docs/README.md)
- [产品目标与范围](docs/product-and-scope.md)
- [架构说明](docs/architecture.md)
- [核心工作流](docs/workflows.md)
- [AI 协作指南](docs/ai-collaboration.md)

## 快速开始

### 环境要求

- macOS
- Node.js 20+
- Python 3.10+
- 已给应用开启以下系统权限
  - 麦克风
  - 辅助功能
- 可选的外部服务凭据
  - `OPENAI_API_KEY`
  - 豆包 ASR / TTS 凭据
  - 通义千问 DashScope API Key

### 安装与启动

```bash
npm install
cp .env.example .env
npm run dev
```

### 构建与检查

```bash
npm run check
npm run build
npm run dist
```

`npm run check` 当前会做两件事：

- TypeScript 类型检查
- Python worker 语法检查

## 环境变量

最常用的是这三个：

```bash
OPENAI_API_KEY=
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_TEXT_MODEL=gpt-4o-mini
```

说明：

- 当默认大模型 provider 为 `env-openai` 时，主流程会使用以上环境变量。
- `.env.example` 里保留了 `OPENAI_TRANSCRIBE_MODEL` 和 `OPENAI_TRANSCRIBE_LANGUAGE`，但当前主流程并不依赖这两个变量，它们更像历史遗留占位。

## 项目结构

```text
src/
  main/
    index.ts                    主进程编排中心、窗口、IPC、快捷键、流程 orchestration
    services/
      macos-input.ts            与 macOS 前台应用、剪贴板、选区、粘贴交互
      memory.ts                 记忆归一化、词典替换、提示词上下文构建
      sensevoice-manager.ts     本地 SenseVoice 安装、启动、健康检查
      qwen-tts-manager.ts       本地 Qwen3-TTS 安装、启动、试听与合成
      doubao-asr.ts             豆包流式 ASR 接入
      doubao-tts.ts             豆包流式 TTS 接入
      ollama.ts                 Ollama 模型发现与调用
      qwen.ts                   通义千问 OpenAI 兼容调用
      text-model.ts             语音助手提示词与统一 LLM 调用入口
      toggle-shortcut.ts        低层全局按键监听与短按/长按判断
  preload/
    index.ts                    向渲染进程暴露安全 IPC API
  renderer/
    app/useAgentController.ts   前端状态中心、录音控制、设备与面板交互
    components/                 主界面、记忆、模型、设置、悬浮 overlay
  shared/
    types.ts                    主进程/渲染进程共享协议与类型
resources/
  sensevoice_worker.py          本地 ASR HTTP worker
  qwen_tts_worker.py            本地 TTS HTTP worker
```

## 核心设计摘要

Jarvis 当前可以理解为 3 条能力链路的组合：

1. 语音输入链路  
   `录音 -> ASR -> 文本输出 -> 自动粘贴/复制`

2. 语音助手链路  
   `录音 -> ASR -> LLM -> 最终结果 -> 自动粘贴/复制`

3. 划词朗读链路  
   `捕获选中文本 -> TTS -> 音频播放`

这三条链路共用：

- 同一套窗口体系
- 同一套快捷键体系
- 同一份记忆与偏好配置
- 同一个历史与日志落盘位置

## 当前限制

- 当前明确以 macOS 为主，`macos-input.ts` 里使用了 AppleScript 与系统事件控制
- 自动粘贴、划词捕获、前台应用切换都依赖系统权限，权限缺失时只能部分降级
- 自动化测试仍比较薄，当前主要依赖 `npm run check` 与手工验证
- `src/main/index.ts` 已承担较多编排职责，后续演进建议继续拆分

## 推荐阅读顺序

如果你是人类开发者：

1. [产品目标与范围](docs/product-and-scope.md)
2. [架构说明](docs/architecture.md)
3. [核心工作流](docs/workflows.md)

如果你是要协作改代码的 AI：

1. [AI 协作指南](docs/ai-collaboration.md)
2. [架构说明](docs/architecture.md)
3. [核心工作流](docs/workflows.md)