sillyspec 3.24.4 → 3.24.6

package/.claude/skills/sillyspec-scan/SKILL.md

@@ -1,74 +1,74 @@
----
-name: sillyspec:scan
-description: 用于扫描项目代码库，生成架构文档、代码约定、目录结构等。适合用户说"扫描项目、分析代码库、生成文档、scan"。产出 7 份扫描文档 + 模块映射。
----
-
-## 何时使用
-
-- 用户说"扫描项目、分析代码库、生成文档、scan"
-- 棕地项目首次接入 sillyspec，生成架构/约定/结构等基础文档
-- 产出 7 份 scan 文档（PROJECT/ARCHITECTURE/CONVENTIONS/STRUCTURE/INTEGRATIONS/TESTING/CONCERNS）+ 模块映射
-
-## 多变更说明
-
-scan 是辅助阶段，通常不需要 `--change`。但项目有多个活跃变更时，所有 `sillyspec run` 命令加 `--change <变更名>` 可指定操作目标。
-
-## 步骤生命周期（所有阶段通用）
-
-> `sillyspec scan` 是 `sillyspec run scan` 的顶层别名，两者等价。
-
-```bash
-sillyspec run scan                             # 输出当前步骤 prompt
-sillyspec run scan --done --output "摘要"      # 完成当前步骤
-sillyspec run scan --status                    # 查看阶段进度
-sillyspec run scan --skip                      # 跳过可选步骤
-sillyspec run scan --reset                     # 重置阶段（从头开始）
-```
-
-## 通用参数（所有阶段适用）
-
-| 参数 | 说明 |
-|---|---|
-| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
-| `--non-interactive` | CI/脚本下禁用交互式 prompt |
-| `--skip-approval` | 跳过审批/校验门控 |
-| `--json` | 输出 JSON（程序化读取） |
-
-## scan 特有参数
-
-| 参数 | 说明 |
-|---|---|
-| `--deep` | 强制 deep 扫描 profile（完整流程，不按规模裁剪） |
-| `--force-rescan` | 覆盖已有 scan 文档的保护（默认覆盖需 source_commit/updated_at 匹配） |
-
-### scanProfile（按项目规模自动裁剪）
-
-CLI 根据源码规模自动选择 profile，无需手动指定：
-
-| profile | 触发条件 | 行为 |
-|---|---|---|
-| quick | ≤30 文件 且 ≤80KB 且 ≤3 项目 | 3 步，0 子代理，5 份核心文档 |
-| standard | ≤200 文件 且 ≤800KB | 压缩步骤，最多 1 子代理 |
-| deep | 大项目或 `--deep` | 完整流程 |
-
-### post-check
-
-scan 完成时 CLI 自动校验 7 份文档齐全。缺失会设状态为 `failed_post_check`，阻断进入主流程下游（brainstorm/plan 等），需修复后重跑 scan。
-
-## 阶段流转
-
-```
-(项目起点) → scan → brainstorm
-```
-
-scan 完成后，运行 `sillyspec run brainstorm "<需求>"` 开始具体变更的设计。
-
-## 铁律
-
-- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
-- 只做当前步骤 prompt 描述的操作，不跳过
-- scan 文档写入 `{DOCS_ROOT}/scan/`（平台模式用占位符路径，不写裸 `.sillyspec/`）
-- 完成后立即 `--done`，不跳过
-
-## 用户指令
-$ARGUMENTS
+---
+name: sillyspec:scan
+description: 扫描项目代码库，生成架构文档、代码约定、目录结构。产出 7 份扫描文档 + 模块映射。
+---
+
+## 何时使用
+
+- 用户说"扫描项目、分析代码库、生成文档、scan"
+- 棕地项目首次接入 sillyspec，生成架构/约定/结构等基础文档
+- 产出 7 份 scan 文档（PROJECT/ARCHITECTURE/CONVENTIONS/STRUCTURE/INTEGRATIONS/TESTING/CONCERNS）+ 模块映射
+
+## 多变更说明
+
+scan 是辅助阶段，通常不需要 `--change`。但项目有多个活跃变更时，所有 `sillyspec run` 命令加 `--change <变更名>` 可指定操作目标。
+
+## 步骤生命周期（所有阶段通用）
+
+> `sillyspec scan` 是 `sillyspec run scan` 的顶层别名，两者等价。
+
+```bash
+sillyspec run scan                             # 输出当前步骤 prompt
+sillyspec run scan --done --output "摘要"      # 完成当前步骤
+sillyspec run scan --status                    # 查看阶段进度
+sillyspec run scan --skip                      # 跳过可选步骤
+sillyspec run scan --reset                     # 重置阶段（从头开始）
+```
+
+## 通用参数（所有阶段适用）
+
+| 参数 | 说明 |
+|---|---|
+| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--non-interactive` | CI/脚本下禁用交互式 prompt |
+| `--skip-approval` | 跳过审批/校验门控 |
+| `--json` | 输出 JSON（程序化读取） |
+
+## scan 特有参数
+
+| 参数 | 说明 |
+|---|---|
+| `--deep` | 强制 deep 扫描 profile（完整流程，不按规模裁剪） |
+| `--force-rescan` | 覆盖已有 scan 文档的保护（默认覆盖需 source_commit/updated_at 匹配） |
+
+### scanProfile（按项目规模自动裁剪）
+
+CLI 根据源码规模自动选择 profile，无需手动指定：
+
+| profile | 触发条件 | 行为 |
+|---|---|---|
+| quick | ≤30 文件 且 ≤80KB 且 ≤3 项目 | 3 步，0 子代理，5 份核心文档 |
+| standard | ≤200 文件 且 ≤800KB | 压缩步骤，最多 1 子代理 |
+| deep | 大项目或 `--deep` | 完整流程 |
+
+### post-check
+
+scan 完成时 CLI 自动校验 7 份文档齐全。缺失会设状态为 `failed_post_check`，阻断进入主流程下游（brainstorm/plan 等），需修复后重跑 scan。
+
+## 阶段流转
+
+```
+(项目起点) → scan → brainstorm
+```
+
+scan 完成后，运行 `sillyspec run brainstorm "<需求>"` 开始具体变更的设计。
+
+## 铁律
+
+- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
+- 只做当前步骤 prompt 描述的操作，不跳过
+- scan 文档写入 `{DOCS_ROOT}/scan/`（平台模式用占位符路径，不写裸 `.sillyspec/`）
+- 完成后立即 `--done`，不跳过
+
+## 用户指令
+$ARGUMENTS

package/.claude/skills/sillyspec-status/SKILL.md

@@ -1,55 +1,55 @@
----
-name: sillyspec:status
-description: 用于查看 SillySpec 当前进度和状态。适合用户说"看下状态、当前进度、status"。显示当前阶段、步骤完成度、活跃变更。
----
-
-## 何时使用
-
-- 用户说"看下状态、当前进度、status"
-- 查看项目整体进度：活跃变更、各阶段状态、步骤完成度
-
-## status vs state 分工
-
-- **`/sillyspec:status`**（本 skill）— 查看项目整体进度（change 文件级别、各阶段状态）。走 `sillyspec run status` 阶段。
-- **`/sillyspec:state`** — 查看当前工作状态（阶段/步骤级别、下一步建议）。走 `sillyspec progress show`。
-
-两者互补：status 看"有什么"，state 看"在做什么"。
-
-## 多变更说明
-
-status 是辅助阶段。项目有多个活跃变更时，加 `--change <变更名>` 查看指定变更的详情；不指定时汇总显示所有变更。
-
-## 步骤生命周期（所有阶段通用）
-
-> `sillyspec status` 是 `sillyspec run status` 的顶层别名，两者等价。status 是辅助阶段，只读。
-
-```bash
-sillyspec run status                           # 输出当前步骤 prompt
-sillyspec run status --done --output "摘要"    # 完成阶段
-sillyspec run status --status                  # 查看阶段状态
-```
-
-## 通用参数（所有阶段适用）
-
-| 参数 | 说明 |
-|---|---|
-| `--change <名>` | 指定变更名（多变更时查看指定变更详情） |
-| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
-| `--json` | 输出 JSON（程序化读取） |
-
-## 配套的只读查询命令（不经 run）
-
-```bash
-sillyspec progress show                        # 当前工作状态（阶段/步骤级）
-sillyspec progress show --change <名>          # 指定变更详情
-sillyspec progress check                       # 状态一致性检查
-```
-
-## 铁律
-
-- status 是只读阶段，**不修改任何文件**
-- **必须用 exec 工具（shell）执行 CLI**
-- 完成后立即 `--done`，不跳过
-
-## 用户指令
-$ARGUMENTS
+---
+name: sillyspec:status
+description: 查看 SillySpec 当前进度与状态：当前阶段、步骤完成度、活跃变更。
+---
+
+## 何时使用
+
+- 用户说"看下状态、当前进度、status"
+- 查看项目整体进度：活跃变更、各阶段状态、步骤完成度
+
+## status vs state 分工
+
+- **`/sillyspec:status`**（本 skill）— 查看项目整体进度（change 文件级别、各阶段状态）。走 `sillyspec run status` 阶段。
+- **`/sillyspec:state`** — 查看当前工作状态（阶段/步骤级别、下一步建议）。走 `sillyspec progress show`。
+
+两者互补：status 看"有什么"，state 看"在做什么"。
+
+## 多变更说明
+
+status 是辅助阶段。项目有多个活跃变更时，加 `--change <变更名>` 查看指定变更的详情；不指定时汇总显示所有变更。
+
+## 步骤生命周期（所有阶段通用）
+
+> `sillyspec status` 是 `sillyspec run status` 的顶层别名，两者等价。status 是辅助阶段，只读。
+
+```bash
+sillyspec run status                           # 输出当前步骤 prompt
+sillyspec run status --done --output "摘要"    # 完成阶段
+sillyspec run status --status                  # 查看阶段状态
+```
+
+## 通用参数（所有阶段适用）
+
+| 参数 | 说明 |
+|---|---|
+| `--change <名>` | 指定变更名（多变更时查看指定变更详情） |
+| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--json` | 输出 JSON（程序化读取） |
+
+## 配套的只读查询命令（不经 run）
+
+```bash
+sillyspec progress show                        # 当前工作状态（阶段/步骤级）
+sillyspec progress show --change <名>          # 指定变更详情
+sillyspec progress check                       # 状态一致性检查
+```
+
+## 铁律
+
+- status 是只读阶段，**不修改任何文件**
+- **必须用 exec 工具（shell）执行 CLI**
+- 完成后立即 `--done`，不跳过
+
+## 用户指令
+$ARGUMENTS

package/.claude/skills/sillyspec-verify/SKILL.md

@@ -1,82 +1,82 @@
----
-name: sillyspec:verify
-description: 用于验证代码实现是否符合 design 和模块文档。适合用户说"验证下、检查下、跑 verify"。对照 design.md + 模块文档检查任务完成度、设计一致性、运行测试。
----
-
-## 何时使用
-
-- 用户说"验证下、检查下、跑 verify"
-- 对照 design.md + 模块文档检查任务完成度
-- 设计一致性检查 + 运行测试套件
-- 产出 `verify-result.md`（PASS / PASS WITH NOTES / FAIL）
-
-## 多变更说明
-
-项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录）时，所有 `sillyspec run` 命令需加 `--change <变更名>` 指定操作目标；只有一个变更时可省略（CLI 自动检测）。
-
-## 步骤生命周期（所有阶段通用）
-
-> `sillyspec verify` 是 `sillyspec run verify` 的顶层别名，两者等价。
-
-```bash
-sillyspec run verify                           # 输出当前步骤 prompt
-sillyspec run verify --done --output "摘要"    # 完成当前步骤（--input "用户原话" 记录输入）
-sillyspec run verify --status                  # 查看阶段进度
-sillyspec run verify --skip                    # 跳过可选步骤
-sillyspec run verify --reset                   # 重置阶段（从头开始）
-sillyspec run verify --reopen --from-step N    # 重新打开已完成阶段修订（N=序号或名称）
-```
-
-## 通用参数（所有阶段适用）
-
-| 参数 | 说明 |
-|---|---|
-| `--change <名>` | 指定变更名（多活跃变更必填，单变更可省略自动检测） |
-| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
-| `--non-interactive` | CI/脚本下禁用交互式 prompt |
-| `--skip-approval` | 跳过审批/校验门控（需明确意图） |
-| `--json` | 输出 JSON（程序化读取） |
-
-## verify 特有：完成门控（重要）
-
-verify 是只读阶段（**禁止改代码/改 git 状态**，只检查 + 写报告）。完成时有硬校验：
-
-- **必须产出 `verify-result.md`**——不存在则阻断完成（不能跳过报告直接 `--done`）
-- **结论为 `FAIL` 则阻断完成**——不能带着 FAIL 标记 verify 完成
-- **`integration-critical` / `deployment-critical` 变更**（design/plan 含 daemon/session/lease/lifecycle 等关键词）：结论 PASS WITH NOTES 降级为 FAIL，必须有真实集成证据（Runtime Evidence section）
-- `verify-required-evidence.json`（execute 写入）中每条 missing evidence → 阻断
-
-被阻断时 CLI 打印 ❌ 校验失败，不会提示"验证通过"。修复 `verify-result.md` 后重新 `--done`。
-
-## verify-result.md 格式
-
-```markdown
-# 验证报告
-## 结论
-PASS / PASS WITH NOTES / FAIL      ← 必须有结论章节（标题含"结论/Conclusion/Result/结果"即可，不限于确切"## 结论"），FAIL 会阻断 verify 完成
-## 任务完成度
-## 设计一致性
-## 探针结果
-## 测试结果
-## 变更风险等级
-## Runtime Evidence（integration/deployment-critical 必填）
-```
-
-## 阶段流转
-
-```
-execute → verify → archive
-```
-
-verify 通过（PASS）后，运行 `sillyspec run archive --change <变更名>` 归档。FAIL 则修复后重跑 `sillyspec run verify`。
-
-## 铁律
-
-- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
-- verify 阶段**绝对禁止** git checkout/restore/reset、删除/覆盖源码文件——只检查 + 报告
-- 发现问题只报告，不尝试修复（修复回 execute）
-- `verify-result.md` 结论必须基于证据，不写"看起来没问题"
-- 完成后立即 `--done`，不跳过
-
-## 用户指令
-$ARGUMENTS
+---
+name: sillyspec:verify
+description: 验证代码实现是否符合 design 与模块文档。对照 design.md + 模块文档检查任务完成度、设计一致性、运行测试。
+---
+
+## 何时使用
+
+- 用户说"验证下、检查下、跑 verify"
+- 对照 design.md + 模块文档检查任务完成度
+- 设计一致性检查 + 运行测试套件
+- 产出 `verify-result.md`（PASS / PASS WITH NOTES / FAIL）
+
+## 多变更说明
+
+项目有多个活跃变更（`.sillyspec/changes/` 下有多个目录）时，所有 `sillyspec run` 命令需加 `--change <变更名>` 指定操作目标；只有一个变更时可省略（CLI 自动检测）。
+
+## 步骤生命周期（所有阶段通用）
+
+> `sillyspec verify` 是 `sillyspec run verify` 的顶层别名，两者等价。
+
+```bash
+sillyspec run verify                           # 输出当前步骤 prompt
+sillyspec run verify --done --output "摘要"    # 完成当前步骤（--input "用户原话" 记录输入）
+sillyspec run verify --status                  # 查看阶段进度
+sillyspec run verify --skip                    # 跳过可选步骤
+sillyspec run verify --reset                   # 重置阶段（从头开始）
+sillyspec run verify --reopen --from-step N    # 重新打开已完成阶段修订（N=序号或名称）
+```
+
+## 通用参数（所有阶段适用）
+
+| 参数 | 说明 |
+|---|---|
+| `--change <名>` | 指定变更名（多活跃变更必填，单变更可省略自动检测） |
+| `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
+| `--non-interactive` | CI/脚本下禁用交互式 prompt |
+| `--skip-approval` | 跳过审批/校验门控（需明确意图） |
+| `--json` | 输出 JSON（程序化读取） |
+
+## verify 特有：完成门控（重要）
+
+verify 是只读阶段（**禁止改代码/改 git 状态**，只检查 + 写报告）。完成时有硬校验：
+
+- **必须产出 `verify-result.md`**——不存在则阻断完成（不能跳过报告直接 `--done`）
+- **结论为 `FAIL` 则阻断完成**——不能带着 FAIL 标记 verify 完成
+- **`integration-critical` / `deployment-critical` 变更**（design/plan 含 daemon/session/lease/lifecycle 等关键词）：结论 PASS WITH NOTES 降级为 FAIL，必须有真实集成证据（Runtime Evidence section）
+- `verify-required-evidence.json`（execute 写入）中每条 missing evidence → 阻断
+
+被阻断时 CLI 打印 ❌ 校验失败，不会提示"验证通过"。修复 `verify-result.md` 后重新 `--done`。
+
+## verify-result.md 格式
+
+```markdown
+# 验证报告
+## 结论
+PASS / PASS WITH NOTES / FAIL      ← 必须有结论章节（标题含"结论/Conclusion/Result/结果"即可，不限于确切"## 结论"），FAIL 会阻断 verify 完成
+## 任务完成度
+## 设计一致性
+## 探针结果
+## 测试结果
+## 变更风险等级
+## Runtime Evidence（integration/deployment-critical 必填）
+```
+
+## 阶段流转
+
+```
+execute → verify → archive
+```
+
+verify 通过（PASS）后，运行 `sillyspec run archive --change <变更名>` 归档。FAIL 则修复后重跑 `sillyspec run verify`。
+
+## 铁律
+
+- **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
+- verify 阶段**绝对禁止** git checkout/restore/reset、删除/覆盖源码文件——只检查 + 报告
+- 发现问题只报告，不尝试修复（修复回 execute）
+- `verify-result.md` 结论必须基于证据，不写"看起来没问题"
+- 完成后立即 `--done`，不跳过
+
+## 用户指令
+$ARGUMENTS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.24.4",
+  "version": "3.24.6",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/db.js

@@ -1,6 +1,6 @@
 import initSqlJs from 'sql.js';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { dirname } from 'path';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { basename, dirname, join } from 'path';
 
 export class DB {
   constructor(dbPath) {
@@ -16,13 +16,8 @@ export class DB {
     // 2. 初始化 sql.js
     const SQL = await initSqlJs();
 
-    // 3. 加载已有数据库或创建新库
-    if (existsSync(this.dbPath)) {
-      const buf = readFileSync(this.dbPath);
-      this.db = new SQL.Database(buf);
-    } else {
-      this.db = new SQL.Database();
-    }
+    // 3. 加载已有数据库（含损坏检测 + .bak 回滚）或创建新库
+    this.db = this._loadDatabase(SQL);
 
     // 4. 设置 PRAGMA
     this.db.run('PRAGMA journal_mode = WAL');
@@ -64,12 +59,17 @@ export class DB {
     return this.db;
   }
 
-  /** 将内存中的数据库持久化到磁盘 */
+  /**
+   * 将内存中的数据库持久化到磁盘（原子写 + 保留上一版 .bak 备份）。
+   * 任何时刻磁盘上的主库要么是完整的上一版、要么是完整的新版，
+   * 不会出现写入中途崩溃导致的截断态。sql.js 是纯内存库，
+   * PRAGMA journal_mode=WAL 对它无意义——真正的持久化原子性在这里保证。
+   */
   _save() {
     if (!this.db) return;
     const data = this.db.export();
     const buffer = Buffer.from(data);
-    writeFileSync(this.dbPath, buffer);
+    this._atomicWriteSync(this.dbPath, buffer);
     // sql.js 的 export() 会重置 PRAGMA 状态，需要重新设置
     this.db.run('PRAGMA journal_mode = WAL');
     this.db.run('PRAGMA busy_timeout = 5000');
@@ -77,6 +77,103 @@ export class DB {
     this.db.run('PRAGMA synchronous = NORMAL');
   }
 
+  /**
+   * 原子落盘：同目录 tmp 写入 → 旧主库改名 .bak → tmp 改名为主库。
+   * 三步保证主库永不处于半写状态；.bak 始终保留上一完整版本。
+   * Windows 上 rename 偶发 EPERM/EBUSY（杀毒/索引扫描占文件），带短退避重试。
+   */
+  _atomicWriteSync(filePath, buffer) {
+    const dir = dirname(filePath);
+    const tmpPath = join(dir, `${basename(filePath)}.tmp`);
+    const bakPath = `${filePath}.bak`;
+    // 1. 完整内容先落 tmp（同目录，保证 rename 不跨卷）
+    writeFileSync(tmpPath, buffer);
+    // 2. 旧主库 → .bak（保留上一版；不存在则跳过；失败不阻断主流程）
+    if (existsSync(filePath)) {
+      try { this._renameSyncRetry(filePath, bakPath); }
+      catch { /* 备份失败最坏只是少一个 .bak，主库仍会被新内容替换 */ }
+    }
+    // 3. tmp → 主库（成功后主库即新版完整态）
+    this._renameSyncRetry(tmpPath, filePath);
+  }
+
+  /** rename 带退避重试，覆盖 Windows 偶发的 EPERM/EBUSY/EACCES/ENOTEMPTY。 */
+  _renameSyncRetry(from, to, retries = 5) {
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        renameSync(from, to);
+        return;
+      } catch (err) {
+        lastErr = err;
+        const code = err && err.code;
+        if (!code || !['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY'].includes(code)) throw err;
+        if (attempt < retries) this._sleepSync(15 * (attempt + 1));
+      }
+    }
+    throw lastErr;
+  }
+
+  /** 同步退避：优先 Atomics.wait，不可用时退化为忙等（仅在 rename 冲突的极端情况触发）。 */
+  _sleepSync(ms) {
+    try {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    } catch {
+      const end = Date.now() + ms;
+      while (Date.now() < end) { /* busy wait */ }
+    }
+  }
+
+  /**
+   * 加载数据库：主库 → .bak → 报错/空库，逐级回退。
+   *  - 主库可正常打开：直接用。
+   *  - 主库缺失/为空/损坏：尝试 .bak；成功则 warn 后用 .bak。
+   *  - 主库与 .bak 都不可用：
+   *      · 全新项目（两者都不存在）：创建空库；
+   *      · 主库曾存在却无法恢复（截断/损坏且无可用备份）：fail-loud 抛错，
+   *        不静默建空库——那会无声吞掉用户所有进度。
+   */
+  _loadDatabase(SQL) {
+    const bakPath = `${this.dbPath}.bak`;
+    // readValid: null=文件不存在；'empty'=存在但 0 字节；Buffer=有内容
+    const readValid = (p) => {
+      if (!existsSync(p)) return null;
+      const b = readFileSync(p);
+      return (b && b.length > 0) ? b : 'empty';
+    };
+    const tryOpen = (raw) => {
+      if (!raw || raw === 'empty') return null;
+      let instance;
+      try { instance = new SQL.Database(raw); }
+      catch { return null; }
+      // 双保险：损坏 buffer 偶尔被 sql.js 静默打开为空库，用一次查询确认它真能用
+      try { instance.exec('SELECT count(*) FROM sqlite_master'); return instance; }
+      catch { try { instance.close(); } catch {} return null; }
+    };
+
+    const primaryRaw = readValid(this.dbPath);
+    const primaryDb = tryOpen(primaryRaw);
+    if (primaryDb) return primaryDb;
+
+    const bakDb = tryOpen(readValid(bakPath));
+    if (bakDb) {
+      const reason = primaryRaw === 'empty'
+        ? 'sillyspec.db 为空（可能被截断）'
+        : primaryRaw === null
+          ? 'sillyspec.db 不存在'
+          : 'sillyspec.db 损坏';
+      console.warn(`⚠️  ${reason}，已从 .bak 备份恢复。`);
+      return bakDb;
+    }
+
+    if (primaryRaw === null) {
+      // 主库与备份都不存在 → 全新项目
+      return new SQL.Database();
+    }
+    // 主库曾存在（空/损坏）但无法恢复 → 数据丢失，必须 fail-loud
+    throw new Error('sillyspec.db 损坏且 .bak 备份不可用，无法恢复。请从版本控制或其他备份恢复 .sillyspec/.runtime/ 后重试。');
+  }
+
   _createSchema() {
     // project 表
     this.db.run(`