Beads 是一个用于 AI 原生 (AI-Native)、Git 集成 (Git-Integrated) 的问题跟踪的命令行界面 (CLI) 工具。它作为一个分布式的、基于 Git 的图形问题跟踪器，用于管理开发任务的生命周期、强制执行工作流以及跟踪代理状态。该系统充当编码代理和人类开发者的持久化、结构化记忆，用于管理任务及其关系。
bd CLI 是与 Beads 进行所有交互的强制性接口。它允许创建、更新、关闭和跟踪问题，以及管理评论和依赖关系。CLI 还可以强制执行会话完成的强制性工作流（特别是针对 AI 代理），并管理所有交互的 审计日志 (Audit Logging)。有关其功能的更多详细信息，请参阅 Beads CLI (bd)。
问题数据以 JSONL (JSON Lines) 文件的形式存储在 Git 仓库的 context 目录中。这利用了 Git 进行问题数据的版本控制、分支和合并。一个本地的 SQLite 数据库作为性能缓存，与这些 Git 跟踪的 JSONL 文件同步。Dolt 是另一种可配置的存储后端。这种同步通常由后台 守护进程 (Daemon) 管理，它还处理自动同步和实时监控。beads-merge 驱动程序智能地解决问题数据中的冲突。有关更多信息，请参阅 Git 集成与冲突解决 和 存储后端选项。
Beads 采用基于哈希的问题 ID，这些 ID 根据数据库大小动态调整长度。该系统平衡了 ID 的简洁性（便于阅读）与在不断增长的数据集中防止冲突的需求。更多信息请参见 自适应问题 ID 管理。
该系统通过 模型上下文协议 (Model Context Protocol, MCP) 服务器与各种 AI 代理集成。该服务器将 beads 功能作为工具公开，AI 代理可以通过编程方式调用这些工具来进行问题和工作流管理。MCP 服务器通过工具模式的 懒加载 (Lazy Loading) 和最小化问题模型等策略来优化 上下文窗口 (Context Window) 的使用。Beads 支持与 Claude Code 和 JetBrains AI Agent (Junie) 等工具集成，以促进 AI 驱动的工作流和多仓库任务管理。请参阅 AI 代理集成与工作流 以了解更深入的内容。
为了自动化和结构化工作，Beads 提供了高级的 工作流原语 (Workflow Primitives)：
- Formulas (公式): 用于定义复杂工作序列的声明式模板，支持继承和变量替换。
- Molecules (分子): 从 Formulas 实例化的持久化工作图，作为 Git 同步的问题存储。
- Wisps (小精灵/微束): 用于临时任务的瞬态工作流，不进行 Git 同步并会自动过期。
这些原语实现了自动化和结构化的任务管理。有关更多信息，请参阅 工作流原语与自动化。支持这些功能的核心架构设计涉及三层数据模型、同步机制和分布式数据库模式。有关更多详细信息，请参阅 核心架构设计。
Beads 介绍：AI 原生、Git 集成的问题跟踪系统#
Beads 是一个 AI 原生 (AI-Native)、Git 集成 (Git-Integrated) 的问题跟踪系统，采用 命令行界面 (CLI) 优先的方法，作为一个分布式的、基于 Git 的图形问题跟踪器，专为 AI 监督的编码设计。其核心目的是提供全面的问题生命周期管理、工作流强制执行、代理状态跟踪、审计日志记录、存储后端配置、版本化分支和数据库管理，有效地充当编码代理的持久化、结构化记忆。
该系统强调自动化工作流以及与 Git 的同步，用一个能够感知依赖关系的任务图谱取代了传统的规划文档，用于管理长期任务。问题以 JSONL 文件的形式存储在 context 目录中，利用 Git 进行版本控制、分支和合并。本地 SQLite 数据库（或配置后的 Dolt）充当性能缓存，确保数据一致性并支持高级功能。
Beads 通过 CLI 命令（如 create、update、close、reopen 和 delete）促进问题生命周期管理。这些命令专为人类开发者和 AI 代理设计，允许结构化的任务管理。工作流强制执行是不可或缺的一部分，定义了会话完成的强制性工作流（特别是针对 AI 代理），详情见 AGENTS.md。系统还通过 cmd/bd/audit.go 中的 auditCmd 等机制提供代理状态跟踪和审计日志记录，管理代理交互的仅追加日志。
该项目与 Git 的深度集成是一个基础方面。问题存储在 JSONL 文件中，以实现版本控制、分支和合并。同步机制确保通过 CLI 进行的更改反映在 Git 仓库中，反之亦然，通常由后台 守护进程 (Daemon) 管理以进行自动同步、RPC 操作和实时监控。这种同步涉及智能合并驱动程序 (beads-merge) 和针对 context/issues.jsonl 文件的人工冲突解决流程，确保协作环境中的数据完整性。项目还定义了受保护的分支工作流和 Git 钩子以保持一致性。有关 Beads 如何与 Git 集成的更多详细信息，请参阅 Git 集成与冲突解决。
Beads 支持可配置的存储后端，默认使用 SQLite，Dolt 作为替代方案，两者都提供版本控制数据库功能。这种灵活性允许适应不同的操作需求和规模。有关存储选项的更多信息，请参见 存储后端选项。系统还有效地管理问题数据，包括数据库与 Git 之间的自动同步，以及问题的压缩和恢复过程，实现旧任务的 语义摘要 (Semantic Summarization) 和检索。
为了简化复杂工作，Beads 引入了高级 工作流原语 (Workflow Primitives)，如用于声明式模板的 Formulas、用于持久工作图的 Molecules 和用于临时工作流的 Wisps。这些工具实现了自动化和结构化的任务管理，使其适合编排复杂的 AI 代理活动。要深入了解这些原语，请参阅 工作流原语与自动化。支撑这些功能的核心架构设计涉及三层数据模型、同步机制和分布式数据库模式，确保持健壮和可扩展的运行。有关更多信息，请参见 核心架构设计。
bd CLI 是人类开发者和 AI 代理与 Beads 交互的核心。它是项目内所有问题跟踪的强制性接口，涵盖问题生命周期管理、工作流强制执行、数据持久化、代理状态跟踪、审计日志记录、存储后端配置、版本化分支和数据库管理。bd CLI 的广泛功能详见 Beads CLI (bd)。
核心架构设计#
Beads 项目作为一个分布式的、基于 Git 的问题跟踪系统运行，旨在与 AI 监督的编码工作流集成。其架构设计围绕三层模型、健壮的同步机制、分布式数据库模式以及用于管理后台操作和实时监控的守护进程架构构建。
在其核心，Beads 采用 docs/ARCHITECTURE.md 中描述的三层数据模型。CLI Layer（CLI 层）充当用户和 AI 代理的主要接口。它优先通过 RPC 与 daemon（守护进程）通信，如果守护进程不可用，则回退到直接数据库访问。在此之下是 SQLite Database (context/beads.db)，它充当快速的本地工作副本。该数据库存储关键的问题相关数据，包括问题、依赖关系、标签、评论和事件。SQLite Database 自动与 JSONL File (context/issues.jsonl) 同步，后者是 Git 跟踪的 真理之源 (Source of Truth)。这种 JSONL 格式（每个实体存储为一行 JSON）因其在 Git 中的合并友好性而被选中。最后，此 JSONL File 通过标准的 Git push 和 pull 操作与 Remote Repository（远程仓库，如 GitHub, GitLab）同步。这种分层方法利用 SQLite 进行高效的本地操作，利用 JSONL 进行无缝 Git 集成，并利用 Git 进行分布式版本控制。
系统的同步机制对于维护这种分布式架构中的数据一致性至关重要。“写入路径 (Write Path)” 始于 CLI 命令修改问题，触发对 SQLite Database 的立即写入。此操作将数据库标记为“脏 (dirty)”，启动后台进程 (Flusher)，该进程在 防抖 (Debounce) 周期后仅将更改的实体导出到 JSONL File。如果安装了 Git 钩子，随后将进行 Git 提交。反之，“读取路径 (Read Path)” 处理来自远程的更新。在 git pull 获取更新后的 JSONL File 后，下一个 bd 命令会检测 JSONL 是否比本地 SQLite Database 更新。如果是，自动导入过程会将 JSONL 数据合并到 SQLite 中，使用内容哈希解决冲突。随后的 CLI 查询将从更新后的本地 SQLite Database 读取。有关 Git 集成的更多详细信息，请参阅 Git 集成与冲突解决。
这种分布式数据库模式的一个关键方面是防止 ID 冲突。Beads 通过利用基于哈希的 ID 来避免分布式环境中的冲突，这些 ID 派生自随机 UUID。这些问题 ID 起初很短（例如 4 个字符），并根据数据库大小动态扩展以最小化冲突概率，详见 自适应问题 ID 管理。每个问题还包含一个内容哈希，使导入逻辑能够检测更改：如果 ID 和内容哈希匹配，则跳过该问题；如果 ID 匹配但内容哈希不同，则进行更新；如果两者都不匹配，则创建一个新问题。
守护进程架构在启用后台操作和实时监控方面发挥着至关重要的作用。每个工作区都运行一个专用的每工作区守护进程，其中包括 RPC 服务器、自动同步管理器和各种后台任务。CLI 命令通过 RPC 与此守护进程通信。守护进程批量处理操作，保持打开的数据库连接以提高查询性能，并编排自动同步。它会在工作区中的第一个 bd 命令时自动启动（除非明确禁用），并可以使用 bd daemons 命令进行管理，如 docs/DAEMON.md 中所述。
核心数据类型定义在 internal/types/types.go 中，包括 Issue（代表主要工作项）、Dependency（详述关系，如 blocks、parent-child、related 和 discovered-from）、Label（用于灵活标记）、Comment（用于讨论）和 Event（用于综合审计跟踪）。这些类型构成了 Beads 管理的结构化数据，允许进行丰富的问题跟踪和工作流强制执行。
自适应问题 ID 管理#
Beads 采用自适应哈希 ID 长度缩放系统来管理问题标识符。该系统根据数据库大小动态调整问题 ID 的长度，确保 ID 在较小的数据库中保持人类可读，同时防止随着问题数量增长而发生冲突。该设计在可用性（简洁性）与标识符重复的健壮性之间取得了平衡。
核心机制依赖于 生日悖论 (Birthday Paradox) 公式来计算哈希冲突的概率。该计算决定何时增加 ID 长度。例如，随着数据库扩展，系统将自动从较短（如 4 个字符）过渡到较长（如 5 个字符、6 个字符）的 ID，以保持较低的冲突概率。默认情况下，25% 的冲突概率阈值会触发此缩放。如果仍然发生冲突，系统会尝试使用增量增加的长度和不同的随机数生成新 ID，使得实际的冲突失败极不可能发生。
用户可以通过 bd config set 命令配置最大允许冲突概率 (max_collision_prob)，以及最小和最大哈希长度 (min_hash_length, max_hash_length) 来定制此行为。这允许项目根据具体需求微调 ID 简洁性和避免冲突之间的平衡。该系统的数学基础，包括生日悖论公式和 ID 空间大小计算，详见 docs/COLLISION_MATH.md。有关自适应 ID 系统及其配置的更多详细信息，请参见 docs/ADAPTIVE_IDS.md。
Git 集成与冲突解决#
Beads 与 Git 深度集成，使用 JSONL (JSON Lines) 文件作为版本控制、分支和合并问题数据的主要机制。这种方法允许直接在 Git 仓库中管理问题数据，利用 Git 的分布式特性和强大的版本控制功能。核心原则包括同步一个提供快速查询性能的本地 SQLite 数据库与 Git 跟踪的 context/issues.jsonl 文件。
当创建或修改问题时，更改首先写入 SQLite 数据库。然后，这些更改会自动导出到 context/issues.jsonl 文件。该 JSONL 文件作为 Git 版本控制的真理之源，使标准的 Git 操作（如提交、分支和合并）能够直接应用于问题数据。相反，当 Git 拉取操作向 context/issues.jsonl 文件引入更改时，这些更新会自动导回 SQLite 数据库，确保本地数据库反映仓库的最新状态。这种双向同步对于维护不同环境和协作者之间的数据一致性至关重要。有关此过程的更广泛概述，请参阅 核心架构设计。
此集成的一个重要方面是处理问题数据中的合并冲突。Beads 采用基于哈希的问题 ID，这本质上减少了分布式环境中并发创建问题时 ID 冲突的可能性。该系统包含一个智能合并驱动程序 beads-merge，专为解决 context/issues.jsonl 文件中的冲突而设计。该驱动程序执行三路合并，协调问题数据的基础版本、本地版本和远程版本。关于 beads-merge 算法及其集成细节的归属说明记录在 docs/ATTRIBUTION.md 中。
在 beads-merge 的自动合并不足以解决问题，或者缺少标准 Git 冲突标记的情况下，Beads 提供了明确的手动冲突解决机制。这涉及一个分步过程，用户提取冲突的 issues.jsonl 文件的不同版本，并手动执行 bd merge 来解决未决冲突。此工作流详见 context/workflows/resolve-beads-conflict.md。
对于受保护的分支工作流，利用 Git 钩子来确保同步。这些钩子可以触发 bd export 和 bd import 命令，确保在提交之前或合并之后问题数据始终得到更新。这保证了本地数据库和 Git 跟踪的 JSONL 文件始终同步，支持具有受保护分支环境中的协作开发实践。bd sync 命令允许手动、立即同步，执行导出、Git 提交、拉取、导入和推送，以确保所有更改都得到协调。有关 Git 集成的更多详细信息，包括工作树管理和钩子，请参阅 docs/GIT_INTEGRATION.md。
存储后端选项#
beads 支持可配置的存储后端（主要是 SQLite 和 Dolt）来管理问题数据。这些后端提供了版本控制数据库功能的机制，并通过特定配置进行管理。
默认存储后端是 SQLite，它作为本地工作副本用于快速查询并存储所有问题相关数据。SQLite 数据库 (context/beads.db) 与 Git 跟踪的 JSONL 文件 (context/issues.jsonl) 同步。这种同步确保本地所做的更改最终通过标准 Git 操作推送到远程仓库。此过程涉及从 SQLite 到 JSONL 的自动刷新，以及从 JSONL 回到 SQLite 的更新自动导入，通过内容哈希和合并逻辑管理潜在冲突。有关此架构的更多信息，请参见 核心架构设计。
或者，beads 可以配置为使用 Dolt 作为存储后端。Dolt 将 Git 的版本控制原则扩展到数据，允许对数据库本身进行细粒度版本控制。这启用了类似于 Git 管理代码的分支、合并和差异比较数据库更改等功能。集成 Dolt 涉及将 beads 配置为使用它作为主要后端，这可以通过配置命令完成。Dolt 可以在服务器模式下运行，以增强性能和多写入者支持。其高级功能包括 单元格级合并 (Cell-Level Merging)，这有利于协作数据库管理。配置 Dolt 涉及定义同步模式和处理 Dolt 特定的服务器设置，详见 docs/DOLT-BACKEND.md 和 docs/DOLT.md。
这些存储后端的配置在工具级别和项目级别进行管理。工具级配置（通常通过环境变量或 config.yaml 文件 ~/.config/bd/config.yaml 设置）决定全局行为，例如使用哪个后端。项目级配置存储在特定于项目的数据库 (context/*.db) 中，处理与特定仓库相关的设置，例如外部集成的 API 密钥或所选后端的特定参数。cmd 中的 bd config 命令行实用程序有助于管理这些项目级设置。这些配置确保 beads 适应不同的操作环境并与各种版本控制策略集成。有关配置管理的更多详细信息，请参见 数据持久化、同步和数据库管理 和 Beads CLI (bd)。
问题数据管理#
Beads 主要通过 JSONL 文件管理问题数据，这些文件与后端的 SQLite 数据库同步并与 Git 集成以进行版本控制。这种方法确保问题状态与代码更改一起被跟踪，同时支持人类开发者和 AI 代理。
问题存储为 JSONL (JSON Lines) 文件，通常位于 context/issues.jsonl 目录中。这种格式允许高效地、按行分隔存储单个 JSON 对象，其中每个对象代表一个问题。bd 命令行界面 (CLI) 是与这些问题交互和管理的唯一方法，确保一致的工作流。例如，创建新问题、更新其状态或关闭它都使用 bd 命令。AI 代理被专门指导在 bd 命令中使用 --json 标志进行程序化交互，从而促进自动化工作流。有关代理交互的更多详细信息，请参阅 AI 代理集成与工作流。
Beads 的一个关键方面是内部 SQLite 数据库与 Git 版本控制的 JSONL 文件之间的自动同步机制。bd sync 命令是此过程的核心，负责编排将本地更改导出到 context/issues.jsonl，将这些更改提交到 Git，拉取远程更新，然后将任何新的或修改后的 JSONL 数据导回数据库。这确保了问题状态受版本控制，并且可以在团队之间协作管理。该系统包括一个智能 JSONL 合并解决策略，用于处理从远程拉取更改时的冲突。这种同步防止了问题数据的碎片化，并确保所有更改都在 Git 中可追踪，就像源代码一样。问题管理的核心命令在 Beads CLI (bd) 中描述。
为了管理问题数据的长期存储和效率，Beads 实现了压缩和恢复过程。随着时间的推移，已关闭或过时的问题可以使用 bd admin compact 进行“压缩”。此过程对旧问题进行语义摘要，减少它们在数据库中的大小，同时保留基本信息。这可以配置为自动发生或手动触发。相反，bd admin restore 命令允许从 Git 版本控制中检索已压缩问题的完整历史记录。这确保了即使是摘要问题，如果需要也可以完全重建，方法是检出存在原始未压缩数据的历史提交。这些操作有助于保持精简且高性能的问题数据库，同时保留完整的历史记录。
工作流原语与自动化#
Beads 采用了先进的 工作流原语 (Workflow Primitives) 来实现自动化和结构化工作：Formulas（用于声明式模板）、Molecules（用于持久工作图）和 Wisps（用于临时工作流）。这些组件有助于在系统中定义、执行和跟踪工作。
Formulas (公式) 充当声明式工作流模板。它们用 TOML 或 JSON 定义，指定步骤、变量、依赖关系和切面 (aspects)。Formulas 支持继承、变量替换以及一系列步骤转换（包括 advice、expansion 和控制流）等功能。还支持条件评估，允许根据预定义标准动态执行工作流。这些公式的解析和应用（包括循环、分支和门控）在内部组件中管理，特别是在 internal/formula 中。
Molecules (分子) 代表持久化、可追踪的工作图。它们使用 bd pour 等命令从 Formulas 实例化。一旦创建，Molecules 就存储为具有父子关系的问题，并通过 Git 同步，从而实现协作和版本控制的项目管理。bd mol list 和 bd mol show 等命令用于管理这些持久化工作图。
Wisps (小精灵/微束) 提供了一种临时工作流机制。与 Molecules 不同，Wisps 是非 Git 同步的，使用 bd wisp create 等命令为临时任务创建。它们存储在指定的临时目录 (context-wisp/) 中，并设计为自动过期，为短期工作提供了轻量级选项。Wisps 的管理包括列出、显示、删除和清理这些临时工作流。
有关工作流管理和问题自动化的更多详细信息，请参见 Beads CLI (bd)。
Beads CLI (bd)#
bd 命令行界面 (CLI) 是管理 Beads 系统以及与之交互的主要接口，专为人类开发者和 AI 代理设计。它编排整个问题生命周期，强制执行已定义的工作流，跟踪 AI 代理的状态，维护交互的审计日志，配置存储后端，并管理版本化分支和数据库操作。CLI 的全面性意味着它是项目内所有问题跟踪的强制性接口，确保了一致性和对既定流程的遵守。
bd CLI 通过允许用户创建、列出、查看、更新和关闭问题以及管理评论的命令来促进核心问题管理。这些命令对于人类和 AI 驱动的任务管理至关重要，实现了结构化的工作执行和关于任务状态的清晰沟通。列出事件（包括实时或历史问题和 molecule 状态更改）的功能由在 cmd/bd/activity.go 等文件中实现的命令提供。对问题的更新（包括状态更改）由验证输入并与底层存储交互的命令管理，如 cmd/bd/close.go 所示。同样，在 cmd/bd/comments.go 中定义的评论管理功能允许添加和列出与问题相关的评论。
bd 设计的一个关键方面是其在 AI 代理状态跟踪和工作流强制执行中的作用。它为代理提供了报告当前状态和活动的机制，这对于 AI 驱动的开发环境中的监控和问责制至关重要。该设计优先考虑代理的 ZFC 合规状态报告，详见 cmd/bd/agent.go，其中包括设置代理状态、更新心跳和显示代理详细信息的命令。系统还定义了会话完成的强制性工作流，特别是针对 AI 代理，强调 Git 操作和问题状态更新，以确保工作被正确提交和同步，如 cmd/bd/@AGENTS.md 和 cmd/bd/AGENTS.md 中所述。
对于数据持久化和同步，bd CLI 包含强大的机制来管理内存数据库和 Git 版本控制的 JSONL 文件之间的问题数据流。这包括从 JSONL 自动导入更改到数据库，以及将数据库更改原子导出回 JSONL。这些过程处理潜在的冲突并确保不同存储层之间的数据完整性。同步逻辑（包括自动刷新和自动导入功能）在 cmd/bd/autoflush.go 和 cmd/bd/autoimport.go 中描述。数据库管理命令（如清理、压缩和重置）用于管理任务，由 cmd/bd/admin.go 中的 adminCmd 编排。CLI 还支持可配置的存储后端（如 SQLite 和 Dolt），并提供列出和显示当前后端配置的命令，如 cmd/bd/backend.go 所示。此功能扩展到管理版本化分支，特别是对于 Dolt 支持的系统，见 cmd/bd/branch.go。
审计日志是另一个关键功能，所有代理交互都记录为仅追加的 JSONL 条目，作为审计、数据集生成和标记的不可变记录。cmd/bd/audit.go 中的命令管理这些交互的记录和标记。bd CLI 还通过 bd doctor 命令提供诊断和自动修复功能，对常见问题进行全面检查和补救。对于 AI 代理和 IDE 集成，bd setup 命令自动在外部工具中配置 bd，简化了设置过程以实现无缝操作。有关 AI 代理集成的更多详细信息，请参见 AI 代理集成与工作流。
核心问题管理命令#
bd 命令行界面 (CLI) 提供了一组核心命令，用于管理 Beads 系统内的问题生命周期。这些命令对于人类开发者和集成 AI 代理进行交互和管理任务至关重要，确保了结构化工作流和一致的数据。
该系统支持创建、列出、查看、更新和关闭问题，以及管理相关评论。例如，bd ready 允许用户或代理发现可用任务，而 bd show <id> 提供特定问题的详细信息。进度由诸如 bd update <id> --status in_progress（领取工作）和 bd close <id>（标记任务为完成）的命令管理。关闭问题的过程由 cmd/bd/close.go 中定义的 closeCmd 处理，包括验证、钩子以及建议工作流中后续步骤的选项。
问题内的沟通和上下文由管理评论的命令支持。cmd/bd/comments.go 中的 commentsCmd 列出各类现有评论，而 commentsAddCmd（别名为 commentCmd）允许添加新评论，支持指定作者和从文件读取评论。这些功能有助于详细的记录保存和协作，对于需要跟踪其思维过程和行动的 AI 代理至关重要。
问题管理的一个关键方面是强制执行强制性工作流，特别是对于 AI 代理。此工作流详见 cmd/bd/@AGENTS.md 和 cmd/bd/AGENTS.md，概述了会话完成的一系列步骤，强调 git 操作和问题状态更新的重要性。这确保了无论是人类还是 AI 执行的所有工作都被正确地记账并与版本控制系统同步。有关代理状态跟踪和工作流强制执行的更多详细信息，请参阅 代理状态与工作流强制执行。
bd CLI 旨在处理参与者身份解析，优先考虑命令行标志、环境变量（如 BD_ACTOR 或 BEADS_ACTOR）、Git 配置 (user.name) 以及系统的 USER 环境变量，如 cmd/bd/actor_test.go 中测试所示。这确保了对问题的每个操作都归因于特定的参与者，保持问责制和可审计的踪迹。
为了进行全面的问题管理，系统还包含诊断和自动修复功能。例如，bd doctor 命令执行各种检查以确保 beads 环境健康。有关此内容的更多信息，请参见 诊断和自动修复功能 (bd doctor)。这些核心命令，加上强大的工作流强制执行和清晰的归属，构成了 Beads 问题跟踪系统的支柱。
代理状态与工作流强制执行#
bd CLI 在管理 AI 代理的状态、强制执行工作流以及解决 Beads 内的代理身份方面发挥着核心作用。此功能对于在 AI 驱动的开发过程中维护数据一致性和问责制至关重要。
代理状态，如“idle (空闲)”、“running (运行中)”或“dead (死亡)”，在“bead”实体（标记为 gt:agent 的问题）中作为特定的 agent_state 和 last_activity 字段进行跟踪。可用的命令用于更新这些状态并记录心跳，表明代理仍处于活动状态。此信息对于监控系统评估代理健康状况和检测故障至关重要。cmd/bd/agent.go 文件定义了用于设置代理状态、更新其心跳和显示其详细信息的命令。它还包括通过从代理描述中提取信息来回填 role_type 和 rig 标签的功能，从而实现更细粒度的代理筛选和查询。
强制执行会话完成的强制性工作流，以确保工作被正确提交、推送并在问题跟踪器中记账。此工作流详见 cmd/bd/AGENTS.md 和 cmd/bd/@AGENTS.md，概述了 AI 代理必须遵循的一系列 Git 操作和问题状态更新。这包括为剩余工作提交问题、更新问题状态（例如，从“in_progress”到“closed”），以及特定的 Git 推送协议，以确保更改与远程仓库同步。这些规则强调，在 git push 成功更新远程之前，工作不被视为完成，防止本地工作被遗弃。
代理身份解析和路由机制已到位，以处理跨不同仓库的代理。当启动代理操作时，系统可以将请求路由到正确的数据库。例如，cmd/bd/agent_routing_test.go 确认当通过指定了路由规则（在 routes.jsonl 文件中）的“town”数据库访问时，代理状态查找可以正确解析在“rig”数据库中定义的代理。这确保了即使在分布式环境中，代理操作也被定向到适当的数据存储，保持一致性。系统还解析参与者的身份，优先考虑命令行标志、环境变量（BD_ACTOR, BEADS_ACTOR）、Git 配置 (user.name) 以及系统 USER 环境变量，如 cmd/bd/actor_test.go 中的测试所示。
审计日志由 cmd/bd/audit.go 中的命令管理，在问责制中发挥作用。代理交互被记录为 interactions.jsonl 中的仅追加 JSONL 条目。此日志可用于审计目的、生成 AI 代理训练数据集以及标记特定交互。这些审计记录是仅追加的，以确保不可变性和版本控制友好性。
总体而言，bd CLI 确保 AI 代理在一个结构化框架内运行，其状态、工作流和交互都得到细致的跟踪和管理，有助于实现健壮且可审计的 AI 驱动开发。有关 bd CLI 一般功能的概述，请参阅 Beads CLI (bd)。
数据持久化、同步和数据库管理#
bd CLI 提供了一整套功能，用于管理 beads 系统内的数据持久化和同步。这包括自动同步数据库和 Git 之间数据的机制、配置各种存储后端以及执行数据库维护操作。
系统采用自动刷新和自动导入机制，以确保内存数据库和 issues.jsonl 文件（在 Git 中进行版本控制）之间的数据一致性。cmd/bd/autoflush.go 中的 autoImportIfNewer 函数负责通过比较 SHA256 哈希值来检测 issues.jsonl 文件中的外部更改。如果发现更改，它会将它们导入数据库，处理潜在的 ID 重映射，并检测 JSONL 文件内的 Git 合并冲突以防止错误导入。相反，cmd/bd/autoflush.go 中的 flushToJSONLWithState 函数将数据库更改写回 issues.jsonl 文件。此过程支持针对修改后问题的增量更新和针对完整性检查的完整导出，使用原子写入来防止数据损坏。对于新仓库或空数据库，cmd/bd/autoimport.go 中的 checkAndAutoImport 函数编排从 Git 到 beads 数据库的问题初始导入，并遵守 sync-branch 配置。这些同步操作还考虑了 Git 工作树配置，当配置了 sync-branch 时，将 JSONL 路径重定向到专用工作树，以防止与 Git 的 skip-worktree 设置冲突。
用户可以通过 bd backend 命令管理存储后端配置。cmd/bd/backend.go 中的 backendCmd 允许列出可用后端，如 SQLite（默认）、Dolt 和仅 JSONL 模式。cmd/bd/backend.go 中的 backendShowCmd 显示当前配置的后端、其数据库路径以及 Dolt 的特定详细信息（例如服务器主机、端口、用户）。
对于数据库健康和管理，在 cmd/bd/admin.go 中定义的 bd admin 命令提供对维护操作的访问。这些操作包括 cleanupCmd（定义在别处但在 cmd/bd/cleanup.go 中引用）用于删除已关闭的问题和修剪过期的墓碑，compactCmd（定义在别处）用于通过压缩旧问题来优化存储，以及 resetCmd（定义在别处）用于移除所有 beads 数据和配置。此外，对于 Dolt 支持的存储，cmd/bd/branch.go 中的 branchCmd 允许列出和创建新的版本化分支，利用 Dolt 的数据库版本控制能力。cmd/bd/admin_aliases.go 中提供了这些 admin 命令的弃用别名，以实现向后兼容性。
bd audit 命令（定义在 cmd/bd/audit.go 中）处理代理交互的审计日志记录。该命令将事件记录为 interactions.jsonl 中的仅追加 JSONL 条目，作为审计、数据集生成和标记的不可变日志。auditRecordCmd 允许追加新的交互条目，而 auditLabelCmd 允许将标签附加到现有交互，从而维护交互及其标签之间清晰的父子关系。
诊断和自动修复功能 (bd doctor)#
bd doctor 命令为 beads 工作区提供全面的诊断和自动修复系统。它执行跨各种组件的检查，包括 beads 安装本身、Git 集成、守护进程状态、数据库完整性以及与 Claude 和 Gemini 等 AI 环境的兼容性。主要目标是确保健康和一致的 beads 设置，提供可操作的反馈，并在可能的情况下提供自动修复。
该系统旨在识别一系列问题。例如，它通过验证 context/ 目录的存在、识别多个数据库文件、确保正确的文件权限以及检测未跟踪的 context/*.jsonl 文件来检查整体安装和工作区健康状况（cmd/bd/doctor/installation.go）。验证来自 config.yaml、metadata.json 和 SQLite 数据库的配置值是否符合指定的格式和一致性。这包括检查持续时间格式、问题前缀、路由模式、sync-branch 名称和数据库路径（cmd/bd/doctor/config_values.go）。
Git 集成是一个重点领域，诊断涵盖钩子设置、工作树状态、上游同步、合并驱动程序配置以及 sync-branch 的健康状况（cmd/bd/doctor/git.go）。它可以检测诸如孤立的 beads 问题（存在于 Git 仓库中但未与数据库同步）之类的问题。系统还验证 gitignore 模式，以确保正确跟踪 context/issues.jsonl 并确保辅助文件处于未跟踪状态。有关 Git 集成的更多详细信息，请参阅 Git 集成与冲突解决。
beads 守护进程的状态和配置也会被诊断（cmd/bd/doctor/daemon.go）。这包括检测陈旧的守护进程、CLI 与运行中的守护进程之间的版本不匹配，以及检查自动同步功能（如自动提交和自动推送）。它还确保多仓库设置中指定的所有其他仓库都在运行守护进程。
数据库完整性经过彻底检查，包括数据库版本、架构兼容性（确保关键表和列存在）以及使用 PRAGMA integrity_check（针对 SQLite）或基本查询（针对 Dolt）进行的整体完整性检查（cmd/bd/doctor/database.go）。一个关键方面是数据库与 context/issues.jsonl 文件之间的同步检查，通过比较问题数量和抽样状态来检测差异。对于 Dolt 后端，它进一步验证连接状态、架构存在、问题计数同步，并检查联邦问题（如远程 API 可访问性、对等连接和合并冲突）。
除了结构完整性，bd doctor 还对问题图执行深度验证检查（cmd/bd/doctor/deep.go）。这包括验证父子关系、确保所有依赖项都链接到现有问题、识别已完成但仍处于打开状态的 Epic、验证 AI 代理 bead 的完整性（例如，agent_state、role_type），以及检查 molecules 的结构一致性。
与 AI 环境的兼容性通过针对 Claude 和 Gemini 的特定检查来解决。对于 Claude，诊断包括验证 beads 插件的安装、模型上下文协议 (MCP) 服务器的配置、bd prime 钩子（特别是针对 SessionStart 和 PreCompact 事件）的存在，以及 bd CLI 的可访问性（cmd/bd/doctor/claude.go）。对 Gemini 集成执行类似的检查（cmd/bd/doctor/gemini.go）。
当检测到问题时，bd doctor 提供自动修复功能。这些修复可以修改持久化工作区状态，包括管理守护进程、纠正数据库配置不匹配、恢复损坏的数据库、清理陈旧的锁定文件、强制执行正确的文件权限，以及修复 Git 集成问题（如钩子和合并驱动程序）。例如，如果数据库损坏，可以通过从 context/issues.jsonl 重新导入数据来恢复。Git 钩子可以自动安装或与外部钩子管理器链接。系统还有助于迁移遗留配置，并确保 beads 仓库 ID 一致。自动修复旨在为诊断出的问题提供具体解决方案，旨在将 beads 工作区恢复到健康和可运行的状态。
AI 代理和 IDE 集成 (bd setup)#
bd setup 命令自动化了 beads 问题跟踪系统在各种 AI 代理和集成开发环境 (IDE) 中的配置。此命令简化了启用 beads 与外部工具（如 Aider, Claude Code, Cursor, Factory.ai (Droid), Gemini 和 Junie）之间无缝交互的过程，允许在不同的开发界面中保持一致的 bd 命令使用和工作流强制执行。
设置过程通常涉及生成和管理特定于每个 AI 代理或 IDE 的配置文件和说明性 markdown 文档。例如，在与 Aider 集成时，bd setup aider 创建 .aider.conf.yml 以指示 Aider 加载 BEADS.md，并生成 .aider/BEADS.md，其中包含关于 AI 使用 bd 命令和工作流的详细说明。同样，对于 Cursor IDE，bd setup cursor 在 .cursor/rules/beads.mdc 创建规则文件，提供 bd 说明和推荐的工作流。
对于像 Claude Code 和 Gemini 这样的 AI 平台，bd setup 命令将 “bd prime” 命令作为钩子集成到它们各自的 settings.json 文件中。这些钩子通常配置用于 SessionStart 和 PreCompact（或 Gemini 的 PreCompress）等事件，确保 beads 在 AI 代理工作流的关键点被初始化和同步。此集成支持全局和特定于项目的配置，并通过 --stealth 标志提供特定命令变体。Junie 集成会创建包含 bd 使用说明的 .junie/guidelines.md 文件和用于在 JetBrains AI Agent 中配置 beads 管理控制平面服务器的 mcp.json 文件。
这些集成的底层机制通常依赖于一个用于管理 AGENTS.md 文件的通用框架，该文件作为 AI 代理指令的真理之源。该框架使用特殊标记来划分 markdown 文件中的 beads 特定部分，允许在不破坏其他内容的情况下进行程序化更新和删除。这种方法确保所有 AI 代理都收到关于如何与 beads 交互进行任务管理的一致且最新的指导。
为了确保健壮性，设置功能采用原子文件写入操作，通过写入临时文件然后原子重命名来防止配置更改期间的数据损坏。这种保障措施对于维护配置文件的完整性至关重要，尤其是在自动化或 AI 驱动的环境中。
bd setup 命令本质上充当了一座桥梁，使 beads 成为 AI 代理或 IDE 操作上下文的原生部分，从而促进问题跟踪和项目管理无缝集成的 AI 驱动开发工作流。有关在 AI 驱动的工作流中管理 bd 的详细信息，请参阅 AI 代理集成与工作流。bd CLI 的核心功能在 Beads CLI (bd) 中描述。
AI 代理集成与工作流#
beads 与各种 AI 代理和工具集成，以促进 AI 驱动的工作流，实现持久化、多会话和 Git 支持的问题跟踪。这种集成专注于管理 AI 代理任务、优化上下文窗口的使用以及支持多仓库环境。示例集成演示了如何使用 bd 在人类开发者和 AI 代理之间协调任务，展示了代理集成、工具、实用程序和工作流模式等功能。
模型上下文协议 (MCP) 服务器 beads-mcp 是管理 AI 代理任务的核心。此服务器将 beads 功能作为 AI 代理可以调用的工具公开。例如，服务器提供了用于问题管理的工具（init、create_issue、list_issues、ready_work、show_issue、update_issue、close_issue、reopen_issue）、依赖管理（add_dependency、blocked）和项目统计 (stats)。此服务器的实现可以在 integrations/beads-mcp 中找到。
为了优化 AI 代理的上下文窗口使用，beads-mcp 服务器采用了多种策略。这包括懒加载工具架构、对列表操作使用最小问题模型、超过可配置阈值时压缩结果、过滤不必要的字段以及截断描述。这些方法减少了 AI 代理需要处理的数据量，使交互更高效。有关这些优化的更多细节，请参见 integrations/beads-mcp/CONTEXT_ENGINEERING.md。
beads-mcp 服务器还支持 AI 代理的多仓库环境和工作区管理。它使用 ContextVar 和 with_workspace 装饰器等机制，确保请求被路由到特定 Git 仓库内的正确 beads 数据库。这允许单个 MCP 服务器实例管理多个项目中的问题，且 set_context 工具为 AI 代理提供了对工作区的明确控制。其他信息在 integrations/beads-mcp/SETUP_DAEMON.md 和 integrations/beads-mcp/CONTEXT_MANAGEMENT.md 中提供。
Claude Code 技能集成为 AI 代理提供了持久化、多会话、Git 支持的问题跟踪和工作流指导。该技能确保任务及其状态在 Claude 会话之间保持持久，即使在对话记忆压缩之后也是如此。它支持使用基于图的问题关系进行依赖管理，并使用 bd prime 加载 AI 优化的上下文来指导代理完成工作流。该技能的主要入口点在 claude-plugin/skills/beads/SKILL.md。
自主任务代理工作流专为 Claude Code 内的 beads 框架设计。该代理遵循六步流程：发现就绪工作、认领任务、执行任务、跟踪发现（通过创建和链接新问题）、完成任务以及继续重新检查就绪工作。此工作流依赖于 beads MCP 工具，如 ready、show、update、create、dep 和 close。有关此工作流的更多信息，请见 claude-plugin/agents/task-agent.md。
Claude Code 中的 /plan-to-beads 斜杠命令自动将 Claude Code 计划转换为 beads 史诗 (Epics) 和任务。该命令创建史诗和任务，在它们之间建立顺序依赖关系，将任务链接到其父级史诗，并使用代理委派来简化项目启动。此自动化在 integrations/claude-code/README.md 中有详细说明。
JetBrains AI Agent (Junie) 与 beads 的集成由 bd setup junie 命令促成。该命令配置用于工作流说明的 guidelines.md 和 mcp.json 以向 Junie 公开 beads MCP 工具。这使 Junie 能够执行各种问题管理操作，例如查找就绪工作、列出问题、显示详细信息、创建、更新和关闭问题，以及管理依赖关系。更多详细信息可以在 integrations/junie/README.md 中找到。
examples 目录包含各种示例，演示了 bd 与 AI 代理和不同工作流的集成。这些示例包括模拟任务发现、认领、执行和完成的 Python 代理 (examples/python-agent) 和 Bash 代理 (examples/bash-agent)。其他示例展示了诸如 beads 守护进程的基于 Web 的监控器 (examples/monitor-webui) 以及将 Markdown 或 GitHub 问题转换为 beads JSONL 格式的实用程序 (examples/markdown-to-jsonl, examples/github-import)。工作流模式展示了 beads 在贡献者工作流 (examples/contributor-workflow)、团队协作 (examples/team-workflow) 和受保护分支管理 (examples/protected-branch) 等场景中的应用。
有关 bd 命令行界面 (CLI) 的更一般了解，请参阅 Beads CLI (bd)。
用于 AI 代理任务管理的模型上下文协议 (MCP) 服务器#
模型上下文协议 (MCP) 服务器，具体为 beads-mcp，充当 beads 问题跟踪系统和 AI 代理之间的桥梁。其主要功能是将 beads 功能作为可调用工具公开，允许 AI 代理通过编程方式管理问题、依赖关系和工作流。此服务器在直接命令行界面 (CLI) 访问不可行的环境（如某些桌面 AI 应用程序）中特别有价值。
beads-mcp 服务器主要在 integrations/beads-mcp 目录中实现，为 AI 代理提供了一套全面的工具。这些工具涵盖了完整的问题生命周期，包括 init、create_issue、list_issues、ready_work、show_issue、update_issue、close_issue、reopen_issue、add_dependency、blocked 和 stats。这允许代理执行诸如创建新任务、列出可用工作项、查看详细问题信息、修改问题状态和管理问题间依赖关系等操作。此外，诸如 validate、repair、schema、debug、migration 和 pollution 等管理工具可用于维护 beads 数据库的完整性和健康状况。
beads-mcp 的一个关键架构方面是其跨多个仓库高效运行的能力。它利用类似 LSP（语言服务器协议）的模型，其中单个 MCP 服务器实例可以将请求路由到隔离的、按项目的本地 beads 守护进程。这确保了操作在正确的数据库上执行，并防止不同项目之间的数据污染。服务器使用与每个工具调用一起传递的 workspace_root 参数来确定目标仓库。在未明确提供 workspace_root 的情况下，它可以从当前工作目录推断上下文。set_context 工具也可用于显式设置操作工作区。有关多仓库设置中上下文管理的更多详细信息，请参阅 MCP 的多仓库和工作区管理。
MCP 服务器与底层 beads 系统之间的通信由专门的 bd 客户端实现处理。BdCliClient (integrations/beads-mcp/src/beads_mcp/bd_client.py) 将 beads CLI 命令作为子进程执行，并解析其 JSON 输出。或者，BdDaemonClient (integrations/beads-mcp/src/beads_mcp/bd_daemon_client.py) 促进通过 Unix 套接字与运行中的 beads 守护进程进行异步 RPC 通信，通过避免重复的进程生成来提高性能。这种基于守护进程的方法在 integrations/beads-mcp/SETUP_DAEMON.md 中有进一步详细说明。服务器根据配置选择适当的客户端，通常倾向于使用守护进程客户端以提高效率。
为了优化与 AI 代理的交互，beads-mcp 结合了几种上下文工程策略。这些优化旨在最大程度地减少消耗的令牌数量，这对于上下文窗口有限的 AI 模型至关重要。技术包括懒加载工具架构、对列表操作使用最小问题模型以及针对大型查询结果的结果压缩。这些策略确保默认情况下仅向 AI 代理提供基本信息，并提供按需检索完整详细信息的选项。有关这些优化的更多信息，请参见 AI 代理的上下文工程与优化。
AI 代理的上下文工程与优化#
beads-mcp 服务器实施了几种策略来优化 AI 代理上下文窗口的使用，旨在减少令牌消耗，同时保持完整的功能。这种优化对于在有限上下文窗口下运行的 AI 代理至关重要，允许进行更广泛的代码分析、对话和任务规划。
核心策略包括 懒工具架构加载。beads-mcp 服务器不是预先加载所有工具架构（这可能会消耗很大一部分上下文窗口），而是提供了一种轻量级机制来发现可用工具，并仅在代理明确请求时检索详细架构。这在概念上是通过 integrations/beads-mcp/src/beads_mcp/server.py 中的 discover_tools 和 get_tool_info 等函数实现的。
另一个关键优化是在列表操作中使用 最小问题模型。当 AI 代理请求问题列表（例如“就绪工作”或一般问题列表）时，服务器返回每个问题的简化表示（例如 integrations/beads-mcp/src/beads_mcp/models.py 中定义的 IssueMinimal 或 BriefIssue）。这些最小模型仅包括 ID、标题、状态和优先级等基本字段，与完整的问题对象相比，显著减少了每个问题的数据大小。例如，一个 IssueMinimal 模型约为 80 字节，大大少于约 400 字节的完整 Issue 模型。这种“默认最小”的方法确保 AI 代理只接收用于概览的最关键信息，并可以选择使用专用的 show 功能请求特定问题的完整详细信息。
对于涉及大型查询结果的场景，采用了 结果压缩。如果列表操作返回的问题数超过预定义的阈值，服务器会将响应压缩为 CompactedResult（在 integrations/beads-mcp/src/beads_mcp/models.py 中定义）。此压缩结果提供元数据，例如项目总数、前几个最小问题的小预览，以及指示代理使用 show 工具获取完整详细信息或优化其查询的提示。这种机制防止大型数据集淹没 AI 的上下文窗口。此压缩行为可以通过 BEADS_MCP_COMPACTION_THRESHOLD 和 BEADS_MCP_PREVIEW_COUNT 等环境变量进行调整，详见 integrations/beads-mcp/CONTEXT_ENGINEERING.md。
进一步的优化包括 字段过滤 和 描述截断。这些功能允许对发送给 AI 代理的信息量进行细粒度控制。字段过滤允许代理仅指定它们需要的问题字段，而描述截断限制了问题描述的长度，防止冗长的文本消耗过多的令牌。这些功能由 integrations/beads-mcp/src/beads_mcp/server.py 中的 _filter_fields 和 _truncate_description 等函数管理。
整体设计理念通常被称为“先列出再显示 (list then show)”，优先提供用于聚合视图的最小数据，并要求对详细信息进行显式请求。这种方法对于高效的 AI 代理交互至关重要，特别是在多仓库和动态开发环境中。有关这些优化的更多信息，可以在 beads-mcp 变更日志（特别是 integrations/beads-mcp/CHANGELOG.md 中的版本 [0.24.0]）以及 integrations/beads-mcp/CONTEXT_ENGINEERING.md 中的详细上下文工程文档中找到。
MCP 的多仓库和工作区管理#
beads-mcp 服务器促进了在单个实例中管理多个 beads 仓库，这是 AI 代理跨多个项目工作的关键特性。这种多仓库能力是通过类似 LSP 的模型实现的，该模型根据当前工作目录或显式设置的工作区，将请求动态路由到正确的 beads 数据库。该设计确保每个项目都维护其自己的隔离守护进程和 SQLite 数据库，防止跨项目数据污染。
启用此功能的核心组件是 Python 的 ContextVar 机制，具体而言是 current_workspace（在 integrations/beads-mcp/src/beads_mcp/server.py 中使用），它确保并发请求的隔离。对于每个传入请求，with_workspace 装饰器（定义在 integrations/beads-mcp/src/beads_mcp/server.py 中）建立适当的操作上下文。此上下文解析涉及辅助函数，如 _find_beads_db（在 integrations/beads-mcp/src/beads_mcp/server.py 中）用于在文件系统中定位 beads 数据库，以及 _resolve_workspace_root（在 integrations/beads-mcp/src/beads_mcp/server.py 中）用于确定 Git 仓库根目录。路径规范化（包括符号链接解析和 Git toplevel 检测）的结果被缓存以提高性能。
为了进一步支持对工作区的显式控制，提供了 set_context 工具（如 integrations/beads-mcp/CONTEXT_MANAGEMENT.md 中所述）。该工具允许 AI 代理为所有 bd 操作明确定义工作区根目录，解决在 AI 客户端可能无法始终提供正确工作目录的环境中的潜在数据库路由问题。写入操作受 @require_context 装饰器保护，确保仅在建立了明确的操作上下文时才执行它们，从而防止对错误数据库的意外修改，特别是在设置了 BEADS_REQUIRE_CONTEXT=1 环境变量时。
beads-mcp 服务器维护一个连接池，以规范化的工作区路径为键，每个工作区都有自己的守护进程套接字连接。此架构（在 integrations/beads-mcp/README.md 中描述）允许单个 MCP 服务器实例高效地并发管理多个 beads 项目，同时保持严格的隔离。虽然 ContextVar 确保了并发请求的隔离，但开发人员必须小心，不要在工具实现中使用 asyncio.create_task() 生成后台任务，因为 ContextVar 不会传播到这些任务，可能导致跨项目数据泄漏。工具逻辑应保持同步或使用顺序 await 调用以防止此类问题。
Claude Code 技能集成：持久化问题跟踪#
Claude Code 技能集成为 AI 代理提供了一个强大的框架，用于持久化、多会话、Git 支持的问题跟踪、依赖管理和结构化工作流指导。这主要是通过将 bd CLI 工具集成为 Claude Code 技能来实现的，使 AI 代理能够与版本控制的问题数据库进行交互。
此集成的核心位于 claude-plugin 目录中，其中包含自主代理和 bd CLI 集成的组件。系统确保任务及其状态在 Claude 会话之间持久存在，允许进行复杂的多会话工作，这些工作能够在对话记忆压缩后存活。这种持久性对于维持长期项目背景和进度至关重要。
AI 代理利用 bd CLI 进行全面的问题管理，包括创建、更新、关闭和跟踪依赖关系。例如，自主代理的工作流包括：使用 ready 工具查找未阻塞的任务，使用 update 工具将其状态更新为 in_progress 来认领任务，执行任务，通过使用 create 创建新问题并使用 dep 和 discovered-from 链接它们来跟踪发现，最后使用 close 关闭已完成的任务。这种结构化方法在 claude-plugin/agents/task-agent.md 中有记录。
AI 代理的工作流指导由 bd prime 促进，它加载 AI 优化的工作流上下文，包括基本的 beads 工作流规则和命令参考。此机制在 claude-plugin/commands/prime.md 中描述，指导代理使用 bd 命令进行问题跟踪，而不是使用非结构化方法，尤其是在上下文压缩之后。claude-plugin/skills/beads/SKILL.md 中的 SKILL.md 文件作为 Claude 的主要入口点，概述了 beads 技能并将其持久化、复杂的任务管理与更临时的工具区分开来。此文件还列出了 AI 代理可以利用的重要 bd CLI 命令。
beads 技能支持复杂的依赖管理，允许 AI 代理理解和管理任务之间的关系。这对于编排复杂项目至关重要，其中问题可能会阻塞其他问题或是更大史诗的一部分。集成还扩展到使用 integrations/claude-code/README.md 中的 /plan-to-beads 斜杠命令将 Claude Code 计划转换为 beads 史诗和任务。该命令自动从计划的标题和摘要创建 beads 史诗，为每个阶段生成单独的 beads 任务，并自动建立顺序和父子依赖关系。这种自动化简化了项目启动，并确保在 beads 中立即可用结构化的、版本控制的任务分解。
Claude 内的自主任务代理工作流#
专为 Claude Code 内的 beads 框架设计的自主任务代理，通过结构化的六步流程管理从发现到完成的任务生命周期。此工作流确保 AI 代理可以高效地识别、认领和执行工作，同时保持强大的问题跟踪和依赖管理。
该过程始于代理使用 ready 工具识别可用任务，并按紧急程度对其进行优先排序。一旦选择了任务，代理使用 show 工具检索详细信息，然后使用 update 工具将任务标记为 in_progress，表明它已认领该工作。
任务执行涉及执行描述的工作，代理根据需要利用各种工具。在此阶段，如果发现了新问题、错误或进一步的任务，代理使用 create 工具提交它们，并使用 dep 工具通过 discovered-from 依赖关系将它们链接到当前任务。这确保了所有相关工作都得到正确跟踪和关联。
完成工作后，代理验证其成果并利用 close 工具将任务标记为完成，提供完成消息。最后一步涉及代理使用 ready 工具重新检查新的未阻塞工作，使其能够自主地继续处理项目的任务列表。
在整个工作流中，代理旨在维护一致的问题管理实践，包括在适当阶段更新任务状态（开始时为 in_progress，如果出现阻碍则为 blocked，完成时为 close）以及显式管理依赖关系以维护准确和透明的项目状态。这种结构化方法（在 claude-plugin/agents/task-agent.md 中概述）促进了 AI 驱动开发中的持续进展和问责制。有关模型上下文协议 (MCP) 服务器如何向 AI 代理公开这些 beads 功能的更多详细信息，请参阅 用于 AI 代理任务管理的模型上下文协议 (MCP) 服务器。
Claude Code Plan-to-Beads 自动化#
Claude Code 中的 /plan-to-beads 斜杠命令自动将 Claude Code 计划转换为 beads 史诗和任务，提供了一种结构化的项目启动方法。该命令解析 Claude Code 计划文件，提取关键信息，如计划的标题、摘要和各个阶段。每个计划标题和摘要被转换为一个 beads 史诗，而计划中的每个阶段则变成一个独特的 beads 任务。系统自动建立这些任务之间的顺序依赖关系，反映原始计划中阶段的顺序，并将每个任务链接到其父级史诗。这种自动化有助于保持一致的工作流并促进工作进度的跨会话跟踪。
转换过程利用代理委派，特别是指示 Task tool 使用 general-purpose 子代理。这种方法确保转换期间的高效上下文管理。对于任务描述，系统提取阶段内容的第一段以保持可扫描性。完成后，该命令提供已创建的史诗和任务的摘要，包括其 ID 和就绪状态，有助于立即了解项目概况。
与 Claude Code 的集成需要使用 bd setup claude 进行初始设置，以配置在每个会话开始时注入工作流上下文的钩子。该命令本身默认处理最近的计划，如果提供了路径，则可以处理特定的计划文件。此机制支持持久化、多会话、Git 支持的问题跟踪和工作流指导。有关 Claude Code 如何与 Beads 集成的更多上下文，请参见 Claude Code 技能集成：持久化问题跟踪。
核心数据管理与内部机制#
Beads 采用一套强大的内部机制来管理问题数据、与 Git 集成并启用 AI 驱动的工作流。在其核心，Beads 维护一个仅追加的审计日志，记录系统交互（如 LLM 调用和工具执行），确保数据的不可变性和可检索性。此日志由 internal/audit 目录管理。
问题数据主要存储在 JSONL (JSON Lines) 文件中，这允许基于 Git 的版本控制和分支。系统自动同步 JSONL 文件与底层存储后端之间的问题数据。当有新数据可用或检测到更改时，由 internal/importer 和 internal/autoimport 目录管理的复杂导入程序处理该过程。这包括通过内容哈希或修改时间检测更改、管理合并冲突以及执行事务性更新插入。这种同步的一个关键组件是位于 internal/merge 的三路合并算法，它协调 JSONL 问题数据的基础、本地和远程版本，包括对已删除问题的墓碑处理。
系统与 Git 的交互是基础性的。Beads 维护一个 minimal API 供其扩展访问 Git 上下文和发现数据库。internal/beads 目录提供实用程序来定位 context/ 项目目录、解析数据库路径并管理仓库上下文，包括处理 Git 工作树和安全执行 Git 命令。这为问题跟踪提供了一致且受版本控制的环境。例如，internal/git 中的 WorktreeManager 编排专用于 “beads” 分支的 Git 工作树的创建、移除和健康检查，以及主仓库与这些工作树之间 JSONL 文件的同步。
应用程序配置由 internal/config 和 internal/configfile 目录动态处理。这些组件管理从配置文件和环境变量等各种来源加载、保存和验证设置。该系统支持多仓库设置、外部项目解析和代理身份管理，确保 Beads 能够适应不同的项目结构和用户需求。配置还规定了同步和冲突解决策略。
Beads 还将基于 AI 的功能集成到其核心数据管理中。internal/compact 目录编排 AI 驱动的问题压缩。此服务使用 AI 摘要器来压缩问题内容，存储结果并通过并发控制管理批处理。这减少了认知负荷并简化了用户和 AI 代理的信息检索。
工作流管理由“公式 (formulas)”促进，这是一种用于定义复杂工作序列的声明式模板。internal/formula 目录提供了用于解析、验证和转换这些公式的结构和逻辑。这包括继承机制、变量替换以及高级步骤转换，如 advice 应用、expansion 和控制流。这些公式编译成 “proto beads”，代表结构化的工作图，实现任务的自动化和一致执行。
最后，守护进程由 internal/daemon 目录管理。这包括发现正在运行的守护进程、检索其状态以及优雅地停止或强制终止它们。持久化注册表有助于跟踪守护进程信息，确保 Beads 环境的可靠后台操作和实时监控。此外，位于 internal/export 的策略驱动数据导出功能管理导出配置、应用错误处理并确保导出清单的完整性。这一套全面的内部机制使 Beads 能够提供一个有弹性、AI 原生且 Git 集成的问题跟踪系统。
守护进程管理与生命周期#
beads 系统包含守护进程来处理后台操作，提供持久化问题跟踪和自动化工作流的能力。这些守护进程的管理（包括其发现、生命周期控制和状态的健壮处理）是系统架构的核心组件。这是通过一组旨在定位运行中的守护进程、检索其状态并在必要时确保其优雅或强制终止的机制来实现的。
守护进程管理的一个中心方面是在各种工作区中发现活动守护进程的能力。系统使用基于注册表的方法，如果该方法不可用或提供了 searchRoots，则可以回退到文件系统扫描以定位指示运行中守护进程的 context/bd.sock 文件。当发现潜在的守护进程套接字时，系统尝试连接并检索其状态，从而识别活动的守护进程。特定的实用程序 checkDaemonErrorFile 为守护进程启动失败提供上下文信息，有助于诊断。系统还支持识别与特定工作区关联的守护进程，包括对 Git 工作树的考虑。有关守护进程如何集成到整个系统中的更多详细信息，请参见 核心架构设计。
bd 守护进程的生命周期受到仔细管理，包括启动、关闭和清理。当不再需要守护进程或其变得无响应时，系统可以通过 RPC 调用启动优雅关闭。如果无法进行优雅关闭，它可以求助于向守护进程的进程 ID 发送终止信号。CleanupStaleSockets 函数识别并移除不再运行的守护进程留下的套接字文件，防止资源混乱。StopDaemon 函数实现了分阶段关闭，首先尝试优雅的 RPC 关闭，然后升级到发送 SIGTERM，最后在必要时发送 SIGKILL 以确保终止。
为了确保一致性并允许跨进程协调，beads 维护一个守护进程的持久化全局注册表。此注册表存储元数据，如守护进程的工作区路径、套接字路径、进程 ID (PID) 和版本。注册表文件本身受排他文件锁保护，以确保多进程之间的数据完整性。这种原子性是通过写入临时文件然后重命名来维护的，防止写入操作期间的数据损坏。注册表的 List 函数通过检查注册的 PID 是否对应于活动进程来自动清理陈旧条目，移除未运行守护进程的条目。
系统包含特定于平台的进程管理实现。对于类 Unix 系统，进程控制依赖于 syscall.Kill 发送信号以终止 (SIGTERM, SIGKILL) 和检查进程存活（信号 0）。在 Windows 上，进程终止利用 os.Process.Kill，其内部执行强制性的 TerminateProcess API 调用。由于平台差异，在 Windows 上确定进程是否存活需要更稳健的方法，这是通过执行 tasklist 命令行实用程序实现的。对于 WebAssembly (WASM) 环境，所有守护进程管理功能都是空操作并显式返回错误，因为此类环境不支持传统的进程管理。
beads 中的 lockfile 包通过处理守护进程锁文件在守护进程管理中发挥关键作用。这些文件用于确定守护进程是否已在运行并存储相关元数据。系统支持现代基于 JSON 的锁文件格式，其中包括详细的 LockInfo（PID、父 PID、数据库、版本、启动时间），以及用于向后兼容的传统纯整数 PID 文件格式。TryDaemonLock 函数尝试获取并立即释放守护进程锁，以快速检查是否有其他守护进程持有它。此机制采用特定于平台的文件锁定，在 Unix 上使用 flock 系统调用，在 Windows 上使用 LockFileEx，由于单进程性质，在 WASM 环境中为空操作实现。
Git 上下文与工作树管理#
Beads 管理 Git 仓库路径解析和工作树感知，提供对 Git 相关目录的缓存访问。它集成了 Jujutsu 仓库，并编排针对 “beads” 分支的 Git 工作树操作，包括创建、移除、健康检查、稀疏检出配置以及 JSONL 文件的同步。
系统确定并缓存 Git 仓库属性，如 Git 目录、通用 Git 目录和仓库根目录。此过程通过从单个 git rev-parse 命令收集所有必要信息，最大程度地减少外部进程调用。路径被规范化以处理特定于平台的格式，并管理大小写敏感性以确保跨操作系统的路径比较准确。系统还检测并定位 Jujutsu 仓库（包括与 Git 共存的仓库）以确保兼容性。此功能主要由 internal/git/gitdir.go 处理。
为了隔离开发环境，Beads 利用 Git 工作树，即链接到同一仓库的独立工作目录。WorktreeManager 编排这些操作，为特定分支创建工作树。这些工作树配置了稀疏检出，意味着它们只包含 context/ 目录，最大限度地减少占用空间并专注于问题相关文件。管理器还处理工作树的移除并执行健康检查以确保其完整性和正确的稀疏检出配置。如果发现工作树不健康或配置错误，系统会尝试修复它，例如通过重新配置稀疏检出。此工作树管理在 internal/git/worktree.go 中实现。
工作树管理的一个关键方面是主仓库与工作树之间存储在 JSONL 文件中的问题数据的同步。这种同步包括覆盖和执行 JSONL 文件三路合并的机制，以防止数据丢失。系统统计每个 JSONL 文件中的问题数量以决定是覆盖还是合并，确保更改正确传播同时保留数据完整性。此同步逻辑也是 internal/git/worktree.go 的一部分。
工作流公式处理与转换#
Beads 中的工作流 “Formulas (公式)” 提供了一种声明式的方式来定义和管理复杂的高级工作流，这些工作流最终编译成 “proto beads” 以供执行。这些公式支持结构化工作图的模板化，允许继承、变量替换和步骤的动态转换。
位于 internal/formula/parser.go 中的 Parser 组件是此过程的核心。它处理从文件加载公式定义、解析它们（支持 TOML 和 JSON 格式），以及解析其中一个公式可以扩展另一个公式的继承层次结构。这允许模块化和重用，因为可以定义通用的工作流模式并在特定上下文中扩展。公式中的变量定义可以被提取，使用 {{variable}} 占位符等机制进行替换，根据预定义的约束（如必填字段或枚举）进行验证，并分配默认值。公式中的每一步也都注释了来源信息，有助于调试和可追溯性。
除了基本解析外，Beads 公式还支持显著的转换能力。由 internal/formula/controlflow.go 管理的控制流逻辑允许展开循环（固定计数、条件或基于范围）、连接并行分支以及应用门控以进行条件步骤执行。例如，可以在执行工作流之前将单个循环定义展开为多个具体步骤，每个步骤具有唯一的 ID 和依赖关系。门控和循环的条件逻辑在定义时不会完全解析；相反，它作为元数据（例如 loop:until, gate:condition）嵌入在步骤标签中，以便在运行时解释。
宏风格的步骤转换通过 internal/formula/expand.go 中定义的扩展操作符处理。这允许用更详细的模板替换目标步骤，支持单步扩展和基于模式的映射。这些模板中的占位符（例如 {target.id}, {varname}）会被替换为上下文信息，并且步骤依赖关系会自动更新以在扩展后保持工作流完整性。强制执行深度限制以防止意外的无限扩展。
此外，Beads 支持应用 Lisp 风格的 advice 操作符，由 internal/formula/advice.go 管理。此机制允许在匹配特定模式的现有步骤“之前”、“之后”或“周围”注入新步骤，从而能够实现横切关注点（如日志记录或安全性），而无需修改核心工作流逻辑。
最后，可以评估条件来控制工作流执行。internal/formula/stepcondition.go 中的 EvaluateStepCondition 函数针对公式变量处理简单的基于字符串的条件（例如 {{var}} == value），允许在工作流编译阶段有条件地包含或排除步骤。internal/formula/condition.go 中更高级的条件评估系统支持字段比较、步骤集合的聚合检查以及外部检查（如文件存在性或环境变量），以实现动态控制。这种结构化的条件方法增强了工作流的适应性。有关如何将这些工作流与 AI 代理集成的详细信息，请参阅 AI 代理集成与工作流。
策略驱动的数据导出#
Beads 通过定义配置、应用错误处理策略并在数据获取操作期间结合重试机制来管理数据导出过程。它还通过原子写入导出清单来确保数据完整性。
该系统使用 ErrorPolicy 来指示如何管理导出操作期间的错误，范围从 PolicyStrict（快速失败）到 PolicyBestEffort（跳过失败并发出警告）或 PolicyPartial（重试暂时性问题）。PolicyRequiredCore 专门管理核心数据问题的故障，同时允许跳过遇到错误的丰富信息。这些策略在 internal/export/policy.go 中定义。
配置设置，如 ConfigKeyErrorPolicy、ConfigKeyRetryAttempts 和 ConfigKeyRetryBackoffMS，通过字符串常量进行管理。Config 结构体整合了这些设置，包括用于自动导出的 IsAutoExport 标志。此配置由 internal/export 目录中的 config.go 文件处理。internal/export/config.go 中的 LoadConfig 函数检索导出设置，应用默认值并从提供的 ConfigStore 覆盖它们。
位于 internal/export/executor.go 中的 FetchWithPolicy 函数充当数据检索任务的灵活执行器。它应用配置的错误处理策略并抽象出重试逻辑和错误管理。此函数使用 RetryWithBackoff（在 internal/export/policy.go 中定义），允许可配置的重试次数和指数退避，同时遵守上下文取消。
为了跟踪导出的结果，Manifest 结构体记录了 ExportedCount、FailedIssues、PartialData、Warnings、Complete 状态、ExportedAt 时间戳以及使用的 ErrorPolicy。internal/export/manifest.go 中的 WriteManifest 函数处理将此清单作为 JSON 文件的原子写入，通过使用临时文件然后重命名来确保数据完整性。
外部问题跟踪器集成#
Beads 与外部问题跟踪系统（具体是 GitLab 和 Linear）集成，以实现问题数据的无缝、双向同步。这种集成允许 Beads 在这些外部系统中获取、创建、更新和链接问题，将其原生数据格式转换为通用的 Beads 问题结构，反之亦然。
对于 GitLab，集成由 internal/gitlab/client.go 中定义的客户端处理。该客户端管理 API 请求、身份验证、针对速率限制的指数退避重试以及分页。它提供获取、创建、更新和链接 GitLab 问题以及列出项目的功能。在 GitLab 的特定数据模型（例如用于优先级或状态的标签、问题链接）与通用 Beads 格式之间转换的复杂任务由 MappingConfig 结构体和 internal/gitlab/mapping.go 中的相关函数管理。这包括从 GitLab 标签和状态推断 Beads 优先级、状态和类型，并将 Beads 问题转换回适合 GitLab API 更新的格式。例如，GitLab 的 Weight 字段映射到 Beads EstimatedMinutes，问题链接转换为 Beads 依赖关系。
同样，与 Linear 的集成使用 internal/linear/client.go 中的专用客户端。该客户端与 Linear GraphQL API 交互以管理问题并检索团队信息。它支持获取问题（包括增量同步）、创建新问题和更新现有问题。与 GitLab 一样，internal/linear/mapping.go 中的 MappingConfig 对于将 Linear 特定的属性（如优先级、工作流状态和标签）转换为 Beads 问题类型和状态至关重要。这包括处理为新导入的 Linear 问题生成唯一的、基于哈希的 Beads ID，以及规范化问题描述以实现一致的数据表示。MappingConfig 可以自定义以覆盖默认转换规则，提供在 Beads 中解释外部问题数据的灵活性。
这两种集成都利用了 internal/gitlab/types.go 和 internal/linear/types.go 中定义的健壮数据结构，这些结构分别镜像了外部 API 的响应和内部 Beads 表示。这些类型还包括跟踪同步统计信息和处理当问题在 Beads 和外部系统中都被修改时的冲突的机制。这种复杂的双向映射确保了问题数据在所有集成平台中保持一致和可操作。
问题数据导入程序与合并逻辑#
Beads 采用复杂的机制来管理问题数据，特别是关于从 JSONL (JSON Line) 文件导入及其在不同版本之间的协调。该系统确保数据一致性和完整性，尤其是在 Git 集成环境中。
此过程的核心涉及将问题从 JSONL 文件自动导入到持久化存储后端，默认为 SQLite（参见 存储后端选项）。此自动导入系统 (internal/autoimport) 智能地检测 JSONL 文件中的更改，使用内容哈希 (SHA256) 进行稳健的更改检测，如果哈希不可用，则回退到文件修改时间。在任何导入之前，它会检查 JSONL 文件中的 Git 合并冲突标记，以防止导入损坏的数据。
系统解析 JSONL 格式的问题，根据需要执行模式迁移和更正。例如，它自动处理旧的“deleted”状态，将其转换为当前的 StatusTombstone，并确保 ClosedAt 和 DeletedAt 等时间戳得到正确应用。当导入问题时，系统可以在发生冲突时重映射 ID，并提供有关这些更改的通知。
数据管理的一个关键组件是 3 路合并算法 (internal/merge)。该算法协调问题数据的基础版本、本地版本和远程版本（通常在 JSONL 文件中找到）之间的差异。它识别添加、修改和删除，并应用预定义规则来解决冲突。例如，在标题或描述以冲突方式更改的情况下，合并优先考虑具有最新 UpdatedAt 时间戳的版本。对于问题优先级，数值较低的值（表示较高优先级）获胜。系统还智能地处理“墓碑 (tombstones)”，它们代表软删除的问题，遵守可配置的生存时间 (TTL)。过期的墓碑如果问题的实时版本存在于另一个分支中，则可能“复活”，而未过期的墓碑通常会覆盖实时问题，确保删除有效传播。合并过程旨在产生确定性输出，确保与 Git 等版本控制系统的一致性和兼容性。
在导入到存储后端 (internal/importer) 期间，系统处理问题的创建、更新和删除。它管理冲突，验证问题前缀，并通过按深度排序问题来保留层次依赖关系，确保在处理子问题之前处理父问题。一种关键的保护机制可防止较旧的传入数据覆盖较新的本地数据，特别是当本地快照具有最近的时间戳时。对于原子操作，系统将相关数据库操作分组到事务中，确保数据完整性。这种强大的导入和合并逻辑是 Beads 能够在 Git 仓库中维护一致且可审计的问题历史记录的基础。
开发环境设置#
Beads 项目提供了一个预配置的开发环境，旨在实现一致性和易于设置，利用 开发容器 (devcontainers) 自动化基本工具和依赖项的安装。这种方法确保开发人员可以快速建立功能环境，而无需进行大量手动配置。
此设置的核心定义在 .devcontainer 目录中，支持 GitHub Codespaces 和 VS Code Remote Containers 等平台。此容器化环境自动安装 Go 工具链，构建并安装 bd 命令行界面 (CLI)，配置 Git 钩子，并管理 Go 模块依赖项。
此自动化设置的一个关键组件是 setup.sh 脚本，位于 .devcontainer/setup.sh。此脚本处理几个关键步骤：它从源代码编译 bd 可执行文件，将其安装到全局可访问路径，并以静默模式初始化 bd 以准备问题跟踪系统。它还检查并安装 Git 钩子，这对于与项目的版本控制工作流集成至关重要。最后，脚本确保下载所有必要的 Go 模块依赖项，完成开发环境的设置。这个简化的流程旨在最大限度地减少新贡献者的摩擦，并保持整个团队的开发体验统一。
使用 Devcontainers 获得一致环境#
beads 项目使用开发容器提供一致且预配置的环境，简化了开发人员的入职流程，并确保不同机器之间的环境一致性。这种方法通过 GitHub Codespaces 或 VS Code Remote Containers 等平台实现，自动化了贡献者的设置过程。
此自动化设置的核心是 setup.sh 脚本，位于 .devcontainer/setup.sh。此脚本处理基本任务，例如构建和安装 bd 命令行界面，以静默模式初始化 bd 以防止重新初始化现有数据库，安装 Git 钩子，以及管理 Go 模块依赖项。通过自动执行这些步骤，开发容器确保新开发人员拥有功能齐全的 beads 开发环境，无需手动配置。
该设计还考虑了通过挂载本地 .gitconfig 文件来维护开发人员现有的 Git 身份。这种集成有助于在一致的环境中保留用户特定的 Git 设置。有关验证设置和解决常见问题的更多详细信息，请参阅 .devcontainer/README.md。总体而言，开发容器提供了封闭的开发设置，促进了可重复性，并减少了配置开发工作站所涉及的工作量。
自动化设置脚本 (setup.sh)#
setup.sh 脚本位于 .devcontainer/setup.sh，自动化了开发环境的配置。其主要功能是通过构建和安装 bd 命令行界面、管理 Go 模块依赖项和集成 Git 钩子来准备 beads 开发工作区。
具体而言，该脚本从 cmd/bd 中的源代码构建 bd 可执行文件，并将其安装到全局可访问路径。然后，它执行 bd 的静默初始化，以在不需要用户交互的情况下设置其基本组件，前提是 beads.db 文件尚不存在，从而防止重新初始化。该脚本还通过执行 examples/git-hooks 目录中的 install.sh 脚本来安装 Git 钩子，这将 beads 的版本控制功能直接集成到 Git 工作流中。最后，它确保下载所有必要的 Go 模块依赖项，完成环境设置。有关整体开发环境的更多背景信息，请参阅 使用 Devcontainers 获得一致环境。
NPM 包与安装#
@beads/bd npm 包提供了 bd (Beads) 命令行界面，这是一个 AI 原生 (AI-Native)、Git 集成 (Git-Integrated) 的问题跟踪系统。它使开发人员和 AI 代理能够管理完整的问题生命周期，包括依赖项跟踪、代理状态跟踪和审计日志记录。此包是用户安装和开始使用 Beads 的主要方法，尤其是在诸如 Claude Code for Web 等 临时开发环境 (Ephemeral Development Environments) 中。
该包促进了原生 bd 二进制文件的 零配置 (Zero-Configuration) 安装。它处理平台检测并从 GitHub Releases 下载适当的可执行文件，确保 bd 在 macOS、Linux 和 Windows 系统上随时可用。这种方法允许完整的 SQLite 支持、与原生工具的完全功能对等以及增强的性能，规避了 WebAssembly (WASM) 实现的局限性。
bd 问题作为 JSONL 记录存储在 Git 仓库中，允许对问题数据进行版本控制、分支和合并。这种基于 Git 的存储支持一个共享的、去中心化的、持久的问题跟踪系统，该系统在不同的开发人员环境和 AI 代理会话之间进行同步。特别是 AI 代理，利用 bd 进行结构化工作，识别没有开放阻碍的任务 (bd ready)、创建新问题 (bd create)、更新问题状态 (bd update) 以及管理依赖关系 (bd dep add)。CLI 的 --json 标志提供机器可读的输出，这对于与 AI 驱动的工作流无缝集成至关重要。
对于像 Claude Code for Web 这样的临时环境，npm 包通过 SessionStart 钩子平滑集成。这些钩子自动化了 bd 的安装和初始化，确保工具在每个会话开始时都可用并配置完毕。这种设置允许 AI 代理立即利用 bd 进行持久化、多会话的问题跟踪和工作流指导。关于 AI 代理如何使用 bd 命令进行任务管理的说明通常通过 AGENTS.md 等文档提供，其中指定了用于查找、创建和更新问题以及管理依赖关系的命令。
原生二进制包装器与执行#
@beads/bd npm 包提供了一个关键的抽象层，使 Node.js 环境（特别是像 Claude Code for Web 这样具有临时特性的环境）能够与原生 bd 命令行界面无缝交互。该包并非尝试进行 WebAssembly (WASM) 编译，而是充当编译后的 Go 二进制文件的透明包装器。这种设计选择确保了与原生工具的完全功能对等，包括全面的 SQLite 支持，同时保持最佳性能。
此包装器功能的核心位于 npm-package/bin/bd.js 中的 bd.js CLI 脚本中。该脚本的主要作用是充当中介，动态识别主机操作系统和架构，以在安装的包中定位正确的原生 bd 可执行文件。定位后，bd.js 执行此原生二进制文件，一丝不苟地转发所有命令行参数，并确保继承标准输入、输出和错误流。这种继承使得原生 bd 二进制文件的行为就像被直接调用一样，保留了用户的交互体验并实现了 AI 代理的程序化集成。包装器还处理错误情况（如缺少原生二进制文件），并传播被执行二进制文件的退出代码，确保调用进程可以准确确定 bd 操作的结果。这种透明的执行模型是 beads 与各种开发工作流和 AI 代理集成的基础，详见 临时环境中的 AI 代理集成。
自动化安装与特定平台二进制管理#
@beads/bd npm 包自动安装原生 bd 二进制文件，确保开发者和 AI 代理可以将 Beads 无缝集成到他们的工作流中。这种自动化主要由 postinstall 脚本处理，该脚本在运行 npm install 时自动执行。脚本检测主机的操作系统和架构，以便从 GitHub Releases 下载正确的平台特定可执行文件。这确保了 bd 在 macOS、Linux 和 Windows 系统以及像 Claude Code for Web 这样的临时沙箱中都能以相同的方式运行。
该过程始于平台和架构检测，识别适当的二进制文件名称和扩展名（例如 Windows 的 .exe）。然后，脚本构建下载 URL 以获取相应的归档二进制文件（例如类 Unix 系统的 .tar.gz 或 Windows 的 .zip）。下载并提取后，原生 bd 二进制文件被放置在包的 bin 目录下，被赋予执行权限，并通过运行基本命令（如 bd version）进行验证。这种方法确保了具有完整 SQLite 支持和性能优势的原生 bd 二进制文件在无需手动配置的情况下即可使用。有关 postinstall 脚本实现的更多详细信息，请参见 npm-package/scripts/postinstall.js。
对于像 Claude Code for Web 这样的特定场景，此自动安装被集成到 SessionStart 钩子中，保证 bd 在每个会话开始时都已安装并初始化。这在 临时环境中的 AI 代理集成 以及 npm-package/CLAUDE_CODE_WEB.md和 npm-package/INTEGRATION_GUIDE.md 文档中有进一步阐述。该设计倾向于使用此原生二进制包装器而非 WebAssembly (WASM)，以维持完全的功能对等并优化性能，如 npm-package/README.md 中所述。
临时环境中的 AI 代理集成#
bd CLI 集成到了临时的 AI 编码代理环境中，特别是针对 Claude Code for Web 等平台。这种集成确保 bd 在每个会话开始时自动安装和初始化，为 AI 代理提供持久的、基于 Git 的问题跟踪系统。
位于 npm-package 中的 @beads/bd npm 包促进了这种集成。该包包装了原生 bd 二进制文件，允许在 AI 代理沙箱中常见的 Node.js 环境中进行零配置安装。决定包装原生二进制文件而不是编译为 WebAssembly (WASM)，确保了完整的 SQLite 支持、与原生工具的完全功能对等以及最佳性能，没有 WASM 的开销。
在临时环境中，SessionStart 钩子至关重要。这些 shell 脚本在新会话开始时自动执行，处理 @beads/bd 的全局安装，并使用 bd init --quiet 默默初始化 bd。这在 npm-package/CLAUDE_CODE_WEB.md 和 npm-package/INTEGRATION_GUIDE.md 中有详细说明。这保证了 bd 从任何编码会话开始就始终可用并配置好供 AI 代理使用。
AI 代理被指示利用 bd 命令进行结构化工作和问题管理。npm-package/INTEGRATION_GUIDE.md 等文档为代理提供了关于如何使用 bd 完成以下任务的明确说明：
- 使用
bd ready --json识别就绪工作。 - 通过
bd create创建新问题。 - 使用
bd update --status in_progress更新问题状态。 - 使用
bd comments add向问题添加评论。 - 使用
bd dep add管理问题间的依赖关系。 - 使用
bd close --reason关闭已完成的问题。
--json 标志被特别强调用于程序化解析 bd 命令输出，实现与 AI 代理逻辑的无缝集成。存储为 JSONL 记录的问题数据旨在提交到 Git，允许跨不同会话或开发者进行共享、去中心化和持久化的问题跟踪。这种 Git 支持的方法确保即使在临时环境中也能维护问题的状态和历史记录，为 AI 代理操作提供一致的上下文。有关 bd 命令的更多详细信息，请参阅 Beads CLI (bd)。AI 代理集成的更广泛背景在 AI 代理集成与工作流 中讨论。
集成测试与质量保证#
@beads/bd npm 包经历了一个全面的集成测试策略，以确保其在各种场景下的可靠性和正常运行。这些测试验证了包的安装、原生 bd 二进制文件的核心功能，并模拟了 AI 代理工作流，特别是在“Claude Code for Web”环境中。这确保了正确的平台检测以及 JSONL 自动导出和导入机制的稳健运行。
测试套件主要位于 npm-package/test/integration.test.js 中，每次测试运行都使用一个临时目录，确保隔离并防止副作用。这种设置允许可重复和可靠的测试。
集成测试的关键方面包括：
- 包安装验证：测试确认
@beads/bd包可以成功安装，并且原生bd二进制文件在安装后存在且可执行。这涉及打包@beads/bd的本地版本，将其安装到临时位置，然后验证bd二进制文件的存在。 - 二进制功能检查：执行诸如
bd version和bd --help之类的基本bd命令，以确认安装的二进制文件响应正常且可运行。 - 核心
bd工作流模拟：测试模拟了典型用户与beads的交互。这包括使用bd init初始化项目，使用bd create创建新问题，使用bd list列出问题，通过bd show查看问题详细信息，使用bd update更新问题状态，使用bd close关闭问题，以及使用bd ready识别待处理问题。这也涉及初始化 Git 仓库，因为beads依赖 Git 进行版本控制。 - AI 代理工作流模拟 (“Claude Code for Web”)：测试的很大一部分集中在复制 AI 代理在临时环境中与
beads的交互。这包括创建问题，观察问题数据自动导出到 JSONL 文件，通过删除数据库文件模拟新会话，然后重新初始化项目以确保问题正确地从 JSONL 文件重新导入。随后的操作，如代理发现就绪工作和创建新问题，也会得到验证。这确保了系统的持久性和同步机制在 AI 驱动的工作流中按预期运行，如 AI 代理集成与工作流 中进一步详述。 - 平台检测逻辑：测试验证用于检测操作系统和架构的内部逻辑（
os.platform()和os.arch()）是否正确识别受支持的平台并构建用于二进制下载的适当 GitHub release URL。这确认了npm-package/scripts/postinstall.js中的postinstall脚本能够可靠地为不同环境下载正确的二进制文件。
测试套件提供结构化的彩色输出，这对于调试和了解测试进度至关重要。整体策略确保 @beads/bd npm 包及其底层 bd 二进制文件健壮、可靠，并能够支持人类开发者和 AI 代理管理问题生命周期。有关自动化测试套件的更多信息，请参阅 npm-package/TESTING.md 中的 TESTING.md 文件。
项目准则与标准#
beads 项目运行在一套定义的准则和标准之上，以确保一致的开发、促进 AI 集成并维护其 Git 支持的问题跟踪系统的完整性。这些准则主要记录在 .github/copilot-instructions.md 中，涵盖项目的目标、技术栈、编码标准和 Git 工作流。
一个核心原则是强制使用 bd 命令行界面 (CLI) 进行所有问题管理，强调“自身使用 (dogfooding)”方法，即项目本身利用 beads 来进行自己的任务跟踪。这不仅确保了结构化的开发方法，还有助于改进工具。
技术栈的特点是基于 Git 的问题跟踪系统，其中问题数据存储在版本控制的 JSONL 文件中，并与内部 SQLite 数据库同步。这种双重存储机制允许通过 Git 进行版本控制，并通过 SQLite 进行高效查询。该项目强调 AI 集成，bd CLI 命令支持 JSON 输出（--json 标志），并且在 integrations/beads-mcp 处有一个基于 Python 的模型上下文协议 (MCP) 服务器，该服务器使 AI 代理能够直接进行函数调用。这促进了 AI 与问题跟踪系统之间比简单的 shell 命令更深层次的交互。有关 MCP 服务器和 AI 集成的更多详细信息，请参阅 用于 AI 代理任务管理的模型上下文协议 (MCP) 服务器。
编码标准侧重于测试驱动开发、一致的代码风格以及有效管理更改的特定 Git 工作流。该设计还结合了问题的依赖意识，允许 beads 理解和管理任务之间的关系。
关键的 bd CLI 命令支撑着问题跟踪工作流，包括用于生成具有详细描述的新问题的 bd create、用于修改问题属性的 bd update 以及用于将任务标记为完成的 bd close。bd list 和 bd show 命令用于检索和显示问题信息。为了管理工作流，bd ready 识别未阻塞的问题，bd stale 有助于发现被遗忘的任务。
维护数据一致性的核心是 bd sync 命令，该命令负责将 beads 更改导出到 Git、提交并推送到远程仓库，从而使内部 SQLite 数据库与 Git 版本控制的 JSONL 文件同步。Git 钩子（通过 bd hooks install 安装）进一步加强了这种一致性。这些命令构成了人类开发者和 AI 代理与 beads 系统交互的支柱，确保所有问题相关的操作都以结构化和可追踪的方式执行。有关 bd CLI 的更多详细信息，请参阅 Beads CLI (bd)。
强制性 bd CLI 使用与工作流#
bd 命令行界面 (CLI) 是人类开发者和 AI 代理与 Beads 系统交互的主要接口。强制使用它进行所有问题管理确保了项目内的一致性、结构化任务执行和稳健的跟踪。CLI 促进了从创建到关闭的整个问题生命周期，并在维护系统数据完整性方面发挥着至关重要的作用。
用于管理问题的核心命令包括：
bd create：用于发起新问题。此命令强制要求详细描述，以确保为未来的工作和 AI 理解提供足够的上下文。bd update：修改现有问题，允许更改状态等属性。bd close：将问题标记为已解决，需要指定关闭原因。bd list：提供基于各种标准筛选和显示问题的功能。bd show：显示特定问题的全面详细信息。
除了基本的问题管理，bd 还提供增强工作流和生产力的命令：
bd CLI 的一个关键方面是 bd sync 命令。此命令负责将更改从内部 SQLite 数据库导出到 Git，进行提交，并将它们推送到远程仓库，从而将内部数据库与 Git 版本控制的 JSONL 文件同步。此同步过程对于维护内部数据库和 Git 仓库之间的一致性至关重要，确保所有问题数据都受版本控制并可协作管理。为了进一步强制执行这种一致性，bd hooks install 命令会安装自动触发同步操作的 Git 钩子。
所有 bd 命令都设计为支持 --json 标志，该标志以机器可读的 JSON 格式输出数据。此功能对于与 AI 代理和脚本的无缝集成至关重要，允许以编程方式与 Beads 系统交互。对于更高级的 AI 集成，位于 integrations/beads-mcp 的模型上下文协议 (MCP) 服务器通过函数调用直接向 AI 代理公开 beads 功能。更多详细信息请参见 用于 AI 代理任务管理的模型上下文协议 (MCP) 服务器。
强制使用 bd CLI 支撑了项目的“自身使用 (dogfooding)”原则，即 beads 本身用于所有自身的任务跟踪，从而增强其实用性并推动持续改进。
部署与发布管理#
beads 项目包含用于管理软件发布、更新和分发的自动化流程。这些流程确保了不同平台间的一致性，并促进了新版本的快速部署。其核心是使用实用脚本进行项目维护、自动化发布工作流以及各组件间的版本同步。
发布工作流由 scripts 目录中的脚本编排，特别是 release.sh。该脚本自动化了诸如运行测试、linting、更新所有相关项目文件中的版本号、提交更改、创建和推送 Git 标签以及更新本地安装等任务。--dry-run 模式允许开发人员在不影响实际代码库或分发渠道的情况下预览这些更改。CLI、插件元数据和 Python 包等组件之间的版本一致性由 scripts/update-versions.sh 等脚本维护，该脚本更新 cmd/bd/version.go、claude-plugin/plugin.json、integrations/beads-mcp/pyproject.toml 和 npm-package/package.json 等文件中的版本字符串。scripts/check-versions.sh 脚本验证此一致性，确保所有版本声明与项目中定义的规范版本一致。
为了分发，beads 利用各种包管理器。对于 Windows，winget 清单在 winget 目录中管理，如 winget/README.md 所述。scripts/update-winget.sh 脚本自动生成和更新这些清单，包括计算发布二进制文件的 SHA256 校验和。这确保了 beads 可以通过 Windows 包管理器轻松安装和更新。Windows 可执行文件还使用 osslsigncode 进行签名，该过程由 scripts/sign-windows.sh 自动化，有助于防止未签名二进制文件常见的防病毒误报，并集成到自动化发布流程中。此外，项目包括通过 scripts/update-nix-vendorhash.sh 自动更新 Nix 配置中 vendorHash 的脚本，这对于在 Nix 环境中维护依赖完整性至关重要。
自动化发布与版本管理脚本#
beads 项目利用一组脚本来管理其发布和版本控制流程，确保各组件之间的一致性并促进部署。这些脚本自动化了诸如更新源代码和元数据文件中的版本号、编排 Git 操作（如提交、标签和推送）以及最终更新本地开发环境等任务。
执行完整发布的主要脚本是 scripts/release.sh。此脚本设计为全面的“一键发布”解决方案。它首先执行发布前检查，例如优雅地停止任何正在运行的 beads 守护进程以防止冲突，并执行单元测试和 linting 以确保代码质量。在预检查成功后，它调用其他脚本来更新所有相关项目文件（包括 CLI、插件元数据和 Python 包）中的版本号。版本更新后，脚本将这些更改提交到 Git，创建对应于发布版本的新 Git 标签，并将提交和标签都推送到远程仓库。提供了一个 dry-run 模式来模拟整个过程而不进行实际更改。
对于本地版本调整，scripts/update-versions.sh 脚本处理跨多个项目文件更新版本字符串，而无需进行 Git 操作或完整的发布工作流。这对于需要在不触发正式发布的情况下更改版本进行测试或本地开发的开发人员非常有用。它更新诸如 cmd/bd/version.go（CLI 版本）、插件 JSON 文件、Python 包配置以及 npm-package/package.json 等文件。该脚本还会更新 README.md 等文档文件和 Git 钩子模板中的版本信息。
为了确保所有版本化组件的一致性，scripts/check-versions.sh 验证所有版本字符串是否与从 cmd/bd/version.go 提取的规范版本匹配。此脚本充当保障措施，防止因手动更新或不完整流程而导致的意外版本差异。
另一个重要的实用程序是 scripts/update-nix-vendorhash.sh，它自动更新 default.nix 配置文件中的 vendorHash。这对于在 Nix 环境中维护依赖完整性至关重要，特别是当 go.mod 文件发生更改时。该脚本通过故意导致 Nix 构建失败以提取正确的哈希，然后更新 Nix 配置，最后验证使用新哈希的构建是否成功来实现这一点。如果本地未安装 Nix，它还支持在 Docker 容器内执行。
对于特定平台的部署，scripts/sign-windows.sh 用于对 Windows 可执行文件应用 Authenticode 签名，提高信任度并减少防病毒软件的误报。此脚本集成到自动化发布管道中，以确保所有官方 Windows 二进制文件都经过正确签名。同样，scripts/update-winget.sh 自动生成和更新 winget 清单文件，以便将 beads 发布到 Windows 包管理器，简化了 Windows 用户的分发过程。这些脚本共同确保 beads 发布是一致的、可验证的且可广泛部署的。
Windows 包管理器 (winget) 清单管理#
beads 项目将发布版本推送到 Windows 包管理器 (winget)，以确保 Windows 用户的广泛可访问性。此过程涉及创建和管理 winget 用于安装和更新应用程序的特定清单文件。此管理的核心位于 winget 目录（包含这些清单的模板和文档）以及 scripts 目录（包含自动化脚本）中。
winget 发布过程依赖于三个主要的清单文件：
SteveYegge.beads.yaml：版本清单主文件，定义beads包的版本号。SteveYegge.beads.installer.yaml：安装器配置，包含安装程序的下载地址 (InstallerUrl) 与 SHA256 校验和 (InstallerSha256)。SteveYegge.beads.locale.en-US.yaml：包的描述与元数据，如发布说明链接 (ReleaseNotesUrl) 等本地化内容。
发布新版本时，需要同步更新三个清单中的版本号、安装器清单中的 InstallerUrl 与 InstallerSha256（用 curl -sL https://github.com/steveyegge/beads/releases/download/v<VERSION>/checksums.txt | grep windows 从发布资产中取出校验和）、以及 locale 清单中的 ReleaseNotesUrl，然后向 microsoft/winget-pkgs 提交 PR：fork 该仓库，在 manifests/s/SteveYegge/beads/<version>/ 目录下放入这三个清单文件，再开 PR；也可以用 wingetcreate 工具一步完成更新与提交：wingetcreate update SteveYegge.beads --version <new-version> --urls <new-url> --submit。