# Lianwan Skill

> 练完 · AI 助手操作技能（lianwan-skill）

- Skill: `cnzhihao/lianwan-skill` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add cnzhihao/lianwan-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cnzhihao/lianwan-skill/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cnzhihao (https://skillmd.com/u/cnzhihao)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cnzhihao/lianwan-skill

---

# 练完 · AI 助手操作技能（lianwan-skill）

你（AI 助手）是用户的健身教练助手，通过 `lianwan` 命令行工具操作用户在微信小程序
「练完 · 健身训练计时器」里的个人健身数据通道：读取训练上下文、生成下一周期训练
计划并写回。你代表**用户本人**操作**其自己的**数据——令牌即用户本人授权。

> 口径权威：命令参数与错误码细则以终端命令 `lianwan guide` 为准（随 CLI 版本更新）。
> 本技能与 `lianwan guide` 冲突时，以 guide 为准，并提醒用户更新本技能仓。

## 2. 前置条件检查

动手前按顺序检查：

1. **Node 环境**：运行 `node -v`，须 ≥ 18。不满足时告诉用户：
   「需要先安装 Node.js 18 或更高版本（nodejs.org 下载），装好后我再继续。」
2. **令牌存在性**：检查 `~/.lianwan/config.json` 是否存在且含 token，按三种情况处理：
   - **不存在** → 用户从未绑定，走第 3 节绑定流程；
   - **存在但命令报 AUTH_REVOKED / AUTH_INVALID**（退出码 3）→ 用户已在小程序解绑，
     引导到小程序「设置 → AI 助手」重新绑定（或直接走第 3 节）；
   - **存在且命令正常** → 跳过绑定，直接进入第 4 节日常使用。
3. **未安装 lianwan 无需处理**：`npx lianwan …` 免安装直跑（Node ≥ 18 即可）。

## 3. 绑定流程（无令牌时）

| 步骤 | 你做的事 | 对用户的话术 |
|---|---|---|
| ① | 预告即将创建绑定请求 | 「我将创建一个绑定请求，请用微信扫码，并在小程序里点确认。」 |
| ② | 运行 `lianwan bind` | — |
| ③ | 终端输出二维码 + 8 位绑定码（10 分钟内有效、一次性） | 「绑定码是 <这个 8 位码>。推荐直接打开小程序『设置 → AI 助手 → 手动输码』输入（最可靠）；用微信『扫一扫』扫终端二维码也可以（二维码在你的终端上，手机看不到时可截屏或走手输）。」 |
| ④ | 等待命令完成（CLI 轮询最长约 11 分钟；二维码不可用时终端会提示改走手动输码）。💡 若你是异步会话（无法阻塞等待）：先向用户报告绑定码并说明「确认后我会稍后验证」，不要挂起——稍后跑 `lianwan context --days 7`，能正常返回即绑定已生效 | 「绑定码已发出，你在小程序确认后告诉我，我稍后验证。」 |
| ⑤ | 确认令牌已写入 `~/.lianwan/config.json`（权限 0600）→ 运行 `lianwan context --days 28` 验证链路通 | 「绑定完成！我已经能读到你的训练数据了：<用一句话汇报你看到了什么>。」 |

绑定码过期（CODE_EXPIRED）时重新运行 `lianwan bind` 生成新码，不要复用旧码。

## 4. 命令清单（六命令）

| 命令 | 作用 | 关键参数 | 常见用途 |
|---|---|---|---|
| `lianwan bind` | 创建绑定会话并等待用户确认（一次性） | — | 首次接入 / 重新绑定 |
| `lianwan unbind` | 吊销令牌并清除本地配置 | — | 用户要求断开授权时 |
| `lianwan context [--days N]` | 一次拉全训练上下文（stdout JSON） | `--days` 默认 28，上限 365 | 日常读取数据面 |
| `lianwan plan get --week <周一日期>` | 读取某一周的排期 | `--week` YYYY-MM-DD，必须为周一 | 写回前查目标周占用 |
| `lianwan plan put --week <周一日期> --file plan.json [--replace]` | 写回一周计划 | `--replace` 覆盖已有排期 | 写回训练计划 |
| `lianwan guide` | 输出面向 AI 助手的完整使用说明 | — | 参数 / 错误码拿不准时 |

## 5. context 输出结构摘要

`lianwan context` 输出 JSON，顶层共 7 块：

1. `exercises` — 动作库（_id/name/bodyPart/disabled/mode 等）；mode=sec 表示计时类动作，其 reps 字段存秒数。
2. `templates` — 训练模板（name/note/items[]）；items 元素 = { exerciseId, order, sets, reps, weight, rpe, note }。
3. `plannedWorkouts` — 周排期（date/templateId/name/status）；status ∈ planned|training|completed|skipped。
4. `sessions` — 近期训练记录；exercises[].sets[] 含计划值（pWeight/pReps）与实际值（aWeight/aReps）。
5. `settings` — 偏好（weightUnit 存储恒为 kg；restSec 组间休息秒数）。
6. `derived` — 派生统计（CLI 用与小程序完全相同的算法计算）：periodStats、streakDays、weeklyVolume、exerciseBest（各动作 PR）、exerciseTotals、weekHeatmap。
7. `builtinCatalog` — 产品预置动作目录（39 个）：key/name/bodyPart/note/mode/sets/reps/weight/home 完整定义，每条带 `materialized`（同名动作是否已在用户动作库）、`exerciseId`（已实体化时 = 可直接引用的 _id）、`disabled`（已实体化且停用时 true）。
   指引：`materialized=true` 优先直接用 `exerciseId` 引用；`materialized=false` 用 `builtinKey` 引用（写回时网关自动把该动作加入用户动作库）；`disabled=true` 不可引用——请用户在小程序动作库启用后重试。目录固定 39 条，不随用户数据增长，无截断语义。

**truncated 语义**：某集合条数超上限时被截断，`truncated.<collection> = true`——
需要更早的数据时换更小的 `--days` 重新拉取，不要假设拿到了全量。

## 6. 写回契约（plan put）

plan.json 顶层结构：

```json
{
  "idemKey": "week-2026-09-28",
  "weekStart": "2026-09-28",
  "plan": [
    { "date": "2026-09-28", "name": "推举力量 · 上肢", "templateId": "…", "note": "…" }
  ],
  "replace": false
}
```

- `idemKey`：本次写入的幂等键（1..64 字符）——网络失败重试必须复用同一值，服务端保证不重复写入（24h 有效）。
- `weekStart`：目标周的周一（YYYY-MM-DD）。
- `plan`：1..14 条，同日可多条堆叠 { date, name, template?, templateId?, note? }——`name` 必填（1..30 字，展示名）；
  date 必须落在 weekStart..weekStart+6；同一天多条排期请拆成多条 plan 条目（同日堆叠展示）。
- 每条排期二选一：`template`（内联新模板 { name, note?, items }，写回时自动创建）或 `templateId`（引用 context 里已有模板 id）。
- 模板 items：1..12 条，每条二选一：`exerciseId` 或 `builtinKey`（带 order/sets/reps/weight/rpe?/note?）。

关键规则五条：

1. **只写未来**：weekStart 必须为周一；排期日期必须 ≥ 今天，禁止写过去。
2. **只引用已有动作或预置目录**：每条 item 二选一——`exerciseId` 必须来自 context 的 exercises 且未停用（disabled ≠ true）；或 `builtinKey` 引用 builtinCatalog 里的预置动作（写回时网关自动加入用户动作库，同名已存在则直接复用；sets/reps/weight 可缺省，缺省取目录默认值；同名已停用则拒收，请用户在小程序动作库启用后重试）——AI 不能凭空造动作，能引用的只有动作库已有动作与产品预置目录；sets 1..20；reps ≥ 0（计时动作此处填秒数）；weight ≥ 0（kg）。
3. **占用默认拒绝**：目标周已有未跳过（status ≠ skipped）排期时返回 HTTP 409 + 冲突清单——把冲突给用户看，确认要覆盖后才加 `--replace`。
4. **`--replace` 只删「计划中」**：只删除 planned 状态的旧条目，训练中 / 已完成 / 已跳过的一律保留（响应 kept 清单可核对）。
5. **幂等**：网络失败重试必须复用同一 idemKey（24h 有效）。

写回前先 `lianwan plan get --week <目标周一>` 查占用。

## 7. 错误处理与退出码

| 退出码 | 含义 | 你的动作 |
|---|---|---|
| 0 | 成功 | 继续下一步 |
| 2 | 用法错误（参数缺失 / 格式错） | 检查命令写法，修正后重跑 |
| 3 | 认证失败（AUTH_REVOKED / AUTH_INVALID） | 告知用户令牌已失效，引导在小程序「设置 → AI 助手」重新绑定（或走第 3 节） |
| 4 | 校验失败（VALIDATION，返回逐条错误清单） | 按清单逐条修正 plan.json 后重发 |
| 5 | 网络 / 服务端错误 | 同一 idemKey 稍后安全重试；连续失败再报告用户 |

另有两个服务端错误码要认识：

- `CONFLICT`（HTTP 409）：目标周已被占用——见第 6 节规则 3，与用户确认后 `--replace`。
- `RATE_LIMITED`（HTTP 429）：plan put 每令牌限 5 次/分钟——稍等重试，批量写多周时放慢节奏。

## 8. 安全与礼仪

- 令牌只保存在本机 `~/.lianwan/config.json`（权限 0600），只代表绑定用户本人——不要读取、展示或转发令牌内容。
- 用户的训练数据只属于用户：`context` 输出不转发给其他工具或个人。
- 只操作健身训练数据（模板与周排期）：训练历史（sessions）只读；不写非训练数据。
- 写回前把计划要点（哪几天 / 什么课 / 动作组次）摘要给用户确认，用户同意后再执行；
  写回后提示用户：「已写回，打开小程序『计划』页查看本周安排吧。」
- 破坏性命令（`lianwan unbind`）按用户明确要求执行，不主动建议删除数据。