agentworkshop 0.7.59 → 0.7.61

package/server/services/workshop/agents/industrial/analysis-tools.ts

@@ -0,0 +1,242 @@
+/**
+ * 数据分析系统 · 分析报告留痕工具(analysis_save / analysis_query)。
+ *
+ * 定位:Agent Channel 把分析产出(关键结论/正文/支撑指标)持久化到平台台账,
+ * 实现"分析结果可留痕、随时可查回"。台账 append-only —— 本族无更新/删除工具
+ * (删仅 REST admin 面),保证留痕不可变。
+ *
+ * 权限语义(同族只读工具口径):
+ *   - 目标产线解析:显式 line_id(须在可见范围)→ 频道绑线兜底 → 都没有则拒。
+ *   - 可见产线 = 节点授权线 ∪ 绑定配方所在线 ∪ 频道绑线(agentOpsScope)。
+ *   - 不进 WRITE_TOOLS/grant-guard 写族:留痕是台账写入,非产线控制写;
+ *     能读该产线数据(≥readonly)的 Agent 才能留痕。
+ */
+import { randomUUID } from 'node:crypto'
+import { agentBadgeLabel } from '../agent-badge'
+import { getDcwController } from '../../dcw/dcw-controller'
+import { getDcwLineRepo } from '../../dcw/dcw-line.repo'
+import { recordOps } from '../../ops/ops'
+import { getAnalysisRepo } from '../../analysis/analysis.repo'
+import { agentOpsScope, channelBoundLineId, fmtAuditAt } from './ops-tools'
+
+export interface AnalysisSaveInput {
+  title?: string
+  summary?: string
+  conclusions?: string[] | string
+  report?: string
+  category?: string
+  line_id?: string
+  recipe_id?: string
+  recipe_version?: string
+  window_from?: string
+  window_to?: string
+  data_sources?: string
+  metrics?: Record<string, unknown>
+}
+
+export interface AnalysisQueryInput {
+  report_id?: string
+  line_id?: string
+  recipe_id?: string
+  category?: string
+  q?: string
+  from?: string
+  to?: string
+  limit?: number | string
+}
+
+/** 可见产线全集 = 节点授权线 ∪ 绑定配方所在线 ∪ 频道绑线(去重) */
+function readableLineIdsOf(agentId: string): string[] {
+  const bound = channelBoundLineId(agentId)
+  const scope = agentOpsScope(agentId)
+  if (!scope) return bound ? [bound] : []
+  return [...new Set([...scope.lineIds, ...scope.boundLineIds, ...(bound ? [bound] : [])])]
+}
+
+/** 目标产线解析:显式 line_id(须可读)→ 频道绑线兜底;返回产线视图或错误文案 */
+function resolveTargetLine(agentId: string, explicitLineId?: string): { lineId: string, lineName: string } | { error: string } {
+  const lineRepo = getDcwLineRepo()
+  const wanted = String(explicitLineId ?? '').trim() || channelBoundLineId(agentId)
+  if (!wanted) {
+    return { error: '无法确定目标产线:本频道未绑定产线,且未指定 line_id。请先绑线,或显式传入可见范围内的 line_id。' }
+  }
+  const line = lineRepo.byId(wanted)
+  if (!line) return { error: `产线不存在: ${wanted}` }
+  const readable = readableLineIdsOf(agentId)
+  if (!readable.includes(wanted)) {
+    return { error: `产线「${line.name}」不在你的可见范围(节点授权线/绑定配方线/频道绑线)。只能对可见产线留痕。` }
+  }
+  return { lineId: line.id, lineName: line.name }
+}
+
+/** 时间入参归一:epoch ms 数值串或 ISO 均收,统一出 ISO;无效返回 null(留空=未指明) */
+function normTimeArg(raw: unknown): string | null {
+  const s = String(raw ?? '').trim()
+  if (!s) return null
+  if (/^\d{10,}$/.test(s)) {
+    const ms = Number(s)
+    return Number.isFinite(ms) ? new Date(ms).toISOString() : null
+  }
+  const t = Date.parse(s)
+  return Number.isNaN(t) ? null : new Date(t).toISOString()
+}
+
+/** conclusions 归一:接受 string[] 或换行分隔的整段字符串(LLM 两种形态都常见) */
+function normConclusions(raw: AnalysisSaveInput['conclusions']): string[] {
+  if (Array.isArray(raw)) return raw.map(x => String(x).trim()).filter(Boolean)
+  return String(raw ?? '')
+    .split('\n')
+    .map(x => x.replace(/^[-*\d.\s]+/, '').trim())
+    .filter(Boolean)
+}
+
+/** 频道名快照(归因用;经全局 manager 直读,未装配/直调上下文留空 —— 同 channelBoundLineId 模式) */
+function channelNameOf(channelId?: string): string {
+  if (!channelId) return ''
+  try {
+    const g = globalThis as typeof globalThis & {
+      __workshopManager?: { deps: { repos: { channels: { findById(id: string): { name?: string } | undefined } } } }
+    }
+    return g.__workshopManager?.deps.repos.channels.findById(channelId)?.name ?? ''
+  }
+  catch {
+    return ''
+  }
+}
+
+/** 产线上下文快照:保存瞬间把产品/批次/控制模式固化进台账 */
+function lineContextSnapshot(lineId: string): Record<string, unknown> {
+  try {
+    const ctrl = getDcwController()
+    const st = ctrl.lineState(lineId)
+    const line = getDcwLineRepo().byId(lineId)
+    return {
+      controlMode: line?.controlMode ?? '',
+      activeRun: st?.active
+        ? { runId: st.runId, recipeName: st.recipeName, productName: st.productName, startedAt: st.startedAt }
+        : null,
+    }
+  }
+  catch {
+    return {}
+  }
+}
+
+/** 工具:analysis_save —— 把本次分析的关键结论与产出持久化到平台分析台账(数据留痕)。 */
+export async function toolAnalysisSave(agentId: string, args: AnalysisSaveInput, channelId?: string): Promise<{ text: string, isError?: boolean }> {
+  const title = String(args.title ?? '').trim()
+  const summary = String(args.summary ?? '').trim()
+  if (!title) return { text: 'title 必填:分析主题(如「BOPET 线膜厚漂移根因分析」),台账列表靠它辨认。', isError: true }
+  if (!summary) return { text: 'summary 必填:一句话关键结论 —— 这是留痕的核心产出,人扫一眼列表要能看懂。', isError: true }
+
+  const line = resolveTargetLine(agentId, args.line_id)
+  if ('error' in line) return { text: line.error, isError: true }
+
+  // 配方联动:校验存在性 + 归属(留痕的 recipe 字段要可信)
+  const recipeId = String(args.recipe_id ?? '').trim()
+  let recipeVersion = String(args.recipe_version ?? '').trim()
+  if (recipeId) {
+    const recipe = getDcwController().listRecipes().find(r => r.id === recipeId)
+    if (!recipe) return { text: `配方 ${recipeId} 不存在,recipe_id 留痕被拒(可用 line_context 查看当前配方)。`, isError: true }
+    if (recipe.lineId && recipe.lineId !== line.lineId) {
+      return { text: `配方「${recipe.name}」不属于产线「${line.lineName}」,不能挂到该线的分析报告下。`, isError: true }
+    }
+    if (!recipeVersion) recipeVersion = String(recipe.version ?? '')
+  }
+
+  const channelName = channelNameOf(channelId)
+  const id = `ar-${randomUUID().replace(/-/g, '').slice(0, 8)}`
+  const now = new Date().toISOString()
+  const conclusions = normConclusions(args.conclusions)
+  const windowFrom = normTimeArg(args.window_from)
+  const windowTo = normTimeArg(args.window_to)
+
+  getAnalysisRepo().insert({
+    id,
+    lineId: line.lineId,
+    lineName: line.lineName,
+    title,
+    category: String(args.category ?? '').trim() || 'general',
+    summary,
+    conclusions,
+    report: String(args.report ?? ''),
+    metrics: (args.metrics && typeof args.metrics === 'object' && !Array.isArray(args.metrics) ? args.metrics : {}) as Record<string, unknown>,
+    recipeId,
+    recipeVersion,
+    windowFrom,
+    windowTo,
+    dataSources: String(args.data_sources ?? ''),
+    context: lineContextSnapshot(line.lineId),
+    channelId: channelId ?? '',
+    channelName,
+    actor: agentId,
+    actorName: agentBadgeLabel(agentId),
+    createdAt: now,
+  })
+
+  try {
+    recordOps({
+      actor: agentId, actorName: agentBadgeLabel(agentId), actorKind: 'agent',
+      action: 'analysis.save', kind: 'analysis', targetKind: 'analysis', targetId: id,
+      lineId: line.lineId, recipeId,
+      summary: `Agent 留痕分析报告「${title}」:产线「${line.lineName}」${recipeId ? `,配方 ${recipeId}` : ''} — ${summary}`,
+    })
+  }
+  catch { /* 审计失败不影响留痕 */ }
+
+  const win = windowFrom || windowTo ? `(数据窗 ${windowFrom ?? '?'} ~ ${windowTo ?? '?'})` : ''
+  return { text: `分析报告已留痕:${id}。产线「${line.lineName}」${win},结论 ${conclusions.length} 条,配方 ${recipeId || '未关联'}。台账 append-only,不可改删;随时可用 analysis_query(report_id="${id}") 查回全文。` }
+}
+
+/** 工具:analysis_query —— 查询历史分析报告(report_id 精确查全文;或按线/配方/时间/关键词列表)。 */
+export async function toolAnalysisQuery(agentId: string, args: AnalysisQueryInput): Promise<{ text: string, isError?: boolean }> {
+  const readable = readableLineIdsOf(agentId)
+  const reportId = String(args.report_id ?? '').trim()
+  const repo = getAnalysisRepo()
+
+  if (reportId) {
+    const report = repo.get(reportId)
+    if (!report) return { text: `分析报告不存在: ${reportId}(留痕不可变,也没有删除找回;请核对 id)。`, isError: true }
+    if (report.lineId && !readable.includes(report.lineId)) {
+      return { text: `分析报告 ${reportId} 属于产线「${report.lineName}」,不在你的可见范围。`, isError: true }
+    }
+    const head = [
+      `分析报告 ${report.id}:「${report.title}」(分类 ${report.category})`,
+      `产线: ${report.lineName || report.lineId || '-'} | 配方: ${report.recipeId || '-'}${report.recipeVersion ? ` v${report.recipeVersion}` : ''}`,
+      `分析时间: ${fmtAuditAt(report.createdAt)} | 数据窗: ${report.windowFrom ? fmtAuditAt(report.windowFrom) : '-'} ~ ${report.windowTo ? fmtAuditAt(report.windowTo) : '-'}`,
+      `来源: ${report.actorName || report.actor}${report.channelName ? ` @频道「${report.channelName}」` : ''}`,
+      `关键结论: ${report.summary}`,
+      ...(report.conclusions.length ? [`结论明细:\n${report.conclusions.map((c, i) => `  ${i + 1}. ${c}`).join('\n')}`] : []),
+    ]
+    const body = report.report ? `\n\n— 完整分析正文 —\n${report.report}` : ''
+    const metrics = Object.keys(report.metrics ?? {}).length ? `\n\n— 支撑指标 —\n${JSON.stringify(report.metrics, null, 1)}` : ''
+    return { text: `${head.join('\n')}${body}${metrics}` }
+  }
+
+  const explicitLine = String(args.line_id ?? '').trim()
+  if (explicitLine && !readable.includes(explicitLine)) {
+    return { text: `产线 ${explicitLine} 不在你的可见范围(节点授权线/绑定配方线/频道绑线)。`, isError: true }
+  }
+  // 作用域空集 = 不可见任何产线 → 直接空结果,不得落成"不过滤"(防越权列举全量台账)
+  if (!explicitLine && readable.length === 0) {
+    return { text: '你当前没有任何可见产线(无节点授权、无绑定配方、频道未绑线),暂无可查的分析报告。' }
+  }
+  const rows = repo.list({
+    lineId: explicitLine || undefined,
+    lineIds: explicitLine ? undefined : readable,
+    recipeId: String(args.recipe_id ?? '').trim() || undefined,
+    category: String(args.category ?? '').trim() || undefined,
+    q: String(args.q ?? '').trim() || undefined,
+    from: normTimeArg(args.from) ?? undefined,
+    to: normTimeArg(args.to) ?? undefined,
+    limit: Math.min(50, Math.max(1, Number(args.limit) || 20)),
+  })
+  if (rows.length === 0) {
+    return { text: `可见范围内暂无匹配的分析报告${args.q ? `(关键词「${String(args.q)}」)` : ''}。留痕由各频道的 analysis_save 产生;若是刚分析完,确认保存工具已被调用。` }
+  }
+  const lines = rows.map((r) => {
+    const recipe = r.recipeId ? ` | 配方 ${r.recipeId}${r.recipeVersion ? ` v${r.recipeVersion}` : ''}` : ''
+    return `[${r.id}] ${fmtAuditAt(r.createdAt)} | ${r.lineName || r.lineId || '-'}${recipe} | ${r.title}(${r.category})\n    ${r.summary} —— ${r.actorName || r.actor}${r.channelName ? ` @「${r.channelName}」` : ''}`
+  })
+  return { text: `共 ${rows.length} 条分析报告(新→旧):\n${lines.join('\n')}\n\n用 analysis_query(report_id="ar-xxxx") 查看单条完整正文与结论明细。` }
+}

package/server/services/workshop/agents/industrial/index.ts

@@ -29,3 +29,4 @@ export { toolTwinProviderCatalog, toolTwinSceneDiscover, toolTwinSceneCompile, t
 export { toolAmlActivity } from './aml-activity'
 export { toolRecipePropose } from './recipe-propose-tools'
 export { toolLineStart, toolLineStop, toolLineStatus } from './line-tools'
+export { toolAnalysisSave, toolAnalysisQuery } from './analysis-tools'

package/server/services/workshop/agents/industrial/ops-tools.ts

@@ -21,8 +21,9 @@ import { assertRecipeOperation, recipeApprovalPayload } from './recipe-gate'
 // 运维日志 / Recipe 变更史查询(Agent 自查面:负责产线 scoped)
 // ================================================================
 
-/** v18:频道绑定产线(只读扩权)——经全局 manager 读;manager 未装配/未绑定 = null */
-function channelBoundLineId(agentId: string): string | null {
+/** v18:频道绑定产线(只读扩权)——经全局 manager 读;manager 未装配/未绑定 = null
+ *  (export 供 analysis-tools 等同族工具复用「频道绑线=默认目标产线」语义) */
+export function channelBoundLineId(agentId: string): string | null {
   try {
     const g = globalThis as typeof globalThis & {
       __workshopManager?: { channelLineBindingOf(id: string): string | null }

package/server/services/workshop/analysis/analysis.repo.ts

@@ -0,0 +1,241 @@
+/**
+ * 数据分析系统 · 分析报告台账(analysis_reports)。
+ *
+ * 定位:Agent Channel 分析产出的持久留痕 —— append-only,工具面只提供 save/query,
+ * 无更新与删除(删仅 REST admin 面)。产线/配方/时间/关键结论为一级字段;
+ * 归因(channel/actor)与产线上下文在保存时快照固化,产线改名或删除后历史仍可读。
+ *
+ * 头注释铁律同 aml.repo:全部参数绑定(无字符串拼 SQL;LIKE 的 % 也在参数侧)。
+ */
+import type { DatabaseSync, SQLInputValue } from 'node:sqlite'
+
+export interface AnalysisReportRow {
+  id: string
+  lineId: string
+  lineName: string
+  title: string
+  category: string
+  /** 一句话关键结论(列表面展示) */
+  summary: string
+  /** 关键结论数组(结构化发现) */
+  conclusions: string[]
+  /** 完整分析正文(markdown) */
+  report: string
+  /** 支撑指标/数据 */
+  metrics: Record<string, unknown>
+  recipeId: string
+  recipeVersion: string
+  /** 分析的数据时间窗(ISO;空 = 未指明) */
+  windowFrom: string | null
+  windowTo: string | null
+  /** 证据来源说明(daq 窗口/mes 数据集/批次号等,人读) */
+  dataSources: string
+  /** 保存时的产线上下文快照(产品/批次/控制模式等) */
+  context: Record<string, unknown>
+  channelId: string
+  channelName: string
+  actor: string
+  actorName: string
+  createdAt: string
+  /** v27 人工修订归因(未修订 = null/空) */
+  updatedAt: string | null
+  updatedBy: string
+  updatedByName: string
+}
+
+export interface AnalysisReportInput {
+  id: string
+  lineId: string
+  lineName: string
+  title: string
+  category: string
+  summary: string
+  conclusions: string[]
+  report: string
+  metrics: Record<string, unknown>
+  recipeId: string
+  recipeVersion: string
+  windowFrom: string | null
+  windowTo: string | null
+  dataSources: string
+  context: Record<string, unknown>
+  channelId: string
+  channelName: string
+  actor: string
+  actorName: string
+  createdAt: string
+}
+
+export interface AnalysisReportFilter {
+  /** 作用域限制(可见产线集合;空 = 不限) */
+  lineIds?: string[]
+  lineId?: string
+  recipeId?: string
+  category?: string
+  /** 关键词(title/summary LIKE) */
+  q?: string
+  /** created_at 下/上界(ISO) */
+  from?: string
+  to?: string
+  limit?: number
+}
+
+const COLS = `id, line_id AS lineId, line_name AS lineName, title, category, summary,
+  conclusions_json AS conclusionsJson, report, metrics_json AS metricsJson,
+  recipe_id AS recipeId, recipe_version AS recipeVersion,
+  window_from AS windowFrom, window_to AS windowTo, data_sources AS dataSources,
+  context_json AS contextJson, channel_id AS channelId, channel_name AS channelName,
+  actor, actor_name AS actorName, created_at AS createdAt,
+  updated_at AS updatedAt, updated_by AS updatedBy, updated_by_name AS updatedByName`
+
+function rowToReport(r: Record<string, unknown>): AnalysisReportRow {
+  const parseJson = (raw: unknown, dflt: unknown): unknown => {
+    try {
+      return JSON.parse(String(raw ?? '')) ?? dflt
+    }
+    catch {
+      return dflt
+    }
+  }
+  return {
+    ...(r as unknown as Omit<AnalysisReportRow, 'conclusions' | 'metrics' | 'context' | 'conclusionsJson' | 'metricsJson' | 'contextJson'>),
+    conclusions: parseJson(r.conclusionsJson, []) as string[],
+    metrics: parseJson(r.metricsJson, {}) as Record<string, unknown>,
+    context: parseJson(r.contextJson, {}) as Record<string, unknown>,
+  } as AnalysisReportRow
+}
+
+export function createAnalysisRepo(db: DatabaseSync) {
+  const insertStmt = db.prepare(
+    `INSERT INTO analysis_reports (id, line_id, line_name, title, category, summary,
+       conclusions_json, report, metrics_json, recipe_id, recipe_version,
+       window_from, window_to, data_sources, context_json,
+       channel_id, channel_name, actor, actor_name, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  )
+  // v27 人工修订:读改写单条全量 UPDATE(patch 在调用方合并,语句一次 prepare)
+  const updateStmt = db.prepare(
+    `UPDATE analysis_reports SET title = ?, category = ?, summary = ?, conclusions_json = ?,
+       report = ?, metrics_json = ?, recipe_id = ?, recipe_version = ?,
+       window_from = ?, window_to = ?, data_sources = ?,
+       updated_at = ?, updated_by = ?, updated_by_name = ?
+     WHERE id = ?`,
+  )
+  const getStmt = db.prepare(`SELECT ${COLS} FROM analysis_reports WHERE id = ?`)
+  const removeStmt = db.prepare(`DELETE FROM analysis_reports WHERE id = ?`)
+  const countStmt = db.prepare('SELECT COUNT(*) AS c FROM analysis_reports')
+
+  return {
+    insert(row: AnalysisReportInput): void {
+      insertStmt.run(
+        row.id, row.lineId, row.lineName, row.title, row.category, row.summary,
+        JSON.stringify(row.conclusions ?? []), row.report ?? '', JSON.stringify(row.metrics ?? {}),
+        row.recipeId ?? '', row.recipeVersion ?? '',
+        row.windowFrom ?? null, row.windowTo ?? null, row.dataSources ?? '', JSON.stringify(row.context ?? {}),
+        row.channelId ?? '', row.channelName ?? '', row.actor ?? '', row.actorName ?? '', row.createdAt,
+      )
+    },
+    get(id: string): AnalysisReportRow | undefined {
+      const r = getStmt.get(id) as Record<string, unknown> | undefined
+      return r ? rowToReport(r) : undefined
+    },
+    list(filter: AnalysisReportFilter = {}): AnalysisReportRow[] {
+      const where: string[] = []
+      const args: SQLInputValue[] = []
+      if (filter.lineId) {
+        where.push('line_id = ?')
+        args.push(filter.lineId)
+      }
+      if (filter.lineIds && filter.lineIds.length > 0) {
+        where.push(`line_id IN (${filter.lineIds.map(() => '?').join(', ')})`)
+        args.push(...filter.lineIds)
+      }
+      if (filter.recipeId) {
+        where.push('recipe_id = ?')
+        args.push(filter.recipeId)
+      }
+      if (filter.category) {
+        where.push('category = ?')
+        args.push(filter.category)
+      }
+      if (filter.q) {
+        // 关键词三列 LIKE:标题 / 一句话结论 / 结论明细(JSON 数组文本,元素原串可命中)
+        where.push('(title LIKE ? OR summary LIKE ? OR conclusions_json LIKE ?)')
+        const like = `%${filter.q}%`
+        args.push(like, like, like)
+      }
+      if (filter.from) {
+        where.push('created_at >= ?')
+        args.push(filter.from)
+      }
+      if (filter.to) {
+        where.push('created_at <= ?')
+        args.push(filter.to)
+      }
+      const sql = `SELECT ${COLS} FROM analysis_reports ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+        ORDER BY created_at DESC LIMIT ?`
+      args.push(Math.min(500, Math.max(1, filter.limit ?? 100)))
+      return (db.prepare(sql).all(...args) as unknown as Record<string, unknown>[]).map(rowToReport)
+    },
+    remove(id: string): boolean {
+      return Number(removeStmt.run(id).changes) > 0
+    },
+    /**
+     * v27 人工修订:部分字段更新(patch 缺省 = 保留原值),固化修订归因。
+     * 编辑面属人类管理操作(Agent 面仍无改删);调用方负责权限校验与窗口归一。
+     */
+    update(id: string, patch: {
+      title?: string
+      category?: string
+      summary?: string
+      conclusions?: string[]
+      report?: string
+      metrics?: Record<string, unknown>
+      recipeId?: string
+      recipeVersion?: string
+      windowFrom?: string | null
+      windowTo?: string | null
+      dataSources?: string
+    }, editor: { id: string, name: string }): AnalysisReportRow | undefined {
+      const cur = getStmt.get(id) as Record<string, unknown> | undefined
+      if (!cur) return undefined
+      const merged = rowToReport(cur)
+      updateStmt.run(
+        patch.title !== undefined ? patch.title : merged.title,
+        patch.category !== undefined ? patch.category : merged.category,
+        patch.summary !== undefined ? patch.summary : merged.summary,
+        JSON.stringify(patch.conclusions !== undefined ? patch.conclusions : merged.conclusions),
+        patch.report !== undefined ? patch.report : merged.report,
+        JSON.stringify(patch.metrics !== undefined ? patch.metrics : merged.metrics),
+        patch.recipeId !== undefined ? patch.recipeId : merged.recipeId,
+        patch.recipeVersion !== undefined ? patch.recipeVersion : merged.recipeVersion,
+        patch.windowFrom !== undefined ? patch.windowFrom : merged.windowFrom,
+        patch.windowTo !== undefined ? patch.windowTo : merged.windowTo,
+        patch.dataSources !== undefined ? patch.dataSources : merged.dataSources,
+        new Date().toISOString(),
+        editor.id,
+        editor.name,
+        id,
+      )
+      return this.get(id)
+    },
+    count(): number {
+      return Number((countStmt.get() as { c: number }).c)
+    },
+  }
+}
+
+export type AnalysisRepo = ReturnType<typeof createAnalysisRepo>
+
+let singleton: AnalysisRepo | null = null
+
+/** Nitro 插件启动时装配(plugins/workshop.ts) */
+export function configureAnalysisRepo(db: DatabaseSync): void {
+  singleton = createAnalysisRepo(db)
+}
+
+/** 运行期取用(未装配即抛 = 装配漏接线的响亮失败) */
+export function getAnalysisRepo(): AnalysisRepo {
+  if (!singleton) throw new Error('analysis repo 未装配(configureAnalysisRepo 未调用)')
+  return singleton
+}

package/server/services/workshop/db/database/migrations.ts

@@ -418,3 +418,13 @@ export function migrateAmlChannelOptimizationColumns(db: DatabaseSync): void {
   db.exec('CREATE INDEX IF NOT EXISTS idx_opt_explorations_channel ON optimization_explorations(channel_id, created_at DESC)')
   // aml_training_plans 建表由 SCHEMA_SQL 的 CREATE TABLE IF NOT EXISTS 兜底(启动时全量幂等执行,新旧库同效)
 }
+
+/**
+ * v27:数据分析报告人工修订列(updated_at/updated_by/updated_by_name)。
+ * 既有库补列(新库由 SCHEMA_SQL 直建);无索引需求 —— 修订列只随行读,不作检索键。
+ */
+export function migrateAnalysisEditColumns(db: DatabaseSync): void {
+  migrateAddColumn(db, 'analysis_reports', 'updated_at', 'TEXT')
+  migrateAddColumn(db, 'analysis_reports', 'updated_by', 'TEXT NOT NULL DEFAULT \'\'')
+  migrateAddColumn(db, 'analysis_reports', 'updated_by_name', 'TEXT NOT NULL DEFAULT \'\'')
+}

package/server/services/workshop/db/database/open.ts

@@ -6,7 +6,7 @@ import type * as sqliteVec from 'sqlite-vec'
 import { DatabaseSync } from 'node:sqlite'
 import { SCHEMA_SQL } from './schema'
 import { createRequire } from 'node:module'
-import { migrateAddColumn, migrateAgentTeamExecutionLeaseColumns, migrateAgentTeamTaskGuardrailColumns, migrateAgentTeamTaskGuardrails, migrateAgentTeamTaskQueueColumns, migrateAmlChannelOptimizationColumns, migrateAmlModelIdentityColumns, migrateApprovalPayloadColumns, migrateDropOwnerFks, migrateGroupChatV17, migrateLegacySchema, migrateMissingForeignKeys, migrateAmlTwinProviderColumns } from './migrations'
+import { migrateAddColumn, migrateAgentTeamExecutionLeaseColumns, migrateAgentTeamTaskGuardrailColumns, migrateAgentTeamTaskGuardrails, migrateAgentTeamTaskQueueColumns, migrateAmlChannelOptimizationColumns, migrateAmlModelIdentityColumns, migrateAnalysisEditColumns, migrateApprovalPayloadColumns, migrateDropOwnerFks, migrateGroupChatV17, migrateLegacySchema, migrateMissingForeignKeys, migrateAmlTwinProviderColumns } from './migrations'
 import { seedDefaultWorkshopData } from './seed'
 
 export const require = createRequire(import.meta.url)
@@ -68,6 +68,8 @@ export function initWorkshopDb(db: DatabaseSync): void {
   migrateAmlChannelOptimizationColumns(db)
   // 产线 Co-Pilot P2:审批历史结构化载荷列(payload_json/choice;既有库补列,新库 DDL 已含)
   migrateApprovalPayloadColumns(db)
+  // v27:数据分析报告人工修订列(updated_*;既有库补列,新库 DDL 已含)
+  migrateAnalysisEditColumns(db)
   seedDefaultWorkshopData(db)
 }
 

package/server/services/workshop/db/database/schema.ts

@@ -748,7 +748,38 @@ CREATE TABLE IF NOT EXISTS mes_fetch_jobs (
 CREATE INDEX IF NOT EXISTS idx_mes_fetch_jobs_dataset ON mes_fetch_jobs(dataset_id);
 CREATE INDEX IF NOT EXISTS idx_mes_fetch_jobs_agent ON mes_fetch_jobs(agent_id, created_at DESC);
 
-CREATE INDEX IF NOT EXISTS idx_hitl_requests_agent ON hitl_requests(agent_id, status);`
+CREATE INDEX IF NOT EXISTS idx_hitl_requests_agent ON hitl_requests(agent_id, status);
+
+-- v26: 数据分析系统 · 分析报告台账(Agent Channel 经 analysis_save 留痕;Agent 面无改删)
+-- 归因与产线上下文在保存时快照固化(line_name/产品/批次),产线改名或删除后历史仍可读。
+-- v27: 人工修订面 —— 人类用户(产线 operate/admin)可经 REST 编辑,updated_* 固化修订归因。
+CREATE TABLE IF NOT EXISTS analysis_reports (
+  id TEXT PRIMARY KEY,
+  line_id TEXT NOT NULL DEFAULT '',
+  line_name TEXT NOT NULL DEFAULT '',
+  title TEXT NOT NULL,
+  category TEXT NOT NULL DEFAULT 'general',
+  summary TEXT NOT NULL DEFAULT '',
+  conclusions_json TEXT NOT NULL DEFAULT '[]',
+  report TEXT NOT NULL DEFAULT '',
+  metrics_json TEXT NOT NULL DEFAULT '{}',
+  recipe_id TEXT NOT NULL DEFAULT '',
+  recipe_version TEXT NOT NULL DEFAULT '',
+  window_from TEXT,
+  window_to TEXT,
+  data_sources TEXT NOT NULL DEFAULT '',
+  context_json TEXT NOT NULL DEFAULT '{}',
+  channel_id TEXT NOT NULL DEFAULT '',
+  channel_name TEXT NOT NULL DEFAULT '',
+  actor TEXT NOT NULL DEFAULT '',
+  actor_name TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL,
+  updated_at TEXT,
+  updated_by TEXT NOT NULL DEFAULT '',
+  updated_by_name TEXT NOT NULL DEFAULT ''
+);
+CREATE INDEX IF NOT EXISTS idx_analysis_reports_line ON analysis_reports(line_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_analysis_reports_recipe ON analysis_reports(recipe_id);`
 
 // ===== 默认种子数据(首轮初始化注入;owner NULL = 公共资源,所有登录用户只读共享) =====
 

package/server/services/workshop/db/ops.repo.ts

@@ -174,7 +174,7 @@ export interface AuditEntry {
   lineId?: string
   productId?: string
   recipeId?: string
-  kind?: 'write' | 'manual' | 'alarm' | 'line' | 'recipe' | 'rollback' | 'daq' | 'system'
+  kind?: 'write' | 'manual' | 'alarm' | 'line' | 'recipe' | 'rollback' | 'daq' | 'analysis' | 'system'
   summary?: string
   /** 严重级(2026-10-08 写控 ACK 鉴定):info 缺省 / warn(未证实) / error(写入失败);日志页红黄标 */
   level?: 'info' | 'warn' | 'error'

package/server/services/workshop/db/retention.ts

@@ -5,6 +5,7 @@
  *   messages          默认 30d   (retention.messages_days)
  *   audit_log         默认 90d   (retention.audit_days;合规观察期,从严保留)
  *   approval_history  默认 180d  (retention.approval_days;历史裁决主张不可变,放宽)
+ *   analysis_reports  默认 365d  (retention.analysis_days;数据分析留痕台账,最宽松)
  * retention.disabled 整体逃生门(env AW_RETENTION_DISABLED / RETENTION_DISABLED 兼容别名)。
  * 覆盖链:config.yml < runtime-settings < env(AW_<键> 或历史别名)。时间列均为 TEXT ISO。
  * channel_events 与 daq_samples 已有各自保留机制,此处不重复覆盖。
@@ -27,6 +28,7 @@ const TARGETS = [
   { table: 'messages', column: 'created_at', days: 30, cfgKey: 'messages_days' },
   { table: 'audit_log', column: 'at', days: 90, cfgKey: 'audit_days' },
   { table: 'approval_history', column: 'created_at', days: 180, cfgKey: 'approval_days' },
+  { table: 'analysis_reports', column: 'created_at', days: 365, cfgKey: 'analysis_days' },
 ] as const
 
 export interface RetentionResult { table: string, removed: number, days: number }

package/server/services/workshop/db/schema.sql

@@ -358,3 +358,34 @@ CREATE TABLE IF NOT EXISTS mes_fetch_jobs (
 );
 CREATE INDEX IF NOT EXISTS idx_mes_fetch_jobs_dataset ON mes_fetch_jobs(dataset_id);
 CREATE INDEX IF NOT EXISTS idx_mes_fetch_jobs_agent ON mes_fetch_jobs(agent_id, created_at DESC);
+
+-- v26: 数据分析系统 · 分析报告台账(Agent Channel 经 analysis_save 留痕;Agent 面无改删)
+-- 归因与产线上下文在保存时快照固化(line_name/产品/批次),产线改名或删除后历史仍可读。
+-- v27: 人工修订面 —— 人类用户(产线 operate/admin)可经 REST 编辑,updated_* 固化修订归因。
+CREATE TABLE IF NOT EXISTS analysis_reports (
+  id TEXT PRIMARY KEY,
+  line_id TEXT NOT NULL DEFAULT '',
+  line_name TEXT NOT NULL DEFAULT '',
+  title TEXT NOT NULL,
+  category TEXT NOT NULL DEFAULT 'general',
+  summary TEXT NOT NULL DEFAULT '',
+  conclusions_json TEXT NOT NULL DEFAULT '[]',
+  report TEXT NOT NULL DEFAULT '',
+  metrics_json TEXT NOT NULL DEFAULT '{}',
+  recipe_id TEXT NOT NULL DEFAULT '',
+  recipe_version TEXT NOT NULL DEFAULT '',
+  window_from TEXT,
+  window_to TEXT,
+  data_sources TEXT NOT NULL DEFAULT '',
+  context_json TEXT NOT NULL DEFAULT '{}',
+  channel_id TEXT NOT NULL DEFAULT '',
+  channel_name TEXT NOT NULL DEFAULT '',
+  actor TEXT NOT NULL DEFAULT '',
+  actor_name TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL,
+  updated_at TEXT,
+  updated_by TEXT NOT NULL DEFAULT '',
+  updated_by_name TEXT NOT NULL DEFAULT ''
+);
+CREATE INDEX IF NOT EXISTS idx_analysis_reports_line ON analysis_reports(line_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_analysis_reports_recipe ON analysis_reports(recipe_id);

package/server/services/workshop/settings.ts

@@ -141,6 +141,7 @@ export interface RetentionSettings {
   messages_days: number
   audit_days: number
   approval_days: number
+  analysis_days: number
 }
 export interface LogSettings {
   level: 'debug' | 'info' | 'warn' | 'error'

package/shared/config/schema.json

@@ -116,6 +116,7 @@
     { "key": "retention.messages_days", "type": "number", "group": "retention", "label": "消息保留(天)", "labelKey": "settings.runtime.retention.messagesDays", "description": "Channel 消息保留天数", "applies": "restart", "default": 30, "min": 1, "max": 3650 },
     { "key": "retention.audit_days", "type": "number", "group": "retention", "label": "审计日志保留(天)", "labelKey": "settings.runtime.retention.auditDays", "description": "审计日志保留天数(合规观察期,从严保留)", "applies": "restart", "default": 90, "min": 1, "max": 3650 },
     { "key": "retention.approval_days", "type": "number", "group": "retention", "label": "审批历史保留(天)", "labelKey": "settings.runtime.retention.approvalDays", "description": "审批历史保留天数(历史裁决主张不可变,放宽)", "applies": "restart", "default": 180, "min": 1, "max": 3650 },
+    { "key": "retention.analysis_days", "type": "number", "group": "retention", "label": "分析报告保留(天)", "labelKey": "settings.runtime.retention.analysisDays", "description": "数据分析报告台账保留天数(数据留痕,宽松保留)", "applies": "restart", "default": 365, "min": 1, "max": 3650 },
 
     { "key": "log.level", "type": "string", "group": "log", "label": "日志级别", "labelKey": "settings.runtime.log.level", "description": "服务端日志级别(debug/info/warn/error)", "applies": "restart", "default": "info", "aliases": ["AWSHOP_LOG_LEVEL"] },