docs(spec): 后端开发规范基线 1.0——依据 PRD 1.0 与 spec 0.6 提炼

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.trellis/spec/backend/database-guidelines.md

@@ -1,51 +1,46 @@
-# Database Guidelines
+# 数据与存储规范
 
-> Database patterns and conventions for this project.
+> 版本：基线 1.0（2026-06-12）。依据：story-repo-spec 0.6 §11（缓存）、不变量 1/2、PRD §4-16（真源唯一）。
 
 ---
 
-## Overview
+## 1. 真源原则
 
-<!--
-Document your project's database conventions here.
+1.1 **文件即真相**：一本书的全部持久状态必须且只能存在于书仓库的 Markdown / YAML 源文件中（`定稿/`、`大纲/`、`文风/`）。禁止任何"只存在于数据库里"的状态。
 
-Questions to answer:
-- What ORM/query library do you use?
-- How are migrations managed?
-- What are the naming conventions for tables/columns?
-- How do you handle transactions?
--->
+1.2 多条记录必须**每条一个文件**（角色卡、伏笔、悬念、感情线、信息差各自成文件）；禁止大一统数据文件。自由文本归 Markdown 正文，front matter 只承载少量平铺短字段。
 
-(To be filled by the team)
+## 2. 唯一派生物：`.cache/index.db`
 
----
+2.1 全系统唯一允许的持久派生物是书仓库内的 `.cache/index.db`，必须使用 Node 内置 `node:sqlite`，必须 gitignored。
 
-## Query Patterns
+2.2 该缓存必须**任何时刻可删**：删除后系统从源文件全量重建，所有查询照常回答。"删光 `.cache/` 全量重建"是 CI 验收项。
 
-<!-- How should queries be written? Batch operations? -->
+2.3 **重建器即格式的参考实现**：重建器能完整重建，即证明源文件格式自洽。修改任何源文件格式时必须同步修改重建器。
 
-(To be filled by the team)
+2.4 表名属机器域，用英文：`chapters`、`threads`、`secrets`、`entities`、`fingerprints`。表设计必须支撑精准读取接口（PRD §3.6）的全部查询。
 
----
+## 3. 禁止事项
 
-## Migrations
+3.1 禁止引入第二个数据库、向量库（语义检索为可选插件，永不做事实召回主路径）、常驻服务。
 
-<!-- How to create and run migrations -->
+3.2 禁止任何形式的"投影/事件溯源"持久层（v6 教训：派生状态与作者手改冲突无解）。
 
-(To be filled by the team)
+3.3 禁止把缓存当真源读：业务逻辑必须能在"缓存刚被删光"的状态下正确工作（触发重建后照常返回）。
 
----
+## 4. 系统写出的结构化内容（防呆方言，CI 强制）
 
-## Naming Conventions
+4.1 front matter 与 `book.yaml` 必须**一律平铺**，禁止嵌套映射。
 
-<!-- Table names, column names, index names -->
+4.2 列表必须块格式（一行一条 `- 条目`），禁止行内 `[a, b]`。
 
-(To be filled by the team)
+4.3 凡可能被 YAML 误判类型的字符串值，写出时必须加引号。
 
----
+4.4 缩进统一两空格；编码 UTF-8 无 BOM。
 
-## Common Mistakes
+4.5 读取必须**容错**：遇到未知字段必须保留原样写回，禁止丢弃或报错。
 
-<!-- Database-related mistakes your team has made -->
+## 5. 待增量补充
 
-(To be filled by the team)
+- [ ] 各表的列定义与索引（实现 O4 精准读取接口时定稿）
+- [ ] 重建器的增量更新策略（全量重建 vs 按 commit 增量）

.trellis/spec/backend/directory-structure.md

@@ -1,54 +1,43 @@
-# Directory Structure
+# 目录结构规范
 
-> How backend code is organized in this project.
+> 版本：基线 1.0（2026-06-12）。依据：v7 PRD 1.0、story-repo-spec 0.6。v7 代码骨架落地后增量修订。
 
 ---
 
-## Overview
+## 1. 分支策略
 
-<!--
-Document your project's backend directory structure here.
+1.1 `master` 为 v6 维护线，**冻结**：仅允许致命 bug 修复，禁止合入任何 v7 工作。
 
-Questions to answer:
-- How are modules/packages organized?
-- Where does business logic live?
-- Where are API endpoints defined?
-- How are utilities and helpers organized?
--->
+1.2 `v7` 为主开发分支：所有 v7 工作的 PR base 必须设为 `v7`。
 
-(To be filled by the team)
-
----
-
-## Directory Layout
+## 2. 仓库顶层布局
 
 ```
-<!-- Replace with your actual structure -->
-src/
-├── ...
-└── ...
+webnovel-writer/                # 仓库根
+├── docs/architecture/          # 设计真源：v7-prd.md（产品决策）、story-repo-spec（格式）、multi-agent-adaptation-spec（多宿主）
+├── .trellis/                   # 开发流程层（任务/规范/日志），与产品代码无关
+├── webnovel-writer/            # v6 插件本体（遗产，禁止改动）
+├── requirements.txt pytest.ini # v6 Python 遗产（禁止改动；v7 禁止引入 Python）
+└── （v7 代码目录待定）          # npx 包骨架落地时修订本节
 ```
 
----
+2.1 **文档先行**：`docs/architecture/v7-prd.md` 是产品决策真源，两份 spec 是格式与多宿主行为真源。代码与文档冲突时以文档为准；变更行为必须先修订文档（走任务流程），再改代码。
 
-## Module Organization
+## 3. v7 产品代码布局原则（骨架待定，原则已定）
 
-<!-- How should new features/modules be organized? -->
+3.1 分发渠道只有 npx（`npx webnovel-writer init` / `update`），即单一 npm 包；禁止恢复插件市场分发。
 
-(To be filled by the team)
+3.2 运行时必须为 **Node ≥ 22，零第三方运行时依赖**；缓存必须使用内置 `node:sqlite`。任何引入运行时依赖的设计必须被驳回。
 
----
+3.3 用户侧安装产物布局（代码必须与之对齐）：
 
-## Naming Conventions
-
-<!-- File and folder naming rules -->
-
-(To be filled by the team)
-
----
+- 工作目录 ⊃ 书目录；插件本体住 `工作目录/.webnovel/`（Node 脚本、角色定义、模板哈希清单、`books.jsonl`）。
+- 书仓库内必须**零工程文件**（唯一例外：指路 `AGENTS.md`）；作者可见的目录名、文件名一律中文。
 
-## Examples
+3.4 文件排序必须依赖零填充数字前缀（`0152-`、`第05卷`、`伏笔-031`），禁止依赖中文字典序。
 
-<!-- Link to well-organized modules as examples -->
+## 4. 待增量补充
 
-(To be filled by the team)
+- [ ] npm 包内部 src/ 模块划分（安装器、状态机、机检、备料、定稿）——首个代码任务时定
+- [ ] 测试目录与命名约定
+- [ ] 题材模板与知识库在包内的存放位置

.trellis/spec/backend/error-handling.md

@@ -1,51 +1,43 @@
-# Error Handling
+# 错误处理规范
 
-> How errors are handled in this project.
+> 版本：基线 1.0（2026-06-12）。依据：PRD §1.4 产品原则 3/4、§3.5 状态机、§5 非功能需求（健壮性）；story-repo-spec 0.6 不变量 4、§10。
 
 ---
 
-## Overview
+## 1. 总原则
 
-<!--
-Document your project's error handling conventions here.
+1.1 **永不带堆栈崩溃**：任何面向作者的执行路径都禁止抛出未捕获异常。所有可预见的失败必须落入"修复确认"或人话提示兜底。
 
-Questions to answer:
-- What error types do you define?
-- How are errors propagated?
-- How are errors logged?
-- How are errors returned to clients?
--->
+1.2 **宁停勿崩**：无法安全继续时必须停下并说明状态，禁止带着不一致状态继续执行。
 
-(To be filled by the team)
+1.3 **可靠性来自自愈，不来自门禁**：能自动修复的先修复再报告；hook 语义必须是 ask，禁止 deny（v6 #113 教训）。
 
----
-
-## Error Types
-
-<!-- Custom error classes/types -->
-
-(To be filled by the team)
+1.4 **系统适应作者，不报错拒绝**：作者手改源文件是合法操作。检测到未入账手改必须提议补登，禁止报错、禁止拒绝启动。
 
----
-
-## Error Handling Patterns
+## 2. 错误分级与处理路径
 
-<!-- Try-catch patterns, error propagation -->
+| 级别 | 示例 | 必须采取的处理 |
+|---|---|---|
+| 可自愈 | `books.jsonl` 缺失/损坏；全角标点等结构性 YAML 错误 | 自动修复（扫描重建 / 预修复），只报不问 |
+| 需作者确认 | 源文件解析失败且涉及内容语义 | 修复确认：定位到行、提议保留作者意图的修复、作者确认后执行 |
+| 需作者决策 | git 异常（半提交/冲突/锁文件/网盘冲突副本） | 启动时 git 健康检查捕获，每种配自动修复或人话指引 |
+| 环境性 | Node 版本不足、不在工作目录启动 | 人话提示该做什么（升级 Node / 回工作目录），禁止英文报错 |
 
-(To be filled by the team)
+## 3. 原子性
 
----
+3.1 定稿必须原子：一次 git commit 要么完成，要么工作区原样保留，禁止中间态。所有多文件写入操作必须遵循同一模式——先全部准备好，再一次提交。
 
-## API Error Responses
+3.2 中断恢复：状态机启动时必须能识别"工作区有未完成流程"并从中断的阶段继续，禁止要求作者重来。
 
-<!-- Standard error response format -->
+## 4. 面向作者的错误文案
 
-(To be filled by the team)
+4.1 必须全中文、自然流畅；禁止出现堆栈、错误码、英文术语，也不强求口语化。
 
----
+4.2 必须说清三件事：发生了什么、影响是什么、作者现在该做什么（或系统已替作者做了什么）。
 
-## Common Mistakes
+4.3 提醒与错误必须区分："悬了太久"等账面提醒不是错误，禁止用错误语气呈现。
 
-<!-- Error handling mistakes your team has made -->
+## 5. 待增量补充
 
-(To be filled by the team)
+- [ ] Node 脚本层的错误类型定义与退出码约定（首个代码任务时定）
+- [ ] git 健康检查的完整异常清单与修复动作映射

.trellis/spec/backend/index.md

@@ -1,38 +1,36 @@
-# Backend Development Guidelines
+# 后端开发规范索引
 
-> Best practices for backend development in this project.
+> 本项目（webnovel-writer v7）的开发规范入口。规范条款的上游依据是 `docs/architecture/v7-prd.md`（产品法律文本）与两份 spec；本目录是其在开发执行层的落地。
 
 ---
 
-## Overview
+## 开发前检查清单（Pre-Development Checklist）
 
-This directory contains guidelines for backend development. Fill in each file with your project's specific conventions.
+写代码前必须确认：
 
----
+1. 已读当前任务的 `prd.md`；
+2. 已读本目录中与任务相关的规范文件（见下表）;
+3. 行为变更已先落进 PRD/spec（文档先行，见目录结构规范 §2.1）。
 
-## Guidelines Index
+## 规范索引
 
-| Guide | Description | Status |
+| 规范 | 内容 | 状态 |
 |-------|-------------|--------|
-| [Directory Structure](./directory-structure.md) | Module organization and file layout | To fill |
-| [Database Guidelines](./database-guidelines.md) | ORM patterns, queries, migrations | To fill |
-| [Error Handling](./error-handling.md) | Error types, handling strategies | To fill |
-| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | To fill |
-| [Logging Guidelines](./logging-guidelines.md) | Structured logging, log levels | To fill |
-
----
+| [目录结构](./directory-structure.md) | 分支策略、仓库布局、v7 代码布局原则 | 基线 1.0 |
+| [数据与存储](./database-guidelines.md) | 真源原则、`.cache/index.db`、防呆方言 | 基线 1.0 |
+| [错误处理](./error-handling.md) | 永不崩溃、错误分级、原子性、错误文案 | 基线 1.0 |
+| [质量规范](./quality-guidelines.md) | 零依赖、职责分界、CI 要求、评审清单 | 基线 1.0 |
+| [输出与日志](./logging-guidelines.md) | 作者界面域/机器域分离、报告文风 | 基线 1.0 |
 
-## How to Fill These Guidelines
+## 质量检查（Quality Check）
 
-For each guideline file:
+提交前必须过质量规范 §5 的评审清单。
 
-1. Document your project's **actual conventions** (not ideals)
-2. Include **code examples** from your codebase
-3. List **forbidden patterns** and why
-4. Add **common mistakes** your team has made
+## 维护方式
 
-The goal is to help AI assistants and new team members understand how YOUR project works.
+- 基线版（2026-06-12）依据 PRD 1.0 与 spec 0.6 提炼，先于 v7 代码存在；各文件末尾的"待增量补充"清单在对应代码任务落地时填实。
+- 每个任务收尾时按 workflow 阶段 3.3（spec update）评估是否有新约定要写回本目录。
 
 ---
 
-**Language**: All documentation should be written in **English**.
+**语言**：本目录文档用中文书写，行文采用严谨的规范体（必须/禁止/应当）。

.trellis/spec/backend/logging-guidelines.md

@@ -1,51 +1,38 @@
-# Logging Guidelines
+# 输出与日志规范
 
-> How logging is done in this project.
+> 版本：基线 1.0（2026-06-12）。依据：PRD §1.4 产品原则 6、§8 术语表；story-repo-spec 0.6 §8（commit 约定）。
 
 ---
 
-## Overview
+## 1. 两个域，严格分离
 
-<!--
-Document your project's logging conventions here.
+1.1 **作者界面域**（作者会看到的一切输出：对话文案、报告、文件名、front matter 字段名、提醒）：
 
-Questions to answer:
-- What logging library do you use?
-- What are the log levels and when to use each?
-- What should be logged?
-- What should NOT be logged (PII, secrets)?
--->
+- 必须全中文、零机器味；术语必须遵守 PRD §8 术语表，废止词（承诺/节奏债/棘轮/盘面/上下文包/合同/决策卡/验收卡 等）禁止出现。
+- 命名原则：网文圈原生词优先；圈内没有的用自然措辞；财务/工程/数据库隐喻禁止；禁止自造两字精简词。文案以自然流畅为准，不强求口语化。
+- 条目编号一律中文全称（伏笔-031、悬念-008、感情线-012、信息差-021），禁止缩写（伏-031）与 ASCII 编号（P-031）。
+- 禁止出现：堆栈、日志级别字样（ERROR/WARN）、英文报错、git 命令原文。
 
-(To be filled by the team)
+1.2 **机器域**（作者看不到、供脚本与诊断使用）：
 
----
-
-## Log Levels
-
-<!-- When to use each level: debug, info, warn, error -->
-
-(To be filled by the team)
-
----
-
-## Structured Logging
+- commit message 前缀固定 ASCII：`ch` / `vol` / `retcon` / `fix`（便于 `git log --grep`）。
+- `book.yaml` 的 `spec_version`、`.cache` 表名、`books.jsonl` 字段名等机器协议用英文，禁止为"全中文"目标改动机器协议。
 
-<!-- Log format, required fields -->
+## 2. 诊断信息
 
-(To be filled by the team)
+2.1 可诊断性依赖统一目录结构（强制项目级安装）：诊断输出应引导用户提供**目录清单**，而非日志文件。
 
----
+2.2 脚本内部诊断输出（stderr/调试信息）允许英文，但禁止混入作者界面域。
 
-## What to Log
+2.3 开发期调试日志禁止留在发布路径上；发布版脚本对作者的全部输出都属于作者界面域，受 1.1 约束。
 
-<!-- Important events to log -->
+## 3. 报告类输出的文风
 
-(To be filled by the team)
-
----
+3.1 全书近况、迁移报告、体检报告等必须先结论后细节，用作者的语言描述（"第 31 个伏笔从第 12 章埋下，悬了 140 章了"），禁止罗列原始数据。
 
-## What NOT to Log
+3.2 提醒不是错误（"悬了太久"是提醒）；报告中禁止用命令式或指责式语气。
 
-<!-- Sensitive data, PII, secrets -->
+## 4. 待增量补充
 
-(To be filled by the team)
+- [ ] 脚本 stdout/stderr 的用途划分与机器可读输出格式（JSON 行协议等，首个代码任务时定）
+- [ ] 调试开关的约定（环境变量名等）

.trellis/spec/backend/quality-guidelines.md

@@ -1,51 +1,56 @@
-# Quality Guidelines
+# 质量规范
 
-> Code quality standards for backend development.
+> 版本：基线 1.0（2026-06-12）。依据：PRD §1.4 产品原则 2/5、§5 非功能需求、§7 发布判据；story-repo-spec 0.6 §2.2。
 
 ---
 
-## Overview
+## 1. 运行时与依赖（硬约束）
 
-<!--
-Document your project's quality standards here.
+1.1 Node ≥ 22；**零第三方运行时依赖**。新增依赖的 PR 必须被驳回，除非先修订 PRD。
 
-Questions to answer:
-- What patterns are forbidden?
-- What linting rules do you enforce?
-- What are your testing requirements?
-- What code review standards apply?
--->
+1.2 禁止引入 Python、pip、.env；安装即用，无环境配置步骤。
 
-(To be filled by the team)
+1.3 开发期依赖（测试框架等）允许，但必须不进入发布产物。
 
----
+## 2. 职责分界（宪法级，评审必查）
 
-## Forbidden Patterns
+2.1 **脚本能做的归脚本，做不到的归 AI 语义判断**：可计数项（字数、频次、格式校验、关键词命中）必须用脚本实现，禁止让模型估算；语义判断（是否真泄密、正文是否写到了某事）必须归 AI，**禁止用正则硬凑语义判断**。
 
-<!-- Patterns that should never be used and why -->
+2.2 机检必须零 token；AI 调用次数每章有预算上限（实现时定数）。
 
-(To be filled by the team)
+2.3 **精准读取**：每类数据文件必须配"定位读到所需一段"的脚本接口；写作材料组装默认用片段，禁止默认整文件读取。
 
----
+## 3. 编码与平台（CI 强制）
 
-## Required Patterns
+3.1 一切文件 IO 显式 UTF-8 无 BOM；禁止依赖系统 locale。
 
-<!-- Patterns that must always be used -->
+3.2 Windows 中文环境是一等公民：CI 必须含 Windows 中文路径全链路测试（建库→写章→定稿→重建缓存）。中文路径、中文文件名在任何代码路径上都必须正确处理。
 
-(To be filled by the team)
+3.3 书仓库初始化必须设置 `git config core.quotepath false`。
 
----
+3.4 缩进两空格。
 
-## Testing Requirements
+## 4. 测试要求
 
-<!-- What level of testing is expected -->
+4.1 每个 CI 验收项对应 PRD/spec 的一条可验证承诺，最低集合：
 
-(To be filled by the team)
+- 删光 `.cache/` 全量重建，查询结果不变；
+- Windows 中文路径全链路；
+- 定稿原子性（中途失败时工作区原样保留）；
+- 防呆方言（系统写出的 YAML 平铺/块列表/危险值引号）。
 
----
+4.2 修 bug 必须附回归测试；同一问题第二次出现视为流程缺陷，必须复盘。
+
+## 5. 评审清单（PR 必过）
 
-## Code Review Checklist
+- [ ] 不新增运行时依赖、不引入 Python
+- [ ] 作者界面文案符合术语表（PRD §8），无废止词、无机器味
+- [ ] 错误路径符合错误处理规范（永不带堆栈崩溃）
+- [ ] 可计数逻辑在脚本里，语义判断不在正则里
+- [ ] 行为变更先改了文档（PRD/spec），代码与文档一致
 
-<!-- What reviewers should check -->
+## 6. 待增量补充
 
-(To be filled by the team)
+- [ ] lint / 格式化工具选型与配置（首个代码任务时定）
+- [ ] 测试框架选型（Node 内置 test runner 候选）与覆盖率要求
+- [ ] commit message 在开发仓库（本仓库）的前缀约定沿用现状：feat/fix/docs/chore

.trellis/tasks/00-bootstrap-guidelines/prd.md

@@ -21,8 +21,8 @@ the rest conversationally.
 
 ## Status (update the checkboxes as you complete each item)
 
-- [ ] Fill backend guidelines
-- [ ] Add code examples
+- [x] Fill backend guidelines (baseline 1.0, 2026-06-12 — derived from v7 PRD 1.0 + spec 0.6; v7 code does not exist yet, so rules codify decided constraints, not observed code)
+- [ ] Add code examples (deferred until the first v7 code task lands real code)
 
 ---