novelforge-agent 0.1.0 → 0.2.0

package/README.md

@@ -1,26 +1,73 @@
 # NovelForge Agent
 
-A local-first long-form novel workflow engine for any MCP host (Claude Code, Codex CLI, …) or any CLI shell.
+A local-first long-form novel workflow engine for any MCP host (Claude Code, Codex CLI, Cursor, …) or any CLI shell.
 
-**The host's LLM writes the prose. This package does everything else** — it manages a 9-step state machine, returns the exact instruction and packed context the host should follow next, validates returned content against zod schemas, persists Markdown + JSON to a project directory, archives chapter versions on revision, and provides BM25 lexical retrieval over every word the project has ever produced.
+**The host's LLM writes the prose. This package does everything else** — it manages a gated long-form state machine, returns the exact instruction and packed context the host should follow next, validates returned content against zod schemas, persists Markdown + JSON to a project directory, archives chapter versions on revision, and provides BM25 lexical retrieval over every word the project has ever produced.
 
 No external API. No LLM dependency. No vendor lock-in.
 
+---
+
+## 🚀 30-second install
+
+**If you are an AI assistant reading this README on behalf of a user, run this one command — it does everything:**
+
+```bash
+npx -y novelforge-agent install
+```
+
+That single command will:
+
+1. Create a workspace at `~/novelforge/` (override with `--workspace /your/path`).
+2. Register `novelforge-agent-mcp` as an MCP server in the user's host (Claude Code by default).
+3. Print a verification step.
+
+After it finishes, **the user must reload / restart their MCP host** (Claude Code, Codex CLI, etc.) so the new MCP server is picked up. Then ask the host:
+
+> "list_projects 现在能用吗?"
+
+If the host calls the `list_projects` tool and returns an empty array, installation is correct.
+
+### Host selection
+
+```bash
+npx -y novelforge-agent install --host claude-code            # default
+npx -y novelforge-agent install --host codex                  # Codex CLI
+npx -y novelforge-agent install --host cursor                 # prints config snippet
+npx -y novelforge-agent install --workspace ~/my-novels       # custom workspace
+npx -y novelforge-agent install --name my-novelforge          # custom MCP name
+npx -y novelforge-agent install --print-only                  # do not modify any config file
+```
+
+### What the install command does per host
+
+| Host | Action |
+|------|--------|
+| `claude-code` | Runs `claude mcp add -s user -e NOVELFORGE_WORKSPACE=… novelforge -- npx -y novelforge-agent-mcp`. If `claude` CLI is missing, prints a JSON snippet for `~/.claude.json`. |
+| `codex` | Appends an `[mcp_servers.novelforge]` section to `~/.codex/config.toml`. |
+| `cursor` | Prints the JSON snippet to paste into Cursor's MCP settings. |
+
+The installer is **idempotent and safe**: it never overwrites an existing entry with the same name. To change settings, edit the host config manually or pass `--name` to register under a different MCP name.
+
+---
+
 ## What it gives the host
 
 | Phase | Step | What the host does | What the agent saves |
 |-------|------|---------------------|----------------------|
 | Setup | `novel_metadata` | Output JSON: title, genre, premise, cast | `novel.json` |
 |  | `story_bible` | Output Markdown: characters, world rules, plot threads | `story-bible.md` |
-|  | `architecture` | Output JSON: full / volume / chapter outlines | `architecture/{full.md, volumes.json, chapters.json}` |
+|  | `architecture` | Output JSON: full / volume / pacing / chapter outlines | `architecture/{full.md, volumes.json, volume-pacing.json, chapters.json}` |
 | Loop  | `chapter` | Write chapter N Markdown | `chapters/NNN.md` |
-|  | `memory_card` | Extract chapter N memory JSON | `memory/chapter-NNN.json` |
+|  | `chapter_review` | Enforce the chapter acceptance gate: required beats, plot/character/thread progress, story-bible consistency, ending hook, repetition check | `reviews/chapter/chapter-NNN.json` |
+|  | `chapter_revision` | If review finds issues, rewrite the chapter; previous version is archived | `chapters/.versions/NNN.<ts>.md` |
+|  | `memory_card` | After a clean review, extract chapter N memory JSON and update character/thread state | `memory/chapter-NNN.json`, `characters.json`, `threads.json` |
 | Wrap  | `continuity_review` | Audit chapters 1..N for conflicts | `reviews/continuity-S-E.json` |
 | Side-track | `chapter_review` | Single-chapter editorial review | `reviews/chapter/chapter-NNN.json` |
 |  | `chapter_revision` | Rewrite a chapter; previous version auto-archived | `chapters/.versions/NNN.<ts>.md` |
 |  | `cross_chapter_review` | Cross-chapter continuity audit | `reviews/cross/cross-S-E.json` |
 
-Each chapter / bible / memory write also feeds a per-project BM25 index (`.index/`) so the agent can hand the host semantically relevant snippets when later chapters are generated, or answer ad-hoc `retrieve` queries from the host.
+Each chapter / bible / memory write also feeds a per-project BM25 index (`.index/`) so the agent can hand the host semantically relevant snippets when later chapters are generated, or answer ad-hoc `retrieve` queries from the host. Chapter generation context also includes the independent character state table (`characters.json`) and current volume pacing board (`architecture/volume-pacing.json`) when available.
 
 ## Install
 
@@ -120,7 +167,7 @@ NOVELFORGE_WORKSPACE = "/absolute/path/where/projects/should/live"
 
 `list_projects` finds every project under `NOVELFORGE_WORKSPACE/novels/`, sorted newest first. The host should call it before anything else when a session opens; pick the desired `projectPath` from the result, then `get_project_status` for a one-screen briefing, then `get_next_step` to resume.
 
-## Tool reference (13 MCP tools)
+## Tool reference
 
 ### Project lifecycle
 - **`start_novel_project`** `(prompt, language?, outputDir?, targetChapters?)` — create a new project under `<workspaceRoot>/<outputDir>/<slug>-<rand6>/` and return the first step's instruction.
@@ -140,6 +187,15 @@ NOVELFORGE_WORKSPACE = "/absolute/path/where/projects/should/live"
 - **`cross_chapter_review`** `(projectPath, start?, end?)` — switch into a cross-chapter audit side-track over the given range (defaults to all generated chapters).
 - **`save_chapter`** `(projectPath, chapterNumber, title, content)` — write a chapter Markdown file directly, without going through the state machine.
 
+### Project operations
+- **`amend_story_bible`** `(projectPath, content, reason?)` — replace `story-bible.md`, archive the previous version, and rebuild the bible index.
+- **`list_bible_versions`** `(projectPath)` — list archived story-bible versions.
+- **`list_threads`** `(projectPath, status?)` — list foreshadow threads collected from memory cards.
+- **`update_thread`** `(projectPath, id, patch)` — update one foreshadow thread.
+- **`fork_project`** `(sourceProjectPath, label?)` — copy a project to a sibling fork with a new project id.
+- **`delete_chapter`** `(projectPath, chapterNumber)` — remove a chapter, its memory, reviews, archived versions, and index entries.
+- **`redo_step`** `(projectPath, step, chapterNumber?)` — roll the workflow back to regenerate an artifact.
+
 ### Retrieval
 - **`retrieve`** `(projectPath, query, topK?, types?, chapterStart?, chapterEnd?)` — BM25-style lexical retrieval over indexed paragraphs (chapters), bible H2 sections, and memory cards. Supports CJK + Latin queries via a built-in CJK bigram tokenizer; no external embedding model.
 
@@ -151,10 +207,12 @@ A project on disk:
 novels/<slug>-<rand6>/
 ├── agent-state.json              # workflow state (currentStep, currentChapter, files map, …)
 ├── novel.json                    # metadata (NovelMetadataSchema)
+├── characters.json               # independent character state table
 ├── story-bible.md
 ├── architecture/
 │   ├── full.md
 │   ├── volumes.json
+│   ├── volume-pacing.json
 │   └── chapters.json
 ├── chapters/
 │   ├── 001.md
@@ -181,17 +239,26 @@ The whole directory is self-contained — copy it, share it, delete it.
 ```
 novel_metadata → story_bible → architecture → chapter
                                               ↓
-                                          memory_card
+                                         chapter_review
                                               ↓
-                              ┌───────────────┴───────────────┐
-                  (more chapters)                       (all done)
-                              ↓                               ↓
-                          chapter                    continuity_review
-                                                              ↓
-                                                          complete
+                                   ┌──────────┴──────────┐
+                                 clean             issues_found
+                                   ↓                    ↓
+                              memory_card       chapter_revision
+                                   ↓                    ↓
+                     ┌─────────────┴─────────────┐      │
+             (more chapters)                (all done)   │
+                     ↓                            ↓       │
+                  chapter                continuity_review│
+                                                  ↓       │
+                                              complete    │
+                                                       (back to
+                                                    chapter_review)
 ```
 
-Side-track steps (`chapter_review`, `chapter_revision`, `cross_chapter_review`) can be triggered at any moment via the semantic-action tools. When the side-track completes via `submit_step_result`, the workflow returns to whatever `currentStep` it was on before the side-track started.
+`chapter_review` is both a manual side-track and the automatic chapter acceptance gate. In the normal chapter loop, the workflow cannot advance to `memory_card` until the review status is `clean`. If the review returns `issues_found`, the workflow forces `chapter_revision`, then returns to `chapter_review` for another pass.
+
+Side-track steps (`chapter_review`, `chapter_revision`, `cross_chapter_review`) can still be triggered at any moment via the semantic-action tools. When a manual side-track completes via `submit_step_result`, the workflow returns to whatever `currentStep` it was on before the side-track started.
 
 The full transition map lives in the `next:` declaration of each handler under [src/core/steps/](src/core/steps/). To change the workflow, edit those files — that is the entire state machine, there is no graph engine.
 
@@ -204,6 +271,7 @@ src/
 │   ├── schemas.ts                # zod schemas (the only validator)
 │   ├── projectStore.ts           # filesystem persistence
 │   ├── projectDiscovery.ts       # list / status
+│   ├── characterStore.ts         # independent character state table
 │   ├── prompts/                  # per-language prompt packs (zh-CN, en-US)
 │   ├── steps/                    # one file per WorkflowStep handler
 │   ├── retrieval/                # BM25 index + CJK tokenizer + chunker

package/dist/src/cli/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
-import { buildContext, createProject, getNextStep, getProjectStatus, listProjects, requestSideTrack, retrieve, submitStepResult, } from '../core/index.js';
+import { amendStoryBible, buildContext, createProject, deleteChapter, forkProject, getNextStep, getProjectStatus, listProjects, loadThreads, redoStep, requestSideTrack, retrieve, submitStepResult, updateThread, } from '../core/index.js';
+import { formatInstallResult, runInstall } from './install.js';
 function valueAfter(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
@@ -10,8 +11,28 @@ function parseLanguage(value) {
         return value;
     throw new Error('Invalid --language. Use zh-CN or en-US');
 }
+function parseHost(value) {
+    const v = (value || 'claude-code').toLowerCase();
+    if (v === 'claude-code' || v === 'claude')
+        return 'claude-code';
+    if (v === 'codex' || v === 'codex-cli')
+        return 'codex';
+    if (v === 'cursor')
+        return 'cursor';
+    throw new Error(`Unknown --host: ${value}. Use claude-code | codex | cursor.`);
+}
 export async function runCli(argv = process.argv.slice(2), cwd = process.cwd()) {
     const [command, projectPath] = argv;
+    if (command === 'install') {
+        const result = await runInstall({
+            host: parseHost(valueAfter(argv, '--host')),
+            workspace: valueAfter(argv, '--workspace'),
+            name: valueAfter(argv, '--name'),
+            printOnly: argv.includes('--print-only'),
+        });
+        console.log(formatInstallResult(result));
+        return;
+    }
     if (command === 'start') {
         const prompt = valueAfter(argv, '--prompt') || '';
         if (!prompt.trim())
@@ -115,7 +136,76 @@ export async function runCli(argv = process.argv.slice(2), cwd = process.cwd())
         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 (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');
+        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');
+        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');
+        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]}`) {
     runCli().catch((error) => {

package/dist/src/cli/install.js

@@ -0,0 +1,224 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const PACKAGE_NAME = 'novelforge-agent';
+const MCP_BIN = 'novelforge-agent-mcp';
+function defaultWorkspace() {
+    return join(homedir(), 'novelforge');
+}
+function defaultName() {
+    return 'novelforge';
+}
+function claudeJsonSnippet(name, workspace) {
+    return JSON.stringify({
+        mcpServers: {
+            [name]: {
+                command: 'npx',
+                args: ['-y', MCP_BIN],
+                env: { NOVELFORGE_WORKSPACE: workspace },
+            },
+        },
+    }, null, 2);
+}
+function codexTomlSnippet(name, workspace) {
+    return [
+        `[mcp_servers.${name}]`,
+        `command = "npx"`,
+        `args = ["-y", "${MCP_BIN}"]`,
+        ``,
+        `[mcp_servers.${name}.env]`,
+        `NOVELFORGE_WORKSPACE = "${workspace}"`,
+        ``,
+    ].join('\n');
+}
+function cursorSnippet(name, workspace) {
+    return JSON.stringify({
+        mcpServers: {
+            [name]: {
+                command: 'npx',
+                args: ['-y', MCP_BIN],
+                env: { NOVELFORGE_WORKSPACE: workspace },
+            },
+        },
+    }, null, 2);
+}
+async function ensureWorkspaceDir(workspace) {
+    await mkdir(workspace, { recursive: true });
+    await mkdir(join(workspace, 'novels'), { recursive: true });
+}
+async function tryClaudeCli(name, workspace) {
+    const args = [
+        'mcp',
+        'add',
+        '-s',
+        'user',
+        '-e',
+        `NOVELFORGE_WORKSPACE=${workspace}`,
+        name,
+        '--',
+        'npx',
+        '-y',
+        MCP_BIN,
+    ];
+    try {
+        const { stdout, stderr } = await execFileAsync('claude', args);
+        return { ok: true, output: `${stdout}\n${stderr}`.trim() };
+    }
+    catch (error) {
+        const err = error;
+        return { ok: false, output: '', error: err.message };
+    }
+}
+async function applyClaudeCode(name, workspace, printOnly) {
+    const snippet = claudeJsonSnippet(name, workspace);
+    const verificationHint = 'In Claude Code, ask the assistant: "list_projects 现在能用吗?". The host should call the list_projects tool and return an empty array.';
+    if (printOnly) {
+        return {
+            host: 'claude-code',
+            name,
+            workspace,
+            applied: false,
+            method: 'print-only',
+            message: 'Print-only mode. Run the snippet below or invoke without --print-only to apply automatically.',
+            manualSnippet: snippet,
+            verificationHint,
+        };
+    }
+    const cli = await tryClaudeCli(name, workspace);
+    if (cli.ok) {
+        return {
+            host: 'claude-code',
+            name,
+            workspace,
+            applied: true,
+            method: 'cli',
+            message: `Registered via \`claude mcp add\`.\n${cli.output}`,
+            verificationHint,
+        };
+    }
+    return {
+        host: 'claude-code',
+        name,
+        workspace,
+        applied: false,
+        method: 'print-only',
+        message: `\`claude\` CLI not available (${cli.error ?? 'unknown error'}). Paste the snippet below into ~/.claude.json under "mcpServers", or run \`claude mcp add -s user -e NOVELFORGE_WORKSPACE=${workspace} ${name} -- npx -y ${MCP_BIN}\` after installing Claude Code.`,
+        manualSnippet: snippet,
+        verificationHint,
+    };
+}
+async function applyCodex(name, workspace, printOnly) {
+    const snippet = codexTomlSnippet(name, workspace);
+    const configPath = join(homedir(), '.codex', 'config.toml');
+    const verificationHint = 'In Codex CLI, ask the assistant: "list_projects 现在能用吗?". The host should call the list_projects tool and return an empty array.';
+    if (printOnly) {
+        return {
+            host: 'codex',
+            name,
+            workspace,
+            applied: false,
+            method: 'print-only',
+            message: `Print-only mode. Append the snippet below to ${configPath}.`,
+            manualSnippet: snippet,
+            verificationHint,
+        };
+    }
+    try {
+        await mkdir(dirname(configPath), { recursive: true });
+        let existing = '';
+        try {
+            existing = await readFile(configPath, 'utf8');
+        }
+        catch {
+            existing = '';
+        }
+        if (existing.includes(`[mcp_servers.${name}]`)) {
+            return {
+                host: 'codex',
+                name,
+                workspace,
+                applied: false,
+                method: 'config-edit',
+                message: `Section [mcp_servers.${name}] already exists in ${configPath}. Edit it manually if you want to change settings.`,
+                manualSnippet: snippet,
+                verificationHint,
+            };
+        }
+        const next = existing.endsWith('\n') || existing === '' ? existing : `${existing}\n`;
+        await writeFile(configPath, `${next}\n${snippet}`, 'utf8');
+        return {
+            host: 'codex',
+            name,
+            workspace,
+            applied: true,
+            method: 'config-edit',
+            message: `Appended [mcp_servers.${name}] to ${configPath}.`,
+            verificationHint,
+        };
+    }
+    catch (error) {
+        return {
+            host: 'codex',
+            name,
+            workspace,
+            applied: false,
+            method: 'print-only',
+            message: `Could not write ${configPath}: ${error.message}. Append the snippet manually.`,
+            manualSnippet: snippet,
+            verificationHint,
+        };
+    }
+}
+async function applyCursor(name, workspace, printOnly) {
+    const snippet = cursorSnippet(name, workspace);
+    return {
+        host: 'cursor',
+        name,
+        workspace,
+        applied: false,
+        method: 'print-only',
+        message: 'Cursor: open Settings → Tools & Integrations → MCP, click "Add new MCP server", and paste the snippet below.',
+        manualSnippet: snippet,
+        verificationHint: 'In Cursor, the agent should be able to call the list_projects tool from the novelforge MCP server.',
+    };
+}
+export async function runInstall(options) {
+    const host = options.host ?? 'claude-code';
+    const workspace = resolve(options.workspace ?? defaultWorkspace());
+    const name = options.name ?? defaultName();
+    const printOnly = options.printOnly ?? false;
+    if (!printOnly) {
+        await ensureWorkspaceDir(workspace);
+    }
+    switch (host) {
+        case 'claude-code':
+            return applyClaudeCode(name, workspace, printOnly);
+        case 'codex':
+            return applyCodex(name, workspace, printOnly);
+        case 'cursor':
+            return applyCursor(name, workspace, printOnly);
+        default:
+            throw new Error(`Unknown host: ${host}. Use claude-code | codex | cursor.`);
+    }
+}
+export function formatInstallResult(result) {
+    const parts = [];
+    parts.push(`Host:        ${result.host}`);
+    parts.push(`MCP name:    ${result.name}`);
+    parts.push(`Workspace:   ${result.workspace}`);
+    parts.push(`Applied:     ${result.applied ? 'yes' : 'no'} (${result.method})`);
+    parts.push('');
+    parts.push(result.message);
+    if (result.manualSnippet) {
+        parts.push('');
+        parts.push('--- Snippet ---');
+        parts.push(result.manualSnippet);
+        parts.push('---------------');
+    }
+    parts.push('');
+    parts.push(`Verify: ${result.verificationHint}`);
+    return parts.join('\n');
+}

package/dist/src/core/bibleStore.js

@@ -0,0 +1,36 @@
+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';
+function isEmpty(content) {
+    return !content || !content.trim();
+}
+export async function amendStoryBible(input) {
+    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'],
+        files: { ...state.files, storyBible: 'story-bible.md' },
+    });
+    return { archivedPath: archived, bibleVersion, savedPath };
+}
+export async function listStoryBibleVersions(projectPath) {
+    try {
+        const items = await readdir(join(projectPath, 'story-bible-versions'));
+        return items.filter((f) => f.endsWith('.md')).sort();
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/core/characterStore.js

@@ -0,0 +1,74 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const CHARACTERS_FILE = 'characters.json';
+function emptyState(member, chapterNumber = 0) {
+    return {
+        name: member.name,
+        role: member.role,
+        goal: '未确认',
+        belief: '未确认',
+        relationships: [],
+        abilities: [],
+        secrets: [],
+        emotionalState: member.description,
+        lastUpdatedAt: chapterNumber,
+    };
+}
+export async function loadCharacterStates(projectPath) {
+    try {
+        const raw = await readFile(join(projectPath, CHARACTERS_FILE), 'utf8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.characters) ? parsed.characters : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function saveCharacterStates(projectPath, characters) {
+    const fullPath = join(projectPath, CHARACTERS_FILE);
+    await writeFile(fullPath, `${JSON.stringify({ characters }, null, 2)}\n`, 'utf8');
+    return fullPath;
+}
+export async function initializeCharacterStates(projectPath, coreCast) {
+    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, chapterNumber, updates) {
+    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;
+}