skill-calorie 0.2.0 → 0.2.1

package/dist/cli/cmd_read.js

@@ -12,8 +12,11 @@
  * <SKILLS_DB_PATH>/calorie_html/<中文command>_<YYYYMMDD>_<HHMMSS>[_N].html（同秒冲突自动加后缀），
  * 中文 command 取 CALORIE_COMBOS[key].title；显式 --output（--html 为 legacy 别名）覆盖任意路径。
  * 落点随 envelope 的 data.output 回传（additive 字段，六形状守卫不校验 data 额外键）。
+ * #91 · `calorie.help.center` 承载**全量速查台**（Q9）：`--params '{"mode":"file|inline|text"}'` 显式选交付形态
+ * （D6，缺省 `file`）；`q`／`keyword` 保留**照片 10 键**语义（非空＝现找、空串＝全量 10 键）。envelope 恒五字段
+ * `version/skill/shape/key/data`（Q8：**无 `status`**），`data` 只回索引与落点／字节数，不回 1 MB 产物。
  */
-import { existsSync, writeFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { openDb } from '../schema.js';
 import { DB_FILENAME } from '../paths.js';
@@ -32,18 +35,34 @@ import { buildGoalExpiringView, buildGoalPredictView, buildGoalVsActualView } fr
 import { buildPredictView, buildAnomalyView, buildContraView, buildDedupeView } from '../render/insightPlate.js';
 import { buildProfileView } from '../render/profilePlate.js';
 import { buildCombinedAnalysis, buildDeficitPlate, buildDietReview } from '../render/analysisPlate.js';
+import { dietFoodRanking, dietMacroRatio } from '../analysis/diet.js';
+import { buildAllRankingsDoc, buildDedupeDoc, buildDietReviewDoc, buildHealthDoc, buildLibraryDoc, buildRankingDoc, buildSearchDoc, buildTodayDietDoc, buildViewDietDoc, } from '../render/dietDocs.js';
+import { buildBodyCompositionDoc, buildBodyMeasureDoc, buildExerciseDoc, buildExerciseGoalDoc, buildVolatilityDoc, buildWeightCompareDoc, buildWeightDoc, buildWeightHistoryDoc, buildWeightReviewDoc, } from '../render/sportDocs.js';
+import { buildCardioDoc, buildDistributionDoc, buildRecapDoc, buildReviewDoc, buildStrengthDoc, buildTrendDoc, } from '../render/sportPortDocs.js';
+import { buildCardioView, buildDistributionView, buildRecapView, buildReviewView, buildStrengthView, buildTrendView, } from '../render/exercisePort.js';
+import { buildNutritionDetailView, buildNutritionRatioView, buildSourceStatsView, buildTodayWaterView, } from '../render/nutritionPort.js';
+import { buildNutritionDetailDoc, buildNutritionRatioDoc, buildSourceStatsDoc, buildTodayWaterDoc, } from '../render/nutritionPortDocs.js';
+import { buildBatchImportPreviewView, buildCalorieTrendView, buildLintHealthView, buildLongTrendView, buildNutritionAnalysisView, buildProcessProgressView, buildReviewTemplateView, buildSixFactorsView, } from '../render/trendMiscPort.js';
+import { buildBatchImportPreviewDoc, buildCalorieTrendDoc, buildLintHealthDoc, buildLongTrendDoc, buildNutritionAnalysisDoc, buildProcessProgressDoc, buildReviewTemplateDoc, buildSixFactorsDoc, } from '../render/trendMiscPortDocs.js';
+import { buildCompositionWizardView, buildGifPlannerView, buildMeasureWizardView, buildPhotoLogWizardView, } from '../render/wizardPort.js';
+import { buildCompositionWizardDoc, buildGifPlannerDoc, buildMeasureWizardDoc, buildPhotoLogWizardDoc, } from '../render/wizardPortDocs.js';
+import { buildAnomalyDoc, buildCombinedDoc, buildContraDoc, buildDeficitDoc, buildGoalPredictDoc, buildPredictDoc, } from '../render/trendDocs.js';
 import { buildHealthPlate } from '../render/health.js';
 import { buildAllRankings, buildFoodRankingPlate } from '../render/ranking.js';
 import { buildProductLibrary, buildProductSearch, buildProductStats } from '../render/library.js';
 import { buildCompareData, buildGalleryData, buildGifTask, buildViewerData } from '../render/photo.js';
 import { buildPhotoHelp, lookupPhotoHelp } from '../render/help.js';
-import { renderCombinedHtml, renderDeficitHtml, renderDietHtml, renderDietReviewHtml, renderExerciseHtml, renderGalleryHtml, renderCompareHtml, renderViewerHtml, renderGifHtml, renderPhotoHelpHtml, renderHelpLookupHtml, renderGoalConfigHtml, renderGoalRecommendHtml, renderGoalWeightHtml, renderGoalProgressHtml, renderGoalStatusHtml, renderGoalHtml, renderHealthHtml, renderHomeHtml, renderProductLibraryHtml, renderProductSearchHtml, renderRankingHtml, renderAllRankingsHtml, renderWeightHtml, renderWeightHistoryHtml, renderWeightCompareHtml, renderWeightReviewHtml, renderVolatilityHtml, renderBodyCompositionHtml, renderBodyMeasureHtml, renderPlanHtml, renderPlanWizardHtml, renderExerciseGoalHtml, renderGoalExpiringHtml, renderGoalPredictHtml, renderGoalVsActualHtml, renderPredictHtml, renderAnomalyHtml, renderContraHtml, renderDedupeHtml, renderProfileHtml, } from '../render/html.js';
-import { assertStatMetrics } from '../render/envelope.js';
+// #91 · 全量速查台（Q9）：只读消费 #88 的 `render/helpCenter.js`（三态同源，零改动）。
+import { HELP_CENTER_MODES, buildHelpSceneData, renderHelpCenterHtml } from '../render/helpCenter.js';
+import { renderGalleryHtml, renderCompareHtml, renderViewerHtml, renderGifHtml, renderPhotoHelpHtml, renderHelpLookupHtml, renderErrorHtml, renderGoalConfigHtml, renderGoalRecommendHtml, renderGoalWeightHtml, renderGoalProgressHtml, renderGoalStatusHtml, renderGoalHtml, renderHomeHtml, renderPlanHtml, renderPlanWizardHtml, renderGoalExpiringHtml, renderGoalVsActualHtml, renderProfileHtml, } from '../render/html.js';
+import { assertStatMetrics, buildDelivery, withDelivery } from '../render/envelope.js';
+import { buildErrorReceipt } from '../render/receipt.js';
+import { buildDataText } from 'base-paint';
 import { CalorieRenderError } from '../render/errors.js';
 import { TRIGGERS, searchHelp } from '../triggers/index.js';
 import { shiftISODate, todayISO } from '../analysis/utils.js';
 import { CALORIE_COMBOS, ENVELOPE_VERSION, CALORIE_SKILL, calorieShapeFor, isCalorieWriteKey } from './keys.js';
-import { HTML_DIR_NAME, resolveDefaultHtmlPath, resolveExplicitHtmlPath } from '../output.js';
+import { HTML_DIR_NAME, deliverHtml, resolveReceiptHtmlPath, } from '../output.js';
 import { openDbReadOnly } from '../db/readonly.js';
 import { dispatchWrite } from './write.js';
 const DEFAULT_TIMEOUT_MS = 30000;
@@ -122,7 +141,7 @@ function latestFoodDate(db) {
         return null;
     }
 }
-function defaultRange(db, params) {
+function defaultRange(db, params, defDays = 7) {
     let end = optStr(params, 'end') ?? optStr(params, 'date') ?? optStr(params, 'today') ?? undefined;
     let start = optStr(params, 'start') ?? undefined;
     if (end)
@@ -142,7 +161,7 @@ function defaultRange(db, params) {
             fail(2, 'start 不得晚于 end');
         return { start, end: end };
     }
-    return { start: shiftISODate(end, -6), end: end };
+    return { start: shiftISODate(end, -(defDays - 1)), end: end };
 }
 /** 本地 envelope 形状校验（镜像 link-core assertShapeData，不运行时 import）。 */
 function assertEnvelopeData(shape, data) {
@@ -203,6 +222,28 @@ function photosDirOf(params) {
     const e = process.env.CALORIE_PHOTOS_DIR;
     return e ? e : undefined;
 }
+/** #91 · 全量速查台的信封载荷：**10 分组索引**（不把 1 MB 产物塞进 envelope）。
+ *
+ *  `items` 恒为 10 条分组（`total` = `items.length`，与 `list` 形语义一致）；
+ *  `sceneTotal`／`subgroupTotal` 把「436 场景／54 子功能」如实回传，避免只报 10 丢掉全量口径。
+ */
+function helpCenterIndex(data) {
+    let sceneTotal = 0;
+    let subgroupTotal = 0;
+    const items = data.groups.map((group) => {
+        const sceneCount = group.subgroups.reduce((n, sub) => n + sub.scenes.length, 0);
+        sceneTotal += sceneCount;
+        subgroupTotal += group.subgroups.length;
+        return {
+            id: group.id,
+            icon: typeof group.icon === 'string' ? group.icon : '',
+            label: group.label,
+            subgroupCount: group.subgroups.length,
+            sceneCount,
+        };
+    });
+    return { items, total: items.length, sceneTotal, subgroupTotal };
+}
 // 全键分发：读走 render/fetch 读，HELP 走触发词现找；未知键上游已拦，此处再拦一道。
 /** #41 · 测试直调出口（纯 CLI 同逻辑，不经过 argv/spawn；CLI 唯一出口仍为 main）。 */
 export function dispatch(key, params, db) {
@@ -216,7 +257,9 @@ export function dispatch(key, params, db) {
             const items = rows.map((r) => ({ id: r.id, date: r.date, time: r.time, food_name: r.food_name, grams: r.grams, calories: r.calories, protein: r.protein, carbs: r.carbs, fat: r.fat }));
             const o = buildDietOverview(db, date, date);
             const dist = buildMealDistribution(db, date);
-            return { data: { items, total: items.length }, html: renderDietHtml(o, dist) };
+            // #108 · 今日饮食全文档（餐次进度＋营养配比＋今日明细；配比无数据即 skip，不编数）。
+            const mt = dietMacroRatio(db, date, date);
+            return { data: { items, total: items.length }, html: buildTodayDietDoc({ overview: o, dist, meals: rows, macro: mt.status === 'ok' ? (mt.data ?? null) : null }) };
         }
         case 'calorie.view.home': {
             const date = optStr(params, 'date') ?? optStr(params, 'today') ?? latestFoodDate(db) ?? todayISO();
@@ -250,6 +293,22 @@ export function dispatch(key, params, db) {
                 else
                     throw e;
             }
+            // #108 · 窗口明细（逐日 listMeals 去水，上限 100 条并明示截断；单日失败跳过）。
+            const mealRows = [];
+            for (const d of o.series) {
+                try {
+                    for (const r of listMeals(db, d.date)) {
+                        if (r.food_name !== '💧水')
+                            mealRows.push(r);
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            const MEAL_CAP = 100;
+            const mealTotal = mealRows.length;
+            const mealSlice = mealRows.slice(0, MEAL_CAP);
             const metrics = nums({
                 totalCalories: o.totalCalories, avgCalories: o.avgCalories, calorieGoal: o.calorieGoal,
                 loggedDays: o.loggedDays, days: o.days, distTotal: dist.totalCalories,
@@ -258,7 +317,10 @@ export function dispatch(key, params, db) {
                 'meal.晚餐': dist.slices.find((s) => s.meal === '晚餐')?.calories,
                 'meal.加餐': dist.slices.find((s) => s.meal === '加餐')?.calories,
             });
-            return { data: { metrics }, html: renderDietHtml(o, dist) };
+            return { data: { metrics }, html: buildViewDietDoc({
+                    overview: o, dist, distDate: date, days: o.series,
+                    meals: mealSlice, mealTotal, mealsTruncated: mealTotal > MEAL_CAP,
+                }) };
         }
         case 'calorie.view.exercise': {
             const { start, end } = defaultRange(db, params);
@@ -268,7 +330,222 @@ export function dispatch(key, params, db) {
                 activeDays: v.review.activeDays, totalBurnedSeries: v.totalBurnedSeries,
                 avgBurnedPerLoggedDay: v.avgBurnedPerLoggedDay, seriesActiveDays: v.activeDays,
             });
-            return { data: { metrics }, html: renderExerciseHtml(v) };
+            return { data: { metrics }, html: buildExerciseDoc(v) };
+        }
+        // #111 · 运动移植 6 键（t71 需移植 exercise_*；envelope stat metrics 只收确定数字）。
+        case 'calorie.view.exercise-strength': {
+            const { start, end } = defaultRange(db, params);
+            const v = buildStrengthView(db, start, end);
+            const metrics = nums({
+                movementCount: v.movementCount, totalSets: v.totalSets,
+                totalVolumeKg: v.totalVolumeKg, totalReps: v.totalReps,
+            });
+            return { data: { metrics }, html: buildStrengthDoc(v) };
+        }
+        case 'calorie.view.exercise-cardio': {
+            const { start, end } = defaultRange(db, params);
+            const v = buildCardioView(db, start, end);
+            const metrics = nums({
+                sessions: v.sessions, totalMinutes: v.totalMinutes,
+                totalDistanceKm: v.totalDistanceKm, avgPaceMinPerKm: v.avgPaceMinPerKm,
+            });
+            return { data: { metrics }, html: buildCardioDoc(v) };
+        }
+        case 'calorie.view.exercise-distribution': {
+            const { start, end } = defaultRange(db, params);
+            const v = buildDistributionView(db, start, end);
+            const metrics = nums({
+                sessions: v.sessions, activeDays: v.activeDays, days: v.days, totalBurned: v.totalBurned,
+                intakeCal: v.intakeCal, tdeeTotal: v.tdeeTotal, deficit: v.deficit,
+            });
+            return { data: { metrics }, html: buildDistributionDoc(v) };
+        }
+        case 'calorie.view.exercise-recap': {
+            const { start, end } = defaultRange(db, params);
+            const v = buildRecapView(db, start, end);
+            const metrics = nums({
+                sessions: v.sessions, totalMinutes: v.totalMinutes, totalBurned: v.totalBurned,
+                activeDays: v.activeDays, days: v.days,
+            });
+            return { data: { metrics }, html: buildRecapDoc(v) };
+        }
+        case 'calorie.view.exercise-review': {
+            const { start, end } = defaultRange(db, params);
+            const v = buildReviewView(db, start, end);
+            const metrics = nums({
+                plannedSessions: v.plannedSessions, hitSessions: v.hitSessions,
+                completionPct: v.completionPct, plannedMovements: v.plannedMovements,
+                hitMovements: v.hitMovements, movementPct: v.movementPct,
+            });
+            return { data: { metrics }, html: buildReviewDoc(v) };
+        }
+        case 'calorie.view.exercise-trend': {
+            const { start, end } = defaultRange(db, params);
+            const v = buildTrendView(db, start, end);
+            const metrics = nums({
+                activeDays: v.activeDays, totalMinutes: v.totalMinutes,
+                totalBurned: v.totalBurned, peakBurned: v.peak?.burned,
+            });
+            return { data: { metrics }, html: buildTrendDoc(v) };
+        }
+        // #112 · 营养移植 4 键（t71 需移植 nutrition_*／source_stats／today_water；envelope stat metrics 只收确定数字）。
+        case 'calorie.view.nutrition-ratio': {
+            const { start, end } = defaultRange(db, params);
+            const v = buildNutritionRatioView(db, start, end);
+            const metrics = nums({
+                totalCalorie: v.totalCalorie, proteinG: v.proteinG, proteinPct: v.proteinPct,
+                carbG: v.carbG, carbPct: v.carbPct, fatG: v.fatG, fatPct: v.fatPct,
+                targetProteinG: v.targetProteinG, targetCarbG: v.targetCarbG, targetFatG: v.targetFatG,
+            });
+            return { data: { metrics }, html: buildNutritionRatioDoc(v) };
+        }
+        case 'calorie.view.nutrition-detail': {
+            const { start, end } = defaultRange(db, params);
+            const v = buildNutritionDetailView(db, start, end);
+            const metrics = nums({
+                days: v.days,
+                matchedMeals: v.matchedMeals,
+                missingFoods: v.missingFoods.length,
+                fiberAvg: v.items[0]?.avg,
+                sodiumAvg: v.items[1]?.avg,
+                sugarAvg: v.items[2]?.avg,
+                fiberPct: v.items[0]?.pct,
+                sodiumPct: v.items[1]?.pct,
+                sugarPct: v.items[2]?.pct,
+            });
+            return { data: { metrics }, html: buildNutritionDetailDoc(v) };
+        }
+        case 'calorie.view.source-stats': {
+            const v = buildSourceStatsView(db);
+            const metrics = nums({ total: v.total, sources: v.sources });
+            return { data: { metrics }, html: buildSourceStatsDoc(v) };
+        }
+        case 'calorie.view.today-water': {
+            const date = optStr(params, 'date') ?? latestFoodDate(db) ?? todayISO();
+            assertISO(date, 'date');
+            const v = buildTodayWaterView(db, date);
+            const metrics = nums({
+                todayMl: v.todayMl, targetMl: v.targetMl, pct: v.pct, remainMl: v.remainMl, cups: v.cups.length,
+            });
+            return { data: { metrics }, html: buildTodayWaterDoc(v) };
+        }
+        // #113 · 趋势 2＋其他 6 移植 8 键（t71 需移植八模板；envelope stat metrics 只收确定数字）。
+        case 'calorie.view.calorie-trend': {
+            const { start, end } = defaultRange(db, params);
+            const v = buildCalorieTrendView(db, start, end);
+            const s = v.data.summary;
+            const metrics = nums({
+                avg: s.avg, target: s.target, trendValue: s.trendValue,
+                startAvg: s.startAvg, endAvg: s.endAvg, weekdayAvg: s.weekdayAvg,
+                weekendAvg: s.weekendAvg, weekendDiff: s.weekendDiff,
+                compliantDays: s.compliantDays, complianceRate: s.complianceRate,
+            });
+            return { data: { metrics }, html: buildCalorieTrendDoc(v) };
+        }
+        case 'calorie.view.long-trend': {
+            const end = optStr(params, 'end') ?? latestFoodDate(db) ?? todayISO();
+            assertISO(end, 'end');
+            const v = buildLongTrendView(db, optStr(params, 'group'), optStr(params, 'window'), end);
+            const metrics = nums({
+                windowDays: v.windowDays, avgCalorie: v.avgCalorie, weightChange: v.weightChange,
+            });
+            return { data: { metrics }, html: buildLongTrendDoc(v) };
+        }
+        case 'calorie.view.nutrition-analysis': {
+            const { start, end } = defaultRange(db, params);
+            const v = buildNutritionAnalysisView(db, start, end);
+            const metrics = nums({
+                days: v.days, totalCalorie: v.totalCalorie,
+                proteinG: v.proteinG, proteinPct: v.proteinPct,
+                carbG: v.carbG, carbPct: v.carbPct, fatG: v.fatG, fatPct: v.fatPct,
+                fiberAvg: v.fiberAvg, sodiumAvg: v.sodiumAvg, sugarAvg: v.sugarAvg,
+                adviceCount: v.advice.length,
+            });
+            return { data: { metrics }, html: buildNutritionAnalysisDoc(v) };
+        }
+        case 'calorie.view.six-factors': {
+            const date = optStr(params, 'date') ?? latestFoodDate(db) ?? todayISO();
+            assertISO(date, 'date');
+            const v = buildSixFactorsView(db, date);
+            const metrics = nums({
+                score: v.score,
+                calorie: v.factors[0]?.ok ? 1 : 0,
+                protein: v.factors[1]?.ok ? 1 : 0,
+                water: v.factors[2]?.ok ? 1 : 0,
+                exercise: v.factors[3]?.ok ? 1 : 0,
+                weigh: v.factors[4]?.ok ? 1 : 0,
+                meals: v.factors[5]?.ok ? 1 : 0,
+            });
+            return { data: { metrics }, html: buildSixFactorsDoc(v) };
+        }
+        case 'calorie.view.measure-wizard': {
+            const v = buildMeasureWizardView(db, params);
+            const metrics = nums({
+                filledCount: v.filledCount, hasRecent: v.recent ? 1 : 0,
+            });
+            return { data: { metrics }, html: buildMeasureWizardDoc(v) };
+        }
+        case 'calorie.view.composition-wizard': {
+            const v = buildCompositionWizardView(db, params);
+            const metrics = nums({
+                filledCount: (v.source ? 1 : 0) + (v.bodyFatPct === null ? 0 : 1) + v.calipers.length,
+                caliperCount: v.calipers.length, sum7: v.sum7, hasRecent: v.recent ? 1 : 0,
+            });
+            return { data: { metrics }, html: buildCompositionWizardDoc(v) };
+        }
+        case 'calorie.view.photo-log-wizard': {
+            const v = buildPhotoLogWizardView(params);
+            const metrics = nums({
+                fileCount: v.srcPaths.length, hasTag: v.tag ? 1 : 0,
+            });
+            return { data: { metrics }, html: buildPhotoLogWizardDoc(v) };
+        }
+        case 'calorie.view.gif-planner': {
+            const dir = photosDirOf(params);
+            const v = buildGifPlannerView(db, params, dir ?? null);
+            const metrics = nums({
+                photoCount: v.photos.length, selectedCount: v.selectedIds.length,
+                missingCount: v.missingIds.length, cropCount: v.photos.filter((p) => p.crop).length,
+            });
+            return { data: { metrics }, html: buildGifPlannerDoc(v) };
+        }
+        case 'calorie.view.lint-health': {
+            const v = buildLintHealthView(db);
+            const metrics = nums({
+                issueCount: v.issueCount,
+                unmatched: v.checks[0]?.count,
+                badCalorie: v.checks[1]?.count,
+                future: v.checks[2]?.count,
+                duplicate: v.checks[3]?.count,
+            });
+            return { data: { metrics }, html: buildLintHealthDoc(v) };
+        }
+        case 'calorie.view.batch-import-preview': {
+            const v = buildBatchImportPreviewView(db, params['items']);
+            const metrics = nums({
+                total: v.total, matched: v.matched, missing: v.missing, totalCalorie: v.totalCalorie,
+            });
+            return { data: { metrics }, html: buildBatchImportPreviewDoc(v) };
+        }
+        case 'calorie.view.process-progress': {
+            const end = optStr(params, 'end') ?? latestFoodDate(db) ?? todayISO();
+            assertISO(end, 'end');
+            const v = buildProcessProgressView(db, end);
+            const metrics = nums({
+                hasPlan: v.hasPlan ? 1 : 0, plannedDays: v.plannedDays,
+                sessions7d: v.sessions7d, minutes7d: v.minutes7d,
+            });
+            return { data: { metrics }, html: buildProcessProgressDoc(v) };
+        }
+        case 'calorie.view.review-template': {
+            const { start, end } = defaultRange(db, params);
+            const v = buildReviewTemplateView(db, start, end);
+            const metrics = nums({
+                days: v.days, meals: v.meals, avgCalorie: v.avgCalorie,
+                sessions: v.sessions, minutes: v.minutes, weightChange: v.weightChange,
+                points: v.points.length,
+            });
+            return { data: { metrics }, html: buildReviewTemplateDoc(v) };
         }
         case 'calorie.view.goal': {
             const { start, end } = defaultRange(db, params);
@@ -343,7 +620,7 @@ export function dispatch(key, params, db) {
                 correlationR: c.analysis.correlation.r, correlationN: c.analysis.correlation.n, days: c.analysis.days,
                 seriesDays: c.series.length,
             });
-            return { data: { metrics }, html: renderCombinedHtml(c) };
+            return { data: { metrics }, html: buildCombinedDoc(c) };
         }
         case 'calorie.view.deficit': {
             const { start, end } = defaultRange(db, params);
@@ -354,7 +631,7 @@ export function dispatch(key, params, db) {
                 days: d.meta.days, weekdayCount: d.meta.weekdayCount, weekendCount: d.meta.weekendCount,
                 targetIntake: d.target.intake, targetTdee: d.target.tdee,
             });
-            return { data: { metrics }, html: renderDeficitHtml(d) };
+            return { data: { metrics }, html: buildDeficitDoc(d) };
         }
         case 'calorie.view.diet-review': {
             const { start, end } = defaultRange(db, params);
@@ -366,13 +643,15 @@ export function dispatch(key, params, db) {
                 'meal.晚餐': r.byMeal.find((s) => s.meal === '晚餐')?.totalCalories,
                 'meal.加餐': r.byMeal.find((s) => s.meal === '加餐')?.totalCalories,
             });
-            return { data: { metrics }, html: renderDietReviewHtml(r) };
+            // #108 · 复盘全文档（趋势折线＋配比环＋高频 TOP5＋按餐汇总；TOP5 取数失败即空态，不编数）。
+            const fr = dietFoodRanking(db, start, end, 'frequent', 5);
+            return { data: { metrics }, html: buildDietReviewDoc(r, fr.status === 'ok' ? (fr.data ?? null) : null) };
         }
         case 'calorie.view.health': {
             const { start, end } = defaultRange(db, params);
             const h = buildHealthPlate(db, start, end);
             const metrics = nums({ loggedDays: h.loggedDays, avgIntake: h.avgIntake, avgDeficit: h.avgDeficit });
-            return { data: { metrics }, html: renderHealthHtml(h) };
+            return { data: { metrics }, html: buildHealthDoc(h) };
         }
         case 'calorie.view.ranking': {
             const { start, end } = defaultRange(db, params);
@@ -384,11 +663,11 @@ export function dispatch(key, params, db) {
                 const one = buildFoodRankingPlate(db, start, end, category, topN);
                 const top = one.items[0];
                 const metrics = nums({ total: one.items.length, topN: one.topN, topCal: top?.totalCal, topCnt: top?.cnt, topRank: top?.rank });
-                return { data: { metrics }, html: renderRankingHtml(one) };
+                return { data: { metrics }, html: buildRankingDoc(one) };
             }
             const all = buildAllRankings(db, start, end, topN);
             const metrics = nums({ okCount: all.okCount, topN: all.topN });
-            return { data: { metrics }, html: renderAllRankingsHtml(all) };
+            return { data: { metrics }, html: buildAllRankingsDoc(all) };
         }
         case 'calorie.view.library': {
             const category = optStr(params, 'category') ?? null;
@@ -398,7 +677,7 @@ export function dispatch(key, params, db) {
             const lib = buildProductLibrary(db, category, limit);
             const stats = buildProductStats(db);
             const metrics = nums({ total: lib.total, statsTotal: stats.total });
-            return { data: { metrics }, html: renderProductLibraryHtml(lib) };
+            return { data: { metrics }, html: buildLibraryDoc(lib, stats.total) };
         }
         case 'calorie.view.search': {
             const keyword = needStr(params, 'keyword');
@@ -407,7 +686,7 @@ export function dispatch(key, params, db) {
                 fail(2, 'limit 须为 1..100 整数');
             const s = buildProductSearch(db, keyword, limit);
             const metrics = nums({ total: s.total, limit: limit });
-            return { data: { metrics }, html: renderProductSearchHtml(s) };
+            return { data: { metrics }, html: buildSearchDoc(s) };
         }
         case 'calorie.photo.list': {
             const dir = photosDirOf(params);
@@ -450,12 +729,39 @@ export function dispatch(key, params, db) {
             return { data: { summary: 'GIF 任务：标签 ' + gif.tag + ' 共 ' + gif.photoCount + ' 张（' + (gif.firstDate ?? '—') + ' ~ ' + (gif.lastDate ?? '—') + '）· ' + gif.note }, html: renderGifHtml(gif) };
         }
         case 'calorie.help.center': {
+            // #91 · Q9：本键承载**全量速查台**（#88 壳，三态同源）；**照片 10 键兼容走 `q`**（既有语义逐字不变）。
+            // D6：交付形态**显式** `mode`（`file`／`inline`／`text`），不靠猜、不从别的参数推；非法值即 exit 2。
             const q = optStr(params, 'q') ?? optStr(params, 'keyword') ?? undefined;
-            const hits = q ? lookupPhotoHelp(q) : buildPhotoHelp();
-            if (q && hits.length === 0)
-                throw new CalorieRenderError('missing-data', 'HELP 无命中：' + q);
-            const items = hits.map((h) => ({ wakeWord: h.wakeWord, key: h.key, desc: h.desc, exec: h.exec }));
-            return { data: { items, total: items.length }, html: renderPhotoHelpHtml(hits, q) };
+            const modeRaw = optStr(params, 'mode');
+            const photoLookup = q !== undefined && q !== '';
+            if (photoLookup && modeRaw !== undefined) {
+                fail(2, '参数 q 与 mode 互斥：q＝照片 HELP 现找（10 键），mode＝全量速查台交付形态（'
+                    + HELP_CENTER_MODES.join('／') + '）');
+            }
+            if (q !== undefined && modeRaw === undefined) {
+                // 照片路径（原样保留）：非空 q ＝ 现找（无命中 exit 4）；`q:""` ＝ 全量 10 键。
+                const hits = photoLookup ? lookupPhotoHelp(q) : buildPhotoHelp();
+                if (photoLookup && hits.length === 0)
+                    throw new CalorieRenderError('missing-data', 'HELP 无命中：' + q);
+                const items = hits.map((h) => ({ wakeWord: h.wakeWord, key: h.key, desc: h.desc, exec: h.exec }));
+                return { data: { items, total: items.length }, html: renderPhotoHelpHtml(hits, q) };
+            }
+            // 全量速查台：缺省 `file`（#88 的缺省同值）；`text` 态把文本一并回传（file／inline 只回落点，不塞 1 MB）。
+            const mode = (modeRaw ?? 'file');
+            if (!HELP_CENTER_MODES.includes(mode)) {
+                fail(2, '参数 mode 非法（' + String(mode) + '）：须为 ' + HELP_CENTER_MODES.join('／'));
+            }
+            const sceneData = buildHelpSceneData();
+            const rendered = renderHelpCenterHtml({ mode, sceneData });
+            const data = {
+                ...helpCenterIndex(sceneData),
+                mode,
+                bytes: Buffer.byteLength(rendered.html, 'utf8'),
+            };
+            if (mode === 'text')
+                data['text'] = rendered.html;
+            // #83 · 渲染层已定文本交付：产物即文本（③ 文本态之一），交付装配层据此走文本通道。
+            return { data, html: rendered.html, deliveryKind: mode === 'text' ? 'text' : 'html' };
         }
         case 'calorie.help.lookup': {
             const q = needStr(params, 'q');
@@ -495,7 +801,7 @@ export function dispatch(key, params, db) {
                 changeKg: w.trend.changeKg, dailyChangeG: w.trend.dailyChangeG,
                 weightGoal: w.weightGoal, gapKg: w.gapKg,
             });
-            return { data: { metrics }, html: renderWeightHtml(w) };
+            return { data: { metrics }, html: buildWeightDoc(w) };
         }
         case 'calorie.view.weight-history': {
             const startDate = optStr(params, 'startDate') ?? optStr(params, 'start');
@@ -515,7 +821,7 @@ export function dispatch(key, params, db) {
                 spanDays: h.change?.spanDays, first: h.change?.first, last: h.change?.last,
                 delta: h.change?.delta, dailyAvg: h.change?.dailyAvg,
             });
-            return { data: { metrics }, html: renderWeightHistoryHtml(h) };
+            return { data: { metrics }, html: buildWeightHistoryDoc(h) };
         }
         case 'calorie.view.weight-compare': {
             const start = needStr(params, 'start');
@@ -528,7 +834,7 @@ export function dispatch(key, params, db) {
                 currentAvg: v.compare.currentPeriod.avgWeight, compareAvg: v.compare.comparePeriod.avgWeight,
                 currentChange: v.compare.currentPeriod.changeKg, compareChange: v.compare.comparePeriod.changeKg,
             });
-            return { data: { metrics }, html: renderWeightCompareHtml(v) };
+            return { data: { metrics }, html: buildWeightCompareDoc(v) };
         }
         case 'calorie.view.weight-review': {
             const today = optStr(params, 'today') ?? optStr(params, 'date');
@@ -538,7 +844,7 @@ export function dispatch(key, params, db) {
                 gapKg: v.milestone.gapKg, actualDailyChangeKg: v.milestone.actualDailyChangeKg,
                 estDays: v.milestone.estDays, calorieAdjustment: v.milestone.calorieAdjustment,
             });
-            return { data: { metrics }, html: renderWeightReviewHtml(v) };
+            return { data: { metrics }, html: buildWeightReviewDoc(v) };
         }
         case 'calorie.view.volatility': {
             const { start, end } = defaultRange(db, params);
@@ -550,7 +856,7 @@ export function dispatch(key, params, db) {
                 points: v.volatility.points.length, anomalies: v.volatility.recentAnomalies.length,
                 deviationKg: v.volatility.earlyWarning.deviationKg,
             });
-            return { data: { metrics }, html: renderVolatilityHtml(v) };
+            return { data: { metrics }, html: buildVolatilityDoc(v) };
         }
         case 'calorie.view.body-composition': {
             const days = optNum(params, 'days') ?? 90;
@@ -558,7 +864,7 @@ export function dispatch(key, params, db) {
             const limit = optNum(params, 'limit') ?? 20;
             const v = buildBodyCompositionView(db, { days: days, source: source ?? undefined, limit: limit });
             const metrics = nums({ total: v.total, latestPct: v.latestPct, trendDays: v.trend.length });
-            return { data: { metrics }, html: renderBodyCompositionHtml(v) };
+            return { data: { metrics }, html: buildBodyCompositionDoc(v) };
         }
         case 'calorie.view.body-measure': {
             const metric = optStr(params, 'metric');
@@ -568,7 +874,7 @@ export function dispatch(key, params, db) {
             const dateTo = optStr(params, 'dateTo');
             const v = buildBodyMeasureView(db, { metric: metric ?? undefined, days: days, limit: limit, dateFrom: dateFrom ?? undefined, dateTo: dateTo ?? undefined });
             const metrics = nums({ total: v.total, latestVal: v.latestVal, trendDays: v.trend.length });
-            return { data: { metrics }, html: renderBodyMeasureHtml(v) };
+            return { data: { metrics }, html: buildBodyMeasureDoc(v) };
         }
         case 'calorie.view.plan': {
             const v = buildPlanView(db);
@@ -581,14 +887,14 @@ export function dispatch(key, params, db) {
                 fail(2, '缺参数 plan（PlanInput 对象）');
             const catalog = params['catalog'];
             const v = buildPlanWizardView(plan, catalog ?? undefined);
-            const metrics = nums({ errorCount: v.errorCount, warningCount: v.warningCount, insertedCount: v.insertedCount });
+            const metrics = nums({ errorCount: v.errorCount, warningCount: v.warningCount, checkedSessions: v.checkedSessions });
             return { data: { metrics }, html: renderPlanWizardHtml(v) };
         }
         case 'calorie.view.exercise-goal': {
             const { start, end } = defaultRange(db, params);
             const v = buildExerciseGoalView(db, start, end);
             const metrics = nums({ dailyGoal: v.dailyGoal, goalTotal: v.goalTotal, actual: v.actual, pct: v.pct, gap: v.gap, achieved: v.achieved ? 1 : 0, days: v.days });
-            return { data: { metrics }, html: renderExerciseGoalHtml(v) };
+            return { data: { metrics }, html: buildExerciseGoalDoc(v) };
         }
         case 'calorie.view.goal-expiring': {
             const withinDays = optNum(params, 'withinDays') ?? optNum(params, 'days') ?? 14;
@@ -598,10 +904,11 @@ export function dispatch(key, params, db) {
             return { data: { metrics }, html: renderGoalExpiringHtml(v) };
         }
         case 'calorie.view.goal-predict': {
-            const { start, end } = defaultRange(db, params);
+            // #103 G2 · 目标预测需 ≥14 条体重记录（simulate SIM_MIN_DAYS=14），7 天默认窗结构性不可达 → 默认 14 天。
+            const { start, end } = defaultRange(db, params, 14);
             const v = buildGoalPredictView(db, start, end);
             const metrics = nums({ targetKg: v.targetKg, current: v.current, daysLeft: v.daysLeft, ratePerWeek: v.ratePerWeek, feasible: v.feasible ? 1 : 0 });
-            return { data: { metrics }, html: renderGoalPredictHtml(v) };
+            return { data: { metrics }, html: buildGoalPredictDoc(v) };
         }
         case 'calorie.view.goal-vs-actual': {
             const { start, end } = defaultRange(db, params);
@@ -614,29 +921,30 @@ export function dispatch(key, params, db) {
             return { data: { metrics }, html: renderGoalVsActualHtml(v) };
         }
         case 'calorie.view.predict': {
-            const { start, end } = defaultRange(db, params);
+            // #103 G2 · 同 goal-predict：默认 14 天，否则缺省调用恒走 missing-data。
+            const { start, end } = defaultRange(db, params, 14);
             const horizonDays = optNum(params, 'horizonDays') ?? optNum(params, 'days') ?? 30;
             const v = buildPredictView(db, start, end, horizonDays);
             const metrics = nums({ current: v.current, ratePerWeek: v.ratePerWeek, forecastValue: v.forecastValue, forecastLo: v.forecastLo, forecastHi: v.forecastHi, horizonDays: v.horizonDays });
-            return { data: { metrics }, html: renderPredictHtml(v) };
+            return { data: { metrics }, html: buildPredictDoc(v) };
         }
         case 'calorie.view.anomaly': {
             const kind = needStr(params, 'kind');
             const { start, end } = defaultRange(db, params);
             const v = buildAnomalyView(db, kind, start, end);
             const metrics = nums({ findingCount: v.findingCount, days: v.diagnosis.days, degraded: v.diagnosis.degraded ? 1 : 0 });
-            return { data: { metrics }, html: renderAnomalyHtml(v) };
+            return { data: { metrics }, html: buildAnomalyDoc(v) };
         }
         case 'calorie.view.contraindication': {
             const part = optStr(params, 'part') ?? 'all';
             const v = buildContraView(db, part);
             const metrics = nums({ scannedSessions: v.scannedSessions, scannedMovements: v.scannedMovements, errorCount: v.errorCount, warnCount: v.warnCount, infoCount: v.infoCount });
-            return { data: { metrics }, html: renderContraHtml(v) };
+            return { data: { metrics }, html: buildContraDoc(v) };
         }
         case 'calorie.view.dedupe': {
             const v = buildDedupeView(db);
             const metrics = nums({ groupCount: v.groupCount, rowCount: v.rowCount, totalProducts: v.totalProducts });
-            return { data: { metrics }, html: renderDedupeHtml(v) };
+            return { data: { metrics }, html: buildDedupeDoc(v) };
         }
         case 'calorie.view.profile': {
             const v = buildProfileView(db);
@@ -652,6 +960,106 @@ export function dispatch(key, params, db) {
             throw new Error('unreachable');
     }
 }
+/* ── #83 · 三态交付装配（M4 HTML-First ＋ 渲染失败回执） ───────────────────────────────── */
+/** 交付落点的可读描述（回执文案用；默认目录名必须出现在文案里，便于用户定位）。 */
+function describeDeliveryTarget(explicit) {
+    return explicit !== undefined ? '显式落点 ' + explicit : '默认目录 <SKILLS_DB_PATH>/' + HTML_DIR_NAME;
+}
+/** ③ 文本态的结构化文本：**同源**取 `buildDataText`（#77 契约，五 shape 投影）。
+ *  `fallback` 形不在 `SERIALIZABLE_SHAPES` 内（#93 登记：无 CLI 出口）——此时退化为缩进 JSON，
+ *  仍是「结构化文本」且零编造；本退化分支由 `delivery-83.test.mjs` 直接钉住。 */
+function dataTextOf(shape, key, data) {
+    try {
+        return buildDataText({
+            envelope: { version: ENVELOPE_VERSION, skill: CALORIE_SKILL, shape, key, data },
+            format: 'text',
+        });
+    }
+    catch {
+        return JSON.stringify(data, null, 2);
+    }
+}
+/** 三态判定 ＋ envelope 装配（**唯一交付落点**：同一 key、同一份 `data`，绝不各自取数）：
+ *  ③ 文本态：用户**明确**要文本（通用 `--params '{"delivery":"text"}'`）／渲染层已产出文本
+ *     （#91 `help.center` 的 `mode:'text'`）／**无 HTML 产物**（结构缝：`html` 为空 ⇒ 无对应模板，允许文字答）；
+ *  ② 内联态：有 HTML 产物但写不进去（只读／沙箱 `EACCES|EPERM|EROFS|EBUSY`）⇒ 产物随 envelope 回传；
+ *  ① 文件态（默认）：落盘 `calorie_html/*.html`，`data.output` 与 `delivery.path` 同值同源。
+ *  `delivery` 为 envelope 的**顶层追加字段**（既有五字段一字不改）；P9「stdout 一行 JSON」不变。 */
+export function buildDeliveredEnvelope(input) {
+    const { key, shape, params, out } = input;
+    const html = typeof out.html === 'string' ? out.html : '';
+    const askedText = params['delivery'] === 'text';
+    const kind = askedText ? 'text' : (out.deliveryKind ?? (html.trim() === '' ? 'text' : 'html'));
+    if (kind === 'text') {
+        // 三态同源：文本由**同一份** envelope data 经 #77 `buildDataText` 投影（技能侧不自产第二套序列化）。
+        const text = typeof out.data['text'] === 'string' ? out.data['text'] : dataTextOf(shape, key, out.data);
+        const data = { ...out.data, text };
+        // 渲染层已定文本交付的键（#91 `help.center` text 态）**保留既有落盘**（`data.output` 指向该文本文件）；
+        // 其余键的文本态只走 envelope（③ 产物＝结构化文本，不落 HTML 文件）。
+        if (out.deliveryKind === 'text') {
+            const d = deliverHtml({ key, params, explicit: input.explicit, html: text });
+            if (d.mode === 'file')
+                data['output'] = d.path;
+            return withDelivery(buildEnvelope(key, shape, data), buildDelivery({
+                mode: 'text', path: d.mode === 'file' ? d.path : undefined, shape, html: text, bytes: d.bytes, template: 'text',
+            }));
+        }
+        return withDelivery(buildEnvelope(key, shape, data), buildDelivery({
+            mode: 'text', shape, html: text, bytes: Buffer.byteLength(text, 'utf8'), template: 'text',
+        }));
+    }
+    const d = deliverHtml({ key, params, explicit: input.explicit, html });
+    const data = d.mode === 'file'
+        ? { ...out.data, output: d.path }
+        : { ...out.data, html };
+    return withDelivery(buildEnvelope(key, shape, data), buildDelivery({
+        mode: d.mode, path: d.mode === 'file' ? d.path : undefined, shape, html, bytes: d.bytes,
+    }));
+}
+/** #83 · M4「渲染失败回执」：**模板化**回执（`buildErrorReceipt` ＋ `renderErrorHtml`，旧
+ *  `render_error_receipt.py` 的等价物）——**严禁手写 HTML 兜底**。回执自身也走三态：默认目录可写即落盘，
+ *  否则内联随 stderr 回传。机器可读回执以一行 `RECEIPT {…}` 落 **stderr**（P9：stdout 保持纯净，
+ *  不吐半截 envelope），exit 5 与既有「渲染/落盘失败」口径一致。 */
+function failWithReceipt(reason, key) {
+    console.error('ERR 5: ' + reason);
+    try {
+        const receipt = buildErrorReceipt({
+            sceneName: '渲染',
+            wakeWord: key ?? '渲染失败',
+            op: '渲染／落盘未完成',
+            reason,
+            suggestions: [
+                '检查 SKILLS_DB_PATH 与 ' + HTML_DIR_NAME + ' 目录权限（只读／沙箱会自动转内联交付）',
+                '用 --output <可写绝对路径> 显式指定落点后重试',
+                '确认 ' + HTML_DIR_NAME + ' 未被同名文件占位（占位会挡住落点解析）',
+            ],
+            fixPrompt: 'calorie-cmd-read ' + (key ?? '<key>') + " --params '{…}' --output <可写绝对路径>",
+        });
+        const receiptHtml = renderErrorHtml(receipt);
+        let delivery;
+        try {
+            const d = deliverHtml({
+                key: key ?? 'calorie.help.center', params: {}, target: resolveReceiptHtmlPath(), html: receiptHtml,
+            });
+            delivery = buildDelivery({
+                mode: d.mode, path: d.mode === 'file' ? d.path : undefined, shape: 'receipt', html: receiptHtml, bytes: d.bytes,
+            });
+        }
+        catch {
+            delivery = buildDelivery({
+                mode: 'inline', shape: 'receipt', html: receiptHtml, bytes: Buffer.byteLength(receiptHtml, 'utf8'),
+            });
+        }
+        // 内联回执把模板化回执页面一并回传（否则调用方拿不到回执正文）；落盘态只回路径。
+        console.error('RECEIPT ' + JSON.stringify({
+            ok: false, ...receipt, delivery, html: delivery.mode === 'inline' ? receiptHtml : undefined,
+        }));
+    }
+    catch (e) {
+        console.error('TOAST: 回执生成失败（' + (e.message || String(e)) + '）');
+    }
+    process.exit(5);
+}
 function parseReadArgs(a) {
     return parseArgs(a);
 }
@@ -695,25 +1103,21 @@ async function main() {
             const out = isCalorieWriteKey(o.key)
                 ? dispatchWrite(o.key, params, db)
                 : dispatch(o.key, params, db);
-            // #87 · 输出落点：--output（显式覆盖）> --html（legacy 别名）> 默认 calorie_html/<中文command>_<TS>[_N].html
-            // #87 返修 F4（A2 S2-4）：落点**解析**本身也会失败（如 <DB>/calorie_html 被同名文件占位 → EEXIST）；
-            // 旧写法把它漏到外层「未知失败」分支 → exit 4（＝取数/超时）＋「未知失败」文案。此处按渲染失败计：
-            // exit 5 ＋ 明确文案（与紧邻的「HTML 写盘失败」同码同形态）。
-            let htmlTarget;
+            // #83 · 三态交付（M4 HTML-First）：① 文件态（默认）／② 内联态（只读·沙箱回退）／③ 文本态。
+            // 落点：--output（显式覆盖）> --html（legacy 别名）> 默认 calorie_html/<中文command>_<TS>[_N].html（#87／#119）。
+            // 只读类写失败 → 内联交付（产物随 envelope 回传，绝不因写不进去而文字答）；
+            // 结构错／渲染错 → 渲染失败回执（模板化回执，exit 5；严禁手写 HTML 兜底）。
             try {
-                htmlTarget = o.output ?? o.html ?? resolveDefaultHtmlPath(o.key);
+                env = buildDeliveredEnvelope({
+                    key: o.key, shape: shape, out, params, explicit: o.output ?? o.html,
+                });
             }
             catch (e) {
-                fail(5, '渲染失败：HTML 落点解析失败（' + (o.output ?? o.html ?? '默认目录 <SKILLS_DB_PATH>/' + HTML_DIR_NAME)
-                    + '）：' + e.message);
-            }
-            try {
-                writeFileSync(resolveExplicitHtmlPath(htmlTarget), out.html, 'utf8');
-            }
-            catch (e) {
-                fail(5, 'HTML 写盘失败：' + htmlTarget + '（' + e.message + '）');
+                if (e instanceof CalorieRenderError)
+                    throw e;
+                failWithReceipt('渲染失败：' + describeDeliveryTarget(o.output ?? o.html) + '：'
+                    + (e.message || String(e)), o.key);
             }
-            env = buildEnvelope(o.key, shape, { ...out.data, output: htmlTarget });
         }
         finally {
             db.close();
@@ -723,7 +1127,9 @@ async function main() {
         if (e instanceof CalorieRenderError) {
             if (e.code === 'missing-data')
                 fail(4, '取数失败（缺失阻断）：' + e.message);
-            fail(e.code === 'bad-input' ? 2 : 5, (e.code === 'bad-input' ? '参数失败：' : '渲染失败：') + e.message);
+            if (e.code === 'bad-input')
+                fail(2, '参数失败：' + e.message);
+            failWithReceipt('渲染失败：' + e.message, o.key);
         }
         if (e instanceof FetchError)
             fail(4, '取数失败：' + e.message);