当前大型语言模型驱动的 coding agents（如 Claude Code、Codex CLI）在处理复杂、长时程软件开发任务时，面临核心瓶颈：无状态性和 token 上下文限制。每轮交互重置导致“健忘症”（amnesia），代理遗漏先前发现的问题、丢失嵌套计划上下文，或在多代理协作中重复劳动，甚至因意外 diff 而 panic。Beads 项目（https://github.com/steveyegge/beads）提供轻量级解决方案：一个 graph-based issue tracker，将任务串成“beads”（珠链），赋予代理持久 episodic memory，存储代码变更 diff、决策 rationale 及环境上下文，支持跨会话迭代开发。
Beads 的核心是四种依赖类型构建的任务图：blocks（阻塞，强制顺序）、related（关联，提供背景）、parent-child（层级分解）、discovered-from（发现链接，新问题追溯源头）。代理无需人类干预，即可自动创建 issue（如 bd create "Fix auth bug" -t bug -p 0），添加依赖（bd dep add NEW-ID PARENT-ID --type discovered-from），更新状态（bd update ID --status in_progress），并关闭（bd close ID --reason "Implemented"）。数据以 JSONL 格式 git 版本化，SQLite 提供查询视图，实现分布式共享：多机代理通过 git pull/push 同步逻辑数据库，避免中心化依赖。“Beads issues are backed by git, but through a clever design it manages to act like a managed, centrally hosted SQL database shared by all of the agents working on a project (repo), even across machines.” 此设计提升审计性：完整变更日志允许重构跨会话操作。
落地参数与配置至关重要。首先，零配置安装：curl -fsSL https://get.beads.sh | bash（支持 macOS/Linux Go 1.21+，fallback 源码构建）。在项目根执行 bd init 生成 .beads/ 目录（SQLite db + JSONL）。代理集成：在 AGENTS.md 或 CLAUDE.md 末尾添加：“We track work in Beads instead of Markdown. Run bd quickstart to see how.” 代理启动即 bd ready --json | jq '.[0]' 选就绪任务（无开阻塞者），优先级 -p 0 高于默认。
CLI 参数优化代理效率：
- 查询：bd ready --json（限 1-5 项，避免 overload）；bd dep tree ID（可视化深度，阈值 <10 防循环）。
- 创建：bd create TITLE -t task|bug|epic -p PRIORITY（0-10），附 --body "Rationale: ..." 存推理。
- 超时/续传：虽无内置 TTL，建议代理脚本每 30min bd sync（git fetch + pull），阻塞超 2h 则 bd update --status stalled。
- 多代理：bd list --agent AGENT_NAME 隔离视图，协作时 bd dep add --type blocks 显式锁序。
监控与阈值清单：
- 就绪任务数：bd ready | wc -l >3 → 负载均衡，分配子代理。
- 依赖深度：bd dep tree --max-depth 8，超阈 → 重构 epic。
- 未闭 issue 率：<20% 总计（bd stats），否则审视 rationale 质量。
- Git 冲突：pre-commit hook 检查 .beads/*.jsonl diff，代理前 bd pull。
风险控制：Alpha 阶段（3.2k stars），API 变更多，限内测。回滚：rm -rf .beads/ 重置 db，回退 git commit。安全：--json 模式防人类误触，仅代理用；隔离项目 db 避跨 repo 污染。
实际案例：在多代理 workflow（如 backend/frontend），Beads 取代 Markdown swamp：代理发现 frontend API 不匹配，bd create "Align schemas" --discovered-from PARENT，后续 bd ready 自动拾取。结合 mcp_agent_mail（steveyegge fork），扩展为邮箱式协调，file_reservation_paths(["src/**"], ttl=3600s) 防覆盖。
Beads 非万能，但针对 coding agents 的 episodic memory 痛点，提供参数化、可审计的持久化路径。集成后，代理“land on their feet”，从 boot 即 orient，无需重述历史。未来扩展：自定义表、宏 bundling，提升 horizon。
资料来源：