autocrew 0.1.0

package/src/modules/research/free-engine.ts

@@ -0,0 +1,360 @@
+/**
+ * Free Research Engine — topic discovery using only public web search
+ *
+ * No crawlers, no third-party APIs. Pure web_search + style calibration + viral scoring.
+ *
+ * PRD §5: "Free 版选题（纯公开搜索）"
+ */
+import { loadProfile, type CreatorProfile } from "../profile/creator-profile.js";
+
+// --- Types ---
+
+export interface TopicCandidate {
+  title: string;
+  description: string;
+  tags: string[];
+  source: string;
+  /** 0-100 viral potential score */
+  viralScore: number;
+  /** Score breakdown */
+  scoreBreakdown: {
+    titleAppeal: number;
+    topicHeat: number;
+    profileFit: number;
+  };
+  /** Why this topic was suggested */
+  reasoning: string;
+}
+
+export interface FreeResearchResult {
+  ok: boolean;
+  keyword: string;
+  industry: string;
+  candidates: TopicCandidate[];
+  /** Search queries that were used */
+  searchQueries: string[];
+  /** Style filters applied */
+  filtersApplied: string[];
+  summary: string;
+}
+
+export interface SearchResult {
+  title: string;
+  snippet: string;
+  url: string;
+}
+
+/**
+ * Build search queries for topic discovery.
+ * Returns 3-5 queries tailored to the user's industry and keyword.
+ */
+export function buildSearchQueries(
+  keyword: string,
+  industry: string,
+  platforms: string[],
+): string[] {
+  const queries: string[] = [];
+  const currentMonth = new Date().toLocaleDateString("zh-CN", { year: "numeric", month: "long" });
+
+  // Core queries
+  queries.push(`${industry} ${keyword} 内容选题`);
+  queries.push(`${industry} 热门话题 ${currentMonth}`);
+  queries.push(`${keyword} 爆款内容 分析`);
+
+  // Platform-specific
+  const platformNames: Record<string, string> = {
+    xhs: "小红书",
+    xiaohongshu: "小红书",
+    douyin: "抖音",
+    wechat_mp: "公众号",
+    bilibili: "B站",
+  };
+  const primaryPlatform = platforms[0];
+  if (primaryPlatform && platformNames[primaryPlatform]) {
+    queries.push(`${keyword} ${platformNames[primaryPlatform]} 爆款`);
+  }
+
+  // Trend query
+  queries.push(`${keyword} 最新趋势 ${new Date().getFullYear()}`);
+
+  return queries;
+}
+
+/**
+ * Score a topic candidate for viral potential.
+ *
+ * Dimensions (each 0-33, total normalized to 0-100):
+ * - Title appeal: length, specificity, emotional triggers, numbers
+ * - Topic heat: keyword relevance, timeliness signals
+ * - Profile fit: alignment with user's industry, audience, writing rules
+ */
+export function scoreCandidate(
+  candidate: { title: string; description: string; tags: string[] },
+  profile: CreatorProfile | null,
+  keyword: string,
+): { viralScore: number; breakdown: TopicCandidate["scoreBreakdown"]; reasoning: string } {
+  let titleAppeal = 15;
+  let topicHeat = 15;
+  let profileFit = 15;
+  const reasons: string[] = [];
+
+  // --- Title Appeal ---
+  const titleLen = candidate.title.length;
+  // Optimal title length: 10-20 chars
+  if (titleLen >= 10 && titleLen <= 20) {
+    titleAppeal += 5;
+  } else if (titleLen > 25) {
+    titleAppeal -= 3;
+  }
+  // Numbers in title
+  if (/\d/.test(candidate.title)) {
+    titleAppeal += 5;
+    reasons.push("标题含数字，吸引力+");
+  }
+  // Emotional triggers
+  if (/别再|千万|后悔|真相|没想到|居然|竟然|绝了|必看|干货|避坑/.test(candidate.title)) {
+    titleAppeal += 5;
+    reasons.push("标题有情绪触发词");
+  }
+  // Specificity (not generic)
+  if (/推荐|分享|介绍|总结/.test(candidate.title) && !/\d/.test(candidate.title)) {
+    titleAppeal -= 5;
+    reasons.push("标题偏泛，建议加具体角度");
+  }
+  // Question format
+  if (/[？?]/.test(candidate.title)) {
+    titleAppeal += 3;
+  }
+  titleAppeal = clamp(titleAppeal, 0, 33);
+
+  // --- Topic Heat ---
+  // Keyword match
+  if (candidate.title.includes(keyword) || candidate.description.includes(keyword)) {
+    topicHeat += 5;
+  }
+  // Timeliness signals
+  const year = String(new Date().getFullYear());
+  if (candidate.description.includes(year) || candidate.description.includes("最新")) {
+    topicHeat += 5;
+    reasons.push("话题有时效性");
+  }
+  // Tags relevance
+  if (candidate.tags.length >= 3) {
+    topicHeat += 3;
+  }
+  // Description quality (has data/evidence)
+  if (/\d+[%％万亿]/.test(candidate.description)) {
+    topicHeat += 5;
+    reasons.push("描述引用了数据");
+  }
+  topicHeat = clamp(topicHeat, 0, 33);
+
+  // --- Profile Fit ---
+  if (profile) {
+    // Industry match
+    if (profile.industry && (candidate.title.includes(profile.industry) || candidate.tags.some((t) => t.includes(profile.industry)))) {
+      profileFit += 5;
+      reasons.push("与用户行业匹配");
+    }
+    // Audience match
+    if (profile.audiencePersona) {
+      const painPoints = profile.audiencePersona.painPoints || [];
+      for (const pain of painPoints) {
+        if (candidate.title.includes(pain) || candidate.description.includes(pain)) {
+          profileFit += 5;
+          reasons.push(`命中受众痛点: ${pain}`);
+          break;
+        }
+      }
+    }
+    // Style boundary check (never list)
+    const neverTopics = profile.styleBoundaries?.never || [];
+    for (const never of neverTopics) {
+      if (candidate.title.includes(never) || candidate.description.includes(never)) {
+        profileFit -= 10;
+        reasons.push(`触碰风格禁区: ${never}`);
+        break;
+      }
+    }
+  }
+  profileFit = clamp(profileFit, 0, 34);
+
+  const viralScore = clamp(titleAppeal + topicHeat + profileFit, 0, 100);
+  const reasoning = reasons.length > 0 ? reasons.join("；") : "综合评估";
+
+  return {
+    viralScore,
+    breakdown: { titleAppeal, topicHeat, profileFit },
+    reasoning,
+  };
+}
+
+/**
+ * Filter candidates against the user's style profile.
+ * Removes topics that conflict with writing rules or style boundaries.
+ */
+export function filterByStyle(
+  candidates: TopicCandidate[],
+  profile: CreatorProfile | null,
+): { filtered: TopicCandidate[]; filtersApplied: string[] } {
+  if (!profile) return { filtered: candidates, filtersApplied: [] };
+
+  const filtersApplied: string[] = [];
+  let filtered = [...candidates];
+
+  // Filter by style boundaries (never list)
+  const neverTopics = profile.styleBoundaries?.never || [];
+  if (neverTopics.length > 0) {
+    const before = filtered.length;
+    filtered = filtered.filter((c) => {
+      return !neverTopics.some(
+        (n) => c.title.includes(n) || c.description.includes(n),
+      );
+    });
+    if (filtered.length < before) {
+      filtersApplied.push(`排除了 ${before - filtered.length} 个触碰风格禁区的选题`);
+    }
+  }
+
+  // Filter low profile-fit scores
+  const lowFitBefore = filtered.length;
+  filtered = filtered.filter((c) => c.scoreBreakdown.profileFit >= 5);
+  if (filtered.length < lowFitBefore) {
+    filtersApplied.push(`排除了 ${lowFitBefore - filtered.length} 个与用户定位不匹配的选题`);
+  }
+
+  return { filtered, filtersApplied };
+}
+
+/**
+ * Process raw search results into scored topic candidates.
+ *
+ * This is the core function that the research skill/tool calls after
+ * performing web searches. It takes raw search results and produces
+ * scored, filtered topic candidates.
+ */
+export async function processSearchResults(
+  searchResults: SearchResult[],
+  keyword: string,
+  profile: CreatorProfile | null,
+  topicCount: number = 5,
+): Promise<{ candidates: TopicCandidate[]; filtersApplied: string[] }> {
+  // Deduplicate by title similarity
+  const seen = new Set<string>();
+  const unique = searchResults.filter((r) => {
+    const key = r.title.slice(0, 15);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  // Convert to candidates and score
+  let candidates: TopicCandidate[] = unique.map((r) => {
+    // Extract a concise title (≤20 chars)
+    let title = r.title.replace(/[-_|—–].*$/, "").trim();
+    if (title.length > 20) title = title.slice(0, 20);
+
+    // Extract tags from snippet
+    const tags = extractTags(r.snippet, keyword);
+
+    const { viralScore, breakdown, reasoning } = scoreCandidate(
+      { title, description: r.snippet, tags },
+      profile,
+      keyword,
+    );
+
+    return {
+      title,
+      description: r.snippet.slice(0, 200),
+      tags,
+      source: `web_search: ${r.url}`,
+      viralScore,
+      scoreBreakdown: breakdown,
+      reasoning,
+    };
+  });
+
+  // Style filter
+  const { filtered, filtersApplied } = filterByStyle(candidates, profile);
+  candidates = filtered;
+
+  // Sort by viral score descending
+  candidates.sort((a, b) => b.viralScore - a.viralScore);
+
+  // Return top N
+  return {
+    candidates: candidates.slice(0, topicCount),
+    filtersApplied,
+  };
+}
+
+/**
+ * Main entry: run the free research engine.
+ *
+ * Note: This function does NOT perform web searches itself — it expects
+ * the caller (skill or tool) to provide search results. This keeps the
+ * module pure and testable.
+ */
+export async function runFreeResearch(opts: {
+  keyword: string;
+  searchResults: SearchResult[];
+  topicCount?: number;
+  dataDir?: string;
+}): Promise<FreeResearchResult> {
+  const { keyword, searchResults, topicCount = 5, dataDir } = opts;
+  const profile = await loadProfile(dataDir);
+  const industry = profile?.industry || "通用";
+
+  const queries = buildSearchQueries(keyword, industry, profile?.platforms || []);
+  const { candidates, filtersApplied } = await processSearchResults(
+    searchResults,
+    keyword,
+    profile,
+    topicCount,
+  );
+
+  const summary =
+    candidates.length > 0
+      ? `找到 ${candidates.length} 个选题候选（最高分 ${candidates[0].viralScore}）`
+      : "未找到合适的选题候选，建议换个关键词或方向";
+
+  return {
+    ok: true,
+    keyword,
+    industry,
+    candidates,
+    searchQueries: queries,
+    filtersApplied,
+    summary,
+  };
+}
+
+// --- Helpers ---
+
+function clamp(v: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, v));
+}
+
+function extractTags(text: string, keyword: string): string[] {
+  const tags = new Set<string>();
+  tags.add(keyword);
+
+  // Extract hashtag-like patterns
+  const hashMatches = text.match(/#[\u4e00-\u9fffA-Za-z0-9]+/g);
+  if (hashMatches) {
+    for (const m of hashMatches.slice(0, 4)) {
+      tags.add(m.replace("#", ""));
+    }
+  }
+
+  // Extract quoted terms
+  const quoteMatches = text.match(/[「」""]/g) ? text.match(/[「「]([^」」]+)[」」]/g) : null;
+  if (quoteMatches) {
+    for (const m of quoteMatches.slice(0, 2)) {
+      const clean = m.replace(/[「」""]/g, "");
+      if (clean.length <= 8) tags.add(clean);
+    }
+  }
+
+  return Array.from(tags).slice(0, 5);
+}

package/src/modules/timeline/markup-generator.ts

@@ -0,0 +1,63 @@
+import type { VideoPreset } from "../../types/timeline.js";
+
+const CARD_TEMPLATES = `
+Available card templates:
+- comparison-table: attrs: title, rows (format: name:pros:cons,name:pros:cons)
+- key-points: attrs: items (comma-separated)
+- flow-chart: attrs: steps (comma-separated)
+- data-chart: attrs: title, items (format: label:value,label:value)
+`.trim();
+
+const MARKUP_SYNTAX = `
+Markup syntax:
+- [card:TEMPLATE_NAME attr1="value1" attr2="value2"] — insert a visual card
+- [broll:PROMPT_DESCRIPTION] — insert a B-roll visual segment
+  Optional: add span=N to link the broll to N preceding narration segments
+`.trim();
+
+const PRESET_GUIDANCE: Record<VideoPreset, string> = {
+  "knowledge-explainer": `
+Preset guidance (knowledge-explainer):
+- Target ~60% card visuals and ~40% broll transitions
+- Use cards when comparing, listing, or highlighting key points
+- Use broll for topic transitions and visual variety
+- broll prompts should be specific: describe the content, style, and atmosphere
+- Alternate between cards and broll to maintain viewer engagement
+`.trim(),
+
+  tutorial: `
+Preset guidance (tutorial):
+- Use numbered step cards (flow-chart, key-points) to structure the tutorial
+- Use broll between steps for transitions and breathing room
+- Mark screen recording placeholders when describing software operations
+  (e.g. [broll:screen recording — opening settings panel])
+- Each major step should have a corresponding card summarizing the action
+`.trim(),
+};
+
+const BASE_INSTRUCTIONS = `
+You are a video script markup assistant. Your job is to read the script below
+and insert [card:...] and [broll:...] tags at appropriate positions.
+
+Rules:
+1. Do NOT modify the script text itself — only insert markup tags on new lines
+2. Place markup tags AFTER the narration line they relate to
+3. Every card must use one of the available templates with proper attributes
+4. broll prompts must be vivid and specific enough for AI image generation
+5. Return the complete script with markup tags inserted
+`.trim();
+
+export function buildMarkupPrompt(
+  script: string,
+  preset: VideoPreset
+): string {
+  const sections = [
+    BASE_INSTRUCTIONS,
+    MARKUP_SYNTAX,
+    CARD_TEMPLATES,
+    PRESET_GUIDANCE[preset],
+    `---\nScript:\n${script}`,
+  ];
+
+  return sections.join("\n\n");
+}

package/src/modules/timeline/parser.ts

@@ -0,0 +1,275 @@
+import type {
+  Timeline,
+  TTSSegment,
+  VisualSegment,
+  VisualType,
+  CardTemplate,
+  VideoPreset,
+  AspectRatio,
+  SegmentStatus,
+} from "../../types/timeline.js";
+
+export interface ParseOptions {
+  contentId: string;
+  preset: VideoPreset;
+  aspectRatio: AspectRatio;
+}
+
+interface ParsedCard {
+  type: "card";
+  template: string;
+  attrs: Record<string, string>;
+}
+
+interface ParsedBroll {
+  type: "broll";
+  prompt: string;
+  span: number;
+}
+
+type ParsedMarkup = ParsedCard | ParsedBroll;
+
+const CARD_RE = /^\[card:([^\]]+)\]$/;
+const BROLL_RE = /^\[broll:([^\]]+)\]$/;
+const ATTR_RE = /(\w+)="([^"]*)"/g;
+const BARE_ATTR_RE = /(\w+)=(\S+)/g;
+
+function estimateDuration(text: string): number {
+  let chineseCount = 0;
+  let nonChineseCount = 0;
+
+  for (const char of text) {
+    if (/[\u4e00-\u9fff\u3400-\u4dbf]/.test(char)) {
+      chineseCount++;
+    } else if (/[a-zA-Z0-9]/.test(char)) {
+      nonChineseCount++;
+    }
+  }
+
+  const chineseSec = chineseCount / 4;
+  const nonChineseSec = nonChineseCount / 15;
+  return Math.max(chineseSec + nonChineseSec, 0.5);
+}
+
+function padId(prefix: string, n: number): string {
+  return `${prefix}-${String(n).padStart(3, "0")}`;
+}
+
+function parseCardContent(raw: string): ParsedCard {
+  const parts = raw.trim();
+  const firstSpace = parts.indexOf(" ");
+
+  let template: string;
+  let rest: string;
+
+  if (firstSpace === -1) {
+    template = parts;
+    rest = "";
+  } else {
+    template = parts.slice(0, firstSpace);
+    rest = parts.slice(firstSpace + 1);
+  }
+
+  const attrs: Record<string, string> = {};
+  let match: RegExpExecArray | null;
+
+  // quoted attrs first
+  ATTR_RE.lastIndex = 0;
+  while ((match = ATTR_RE.exec(rest)) !== null) {
+    attrs[match[1]] = match[2];
+  }
+
+  return { type: "card", template, attrs };
+}
+
+function parseBrollContent(raw: string): ParsedBroll {
+  const trimmed = raw.trim();
+  let span = 1;
+
+  // extract bare attrs like span=2
+  let prompt = trimmed;
+  const spanMatch = /\bspan=(\d+)\b/.exec(trimmed);
+  if (spanMatch) {
+    span = parseInt(spanMatch[1], 10);
+    prompt = trimmed.slice(0, spanMatch.index).trim();
+    const after = trimmed.slice(spanMatch.index + spanMatch[0].length).trim();
+    if (after) prompt = prompt ? `${prompt} ${after}` : after;
+  }
+
+  return { type: "broll", prompt, span };
+}
+
+function parseCardData(attrs: Record<string, string>): Record<string, unknown> {
+  const data: Record<string, unknown> = {};
+
+  if (attrs.title) {
+    data.title = attrs.title;
+  }
+
+  if (attrs.rows) {
+    data.rows = attrs.rows.split(",").map((row) => {
+      const parts = row.split(":");
+      return { name: parts[0], pros: parts[1] ?? "", cons: parts[2] ?? "" };
+    });
+  }
+
+  if (attrs.items) {
+    data.items = attrs.items.split(",");
+  }
+
+  if (attrs.steps) {
+    data.steps = attrs.steps.split(",");
+  }
+
+  return data;
+}
+
+export function parseMarkedScript(
+  script: string,
+  options: ParseOptions
+): Timeline {
+  const lines = script.split("\n");
+  const ttsSegments: TTSSegment[] = [];
+  const visualSegments: VisualSegment[] = [];
+
+  // Accumulate text lines and pair them with following markup
+  let textBuffer: string[] = [];
+  let ttsCounter = 0;
+  let visCounter = 0;
+  let currentStart = 0;
+
+  // Track which tts+layer combos are taken
+  const layerMap = new Map<string, Set<number>>();
+
+  function flushText(): string | null {
+    if (textBuffer.length === 0) return null;
+    const text = textBuffer.join("\n");
+    textBuffer = [];
+    return text;
+  }
+
+  function createTts(text: string): TTSSegment {
+    ttsCounter++;
+    const duration = estimateDuration(text);
+    const seg: TTSSegment = {
+      id: padId("tts", ttsCounter),
+      text,
+      estimatedDuration: parseFloat(duration.toFixed(2)),
+      start: parseFloat(currentStart.toFixed(2)),
+      asset: null,
+      status: "pending" as SegmentStatus,
+    };
+    currentStart += duration;
+    return seg;
+  }
+
+  function pickLayer(ttsIds: string[], preferredLayer: number): number {
+    for (const ttsId of ttsIds) {
+      const taken = layerMap.get(ttsId);
+      if (taken?.has(preferredLayer)) {
+        return preferredLayer + 1;
+      }
+    }
+    return preferredLayer;
+  }
+
+  function markLayer(ttsIds: string[], layer: number): void {
+    for (const ttsId of ttsIds) {
+      if (!layerMap.has(ttsId)) layerMap.set(ttsId, new Set());
+      layerMap.get(ttsId)!.add(layer);
+    }
+  }
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed === "") continue;
+
+    const cardMatch = CARD_RE.exec(trimmed);
+    const brollMatch = BROLL_RE.exec(trimmed);
+
+    if (cardMatch) {
+      // Flush preceding text as TTS
+      const text = flushText();
+      if (text) {
+        ttsSegments.push(createTts(text));
+      }
+
+      const parsed = parseCardContent(cardMatch[1]);
+      const lastTtsId =
+        ttsSegments.length > 0
+          ? ttsSegments[ttsSegments.length - 1].id
+          : null;
+      const linkedTts = lastTtsId ? [lastTtsId] : [];
+
+      const layer = pickLayer(linkedTts, 0);
+      markLayer(linkedTts, layer);
+
+      visCounter++;
+      visualSegments.push({
+        id: padId("vis", visCounter),
+        layer,
+        type: "card" as VisualType,
+        template: parsed.template as CardTemplate,
+        data: parseCardData(parsed.attrs),
+        linkedTts,
+        opacity: 0.85,
+        asset: null,
+        status: "pending" as SegmentStatus,
+      });
+    } else if (brollMatch) {
+      // Flush preceding text as TTS
+      const text = flushText();
+      if (text) {
+        ttsSegments.push(createTts(text));
+      }
+
+      const parsed = parseBrollContent(brollMatch[1]);
+      const span = Math.min(parsed.span, ttsSegments.length);
+      const linkedTts = ttsSegments
+        .slice(-span)
+        .map((s) => s.id);
+
+      const layer = pickLayer(linkedTts, 0);
+      markLayer(linkedTts, layer);
+
+      visCounter++;
+      visualSegments.push({
+        id: padId("vis", visCounter),
+        layer,
+        type: "broll" as VisualType,
+        prompt: parsed.prompt,
+        linkedTts,
+        asset: null,
+        status: "pending" as SegmentStatus,
+      });
+    } else {
+      textBuffer.push(trimmed);
+    }
+  }
+
+  // Flush remaining text
+  const remaining = flushText();
+  if (remaining) {
+    ttsSegments.push(createTts(remaining));
+  }
+
+  return {
+    version: "2.0",
+    contentId: options.contentId,
+    preset: options.preset,
+    aspectRatio: options.aspectRatio,
+    subtitle: {
+      template: "modern-outline",
+      position: "bottom",
+    },
+    tracks: {
+      tts: ttsSegments,
+      visual: visualSegments,
+      subtitle: {
+        asset: null,
+        status: "pending",
+      },
+    },
+  };
+}