工具效率层

---
name: tokenrhythm-quota
description: |
  查询 tokenrhythm.studio（中转渠道）账号的剩余额度 / 余额 / 调用明细，以及批量接入多个账号到 WorkBuddy/CodeBuddy 自定义模型配置。
  触发词：「查额度」「tokenrhythm 额度」「sk_tr 余额」「中转渠道还剩多少」「tokenrhythm 余额」「接入 tokenrhythm」「把 key 接入」「批量查额度」「多账号接入」。
  关键事实：API Key（sk_tr_ 开头）本身查不到账户余额，必须改用网站登录态 sess_ 令牌当 Bearer 鉴权。
---

# tokenrhythm 账号操作手册

## 一、额度查询

### 适用场景
用户给出 tokenrhythm.studio 中转渠道的一组凭据（手机号 / `sess_xxx` 登录态 / `sk_tr_xxx` API Key 三者之一或全部），要查「还剩多少额度」「余额多少」「调用了多少次」。

### 核心事实（务必记住）
- 查余额的接口是网站侧接口，不是 API Key 接口。
- **API Key（`sk_tr_` 开头）不能查余额**，只能用来发起模型调用。
- **能查余额的是网站登录态令牌 `sess_xxx`**，作为 `Authorization: Bearer <sess>` 调用。
- 用户常误以为 `sk_tr_` 能查余额 —— 直接纠正：必须走登录态。
- 手机号 / 用户名只是账户标识回填，不参与鉴权。
- sess 令牌有有效期，过期后需要用户重新从网站登录后复制。

### 接口与鉴权
- 方法 / 地址：`GET https://tokenrhythm.studio/api/usage-summary`
- 鉴权头：`Authorization: Bearer <sess_令牌>`
- 响应：`application/json`，结构见下方「返回字段」。

### 单账号查询（执行步骤）
1. 向用户索取 `sess_xxx` 网站登录态令牌（若用户只给了 `sk_tr_`，明确告知换不成，需要登录态）。
2. 用环境变量传入 SESS，避免命令行泄露明文：

```bash
TR_SESS="sess_此处替换" node -e "
const SESS = process.env.TR_SESS;
fetch('https://tokenrhythm.studio/api/usage-summary', {
  headers: { authorization: 'Bearer ' + SESS, accept: 'application/json' },
  redirect: 'manual', signal: AbortSignal.timeout(20000),
}).then(r => r.text().then(b => console.log('status='+r.status+' body='+b.slice(0,1500))));
"
```

3. `status` 非 200 时按「异常处理」排查；200 则解析 `data` 字段。

### 批量查询（多个账号）
当用户给出多个 `sess_` 令牌或多个账号的完整凭据时，用脚本批量核查并给出汇总表：

```bash
cat > _batch.mjs <<'SCRIPT'
const ACCOUNTS = [
  # 每个账号：{ n: 1, phone: "手机号", sess: "sess_xxx", sk: "sk_tr_xxx" },
];
async function check(a) {
  try {
    const r = await fetch("https://tokenrhythm.studio/api/usage-summary", {
      headers: { authorization: `Bearer a.sess`, accept: "application/json" },
      redirect: "manual", signal: AbortSignal.timeout(20000),
    });
    const j = await r.json().catch(() => null);
    if (!r.ok || !j || j.code !== 0) return { ...a, status: r.status, err: j?.message || "bad" };
    const d = j.data;
    return { ...a, available: d.availableBalanceCny, expiring: d.expiringBalanceCny, nextExpiry: d.nextExpiryAt, cost: d.costCny, calls: d.calls, success: d.successCalls, error: d.errorCalls };
  } catch (e) { return { ...a, err: e?.message?.slice(0, 120) }; }
}
const results = await Promise.all(ACCOUNTS.map(check));
for (const r of results) {
  if (r.err) { console.log(`#r.n r.phone ERR r.err`); continue; }
  const is68 = Math.abs(Number(r.available) - 68) < 0.01;
  console.log(`#r.n r.phone 可用¥r.available 即将过期¥r.expiring 到期r.nextExpiry 累计耗¥r.cost 调用r.calls(成功r.success/失败r.error)`);
}
SCRIPT
TR_SESS="sess_xxx" node _batch.mjs
rm -f _batch.mjs
```

### 返回字段（data 内，单位均为人民币 CNY / token 数）
| 字段 | 含义 |
|---|---|
| `availableBalanceCny` | 可用余额（用户最关心的「还剩多少」）|
| `balanceCny` | 总余额 |
| `frozenBalanceCny` | 冻结金额 |
| `expiringBalanceCny` | 即将过期余额 |
| `nextExpiryAt` | 最近一笔过期时间（ISO8601 UTC）|
| `costCny` / `tokenCostCny` / `imageCostCny` | 累计已消耗（总 / token / 图片）|
| `calls` / `successCalls` / `errorCalls` / `abortedCalls` | 累计调用 / 成功 / 失败 / 中止 |
| `inputTokens` / `outputTokens` | 累计输入 / 输出 token |
| `currency` | 币种，通常为 `CNY` |

### 输出话术模板（给用户）
结论先行，结构化呈现：
- 账号（若用户提供）：用户名 / 手机尾号
- 可用余额：¥<availableBalanceCny>
- 总余额 / 冻结：¥<balanceCny> / ¥<frozenBalanceCny>
- 累计已消耗：¥<costCny>
- 累计调用：<calls> 次（成功 <successCalls>，失败 <errorCalls>，中止 <abortedCalls>）
- 累计用量：输入 <inputTokens> token / 输出 <outputTokens> token
- ⚠️ 到期提醒：若 `expiringBalanceCny` 接近 `availableBalanceCny`，高亮「¥XXX 将于 <nextExpiryAt 转本地时间> 到期清零，要用的趁早」。

批量查询时输出汇总表，逐账号列出上述字段，最后标注「是否全部满额」。

### 异常处理
- `401` / `AUTH_REQUIRED`：sess 令牌失效或填错 —— 让用户重新从 tokenrhythm 网站登录后复制登录态（浏览器 Network 里任意请求带的 `Authorization: Bearer sess_...`，或直接复制 cookie 里的 `sess_xxx`）。
- 网络超时 / 无法连接：确认能访问 `tokenrhythm.studio`（有时需代理 / 特殊网络）。
- `code` 非 0：把 `message` / `traceId` 原样回给用户。

---

## 二、接入 models.json（将 tokenrhythm 渠道接入 WorkBuddy / CodeBuddy）

### 适用场景
用户有 tokenrhythm 的 `sk_tr_` API Key，希望把它加进 WorkBuddy 和 CodeBuddy 的 `models.json` 自定义模型配置，让本地 AI 工具能通过这个渠道调用模型。

### 核心约束（务必记住）
- **`id` 必须等于上游 `/v1/models` 返回的真实模型名**，禁止加渠道前缀。例如上游返回 `glm-5.2`，配置里的 `id` 就必须是 `glm-5.2`；写成 `tr1-glm-5.2` 会导致客户端把错误模型名传给上游，报 "Model is not supported by any configured account"。
- **`id` 必须全局唯一**。同一个模型名（如 `glm-5.2`）在配置中只能出现一次，不能为了多个账号重复写入。
- 两份文件 (`%USERPROFILE%\.workbuddy\models.json` + `%USERPROFILE%\.codebuddy\models.json`) 内容必须同步。

### 接入步骤

#### 1. 定位文件
```
%USERPROFILE%\.workbuddy\models.json
%USERPROFILE%\.codebuddy\models.json
```
禁止写死用户名（不用 `C:\Users\lsb\`），始终用 `%USERPROFILE%` 环境变量。

#### 2. 查询上游真实模型列表
用用户提供的 `sk_tr_` key 请求：
```
GET https://tokenrhythm.studio/v1/models
Authorization: Bearer sk_tr_xxx
```
返回的 `data.models[].id` 或 `models[].id` 即为真实模型名。记录用户想要的模型（如 `glm-5.2`、`deepseek-v4-flash`）。

常见 tokenrhythm 模型名（带连字符，用户可能写错格式）：
- `glm-5.2`（不是 `glm5.2`）
- `deepseek-v4-flash`（不是 `deepseekv4flash`）
- `deepseek-v4-pro`
- `glm-5.1`
- `kimi-k2.7-code` / `kimi-k2.6`
- `qwen3.8-max` / `mimo-v2.5-pro` / `seed-2.1-pro` / `minimax-m2.7`

#### 3. 写入配置
读取现有两份 JSON，保留原有所有模型。对于每个要接入的模型 id：
- 若该 `id` 已存在于配置中 → **不新增、不加前缀、不覆盖原渠道，跳过并报告**。
- 若该 `id` 不存在 → 新增一条记录，格式：

```json
{
  "id": "上游真实模型名",
  "name": "渠道显示名（如 tr1、WLAI）",
  "vendor": "tokenrhythm",
  "apiKey": "sk_tr_xxx",
  "url": "https://tokenrhythm.studio/v1/chat/completions",
  "maxInputTokens": 360000,
  "maxOutputTokens": 8192,
  "supportsToolCall": true,
  "supportsImages": true,
  "supportsReasoning": true
}
```

能力字段 `supportsToolCall` / `supportsImages` / `supportsReasoning`：只有确定支持才写 `true`，不确定一律 `false`。

#### 4. 原子替换
- 把完整 JSON 写入临时文件（如 `models.json.tmp`）。
- 校验临时文件是合法 JSON。
- `rename`（原子替换）覆盖原文件。

#### 5. 连通性验证
对新增的至少一个文本模型做最小调用：
```bash
curl -s -X POST https://tokenrhythm.studio/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_tr_xxx" \
  -d '{"model":"glm-5.2","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'
```
期望 `status 200` + 有效 `choices[0].message.content`。

#### 6. 最终验证
- 两份文件都是合法 JSON，模型数量一致。
- 所有新增模型 `id` 与上游 `/v1/models` 返回值一致。
- `id` 全局唯一。
- 已连通性通过。

---

## 三、多账户策略（当用户有多个 tokenrhythm key 时）

### 问题的根源
用户常批量购买多个 tokenrhythm 账户，每个账户都有相同的可用模型（如 `glm-5.2`、`deepseek-v4-flash`）。但 `models.json` 的扁平数组结构要求：
1. **`id` 必须全局唯一** —— 同一个模型名不能出现两次。
2. **`id` 必须等于上游真实模型名** —— 不能通过加后缀（如 `glm-5.2-acct2`）来区分不同账户，因为客户端会把加了后缀的模型名发给上游，导致调用失败。

因此：**同一对模型无法在配置里同时装下多个不同的 tokenrhythm 账号**。

### 推荐策略：一活跃 + 多备用
1. 选其中一个 key 作为「活跃 key」，将其写入 `models.json`（该 key 在线可用）。
2. 其余 key 作为「备用 key」，存一份本地清单文件，不写入配置。
3. 当活跃 key 余额将用完或过期时，手动轮换：编辑 `models.json` 中 `vendor: "tokenrhythm"` 两条记录的 `apiKey`，替换为下一个备用 key 的 `sk_tr_`，重启 WorkBuddy/CodeBuddy 生效。

### 备用清单文件模板
```
# tokenrhythm 备用 Key 清单

| 标签 | 手机 | 余额 | 到期时间 |
|---|---|---|---|
| tr1 | 170xxxxxxx | ¥68.00 | 2026-09-22 |
| tr2 | 170xxxxxxx | ¥68.00 | 2026-09-22 |

- tr1（已激活）
  - sess: sess_xxx
  - sk: sk_tr_xxx
- tr2（备用）
  - sess: sess_xxx
  - sk: sk_tr_xxx
```

清单放在 `E:\codex\niannianai\outputs\` 或用户指定的位置。清单包含完整 sess + sk（本机备份），不对外回显。

### 轮换操作
1. 打开 `%USERPROFILE%\.workbuddy\models.json` 和 `%USERPROFILE%\.codebuddy\models.json`。
2. 找到 `vendor: "tokenrhythm"` 的两条记录（glm-5.2 / deepseek-v4-flash）。
3. 把 `apiKey` 字段替换为下一个备用 key 的 `sk_tr_`。
4. 校验 JSON 合法 + id 唯一。
5. 重启 WorkBuddy / CodeBuddy。

---

## 四、安全与隐私
- 不要把完整 `sess_` / `sk_tr_` 明文回显到外部对话或日志；最终回复最多显示前 4 位 + 后 4 位。
- 临时脚本用完即删。
- 额度查询是只读 GET，无副作用，可放心执行。
- 凭据由用户提供并仅用于本次操作，不持久化保存（除非用户明确要求写入清单文件）。
- 备用清单是本机备份，包含完整凭据，不要上传到外部。

---
name: models-vision-routing
summary: 给 WorkBuddy/CodeBuddy 自定义模型配置补视觉能力——为纯文本模型配置 relatedModels.vision，让图片任务自动路由到视觉底座，避免 image_url 报错。
description: |
  当用户提到"自定义模型遇到图片报错""纯文本模型不支持 image_url""给模型补视觉能力"
  "relatedModels.vision" "models.json 视觉路由" 时使用。
  解决的问题：WorkBuddy/CodeBuddy 的自定义模型若 lacks supportsImages:true，遇到图片输入会直接报错；
  通过 relatedModels.vision 字段把图片任务路由到已支持视觉的模型。
---

# 自定义模型补视觉能力（relatedModels.vision）

## 问题
WorkBuddy / CodeBuddy 的自定义模型（`models.json` 中的条目），若没有 `"supportsImages": true`，
遇到图片输入会报错——因为该模型本身不支持 `image_url` 消息。

## 官方解决方案
`models.json` 的 `relatedModels.vision` 字段：给纯文本模型指定一个**视觉模型**，
WorkBuddy 遇到图片时自动把视觉任务路由过去，纯文本对话不受影响。

## 配置文件位置
- `%USERPROFILE%\.workbuddy\models.json`
- `%USERPROFILE%\.codebuddy\models.json`

两份可能不一致，务必**两份都检查、都改**，最后核对一致性。

## 操作步骤

### 1. 找纯文本模型
找出所有**没有** `"supportsImages": true` 的模型。

### 2. 确认视觉底座存在
配置里必须有一个 `"supportsImages": true` 的模型作为视觉底座，例如 `qwen3.8-max`、`glm-5.2` 等。
选一个**长期在线、确认支持视觉**的，作为路由目标（推荐 tokenrhythm 的 `qwen3.8-max`）。

### 3. 加 `relatedModels.vision`
对每个纯文本模型追加：
```json
"relatedModels": { "vision": "qwen3.8-max" }
```
`vision` 的值 = 视觉模型的 `id`（必须真实存在于同文件，否则路由悬空）。

### 4. 验证
- JSON 合法性 + 无重复 id（id 必须全局唯一）。
- 所有纯文本模型都已配 vision；所有 vision 指向的 id 确实存在。
- 两份文件（.workbuddy / .codebuddy）同 id 的 supportsImages 与 relatedModels 一致。
- 向视觉底座发图片请求确认真能看图：
```bash
IMG=$(base64 -w0 your.png)
curl https://<视觉模型url>/v1/chat/completions \
  -H "Authorization: Bearer <视觉模型apiKey>" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"<视觉模型id>\",\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"描述这张图\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"data:image/png;base64,$IMG\"}}]}],\"max_tokens\":512}"
```
返回 200 且含 `image_tokens` 即成功。

## 注意事项
- `models.json` 热重载（约 1 秒），无需重启客户端。
- `relatedModels.vision` 仅路由图片任务，不影响纯文本模型正常对话。
- 部分模型有思考模式，测试时 `max_tokens` 至少 512，否则输出可能被思考 token 占满。
- **改前备份**：`cp models.json models.json.bak-YYYYMMDD`。
- 测试图不要用 1×1 透明 PNG——上游常报「image format illegal」。用 ≥16×16 的实色 PNG（node 现造即可）。
- 跨文件一致性最易漏：同一模型在两份里 supportsImages 必须一致，否则一边能看图一边报错。

## 关键坑：前端 supportsImages 拦截会绕过 relatedModels 路由
- **现象**：模型已配 `relatedModels.vision`，但软件仍弹"该模型不支持图片 / 不支持 image_url"。
- **根因**：WorkBuddy/CodeBuddy 前端在发请求**前**就按 `supportsImages:false` 拦掉图片输入，
  `relatedModels.vision` 的路由逻辑根本没机会执行。也就是说，纯靠 relatedModels 无法突破前端拦截。
- **判别方法（关键，别只看状态码）**：直接向该模型的渠道 URL 发一张正常 PNG（≥16×16 实色），
  必须确认响应**含 `image_tokens` 或 `content` 真正作答**才算支持图。
  ⚠️ 陷阱：有的上游对带图的请求返回 HTTP 200 但 `content` 为空、只有 `reasoning_content`，
  那是"把图当纯文本 prompt 在推理"的**假成功**，并非真正读图；真不支持图时会返回
  `400001 / "Model do not support image input"`。务必按 400 或真读图结果判定。
- **最稳修法（两种情况）**：
  1. 实测渠道**确实支持图**（响应真读图）→ 直接把该模型 `"supportsImages": false` 改成 `true`，前端不拦截、图直发渠道。
  2. 实测渠道**不支持图**（返回 400001）→ **绝对不能**把 supportsImages 置 true（否则请求出 400 被上游拒）。
     应保留 `supportsImages: false` + `relatedModels.vision` 指向一个真正支持图的底座（底座自身 supportsImages 必须 true）。
     但前端在 supportsImages=false 时会先拦、路由是否触发取决于客户端版本——**此处存在不确定**，需实测：
     若客户端版本不触发路由，则只能让用户发图时直接选视觉底座模型，或给该渠道另加一个支持图的模型 id。
- 结论：先判渠道是否真支持图（看 400 / image_tokens，别只看 200）；支持才置 true，不支持就靠路由或改用底座。

## 已落地的路由（tr4 激活期）
- 视觉底座：`qwen3.8-max`（tokenrhythm）
- 已配 vision 路由的纯文本模型：`codex-auto-review`、`deepseek-v4-flash`、`glm-5.2`(tokenrhythm)、`grok-4.5`、`grok-4.6`、`gpt-5.6-luna`

---
name: qingli-skill
description: Analyze, compare, preview, and safely clean Windows disk space. Use when a user asks to inspect a full C drive, find large files, compare disk growth, remove temporary files or caches, clean Windows update leftovers, migrate growing application data, or schedule low-risk maintenance. This unified skill routes the request through four bundled community backends and keeps deletion separate from read-only analysis.
---

# 清理Skill

Use this skill as a unified router for four bundled Windows disk-space projects. The default operation is read-only analysis or dry-run preview. Never run several destructive cleaners against the same drive in one pass because their targets overlap.

## Operating modes

- `scan`: inspect the drive and report what consumes space. No deletion.
- `preview`: run each backend's safe preview or dry-run mode and compare overlap. No deletion.
- `clean`: execute only the user-selected cleanup level through the most suitable backend, then verify free space.
- `migrate`: move a user-controlled, high-growth directory to another drive with a rollback path or junction.
- `schedule`: schedule only low-risk maintenance after the user gives a recurrence and threshold.

When the user says only "clean my C drive", map it to `scan` followed by `preview`. If the user explicitly asks to delete or clean, show the categories and estimated space first, then execute only the selected categories. Protect documents, desktop files, photos, videos, music, downloads, chat databases, backups, restore points, `pagefile.sys`, `swapfile.sys`, `C:\Windows\WinSxS`, `C:\Windows\Installer`, drivers, security databases, and the current agent runtime by default.

## Backend selection

1. **Audit and migration:** `providers/vhaozheng` (`windows-disk-cleanup`). Use for top directories, largest files, saved baselines, growth comparison, and migration suggestions. It is the preferred backend when the real problem is a directory that keeps growing.
2. **Risk-classified Windows cleanup:** `providers/scauyjj` (`windows-disk-cleaner`). Use as the primary cleanup backend. It has L0-L4 levels, reusable JSON plans, allowlists, application-specific patterns, dry-run support, and verification.
3. **Module-based PowerShell cleanup:** `providers/orzcls` (`win-disk-cleaner`). Use for an explicit preview of temp files, recycle bin, update cache, browser/app/developer caches, hibernation, WinSxS, and restore-point modules. Always pass skip flags for hibernation, WinSxS, and restore points during comparison unless the user specifically selects them.
4. **Cross-platform Python analysis:** `providers/gccszs` (`disk-cleaner`). Use for bounded sampling, progressive scans, duplicate detection, growth analysis, monitoring, and a second opinion. Run its quick sample before a full scan on a large drive.

## Required workflow

### 1. Preflight

Check Windows version, current free space, target drives, administrator status, and whether the user needs hibernation, sleep, restore points, chat history, Docker, WSL, or developer caches. Do not force-stop applications or change permissions.

Before running a Python backend, validate the interpreter itself rather than trusting command resolution. Run the resolved executable with `--version` and require a successful exit plus a `Python` version string. If `python` resolves to a WindowsApps placeholder or returns no usable output, try `py -3` or locate an installed runtime such as a Conda or standalone Python installation, then pass that explicit executable to the backend. Capture stderr as well as stdout; an empty result, non-zero exit, or invalid JSON means the backend did not run and must not be reported as a successful cleanup.

### 2. Scan or preview

Run the following from this skill directory. Replace `C:` only when the user names another drive.

```powershell
$skillRoot = 'C:\Users\lsb\.codex\skills\qingli-skill'

# Backend 1: audit scan
powershell -ExecutionPolicy Bypass -File "$skillRoot\providers\vhaozheng\scripts\scan_disk_usage.ps1" -Drive C

# Backend 2: fast scan and reusable cleanup plan
powershell -ExecutionPolicy Bypass -File "$skillRoot\providers\scauyjj\scripts\scan_space.ps1" -Drives C: -Mode Fast

# Backend 3: module preview, excluding the highest-risk modules
powershell -ExecutionPolicy Bypass -File "$skillRoot\providers\orzcls\scripts\disk_cleaner.ps1" -DryRun -SkipHibernation -SkipWinSxS -SkipRestorePoints

# Backend 4: bounded Python sample and analysis
& $python "$skillRoot\providers\gccszs\scripts\analyze_disk.py" --sample --path C: --json
& $python "$skillRoot\providers\gccszs\scripts\analyze_disk.py" --path C: --file-limit 10000 --time-limit 30 --json
& $python "$skillRoot\providers\gccszs\scripts\clean_disk.py" --dry-run
```

If a backend needs administrator rights, report that it was skipped and continue with the other read-only backends. Do not turn an elevation failure into permission changes.

### 3. Normalize results

Deduplicate paths and group results into: disposable cache/temp data; safe only after closing an application; review-first app data; user files to move or archive; Windows-managed paths to leave alone. Report the top three categories, estimated recoverable space, and conflicts between backends. Do not claim that a scan result is deleted space.

### 4. Execute one selected cleanup path

Prefer the `scauyjj` plan for normal Windows cleanup:

```powershell
powershell -ExecutionPolicy Bypass -File "$skillRoot\providers\scauyjj\scripts\clean_space.ps1" -PlanPath '<plan path from scan>' -DryRun
```

Remove `-DryRun` only after the user has selected the categories and the plan is current. For application data migration, use the migration backend only after checking the destination drive, closing the application, copying and verifying the data, creating the junction, and recording restore instructions.

### 5. Verify

Recheck free space, confirm the intended directories changed, record skipped or protected items, and report errors. For Python backends, require non-empty valid JSON and inspect its reported counts before accepting the run. Never report success from an exit code alone if the free-space measurement did not change or the path remains present.

## Safety rules

- Never manually delete `C:\Windows\WinSxS`, `C:\Windows\Installer`, `Program Files`, drivers, security software data, `pagefile.sys`, or `swapfile.sys`.
- Use Windows-native cleanup or DISM for Windows-managed component storage.
- Treat `Windows.old`, hibernation, restore points, package-manager caches, Docker/WSL images, browser profiles, and chat/application data as review-first or explicit-confirmation targets.
- Do not delete Downloads, Desktop, Documents, Photos, Videos, Music, backups, or chat databases as part of an automatic cleanup.
- Do not run the four destructive backends sequentially. Use all four for analysis/preview, then one selected executor for cleanup.
- Preserve the source manifest in `references/source-manifest.md` when updating bundled providers.

## Bundled resources

- `providers/vhaozheng`: audit, baseline comparison, destination suggestions, junction migration.
- `providers/scauyjj`: Windows risk classification, cleanup plans, application patterns, migration, and scheduling.
- `providers/orzcls`: modular PowerShell dry-run cleaner and free-tool references.
- `providers/gccszs`: Python analysis, progressive scanning, duplicate detection, monitoring, and dry-run cleanup.
- `references/source-manifest.md`: GitHub URLs, commit pins, and integration notes.

---
name: disk-backup-vault
description: 本地磁盘重要资料备份库。用于把一台电脑上有价值的内容按 P0/P1/P2 分类、只读复制到异地/异盘备份根、生成索引清单与完整性校验，并明确“备份优先于清理”的安全边界。触发词：备份电脑、打包资料、迁移文件、整理磁盘、防止丢失、做个备份、把重要文件拷到别的盘。
agent_created: true
---

# disk-backup-vault｜本地资料备份库

把“有价值但怕丢”的本地资料，按价值分级、只读复制到备份根（另一块盘/网盘/移动硬盘），并产出可还原的索引。本 Skill **只复制、不删除**；清理动作必须发生在备份完成且确认冗余之后。

## 何时使用

- 用户说“把电脑有用的东西备份一下”“打包重要资料”“防止电脑东西被删”
- 换电脑、重装系统、磁盘快满、担心误删前，先做备份
- 想建立定期备份习惯，把备份变成可复用流程

## 核心原则（硬边界）

1. **只读复制**：所有操作是 copy/robocopy，绝不 `rm`、绝不移动源文件。
2. **备份优先于清理**：任何“删掉腾空间”只能在对应目录已备份且用户确认冗余后发生。先删后补是禁止的。
3. **分级不分家**：P0/P1/P2 都进入同一备份根的不同子目录，互不覆盖。
4. **索引即资产**：没有 `00_INDEX.md` 的备份库视为未完成。
5. **不备份可再生物**：缓存、临时文件、包管理器仓库、conda/anaconda 环境、WSL 发行版（除非用户明确要）不纳入，避免备份库膨胀。
6. **排除运行中的系统目录**：WSL、正在运行的程序数据、页面文件等不强制备份；若用户坚持，单独确认再处理。

## 备份分级

| 级别 | 定义 | 典型内容 |
|---|---|---|
| **P0 系统核心** | 丢了无法重建、决定“你是谁”的资产 | 工作记忆 `.workbuddy/memory`、用户级 Skill、知识卡、项目契约 AGENTS.md、长期配置 |
| **P1 文档项目** | 高重建成本、日常依赖 | 笔记库（Obsidian 等）、项目文档、会话历史、桌面文件、代码仓库 |
| **P2 媒体素材** | 体积大、可重新生成但耗时 | 图片素材库、视频素材、AI 生成资产、设计源文件 |

## 标准流程

1. **预检**：确认源盘、目标盘、可用空间、是否管理员。目标盘空间应远大于待备份量。
2. **建结构**：在备份根建 `P0_系统核心/`、`P1_文档项目/`、`P2_媒体素材/` 和 `00_INDEX.md`。
3. **分类复制**：
   - P0 用普通 `cp -r`（量小、需完整）。
   - P1/P2 用 `robocopy <src> <dst> /E /R:0 /W:1 /XJ /MT:16`，长路径更稳；用 `/XD` 排除已知垃圾（如 `.tmp`、`xwechat_files`、`BaiduNetdiskTmp`）。
   - 锁定文件跳过即可，不中断整体任务。
4. **生成索引**：写 `00_INDEX.md`，逐类记录来源路径、大小、文件数、排除项、还原方法、备份时间。
5. **完整性校验**：对比源/备文件数与总大小；对 P0 关键文件抽样比对。
6. **可选归档**：若需上传网盘，把 P0/P1 打成 zip（用 `python -m zipfile`）；P2 媒体按需单独处理。
7. **安全收尾**：明确告知用户“已复制、未删除”；如需清理某目录，单独确认。

## 排除清单（默认不备份）

- `AppData` 下的缓存：`npm-cache`、`pip/cache`、`ms-playwright`、各应用 `Cache`
- `Local\Temp` 全部
- `anaconda3`、`miniconda`、Python 虚拟环境
- `.gradle/caches`、`.nuget/packages`、`.cargo/registry`、`.rustup`
- `Local\wsl`、`docker-desktop` 数据（运行中使用）
- 系统目录 `C:\Windows`、`Program Files`、`pagefile.sys`、`swapfile.sys`
- 聊天软件的庞大数据（如 `xwechat_files`）默认排除，注明“可客户端重登同步”

## 与清理类 Skill 的边界

- 本 Skill 不删除、不调用磁盘清理器。
- 若用户想“备份完再清理腾空间”，先完成本 Skill 全流程并确认备份库可读，再单独推进清理，清理前每个目录逐一确认。
- 清理类能力见 `qingli-skill`，但必须在本 Skill 之后使用。

## 索引模板

见 `references/backup-index-template.md`；分类细则见 `references/backup-classification.md`；安全规则见 `references/safety-rules.md`。

---
name: skill-optimizer
description: "Diagnose and optimize Agent Skills (SKILL.md) with real session data and research-backed static analysis. Use when auditing skill quality, checking trigger/undertrigger problems, or reviewing SKILL.md structure. Works with WorkBuddy, Claude Code, Codex, and any Agent Skills-compatible agent."
risk: safe
source: hqhq1025/skill-optimizer (MIT)，WorkBuddy 适配版
date_added: "2026-08-24"
---

## When to Use This Skill

- Use when skills are not triggering as expected or seem broken
- Use when you want to audit and improve your skill library's quality
- Use when you want to understand which skills are underperforming or wasting context tokens

## Rules

- **Read-only**: never modify skill files. Only output report.
- **All 8 dimensions**: do not skip any. If data is insufficient, report "N/A — insufficient session data" rather than omitting.
- **Quantify**: "you had 12 research tasks last week but the skill never triggered" beats "you often do research".
- **Suggest, don't prescribe**: give specific wording suggestions for description improvements, but frame as suggestions.
- **Show evidence**: for undertrigger claims, quote the actual user message that should have triggered the skill.
- **Evidence-based suggestions**: when suggesting description rewrites, cite the specific research finding that motivates the change (e.g., "front-load trigger keywords — MCP study shows 3.6x selection rate improvement").

## Overview

Analyze skills using **historical session data + static quality checks**, output a diagnostic report with P0/P1/P2 prioritized fixes. Scores each skill on a 5-point composite scale across 8 dimensions.

CSO (Claude/Agent Search Optimization) = writing skill descriptions so agents select the right skill at the right time. This skill checks for CSO violations.

## Usage

- `/optimize-skill` → scan all skills
- `/optimize-skill my-skill` → single skill
- `/optimize-skill skill-a skill-b` → multiple specified skills

## Data Sources

Auto-detect the current agent platform and scan the corresponding paths:

| Source | WorkBuddy | Claude Code | Codex | Shared |
|--------|-----------|------------|-------|--------|
| Session transcripts | `~/.workbuddy/sessions/*.json`（按会话 ID 存 JSON，非 JSONL；结构未公开，解析失败时按规则报 N/A）；`~/.workbuddy/audit-log/*.jsonl`（工具审计日志，可作调用证据） | `~/.claude/projects/**/*.jsonl` | `~/.codex/sessions/**/*.jsonl` | — |
| Skill files | `~/.workbuddy/skills/*/SKILL.md` | `~/.claude/skills/*/SKILL.md` | `~/.codex/skills/*/SKILL.md` | `~/.agents/skills/*/SKILL.md` |

**Platform detection:** Check which directories exist. Scan all available sources — a user may have multiple agents installed. WorkBuddy 会话 JSON 结构未知时，不要猜测字段；改用 audit-log JSONL 与静态维度出报告，会话维度标 N/A。

## Workflow

```
Identify target skills
        ↓
Collect session data (python3 scripts scan JSONL transcripts)
        ↓
Run 8 analysis dimensions
        ↓
Compute composite scores
        ↓
Output report with P0/P1/P2
```

### Step 1: Identify Target Skills

Scan skill directories in order: `~/.workbuddy/skills/`, `~/.claude/skills/`, `~/.codex/skills/`, `~/.agents/skills/`. Deduplicate by skill name (same name in multiple locations = same skill). For each, read `SKILL.md` and extract:
- name, description (from YAML frontmatter)
- trigger keywords (from description field)
- defined workflow steps (Step 1/2/3... or ### sections under Workflow)
- word count

If user specified skill names, filter to only those.

### Step 2: Collect Session Data

Use python3 scripts via Bash to scan session JSONL files. Extract:

**Claude Code sessions** (`~/.claude/projects/**/*.jsonl`):
- `Skill` tool_use calls (which skills were invoked)
- User messages (full text)
- Assistant messages after skill invocation (for workflow tracking)
- User messages after skill invocation (for reaction analysis)

**Codex sessions** (`~/.codex/sessions/**/*.jsonl`):
- `session_meta` events → extract `base_instructions` for skill loading evidence
- `response_item` events → assistant outputs (workflow tracking)
- `event_msg` events → tool execution and skill-related events
- User messages from `turn_context` events (for reaction analysis)

**Note:** Codex injects skills via context rather than explicit `Skill` tool calls. Skill loading (present in `base_instructions`) does NOT equal active invocation. To detect actual use, search for skill-specific workflow markers (step headers, output formats) in `response_item` content within that session. A skill is "invoked" only if the agent produced output following the skill's defined workflow.

**Aggregated:**
- Per-skill: invocation count, trigger keyword match count
- Per-skill: user reaction sentiment after invocation
- Per-skill: workflow step completion markers

### Step 3: Run 8 Analysis Dimensions

**You MUST run ALL 8 dimensions.** The baseline behavior without this skill is to skip dimensions 4.2, 4.3, 4.5b, and 4.8. These are the most valuable dimensions — do not skip them.

#### 4.1 Trigger Rate

Count how many times each skill was actually invoked vs how many times its trigger keywords appeared in user messages.

**Claude Code:** count `Skill` tool_use calls in transcripts.
**Codex:** count sessions where the agent produced output following the skill's workflow markers (not merely loaded in context).

**Diagnose:**
- Never triggered → skill may be useless or trigger words wrong
- Keywords match >> actual invocations → undertrigger problem, description needs work
- High frequency → core skill, worth optimizing

#### 4.2 Post-Invocation User Reaction

**This dimension is critical and easy to skip. Do not skip it.**

After a skill is invoked in a session, read the user's next 3 messages. Classify:
- **Negative**: "no", "wrong", "never mind", "not what I wanted", user interrupts
- **Correction**: user re-describes their intent, manually overrides skill output
- **Positive**: "good", "ok", "continue", "nice", user follows the workflow
- **Silent switch**: user changes topic entirely (likely false positive trigger)

Report per-skill satisfaction rate.

#### 4.3 Workflow Completion Rate

**This dimension is critical and easy to skip. Do not skip it.**

For each skill invocation found in session data:
1. Extract the skill's defined steps from SKILL.md
2. Search the assistant messages in that session for step markers (Step N, specific output formats defined in the skill)
3. Calculate: how far did execution get?

Report: `{skill-name} (N steps): avg completed Step X/N (Y%)`

If a specific step is frequently where execution stops, flag it.

#### 4.4 Static Quality Analysis

Check each SKILL.md against these 14 rules:

| Check | Pass Criteria |
|-------|--------------|
| Frontmatter format | Only `name` + `description`, total < 1024 chars |
| Name format | Letters, numbers, hyphens only |
| Description trigger | Starts with "Use when..." or has explicit trigger conditions |
| Description workflow leak | Description does NOT summarize the skill's workflow steps (CSO violation) |
| Description pushiness | Description actively claims scenarios where it should be used, not just passive |
| Overview section | Present |
| Rules section | Present |
| MUST/NEVER density | Count ALL-CAPS directive words; >5 per 100 words = flag |
| Word count | < 500 words (flag if over) |
| Narrative anti-pattern | No "In session X, we found..." storytelling |
| YAML quoting safety | description containing `: ` must be wrapped in double quotes |
| Critical info position | Core trigger conditions and primary actions must be in the first 20% of SKILL.md |
| Description 250-char check | Primary trigger keywords must appear within the first 250 characters of description |
| Trigger condition count | ≤ 2 trigger conditions in description is ideal |

#### 4.5a False Positive Rate (Overtrigger)

Skill was invoked but user immediately rejected or ignored it.

#### 4.5b Undertrigger Detection

**This is the highest-value dimension.** For each skill, extract its **capability keywords** (not just trigger keywords — what the skill CAN do). Then scan user messages for tasks that match those capabilities but where the skill was NOT invoked.

Report: which user messages SHOULD have triggered the skill but didn't, and suggest description improvements.

**Compounding Risk Assessment:**
For skills with chronic undertriggering (0 triggers across 5+ sessions where relevant tasks appeared), flag as "compounding risk" — undertriggered skills cannot self-improve through usage feedback, causing the gap to widen over time. Recommend immediate description rewrite as P0.

#### 4.6 Cross-Skill Conflicts

Compare all skill pairs:
- Trigger keyword overlap (same keywords in two descriptions)
- Workflow overlap (two skills teach similar processes)
- Contradictory guidance

#### 4.7 Environment Consistency

For each skill, extract referenced:
- File paths → check if they exist (`test -e`)
- CLI tools → check if installed (`which`)
- Directories → check if they exist

Flag any broken references.

#### 4.8 Token Economics

**This dimension is critical and easy to skip. Do not skip it.**

For each skill:
- Word count (from Step 1)
- Trigger frequency (from 4.1)
- Cost-effectiveness = trigger count / word count
- Flag: large + never-triggered skills as candidates for removal or compression

**Progressive Disclosure Tier Check:**
Evaluate each skill against the 3-tier loading model:
- Tier 1 (frontmatter): ~100 tokens. Check: is description ≤ 1024 chars?
- Tier 2 (SKILL.md body): <500 lines recommended. Check: word count.
- Tier 3 (reference files): loaded on demand. Check: does skill use reference files for detailed content, or cram everything into SKILL.md?

Flag skills that put 500+ words in SKILL.md without using reference files as "poor progressive disclosure".

### Step 4: Composite Score

Rate each skill on a 5-point scale:

| Score | Meaning |
|-------|---------|
| 5 | Healthy: high trigger rate, positive reactions, complete workflows, clean static |
| 4 | Good: minor issues in 1-2 dimensions |
| 3 | Needs attention: significant gap in 1 dimension or minor gaps in 3+ |
| 2 | Problematic: never triggered, or negative user reactions, or major static issues |
| 1 | Broken: doesn't work, references missing, or fundamentally misaligned |

**Scored dimensions** (weighted average):
- Trigger rate: 25%
- User reaction: 20%
- Workflow completion: 15%
- Static quality: 15%
- Undertrigger: 15%
- Token economics: 10%

**Qualitative dimensions** (reported but not scored):
- 4.5a Overtrigger: reported as count + examples
- 4.6 Cross-Skill Conflicts: reported as conflict pairs
- 4.7 Environment Consistency: reported as pass/fail per reference

## Report Format

```markdown
# Skill Optimization Report
**Date**: {date}
**Scope**: {all / specified skills}
**Session data**: {N} sessions, {date range}

## Overview
| Skill | Triggers | Reaction | Completion | Static | Undertrigger | Token | Score |
|-------|----------|----------|------------|--------|--------------|-------|-------|
| example-skill | 2 | 100% | 86% | B+ | 1 miss | 486w | 4/5 |

## P0 Fixes (blocking usage)
1. ...

## P1 Improvements (better experience)
1. ...

## P2 Optional Optimizations
1. ...

## Per-Skill Diagnostics
### {skill-name}
#### 4.1 Trigger Rate
...
#### 4.2 User Reaction
...
(all 8 dimensions)
```

## Research Background

The analysis dimensions in this report are grounded in the following research:
- **Undertrigger detection**: Memento-Skills (arXiv:2603.18743) — skills as structured files require accurate routing; unrouted skills cannot self-improve via the read-write learning loop
- **Description quality**: MCP Description Quality (arXiv:2602.18914) — well-written descriptions achieve 72% tool selection rate vs. 20% random baseline (3.6x improvement)
- **Information position**: Lost in the Middle (Liu et al., TACL 2024) — U-shaped LLM attention curve
- **Format impact**: He et al. (arXiv:2411.10541) — format changes alone can cause 9-40% performance variance
- **Instruction compliance**: IFEval (arXiv:2311.07911) — LLMs struggle with multi-constraint prompts

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

---
name: prompt-vault
description: 提示词管理库。当用户需要搜索、分类、索引、记录使用次数、查看统计或管理提示词时使用。触发词：提示词管理、搜索提示词、找提示词、提示词统计、prompt vault、记录提示词使用、提示词用了几次。
agent_created: true
---

# Prompt Vault - 提示词管理

## 定位

个人提示词积累与管理工具。解决"用过的提示词找不到、效果好的记不住、不知道用了多少次"的问题。自动扫描项目 `prompts/` 目录，建立索引，支持搜索、分类、使用次数统计和评分。

## 核心能力

1. **自动扫描索引**：扫描 `prompts/` 下所有 `.md` 文件，解析标题、用途、模型、效果、日期，建立 JSON 索引
2. **搜索**：按关键词搜索提示词标题、用途、模型、效果和分类
3. **使用次数追踪**：每次使用提示词后记录一次，统计总使用次数和最后使用时间
4. **评分系统**：对提示词效果打分（S+/A/B/C 等）
5. **统计面板**：总数、模板明细、分类明细、使用次数 TOP 10、已评分列表、提炼候选
6. **模板系统**：分类模板 + 适配规则 + 必填字段，减少重复劳动，实现提示词复利
7. **提炼提醒**：使用次数 ≥ 3 且评分 ≥ A 的提示词自动提醒提炼为模板
8. **GitHub 源管理**：收录已知的优质 GitHub 提示词项目，方便查找和参考

## 模板系统（复利核心）

模板是提示词的复利机制：好用的提示词提炼成模板后，后续每次使用都在已有经验上叠加。

### 现有模板

| 模板文件 | 适用场景 | 必填字段数 |
|---|---|---|
| `_template.md` | 基础通用（最小字段集） | 6 |
| `_template_sd25.md` | Seedance 2.5 图生视频/文生视频 | 12 |
| `_template_image_gen.md` | AI 图片生成（MJ/OpenLux） | 12 |
| `_template_ai_video.md` | 其他 AI 视频（Runway/Kling/Veo） | 9 |
| `_template_general.md` | 日常工作（代码审查/文档/分析） | 7 |

### 适配规则

每个模板文件头部有 `<!-- 适配规则 -->` 注释，写明：什么场景用这个模板、填之前必须先确认什么、正文填写注意事项。运行 `templates` 命令可查看全部模板及适配规则。

### 提炼规则（复利闭环）

当一条提示词使用次数 ≥ 3 次且评分 ≥ A 时，`suggest` 命令会提醒提炼为模板：

1. 识别可复用结构（角色/输出格式/约束条件）
2. 把每次变化的部分改成 `{变量名}`
3. 复制 `_template.md` 为 `_template_<细分>.md`，写适配规则
4. 运行 `scan` 更新索引

完整模板规范见 `references/template-rules.md`。

## 提示词库结构

提示词存放在项目根目录 `prompts/` 下，按分类组织：

```
prompts/
├── README.md
├── _template.md                 ← 基础通用模板
├── _template_sd25.md            ← Seedance 2.5 视频模板
├── _template_image_gen.md       ← AI 图片生成模板
├── _template_ai_video.md        ← AI 视频通用模板
├── _template_general.md         ← 日常工作模板
├── ai-video/                    ← AI 视频类
├── seedance-2.5/                 ← Seedance 2.5 专用
├── image-gen/                   ← 图片生成类
└── general-work/                ← 日常工作类
```

每条提示词是一个 `.md` 文件，包含：标题、用途、适用模型、效果备注、使用日期、提示词正文。新建提示词时复制对应分类的模板，按模板内的适配规则填写。

使用次数、评分、GitHub 源和模板索引自动保存在 `C:/Users/lsb/.workbuddy/prompt-vault-indexes/`，不污染项目目录，也避免项目权限影响面板按钮。

## 使用方式

### 扫描并更新索引

当新增或修改提示词文件后，运行：

```bash
python scripts/prompt_vault.py scan
```

### 搜索提示词

```bash
# 搜索包含"国风"的提示词
python scripts/prompt_vault.py search 国风

# 列出全部提示词
python scripts/prompt_vault.py search
```

### 记录使用

每次使用某条提示词后记录一次（路径关键词模糊匹配）：

```bash
python scripts/prompt_vault.py use guofeng-15s
```

### 设置评分

对提示词效果打分：

```bash
python scripts/prompt_vault.py rate guofeng-15s S+
```

### 查看统计

```bash
python scripts/prompt_vault.py stats
```

输出：总数、模板明细、分类明细、使用次数 TOP 10、已评分列表、模板提炼候选。

### 查看模板与适配规则

```bash
python scripts/prompt_vault.py templates
```

列出全部模板、必填字段数和适配规则，帮助选择该用哪个模板。

### 模板提炼提醒

```bash
python scripts/prompt_vault.py suggest
```

列出使用次数 ≥ 3 且评分 ≥ A 的提示词，提醒提炼为模板（复利闭环）。

### 管理 GitHub 源

查看已收录的 GitHub 提示词管理项目：

```bash
python scripts/prompt_vault.py github
```

添加新的 GitHub 源：

```bash
python scripts/prompt_vault.py add-github PromptDex https://github.com/kristyc/PromptDex "Chrome 右键存提示词"
```

## 新建提示词流程

1. 运行 `python scripts/prompt_vault.py templates` 看该用哪个模板
2. 复制对应模板（如 `_template_sd25.md`）到对应分类目录，去掉文件名前缀改成 `prompt-<描述>.md`
3. 按模板头部适配规则填写必填字段（带 ★ 的）
4. 运行 `python scripts/prompt_vault.py scan` 更新索引
5. 用完后运行 `python scripts/prompt_vault.py use <关键词>` 记录使用
6. 效果好就 `python scripts/prompt_vault.py rate <关键词> S+` 评分
7. 用到 3 次以上且评分 A+，`suggest` 会提醒你提炼成新模板

## 脚本路径

核心脚本：`scripts/prompt_vault.py`

GitHub 源参考：`references/github-sources.md`

模板规范与复利规则：`references/template-rules.md`

## 与外部工具配合

| 工具 | 角色 | 本地路径 |
|---|---|---|
| PromptDex | 浏览器右键快速存 | `tools/PromptDex/` |
| prompts/ 目录 | 长期积累 + Git 版本 | `prompts/` |
| prompts.chat | 自托管搜索 UI + MCP | `tools/prompts-chat-src/` |
| prompt-vault.py | 索引 + 搜索 + 统计 | 本 Skill `scripts/` |
| prompts MCP | WorkBuddy 直接搜索/保存 | 本 Skill `scripts/prompts_mcp_server.py` |

日常流程：PromptDex 右键存 → 导出 JSON → 转存为 `prompts/` 下的 `.md` → `scan` 更新索引 → 用完 `use` 记录 → 定期 `stats` 查看哪些好用。

## 对话蒸馏（女娲式提取）

自动从对话记录或外部来源中提取提示词、分类并保存到 prompts.chat。

### 触发

在对话中直接说：
- "把对话里的提示词提取出来"
- "蒸馏一下今天的对话"
- "女娲蒸馏"
- "把刚才的提示词整理一下存起来"
- "帮我把这个链接里的提示词存到库里"（外部来源）
- "导入这个 GitHub 仓库的提示词"

### 工作流

1. **获取内容** — 对话记录 / 网页链接 / GitHub 仓库 / 粘贴文本
2. **识别提取** — 找到所有完整提示词、模板、效果评价
3. **分类决策** — 按内容自动分到 `seedance-2-5` / `ai-video` / `ai-image` / `general-work` / `prompt-templates`
4. **去重保存** — 检查是否已存在，调用 MCP `save_prompt` 工具写入
5. **报告** — 输出摘要：来源、提取数、去重数、新增数、分类明细

详细流程见 `references/distill-workflow.md`。

### 命令行工具

```bash
python scripts/save_prompt.py --title "标题" --content "内容" --type VIDEO --description "用途" --category seedance-2-5
```