novelforge-agent 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "novelforge-agent",
+  "version": "0.1.0",
+  "description": "Local-first long-form novel workflow engine for any MCP host (Claude Code, Codex CLI, …) or CLI. State machine + zod schemas + BM25 retrieval + persistent project state. No LLM dependency.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "codex",
+    "novel",
+    "fiction",
+    "writing",
+    "agent",
+    "workflow",
+    "bm25",
+    "retrieval"
+  ],
+  "homepage": "https://github.com/linkzhao/novelforge-agent#readme",
+  "bugs": {
+    "url": "https://github.com/linkzhao/novelforge-agent/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linkzhao/novelforge-agent.git"
+  },
+  "license": "MIT",
+  "author": "linkzhao <linkzhao8@gmail.com>",
+  "type": "module",
+  "bin": {
+    "novelforge-agent": "./dist/src/cli/index.js",
+    "novelforge-agent-mcp": "./dist/src/mcp/server.js"
+  },
+  "files": [
+    "dist/src/**/*.js",
+    "dist/src/**/*.d.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/*.test.js",
+    "dev:mcp": "tsx src/mcp/server.ts",
+    "dev:cli": "tsx src/cli/index.ts",
+    "prepublishOnly": "npm run build && npm test",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "minisearch": "^7.2.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.3",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import {
+  buildContext,
+  createProject,
+  getNextStep,
+  getProjectStatus,
+  listProjects,
+  requestSideTrack,
+  retrieve,
+  submitStepResult,
+} from '../core/index.js';
+
+function valueAfter(args: string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+function parseLanguage(value: string): 'zh-CN' | 'en-US' {
+  if (value === 'zh-CN' || value === 'en-US') return value;
+  throw new Error('Invalid --language. Use zh-CN or en-US');
+}
+
+export async function runCli(argv = process.argv.slice(2), cwd = process.cwd()): Promise<void> {
+  const [command, projectPath] = argv;
+
+  if (command === 'start') {
+    const prompt = valueAfter(argv, '--prompt') || '';
+    if (!prompt.trim()) throw new Error('Missing --prompt');
+    const language = parseLanguage(valueAfter(argv, '--language') || 'zh-CN');
+    const chapters = Number(valueAfter(argv, '--chapters') || 3);
+    const outputDir = valueAfter(argv, '--output') || 'novels';
+    const result = await createProject({ workspaceRoot: cwd, prompt, language, outputDir, targetChapters: chapters });
+    const next = await getNextStep(result.state.projectPath);
+    console.log(JSON.stringify({ state: result.state, next }, null, 2));
+    return;
+  }
+
+  if (command === 'next') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    console.log(JSON.stringify(await getNextStep(projectPath), null, 2));
+    return;
+  }
+
+  if (command === 'submit') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const step = valueAfter(argv, '--step');
+    const file = valueAfter(argv, '--file');
+    if (!step || !file) throw new Error('Missing --step or --file');
+    const content = await readFile(file, 'utf8');
+    console.log(JSON.stringify(await submitStepResult({ projectPath, step: step as any, content }), null, 2));
+    return;
+  }
+
+  if (command === 'context') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const purpose = valueAfter(argv, '--purpose') || 'chapter_generation';
+    const chapter = valueAfter(argv, '--chapter');
+    const start = valueAfter(argv, '--start');
+    const end = valueAfter(argv, '--end');
+    console.log(await buildContext({
+      projectPath,
+      purpose: purpose as any,
+      chapterNumber: chapter ? Number(chapter) : undefined,
+      range: start && end ? { start: Number(start), end: Number(end) } : undefined,
+    }));
+    return;
+  }
+
+  if (command === 'review') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const chapter = valueAfter(argv, '--chapter');
+    if (!chapter) throw new Error('Missing --chapter');
+    console.log(JSON.stringify(
+      await requestSideTrack({ projectPath, step: 'chapter_review', chapterNumber: Number(chapter) }),
+      null,
+      2
+    ));
+    return;
+  }
+
+  if (command === 'revise') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const chapter = valueAfter(argv, '--chapter');
+    if (!chapter) throw new Error('Missing --chapter');
+    const feedbackFile = valueAfter(argv, '--feedback-file');
+    const feedback = feedbackFile ? await readFile(feedbackFile, 'utf8') : valueAfter(argv, '--feedback');
+    console.log(JSON.stringify(
+      await requestSideTrack({ projectPath, step: 'chapter_revision', chapterNumber: Number(chapter), feedback }),
+      null,
+      2
+    ));
+    return;
+  }
+
+  if (command === 'cross-review') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const start = valueAfter(argv, '--start');
+    const end = valueAfter(argv, '--end');
+    const range = start && end ? { start: Number(start), end: Number(end) } : undefined;
+    console.log(JSON.stringify(
+      await requestSideTrack({ projectPath, step: 'cross_chapter_review', range }),
+      null,
+      2
+    ));
+    return;
+  }
+
+  if (command === 'list') {
+    const outputDir = valueAfter(argv, '--output') || 'novels';
+    console.log(JSON.stringify(await listProjects({ workspaceRoot: cwd, outputDir }), null, 2));
+    return;
+  }
+
+  if (command === 'status') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    console.log(JSON.stringify(await getProjectStatus(projectPath), null, 2));
+    return;
+  }
+
+  if (command === 'retrieve') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const query = valueAfter(argv, '--query');
+    if (!query) throw new Error('Missing --query');
+    const topK = valueAfter(argv, '--top-k');
+    const start = valueAfter(argv, '--start');
+    const end = valueAfter(argv, '--end');
+    const typesArg = valueAfter(argv, '--types');
+    const types = typesArg ? (typesArg.split(',') as Array<'chapter' | 'bible' | 'memory'>) : undefined;
+    const hits = await retrieve(projectPath, query, {
+      topK: topK ? Number(topK) : undefined,
+      types,
+      chapterRange: start && end ? { start: Number(start), end: Number(end) } : undefined,
+    });
+    console.log(JSON.stringify({ query, hits }, null, 2));
+    return;
+  }
+
+  throw new Error('Usage: novelforge-agent start|list|status|next|submit|context|review|revise|cross-review|retrieve');
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runCli().catch((error) => {
+    console.error((error as Error).message);
+    process.exitCode = 1;
+  });
+}

package/src/core/contextBuilder.ts

@@ -0,0 +1,131 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { chapterFileName, chapterReviewFileName, memoryFileName } from './fileNames.js';
+import { formatHits, retrieve } from './retrieval/index.js';
+
+export type ContextPurpose =
+  | 'chapter_generation'
+  | 'memory_extraction'
+  | 'continuity_review'
+  | 'revision'
+  | 'chapter_review'
+  | 'cross_chapter_review';
+
+export interface BuildContextInput {
+  projectPath: string;
+  purpose: ContextPurpose;
+  chapterNumber?: number;
+  range?: { start: number; end: number };
+  feedback?: string;
+}
+
+async function readOptional(path: string): Promise<string> {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+export async function buildContext(input: BuildContextInput): Promise<string> {
+  const parts: string[] = [];
+  const metadata = await readOptional(join(input.projectPath, 'novel.json'));
+  const storyBible = await readOptional(join(input.projectPath, 'story-bible.md'));
+  const chaptersJson = await readOptional(join(input.projectPath, 'architecture/chapters.json'));
+
+  if (metadata) parts.push(`## Novel Metadata\n${metadata}`);
+  if (storyBible) parts.push(`## Story Bible\n${storyBible.slice(0, 4000)}`);
+
+  if (input.purpose === 'chapter_generation' && input.chapterNumber) {
+    let currentArchitectureForQuery: { summary?: string; requiredBeats?: string[]; title?: string } | undefined;
+    if (chaptersJson) {
+      const chapters = JSON.parse(chaptersJson) as Array<{ chapterNumber: number; title: string; summary: string; requiredBeats?: string[] }>;
+      const chapter = chapters.find((item) => item.chapterNumber === input.chapterNumber);
+      if (chapter) {
+        currentArchitectureForQuery = chapter;
+        parts.push(`## Current Chapter Architecture\n${JSON.stringify(chapter, null, 2)}`);
+      }
+    }
+    if (input.chapterNumber > 1) {
+      const previous = await readOptional(join(input.projectPath, 'chapters', chapterFileName(input.chapterNumber - 1)));
+      const previousMemory = await readOptional(join(input.projectPath, 'memory', memoryFileName(input.chapterNumber - 1)));
+      if (previous) parts.push(`## Previous Chapter Ending\n${previous.slice(-1600)}`);
+      if (previousMemory) parts.push(`## Previous Chapter Memory\n${previousMemory}`);
+
+      const queryPieces: string[] = [];
+      if (currentArchitectureForQuery?.title) queryPieces.push(currentArchitectureForQuery.title);
+      if (currentArchitectureForQuery?.summary) queryPieces.push(currentArchitectureForQuery.summary);
+      if (currentArchitectureForQuery?.requiredBeats?.length) {
+        queryPieces.push(currentArchitectureForQuery.requiredBeats.join(' '));
+      }
+      const query = queryPieces.join(' ').trim();
+      if (query) {
+        const hits = await retrieve(input.projectPath, query, {
+          topK: 5,
+          chapterRange: { start: 1, end: input.chapterNumber - 1 },
+        });
+        const formatted = formatHits(hits);
+        if (formatted) parts.push(`## Retrieved Relevant Snippets (lexical, BM25-style)\n${formatted}`);
+      }
+    }
+  }
+
+  if (input.purpose === 'memory_extraction' && input.chapterNumber) {
+    const chapter = await readOptional(join(input.projectPath, 'chapters', chapterFileName(input.chapterNumber)));
+    if (chapter) parts.push(`## Current Chapter\n${chapter}`);
+  }
+
+  if (input.purpose === 'continuity_review') {
+    if (chaptersJson) parts.push(`## Chapter Architecture List\n${chaptersJson}`);
+    const memoryParts: string[] = [];
+    for (let i = 1; i <= 20; i += 1) {
+      const memory = await readOptional(join(input.projectPath, 'memory', memoryFileName(i)));
+      if (memory) memoryParts.push(`### Chapter ${i}\n${memory}`);
+    }
+    if (memoryParts.length) parts.push(`## Memory Cards\n${memoryParts.join('\n')}`);
+  }
+
+  if (input.purpose === 'chapter_review' && input.chapterNumber) {
+    if (chaptersJson) {
+      const chapters = JSON.parse(chaptersJson) as Array<{ chapterNumber: number; title: string; summary: string; requiredBeats?: string[] }>;
+      const arch = chapters.find((item) => item.chapterNumber === input.chapterNumber);
+      if (arch) parts.push(`## Target Chapter Architecture\n${JSON.stringify(arch, null, 2)}`);
+    }
+    const chapter = await readOptional(join(input.projectPath, 'chapters', chapterFileName(input.chapterNumber)));
+    if (chapter) parts.push(`## Chapter ${input.chapterNumber} Text\n${chapter}`);
+    if (input.chapterNumber > 1) {
+      const prevMemory = await readOptional(join(input.projectPath, 'memory', memoryFileName(input.chapterNumber - 1)));
+      if (prevMemory) parts.push(`## Previous Chapter Memory\n${prevMemory}`);
+    }
+  }
+
+  if (input.purpose === 'revision' && input.chapterNumber) {
+    const chapter = await readOptional(join(input.projectPath, 'chapters', chapterFileName(input.chapterNumber)));
+    if (chapter) parts.push(`## Current Chapter Text\n${chapter}`);
+    const review = await readOptional(join(input.projectPath, 'reviews/chapter', chapterReviewFileName(input.chapterNumber)));
+    if (review) parts.push(`## Editor Review\n${review}`);
+    if (input.feedback) parts.push(`## Additional Feedback\n${input.feedback}`);
+    if (input.chapterNumber > 1) {
+      const previous = await readOptional(join(input.projectPath, 'chapters', chapterFileName(input.chapterNumber - 1)));
+      if (previous) parts.push(`## Previous Chapter Ending\n${previous.slice(-1600)}`);
+    }
+  }
+
+  if (input.purpose === 'cross_chapter_review' && input.range) {
+    if (chaptersJson) parts.push(`## Chapter Architecture List\n${chaptersJson}`);
+    const memoryParts: string[] = [];
+    for (let i = input.range.start; i <= input.range.end; i += 1) {
+      const memory = await readOptional(join(input.projectPath, 'memory', memoryFileName(i)));
+      if (memory) memoryParts.push(`### Chapter ${i} Memory\n${memory}`);
+    }
+    if (memoryParts.length) parts.push(`## Memory Cards In Range\n${memoryParts.join('\n')}`);
+    const tailParts: string[] = [];
+    for (let i = input.range.start; i <= input.range.end; i += 1) {
+      const chapter = await readOptional(join(input.projectPath, 'chapters', chapterFileName(i)));
+      if (chapter) tailParts.push(`### Chapter ${i} Last 800 Chars\n${chapter.slice(-800)}`);
+    }
+    if (tailParts.length) parts.push(`## Chapter Tails\n${tailParts.join('\n')}`);
+  }
+
+  return parts.join('\n\n').trim();
+}

package/src/core/fileNames.ts

@@ -0,0 +1,48 @@
+const PINYIN_FALLBACK: Record<string, string> = {
+  星: 'xing',
+  火: 'huo',
+  长: 'chang',
+  夜: 'ye',
+};
+
+export function makeProjectSlug(title: string): string {
+  const replaced = title
+    .trim()
+    .split('')
+    .map((char) => PINYIN_FALLBACK[char] || char)
+    .join('-')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return replaced || `novel-${Date.now()}`;
+}
+
+export function padChapterNumber(chapterNumber: number): string {
+  if (!Number.isInteger(chapterNumber) || chapterNumber <= 0) {
+    throw new Error(`Invalid chapter number: ${chapterNumber}`);
+  }
+  return String(chapterNumber).padStart(3, '0');
+}
+
+export function chapterFileName(chapterNumber: number): string {
+  return `${padChapterNumber(chapterNumber)}.md`;
+}
+
+export function memoryFileName(chapterNumber: number): string {
+  return `chapter-${padChapterNumber(chapterNumber)}.json`;
+}
+
+export function chapterReviewFileName(chapterNumber: number): string {
+  return `chapter-${padChapterNumber(chapterNumber)}.json`;
+}
+
+export function crossChapterReviewFileName(start: number, end: number): string {
+  return `cross-${padChapterNumber(start)}-${padChapterNumber(end)}.json`;
+}
+
+export function chapterVersionFileName(chapterNumber: number, timestamp: string): string {
+  const safeTs = timestamp.replace(/[:.]/g, '-');
+  return `${padChapterNumber(chapterNumber)}.${safeTs}.md`;
+}

package/src/core/index.ts

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './schemas.js';
+export * from './fileNames.js';
+export * from './projectStore.js';
+export * from './workflow.js';
+export * from './contextBuilder.js';
+export * from './prompts.js';
+export * from './retrieval/index.js';
+export * from './projectDiscovery.js';

package/src/core/projectDiscovery.ts

@@ -0,0 +1,174 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { AgentState, NovelMetadata, WorkflowStep } from './types.js';
+import { loadState } from './projectStore.js';
+
+export interface ProjectSummary {
+  projectId: string;
+  projectPath: string;
+  title?: string;
+  genre?: string;
+  language: AgentState['language'];
+  currentStep: WorkflowStep;
+  currentChapter: number;
+  targetChapters: number;
+  completedSteps: number;
+  chaptersWritten: number;
+  updatedAt: string;
+  createdAt: string;
+}
+
+export interface ListProjectsInput {
+  workspaceRoot: string;
+  outputDir?: string;
+}
+
+async function readMetadata(projectPath: string): Promise<NovelMetadata | undefined> {
+  try {
+    const raw = await readFile(join(projectPath, 'novel.json'), 'utf8');
+    return JSON.parse(raw) as NovelMetadata;
+  } catch {
+    return undefined;
+  }
+}
+
+function countChapters(state: AgentState): number {
+  let count = 0;
+  for (const key of Object.keys(state.files)) {
+    if (/^chapter-\d+$/.test(key)) count += 1;
+  }
+  return count;
+}
+
+async function summarizeOne(projectPath: string): Promise<ProjectSummary | undefined> {
+  let state: AgentState;
+  try {
+    state = await loadState(projectPath);
+  } catch {
+    return undefined;
+  }
+  const metadata = await readMetadata(projectPath);
+  return {
+    projectId: state.projectId,
+    projectPath,
+    title: metadata?.title,
+    genre: metadata?.genre,
+    language: state.language,
+    currentStep: state.currentStep,
+    currentChapter: state.currentChapter,
+    targetChapters: state.targetChapters,
+    completedSteps: state.completedSteps.length,
+    chaptersWritten: countChapters(state),
+    updatedAt: state.updatedAt,
+    createdAt: state.createdAt,
+  };
+}
+
+export async function listProjects(input: ListProjectsInput): Promise<ProjectSummary[]> {
+  const root = resolve(input.workspaceRoot, input.outputDir ?? 'novels');
+  let entries: string[];
+  try {
+    entries = await readdir(root);
+  } catch {
+    return [];
+  }
+  const summaries = await Promise.all(
+    entries.map((entry) => summarizeOne(join(root, entry)))
+  );
+  return summaries
+    .filter((s): s is ProjectSummary => Boolean(s))
+    .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+export interface ProjectStatus extends ProjectSummary {
+  pendingAction?: AgentState['pendingAction'];
+  files: Record<string, string>;
+  openThreads: string[];
+  latestReview?: {
+    type: 'chapter' | 'cross' | 'continuity';
+    path: string;
+    status?: string;
+    chapterNumber?: number;
+    range?: { start: number; end: number };
+    issueCount?: number;
+  };
+  done: boolean;
+}
+
+async function findLatestReview(projectPath: string, files: Record<string, string>): Promise<ProjectStatus['latestReview']> {
+  const keys = Object.keys(files);
+  const chapterReviewKeys = keys.filter((k) => k.startsWith('review-chapter-'));
+  const crossReviewKeys = keys.filter((k) => k.startsWith('review-cross-'));
+  const continuityReviewKey = files.continuityReview;
+
+  type Candidate = { type: 'chapter' | 'cross' | 'continuity'; relative: string; key: string };
+  const candidates: Candidate[] = [];
+  for (const key of chapterReviewKeys) candidates.push({ type: 'chapter', relative: files[key], key });
+  for (const key of crossReviewKeys) candidates.push({ type: 'cross', relative: files[key], key });
+  if (continuityReviewKey) candidates.push({ type: 'continuity', relative: continuityReviewKey, key: 'continuityReview' });
+  if (!candidates.length) return undefined;
+
+  // pick the most-recently-modified one by reading mtimes; fall back to last in map order
+  const { stat } = await import('node:fs/promises');
+  let best: { c: Candidate; mtime: number } | undefined;
+  for (const c of candidates) {
+    try {
+      const s = await stat(join(projectPath, c.relative));
+      if (!best || s.mtimeMs > best.mtime) best = { c, mtime: s.mtimeMs };
+    } catch {
+      // skip missing files
+    }
+  }
+  if (!best) return undefined;
+  try {
+    const raw = await readFile(join(projectPath, best.c.relative), 'utf8');
+    const parsed = JSON.parse(raw);
+    return {
+      type: best.c.type,
+      path: best.c.relative,
+      status: parsed?.status,
+      chapterNumber: parsed?.chapterNumber,
+      range: parsed?.range,
+      issueCount: Array.isArray(parsed?.issues) ? parsed.issues.length : undefined,
+    };
+  } catch {
+    return { type: best.c.type, path: best.c.relative };
+  }
+}
+
+async function collectOpenThreads(projectPath: string, state: AgentState): Promise<string[]> {
+  const threads: string[] = [];
+  const memoryKeys = Object.keys(state.files).filter((k) => /^memory-\d+$/.test(k));
+  for (const key of memoryKeys) {
+    try {
+      const raw = await readFile(join(projectPath, state.files[key]), 'utf8');
+      const parsed = JSON.parse(raw) as { openThreads?: string[] };
+      if (Array.isArray(parsed.openThreads)) {
+        for (const thread of parsed.openThreads) {
+          if (thread && !threads.includes(thread)) threads.push(thread);
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+  return threads;
+}
+
+export async function getProjectStatus(projectPath: string): Promise<ProjectStatus> {
+  const summary = await summarizeOne(projectPath);
+  if (!summary) throw new Error(`Not a NovelForge project: ${projectPath}`);
+  const state = await loadState(projectPath);
+  const [latestReview, openThreads] = await Promise.all([
+    findLatestReview(projectPath, state.files),
+    collectOpenThreads(projectPath, state),
+  ]);
+  return {
+    ...summary,
+    pendingAction: state.pendingAction,
+    files: state.files,
+    openThreads,
+    latestReview,
+    done: state.currentStep === 'complete',
+  };
+}

package/src/core/projectStore.ts

@@ -0,0 +1,111 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { AgentState } from './types.js';
+import { makeProjectSlug } from './fileNames.js';
+
+export interface CreateProjectInput {
+  workspaceRoot: string;
+  prompt: string;
+  language?: AgentState['language'];
+  outputDir?: string;
+  targetChapters?: number;
+}
+
+export interface CreateProjectResult {
+  state: AgentState;
+}
+
+function assertInsideWorkspace(workspaceRoot: string, targetPath: string): void {
+  const root = resolve(workspaceRoot);
+  const target = resolve(targetPath);
+  const rel = relative(root, target);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`Refusing to write outside workspace: ${target}`);
+  }
+}
+
+export async function ensureProjectDirectories(projectPath: string): Promise<void> {
+  await mkdir(projectPath, { recursive: true });
+  await mkdir(join(projectPath, 'architecture'), { recursive: true });
+  await mkdir(join(projectPath, 'chapters'), { recursive: true });
+  await mkdir(join(projectPath, 'chapters/.versions'), { recursive: true });
+  await mkdir(join(projectPath, 'memory'), { recursive: true });
+  await mkdir(join(projectPath, 'reviews'), { recursive: true });
+  await mkdir(join(projectPath, 'reviews/chapter'), { recursive: true });
+  await mkdir(join(projectPath, 'reviews/cross'), { recursive: true });
+  await mkdir(join(projectPath, '.agent-recovery'), { recursive: true });
+}
+
+export async function archiveChapterVersion(projectPath: string, chapterRelative: string, versionRelative: string): Promise<string | undefined> {
+  const sourcePath = join(projectPath, chapterRelative);
+  try {
+    const existing = await readFile(sourcePath, 'utf8');
+    return saveMarkdownFile(projectPath, versionRelative, existing);
+  } catch {
+    return undefined;
+  }
+}
+
+export async function createProject(input: CreateProjectInput): Promise<CreateProjectResult> {
+  const workspaceRoot = resolve(input.workspaceRoot);
+  const baseDir = input.outputDir || 'novels';
+  const targetChapters = Math.max(1, Math.floor(Number(input.targetChapters || 3)));
+  const baseSlug = makeProjectSlug(input.prompt.slice(0, 48));
+  const suffix = randomBytes(3).toString('hex');
+  const slug = `${baseSlug}-${suffix}`;
+  const projectPath = resolve(workspaceRoot, baseDir, slug);
+  assertInsideWorkspace(workspaceRoot, projectPath);
+  await ensureProjectDirectories(projectPath);
+
+  const now = new Date().toISOString();
+  const state: AgentState = {
+    projectId: randomUUID(),
+    projectPath,
+    initialPrompt: input.prompt,
+    language: input.language || 'zh-CN',
+    targetChapters,
+    currentStep: 'novel_metadata',
+    currentChapter: 1,
+    completedSteps: [],
+    files: {},
+    createdAt: now,
+    updatedAt: now,
+  };
+  await saveState(state);
+  return { state };
+}
+
+export async function loadState(projectPath: string): Promise<AgentState> {
+  const raw = await readFile(join(projectPath, 'agent-state.json'), 'utf8');
+  return JSON.parse(raw) as AgentState;
+}
+
+export async function saveState(state: AgentState): Promise<void> {
+  const nextState = { ...state, updatedAt: new Date().toISOString() };
+  await writeFile(
+    join(state.projectPath, 'agent-state.json'),
+    `${JSON.stringify(nextState, null, 2)}\n`,
+    'utf8'
+  );
+}
+
+export async function saveJsonFile(projectPath: string, relativePath: string, value: unknown): Promise<string> {
+  const fullPath = join(projectPath, relativePath);
+  await mkdir(dirname(fullPath), { recursive: true });
+  await writeFile(fullPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  return fullPath;
+}
+
+export async function saveMarkdownFile(projectPath: string, relativePath: string, value: string): Promise<string> {
+  const fullPath = join(projectPath, relativePath);
+  await mkdir(dirname(fullPath), { recursive: true });
+  await writeFile(fullPath, value.endsWith('\n') ? value : `${value}\n`, 'utf8');
+  return fullPath;
+}
+
+export async function saveRecoveryFile(projectPath: string, step: string, content: string): Promise<string> {
+  const safeStep = step.replace(/[^a-z0-9_-]+/gi, '-').toLowerCase();
+  const fileName = `.agent-recovery/failed-${safeStep}-${Date.now()}.txt`;
+  return saveMarkdownFile(projectPath, fileName, content);
+}