dsh-novel-write-engine 0.1.3 → 0.2.1

package/lib/types/types.d.ts

@@ -20,8 +20,8 @@ export declare const SCENE_TYPES: readonly ["战斗/动作章", "日常过渡章
 export type SceneType = (typeof SCENE_TYPES)[number];
 /** A violation is blocking unless the rule pack declares it advisory. */
 export type Severity = 'blocker' | 'advisory';
-/** All twenty-two service operations. */
-export declare const OPERATIONS: readonly ["initProject", "archiveChapter", "amend", "rollback", "submitWorldPlan", "submitChapterPlan", "submitDraft", "submitReview", "submitRevision", "runCheck", "getStatus", "getBrief", "countWords", "queryState", "diff", "auditHistory", "advise", "export", "panelSummary", "panelChapters", "panelGates", "stats"];
+/** All thirty-one service operations (22 inherited from 0.1.x, 9 book-level). */
+export declare const OPERATIONS: readonly ["initProject", "archiveChapter", "amend", "rollback", "reopenChapter", "submitWorldPlan", "submitChapterPlan", "submitDraft", "submitReview", "submitRevision", "runCheck", "submitBookPlan", "submitOutline", "importOutline", "submitWorldbook", "getStatus", "getBrief", "countWords", "queryState", "diff", "auditHistory", "advise", "search", "doctor", "report", "guide", "export", "panelSummary", "panelChapters", "panelGates", "stats", "restoreBackup"];
 export type Operation = (typeof OPERATIONS)[number];
 /** Structured, non-fatal note attached to a successful result. */
 export interface Warning {
@@ -70,6 +70,8 @@ export declare const ERROR_CODES: {
     readonly PATH_ESCAPE: "ENGINE_PATH_ESCAPE";
     readonly LOCK_TIMEOUT: "ENGINE_LOCK_TIMEOUT";
     readonly TXN_ABORTED: "ENGINE_TXN_ABORTED";
+    readonly JOURNAL_MISSING: "ENGINE_JOURNAL_MISSING";
+    readonly TXN_IN_PROGRESS: "ENGINE_TXN_IN_PROGRESS";
     readonly RULEPACK_INVALID: "ENGINE_RULEPACK_INVALID";
     readonly ID_EXHAUSTED: "ENGINE_ID_EXHAUSTED";
     readonly CONFIG_INVALID: "ENGINE_CONFIG_INVALID";
@@ -159,6 +161,7 @@ export interface CheckDocument {
     content_hash: string;
     machine: {
         violations: Violation[];
+        advisories?: Violation[];
         metrics: WordMetrics;
     };
     semantic: {
@@ -169,10 +172,12 @@ export interface CheckDocument {
             note: string;
         }>;
     };
+    /** Advisory codes the author has explicitly acknowledged for this content. */
+    acknowledged?: string[];
     verdict: 'pass' | 'fail';
 }
 /** Every persisted document whose damage status/panel can report. */
-export type StateErrorCode = 'PROJECT_UNREADABLE' | 'PLAN_UNREADABLE' | 'WORLD_PLAN_UNREADABLE' | 'REVIEW_UNREADABLE' | 'CHECK_UNREADABLE' | 'CHAPTERS_UNREADABLE' | 'CHARACTERS_UNREADABLE' | 'WORLD_UNREADABLE' | 'LOCKS_UNREADABLE' | 'TIMELINE_UNREADABLE' | 'FORESHADOWS_UNREADABLE' | 'RELATIONSHIPS_UNREADABLE' | 'HANDOFF_UNREADABLE';
+export type StateErrorCode = 'PROJECT_UNREADABLE' | 'PLAN_UNREADABLE' | 'WORLD_PLAN_UNREADABLE' | 'REVIEW_UNREADABLE' | 'CHECK_UNREADABLE' | 'CHAPTERS_UNREADABLE' | 'CHARACTERS_UNREADABLE' | 'WORLD_UNREADABLE' | 'LOCKS_UNREADABLE' | 'TIMELINE_UNREADABLE' | 'FORESHADOWS_UNREADABLE' | 'RELATIONSHIPS_UNREADABLE' | 'HANDOFF_UNREADABLE' | 'OUTLINE_UNREADABLE' | 'WORLDBOOK_UNREADABLE';
 /** A state document that exists but cannot be read safely. */
 export interface StateError {
     path: string;
@@ -187,6 +192,8 @@ export interface WordMetrics {
     numbers: number;
     chinese_punct: number;
     english_punct: number;
+    /** All punctuation counted by the engine; total = cjk + words + numbers + punctuation. */
+    punctuation_chars: number;
     non_ws_chars: number;
     total_lines: number;
     non_empty_lines: number;
@@ -209,6 +216,10 @@ export interface ChapterRecord {
     status: 'draft' | 'reviewed';
     content_hash: string;
     summary: ChapterSummary;
+    /** How hard this chapter was before it was archived. */
+    rounds?: RoundCounters;
+    final_check?: 'pass' | 'fail';
+    archived_at?: string;
     /** Keys allocated by the archive transaction; lets a cross-process retry replay. */
     assigned_ids?: Record<string, string>;
     /** Digest of the archive request that produced this row. */
@@ -223,6 +234,7 @@ export interface ChapterSummary {
             key: string;
             title: string;
             description: string;
+            anchor?: string;
         }>;
         advanced: Array<{
             key: string;
@@ -256,6 +268,8 @@ export interface RoundCounters {
     review: number;
     revise: number;
     check: number;
+    /** Lifetime rollback count on a chapter record; never stored in the live pipeline. */
+    rollbacks?: number;
 }
 /** How one ledger entity changed in this chapter. */
 export type DeltaAction = 'created' | 'updated' | 'no_change';
@@ -287,6 +301,8 @@ export interface ForeshadowDelta {
     action: DeltaAction;
     reason?: string;
     title?: string;
+    /** Verbatim manuscript quote used for verification; title stays a readable label. */
+    anchor?: string;
     description?: string;
     note?: string;
     new_info?: boolean;
@@ -329,6 +345,28 @@ export interface ArchiveHandoff {
     act?: string;
     act_progress?: string;
 }
+/** One issued task-book receipt; the brief itself is rendered on demand. */
+export interface BriefReceipt {
+    chapter: number;
+    stage: BriefStage;
+    digest: string;
+    issued_at: string;
+}
+/** `state/briefs.yaml`: append-only task-book evidence outside content transactions. */
+export interface BriefReceiptsDocument {
+    schema_version: 1;
+    receipts: BriefReceipt[];
+}
+/** The active draft's own metadata; P2 plan stays immutable after submission. */
+export interface DraftState {
+    chapter: number;
+    title: string;
+    scene_type: SceneType;
+    narrator: string;
+    summary: ChapterSummary;
+    content_hash: string;
+    updated_at: string;
+}
 /** Pipeline document (`state/pipeline.yaml`). */
 export interface PipelineState {
     schema_version: 1;
@@ -341,6 +379,8 @@ export interface PipelineState {
         digest: string;
     }>;
     blocking: BlockingItem[];
+    /** Current draft summary/title; never written into the P2 plan file. */
+    draft?: DraftState;
     /** Hash of the review document last written by submitReview/submitRevision. */
     review_digest?: string;
     last_action: {
@@ -420,6 +460,7 @@ export interface ForeshadowsDocument {
         status: 'planted' | 'dormant' | 'advanced' | 'resolved';
         resolved_at: number | null;
         description: string;
+        anchor?: string;
         advance_log: Array<{
             chapter: number;
             note: string;
@@ -526,6 +567,317 @@ export interface ChapterPlanInput {
     /** Optional in 0.1.3: older plans remain readable; new plans may name 1–8 actors. */
     cast?: ChapterCastMember[];
 }
+/** Book-level pitch and structure, persisted in `outline/outline.yaml`. */
+export interface BookPlan {
+    premise: string;
+    logline: string;
+    themes: string[];
+    tone: string;
+    pov: string;
+    audience: string;
+    selling_points: string[];
+    ending: string;
+    /** Strict mode requires a chapter card before P2/P3 for every chapter. */
+    strict: boolean;
+    /** True once the author explicitly chose strict on/off; used for the first-outline default. */
+    strict_explicit?: boolean;
+}
+/** One volume of the planned book. `end_chapter` is inclusive. */
+export interface OutlineVolume {
+    id: string;
+    title: string;
+    start_chapter: number;
+    end_chapter: number;
+    goal: string;
+    arc: string;
+    climax: string;
+    status: 'planned' | 'writing' | 'done';
+}
+/** One planned chapter card. Only the archive transaction may write the archived fields. */
+export interface OutlineChapter {
+    num: number;
+    volume: number | null;
+    title: string;
+    scene_type: SceneType;
+    goal: string;
+    conflict: string;
+    hook: string;
+    cast: string[];
+    target_words: [number, number];
+    notes: string;
+    status: 'planned' | 'archived';
+    archived_at: string | null;
+    word_count: number | null;
+    score: number | null;
+}
+/** The planning SSOT read by P1–P8, PG-13, report, doctor and export. */
+export interface OutlineDocument {
+    schema_version: 1;
+    updated_at: string;
+    book: BookPlan;
+    volumes: OutlineVolume[];
+    chapters: OutlineChapter[];
+}
+/** One worldbuilding rule/constraint. */
+export interface WorldbookRule {
+    name: string;
+    description: string;
+}
+/** One faction in the world bible. */
+export interface WorldbookFaction {
+    name: string;
+    description: string;
+    goal: string;
+}
+/** One location in the world bible. */
+export interface WorldbookLocation {
+    name: string;
+    description: string;
+    layout: string;
+    capacity: number;
+}
+/** One planned character (not the post-prose ledger entry). */
+export interface WorldbookCharacter {
+    name: string;
+    role: string;
+    description: string;
+    arc: string;
+}
+/** One glossary entry. */
+export interface WorldbookGlossary {
+    term: string;
+    definition: string;
+}
+/** One backstory event. */
+export interface WorldbookBackstory {
+    time: string;
+    event: string;
+}
+/** One declared numeric canon, checked against the manuscript on request. */
+export interface WorldbookFact {
+    alias: string;
+    value: number;
+    unit: string;
+    tolerance?: number;
+    note?: string;
+}
+/** Worldbuilding plan, persisted in `outline/worldbook.yaml`. */
+export interface WorldbookDocument {
+    schema_version: 1;
+    updated_at: string;
+    premise: string;
+    setting: string;
+    rules: WorldbookRule[];
+    factions: WorldbookFaction[];
+    locations: WorldbookLocation[];
+    characters: WorldbookCharacter[];
+    glossary: WorldbookGlossary[];
+    backstory: WorldbookBackstory[];
+    /** Optional numeric canon; old documents omit it. */
+    facts?: WorldbookFact[];
+    themes: string[];
+}
+/** One hit from `novel_search`; the scope names the source family. */
+export interface SearchResultItem {
+    kind: 'chapters' | 'summaries' | 'outline' | 'worldbook' | 'ledgers';
+    chapter?: number;
+    title?: string;
+    paragraph?: number;
+    snippet: string;
+}
+/** Search response; `total` counts every matching segment, `results` is capped by `limit`. */
+export interface SearchReport {
+    query: string;
+    scope: 'all' | 'chapters' | 'summaries' | 'outline' | 'worldbook' | 'ledgers';
+    total: number;
+    truncated: boolean;
+    results: SearchResultItem[];
+}
+/** One structured health check. */
+export interface DoctorCheck {
+    id: string;
+    severity: 'ok' | 'info' | 'warning' | 'error';
+    title: string;
+    detail: string;
+    hint?: string;
+}
+/** `novel_doctor` payload; a missing project is reported, never thrown. */
+export interface DoctorReport {
+    ok: boolean;
+    root: string;
+    checks: DoctorCheck[];
+    summary: {
+        errors: number;
+        warnings: number;
+        infos: number;
+    };
+}
+/** One canonical outline-progress calculation shared by every adapter. */
+export interface OutlineProgress {
+    present: boolean;
+    target: number | null;
+    total: number;
+    planned: number;
+    archived: number;
+    missingCards: number;
+    plannedCoverage: number | null;
+    archivedCoverage: number | null;
+    /** Compatibility alias: planned coverage when a target exists, otherwise card coverage. */
+    coverage: number;
+    /** Fraction of archived chapters that have a matching archived card. */
+    cardCoverage: number;
+    volumes: number;
+}
+/** Book-wide quality, outline, cast and pacing aggregates. */
+export interface BookReport {
+    progress: {
+        archived: number;
+        target: number | null;
+        words: number;
+        average_words: number;
+        percent: number;
+        remaining_words: number | null;
+        remaining_words_min: number | null;
+        remaining_words_average: number | null;
+        remaining_words_basis: 'actual_average' | 'minimum_target' | 'none';
+    };
+    outline: {
+        present: boolean;
+        strict: boolean;
+        target: number | null;
+        total: number;
+        planned: number;
+        archived: number;
+        missing_cards: number;
+        planned_coverage: number | null;
+        archived_coverage: number | null;
+        coverage: number;
+        card_coverage: number;
+        volumes: Array<{
+            title: string;
+            start: number;
+            end: number;
+            planned: number;
+            archived: number;
+        }>;
+        drift: Array<{
+            chapter: number;
+            field: string;
+            planned: string;
+            actual: string;
+        }>;
+    };
+    worldbook: {
+        present: boolean;
+        characters: number;
+        locations: number;
+        factions: number;
+        rules: number;
+        glossary: number;
+        backstory: number;
+        facts?: number;
+    };
+    quality: {
+        average: number;
+        median: number;
+        min: number;
+        max: number;
+        last_five: number[];
+        trend: number;
+        dimensions: Array<{
+            id: string;
+            average: number;
+            samples: number;
+        }>;
+    };
+    /** Per-chapter effort survives archive (pipeline rounds are reset). */
+    effort: {
+        reviews: number;
+        revisions: number;
+        checks: number;
+        rollbacks: number;
+        chapters: Array<{
+            num: number;
+            reviews: number;
+            revisions: number;
+            checks: number;
+            rollbacks: number;
+            final_check: 'pass' | 'fail' | null;
+            archived_at: string | null;
+        }>;
+    };
+    pacing: {
+        scene_types: Record<string, number>;
+        hook_strength: Record<string, number>;
+        plot_advancement: Record<string, number>;
+        longest: {
+            chapter: number;
+            words: number;
+        } | null;
+        shortest: {
+            chapter: number;
+            words: number;
+        } | null;
+    };
+    cast: {
+        total: number;
+        top: Array<{
+            name: string;
+            appearances: number;
+            last_seen: number;
+            role: string;
+        }>;
+    };
+    foreshadows: {
+        open: number;
+        dormant: number;
+        overdue: number;
+        resolved: number;
+        oldest: Array<{
+            id: string;
+            title: string;
+            last_touched: number;
+            age: number;
+        }>;
+    };
+    timeline: {
+        events: number;
+        first_chapter: number | null;
+        last_chapter: number | null;
+    };
+    relationships: {
+        total: number;
+        types: Record<string, number>;
+    };
+    activity: Array<{
+        at: string;
+        op: string;
+        chapter: number;
+        status: string;
+    }>;
+    warnings: string[];
+}
+/** One onboarding step. */
+export interface GuideStep {
+    id: string;
+    title: string;
+    detail: string;
+    done: boolean;
+    tool?: string;
+}
+/** `novel_guide` payload. */
+export interface GuideReport {
+    state: 'no-project' | 'new' | 'planning' | 'writing' | 'blocked' | 'finished';
+    title: string;
+    steps: GuideStep[];
+    next: {
+        tool: string;
+        args: Record<string, unknown>;
+        reason: string;
+    };
+    commands: string[];
+    tips: string[];
+}
 /** Draft submission payload. */
 export interface DraftInput {
     chapter: number;
@@ -544,10 +896,23 @@ export interface ReviewInput {
     total: number;
     proof: ReadingProof;
 }
+/** One exact, unique replacement used by patch-mode revisions. */
+export interface RevisionEdit {
+    old_text: string;
+    new_text: string;
+    /** 1-based occurrence; defaults to requiring exactly one match. */
+    occurrence?: number;
+}
+/** Patch-mode revision; content and patch are mutually exclusive. */
+export interface RevisionPatch {
+    expected_hash: string;
+    edits: RevisionEdit[];
+}
 /** Revision submission payload. */
 export interface RevisionInput {
     chapter: number;
-    content: string;
+    content?: string;
+    patch?: RevisionPatch;
     summary: ChapterSummary;
 }
 /** Semantic check items supplied by the model. */
@@ -598,6 +963,12 @@ export interface GateInput {
     /** The three preceding chapters, newest first, for the duplicate rule. */
     previousTexts: string[];
     priorSceneTypes: SceneType[];
+    /** 0.2.0 planning input; undefined means "no outline" for older fixtures. */
+    outline?: OutlineDocument | null;
+    /** The chapter plan's target range, used by PG-13. */
+    planTargetWords?: [number, number] | null;
+    /** The chapter plan's declared cast names, used by PG-13. */
+    planCast?: string[] | null;
 }
 /** Gate evaluation outcome. */
 export interface GateResult {
@@ -636,6 +1007,36 @@ export interface StatusReport {
     volume_name?: string;
     act?: string;
     act_progress?: string;
+    /** 0.2.0 book-level visibility; absent on older synthetic payloads. */
+    book?: {
+        premise: string;
+        logline: string;
+        strict: boolean;
+        outline: {
+            present: boolean;
+            target: number | null;
+            total: number;
+            planned: number;
+            archived: number;
+            missing_cards: number;
+            planned_coverage: number | null;
+            archived_coverage: number | null;
+            coverage: number;
+            card_coverage: number;
+            volumes: number;
+            current: OutlineChapter | null;
+        };
+        worldbook: {
+            present: boolean;
+            characters: number;
+            locations: number;
+            factions: number;
+            rules: number;
+            glossary: number;
+            backstory: number;
+            facts?: number;
+        };
+    };
     next: {
         tool: string;
         args: Record<string, unknown>;
@@ -654,6 +1055,8 @@ export interface AdviceReport {
 }
 /** One history row derived from the journal. */
 export interface AuditRow {
+    /** Stable chronological cursor; absent only on hand-built test rows. */
+    seq?: number;
     at: string;
     op: string;
     chapter: number;
@@ -661,6 +1064,14 @@ export interface AuditRow {
     txid: string;
     status: 'committed' | 'aborted';
     files: string[];
+    /** Machine code and human reason for a refused attempt. */
+    code?: string;
+    reason?: string;
+    hint?: string;
+    stage?: string;
+    /** True when no transaction started: the gate/input refused the call. */
+    attempt?: boolean;
+    blocking?: BlockingItem[];
 }
 /** One diff hunk between two revisions of a chapter. */
 export interface DiffReport {
@@ -674,5 +1085,5 @@ export interface DiffReport {
         line: string;
     }>;
 }
-/** Export capabilities. */
-export type ExportKind = 'md' | 'txt' | 'epub';
+/** Export capabilities; the last three are book-planning deliverables. */
+export type ExportKind = 'md' | 'txt' | 'epub' | 'outline' | 'worldbook' | 'proposal';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-novel-write-engine",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Novel writing engine for DeepSeek Harness: state machine, gates, rulepacks and ledgers moved from prompts into code.",
   "keywords": [
     "dsh-plugin",

package/presets/novel-write-engine.patch.yml

@@ -4,7 +4,7 @@
       config:
         id: novel-write-engine
         name: 网文工坊
-        description: 网文创作专用会话：18 个小说工具全开，无文件写权限，门控与字数由引擎裁决。
+        description: 网文创作专用会话：28 个小说工具全开，无文件写权限，门控与字数由引擎裁决。
         order: 20
         plugins:
           - id: persona

package/skills/entry.md

@@ -16,6 +16,10 @@ description: 引擎版小说创作流程——状态、门控、字数与写盘
 5. **不编设定。** 人物、地点、伏笔、资源状态拿不准就 `novel_state` 查。
 6. **归档是一次事务，且必须核销。** `novel_archive` 必须带 `state_delta`：本章每个角色/伏笔/事件/新设定/关系逐条声明 `created|updated|no_change`；不要手工拼章节索引或交接文件。
 
+## 书级规划（0.2.0）
+
+新项目先 `novel_guide`；推荐但不强制：`novel_blueprint`（蓝图/卷）→ `novel_outline`（章卡）→ `novel_worldbook`（设定集）。已有大纲可用 `novel_outline_import` 导入 Markdown/YAML/JSON。只要存在章卡，P2/P3 就按章卡校验标题、场景、字数与 cast；严格模式还要求章卡必须存在。要改已归档章先 `novel_reopen`（必须带 reason）。
+
 ## 流程路由
 
 | 当前阶段         | 任务书           | 下一动作             |
@@ -36,33 +40,43 @@ description: 引擎版小说创作流程——状态、门控、字数与写盘
 | 工具 | 用途 |
 | --- | --- |
 | `novel_init` | 建项目 |
-| `novel_status` | 当前章/阶段/阻塞/下一步 |
+| `novel_status` | 当前章/阶段/阻塞/书级摘要/下一步 |
+| `novel_blueprint` | 书级蓝图与卷结构 |
+| `novel_outline` | 卷/章卡 |
+| `novel_outline_import` | 导入 Markdown/YAML/JSON 大纲 |
+| `novel_worldbook` | 世界观设定集 |
+| `novel_search` | 搜索正文/大纲/世界观/台账 |
+| `novel_doctor` | 项目体检 |
+| `novel_report` | 全书报告 |
+| `novel_guide` | 上手引导与下一步 |
+| `novel_reopen` | 从归档备份重开紧邻的上一章 |
+| `novel_restore` | 从标记备份恢复活动章 |
 | `novel_brief` | 取阶段任务书与上下文 |
 | `novel_plan_world` | P1 世界观计划 |
 | `novel_plan_chapter` | P2 章节计划 |
 | `novel_write_draft` | P3 初稿 |
 | `novel_review` | P4 十五维评分 |
-| `novel_revise` | P5 修订 |
-| `novel_check` | P6 一致性校验 |
+| `novel_revise` | P5 修订（支持 exact patch） |
+| `novel_check` | P6 一致性校验（advisory 可 acknowledge） |
 | `novel_archive` | 归档事务 |
 | `novel_word_count` | 字数口径 |
-| `novel_state` | 只读台账/计划/评审 |
+| `novel_state` | 只读台账/计划/评审/history/backups/briefs |
 | `novel_amend` | 受控改状态文档 |
 | `novel_rollback` | 回退阶段 |
 | `novel_diff` | 与备份/文本对比 |
-| `novel_export` | md/txt/epub |
-| `novel_audit` | 事务审计 |
+| `novel_export` | md/txt/epub/outline/worldbook/proposal |
+| `novel_audit` | 事务与失败 attempt 审计 |
 | `novel_pipeline` | 推荐下一步与参数 |
 
 ## 工具怎么用
 
 - 参数是 JSON 对象；`summary`、`dimensions`、`issues`、`proof` 是结构化对象，按任务书字段填。
-- `novel_check` 必须带四个语义项（`L2-SCENE-ANCHOR` / `L2-CHARACTER-STATE` / `L2-CAUSALITY` / `L2-VOICE`），每项都要有正文逐字引用；缺一项即校验不过。
+- `novel_check` 必须带五个语义项（`L2-SCENE-ANCHOR` / `L2-CHARACTER-STATE` / `L2-CAUSALITY` / `L2-VOICE` / `L2-POV`），每项都要有正文逐字引用，且来自不同句子；缺一项即校验不过。
 - 失败分三类：参数错（改参数）、门控没过（改正文）、系统故障（查目录/稍后重试）。错误消息里的 code 说明属于哪类。
 - 门控失败会一次列出**全部**阻塞项；一次改完再交，不要逐条试。
 
 ## 交付
 
 - 每章归档后，用户在面板「网文工坊」看到章节表与阻塞区。
-- 导出：`novel_export md|txt|epub`。
+- 导出：`novel_export md|txt|epub|outline|worldbook|proposal`。
 - 不要在对话里重复整章正文；工具结果已经可见。