NEEDLE：驱动无头编程 CLI 智能体的确定性状态机编排器

核心能力与快速开始

★ 28 · Rust

能做什么

确定性状态机驱动的 bead 队列处理：按优先级顺序选择、通过 bead CLI 原子认领、从 bead 上下文构建确定性提示词、渲染适配器 YAML 模板并通过 bash -c 无头分派执行。内置适配器包括 Claude Code、OpenCode、Codex 与 Aider。对 success（0，校验后关闭 bead 并记录）、failure（1，记录原因并释放、重试计数加一）、timeout（124，释放并标记 deferred）、crash（>128，释放并创建告警 bead）、race lost（4，排除候选重新选择）、queue empty（进入 strand 升级）等结果均有显式处理路径。支持多个 worker 并行，通过 bead CLI 的 SQLite 事务保证认领唯一性，无中央编排器。队列为空时按顺序执行 strand：pluck、mend、explore、weave、unravel、pulse、reflect、splice、knot。提供 needle doctor 健康检查、needle list/status/attach 会话管理，以及 worker 生命周期与清理流程。默认启用 shipped-work gate，要求派发产生位于 notes/ 与 .beads/ 之外、且已推送到分支上游的提交才接受关闭；未显式配置门禁的工作区会由语言默认解析器或临时回退门禁按固定顺序（scripts/definition-of-done.sh、go.mod、Cargo.toml、package.json 的 test 脚本、pyproject.toml、pytest.ini）选择验证命令，并在 git archive HEAD 的干净导出中运行。可选尝试归档会按次写入本地 spool 的对话记录、追踪与提示词包。安装脚本默认校验 SHA-256。

适用场景

面向需要无人值守、长时间、成本可控地批量推进编码任务的场景：把结构化工作项（bead）放进共享队列，由多个 worker 并行认领并交给无头编码 CLI 智能体执行，再按结果自动关闭、重试、延迟或告警。适合希望用显式状态机替代对话式框架的团队编排非确定性智能体步骤，也适合在仓库中接入验证门禁以确保任务完成有可验证证据。

项目形态

可直接使用的工具

部署方式

提供 Linux x86_64 预编译二进制，其余平台需从源码构建（Rust 1.85+，工具链版本固定在 rust-toolchain.toml）；可用 cargo install 从 Forgejo 主仓库或 GitHub 只读镜像安装，安装脚本默认写入 ~/.local/bin（可用 NEEDLE_INSTALL_PATH 覆盖）。材料未说明托管服务形态或其他平台支持情况。

主要依赖

需要 git、tmux，以及 PATH 中可用的智能体 CLI（快速上手流程使用 Claude Code）；工作分支需设置上游（默认门禁要求提交已推送）。使用 bead-rs 后端时依赖其 SQLite 存储与 bead CLI。材料未说明具体硬件、API 配额与费用要求。

使用限制

内置 claude 适配器会以 --dangerously-skip-permissions 调用 claude -p，即无人值守运行时不出现权限提示，需在执行前阅读 needle config。shipped-work gate 对没有上游分支的纯本地仓库无法检查，需显式关闭。当前回退验证门禁被标注为 INTERIM 机制，计划由 needle-d1b2ee0d runner 替代，机制可能变化。材料未说明各智能体 CLI 的授权、API 成本与限流情况，也未说明可商用的具体约束（仅标注 MIT 许可证）。

许可证

MIT

最近推送

2026-09-29 06:53

资料检查：2026-09-29 07:00 · 卡片整理：2026-09-29 07:00
卡片由 AI 根据仓库资料整理，未进行安装或运行验证 · 本次更新未完成，保留上次成功内容

职业应用

程序员

作为无头编程 CLI 智能体的编排器，按确定性优先级从共享 bead 队列中原子认领工作项，生成确定性提示词并分派给 Claude Code、OpenCode、Codex、Aider 等适配器以 bash -c 无头执行，再按成功、失败、超时、崩溃、竞争失败等结果走显式处理路径，用于自动化代码编写、测试与交付验证。

官方使用入口 ↗

由 AI 根据来源材料整理，未进行安装或运行验证