别再重装了！三步解决 bd create 提示数据库未初始化问题

在 Beads (bd) 的开发者社区里，有一个极其高频且令人沮丧的“死循环”：你执行了 bd init，甚至尝试了 bd bootstrap，控制台也大方地给了你成功的反馈。但只要你敲下 bd create --title "Test"，系统就会冷冰冰地弹出一句：

{ "error": "database not initialized: missing issue_prefix" }

很多人的第一反应是“环境坏了”，于是开始疯狂删目录、重装二进制文件、重启终端。作为一名深度参与过分布式数据库工具链调优的架构师，我要告诉你：这根本不是安装问题，而是底层状态机在初始化时的“逻辑断层”。

💡 报错现象总结：用户在已经初始化过的仓库中执行创建任务，依然被告知数据库未初始化。即使 bd config show 显示有前缀，bd create 依然报错。本质原因是 bootstrap 仅仅标记了“初始化开始”，却未能在数据库的作用域内真正写入核心元数据，导致严格检查器（Strict Checker）判定当前处于非法状态。

---

绕过“成功”的假象：为什么 bootstrap 救不了你？

在 Beads 的逻辑架构中，初始化分为“外壳初始化”和“内核初始化”。

为什么你会陷入初始化循环？

故障阶段	现象描述	架构师深度剖析
虚假成功	bd bootstrap 报告 Success	仅完成了本地文件同步，未触发 Dolt 层的元数据事务写入
检查器报错	bd create 提示未初始化	严格检查器只认数据库 System 表里的 issue_prefix 字段
配置盲区	config set 无法修复状态	该命令默认只修改配置文件，无法穿透到底层数据库表
前缀丢失	rename-prefix 返回 <nil>	由于旧前缀从未被写入数据库，重命名逻辑因找不到源而挂起

参考 高赞 Issue 3534 的反馈，这种状态是最糟糕的：系统声称可以修复，但你尝试了所有官方路径（config set、bootstrap、rename-prefix）全都石沉大海。

---

源码排雷：严格检查器（Strict Checker）的硬核逻辑

如果你去翻阅 Beads 处理写操作的代码，你会发现它在执行任何 INSERT 操作前，都会强制校验数据库的“元数据健康度”。

// 模拟 Beads 内部的写操作前置校验逻辑
func (app *App) EnsureInitialized() error {
    // 痛点：它绕过了 config.yaml，直接通过 SQL 查询系统元数据表
    prefix, err := app.db.FetchMetadata("issue_prefix")
    
    // 核心 Bug：如果 bootstrap 过程因为权限或路径问题没写进这一行
    // 即使你配置文件里写了 "bd-"，这里拿到的依然是 <nil>
    if prefix == "" || prefix == "<nil>" {
        return errors.New("database not initialized: missing issue_prefix")
    }
    return nil
}

由于 Beads 强依赖于 Dolt 数据库的一致性，它拒绝在元数据不完整的状态下产生任何业务数据。这种“宁缺毋滥”的设计初衷是好的，但却因为初始化指令的非幂等性，把开发者锁死在了门外。

---

痛苦的临时方案：为何“反复重试”是低效的？

很多开发者在报错后会尝试：

1. 无限循环 bd init：结果系统提示“目录已存在”，依然无法修复元数据。
2. 手动修改环境变量：试图用 BEADS_ISSUE_PREFIX 来“骗过”检查器。这在某些读操作中有效，但在 bd create 这种强约束写操作中，底层依然会去校验数据库本体。
3. 彻底删除 .beads：这虽然能解决问题，但意味着你之前所有调试好的分支、快照和任务历史全部灰飞烟灭。

---

三步手动校准，重获“读写能力”

别再被“重装”这种思维定式给毁了。要解决这个问题，我们需要一套能绕过不靠谱的 bootstrap、直接向数据库“捅入”元数据的方案。

我已经根据 Issue 中记录的唯一有效路径，整理出了这套**“快速排空”初始化工具包**。它不再依赖脆弱的交互式流程，而是利用 bd init --reinit-local 配合显式的 Maintainer 角色权限，强行校准数据库内部的标识位。

让数据库说真话，而不是只听配置文件的。 这种针对“状态机锁死”的深度修复，是每一个使用 Beads 的架构师必须掌握的救火技能。你可以直接前往 GitCode 获取这个工具包，只需三步命令，就能让你的任务追踪系统起死回生。

[点击前往 GitCode 获取“快速排空”初始化工具包]