@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/core/src/agents/state-validator.ts

@@ -0,0 +1,322 @@
+import { BaseAgent } from "./base.js";
+
+export interface ValidationWarning {
+  readonly category: string;
+  readonly description: string;
+}
+
+export interface ValidationResult {
+  readonly warnings: ReadonlyArray<ValidationWarning>;
+  readonly passed: boolean;
+}
+
+export interface StateValidationAuthorityContext {
+  readonly storyFrame?: string;
+  readonly bookRules?: string;
+  readonly chapterSummaries?: string;
+}
+
+/**
+ * Validates Settler output by comparing old and new truth files via LLM.
+ * Catches contradictions, missing state changes, and temporal inconsistencies.
+ *
+ * Uses a minimal verdict protocol instead of requiring structured JSON:
+ *   Line 1: PASS or FAIL
+ *   Remaining lines: free-form warnings (one per line, optional category prefix)
+ */
+export class StateValidatorAgent extends BaseAgent {
+  get name(): string {
+    return "state-validator";
+  }
+
+  async validate(
+    chapterContent: string,
+    chapterNumber: number,
+    oldState: string,
+    newState: string,
+    oldHooks: string,
+    newHooks: string,
+    language: "zh" | "en" = "zh",
+    authorityContext?: StateValidationAuthorityContext,
+  ): Promise<ValidationResult> {
+    const stateDiff = this.computeDiff(oldState, newState, "State Card");
+    const hooksDiff = this.computeDiff(oldHooks, newHooks, "Hooks Pool");
+
+    // Skip validation if nothing changed
+    if (!stateDiff && !hooksDiff) {
+      return { warnings: [], passed: true };
+    }
+
+    const langInstruction = language === "en"
+      ? "Respond in English."
+      : "用中文回答。";
+
+    const systemPrompt = `You are a continuity validator for a novel writing system. ${langInstruction}
+
+Given the chapter text and the CHANGES made to truth files (state card + hooks pool), check for contradictions:
+
+1. State change without narrative support — truth file says something changed but the chapter text doesn't describe it
+2. Missing state change — chapter text describes something happening but the truth file didn't capture it
+3. Temporal impossibility — character moves locations without transition, injury heals without time passing
+4. Hook anomaly — a hook disappeared without being marked resolved, or a new hook has no basis in the chapter
+5. Retroactive edit — truth file change implies something happened in a PREVIOUS chapter, not the current one
+6. Cross-truth key-setting conflict — numbered rules, named laws, ranks, identities, locations, or relationship labels in the new truth files contradict the chapter text or the authority context
+
+Output format (simple, NOT JSON):
+- First line: exactly PASS or FAIL (nothing else on this line)
+- Following lines: one warning per line, optionally prefixed with [category]
+- If no issues at all, just output: PASS
+
+Example:
+PASS
+[unsupported_change] State card says character moved to the forest, but text only shows intent
+[minor] Hook H03 advanced but text mention is brief
+
+Or if there are hard contradictions:
+FAIL
+[contradiction] State says character is dead but chapter text shows them speaking
+[unsupported_change] New location not mentioned anywhere in chapter text
+
+IMPORTANT: Output FAIL ONLY for hard contradictions — facts that directly conflict with the chapter text. Do NOT fail for:
+- Slightly ahead-of-text inferences
+- Missing details that the state card didn't capture
+- Reasonable extrapolations from text
+- Hook management differences that don't contradict text
+These should be warnings with PASS, not FAIL.`;
+
+    const authorityBlock = this.buildAuthorityContextBlock(authorityContext);
+
+    const userPrompt = `Chapter ${chapterNumber} validation:
+
+${authorityBlock}
+
+## State Card Changes
+${stateDiff || "(no changes)"}
+
+## Hooks Pool Changes
+${hooksDiff || "(no changes)"}
+
+## Chapter Text (for reference)
+${chapterContent.slice(0, 6000)}`;
+
+    try {
+      const response = await this.chat(
+        [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt },
+        ],
+        { temperature: 0.1 },
+      );
+
+      return this.parseResult(response.content);
+    } catch (error) {
+      this.log?.warn(`State validation failed: ${error}`);
+      throw error;
+    }
+  }
+
+  private computeDiff(oldText: string, newText: string, label: string): string | null {
+    if (oldText === newText) return null;
+
+    const oldLines = oldText.split("\n").filter((l) => l.trim());
+    const newLines = newText.split("\n").filter((l) => l.trim());
+
+    const added = newLines.filter((l) => !oldLines.includes(l));
+    const removed = oldLines.filter((l) => !newLines.includes(l));
+
+    if (added.length === 0 && removed.length === 0) return null;
+
+    const parts = [`### ${label}`];
+    if (removed.length > 0) parts.push("Removed:\n" + removed.map((l) => `- ${l}`).join("\n"));
+    if (added.length > 0) parts.push("Added:\n" + added.map((l) => `+ ${l}`).join("\n"));
+    return parts.join("\n");
+  }
+
+  private buildAuthorityContextBlock(authorityContext?: StateValidationAuthorityContext): string {
+    if (!authorityContext) return "## Authority / Cross-Truth Context\n(no authority context provided)";
+
+    const storyFrame = this.truncateHead(authorityContext.storyFrame ?? "", 3500);
+    const bookRules = this.truncateHead(authorityContext.bookRules ?? "", 2000);
+    const chapterSummaries = this.truncateTail(authorityContext.chapterSummaries ?? "", 3500);
+
+    return [
+      "## Authority / Cross-Truth Context",
+      "Authority priority: current chapter text > runtime truth files/current summaries > story_frame/book_rules > legacy story_bible intro or marketing-style prose. If the current chapter establishes a numbered/name mapping, new truth files must follow that mapping instead of preserving an older intro-only version.",
+      "",
+      "### story_frame / legacy story_bible excerpt",
+      storyFrame || "(empty)",
+      "",
+      "### book_rules excerpt",
+      bookRules || "(empty)",
+      "",
+      "### recent chapter_summaries excerpt",
+      chapterSummaries || "(empty)",
+    ].join("\n");
+  }
+
+  private truncateHead(text: string, maxChars: number): string {
+    const trimmed = text.trim();
+    if (trimmed.length <= maxChars) return trimmed;
+    return `${trimmed.slice(0, maxChars).trimEnd()}\n\n[...truncated...]`;
+  }
+
+  private truncateTail(text: string, maxChars: number): string {
+    const trimmed = text.trim();
+    if (trimmed.length <= maxChars) return trimmed;
+    return `[...truncated...]\n\n${trimmed.slice(-maxChars).trimStart()}`;
+  }
+
+  private parseResult(content: string): ValidationResult {
+    const trimmed = content.trim();
+    if (!trimmed) {
+      throw new Error("LLM returned empty response");
+    }
+
+    const jsonResult = this.tryParseJsonResult(trimmed);
+    if (jsonResult) {
+      return jsonResult;
+    }
+
+    const lines = trimmed.split("\n").map((line) => line.trim()).filter(Boolean);
+    if (lines.length === 0) {
+      throw new Error("LLM returned empty response");
+    }
+
+    const verdictLine = lines[0]!;
+    if (!/^(PASS|FAIL)$/i.test(verdictLine)) {
+      throw new Error("State validator returned invalid response");
+    }
+    const passed = /^PASS$/i.test(verdictLine);
+
+    const warnings: ValidationWarning[] = [];
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i]!;
+      if (/^(PASS|FAIL)$/i.test(line)) continue;
+
+      const categoryMatch = line.match(/^\[([^\]]+)\]\s*(.+)$/);
+      if (categoryMatch) {
+        warnings.push({
+          category: categoryMatch[1]!.trim(),
+          description: categoryMatch[2]!.trim(),
+        });
+      } else if (line.startsWith("- ") || line.startsWith("* ")) {
+        warnings.push({
+          category: "general",
+          description: line.slice(2).trim(),
+        });
+      } else if (line.length > 5) {
+        warnings.push({
+          category: "general",
+          description: line,
+        });
+      }
+    }
+
+    return { warnings, passed };
+  }
+
+  private tryParseJsonResult(text: string): ValidationResult | null {
+    const direct = this.tryParseExactJsonResult(text);
+    if (direct) {
+      return direct;
+    }
+
+    const candidate = extractBalancedJsonObject(text);
+    if (!candidate) {
+      return null;
+    }
+    return this.tryParseExactJsonResult(candidate);
+  }
+
+  private tryParseExactJsonResult(text: string): ValidationResult | null {
+    try {
+      const parsed = JSON.parse(text) as {
+        warnings?: Array<{ category?: string; description?: string }>;
+        passed?: boolean;
+      };
+      if (typeof parsed.passed !== "boolean") return null;
+      return {
+        warnings: (parsed.warnings ?? []).map((w) => ({
+          category: w.category ?? "unknown",
+          description: w.description ?? "",
+        })),
+        passed: parsed.passed,
+      };
+    } catch {
+      return null;
+    }
+  }
+}
+
+function extractBalancedJsonObject(text: string): string | null {
+  const start = text.indexOf("{");
+  if (start < 0) {
+    return null;
+  }
+
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  let endIndex = -1;
+
+  for (let index = start; index < text.length; index += 1) {
+    const char = text[index]!;
+
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (char === "\"") {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === "\"") {
+      inString = true;
+      continue;
+    }
+
+    if (char === "{") {
+      depth += 1;
+      continue;
+    }
+
+    if (char === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        endIndex = index;
+        break;
+      }
+      if (depth < 0) {
+        return null;
+      }
+    }
+  }
+
+  if (endIndex < 0) return null;
+
+  // Only accept the candidate if what follows the closing brace is
+  // nothing, whitespace, or a structural JSON terminator.
+  // This rejects trailing content like "{...} more text here"
+  const followingChar = text[endIndex + 1];
+  if (
+    followingChar !== undefined &&
+    followingChar !== "\n" &&
+    followingChar !== "\r" &&
+    followingChar !== "\t" &&
+    followingChar !== " " &&
+    followingChar !== "," &&
+    followingChar !== "]" &&
+    followingChar !== "}"
+  ) {
+    return null;
+  }
+
+  return text.slice(start, endIndex + 1);
+}

package/inkos/packages/core/src/agents/style-analyzer.ts

@@ -0,0 +1,93 @@
+/**
+ * Style fingerprint analysis — pure text analysis (no LLM).
+ * Extracts statistical features from reference text to build a StyleProfile.
+ */
+
+import type { StyleProfile } from "../models/style-profile.js";
+
+// Common rhetorical patterns in Chinese fiction
+const RHETORICAL_PATTERNS: ReadonlyArray<{ readonly name: string; readonly regex: RegExp }> = [
+  { name: "比喻(像/如/仿佛)", regex: /[像如仿佛似](?:是|同|一般|一样)/g },
+  { name: "排比", regex: /[，。；]([^，。；]{2,6})[，。；]\1/g },
+  { name: "反问", regex: /难道|怎么可能|岂不是|何尝不/g },
+  { name: "夸张", regex: /天崩地裂|惊天动地|翻天覆地|震耳欲聋/g },
+  { name: "拟人", regex: /[风雨雪月花树草石](?:在|像|仿佛).*?(?:笑|哭|叹|呻|吟|怒|舞)/g },
+  { name: "短句节奏", regex: /[。！？][^。！？]{1,8}[。！？]/g },
+];
+
+/**
+ * Analyze a reference text and extract its style profile.
+ * The returned profile can be serialized to style_profile.json.
+ */
+export function analyzeStyle(text: string, sourceName?: string): StyleProfile {
+  const sentences = text
+    .split(/[。！？\n]/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+
+  const paragraphs = text
+    .split(/\n\s*\n/)
+    .map((p) => p.trim())
+    .filter((p) => p.length > 0);
+
+  // Sentence length stats
+  const sentenceLengths = sentences.map((s) => s.length);
+  const avgSentenceLength = sentenceLengths.length > 0
+    ? sentenceLengths.reduce((a, b) => a + b, 0) / sentenceLengths.length
+    : 0;
+  const sentenceLengthStdDev = sentenceLengths.length > 1
+    ? Math.sqrt(
+        sentenceLengths.reduce((sum, l) => sum + (l - avgSentenceLength) ** 2, 0) /
+          sentenceLengths.length,
+      )
+    : 0;
+
+  // Paragraph length stats
+  const paragraphLengths = paragraphs.map((p) => p.length);
+  const avgParagraphLength = paragraphLengths.length > 0
+    ? paragraphLengths.reduce((a, b) => a + b, 0) / paragraphLengths.length
+    : 0;
+  const minParagraph = paragraphLengths.length > 0 ? Math.min(...paragraphLengths) : 0;
+  const maxParagraph = paragraphLengths.length > 0 ? Math.max(...paragraphLengths) : 0;
+
+  // Vocabulary diversity (TTR — Type-Token Ratio)
+  // Use character-level for Chinese (each char is roughly a "token")
+  const chars = text.replace(/[\s\n\r，。！？、：；""''（）【】《》\d]/g, "");
+  const uniqueChars = new Set(chars);
+  const vocabularyDiversity = chars.length > 0 ? uniqueChars.size / chars.length : 0;
+
+  // Top sentence opening patterns (first 2 chars)
+  const openingCounts: Record<string, number> = {};
+  for (const s of sentences) {
+    if (s.length >= 2) {
+      const opening = s.slice(0, 2);
+      openingCounts[opening] = (openingCounts[opening] ?? 0) + 1;
+    }
+  }
+  const topPatterns = Object.entries(openingCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .filter(([, count]) => count >= 3)
+    .map(([pattern, count]) => `${pattern}...(${count}次)`);
+
+  // Rhetorical features
+  const rhetoricalFeatures: string[] = [];
+  for (const { name, regex } of RHETORICAL_PATTERNS) {
+    const matches = text.match(regex);
+    if (matches && matches.length >= 2) {
+      rhetoricalFeatures.push(`${name}(${matches.length}处)`);
+    }
+  }
+
+  return {
+    avgSentenceLength: Math.round(avgSentenceLength * 10) / 10,
+    sentenceLengthStdDev: Math.round(sentenceLengthStdDev * 10) / 10,
+    avgParagraphLength: Math.round(avgParagraphLength),
+    paragraphLengthRange: { min: minParagraph, max: maxParagraph },
+    vocabularyDiversity: Math.round(vocabularyDiversity * 1000) / 1000,
+    topPatterns,
+    rhetoricalFeatures,
+    sourceName,
+    analyzedAt: new Date().toISOString(),
+  };
+}

package/inkos/packages/core/src/agents/writer-parser.ts

@@ -0,0 +1,178 @@
+import type { GenreProfile } from "../models/genre-profile.js";
+import type { LengthCountingMode } from "../models/length-governance.js";
+import type { WriteChapterOutput } from "./writer.js";
+import { countChapterLength } from "../utils/length-metrics.js";
+
+export interface CreativeOutput {
+  readonly title: string;
+  readonly content: string;
+  readonly wordCount: number;
+  readonly preWriteCheck: string;
+}
+
+export function parseCreativeOutput(
+  chapterNumber: number,
+  content: string,
+  countingMode: LengthCountingMode = "zh_chars",
+): CreativeOutput {
+  const extract = (tag: string): string => {
+    const regex = new RegExp(
+      `=== ${tag} ===\\s*([\\s\\S]*?)(?==== [A-Z_]+ ===|$)`,
+    );
+    const match = content.match(regex);
+    return match?.[1]?.trim() ?? "";
+  };
+
+  let chapterContent = extract("CHAPTER_CONTENT");
+
+  // Fallback: if === TAG === parsing fails (common with local/small models),
+  // try to extract usable content from the raw output
+  if (!chapterContent) {
+    chapterContent = fallbackExtractContent(content, countingMode);
+  }
+
+  let title = extract("CHAPTER_TITLE");
+  if (!title) {
+    title = fallbackExtractTitle(content, chapterNumber, countingMode);
+  }
+
+  return {
+    title,
+    content: chapterContent,
+    wordCount: countChapterLength(chapterContent, countingMode),
+    preWriteCheck: extract("PRE_WRITE_CHECK"),
+  };
+}
+
+/**
+ * Fallback content extraction when === CHAPTER_CONTENT === tag is missing.
+ * Tries common patterns from local/small models, then falls back to
+ * stripping metadata and returning the longest prose block.
+ */
+function fallbackExtractContent(raw: string, countingMode: LengthCountingMode): string {
+  // Try markdown heading: # 第N章 ... followed by content
+  const headingMatch = raw.match(/^#\s*第\d+章[^\n]*\n+([\s\S]+)/m);
+  if (headingMatch) {
+    return headingMatch[1]!.trim();
+  }
+
+  if (countingMode === "en_words") {
+    const englishHeadingMatch = raw.match(/^#\s*Chapter\s+\d+(?::|\s+)([^\n]*)\n+([\s\S]+)/im);
+    if (englishHeadingMatch) {
+      return englishHeadingMatch[2]!.trim();
+    }
+  }
+
+  // Try "正文" or "内容" labeled section
+  const labelMatch = raw.match(/(?:正文|内容|章节内容)[：:]\s*\n+([\s\S]+)/);
+  if (labelMatch) {
+    return labelMatch[1]!.trim();
+  }
+
+  if (countingMode === "en_words") {
+    const englishLabelMatch = raw.match(/(?:content|chapter content)[：:]\s*\n+([\s\S]+)/i);
+    if (englishLabelMatch) {
+      return englishLabelMatch[1]!.trim();
+    }
+  }
+
+  // Last resort: strip lines that look like metadata/tags, keep the rest
+  const lines = raw.split("\n");
+  const proseLines = lines.filter((line) => {
+    const trimmed = line.trim();
+    // Skip tag-like lines, empty lines at boundaries, and short key-value lines
+    if (/^===\s*[A-Z_]+\s*===/.test(trimmed)) return false;
+    if (/^(PRE_WRITE_CHECK|CHAPTER_TITLE|章节标题|写作自检)[：:]/.test(trimmed)) return false;
+    return true;
+  });
+  const result = proseLines.join("\n").trim();
+  // Only use fallback if we got meaningful content (>100 chars)
+  return result.length > 100 ? result : "";
+}
+
+/**
+ * Fallback title extraction when === CHAPTER_TITLE === tag is missing.
+ */
+function fallbackExtractTitle(
+  raw: string,
+  chapterNumber: number,
+  countingMode: LengthCountingMode,
+): string {
+  // Try: # 第N章 Title
+  const headingMatch = raw.match(/^#\s*第\d+章\s*(.+)/m);
+  if (headingMatch) {
+    return headingMatch[1]!.trim();
+  }
+  if (countingMode === "en_words") {
+    const englishHeadingMatch = raw.match(/^#\s*Chapter\s+\d+(?::|\s+)\s*(.+)/im);
+    if (englishHeadingMatch) {
+      return englishHeadingMatch[1]!.trim();
+    }
+  }
+  // Try: 章节标题：Title or CHAPTER_TITLE: Title (without === delimiters)
+  const labelMatch = raw.match(/(?:章节标题|CHAPTER_TITLE)[：:]\s*(.+)/);
+  if (labelMatch) {
+    return labelMatch[1]!.trim();
+  }
+  return defaultChapterTitle(chapterNumber, countingMode);
+}
+
+export type ParsedWriterOutput = Omit<WriteChapterOutput, "postWriteErrors" | "postWriteWarnings">;
+
+/**
+ * Parse LLM output that uses === TAG === delimiters into structured chapter data.
+ * Shared by WriterAgent (writing new chapters) and ChapterAnalyzerAgent (analyzing existing chapters).
+ */
+export function parseWriterOutput(
+  chapterNumber: number,
+  content: string,
+  genreProfile: GenreProfile,
+  countingMode: LengthCountingMode = "zh_chars",
+): ParsedWriterOutput {
+  const extract = (tag: string): string => {
+    const regex = new RegExp(
+      `=== ${tag} ===\\s*([\\s\\S]*?)(?==== [A-Z_]+ ===|$)`,
+    );
+    const match = content.match(regex);
+    return match?.[1]?.trim() ?? "";
+  };
+
+  const chapterContent = extract("CHAPTER_CONTENT");
+
+  return {
+    chapterNumber,
+    title: extract("CHAPTER_TITLE") || defaultChapterTitle(chapterNumber, countingMode),
+    content: chapterContent,
+    wordCount: countChapterLength(chapterContent, countingMode),
+    preWriteCheck: extract("PRE_WRITE_CHECK"),
+    postSettlement: extract("POST_SETTLEMENT"),
+    updatedState: extract("UPDATED_STATE") || defaultStatePlaceholder(countingMode),
+    updatedLedger: genreProfile.numericalSystem
+      ? (extract("UPDATED_LEDGER") || defaultLedgerPlaceholder(countingMode))
+      : "",
+    updatedHooks: extract("UPDATED_HOOKS") || defaultHooksPlaceholder(countingMode),
+    chapterSummary: extract("CHAPTER_SUMMARY"),
+    updatedSubplots: extract("UPDATED_SUBPLOTS"),
+    updatedEmotionalArcs: extract("UPDATED_EMOTIONAL_ARCS"),
+    updatedCharacterMatrix: extract("UPDATED_CHARACTER_MATRIX"),
+  };
+}
+
+function defaultChapterTitle(
+  chapterNumber: number,
+  countingMode: LengthCountingMode,
+): string {
+  return countingMode === "en_words" ? `Chapter ${chapterNumber}` : `第${chapterNumber}章`;
+}
+
+function defaultStatePlaceholder(countingMode: LengthCountingMode): string {
+  return countingMode === "en_words" ? "(state card not updated)" : "(状态卡未更新)";
+}
+
+function defaultLedgerPlaceholder(countingMode: LengthCountingMode): string {
+  return countingMode === "en_words" ? "(ledger not updated)" : "(账本未更新)";
+}
+
+function defaultHooksPlaceholder(countingMode: LengthCountingMode): string {
+  return countingMode === "en_words" ? "(hooks pool not updated)" : "(伏笔池未更新)";
+}