beads 与 Azure DevOps 双向同步实战bd ado 命令全解与源码级原理【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本篇指南围绕 beads 的 Azure DevOpsADO集成命令bd ado展开完整覆盖从连接配置、项目探查、状态检查到双向同步的完整操作链路并深入cmd/bd/ado.go与internal/ado/源码讲清过滤、冲突解决、字段映射、首次匹配、对账与依赖链接同步的底层机制。读完你可以直接配置 ADO 凭据并落地可复用的 issue 同步工作流。一、bd ado 是什么beads 与 Azure DevOps 的同步桥梁bd ado是 beads 提供的一组命令用于在 beads 本地 issue 数据库与 Azure DevOps 工作项work item之间同步 issue。它实现了真正意义上的双向同步从 Azure DevOps 拉取pull新增/更新的工作项到 beads将本地 beads issue 推送push到 Azure DevOps。该命令族的命令定义位于 cmd/bd/ado.go底层与 Azure DevOps REST API 交互的完整实现位于 internal/ado 包包括客户端client.go、跟踪器tracker.go、字段映射fieldmapper.go、mapping.go、首次同步去重bootstrap.go、对账reconcile.go、依赖链接同步links.go与 API 数据类型types.go。bd ado下共有 5 个子命令子命令作用bd ado projects列出当前 PAT 可访问的 Azure DevOps 项目bd ado pull从 ADO 定向拉取一个或多个工作项bd ado push将本地 beads issue 定向推送到 ADObd ado status显示当前 ADO 配置与同步状态bd ado sync核心命令在 beads 与 ADO 之间同步 issue二、连接配置bd config 与环境变量双通道bd ado的所有子命令都依赖一组连接配置可以通过bd config持久化也可以通过环境变量注入。二者等价代码中通过getADOConfigValue统一读取先查 beads 配置存储再回退到环境变量见 cmd/bd/ado.go#L193-L220。配置键bd config set环境变量说明ado.orgAZURE_DEVOPS_ORG组织名Organizationado.projectAZURE_DEVOPS_PROJECT项目名单值向后兼容ado.projectsAZURE_DEVOPS_PROJECTS项目名列表逗号分隔ado.patAZURE_DEVOPS_PAT个人访问令牌Personal Access Tokenado.urlAZURE_DEVOPS_URL自定义基础 URL用于本地部署的 Azure DevOps Server配置键到环境变量的映射集中在 cmd/bd/ado.go#L223-L238 的adoConfigToEnvVar中。示例# 方式一通过 bd config 持久化 bd config set ado.org myorg bd config set ado.project myproject bd config set ado.pat xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 方式二通过环境变量注入 export AZURE_DEVOPS_ORGmyorg export AZURE_DEVOPS_PROJECTmyproject export AZURE_DEVOPS_PATxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx几点源码级注意事项必填项校验ado sync、ado projects等命令执行前会调用validateADOConfigcmd/bd/ado.go#L241-L252校验三项PAT 必须配置ado.org与ado.url至少配置其一至少配置一个项目。缺失时命令会给出明确的设置指引。多项目支持ado.projects支持逗号分隔的多个项目名。代码用tracker.ResolveProjectIDs解析多值优先ado.project作为单值回退cmd/bd/ado.go#L181-L187。同步时 WIQL 查询会跨多个项目执行。密钥安全ado.pat属于 yaml-only 配置键读取时优先从config.yaml读取而非 Dolt 数据库避免将凭据随数据库推送泄漏到远程见 internal/ado/tracker.go#L331-L356。此外 PAT 在内部被包装为SecretString类型fmt输出与 JSON 序列化时都会显示[REDACTED]不会泄露明文internal/ado/types.go#L101-L131。内部部署ado.url用于 Azure DevOps Server 本地部署。代码强制要求非 localhost 地址必须使用 HTTPS仅localhost/127.0.0.1/::1允许 HTTP 用于本地测试internal/ado/client.go#L126-L152。三、bd ado projects探查令牌可访问的项目bd ado projects用于列出当前 PAT 在组织下可访问的所有团队项目便于确认凭据配置是否正确、项目名拼写是否准确bd ado projects人类可读输出示例Azure DevOps Projects myproject 示例项目描述 another-project该命令支持--json输出返回项目对象数组含id、name、description、state等字段。实现上调用client.ListProjects走的是组织级_apis/projects端点而非项目级端点cmd/bd/ado.go#L414-L463。注意ado projects与ado status、ado sync一样在代理服务器proxied-server模式下不支持会直接报错提示。四、bd ado status检查配置与同步就绪状态bd ado status用于快速查看当前 ADO 配置与同步状态输出内容包含Organization组织名Project / Projects项目名多项目时显示数量PAT脱敏显示仅显示前 4 个字符如xxxx****见 cmd/bd/ado.go#L255-L265Base URL自定义 URL仅配置时显示配置状态✓ Configured / ❌ Not configured及错误原因bd ado status同样支持--json输出JSON 字段包括org、project、projects、has_token、url、configured、error便于脚本化检查配置是否就绪cmd/bd/ado.go#L346-L411。五、bd ado sync核心双向同步命令bd ado sync是集成功能的中枢。默认执行双向同步既从 ADO 拉取新增/更新的工作项到 beads也把本地 beads issue 推送到 ADO。bd ado sync5.1 方向控制Flag作用--pull-only只从 ADO 拉取不推送--push-only只推送本地 issue 到 ADO不拉取两者互斥同时指定会报错cannot use both --pull-only and --push-onlycmd/bd/ado.go#L506-L508。5.2 同步范围选择Flag作用--issues string逗号分隔的 bead ID 列表只同步指定 issue如bd-abc,bd-def。与--parent互斥--parent string只推送该 bead 及其后代仅限 push。与--issues互斥5.3 过滤条件pull 侧 WIQL / push 侧本地过滤以下过滤条件同时影响拉取与推送并且既可以用 CLI flag 临时指定也可以通过配置持久化ado.filter.area_path、ado.filter.iteration_path、ado.filter.types、ado.filter.statesCLI flag 优先于配置值。Flag持久化配置键作用--area-path stringado.filter.area_path按 ADO 区域路径过滤如Project\TeamUNDER 语义包含子路径--iteration-path stringado.filter.iteration_path按迭代路径过滤如Project\Sprint 1--types stringado.filter.types按工作项类型过滤逗号分隔如Bug,Task,User Story--states stringado.filter.states按状态过滤逗号分隔如New,Active,Resolved源码层面CLI flag 通过cmd.Flags().Changed(...)判断是否显式设置未设置时回退读取配置值cmd/bd/ado.go#L302-L344pull 方向过滤条件被翻译进 WIQL 查询的 WHERE 子句。--area-path/--iteration-path使用UNDER运算符包含子路径层级--types/--states使用IN列表internal/ado/client.go#L373-L432。push 方向--types和--states会先把 ADO 的类型/状态值经字段映射反查为 beads 的类型/状态再在本地推送前过滤cmd/bd/ado.go#L939-L984。所有过滤值在进入 WIQL 前都会经过正则白名单校验PullFilters.Validate见 internal/ado/client.go#L56-L74与转义处理escapeWIQL防止查询注入。配置示例持久化过滤条件bd config set ado.filter.types Bug,Task,User Story bd config set ado.filter.states New,Active,Resolved bd config set ado.filter.area_path Project\TeamA5.4 冲突解决策略双向同步可能遇到同一 issue 在两侧都被修改的冲突通过三个互斥 flag 控制策略Flag行为--prefer-newer冲突时采用更新时间最新的版本默认--prefer-local冲突时保留本地 beads 版本--prefer-ado冲突时采用 Azure DevOps 版本三者互斥设置多个会报错getADOConflictStrategycmd/bd/ado.go#L115-L137。底层映射到同步引擎的三种冲突解决模式ConflictTimestamp按时间戳、ConflictLocal、ConflictExternalcmd/bd/ado.go#L574-L582。5.5 安全与幂等控制Flag作用--dry-run只展示将要同步的内容不做任何实际变更结尾提示Run without --dry-run to apply changes--no-create双向都不创建新条目pull 侧跳过未匹配的 ADO 工作项push 侧只更新已关联 ADO 的 issue绝不新建工作项--dry-run模式下sync会跳过只读检查CheckReadonly适合在只读数据库上做预演cmd/bd/ado.go#L502-L504。5.6 首次同步去重Flag作用--bootstrap-match首次同步时启用启发式匹配把 ADO 工作项与本地已有 issue 关联避免创建重复条目匹配按优先级依次尝试三种策略见 internal/ado/bootstrap.goexternal_ref 匹配本地 issue 的 external ref 与 ADO 工作项 URL 完全一致source_system 匹配本地 issue 的 source_system 中记录的 ADO ID 与工作项 ID 一致启发式匹配需--bootstrap-match开启标题相同 beads 类型相同 创建时间差在 24 小时窗口内bootstrapTimeWindow 24 * time.Hourinternal/ado/bootstrap.go#L11-L14。恰有一个候选则匹配成功多个候选则视为歧义并告警不强行关联。匹配成功后会把 ADO external ref 与source_system写回本地 issue实现关联闭环cmd/bd/ado.go#L901-L933。匹配到多个候选时输出Ambiguous bootstrap match警告匹配成功输出Bootstrap matched ADO #x → bd-xxx。5.7 对账扫描Flag作用--reconcile强制触发一次删除项对账扫描对账reconciliation用于检测已在 ADO 侧删除或无权访问的工作项防止本地残留僵尸 issue。默认每 10 次同步自动执行一次DefaultReconcileInterval 10可用配置ado.reconcile_interval调整见 internal/ado/reconcile.go#L13-L21。对账流程cmd/bd/ado.go#L608-L676收集所有带 ADO external ref 的本地 issue得到 ADO 工作项 ID 集合批量向 ADO 查询这些工作项404已删除与 403无权限的工作项被单独标记已删除404自动关闭对应本地 issue关闭原因记录为ADO work item {id} deleted无权限403输出ADO work item {id} access denied (403)警告不关闭本地 issue对账完成后计数器归零否则每成功同步一次累加 1。5.8 输出与统计bd ado sync支持--json输出返回结构化统计字段cmd/bd/ado.go#L465-L482JSON 字段含义dry_run是否试运行pulled/pushed拉取/推送的 issue 数created/updated新建/更新数skipped/conflicts/errors跳过/冲突/错误数links_pushed同步的依赖链接数bootstrap_matched首次匹配成功的数量reconciled/reconcile_checked/reconcile_deleted/reconcile_denied对账结果人类可读输出示例✓ Bootstrap matched 5 issues ✓ Pulled 12 issues (10 created, 2 updated) ✓ Pushed 8 issues ✓ Synced 3 dependency links → Resolved 2 conflicts ✓ Reconciled 20 work items (1 deleted)六、bd ado pull 与 bd ado push定向快捷命令两个定向命令本质上是bd ado sync的语法糖bd ado pull [refs...]等价于bd ado sync --pull-only --issues refs位置参数接受 bead ID 或外部引用ADO 工作项 URLbd ado push [bead-ids...]等价于bd ado sync --push-only --issues ids位置参数接受 bead ID。两者都支持--dry-run预演# 只拉取指定工作项预览 bd ado pull https://dev.azure.com/myorg/myproject/_workitems/edit/123 --dry-run # 只拉取指定工作项实际执行 bd ado pull https://dev.azure.com/myorg/myproject/_workitems/edit/123 # 只推送指定本地 issue预览 bd ado push bd-abc,bd-def --dry-run # 只推送指定本地 issue实际执行 bd ado push bd-abc,bd-def七、字段映射beads 与 ADO 数据模型的对齐双向同步的核心难点在于两套数据模型并不一致internal/ado/fieldmapper.go与internal/ado/mapping.go完成了这套转换。7.1 状态映射默认 Agile 模板beads 状态ADO 状态push 方向ADO 状态pull 方向openNewNew → openin-progressActiveActive → in-progressblockedActive附加beads:blocked标签Active beads:blocked标签 → blockeddeferredRemovedRemoved → deferredclosedClosedResolved / Closed → closed值得注意的细节ADO 没有 blocked 状态因此 beads 的 blocked 在推送时被映射为Active并在标签中写入beads:blocked内部标签拉取时反向识别该标签恢复 blocked 状态internal/ado/mapping.go#L44-L48。同理所有beads:*内部标签在拉取时会被过滤不混入用户标签filterBeadsTags。7.2 类型映射beads 类型ADO 工作项类型push 方向ADO 类型pull 方向bugBugBug → bugfeatureUser StoryUser Story / Product Backlog Item → featureepicEpicEpic → epictaskTaskTask → taskchoreTask其他未知类型默认 → task7.3 优先级映射有损映射与恢复机制pull 方向ADO 优先级 1→0、2→1、3→2、4→3beads 优先级 0-4未知默认 2push 方向beads 0→1、1→2、2→3、3→4、4→4有损beads 3 和 4 都映射到 ADO 4。为弥补这个有损映射beads 3/4 在推送时会把原始优先级写入元数据beads_priority拉取时再从中恢复internal/ado/mapping.go#L124-L138。此外ADO 的 Bug 类型强制要求 Severity 字段推送 Bug 时会根据优先级自动推导1 - Critical~4 - LowSeverityForBuginternal/ado/fieldmapper.go#L166-L181。7.4 描述格式转换ADO 工作项描述是 HTMLbeads 是 Markdown。同步时自动完成 HTML ⇄ Markdown 双向转换HTMLToMarkdown/MarkdownToHTMLinternal/ado/mapping.go#L24-L25。7.5 自定义映射可通过配置覆盖默认映射# 自定义状态映射beads 状态 → ADO 状态 bd config set ado.state_map.closed Done # 自定义类型映射beads 类型 → ADO 类型 bd config set ado.type_map.story User Story实现采用前缀扫描读取ado.state_map.*与ado.type_map.*全部键internal/ado/tracker.go#L114-L119支持为自定义工作项类型/状态提供映射。八、底层同步机制与调用链8.1 同步引擎bd ado sync实际委托给tracker.NewEngine(at, store, actor)执行cmd/bd/ado.go#L542-L543at是实现了tracker.IssueTracker接口的 ADO 跟踪器在包初始化时通过tracker.Register(ado, ...)注册internal/ado/tracker.go#L22-L26。CLI 通过PullHooks/PushHooks注入 ADO 特定的拉取bootstrap 匹配、no-create 跳过与推送类型/状态过滤、no-create 限制行为。8.2 ADO 客户端认证、重试与批量internal/ado/client.go实现了 REST 客户端认证采用 HTTP Basic将 PAT 做 Base64 编码放入Authorization头固定使用 API 版本7.1幂等重试GET 请求与 WIQL 查询POST 到/wit/wiql安全可重试最多重试 3 次MaxRetries采用指数退避 抖动jitter并尊重服务端Retry-After头对 429 与 5xx 重试400/401/403/404 视为永久失败直接返回internal/ado/client.go#L186-L287工作项按MaxBatchSize 200批量获取增量同步通过 WIQL 的[System.ChangedDate] YYYY-MM-DD条件实现formatWIQLDate强制 UTC 日期格式因为 ADO 的日期精度字段不接受时间分量。8.3 依赖链接同步beads 的 issue 依赖关系可以同步为 ADO 工作项之间的关系链接relations。在每次非试运行的 push 之后会执行一轮链接同步cmd/bd/ado.go#L596-L606beads 依赖类型 → ADO 链接类型blocks→ Dependency-ForwardPredecessor-Successor、parent-child→ Hierarchy-Reverse、related/discovered-from→ Related反向pull时把 ADO 链接解析回 beads 依赖并做方向归一化例如 Hierarchy-Forward 与 Dependency-Reverse 会交换 from/topush 采用读取-对比-写入的收敛方式只删除 beads 拥有类型 目标在 beads 管理集合内的过期链接保留人工创建或指向未跟踪项的链接避免覆盖他人数据internal/ado/links.go#L232-L333。九、常见问题排查Q1提示ado.pat not configured或ado.org not configured配置未就绪。按第二节方式设置bd config set ado.pat ...、bd config set ado.org ...、bd config set ado.project ...或导出对应环境变量然后用bd ado status验证。Q2cannot use both --pull-only and --push-only两个方向 flag 互斥只能二选一。Q3cannot use multiple conflict resolution flags--prefer-local、--prefer-ado、--prefer-newer互斥只能设置一个不设置时默认--prefer-newer。Q4ado sync is not supported in proxied-server modeado系列命令目前在代理服务器模式下不可用请使用直接模式direct mode运行。Q5使用ado.url配置内部部署时报 HTTPS 错误非 localhost 地址强制要求 HTTPS。仅localhost/127.0.0.1/::1允许 HTTP用于本地测试。Q6同步后本地出现重复 issue首次接入存量 ADO 时建议使用--bootstrap-match做一次匹配去重后续增量同步会以 external ref 为准不会重复创建。Q7希望完全只读预演所有写操作命令sync、pull、push都支持--dry-run配合bd ado status可先确认配置再执行真实同步。本文以 docs/cli-reference/ado.md 为骨架结合 cmd/bd/ado.go 与 internal/ado 源码展开。若需了解bd config的通用配置用法可参考 config.md涉及同步引擎与字段映射的通用接口可深入 internal/tracker 继续阅读。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考