Beadsbd rename-prefix全解析全局 Issue 前缀重命名与多前缀修复实战指南【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd rename-prefix是 Beads 中少数面向“整库级维护”的命令它一次性重命名数据库内所有 Issue 的 ID 前缀并同步改写标题、描述、设计、验收标准、备注等全部文本字段中的旧前缀引用同时把依赖关系与事件日志一并迁移到新 ID 上。本文以 docs/cli-reference/rename-prefix.md 为骨架结合命令实现源码与集成测试完整讲解前缀校验规则、--dry-run预演、--repair多前缀修复、底层重命名机制及各类边界情况帮助你安全地完成前缀缩短、品牌重命名与损坏数据库的前缀归并。适用前提本文面向 Beads 的bdCLI。该命令属于维护类maint分组操作仅在直接访问数据库的嵌入式模式下可用不支持 proxied-server 模式。一、命令概览它到底做了什么bd rename-prefix new-prefix [flags]一次执行会完成三件事重写所有 Issue ID把数据库内每个 Issue 的 ID 前缀替换为目标前缀如knowledge-work-a3f8e9→kw-a3f8e9。改写所有文本引用Issue 的title、description、design、acceptance_criteria、notes字段中出现的旧前缀 ID全部按映射替换为新 ID保证“正文引用不悬空”。同步底层存储通过存储层的UpdateIssueID把依赖表、wisp 行、事件日志一并迁移到新 ID保证 rename 之后依赖关系依然成立。命令的完整实现在 cmd/bd/rename_prefix.go核心调用链为renamePrefixInDB/repairPrefixes→store.UpdateIssueIDinternal/storage/dolt/rename.go→issueops.UpdateIssueIDInTxinternal/storage/issueops/bulk_ops.go。二、典型使用场景原文档列出四类高频场景本质上都是“ID 前缀承载了团队/项目命名语义”的产物缩短冗长前缀如knowledge-work-→kw-减少 ID 长度、降低输入成本。品牌与命名规范更名项目改名后让 Issue ID 与新的命名约定保持一致。数据库损坏后的多前缀归并损坏或半迁移的库中可能同时存在bd-、beads-、kw-多种前缀用--repair统一。对齐团队命名标准多个仓库/工作区合并时统一前缀规范。原文档特别强调这是一个极少使用的操作大多数用户永远不需要它。请把它当作一次性维护工具而非日常命令。三、前缀命名规则校验逻辑与源码实现合法的前缀必须同时满足以下规则见原文档及 cmd/bd/rename_prefix.go 的validatePrefix实现规则说明源码校验方式最大长度8 个字符文档约定文档声明源码以正则约束字符集允许字符小写字母、数字、连字符正则^[a-z][a-z0-9-]*$首字符必须是字母正则首字符[a-z]结尾必须以连字符结尾如kw-、work-传入时TrimRight(prefix, -)归一化后再校验禁止不能为空、不能只是连字符空串直接报错禁止以-开头或包含--源码中的实际执行顺序是先把用户输入末尾的连字符剥掉strings.TrimRight(newPrefix, -)再做三项检查——非空、正则匹配、连字符位置合法。也就是说用户写kw或kw-都会被接受并归一化为kw最终写入存储的配置值是去掉尾部连字符后的形式。测试用例 cmd/bd/rename_prefix_embedded_test.go 验证了大写前缀UPPER与非法字符BAD!都会导致命令失败并报错。四、两种工作模式普通重命名与--repair修复命令核心逻辑先扫描全库用detectPrefixes对每一条 Issue 调用 internal/utils/issue_id.go 的ExtractIssuePrefix提取前缀并统计仅检测到1 个前缀→ 走普通重命名路径renamePrefixInDB。检测到多个前缀1→ 必须加--repair否则命令以错误终止并给出提示✗ Multiple prefixes detected in database: - bd-: 12 issues - kw-: 3 issues cannot rename with multiple prefixes. Use --repair to consolidate. Example: bd rename-prefix team- --repair4.1 普通重命名逐 Issue 改写 ID 与文本renamePrefixInDBcmd/bd/rename_prefix.go的流程为以正则\boldP-(\d)\b匹配文本中形如oldP-123的旧 ID 引用对每个 Issue 的 5 个文本字段Title / Description / Design / AcceptanceCriteria / Notes执行ReplaceAllStringFunc替换调用rewriteIssueID计算新 IDnewP - strings.TrimPrefix(oldID, oldP-)逐条调用store.UpdateIssueID(oldID, newID, issue, actor)提交数据库最后store.SetConfig(ctx, issue_prefix, newP)更新配置单元。源码注释明确提醒每个 Issue 在各自的事务中更新中途失败可能留下“部分已改名”的混合状态生产环境建议在存储层实现单事务原子RenamePrefix()。因此执行前务必先--dry-run并做好备份。4.2--repair多前缀归并repairPrefixescmd/bd/rename_prefix.go把 Issue 分为两组已是目标前缀的 Issue原样保留ID 与文本均不动错误前缀的 Issue生成新的哈希 ID后重写。归并顺序先按旧前缀字典序、再按编号排序保证输出可预期。新 ID 由generateRepairHashID生成对标题|描述|actor|CreatedAt|nonce做 SHA-256取前 4 字节转 8 位十六进制作为 ID 后缀即mtg-a3f8e9cd这种形式若与批次内已有 ID 冲突则递增 nonce 重试最多 100 次实现批内去重。文本替换采用更宽泛的模式\b[a-z][a-z0-9-]*-[a-z0-9]\b通过「旧 ID → 新 ID」的映射表renameMap精确替换未命中的匹配保持原样避免误伤无关文本。归并完成后同样回写issue_prefix配置。4.3 边界情况处理源码对以下特殊情况有明确分支空数据库没有 Issue 可改仅更新配置并提示No issues to rename. Updating prefix to ...新旧前缀相同直接报错new prefix is the same as current prefix配置与行数据不一致GH#4827 半迁移库若行上检测到的前缀已等于目标前缀而配置单元过期则只修复配置、不改写任何 ID输出Repaired config prefix: ... (0 issues rewritten)——这正是防止产生atlas-atlas-*双重前缀的关键守卫前缀缩短歧义PR #5135beads-vscode-→beads-时beads-vscode-1虽然也以beads-开头但必须被改写rewriteIssueID的注释与测试 rename_prefix_embedded_test.go 专门回归了这一场景。五、命令 Flags 详解Flag默认值作用--dry-runfalse预演模式输出将要发生的变化但不写入任何数据--repairfalse修复模式允许把多个前缀归并为目标前缀--dry-run有几个值得注意的实现细节它是唯一允许在只读模式下执行的分支——源码中CheckReadonly仅在非 dry-run 时触发cmd/bd/rename_prefix.go因此只读仓库上也可以安全预演。普通重命名下它打印前 5 条旧ID - 新ID示例并汇总剩余数量--repair下打印前 10 条计划重命名及“正确/待修”的 Issue 计数。并发预演是安全的TestEmbeddedRenamePrefixConcurrentcmd/bd/rename_prefix_embedded_test.go用 8 个 worker 同时跑--dry-run仅允许独占写入错误出现验证预演本身无写竞争。六、实操示例# 预演把 knowledge-work- 缩短为 kw-仅预览不落库 bd rename-prefix kw- --dry-run # 正式执行前缀缩短 bd rename-prefix kw- # 预演多前缀归并把所有非 mtg- 前缀统一为 mtg- bd rename-prefix mtg- --repair --dry-run # 正式归并 bd rename-prefix mtg- --repair # 空库直接改前缀配置 bd rename-prefix team-成功输出示例--repair模式✓ Successfully consolidated 2 prefixes into mtg- 3 issues repaired, 12 issues unchanged七、底层机制一次 rename 在存储层如何完成UpdateIssueID的真正实现在 internal/storage/issueops/bulk_ops.go若事件日志启用先捕获旧 ID 的所有依赖边dependencyEdgesForIssueIDsInTx判断该 ID 是普通 Issue 还是活跃 wispIsActiveWispInTx分别走updateIssueIDInTx或updateWispIDInTxupdateIssueIDInTx用一条 UPDATE 同时改写issues表的id与 5 个文本字段并更新updated_at随后调用UpdateIssueIDInDependenciesInTx把所有依赖表中的旧 ID 引用改为新 IDrecordRenameInJournal把这次改名以「删除旧边 → 删除旧 bead → 创建新 bead → 按新 ID 重加依赖边」的事件序列写入 journal让不理解“身份变更”的下游消费者也能正确重放。存储层的重命名有配套的专项测试覆盖TestUpdateIssueIDUpdatesWispDependencyTargets、TestUpdateIssueIDUpdatesPersistentDependencyTargets、TestUpdateIssueIDDependencyTargetCollisionFails等均位于 internal/storage/dolt/rename_test.go分别验证 wisp 依赖目标、持久化依赖行、目标冲突报错等场景。八、相关配置与使用限制前缀配置项为issue_prefix不能通过bd config set修改。配置文档 docs/reference/configuration.md 明确说明设置前缀只能走bd init --prefix、bd bootstrap或bd rename-prefix三条路径。rename-prefix正是唯一支持“事后修改已有库前缀”的途径。命令注册在maint分组见 cmd/bd/rename_prefix.go 与 docs/CLI_REFERENCE.md与bd doctor、bd gc等维护类命令并列。proxied-server 模式下执行会直接报错rename-prefix is not supported in proxied-server mode。命令支持--json全局输出普通重命名返回old_prefix/new_prefix/issues_count修复模式返回target_prefix/prefixes_found/issues_repaired/issues_unchanged配置修复场景额外带config_repaired: true便于脚本化集成。git worktree 场景不受旧版“禁止从 worktree 运行”限制测试 cmd/bd/rename_prefix_worktree_test.go 验证了 worktree 下会正确解析主仓库的.beads数据库路径因此可以从 worktree 中对主库执行该命令。九、安全执行建议先预演任何真实执行前先跑一次bd rename-prefix prefix --dry-run核对示例映射与“待修 Issue 数量”。检查前缀污染若输出显示 Multiple prefixes说明库已处于不一致状态务必带--repair并先备份。了解非原子性普通重命名为逐 Issue 事务提交中途失败可能部分完成执行前用bd backup或仓库快照做好恢复预案。验证结果执行后运行bd list确认新前缀生效、旧前缀无残留并抽查正文引用是否同步更新。延伸阅读命令实现cmd/bd/rename_prefix.go前缀提取启发式算法internal/utils/issue_id.go存储层 ID 重命名与 journal 记录internal/storage/issueops/bulk_ops.go集成测试cmd/bd/rename_prefix_embedded_test.go、internal/storage/dolt/rename_test.goAgent 技能文档plugins/beads/skills/beads/commands/rename-prefix.md配置说明docs/reference/configuration.md【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Beads `bd rename-prefix` 全解析：全局 Issue 前缀重命名与多前缀修复实战指南
Beadsbd rename-prefix全解析全局 Issue 前缀重命名与多前缀修复实战指南【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd rename-prefix是 Beads 中少数面向“整库级维护”的命令它一次性重命名数据库内所有 Issue 的 ID 前缀并同步改写标题、描述、设计、验收标准、备注等全部文本字段中的旧前缀引用同时把依赖关系与事件日志一并迁移到新 ID 上。本文以 docs/cli-reference/rename-prefix.md 为骨架结合命令实现源码与集成测试完整讲解前缀校验规则、--dry-run预演、--repair多前缀修复、底层重命名机制及各类边界情况帮助你安全地完成前缀缩短、品牌重命名与损坏数据库的前缀归并。适用前提本文面向 Beads 的bdCLI。该命令属于维护类maint分组操作仅在直接访问数据库的嵌入式模式下可用不支持 proxied-server 模式。一、命令概览它到底做了什么bd rename-prefix new-prefix [flags]一次执行会完成三件事重写所有 Issue ID把数据库内每个 Issue 的 ID 前缀替换为目标前缀如knowledge-work-a3f8e9→kw-a3f8e9。改写所有文本引用Issue 的title、description、design、acceptance_criteria、notes字段中出现的旧前缀 ID全部按映射替换为新 ID保证“正文引用不悬空”。同步底层存储通过存储层的UpdateIssueID把依赖表、wisp 行、事件日志一并迁移到新 ID保证 rename 之后依赖关系依然成立。命令的完整实现在 cmd/bd/rename_prefix.go核心调用链为renamePrefixInDB/repairPrefixes→store.UpdateIssueIDinternal/storage/dolt/rename.go→issueops.UpdateIssueIDInTxinternal/storage/issueops/bulk_ops.go。二、典型使用场景原文档列出四类高频场景本质上都是“ID 前缀承载了团队/项目命名语义”的产物缩短冗长前缀如knowledge-work-→kw-减少 ID 长度、降低输入成本。品牌与命名规范更名项目改名后让 Issue ID 与新的命名约定保持一致。数据库损坏后的多前缀归并损坏或半迁移的库中可能同时存在bd-、beads-、kw-多种前缀用--repair统一。对齐团队命名标准多个仓库/工作区合并时统一前缀规范。原文档特别强调这是一个极少使用的操作大多数用户永远不需要它。请把它当作一次性维护工具而非日常命令。三、前缀命名规则校验逻辑与源码实现合法的前缀必须同时满足以下规则见原文档及 cmd/bd/rename_prefix.go 的validatePrefix实现规则说明源码校验方式最大长度8 个字符文档约定文档声明源码以正则约束字符集允许字符小写字母、数字、连字符正则^[a-z][a-z0-9-]*$首字符必须是字母正则首字符[a-z]结尾必须以连字符结尾如kw-、work-传入时TrimRight(prefix, -)归一化后再校验禁止不能为空、不能只是连字符空串直接报错禁止以-开头或包含--源码中的实际执行顺序是先把用户输入末尾的连字符剥掉strings.TrimRight(newPrefix, -)再做三项检查——非空、正则匹配、连字符位置合法。也就是说用户写kw或kw-都会被接受并归一化为kw最终写入存储的配置值是去掉尾部连字符后的形式。测试用例 cmd/bd/rename_prefix_embedded_test.go 验证了大写前缀UPPER与非法字符BAD!都会导致命令失败并报错。四、两种工作模式普通重命名与--repair修复命令核心逻辑先扫描全库用detectPrefixes对每一条 Issue 调用 internal/utils/issue_id.go 的ExtractIssuePrefix提取前缀并统计仅检测到1 个前缀→ 走普通重命名路径renamePrefixInDB。检测到多个前缀1→ 必须加--repair否则命令以错误终止并给出提示✗ Multiple prefixes detected in database: - bd-: 12 issues - kw-: 3 issues cannot rename with multiple prefixes. Use --repair to consolidate. Example: bd rename-prefix team- --repair4.1 普通重命名逐 Issue 改写 ID 与文本renamePrefixInDBcmd/bd/rename_prefix.go的流程为以正则\boldP-(\d)\b匹配文本中形如oldP-123的旧 ID 引用对每个 Issue 的 5 个文本字段Title / Description / Design / AcceptanceCriteria / Notes执行ReplaceAllStringFunc替换调用rewriteIssueID计算新 IDnewP - strings.TrimPrefix(oldID, oldP-)逐条调用store.UpdateIssueID(oldID, newID, issue, actor)提交数据库最后store.SetConfig(ctx, issue_prefix, newP)更新配置单元。源码注释明确提醒每个 Issue 在各自的事务中更新中途失败可能留下“部分已改名”的混合状态生产环境建议在存储层实现单事务原子RenamePrefix()。因此执行前务必先--dry-run并做好备份。4.2--repair多前缀归并repairPrefixescmd/bd/rename_prefix.go把 Issue 分为两组已是目标前缀的 Issue原样保留ID 与文本均不动错误前缀的 Issue生成新的哈希 ID后重写。归并顺序先按旧前缀字典序、再按编号排序保证输出可预期。新 ID 由generateRepairHashID生成对标题|描述|actor|CreatedAt|nonce做 SHA-256取前 4 字节转 8 位十六进制作为 ID 后缀即mtg-a3f8e9cd这种形式若与批次内已有 ID 冲突则递增 nonce 重试最多 100 次实现批内去重。文本替换采用更宽泛的模式\b[a-z][a-z0-9-]*-[a-z0-9]\b通过「旧 ID → 新 ID」的映射表renameMap精确替换未命中的匹配保持原样避免误伤无关文本。归并完成后同样回写issue_prefix配置。4.3 边界情况处理源码对以下特殊情况有明确分支空数据库没有 Issue 可改仅更新配置并提示No issues to rename. Updating prefix to ...新旧前缀相同直接报错new prefix is the same as current prefix配置与行数据不一致GH#4827 半迁移库若行上检测到的前缀已等于目标前缀而配置单元过期则只修复配置、不改写任何 ID输出Repaired config prefix: ... (0 issues rewritten)——这正是防止产生atlas-atlas-*双重前缀的关键守卫前缀缩短歧义PR #5135beads-vscode-→beads-时beads-vscode-1虽然也以beads-开头但必须被改写rewriteIssueID的注释与测试 rename_prefix_embedded_test.go 专门回归了这一场景。五、命令 Flags 详解Flag默认值作用--dry-runfalse预演模式输出将要发生的变化但不写入任何数据--repairfalse修复模式允许把多个前缀归并为目标前缀--dry-run有几个值得注意的实现细节它是唯一允许在只读模式下执行的分支——源码中CheckReadonly仅在非 dry-run 时触发cmd/bd/rename_prefix.go因此只读仓库上也可以安全预演。普通重命名下它打印前 5 条旧ID - 新ID示例并汇总剩余数量--repair下打印前 10 条计划重命名及“正确/待修”的 Issue 计数。并发预演是安全的TestEmbeddedRenamePrefixConcurrentcmd/bd/rename_prefix_embedded_test.go用 8 个 worker 同时跑--dry-run仅允许独占写入错误出现验证预演本身无写竞争。六、实操示例# 预演把 knowledge-work- 缩短为 kw-仅预览不落库 bd rename-prefix kw- --dry-run # 正式执行前缀缩短 bd rename-prefix kw- # 预演多前缀归并把所有非 mtg- 前缀统一为 mtg- bd rename-prefix mtg- --repair --dry-run # 正式归并 bd rename-prefix mtg- --repair # 空库直接改前缀配置 bd rename-prefix team-成功输出示例--repair模式✓ Successfully consolidated 2 prefixes into mtg- 3 issues repaired, 12 issues unchanged七、底层机制一次 rename 在存储层如何完成UpdateIssueID的真正实现在 internal/storage/issueops/bulk_ops.go若事件日志启用先捕获旧 ID 的所有依赖边dependencyEdgesForIssueIDsInTx判断该 ID 是普通 Issue 还是活跃 wispIsActiveWispInTx分别走updateIssueIDInTx或updateWispIDInTxupdateIssueIDInTx用一条 UPDATE 同时改写issues表的id与 5 个文本字段并更新updated_at随后调用UpdateIssueIDInDependenciesInTx把所有依赖表中的旧 ID 引用改为新 IDrecordRenameInJournal把这次改名以「删除旧边 → 删除旧 bead → 创建新 bead → 按新 ID 重加依赖边」的事件序列写入 journal让不理解“身份变更”的下游消费者也能正确重放。存储层的重命名有配套的专项测试覆盖TestUpdateIssueIDUpdatesWispDependencyTargets、TestUpdateIssueIDUpdatesPersistentDependencyTargets、TestUpdateIssueIDDependencyTargetCollisionFails等均位于 internal/storage/dolt/rename_test.go分别验证 wisp 依赖目标、持久化依赖行、目标冲突报错等场景。八、相关配置与使用限制前缀配置项为issue_prefix不能通过bd config set修改。配置文档 docs/reference/configuration.md 明确说明设置前缀只能走bd init --prefix、bd bootstrap或bd rename-prefix三条路径。rename-prefix正是唯一支持“事后修改已有库前缀”的途径。命令注册在maint分组见 cmd/bd/rename_prefix.go 与 docs/CLI_REFERENCE.md与bd doctor、bd gc等维护类命令并列。proxied-server 模式下执行会直接报错rename-prefix is not supported in proxied-server mode。命令支持--json全局输出普通重命名返回old_prefix/new_prefix/issues_count修复模式返回target_prefix/prefixes_found/issues_repaired/issues_unchanged配置修复场景额外带config_repaired: true便于脚本化集成。git worktree 场景不受旧版“禁止从 worktree 运行”限制测试 cmd/bd/rename_prefix_worktree_test.go 验证了 worktree 下会正确解析主仓库的.beads数据库路径因此可以从 worktree 中对主库执行该命令。九、安全执行建议先预演任何真实执行前先跑一次bd rename-prefix prefix --dry-run核对示例映射与“待修 Issue 数量”。检查前缀污染若输出显示 Multiple prefixes说明库已处于不一致状态务必带--repair并先备份。了解非原子性普通重命名为逐 Issue 事务提交中途失败可能部分完成执行前用bd backup或仓库快照做好恢复预案。验证结果执行后运行bd list确认新前缀生效、旧前缀无残留并抽查正文引用是否同步更新。延伸阅读命令实现cmd/bd/rename_prefix.go前缀提取启发式算法internal/utils/issue_id.go存储层 ID 重命名与 journal 记录internal/storage/issueops/bulk_ops.go集成测试cmd/bd/rename_prefix_embedded_test.go、internal/storage/dolt/rename_test.goAgent 技能文档plugins/beads/skills/beads/commands/rename-prefix.md配置说明docs/reference/configuration.md【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考