lumencode 1.3.3 → 1.3.4

package/README.md

@@ -66,6 +66,7 @@ npx lumencode serve
 | 🎯 **行级 AI 归因** | 通过 hook 步骤追踪，精确识别每一行代码的 AI 参与度。不是"这个提交 AI 帮忙了"，而是"这行代码是 AI 写的" |
 | 🌐 **三工具统一** | Claude Code / Codex / OpenCode 数据全自动汇总，左侧标签一键切换 |
 | 📝 **自然语言工作汇报** | 详报/简报一键生成，支持标准 Markdown / 飞书 / 钉钉三种格式，每个板块附诊断解读 |
+| 🤖 **智能报告生成** | 连接本地 OpenCode CLI，对受限统计上下文和原始工作汇报做 AI 分析，支持默认风格与面向领导汇报的「牛马」风格 |
 | 📂 **按项目独立汇报** | 右侧面板选择项目，生成该项目的独立工作汇报（commits + AI 交互量 + 热点文件） |
 | 📅 **自定义时间范围** | 除日/周/月外，支持选择任意起止日期，方便对齐 Sprint 周期 |
 | 💰 **精确费用估算** | 600+ 模型本地定价（含 GLM/Kimi/Qwen/DeepSeek）+ Portkey API 兜底，未知模型不计费而非乱算 |
@@ -119,6 +120,9 @@ npx lumencode serve
 
 - **详报** —— 完整数据 + 洞察解读 + 板块编号，适合周报、月报
 - **简报** —— 3-5 句话核心摘要，适合日报或群消息
+- **智能报告** —— 页面内调用本地 OpenCode CLI 生成 AI 分析报告，补充数据摘要、工作亮点分析、关键洞察、风险与建议
+- **风格选择** —— 生成前可选择默认风格，或「牛马」风格输出更适合向领导汇报的表达倾向
+- **持久化与更新提醒** —— 智能报告会按周期、项目、报告层级和风格保存；统计数据变化后提示重新生成
 - **多平台格式** —— 标准 Markdown / 飞书 / 钉钉，一键切换
 - **按项目生成** —— 右侧面板选择项目，生成该项目的独立汇报
 
@@ -250,6 +254,14 @@ node index.js hooks disable
 
 ## 更新日志
 
+### v1.3.4 (2026-06-05) — 智能报告风格与工作亮点分析
+
+- **智能报告风格选择** — 生成智能报告前弹窗选择「默认风格」或「牛马」风格，后者面向领导汇报口径，突出投入、产出、风险兜底和下一步计划
+- **工作亮点分析** — AI 智能报告新增「工作亮点分析」章节要求，让报告不止复述统计数据，而是提炼可汇报的亮点与依据
+- **Boss 汇报迁移** — 移除普通工作汇报里的「汇报 Boss」层级，将其能力迁移为智能报告的一种风格，减少普通报告入口复杂度
+- **报告持久化增强** — 智能报告按风格独立保存，默认风格兼容旧记录，刷新或切换页面后不会丢失
+- **后台生成体验** — 智能报告改为后台任务生成，支持刷新后恢复进度，并用渐进进度条降低长时间等待的不确定感
+
 ### v1.3.0 (2026-05-28) — 行级 AI 归因 & 交互式 Hooks 管理
 
 - **行级 AI 归因** — 通过 hook 步骤追踪系统，将归因粒度从提交级细化到行级，精确识别每一行代码的 AI 参与度

package/lib/server.js

@@ -1,7 +1,8 @@
-import { createServer } from 'http';
-import { readFileSync, existsSync } from 'fs';
-import { join, extname, resolve, sep } from 'path';
-import { fileURLToPath } from 'url';
+import { createServer } from 'http';
+import { readFileSync, existsSync } from 'fs';
+import { join, extname, resolve, sep } from 'path';
+import { fileURLToPath } from 'url';
+import { randomUUID } from 'crypto';
 import { saveConfig } from './config.js';
 import { parseRepoPaths } from './path-utils.js';
 import { generateWorkReport, generateFeishuCard, generateBossReport } from './report.js';
@@ -14,7 +15,9 @@ import { identifyBillingBlocks } from './blocks.js';
 import { detectAvailableTools, parseAllEnabledTools } from './parsers/index.js';
 import { isAssistantRecord, getInputTokens, getOutputTokens } from './record-utils.js';
 import { StepTracker } from './step-tracker.js';
-import { disableHooks, enableHooks, getHooksStatus, HOOK_TOOLS, initStepTracking } from './hooks-manager.js';
+import { disableHooks, enableHooks, getHooksStatus, HOOK_TOOLS, initStepTracking } from './hooks-manager.js';
+import { SMART_REPORT_PROMPT_MARKER, buildSmartReportContext, createSmartReport, detectSmartReportAgents } from './smart-report.js';
+import { buildSmartReportKey, buildSourceHash, getSmartReportStoreDir, readSmartReportRecord, saveSmartReportRecord } from './smart-report-store.js';
 
 // basename 提取，兼容不同路径格式
 function getProjectBaseName(p) {
@@ -87,9 +90,11 @@ export function startServer(config, effectiveIncludeProjects, buildReportData, c
   const PARSED_CACHE_TTL = 30_000; // 30s
 
   // ── 查询结果缓存（按查询条件缓存 buildReportData 结果） ──
-  const _reportCache = new Map();
-  const REPORT_CACHE_TTL = 30_000; // 30s
-  const REPORT_CACHE_MAX_SIZE = 50;
+  const _reportCache = new Map();
+  const REPORT_CACHE_TTL = 30_000; // 30s
+  const REPORT_CACHE_MAX_SIZE = 50;
+  const smartReportJobs = new Map();
+  const SMART_REPORT_JOB_KEEP_MS = 30 * 60_000;
 
   function getReportCacheKey(period, date, tool, customStart, customEnd) {
     return `${period}|${date}|${tool || 'all'}|${customStart || ''}|${customEnd || ''}`;
@@ -115,13 +120,38 @@ export function startServer(config, effectiveIncludeProjects, buildReportData, c
     _reportCache.clear();
   }
 
-  function writeJson(res, statusCode, data) {
+  function writeJson(res, statusCode, data) {
     res.writeHead(statusCode, {
       'Content-Type': 'application/json',
       'Access-Control-Allow-Origin': 'http://localhost:' + PORT,
     });
-    res.end(JSON.stringify(data));
-  }
+    res.end(JSON.stringify(data));
+  }
+
+  function publicSmartReportJob(job) {
+    if (!job) return null;
+    return {
+      id: job.id,
+      reportKey: job.reportKey,
+      status: job.status,
+      error: job.error || '',
+      startedAt: job.startedAt,
+      updatedAt: job.updatedAt,
+      completedAt: job.completedAt || '',
+    };
+  }
+
+  function rememberSmartReportJob(job) {
+    smartReportJobs.set(job.reportKey, job);
+    return job;
+  }
+
+  function forgetSmartReportJobLater(reportKey) {
+    setTimeout(() => {
+      const job = smartReportJobs.get(reportKey);
+      if (job && job.status !== 'running') smartReportJobs.delete(reportKey);
+    }, SMART_REPORT_JOB_KEEP_MS).unref?.();
+  }
 
   function parseHookTools(value) {
     if (!value) return [HOOK_TOOLS.CLAUDE, HOOK_TOOLS.CODEX, HOOK_TOOLS.OPENCODE];
@@ -181,7 +211,7 @@ export function startServer(config, effectiveIncludeProjects, buildReportData, c
     return result;
   }
 
-  function deriveProjectGitStats(gitStats, project, start, end, attributionOptions) {
+  function deriveProjectGitStats(gitStats, project, start, end, attributionOptions) {
     if (!gitStats?.commitList?.length || !project) return null;
     const windowEnd = end + 'T23:59:59';
     const commitList = gitStats.commitList.filter(c => {
@@ -199,10 +229,178 @@ export function startServer(config, effectiveIncludeProjects, buildReportData, c
       fileHotspots: computeFileHotspots(commitList, 10),
       aiContribution: computeAIContribution(commitList, null, attributionOptions),
       attributionSummary: gitStats.attributionSummary,
-    };
-  }
-
-  function prepareJsonReportData(baseData, tool) {
+    };
+  }
+
+  function parseSmartReportParams(input = {}) {
+    return {
+      agent: input.agent || '',
+      period: input.period || 'daily',
+      date: input.date || new Date().toISOString().slice(0, 10),
+      start: input.start || '',
+      end: input.end || '',
+      tool: input.tool || 'all',
+      project: input.project || '',
+      level: input.level || 'detailed',
+      style: input.style || 'default',
+      platform: input.platform || 'default',
+    };
+  }
+
+  function validateSmartReportParams(params) {
+    const validPeriods = ['daily', 'weekly', 'monthly', 'custom'];
+    if (!validPeriods.includes(params.period)) {
+      return `无效的 period 参数，可选值：${validPeriods.join('/')}`;
+    }
+    if (params.period === 'custom') {
+      if (!params.start || !params.end || !/^\d{4}-\d{2}-\d{2}$/.test(params.start) || !/^\d{4}-\d{2}-\d{2}$/.test(params.end)) {
+        return '自定义周期需要 start 和 end 参数 (YYYY-MM-DD)';
+      }
+      if (params.start > params.end) return '起始日期不能晚于结束日期';
+    }
+    const validStyles = ['default', 'workhorse'];
+    if (!validStyles.includes(params.style)) {
+      return `无效的 style 参数，可选值：${validStyles.join('/')}`;
+    }
+    return '';
+  }
+
+  function buildSmartReportRecordIdentity(params, data) {
+    return {
+      agent: params.agent,
+      period: params.period,
+      date: params.period === 'daily' ? data.start : '',
+      start: data.start,
+      end: data.end,
+      tool: params.tool,
+      project: params.project,
+      level: params.level,
+      style: params.style,
+      platform: params.platform,
+    };
+  }
+
+  function isSmartReportInternalRecord(record) {
+    const text = String(record?.metadata?.text || record?.text || '');
+    return text.includes(SMART_REPORT_PROMPT_MARKER)
+      || text.includes('LumenCode 的智能报告分析器');
+  }
+
+  function filterInternalSmartReportParsed(parsed) {
+    if (!parsed?.records?.length) return parsed;
+    const internalSessions = new Set(
+      parsed.records
+        .filter(isSmartReportInternalRecord)
+        .map(r => r.sessionId)
+        .filter(Boolean)
+    );
+    if (internalSessions.size === 0) return parsed;
+
+    const records = parsed.records.filter(r => !internalSessions.has(r.sessionId));
+    const toolBreakdown = {};
+    for (const [tool, base] of Object.entries(parsed.toolBreakdown || {})) {
+      toolBreakdown[tool] = { recordCount: 0, sessionCount: 0, error: base.error };
+    }
+    const groups = {};
+    for (const record of records) {
+      const tool = record.tool || 'claude';
+      if (!groups[tool]) groups[tool] = { recordCount: 0, sessions: new Set() };
+      groups[tool].recordCount++;
+      if (record.sessionId) groups[tool].sessions.add(record.sessionId);
+    }
+    for (const [tool, group] of Object.entries(groups)) {
+      toolBreakdown[tool] = {
+        recordCount: group.recordCount,
+        sessionCount: group.sessions.size,
+      };
+    }
+    return { ...parsed, records, toolBreakdown };
+  }
+
+  function sourceReportHashesMatch(record, source) {
+    const saved = record?.sourceReports || {};
+    const current = source?.sourceHashes || {};
+    if (!saved.detailedHash && !saved.briefHash && !saved.bossHash) return false;
+    return ['detailedHash', 'briefHash', 'bossHash'].every(key => (saved[key] || '') === (current[key] || ''));
+  }
+
+  function smartReportNeedsUpdate(record, source) {
+    if (!record?.sourceHash) return false;
+    if (record.sourceHash === source.sourceHash) return false;
+    if ((record.sourceHashVersion || 1) < 2 && sourceReportHashesMatch(record, source)) return false;
+    return true;
+  }
+
+  async function buildSmartReportSource(params) {
+    const includeProjects = computeIncludeProjects(config);
+    const parsed = filterInternalSmartReportParsed(await getOrParse(config, includeProjects));
+    const data = await buildReportData(params.period, params.date, config, includeProjects, params.tool, parsed, {
+      customStart: params.start,
+      customEnd: params.end,
+    });
+    if (!data) return null;
+
+    let reportData = data;
+    let workUsageStats = data.usageStats;
+    let workGitStats = data.gitStats;
+    let workPrevStats = data.prevStats;
+    let projectName = '';
+
+    if (params.project) {
+      const { records: allRecords } = parsed;
+      const toolRecords = params.tool !== 'all' ? allRecords.filter(r => r.tool === params.tool) : allRecords;
+      const projRecords = toolRecords.filter(r => getProjectBaseName(r.project) === params.project);
+      const { filtered: projFiltered, start: pStart, end: pEnd } = filterRecordsByPeriod(projRecords, params.period, params.date, { customStart: params.start, customEnd: params.end });
+      workUsageStats = projFiltered.length > 0 ? computeUsageStats(projFiltered, config.scenarioKeywords, config.costMode) : { requestCount: 0, projects: {} };
+      workPrevStats = null;
+      workGitStats = deriveProjectGitStats(data.gitStats, params.project, pStart, pEnd, config.aiAttribution);
+      projectName = params.project;
+      reportData = {
+        ...data,
+        usageStats: workUsageStats,
+        gitStats: workGitStats,
+        prevStats: workPrevStats,
+      };
+    }
+
+    const detailedMarkdown = generateWorkReport(workUsageStats, workGitStats, params.period, data.start, data.end, workPrevStats, { level: 'detailed', platform: params.platform, tool: params.tool, projectName });
+    const briefMarkdown = generateWorkReport(workUsageStats, workGitStats, params.period, data.start, data.end, workPrevStats, { level: 'brief', platform: params.platform, tool: params.tool, projectName });
+    const bossMarkdown = generateBossReport(workUsageStats, workGitStats, params.period, data.start, data.end, workPrevStats, params.platform);
+    const workMarkdown = params.level === 'brief' ? briefMarkdown : detailedMarkdown;
+    const includeBossSource = params.style === 'workhorse';
+    const sourceReports = {
+      detailedMarkdown,
+      briefMarkdown,
+      bossMarkdown: includeBossSource ? bossMarkdown : '',
+    };
+    const sourceHashes = {
+      detailedHash: buildSourceHash(detailedMarkdown),
+      briefHash: buildSourceHash(briefMarkdown),
+      bossHash: includeBossSource ? buildSourceHash(bossMarkdown) : '',
+    };
+    const sourceHash = buildSourceHash(buildSmartReportContext(reportData, workMarkdown, {
+      period: params.period,
+      date: params.date,
+      tool: params.tool,
+      project: params.project,
+      level: params.level,
+      style: params.style,
+      platform: params.platform,
+      sourceReports,
+    }));
+
+    return {
+      data,
+      reportData,
+      workMarkdown,
+      sourceReports,
+      sourceHashes,
+      sourceHash,
+      identity: buildSmartReportRecordIdentity(params, data),
+    };
+  }
+
+  function prepareJsonReportData(baseData, tool) {
     const data = { ...baseData };
 
     if (tool !== 'all' && data.gitStats?.aiContributionByTool) {
@@ -251,8 +449,146 @@ export function startServer(config, effectiveIncludeProjects, buildReportData, c
     res.setHeader('X-XSS-Protection', '1; mode=block');
     res.setHeader('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
 
-    // API endpoint
-    if (url.pathname === '/api/hooks') {
+    // API endpoint
+    if (url.pathname === '/api/smart-report/tools') {
+      try {
+        const tools = await detectSmartReportAgents();
+        writeJson(res, 200, { tools });
+      } catch (err) {
+        console.error('API error:', err.message);
+        writeJson(res, 500, { error: err.message || '服务端内部错误' });
+      }
+      return;
+    }
+
+    if (url.pathname === '/api/smart-report') {
+      if (req.method === 'GET') {
+        const params = parseSmartReportParams({
+          agent: url.searchParams.get('agent') || '',
+          period: url.searchParams.get('period') || 'daily',
+          date: url.searchParams.get('date') || '',
+          start: url.searchParams.get('start') || '',
+          end: url.searchParams.get('end') || '',
+          tool: url.searchParams.get('tool') || 'all',
+          project: url.searchParams.get('project') || '',
+          level: url.searchParams.get('level') || 'detailed',
+          style: url.searchParams.get('style') || 'default',
+          platform: url.searchParams.get('platform') || 'default',
+        });
+        const validationError = validateSmartReportParams(params);
+        if (validationError) {
+          writeJson(res, 400, { error: validationError });
+          return;
+        }
+
+        const source = await buildSmartReportSource(params);
+        if (!source) {
+          writeJson(res, 200, { record: null, needsUpdate: false });
+          return;
+        }
+
+        const storeDir = getSmartReportStoreDir(configPath);
+        let record = readSmartReportRecord(storeDir, buildSmartReportKey(source.identity));
+        if (!record) {
+          record = readSmartReportRecord(storeDir, buildSmartReportKey(params));
+        }
+        const reportKey = buildSmartReportKey(source.identity);
+        const job = smartReportJobs.get(reportKey) || null;
+        const needsUpdate = smartReportNeedsUpdate(record, source);
+        writeJson(res, 200, {
+          record,
+          job: publicSmartReportJob(job),
+          needsUpdate,
+          currentSourceHash: source.sourceHash,
+          range: { start: source.data.start, end: source.data.end },
+        });
+        return;
+      }
+
+      if (req.method !== 'POST') {
+        writeJson(res, 405, { error: 'Method not allowed' });
+        return;
+      }
+
+      readJsonBody(req, res, async (body) => {
+        const params = parseSmartReportParams(body);
+        const validationError = validateSmartReportParams(params);
+        if (validationError) {
+          writeJson(res, 400, { error: validationError });
+          return;
+        }
+
+        const source = await buildSmartReportSource(params);
+        if (!source) {
+          writeJson(res, 404, { error: '未找到可用于智能报告的数据' });
+          return;
+        }
+
+        const storeDir = getSmartReportStoreDir(configPath);
+        const reportKey = buildSmartReportKey(source.identity);
+        const existingJob = smartReportJobs.get(reportKey);
+        if (existingJob?.status === 'running') {
+          const record = readSmartReportRecord(storeDir, reportKey);
+          writeJson(res, 202, {
+            record,
+            job: publicSmartReportJob(existingJob),
+            needsUpdate: smartReportNeedsUpdate(record, source),
+            currentSourceHash: source.sourceHash,
+          });
+          return;
+        }
+
+        const job = rememberSmartReportJob({
+          id: randomUUID(),
+          reportKey,
+          status: 'running',
+          error: '',
+          startedAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+          completedAt: '',
+        });
+
+        Promise.resolve().then(async () => {
+          try {
+            const markdown = await createSmartReport({
+              agent: params.agent,
+              reportData: source.reportData,
+              workMarkdown: source.workMarkdown,
+              options: { period: params.period, date: params.date, tool: params.tool, project: params.project, level: params.level, style: params.style, platform: params.platform, sourceReports: source.sourceReports },
+              requireAvailable: true,
+            });
+            const record = saveSmartReportRecord(storeDir, {
+              ...source.identity,
+              markdown,
+              sourceHash: source.sourceHash,
+              sourceHashVersion: 2,
+              sourceReports: source.sourceHashes,
+            });
+            job.status = 'completed';
+            job.record = record;
+            job.completedAt = new Date().toISOString();
+            job.updatedAt = job.completedAt;
+          } catch (err) {
+            job.status = 'failed';
+            job.error = err.message || '智能报告生成失败';
+            job.updatedAt = new Date().toISOString();
+          } finally {
+            forgetSmartReportJobLater(reportKey);
+          }
+        });
+
+        const record = readSmartReportRecord(storeDir, reportKey);
+        writeJson(res, 202, {
+          record,
+          job: publicSmartReportJob(job),
+          needsUpdate: smartReportNeedsUpdate(record, source),
+          currentSourceHash: source.sourceHash,
+        });
+      });
+      return;
+    }
+
+    if (url.pathname === '/api/hooks') {
       try {
         if (req.method === 'GET') {
           writeJson(res, 200, getConfiguredHooksStatus(config));
@@ -402,11 +738,12 @@ export function startServer(config, effectiveIncludeProjects, buildReportData, c
           return;
         }
 
-        if (format === 'work') {
-          const platform = url.searchParams.get('platform') || 'default';
-          const level = url.searchParams.get('level') || 'detailed';
-          const feishuCard = url.searchParams.get('feishuCard') === 'true';
-          const project = url.searchParams.get('project') || '';
+        if (format === 'work') {
+          const platform = url.searchParams.get('platform') || 'default';
+          const requestedLevel = url.searchParams.get('level') || 'detailed';
+          const level = requestedLevel === 'brief' ? 'brief' : 'detailed';
+          const feishuCard = url.searchParams.get('feishuCard') === 'true';
+          const project = url.searchParams.get('project') || '';
 
           if (feishuCard) {
             const card = generateFeishuCard(data.usageStats, data.gitStats, period, data.start, data.end, tool);
@@ -446,12 +783,7 @@ export function startServer(config, effectiveIncludeProjects, buildReportData, c
             projGitStats = deriveProjectGitStats(data.gitStats, project, pStart, pEnd, config.aiAttribution);
           }
 
-          let markdown;
-          if (level === 'boss') {
-            markdown = generateBossReport(projUsageStats, projGitStats, period, data.start, data.end, projPrevStats, platform);
-          } else {
-            markdown = generateWorkReport(projUsageStats, projGitStats, period, data.start, data.end, projPrevStats, { level, platform, tool, projectName });
-          }
+          const markdown = generateWorkReport(projUsageStats, projGitStats, period, data.start, data.end, projPrevStats, { level, platform, tool, projectName });
           res.writeHead(200, {
             'Content-Type': 'text/plain; charset=utf-8',
             'Access-Control-Allow-Origin': 'http://localhost:' + PORT,

package/lib/smart-report-store.js

@@ -0,0 +1,98 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { createHash } from 'crypto';
+
+const STORE_FILE = 'records.json';
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function hashText(text) {
+  return createHash('sha256').update(String(text)).digest('hex');
+}
+
+export function getSmartReportStoreDir(configPath) {
+  return join(dirname(configPath || join(process.cwd(), 'config.json')), 'smart-reports');
+}
+
+export function buildSmartReportKey(input = {}) {
+  return hashText(stableStringify({
+    agent: input.agent || '',
+    period: input.period || '',
+    date: input.date || '',
+    start: input.start || '',
+    end: input.end || '',
+    tool: input.tool || 'all',
+    project: input.project || '',
+    level: input.level || 'detailed',
+    style: input.style && input.style !== 'default' ? input.style : '',
+    platform: input.platform || 'default',
+  }));
+}
+
+export function buildSourceHash(source = {}) {
+  return hashText(stableStringify(source));
+}
+
+function getStorePath(storeDir) {
+  return join(storeDir, STORE_FILE);
+}
+
+function readStore(storeDir) {
+  const file = getStorePath(storeDir);
+  if (!existsSync(file)) return { records: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || !parsed.records) return { records: {} };
+    return parsed;
+  } catch {
+    return { records: {} };
+  }
+}
+
+function writeStore(storeDir, store) {
+  if (!existsSync(storeDir)) mkdirSync(storeDir, { recursive: true });
+  writeFileSync(getStorePath(storeDir), JSON.stringify(store, null, 2), 'utf8');
+}
+
+export function readSmartReportRecord(storeDir, reportKey) {
+  const store = readStore(storeDir);
+  return store.records[reportKey] || null;
+}
+
+export function saveSmartReportRecord(storeDir, input) {
+  const store = readStore(storeDir);
+  const reportKey = buildSmartReportKey(input);
+  const now = new Date().toISOString();
+  const existing = store.records[reportKey] || null;
+  const record = {
+    id: existing?.id || reportKey,
+    reportKey,
+    agent: input.agent || '',
+    period: input.period || '',
+    date: input.date || '',
+    start: input.start || '',
+    end: input.end || '',
+    tool: input.tool || 'all',
+    project: input.project || '',
+    level: input.level || 'detailed',
+    style: input.style || 'default',
+    platform: input.platform || 'default',
+    markdown: input.markdown || '',
+    sourceHash: input.sourceHash || '',
+    sourceHashVersion: input.sourceHashVersion || 1,
+    sourceReports: input.sourceReports || {},
+    createdAt: existing?.createdAt || now,
+    updatedAt: now,
+    generatedCount: (existing?.generatedCount || 0) + 1,
+  };
+
+  store.records[reportKey] = record;
+  writeStore(storeDir, store);
+  return record;
+}