@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/cli/src/commands/short-fiction.ts

@@ -0,0 +1,294 @@
+import { Command } from "commander";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import {
+  SHORT_FICTION_DEFAULT_CHAPTERS,
+  SHORT_FICTION_DEFAULT_CHARS_PER_CHAPTER,
+  SHORT_FICTION_MAX_CHAPTERS,
+  SHORT_FICTION_MAX_CHARS_PER_CHAPTER,
+  SHORT_FICTION_MIN_CHAPTERS,
+  SHORT_FICTION_MIN_CHARS_PER_CHAPTER,
+  createLLMClient,
+  runShortFictionProduction,
+  type LLMConfig,
+  type Logger,
+  type OnStreamProgress,
+  type ShortFictionReference,
+} from "@actalk/inkos-core";
+import { buildPipelineConfig, findProjectRoot, loadConfig, log, logError } from "../utils.js";
+
+export { extractResponsesImageBase64, resolveCoverApiKey } from "@actalk/inkos-core";
+
+export const shortCommand = new Command("short")
+  .description("Short fiction production workflow");
+
+shortCommand
+  .command("run")
+  .description("Run a short fiction chain from a direction")
+  .requiredOption("--direction <text>", "Story direction, e.g. 女频短篇 婚姻背叛 证据反杀")
+  .option("--reference <path>", "Optional reference notes/text")
+  .option("--story-id <id>", "Output story id under shorts/")
+  .option("--out-dir <path>", "Output directory", "shorts")
+  .option("--chapters <n>", "Complete short chapter count (12-18)", String(SHORT_FICTION_DEFAULT_CHAPTERS))
+  .option("--chars <n>", "Target characters per chapter (900-1200)", String(SHORT_FICTION_DEFAULT_CHARS_PER_CHAPTER))
+  .option("--stage <stage>", "Execution stage (outline | draft | package | all)", "all")
+  .option("--llm-base-url <url>", "Override LLM base URL")
+  .option("--model <model>", "Fallback model for all short stages")
+  .option("--planner-model <model>", "Model for outline creation/revision")
+  .option("--outline-review-model <model>", "Model for outline review")
+  .option("--writer-model <model>", "Model for first full draft")
+  .option("--draft-review-model <model>", "Model for draft review")
+  .option("--revise-model <model>", "Model for second full draft")
+  .option("--package-model <model>", "Model for synopsis and cover prompt packaging")
+  .option("--cover-base-url <url>", "OpenAI-compatible Responses API base URL for cover generation, e.g. https://api.openai.com/v1")
+  .option("--cover-endpoint <url>", "Exact Responses endpoint for cover generation; overrides --cover-base-url")
+  .option("--cover-model <model>", "Image-capable Responses model for cover generation", "gpt-5.5")
+  .option("--cover-size <size>", "Cover image size", "1024x1360")
+  .option("--cover-api-key-env <name>", "Env var containing cover API key", "INKOS_COVER_API_KEY")
+  .option("--no-cover", "Skip cover image generation")
+  .option("--json", "Output JSON")
+  .action(async (opts: ShortRunOptions) => {
+    try {
+      const root = findProjectRoot();
+      const chapterCount = parseBoundedInteger(
+        opts.chapters,
+        SHORT_FICTION_DEFAULT_CHAPTERS,
+        "chapters",
+        SHORT_FICTION_MIN_CHAPTERS,
+        SHORT_FICTION_MAX_CHAPTERS,
+      );
+      const charsPerChapter = parseBoundedInteger(
+        opts.chars,
+        SHORT_FICTION_DEFAULT_CHARS_PER_CHAPTER,
+        "chars",
+        SHORT_FICTION_MIN_CHARS_PER_CHAPTER,
+        SHORT_FICTION_MAX_CHARS_PER_CHAPTER,
+      );
+      const reference = opts.reference ? await readReference(root, opts.reference) : undefined;
+      const models = resolveShortRunModels(opts);
+
+      const plannerRuntime = await createShortRuntime(root, {
+        llmBaseUrl: opts.llmBaseUrl,
+        model: models.planner,
+        quiet: Boolean(opts.json),
+      });
+      const outlineReviewRuntime = await createShortRuntime(root, {
+        llmBaseUrl: opts.llmBaseUrl,
+        model: models.outlineReview,
+        quiet: Boolean(opts.json),
+      });
+      const writerRuntime = await createShortRuntime(root, {
+        llmBaseUrl: opts.llmBaseUrl,
+        model: models.writer,
+        quiet: Boolean(opts.json),
+      });
+      const draftReviewRuntime = await createShortRuntime(root, {
+        llmBaseUrl: opts.llmBaseUrl,
+        model: models.draftReview,
+        quiet: Boolean(opts.json),
+      });
+      const reviseRuntime = await createShortRuntime(root, {
+        llmBaseUrl: opts.llmBaseUrl,
+        model: models.revise,
+        quiet: Boolean(opts.json),
+      });
+      const packageRuntime = await createShortRuntime(root, {
+        llmBaseUrl: opts.llmBaseUrl,
+        model: models.package,
+        quiet: Boolean(opts.json),
+      });
+
+      const result = await runShortFictionProduction({
+        projectRoot: root,
+        direction: opts.direction,
+        runtimes: {
+          planner: { ...plannerRuntime, projectRoot: root },
+          outlineReview: { ...outlineReviewRuntime, projectRoot: root },
+          writer: { ...writerRuntime, projectRoot: root },
+          draftReview: { ...draftReviewRuntime, projectRoot: root },
+          revise: { ...reviseRuntime, projectRoot: root },
+          package: { ...packageRuntime, projectRoot: root },
+        },
+        reference,
+        storyId: opts.storyId,
+        outDir: opts.outDir,
+        chapterCount,
+        charsPerChapter,
+        stage: opts.stage,
+        cover: opts.cover,
+        coverBaseUrl: opts.coverBaseUrl,
+        coverEndpoint: opts.coverEndpoint,
+        coverModel: opts.coverModel,
+        coverSize: opts.coverSize,
+        coverApiKeyEnv: opts.coverApiKeyEnv,
+        onProgress: opts.json ? undefined : (message) => log(message),
+      });
+
+      const payload = {
+        ...result,
+        models,
+      };
+
+      if (opts.json) {
+        log(JSON.stringify(payload, null, 2));
+      } else {
+        log(`Short run complete: ${result.storyId}`);
+        log(`Final: ${payload.finalMarkdownPath}`);
+        log(`Sales package: ${payload.salesPackagePath}`);
+        log(formatCoverStatus(payload.coverImagePath, payload.coverError));
+      }
+    } catch (e) {
+      logCommandError("Short run failed", e, opts.json);
+    }
+  });
+
+interface ShortRunOptions {
+  readonly direction: string;
+  readonly reference?: string;
+  readonly storyId?: string;
+  readonly outDir: string;
+  readonly chapters?: string;
+  readonly chars?: string;
+  readonly stage?: "outline" | "draft" | "package" | "all";
+  readonly llmBaseUrl?: string;
+  readonly model?: string;
+  readonly plannerModel?: string;
+  readonly outlineReviewModel?: string;
+  readonly writerModel?: string;
+  readonly draftReviewModel?: string;
+  readonly reviseModel?: string;
+  readonly packageModel?: string;
+  readonly coverBaseUrl?: string;
+  readonly coverEndpoint?: string;
+  readonly coverModel?: string;
+  readonly coverSize?: string;
+  readonly coverApiKeyEnv?: string;
+  readonly cover?: boolean;
+  readonly json?: boolean;
+}
+
+interface ShortRuntime {
+  readonly client: ReturnType<typeof createLLMClient>;
+  readonly model: string;
+  readonly logger?: Logger;
+  readonly onStreamProgress?: OnStreamProgress;
+}
+
+interface ShortRunModels {
+  readonly planner?: string;
+  readonly outlineReview?: string;
+  readonly writer?: string;
+  readonly draftReview?: string;
+  readonly revise?: string;
+  readonly package?: string;
+}
+
+function resolveShortRunModels(options: ShortRunOptions): ShortRunModels {
+  return {
+    planner: options.plannerModel || options.model,
+    outlineReview: options.outlineReviewModel || options.model,
+    writer: options.writerModel || options.model,
+    draftReview: options.draftReviewModel || options.model,
+    revise: options.reviseModel || options.model,
+    package: options.packageModel || options.model,
+  };
+}
+
+async function createShortRuntime(
+  root: string,
+  options: {
+    readonly llmBaseUrl?: string;
+    readonly model?: string;
+    readonly quiet?: boolean;
+  },
+): Promise<ShortRuntime> {
+  try {
+    const config = await loadConfig({ projectRoot: root });
+    if (options.llmBaseUrl) config.llm.baseUrl = options.llmBaseUrl;
+    if (options.model) config.llm.model = options.model;
+    const pipelineConfig = buildPipelineConfig(config, root, { quiet: options.quiet });
+    return {
+      client: pipelineConfig.client,
+      model: pipelineConfig.model,
+      logger: pipelineConfig.logger,
+      onStreamProgress: pipelineConfig.onStreamProgress,
+    };
+  } catch (e) {
+    if (!String(e).includes("inkos.json not found")) throw e;
+    const llmConfig = buildEnvLLMConfig(options);
+    return {
+      client: createLLMClient(llmConfig),
+      model: llmConfig.model,
+    };
+  }
+}
+
+function buildEnvLLMConfig(options: {
+  readonly llmBaseUrl?: string;
+  readonly model?: string;
+}): LLMConfig {
+  const baseUrl = options.llmBaseUrl ?? process.env.INKOS_LLM_BASE_URL;
+  const model = options.model ?? process.env.INKOS_LLM_MODEL;
+  if (!baseUrl) throw new Error("LLM base URL is required. Set INKOS_LLM_BASE_URL or pass --llm-base-url.");
+  if (!model) throw new Error("LLM model is required. Set INKOS_LLM_MODEL or pass --model.");
+  return {
+    provider: "openai",
+    service: process.env.INKOS_LLM_SERVICE ?? "custom",
+    configSource: "env",
+    baseUrl,
+    apiKey: process.env.INKOS_LLM_API_KEY ?? "",
+    model,
+    temperature: parseEnvNumber(process.env.INKOS_LLM_TEMPERATURE, 0.1),
+    thinkingBudget: parseEnvInteger(process.env.INKOS_LLM_THINKING_BUDGET, 0),
+    apiFormat: process.env.INKOS_LLM_API_FORMAT === "responses" ? "responses" : "chat",
+    stream: process.env.INKOS_LLM_STREAM === "false" ? false : true,
+  };
+}
+
+async function readReference(root: string, path: string): Promise<ShortFictionReference> {
+  const resolved = resolve(root, path);
+  return {
+    path,
+    text: await readFile(resolved, "utf-8"),
+  };
+}
+
+function parseBoundedInteger(
+  value: string | undefined,
+  fallback: number,
+  name: string,
+  min: number,
+  max: number,
+): number {
+  const parsed = value ? Number.parseInt(value, 10) : fallback;
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw new Error(`${name} must be an integer between ${min} and ${max}.`);
+  }
+  return parsed;
+}
+
+function parseEnvNumber(value: string | undefined, fallback: number): number {
+  if (!value) return fallback;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function parseEnvInteger(value: string | undefined, fallback: number): number {
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function formatCoverStatus(coverImagePath?: string, coverError?: string): string {
+  if (coverImagePath) return `Cover: ${coverImagePath}`;
+  if (coverError) return `Cover: skipped (${coverError})`;
+  return "Cover: skipped";
+}
+
+function logCommandError(prefix: string, error: unknown, json?: boolean): void {
+  if (json) {
+    log(JSON.stringify({ error: `${prefix}: ${String(error)}` }, null, 2));
+    return;
+  }
+  logError(`${prefix}: ${String(error)}`);
+}

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

@@ -0,0 +1,138 @@
+import { Command } from "commander";
+import { StateManager, formatLengthCount, readGenreProfile, resolveLengthCountingMode } from "@actalk/inkos-core";
+import { findProjectRoot, getLegacyMigrationHint, log, logError } from "../utils.js";
+
+export const statusCommand = new Command("status")
+  .description("Show project status")
+  .argument("[book-id]", "Book ID (optional, shows all if omitted)")
+  .option("--chapters", "Show per-chapter status and issues")
+  .option("--json", "Output JSON")
+  .action(async (bookIdArg: string | undefined, opts) => {
+    try {
+      const root = findProjectRoot();
+      const state = new StateManager(root);
+
+      const allBookIds = await state.listBooks();
+      const bookIds = bookIdArg ? [bookIdArg] : allBookIds;
+
+      if (bookIdArg && !allBookIds.includes(bookIdArg)) {
+        throw new Error(
+          `Book "${bookIdArg}" not found. Available: ${allBookIds.join(", ") || "(none)"}`,
+        );
+      }
+
+      const booksData = [];
+
+      if (!opts.json) {
+        log(`InkOS Project: ${root}`);
+        log(`Books: ${allBookIds.length}`);
+        log("");
+      }
+
+      for (const id of bookIds) {
+        const book = await state.loadBookConfig(id);
+        const index = await state.loadChapterIndex(id);
+        const migrationHint = await getLegacyMigrationHint(root, id);
+        const persistedChapterCount = await state.getPersistedChapterCount(id);
+        const { profile: genreProfile } = await readGenreProfile(root, book.genre);
+        const countingMode = resolveLengthCountingMode(book.language ?? genreProfile.language);
+
+        const approved = index.filter((ch) => ch.status === "approved").length;
+        const pending = index.filter(
+          (ch) => ch.status === "ready-for-review",
+        ).length;
+        const failed = index.filter(
+          (ch) => ch.status === "audit-failed",
+        ).length;
+        const degraded = index.filter(
+          (ch) => ch.status === "state-degraded",
+        ).length;
+        const totalWords = index.reduce((sum, ch) => sum + ch.wordCount, 0);
+        const avgWords = index.length > 0 ? Math.round(totalWords / index.length) : 0;
+
+        booksData.push({
+          id,
+          title: book.title,
+          status: book.status,
+          genre: book.genre,
+          platform: book.platform,
+          chapters: persistedChapterCount,
+          targetChapters: book.targetChapters,
+          totalWords,
+          avgWordsPerChapter: avgWords,
+          approved,
+          pending,
+          failed,
+          degraded,
+          ...(migrationHint ? { migrationHint } : {}),
+          ...(opts.chapters ? {
+            chapterList: index.map((ch) => ({
+              number: ch.number,
+              title: ch.title,
+              status: ch.status,
+              wordCount: ch.wordCount,
+              ...(ch.status === "audit-failed" || ch.status === "state-degraded"
+                ? { issues: ch.auditIssues }
+                : {}),
+            })),
+          } : {}),
+        });
+
+        if (!opts.json) {
+          log(`  ${book.title} (${id})`);
+          log(`    Status: ${book.status}`);
+          log(`    Platform: ${book.platform} | Genre: ${book.genre}`);
+          log(`    Chapters: ${persistedChapterCount} / ${book.targetChapters}`);
+          log(`    Words: ${totalWords.toLocaleString()} (avg ${avgWords}/ch)`);
+          log(`    Approved: ${approved} | Pending: ${pending} | Failed: ${failed} | Degraded: ${degraded}`);
+          if (migrationHint) {
+            log(`    Migration: ${migrationHint}`);
+          }
+
+          if (opts.chapters && index.length > 0) {
+            log("");
+            for (const ch of index) {
+              const icon = ch.status === "approved"
+                ? "+"
+                : ch.status === "audit-failed"
+                  ? "!"
+                  : ch.status === "state-degraded"
+                    ? "x"
+                    : "~";
+              log(`    [${icon}] Ch.${ch.number} "${ch.title}" | ${formatLengthCount(ch.wordCount, countingMode)} | ${ch.status}`);
+              if ((ch.status === "audit-failed" || ch.status === "state-degraded") && ch.auditIssues.length > 0) {
+                const criticals = ch.auditIssues.filter((i: string) => i.startsWith("[critical]"));
+                const warnings = ch.auditIssues.filter((i: string) => i.startsWith("[warning]"));
+                if (criticals.length > 0) {
+                  for (const issue of criticals) {
+                    log(`        ${issue}`);
+                  }
+                }
+                if (warnings.length > 0) {
+                  if (ch.status === "state-degraded") {
+                    for (const issue of warnings) {
+                      log(`        ${issue}`);
+                    }
+                  } else {
+                    log(`        + ${warnings.length} warning(s)`);
+                  }
+                }
+              }
+            }
+          }
+          log("");
+        }
+      }
+
+      if (opts.json) {
+        log(JSON.stringify({ project: root, books: booksData }, null, 2));
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Failed to get status: ${e}`);
+      }
+      process.exit(1);
+    }
+  });

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

@@ -0,0 +1,194 @@
+import { Command } from "commander";
+import { findProjectRoot, log, logError } from "../utils.js";
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { access } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { ensureProjectDirectoryInitialized } from "../project-bootstrap.js";
+
+export interface StudioLaunchSpec {
+  readonly studioEntry: string;
+  readonly command: string;
+  readonly args: string[];
+}
+
+export interface BrowserLaunchSpec {
+  readonly command: string;
+  readonly args: string[];
+}
+
+export interface StudioCommandHooks {
+  readonly launchStudio?: (projectRoot: string, port: string) => Promise<void> | void;
+}
+
+async function prepareStudioRoot(root: string): Promise<{ readonly root: string; readonly initialized: boolean }> {
+  const initialized = await ensureProjectDirectoryInitialized(root, { language: "zh" });
+  return { root, initialized };
+}
+
+async function firstAccessiblePath(paths: readonly string[]): Promise<string | undefined> {
+  for (const path of paths) {
+    try {
+      await access(path);
+      return path;
+    } catch {
+      // continue
+    }
+  }
+  return undefined;
+}
+
+const cliPackageRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+export function toNodeImportSpecifier(path: string): string {
+  if (/^[A-Za-z]:[\\/]/.test(path)) {
+    return `file:///${path.replace(/\\/g, "/")}`;
+  }
+  return path;
+}
+
+export function resolveBrowserLaunch(
+  platform: NodeJS.Platform,
+  url: string,
+): BrowserLaunchSpec {
+  if (platform === "darwin") {
+    return { command: "open", args: [url] };
+  }
+  if (platform === "win32") {
+    return { command: "cmd", args: ["/c", "start", "", url] };
+  }
+  return { command: "xdg-open", args: [url] };
+}
+
+export async function resolveStudioLaunch(root: string): Promise<StudioLaunchSpec | null> {
+  const sourceEntry = await firstAccessiblePath([
+    join(root, "packages", "studio", "src", "api", "index.ts"),
+    join(root, "..", "packages", "studio", "src", "api", "index.ts"),
+    join(root, "..", "studio", "src", "api", "index.ts"),
+  ]);
+  if (sourceEntry) {
+    const studioPackageRoot = dirname(dirname(dirname(sourceEntry)));
+    const localTsxLoader = await firstAccessiblePath([
+      join(studioPackageRoot, "node_modules", "tsx", "dist", "loader.mjs"),
+    ]);
+    if (localTsxLoader) {
+      return {
+        studioEntry: sourceEntry,
+        command: "node",
+        args: ["--import", toNodeImportSpecifier(localTsxLoader), sourceEntry, root],
+      };
+    }
+
+    const localTsx = await firstAccessiblePath([
+      join(studioPackageRoot, "node_modules", ".bin", "tsx"),
+    ]);
+    if (localTsx) {
+      return {
+        studioEntry: sourceEntry,
+        command: localTsx,
+        args: [sourceEntry, root],
+      };
+    }
+    return {
+      studioEntry: sourceEntry,
+      command: "npx",
+      args: ["tsx", sourceEntry, root],
+    };
+  }
+
+  const builtEntry = await firstAccessiblePath([
+    join(root, "node_modules", "@actalk", "inkos-studio", "dist", "api", "index.js"),
+    join(root, "node_modules", "@actalk", "inkos-studio", "server.cjs"),
+    join(cliPackageRoot, "node_modules", "@actalk", "inkos-studio", "dist", "api", "index.js"),
+    join(cliPackageRoot, "node_modules", "@actalk", "inkos-studio", "server.cjs"),
+    join(cliPackageRoot, "..", "inkos-studio", "dist", "api", "index.js"),
+    join(cliPackageRoot, "..", "inkos-studio", "server.cjs"),
+  ]);
+  if (builtEntry) {
+    return {
+      studioEntry: builtEntry,
+      command: "node",
+      args: [builtEntry, root],
+    };
+  }
+
+  return null;
+}
+
+export async function launchStudioWorkbench(root: string, port: string): Promise<void> {
+  const prepared = await prepareStudioRoot(root);
+  const url = prepared.initialized
+    ? `http://localhost:${port}#/services`
+    : `http://localhost:${port}`;
+  const launch = await resolveStudioLaunch(root);
+
+  if (!launch) {
+    logError(
+      "InkOS Studio not found. If you cloned the repo, run:\n" +
+      "  cd packages/studio && pnpm install && pnpm build\n" +
+      "Then run 'inkos studio' from the project root.",
+    );
+    process.exit(1);
+  }
+
+  log(`Starting InkOS Studio on ${url}`);
+
+  const child = spawn(launch.command, launch.args, {
+    cwd: root,
+    stdio: "inherit",
+    env: { ...process.env, INKOS_STUDIO_PORT: port },
+  });
+
+  child.on("error", (e) => {
+    logError(`Failed to start studio: ${e.message}`);
+    process.exit(1);
+  });
+
+  const browserLaunch = resolveBrowserLaunch(process.platform, url);
+  const browser = spawn(browserLaunch.command, browserLaunch.args, {
+    cwd: root,
+    stdio: "ignore",
+    detached: true,
+  });
+  browser.on("error", () => {
+    // Best effort only — server startup should not fail just because browser open failed.
+  });
+  if (typeof browser.unref === "function") {
+    browser.unref();
+  }
+
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+}
+
+export async function launchStudioEntry(
+  root: string,
+  port: string,
+  hooks: StudioCommandHooks = {},
+): Promise<void> {
+  const prepared = await prepareStudioRoot(root);
+  if (prepared.initialized) {
+    log(`No inkos.json found in ${root}. Initialized a minimal InkOS project for Studio.`);
+  }
+
+  if (hooks.launchStudio) {
+    await hooks.launchStudio(prepared.root, port);
+    return;
+  }
+
+  await launchStudioWorkbench(prepared.root, port);
+}
+
+export function createStudioCommand(hooks: StudioCommandHooks = {}): Command {
+  return new Command("studio")
+  .description("Start InkOS Studio web workbench")
+  .option("-p, --port <port>", "Server port", "4567")
+  .action(async (opts) => {
+    const root = findProjectRoot();
+    const port = opts.port;
+    await launchStudioEntry(root, port, hooks);
+  });
+}
+
+export const studioCommand = createStudioCommand();