novelforge-agent 0.1.1 → 0.3.0

package/dist/src/mcp/tools.js

@@ -1,6 +1,28 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { buildContext, chapterFileName, createProject, getNextStep, getProjectStatus, listProjects, requestSideTrack, retrieve, saveMarkdownFile, submitStepResult, } from '../core/index.js';
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { amendStoryBible, assertProjectPath, buildContext, createProject, deleteChapter, forkProject, getNextStep, getProjectStatus, listProjects, listStoryBibleVersions, loadState, loadThreads, redoStep, requestSideTrack, retrieve, submitStepResult, updateThread, } from '../core/index.js';
+function packageVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        try {
+            const raw = readFileSync(join(dir, 'package.json'), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.version === 'string' && parsed.version)
+                return parsed.version;
+        }
+        catch {
+            // keep walking upward until the package root is found
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return '0.0.0';
+        dir = parent;
+    }
+}
+const MCP_SERVER_VERSION = packageVersion();
 function textResult(value) {
     return {
         content: [{
@@ -10,36 +32,48 @@ function textResult(value) {
     };
 }
 export function createNovelAgentServer(options) {
+    function checkedProjectPath(projectPath) {
+        assertProjectPath(options.workspaceRoot, projectPath);
+        return projectPath;
+    }
+    function checkedOutputDir(outputDir) {
+        assertProjectPath(options.workspaceRoot, resolve(options.workspaceRoot, outputDir));
+        return outputDir;
+    }
     const server = new McpServer({
         name: 'novelforge-agent',
-        version: '0.1.0',
+        version: MCP_SERVER_VERSION,
     });
     server.tool('start_novel_project', 'Create a local novel project and return the first generation instruction.', {
         prompt: z.string().min(1),
         language: z.enum(['zh-CN', 'en-US']).default('zh-CN'),
         outputDir: z.string().default('novels'),
-        targetChapters: z.number().int().positive().default(3),
-    }, async ({ prompt, language, outputDir, targetChapters }) => {
+        targetChapters: z.number().int().positive().default(5),
+        plannedTotalChapters: z.number().int().positive().default(12),
+    }, async ({ prompt, language, outputDir, targetChapters, plannedTotalChapters }) => {
         const result = await createProject({
             workspaceRoot: options.workspaceRoot,
             prompt,
             language,
             outputDir,
             targetChapters,
+            plannedTotalChapters,
         });
         return textResult({ state: result.state, next: await getNextStep(result.state.projectPath) });
     });
     server.tool('list_projects', 'List all NovelForge projects under the workspace, sorted by most recently updated. Use this to find an existing projectPath instead of asking the user.', {
         outputDir: z.string().default('novels'),
-    }, async ({ outputDir }) => textResult(await listProjects({ workspaceRoot: options.workspaceRoot, outputDir })));
-    server.tool('get_project_status', 'Return a compact, one-screen summary of a project: current step, chapters written, open threads, latest review verdict, completion state.', { projectPath: z.string().min(1) }, async ({ projectPath }) => textResult(await getProjectStatus(projectPath)));
-    server.tool('get_next_step', 'Return the next required generation step for a novel project.', { projectPath: z.string().min(1) }, async ({ projectPath }) => textResult(await getNextStep(projectPath)));
+    }, async ({ outputDir }) => textResult(await listProjects({ workspaceRoot: options.workspaceRoot, outputDir: checkedOutputDir(outputDir) })));
+    server.tool('get_project_status', 'Return a compact, one-screen summary of a project: current step, chapters written, open threads, latest review verdict, completion state.', { projectPath: z.string().min(1) }, async ({ projectPath }) => textResult(await getProjectStatus(checkedProjectPath(projectPath))));
+    server.tool('get_next_step', 'Return the next required generation step for a novel project.', { projectPath: z.string().min(1) }, async ({ projectPath }) => textResult(await getNextStep(checkedProjectPath(projectPath))));
     server.tool('submit_step_result', 'Submit host-generated content for validation, saving, and workflow advancement.', {
         projectPath: z.string().min(1),
         step: z.enum([
             'novel_metadata',
             'story_bible',
+            'style_guide',
             'architecture',
+            'architecture_extension',
             'chapter',
             'memory_card',
             'continuity_review',
@@ -49,11 +83,13 @@ export function createNovelAgentServer(options) {
             'complete',
         ]),
         content: z.string(),
-    }, async ({ projectPath, step, content }) => textResult(await submitStepResult({ projectPath, step, content })));
+    }, async ({ projectPath, step, content }) => textResult(await submitStepResult({ projectPath: checkedProjectPath(projectPath), step, content })));
     server.tool('get_context', 'Build purpose-specific context for generation, memory extraction, review, or revision.', {
         projectPath: z.string().min(1),
         purpose: z.enum([
             'chapter_generation',
+            'style_guide',
+            'architecture_extension',
             'memory_extraction',
             'continuity_review',
             'revision',
@@ -64,44 +100,51 @@ export function createNovelAgentServer(options) {
         start: z.number().int().positive().optional(),
         end: z.number().int().positive().optional(),
     }, async ({ projectPath, purpose, chapterNumber, start, end }) => textResult(await buildContext({
-        projectPath,
+        projectPath: checkedProjectPath(projectPath),
         purpose,
         chapterNumber,
         range: start && end ? { start, end } : undefined,
     })));
-    server.tool('save_chapter', 'Save a generated chapter directly as Markdown.', {
+    server.tool('save_chapter', 'Submit a generated chapter Markdown draft through the workflow state machine. This requires currentStep="chapter" and advances to chapter_review.', {
         projectPath: z.string().min(1),
         chapterNumber: z.number().int().positive(),
         title: z.string().min(1),
         content: z.string().min(1),
     }, async ({ projectPath, chapterNumber, title, content }) => {
-        const fileName = `chapters/${chapterFileName(chapterNumber)}`;
-        const savedPath = await saveMarkdownFile(projectPath, fileName, `# ${title}\n\n${content}`);
-        return textResult({ savedPath, suggestedNextStep: 'memory_card' });
+        const checked = checkedProjectPath(projectPath);
+        const state = await loadState(checked);
+        if (state.currentStep !== 'chapter' || state.currentChapter !== chapterNumber) {
+            throw new Error(`save_chapter requires currentStep="chapter" and currentChapter=${chapterNumber}; got currentStep="${state.currentStep}", currentChapter=${state.currentChapter}`);
+        }
+        return textResult(await submitStepResult({
+            projectPath: checked,
+            step: 'chapter',
+            content: `# ${title}\n\n${content}`,
+        }));
     });
     server.tool('generate_chapter', 'Build the chapter-generation context and instruction for a specific chapter without changing workflow state.', {
         projectPath: z.string().min(1),
         chapterNumber: z.number().int().positive(),
     }, async ({ projectPath, chapterNumber }) => textResult({
-        context: await buildContext({ projectPath, purpose: 'chapter_generation', chapterNumber }),
-        hint: 'Persist the result via save_chapter or submit_step_result(step="chapter") when the workflow currentStep is "chapter".',
+        context: await buildContext({ projectPath: checkedProjectPath(projectPath), purpose: 'chapter_generation', chapterNumber }),
+        hint: 'Persist the result via submit_step_result(step="chapter") when the workflow currentStep is "chapter"; the workflow then requires chapter_review before memory_card.',
     }));
     server.tool('extract_memory_card', 'Build the memory-extraction context for a specific chapter without changing workflow state.', {
         projectPath: z.string().min(1),
         chapterNumber: z.number().int().positive(),
     }, async ({ projectPath, chapterNumber }) => textResult({
-        context: await buildContext({ projectPath, purpose: 'memory_extraction', chapterNumber }),
+        context: await buildContext({ projectPath: checkedProjectPath(projectPath), purpose: 'memory_extraction', chapterNumber }),
         hint: 'Submit the extracted memory card via submit_step_result with step="memory_card" when the workflow currentStep matches.',
     }));
     server.tool('review_chapter', 'Ask the host to review a specific chapter. Switches the workflow into chapter_review side-track and returns the review prompt + packed context. Resume original step after submit_step_result(step="chapter_review").', {
         projectPath: z.string().min(1),
         chapterNumber: z.number().int().positive(),
-    }, async ({ projectPath, chapterNumber }) => textResult(await requestSideTrack({ projectPath, step: 'chapter_review', chapterNumber })));
+    }, async ({ projectPath, chapterNumber }) => textResult(await requestSideTrack({ projectPath: checkedProjectPath(projectPath), step: 'chapter_review', chapterNumber })));
     server.tool('revise_chapter', 'Ask the host to rewrite a specific chapter based on prior review feedback and optional extra instructions. Previous version is archived under chapters/.versions/.', {
         projectPath: z.string().min(1),
         chapterNumber: z.number().int().positive(),
         feedback: z.string().optional(),
-    }, async ({ projectPath, chapterNumber, feedback }) => textResult(await requestSideTrack({ projectPath, step: 'chapter_revision', chapterNumber, feedback })));
+    }, async ({ projectPath, chapterNumber, feedback }) => textResult(await requestSideTrack({ projectPath: checkedProjectPath(projectPath), step: 'chapter_revision', chapterNumber, feedback })));
     server.tool('retrieve', 'Lexical BM25-style retrieval over indexed chapter paragraphs, story-bible sections, and memory cards. Returns ranked snippets with chapter attribution.', {
         projectPath: z.string().min(1),
         query: z.string().min(1),
@@ -111,7 +154,7 @@ export function createNovelAgentServer(options) {
         chapterEnd: z.number().int().positive().optional(),
     }, async ({ projectPath, query, topK, types, chapterStart, chapterEnd }) => {
         const chapterRange = chapterStart && chapterEnd ? { start: chapterStart, end: chapterEnd } : undefined;
-        const hits = await retrieve(projectPath, query, { topK, types, chapterRange });
+        const hits = await retrieve(checkedProjectPath(projectPath), query, { topK, types, chapterRange });
         return textResult({ query, hits });
     });
     server.tool('cross_chapter_review', 'Ask the host to review a chapter range for cross-chapter continuity conflicts. Defaults to all generated chapters.', {
@@ -120,7 +163,172 @@ export function createNovelAgentServer(options) {
         end: z.number().int().positive().optional(),
     }, async ({ projectPath, start, end }) => {
         const range = start && end ? { start, end } : undefined;
-        return textResult(await requestSideTrack({ projectPath, step: 'cross_chapter_review', range }));
+        return textResult(await requestSideTrack({ projectPath: checkedProjectPath(projectPath), step: 'cross_chapter_review', range }));
+    });
+    // ----- v0.2 tools -----
+    server.tool('amend_story_bible', 'Replace the story bible with a revised version. Old version is auto-archived under story-bible-versions/ and the lexical index is rebuilt for the new content.', {
+        projectPath: z.string().min(1),
+        content: z.string().min(1),
+        reason: z.string().optional(),
+    }, async ({ projectPath, content, reason }) => textResult(await amendStoryBible({ projectPath: checkedProjectPath(projectPath), content, reason })));
+    server.tool('list_bible_versions', 'List archived story-bible versions for a project (filenames sorted oldest first).', { projectPath: z.string().min(1) }, async ({ projectPath }) => textResult({ versions: await listStoryBibleVersions(checkedProjectPath(projectPath)) }));
+    server.tool('list_threads', 'List foreshadow threads for a project, optionally filtered by status. Threads are aggregated from memory_card.threadActions.', {
+        projectPath: z.string().min(1),
+        status: z.enum(['planted', 'building', 'paid', 'dropped']).optional(),
+    }, async ({ projectPath, status }) => {
+        const all = await loadThreads(checkedProjectPath(projectPath));
+        const filtered = status ? all.filter((t) => t.status === status) : all;
+        return textResult({ threads: filtered });
     });
+    server.tool('update_thread', 'Update a single foreshadow thread (override status, plannedPayoffAt, paidOffAt, droppedAt, description, notes).', {
+        projectPath: z.string().min(1),
+        id: z.string().min(1),
+        status: z.enum(['planted', 'building', 'paid', 'dropped']).optional(),
+        plannedPayoffAt: z.number().int().positive().nullable().optional(),
+        paidOffAt: z.number().int().positive().nullable().optional(),
+        droppedAt: z.number().int().positive().nullable().optional(),
+        description: z.string().min(1).optional(),
+        notes: z.string().nullable().optional(),
+    }, async ({ projectPath, id, ...patch }) => textResult(await updateThread(checkedProjectPath(projectPath), id, patch)));
+    server.tool('fork_project', 'Copy an existing project to a new sibling directory with a new projectId. Use to try alternate plot branches without losing the original.', {
+        sourceProjectPath: z.string().min(1),
+        label: z.string().optional(),
+    }, async ({ sourceProjectPath, label }) => textResult(await forkProject({ sourceProjectPath: checkedProjectPath(sourceProjectPath), label })));
+    server.tool('delete_chapter', 'Delete a chapter, its memory card, its single-chapter review, and all archived versions. Removes the chapter from the lexical index and rewinds the workflow if needed.', {
+        projectPath: z.string().min(1),
+        chapterNumber: z.number().int().positive(),
+    }, async ({ projectPath, chapterNumber }) => textResult(await deleteChapter({ projectPath: checkedProjectPath(projectPath), chapterNumber })));
+    server.tool('redo_step', 'Roll the workflow back to a specific step. Files produced by that step (and dependent chapter content for chapter/memory_card steps) are removed; the host must regenerate.', {
+        projectPath: z.string().min(1),
+        step: z.enum([
+            'novel_metadata',
+            'story_bible',
+            'style_guide',
+            'architecture',
+            'chapter',
+            'memory_card',
+            'continuity_review',
+        ]),
+        chapterNumber: z.number().int().positive().optional(),
+    }, async ({ projectPath, step, chapterNumber }) => textResult(await redoStep({ projectPath: checkedProjectPath(projectPath), step, chapterNumber })));
+    // ===== MCP Prompts (slash commands) =====
+    server.prompt('nf-start', 'Start a brand new novel project under the configured workspace.', {
+        prompt: z.string().describe('User idea / premise / genre, in any language.'),
+        chapters: z.string().optional().describe('Planning batch size as a string. Defaults to 5.'),
+        totalChapters: z.string().optional().describe('Whole-book target chapter count as a string. Defaults to 12.'),
+    }, ({ prompt, chapters, totalChapters }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Use the novelforge MCP server. Call start_novel_project with prompt="${prompt}", targetChapters=${chapters ?? '5'}, plannedTotalChapters=${totalChapters ?? '12'}, then enter the autonomous loop: read next.instruction, generate the requested content, call submit_step_result, repeat until currentStep is "complete". Show me the projectPath after start_novel_project returns.`,
+                },
+            }],
+    }));
+    server.prompt('nf-next', 'Continue the current novelforge workflow by one step.', {
+        projectPath: z.string().describe('Absolute path to the project.'),
+    }, ({ projectPath }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Use the novelforge MCP server. Call get_next_step with projectPath="${projectPath}". Read the returned instruction + context and produce the requested artifact, then call submit_step_result. Show me what step was advanced.`,
+                },
+            }],
+    }));
+    server.prompt('nf-list', 'List all novelforge projects in the workspace.', {}, () => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: 'Use the novelforge MCP server: call list_projects with no arguments. Show me the result in a compact table (title, currentStep, chaptersWritten/plannedTotalChapters, updatedAt, projectPath).',
+                },
+            }],
+    }));
+    server.prompt('nf-status', 'Show a one-screen status for a novelforge project.', {
+        projectPath: z.string(),
+    }, ({ projectPath }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Use the novelforge MCP server: call get_project_status with projectPath="${projectPath}". Summarize: title, current step, chapters written, open threads count, latest review verdict.`,
+                },
+            }],
+    }));
+    server.prompt('nf-review-chapter', 'Run a single-chapter editorial review.', {
+        projectPath: z.string(),
+        chapterNumber: z.string(),
+    }, ({ projectPath, chapterNumber }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Use the novelforge MCP server: call review_chapter with projectPath="${projectPath}", chapterNumber=${chapterNumber}. Read the returned instruction + context, produce the JSON chapter review, then call submit_step_result with step="chapter_review". Summarize the findings for me.`,
+                },
+            }],
+    }));
+    server.prompt('nf-revise-chapter', 'Revise a chapter based on review feedback or new instructions.', {
+        projectPath: z.string(),
+        chapterNumber: z.string(),
+        feedback: z.string().optional(),
+    }, ({ projectPath, chapterNumber, feedback }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Use the novelforge MCP server: call revise_chapter with projectPath="${projectPath}", chapterNumber=${chapterNumber}${feedback ? `, feedback=${JSON.stringify(feedback)}` : ''}. Read the returned instruction + context, produce the revised Markdown chapter, then call submit_step_result with step="chapter_revision". Confirm the previous version was archived.`,
+                },
+            }],
+    }));
+    server.prompt('nf-cross-review', 'Cross-chapter continuity review over a range.', {
+        projectPath: z.string(),
+        start: z.string().optional(),
+        end: z.string().optional(),
+    }, ({ projectPath, start, end }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Use the novelforge MCP server: call cross_chapter_review with projectPath="${projectPath}"${start && end ? `, start=${start}, end=${end}` : ''}. Read the returned instruction + context, produce the JSON cross-chapter review, then call submit_step_result with step="cross_chapter_review". Summarize verdict and any issues.`,
+                },
+            }],
+    }));
+    server.prompt('nf-retrieve', 'Lexical retrieval over a project (BM25-style).', {
+        projectPath: z.string(),
+        query: z.string(),
+    }, ({ projectPath, query }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Use the novelforge MCP server: call retrieve with projectPath="${projectPath}", query=${JSON.stringify(query)}, topK=8. List the hits with chapter attribution and short excerpts.`,
+                },
+            }],
+    }));
+    server.prompt('nf-amend-bible', 'Amend the story bible with new content (previous version auto-archived).', {
+        projectPath: z.string(),
+        reason: z.string().optional(),
+    }, ({ projectPath, reason }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Use the novelforge MCP server. First call get_project_status with projectPath="${projectPath}" to confirm the project exists, then read the current story-bible.md (you may use the host's filesystem tools). Apply the following amendment intent and produce a complete revised story bible Markdown:\n\n${reason ?? '(no specific reason supplied — ask the user what to change)'}\n\nThen call amend_story_bible with projectPath="${projectPath}" and the new content. Confirm the archived version path.`,
+                },
+            }],
+    }));
+    server.prompt('nf-threads', 'Show active foreshadow threads for a project.', {
+        projectPath: z.string(),
+        status: z.enum(['planted', 'building', 'paid', 'dropped']).optional(),
+    }, ({ projectPath, status }) => ({
+        messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Use the novelforge MCP server: call list_threads with projectPath="${projectPath}"${status ? `, status="${status}"` : ''}. Show me the threads as a compact list: id, status, plantedAt, plannedPayoffAt (if set), description.`,
+                },
+            }],
+    }));
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novelforge-agent",
-  "version": "0.1.1",
+  "version": "0.3.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",
@@ -43,6 +43,10 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --test dist/test/*.test.js",
+    "test:e2e": "npm run build && bash scripts/e2e.sh",
+    "inspect": "npm run build && npx -y @modelcontextprotocol/inspector node dist/src/mcp/server.js",
+    "inspect:tools": "npm run build && npx -y @modelcontextprotocol/inspector --cli node dist/src/mcp/server.js --method tools/list",
+    "inspect:prompts": "npm run build && npx -y @modelcontextprotocol/inspector --cli node dist/src/mcp/server.js --method prompts/list",
     "dev:mcp": "tsx src/mcp/server.ts",
     "dev:cli": "tsx src/cli/index.ts",
     "prepublishOnly": "npm run build && npm test",

package/src/cli/index.ts

@@ -1,14 +1,20 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
 import {
+  amendStoryBible,
   buildContext,
   createProject,
+  deleteChapter,
+  forkProject,
   getNextStep,
   getProjectStatus,
   listProjects,
+  loadThreads,
+  redoStep,
   requestSideTrack,
   retrieve,
   submitStepResult,
+  updateThread,
 } from '../core/index.js';
 import { formatInstallResult, runInstall, InstallHost } from './install.js';
 
@@ -48,9 +54,17 @@ export async function runCli(argv = process.argv.slice(2), cwd = process.cwd()):
     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 chapters = Number(valueAfter(argv, '--chapters') || 5);
+    const totalChapters = Number(valueAfter(argv, '--total-chapters') || 12);
     const outputDir = valueAfter(argv, '--output') || 'novels';
-    const result = await createProject({ workspaceRoot: cwd, prompt, language, outputDir, targetChapters: chapters });
+    const result = await createProject({
+      workspaceRoot: cwd,
+      prompt,
+      language,
+      outputDir,
+      targetChapters: chapters,
+      plannedTotalChapters: totalChapters,
+    });
     const next = await getNextStep(result.state.projectPath);
     console.log(JSON.stringify({ state: result.state, next }, null, 2));
     return;
@@ -156,7 +170,74 @@ export async function runCli(argv = process.argv.slice(2), cwd = process.cwd()):
     return;
   }
 
-  throw new Error('Usage: novelforge-agent install|start|list|status|next|submit|context|review|revise|cross-review|retrieve');
+  if (command === 'amend-bible') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const file = valueAfter(argv, '--file');
+    const reason = valueAfter(argv, '--reason');
+    if (!file) throw new Error('Missing --file with new bible Markdown');
+    const content = await readFile(file, 'utf8');
+    console.log(JSON.stringify(await amendStoryBible({ projectPath, content, reason }), null, 2));
+    return;
+  }
+
+  if (command === 'threads') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const status = valueAfter(argv, '--status') as 'planted' | 'building' | 'paid' | 'dropped' | undefined;
+    const all = await loadThreads(projectPath);
+    const filtered = status ? all.filter((t) => t.status === status) : all;
+    console.log(JSON.stringify(filtered, null, 2));
+    return;
+  }
+
+  if (command === 'update-thread') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const id = valueAfter(argv, '--id');
+    if (!id) throw new Error('Missing --id');
+    const status = valueAfter(argv, '--status') as 'planted' | 'building' | 'paid' | 'dropped' | undefined;
+    const plannedPayoffAt = valueAfter(argv, '--planned-payoff');
+    const description = valueAfter(argv, '--description');
+    const notes = valueAfter(argv, '--notes');
+    const updated = await updateThread(projectPath, id, {
+      status,
+      plannedPayoffAt: plannedPayoffAt ? Number(plannedPayoffAt) : undefined,
+      description,
+      notes,
+    });
+    console.log(JSON.stringify(updated, null, 2));
+    return;
+  }
+
+  if (command === 'fork') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const label = valueAfter(argv, '--label');
+    console.log(JSON.stringify(await forkProject({ sourceProjectPath: projectPath, label }), null, 2));
+    return;
+  }
+
+  if (command === 'delete-chapter') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const chapter = valueAfter(argv, '--chapter');
+    if (!chapter) throw new Error('Missing --chapter');
+    console.log(JSON.stringify(await deleteChapter({ projectPath, chapterNumber: Number(chapter) }), null, 2));
+    return;
+  }
+
+  if (command === 'redo') {
+    if (!projectPath) throw new Error('Missing projectPath');
+    const step = valueAfter(argv, '--step') as
+      | 'novel_metadata' | 'story_bible' | 'style_guide' | 'architecture' | 'chapter' | 'memory_card' | 'continuity_review'
+      | undefined;
+    if (!step) throw new Error('Missing --step');
+    const chapter = valueAfter(argv, '--chapter');
+    console.log(JSON.stringify(await redoStep({
+      projectPath,
+      step,
+      chapterNumber: chapter ? Number(chapter) : undefined,
+    }), null, 2));
+    return;
+  }
+
+  throw new Error('Usage: novelforge-agent install|start|list|status|next|submit|context|review|revise|cross-review|retrieve|amend-bible|threads|update-thread|fork|delete-chapter|redo');
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {

package/src/core/bibleStore.ts

@@ -0,0 +1,57 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  archiveStoryBible,
+  loadState,
+  saveMarkdownFile,
+  saveState,
+} from './projectStore.js';
+import { storyBibleVersionFileName } from './fileNames.js';
+import { indexStoryBible } from './retrieval/index.js';
+
+export interface AmendStoryBibleInput {
+  projectPath: string;
+  content: string;
+  reason?: string;
+}
+
+export interface AmendStoryBibleResult {
+  archivedPath?: string;
+  bibleVersion: number;
+  savedPath: string;
+}
+
+function isEmpty(content: string): boolean {
+  return !content || !content.trim();
+}
+
+export async function amendStoryBible(input: AmendStoryBibleInput): Promise<AmendStoryBibleResult> {
+  if (isEmpty(input.content)) throw new Error('Amended story bible content is empty');
+  const state = await loadState(input.projectPath);
+  // Archive current
+  const archived = await archiveStoryBible(
+    state.projectPath,
+    join('story-bible-versions', storyBibleVersionFileName(new Date().toISOString()))
+  );
+  // Save new
+  const savedPath = await saveMarkdownFile(state.projectPath, 'story-bible.md', input.content);
+  // Re-index
+  await indexStoryBible(state.projectPath, input.content);
+  // Track in state
+  const bibleVersion = (state.completedSteps.filter((s) => s === 'story_bible_amend').length ?? 0) + 1;
+  await saveState({
+    ...state,
+    completedSteps: [...state.completedSteps, 'story_bible_amend' as const],
+    files: { ...state.files, storyBible: 'story-bible.md' },
+  });
+  return { archivedPath: archived, bibleVersion, savedPath };
+}
+
+export async function listStoryBibleVersions(projectPath: string): Promise<string[]> {
+  try {
+    const items = await readdir(join(projectPath, 'story-bible-versions'));
+    return items.filter((f) => f.endsWith('.md')).sort();
+  } catch {
+    return [];
+  }
+}

package/src/core/characterStore.ts

@@ -0,0 +1,93 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CharacterState, CharacterStateUpdate, CoreCastMember } from './types.js';
+
+const CHARACTERS_FILE = 'characters.json';
+
+export interface CharactersBundle {
+  characters: CharacterState[];
+}
+
+function emptyState(member: CoreCastMember, chapterNumber = 0): CharacterState {
+  return {
+    name: member.name,
+    role: member.role,
+    goal: '未确认',
+    belief: '未确认',
+    relationships: [],
+    abilities: [],
+    secrets: [],
+    emotionalState: member.description,
+    lastUpdatedAt: chapterNumber,
+  };
+}
+
+export async function loadCharacterStates(projectPath: string): Promise<CharacterState[]> {
+  try {
+    const raw = await readFile(join(projectPath, CHARACTERS_FILE), 'utf8');
+    const parsed = JSON.parse(raw) as CharactersBundle;
+    return Array.isArray(parsed.characters) ? parsed.characters : [];
+  } catch {
+    return [];
+  }
+}
+
+export async function saveCharacterStates(projectPath: string, characters: CharacterState[]): Promise<string> {
+  const fullPath = join(projectPath, CHARACTERS_FILE);
+  await writeFile(fullPath, `${JSON.stringify({ characters }, null, 2)}\n`, 'utf8');
+  return fullPath;
+}
+
+export async function initializeCharacterStates(
+  projectPath: string,
+  coreCast: CoreCastMember[]
+): Promise<string> {
+  const existing = await loadCharacterStates(projectPath);
+  const byName = new Map(existing.map((c) => [c.name, c]));
+  for (const member of coreCast) {
+    if (!byName.has(member.name)) {
+      byName.set(member.name, emptyState(member));
+    }
+  }
+  return saveCharacterStates(projectPath, Array.from(byName.values()));
+}
+
+export async function applyCharacterUpdates(
+  projectPath: string,
+  chapterNumber: number,
+  updates: CharacterStateUpdate[] | undefined
+): Promise<CharacterState[]> {
+  const existing = await loadCharacterStates(projectPath);
+  if (!updates || !updates.length) return existing;
+
+  const byName = new Map(existing.map((c) => [c.name, { ...c }]));
+  for (const update of updates) {
+    const current = byName.get(update.name) ?? {
+      name: update.name,
+      role: update.role,
+      goal: '未确认',
+      belief: '未确认',
+      relationships: [],
+      abilities: [],
+      secrets: [],
+      emotionalState: '未确认',
+      lastUpdatedAt: chapterNumber,
+    };
+
+    byName.set(update.name, {
+      ...current,
+      role: update.role ?? current.role,
+      goal: update.goal ?? current.goal,
+      belief: update.belief ?? current.belief,
+      relationships: update.relationships ?? current.relationships,
+      abilities: update.abilities ?? current.abilities,
+      secrets: update.secrets ?? current.secrets,
+      emotionalState: update.emotionalState ?? current.emotionalState,
+      lastUpdatedAt: chapterNumber,
+    });
+  }
+
+  const next = Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+  await saveCharacterStates(projectPath, next);
+  return next;
+}