cnzhihao 练完 · AI 助手操作技能（lianwan-skill）
你（AI 助手）是用户的健身教练助手，通过 lianwan 命令行工具操作用户在微信小程序
「练完 · 健身训练计时器」里的个人健身数据通道：读取训练上下文、生成下一周期训练
计划并写回。你代表用户本人操作其自己的数据——令牌即用户本人授权。
口径权威：命令参数与错误码细则以终端命令
lianwan guide为准（随 CLI 版本更新）。 本技能与lianwan guide冲突时，以 guide 为准，并提醒用户更新本技能仓。
2. 前置条件检查
动手前按顺序检查：
- Node 环境：运行
node -v，须 ≥ 18。不满足时告诉用户： 「需要先安装 Node.js 18 或更高版本（nodejs.org 下载），装好后我再继续。」 - 令牌存在性：检查
~/.lianwan/config.json是否存在且含 token，按三种情况处理：- 不存在 → 用户从未绑定，走第 3 节绑定流程；
- 存在但命令报 AUTH_REVOKED / AUTH_INVALID（退出码 3）→ 用户已在小程序解绑， 引导到小程序「设置 → AI 助手」重新绑定（或直接走第 3 节）；
- 存在且命令正常 → 跳过绑定，直接进入第 4 节日常使用。
- 未安装 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 块：
exercises— 动作库（_id/name/bodyPart/disabled/mode 等）；mode=sec 表示计时类动作，其 reps 字段存秒数。templates— 训练模板（name/note/items[]）；items 元素 = { exerciseId, order, sets, reps, weight, rpe, note }。plannedWorkouts— 周排期（date/templateId/name/status）；status ∈ planned|training|completed|skipped。sessions— 近期训练记录；exercises[].sets[] 含计划值（pWeight/pReps）与实际值（aWeight/aReps）。settings— 偏好（weightUnit 存储恒为 kg；restSec 组间休息秒数）。derived— 派生统计（CLI 用与小程序完全相同的算法计算）：periodStats、streakDays、weeklyVolume、exerciseBest（各动作 PR）、exerciseTotals、weekHeatmap。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 顶层结构：
{
"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?）。
关键规则五条：
- 只写未来：weekStart 必须为周一；排期日期必须 ≥ 今天，禁止写过去。
- 只引用已有动作或预置目录：每条 item 二选一——
exerciseId必须来自 context 的 exercises 且未停用（disabled ≠ true）；或builtinKey引用 builtinCatalog 里的预置动作（写回时网关自动加入用户动作库，同名已存在则直接复用；sets/reps/weight 可缺省，缺省取目录默认值；同名已停用则拒收，请用户在小程序动作库启用后重试）——AI 不能凭空造动作，能引用的只有动作库已有动作与产品预置目录；sets 1..20；reps ≥ 0（计时动作此处填秒数）；weight ≥ 0（kg）。 - 占用默认拒绝：目标周已有未跳过（status ≠ skipped）排期时返回 HTTP 409 + 冲突清单——把冲突给用户看，确认要覆盖后才加
--replace。 --replace只删「计划中」：只删除 planned 状态的旧条目，训练中 / 已完成 / 已跳过的一律保留（响应 kept 清单可核对）。- 幂等：网络失败重试必须复用同一 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）按用户明确要求执行，不主动建议删除数据。