@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/cli/src/commands/agent.ts

@@ -0,0 +1,65 @@
+import { Command } from "commander";
+import { runAgentLoop } from "@actalk/inkos-core";
+import { loadConfig, createClient, findProjectRoot, resolveContext, log, logError } from "../utils.js";
+
+export const agentCommand = new Command("agent")
+  .description("Natural language agent mode (LLM orchestrates via tool-use)")
+  .argument("<instruction>", "Natural language instruction")
+  .option("--context <text>", "Additional context (natural language)")
+  .option("--context-file <path>", "Read additional context from file")
+  .option("--max-turns <n>", "Maximum agent turns", "20")
+  .option("--json", "Output JSON (suppress progress messages)")
+  .option("--quiet", "Suppress tool call logs")
+  .action(async (instruction: string, opts) => {
+    try {
+      const config = await loadConfig();
+      const client = createClient(config);
+      const root = findProjectRoot();
+      const context = await resolveContext(opts);
+
+      const fullInstruction = context
+        ? `${instruction}\n\n补充信息：${context}`
+        : instruction;
+
+      const maxTurns = parseInt(opts.maxTurns, 10);
+
+      const result = await runAgentLoop(
+        {
+          client,
+          model: config.llm.model,
+          projectRoot: root,
+        },
+        fullInstruction,
+        {
+          maxTurns,
+          onToolCall: opts.quiet || opts.json
+            ? undefined
+            : (name, args) => {
+                log(`  [tool] ${name}(${JSON.stringify(args)})`);
+              },
+          onToolResult: opts.quiet || opts.json
+            ? undefined
+            : (name, result) => {
+                const preview = result.length > 200 ? `${result.slice(0, 200)}...` : result;
+                log(`  [result] ${name} → ${preview}`);
+              },
+          onMessage: opts.json
+            ? undefined
+            : (content) => {
+                log(`\n${content}`);
+              },
+        },
+      );
+
+      if (opts.json) {
+        log(JSON.stringify({ result }));
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Agent failed: ${e}`);
+      }
+      process.exit(1);
+    }
+  });

package/inkos/packages/cli/src/commands/analytics.ts

@@ -0,0 +1,77 @@
+import { Command } from "commander";
+import { StateManager, computeAnalytics } from "@actalk/inkos-core";
+import { loadConfig, findProjectRoot, resolveBookId, log, logError } from "../utils.js";
+
+export const analyticsCommand = new Command("analytics")
+  .alias("stats")
+  .description("Show analytics and token stats for a book")
+  .argument("[book-id]", "Book ID (auto-detected if only one book)")
+  .option("--json", "Output JSON")
+  .action(async (bookIdArg: string | undefined, opts) => {
+    try {
+      await loadConfig();
+      const root = findProjectRoot();
+      const bookId = await resolveBookId(bookIdArg, root);
+      const state = new StateManager(root);
+      const chapters = await state.loadChapterIndex(bookId);
+
+      const analytics = computeAnalytics(bookId, chapters);
+
+      if (opts.json) {
+        log(JSON.stringify(analytics, null, 2));
+      } else {
+        log(`Analytics for "${bookId}":`);
+        log("");
+        log(`  Total chapters: ${analytics.totalChapters}`);
+        log(`  Total words: ${analytics.totalWords.toLocaleString()}`);
+        log(`  Avg words/chapter: ${analytics.avgWordsPerChapter.toLocaleString()}`);
+        log(`  Audit pass rate: ${analytics.auditPassRate}%`);
+        log("");
+
+        if (Object.keys(analytics.statusDistribution).length > 0) {
+          log("  Status distribution:");
+          for (const [status, count] of Object.entries(analytics.statusDistribution)) {
+            log(`    ${status}: ${count}`);
+          }
+          log("");
+        }
+
+        if (analytics.tokenStats) {
+          log("  Token usage:");
+          log(`    Total tokens: ${analytics.tokenStats.totalTokens.toLocaleString()}`);
+          log(`    Prompt tokens: ${analytics.tokenStats.totalPromptTokens.toLocaleString()}`);
+          log(`    Completion tokens: ${analytics.tokenStats.totalCompletionTokens.toLocaleString()}`);
+          log(`    Avg tokens/chapter: ${analytics.tokenStats.avgTokensPerChapter.toLocaleString()}`);
+          if (analytics.tokenStats.recentTrend.length > 0) {
+            log("    Recent trend:");
+            for (const { chapter, totalTokens } of analytics.tokenStats.recentTrend) {
+              log(`      Ch.${chapter}: ${totalTokens.toLocaleString()} tokens`);
+            }
+          }
+          log("");
+        }
+
+        if (analytics.topIssueCategories.length > 0) {
+          log("  Most common issue categories:");
+          for (const { category, count } of analytics.topIssueCategories) {
+            log(`    ${category}: ${count}`);
+          }
+          log("");
+        }
+
+        if (analytics.chaptersWithMostIssues.length > 0) {
+          log("  Chapters with most issues:");
+          for (const { chapter, issueCount } of analytics.chaptersWithMostIssues) {
+            log(`    Ch.${chapter}: ${issueCount} issues`);
+          }
+        }
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Analytics failed: ${e}`);
+      }
+      process.exit(1);
+    }
+  });

package/inkos/packages/cli/src/commands/audit.ts

@@ -0,0 +1,52 @@
+import { Command } from "commander";
+import { PipelineRunner } from "@actalk/inkos-core";
+import { loadConfig, buildPipelineConfig, findProjectRoot, resolveBookId, log, logError } from "../utils.js";
+
+export const auditCommand = new Command("audit")
+  .description("Audit a chapter for continuity issues")
+  .argument("[book-id]", "Book ID (auto-detected if only one book)")
+  .argument("[chapter]", "Chapter number (defaults to latest)")
+  .option("--json", "Output JSON")
+  .action(async (bookIdArg: string | undefined, chapterStr: string | undefined, opts) => {
+    try {
+      const config = await loadConfig();
+      const root = findProjectRoot();
+
+      // If first arg looks like a number, treat it as chapter (auto-detect book)
+      let bookId: string;
+      let chapterNumber: number | undefined;
+      if (bookIdArg && /^\d+$/.test(bookIdArg)) {
+        bookId = await resolveBookId(undefined, root);
+        chapterNumber = parseInt(bookIdArg, 10);
+      } else {
+        bookId = await resolveBookId(bookIdArg, root);
+        chapterNumber = chapterStr ? parseInt(chapterStr, 10) : undefined;
+      }
+
+      const pipeline = new PipelineRunner(buildPipelineConfig(config, root));
+
+      if (!opts.json) log(`Auditing "${bookId}"${chapterNumber ? ` chapter ${chapterNumber}` : " (latest)"}...`);
+
+      const result = await pipeline.auditDraft(bookId, chapterNumber);
+
+      if (opts.json) {
+        log(JSON.stringify(result, null, 2));
+      } else {
+        log(`  Chapter ${result.chapterNumber}: ${result.passed ? "PASSED" : "FAILED"}`);
+        log(`  Summary: ${result.summary}`);
+        if (result.issues.length > 0) {
+          log("  Issues:");
+          for (const issue of result.issues) {
+            log(`    [${issue.severity}] ${issue.category}: ${issue.description}`);
+          }
+        }
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Audit failed: ${e}`);
+      }
+      process.exit(1);
+    }
+  });

package/inkos/packages/cli/src/commands/book.ts

@@ -0,0 +1,260 @@
+import { Command } from "commander";
+import { access, readFile, rm } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { join, resolve } from "node:path";
+import { deriveBookIdFromTitle, normalizePlatformOrOther, PipelineRunner, StateManager, type BookConfig } from "@actalk/inkos-core";
+import {
+  formatBookCreateCreated,
+  formatBookCreateCreating,
+  formatBookCreateFoundationReady,
+  formatBookCreateLocation,
+  formatBookCreateNextStep,
+  resolveCliLanguage,
+} from "../localization.js";
+import { loadConfig, buildPipelineConfig, findProjectRoot, resolveBookId, log, logError } from "../utils.js";
+
+export const bookCommand = new Command("book")
+  .description("Manage books");
+
+bookCommand
+  .command("create")
+  .description("Create a new book with AI-generated foundation")
+  .requiredOption("--title <title>", "Book title")
+  .option("--genre <genre>", "Genre", "xuanhuan")
+  .option("--platform <platform>", "Target platform", "tomato")
+  .option("--target-chapters <n>", "Target chapter count", "200")
+  .option("--chapter-words <n>", "Words per chapter", "3000")
+  .option("--brief <path>", "Path to creative brief file (.md/.txt) — Architect builds from your ideas instead of generating from scratch")
+  .option("--lang <language>", "Writing language: zh (Chinese) or en (English). Defaults from genre.")
+  .option("--json", "Output JSON")
+  .action(async (opts) => {
+    try {
+      const root = findProjectRoot();
+
+      const bookId = deriveBookIdFromTitle(opts.title) || `book-${Date.now().toString(36)}`;
+
+      const bookDir = join(root, "books", bookId);
+      try {
+        await access(bookDir);
+        const state = new StateManager(root);
+        if (await state.isCompleteBookDirectory(bookDir)) {
+          throw new Error(`Book "${bookId}" already exists at books/${bookId}/. Use a different title or delete the existing book first.`);
+        }
+        await rm(bookDir, { recursive: true, force: true });
+      } catch (e) {
+        if (e instanceof Error && e.message.includes("already exists")) throw e;
+        // Directory doesn't exist, good
+      }
+
+      const config = await loadConfig();
+      const now = new Date().toISOString();
+      const book: BookConfig = {
+        id: bookId,
+        title: opts.title,
+        platform: normalizePlatformOrOther(opts.platform),
+        genre: opts.genre,
+        status: "outlining",
+        targetChapters: parseInt(opts.targetChapters, 10),
+        chapterWordCount: parseInt(opts.chapterWords, 10),
+        language: opts.lang ?? config.language,
+        createdAt: now,
+        updatedAt: now,
+      };
+      const language = resolveCliLanguage(book.language);
+
+      if (!opts.json) log(formatBookCreateCreating(language, book.title, book.genre, book.platform));
+
+      const brief = opts.brief
+        ? await readFile(resolve(opts.brief), "utf-8")
+        : undefined;
+
+      const pipeline = new PipelineRunner(buildPipelineConfig(config, root, { externalContext: brief }));
+
+      await pipeline.initBook(book);
+
+      if (opts.json) {
+        log(JSON.stringify({
+          bookId,
+          title: book.title,
+          genre: book.genre,
+          platform: book.platform,
+          location: `books/${bookId}/`,
+          nextStep: `inkos write next ${bookId}`,
+        }, null, 2));
+      } else {
+        log(formatBookCreateCreated(language, bookId));
+        log(formatBookCreateLocation(language, bookId));
+        log(formatBookCreateFoundationReady(language));
+        log("");
+        log(formatBookCreateNextStep(language, bookId));
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Failed to create book: ${e}`);
+      }
+      process.exit(1);
+    }
+  });
+
+bookCommand
+  .command("update")
+  .description("Update book settings")
+  .argument("[book-id]", "Book ID (auto-detected if only one book)")
+  .option("--chapter-words <n>", "Words per chapter")
+  .option("--target-chapters <n>", "Target chapter count")
+  .option("--status <status>", "Book status (outlining/active/paused/completed)")
+  .option("--lang <language>", "Writing language: zh or en")
+  .option("--json", "Output JSON")
+  .action(async (bookIdArg: string | undefined, opts) => {
+    try {
+      const root = findProjectRoot();
+      const bookId = await resolveBookId(bookIdArg, root);
+      const state = new StateManager(root);
+      const book = await state.loadBookConfig(bookId);
+
+      const updates: Record<string, unknown> = {};
+      if (opts.chapterWords) updates.chapterWordCount = parseInt(opts.chapterWords, 10);
+      if (opts.targetChapters) updates.targetChapters = parseInt(opts.targetChapters, 10);
+      if (opts.status) updates.status = opts.status;
+      if (opts.lang) updates.language = opts.lang;
+
+      if (Object.keys(updates).length === 0) {
+        if (opts.json) {
+          log(JSON.stringify(book, null, 2));
+        } else {
+          log(`Book: ${book.title} (${bookId})`);
+          log(`  Words/chapter: ${book.chapterWordCount}`);
+          log(`  Target chapters: ${book.targetChapters}`);
+          log(`  Status: ${book.status}`);
+          log(`  Genre: ${book.genre} | Platform: ${book.platform}`);
+        }
+        return;
+      }
+
+      const updated: BookConfig = {
+        ...book,
+        ...updates,
+        updatedAt: new Date().toISOString(),
+      };
+      await state.saveBookConfig(bookId, updated);
+
+      if (opts.json) {
+        log(JSON.stringify(updated, null, 2));
+      } else {
+        for (const [key, value] of Object.entries(updates)) {
+          log(`  ${key}: ${(book as Record<string, unknown>)[key]} → ${value}`);
+        }
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Failed to update book: ${e}`);
+      }
+      process.exit(1);
+    }
+  });
+
+bookCommand
+  .command("list")
+  .description("List all books")
+  .option("--json", "Output JSON")
+  .action(async (opts) => {
+    try {
+      const root = findProjectRoot();
+      const state = new StateManager(root);
+      const bookIds = await state.listBooks();
+
+      if (bookIds.length === 0) {
+        if (opts.json) {
+          log(JSON.stringify({ books: [] }));
+        } else {
+          log("No books found. Create one with: inkos book create --title '...'");
+        }
+        return;
+      }
+
+      const books = [];
+      for (const id of bookIds) {
+        const book = await state.loadBookConfig(id);
+        const nextChapter = await state.getNextChapterNumber(id);
+        const info = {
+          id,
+          title: book.title,
+          genre: book.genre,
+          platform: book.platform,
+          status: book.status,
+          chapters: nextChapter - 1,
+        };
+        books.push(info);
+        if (!opts.json) {
+          log(`  ${id} | ${book.title} | ${book.genre}/${book.platform} | ${book.status} | chapters: ${nextChapter - 1}`);
+        }
+      }
+
+      if (opts.json) {
+        log(JSON.stringify({ books }, null, 2));
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Failed to list books: ${e}`);
+      }
+      process.exit(1);
+    }
+  });
+
+bookCommand
+  .command("delete")
+  .description("Delete a book and all its chapters, truth files, and snapshots")
+  .argument("<book-id>", "Book ID to delete")
+  .option("--force", "Skip confirmation prompt")
+  .option("--json", "Output JSON")
+  .action(async (bookId: string, opts) => {
+    try {
+      const root = findProjectRoot();
+      const state = new StateManager(root);
+
+      const allBooks = await state.listBooks();
+      if (!allBooks.includes(bookId)) {
+        throw new Error(`Book "${bookId}" not found. Available: ${allBooks.join(", ") || "(none)"}`);
+      }
+
+      const book = await state.loadBookConfig(bookId);
+      const index = await state.loadChapterIndex(bookId);
+
+      if (!opts.force) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise<string>((resolve) => {
+          rl.question(
+            `Delete "${book.title}" (${bookId})? This will remove ${index.length} chapter(s) and all data. (y/N) `,
+            resolve,
+          );
+        });
+        rl.close();
+        if (answer.toLowerCase() !== "y") {
+          log("Cancelled.");
+          return;
+        }
+      }
+
+      const bookDir = join(root, "books", bookId);
+      await rm(bookDir, { recursive: true, force: true });
+
+      if (opts.json) {
+        log(JSON.stringify({ deleted: bookId, chapters: index.length }));
+      } else {
+        log(`Deleted "${book.title}" (${bookId}): ${index.length} chapter(s) removed.`);
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Failed to delete book: ${e}`);
+      }
+      process.exit(1);
+    }
+  });

package/inkos/packages/cli/src/commands/compose.ts

@@ -0,0 +1,50 @@
+import { Command } from "commander";
+import { PipelineRunner } from "@actalk/inkos-core";
+import { buildPipelineConfig, findProjectRoot, loadConfig, log, logError, resolveBookId, resolveContext } from "../utils.js";
+
+export const composeCommand = new Command("compose")
+  .description("Compose chapter runtime artifacts");
+
+composeCommand
+  .command("chapter")
+  .description("Generate context/rule-stack/trace artifacts for the next chapter")
+  .argument("[book-id]", "Book ID (auto-detected if only one book)")
+  .option("--context <text>", "Chapter steering guidance")
+  .option("--context-file <path>", "Read guidance from file")
+  .option("--json", "Output JSON")
+  .option("-q, --quiet", "Suppress console output")
+  .action(async (bookIdArg: string | undefined, opts) => {
+    try {
+      const config = await loadConfig({ requireApiKey: false });
+      const root = findProjectRoot();
+      const bookId = await resolveBookId(bookIdArg, root);
+      const context = await resolveContext(opts);
+
+      const pipeline = new PipelineRunner(
+        buildPipelineConfig(config, root, {
+          externalContext: context,
+          inputGovernanceMode: "v2",
+          quiet: opts.quiet,
+        }),
+      );
+
+      const result = await pipeline.composeChapter(bookId, context);
+
+      if (opts.json) {
+        log(JSON.stringify(result, null, 2));
+      } else {
+        log(`Composed chapter ${result.chapterNumber} for "${bookId}"`);
+        log(`  Intent: ${result.intentPath}`);
+        log(`  Context: ${result.contextPath}`);
+        log(`  Rule stack: ${result.ruleStackPath}`);
+        log(`  Trace: ${result.tracePath}`);
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Failed to compose chapter: ${e}`);
+      }
+      process.exit(1);
+    }
+  });