Files
usage-zh/README.md
T
cat-shark 50740b4d08 feat: /usage 用量面板中文化(上游 0.10.2)
基于 @tmustier/pi-usage-extension 0.10.2(github.com/tmustier/pi-extensions 的
usage-extension/),仅改文案与 3 处中文宽度/排版补丁。

- zh-map.mjs:100 条词表(103 处替换),覆盖视图/周期/表头/快捷键/加载/洞察全部文案
- apply-zh.mjs:幂等应用器,上游改文案时报 MISS 而非静默漏译
- 本地补丁:x 轴日期改 ASCII M/D、分组横线用 visibleWidth、中文括号前不补空格
- 数据层:辅助用量伪渠道改 工具/摘要,CACHE_VERSION 6→7(名字会 intern 进缓存)
- 保持英文:CSV 表头、JSON 键名、导出文件名,避免下游表格/脚本失配
- scripts/:渲染与数据/导出冒烟脚本
2026-11-18 14:46:30 +08:00

57 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# /usage 用量面板(中文副本)
中文界面副本,源自 `@tmustier/pi-usage-extension` **0.10.2**(上游 `github.com/tmustier/pi-extensions` 的 `usage-extension/`)。
本目录被 pi 自动发现(`~/.pi/agent/extensions/*/package.json` 的 `pi.extensions` 或 `index.ts`),命令仍是 `/usage`。
## 文件
| 文件 | 说明 |
|---|---|
| `index.ts` `data.ts` `graph.ts` `export.ts` | 上游源码(仅改了文案与 3 处本地补丁) |
| `export.ts` | **未汉化**:CSV 表头保持英文(`provider,model,cost_usd,...`),避免下游表格/脚本失配 |
| `zh-map.mjs` | 汉化词表:`{文件: [[英文原文, 中文], ...]}` |
| `apply-zh.mjs` | 词表应用器 + 本地补丁(幂等,未命中即报错) |
| `package.json` | 本副本清单,`version: 0.10.2-zh.1` |
| `scripts/usage-render-smoke.mjs` | 渲染冒烟:三视图按指定宽度渲染为纯文本,报超宽行 |
| `scripts/usage-data-smoke.mjs` | 数据/导出冒烟:采集 + 洞察文案 + CSV/JSON 片段 |
## 汉化覆盖
- 视图名 / 周期 Tab / 表头 / 合计行 / 底部快捷键提示 / 加载进度 / 导出回执
- 图表模式行、指标名、分组名、图例 `合计` 与 `其他 (N)`
- 洞察页全部文案(标题、副标题、分组标题、6 类告警 + 5 类结构结论含 advice)
- 辅助用量伪渠道 `工具 / 摘要`(旧版为 `Tools / summaries`)
保持英文:CSV 表头、JSON 键名(`period`/`totals`/`insights`…)、导出文件名(`usage-graph-allTime-…csv`)、模型名与思考等级等数据值。
## 本地补丁(与语言无关的宽度/排版修正)
1. 图表 x 轴日期改 ASCII `M/D`:`renderChart` 用字符串长度算轴位,`toLocaleDateString` 在 zh-CN 下返回 `8月14日`(宽度 = 长度×2),会把末尾标签挤出并截断。
2. 洞察分组横线长度改用 `visibleWidth(label)` 而不是 `label.length`,否则中文标签会让横线超出宽度、被截成 `…`。
3. 告警标题里的 `(本期 x%)` 前不再补空格(英文 `(12% of this period)` 需要空格,中文不需要)。
## 数据层改动
`AUXILIARY_PROVIDER/AUXILIARY_MODEL` 改为中文并 **bump `CACHE_VERSION` 6 → 7**:这些名字会被 intern 进 `~/.pi/agent/usage-extension-cache.json`,不 bump 会出现中英混排。代价是首次 `/usage` 走一次"重建"(本机 312 个会话约 2s)。
## 升级上游
```bash
SRC=~/.pi/agent/npm/node_modules/@tmustier/pi-usage-extension
cp $SRC/{index.ts,data.ts,graph.ts,export.ts} ~/.pi/agent/extensions/usage-zh/
cd ~/.pi/agent/extensions/usage-zh && node apply-zh.mjs # 报 MISS 即上游改了文案
node scripts/usage-render-smoke.mjs --width 80 # 渲染冒烟
node scripts/usage-data-smoke.mjs # 数据/导出冒烟
```
冒烟脚本默认以仓库根为扩展目录,可用 `--dir` 指到别处;`PI_DIST` / `JITI` 环境变量可覆盖依赖路径。
`MISS` 条目按 `zh-map.mjs` 的英文原文更新后重跑;新增界面文案需自行补条目。
## 注意
- 仓库:`ssh://git@git.cat-shark.xyz:2222/cat-shark/usage-zh.git`;本目录即工作副本,`origin/main`
- **不要把 `npm:@tmustier/pi-usage-extension` 再加回 `settings.json`**:两个扩展都会注册 `/usage`,命令重复。同理也不要用 `pi install` 再装本仓库的 git 包
- 上游 npm 版仍留在 `~/.pi/agent/npm/node_modules/`,用作 diff/升级参照,不影响加载
- 改完后:`node apply-zh.mjs` → 冒烟通过 → `/reload` 生效 → commit/push