Domů Procházet Nápověda
Registrovat se Přihlásit se
haiany
/
webnovel-writer
zrcadlo https://github.com/lingfengQAQ/webnovel-writer.git
1
0
Rozštěpit 0
Soubory Úkoly 0 Wiki
Strom: 05b09052d2
Větve Značky
webnovel-writer
/
.trellis
/
tasks
/
06-27-m1-format-core
/
prd.md

prd.md 15 KB
Historie Surový

M1 格式层核心库 + 派生缓存

Goal

实现 v7 的格式层基础设施，使系统能够可靠地读写 story repo 源文件，并通过缓存支撑精准读取。交付四层能力（依赖链）：① 容错读写库 → ② Storage Adapter 小端口 → ③ .cache/index.db 五表+重建器 → ④ 41 精准读取接口 CLI。出口：删光 .cache 全量重建测试绿 + 精准读取 41 接口逐条测试绿。

Background

上游就绪：

  • spec 0.8：格式法律文本（§1 不变量、§2-6 文件格式、§11 缓存）
  • O4 缓存设计（2026-06-26 定稿）：五表 DDL、41 接口清单、优先级分层
  • 实施计划 §1.5：架构原则（拆小端口、AI 不碰文件、状态机不判业务）
  • 后端规范基线 1.1：零依赖、node:sqlite、容错读取、防呆方言、永不带栈崩
  • M0 骨架：v7/src/storage/index.js、v7/src/cache/index.js 占位已存在

范围决策（2026-06-27）：

  • 本任务一次交付全 41 个精准读取接口（分 P0/P1/P2 三层实现、每层一 commit 检查点）
  • 不拆父子任务（四块是依赖链不是独立交付物，拆了反而增加跨任务状态管理成本）

Requirements

R1 容错读写库（格式解析与序列化）

R1.1 Front matter 读写

  • 解析章节文件的 YAML front matter（--- 包裹），提取结构化字段
  • 解析三类条目文件（伏笔/悬念/感情线）的 front matter + Markdown 正文分区（描述/收尾计划/履历）
  • 解析角色卡、信息差、世界观、名册文件
  • 容错：遇到未知字段必须保留原样（不变量 9）；YAML 解析失败返回错误对象（不崩溃）

R1.2 平铺 YAML 与 book.yaml

  • 读取 book.yaml 的平铺字段（spec §3）
  • 写出时强制防呆方言（spec §2.3、数据规范 §4）：
    • 一律平铺（禁止嵌套映射）
    • 列表块格式（- 项，禁 [a,b]）
    • 危险值加引号（数字串、含冒号/true/null 等易误判的字符串）
    • 两空格缩进、UTF-8 无 BOM

R1.3 时间线 Markdown 表格

  • 解析 定稿/设定/时间线/第NN卷.md 的 Markdown 表（| 章 | 书内时间 | 一句话事件 | 在场 |）
  • 提取行到结构化数组

R1.4 名册解析

  • 解析 定稿/设定/名册.md 表（| 正名 | 别名 | 类型 | 首现章 |）
  • 建立别名→正名映射

R2 Storage Adapter 小端口（架构原则 §1.5）

禁止上帝对象：不做 20 方法的 StoryRepo 大类，拆成职责最小的独立端口：

  • ChapterReader：读章节 front matter、正文、指定范围
  • ChapterWriter：写新章到定稿（M2 调用，本任务只定接口）
  • ThreadLedgerReader：读三类条目（伏笔/悬念/感情线）基本信息、履历、收尾计划
  • ThreadLedgerWriter：更新条目状态、追加履历（M2 调用，本任务只定接口）
  • EntityReader：读角色卡、解析别名、列出实体
  • TimelineReader：读指定卷时间线、按在场过滤
  • SecretReader：读信息差基本信息、内容
  • OutlineReader：读总纲/卷纲指定小节
  • BookConfigReader：读 book.yaml

每个端口只暴露 2-5 个方法，调用方按需依赖（权限最小化）。

R3 .cache/index.db 五表与重建器

R3.1 五表 DDL（O4 §1，表名英文、内容中文）

  • chapters：章 front matter 展开（章号/标题/卷/视角/章定位/钩子/情绪定位/字数/file_path）
  • threads：三类条目统一存放（id/type/short_title/strength/status/opened_chapter/planned_end/last_advanced_chapter/file_path）
  • secrets：信息差（id/short_title/known_to JSON/reader_knows/registered_chapter/keywords JSON/file_path）
  • entities：名册（id 即正名/type/status/location/realm/possessions JSON/last_changed_chapter/file_path）
  • entity_aliases：别名表（alias PK/entity_id FK）
  • fingerprints：文体指纹（chapter_range_start+end 复合 PK/is_baseline/常用特征列/fingerprint_data JSON）

索引：按 O4 §1 各表建必要索引（volume_num、type、status、reader_knows、is_baseline 等）

R3.2 重建器（node:sqlite，O4 §4）

  • 输入：只读 定稿/、大纲/、文风/（不读工作区）、book.yaml
  • 输出：全量重建五表（DELETE 旧数据 → 扫描源文件 → INSERT）
  • 校验：
    • 履历证据章节文件存在性（spec 0.8 A3 决策）
    • 别名唯一性（同一别名不能指向多个实体）
  • 触发：.cache/index.db 不存在或损坏时
  • 不做：语义验证（履历真假、泄密真假）→ 两审负责

R3.3 派生值策略（O4 §0 原则 5）

  • 不物化：悬了太久章数（当前最大章号 − last_advanced_chapter）、信息差蓄积章数、是否超期 → 查询时算
  • 不存：随当前章号漂移的任何值
  • 理由：避免每章定稿刷新全表，避免失同步

R4 精准读取接口 CLI（41 个，O4 §2）

命令式 API：每个接口是一个明确的脚本命令，可在 CLI 调用、AI 友好、默认精准、统一 JSON/文本输出。

P0（8 个，写章流程依赖）：

  • 时间线：读当前卷+上一卷
  • 条目：读条目基本信息、读条目履历
  • 正文：读近 N 章结尾、读章摘要
  • 设定：读角色卡 front matter、解析别名
  • 报表：悬了太久清单

P1（7 个，机检与全书近况）：

  • 正文：读章节 front matter、按章定位筛选
  • 信息差：列出未揭晓信息差
  • 全文检索：关键词全文检索
  • 报表：全书统计摘要、连续弱钩计数

P2（26 个，AI 角色与自动模式优化）：

  • 条目：读条目收尾计划、读条目描述、列出某类型条目、按强度筛选
  • 大纲：读总纲指定小节、读总纲结局段、读卷纲全文、读卷纲指定小节、列出所有卷纲
  • 正文：读章节正文、读章节结尾 N 字、读章节开头 N 字、读章节范围摘要
  • 时间线：读当前卷、读指定卷、按在场角色筛选
  • 设定：读角色卡完整、读角色卡指定小节、列出所有角色、读世界观指定小节
  • 信息差：读信息差内容
  • 全文检索：正则表达式检索
  • 报表：信息差蓄积报表、文体漂移报告、条目活跃率报表

完整清单见 O4 §2.2-2.9 各表（本 PRD 不重复列全部参数）。

Constraints

技术约束（后端规范 + spec 不变量）

C1 零第三方依赖（质量规范 §1.1）

  • 缓存用 node:sqlite（内置）
  • 测试用 node:test + node:assert（内置）
  • 唯一例外：YAML 解析用 js-yaml（MIT、零传递依赖、YAML 规范复杂不适合手写）；序列化手写（简单、可控）

C2 容错与防呆（不变量 1/9，数据规范 §4）

  • 任何源文件解析失败不得崩溃，返回错误对象
  • 未知字段保留原样写回
  • 系统写出的 YAML 强制防呆方言（平铺/块列表/危险值引号）

C3 编码与平台（质量规范 §3）

  • 所有文件 IO 显式 UTF-8 无 BOM
  • Windows 中文路径必须正确处理（CI 验收项）
  • 文件排序靠零填充数字前缀（0152-、伏笔-031），不依赖中文字典序

C4 职责分界（质量规范 §2.1）

  • 本任务只做脚本能做的：文件 IO、格式解析、SQL 查询、字符串拼接
  • 不做语义判断（履历真假、泄密真假）→ 两审负责
  • 禁止用正则凑语义判断

C5 错误处理（错误规范 §1）

  • 永不带堆栈崩溃
  • 面向作者的错误全中文、说清发生了什么/影响/该怎么办

Acceptance Criteria

核心验收（CI 强制）

AC1 删光 .cache 全量重建（不变量 2）

  • .cache/index.db 不存在时，首次查询触发全量重建
  • 重建后五表填充完整，所有查询正确返回
  • 删除 .cache/ 后再次查询，行为不变（可重建）
  • CI 测试：删缓存→重建→验证查询结果与预期一致

AC2 41 精准读取接口逐条测试

  • 每个接口有至少一个测试用例（喂真实 fixture 或 mock 数据，断言输出格式与内容）
  • P0 接口测试覆盖典型输入与边界（空结果、不存在的 ID、范围越界）
  • P1/P2 接口至少有正常路径测试

AC2 权威 41 接口清单（对齐 O4 §2.2-2.9，命令层测试逐条核对此表）：

# 分类 接口 命令
1 条目 读条目基本信息 read-thread <id> --fields=基本信息
2 条目 读条目履历 read-thread <id> --履历
3 条目 读条目收尾计划 read-thread <id> --收尾计划
4 条目 读条目描述 read-thread <id> --描述
5 条目 列出悬了太久 list-threads --悬了太久
6 条目 列出某类型 list-threads --type=<t> [--status=<s>]
7 条目 按强度筛选 list-threads --strength=高
8 大纲 读总纲指定小节 read-outline --总纲 --section=<标题>
9 大纲 读总纲结局段 read-outline --总纲 --结局
10 大纲 读卷纲全文 read-outline --卷=<N>
11 大纲 读卷纲指定小节 read-outline --卷=<N> --section=<标题>
12 大纲 列出所有卷纲 list-volumes
13 正文 读章节 front matter read-chapter <num> --front-matter
14 正文 读章节正文 read-chapter <num>
15 正文 读章节结尾 N 字 read-chapter <num> --tail=<N>
16 正文 读章节开头 N 字 read-chapter <num> --head=<N>
17 正文 读章摘要 read-chapter <num> --摘要
18 正文 读章节范围摘要 read-chapters --range=<a>-<b> --摘要
19 正文 读近 N 章结尾 read-chapters --recent=<N> --tail=<M>
20 正文 按章定位筛选 list-chapters --章定位=推进 [--卷=<N>]
21 时间线 读当前卷 read-timeline --current-volume
22 时间线 读当前卷+上一卷 read-timeline --current-and-prev
23 时间线 读指定卷 read-timeline --卷=<N>
24 时间线 按在场筛选 read-timeline --在场=<角色名>
25 设定 读角色卡 front matter read-character <name> --front-matter
26 设定 读角色卡完整 read-character <name>
27 设定 读角色卡指定小节 read-character <name> --section=<标题>
28 设定 解析别名 resolve-alias <别名>
29 设定 列出所有角色 list-characters [--status=<s>]
30 设定 读世界观指定小节 read-worldview --section=<标题>
31 信息差 读信息差基本信息 read-secret <id> --基本信息
32 信息差 读信息差内容 read-secret <id> --内容
33 信息差 列出未揭晓 list-secrets --reader-knows=false
34 检索 关键词全文检索 grep-story <关键词>
35 检索 正则检索 grep-story --regex=<pattern>
36 报表 悬了太久清单 report-overdue-threads
37 报表 信息差蓄积 report-secret-accumulation
38 报表 文体漂移（M1 边界：读表对比基线，不做特征提取） report-style-drift
39 报表 条目活跃率 report-thread-activity --卷=<N>
40 报表 连续弱钩计数 report-weak-hook-streak
41 报表 全书统计摘要 report-book-stats

合计 7+5+8+4+6+3+2+6 = 41，分布于 21 个命令文件（多接口共享文件，靠 --选项 分流）。

AC3 容错读取（不变量 9）

  • front matter 含未知字段时，解析不崩溃，字段保留
  • 写回时未知字段原样出现在输出 YAML 中
  • 测试：构造含 自定义字段: 值 的章节文件，读→改标题→写，自定义字段不丢失

AC4 防呆写出（数据规范 §4）

  • 写出的 front matter 一律平铺（无嵌套映射）
  • 列表一律块格式（每行 - 项）
  • 危险值加引号（"123" 不误判数字、"true" 不误判布尔）
  • 测试：写含列表/数字串/含冒号字符串的 YAML，手工验证输出格式

AC5 Windows 中文路径全链路（质量规范 §3.2）

  • CI Windows job 包含中文目录名与文件名的 fixture
  • 读写、重建、查询全流程在中文路径下通过

接口行为验收（抽查典型）

AC6 章节读取

  • read-chapter <num> --front-matter：返回 JSON 含章号/标题/卷/视角等字段
  • read-chapter <num> --tail=500：返回正文末尾 500 字（不含 front matter）
  • 不存在的章号返回明确错误（不崩溃）

AC7 条目读取

  • read-thread <id> --fields=基本信息：返回强度/状态/开启章/预计收尾
  • read-thread <id> --履历：返回履历列表（按章号排序）
  • list-threads --悬了太久：计算 当前最大章号 − last_advanced_chapter，返回超过阈值的条目（阈值从 book.yaml 读取）

AC8 别名解析

  • resolve-alias <别名>：返回正名
  • 未登记别名返回"未找到"（不崩溃）
  • 同一别名指向多个正名时，重建器报错（别名唯一性校验）

AC9 报表生成

  • report-overdue-threads：按类型分组返回悬了太久的条目清单
  • report-book-stats：返回总章数/总字数/条目数/角色数
  • report-weak-hook-streak：返回末尾连续弱钩章数

AC10 重建器校验

  • 履历引用不存在的章节文件时，重建器记录警告（不阻断重建，但输出可见）
  • 别名冲突时，重建器报错并拒绝重建

架构验收

AC11 小端口分离（架构原则 §1.5）

  • storage/ 导出至少 8 个独立 reader 端口（ChapterReader / ThreadLedgerReader / EntityReader / TimelineReader / SecretReader / OutlineReader / BookConfigReader + 未来 Writer 占位）
  • 每个端口方法数 ≤ 5
  • 测试中可单独 import 某一端口，不依赖其他端口实例化

AC12 测试镜像 src

  • v7/test/storage/ 与 v7/src/storage/ 镜像
  • v7/test/cache/ 与 v7/src/cache/ 镜像
  • 测试文件命名 *.test.js

Out of Scope

  • ❌ Writer 端口的真实实现（M2 定稿流程调用，本任务只定接口占位）
  • ❌ 增量更新缓存（定稿时只写变化行）→ M2 优化
  • ❌ 文体指纹特征提取算法（fingerprints 表建好但留空，特征提取随 M3+ 体检/卷复盘补）；report-style-drift 接口存在、能读表并对比基线，但 M1 不实现特征提取函数
  • ❌ 向量库与语义检索（可选插件，7.x）
  • ❌ CLI 子命令注册机制优化（当前动态 import 按命令名加载，M3+ 可做统一注册表）

Open Questions

无阻断问题。以下为实施细节，进入 design 阶段决策：

  • YAML 库选型：js-yaml（零依赖、MIT）vs 手写轻量解析器？
  • 测试 fixture 布局：v7/test/fixtures/ 放示例书仓库？
  • CLI 命令 41 个如何组织：全扁平 bin/commands/*.js 还是按类型分组子目录？
  • 文体指纹 fingerprints 表在 M1 只建表结构 + 占位查询接口，特征提取函数留桩——这个边界在 design 明确

Notes

  • 本任务是 M2-M6 的地基：M2 写章流程脚本依赖 P0 接口、M3 状态机依赖全书近况、M4 AI 角色依赖完整读取面
  • 四块交付物是依赖链（容错读写库 → 小端口 → 五表+重建 → 41 接口），不拆父子任务
  • 实施分四阶段（每阶段一 commit）：① 容错读写库 → ② Storage Adapter 端口 → ③ 五表+重建器 → ④ 41 接口分层（P0→P1→P2，每层 sub-commit）
  • 后端规范 + spec 0.8 + O4 是法律文本，本 PRD 与之冲突时以它们为准