# zcode-assistant

**Repository Path**: argustang/zcode-assistant

## Basic Information

- **Project Name**: zcode-assistant
- **Description**: zcode 已提优化意见，为何迟迟不更新？是人性的扭曲，还是道德的沦丧。
既然你迟迟不优化，那让我来把。zcode助手，你值得拥有！
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2026-08-13
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zcode-assistant

> zcode 使用增强工具：配额监控、模型管理、自动切换、悬浮球、账号切换、用量统计。

一个基于 **Tauri 2 + Vue 3 + myui + TypeScript + Vite** 的桌面应用，采用统一界面方案（myui 设计令牌 · OKLCH 液态玻璃 · 深/浅双主题），所有数据本地读写 `~/.zcode/v2`，不外传。

## ✨ 功能特性

| 模块 | 说明 |
| --- | --- |
| 📊 总览 | 配额监控（每 5 小时 / 每周）、当前模型、账号状态，托盘双环图标实时反映用量 |
| 🧩 模型管理 | 拉取可用模型、配置上下文 / 输出上限、写回 zcode、自定义供应商 + 预设一键填充；支持与 Oh My Pi（OMP）原生 `~/.pi/agent/models.json` 手动双向同步；Token Plan 6 家供应商自动额度查询 |
| 🔀 自动切换 | 定时切换、配额耗尽自动切换到下一个供应商（直写 zcode 会话模型选择记录 + 直改 setting.json） |
| 📁 项目 / 会话 | 读取 zcode 会话库，按项目查看会话数 / 对话次数 / token 消耗；行内改名、归档 / 恢复（项目 / 会话独立按钮）、批量归档（会话 / 项目）、批量删除；清理缓存（按 3 天–1 个月时间范围批量清理久未活跃会话及其数据并压缩会话库） |
| 👤 智谱账号 | 多账号捕获与一键切换 |
| 🌐 网络代理 | HTTP / SOCKS5 代理 |
| 📈 用量查询 | 解析 zcode rollout 日志，按供应商 / 模型 / 日期统计 token 用量与速度，支持月限额桶 |
| 🎨 美化 | ZCode 主题换肤 / 换字体 / 毛玻璃 / 图片·视频壁纸：asar 秒级原地补丁注入 `file://` 外链，主题资产外置 + 每秒热重载，参数改动约 1 秒实时生效，支持三区域独立透明度与文字描边 |
| ⚙️ 设置 | 主题（深色液态玻璃 / 浅色）、配额查询模板、关于、检查更新 |
| 🎈 悬浮球 | 桌面悬浮快捷面板 |

## 🚀 快速开始

### 环境要求

- [Node.js](https://nodejs.org/) ≥ 18
- [Rust](https://www.rust-lang.org/)（stable 工具链）
- Tauri 2 系统依赖：参见 [Tauri Prerequisites](https://tauri.app/start/prerequisites/)

### 安装依赖

```bash
npm install
```

### 开发模式

```bash
npm run tauri:dev
```

### 打包发布

```bash
npm run tauri:build      # 产物在 src-tauri/target/release/bundle/
```

## 🧱 技术栈

- **前端**：Vue 3 · myui（统一组件库，git 依赖）· Element Plus · TypeScript · Vite 6
- **后端**：Rust · Tauri 2
- **存储**：SQLite（rusqlite，bundled）+ 系统 keyring（凭证安全）
- **加密**：AES-256-GCM（zcode `credentials.json` 的 `enc:v1` 解密）
- **网络**：reqwest（rustls，免 OpenSSL）

## 🔢 版本号与发版

版本号的**单一真相源**是 [`src-tauri/Cargo.toml`](./src-tauri/Cargo.toml) 的 `[package] version`：

- 编译期通过 `env!("CARGO_PKG_VERSION")` 注入（见 [`version.rs`](./src-tauri/src/version.rs)）
- `npm run build` 会自动通过 [`scripts/sync-version.mjs`](./scripts/sync-version.mjs) 同步到 `package.json` / `package-lock.json`
- `tauri.conf.json` 不再写 `version` 字段，Tauri v2 直接读 Cargo.toml
- 单独同步：`npm run version:sync`

发版流程：

```bash
# 1. 改 Cargo.toml 的 version
# 2. 同步 + 打包
npm run version:sync
npm run tauri:build

# 3. 发布到 Gitee / GitHub（需设置对应 TOKEN 环境变量，或仓库根 .gitee-token / .github-token 文件）
npm run release:gitee  -- <version> <notes.md>
npm run release:github -- <version> <notes.md>
# 例：npm run release:gitee -- 0.2.0 CHANGELOG.md
```

## 📦 仓库

- Gitee：<https://gitee.com/argustang/zcode-assistant>
- GitHub：<https://github.com/DearTang/zcode-assistant>

## 🔄 自动更新

采用**自定义轻量更新**方案（不集成 `tauri-plugin-updater`，无签名密钥 / CI manifest）：

- 后端 `check_for_updates` 拉取 Gitee 发行版列表，按 semver 取最大 tag 与当前版本比较
- 发现新版本后弹窗：`更新` → 流式下载安装包（进度条）→ `安装并重启`
- 非 Windows 平台走「打开下载页」浏览器兜底
- 配置项在 [`src-tauri/src/updater.rs`](./src-tauri/src/updater.rs) 顶部的 `RELEASES_ENDPOINT`

## 📊 匿名使用统计（opt-in）

- 默认**关闭**，每个新版本首次启动询问一次（同意 / 暂不）
- 仅上报：**匿名设备 ID + 应用版本 + 操作系统**，绝不收集账号 / 凭据 / 连接内容
- 经 [Umami Cloud](https://cloud.umami.is/) 上报，每版本一次
- 启用：在 [`src/lib/usageStats.ts`](./src/lib/usageStats.ts) 填入你注册的 `UMAMI_WEBSITE_ID`（留空则跳过上报）

## 🔒 隐私与安全

- 所有配置本地读写，不外传
- API Key 等凭证通过系统 keyring 存储，界面层脱敏展示
- 仓库已通过敏感信息扫描，无硬编码密钥 / 令牌

## 📁 项目结构

```
zcode-assistant/
├── src/                    # 前端（Vue 3 + TS）
│   ├── views/              # 各功能页面（每个视图一个目录）
│   ├── components/         # 复用组件（壳层、弹窗、字段件、配额环等）
│   ├── composables/        # 组合式函数（toast、换肤、更新检查）
│   ├── store/              # 轻量全局状态（主题 / 布局偏好）
│   ├── icons/              # 自绘 SVG 图标（注册进 myui 图标白名单）
│   ├── i18n/               # vue-i18n（仅承载 myui 库词条）
│   ├── lib/                # 工具库（使用统计等）
│   └── api.ts              # Tauri command 调用封装
├── src-tauri/              # 后端（Rust + Tauri）
│   ├── src/
│   │   ├── commands/       # #[tauri::command] 命令模块
│   │   ├── zcode/          # zcode 配置读写 / 解密 / 进程
│   │   ├── updater.rs      # 自动更新逻辑
│   │   ├── version.rs      # 版本号常量
│   │   └── db.rs           # SQLite 数据层
│   └── tauri.conf.json
└── scripts/                # 版本同步 / 发版脚本
```

## 📄 License

私有项目。

## 🔄 更新日志

完整版本历史见 [CHANGELOG.md](./CHANGELOG.md)。最新版要点摘录：

### 未发布

### v0.13.0 (2026-09-22)

**新增**：ZCode 3.14 模型信息自动迁移。ZCode 升级到 3.14 时自带的迁移只搬运了模型的上下文窗口（`limit.context` → `properties.contextWindow`），模型原有的**输出上限、模态、推理档位**全部没跟着搬，表现为「升级后原来导入的模型信息都不见了」（旧 `config.json` 里这些数据仍在，只是新配置里为空）。现从旧 `config.json` 自动回填缺失字段，**只补缺不覆盖**、幂等可重复执行：应用启动时后台自动跑一次，模型管理页进入时再核对一次，有回填时页面顶部给出横幅汇总（供应商 / 模型 / 字段数），也可点「重新检查」手动重跑。回填时保留 ZCode 自己写入的字段（`optionSpecs.reasoningLevel.map` 等请求体映射），纯文本模型不写 `inputFormat` 以免覆盖内置更准确的模态声明，手动配置的模型规则原地补齐、不会被挪进智能规则表。

### v0.12.2 (2026-09-22)

**修复**：ZCode 升级到 3.14 后「模型管理」失效——ZCode 3.14 起把用户自定义供应商与模型配置从 `~/.zcode/v2/config.json` 迁到 `~/.zcode/v2/provider_config.json`（`schemaVersion: 1` 全新结构），旧文件不再被读取，导致改上下文 / 输出上限、启用禁用模型、增删供应商与模型、拖拽排序等操作全部写进废弃文件而不生效。新增 `provider_config.rs` 适配层做双向投影：读取时把新结构还原为既有的 `{"provider": {...}}` 形状，写回时把改动合并进新结构（只动用户自定义 provider，`builtin:` / `account:` 归 ZCode 内置配置所有原样保留），并保留 ZCode 自己写入的字段（`optionSpecs.reasoningLevel` 等请求体映射、套餐模型顺序）；订阅套餐 provider 的新 id（`account:bigmodel-individual-coding-plan` 等）投影时还原为旧 `builtin:*` id，使既有订阅识别与配额逻辑继续生效；旧版 ZCode 仍自动回退 `config.json` · 账号切换（快照 / 切换 / 回滚）同样按版本落到当前生效的配置文件，新格式下只覆盖账号作用域的订阅规则，用户自定义供应商不受影响 · 「导入配置」来源 `zcode` 的默认路径与解析同步适配新文件。

### v0.12.1 (2026-09-21)

**修复**：`addProvider` invoke 时参数键误写为 `baseURL`，Tauri v2 默认按 snake_case→camelCase 自动映射 `base_url`，期望前端键为 `baseUrl`，导致后端报 `missing required key baseUrl`；TS 形参名保持 `baseURL`，仅修正 invoke 载荷键，与同文件 `updateProvider` / `testConnection` 的「TS 形参 `baseURL`、invoke 键 `baseUrl`」写法对齐。症状：模型管理「添加供应商」保存按钮提交后弹窗报「invalid args baseUrl for command add_provider: missing required key baseUrl」。

### v0.12.0 (2026-09-19)

**新增**：主界面接入命令面板（Ctrl/Cmd+K 唤起），按关键词搜索并跳转全部 10 个功能页。

**变更**：前端整体迁移到统一界面方案——React 18 → Vue 3 + myui 组件库（v0.7.0 起），壳层布局对齐 unified-ui 模板（顶栏 + 可折叠侧栏 + 内容区 + Overlay 层），全部页面 / 弹窗 / 表单改用 myui 组件与统一设计令牌（OKLCH 液态玻璃、`html.dark/html.light` 双主题），新增《统一界面重构评估报告》《myui 缺口反馈清单》工程文档 · 主题系统升级为三态（深色 / 浅色 / 跟随系统），旧主题偏好自动迁移 · 「外观定制」换肤在统一令牌体系上重写，存量偏好无缝沿用 · 模型管理页巨石拆解（3838 行单文件 → 主视图 + 5 个弹窗子组件 + 配额行组件），行为不变 · 确认交互统一为 Promise 式 `confirmDialog()`，不再使用原生 `confirm()` · 依赖变更：移除 React 全家桶，新增 vue / element-plus / vue-i18n / myui / markdown-it；`npm run test:ts` 改为 `vue-tsc` · myui 三轮跟进升级至 v0.18.0（v0.10.0 回落框架能力删除 5 个本地兜底组件；v0.12.0 修复命令面板 0×0 与双环分档缺陷；v0.18.0 顺带修复侧栏线性图标被灌成实心块的观感问题）。

**修复**：项目 / 模型 / 自动切换 / 账号 / 美化等页状态标签与文本重叠——`MyBadge`（el-badge 角标，内容绝对定位）被误用作内联状态药丸，全部改用 `MyTag` · 主窗口只显示背景图、界面不渲染——壁纸层 `fixed + z-index:0` 绘制顺序盖住无层叠上下文的壳层，改为 `z-index:-1` 置底 · 设置页「外观」主题按钮选中态样式笔误与 Beautify 徽标类名笔误。

### v0.11.0 (2026-09-11)

**新增**：模型管理新增 Oh My Pi（OMP）模型双向同步——可从 `~/.pi/agent/models.json` 预览并导入供应商、模型名称及上下文 / 输出限制，也可将 ZCode 自定义供应商同步回 OMP；两端均需在预览中勾选确认，按 `baseUrl + apiKey` 覆盖或新增，不删除既有条目。导出自动生成 `models.json.bak`，且不会修改 OMP `settings.json` 的默认供应商 / 模型。

### v0.10.0 (2026-09-09)

**新增**：侧边栏新增「重启 ZCode」快捷入口，位于底部操作分隔线之上；点击后显示重启中状态与结果提示，无需切换到其他页面即可手动重启 ZCode。

### v0.9.0 (2026-09-07)

**新增**：美化「外置主题 + 实时热更新」架构重构——`app.asar` 仅注入 3 个 `file://` 外链（变量 / 主题 / 运行时脚本），主题资产外置到本应用数据目录；已注入状态下**所有参数改动约 1 秒实时生效**（运行时脚本每秒热重载变量文件），无需重打 asar / 重启 ZCode；「应用美化」仅首次注入 / ZCode 升级 / 修复注入时使用 · 美化新增视频壁纸（mp4 / webm / mov，按扩展名自动切换 `<video>` / `<img>`，副本存于主题目录不依赖源路径）、壁纸滤镜与可读性参数（亮度 / 饱和度 / 模糊 / 压暗遮罩 / 视频播放速率 / 三区域独立透明度 / 文字描边强度）、分区透明元素规则与 Windows 全视口应用壳透明规则（实机选择器沿用 ZCode 桌面端 `#sidebar` / `[data-pane-id]`，统一由「透出模式」开关门控） · 项目管理新增「清理缓存」——按 3 天 / 5 天 / 7 天 / 半个月 / 1 个月时间范围批量删除久未活跃会话及其全部数据（消息 / 子代理 / 任务索引 / agents / artifacts / exec / rollout），并 VACUUM 压缩会话库回收磁盘空间；弹窗实时预览待删会话数与可释放空间，执行前双重确认 · 项目管理批量归档扩展到项目（新增「归档所选项目」，逐个归档其全部活跃会话，只归档不删除可随时恢复）；原「关闭所选」更名为「归档所选会话」。

**变更**：归档 / 恢复按钮名称具体化消除歧义——项目行 →「归档项目 / 恢复项目」，会话行 →「归档会话 / 恢复会话」，相关确认与提示文案同步更新 · 项目 / 会话删除改为双重确认（删范围 + 数据不可恢复），结果提示新增实际释放的磁盘空间 · 美化配置新增字段（`sidebar_opacity` / `panel_opacity` / `sidebar_right_opacity` / `text_shadow` / `wallpaper` / `wp_brightness` / `wp_saturate` / `wp_blur` / `mask_strength` / `playback_rate`）；旧 `bg_image` 字段与既有 config.json / 模板完全兼容（`wallpaper` 优先），旧版注入（asar 内打包 css/js）的应用会在下次「应用美化」时自动升级为外链方案并清理旧资产。

### v0.8.0 (2026-09-02)

**新增**：项目管理会话列表全选 + 批量关闭——表头全选框（半选态），勾选后「关闭所选」批量归档所选会话（已归档自动跳过，可在「查看历史会话」恢复），清理积压会话不再逐个点击 · 自动切换「应用启动」规则支持生效时间范围——默认全天生效，可指定起止时间（默认 09:00–18:00，支持跨零点范围），仅启动时刻落在范围内才触发，规则列表同步展示。

**修复**：「应用启动」自动切换被误判「已是目标」而静默跳过——此前依据最近一次自动切换写入的内部标记判断，手动把模型切走（供应商不变）后标记不更新，下次启动不执行；现改为读取最近活跃会话的实际模型选择，手动切换可被感知，启动触发恢复可靠。

### v0.7.0 (2026-08-28)

**新增**：侧边栏「ZCode 设置」页，首个能力「模型调用重试」——通过 `ZCODE_MODEL_RETRY_*` 环境变量调整重试次数 / 起步延迟 / 退避倍数 / 延迟上限，留空跟随默认、一键恢复、实时预览退避序列 · 悬浮球面板「固定」——单击球固定常驻（移开 / 点窗外不收起，「已固定」徽标提示），悬停快查行为不变。

**变更**：打包提速——release 配置换 thin LTO + codegen-units=16，重复打包编译耗时大幅下降，体积与性能几乎不变 · 依赖例行维护与安全扫描——npm audit 0 漏洞；Rust 36 个小版本更新，OSV/RustSec 无影响 Windows 产物的漏洞。

### v0.6.0 (2026-08-25)

**新增**：设置「外观定制」——主题色（预设色板 + 色相滑杆，深/浅主题分别适配）、面板透明度、背景图（铺满整窗，侧边栏 / 顶栏自动降为轻纱玻璃透出背景，光晕同步压低），即时生效、一键还原 · 自动切换规则「同时切换主供应商」开关——触发切换时同步 ⭐ 主供应商标记，总览 / 悬浮球 / 托盘的配额展示跟随，手动「测试」同样生效。

**变更**：构建提速——`crate-type` 仅保留 rlib（去掉 Tauri 移动端遗留的全量产物）、MSVC 目标改用 rust-lld 链接器，全量重建与磁盘占用更低。

**修复**：升级后「开机自启动」失效——升级流程先静默跑旧版卸载器，非更新模式会顺手删掉 HKCU Run 自启注册项且新版不补注册。现在升级路径始终以更新模式执行旧卸载器（保留自启项与快捷方式），应用启动时按偏好自愈（注册项丢失重新注册、指向旧安装路径时刷新）。

### v0.5.1 (2026-08-24)

**变更**：「应用美化」改为 app.asar 原地补丁，不再整包解包/重打包——只更新被触及的条目、原字节顺序照抄，284MB 的包实测从数十秒降到约 2 秒，关闭 ZCode 的停机窗口同步缩短。

**修复**：ZCode 升级后美化备份过期的问题——重新应用时不会备份新版本官方包，「还原」会把旧版本 asar 覆盖到新版本安装上（主程序与渲染层错配，可能损坏 ZCode）。现在备份感知版本：升级后首次应用自动用官方包重建；版本不一致时拒绝还原并说明原因；美化状态同步显示备份所属版本，不一致时黄字提醒并按情形给出指引。

### v0.5.0 (2026-08-21)

**新增**：「登录 Token」新增手动输入入口（≥8 字符，与自动捕获同一 keyring 通道）· 用量模板对齐 cc-switch：四桶口径（主桶 / 每5小时 / 每周）+ 双环展示；新增「配额单位 %」· 新增 智谱国际 / MiniMax 国际 / Qwen Token Plan 三组内置预设 · Token 提取支持 `cookie:*` 完整 cookie 串（Windows 含 HttpOnly）· 启动引导主供应商（智谱 Coding Plan → 第一个用户供应商），全新环境不再因「无主供应商」报错刷屏。

**变更**：OpenRouter 目录新增输出长度字段 `max_completion_tokens`（缺省 131072 兜底），导出 cc-switch/opencode 不再因 limit.output 缺失失败。

**修复**：供应商卡片「剩 0% 却判可用」（改用 Math.round 取整口径统一显示/可用判定）· 重置时间优先展示已耗尽桶（耗尽时月→周→5h）· 美化主题补全 panel / sidebar / header / input 四个 token（侧栏与输入栏不再留浅色）· 毛玻璃与背景图在界面挂载后真正可见——三层修复（运行时 JS 补丁穿透 Tailwind 字面量色值 + 表面 token 补全 + 混色源改用主题基色），新增 `zcode-custom.js` 给最大 ≤6 个大面块加真实 backdrop-filter 磨砂 · cc-switch 同步后 opencode「Configuration is invalid」（reasoning 改 boolean、limit.output 缺省兜底）。

### v0.4.1 (2026-08-20)

**修复**：应用内更新启动安装器 os error 740（perMachine 安装包改用 ShellExecuteW("runas") 提权启动，弹 UAC 确认）· 「覆盖启动」生产版不生效（避开单实例锁竞态，cmd 延迟代理启动）。

### v0.4.0 (2026-08-20)

**新增**：同步到 cc-switch（zcode 供应商统一写入其 opencode 供应商组，覆盖/新增 + 自动备份）· 导入配置「重新获取上下文」开关（目录匹配真实上下文，未命中弹窗确认，仅当次生效）· 设置「开机自启动」开关。

**变更**：应用图标重设计（Z 字母标识）· NSIS 安装包改造（静默升级 + /REBOOTOK）· ⚡ 检测改为「配置验证」口径 · 配额百分比统一取整 · 「模型用量展示方案」升级为全局口径（总览/供应商管理跟随）并独立设置分区。

**修复**：火山方舟 AccessKey 额度查询报错含糊（解析错误信封 + 鉴权引导）· dev 模式「覆盖启动」弄断 tauri dev 会话 · 用量统计与 zcode 对不上（同步对账回收已删记录）· 模型拖拽排序在 zcode 内不生效（补写 zcode.priority / modified）。

### v0.3.0 (2026-08-18)

**新增**：模型拖拽排序（供应商详情 ⠿ 手柄）· 主供应商快捷切换（列表右侧 ⭐ 按钮，详情弹窗复选框移除）· Token 获取展示最终捕获内容（默认掩码，点「显示」可复制）· 模型真实上下文长度（每日拉取 OpenRouter 目录，模糊匹配兜底，优先于内置写死规格）。

**修复**：火山方舟 AccessKey / 智谱团队版组织 ID 保存体验（「使用模板」不再清空附加凭据，凭据框独立「保存」按钮 + 提示）· Token 获取支持 HttpOnly cookie（Windows WebView2 CookieManager 轮询兜底，可读阿里系 SSO 等 HttpOnly 票据）。

### v0.2.0 (2026-08-18)

**新增**：月度额度查询 · 项目 / 会话管理 · Token Plan 6 家供应商自动额度查询 · 供应商预设 · 应用内「关于」弹窗 · 单实例启动 · 全局 Toast 通知 · 立即检测供应商连接。

**变更**：自动切换改为直写 zcode 会话模型选择记录（修复「未实际切到所选模型」的回归）· ZCode 主题换肤（asar 自实现解 / 重打包，保留 `unpacked` 标记）· 供应商 UUID 别名解析（用量页等显示真名）· 模型管理 / 自动切换页面改版 · 悬浮球面板交互优化 · 用量页文案与口径微调 · Umami 事件名加 `app` 前缀，与 myshell 区分。