@winspan/claude-forge 8.41.0 → 8.51.0

package/src/web/analytics/weekly-report.ts

@@ -0,0 +1,431 @@
+/**
+ * WeeklyReportGenerator — 周报生成引擎
+ *
+ * 基于现有 events / sessions / routing_events / skill_invocations / tasks 表
+ * 聚合上一周（ISO week，周一 00:00 — 周日 23:59）的关键指标，并提供
+ * Markdown 渲染输出。
+ *
+ * 不修改任何 schema：完全基于现有表。
+ */
+
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+
+export interface WeeklyReport {
+  generatedAt: string;
+  week: { start: string; end: string; isoWeekNumber: number };
+  overview: {
+    totalSessions: number;
+    totalEvents: number;
+    totalTasks: number;
+    activeProjects: string[];
+    activeDays: number;
+  };
+  agentDelegation: {
+    totalPrompts: number;
+    delegations: number;
+    rate: string;
+    weekOverWeek: string;
+    topAgents: Array<{ agent: string; count: number }>;
+  };
+  skills: {
+    invocations: number;
+    distinct: number;
+    topSkills: Array<{ skill_id: string; count: number }>;
+    neverUsed: string[];
+  };
+  tools: {
+    totalCalls: number;
+    topTools: Array<{ name: string; count: number }>;
+    failureRate: string;
+  };
+  files: {
+    topEdited: Array<{ path: string; editCount: number }>;
+    totalEdits: number;
+  };
+  anomalies: Array<{ type: string; description: string }>;
+}
+
+interface WeekRange {
+  startMs: number;
+  endMs: number;
+  startISO: string;
+  endISO: string;
+  isoWeekNumber: number;
+}
+
+const FILE_EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+
+export class WeeklyReportGenerator {
+  constructor(
+    private storage: SQLiteStorage,
+    private skillRegistry?: { getAll(): Array<{ id: string }> },
+  ) {}
+
+  /**
+   * 生成周报
+   * @param weekOffset 周偏移：0 = 本周, -1 = 上周, -2 = 上上周
+   */
+  generate(weekOffset: number = 0): WeeklyReport {
+    const week = this.computeWeekRange(weekOffset);
+    const previousWeek = this.computeWeekRange(weekOffset - 1);
+
+    const overview = this.aggregateOverview(week);
+    const agentDelegation = this.aggregateAgentDelegation(week, previousWeek);
+    const skills = this.aggregateSkills(week);
+    const tools = this.aggregateTools(week);
+    const files = this.aggregateFiles(week);
+    const anomalies = this.aggregateAnomalies(week);
+
+    return {
+      generatedAt: new Date().toISOString(),
+      week: {
+        start: week.startISO,
+        end: week.endISO,
+        isoWeekNumber: week.isoWeekNumber,
+      },
+      overview,
+      agentDelegation,
+      skills,
+      tools,
+      files,
+      anomalies,
+    };
+  }
+
+  // ── Aggregation methods ──────────────────────────────────────────────
+
+  private aggregateOverview(week: WeekRange): WeeklyReport['overview'] {
+    // H2 Phase 3: 改用 facade 聚合方法。
+    const overview = this.storage.aggregateOverviewByRange({
+      since: week.startISO,
+      until: week.endISO,
+    });
+    const activeProjects = this.storage.queryDistinctProjects({
+      since: week.startISO,
+      until: week.endISO,
+    });
+    const totalTasks = this.storage.countTasksByRange({
+      since: week.startISO,
+      until: week.endISO,
+    });
+
+    return {
+      totalSessions: overview.session_count || 0,
+      totalEvents: overview.event_count || 0,
+      totalTasks: totalTasks || 0,
+      activeProjects,
+      activeDays: overview.day_count || 0,
+    };
+  }
+
+  private aggregateAgentDelegation(
+    week: WeekRange,
+    previousWeek: WeekRange,
+  ): WeeklyReport['agentDelegation'] {
+    const current = this.computeAgentRate(week);
+    const previous = this.computeAgentRate(previousWeek);
+
+    const diff = current.rateNum - previous.rateNum;
+    const weekOverWeek = `${diff >= 0 ? '+' : ''}${diff.toFixed(1)}pp`;
+
+    return {
+      totalPrompts: current.totalPrompts,
+      delegations: current.delegations,
+      rate: `${current.rateNum.toFixed(1)}%`,
+      weekOverWeek,
+      topAgents: current.topAgents,
+    };
+  }
+
+  private computeAgentRate(week: WeekRange): {
+    totalPrompts: number;
+    delegations: number;
+    rateNum: number;
+    topAgents: Array<{ agent: string; count: number }>;
+  } {
+    const events = this.storage.queryRoutingEvents({
+      since_ts: week.startMs,
+      limit: 100000,
+    }).filter(e => e.ts < week.endMs);
+
+    const totalPrompts = events.length;
+    const delegations = events.filter(e => e.obeyed === 1).length;
+    const rateNum = totalPrompts > 0 ? (delegations / totalPrompts) * 100 : 0;
+
+    const agentMap = new Map<string, number>();
+    for (const e of events) {
+      if (e.obeyed === 1 && e.routed_to_name) {
+        agentMap.set(e.routed_to_name, (agentMap.get(e.routed_to_name) || 0) + 1);
+      }
+    }
+    const topAgents = Array.from(agentMap.entries())
+      .map(([agent, count]) => ({ agent, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 5);
+
+    return { totalPrompts, delegations, rateNum, topAgents };
+  }
+
+  private aggregateSkills(week: WeekRange): WeeklyReport['skills'] {
+    const invocations = this.storage.querySkillInvocations({
+      since: week.startMs,
+      limit: 100000,
+    }).filter(inv => inv.timestamp < week.endMs);
+
+    const skillMap = new Map<string, number>();
+    for (const inv of invocations) {
+      skillMap.set(inv.skill_id, (skillMap.get(inv.skill_id) || 0) + 1);
+    }
+
+    const topSkills = Array.from(skillMap.entries())
+      .map(([skill_id, count]) => ({ skill_id, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 5);
+
+    const allSkillIds = this.skillRegistry
+      ? this.skillRegistry.getAll().map(s => s.id)
+      : [];
+    const usedSet = new Set(skillMap.keys());
+    const neverUsed = allSkillIds.filter(id => !usedSet.has(id));
+
+    return {
+      invocations: invocations.length,
+      distinct: skillMap.size,
+      topSkills,
+      neverUsed,
+    };
+  }
+
+  private aggregateTools(week: WeekRange): WeeklyReport['tools'] {
+    // H2 Phase 3: 改用 facade。
+    // Phase 2 偏差：spec 列出的 aggregateToolUsage({ since, until, ... }) 实际只实现了
+    // since/limit/hook_type，缺 until。这里用 queryEventsByTimeRange + 内存聚合保留
+    // 旧 SQL 的 [since, until) 半开区间语义（changelog 已记）。
+    const preEvents = this.storage.queryEventsByTimeRange({
+      since: week.startISO,
+      until: week.endISO,
+    }).filter(e => e.hook_type === 'PreToolUse' && e.tool_name);
+
+    const toolCount = new Map<string, number>();
+    for (const ev of preEvents) {
+      const name = ev.tool_name as string;
+      if (!name) continue;
+      toolCount.set(name, (toolCount.get(name) || 0) + 1);
+    }
+    const toolRows = Array.from(toolCount.entries())
+      .map(([tool_name, cnt]) => ({ tool_name, cnt }))
+      .sort((a, b) => b.cnt - a.cnt);
+
+    const totalCalls = toolRows.reduce((sum, r) => sum + r.cnt, 0);
+    const topTools = toolRows.slice(0, 5).map(r => ({ name: r.tool_name, count: r.cnt }));
+
+    // Failure rate: facade 提供 [since, until) 半开区间精确计算。
+    const failure = this.storage.aggregateToolFailureRate({
+      since: week.startISO,
+      until: week.endISO,
+    });
+
+    const failureRate = failure.post_total > 0
+      ? `${((failure.failed / failure.post_total) * 100).toFixed(1)}%`
+      : '0.0%';
+
+    return {
+      totalCalls,
+      topTools,
+      failureRate,
+    };
+  }
+
+  private aggregateFiles(week: WeekRange): WeeklyReport['files'] {
+    // H2 Phase 3: 改用 facade 聚合方法。
+    const rows = this.storage.queryFileEditInputs({
+      since: week.startISO,
+      until: week.endISO,
+      tool_names: Array.from(FILE_EDIT_TOOLS),
+    });
+
+    const fileMap = new Map<string, number>();
+    let totalEdits = 0;
+    for (const row of rows) {
+      try {
+        const input = JSON.parse(row.tool_input) as { file_path?: string; notebook_path?: string };
+        const path = input.file_path || input.notebook_path;
+        if (typeof path === 'string' && path.length > 0) {
+          fileMap.set(path, (fileMap.get(path) || 0) + 1);
+          totalEdits++;
+        }
+      } catch {
+        // skip malformed JSON
+      }
+    }
+
+    const topEdited = Array.from(fileMap.entries())
+      .map(([path, editCount]) => ({ path, editCount }))
+      .sort((a, b) => b.editCount - a.editCount)
+      .slice(0, 5);
+
+    return { topEdited, totalEdits };
+  }
+
+  private aggregateAnomalies(_week: WeekRange): WeeklyReport['anomalies'] {
+    // Anomaly aggregation is delegated to AntiPatternDetector
+    // (exposed separately via /api/insights). Keep empty here.
+    return [];
+  }
+
+
+  // ── Helper methods ──────────────────────────────────────────────────
+
+  /**
+   * 计算 ISO 周的起止时间（周一 00:00:00 — 下周一 00:00:00）。
+   * weekOffset: 0 = 本周, -1 = 上周, -2 = 上上周
+   */
+  private computeWeekRange(weekOffset: number): WeekRange {
+    const now = new Date();
+    // 计算本周一（ISO week 起点）
+    const dayOfWeek = now.getDay(); // 0=Sun, 1=Mon, ...
+    const daysFromMonday = (dayOfWeek + 6) % 7; // Mon=0, Tue=1, ..., Sun=6
+
+    const monday = new Date(
+      now.getFullYear(),
+      now.getMonth(),
+      now.getDate() - daysFromMonday + weekOffset * 7,
+      0, 0, 0, 0,
+    );
+    const nextMonday = new Date(monday);
+    nextMonday.setDate(monday.getDate() + 7);
+
+    return {
+      startMs: monday.getTime(),
+      endMs: nextMonday.getTime(),
+      startISO: monday.toISOString(),
+      endISO: nextMonday.toISOString(),
+      isoWeekNumber: getISOWeekNumber(monday),
+    };
+  }
+
+
+  // ── Markdown rendering ──────────────────────────────────────────────
+
+  toMarkdown(report: WeeklyReport): string {
+    const { week, overview, agentDelegation, skills, tools, files, anomalies } = report;
+
+    const lines: string[] = [];
+    lines.push(`# 周报 — 第 ${week.isoWeekNumber} 周`);
+    lines.push('');
+    lines.push(`**周期**: ${week.start.slice(0, 10)} ~ ${week.end.slice(0, 10)}`);
+    lines.push(`**生成时间**: ${report.generatedAt}`);
+    lines.push('');
+
+    lines.push('## 概览');
+    lines.push('');
+    lines.push(`- 总会话数: **${overview.totalSessions}**`);
+    lines.push(`- 总事件数: **${overview.totalEvents}**`);
+    lines.push(`- 总任务数: **${overview.totalTasks}**`);
+    lines.push(`- 活跃天数: **${overview.activeDays}** 天`);
+    lines.push(`- 活跃项目: ${overview.activeProjects.length} 个`);
+    if (overview.activeProjects.length > 0) {
+      for (const p of overview.activeProjects) {
+        lines.push(`  - \`${p}\``);
+      }
+    }
+    lines.push('');
+
+    lines.push('## Agent 委托');
+    lines.push('');
+    lines.push(`- 总路由数: **${agentDelegation.totalPrompts}**`);
+    lines.push(`- 委托数: **${agentDelegation.delegations}**`);
+    lines.push(`- 委托率: **${agentDelegation.rate}** (环比 ${agentDelegation.weekOverWeek})`);
+    if (agentDelegation.topAgents.length > 0) {
+      lines.push('');
+      lines.push('**Top Agents**:');
+      lines.push('');
+      lines.push('| Agent | 调用次数 |');
+      lines.push('| --- | ---: |');
+      for (const a of agentDelegation.topAgents) {
+        lines.push(`| ${a.agent} | ${a.count} |`);
+      }
+    }
+    lines.push('');
+
+    lines.push('## Skills');
+    lines.push('');
+    lines.push(`- 调用总数: **${skills.invocations}**`);
+    lines.push(`- 不同 Skill: **${skills.distinct}**`);
+    if (skills.topSkills.length > 0) {
+      lines.push('');
+      lines.push('**Top Skills**:');
+      lines.push('');
+      lines.push('| Skill | 调用次数 |');
+      lines.push('| --- | ---: |');
+      for (const s of skills.topSkills) {
+        lines.push(`| ${s.skill_id} | ${s.count} |`);
+      }
+    }
+    if (skills.neverUsed.length > 0) {
+      lines.push('');
+      lines.push(`**从未使用** (${skills.neverUsed.length}): ${skills.neverUsed.map(s => `\`${s}\``).join(', ')}`);
+    }
+    lines.push('');
+
+    lines.push('## Tools');
+    lines.push('');
+    lines.push(`- 调用总数: **${tools.totalCalls}**`);
+    lines.push(`- 失败率: **${tools.failureRate}**`);
+    if (tools.topTools.length > 0) {
+      lines.push('');
+      lines.push('**Top Tools**:');
+      lines.push('');
+      lines.push('| Tool | 调用次数 |');
+      lines.push('| --- | ---: |');
+      for (const t of tools.topTools) {
+        lines.push(`| ${t.name} | ${t.count} |`);
+      }
+    }
+    lines.push('');
+
+    lines.push('## Files');
+    lines.push('');
+    lines.push(`- 编辑总数: **${files.totalEdits}**`);
+    if (files.topEdited.length > 0) {
+      lines.push('');
+      lines.push('**Top Edited**:');
+      lines.push('');
+      lines.push('| 文件 | 编辑次数 |');
+      lines.push('| --- | ---: |');
+      for (const f of files.topEdited) {
+        lines.push(`| \`${f.path}\` | ${f.editCount} |`);
+      }
+    }
+    lines.push('');
+
+    lines.push('## 异常');
+    lines.push('');
+    if (anomalies.length === 0) {
+      lines.push('本周无异常。');
+    } else {
+      for (const a of anomalies) {
+        lines.push(`- **${a.type}**: ${a.description}`);
+      }
+    }
+    lines.push('');
+
+    return lines.join('\n');
+  }
+}
+
+/**
+ * 计算 ISO 8601 周数。
+ */
+function getISOWeekNumber(date: Date): number {
+  const target = new Date(date.getTime());
+  // ISO 周以周四为锚点
+  target.setHours(0, 0, 0, 0);
+  target.setDate(target.getDate() + 3 - ((target.getDay() + 6) % 7));
+  const week1 = new Date(target.getFullYear(), 0, 4);
+  return 1 + Math.round(
+    ((target.getTime() - week1.getTime()) / 86400000
+      - 3 + ((week1.getDay() + 6) % 7)) / 7,
+  );
+}
+

package/src/web/auth-middleware.ts

@@ -0,0 +1,54 @@
+/**
+ * Web API Authorization middleware
+ *
+ * 复用 daemon 的 auth token 机制（~/.claude-forge/daemon.token），
+ * 对写操作（POST/PUT/DELETE）强制校验 Authorization: Bearer <token>。
+ *
+ * 设计要点：
+ * - 同源本机场景：token 文件 chmod 600，读到即等价身份确认
+ * - token 缺失（daemon 极早期启动）时放行以免死锁，由 daemon lifecycle 负责尽快写入
+ * - 读操作（GET）不走这里，保留前端轮询的向后兼容
+ */
+
+import fs from 'fs';
+import type { Request, Response, NextFunction } from 'express';
+import { FORGE_PATHS } from '../core/constants.js';
+
+const TOKEN_FILE = FORGE_PATHS.daemonToken();
+
+/** 读取当前 daemon auth token，不存在或读取失败返回 null */
+export function readAuthToken(): string | null {
+  try {
+    if (!fs.existsSync(TOKEN_FILE)) return null;
+    return fs.readFileSync(TOKEN_FILE, 'utf-8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Express middleware：强制 Authorization: Bearer <token> 校验
+ *
+ * - token 文件缺失：放行（早期启动保护）
+ * - header 缺失或不匹配：401
+ */
+export function requireAuth(req: Request, res: Response, next: NextFunction): void {
+  const expected = readAuthToken();
+  if (!expected) {
+    // 早期启动保护：daemon 尚未写 token，避免自锁
+    next();
+    return;
+  }
+
+  const auth = req.header('Authorization') ?? '';
+  const match = auth.match(/^Bearer\s+(.+)$/);
+  if (!match || match[1].trim() !== expected) {
+    res.status(401).json({
+      error: 'AUTH_REQUIRED',
+      message:
+        'Include "Authorization: Bearer <token>" header. Token is stored at ~/.claude-forge/daemon.token',
+    });
+    return;
+  }
+  next();
+}

package/src/web/routes/_helpers.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared helpers for web routes.
+ */
+
+/**
+ * Recursively truncate string/array fields inside an arbitrary value so the
+ * serialised JSON payload stays bounded. Used to keep tool input/output
+ * previews small in /api/tasks and /api/sessions.
+ *
+ * - strings longer than `maxLen` are sliced and suffixed with "..."
+ * - arrays are sliced to the first `arrayLimit` elements (NOT recursed into,
+ *   matching the original call sites' behaviour)
+ * - objects are walked recursively
+ * - everything else is returned as-is (including null/undefined)
+ */
+export function truncateField(
+  obj: unknown,
+  maxLen = 300,
+  arrayLimit = 10,
+): unknown {
+  if (!obj) return obj;
+  if (typeof obj === 'string') {
+    return obj.length > maxLen ? obj.slice(0, maxLen) + '...' : obj;
+  }
+  if (Array.isArray(obj)) return obj.slice(0, arrayLimit);
+  if (typeof obj === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+      result[k] = truncateField(v, maxLen, arrayLimit);
+    }
+    return result;
+  }
+  return obj;
+}