# koread_ext_psv

**Repository Path**: rymaker/koread_ext_psv

## Basic Information

- **Project Name**: koread_ext_psv
- **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-08
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VitaQuota

PS Vita 上的 AI 额度排行榜。聚合 Grok / Claude Code / Codex / Kimi Code / OpenCode Go / Antigravity（AGY）的用量接口，单列排行展示。

## 构建与验证

依赖：VitaSDK（`VITASDK` 环境变量）、cmake ≥ 3.20、make、主机侧 gcc。在 WSL Ubuntu 内：

```bash
# 一键验证：主机侧测试 → 静态检查 → 交叉编译
bash scripts/verify.sh
```

单独构建 VPK：

```bash
bash scripts/build.sh
# 产物：build/vitaquota.vpk
```

### 安装失败排查（`0x8010113D`）

```bash
# 打最小 VPK（不含 LiveArea 资源），排除资源问题
cmake -S . -B build -DVQ_NO_LIVEAREA=ON ...
```

最小 VPK 能装而完整版不行 → 问题在 LiveArea 资源（`template.xml` 或图片尺寸）。

`scripts/verify.sh` 覆盖：主机侧断言（ASan + UBSan + `-Werror`）、静态检查、交叉编译。拆开跑也可以：`bash scripts/test.sh`、`bash scripts/check.sh`、`bash scripts/build.sh`。

## 操作表

一个按键只发一条命令，含义由当前页决定。

| 按键 | 列表页 | 设置页 | 日志页 |
| --- | --- | --- | --- |
| ○ | 刷新 | 接口地址行拉起输入法，其余行切下一档 | — |
| × | 空闲时退出；请求进行中取消本次请求 | 返回列表 | 返回列表 |
| △ | 切换跟随/已用/剩余 | — | — |
| □ | 打开设置页 | — | — |
| SELECT | 打开日志页 | — | 返回列表 |
| START | 退出 | 退出 | 退出 |
| 方向键上下 / 左摇杆 | 逐行滚动 | 移动焦点 | 逐行滚动 |
| 方向键左右 | 切换额度从高到低 / 从低到高 | 切换当前项的档位 | — |
| L / R | 翻页 | — | 翻页 |
| 触摸拖动 | 滚动（带惯性与越界回弹） | — | — |

## 设置页

顶部是只读信息区（接口地址、本次快照年龄、告警阈值、最近错误、七家各自的
`fetchedAt`），下面七个设置项：

- 接口地址（○ 拉起 SceIme 编辑，保存后立即重新拉取）
- 自动刷新间隔（←→ 在 60 / 120 / 300 / 600 / 1800 秒间循环，默认 300）
- 显示模式（跟随接口 / 已用 / 剩余）
- 排序（从高到低 / 从低到高；列表页 ←→ 同样切换，标题栏徽章用 ↓/↑ 标明）
- 动效（完整 / 精简 / 关闭）
- 自动息屏（关 / 开，默认关 = 常亮）
- 息屏时间（30 秒 / 1 / 2 / 5 / 10 分钟，默认 2 分钟；自动息屏关闭时不可调）

自动息屏关闭时禁止休眠、息屏和调光。打开后仍禁止自动休眠（后台刷新继续），
无输入达到息屏时间后请求关屏；任意按键或触摸唤醒。关屏与唤醒的真机行为待验证。

改动即时写回 `ux0:data/VitaQuota/config.ini`（目录在启动时自动建）。

## 字体来源与许可

- 寒蝉全圆体 ChillRoundF（[OFL](https://github.com/Warren2060/ChillRound)）。子集 `assets/fonts/ChillRoundF-subset.ttf` 已提交进仓库，构建时自动打进 VPK。
- 改了界面文案（新增了仓库里没出现过的字）就重跑 `python3 scripts/gen_font.py`（需 fontTools）重新生成。字体源是全圆体 Regular TTF（放到 `assets/fonts/ChillRoundF-Regular.ttf`，不进仓库）。
- 若源是可变字体，脚本先钉到 `wght=400` 再子集；寒蝉全圆体 Regular 本身已是静态 400。
- 两道自检任一不过就非零退出：子集缺「界面用字 + 必含集」里的字；产物不是钉死在 Regular 的静态字体。找不到字体源同样非零退出。

字体加载顺序：`ux0:data/VitaQuota/font.ttf`（用户自备）→ 随包子集 →
系统 PVF 的中文字面 → 日文字面 → vita2d 默认 PVF。**默认 PVF 走的是拉丁
字面，不含汉字**，所以中日文字面必须排在它前面 —— 没有随包字体时，界面
文案就是靠这一步才画得出来。

## 安全警告

**仅在可信局域网使用，不要暴露到公网。** 接口无认证，额度信息仍是账号信息。

## 真机待验证

以下只能写进 README 的「待验证」，**不得声称已完成**：

- LiveArea 显示
- VPK 实际安装
- WiFi 断开时的提示
- 待机恢复补刷
- 自动息屏按时关屏、按键/触摸唤醒
- 长时间挂机稳定性
- 真实接口端到端拉取
- 中文字形实际渲染效果
- 触摸滚动手感
- 动效的实际观感与帧率
- 启动过渡（黑屏是否消失、条生长与落定、标题淡入、按键跳过、淡出主界面）

## 文档

| 文件 | 内容 |
| --- | --- |
| `doc/plan.md` | 实施计划：偏差、架构、行模型、动效规则 |
| `doc/tasks.md` | 44 步实施清单（含交付物与验收） |
| `doc/fix-tasks.md` | 返工与补完清单：30 步，对上一轮验收失败项的修复计划 |
| `doc/ui-style.md` | 样式规范：颜色、字号、间距、组件像素表 |
| `doc/usage-api.md` | 接口契约（唯一事实来源） |
| `doc/audit-2026-09-07.md` | 项目审计：已复现问题、UI 优化方案与后续功能路线 |