# qwen-ts

**Repository Path**: xccblank/qwen-ts

## Basic Information

- **Project Name**: qwen-ts
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-29
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QwenPaw 桌面版（qwen-ts）

Electron + TypeScript 编写的**单机 AI 智能体桌面端**：本地 SQLite 持久化会话，
内置 ReAct 循环与 9 个工具（文件读写、命令执行、长期记忆、文件交付），
支持 **OpenAI 兼容协议与 Anthropic 兼容协议**（按 baseURL 自动识别）流式对话。

## v1.1 变更（2026-09-29）

1. **Anthropic 协议支持**：baseURL 含 `anthropic` 即自动切换（如智谱
   `https://open.bigmodel.cn/api/anthropic`，请求自动归一化到 `/v1/messages`，
   `x-api-key` + Bearer 双认证 + `anthropic-version` 头）。工具调用
   （tool_use/tool_result）、思考流（thinking_delta）均支持。
2. **better-sqlite3 升级 ^12.11.1**：提供 Node 20-24 与 Electron 31 的预编译二进制，
   Windows 免装 Visual Studio（配合 `.npmrc` 国内镜像直连下载）。
3. **`.npmrc` 内置镜像**：registry / electron / electron-builder / better-sqlite3
   二进制全部走 npmmirror，绕开 GitHub 下载（解决 ECONNRESET）。
4. **修复**：`getSettings()` 数值字段类型归一化（temperature 以数字下发，
   修复字符串类型导致部分 API 400）。

## 快速开始

```bash
npm install        # 安装依赖（首次会编译 better-sqlite3 原生模块）
npm run dev        # 开发模式启动（electron-vite）
npm run build      # 打包安装包（electron-builder，产物在 dist/）
npm run typecheck  # 类型检查（node + web 两份 tsconfig）
```

启动后点右上角 **⚙** 填 API Base URL / Key / 模型，选择工作区目录，保存即可对话。

## 技术栈

| 层 | 选型 |
|---|---|
| 壳 | Electron 31 |
| 构建 | electron-vite 2 |
| 主进程 | TypeScript + better-sqlite3（WAL）+ 手写 fetch/SSE |
| 渲染 | Vue 3.4 `<script setup>` + 原生 CSS（暗色主题） |
| 桥接 | contextBridge 暴露类型安全的 `window.qwenpaw` |

## 目录结构

```
qwen-ts/
├── electron.vite.config.ts     # 三端（main/preload/renderer）构建配置
├── src/
│   ├── shared/types.ts         # ★ 唯一真相源：主/渲染共享类型与 API 形状
│   ├── main/                   # 主进程
│   │   ├── index.ts            # app 入口（单实例锁、窗口、初始化）
│   │   ├── ipc.ts              # 全部 ipcMain.handle（QwenpawApi 的实现）
│   │   ├── db.ts               # SQLite 四表 + DAO（sessions/messages/tool_calls/settings）
│   │   ├── settings.ts         # 设置读写（落 SQLite）
│   │   ├── workspace.ts        # 工作区路径安全（防 ../ 逃逸、交付文件解析）
│   │   ├── agent/
│   │   │   ├── react.ts        # ★ ReAct 循环（迭代、工具执行、标题生成）
│   │   │   ├── model-client.ts # 流式 SSE 客户端（丢弃 reasoning_content 规避 400）
│   │   │   ├── prompts.ts      # 系统提示词
│   │   │   └── types.ts        # Agent 内部类型
│   │   └── tools/              # 9 个工具
│   │       ├── index.ts        # 工具注册表 + send_file_to_user
│   │       ├── fs.ts           # read/write/append/edit/list/grep
│   │       ├── shell.ts        # run_command（60s 超时 + 输出截断）
│   │       └── memory.ts       # memory_search / remember_memory
│   ├── preload/index.ts        # contextBridge 暴露 window.qwenpaw
│   └── renderer/               # 渲染进程（Vue）
│       ├── index.html
│       └── src/
│           ├── main.ts         # createApp(App).mount('#app')
│           ├── App.vue         # ★ 状态中心 + 9 种 AgentEvent 分发
│           ├── chat.css        # 暗色主题
│           └── components/
│               ├── SessionSidebar.vue  # 会话列表/新建/重命名/删除
│               ├── ChatPanel.vue       # 消息流 + 流式预览 + 输入区
│               ├── MessageBubble.vue   # 气泡（reasoning 折叠）
│               ├── ToolCallCard.vue    # 工具调用卡片（状态图标）
│               ├── FileCard.vue        # 交付文件卡片（点击打开）
│               └── SettingsModal.vue   # 设置表单（含测试连接）
```

## 运行时数据流

```
用户输入 → ChatPanel emit('send')
  → App.onSend → 乐观追加用户消息 → window.qwenpaw.send({sessionId, content})
  → [主进程] ipc 'chat:send' → runAgent({sessionId, userText, settings, emit, signal})
      → 循环：model-client 流式请求 → emit assistant-delta
              → 解析 tool_calls → 执行工具 → emit tool-start/end/tool-message
      → 达到终止条件 → 持久化 assistant 消息 → emit done
  → [渲染] onEvent 收事件 → 更新 stream/messages/records/files
  → done 后 refreshActive() + loadSessions() 对齐数据库
```

**关键约定**
- 所有事件走单一通道 `agent:event`，由 `AgentEvent` 联合类型约束（9 种）。
- 主进程按会话维护 `AbortController`，`chat:stop` 中止运行。
- 同一会话并发发送会被拒绝（"该会话正在回复中"）。
- 工具只能在工作区内操作（`workspace.ts` 拒绝 `../` 逃逸）。
- 流式期间 UI 用内存缓冲渲染，`done` 后以数据库为准刷新，避免重复。

## 安全说明

- API Key 存于本地 SQLite（`userData/qwenpaw.db`），不上传第三方，仅用于调用所配置的模型接口。
- 工作区路径做归一化 + 前缀校验，工具无法越出工作区（`send_file_to_user` 除外，它按交付白名单解析）。
- `run_command` 以当前用户权限执行，设 60s 超时与输出截断，请勿在工作区放大规模破坏性脚本。

## 已知限制

- 暂不含：多会话并发回复、附件上传、Markdown 富渲染、自动更新。

## 故障排查（Windows / 国内网络）

| 现象 | 原因与处理 |
|---|---|
| `prebuild-install read ECONNRESET` | 二进制从 GitHub 下载被重置。本项目 `.npmrc` 已配置 npmmirror 镜像，确认该文件在项目根目录后重试。 |
| `gyp ERR! find VS`（要求 VS2019+） | 说明走了本地编译。better-sqlite3 ^12.11.1 有 Node 24 / Electron 31 预编译包，正常情况**不需要 VS**。若仍触发：确认 `.npmrc` 存在 + `npm cache clean --force` 后重装。 |
| `ETARGET No matching version` | registry 里无该版本。better-sqlite3 12.x 最高 `12.11.1`（不存在 12.12.0）。 |
| `EPERM rmdir node_modules` | 残留目录被占用。关闭编辑器/终端后重启电脑再删，或用资源管理器删除。 |
| `npm warn Unknown project config "electron_mirror"...` | **无害**。npm 11 对 .npmrc 第三方配置项的提醒，配置仍生效。 |
| `Error: Electron uninstall`（dev 启动即报） | Electron 二进制没下载成功（`node_modules/electron/dist` 缺失）。**勿用 `npm install --ignore-scripts`**。修复：`set ELECTRON_MIRROR=https://registry.npmmirror.com/-/binary/electron/` 后执行 `npm run fix:electron`（或 `node node_modules\electron\install.js`）。 |
| Electron 二进制下载卡住/校验失败 | 上次下载中断留下坏缓存。加 `set force_no_cache=true` 再跑 `npm run fix:electron`，或删除缓存目录 `%LOCALAPPDATA%\electron\Cache`。 |
| `ENOSPC: no space left on device` | 磁盘满（Electron 需 ~400MB 空间：110MB 压缩包 + 解压）。清理空间或把项目移到空间充足的盘再装。 |
| `npm run rebuild` 报 electron-rebuild 不存在 | 旧版脚本笔误，v1.2 已改为 `electron-builder install-app-deps`。 |
| 聊天回答空白 | 旧版对 Anthropic 端点用错协议导致错误被吞。v1.1 已支持 Anthropic 协议；若再出现，请看 `npm run dev` 终端输出。 |
| 气泡显示 `HTTP 429 [1113] 余额不足` | 账户问题：去模型服务商控制台充值或换 key，与代码无关。 |

## 许可

内部项目，未附开源许可。


## Electron 手动安装（fix-electron.cmd 失败时的兜底）

1. 浏览器打开（约 110MB，浏览器下载通常更稳）：
   `https://registry.npmmirror.com/-/binary/electron/31.7.0/electron-v31.7.0-win32-x64.zip`
2. 解压 zip，得到 `electron.exe` 等一堆文件
3. 在项目下新建目录 `node_modules\electron\dist`，把解压出的**全部文件**移进去
4. 在 `node_modules\electron` 下新建文本文件 `path.txt`，内容只写一行：`electron.exe`（末尾不要回车）
5. 再执行 `npm run dev`

注意：`path.txt` 和 `dist\` 必须都在 `node_modules\electron` 这一层，缺一个都会报 `Error: Electron uninstall`。