Beadsbd edit命令详解用 $EDITOR 编辑 Issue 字段的完整指南【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读bd edit是 Beads 命令行工具中用于编辑 Issue 字段的交互式命令它会把 Issue 的某个字段默认是描述写入临时文件唤起你配置的$EDITOR编辑器进行编辑再把编辑结果原子写回 Beads 存储。本文以官方 CLI 文档 docs/cli-reference/edit.md 为主体结合命令入口 cmd/bd/edit.go、代理服务器实现 cmd/bd/edit_proxied_server.go、ID 路由解析 cmd/bd/routed.go 与存储层 internal/storage/embeddeddolt/issues.go 等源码带你掌握bd edit的完整用法、底层执行链路、跨库路由与错误恢复机制并给出可直接复制的实战示例。命令概览bd edit的核心设计目标是用你最熟悉的本地编辑器修改 Beads Issue 的一个字段而不是在终端里敲入易错的长字符串。它属于 Issue 操作类命令GroupID: issues基本语法为bd edit [id] [flags]官方文档给出的最小示例docs/cli-reference/edit.mdbd edit bd-42 # Edit description bd edit bd-42 --title # Edit title bd edit bd-42 --design # Edit design notes bd edit bd-42 --notes # Edit notes bd edit bd-42 --acceptance # Edit acceptance criteria参数id是必填的源码中Args: cobra.ExactArgs(1)强制要求恰好一个参数可以是完整 Issue ID也可以是能够唯一解析的短 ID如bd-42或带前缀路由的跨库 ID。不带任何标志时编辑的是 **description描述**字段。编辑完成后命令会输出类似✓ Updated description for issue: bd-42 ...的成功提示✓通过ui.RenderPass渲染源码见 cmd/bd/edit.go。前置条件配置 $EDITORbd edit本身不内置编辑器而是依赖环境变量这一点在官方文档和源码中都有明确体现。编辑器解析优先级见 cmd/bd/edit.go环境变量EDITOR环境变量VISUAL当EDITOR未设置时依次探测vim、vi、nano、emacs找到第一个存在于PATH中的默认编辑器如果以上都不存在命令直接报错退出no editor found. Set $EDITOR or $VISUAL environment variable。因此在使用bd edit之前建议在 shell 配置如~/.bashrc、~/.zshrc中显式设置export EDITORcode --wait # VS Code--wait 保证等待编辑完成 # 或 export EDITORvim # 或 export EDITORnano源码对$EDITOR的值做了空白切分strings.Fields(editor)因此code --wait、vim -f这类命令 参数的写法都能被正确解析第一个 token 作为可执行文件其余 token 作为参数追加最后再附上临时文件路径cmd/bd/edit.go。如果你习惯使用VISUAL变量同样会被兼容识别。Flags 详解五个可编辑字段官方文档列出的全部标志如下docs/cli-reference/edit.md--acceptance Edit the acceptance criteria --description Edit the description (default) --design Edit the design notes --notes Edit the notes --title Edit the title在 cmd/bd/edit.go 中这五个标志被注册为布尔型Bool标志。字段选择逻辑为标志内部字段名说明默认description编辑描述缺省行为--titletitle编辑标题--designdesign编辑设计笔记design notes--notesnotes编辑备注--acceptanceacceptance_criteria编辑验收标准acceptance criteria字段判定依据的是标志是否被用户显式触发cmd.Flags().Changed(...)其优先级顺序为--title--design--notes--acceptance当这些标志都未被触发时回落到默认的descriptioncmd/bd/edit.go。因此即使同时传入多个标志也只会有一个字段被编辑。命令行还注册了issueIDCompletion作为 ID 补全函数在支持 shell 补全的环境下输入bd edit TAB可以获得候选 Issue ID。从字段名到 Issue 数据结构的映射也值得注意命令行使用连字符风格--acceptance底层 Issue 结构中的字段名是下划线风格acceptance_criteria成功提示中又会把下划线还原为空格显示为acceptance criteria见 cmd/bd/edit.go 与 cmd/bd/edit.go。这些字段与 docs/cli-reference/create.md 中--description、--design、--notes、--acceptance等创建参数一一对应形成创建—编辑闭环。完整工作流程一次编辑在底层发生了什么从 cmd/bd/edit.go 的RunE主流程看一次bd edit的完整生命周期如下只读保护检查调用CheckReadonly(edit)若当前数据库处于只读/不可变模式则拒绝执行见 cmd/bd/errors.go。命令事件埋点创建metrics.NewCommandEvent(edit)记录命令执行情况结束后写入全局 metrics 收集器。模式分发调用usesProxiedServer()判断当前运行环境——若使用代理服务器模式Dolt server则转交runEditProxiedServer见下文代理服务器模式一节否则走嵌入式存储路径。ID 解析与路由调用resolveAndGetIssueForMutation(ctx, store, id)解析短 ID 并获取 Issue该函数支持本地库 → 前缀路由 → 贡献者自动路由三级查找详见下文ID 解析与跨库路由。读取当前字段值按上表把目标字段的当前内容读入内存作为编辑的初始内容。创建临时文件使用os.CreateTemp(, bd-edit-field-*.txt)在系统临时目录创建文件把当前值写入其中然后关闭文件句柄cmd/bd/edit.go。唤起编辑器按上文优先级确定编辑器命令绑定当前进程的 stdin/stdout/stderr 后运行。这意味着vim、nano等交互式编辑器可以正常获得终端控制权code --wait这类 GUI 编辑器也会阻塞等待用户关闭文件。读回编辑结果编辑器退出后读取临时文件内容并执行strings.TrimSpace去除首尾空白cmd/bd/edit.go。无变化短路如果TrimSpace后的内容与原始内容完全一致则输出No changes made并直接返回不产生任何数据库写入cmd/bd/edit.go。标题非空校验如果编辑的是title且结果为空白报错title cannot be emptycmd/bd/edit.go。写回数据库构造updatesmap仅包含被编辑的那一个字段调用issueStore.UpdateIssue(ctx, id, updates, actor)持久化修改。故障自愈重试如果更新失败先检查存储是否实现了storage.RawDBAccessor接口若是则对底层数据库连接执行一次PingContext并重置ConnMaxIdleTime(0)后重试一次更新——这是针对 Dolt 连接因空闲被回收导致偶发失败的恢复逻辑cmd/bd/edit.go。嵌入式模式自动提交若处于嵌入式embedded Dolt模式调用commitPendingIfEmbedded以Command: edit和本次 Issue ID 发起自动提交见 cmd/bd/dolt_autocommit.go。输出结果打印✓ Updated field name for issue: id title其中若编辑的是标题则展示新标题cmd/bd/edit.go。存储层原理UpdateIssue 是如何落库的bd edit的所有字段写入最终都汇聚到存储接口的UpdateIssue。以嵌入式 Dolt 存储为例实现在 internal/storage/embeddeddolt/issues.go若更新内容包含metadata字段会先做元数据规范化与 schema 校验storage.NormalizeMetadataValueissueops.ValidateMetadataIfConfigured不符合配置的元数据 schema 会在写库前被拒绝之后在单个 SQL 事务内把更新委托给issueops.UpdateIssueInTx(ctx, tx, id, updates, actor)事务提交由嵌入式 Dolt 自动完成——也就是说更新 提交是原子的。这意味着bd edit并非简单地改写一个文本文件而是走完整的 IssueOps 更新管线与bd update等命令共享同一套字段更新语义含事件记录、行版本等副作用。此外存储层还提供了UpdateIssueCheckedinternal/storage/embeddeddolt/issues.go支持版本号ExpectedVersion、指派人ExpectedAssignee、状态ExpectedStatus等原子前置条件校验供需要比较并交换CAS语义的高级调用方使用——bd edit本身是读取-编辑-写回的宽松语义。ID 解析与跨库路由bd edit xe-5ls为什么也能工作Beads 支持多数据库rig协作Issue ID 往往带有前缀如hr-、hq-。bd edit使用的resolveAndGetIssueForMutationcmd/bd/routed.go实现了三级查找本地库优先先在当前数据库中用utils.ResolvePartialID解析短 ID 并读取 Issuecmd/bd/routed.go前缀路由若本地未找到从 ID 提取前缀如hr-8wn.1→hr-在.beads/routes.jsonl中查找前缀到 rig 目录的映射打开目标 rig 的数据库继续解析。注意源码注释明确指出普通读命令使用只读打开而变更类命令包括bd edit必须通过resolveAndGetIssueForMutation以可写模式打开目标库从而保证路由到外库的修改能真正提交回该库同时避免只读打开时把迁移等副作用写进他人项目cmd/bd/routed.go贡献者自动路由作为兜底尝试打开贡献者项目进行只读查找该路径保持只读绝不对外部贡献者库做写入见 cmd/bd/routed.go。路由查找涉及环境变量BEADS_DOLT_SERVER_DATABASE的临时切换以便共享 Dolt 服务器上的存储能连接到正确的目标数据库调试时设置BD_DEBUG_ROUTING可在 stderr 打印路由决策cmd/bd/routed.go。routes.jsonl的每一行是一个 JSON 对象形如{prefix:hr-,path:herald}#开头的行为注释。代理服务器模式runEditProxiedServer当 Beads 通过代理服务器shared Dolt server运行时bd edit走 cmd/bd/edit_proxied_server.go 中的runEditProxiedServer。它与嵌入式路径的差异在于通过proxiedOpenReadUOW打开只读工作单元UOW调用workapi.GetIssueOrWisp获取 Issue若找不到则返回issue %s not found字段选择、临时文件编辑、TrimSpace、无变化短路、标题非空校验等逻辑与嵌入式路径完全一致最终写入调用proxiedUpdateIssueFields(ctx, id, bd: edit id, updates, false)定义于 cmd/bd/mutate_proxied_server.go把字段更新提交到服务器端。这种本地打开 UOW 读取 服务器端提交的分工保证了在代理模式下bd edit依然只有一次原子更新且能复用服务器端的事务与事件记录能力。数据安全与错误恢复你的编辑内容不会丢bd edit对失败场景做了专门的保护设计临时文件保留只要出现写库失败或提交失败命令会向 stderr 打印Your edits are preserved in: tmpPath告知你编辑内容保存在哪个临时文件中cmd/bd/edit.go。只有在写库/提交成功后临时文件才会被删除editSaved true时 defer 清理。无变化不写库未修改内容直接返回No changes made避免产生无意义的版本记录。标题不允许为空防止把 Issue 标题改成空串导致数据不完整。连接级自愈更新失败时通过 ping 数据库连接并重置空闲连接上限后重试一次尽可能消除空闲连接被回收导致的偶发失败cmd/bd/edit.go。测试验证与实战建议bd edit的核心行为有集成测试覆盖见 cmd/bd/field_mutation_proxied_integration_test.go 的TestProxiedServerEdit测试创建一个描述为original body的 Issue写一个editor.sh脚本把固定文本写入$1指向的文件设置EDITOReditor.sh后执行bd edit断言输出包含Updated description且 Issue 描述变为edited via proxied editor。这说明把EDITOR指向任意脚本/程序即可完全自动化bd edit——例如在 CI 或 Agent 工作流中用脚本把新内容写入临时文件实现无头编辑。综合实战建议优先用bd show id查看当前字段内容再决定编辑哪个字段--long可看全字段docs/cli-reference/show.md编辑器选择上终端内使用推荐vim/nano远程/Agent 场景推荐EDITORcode --wait或指向自动化脚本明确要修改的目标字段用对应 flag 一次只改一个字段避免多字段混合提交利用短 ID 与 shell 补全快速定位 Issue跨库场景直接使用带前缀的完整 ID如bd edit hr-8wn.1即可触发前缀路由若命令中途失败按 stderr 提示的临时文件路径找回编辑内容重跑命令即可。小结bd edit用临时文件 外部编辑器 原子写回的经典 Unix 设计把 Issue 字段编辑从敲长命令变成在你最顺手的编辑器里改完即存同时通过前缀路由、代理模式、连接自愈与临时文件兜底保证了跨库协作场景下的可用性与数据安全。掌握它是高效使用 Beads 管理 Issue 生命周期的重要一环。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Beads `bd edit` 命令详解：用 $EDITOR 编辑 Issue 字段的完整指南
Beadsbd edit命令详解用 $EDITOR 编辑 Issue 字段的完整指南【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读bd edit是 Beads 命令行工具中用于编辑 Issue 字段的交互式命令它会把 Issue 的某个字段默认是描述写入临时文件唤起你配置的$EDITOR编辑器进行编辑再把编辑结果原子写回 Beads 存储。本文以官方 CLI 文档 docs/cli-reference/edit.md 为主体结合命令入口 cmd/bd/edit.go、代理服务器实现 cmd/bd/edit_proxied_server.go、ID 路由解析 cmd/bd/routed.go 与存储层 internal/storage/embeddeddolt/issues.go 等源码带你掌握bd edit的完整用法、底层执行链路、跨库路由与错误恢复机制并给出可直接复制的实战示例。命令概览bd edit的核心设计目标是用你最熟悉的本地编辑器修改 Beads Issue 的一个字段而不是在终端里敲入易错的长字符串。它属于 Issue 操作类命令GroupID: issues基本语法为bd edit [id] [flags]官方文档给出的最小示例docs/cli-reference/edit.mdbd edit bd-42 # Edit description bd edit bd-42 --title # Edit title bd edit bd-42 --design # Edit design notes bd edit bd-42 --notes # Edit notes bd edit bd-42 --acceptance # Edit acceptance criteria参数id是必填的源码中Args: cobra.ExactArgs(1)强制要求恰好一个参数可以是完整 Issue ID也可以是能够唯一解析的短 ID如bd-42或带前缀路由的跨库 ID。不带任何标志时编辑的是 **description描述**字段。编辑完成后命令会输出类似✓ Updated description for issue: bd-42 ...的成功提示✓通过ui.RenderPass渲染源码见 cmd/bd/edit.go。前置条件配置 $EDITORbd edit本身不内置编辑器而是依赖环境变量这一点在官方文档和源码中都有明确体现。编辑器解析优先级见 cmd/bd/edit.go环境变量EDITOR环境变量VISUAL当EDITOR未设置时依次探测vim、vi、nano、emacs找到第一个存在于PATH中的默认编辑器如果以上都不存在命令直接报错退出no editor found. Set $EDITOR or $VISUAL environment variable。因此在使用bd edit之前建议在 shell 配置如~/.bashrc、~/.zshrc中显式设置export EDITORcode --wait # VS Code--wait 保证等待编辑完成 # 或 export EDITORvim # 或 export EDITORnano源码对$EDITOR的值做了空白切分strings.Fields(editor)因此code --wait、vim -f这类命令 参数的写法都能被正确解析第一个 token 作为可执行文件其余 token 作为参数追加最后再附上临时文件路径cmd/bd/edit.go。如果你习惯使用VISUAL变量同样会被兼容识别。Flags 详解五个可编辑字段官方文档列出的全部标志如下docs/cli-reference/edit.md--acceptance Edit the acceptance criteria --description Edit the description (default) --design Edit the design notes --notes Edit the notes --title Edit the title在 cmd/bd/edit.go 中这五个标志被注册为布尔型Bool标志。字段选择逻辑为标志内部字段名说明默认description编辑描述缺省行为--titletitle编辑标题--designdesign编辑设计笔记design notes--notesnotes编辑备注--acceptanceacceptance_criteria编辑验收标准acceptance criteria字段判定依据的是标志是否被用户显式触发cmd.Flags().Changed(...)其优先级顺序为--title--design--notes--acceptance当这些标志都未被触发时回落到默认的descriptioncmd/bd/edit.go。因此即使同时传入多个标志也只会有一个字段被编辑。命令行还注册了issueIDCompletion作为 ID 补全函数在支持 shell 补全的环境下输入bd edit TAB可以获得候选 Issue ID。从字段名到 Issue 数据结构的映射也值得注意命令行使用连字符风格--acceptance底层 Issue 结构中的字段名是下划线风格acceptance_criteria成功提示中又会把下划线还原为空格显示为acceptance criteria见 cmd/bd/edit.go 与 cmd/bd/edit.go。这些字段与 docs/cli-reference/create.md 中--description、--design、--notes、--acceptance等创建参数一一对应形成创建—编辑闭环。完整工作流程一次编辑在底层发生了什么从 cmd/bd/edit.go 的RunE主流程看一次bd edit的完整生命周期如下只读保护检查调用CheckReadonly(edit)若当前数据库处于只读/不可变模式则拒绝执行见 cmd/bd/errors.go。命令事件埋点创建metrics.NewCommandEvent(edit)记录命令执行情况结束后写入全局 metrics 收集器。模式分发调用usesProxiedServer()判断当前运行环境——若使用代理服务器模式Dolt server则转交runEditProxiedServer见下文代理服务器模式一节否则走嵌入式存储路径。ID 解析与路由调用resolveAndGetIssueForMutation(ctx, store, id)解析短 ID 并获取 Issue该函数支持本地库 → 前缀路由 → 贡献者自动路由三级查找详见下文ID 解析与跨库路由。读取当前字段值按上表把目标字段的当前内容读入内存作为编辑的初始内容。创建临时文件使用os.CreateTemp(, bd-edit-field-*.txt)在系统临时目录创建文件把当前值写入其中然后关闭文件句柄cmd/bd/edit.go。唤起编辑器按上文优先级确定编辑器命令绑定当前进程的 stdin/stdout/stderr 后运行。这意味着vim、nano等交互式编辑器可以正常获得终端控制权code --wait这类 GUI 编辑器也会阻塞等待用户关闭文件。读回编辑结果编辑器退出后读取临时文件内容并执行strings.TrimSpace去除首尾空白cmd/bd/edit.go。无变化短路如果TrimSpace后的内容与原始内容完全一致则输出No changes made并直接返回不产生任何数据库写入cmd/bd/edit.go。标题非空校验如果编辑的是title且结果为空白报错title cannot be emptycmd/bd/edit.go。写回数据库构造updatesmap仅包含被编辑的那一个字段调用issueStore.UpdateIssue(ctx, id, updates, actor)持久化修改。故障自愈重试如果更新失败先检查存储是否实现了storage.RawDBAccessor接口若是则对底层数据库连接执行一次PingContext并重置ConnMaxIdleTime(0)后重试一次更新——这是针对 Dolt 连接因空闲被回收导致偶发失败的恢复逻辑cmd/bd/edit.go。嵌入式模式自动提交若处于嵌入式embedded Dolt模式调用commitPendingIfEmbedded以Command: edit和本次 Issue ID 发起自动提交见 cmd/bd/dolt_autocommit.go。输出结果打印✓ Updated field name for issue: id title其中若编辑的是标题则展示新标题cmd/bd/edit.go。存储层原理UpdateIssue 是如何落库的bd edit的所有字段写入最终都汇聚到存储接口的UpdateIssue。以嵌入式 Dolt 存储为例实现在 internal/storage/embeddeddolt/issues.go若更新内容包含metadata字段会先做元数据规范化与 schema 校验storage.NormalizeMetadataValueissueops.ValidateMetadataIfConfigured不符合配置的元数据 schema 会在写库前被拒绝之后在单个 SQL 事务内把更新委托给issueops.UpdateIssueInTx(ctx, tx, id, updates, actor)事务提交由嵌入式 Dolt 自动完成——也就是说更新 提交是原子的。这意味着bd edit并非简单地改写一个文本文件而是走完整的 IssueOps 更新管线与bd update等命令共享同一套字段更新语义含事件记录、行版本等副作用。此外存储层还提供了UpdateIssueCheckedinternal/storage/embeddeddolt/issues.go支持版本号ExpectedVersion、指派人ExpectedAssignee、状态ExpectedStatus等原子前置条件校验供需要比较并交换CAS语义的高级调用方使用——bd edit本身是读取-编辑-写回的宽松语义。ID 解析与跨库路由bd edit xe-5ls为什么也能工作Beads 支持多数据库rig协作Issue ID 往往带有前缀如hr-、hq-。bd edit使用的resolveAndGetIssueForMutationcmd/bd/routed.go实现了三级查找本地库优先先在当前数据库中用utils.ResolvePartialID解析短 ID 并读取 Issuecmd/bd/routed.go前缀路由若本地未找到从 ID 提取前缀如hr-8wn.1→hr-在.beads/routes.jsonl中查找前缀到 rig 目录的映射打开目标 rig 的数据库继续解析。注意源码注释明确指出普通读命令使用只读打开而变更类命令包括bd edit必须通过resolveAndGetIssueForMutation以可写模式打开目标库从而保证路由到外库的修改能真正提交回该库同时避免只读打开时把迁移等副作用写进他人项目cmd/bd/routed.go贡献者自动路由作为兜底尝试打开贡献者项目进行只读查找该路径保持只读绝不对外部贡献者库做写入见 cmd/bd/routed.go。路由查找涉及环境变量BEADS_DOLT_SERVER_DATABASE的临时切换以便共享 Dolt 服务器上的存储能连接到正确的目标数据库调试时设置BD_DEBUG_ROUTING可在 stderr 打印路由决策cmd/bd/routed.go。routes.jsonl的每一行是一个 JSON 对象形如{prefix:hr-,path:herald}#开头的行为注释。代理服务器模式runEditProxiedServer当 Beads 通过代理服务器shared Dolt server运行时bd edit走 cmd/bd/edit_proxied_server.go 中的runEditProxiedServer。它与嵌入式路径的差异在于通过proxiedOpenReadUOW打开只读工作单元UOW调用workapi.GetIssueOrWisp获取 Issue若找不到则返回issue %s not found字段选择、临时文件编辑、TrimSpace、无变化短路、标题非空校验等逻辑与嵌入式路径完全一致最终写入调用proxiedUpdateIssueFields(ctx, id, bd: edit id, updates, false)定义于 cmd/bd/mutate_proxied_server.go把字段更新提交到服务器端。这种本地打开 UOW 读取 服务器端提交的分工保证了在代理模式下bd edit依然只有一次原子更新且能复用服务器端的事务与事件记录能力。数据安全与错误恢复你的编辑内容不会丢bd edit对失败场景做了专门的保护设计临时文件保留只要出现写库失败或提交失败命令会向 stderr 打印Your edits are preserved in: tmpPath告知你编辑内容保存在哪个临时文件中cmd/bd/edit.go。只有在写库/提交成功后临时文件才会被删除editSaved true时 defer 清理。无变化不写库未修改内容直接返回No changes made避免产生无意义的版本记录。标题不允许为空防止把 Issue 标题改成空串导致数据不完整。连接级自愈更新失败时通过 ping 数据库连接并重置空闲连接上限后重试一次尽可能消除空闲连接被回收导致的偶发失败cmd/bd/edit.go。测试验证与实战建议bd edit的核心行为有集成测试覆盖见 cmd/bd/field_mutation_proxied_integration_test.go 的TestProxiedServerEdit测试创建一个描述为original body的 Issue写一个editor.sh脚本把固定文本写入$1指向的文件设置EDITOReditor.sh后执行bd edit断言输出包含Updated description且 Issue 描述变为edited via proxied editor。这说明把EDITOR指向任意脚本/程序即可完全自动化bd edit——例如在 CI 或 Agent 工作流中用脚本把新内容写入临时文件实现无头编辑。综合实战建议优先用bd show id查看当前字段内容再决定编辑哪个字段--long可看全字段docs/cli-reference/show.md编辑器选择上终端内使用推荐vim/nano远程/Agent 场景推荐EDITORcode --wait或指向自动化脚本明确要修改的目标字段用对应 flag 一次只改一个字段避免多字段混合提交利用短 ID 与 shell 补全快速定位 Issue跨库场景直接使用带前缀的完整 ID如bd edit hr-8wn.1即可触发前缀路由若命令中途失败按 stderr 提示的临时文件路径找回编辑内容重跑命令即可。小结bd edit用临时文件 外部编辑器 原子写回的经典 Unix 设计把 Issue 字段编辑从敲长命令变成在你最顺手的编辑器里改完即存同时通过前缀路由、代理模式、连接自愈与临时文件兜底保证了跨库协作场景下的可用性与数据安全。掌握它是高效使用 Beads 管理 Issue 生命周期的重要一环。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
