# 项目文件与产物协议

#### 项目文件结构

需落盘时在用户指定目录按下表组织；只讨论不建工程，仅规划只创建本次产物所需目录，不为凑齐目录树生成正文或追踪：

```
{书名}/
├── 设定/
│   ├── 世界观/
│   │   ├── 背景设定.md        # 时代背景、地理、历史
│   │   ├── 力量体系.md        # 修炼/能力/等级体系
│   │   └── ...
│   ├── 角色/
│   │   ├── 沈栀.md            # 每个人物一个文件，文件名用角色名
│   │   └── ...
│   ├── 势力/
│   │   ├── 天机阁.md          # 每个势力/组织一个文件
│   │   └── ...
│   ├── 关系.md                # 角色关系映射
│   ├── 题材定位.md            # 题材核心梗+对标分析+终局底牌/升级台阶（防写无可写）
│   ├── 文风.md                # 本书自定义文风（可选）
│   └── 题材正文提示卡.md       # 题材正文核心：边界/期待/爽点/节奏/禁漂移
├── 大纲/
│   ├── 大纲.md                # 全书卷级结构
│   ├── 卷纲_第一卷.md         # 每卷一个：卷契约+故事线+剧情单元卡+情绪弧线+人物弧线+伏笔+反转
│   ├── 排纲底稿_L1-01.md      # 每单元一份：供给自查+建纲追加
│   └── 细纲_第001章.md        # 每章一个：九个必填字段+四个小节+结尾设定和钩子
├── 正文/
│   ├── 第001章_章名.md
│   └── ...
├── 对标/                          ← 拆文产出的结构化资产
│   └── {对标书名}/
│       ├── 原文/第001章_章名.md
│       ├── 章节/第K章_摘要.md
│       ├── 角色/                  ← 从拆文库/结构化输出同步
│       │   └── {角色名}.md
│       ├── 剧情/                  ← 从拆文库/结构化输出同步
│       │   ├── {剧情单元名}.md
│       │   ├── 故事线.md
│       │   ├── 节奏.md             # 关键信息推进 + 情绪触动点 + 爆发节奏（权威节奏索引）
│       │   └── 情绪模块.md         # 读者需求/情绪引擎 + 可复现模块（权威模块索引）
│       ├── 设定/                  ← 从拆文库/结构化输出同步
│       │   ├── 世界观/{主题}.md
│       │   └── 势力/{势力名}.md
│       ├── 文风.md
│       └── 拆文报告.md
├── 追踪/
│   ├── _tracking-state.json        ← 唯一结构化权威状态
│   ├── 上下文.md                  ← 派生续写状态卡（固定 7 栏），≤12KB
│   ├── 逐章记录/第NNN章.md          ← 未来相关紧凑记录，≤3072 字节
│   ├── 角色状态/{角色名}.md         ← 派生核心角色当前快照
│   ├── 伏笔.md                    ← 派生伏笔当前视图
│   └── 时间线/{作者真相.md,读者已知.md}
├── 参考资料/
│   └── {topic}.md             # story-researcher 输出的研究资料
├── .story/work/第NNN章/        ← 本章临时文件（分组 segment、prompt 留档、事务 JSON），提交后自动删除
```

**产物映射表**（创建模板详见 [references/artifact-protocols.md](artifact-protocols.md)）：

| 文件 | 粒度 | 创建阶段 | 读取时机 |
|------|------|---------|---------|
| 设定/关系.md | 全书 | Phase 2 | 按需：story-explorer relationship 查询、story-review 查设定（不在每章写作回路里逐章读） |
| 设定/题材定位.md（含 `主对标书` 字段，多对标时必填） | 全书 | Phase 1 建，Phase 2 补全 | Phase 3 大纲、每卷开始前、Phase 4 写前召回 |
| 设定/题材正文提示卡.md | 全书/题材 | 写第 1 章前由写前召回生成 | Phase 4 每章写作前：按 `genre-prose-cards.md` 索引匹配后读取 `genre-prose-cards/` 目录对应单题材卡优先、`style-genre-modules.md` 通用模块兜底，与通用正文要求、情绪/节奏召回和文风一起组装 prompt |
| 设定/角色/{角色名}.md、设定/势力/{名}.md | 角色/势力 | Phase 2 建主角与关键角色；Phase 3 细纲后增量补全 | Phase 4 状态筛选/写作 |
| 设定/文风.md（自定义文风·优先级最高） | 本书 | 用户自写（Claude Code 可代写）；导入/拆解不覆盖 | Phase 4 每章写作前：含实质内容则取代对标文风作权威风格基 |
| 对标/{书名}/文风.md | 对标书 | analyze Stage 6 输出 → story-import 显式绑定或本 skill 首次引用时同步 | Phase 4 每章写作前（文风召回；有自定义文风时降为参考/句长兜底） |
| 大纲/卷纲_第X卷.md | 卷 | Phase 3 | **一律走取段器 `outline_view.py --unit/--contract/--toc`，不整读**（见「路径与术语约定」）；段位契约与 checker 见 artifact-protocols.md |
| 大纲/排纲底稿_{单元ID}.md | 剧情单元 | Phase 3；正文「细纲没给」追加进「建纲追加」 | 只在排纲/补纲时读 |
| 追踪/_tracking-state.json | 全书 | 首次写正文前初始化（规划阶段不建） | 唯一结构化权威，不进正文 prompt；每章运行 `tracking_commit.py check` 读取章号和修订号 |
| 追踪/伏笔.md | 全书当前视图 | 与 state 同时初始化 | 续写状态卡缺项时按 ID 定点查询；每 ID 只一行 |
| 追踪/时间线/{作者真相.md,读者已知.md} | 全书当前事实/认知派生视图 | 与 state 同时初始化 | 按作者真相或读者认知的实际问题选择视图 |
| 对标/{书名}/拆文报告.md | 对标书 | 用户手动+analyze | Phase 2 核心设定、Phase 3 大纲、Phase 4 写作 |
| 追踪/逐章记录/第NNN章.md | 章 | Phase 4 每章事务 | 日更默认不整读，查历史原因时定点读取；目标 ≤1536 字节、硬上限 3072 字节，按需查询历史原因 |
| 追踪/上下文.md（续写状态卡，≤12KB） | 全书当前状态 | 与 state 同时初始化 | 日更每章整份读；由事务工具整份重建，固定 7 栏 |
| 参考资料/{topic}.md | 按需 | Phase 4（story-researcher 输出） | Phase 4 后续章节写作时复用 |
| 追踪/角色状态/{角色名}.md | 核心角色 | 首次进入正文或导入初始化 | 久别角色按名读取一个小快照；目标 ≤4096 字节、硬上限 8192 字节；静态人设仍读 `设定/角色/` |
| 对标/{书名}/角色/{角色名}.md | 对标书 | analyze 输出 | Phase 4 模块召回（角色参考） |
| 对标/{书名}/剧情/{剧情单元名}.md | 对标书 | analyze 输出 | Phase 3 卷纲选段与细纲成批（剧情单元卡「对标剧情参照」）、Phase 4 模块召回（剧情模块参考） |
| 对标/{书名}/剧情/情绪模块.md | 对标书 | analyze Stage 3 输出 → story-import 显式绑定或本 skill 首次引用时同步 | Phase 2 核心设定、Phase 3 大纲、Phase 4 每章写作前（读者需求 / 情绪引擎、可复现模块选择） |
| 对标/{书名}/剧情/节奏.md | 对标书 | analyze Stage 3 输出 → story-import 显式绑定或本 skill 首次引用时同步 | Phase 3 大纲、Phase 4 每章写作前（关键信息推进、情绪触动点、爆发节奏参考） |
| 对标/{书名}/设定/*.md | 对标书 | analyze 输出 | Phase 2 设定参考、Phase 4 世界观约束 |

**缺失文件处理**：先按进度、报告总章数与逐章覆盖识别资料代际；当前契约缺项时显式修复，不拼装降级结果：
1. **角色状态文件缺失** → 当前协议项目先运行 `tracking_commit.py check`，再重跑产生该状态的完整事务；已有正文但 `_tracking-state.json` 缺失时重新 `/story-import`。不得从前文临时推断后直接手写快照。
2. **角色、普通剧情单元或设定等非主产物子目录缺失** → 按「对标书路径查找」查找项目视图与根目录数据源，仍缺失则跳过该可选模块。本条不适用于 `剧情/情绪模块.md` 和 `剧情/节奏.md`。
3. **全量召回时 `剧情/情绪模块.md` / `剧情/节奏.md` 缺失** → 写前准备必须停下，设置 `missing_primary_contract: true` 并给出 `repair_action`：重跑 `/story-long-analyze` Stage 3+ 或重新 `/story-import`，不得用摘要文件假装已召回权威模块。成熟项目短路径按 benchmark-recall.md 的条件判定。
4. **有对标书但 `文风.md` 缺失** → 若有 `设定/文风.md`（含实质内容）走自定义文风模式继续；否则日更文风召回 fail-fast，请作者用 `/story-long-analyze` 给这本对标书补跑 Stage 6 文风分析；之后首次写作引用时会同步到 `对标/`。**完全无对标项目**则跳过文风召回、不阻塞（有 `设定/文风.md` 时用它写作）。全量召回的情绪/节奏轴（`missing_primary_contract`）独立，自定义文风模式本身不豁免其 fail-fast。
5. **伏笔/时间线文件缺失** → 视为当前状态损坏，停止写正文；先运行 `tracking_commit.py check`，再用事务修复。卷纲/大纲中的计划不能代替已发生的事实。
6. **`设定/题材正文提示卡.md` 缺失** → 不阻塞；写前从 `设定/题材定位.md` 精确匹配 `references/genre-prose-cards.md` 索引，并只读取 `references/genre-prose-cards/` 中对应题材单卡（高/中/低置信照原卡标注），无命中再用 `references/style-genre-modules.md` 通用流派模块即时生成短 `genre_prose_card`。只有 `设定/题材定位.md` 也缺失时，退回细纲和目标平台做低置信题材卡，并在意图确认写明。

**对标分析权威优先级（权威读取顺序）**：
1. `剧情/情绪模块.md` 是读者需求 / 情绪引擎、爽文套路框架、可复现模块和重组指南的权威来源。
2. `剧情/节奏.md` 是关键信息推进（含扩写方式）、情绪触动点和爆发节奏的权威来源。
3. `文风.md` 只管句长、标点、对话潜台词、原文锚点等风格；它不能覆盖情绪模块或节奏意图。**自定义文风 `设定/文风.md`（用户自写、不被导入/拆解覆盖）优先级高于对标 `文风.md`**：含实质内容时作权威风格基，对标文风降为参考与句长数值兜底；句长、停顿标点、视角与修辞按 `references/style-resolution.md` 裁决；段间空行等文件结构仍按交付协议，不把通用表达禁令称为硬安全线。
4. `章节/第K章_摘要.md` 是具体章节证据，用来校验和补足权威索引，不反向覆盖 `情绪模块.md` / `节奏.md`。
5. `拆文报告.md`、`剧情/故事线.md` 是投影/摘要；若与 `剧情/情绪模块.md` 或 `剧情/节奏.md` 冲突，写作以两个权威文件为准，并在写前准备 `gaps.conflict` 记录冲突来源。
6. **公共灵感召回**（工作区有 `灵感库/` 时）按任务标签选 Top 3–8 张 active CBA；不传 IA/NM，不把灵感卡当风格样本；灵感卡只影响设计选择，与上述权威文件或细纲事实冲突时以后者为准。

**文件组织原则：**
- **人物一个一个文件**：`角色/角色名.md`，方便按需读取
- **势力一个一个文件**：`势力/势力名.md`，组织/门派/家族/国家等
- **世界观按主题拆分**：背景、力量体系、社会结构等各自独立
- **细纲一章一个文件**：`细纲_第XXX章.md`，含钩子设计，与正文一一对应
- **正文按章拆分**：每章一个文件，`第XXX章_章名.md`
- 每章写完直接写入 `正文/` 目录，不要先输出到对话

`/story-long-analyze` 产出在 `拆文库/`，首次引用时同步到项目 `对标/`。