小克

Linux / 服务器没有图形界面，也是一行装完：

curl -fsSL https://aikaui.com/install.sh | sh

---

为什么做这个

装 Claude Code 本可以五分钟结束，但国内用户实际要过这几关：装 Node（MSI 安装包还经常 以 1603 失败）、npm 全局目录不在 PATH 里、地区限制、中转地址写在哪、VSCode 插件、 第一次启动该用哪个工作目录……每一步都能卡住一个不太折腾电脑的人。

小克把这件事交给一个会自己看环境、会调工具的 Agent：它检测、它下载、它写配置、它问你 「以后在哪个文件夹里干活」，装完把 VSCode 或终端打开。每一步都用大白话解释一句，要装东西 之前先问过你，装到一半不耐烦了可以点「中断」。

它同时是个能聊的助手：查余额、看用量图表、扫码充值，都在同一个窗口里。窗口左边一条导航栏， 右边三个页面：💬 对话、📊 用量信息 和 🔐 账户信息。

为什么可以放心装

• 客户端代码全在这里 —— 它怎么找到 claude、怎么写 settings.json、凭证存在哪， 都能在仓库里读到，没有藏在安装包里的黑盒步骤。
• 凭证只落在你自己机器上：注册拿到的 api_key 存本机（Windows 走 DPAPI，POSIX 是 0600 文件），本机密钥和设备指纹一起做「同一台机器找回同一个号」的双验证。
• 841 个离线单元测试，不联网、不需要图形界面就能跑。
• 不做托盘、不留后台：关窗口就是退出程序。

功能

装 Claude Code（一键完成）

底部一个「一键安装 Claude Code」按钮，或者直接说"帮我装 Claude Code"。Agent 按固定顺序 调前四个工具：领 token → 绕过地区限制 → 写配置 → 建桌面快捷方式，然后问清楚工作目录， 最后二选一收尾：装好 Claude 的 VSCode 插件并用 VSCode 打开（默认），或者开一个新终端。 中途每一步都会用大白话跟你解释一句，要装东西之前会先问过你。

装到一半不耐烦了可以点「中断」（2026-10-31 加）

装 winget 要下 58MB、走官方安装包那条路要下 240MB，几分钟很正常。输入框右边有一个 「中断」按钮，平时是灰的，Agent 一开工就亮起来。点了会同时做三件事：

1. 立一块「中断」牌子（agent_bus.cancel_event）—— Agent 循环每走一步、每个下载循环 每 1MB 都会看一眼，看见就停；
2. 掐掉正在跑的子进程（kill_active_children()，Windows 上 taskkill /F /T）， 不然 winget / powershell / 安装包能自顾自跑几分钟，按钮就成了摆设；
3. 如果 Agent 正卡在问你问题那一步，把等待叫醒，别让线程一直挂着。

已经装到一半的东西不会回滚，点完的提示里也这么写。下一轮任务开工时牌子会自动摘掉 （agent_worker / 服务器版每轮调 clear_cancel()）。服务器版对应的是连按两次 Ctrl-C （第一次只是「上膛」），同一个牌子、同一套收尾。

装完不自动关窗口（2026-10-31）。以前安装流程走完会留 10 秒，然后助手自己退出； 用户明确说不要 —— 装完正是最想回头问两句的时候（"这个面板怎么用""项目放哪"）， 助手自己关掉最招人烦。install_done 这个事件还在（它仍然是"这一轮真把用户领进门了" 的唯一判据），只是界面拿到它什么都不做。关窗口只有两个办法：点右上角 X，或直接说再见。 顺带的好处：助手常驻之后，PyInstaller 报的 Failed to remove temporary directory: …\_MEI… 也不会再被"自己先退出、VSCode 还占着目录"触发。

先定工作目录，再启动

Claude Code 只看得到你给它的一个文件夹。所以启动之前 Agent 必须先问清楚"以后在哪个 文件夹里干活"（ask_user 给三个选项：桌面新建一个 / 用户主目录 / 自己指定路径）， 再把这个目录传给 open_vscode(directory=…) / launch_claude(directory=…) 当 cwd。目录不存在会建出来，越界（跑到 用户主目录外面）会被退回主目录并在日志里说明原因 —— 跟 read_file / write_file 是同一条规则。

启动完还会把这件事再讲一遍：一个项目一个文件夹，换项目就在 VSCode 里打开那个文件夹（或在那个文件夹里重新启动）。

装完接到 VSCode：检测 → 问 → 装 / 装插件 → 打开

装完 Claude Code、定好工作目录之后，Agent 先 check_vscode() 拿事实，再按情况只问一次：

情况	问什么	同意之后
没有 VSCode	先讲一句好处（改了什么在编辑器里直接看到、能一键撤销），问要不要装	install_vscode() → install_claude_extension() → open_vscode()
有 VSCode 没插件	问要不要装 Claude 插件	install_claude_extension() → open_vscode()
都有	不问	直接 open_vscode()

用户说"不用"，就退回 launch_claude() 开终端，之后任何一轮都不再提 VSCode。 两个入口只能开一个，绝不都开。

打开 VSCode 时关掉「工作区信任」门禁（2026-10-31）。助手是替用户新建的目录， VSCode 一定把它当成"未信任"，先弹一个「Do you trust the authors of the files in this folder? … Creating a terminal process requires executing code」。在用户点「信任」之前， 扩展跑在受限模式里：Claude 面板出不来、连终端都开不了 —— 用户看到的现象是"插件装了却没开"。 所以 open_vscode() 一律带 --disable-workspace-trust（VSCODE_NO_TRUST_FLAG）： 只对这一次打开的那个窗口生效，不改任何全局设置，用户之后自己打开别的文件夹照样会被问。 带开关就得走 CLI（直接起 Code.exe 时参数会被转手给已运行的实例，开关不生效）。

装 VSCode 本身：Windows 走 winget --scope user（不弹 UAC），macOS 走 brew install --cask， Linux 只打开官网下载页（apt/snap 要 sudo，助手不替你提权）。装不上就打开下载页并如实说明； 插件市场连不上也一样，照样用 VSCode 打开，让用户在扩展面板里手动装。

机器上没有 winget 时先把它装上（ensure_winget()，2026-10-30 加）。原因很实在： Windows 10/11 的家庭版精简镜像、老 LTSC、服务器版都可能不带 App Installer， 走到 install_vscode() 就直接死在「这台机器上没有 winget」，用户被卡在装到一半。

• 包是我们自己 CDN 上的微软官方 App Installer（x64 那个 msix，58MB，sha256 钉在 platform_support/windows.py 里）。不走 GitHub：2026-10-30 实测国内直连 objects.githubusercontent.com 是 0 字节，而 winget 的 msixbundle 有 200MB+。 这里只取 bundle 里 x64 的那一份，内容与微软发布的完全一致，没有做任何改动。
• 先装依赖框架包再装主包（2026-10-31 加）：App Installer 依赖 Microsoft.UI.Xaml.2.8 和 Microsoft.VCLibs.140.00.UWPDesktop，微软把它们单独放在 DesktopAppInstaller_Dependencies.zip 里。漏了这一步，主包可能装不上。 两个包（6.7MB + 5.1MB，sha256 钉在 WINGET_DEPS 里）下到 %TEMP%\aikaui-winget-deps\，大小和 sha256 都对得上就复用、不再走网络。 依赖装不上不直接放弃（机器上可能本来就有），主包照样试；两个都失败才报两句。 Add-AppxPackage 的 0x80073D06 / 0x80073CFB / 0x80073D02（更高版本已装 / 同版本 已装 / 资源包已注册）都算成功 —— 重装依赖时天天撞见，不认它就是误报。
• Add-AppxPackage 的参数名只能是 -Path（2026-10-31 查清，这是那个老 bug 的真正原因）。 它没有 -LiteralPath；写上它 PowerShell 当场抛 ParameterBindingException / NamedParameterNotFound, Microsoft.Windows.Appx.PackageManager.Commands.AddAppxPackageCommand，整条命令一句都没执行。 表现就是用户日志里的「Add-AppxPackage 返回 1」，然后一路退到 240MB 的官方安装包 —— 走得通，但慢得多。-Path 认通配符，所以路径里真带 [ ] ` 时会先 Set-Location -LiteralPath <目录> 再只传文件名。
• 失败时要留下能看的错误（2026-10-31 重写）。原来是「取最后三行」—— 取到的正好 是 PowerShell 的 + ~~~~ 位置标记，真正有信息的第一行 Deployment failed with HRESULT: 0x8007… 反被丢了；而且硬按 UTF-8 解码， 中文路径 张三 在用户日志里变成 ????（中文 Windows 的 PowerShell 写 GBK）。 现在 _summarize_powershell_error()：先去掉纯装饰行，保留第一行，再补一条带 0x8… 的、一条 CategoryInfo、一条 FullyQualifiedErrorId；解码走 smart_decode()（UTF-8 → 本地编码）。
• 失败后隔 2 秒再试一次，第二次把 msix 复制到 %PUBLIC%\aikaui\（纯 ASCII 路径） 再装 —— AppX 部署对非 ASCII 路径有过 IO 报错，ASCII 副本是绕开它的最省事办法。 _ascii_copy() 只在原路径含非 ASCII 时才做，装完（无论成败）删掉副本。 两次都失败就报两段的错误。
• 先 Add-AppxPackage（用户级、不弹 UAC、不改系统策略）；装不上就认。 2026-10-31 删掉了「解压便携版」那条路：便携版没注册成 AppX 包，源索引永远打不开， winget install 必然 0x8A15004B。以前这里会解压一份、打一行「已装好 winget （便携版，解压即用）」，下一句紧接着就是「读不到软件源，改用官方安装包」—— 白等十几秒，日志还自相矛盾。现在直接返回失败原因，install_vscode() 跳第 3 条。
• 装不上时把那个老版本的名字说出来（2026-10-31）。Get-AppxPackage Microsoft.DesktopAppInstaller 可能注册着，但版本是 1.0.30251.0 —— winget 出现之前的那版，包里根本没有 winget.exe（winget 要 1.11 以上才带）。 这时候日志里会多一句「太老…在 Microsoft Store「库 → 获取更新」里升级它能一劳永逸」， 而不是只有一句看不懂的「装不上」。这是用户真机上撞到的情形。

winget 装上了不等于能用（2026-10-30 第二个坑）。刚装好的 winget 没有源索引， winget install 会当场返回 0x8A15004B（SourceOpenFailedSuggestion）—— 用户在真机上撞到的就是这个：包下完了、winget 也装上了，然后报 winget 返回 2316632139。所以 install_vscode() 现在是三条路依次试：

1. winget install。失败时只有看着像源的问题（SourceOpenFailed / source）才 winget source update，不行再 source reset --force + update，然后重试一次。 超时之类的失败不重试 —— 那等于把上限翻倍。
2. 没有 winget 就先 ensure_winget() 装上（上面那 58MB），再走第 1 条。 ensure_winget() 失败（Add-AppxPackage 两次都没成）就直接跳第 3 条 —— 不再解压便携版，理由见上。
3. 都不通就绕开 winget：直接下微软官方的用户级安装包 （update.code.visualstudio.com/latest/win32-x64-user/stable，约 240MB）， /VERYSILENT /MERGETASKS=!runcode 静默装，退出码 3010（要求重启）也算成功。 这条和下载页给用户的是同一个文件，签名也是微软的。 下载走 6 路分段（2026-10-31 加，见下），240MB 从 9 分钟变一分半。

三条都不行才打开下载页，并把每一步卡在哪如实说出来（on_note 会往对话里打行）。

240MB 那个安装包用 6 路并发下（_download_parallel()，2026-10-31 加）。 起因是用户的原话「直接下载微软官方的安装包花的时间太久了」：微软那个 CDN 单条连接 只有 ~450KB/s，240MB 要 9 分钟。先问一次 update.code.visualstudio.com/api/update/win32-x64-user/stable/latest（几百字节的 JSON） 拿到带版本号的真实地址和 sha256hash，再用 Range 把它切成 6 段并发下。 本机实测 2.64MB/s、90.9 秒下完 251,590,472 字节、sha256 对得上（快 6 倍）。 分段拿不到（代理拦了 Range、服务器不支持）就退回单连接那条老路 —— 慢，但通； 退回去之后仍然按 API 给的 sha256 校验，因为"某一段少了一截"的文件头照样是 MZ。 用户点中断时不会偷偷再下一遍。

find_winget(verify=True) 的顺序是 PATH → 执行别名 → 最后问一次 AppX 注册表， 前面那几个候选手到之后都会真跑一次 --version：WindowsApps 下的执行别名可能是空壳 （文件在、包没为这个用户装，Popen 直接 WinError 3），不验就会拿一个跑不起来的路径去装东西。 便携版那条候选删掉了（2026-10-31）：老的解压目录就算还在，拿它装东西也必然失败。

最后那道 _winget_from_appx_registration()（2026-10-31 加）是不再靠猜路径的兜底： 问系统 (Get-AppxPackage Microsoft.DesktopAppInstaller).InstallLocation 拿到包真正装在哪， 再用那里的 winget.exe。加它的原因很实在 —— 用户机器上 winget 明明是好的 （Get-AppxPackage 报 1.29.380 / Ok，别名跑 --version 回 v1.29.380），我们却判定 「没有 winget」，于是白下 58MB、白装一遍（还失败）、再白下 240MB。上面那些候选全靠猜： PATH 最前面那条 WindowsApps 可能属于另一个账户（本机就是，Administrator 的空壳）， %USERPROFILE% 也可能不是你以为的那个目录（本机 USERNAME 是中文名，profile 却是 C:\Users\abc）。问 AppX 注册表则没有「猜」这回事。

open_vscode() 不只是开窗：它把 Claude 面板也一起打开。VSCode 命令行没有 --command 这种东西，所以走的是插件自己注册的 URI 入口 vscode://anthropic.claude-code/open （插件 extension.js 里的 registerUriHandler 接到它就执行 claude-vscode.primaryEditor.open）。 两个细节：① 只在 --list-extensions 里确认插件存在时才发链接 —— 否则 VSCode 会弹一个 "无法打开链接"的报错框；② 本流程刚装完插件会先开一个新窗口（已开着的窗口是在装插件 之前加载扩展的，里面没有它），等 4 秒让插件宿主注册好 URI 处理器再发。 面板没能自动打开时，返回里会写清楚，让用户点左边活动栏的 Claude 图标 —— 不会假装成功。

检测不依赖 PATH：Windows 先查注册表（App Paths → Applications\Code.exe → vscode 协议）， 再查常见目录，最后才是 which。这样装在 D:\vs code 这种非默认位置也找得到。 CLI 一律用安装目录里的 bin\code.cmd（Code.exe --list-extensions 是空输出）， Code.exe 只用来开窗；所有 VSCode 子进程都先过 clean_env() 摘掉 ELECTRON_RUN_AS_NODE / VSCODE_*（带着它们 Code.exe <目录> 会当 node 脚本跑完就退， 不报错也不弹窗）。

对话式的「小克」

不装东西的时候它就是个普通助手，问它什么都行。系统提示词里写死了：用户只是在打招呼或 提问时，不要自作主张去装东西。

📊 用量信息页

跟钱有关的东西只有这一页：余额（大数字，低于 ¥2 变橙、低于 ¥1 变红）、今日/本月消耗、 两张按时间分布的 token 用量柱状图（上 flash、下 pro）、右上角的「充值」按钮。数据每 30 秒 自动刷一次，这一页也有「刷新」按钮。

两张图各画在 tk.Canvas 上，上下叠着：今日按小时、本月按天（服务端按北京时间分桶）， 单色（刻度写在轴线下面，颜色不承担区分职责，也就不需要图例）、柱顶直接标数值、 鼠标悬停出提示框。时间桶多时只每隔几个画一个刻度（从最后一根往回数，保证当前小时 / 今天一定有标签）。卡片标题就是模型名，右上角写这一期间的合计，所以不靠悬停也能 知道每个模型花了多少。模型按名字里的 flash / pro 挑，某个模型当期没用量也留着 那张空图（"暂无数据"），不会两张图变成同一个模型。色板跑过对比度校验 （#3987e5 在卡片底色 #1f1f1f 上 ≥3:1）。

后端 /api/usage 的 today / month 里各带一个 series_by_model （{模型: [按小时 / 按天的序列]}）。两张图吃 series_by_model；老服务端只给 series / by_model 时，客户端会退化成每个模型一根总量柱子，并注明 "服务器暂未按模型拆分时间"，不会白屏 —— 详见下面「服务端接口」一节。

余额不足时点服务器给的 aikaui://recharge 链接，助手先显示这一页（让人看清钱花在 哪了），数据回来后再自动弹充值窗；充值窗停在主窗右边，不把图表整个盖住。

余额卡下面那行账户码只露前 4 位（完整凭证在「🔐 账户信息」页）：这一页是用户最容易 截图发给别人的地方。

🔐 账户信息页

账户码和账户密钥在这里，默认打码（CC-D************ / ************************）。 每行有「👁 显示」按钮，点一下才看明文；再点变回打码，切走再回来也是打码 —— 明文状态 不做任何持久化。旁边是「复制」，只写系统剪贴板，不写日志（日志是用户会截图的地方）。

两串的分工：账户码"找到哪个账号"，账户密钥"证明这个账号是你的"。换设备登录要两样 一起填（见下面「换设备登录要两样」）。

下面一行红字是这一页存在的理由：

⚠️ 重要：这是您找回账户和余额的唯一凭证，请截图保存在安全的地方。切勿发给他人，否则余额将被盗用。

打码只是"别被路过的人一眼看走"，不是加密：明文就躺在本地凭证里。所以那句警告是必需品， 不是装饰。

余额见底只问一句，不主动弹充值页

余额跌破 ¥1 时，程序不会自己打开充值窗口，只在窗口底部冒一条暗琥珀色的 "⚠️ 余额只剩 ¥x.xx，是否立即充值？"（服务器真的说"余额已用完"时同理）。点「立即充值」 才弹充值窗，点「暂不」就收起来，并提示"需要充值随时点左边「用量信息」→「充值」"。 一次会话只问一次（服务器明确报余额用完时那次除外）。

402 有两种，不能混成一句「余额已用完」

new-api 在请求开始前按「上下文 + max_tokens」做预扣费估算，估算值超过剩余额度就拒绝， 不等实际生成完再算。所以一次很大的请求（图片、长文件、大 max_tokens）完全可能被拒， 而余额还有几毛钱 —— 2026-10-28 就因此让用户充了不必要充的钱。两种情况的处置完全不同：

服务器回的 code	真实含义	界面怎么说	要不要劝充值
insufficient_user_quota	余额真的没了	「账户余额已用完」	要
quota_exceeded_for_request	余额还在，这次请求的预估花费超了	「这次请求的预估花费超过了剩余余额（还剩 ¥0.75）」	不要，先让他把请求改小

llm.insufficient_balance() 返回 {"kind", "text", "remaining"}，agent_core 只对 kind == "empty" 发 ("recharge", …) 事件。代理还会把真实剩余额度放在 remaining （单位：元）里 —— 只要它大于 0，就算 code 还是老的那几个，也按第二种处理。 老代理只发一句中文、没有这些字段，那就按第一种走（和 v1.4.8 以前行为一致）， 所以两边谁先上线都不会坏。

ask_user 选项交互

Agent 需要你拿主意时，不是把 "1. xxx 2. xxx" 打在日志里，而是渲染成可点的选项行： 点一下就直接当答案提交（没有"先选、再点确定"那一步），也可以 ↑↓ 移动选中、回车提交， 或者直接打序号。Esc 跳到自由输入。最后一行永远是「✏️ 输入点别的」。

关闭窗口 = 退出程序

三个平台都不做托盘。点右上角 X 就是真的退出，不会留一个找不到的常驻进程。 （以前 Windows 上"关窗缩到托盘"的行为已删除。）

字体是一处定义的

界面字体按平台挑：Windows 用 Microsoft YaHei UI（设置面板用的那一款，比普通雅黑字距更紧）、 macOS 用 PingFang SC、Linux 用 Noto Sans CJK SC；数字和订单号走等宽， 这样 token 数、金额、日志列与列之间是对齐的。字体是运行时按优先级问 Tk 要的， 一个都找不到才退到系统兜底字体。字号全在 ui/fonts.py 一张表里，改一处整个界面跟着变。

快速开始

需要 Python 3（开发环境用的是 3.12.4），Windows / macOS / Linux 都行。

pip install -r requirements.txt
python main.py

首次运行会自动注册一个账号（服务器要求做一次 PoW 人机校验，通常一两秒）， 凭证存到 ~/.claude-agent/identity.json。之后每次启动都直接用这份本地凭证，不再联网注册。

离线测试（不需要联网，也不需要 GUI）：

python -m unittest discover -s tests

服务器上没有图形界面怎么办？ 用服务器版（见下一节），它不需要 $DISPLAY。

服务器版（Linux，无图形界面）

服务器上没有 X11 / Wayland，python main.py 一进来就 import customtkinter， ctk.CTk() 会直接抛 TclError。所以 Linux 发的是另一份产物：一个纯终端程序。

它和桌面版跑的是同一套 Agent 循环（agent_core.run_one_task），只是把界面换成了 终端对话：装 Node → 装 claude → 领账号 → 写配置这几件事由模型来决定顺序、怎么补救、 什么时候该问你，不再是一条写死的流水线。唯一的确定性环节是账号引导——模型客户端 本身就要 identity.json 才能说话，所以那几步由代码问、代码办。

终端里的约定：

• 在干活时不能打字（底部一行转圈 + 已用时），干完了才能打字、回车发送；
• 有选项时高亮整行，↑/↓ 选、回车确认，Esc 跳到「自己打字」；
• Ctrl-C 要按两次：第一次只是「上膛」，2 秒内再按一次才中断。 已经开始的下载/安装不会被杀掉（子进程是独立会话），它会自己在后台跑完；
• 真终端里装完会自动进入 claude；管道/容器里（--yes）不会，只打印怎么启动。

一条命令装好（脚本会自动下 latest.json 里 linux-x64 那一条，校验 sha256，不需要 root）：

curl -fsSL https://aikaui.com/install.sh | sh

装到 ~/.local/lib/claude-code-assistant/，软链成 ~/.local/bin/claude-code-assistant， 并往 ~/.bashrc / ~/.profile 写一段带标记的 PATH（# >>> aikaui >>>，重跑不会重复写）。 装完会跑一次 --version：跑不起来就退 4，不会留下一个"装上了但用不了"的状态。

装完直接启动（模型会一步步做，需要你拿主意的时候它才问）：

claude-code-assistant                 # 首次运行：注册账号 → 写 ~/.claude.json → 提示怎么用
claude-code-assistant --account-code <账户码> --account-key <账户密钥>   # 用已有账号绑这台机器
claude-code-assistant --yes           # 全默认，适合写进 Dockerfile / cloud-init（需要模型可达）
claude-code-assistant --dry-run       # 只打印要做什么，不下载、不写任何文件
claude-code-assistant --repair        # 只对账配置：跟 identity.json 不一致就补齐（见下）
claude-code-assistant --balance       # 查余额和用量
claude-code-assistant --recharge 20   # 充 20 元：在终端里打印付款二维码

参数	作用
--dir PATH	claude 的工作目录，默认 $HOME
--account-code / --account-key	绑已有账号（比在新机器上再注册一个更常见）
--new-account	上次注册没走完、留下了旧账户码时，明确放弃它重新注册
--node-version / --claude-version	钉版本；默认 Node 取 LTS、claude 取 latest
--yes / --force / --quiet	不提问（提问时自动选第一项）/ 已装也重装 / 只输出错误；--yes 现在需要模型可达，见下
--repair	只检查并修复 ~/.claude.json 和 ~/.claude/settings.json，不装 Node、不装 claude、不注册账号
--balance	只查余额和用量（今日 / 本月 token），不装东西
--recharge 金额	创建充值订单并打印二维码；--channel wechat 可指定微信（默认支付宝）
--allow-root	1.4.4 起 root 默认就能装，这个参数只为兼容老脚本保留

--repair / --balance / --recharge 是"只做一件事"的模式，互相不能组合， 也不能和 --account-code / --new-account 一起用（那是安装路径的事）。

余额和充值（服务器版）。没有图形界面，所以付款走终端： server/billing_console.py 把 server/api.py 拿到的数据变成几行字，二维码用 segno 画成方块 —— 黑字白底（深色终端里不这么做，黑白是反的，有些扫码器不认）。画不出来不影响充值： 没装 segno、或者服务器没给二维码内容时，退回打印 pay_url 和二维码图片地址。

余额跌破 ¥1（和桌面版同一条线）时，--balance 和装完最后那屏都会把两条路摆出来：

1. claude-code-assistant --recharge 20 —— 就地充，二维码直接打在终端里；
2. 绑到桌面版扫码 —— 用同一个账户码，余额记在账号上，这台服务器立刻能用 （账户密钥在 ~/.claude-agent/identity.json 的 account_key，只填进桌面版，别外传）。

账户码、金额、订单号可以打；api_key / account_key 的值任何一行都不打印， 提示里只出现 <密钥> 这样的占位符。

它是分两层跑的： 上面这几件"装什么、怎么装"交给模型（工具在 server/agent_tools.py，提示词在 server/prompts_server.py），模型的顺序大概率是这四步； --dry-run 打印的就是这条确定性参考路线（不联网、不调模型，退出码照旧）。

模型能用的 12 个工具：ensure_node / install_claude / configure_claude / finish_install（验收闸门：Node、claude、账号、两份配置都在才算装好）、 bash / read_file / write_file / ask_user、query_balance / query_usage / query_pay_methods / create_recharge。没有 VSCode、快捷方式、aikaui:// 协议、 login_with_account_code —— 账户密钥不进模型的上下文。

bash 有护栏：不许 sudo、不许 apt/dnf/yum/apk/snap install、不许自己 npm install （那几条坑在 install_claude 里已经处理好了，让模型现编就是事故重演）、 不许读写 ~/.claude-agent/（里面有 api_key）；子进程一律 stdin=/dev/null， 否则它会抢走终端的按键，用户看到的是"打字没反应"。

四步的细节（也就是那四个工具的实现在做什么）：

1. 环境自检：不是 Linux、架构不是 x86_64/aarch64、~/.local 不可写，都会在下载任何 东西之前就失败（退出码 3）。root 不拦，只警告一句：东西全落在 /root 下，换个人用不了。
2. Node：node 主版本 ≥ 22 就复用；否则从 cdn.npmmirror.com 下 node-v<ver>-linux-<arch>.tar.xz，对 SHASUMS256.txt 校验，装到 ~/.local/node-v<ver> 再软链成 ~/.local/node。全程不 sudo。
3. claude CLI：npm install -g --prefix ~/.local @anthropic-ai/claude-code --include=optional --allow-scripts=@anthropic-ai/claude-code。 --include=optional 不能省：真二进制在 optionalDependencies 的平台子包里。 --allow-scripts 也不能省：npm ≥ 11 默认不跑依赖的安装脚本，只警告一句 npm warn install-scripts … not yet covered by allowScripts，而这个包正是靠 postinstall 把二进制拷到 bin/。脚本一被拦，装完就是「added 1 package」加一个 500 字节的占位。参数写裸包名（npm 的匹配规则允许，钉版本会随发版失效）； npm 10 不认这个参数，但它只当普通配置忽略，不会报错。 另外 npm_env() 把所有继承来的 npm_config_* 全部清掉再显式设一遍， 防用户 .npmrc 里的 ignore-scripts=true / omit=optional。 原生包还是没下来时（132MB 断在半路），单独 npm install -g 平台子包并 自动重试 3 次；如果它其实已经在树里、只是没拷到位，就只跑一次 install.cjs，不重复下载。
4. 账号 + 配置：本地已有 identity 就复用（不会偷偷重注册）；--account-code 走 bind_account()；都没有才 register_device()（PoW 进度在终端里画一行）。 最后 bypass_region_check() + set_model_config() 写 ~/.claude.json 和 ~/.claude/settings.json。

模型连不上就直说连不上。 这是用户明确要的：不假装装好了、也不含糊成"安装失败"。 server/agent_install.py 按原因分开说：

原因	打出来的话	退出码
本机没有账号凭证	本机没有账号凭证，模型用不了	4
余额不足	账户余额不足（+ 充值命令）	4
连不上模型服务器	连不上模型服务器（+ 先确认能打开 aikaui.com）	1
模型服务器返回看不懂的内容	等一会儿重跑；一直这样请联系我们	1
跑满 40 步还没装完	Agent 跑满了步数上限还没装完	1
用户按了两次 Ctrl-C	已中断	130

配置自愈。两份配置里的 ANTHROPIC_* 是我们写的，但用户重装 / 升级 Claude Code、 上次写盘中断、服务端轮换 token，都会让它们跟 ~/.claude-agent/identity.json 对不上。 桌面版每次启动、服务器版每次 --repair 都会对一次账 （server/claude_config.py 的 check_and_repair）：

• 只修自己的：磁盘上的 ANTHROPIC_BASE_URL 与 identity 一致（或一个受管键都没有） 才算我们的；指向别处的不自动改（那是用户自己的东西），但也不算配好了 —— 桌面版会拦下来（见下面「别人的中转」），服务器版 --repair 报成失败（退出码 7）， 加 --force 才换成我们的；
• 坏文件绝不覆盖（JSON 解析不了、env 不是对象、路径是软链 → 跳过并说明）；
• 没有 diff 就不写；写之前留一份 <文件名>.aikaui-bak； settings.json 顶层的 model 不碰 —— 那是用户在 /model 里的选择；
• 桌面版只在真的补了东西时往对话区留一行日志，不弹窗。

<文件名>.aikaui-bak 的定义是"装我们之前的样子"，不是"上一次写入前的样子"： apply()（安装 / 换账号时那次覆盖）和 check_and_repair()（自动修复） 都只在备份还不存在时才写它。这样用户原来那套别家中转（连同它自己的 token） 永远留在备份里 —— 管家给的选项写着「换成我们的（原来的会备份，随时能换回）」， 这条承诺就得对后来每一次自动修复都成立。

别人的中转：拒绝使用，除非换成我们的。 这个客户端只配合 aikaui 中转工作 —— 终端要是还指着别处，我们既收不到那台机器的用量，也不该继续发它对话额度。 server/relay_gate.py 只看两个文件的 env.ANTHROPIC_BASE_URL：

情况	判定
没写 base / 只写了 token	不算（还没接别家）
与 identity 的 api_base 规范化后相同（带不带 /v1 都算）	我们的
是别的地址	拦 —— 桌面版弹窗只给「换成 aikaui 中转」和「退出」两条路
文件坏了 / 是软链 / env 不是对象	判断不了就不拦，交给 --repair 报

• 「换成 aikaui 中转」= 先备份再覆盖（apply()），原配置随时能换回；
• 还没有账号时它顺带注一个（首次运行就是这样），注册失败照实说，不假装切换成功；
• 用户选「退出」，程序直接关，不会起 Agent；
• --recharge 那条只付钱、不碰终端配置，不拦；
• 服务器版从来只写我们的配置，--repair 发现还指着别处就退出 7。

退出码。两个程序的码各有各的含义，脚本化部署时靠它判断，别只 grep 输出：

install.sh（下载和落地这一段）：

码	含义
0	装好了
1	拉不到 latest.json、下载失败，或清单里缺字段
2	被前置检查拒绝：root、HOME 为空或 /、缺 tar/awk/curl
3	包不对：非 https、大小不符、sha256 不符、tar 读不了、包里有 ../、包内没有可执行文件
4	装上了但 --version 跑不起来（glibc / 架构不兼容）

claude-code-assistant（Agent 装 + 终端对话）：

码	含义
0	装好了（--dry-run / --balance / --recharge / --repair 成功也走这个码）
1	没归类的失败：模型连不上、模型服务器返回看不懂的内容、跑满步数还没装完、装完但核验没过
2	参数不对（argparse）
3	环境不支持 / ~/.local 不可写，或没有 TTY 又没给 --yes
4	账号：注册失败、绑账号失败、本地留着未完成注册的旧账户码却没给 --new-account（--repair 时是"本机没有账号"）
5	Node 装不上（镜像挂了、校验失败）
6	npm 装不上（网络、权限、包缺原生二进制）
7	配置写不进 ~/.claude.json / ~/.claude/settings.json；--repair 遇到坏文件、写入校验失败，或者配置还指向别家中转（加 --force 才换成我们的）
130	用户在终端里按了两次 Ctrl-C

★ 5/6/7 现在是 Agent 调工具时拿到的失败：它自己会重试、换镜像、问你要不要继续， 这几条只在"它也解决不了、最后收场"时才成为退出码。所以脚本化部署仍然可以按码判断。

装完 install.sh 会直接进向导，并把向导的退出码原样透传出来 —— 所以 curl … | sh 返回 5/6/7 时，问题在向导那一步，照第二张表查。

没有 TTY 的时候（CI、ssh host cmd、被别的脚本调用）：不阻塞、不假装成功。 DISPLAY 在就试着用 x-terminal-emulator/gnome-terminal 之类把向导开在真终端里， 否则打一行提示 + 写 ~/.claude-agent/cli.log，退 3。

--yes 可以完全绕过这个分支，但语义变了：它现在进的是 Agent 模式， 所以要求 ① 这台机器已经有账号（没有的话 --account-code/--account-key 一起给， 或者先在真终端里跑一次），② 模型服务连得上。两条缺一条就会照实报错退出 （4 / 1），不会退回去走那条老流水线。管道里没有主循环，所以：

• 模型提问时自动选第一项，并打一行 [自动] 选了：… 留痕；
• 不会自动进 claude（那是给人用的交互界面），只打印 cd <工作目录> && claude。

install.sh 认这几个环境变量（都是给测试和特殊部署用的，正常安装不用管）： AIKAUI_SITE（换站点，默认 https://aikaui.com）、AIKAUI_LIB（换安装目录）、 AIKAUI_NO_RUN（只装不启动）、AIKAUI_ALLOW_ROOT=1（1.4.4 起不需要了：root 默认就装，只打一行警告； 留着只为兼容老文档。向导那边照旧传 --allow-root，钉老版本时才用得上）。

root：容器里常常只有 root，所以不拦。代价是 Node、claude 和配置全落在 /root 下， 换个人用不了 —— 警告里直说这一点。

边界：一台机器一个账号 —— 同一个 $HOME 下的所有用户共用一份凭证，本版不做多租户。

打包

Windows / macOS 用 agent.spec，Linux 用 server.spec （两份的入口不同：main.py / server_main.py）。文件名都用 ASCII，CI 和命令行都能直接引用：

python -m PyInstaller agent.spec --noconfirm --clean     # Windows / macOS
python -m PyInstaller server.spec --noconfirm --clean    # Linux（服务器版）

平台	产物	说明
Windows	dist/ClaudeCode安装助手.exe	单文件、无控制台；先跑 python build_tools/make_version_info.py 才有文件版本信息
macOS	dist/ClaudeCodeAssistant.app	未签名；Info.plist 里声明了 aikaui://
Linux	dist/ClaudeCodeAssistant	单文件、有控制台（服务器版）；发行时和 agent.png 一起打 tar.gz

.spec 里的入口只写了 main.py / server_main.py，PyInstaller 会顺着 import 图自己把 ui/、server/、platform_support/ 收进去，不用手工维护模块清单。要手工列的数据文件只有图标 （Windows 的 agent.ico、macOS/Linux 的 agent.png）和 macOS 的 agent.icns。

server.spec 另外做了几件和 agent.spec 不同的事，改的时候别照抄漏掉：

• console=True。GUI 版没有控制台是有意的；服务器版没有控制台等于把所有报错吞掉。
• excludes 里点名 tkinter / _tkinter / customtkinter / PIL / Pillow / ui / images / deps / bus / prompts / updater / notify / platform_support.windows|macos。 这不是省体积，是保证界面库进不来 —— tests/test_imports.py 会断言 import server_main 之后这些模块（连同 openai / pydantic / agent_core）不在 sys.modules 里，所以"不小心 import 了 ui.something"会在测试阶段就红。 bus 和 prompts 容易漏：agent_core 里确实写着 from prompts import …， 只是挪进了 agent_worker()（服务器版不调它）；bus 则是把 tkinter 拖进包的那根线。 排掉它们的前提就是这两句只在函数里 —— 所以 tests/test_updater_linux_payload.py 连"是不是写在函数里"一起断言。
• 模型栈现在进包了（1.4.6 起服务器版是 Agent 装）。openai / pydantic / pydantic_core / httpx2 / httpcore2 / anyio / jiter / sniffio 的数据文件和 子模块都要收，包从 26MB 涨到 36.5MB（tar.gz 35.9MB，2026-10-28 量的）。 涨的空间基本就是模型栈：openai + pydantic + httpx2。注意 openai 3.x 依赖的是 httpx2 / httpcore2，不是 httpx / httpcore —— 写错名字会静默跳过， 到用户机器上才 ModuleNotFoundError。 ★ 收这些包用 _collect()，不用 collect_all()：后者默认 include_py_files=True，会把每个包的 .py 再作为数据文件放一份（PYZ 里已经有 字节码了）。桌面版靠这一条从 35.9MB 降到 23.6MB，服务器版同理。改这里时别贪方便 换回 collect_all。
• helpers 不能排除：server/term_render.py 从它取 norm_options / resolve_option （桌面版和终端版的选项语义靠同一个来源对齐）。它只 import math / re。
• hiddenimports 点名 agent_bus / agent_core / llm / server.agent_install / server.agent_tools / / / / / / / 。这些全是 的（ 不该把模型栈拖起来），静态分析跟不到，漏一个就是运行时崩。 是解 Node 的 用的（PyInstaller 不会自动收 C 扩展）， 是 按平台延迟 import 的。

体积（2026-10-28 量的 Windows 单文件）：23.6MB，改之前 35.9MB，少了 12.3MB（−34%）。 省下来的是打包方式，功能一个没减，细节和"哪些不能动"写在 agent.spec 文件头： 不用 collect_all（源码会重复进包）、只声明真的用到的 win32com.client、排掉已经坏了的 win10toast → pkg_resources → setuptools 那条链、去掉 Pillow 用不到的 _avif / _imagingcms 解码器、optimize=2（等价 python -OO）。tcl/tk（5.9MB）、libcrypto/libssl（2.4MB）、 openai 的资源模块（5.9MB）都没动 —— 那是拿功能换体积。

想再量一遍，或者怀疑哪个包又变胖了：

python build_tools/analyze_archive.py dist/ClaudeCode安装助手.exe

它按顶层包归总，comp MB 才是能省下来的量（uncomp MB 是解压后的大小）；PYZ 里那 几千个模块压缩是整体的，单列一行，拆不到单个包。

CI：打 v* tag（或手动触发）时 .github/workflows/build.yml 在四个 runner 上并行构建（windows-x64 / macos-arm64 / macos-x64 / linux-x64）。矩阵每一行带 spec:，Linux 那行指向 server.spec；构建完还有一个 Linux smoke test 步骤跑 ./dist/ClaudeCodeAssistant --version 和 --help —— 这两条能过就说明没有把 tkinter 拖进来、 lzma 也在，省得下载下来才发现跑不起来。

产物有两个去处：GitHub Release（打 tag 时 release job 挂上去，本机用 python build_tools/fetch_release.py v1.0.1 --dir release 取回来 —— 装了 gh 的话 gh release download v1.0.1 --dir release 等价）和 Actions artifact（保留 30 天）。 CI 不部署到服务器 —— 见上面「发布新版本」里的分工表和原因；Actions 的摘要页也会 写清楚「线上还没变，部署在本机跑」。

macOS 两个包都没有签名：首次打开要右键 →「打开」， 或者终端跑 xattr -dr com.apple.quarantine /Applications/ClaudeCodeAssistant.app。

自动更新

程序不弹窗、不打断：后台静默检查 → 静默下载 → 下次启动时换上新版本。 用量页底部有一行 v1.0.0，就是当前跑着的版本。

客户端怎么工作（updater.py）

1. 启动 25 秒后起一个 daemon 线程，之后每 6 小时拉一次 https://aikaui.com/latest.json（网络失败就退回上次缓存的清单）。
2. 只接受 schema_version: 1、https 地址、64 位十六进制 SHA-256、 size <= 300 MB，而且版本必须比当前新、当前版本不低于 min_version。
3. 流式下载到 ~/.claude-agent/updates/staged/<版本>/，边写边算哈希； 对不上就删掉 .part，绝不替换。
4. 下好只写一行日志「新版本 vX 已下载，下次启动自动更新。」，然后什么都不做。
5. 下一次启动、创建 Tk 窗口之前（main.py 最前面）： 拿文件锁 → 把旧文件改名为 .old-<pid> → 放入新文件 → 失败就换回去 → 用原来的参数重新拉起自己 → sys.exit(0)。新进程打一行「已自动更新到 vX」。
6. 同一个版本连续 3 次替换失败（只读目录、杀毒软件锁文件）就写 failed.json、 删掉暂存，不再拿它骚扰用户。更新失败永远只是"这次没更新成"，不会让程序起不来。

状态文件都在 ~/.claude-agent/updates/：manifest.json（清单缓存）、pending.json （待安装）、applied.json（更新成功的提示，只提示一次）、failed.json、update.log。

macOS：从"下载"目录直接打开的 app 会被 App Translocation 放到只读的随机路径， 替换会失败（只记日志）。把 app 拖进 /Applications 再运行即可正常更新。

发布新版本

1. 改 config.py 里的 APP_VERSION，跑一遍 python -m unittest discover -s tests，提交。

2. 打注释 tag（必须与 APP_VERSION 一致，CI 会校验），正文写这版改了什么 —— 整个正文会变成 GitHub Release 的说明和 latest.json 里的 notes，只维护这一份：

   git tag -a v1.0.1 -F - <<'EOF'
   一句话说这版改了什么
   下面几行可以写细节
   EOF
   git push origin v1.0.1
   

3. CI 在四个 runner 上并行构建，然后由 release job 把四个产物挂到 GitHub Release 上。 CI 不部署——见下面那张分工表。Actions 摘要页会写「线上还没变」。

4. 在本机部署。先把产物取回来（本机没装 gh CLI，用仓库里的脚本；装了的话 gh release download v1.0.1 --dir release 等价），然后：

   python build_tools/fetch_release.py v1.0.1 --dir release
   DEPLOY_HOST=… DEPLOY_USER=root DEPLOY_SSH_KEY=… \
     NOTES="$(git tag -l --format='%(contents)' v1.0.1)" \
     bash build_tools/deploy_downloads.sh 1.0.1 ./release
   

   加 DRY_RUN=1 只生成清单、用客户端自己的 updater 验一遍，不碰服务器。

为什么 CI 不部署： GitHub runner 到我们那台服务器（49.233.72.225）的上行只有 ~17KB/s —— 2026-10-28 实测，136MB 传了十几分钟才走 11MB，按那个速度要两小时。 本机到同一台机器约 5MB/s，几十秒就完。所以分工是：

谁	干什么	为什么是它
CI	四个平台的构建 + 挂 GitHub Release	macOS 的包只能在 macOS runner 上打
本机	deploy_downloads.sh 推到 nginx + COS	上行快；而且部署变成显式动作，不会"打个 tag 就改了生产"

deploy_downloads.sh 的执行顺序是刻意的：传包到 nginx → 传包到 COS → 两边 HEAD 验大小 → 才原子换 latest.json → 更新 install.sh → 改两个页面的版本号 → 最后以客户端视角再确认一遍。 任何一步没验过就退出，所以清单永远不会指向一个取不到的文件。 中间被打断也安全：线上清单还是旧的，只是多了一个半截的版本目录，删掉重跑即可。

releases/winget/<版本>/AppInstaller_x64.msix 不归发版管（2026-10-30 加）。 它是客户端「没有 winget 时自动装一个」用的包，版本固定、内容永久不变，已经在 releases/winget/1.11.430/ 下，发新版本不用动它。要换 winget 版本才跑一次 build_tools/deploy_winget.sh <msix> <版本>，然后把 platform_support/windows.py 里的三个常量（WINGET_VERSION / WINGET_MSIX_SIZE / WINGET_MSIX_SHA256）一起改掉 —— 脚本结尾会把该填的值打出来。忘了改常量的后果是客户端 sha256 校验不过，走下载页兜底。

发布时有三个容易踩的坑，脚本已经处理好了，但你要知道它在干什么：

• 同一份包有两个源，两个都要传。 下载页的 HTML 用相对路径走 aikaui.com（nginx 的 /var/www/aikaui/releases/），而 latest.json 里给自动更新用的 url 指向 dl.aikaui.com （腾讯云 COS + CDN）。脚本两边都传、两边都 HEAD 验大小；任何一边取不到就直接退出， 不换清单。只传一边的后果不是报错，而是客户端悄悄 404 —— 只会在 update.log 里留一行， 6 小时后再试一次。
• 下载页里写死了版本号。 index.html 和 download/index.html 各有 4 条 /releases/<版本>/… 的链接，只换 latest.json 的话，新用户从下载页拿到的还是旧包。 脚本在换完清单之后用正则把这两页的版本号改成新的（备份成 *.bak-<时间戳>， 同目录 mv 原子替换）。用正则而不是替换某个固定字符串，所以不用每次改脚本。
• install.sh 和版本号无关，但每次发版都要重传。 官网那行 curl -fsSL https://aikaui.com/install.sh | sh 拉的是服务器上的一个固定文件， 它自己去读 latest.json，所以没有版本号要改 —— 也正因如此，改了脚本却忘了传， 线上还是老脚本，比发错包更难发现。脚本先 sh -n 语法校验，再 scp 成 .tmp 后 mv， 最后 curl 回来 cmp 一次字节一致，不一致就退出。

顺序是刻意的：传包 → 两边都验 → 才换 latest.json → 再改下载页。 清单永远不会指向一个取不到的文件。DRY_RUN=1 只生成清单并用客户端自己的 updater.py 验一遍（形状、sha256、size、min_version、已是最新时不再提示），不连服务器。

老用户注意：v1.0.0 是第一个带 updater 的版本。更早安装的版本里面没有更新代码， 必须手动装一次 v1.0.0，之后才能自动更新。

目录结构

agent_demo/
│
├── main.py                       182   程序入口：先换新版本 → 建窗口 → 别家中转就拦下 → 起线程（含配置自愈）→ 事件循环
├── server_main.py                618   服务器版入口：环境自检 → Node → claude → 账号 → 配置（--repair 只对账，--balance / --recharge 只查账收钱）
│
├── config.py                      98   唯一的常量源：版本、服务器地址、凭证、路径、配色、更新参数、MAX_STEPS
├── updater.py                    660   自动更新：清单校验 / 静默下载 / 下次启动替换自己（不 import tkinter）
├── deps.py                        19   可选依赖探测：Pillow 在不在
├── helpers.py                    240   数字金额格式化 + 用量取数（按模型 / 时间序列）+ 刻度 + 文字宽度估算 + 选项清洗 + 凭证打码
├── images.py                     138   窗口图标（打包资源优先，缺了现画）+ 付款二维码下载
├── notify.py                      26   桌面通知薄封装（各平台实现在 platform_support）
├── bus.py                        112   线程间队列 + poll_queue（每 100ms 把消息翻译成界面操作）
├── llm.py                        126   大模型客户端（走 aikaui.com 代理，用本机账号的 api_key）
├── agent_core.py                 285   Agent 主循环：run_one_task / agent_worker / balance_worker
├── prompts.py                    614   系统提示词（按平台给安装指令 + 工作目录 + VSCode 询问分支 + 余额分寸）
│
├── platform_support/                  三平台差异（调用方只 import 这个包）
│   ├── __init__.py               181   按 sys.platform 延迟加载并转发
│   ├── common.py                 230   safe_cwd（HOME 越界检查）、find_claude、clean_env、跑子进程抓输出、VSCode 值解析
│   ├── windows.py               1524   注册表协议 / .lnk / cmd / WinRT toast / VSCode 探测 + winget 安装（含"没 winget 就装一个"、问 AppX 注册表定位、240MB 安装包 6 路分段下）/ 指纹原始值（主板+CPU、MachineGuid）/ claude 探测（含便携 Node 的 %USERPROFILE%\nodejs 和 npm 全局前缀）
│   ├── macos.py                  467   Info.plist 协议 + Apple Event / .command 快捷方式 / Terminal.app / VSCode 探测 + brew 安装 / 指纹原始值（IOPlatformUUID）
│   └── linux.py                  387   .desktop + xdg-mime / 终端探测 / notify-send / VSCode 探测（安装只开下载页）/ 指纹原始值（machine-id + DMI，容器里带 hostname）
│
├── server/                            服务端与工具层（不 import 界面）
│   ├── ui_bridge.py               31   GUI 注入桥：set_ui / get_ui
│   ├── cli.py                    335   服务器版共用的地基：退出码、子进程封装、sha256、安全解包、shell PATH 块、HttpClient
│   ├── console_ui.py             128   终端里的进度实现（实现 ui_bridge 那几个钩子，不阻塞、没 tty 也不卡住）
│   ├── node_setup.py             346   Node 检测 / 选 LTS / 从 npmmirror 下载校验 / 解到 ~/.local/node / 软链命令
│   ├── claude_setup.py           462   npm install -g --prefix ~/.local（清掉继承的 npm_config_*，显式 --include=optional + --allow-scripts；原生包没下来时单独补装，断网自己重试）
│   ├── identity.py               581   设备身份、PoW 注册、本地凭证、换设备登录、_ensure_account_code / _ensure_user_id、pending_recovery
│   ├── device_key.py              68   本机密钥：首次注册生成 32 字节随机数，存在比 identity.json 深的地方，**只随注册请求**发给服务器（服务器只存 sha256，用来认出"这台机器来过"）
│   ├── fingerprint.py            186   设备指纹：按来源优先取（board+cpu / MachineGuid / IOPlatformUUID / machine-id+dmi / device_id）→ SHA-256 前 32 位（不是凭据，注册时上报，服务器按它还回旧账号）
│   ├── vault.py                  268   凭证的"第二份"：账户码存注册表（DPAPI 加密）/ 配置目录；本机密钥也存在这里，但是另一个槽位
│   ├── pow.py                    128   PoW 求解（进度 / 取消 / 90 秒超时），和服务器 pow.js 逐位对齐
│   ├── api.py                    504   余额 / 用量 / 充值 HTTP 层（永远不抛异常）
│   ├── claude_config.py          495   把身份写进两份配置 + 事后对账自愈（坏文件不覆盖、外家中转不碰）
│   ├── relay_gate.py             132   别家中转的判定：有 base 且不是我们的就拦住（不 import 界面，可离线测）
│   ├── billing_console.py        226   服务器版的措辞层：余额/用量排版、终端二维码、装完能敲的命令（不联网、不 import 界面）
│   ├── tools_fixed.py            148   五个固定工具 + aikaui:// 协议注册（转发 platform_support）
│   ├── tools_general.py          125   bash / read_file / write_file / ask_user（解码和杀进程树在 platform_support.common）
│   ├── tools_vscode.py           246   check_vscode / install_vscode / install_claude_extension / open_vscode（连 Claude 面板一起开）
│   └── tool_specs.py             386   工具说明书：tools[] + tool_map（19 个工具）
│
├── ui/                                界面层
│   ├── fonts.py                  179   全界面字体表：按平台选字体 + 字号常量 + 画布缩放
│   ├── gui.py                     31   class GUI(WindowMixin, OptionsMixin, RechargeMixin, UsageMixin, LoginMixin, AccountMixin, GateMixin)
│   ├── window.py                 521   WindowMixin：窗口壳、左侧导航、对话页、底部询问条、余额回流
│   ├── usage.py                  625   UsageMixin：用量信息页（余额卡 + 两张按模型的时间分布图 + 充值入口）
│   ├── account.py                272   AccountMixin：账户信息页（账户码 / 密钥打码、眼睛、复制、防泄露红字）
│   ├── options.py                219   OptionsMixin：ask_user 选项面板（点击 / ↑↓ / 回车 / Esc）
│   ├── recharge.py               627   RechargeMixin：充值弹窗两页 + 创单 + 付款后刷新 + 只办充值时的靠右定位
│   ├── login.py                  323   LoginMixin：换设备登录弹窗（账户码 + 账户密钥；也承担"本地凭证丢了"时的自动找回）
│   └── gate.py                   156   GateMixin：检测到别家中转时的模态窗（换成我们的 / 退出）
│
├── build_tools/
│   ├── make_version_info.py       80   生成 Windows 文件版本信息（build/version_info.txt）
│   ├── make_manifest.py          113   四个产物 → latest.json（校验版本、算 sha256 / size）
│   ├── fetch_release.py               从 GitHub Release 取回四个产物（本机没有 gh CLI）
│   ├── analyze_archive.py             按顶层包归总产物，量体积时看谁最占地方
│   ├── deploy_downloads.sh            发布：传 nginx + 传 COS → 两边验大小 → 换清单 → 改下载页版本号
│   └── deploy_winget.sh               单独发那份 App Installer（换 winget 版本时才跑）
├── tests/                            离线单元测试（stdlib unittest）
│   ├── test_version.py                版本解析 / 比较 / 清单校验
│   ├── test_download.py               本地假服务器：下载、哈希、404、缓存回退
│   ├── test_apply.py                  备份、回滚、失败上限、锁、更新提示
│   ├── test_pow.py                    PoW 求解（和服务器 pow.js 的测试向量对齐）
│   ├── test_register_flow.py          本地假服务器说真契约：注册、不重注册、不泄密、指纹字段、fingerprint_required、is_recovered、保险箱不被动静冲掉
│   ├── test_credentials.py            打码、设备指纹（各来源 / 占位符 / 老公式冻结 / 失败兜底）、保险箱往返
│   ├── test_ui_messages.py            poll_queue 把 recovery / recovered 送到对的界面方法
│   ├── test_bash_timeout.py           bash 工具的超时与杀干净
│   ├── test_platform_support.py       三平台抽象层
│   ├── test_prompts.py                提示词按平台切换 + VSCode 询问分支的关键句
│   ├── test_vscode.py                 VSCode 探测 / 安装 / 打开（三平台，全程打桩）
│   ├── test_winget.py                 没 winget 时自动装：sha256 校验、依赖包先装、失败报错要能看（HRESULT / 中文不乱码 / 重试一次）、不再解压便携版、问 AppX 注册表、老版本要点名、240MB 6 路分段（拼序 / 接不到段 / 中断 / 校验）
│   ├── test_cancel.py                 「中断」：牌子语义、子进程登记/清理、下载到一半能停
│   ├── test_tools_vscode.py           四个 VSCode 工具的返回值、失败归类、Claude 面板什么时候发链接
│   ├── test_agent_core.py             install_done 什么时候触发（"这一轮真装完了"的判定）
│   ├── test_tool_specs.py             tools[] 和 tool_map 一一对上
│   ├── test_server_cli.py             服务器版：参数、退出码、--dry-run 不落地、无 TTY 不阻塞、不重复注册、密钥不进报错
│   ├── test_billing_console.py        余额/充值措辞：读不懂的余额不编成 0、二维码每行等宽、没装 segno 就退回链接、密钥不出现
│   ├── test_claude_config.py          配置自愈：没 diff 不写、坏文件不覆盖、外家中转不碰、顶层 model 不动、日志不含 token
│   ├── test_relay_gate.py             别家中转一律拦：带不带 /v1 都认得出、坏文件不拦、切换留备份、文字不含 token
│   ├── test_node_setup.py             Node 选版本 / 资产名 / SHASUMS / 校验失败 / PATH 块只写一次
│   ├── test_claude_setup.py           npm argv 精确 / --allow-scripts 带裸包名 / npm_config_* 被清掉 / 失败映射到 6 / 原生包没下来时补装、已下过的不再下一遍、断网重试
│   ├── test_console_ui.py             终端进度条：管道里不打 \r、静默模式、流坏了不抛
│   ├── test_install_sh.py             真跑 sh：假 curl + 真 tar，装到哪、校验失败退几、包里有 ../ 会不会接
│   ├── test_updater_linux_payload.py  server.spec / CI 矩阵 / updater 还认得这个包
│   └── test_imports.py                工具层导入不依赖 Windows；服务器版入口不拖界面
├── packaging/
│   ├── install.sh               322   官网那一行 `curl … | sh` 拉的就是它（POSIX sh，上线前 sh -n 校验）
│   └── claude-code-assistant.desktop   Linux 桌面启动器（服务器版不再发它，留着给手动装桌面版的人）
├── collab/                            两台机器上两个 Agent 的协作规约与实现（PROTOCOL.md / collab.py）
├── docs/                              公共文档用的截图（README 顶部那张）
├── .github/workflows/build.yml        四平台 CI 构建 + tag 时发布
│
├── agent.spec                          PyInstaller 打包配置（Windows / macOS，入口 main.py）
├── server.spec                   105   PyInstaller 打包配置（Linux 服务器版，入口 server_main.py）
├── requirements.txt                    第三方依赖（按平台带 marker）
├── agent.ico / agent.png / agent.icns  窗口 / 应用图标
├── 文件执行或调用顺序.md                一次对话里各模块的出场顺序
├── LICENSE                             MIT
└── README.md

架构

分层依赖

main.py ─→ ui/ ─→ agent_core ─→ llm / server/ ─→ config

依赖是单向的，全图无环：

• config.py 不依赖任何本地模块，是所有常量的唯一来源。
• 界面层（ui/）按职责拆成六个 mixin，拼成 GUI；六个 mixin 方法名互不重复， 也没有一个调 super()，所以 MRO 顺序不影响行为。
• 工具层（server/）不 import 界面。

线程模型：4 条线程，全靠队列说话

线程	起点	周期	干什么
主线程	mainloop()	poll_queue 每 100ms	唯一能碰 tkinter 的地方
Agent 线程	agent_core.py	阻塞在 user_input_queue.get()	跑模型、调工具
余额线程	agent_core.py	每 30 秒	查余额 / 用量 → 丢进 msg_queue
协议线程	main.py	一次性	注册 aikaui://，注册完就结束

线程之间没有任何直接调用，全靠 bus.py 里那四个东西连着：msg_queue（工作线程 → 界面）、 user_input_queue（界面 → Agent）、input_event + input_holder（ask_user 专用的 "闹钟 + 信箱"）。

铁律：非主线程绝不碰控件，一律往 msg_queue 丢消息，由主线程在 poll_queue 里更新界面。

poll_queue 会分发的消息种类：log、balance、busy、recharge、recharge_result、 recharge_methods、recharge_qr、recharge_paid、login_result、recovery、recovered、 ask、progress_start、pow_progress、progress_stop。其中 recharge（服务器说余额不足） 不弹窗，只调 offer_recharge() 在底部问一句。

一次对话里文件和线程的完整流转，见 文件执行或调用顺序.md。

五个容易踩的坑

1. _ui 的晚绑定。

工具层拿界面对象必须走 server/ui_bridge.py 的 get_ui()：

u = get_ui()
if u:
    u.ui_log("...")

不能 from server.ui_bridge import _ui —— 那样会在 import 的那一刻把值（通常是 None） 拷进来，之后 set_ui(gui) 改的是 ui_bridge 里的 _ui，你那份永远还是 None。

2. 两个同名的"刷新余额"。 ui/recharge.py 和 ui/usage.py 都用到了，别搞混：

from agent_core import refresh_balance          # 查完丢进队列，刷用量页
from server.api import refresh_balance as fetch_balance   # 查完返回 dict，判断到没到账

ui/usage.py 的「刷新」按钮也是起一条 daemon 线程跑 agent_core.refresh_balance —— 网络请求不能落在主线程上，不然界面会卡住。

3. 六个 mixin 的方法名不能撞。 GUI 靠 MRO 把六个 mixin 拼起来，谁都不调 super()，所以一旦两个 mixin 定义了同名方法， 排在后面的那个会被静默吃掉。加方法前先在全目录搜一下同名。

4. _ensure_account_code / _ensure_user_id 必须留在 server/identity.py。 server/api.py 要用它们，而它们内部会回调 register_device()。挪进 api.py 就变成 api ↔ identity 双向依赖，直接循环导入。

5. tk.Canvas 上的东西不会被 CTk 缩放。 字体全在 ui/fonts.py 一处定义：控件用 font(S_BODY)，画布用 spec(S_CANVAS)， 别在别处写 ctk.CTkFont(size=11) 或 font=("微软雅黑", 11) 这种字面量。特别是画布—— ctk.CTkFont 的 size 是像素（还会按屏幕 DPI 再放大一遍，这台机器 150% 就是 ×1.5）， 而 create_text 老实按 Tk 的规矩解释：正数是磅、负数是像素，1 磅只有 1.33 像素。 所以 spec() 传的是负数；同时画布上的长度（留白、柱宽、提示框）也得乘 canvas_scale()， 不然图上的字永远比旁边的控件小一圈。文字宽度用 helpers._text_width(text, fonts.csize(S_AXIS)) 估算 —— 字号口径必须和 spec() 一致，否则提示框会量错、把文字切掉。

数据与凭证

文件	内容
~/.claude-agent/identity.json	本机凭证：device_id、api_key、account_key、api_base、model、fast_model、user_id、account_code、balance、fingerprint（取到时），以及最近一笔充值订单 last_order。POSIX 上权限是 0600
HKCU\Software\aikaui\ClaudeCodeAssistant	凭证的第二份（只有 account_code / account_key / user_id），值用 DPAPI 加密 —— 只有同一个 Windows 用户、同一台机器解得开。macOS 在 ~/Library/Application Support/aikaui/credential.json，Linux 在 ~/.config/aikaui/credential.json（都 0600）
同一个注册表键下的值 m / 凭证目录里的 .state	本机密钥（server/device_key.py），和上面那份分开存：vault.clear() 不会动它。它不进 identity.json、不进界面、不进日志，只在注册请求里发一次
~/.claude.json	Claude Code 的配置，set_model_config 往它的 env 里写中转地址、token 和各档位模型映射
~/.claude/settings.json	Claude Code 的用户级设置，set_model_config 会把同一套 env 也写进去（优先级更高），并把 model 钉成 flash，其它键原样保留

模型档位：默认只走 flash，pro 要自己主动选

set_model_config 写进去的映射分两层：

档位	环境变量	指向
默认	ANTHROPIC_MODEL / ANTHROPIC_SMALL_FAST_MODEL / ANTHROPIC_DEFAULT_MODEL	flash
默认	ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_DEFAULT_HAIKU_MODEL	flash
显式	ANTHROPIC_DEFAULT_OPUS_MODEL	pro

外加 ~/.claude/settings.json 的 "model" 也钉成 flash（写完整模型名而不是 haiku 这类别名，可以直接绕开别名解析）。

ANTHROPIC_DEFAULT_{SONNET,OPUS,HAIKU}_MODEL 不是"优先级较低的默认值"，而是给 sonnet / opus / haiku 这几个别名做重定向的。Claude Code 在用户没明确指定模型时 走的是 sonnet 档，所以 ANTHROPIC_DEFAULT_SONNET_MODEL 一旦指向强模型，用户什么 都没选也会打到贵的那个上 —— 这就是"指定了 flash 却偷偷调用 pro"的原因。 同理，只要 ANTHROPIC_DEFAULT_OPUS_MODEL 指向 pro，任何请求到 opus 档的地方 （子 agent、plan 模式等）都会落到 pro；这是留给用户自己 /model 选 opus 的通道， 不想要可以把它也改成 flash。

device_id 是主机名 + MAC + 架构 的 sha256 前 16 位，同一台机器每次算出来都一样。 它现在只是本机标识（bind-account 用它去重），不再是身份凭证 —— 服务器只按 api_key / account_code 认人，所以同一个 device_id 换不出任何东西。

同一个 account_code（形如 CC-XXXXXX-XXXXXX）可以换设备找回账号，「🔐 账户信息」页把它和 account_key 都列出来（默认打码，点眼睛看明文，带复制和红字警告）；「用量信息」页只露前 4 位。 服务端还回一个 account_key（64 位 hex，只回一次），存在 identity.json 里，目前只用来核对 账号归属，接口并不需要它。

注册不是幂等的：新契约下"注册"= 用 PoW 开一个新账号，所以只要本地有凭证， 客户端一次请求都不会再发（重复注册会开新号、把余额丢掉）。

凭证丢了怎么找回来（三条路）

1. 本机凭证被删 / 被清理工具带走：注册或换设备登录成功时，账户码和账户密钥会另存一份到 server/vault.py（Windows 注册表 + DPAPI）。下次启动发现 identity.json 不在了、 但保险箱里还有凭证，程序不注册新号，而是弹出「换设备登录」窗口把两串都预填好， 由用户点一下「登录」确认 —— 恢复走的是现成的 POST /api/bind-account。 不替用户自动确认：共用电脑上前一个人删了凭证，后一个人一开机就被"恢复"进别人的账号， 等于把余额送给陌生人。

2. 换了机器 / 重装了系统：只能靠用户自己存下来的账户码 + 账户密钥（这也是「🔐 账户信息」页 要红字提醒"截图保存"的原因）。

3. 同一台机器上再注册一次（2026-10-31 起）：/api/auto-register 会拿设备指纹去找有没有 属于这台机器的账号，有就直接把那个账号还回来（响应 is_recovered: true，界面上会弹 「账号已自动恢复」）。这是为了堵住"删掉 identity.json 再注册一次就多领一份赠送额度"。 ★ 这条只发 api_key + account_code，不发 account_key：指纹不是秘密（见下一节）， 撞号或泄露的风险只能靠"不交主人凭证"来兜底。所以保险箱里的密钥客户端自己续上， identity.py 里专门处理了"恢复时别拿空值冲掉旧密钥"。

   2026-11-01 起这条路前面还多加了一道本机密钥（见「本机密钥」一节）：它比指纹强， 命中时优先按它恢复 —— 删掉 ~/.claude-agent 删不掉它，所以"清配置刷号"这一步就断了。

换设备登录要两样

服务端 POST /api/bind-account 要 {account_code, account_key, device_id}：

• 账户码会露给旁人（截图、口述、页面上露前 4 位），单靠它就把整台机器的余额领走太薄；
• 账户密钥是 32 字节随机数的 hex，注册时下发一次，服务端只存 SHA-256。 比对时 trim + 大小写不敏感（那串 hex 大小写不携带信息，用户手抄容易错）， 用 timingSafeEqual 比，不按字节早退。

三种回答分得很清楚，别混着说：

服务端	含义	界面上
404 account_code not found	码查不到	让用户核对账户码
403 account_key_required	码对、但没给密钥	光标跳到密钥框
403 account_key_invalid	密钥不对	强调"整串复制，别只抄一段"

老账号（2026-10-24 之前注册的）没有密钥，服务端对它们只认码 —— 那批账号的密钥 从来没下发过，现发一把会让"只知道码的人先登录把真用户锁在外面"。所以客户端不把密钥 设成必填，空着照样发，由服务端决定。

设备指纹是什么、不是什么

注册时随请求发一个 32 位十六进制的设备指纹（server/fingerprint.py）。取值按顺序， 第一个拿到的赢：

来源	平台	取的是什么
board+cpu	Windows	SHA-256(主板序列号 | ProcessorId)[:32] —— 老公式，一个字都不能改（线上已入库的指纹还认它）
machine-guid	Windows	主板序列号是占位串 / 虚拟机时，退到 HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid（winreg 读，不起 PowerShell）
platform-uuid / platform-serial	macOS	ioreg -rd1 -c IOPlatformExpertDevice 的 IOPlatformUUID（读不到才用硬件序列号）
machine-id+dmi	Linux	/etc/machine-id + DMI 的 product_uuid / board_serial；容器里再加 hostname（同宿主机同镜像的两个容器前三个完全一样，不加就撞号）
device-id	全平台	兜底：主机名 + MAC + 架构。弱，但保证不会空

原始值的读取全在 platform_support/{windows,macos,linux}.py 的 fingerprint_parts()； 哈希和"选哪个来源"在 server/fingerprint.py 的纯函数 derive() 里，测试不碰系统。 指纹连同来源一起上报（fingerprint_src），只进服务端日志 —— 两个人"撞"到同一个账号时， 得能一眼看出是哪个来源撞的。

它不是凭据：本机任何程序都读得到，随手也能往接口里传任意字符串；ProcessorId 对同型号 CPU 是常量（CPUID 特性位 + 型号签名，不是序列号）；不少 OEM 主板 / 虚拟机的序列号是 Default string、To be filled by O.E.M. 这类占位符 —— 这些值一律当"没有"，退到下一个来源。

服务端拿它做两件事：同一指纹再注册就还回原来的账号（见上一节第 3 条），以及 同一指纹 24 小时内最多 5 次新注册（POW_FP_HARD，和 IP 硬阈值一个数量级）。 恢复本身不计入这个配额（审计记 outcome='recovered'，配额只数 'registered'）。

上线顺序：客户端先发（指纹永不空、始终上报），服务端随后。服务端第一版 FINGERPRINT_REQUIRED=0（缺指纹照旧放行，兼容 1.5.5 及更老的客户端），等日志里确认 指纹齐全了再翻成 1 硬拒。

真正能证明"这账号是我的"的，只有账户码 + 账户密钥。

本机密钥（device key）是什么、不是什么

指纹能挡住"清配置刷号"，但它有个弱点：不保密，本机随便一个程序都读得到，改一改还能 伪造。所以 2026-11-01 加了一串客户端自己生成的密钥：

• 是什么：第一次注册时生成的 32 字节随机数（64 位 hex，server/device_key.py）。 它只随 /api/auto-register 发一次，和 device_id 一起上去；服务器只存 SHA-256 （cc_accounts.device_key_hash + device_id），日志里连哈希都只打前 8 位。
• 存在哪：比 identity.json 深一层 —— Windows 是 HKCU\Software\aikaui\ClaudeCodeAssistant 下的另一个值（值名 m，DPAPI 加密），macOS / Linux 是凭证目录里一个 0600 的 .state。 不在 identity.json 里、不进界面、不进日志、不进任何给模型看的文本。 删掉 ~/.claude-agent 不会把它一起删掉；vault.clear()（换账号）也不动它。
• 服务器怎么用：拿到 SHA-256(device_key) 先查有没有账号 —— 命中就还回原账号（和指纹恢复同一个响应形状，只给 api_key + account_code）， 优先级高于指纹（密钥比指纹强）。没命中再看指纹，都没命中才建新号。 闸门和指纹一样在「挑战校验 + PoW + 消费挑战」之后，不然就成了不花算力就能枚举 "这台机器有没有账号"的入口。
• 它不是凭据：客户端自己能生成，就能被重置（删注册表值 / .state，或客服帮忙清）。 它抬高的是刷号成本，不是不可伪造的证明。所以命中后依旧不发 account_key。

服务端开关 DEVICE_KEY_REQUIRED 默认 0（1.5.6 及更老的客户端不认这个字段，硬拒会让它们 一装就注册不了），等 1.5.7 铺开、日志里确认密钥齐全之后再翻成 1。注册风控白名单 （cc_settings.ip_whitelist）同样跳过这个开关。

服务端接口

统一走 https://aikaui.com。X-Agent-Key 只在注册链路里发（它打在 exe 里， 是公开的"敲门砖"，不是秘密）；聊天用注册拿到的专属 api_key。

接口	用途
GET /api/challenge	取一个 PoW 挑战（带 X-Agent-Key）
POST /api/auto-register	提交 {challenge, nonce, fingerprint, fingerprint_src?}，换回账号与专属 api_key；指纹已对应到账号时直接还回那个账号（is_recovered: true，不发 account_key）
POST /api/bind-account	用 {account_code, account_key, device_id} 换设备登录（不需要 X-Agent-Key；老账号 account_key 可省）
GET /api/balance	查余额（按 account_code 查）
GET /api/usage	查 token 消耗
POST /api/create-order	创建充值订单，返回付款二维码
POST /api/chat/completions	助手自己聊天，只认 Authorization: Bearer <用户 api_key>
aikaui://recharge?user_id=N	自定义协议：支付页付完款靠它把本程序唤起来

POST /api/issue-token 已经下线（恒返回 410），客户端不再调用。

注册：PoW 人机校验

/api/challenge 给一个 32 位 hex 的挑战（绑定来源 IP、120 秒过期、只能用一次）， 客户端要在本地找一个 nonce，使 SHA256(challenge + nonce) 的前 difficulty 个二进制位 全为 0，再交给 /api/auto-register。难度平时是 16，同一出口注册太频繁会抬到 22。

求解在 server/pow.py，跑在 Agent 线程里：能报进度（已算多少次 / 约百分之几）、能取消 （进度条上有个「取消」）、单次 90 秒硬超时，一次注册最多重来 3 次（每次都重新取挑战）。 失败原因会照实带到界面上：注册关闭、网络太频繁、认不出 IP，三种情况用户该做的事不一样。

提交时一定带 fingerprint（除非连 device_id 都拿不到，那是极端情况，见上面 「设备指纹是什么、不是什么」）。服务端还是老版本、不认识这个字段而整条请求 400 时， 客户端会去掉字段再试一轮 —— 兼容老服务端用；但服务端明确回 fingerprint_required 时不重试（丢掉指纹只会失败得更难看），直接如实报错让用户升级。

server/api.py 里的所有函数永远不抛异常 —— 失败就返回 (None, 错误说明) 或 {"error": "..."}，错误原文会被翻译成大白话带到界面上。余额查不到、支付平台挂了， 都不会把程序搞崩。

/api/usage 的响应形状（后端已按这个返回）

today / month 两块里各带一个 by_model、一个 series（总量序列）和一个 series_by_model（按模型拆开的时间序列，两张图读这个）。 序列按北京时间分桶：今日是 0 点到当前小时，本月是 1 号到今天。

{"today": {"tokens": 11785016, "yuan": "2.22",
           "by_model": {"deepseek-flash": {"tokens": 11785016, "yuan": "2.22"}},
           "series": [{"label": "00:00", "tokens": 0, "yuan": "0"},
                      {"label": "01:00", "tokens": 1234, "yuan": "0.01"}],
           "series_by_model": {
               "deepseek-flash": [{"label": "00:00", "tokens": 0, "yuan": "0"},
                                  {"label": "01:00", "tokens": 1234, "yuan": "0.01"}],
               "deepseek-v4-pro": [{"label": "00:00", "tokens": 0, "yuan": "0"}]}},
 "month": {"tokens": 48647024, "yuan": "13.44",
           "by_model": {"deepseek-flash": {"tokens": 44580889, "yuan": "9.81"},
                        "deepseek-v4-pro": {"tokens": 4066135, "yuan": "3.64"}},
           "series_by_model": {
               "deepseek-flash": [{"label": "10-01", "tokens": 100, "yuan": "0"}],
               "deepseek-v4-pro": [{"label": "10-01", "tokens": 0, "yuan": "0"}]}}}

改动这个接口时守四条：by_model 里各模型的 tokens 加起来等于同级的 tokens； series 里各桶的 tokens 加起来也等于同级的 tokens；series_by_model 里每个模型的 桶加起来等于该模型在 by_model 里的 tokens；老的 tokens / yuan 字段保留原样 （余额卡和两个消耗小格读的是它们）。

客户端解析做得很松：helpers._norm_by_model 认 by_model / models / by_model_tokens， 值可以是 {模型: token数}、{模型: {"tokens":…, "yuan":…}}，也可以是 [{"model": …, "tokens": …}, …]；helpers._norm_series 认 series / by_hour / by_day （series_by_model 里的每一段也走它）。按模型序列缺失时那两张图退回每个模型一根 总量柱子并注明"服务器暂未按模型拆分时间"；连模型数据都没有时退回总量的单根柱子 + "暂无数据"，不会白屏。

这个仓库是怎么维护的

顺带一提：这里有两个 Agent 在干活 —— 一个在作者的 Windows 电脑上，一个在服务器上。 它们不共享会话记忆，靠 git 当共享外存：认领任务、开自己的分支、推上去、用 ask / done 交接。规约写在 collab/PROTOCOL.md，实现是 collab/collab.py，连"每次开工自动看一眼对端有没有新消息"的 hook 都配好了。这套东西本身就是个可以抄的样本：让两个不会互相记得的 Agent 不靠自觉、 靠机制把活接上。

已知限制

• 「没 winget 就自动装」这一步，真机上还没成功过一次。 能确定的是：包从 CDN 下得下来（实测 58MB / 11 秒 / sha256 对得上）、 Add-AppxPackage 的参数绑定不再报错、分支逻辑全有离线测试。 用户的机器走到的是 DeploymentError / IOException（部署进程已排队，然后 IO 失败）， 这属于 AppX 部署本机故障，不是我们能绕的：1.5.4 那次的 ParameterBindingException 已经修掉，剩下的这类失败会如实报出来、隔 2 秒换 ASCII 路径再试一次，还不行就退到 240MB 官方安装包，不会卡住。手上没有一台"干净、没有 App Installer"的机器， 所以这条路没跑过完整成功一遍。

• 用户那台机器上的 winget 是"本来就装不上"的（2026-10-31 查清）。 Get-AppxPackage Microsoft.DesktopAppInstaller 有结果，但版本是 1.0.30251.0 —— winget 出现之前的老版本，包里没有 winget.exe，winget 自然也不在 PATH 里 （用户那边报的是 CommandNotFoundException，这是正确的，不是环境坏了）。 我们下的 1.11.430 想把它升级上去，Add-AppxPackage 在部署阶段 IO 失败。 这种事在用户态没有可靠的绕法（Remove-AppxPackage 动的是系统预置包，要管理员权限， 而且会把双击安装 msix 的能力一起弄没）—— 所以这事停在这里，交给用户在 Microsoft Store 里更新「应用安装程序」。装不上也不会卡：走 240MB 官方安装包。

• Add-AppxPackage 返回 1 的原因查清了（2026-10-31）。不是缺依赖，是参数名写错： Add-AppxPackage 没有 -LiteralPath，写上它 PowerShell 抛 ParameterBindingException、 一句都不执行。10-30 那次的日志只剩「返回 1： and」，所以当时猜成了缺框架包； 10-31 的日志留了三行，FullyQualifiedErrorId: NamedParameterNotFound,…AddAppxPackageCommand 才把它点破。现在用 -Path（带通配符字符时先 Set-Location -LiteralPath 再传文件名）。 1.5.4 之后用户那边的报错换成了 DeploymentError / IOException —— 说明参数这关过去了，卡在 AppX 部署本身（本机 WindowsApps\Deleted 下有删不掉的残留、 ClipSVC 停着，都是仓库受损的迹象）。

• 便携版 winget 装不了东西（2026-10-31 确认）。它不是 AppX 包，源索引永远打不开， winget install 必然 0x8A15004B。所以 2026-10-31 起不再解压便携版（以前解压完 打一行「已装好」、下一行就说「读不到软件源」，白等十几秒还自相矛盾）： ensure_winget() 装不上就返回失败原因，install_vscode() 直接走官方安装包。

• find_winget 不再靠猜路径（2026-10-31）。用户机器上 winget 是好的，我们却报了 「没有 winget」：PATH 里第一条 WindowsApps 属于别的账户（空壳别名），%USERPROFILE% 和实际 profile 目录也可能不是一个（本机 USERNAME 是中文名，profile 是 C:\Users\abc）。 现在最后一道是问 Get-AppxPackage Microsoft.DesktopAppInstaller 的 InstallLocation。 这条在这台机器上验证过（能准确拿到 1.29.380 的包目录），但它依赖 PowerShell 能起得来； 起不来就当没有，行为退回以前。

• 新装的 winget 源索引是空的，2026-10-30 用户在真机上撞到 0x8A15004B。 已经加了 / 重试和「直接下微软安装包」那条兜底， 但（本机的 winget 本来就是装好的、源索引也在）。 下次再遇到，日志里会多出「刷新源索引后再试一次」这些行，能直接看出走到哪一步。