# ai-relay **Repository Path**: rachpt/ai-relay ## Basic Information - **Project Name**: ai-relay - **Description**: Windows 原生 AI Provider 流量转发工具，**Rust + Win32**，支持托盘、单实例、流式代理和本地用量分析。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-18 - **Last Updated**: 2026-10-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # AI Relay Windows 原生 AI Provider 流量转发工具，**Rust + Win32**，支持托盘、单实例、流式代理和本地用量分析。 > 当前为功能开发预览，不是全部验收完成的正式版本。未完成项目与验证限制见 [STATUS](docs/development/STATUS.md)。旧 JS/CMD/PowerShell 参考实现及其日志/PID 已按用户授权移除，不属于公开仓库或原生版发布包。 ## 运行 - 开发构建：`cargo run`。 - 日期版本：`2026.10.18`，Git 标签 `v2026.10.18`；同日后续构建可用发布脚本的 `-BuildLabel` 区分。 - Release：`target/release/ai-relay.exe`；静态 CRT 打包使用 `target/x86_64-pc-windows-msvc/release/ai-relay.exe`。 - 静态 CRT 便携预览包：`dist/ai-relay-2026.10.18-windows-x64-preview.zip`（构建后生成）。 - 普通双击不创建控制台；关闭主窗口隐藏至托盘，双击托盘恢复。再次启动唤醒同一用户会话的原实例。 - 客户端顶部左侧 **☰** 打开“文件／代理／视图／帮助”；支持 F10、Alt+M，Alt+Space 保留系统菜单。文件菜单可打开数据目录、导入/导出配置及退出，代理菜单沿用原有启停规则；弹出菜单使用系统样式，不额外占一行高度。 - 默认窗口800×680 DIP，最小800×560 DIP（受显示器工作区限制）；顶部导航和底部状态栏固定，页面内容可滚动，各页独立保留位置。Tab聚焦到屏外控件时自动滚动揭示，不丢未保存输入。 ### 首次设置 在“设置”页填写上游 URL、监听 IP/端口、Key 与注入策略，选择软件目录或 Windows LocalAppData。 - **保存并应用**：保存后启动，运行中受控重启；失败显示真实状态，可明确确认回滚上一配置。 - **启动已保存配置**：只使用已保存设置，不使用界面草稿。 - 默认仅回环；GUI 非回环监听每次单独确认，CLI/自动启动不复用授权。 - 默认 DPAPI 当前用户保护，密文与配置一起原子保存。不能保证跨用户/跨机器解密；明文便携需确认风险，备份同样敏感。 - 登录自启是当前用户登录后运行，不是服务；在设置中显式启用/关闭，显示系统实际状态。测试未修改真实 Startup。 - 迁移需先停止代理，预览并确认。复制配置及一致历史快照，保留源数据，日志不迁移；目标已有历史时拒绝自动合并。可识别的已启用自启同步更新。 - 支持脱敏配置导出、导入预览、备份恢复；不覆盖预览后外部改变的配置。 ## 四个页面 顶部四个原生 Tab 使用统一的 SVG 派生线性图标，支持浅深主题着色；图标随 EXE 内嵌，不需要 SVG 或浏览器运行时，高对比度使用原生文字回退。输入框保留完整的原生矩形边框，按钮、闭合下拉与日期框保留小圆角。 底部共用固定贴底的40 DIP单行状态栏：显示状态、当前操作和说明。长文字省略显示，原始完整内容仍保留；原生悬停提示已接入，但自动悬停显示尚待稳定性验收。 ### 概览 顶部显示监听、上游、Base URL 和会话时长，提供一排启停、重启、复制 URL、打开目录操作。数据目录初始化完成且后台空闲后可打开，结果在状态栏显示；系统接受请求不等于资源管理器窗口一定显示。四张大号卡片展示累计请求、错误次数、活动请求（含隧道/入站提示）和下载/上传累计。 两张大趋势图展示请求/错误速率及上传/下载速率，约每秒采样，最多保存最近120秒/120点；首次采样等待建立基线，超过5秒的缺口或计数饱和保持未知，不补造曲线。趋势只属当前程序会话、不跨重启持久化；切页继续采样但不重绘，窗口较矮时降级精确文字指标。 会话计数跨代理启停保留，时长包含停止时间；错误次数不是成功率，HTTP 流量不含头/分帧、不是线速或账单。 ### 统计分析 历史 SQLite 数据跨重启保留，与当前程序会话 usage 分开： - IP、请求/响应模型、UTC或本地日期范围、客户端与实际发送的上游凭据 ID、实际目标 origin、协议、接口、状态与结果组合筛选。 - 最多三级分组、原生明细/汇总表格；按时间、请求数或 Token 排序，未知值单独保留。小时/日/月趋势按所选时区的历史规则分桶，处理夏令时，不使用当前偏移冒充历史时区。高级筛选可收起且保留条件。 - 历史/会话、日期快捷项、UTC/本地、日/小时/月、结果视图和导出范围使用一键分段选择；只有“自定义”显示两个原生日期选择器，可弹出月历或键盘选日；左侧复选框取消勾选表示该侧不设边界。开始日包含、结束日不包含，按所选时区解释。已有查询结果时，切换时区/粒度自动后台重查。 - 浅色为白底蓝色强调；深色统一表格/表头和下拉箭头，系统滚动条仍可能保留系统外观。日期控件聚焦编辑与弹出月历保留 Windows 原生样式，暗色下也可能是浅色，以确保日期布局及键盘选日可靠。布尔选项显示为开关，保留原有确认与保存规则。当前完整集成验证见 STATUS。 - 输入/输出/总量、缓存/推理，以及未知、部分、截断、错误、队列丢失等覆盖状态。 - 图表摘要和数值标签自动使用十进制 K/M（1K=1,000、1M=1,000,000），最多两位小数、去末尾零；省略精度时标 `≈`。明细和 CSV 保留精确整数，未知不补零。 - 凭据用本地 HMAC-SHA256 ID，不保存原始 Key；完整64位ID可直接筛选，不接受Key片段。 - CSV 可选择当前明细页或筛选后**全部记录**；全量使用同一数据库快照逐行写出，默认移除 IP 和凭据 ID，保留别名及完整用量/覆盖字段；包含别名的导出仍应妥善保护。 - “凭据/存储”可管理凭据别名、查看数据库占用，确认调整保留期/条数或预览清空。默认90天/10万条，可设1–90天和1–10万条，先到先清理；清空默认保留身份和别名。策略独立保存，不重启代理。 支持 OpenAI Chat/Responses 与 Anthropic JSON/SSE usage；不修改请求强制索取用量。未知不是0，不保存正文，不以统计冒充账单。请求模型仅在无压缩且完整合法JSON上传不超过64KiB时被动提取；超限、取消、重复字段或格式不支持时保持未知，不从响应猜测。查询/全量导出运行于独立只读worker，不占写入worker；10万条高基数报表仍可能耗时十余秒，界面显示查询中。 ### 实时日志 实时/文件视图均支持原生日期picker的UTC日期范围（起止均含整日，取消勾选某侧表示不限）、类别分段、状态码/区间、仅错误、文本与级别的AND组合筛选；暂停时冻结显示窗口，后台仍记录。支持清空视图、文件尾读、向前分页、自动跟随。文件替换/截断/缺失会停止跟随并提示重新读取。 日志目录为所选数据目录的 `logs`，JSONL，支持文件/访问日志开关、轮转、保留数量/天数及缓存限制。应用日志设置即时生效，正常保存配置后持久化。 清空视图不删文件；清理先预览确认，全部清理二次确认，部分失败逐项报告。不删除配置、历史数据库或旧版日志。未知路径脱敏，不记录Key、正文或查询参数。 ### 设置 六个分类通过常驻分段导航一键切换：上游与监听、访问控制、正向代理/CONNECT/CORS、网络限制、启动/存储/配置、外观/日志；保存等操作紧跟当前分类内容，不再留大段空白。可设置关闭到托盘或退出、记忆窗口位置/大小/最大化；偏好保存在所选目录的window.json，后台原子保存，显示器移除后校正到工作区。浅色、深色、跟随系统以分段选择直接预览，默认跟随；高对比度优先系统配色。日志/表格/页面原生滚动条已提供暗色覆绘，不改变原生滚动行为；系统菜单、弹出控件和拖动动画仍可能保留系统外观。 ## 协议与安全 HTTP/HTTPS 反向代理及流式 SSE；可选 HTTP 正向代理、CONNECT 和 CORS。关闭正向改写时仅可信 origin 注入上游 Key；CONNECT 是不解密的 TCP 隧道。支持独立客户端令牌、IP/CIDR 白名单、超时、并发上限和取消。 不关闭 TLS 校验，不跟随上游重定向，不自动重试可能发出的 POST；不自动修改系统代理或防火墙。 ## 命令行 ```text ai-relay.exe [--background] [--config-dir <绝对目录>] ai-relay.exe start|restart|status|stop|show|quit ai-relay.exe --help ai-relay.exe --version ``` 无主实例时 start/restart 创建后台实例，限时等待真实监听。退出码：0成功、1未运行/监听、2参数/配置错误、3操作或IPC失败。quit回执仅表示已接受优雅退出。 ## 开发与验证 Windows x64，当前验证 Rust/Cargo 1.99.1 MSVC，需要 C++ Build Tools、Windows SDK、rustfmt、Clippy。最低Rust/Windows构建号尚待完整验证。 ```text cargo fmt --check cargo check --all-targets --locked cargo test --locked cargo clippy --all-targets --locked -- -D warnings cargo build --release --locked ``` Windows PowerShell 冒烟使用临时目录、本地mock和虚构凭据，不产生模型费用： ```powershell .\tools\smoke-proxy-ui.ps1 .\tools\smoke-history-ui.ps1 .\tools\smoke-settings-ui.ps1 .\tools\smoke-logs-ui.ps1 -RequireAccessLog .\tools\smoke-theme-ui.ps1 .\tools\smoke-cli.ps1 .\tools\smoke-window-ui.ps1 .\tools\smoke-modern-ui.ps1 -ExePath .\target\debug\ai-relay.exe .\tools\smoke-ui-regressions.ps1 -ValidateOnly .\tools\smoke-ui-regressions.ps1 -ExePath .\target\debug\ai-relay.exe .\tools\package.ps1 ``` 应用图标源为 `assets/ai-relay.svg`，`tools/generate-icon.ps1` 生成 ICO。导航图标源在 `assets/navigation/`；`tools/generate-navigation-icons.ps1 -ValidateOnly -SelfTest` 复核已提交遮罩，去掉 `-ValidateOnly` 离线重建。该脚本只支持受限 SVG 子集，不是任意 SVG 渲染器；正常构建和运行不需要执行脚本，详见 [导航资源说明](assets/navigation/README.md)。打包仅纳入白名单文件，不包含旧脚本、配置、密钥、日志或数据库；静态CRT+PE导入检查不能代替干净系统、签名和许可证验收。 ## GitHub 公开前检查 - 全部历史提交作者/提交者统一为 `rachpt `；本地身份配置一致。历史重写改变提交哈希，旧克隆不要合并回新历史。 - 旧参考脚本、真实配置/密钥、日志、PID、`target/` 与 `dist/` 不纳入源码发布；`.gitignore` 不等于历史清洗。扫描方法和边界见 [开发指南](docs/DEVELOPMENT.md#公开前的历史检查)。 - 项目采用 [MIT 许可证](LICENSE)，Cargo 元数据与发布脚本已同步；[第三方声明](THIRD-PARTY-NOTICES.txt) 收集当前 Windows 构建依赖的原始许可/版权文本并随包附带，不因项目使用 MIT 而改变其条款，也不代替完整法律/工具链许可审核。 - 历史扫描无法证明绝对无泄露。旧部署使用过的 Key 建议轮换；不要把仓库外恢复备份、旧克隆或未审查的预览产物上传到 GitHub。 ## 许可证 本项目采用 [MIT License](LICENSE)，Copyright (c) 2026 rachpt。复制或分发软件的全部或重要部分时，须保留版权及许可声明；软件按原样提供，不作担保。第三方组件仍遵循各自许可证，见 [THIRD-PARTY-NOTICES.txt](THIRD-PARTY-NOTICES.txt)。维护依赖后通过 `python tools/generate-third-party-notices.py --cargo --check` 复核，未安装开发工具的最终用户无需执行。 ## 文档 [需求](REQUIREMENTS.md) · [约束](AGENTS.md) · [导航](docs/README.md) · [状态](docs/development/STATUS.md) · [架构](docs/ARCHITECTURE.md) · [开发指南](docs/DEVELOPMENT.md) · [便携说明](docs/PORTABLE.md)