@waterwx/dsh-novel-forge 0.1.0

package/lib/types/assets.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Writing assets — 题材基底库 / 推进模式库 / 反 AI 规则 / 写法引擎.
+ *
+ * Ported from AI-Novel-Writing-Assistant (Apache-2.0) built-in seed data:
+ * - 8 preset style templates (DEFAULT_STYLE_TEMPLATES)
+ * - 12 anti-AI rules with concrete detect patterns (DEFAULT_ANTI_AI_RULES)
+ * - genre tree + progression mode seeds
+ * Assets persist with the project (novel-project.json) and are injected into
+ * generation / planning / review prompts, and available to the AI assistant.
+ */
+import type { AntiAiRule, GenreNode, ProgressionMode, ProjectAssets, StyleAsset, StyleTemplate } from './protocol.ts';
+/** 预置写法模板（来自 AI-Novel-Writing-Assistant 内置 DEFAULT_STYLE_TEMPLATES）。 */
+export declare const BUILTIN_STYLE_TEMPLATES: StyleTemplate[];
+/** 内置全局反 AI 规则（来自 AI-Novel-Writing-Assistant 内置 DEFAULT_ANTI_AI_RULES）。 */
+export declare const BUILTIN_ANTI_AI_RULES: AntiAiRule[];
+/** 内置题材基底库（常用网文题材树，跨书复用）。 */
+export declare const BUILTIN_GENRE_LIBRARY: GenreNode[];
+/** 内置常用推进模式。 */
+export declare const BUILTIN_PROGRESSION_MODES: ProgressionMode[];
+/** 默认（空）项目写作资产。 */
+export declare function emptyProjectAssets(): ProjectAssets;
+/** 合并项目资产与内置库：返回「生效的反 AI 规则」（内置全局 + 项目自定义）。 */
+export declare function effectiveAntiAiRules(assets: ProjectAssets | undefined): AntiAiRule[];
+/** 把生效规则渲染成提示词块。 */
+export declare function renderAntiAiRules(assets: ProjectAssets | undefined): string;
+/** 渲染题材与推进模式提示词块。 */
+export declare function renderGenreAndProgression(assets: ProjectAssets | undefined): string;
+/** 渲染写法资产提示词块。 */
+export declare function renderStyleAssets(assets: ProjectAssets | undefined): string;
+/** 渲染全部写作资产提示词（供生成/规划/审稿注入）。 */
+export declare function renderAllAssets(assets: ProjectAssets | undefined): string;
+/** 预置写法模板 → 可直接绑定的 StyleAsset。 */
+export declare function styleTemplateToAsset(template: StyleTemplate): StyleAsset;
+/** 写法引擎：从样本文本提取风格资产的系统提示词。 */
+export declare function styleEngineSystemPrompt(): string;

package/lib/types/assistant.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AI assistant engine — a conversational editor over the novel project.
+ *
+ * The user talks to the assistant about plot, characters, settings; the
+ * assistant can reply in prose AND emit action directives that the host
+ * executes (rewrite a paragraph, edit the bible, regenerate a chapter,
+ * export the book, ...). Conversation history persists next to the project
+ * as NDJSON, so a reload keeps the thread.
+ *
+ * Action protocol: the model emits a line of the form
+ *   <dsh-action name="toolName">{jsonArgs}</dsh-action>
+ * anywhere in its reply. The host strips it, executes the tool, appends the
+ * result as a tool-role message, and continues the loop (bounded rounds).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AssistantMessage, NovelConfig, ProjectState } from './protocol.ts';
+import { chapterFileName } from './engine.ts';
+/** History file name inside the output dir. */
+export declare const ASSISTANT_HISTORY_FILE = "novel-assistant.jsonl";
+/** Load the persisted conversation (empty when none). */
+export declare function loadAssistantHistory(outputDir: string): AssistantMessage[];
+/** Execute one action directive. Returns a text result (or throws). */
+/**
+ * Execute one action directive as an async generator: yields live progress
+ * text (chapter text being generated/rewritten), then yields the final result
+ * string. Throws on failure.
+ */
+export declare function executeAction(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, name: string, args: Record<string, unknown>): AsyncGenerator<string, string, unknown>;
+/** Run one user turn. Yields stream frames; persists history. */
+export declare function runAssistantTurn(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, userMessage: string): AsyncGenerator<{
+    frame: 'delta';
+    text: string;
+} | {
+    frame: 'tool';
+    name: string;
+    status: 'start' | 'done' | 'error';
+    detail?: string;
+} | {
+    frame: 'toolDelta';
+    name: string;
+    text: string;
+}, void, unknown>;
+export { chapterFileName };

package/lib/types/bookshelf.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 书架（Bookshelf）— 多书管理：一本书记录一个独立输出目录。
+ * 状态持久化到 ~/.dsh/dsh-novel-forge-bookshelf.json（跟随 dsh 配置惯例）。
+ */
+import type { BookEntry, BookshelfSnapshot } from './protocol.ts';
+/** 书架配置文件路径。 */
+export declare function bookshelfFile(): string;
+interface BookshelfStore {
+    books: BookEntry[];
+    activeBookId: string | null;
+}
+/** 读取书架（无则返回空）。 */
+export declare function loadBookshelf(): BookshelfStore;
+/** 当前激活的书。 */
+export declare function activeBook(store: BookshelfStore): BookEntry | undefined;
+/** 书架快照（含每本书的进度摘要）。 */
+export declare function bookshelfSnapshot(store: BookshelfStore): BookshelfSnapshot;
+/** 新建一本书（自动成为当前书）。 */
+export declare function createBook(bookName: string, outputDir: string): BookEntry;
+/**
+ * 播种：书架为空时，把指定输出目录下已有的项目自动登记为第一本书。
+ * 兼容升级场景 —— 旧版插件直接在输出目录写项目，从未登记书架。
+ * @param outputDir - 候选输出目录（通常为 settings 的默认输出目录）。
+ * @returns 是否发生了播种。
+ */
+export declare function seedBookshelfFromOutputDir(outputDir: string): boolean;
+/** 激活一本书。 */
+export declare function activateBook(id: string): BookEntry | undefined;
+/** 移除一本书。 */
+export declare function removeBook(id: string): boolean;
+/** 当前书输出目录（无书架则 undefined，回退 settings）。 */
+export declare function activeBookOutputDir(): string | undefined;
+/** 默认输出目录推断：桌面/书名。 */
+export declare function defaultOutputDirFor(bookName: string): string;
+export {};

package/lib/types/client/api.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Browser-side API client for the /api/dsh-novel-forge route family. Plain
+ * fetch, same origin; generation/rewrite/polish ride NDJSON streams read
+ * incrementally.
+ */
+import { type AssetsPatch, type AssetsResponse, type BibleResponse, type ChapterResponse, type ConfigPatch, type ExportResponse, type ForeshadowRequest, type ForeshadowResponse, type JobFrame, type LoadOutlineResponse, type NovelConfig, type PlanResponse, type ReviewReport, type StatusResponse, type StyleEngineRequest, type StyleAsset, type VolumesResponse } from '../protocol.ts';
+/** Error carrying the route's JSON error message. */
+export declare class NovelApiError extends Error {
+    constructor(message: string);
+}
+/** The browser half's only data entry point. */
+export declare class NovelApi {
+    status(): Promise<StatusResponse>;
+    loadOutline(path?: string, text?: string): Promise<LoadOutlineResponse>;
+    saveOutline(text: string): Promise<{
+        ok: boolean;
+        bookName: string;
+    }>;
+    plan(outline?: string, chapterCount?: number, volume?: number): Promise<PlanResponse>;
+    volumes(outline?: string): Promise<VolumesResponse>;
+    bible(outline?: string): Promise<BibleResponse>;
+    review(chapterNo: number): Promise<{
+        report: ReviewReport;
+    }>;
+    summarize(chapterNo: number): Promise<{
+        summary: string;
+    }>;
+    foreshadow(req: ForeshadowRequest): Promise<ForeshadowResponse>;
+    exportBook(format: 'txt' | 'md'): Promise<ExportResponse>;
+    chapter(no: number): Promise<ChapterResponse>;
+    patchConfig(patch: ConfigPatch): Promise<{
+        config: NovelConfig;
+    }>;
+    openFolder(): Promise<void>;
+    /** 书架快照。 */
+    bookshelf(): Promise<import('../protocol.ts').BookshelfSnapshot>;
+    /** 新建书并激活。 */
+    bookCreate(bookName: string, outputDir?: string): Promise<import('../protocol.ts').BookshelfSnapshot>;
+    /** 切换当前书。 */
+    bookActivate(id: string): Promise<import('../protocol.ts').BookshelfSnapshot>;
+    /** 移除书架条目。 */
+    bookRemove(id: string): Promise<import('../protocol.ts').BookshelfSnapshot>;
+    /** Get project writing assets + built-in libraries. */
+    assets(): Promise<AssetsResponse>;
+    /** Patch project writing assets. */
+    patchAssets(patch: AssetsPatch): Promise<AssetsResponse>;
+    /** Extract a style asset from sample text. */
+    styleEngine(req: StyleEngineRequest): Promise<{
+        styleAsset: StyleAsset;
+    }>;
+    /**
+     * Consume an NDJSON job stream (generate / rewrite / polish).
+     * @param path - the route to POST to.
+     * @param payload - the JSON body.
+     * @param onFrame - receives every frame as it lands.
+     */
+    private streamJob;
+    /** Generate one chapter. */
+    generate(chapterNo: number, skipReview: boolean, onFrame: (frame: JobFrame) => void): Promise<void>;
+    /** Rewrite one chapter (whole-chapter, or local when `target` is given). */
+    rewrite(chapterNo: number, instructions: string, target: string, onFrame: (frame: JobFrame) => void): Promise<void>;
+    /** Polish (de-AI-ify) one chapter. */
+    polish(chapterNo: number, onFrame: (frame: JobFrame) => void): Promise<void>;
+    /** Run one assistant turn (NDJSON stream). */
+    assistant(message: string, onFrame: (frame: import('../protocol.ts').AssistantFrame) => void): Promise<void>;
+    /** Load the persisted assistant conversation. */
+    assistantHistory(): Promise<import('../protocol.ts').AssistantMessage[]>;
+}

package/lib/types/client/docx.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Browser-side docx outline extraction: a .docx is a zip whose
+ * word/document.xml holds the body text in <w:t> runs inside <w:p> paragraphs.
+ * Uses fflate (inlined into the client bundle) so the user can pick or drag a
+ * docx without any server upload.
+ *
+ * Import from 'fflate/browser' (not 'fflate'): the default entry resolves to
+ * the Node build (esm/index.mjs), which calls module.createRequire() for the
+ * optional worker_threads path — inlining that into the browser bundle leaves
+ * a bare require("module") the client-modules table cannot answer.
+ */
+/** Extract plain text from a docx buffer: one line per <w:p> paragraph. */
+export declare function extractDocxTextFromBuffer(buffer: ArrayBuffer | Uint8Array): string;
+/** Read a File as ArrayBuffer. */
+export declare function readFileAsArrayBuffer(file: File): Promise<ArrayBuffer>;

package/lib/types/client/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Browser-half entry for the dsh-novel-forge plugin — runs inside the dsh web
+ * GUI. Registers the sidebar entry row and the workbench panel. DOM mounting
+ * problems are logged, never thrown — the web shell fails the whole boot when
+ * a plugin apply throws.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+/** Required services (fiber inject waiting). */
+export declare const inject: string[];
+/**
+ * Mount the novel-forge workbench.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,139 @@
+/**
+ * dsh-novel-forge — locale dictionaries (zh / en).
+ */
+/** zh dictionary. */
+export declare const zh: {
+    readonly 'entry.label': "小说工坊";
+    readonly 'entry.tooltip': "AI 编译小说工作台：大纲 → 设定圣经 → 卷计划 → 章节计划 → 逐章生成+审稿";
+    readonly 'panel.title': "小说工坊";
+    readonly 'common.close': "关闭";
+    readonly 'common.loading': "加载中…";
+    readonly 'common.save': "保存";
+    readonly 'common.error': "错误";
+    readonly 'common.success': "成功";
+    readonly 'common.generating': "生成中…";
+    readonly 'common.chars': "字";
+    readonly 'tab.workflow': "工作流";
+    readonly 'tab.overview': "大纲";
+    readonly 'tab.plan': "章节";
+    readonly 'tab.bible': "设定库";
+    readonly 'tab.foreshadow': "伏笔";
+    readonly 'tab.assistant': "AI 助手";
+    readonly 'tab.settings': "设置";
+    readonly 'workflow.title': "创作工作流";
+    readonly 'workflow.step1': "① 加载大纲";
+    readonly 'workflow.step2': "② 提炼设定圣经";
+    readonly 'workflow.step3': "③ 规划卷";
+    readonly 'workflow.step4': "④ 生成章节计划";
+    readonly 'workflow.step5': "⑤ 逐章写作 + AI 审稿";
+    readonly 'workflow.step6': "⑥ 润色 / 导出";
+    readonly 'workflow.loadOutline': "读取大纲";
+    readonly 'workflow.genBible': "提炼设定圣经";
+    readonly 'workflow.genVolumes': "生成卷计划";
+    readonly 'workflow.genPlan': "生成章节计划";
+    readonly 'workflow.done': "已完成";
+    readonly 'workflow.todo': "待办";
+    readonly 'workflow.bibleDone': "设定圣经已生成（{n} 条规则 / {c} 个角色 / {r} 条红线）";
+    readonly 'workflow.volumesDone': "卷计划已生成（{n} 卷）";
+    readonly 'workflow.planDone': "章节计划已生成（{n} 章）";
+    readonly 'workflow.progress': "进度：大纲 ✓ · 设定 {bible} · 卷 {volumes} · 计划 {plan} · 已完成 {done}/{total} 章";
+    readonly 'overview.loadDocx': "从 docx 读取大纲";
+    readonly 'overview.loadDocxDefault': "读取默认大纲";
+    readonly 'overview.loadingOutline': "正在解析 docx…";
+    readonly 'overview.outlineHint': "大纲文本（可编辑）";
+    readonly 'overview.outlineChars': "大纲字数";
+    readonly 'overview.saveOutline': "保存大纲";
+    readonly 'overview.saved': "大纲已保存";
+    readonly 'overview.bookName': "书名";
+    readonly 'overview.loadCustom': "指定 docx 路径";
+    readonly 'overview.loadCustomHint': "绝对路径，留空使用默认";
+    readonly 'plan.generate': "生成章节计划";
+    readonly 'plan.generateHint': "章节数量";
+    readonly 'plan.count': "章";
+    readonly 'plan.empty': "暂无章节计划，请先生成";
+    readonly 'plan.chapter': "章";
+    readonly 'plan.pending': "待生成";
+    readonly 'plan.generating': "生成中";
+    readonly 'plan.written': "待审稿";
+    readonly 'plan.reviewing': "审稿中";
+    readonly 'plan.approved': "已通过";
+    readonly 'plan.rejected': "待修订";
+    readonly 'plan.error': "失败";
+    readonly 'plan.write': "生成本章";
+    readonly 'plan.rewrite': "修订";
+    readonly 'plan.review': "审稿";
+    readonly 'plan.polish': "去AI味";
+    readonly 'plan.writeAll': "批量生成全部";
+    readonly 'plan.writeAllPending': "批量生成剩余";
+    readonly 'plan.generated': "已生成";
+    readonly 'plan.progress': "进度";
+    readonly 'plan.beats': "剧情要点";
+    readonly 'plan.reviewReport': "审稿报告";
+    readonly 'plan.reviewScore': "评分";
+    readonly 'plan.reviewVerdict': "总评";
+    readonly 'plan.reviewIssues': "问题清单";
+    readonly 'plan.reviewPass': "通过";
+    readonly 'plan.reviewFail': "未通过";
+    readonly 'plan.approve': "手动通过";
+    readonly 'plan.summary': "章节摘要";
+    readonly 'plan.volumes': "卷";
+    readonly 'plan.noVolume': "未分卷";
+    readonly 'bible.title': "设定圣经";
+    readonly 'bible.gen': "AI 提炼设定圣经";
+    readonly 'bible.genre': "题材基调";
+    readonly 'bible.worldRules': "世界规则";
+    readonly 'bible.characters': "角色卡";
+    readonly 'bible.redLines': "写作红线";
+    readonly 'bible.style': "风格要求";
+    readonly 'bible.none': "尚未生成设定圣经。生成后写作会严格遵守人设与金手指规则，审稿也会按红线检查。";
+    readonly 'foreshadow.title': "伏笔管理";
+    readonly 'foreshadow.suggest': "AI 建议伏笔";
+    readonly 'foreshadow.none': "暂无伏笔";
+    readonly 'foreshadow.status': "状态";
+    readonly 'foreshadow.planned': "计划中";
+    readonly 'foreshadow.planted': "已埋设";
+    readonly 'foreshadow.progressing': "推进中";
+    readonly 'foreshadow.resolved': "已回收";
+    readonly 'foreshadow.abandoned': "已放弃";
+    readonly 'foreshadow.target': "预计回收";
+    readonly 'foreshadow.plantedAt': "埋设于";
+    readonly 'foreshadow.setPlanted': "标记已埋设";
+    readonly 'foreshadow.setResolved': "标记已回收";
+    readonly 'settings.title': "设置";
+    readonly 'settings.outlinePath': "默认大纲路径";
+    readonly 'settings.outputDir': "输出目录";
+    readonly 'settings.provider': "模型提供商";
+    readonly 'settings.model': "模型";
+    readonly 'settings.chapterChars': "每章目标字数";
+    readonly 'settings.maxTokens': "单章最大输出 tokens";
+    readonly 'settings.reviewPassScore': "审稿通过分数（0-100）";
+    readonly 'settings.autoReview': "生成后自动审稿";
+    readonly 'settings.save': "保存设置";
+    readonly 'settings.saved': "设置已保存";
+    readonly 'settings.openFolder': "打开输出文件夹";
+    readonly 'settings.export': "导出";
+    readonly 'settings.exportTxt': "导出 TXT";
+    readonly 'settings.exportMd': "导出 Markdown";
+    readonly 'settings.exported': "已导出：{file}（{chars} 字，{chapters} 章）";
+    readonly 'progress.generating': "正在生成第 {no} 章《{title}》…";
+    readonly 'progress.done': "第 {no} 章完成（{chars} 字）→ {file}";
+    readonly 'progress.reviewed': "第 {no} 章审稿：{score} 分 — {verdict}";
+    readonly 'progress.error': "第 {no} 章失败：{message}";
+    readonly 'progress.rewriting': "正在修订第 {no} 章…";
+    readonly 'progress.polishing': "正在润色第 {no} 章…";
+    readonly 'progress.empty': "生成/审稿进度将显示在这里";
+    readonly 'assistant.hint': "和 AI 编辑讨论剧情、人设、伏笔；达成一致后可让它直接修改大纲、设定圣经、章节内容。";
+    readonly 'assistant.placeholder': "例如：我想让第 2 章结尾加一个悬念——墟境里传来爷爷的声音…";
+    readonly 'assistant.send': "发送";
+    readonly 'assistant.toolStart': "⚙ 执行操作：{name}…";
+    readonly 'assistant.toolDone': "✓ {name} 完成：{detail}";
+    readonly 'assistant.toolError': "✗ {name} 失败：{detail}";
+    readonly 'assistant.empty': "还没有对话。和 AI 编辑聊聊剧情吧。";
+    readonly 'status.projectNone': "输出目录中还没有项目。请先加载大纲。";
+    readonly 'status.files': "已生成文件";
+    readonly 'api.error': "请求失败";
+};
+/** en dictionary (fallback). */
+export declare const en: Record<string, string>;
+/** Keys type for the zh dictionary. */
+export type NovelKey = keyof typeof zh;

package/lib/types/client/mount.d.ts

@@ -0,0 +1,9 @@
+import type { NovelApi } from './api.ts';
+import type { PanelController } from './panel/controller.ts';
+/** The injected panel container. */
+export declare const PANEL_VIEW_SELECTOR = "[data-dsh-novelforge-view]";
+/**
+ * Mount the panel React tree into the center column and bind visibility to
+ * the controller.
+ */
+export declare function mountPanel(controller: PanelController, api: NovelApi): () => void;

package/lib/types/client/panel/AssetsTab.d.ts

@@ -0,0 +1,7 @@
+import type { NovelApi } from '../api.ts';
+/** Props. */
+export interface AssetsTabProps {
+    api: NovelApi;
+}
+/** 写作资产页签。 */
+export declare function AssetsTab({ api }: AssetsTabProps): import("react").JSX.Element;

package/lib/types/client/panel/AssistantTab.d.ts

@@ -0,0 +1,7 @@
+import type { NovelApi } from '../api.ts';
+/** Props. */
+export interface AssistantTabProps {
+    api: NovelApi;
+}
+/** The assistant conversation tab. */
+export declare function AssistantTab({ api }: AssistantTabProps): import("react").JSX.Element;

package/lib/types/client/panel/BookshelfBar.d.ts

@@ -0,0 +1,11 @@
+import type { NovelApi } from '../api.ts';
+import type { BookshelfSnapshot } from '../../protocol.ts';
+/** Props. */
+export interface BookshelfBarProps {
+    api: NovelApi;
+    shelf: BookshelfSnapshot;
+    /** 刷新整个面板（切换书后重新拉状态）。 */
+    onSwitch: () => void;
+}
+/** 书架条。 */
+export declare function BookshelfBar({ api, shelf, onSwitch }: BookshelfBarProps): import("react").JSX.Element;

package/lib/types/client/panel/NovelPanel.d.ts

@@ -0,0 +1,13 @@
+import type { NovelApi } from '../api.ts';
+import type { PanelController } from './controller.ts';
+/** The panel's tab identifiers. */
+export type NovelTab = 'workflow' | 'overview' | 'plan' | 'bible' | 'assets' | 'foreshadow' | 'assistant' | 'settings';
+/** Panel shell props. */
+export interface NovelPanelProps {
+    /** The panel state owner (open/close/toggle). */
+    controller: PanelController;
+    /** The API client every tab operates through. */
+    api: NovelApi;
+}
+/** The novel-forge panel. */
+export declare function NovelPanel({ controller, api }: NovelPanelProps): import("react").JSX.Element;

package/lib/types/client/panel/controller.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Novel-forge panel controller: the single owner of the panel's open/closed
+ * state (framework-free, mirroring the family plugins' controllers).
+ */
+/** Immutable controller snapshot for UI subscriptions. */
+export interface PanelControllerSnapshot {
+    panelOpen: boolean;
+}
+/** The panel state owner the sidebar entry toggles and the view renders from. */
+export declare class PanelController {
+    private panelOpen;
+    private listeners;
+    getSnapshot(): PanelControllerSnapshot;
+    subscribe(fn: () => void): () => void;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    private notify;
+}

package/lib/types/client/panel/helpers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tiny translation helper for the panel: reads the zh dict with the en dict
+ * as fallback (the family plugins use a full locale registry; the panel keeps
+ * a dependency-free helper so the client bundle stays self-contained).
+ */
+import { type NovelKey } from '../locales.ts';
+/** Translate one key with optional {placeholder} substitution. */
+export declare function tt(key: NovelKey, params?: Record<string, string | number>): string;

package/lib/types/client/sidebar-entry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sidebar entry injection — mirrors the family plugins' DOM-level pattern:
+ * the shell exposes no external slot, so the entry row is injected after the
+ * sibling plugin entries and self-heals via MutationObserver.
+ */
+import type { PanelController } from './panel/controller.ts';
+/** Stable data attribute identifying the injected entry row. */
+export declare const ENTRY_SELECTOR = "[data-dsh-novelforge-entry]";
+/**
+ * Mount the sidebar entry, waiting for the shell and self-healing on
+ * re-renders.
+ */
+export declare function mountSidebarEntry(controller: PanelController): () => void;

package/lib/types/docx.d.ts

@@ -0,0 +1,19 @@
+/**
+ * docx outline extraction: a .docx is a zip whose word/document.xml holds the
+ * body text in <w:t> runs inside <w:p> paragraphs. We unzip with fflate and
+ * walk the XML with a tiny tokenizer — no heavyweight XML/DOM dependency.
+ */
+/**
+ * Extract plain text from a docx buffer: one line per <w:p> paragraph, with
+ * <w:tab>/<w:br> preserved as whitespace. Tables and nested structures are
+ * flattened in document order (their paragraphs are just <w:p> too).
+ * @param buffer - the raw .docx bytes.
+ * @returns the body text.
+ */
+export declare function extractDocxText(buffer: Uint8Array): string;
+/**
+ * Read and extract a docx outline from disk.
+ * @param path - absolute path to the .docx file.
+ * @returns the extracted outline text.
+ */
+export declare function readOutlineFromDocx(path: string): string;

package/lib/types/engine.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Novel engine — the host half's core: LLM-driven story-bible extraction,
+ * volume planning, chapter planning, chapter-by-chapter writing with
+ * auto-review + rewrite, polish (de-AI-ify), narrative summaries, foreshadow
+ * tracking, project persistence, and whole-book export. Pure Node (no
+ * web-server dependencies), so routes stay thin and logic is testable.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ChapterPlan, Foreshadow, NovelConfig, ProjectState, ReviewReport, StoryBible, Volume } from './protocol.ts';
+/** Project state file name inside the output dir. */
+export declare const PROJECT_FILE = "novel-project.json";
+/** Chapter output file name, e.g. 第001章_开篇.md */
+export declare function chapterFileName(chapter: ChapterPlan): string;
+/** Infer a book name from the outline's first non-empty line. */
+export declare function inferBookName(outline: string): string;
+/** Read the persisted project from the output dir (undefined when absent). */
+export declare function loadProject(outputDir: string): ProjectState | undefined;
+/** Persist the project state next to the chapters. */
+export declare function saveProject(outputDir: string, project: ProjectState): void;
+/** List generated chapter files in the output dir (sorted). */
+export declare function listChapterFiles(outputDir: string): string[];
+/** Re-sync chapter status against files on disk (a file may exist without state). */
+export declare function syncProjectWithDisk(project: ProjectState, outputDir: string): void;
+/** Read a chapter's markdown body from disk (undefined when missing). */
+export declare function readChapterFile(outputDir: string, chapter: ChapterPlan): string | undefined;
+/** Create a fresh project from an outline. */
+export declare function createProject(outline: string, outlinePath?: string): ProjectState;
+/** Extract the story bible from an outline. */
+export declare function extractBible(ctx: Context, config: NovelConfig, outline: string): Promise<StoryBible>;
+/** Plan volumes from an outline. */
+export declare function planVolumes(ctx: Context, config: NovelConfig, outline: string): Promise<Volume[]>;
+/**
+ * Plan chapters from an outline (optionally for one volume).
+ */
+export declare function planChapters(ctx: Context, config: NovelConfig, project: ProjectState, chapterCount: number, volumeNo?: number): Promise<ChapterPlan[]>;
+/** Run the AI review on one chapter. */
+export declare function reviewChapter(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number): Promise<ReviewReport>;
+/**
+ * Stream a chapter rewrite. With `target` (a passage of the body), only that
+ * passage's paragraph is rewritten and spliced back — everything else stays
+ * untouched (local revision). Without `target`, the whole chapter is
+ * rewritten. Yields delta text; persists when done.
+ */
+export declare function rewriteChapterStream(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number, instructions: string, target?: string): AsyncGenerator<{
+    frame: 'start';
+} | {
+    frame: 'delta';
+    text: string;
+} | {
+    frame: 'done';
+    file: string;
+    chars: number;
+}, void, unknown>;
+/** Stream a chapter polish (de-AI-ify). */
+export declare function polishChapterStream(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number): AsyncGenerator<{
+    frame: 'start';
+} | {
+    frame: 'delta';
+    text: string;
+} | {
+    frame: 'done';
+    file: string;
+    chars: number;
+}, void, unknown>;
+/** Generate one chapter (streaming). Yields progress frames; persists when done. */
+export declare function generateChapterStream(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number): AsyncGenerator<{
+    frame: 'start';
+} | {
+    frame: 'delta';
+    text: string;
+} | {
+    frame: 'done';
+    file: string;
+    chars: number;
+}, void, unknown>;
+/** Generate a chapter summary (narrative memory). */
+export declare function summarizeChapter(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number): Promise<string>;
+/** Suggest foreshadows from the outline + plan. */
+export declare function suggestForeshadows(ctx: Context, config: NovelConfig, project: ProjectState): Promise<Foreshadow[]>;
+/**
+ * 写法引擎：从样本文本提取一份写法资产（叙事风格规则）。
+ * @returns 提取出的风格规则（未持久化，由调用方存入 project.assets）。
+ */
+export declare function extractStyleAsset(ctx: Context, config: NovelConfig, sampleText: string): Promise<{
+    proseRules: string[];
+    dialogueRules: string[];
+    descriptionRules: string[];
+    boundaries: string[];
+}>;
+/** Export the whole book as one txt/md file. */
+export declare function exportBook(outputDir: string, project: ProjectState, format: 'txt' | 'md'): {
+    file: string;
+    chars: number;
+    chapters: number;
+};

package/lib/types/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * dsh-novel-forge — host half. Mounts the AI novel-forge workbench: docx
+ * outline import, LLM chapter planning, chapter-by-chapter generation
+ * (3000-4000 chars each), Markdown output into your chosen folder, and the
+ * /api/dsh-novel-forge route family. The browser half (./client) renders the
+ * workbench panel. Everything rides official NPM SDK packages — no dsh source
+ * changes.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from 'schemastery';
+import type { NovelConfig } from './protocol.ts';
+/** Stable cordis plugin name. */
+export declare const name = "novel-forge";
+/** Services required before the novel-forge surfaces can mount. */
+export declare const inject: string[];
+/**
+ * Settings namespace of the novel-forge capability — the section the web
+ * settings surface edits. Spelled here rather than imported: the browser half
+ * spells the same value and must not depend on a Host package.
+ */
+export declare const NOVEL_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** Plugin config, validated by the same-named schemastery schema. */
+export interface Config {
+    /** When true (default), a system-prompt section announces the plugin to every agent. */
+    announceToAgent?: boolean;
+    /** Master switch for the plugin (routes, prompt section). */
+    enabled?: boolean;
+    /** Absolute path of the default docx outline to load. */
+    outlinePath?: string;
+    /** Absolute output directory for chapters + project state. */
+    outputDir?: string;
+    /** LLM provider route. */
+    provider?: string;
+    /** LLM model id. */
+    model?: string;
+    /** Target characters per chapter. */
+    chapterChars?: number;
+    /** Max output tokens per chapter call. */
+    maxTokens?: number;
+    /** Review pass threshold (0-100). */
+    reviewPassScore?: number;
+    /** Whether generation auto-runs review after writing. */
+    autoReview?: boolean;
+}
+export declare const Config: z<Config>;
+/** Model-facing announcement: plugin presence, capabilities, and limits. */
+export declare const NOVEL_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-novel-forge \u63D2\u4EF6\uFF08AI \u7F16\u8BD1\u5C0F\u8BF4\u5DE5\u4F5C\u53F0\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300C\u5C0F\u8BF4\u5DE5\u574A\u300D\u5165\u53E3\u3002\u80FD\u529B\uFF1A\u8BFB\u53D6 docx \u5927\u7EB2\uFF08\u9ED8\u8BA4\u684C\u9762\u300A\u5F52\u589F\u7389\u4E3B\u300B\u5927\u7EB2\uFF09\u6216\u7C98\u8D34\u5927\u7EB2\u6587\u672C\uFF1B\u7528 LLM \u63D0\u70BC\u8BBE\u5B9A\u5723\u7ECF\uFF08\u4EBA\u8BBE/\u4E16\u754C\u89C2/\u91D1\u624B\u6307\u89C4\u5219/\u5199\u4F5C\u7EA2\u7EBF\uFF09\uFF1B\u751F\u6210\u5377\u8BA1\u5212\u4E0E\u7AE0\u8282\u8BA1\u5212\uFF1B\u9010\u7AE0\u8C03\u7528 LLM \u751F\u6210 3000-4000 \u5B57\u6B63\u6587\u5E76\u4FDD\u5B58\u4E3A Markdown\uFF08\u9ED8\u8BA4\u8F93\u51FA\u5230 \u684C\u9762\\\u5F52\u589F\u7389\u4E3B\uFF09\uFF1B\u6BCF\u7AE0\u81EA\u52A8\u751F\u6210\u6458\u8981\uFF08\u53D9\u4E8B\u8BB0\u5FC6\uFF09\u3001\u81EA\u52A8 AI \u5BA1\u7A3F\uFF08\u4EBA\u8BBE/\u8BBE\u5B9A/\u7EA2\u7EBF/\u6587\u7B14/\u723D\u70B9/\u903B\u8F91\uFF09\uFF0C\u652F\u6301\u6309\u5BA1\u7A3F\u610F\u89C1\u91CD\u5199\u3001\u53BB AI \u5473\u6DA6\u8272\u3001\u4F0F\u7B14\u7BA1\u7406\u3001\u6279\u91CF\u8FDE\u5199\u4E0E\u5168\u672C\u5BFC\u51FA\uFF08txt/md\uFF09\u3002\u9650\u5236\uFF1A\u751F\u6210\u6D88\u8017 LLM API \u989D\u5EA6\uFF1B\u8F93\u51FA\u76EE\u5F55\u4E0E\u6A21\u578B\u53EF\u5728\u63D2\u4EF6\u8BBE\u7F6E\u4E2D\u4FEE\u6539\uFF1B\u7AE0\u8282\u6B63\u6587\u8D28\u91CF\u53D6\u51B3\u4E8E\u5927\u7EB2\u5B8C\u6574\u5EA6\u3002\u7528\u6237\u63D0\u5230\u300C\u5C0F\u8BF4 / \u5927\u7EB2 / \u5199\u5C0F\u8BF4 / \u7AE0\u8282 / \u5BA1\u7A3F / \u4F0F\u7B14 / \u6DA6\u8272 / \u5F52\u589F\u7389\u4E3B\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+/** Resolve a config-like value into the full runtime config. */
+export declare function resolveConfig(value: Partial<Config> | undefined): NovelConfig;
+/**
+ * Mount the routes and announcement.
+ * @param ctx - host plugin context carrying webServer/llm/systemPrompt.
+ * @param config - resolved plugin config (schema defaults applied by the loader).
+ */
+export declare function apply(ctx: Context, config?: Config): void;