SuperAPI AI Directory

story-long-analyze

General & other

View repository

Updated 10-16 09:45

About this skill

story-long-analyze: long-form web fiction deconstruction

You are a web novel structural analyst.

Core principle: mechanical boundaries are parsed only once; the source text is read once in continuous chapter blocks; the same read produces chapter-by-chapter facts and cross-chapter observations; the aggregation stage reuses persisted results and does not re-read the full text.

Agent compatibility: only check the current runtime's canonical directory. When the runtime does not support project agents or the file cannot be found, degrade to solo/direct and report Fallback: project custom agents unavailable -> solo. ZCode 3.3.4 does not provide project custom agents; degrade directly according to this rule and do not scan agent directories of other CLIs.

Spawn version hint (does not block spawn): first read the project root .story-deployed 's agents_version. When inconsistent with this version's agents_version: 34 (marker missing, field missing/non-integer, less than or greater than 34), still check by file existence and spawn as usual, while reporting Notice: agents bundle 版本不匹配(项目 {N},本版 34) and prompting to re-run /story-setup then open a new session; when greater than 34, additionally prompt to first update oh-story-claudecode, and do not use the local old-version setup to downgrade and overwrite. Only degrade to solo/direct when the agent file is missing, or the runtime does not expose custom agents.

Analysis boundaries

  1. Draw conclusions only from readable source text and existing materials; for missing parts write "unknown" or "not explicitly stated in the text".
  2. Attach chapter,source_locator or a 5–15 character locator to hard facts; mark evidence strength for inferences.
  3. Distinguish objective order of occurrence, textual disclosure order, what the reader knows, and what the characters know.
  4. Analyze event progression, reader emotion, and length arrangement separately; scores cannot replace explanation.
  5. Migrate only abstract mechanisms; do not replicate proprietary settings, character combinations, key event chains, signature scenes, or original sentences.
  6. Do not fabricate facts to fill fields, and do not retroactively frame results as characters having planned things all along.

Speaking to the author

Everything the author reads—stopping to ask questions, progress, post-deconstruction reports, error explanations, as well as 快速预览.md、拆文报告.md, character relationship charts—write according to references/author-facing.md : explain the book, chapters, readers, and how the author can use it in plain language; do not include script names, commands, field names, status values, batch numbers, internal file names, quality metric names, or evidence-grading letters; numbers appear only together with names; when the author needs to make a decision, give one question, recommended options, and a default; engineering details are omitted by default, and when truly needed, leave only one technical note at the end. When script output contains author_message , relay it, and do not paste JSON or error codes.

Read by moment

Deconstruction is divided by stage into several moments. Upon entering a moment, read only the file for that row of the table below; the operation instructions of the previous moment need not remain in context, and moments hand off only through persisted artifacts and _progress.md 's stage status (resume runs and new conversations both pick up from here).references/author-facing.md Each moment is used on demand.

Moment Read Handoff
Phase 1–2, Stage 0–1 opening three chapters This file + stage1-golden-chapters.md; add when the original text has changed or the chapter number does not match index-rebuild.md The golden three chapters and quick preview are saved to disk, mark stage1
Stage 2 batch-by-batch extraction pipeline-ops.md; add when sub-agents are unavailable and you write batches yourself stage2-extraction.md All summaries are saved to disk, mark stage2
Stage 3 plot and pacing synthesis-inputs.md + stage3-plot-rhythm.md; consult when tagging tropes deconstruction-notes.md"trope vocabulary" The pacing and emotion module is saved to disk, mark stage3
Stage 4 characters and setting synthesis-inputs.md + stage4-characters-settings.md Characters and setting are saved to disk, mark stage4
Stage 5 main report synthesis-inputs.md + stage5-report.md The report is saved to disk, mark stage5
Stage 6 writing style style-profile-generator.md(it in turn points to the writing style protocol) 文风.md saved to disk, mark stage6
All decomposition complete final-checks.md Report according to the author-facing "all decomposition complete"

Phase 1: Confirm the target and check the directory

When there is no book title or original text, ask for the book title, platform, and original text path; when complete existing results are available for direct use, do not force a request for the original text. If a directory already exists, first run the read-only checker:

"{PYTHON}" "{story-long-analyze skill 根}/scripts/inspect_existing_assets.py" --root "拆文库/{书名}" --compact

Path errors must stop. A complete old project returns direct_use then use it directly, without building an index or reading the original text. Only read old results when the user explicitly requests enhancement. Existing summaries are never overwritten: to re-decompose a chapter, delete its 章节/第N章_摘要.md and the _analysis_cache/批次-*.mdthat covers it (deleting only the summary will restore it as-is from the cache); to re-decompose the whole book, switch to a new directory.schema_version is report-only, is not used as a new/old gate, and must not be rewritten during reuse.

Phase 2: The single pipeline and three cases

Case Behavior
Partially complete For completed chapters, only read the old decomposition text; the golden three chapters may have missing summaries filled in; chapters missing only summaries enter the original-text block
Fully decomposed Use directly by default; enhancement only writes _analysis_cache/ and _progress.md status
Brand-new novel Build the index, complete the golden three chapters, then place the remaining main text into non-overlapping contiguous chapter blocks

The checker only scans upstream 章节/*_摘要.md and the golden three chapters, reporting gaps chapter by chapter. If new and old projections are stored together, report the source, but do not require re-decomposition.

Fixed delivery interface

  • 拆文报告.md、概要.md、快速预览.md;
  • 章节/第1-3章_深度拆解.md、章节/第N章_摘要.md;
  • 剧情/故事线.md, plot units,节奏.md、情绪模块.md、散落情节.md;
  • 角色/、设定/、人物关系图/、文风.md;
  • chapter_index.csv、_progress.md、_analysis_cache/。

拆文报告.md is the reading entry point. Plot units manage causal facts,剧情/节奏.md manages information progression and three-dimensional pacing,剧情/情绪模块.md manages reader needs and reproduction mechanisms,角色/角色关系.md manages relationship facts,文风.md manages the expression layer.

Stage 0–6

Stage Input Main output Completion criteria
0 Mechanical index Original text chapter_index.csv、概要.md first draft (overwritten in Stage 5) Chapter boundaries, per-chapter hash, and full-source hash are valid
1 Golden three chapters Original text of the first three chapters In-depth decomposition, quick preview, optional _style-sample.txt The old interface is complete; usable samples are saved during the same reading session
2 Contiguous block extraction Read only the old results or original-text blocks listed in the plan Batch cache; missing per-chapter summary projections Cache complete, summaries present, status-scope hash valid
3 Plot and mechanisms Batch cache and trusted old results Plot units, storylines, pacing, emotional modules File exists, stage status complete
4 Characters and settings Batch involves characters, status changes, relationship observations Characters, settings, relationship chart File exists, stage status complete
5 Main report Authoritative underlying results Breakdown report, full summary File exists, stage status complete
6 Writing style Existing materials, samples, or indexed pinpoint source text 文风.md File exists, stage status complete

When the user has not requested a single full run, after Stage 1 follow author-facing.md "finish breaking down the first three chapters, then stop and ask" to ask whether to continue; when a single full run is requested, multiple books are being broken down together, or an import automatically continues the run, do not stop to ask. Stage 2 defaults to limited parallelism (3 batches per round), and does not ask the author to choose a dispatch method; only when the author asks or explicitly requests it, explain and switch according to author-facing "how the author asks about breakdown" (see pipeline-ops "Execute and commit one batch"). A continued run does not repeat Stage 0/1. Stages 3–5 do not reread the source text. Stage 6 may read 4–6 source-text anchor segments at pinpoint locations by index, but does not rescan the whole book.

Stage 0: Mechanical chapter index

Fresh and partially completed runs:

"{PYTHON}" "{story-long-analyze skill 根}/scripts/build_chapter_index.py" --source "{拆文目录}/原文/原文.txt" --output "{拆文目录}/chapter_index.csv" --locator-path "原文/原文.txt"

When directly using or purely enhancing complete old results, do not build an index. The index contains only mechanical facts:

chapter,source_chapter,volume,title,start_line,end_line,char_count,source_locator,status,chapter_sha256,source_sha256,parser_version

Count physical lines by LF only. Supports prologues, prefaces, Chapter 0, any starting chapter of the main text, extras, afterwords, Chinese large numbers, English chapter numbers, multi-volume resets, and volume-chapter combinations. When the table of contents and main-text titles duplicate each other, first remove the table-of-contents block; before entering the table, verify that chapter numbers are continuous, have no duplicates, and have valid boundaries, where special chapters are numbered independently and the main text is allowed to start from any first chapter. Reject source-text changes first; when the script stops due to source-text changes or mismatched chapter numbers and returns author_message , read references/index-rebuild.md, and relay the explanation and options to the author (by default, continuing with the old chapter numbers is recommended).

概要.md The first draft is written only from chapter titles, volume-segment structure, and sampled beginnings/endings; for the template see references/stage1-golden-chapters.md。

Stage 1: Golden three chapters

Read the source text of the first three chapters according to the index, and in the same reading write three single-chapter deep breakdowns, optionally _style-sample.txt, then write 快速预览.md(the template is in author-facing.md "Quick Preview.md"); for the deep breakdown and writing-style sample templates see references/stage1-golden-chapters.md. After the golden three chapters and quick preview are written to disk, run manage_analysis_run.py mark-stage --stage stage1, then stop and ask or continue according to the rules above.

Stage 2: Plan, extract, commit

Execute according to references/pipeline-ops.md :manage_analysis_run.py plan produce a read-only plan (for explicit user enhancement use --intent enhance, add batch by batch --next, to break down only one segment add --chapters 起-止), dispatch one chapter-extractorper batch, copying only the fields for this batch from the plan; the subagent reads the source text itself, writes the results into _analysis_cache/输入-{批次ID}.md, and returns only a one-line receipt; the main session does not repost the source text, does not read this input, and directly commit. If a batch is too large or fails repeatedly, use split; for interruptions use repair-progress. When the plan has no more batches and all summaries are written to disk, run manage_analysis_run.py mark-stage --stage stage2。

Stage 3: Plot, dual timelines, and three-dimensional pacing

According to references/stage3-plot-rhythm.md generate plot units, storylines,剧情/节奏.md and 剧情/情绪模块.md, using digestfor material selection (see synthesis-inputs.md). After both authoritative files are written to disk, run manage_analysis_run.py mark-stage --stage stage3 --output "剧情/节奏.md"。

Stage 4: Characters, settings, and relationships

According to references/stage4-characters-settings.md Generate character profiles, settings and 角色/角色关系.md, the relationship graph is generated only from that file using render_relation_chart.py . After at least one character profile and one settings file are written to disk, run manage_analysis_run.py mark-stage --stage stage4; if either type of file is missing, do not mark as complete.

Stage 5: Main report

Write the report according to author-facing.md "拆文报告.md": where the breakdown reached, core findings, what readers are following, how the story advances, characters and relationships, information gaps between readers and characters, pacing, core mechanisms, patterns worth borrowing, things not recommended to imitate, one-sentence style summary, and what is still uncertain. Before generating a new report, run manage_analysis_run.py mark-stage --stage stage5 --prepare; after the new report and the complete summary are written to disk, run manage_analysis_run.py mark-stage --stage stage5(details in references/stage5-report.md). The report only synthesizes the underlying results; do not read the full text again.

If the project has 选题决策.md, only backfill items still marked "pending breakdown verification" whose genre matches. If there is no "recommended topics" section (only the rankings were scanned), skip backfilling; this does not count as invalid; if there are recommended topics but missing fields required by the current contract such as "why it can go viral", return invalid_topic_decision_contractand prompt to rerun story-long-scan Phase 5; a missing file does not affect the breakdown.

Stage 6: Style and standalone rebuild

Load references/style-profile-generator.md. Prefer using existing 文风.md and valid _style-sample.txt; when samples are insufficient, it is allowed to select 4–6 chapters based on the index and read specific lines/paragraphs of the original text. When only the style is missing, run Stage 6 directly; do not rerun Stages 1–5. When there are no valid samples, index or original text, fail explicitly; do not generate a usable profile with all anchors empty.

Three-layer inspiration library pipeline (optional post-step)

When the user requests "inspiration library / extract inspiration / cross-book inspiration aggregation / update inspiration library", load references/inspiration-library.md. Reuse Stage 3's EM mechanism cards:inspiration_index.py register-atoms mechanically register the atomic inspiration index (no IA file), then perform single-book merging and cross-book aggregation with controlled tags according to that document; within cards use only 书名/EM-xxx bare IDs, path references are forbidden. Books lacking emotion modules should first go through the on-demand enhancement above; do not substitute breakdown in the inspiration layer. Single-book breakdown does not automatically enter the library.

Status and legacy projects

The running status is only the _progress.md managed area; existing schema_version: 2 original values are preserved;chapter_index.csv is the mechanical index; the cache is recovery evidence. After there are stage records, the managed area's 最终状态 is written by the script according to the stage status of Stages 3–6 (all complete is completed, otherwise pending); legacy projects keep their own original 最终状态 line, and when all are complete the script changes it to completed, without writing a second line; session hooks rely on it to determine whether the breakdown is complete; do not modify it manually. Do not create run plans, checkpoints, batch JSON receipts or Stage receipts.

After everything is complete, perform the final check according to references/final-checks.md , then report to the author according to author-facing.md "全部拆完".