Singular：并行驱动自主 AI 编码代理的编排引擎

Singular 是一个开源的本地编排引擎，专注于在同一个代码仓库内并行调度多个自主 AI 编码代理（AI coding agents），例如 Claude、Codex 等。它以 Bash 与 Python 实现，提供三层智能体调度、租约管理、状态包传递、门禁审计以及 git worktree 隔离等机制，目标是把「一个编排引擎、多个消费仓库」的运维模式固化下来：引擎在机器上只装一次，消费仓库通过版本号 pin 引用，升级靠调整 pin，无需重新复制脚本。

三层智能体架构

Singular 的核心是一个三层调度模型，把任务从规划到执行的职责清晰拆分：

L0 origin（编排层）：系统中唯一的调度器，运行 reconcile 循环（导入 → 恢复 → 集成 → 派发 → 快照），仅在控制操作期间持有 origin 锁。
L1 area planners（区域规划层）：每个 DAG 节点对应一个 planner，读取节点上下文后，将一批 L2 任务作为 proposal 暂存，等待 L0 导入。
L2 workers（执行层）：在独立的 git worktree 与 per-task 分支上执行单个任务，产出包含归属文件、变更、命令、测试与证据的 state packet，再交给审计器审核。

这种分层使得规划与执行解耦，便于在并发场景下既保持一致性，又允许长任务在后台运行。

协调循环与状态管理

每次 singular reconcile --actuate 会按顺序执行五个阶段：Import 拉取 L1 的待处理 proposal；Recover 回收 worker 已退出或超时的过期租约；Integrate 在 git-op 锁下把完成的分支合并到目标分支；Dispatch 预占 frontier 任务并启动 L2 worker；Snapshot 输出人类可读的项目状态快照。

每个在飞任务持有一份租约（lease），记录归属、重试次数与到期时间；任务结束后写入符合 state-packet.v0.schema.json 的状态包，列出归属文件、变更文件、命令、测试及证据。审计器校验状态包，reaper 则在后续周期内把结果归属到对应记录上。

门禁与审计机制

每个 L2 worker 运行结束后，宿主会执行配置的「门禁命令」（例如 npm test），并生成 gate-result.v0.schema.json 结果文件，再交给审计模型产出 audit-verdict.v0.schema.json 裁决。决策器（decider）根据（失败类别, 剩余重试次数）映射出 retry、amend-scope、escalate、park 等恢复动作，并优先走一张确定性的快速路径表，只有在表中无法命中时才回退到模型调用。

引擎也支持可选的「gate observation」，用于：

提供稳定的失败签名 failures[].signature，以便 singular gate baseline 区分已知失败与新失败；
上报 infrastructureFailure / infrastructureReason，把环境类故障（缺依赖、磁盘满、网络不可达）标记为 inconclusive-infrastructure，避免模型在代码本身没问题的情况下浪费重试预算。

如果消费方没有提供 sidecar，引擎会退化为只依赖退出码与一个刻意收窄的环境错误日志签名集合。

派发与进程管理

默认开启「detached dispatch」（SINGULAR_DETACHED_DISPATCH=1）：reconcile 预占 frontier 任务后，通过 dispatch-wrap.sh 把 worker 派发到独立 session 进程，自身在秒级返回。origin 锁只在控制操作期间持有，长任务在后台运行。singular_reap_dispatches 在每次 apply/actuate 周期顶部回收派发结果，通过派发记录与 worker 退出文件归属完成、失败与崩溃——崩溃检测窗口从 60 分钟的 stale-lease 缩短到约一个周期，从而让 import、integrate、recover、STATUS、STOP 等命令保持响应。

如需回到旧的同步批处理模式，只需将 SINGULAR_DETACHED_DISPATCH 设为 0，让 reconcile 等待所有 worker 完成后再返回。

安装与初始化

运行要求 Bash ≥ 4、python3、git，以及至少一个支持的 runner CLI（claude、codex 等）位于 PATH。macOS 用户若通过 Homebrew 安装新版 Bash，需设置 SINGULAR_BASH_BIN=/opt/homebrew/bin/bash；多套 Codex 安装并存时需用 SINGULAR_CODEX_BIN 指定绝对路径。

基本步骤：

克隆仓库并执行 bash install.sh，引擎会被安装到 ~/.singular/versions/<ver>/，并通过 ~/.singular/current 软链接指向当前版本；
将 ~/.singular/bin 加入 PATH；
在每个消费仓库中运行 singular setup：一次性完成解释器、repo、git worktree 自检、解析引擎 pin、安装缺失的 pin、写入版本文件等动作，使仓库进入「已验证、已停止」的稳定状态。

引擎启动后会刻意使用一个干净的命名空间（SINGULAR_*、singular.config.json、.singular-version、.singular-state/ 以及 SINGULAR_HOME），不读取或导入此前的同名变量，因此每个新消费仓库都需要从 singular setup 重新搭建 DAG，并随版本升级通过 bump pin 的方式接收引擎改进。