skill-calorie 0.2.3 → 0.2.5

package/dist/xunji/store.d.ts

@@ -0,0 +1,31 @@
+/** 回写落库：三列幂等键 ＋ 7 列 UPDATE（保留 `note`／`date`），见老适配器（代码新写）。
+ *
+ * 口径（只读参照 `adapters/xunji_adapter.py:upsert_exercise_log`，`:72-141`）：
+ * - 幂等键＝**三列** `xunji_localid＋exercise_type＋set_index`（老 `:98-101` 的 SQL 为准；
+ *   老 `backfill.py:7` 与原 `t350:15` 写“两列”是错的，见证据件更正节）；
+ * - 命中 → UPDATE 覆盖 7 列（`exercise_type／reps／load_kg／calories_burned／category／
+ *   difficulty／xunji_title`，老 `:105-114`）＋ `updated_at`，**不动 `note`／`date`**
+ *   （老 UPDATE 语句里没有这两列）；
+ * - 未命中 → INSERT（老 `:117-126` 十列；另带 `is_backfill=1`，新仓语义：这行是回写来的）；
+ * - 行级失败记 `errors` 不中断整体（老 `:128-131`）；游标级异常向上抛，
+ *   调用方回滚（老 `:87-88`）。
+ *
+ * INSERT 经运动门回写桥（R2 收口 #613：`exercise/index.js#exerciseBackfillBridge.addRecord`，
+ * 本件不深引 `exerciseStore.ts` 内部件）；
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { XunjiBackfillRow } from './rows.js';
+/** 幂等键三列（库列名；唯一定义地，别处引用——文档写两列处是错的）。 */
+export declare const XUNJI_IDEMPOTENT_COLUMNS: readonly ["xunji_localid", "exercise_type", "set_index"];
+/** UPDATE 覆盖的 7 列（库列名；唯一定义地；`note`／`date` 不在其中＝被保留）。 */
+export declare const XUNJI_UPDATE_COLUMNS: readonly ["exercise_type", "reps", "load_kg", "calories_burned", "category", "difficulty", "xunji_title"];
+/** 落库小结（老 `:84-85` 四键）。 */
+export interface XunjiUpsertReport {
+    readonly inserted: number;
+    readonly updated: number;
+    readonly total: number;
+    readonly errors: readonly string[];
+}
+/** 三列幂等落库（调用方负责开事务／提交／回滚；游标级异常向上抛）。 */
+export declare function upsertXunjiRows(db: DatabaseSync, rows: readonly XunjiBackfillRow[]): XunjiUpsertReport;
+//# sourceMappingURL=store.d.ts.map

package/dist/xunji/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/xunji/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,wCAAwC;AACxC,eAAO,MAAM,wBAAwB,0DAA2D,CAAC;AAEjG,wDAAwD;AACxD,eAAO,MAAM,oBAAoB,2GAQvB,CAAC;AAEX,2BAA2B;AAC3B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,uCAAuC;AACvC,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,gBAAgB,EAAE,GAAG,iBAAiB,CAkCtG"}

package/dist/xunji/store.js

@@ -0,0 +1,60 @@
+/** 回写落库：三列幂等键 ＋ 7 列 UPDATE（保留 `note`／`date`），见老适配器（代码新写）。
+ *
+ * 口径（只读参照 `adapters/xunji_adapter.py:upsert_exercise_log`，`:72-141`）：
+ * - 幂等键＝**三列** `xunji_localid＋exercise_type＋set_index`（老 `:98-101` 的 SQL 为准；
+ *   老 `backfill.py:7` 与原 `t350:15` 写“两列”是错的，见证据件更正节）；
+ * - 命中 → UPDATE 覆盖 7 列（`exercise_type／reps／load_kg／calories_burned／category／
+ *   difficulty／xunji_title`，老 `:105-114`）＋ `updated_at`，**不动 `note`／`date`**
+ *   （老 UPDATE 语句里没有这两列）；
+ * - 未命中 → INSERT（老 `:117-126` 十列；另带 `is_backfill=1`，新仓语义：这行是回写来的）；
+ * - 行级失败记 `errors` 不中断整体（老 `:128-131`）；游标级异常向上抛，
+ *   调用方回滚（老 `:87-88`）。
+ *
+ * INSERT 经运动门回写桥（R2 收口 #613：`exercise/index.js#exerciseBackfillBridge.addRecord`，
+ * 本件不深引 `exerciseStore.ts` 内部件）；
+ */
+import { exerciseBackfillBridge } from '../exercise/index.js';
+/** 幂等键三列（库列名；唯一定义地，别处引用——文档写两列处是错的）。 */
+export const XUNJI_IDEMPOTENT_COLUMNS = ['xunji_localid', 'exercise_type', 'set_index'];
+/** UPDATE 覆盖的 7 列（库列名；唯一定义地；`note`／`date` 不在其中＝被保留）。 */
+export const XUNJI_UPDATE_COLUMNS = [
+    'exercise_type',
+    'reps',
+    'load_kg',
+    'calories_burned',
+    'category',
+    'difficulty',
+    'xunji_title',
+];
+/** 三列幂等落库（调用方负责开事务／提交／回滚；游标级异常向上抛）。 */
+export function upsertXunjiRows(db, rows) {
+    const find = db.prepare('SELECT id FROM exercise_log WHERE xunji_localid = ? AND exercise_type = ? AND set_index = ?');
+    const touch = db.prepare('UPDATE exercise_log SET exercise_type = ?, reps = ?, load_kg = ?, calories_burned = ?, ' +
+        'category = ?, difficulty = ?, xunji_title = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?');
+    let inserted = 0;
+    let updated = 0;
+    const errors = [];
+    for (const row of rows) {
+        try {
+            const hit = find.get(row.xunjiLocalid, row.exerciseType, row.setIndex);
+            if (hit !== undefined) {
+                touch.run(row.exerciseType, row.reps, row.loadKg, row.caloriesBurned, row.category, row.difficulty, row.xunjiTitle, hit.id);
+                updated += 1;
+            }
+            else {
+                exerciseBackfillBridge.addRecord(db, {
+                    date: row.date, exerciseType: row.exerciseType, caloriesBurned: row.caloriesBurned,
+                    reps: row.reps, category: row.category, difficulty: row.difficulty,
+                    setIndex: row.setIndex, loadKg: row.loadKg, isBackfill: true,
+                    xunjiLocalid: row.xunjiLocalid, xunjiTitle: row.xunjiTitle,
+                });
+                inserted += 1;
+            }
+        }
+        catch (e) {
+            errors.push('localid=' + row.xunjiLocalid + ' set_index=' + String(row.setIndex) + ': ' + (e instanceof Error ? e.message : String(e)));
+        }
+    }
+    return { inserted, updated, total: inserted + updated, errors };
+}
+//# sourceMappingURL=store.js.map

package/dist/xunji/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/xunji/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,wCAAwC;AACxC,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,eAAe,EAAE,eAAe,EAAE,WAAW,CAAU,CAAC;AAEjG,wDAAwD;AACxD,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,eAAe;IACf,MAAM;IACN,SAAS;IACT,iBAAiB;IACjB,UAAU;IACV,YAAY;IACZ,aAAa;CACL,CAAC;AAUX,uCAAuC;AACvC,MAAM,UAAU,eAAe,CAAC,EAAgB,EAAE,IAAiC;IACjF,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CACrB,6FAA6F,CAC9F,CAAC;IACF,MAAM,KAAK,GAAG,EAAE,CAAC,OAAO,CACtB,yFAAyF;QACvF,4FAA4F,CAC/F,CAAC;IACF,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,QAAQ,CAA+B,CAAC;YACrG,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,KAAK,CAAC,GAAG,CACP,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,cAAc,EAC1D,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,CACrD,CAAC;gBACF,OAAO,IAAI,CAAC,CAAC;YACf,CAAC;iBAAM,CAAC;gBACN,sBAAsB,CAAC,SAAS,CAAC,EAAE,EAAE;oBACnC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,cAAc,EAAE,GAAG,CAAC,cAAc;oBAClF,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU;oBAClE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI;oBAC5D,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU;iBAC3D,CAAC,CAAC;gBACH,QAAQ,IAAI,CAAC,CAAC;YAChB,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC,YAAY,GAAG,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1I,CAAC;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC;AAClE,CAAC"}

package/dist/xunji/subcommands.d.ts

@@ -0,0 +1,64 @@
+/** 训记模块的**对外面**：8 条子命令的声明（**唯一定义地**，逐字照老 `xunji_bridge` 的 CLI 形状）。
+ *
+ * 形状出处（只读参照）：`D:\2Study\StudyNotes\SKILLS\卡路里\scripts\xunji_bridge\__main__.py`
+ * （子命令／参数／退出码／用法示例逐条对照）＋ `#595` 契约证据件。
+ *
+ * 本件只放**声明**：每条的名字／一句话职责／用法／参数／会走的退出码／用法示例／实现状态／归属票。
+ * 实现住各自的家（`verify` 见 #606、`upsert`／`push-plan` 见 #607、`fetch`／`backfill` 见 #608、
+ * `key` 见 #610；`overlay-plan` 见 #610；`run-sync` 见 #610（八条全实现，无留位）。
+ *
+ * 为什么这件不叫 `commands.ts`：`scripts/gen-cli.mjs:80-104` 把 `src/<能力>/commands.ts` 当**卡路里命令**
+ * 的权威声明读（六字段：kind／key／shape／title／example／run），且根测试 `test/calorie-routing-81.test.mjs:122-126`
+ * 要求每条声明命令都有可执行入口——本模块的 8 条子命令是**模块自己的对外面**，不是卡路里命令面，
+ * 故另起一件（有意偏离，见证据件 §四）。
+ */
+/** 退出码（老 `__main__.py:29-34` 的自述：0 成功／1 一般错误／2 鉴权失败／3 接口报错／4 校验失败）。
+ *  #595 实测两处「自述与实况不符」（401／403 实退 3），逐条映射表由 #607／#608／#610 出。 */
+export declare const XUNJI_EXIT_CODES: {
+    readonly ok: 0;
+    readonly error: 1;
+    readonly auth: 2;
+    readonly api: 3;
+    readonly invalid: 4;
+};
+/** 一条子命令的参数声明。位置参数写成 `flag: '<动作名>'`；开关型参数 `value: ''`。 */
+export interface XunjiArg {
+    readonly flag: string;
+    readonly value: string;
+    readonly required: boolean;
+    /** 位置参数里可重复（老 `nargs='+'`） */
+    readonly many?: boolean;
+    readonly note: string;
+}
+/** 一条子命令的对外形状。 */
+export interface XunjiSubcommand {
+    /** 老 8 条的名字，逐字 */
+    readonly name: string;
+    /** 一句话职责（用户看得懂的话） */
+    readonly does: string;
+    readonly usage: string;
+    readonly args: readonly XunjiArg[];
+    /** 这条会走的退出码（取值见 `XUNJI_EXIT_CODES`） */
+    readonly exits: readonly number[];
+    /** 用法示例：老实现的原样调用（形状参照）；本仓已实现的那条给**本仓可跑**的读法 */
+    readonly example: string;
+    /** `implemented`＝本仓真跑得通；`declared`＝只留位，等归属票 */
+    readonly state: 'implemented' | 'declared';
+    /** `declared` 时点名归哪张票；`implemented` 时为 null */
+    readonly ownerTicket: string | null;
+}
+/** 8 条子命令（顺序照老 CLI 的装配顺序：verify／fetch／upsert／push-plan／overlay-plan／backfill／key／run-sync）。 */
+export declare const XUNJI_SUBCOMMANDS: readonly XunjiSubcommand[];
+/** 8 条的名字（顺序同上）。 */
+export declare const XUNJI_SUBCOMMAND_NAMES: readonly string[];
+/** 按名字取声明；没有＝未知子命令。 */
+export declare function findSubcommand(name: string): XunjiSubcommand | undefined;
+/** 按声明解析出来的一份参数（键＝声明里的 `flag` 逐字）。 */
+export interface ParsedArgs {
+    readonly values: Readonly<Record<string, string | boolean | readonly string[]>>;
+    /** 没解析过的地方（缺参／未知参数／多余位置参数），null＝解析通过；用法行由调用方接 */
+    readonly problem: string | null;
+}
+/** 按**声明**解析一条子命令的参数：声明之外的一律不认（声明因此不是墙纸）。 */
+export declare function parseSubcommandArgs(sub: XunjiSubcommand, argv: readonly string[]): ParsedArgs;
+//# sourceMappingURL=subcommands.d.ts.map

package/dist/xunji/subcommands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subcommands.d.ts","sourceRoot":"","sources":["../../src/xunji/subcommands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;gEACgE;AAChE,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAEX,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,kBAAkB;AAClB,MAAM,WAAW,eAAe;IAC9B,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAAC;IAC3C,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAID,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EAgHvD,CAAC;AAEF,oBAAoB;AACpB,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAyC,CAAC;AAE9F,uBAAuB;AACvB,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAExE;AAED,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IAChF,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAiD7F"}

package/dist/xunji/subcommands.js

@@ -0,0 +1,202 @@
+/** 训记模块的**对外面**：8 条子命令的声明（**唯一定义地**，逐字照老 `xunji_bridge` 的 CLI 形状）。
+ *
+ * 形状出处（只读参照）：`D:\2Study\StudyNotes\SKILLS\卡路里\scripts\xunji_bridge\__main__.py`
+ * （子命令／参数／退出码／用法示例逐条对照）＋ `#595` 契约证据件。
+ *
+ * 本件只放**声明**：每条的名字／一句话职责／用法／参数／会走的退出码／用法示例／实现状态／归属票。
+ * 实现住各自的家（`verify` 见 #606、`upsert`／`push-plan` 见 #607、`fetch`／`backfill` 见 #608、
+ * `key` 见 #610；`overlay-plan` 见 #610；`run-sync` 见 #610（八条全实现，无留位）。
+ *
+ * 为什么这件不叫 `commands.ts`：`scripts/gen-cli.mjs:80-104` 把 `src/<能力>/commands.ts` 当**卡路里命令**
+ * 的权威声明读（六字段：kind／key／shape／title／example／run），且根测试 `test/calorie-routing-81.test.mjs:122-126`
+ * 要求每条声明命令都有可执行入口——本模块的 8 条子命令是**模块自己的对外面**，不是卡路里命令面，
+ * 故另起一件（有意偏离，见证据件 §四）。
+ */
+/** 退出码（老 `__main__.py:29-34` 的自述：0 成功／1 一般错误／2 鉴权失败／3 接口报错／4 校验失败）。
+ *  #595 实测两处「自述与实况不符」（401／403 实退 3），逐条映射表由 #607／#608／#610 出。 */
+export const XUNJI_EXIT_CODES = {
+    ok: 0,
+    error: 1,
+    auth: 2,
+    api: 3,
+    invalid: 4,
+};
+const CLI = 'node packages/skill-calorie/dist/xunji/cli.js';
+/** 8 条子命令（顺序照老 CLI 的装配顺序：verify／fetch／upsert／push-plan／overlay-plan／backfill／key／run-sync）。 */
+export const XUNJI_SUBCOMMANDS = [
+    {
+        name: 'verify',
+        does: '校验动作名在不在训记官方库',
+        usage: 'xunji verify <动作名> [<动作名> …] [--catalog <库文件路径>]',
+        args: [
+            { flag: '<动作名>', value: '动作名', required: true, many: true, note: '至少一个；空格分隔多个' },
+            { flag: '--catalog', value: '库文件路径', required: false, note: '本仓新增的显式覆盖（老机器路径可作覆盖）；缺省读包内预置快照' },
+        ],
+        exits: [XUNJI_EXIT_CODES.ok, XUNJI_EXIT_CODES.error, XUNJI_EXIT_CODES.invalid],
+        example: `${CLI} verify 哑铃弯举`,
+        state: 'implemented',
+        ownerTicket: null,
+    },
+    {
+        name: 'fetch',
+        does: '拉取某天的训记训练数据（只读，不改本仓）',
+        usage: 'xunji fetch --date YYYY-MM-DD [--full] [--raw] [--respect-rate-limit]',
+        args: [
+            { flag: '--date', value: 'YYYY-MM-DD', required: true, note: '要拉的那天' },
+            { flag: '--full', value: '', required: false, note: '用 include_full_data（30 秒限频）' },
+            { flag: '--raw', value: '', required: false, note: '输出原始 JSON，不整理' },
+            { flag: '--respect-rate-limit', value: '', required: false, note: '尊重限频：窗口内二次调用先等（跨进程，默认关）' },
+        ],
+        exits: [XUNJI_EXIT_CODES.ok, XUNJI_EXIT_CODES.auth, XUNJI_EXIT_CODES.api],
+        example: 'python scripts/xunji_bridge.py fetch --date 2026-07-13',
+        state: 'implemented',
+        ownerTicket: null,
+    },
+    {
+        name: 'upsert',
+        does: '训记 upsert 接口的原子调用（增／改，res[] 透传；`push-plan` 的底层）',
+        usage: 'xunji upsert (--json <res[] 串> | --json-file <路径>) [--client-request-id <幂等键>] [--include-full-data] [--dry-run]',
+        args: [
+            { flag: '--json', value: 'res[] JSON 串', required: false, note: '与 --json-file 二选一' },
+            { flag: '--json-file', value: '路径', required: false, note: '与 --json 二选一' },
+            { flag: '--client-request-id', value: '幂等键', required: false, note: '缺则自动生成' },
+            { flag: '--include-full-data', value: '', required: false, note: '改 RPE／难度／备注时建议带上' },
+            { flag: '--dry-run', value: '', required: false, note: '只构造请求，不调接口' },
+        ],
+        exits: [XUNJI_EXIT_CODES.ok, XUNJI_EXIT_CODES.error, XUNJI_EXIT_CODES.auth, XUNJI_EXIT_CODES.api],
+        example: `python scripts/xunji_bridge.py upsert --json '[{"datestr":"2026-07-13","localid":0,"title":"胸","start":0,"end":0,"movements":[]}]' --dry-run`,
+        state: 'implemented',
+        ownerTicket: null,
+    },
+    {
+        name: 'push-plan',
+        does: '推送某天的训练计划到训记（新建，localid＝0；45 秒限频）',
+        usage: 'xunji push-plan --date YYYY-MM-DD [--dry-run]',
+        args: [
+            { flag: '--date', value: 'YYYY-MM-DD', required: true, note: '要推的那天' },
+            { flag: '--dry-run', value: '', required: false, note: '只转换不调接口' },
+        ],
+        exits: [XUNJI_EXIT_CODES.ok, XUNJI_EXIT_CODES.auth, XUNJI_EXIT_CODES.api],
+        example: 'python scripts/xunji_bridge.py push-plan --date 2026-07-13 --dry-run',
+        state: 'implemented',
+        ownerTicket: null,
+    },
+    {
+        name: 'overlay-plan',
+        does: '用本仓计划覆盖训记某天的训练（localid 已有，start／end＝0）',
+        usage: 'xunji overlay-plan --date YYYY-MM-DD [--dry-run] [--missing fail|skip]',
+        args: [
+            { flag: '--date', value: 'YYYY-MM-DD', required: true, note: '要覆盖的那天' },
+            { flag: '--dry-run', value: '', required: false, note: '只构造请求，不调接口' },
+            { flag: '--missing', value: 'fail|skip', required: false, note: '「卡路里有、训记没」的 title 怎么办（默认 fail）' },
+        ],
+        exits: [XUNJI_EXIT_CODES.ok, XUNJI_EXIT_CODES.error, XUNJI_EXIT_CODES.auth, XUNJI_EXIT_CODES.api],
+        example: 'python scripts/xunji_bridge.py overlay-plan --date 2026-07-13 --dry-run',
+        state: 'implemented',
+        ownerTicket: null,
+    },
+    {
+        name: 'backfill',
+        does: '拉训记实绩并回写本仓运动记录（幂等）',
+        usage: 'xunji backfill [--date YYYY-MM-DD] [--days N]',
+        args: [
+            { flag: '--date', value: 'YYYY-MM-DD', required: false, note: '结束日（缺省＝今天）' },
+            { flag: '--days', value: 'N', required: false, note: '回写 [结束日−N+1, 结束日] 区间（缺省 1 天）' },
+        ],
+        exits: [XUNJI_EXIT_CODES.ok, XUNJI_EXIT_CODES.auth, XUNJI_EXIT_CODES.api],
+        example: 'python scripts/xunji_bridge.py backfill --date 2026-07-13',
+        state: 'implemented',
+        ownerTicket: null,
+    },
+    {
+        name: 'key',
+        does: 'KEY 管理（看状态／写入／清除）——KEY 存在配置文件里（#676）',
+        usage: 'xunji key status|set|clear',
+        args: [
+            { flag: '<子动作>', value: 'status|set|clear', required: true, note: '要做的那一步' },
+            { flag: '<KEY 值>', value: 'KEY 值', required: false, note: '只有 `key set` 要给（不回显、不进仓）' },
+        ],
+        exits: [XUNJI_EXIT_CODES.ok, XUNJI_EXIT_CODES.error, XUNJI_EXIT_CODES.auth],
+        example: 'python scripts/xunji_bridge.py key status',
+        state: 'implemented',
+        ownerTicket: null,
+    },
+    {
+        name: 'run-sync',
+        does: '一条链跑完：补计划→记心愿→推送→回写（串行 N 天，写状态文件）',
+        usage: 'xunji run-sync [--days N] [--start-offset N] [--dry-run]',
+        args: [
+            { flag: '--days', value: 'N', required: false, note: '同步天数（缺省 3）' },
+            { flag: '--start-offset', value: 'N', required: false, note: '起始日偏移（0＝今天）' },
+            { flag: '--dry-run', value: '', required: false, note: '只建状态文件，不实际跑' },
+        ],
+        exits: [XUNJI_EXIT_CODES.ok, XUNJI_EXIT_CODES.error, XUNJI_EXIT_CODES.auth, XUNJI_EXIT_CODES.api],
+        example: 'python scripts/xunji_bridge.py run-sync --days 3 --dry-run',
+        state: 'implemented',
+        ownerTicket: null,
+    },
+];
+/** 8 条的名字（顺序同上）。 */
+export const XUNJI_SUBCOMMAND_NAMES = XUNJI_SUBCOMMANDS.map((s) => s.name);
+/** 按名字取声明；没有＝未知子命令。 */
+export function findSubcommand(name) {
+    return XUNJI_SUBCOMMANDS.find((s) => s.name === name);
+}
+/** 按**声明**解析一条子命令的参数：声明之外的一律不认（声明因此不是墙纸）。 */
+export function parseSubcommandArgs(sub, argv) {
+    const values = {};
+    const positionals = sub.args.filter((a) => a.flag.startsWith('<'));
+    const sink = positionals.find((a) => a.many);
+    const usedPositional = new Set();
+    const takePositional = () => {
+        const next = positionals.find((a) => !a.many && !usedPositional.has(a.flag));
+        if (next)
+            usedPositional.add(next.flag);
+        return next;
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i] ?? '';
+        if (token.startsWith('--')) {
+            const eq = token.indexOf('=');
+            const name = eq >= 0 ? token.slice(0, eq) : token;
+            const inline = eq >= 0 ? token.slice(eq + 1) : undefined;
+            const decl = sub.args.find((a) => a.flag === name);
+            if (!decl)
+                return { values, problem: '未知参数：' + name };
+            if (decl.value === '') {
+                if (inline !== undefined)
+                    return { values, problem: name + ' 是开关型参数，不带值' };
+                values[name] = true;
+                continue;
+            }
+            const value = inline ?? argv[i + 1];
+            if (value === undefined || value === '' || (inline === undefined && value.startsWith('--'))) {
+                return { values, problem: name + ' 缺值' };
+            }
+            if (inline === undefined)
+                i += 1;
+            values[name] = value;
+            continue;
+        }
+        if (sink) {
+            const list = values[sink.flag] ?? [];
+            list.push(token);
+            values[sink.flag] = list;
+            continue;
+        }
+        const target = takePositional();
+        if (!target)
+            return { values, problem: '多余的位置参数：' + token };
+        values[target.flag] = token;
+    }
+    for (const a of sub.args) {
+        if (!a.required)
+            continue;
+        const v = values[a.flag];
+        if (v === undefined || (Array.isArray(v) && v.length === 0)) {
+            return { values, problem: '缺参数：' + a.flag };
+        }
+    }
+    return { values, problem: null };
+}
+//# sourceMappingURL=subcommands.js.map

package/dist/xunji/subcommands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subcommands.js","sourceRoot":"","sources":["../../src/xunji/subcommands.ts"],"names":[],"mappings":"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"}

package/dist/xunji/upsert.d.ts

@@ -0,0 +1,61 @@
+/** 训记 upsert 原子调用（老 `xunji_bridge/upsert.py:57-138`，代码新写）。
+ *
+ * 行为（逐条对老）：
+ * - 接口 `POST https://trains.xunjiapp.cn/api_upsert_trains_for_llm_v2`（老 `:53-54`）；
+ * - 包体五键 `schema_version／client_request_id／dry_run／include_full_data／res`
+ *   （老 `:90-96`），`res` 透传；`client_request_id` 缺省自动生成（老 `:77-79`）；
+ * - `dry_run` 只组包体摘要、不读 KEY、不调网（老 `:81-89` 在 `require_key` 之前）；
+ * - 非 dry-run 先要 KEY（缺 KEY 即 `auth` 失败，不调网、不重试；老 `:89` 的 `require_key` 抛错位）；
+ * - 超时缺省 30 秒（老 `:62` 的 `timeout=30`），超时走 `network` 进重试（老 `:109-111`）；
+ * - 重试 `max_retries=2`（老 `:135`），`auth／vip／validation` 不重试（见 `retry.ts`）；
+ * - 响应 `gzip` 由运行时自动解（Node 全局 fetch 缺省解压；老 `:112-114` 手工解是 urllib 才要的）。
+ *
+ * KEY 口径（只读参照 `auth.py:35-55`；**定义住 `key.ts`**，本件只薄转出保既有引用不断）：
+ * - 缺省读**配置文件**里的 `xunji.key`（#676：环境变量读取已删，见 `key.ts` 件头）；
+ * - 调用方可显式传 `key` 或换 `readKey`（测试挡板从这里进；真 KEY 永不进仓）。
+ */
+import type { XunjiResItem } from './request.js';
+import { XUNJI_KEY_FIELD, readKey } from './key.js';
+import type { XunjiCallOutcome } from './retry.js';
+/** KEY 落点名＋缺省读法薄转出（定义见 `key.ts`）。 */
+export { XUNJI_KEY_FIELD, readKey };
+/** upsert 接口地址（老 `upsert.py:53-54` 同值；全模块只此一处）。 */
+export declare const XUNJI_UPSERT_ENDPOINT = "https://trains.xunjiapp.cn/api_upsert_trains_for_llm_v2";
+/** 最小传输面（只取“状态＋正文”；全局 fetch 与测试挡板都包得住）。 */
+export interface UpsertTransport {
+    (url: string, init: {
+        method: 'POST';
+        headers: Record<string, string>;
+        body: string;
+        signal: AbortSignal;
+    }): Promise<{
+        readonly status: number;
+        readonly bodyText: () => Promise<string>;
+    }>;
+}
+/** `upsertTrains` 的可注入件（测试挡板从这里进；生产全缺省）。 */
+export interface UpsertOptions {
+    /** 幂等键（缺省自动生成，老 `upsert.py:77-79`）。 */
+    readonly clientRequestId?: string;
+    /** 改 RPE／难度／备注时建议 true（老 `:70`）。 */
+    readonly includeFullData?: boolean;
+    /** 只组包体摘要，不读 KEY、不调网（老 `:63`）。 */
+    readonly dryRun?: boolean;
+    /** 显式 KEY（给了就不用 `readKey`）。 */
+    readonly key?: string | null;
+    /** KEY 来源（缺省读环境变量；#610 后改走能力门）。 */
+    readonly readKey?: () => string | null;
+    /** 传输（缺省全局 fetch）。 */
+    readonly transport?: UpsertTransport;
+    /** 超时毫秒（缺省 30000，老 `:62` 的 `timeout=30`）。 */
+    readonly timeoutMs?: number;
+    /** 重试次数（缺省 2，老 `:135`）。 */
+    readonly maxRetries?: number;
+    /** 睡眠（缺省真实 sleep；重试退避用）。 */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/** `upsertTrains` 的结局（成功透传训记正文；失败带结构化读数；`attempts` 为实际调用次数）。 */
+export type UpsertOutcome = XunjiCallOutcome;
+/** 调一次 upsert（原子层，无业务：不读库、不转计划、不对账，老 `:28` 同述）。 */
+export declare function upsertTrains(resList: readonly XunjiResItem[], opts?: UpsertOptions): Promise<UpsertOutcome>;
+//# sourceMappingURL=upsert.d.ts.map

package/dist/xunji/upsert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../src/xunji/upsert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,YAAY,CAAC;AAEjE,qCAAqC;AACrC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC;AAEpC,mDAAmD;AACnD,eAAO,MAAM,qBAAqB,4DAA4D,CAAC;AAE/F,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QACnH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;KAC1C,CAAC,CAAC;CACJ;AAYD,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,oCAAoC;IACpC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvC,sBAAsB;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2BAA2B;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,gEAAgE;AAChE,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAa7C,mDAAmD;AACnD,wBAAsB,YAAY,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAgDrH"}

package/dist/xunji/upsert.js

@@ -0,0 +1,100 @@
+/** 训记 upsert 原子调用（老 `xunji_bridge/upsert.py:57-138`，代码新写）。
+ *
+ * 行为（逐条对老）：
+ * - 接口 `POST https://trains.xunjiapp.cn/api_upsert_trains_for_llm_v2`（老 `:53-54`）；
+ * - 包体五键 `schema_version／client_request_id／dry_run／include_full_data／res`
+ *   （老 `:90-96`），`res` 透传；`client_request_id` 缺省自动生成（老 `:77-79`）；
+ * - `dry_run` 只组包体摘要、不读 KEY、不调网（老 `:81-89` 在 `require_key` 之前）；
+ * - 非 dry-run 先要 KEY（缺 KEY 即 `auth` 失败，不调网、不重试；老 `:89` 的 `require_key` 抛错位）；
+ * - 超时缺省 30 秒（老 `:62` 的 `timeout=30`），超时走 `network` 进重试（老 `:109-111`）；
+ * - 重试 `max_retries=2`（老 `:135`），`auth／vip／validation` 不重试（见 `retry.ts`）；
+ * - 响应 `gzip` 由运行时自动解（Node 全局 fetch 缺省解压；老 `:112-114` 手工解是 urllib 才要的）。
+ *
+ * KEY 口径（只读参照 `auth.py:35-55`；**定义住 `key.ts`**，本件只薄转出保既有引用不断）：
+ * - 缺省读**配置文件**里的 `xunji.key`（#676：环境变量读取已删，见 `key.ts` 件头）；
+ * - 调用方可显式传 `key` 或换 `readKey`（测试挡板从这里进；真 KEY 永不进仓）。
+ */
+import { randomUUID } from 'node:crypto';
+import { buildUpsertPayload } from './request.js';
+import { XUNJI_KEY_FIELD, readKey } from './key.js';
+import { classifyStatusBody, classifyThrown, retryWithBackoff, softFailureOf } from './retry.js';
+/** KEY 落点名＋缺省读法薄转出（定义见 `key.ts`）。 */
+export { XUNJI_KEY_FIELD, readKey };
+/** upsert 接口地址（老 `upsert.py:53-54` 同值；全模块只此一处）。 */
+export const XUNJI_UPSERT_ENDPOINT = 'https://trains.xunjiapp.cn/api_upsert_trains_for_llm_v2';
+/** 缺省传输（全局 fetch；缺失即明确失败，不静默）。 */
+const defaultTransport = (url, init) => {
+    const f = globalThis.fetch;
+    if (typeof f !== 'function')
+        return Promise.reject(new Error('HTTP 通道不可用：全局 fetch 缺失'));
+    return f(url, init).then((r) => ({
+        status: r.status,
+        bodyText: () => r.text(),
+    }));
+};
+function authMissing() {
+    const failure = {
+        error_type: 'auth',
+        message: '未配置训记 KEY（配置项 ' + XUNJI_KEY_FIELD + '；用 key set <KEY> 写进配置文件）',
+        retry_after: null,
+        raw_body: null,
+        code: null,
+    };
+    return { ok: false, failure, attempts: 0 };
+}
+/** 调一次 upsert（原子层，无业务：不读库、不转计划、不对账，老 `:28` 同述）。 */
+export async function upsertTrains(resList, opts = {}) {
+    const clientRequestId = opts.clientRequestId !== undefined && opts.clientRequestId !== '' ? opts.clientRequestId : randomUUID().replace(/-/g, '');
+    const includeFullData = opts.includeFullData ?? false;
+    if (opts.dryRun === true) {
+        return {
+            ok: true,
+            response: { dry_run: true, client_request_id: clientRequestId, include_full_data: includeFullData, res_count: resList.length },
+            attempts: 0,
+        };
+    }
+    const key = opts.key !== undefined && opts.key !== null && opts.key !== '' ? opts.key : (opts.readKey ?? readKey)();
+    if (key === null || key === '')
+        return authMissing();
+    const transport = opts.transport ?? defaultTransport;
+    const timeoutMs = opts.timeoutMs ?? 30000;
+    const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => { setTimeout(resolve, ms); }));
+    const payload = buildUpsertPayload(resList, clientRequestId, includeFullData);
+    const body = JSON.stringify(payload);
+    const once = async () => {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+        try {
+            const resp = await transport(XUNJI_UPSERT_ENDPOINT, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + key },
+                body,
+                signal: ctrl.signal,
+            });
+            const text = await resp.bodyText();
+            let parsed = text;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                const failure = { error_type: 'validation', message: '响应 JSON 解析失败', retry_after: null, raw_body: text.slice(0, 200), code: resp.status };
+                return { ok: false, failure, attempts: 1 };
+            }
+            if (resp.status >= 200 && resp.status < 300) {
+                const soft = softFailureOf(parsed);
+                if (soft !== null)
+                    return { ok: false, failure: soft, attempts: 1 };
+                return { ok: true, response: parsed, attempts: 1 };
+            }
+            return { ok: false, failure: classifyStatusBody(resp.status, parsed, text.slice(0, 2000)), attempts: 1 };
+        }
+        catch (e) {
+            return { ok: false, failure: classifyThrown(e), attempts: 1 };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    return retryWithBackoff(once, opts.maxRetries ?? 2, 5000, sleep);
+}
+//# sourceMappingURL=upsert.js.map

package/dist/xunji/upsert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upsert.js","sourceRoot":"","sources":["../../src/xunji/upsert.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,29 +1,26 @@
 {
   "name": "skill-calorie",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "卡路里SKILL一期：DB schema与迁移收敛（T1 #20），零依赖",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
-    "./triggers": "./dist/triggers/index.js",
-    "./fetch": "./dist/fetch/index.js",
-    "./render": "./dist/render/index.js",
     "./cli": "./dist/cli/cmd_read.js",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "SKILL.md",
-    "templates/*.html"
+    "workflows/*.md",
+    "templates/*.html",
+    "src/xunji/data/训记官方动作.json"
   ],
   "dependencies": {
+    "base-link-core": "^0.3.0",
     "base-paint": "^0.3.0"
   },
-  "devDependencies": {
-    "base-link-core": "^0.1.0"
-  },
   "bin": {
     "skill-calorie-fetch": "./dist/fetch/cli.js",
     "calorie-cmd-read": "./dist/cli/cmd_read.js"
@@ -33,6 +30,6 @@
   },
   "scripts": {
     "build": "tsc -b && node scripts/build-help.mjs",
-    "test": "node --test ../../test/scaffold.test.mjs ../../test/calorie-triggers.test.mjs test/fetch-t6.test.mjs"
+    "test": "node --test ../../test/scaffold.test.mjs ../../test/calorie-triggers.test.mjs test/fetch-t6.test.mjs test/help-reuse-245.test.mjs"
   }
 }