fagan

Fagan

把 Token 花在判断上，而不是敲代码上。

一个真实故事（STE-1, PR #986）在看板上的流转：由开源权重模型实现，经评审退回一次，最终合并。延时呈现 14 分钟的过程。

立即试用（macOS；Linux 可通过 Ollama 或 LM Studio 使用），然后查看快速入门：

curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh | bash

前沿模型按 Token 收费，擅长判断。本地模型可免费运行，编写代码也够用。这条流水线正是沿着这条分界来拆分软件工程工作：前沿模型负责分解工作、制定计划、评审差异，并裁定任何高风险事项；本地模型则负责编写实现，无需额外费用。

让低成本环节值得信赖的关键在于检查。Michael Fagan 在 1976 年 IBM 研究中发现，正式检查找出了已发布产品中 82% 的缺陷——每千行代码 38 个，而单元测试为每千行代码 8 个。质量取决于把关，而非作者。因此，本项目将预算用于把关：在实现前强制执行 TDD，进行独立评审，通过验收预言机评分，设置分级风险的监督机制，对任何不可逆操作暂停并交由人工处理，并设置合并关卡，在合并前针对变基后的分支重新运行测试套件。

目标明确而具体：以每月 20 美元的预算，实现企业级工程规范——任务分解、TDD、代码评审和按依赖顺序交付。

详细参考资料请参阅 REFERENCE.md。

**开始之前：**请阅读下方的可靠性与局限。这是一个自主编码流水线，存在真实且有文档记录的失败模式——它还不是那种无需操心、只需“描述功能即可获得 PR”的工具。

平台支持

本项目在 macOS 上开发，并作为日常工作环境使用。核心部分（MCP 服务、仪表板、Claude 后端的派发与评审、完整测试套件）均为纯 Python；CI 会在每次推送时，于 Ubuntu 上使用 Python 3.11–3.14 进行测试，并在 macOS 上使用 Python 3.14 进行测试。以下两部分仅支持 macOS：

• launchd/*.plist — 在 macOS 上，调度器、MLX 监督程序和用量轮询器会打包为 launchd 任务。在 Linux 上，请使用 scripts/generate_systemd_units.sh 生成对应的 systemd 配置（参见下文的调度器），而不是手动编写 init 文件；也可以直接在前台终端或 tmux 会话中运行入口程序。
• MLX（PIPELINE_LOCAL_PROVIDER=mlx）——仅支持 Apple Silicon。Linux 上也可通过 Ollama 或 LM Studio 正常进行本地派发（PIPELINE_LOCAL_PROVIDER=ollama / lmstudio）。

未经 Windows 测试。

快速入门

一行安装

curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh | bash

这会将仓库克隆到 ~/.fagan（可通过 FAGAN_INSTALL_DIR 覆盖位置，并通过 FAGAN_REPO_URL 覆盖源 URL），然后在仓库内运行 scripts/install.sh——相当于下面的手动克隆和运行步骤，只是省去了输入命令。之后再次运行时会更新现有 检出内容（git pull --ff-only），而不是重新克隆。

将远程脚本通过管道传给 bash，意味着要信任该 URL 在获取时提供的内容。 如果你想先阅读脚本：

curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh -o remote-install.sh
less remote-install.sh   # or open it in an editor
bash remote-install.sh

无论使用哪种方式，都要进入安装目录（命令会报告该目录，默认为 ~/.fagan）； 步骤 1–3 已经完成，因此请重启 Claude Code（步骤 5）。想手动克隆？请改用 下面的步骤。

这样就能注册 MCP 服务，并端到端运行第一个计划。 首次运行完全不需要本地模型：如果没有任何配置，调度和审查会回退到 claude 后端，该后端会调用 Claude Code CLI。这种回退是起始配置，并非预期配置 ——只有在你有意将实现角色路由到本地模型后，上文所述的成本划分才会生效。也正因如此，随附的注册表 本身不包含 roles 块：准备好选择时，请参阅下文的提供方选择与授权。

# 1. Clone and install the Python environment
git clone https://github.com/motock/fagan.git
cd fagan
scripts/install.sh          # creates .venv, installs requirements.txt

# 2. Register the MCP server with Claude Code (adjust the path to where you cloned it)
claude mcp add -s user pipeline "$(pwd)/.venv/bin/python3" "$(pwd)/app/pipeline_mcp_server.py"

# 3. Copy the persona subagents and decision policy into place
#    (cp -n skips any file you already have — e.g. a customized code-reviewer.md —
#    instead of silently overwriting it; diff before removing -n if you do want the update)
mkdir -p ~/.claude/agents
cp -n agents/*.md ~/.claude/agents/
cp -n overlord-policy.md ~/.claude/overlord-policy.md

# 4. (Optional) Install the global rules bundle for your agent CLIs
#    scripts/install_global_rules.py --tools=claude,codex,opencode
#    Opt-in: nothing is written unless --tools is passed. It writes the bundle into
#    ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md and ~/.config/opencode/AGENTS.md, copies
#    the rule files into the sibling fagan-rules/ directory, and backs up an existing
#    file as <name>.fagan-bak-<UTC timestamp>. Re-running refreshes only the fenced
#    block between the fagan:begin and fagan:end markers.

# 5. Restart Claude Code (or start a new session) so it picks up the MCP server

scripts/install.sh 会创建 .venv，安装 requirements.txt 和 requirements-dashboard.txt（仪表板的 fastapi/uvicorn 依赖，每次运行都会安装； --dev 安装会使用 requirements-dev.txt，其中已包含仪表板依赖），并报告流水线调用的 工具状态——必需工具：git、gh 和 claude CLI；可选工具：ollama 和 docker——同时提供优雅降级提示，且可安全地重复运行。它不会注册 MCP 服务、设置环境 变量或安装 persona 子 Agent——上文的步骤 2–3 会处理这些。若只配置了 claude 后端， 没有安装 ollama/docker 是预期情况，并非错误。

在你希望流水线处理的项目中，启动 Claude Code 会话，然后：

1. 请 product-analyst 子 Agent 将目标拆分为史诗/用户故事，或按照架构手动编写计划。
2. 调用 mcp__pipeline__save_plan（或 ingest_plan），传入该计划以及指向目标项目的 repo_root——不要指向本流水线仓库。
3. 调用 mcp__pipeline__list_ready_stories 查看哪些故事已解除阻塞，然后调用 mcp__pipeline__dispatch_story 领取并启动一个故事。
4. 通过仪表板监控进度：运行 scripts/dashboard.sh start，然后打开 http://localhost:8000。
5. 如需无人值守运行，请启动调度器，让已就绪的故事自动推进，而无需你手动调用 advance_pipeline： .venv/bin/python3 -m pipeline.scheduler_daemon（前台运行，或通过 launchd/systemd/tmux 运行——参见下文的调度器）。

先使用 PIPELINE_AUTONOMY=dry-run（仅生成计划和日志，不会调度或合并任何内容）， 直到你观察过一次计划运行并信任各项关卡——参见自主级别。

只使用 claude 后端？ 只有在你选择让某个角色通过本地模型调度时， PIPELINE_LOCAL_* 和 PIPELINE_BACKEND_*=ollama/lmstudio/mlx 变量以及 Ollama/MLX/LM Studio 设置才有用——但仍必须进行提供方选择（随附的注册表不会路由任何内容； 参见下文的提供方选择与授权）。此外，即便使用 claude 路径，首次调度前也需要两项凭据： gh auth login（流水线通过 GitHub CLI 创建和合并 PR）以及 Claude Code CLI 自身的登录凭据。请参阅 最简配置，了解首日真正值得设置的少数几个变量， 以及约 100 个纯粹用于调优的变量。

提供方选择与授权

选择提供方是必需的设置步骤。 随附的 model_registry.json 明确声明了各提供方支持哪些模型， 但有意不提供任何 roles 路由：本项目不依赖任何单一 提供方，因此由操作者自行选择。每个角色有两种受支持的提供方选择方式， resolve_role 会按以下顺序检查：

1. 计划角色配置 — 计划中针对各角色设置的 provider/model 优先级 高于以下所有选项。
2. 注册表文件中的 roles 块 — 角色路由的唯一事实来源；见下文。
3. PIPELINE_BACKEND_<ROLE> 环境变量 — 仅当注册表中没有该角色的条目时才会检查（空状态路径，因此新克隆的项目仍可启动）；例如，PIPELINE_BACKEND_DISPATCH=ollama 会让调度角色使用 Ollama。
4. 调用方自己的回退选项 — 对调度/审查而言，这是 claude 后端。

如需交互式地选择提供方，而不是手动编辑注册表 JSON，请运行 选择器：.venv/bin/python scripts/choose_providers.py。它会逐一引导设置全部 九个角色，显示每个角色当前的提供方/模型及其设置来源，并允许你输入选项编号进行切换——九个角色分别独立配置，每次更改都会先根据注册表进行验证，再写入文件。你可以随时安全地重新运行：重新运行只会重新读取当前路由，按 Enter 则保留该角色现有的设置。

两种选择方式使用相同的两个注册表文件：

• PIPELINE_MODEL_REGISTRY_PATH 用于指定管线使用的任意注册表 JSON。
• model_registry.local.json（仓库根目录）是个人注册表的惯用文件名：该文件已被 gitignore，因此各角色的路由设置不会进入 仓库。将 PIPELINE_MODEL_REGISTRY_PATH 指向该文件；如果你不想设置此变量，也可以在本地将其复制并覆盖 model_registry.json。

roles 块会为每个角色指定一个提供方和一个易读的模型名称；该易读名称必须存在于同一文件中该提供方的 models 下，并由此解析出具体标签。拼写错误会引发错误，而不是静默回退。

授权矩阵。 选择提供方也决定了你必须先配置哪些凭据——scripts/install_checks.py 会检查这些凭据，并在可行时报告 unauthorized（解决方法：登录，而非安装）：

提供方 / 工具	所需凭据	配置方法
git / gh	GitHub 身份验证（管线通过 gh 创建并合并 PR）	gh auth login
claude 后端	Claude Code CLI 自身的登录	claude auth login（检查：claude auth status）
任何 :cloud ollama 标签	ollama.com 账户，并登录到本地守护进程	ollama signin
litellm 后端	各供应商的 API 密钥	参见 docs/specs/LITELLM_PROVIDER.md
设备本地的 ollama / lmstudio / mlx 标签	无需额外配置	—

对于 :cloud 行：这些调用会通过本地 ollama 守护进程代理至 https://ollama.com，并由该守护进程发送自身凭据——管线本身不会发送凭据。:cloud 标签是唯一需要登录的 ollama 标签；纯设备本地标签只需确保守护进程正在运行。

入门指南

该指南适用于你配置的任意调度提供方 — PIPELINE_BACKEND_DISPATCH（显式设置，或在本地注册表中添加 roles 块 — 随附的注册表不会路由任何内容；请参阅上文的提供方选择 与授权）。配置 claude 时，调度和审查会调用 Claude Code CLI；配置 ollama 等本地提供方时，则会改用该本地模型运行。

1. 安装 — 只需一条命令：scripts/install.sh（有关它会做什么和不会做什么，请参阅上文的快速入门）。
2. 注册 MCP 服务和角色设定 — 按照上文快速入门的步骤 2–3 操作（运行 claude mcp add ...，并复制 agents/*.md 和 overlord 策略），然后重启 Claude Code。
3. 启动仪表板 — 运行 scripts/dashboard.sh start，然后打开 http://localhost:8000，并在工作区选择器中选择目标项目。
4. 分解一个小目标 — 请 product-analyst 子 Agent（或使用仪表板的分解操作）将一句话目标拆分为 史诗/故事，然后使用 mcp__pipeline__save_plan 保存结果，并将其中的 repo_root 字段指向目标项目，而非此流水线仓库。
5. 调度首个就绪故事 — 运行 mcp__pipeline__list_ready_stories， 然后对第一个故事运行 mcp__pipeline__dispatch_story，并在仪表板中观察故事 在看板上推进。
6. 观察合并 — 使用 PIPELINE_AUTONOMY=gated（默认值）时，通过审查的 风险等级为 low 的故事会在无人值守的情况下合并。请先按上文快速入门的建议， 使用 PIPELINE_AUTONOMY=dry-run。 设置 PIPELINE_AUTO_MERGE=0，即可保持其他步骤自动执行，但不自动合并；之后只能通过 approve_merge 或手动方式合并。
7. 更喜欢脚本方式？ — .venv/bin/python scripts/smoke_getting_started.py 会在临时的 PLAN_DIR 中端到端运行相同流程，不使用仪表板，也不会触碰你的真实计划。此冒烟测试 与提供方无关：它会使用你配置的调度提供方运行 （PIPELINE_BACKEND_DISPATCH，默认值为 claude），并在开始时公布解析出的 提供方、模型和来源，让你始终清楚它验证的是哪个后端。退出码：0 表示通过（故事到达 tests_passed），1 表示解析出的提供方是 claude，但缺少 claude CLI；退出码 2 表示 配置的提供方为空或无法识别 — 这是配置错误， 并非拒绝使用本地提供方；3 表示有界轮询超时；4 表示 故事失败。坦诚说明：通过与否取决于配置的模型是否实际完成故事，因此弱本地模型上的失败反映的是该 模型，而不是流水线损坏。

有关仍可能出错的情况，请参阅 可靠性与局限性。

配套 MCP 服务（仅限 overlord + 验收预言机）

还没准备好采用整套编排器？pipeline/companion_server.py 是第二个、更精简的 MCP 服务（pipeline-companion），提供两个无需采用流水线其余部分也能独立使用的功能： escalate_decision（overlord 决策路径）以及验收预言机辅助工具 classify_oracle_outcome / acceptance_digests。它导入实际的 pipeline.overlord 和 pipeline.oracle_gate 模块，而不是复制这些模块，因此能与主服务保持 同步。将其作为第二个 mcpServers 条目，与主服务一同添加：

{
  "mcpServers": {
    "pipeline": {
      "command": ".venv/bin/python3",
      "args": ["app/pipeline_mcp_server.py"]
    },
    "pipeline-companion": {
      "command": ".venv/bin/python3",
      "args": ["-m", "pipeline.companion_server"]
    }
  }
}

此服务导出的可采用规范位于 docs/specs/： OVERLORD_POLICY_SPEC.md（overlord 决策路径）、 ACCEPTANCE_ORACLE_PATTERN.md（验收预言机评分模式），以及 DOCKER_SANDBOX.md（选择启用的 Docker 沙箱行为）。

独立运行（仪表板 + 调度器，无需 MCP 服务）

仪表板提供与 MCP 工具相同的操作——保存/导入计划、分解目标、分派故事、推进、审查、批准合并——因此无需注册 MCP 服务也能运行整个流水线。这种功能对等性体现在 HTTP API 中，而不是 UI 中：仪表板 UI 可直接使用聊天功能（包括起草计划）、浏览计划、故事、日志记录和日志、工作区选择器、工作树补丁审查/应用流程、角色配置，以及导入已保存的计划。分派、推进、审查和批准合并都有可用于脚本的无 UI API 路由（/api/plans/{plan_name}/stories/{story_key}/dispatch 等）；对于独立运行流程，预期由调度器驱动：先从仪表板起草并导入计划，然后让调度器自行分派、推进、审查并合并已就绪的故事。受支持的方式只需一条命令：

scripts/standalone-setup.sh up

up 会准备一个临时数据目录（默认为 ~/pipeline-standalone），写入包含绝对路径的共享运维环境文件，通过现有辅助脚本启动仪表板和调度器，然后在 GET /api/health 返回的 config_mismatch 为空且 plan_dir 符合预期之前，拒绝报告成功。主要选项：--data-dir DIR（默认为 ~/pipeline-standalone）、--target-repo DIR（默认为数据目录下的临时仓库）、--port PORT（默认为 8001）、--autonomy MODE（默认为 dry-run），以及 --repo-root 和 --force。down 会停止两个进程并保留临时数据；status 会打印解析后的路径和两个进程的状态。

两个长时间运行的进程读取同一个运维环境文件： scripts/dashboard.sh 和 scripts/scheduler.sh 都会先加载 .pipeline.env（已加入 gitignore；参见 .pipeline.env.example），再加载 .dashboard.env（已加入 gitignore；参见 .dashboard.env.example），因此现有仅安装仪表板的部署仍保持当前的后写优先级——.dashboard.env 仍可使用，并会覆盖与 .pipeline.env 中重叠的配置。

由于仪表板和调度器是独立进程，二者的 PLAN_DIR 必须一致：调度器会将配置指纹写入 <plan_dir>/.scheduler_health.json，而 /api/health 会在 config_mismatch 中列出仪表板解析出的配置与该指纹不一致的字段。config_mismatch 非空意味着 UI 和调度器使用的是不同的计划存储目录——请检查二者是否都以相同的 PLAN_DIR 启动（独立运行脚本正是为此写入同一个环境文件，并且在 config_mismatch 非空时会直接失败）。

独立模式仍需满足常规前置条件：走 PR/合并流程需执行 gh auth login（流水线通过 GitHub CLI 创建并合并 PR），并为所配置的后端完成授权——参见上文的 提供方选择与授权。

引导式配置（一条命令）

scripts/install.sh 会在结束时运行 scripts/configure.py，该脚本会检测已有配置，并写入 .pipeline.env、角色路由，以及（可选的）后台服务。只有 stdin 和 stdout 都是 TTY 时才会提示；使用 --yes 或通过管道安装（curl ... | bash）时，会应用安全默认值且不会提示。

传入 --dry-run 可打印计划而不进行任何写入。所有标志、键和默认值均记录在 docs/guided-setup.md 中。

组件一览

组件	位置	作用
角色子 Agent	~/.claude/agents/*.md	Agent 扮演的 SDLC 角色
决策策略	~/.claude/overlord-policy.md	overlord 如何做出决策
流水线 MCP 服务	app/pipeline_mcp_server.py（启动垫片）→ pipeline/ 包	所有流水线工具和编排；pipeline/server.py 是入口模块，功能拆分到 pipeline/*.py（分发、审查、CI、推进、存储等）
后端接口	app/backend.py	按角色路由驱动程序（claude / ollama / lmstudio / mlx / local）；单次调用、审查、分发、资源门控
本地 Agent 循环	scripts/local_agent.py	用于本地分发的原生工具调用编写循环（子进程）
监控仪表板	app/dashboard.py、static/	FastAPI 状态／生命周期查看器；在独立模式下（参见上文“独立运行”），还可直接驱动保存／摄取／分发／审查／合并
安装／依赖项	scripts/install.sh、requirements*.txt	venv 和依赖项设置
测试	tests/unit/（15,000+ 项测试）	pytest，通过 venv 运行
计划／清单／日志	~/.claude/plans/	计划、清单、决策、通知
Worktree	~/.claude/worktrees/	按故事隔离的分支
问题跟踪器	Plane（外部，可选）	故事状态的镜像；未配置时完全跳过（清单是事实来源）

仪表板的通讯视图——询问哪些事项受阻、起草计划或批准合并，所有操作都通过同一套受门控 API 路由，该 API 也供看板自身的按钮调用。更多截图（实时看板和工作区选择器）请见 docs/DEMO.md。

超越核心循环

• 不只是 Python。 测试、lint 和构建门控会根据目标仓库的构建文件识别其生态系统；已提交的 .fagan.json 则声明无法自动识别的命令。请参见 测试、lint 和构建命令。
• 通知。 每个流水线事件都会写入按计划区分的通知日志。选择启用电子邮件（PIPELINE_NOTIFY_EMAIL_ENABLED=1）后，调度器会通过发件箱发送计划完成、搁置的故事，以及分发、测试和 Agent 失败通知；未送达的消息会保留到下次尝试。请参见 通知。
• 从仪表板进行审查。 每个故事的模态窗口都会显示其 worktree 相对于分叉点的只读差异（也可通过 get_story_diff 工具获取）；卡住的故事可以通过补丁审查和应用提交建议的补丁；计划列表则限定为当前活跃仓库。
• 跨计划协调。 故事可以等待另一个计划中的故事（blocked_by）；如果两个计划中正在进行的故事修改了相同文件，流水线会发出警告。请参见 跨计划协调。
• 需人工把关的合并。 PIPELINE_AUTO_MERGE=0 会保留自动分发和审查，但将每个已审查的 PR 搁置，等待你通过 approve_merge 或手动合并。
• Agent 的运行位置。 可选择启用 Docker 沙箱、通过 SSH 远程分发或审查，以及通过 LiteLLM 路由到托管服务商。
• 卡住故事的处理。 对于 Agent 已停止响应的进行中故事（默认 30 分钟），调度器会发出标记；启用 PIPELINE_AUTO_TRIAGE=1 后，overlord 会对失败或搁置的故事采取措施：升级模型、拆分故事、修补损坏的验收测试夹具，或将其暂时保留供你处理。pause_plan 可暂停一个计划，不影响其他计划。

---

架构

 ┌────────────────────────────────────────────────────────────────────────┐
 │ Scheduler daemon (or a manual advance_pipeline call)                   │
 │ advance_pipeline(plan) — one idempotent tick                           │
 └────────────────────────────────────────────────────────┬───────────────┘
                          ready stories (deps satisfied)  │
                                                          ▼
 ┌───────────────┐  resolve backend +     ┌───────────────────────────────┐
 │ Plan/Manifest │  persona/model         │ Dispatch                      │
 │ (JSON, Plane) │───────────────────────►│  claude -p  OR  local loop    │
 └───────────────┘                        │  (tech-lead plans for local → │
                                          │   .agent_plan.md)             │
                                          └───────────────┬───────────────┘
                                                          ▼
                                          ┌───────────────────────────────┐
                                          │ Headless story agent, TDD-    │
                                          │ first, in an isolated git     │
                                          │ worktree                      │
                                          └───────────────┬───────────────┘
                                   local fail → escalate  │ tests +
                                      to claude (`auto`)  │ acceptance oracle
                                                          ▼
                                          ┌───────────────────────────────┐
                                          │ code-reviewer: VERDICT,       │
                                          │ opens a PR                    │
                                          └───────────────┬───────────────┘
                                                          ▼
      low    → decide silently            ┌───────────────────────────────┐
      medium → decide, notify the user    │ Overlord adjudicates risk     │──► decisions log
      high   → park, wait for a human     │ (blocked decisions, merge,    │    (audit trail)
                                          │  scope disputes)              │
                                          └───────────────┬───────────────┘
                                                          ▼ approved
                                          ┌───────────────────────────────┐
                                          │ Merge gate: rebase on master, │
                                          │ force-push, poll CI, re-run   │
                                          │ the suite on the rebased      │
                                          │ branch                        │
                                          └───────────────┬───────────────┘
                                                          ▼
                                                       master

Personas（~/.claude/agents/）

每个 persona 都是 Claude Code 子 Agent：一个包含 YAML frontmatter（name、description、model，以及可选的 memory: user）和系统提示词正文的 Markdown 文件。流水线会读取正文，并以此作为角色提示，调度一个无头 Agent。

memory: user 会在每次 Claude 调用时将用户记忆目录注入系统提示词，能提供高价值上下文，但会消耗大量 token。审查者 personas（code-reviewer、security-engineer）特意省略了该设置：它们的任务是机械式检查（运行测试、阅读差异、输出 VERDICT），所需的 CLAUDE.md 规则已写在 persona 正文中；跳过约 132 KB 的记忆注入，可让每次审查调用的输入 token 减少约 30–40%。调度和 overlord personas 则保留该设置，因为它们能从项目上下文中受益，且调用频率较低。

Persona	默认模型	职责
product-analyst	opus	将目标分解为包含验收标准、依赖项和逐项 persona/model/risk 的史诗/故事
solution-architect	opus	通用系统设计、技术选型、API 设计（将移动端工作委派给 mobile-architect）
software-engineer	sonnet	非移动端工作的默认 TDD 实施者
security-engineer	opus	威胁建模和安全审查（OWASP、Secure by Design）
devops-release-engineer	sonnet	构建/CI、分支和工作树规范、发布
code-reviewer	sonnet	审查分支、输出 VERDICT、创建 PR
tech-writer	haiku	为外部可见的变更编写文档
overlord	sonnet	决策权威（见下文）

现有的移动端专家（mobile-architect、mobile-engineer、ux-mobile-principal、qa-test-engineer）保持不变，用于移动端工作。

如需更改某个 persona 的行为或默认模型，请编辑其 .md 文件。frontmatter 中的 model: 行是故事未指定模型时的回退模型。

---

overlord 与决策策略

当故事 Agent 遇到阻碍、两个 personas 意见不一致或某个关卡需要裁定时，overlord（~/.claude/agents/overlord.md）会代表用户作出裁决。它遵循 ~/.claude/overlord-policy.md（以及可选的按仓库设置的 <repo>/.overlord-policy.md 覆盖文件）。

决策级别：

1. 常规 / 可逆 → 静默决策（命名、内部结构、已批准技术栈内的库、重构）。
2. 异步通知（risk: medium）→ 作出决策并继续执行，同时告知用户（新增依赖项、架构变更、增量式 API 变更）。
3. 暂缓并通知（risk: high）→ 不得无人值守地采取行动；暂停并等待人工审查，同时通知用户。包括任何不可逆变更、安全/身份验证、资金、生产配置或破坏性变更。在 dry-run 和 gated 模式下，这些事项会交由人工处理；在 full 模式下，overlord 会裁定并记录裁决，供事后审计。

overlord 会返回结构化裁决（RULING / TIER / RISK / RATIONALE / NOTIFY_USER），解析后写入计划的决策日志，作为审计记录。

---

参考

请参阅 REFERENCE.md，了解完整的 MCP 工具参考、计划/故事 JSON 架构、按角色配置提供商/模型、引导式分解和 TDD 拆分详情、所有 PIPELINE_*/LOCAL_AGENT_* 环境变量、端到端工作流、安全控制、使用门控以及开发/测试说明。

如需查看流水线开发本仓库的端到端实例，包括安装命令、实际生成的拉取请求，以及对其当前能力限制的坦诚说明，请参阅 docs/DEMO.md。

如需了解如何创建发布版本，请参阅 docs/RELEASING.md。

如需查看一键引导式设置（标志、配置键、安全默认值、故障排除），请参阅 docs/guided-setup.md。

前置条件

• Python 3.11+ 和项目 venv。CI 会在每次推送时，于 Ubuntu 上测试 3.11–3.14，并在 macOS 上测试 3.14。
• git 已加入 PATH。
• Claude Code CLI（claude）。
• 当前 forge 的 CLI — PIPELINE_FORGE 用于选择代码托管平台（auto | github | gitlab，默认值为 auto，根据 origin 远程仓库的主机名确定）：github 对应 gh，gitlab 对应 glab。未知值会触发错误。

调度器

advance-scheduler 作为长期运行的守护进程，而不是定期触发的 launchd 任务。launchd 仅负责通过 KeepAlive 在进程崩溃后重启它。

环境变量

• PIPELINE_SCHEDULER_INTERVAL_S – 默认协调扫描间隔（默认 60 秒）。
• PIPELINE_SCHEDULER_HEALTH_PATH – 可选路径，守护进程每次迭代时会在此写入健康状态 JSON。

为你的机器生成 launchd 文件

已提交的 launchd/*.plist 文件和 launchd/pipeline-logs.newsyslog.conf 仅供参考：其中包含维护者自己的绝对路径（/Users/<name>/... 主目录、特定的模型缓存路径），未经修改无法在其他机器上使用。在全新安装时，请使用 scripts/generate_launchd_plists.sh 重新生成这些文件（引导式设置仅在你选择启用后台服务时才会为你生成这些文件）——该脚本根据三个标志填充 launchd/ 中的模板（launchd/com.fagan.pipeline.*.plist.template）：

• --repo-root — 生成的文件应指向的 pipeline 检出目录（默认值：包含该脚本的仓库）。
• --out-dir — 生成的文件的写入位置（默认值：<repo-root>/launchd）。
• --mlx-model-path — 写入 mlx-supervisor plist 的本地 MLX 模型目录。也可以设置 MLX_MODEL_PATH 环境变量来代替此标志；两者同时提供时，以标志为准。如果两者均未提供，脚本会安全地失败并退出，同时显示错误。

同一脚本还会根据 launchd/pipeline-logs.newsyslog.conf.template 生成 launchd/pipeline-logs.newsyslog.conf，仅替换仓库根目录。

scripts/generate_launchd_plists.sh \
  --repo-root "$HOME/.claude/mcp-servers/pipeline" \
  --out-dir "$HOME/.claude/mcp-servers/pipeline/launchd" \
  --mlx-model-path "$HOME/.cache/qwen2.5_coder_14b_manual"

这些 launchd 文件仅适用于 macOS，参见平台支持。

为 Linux 生成 systemd 单元

scripts/generate_systemd_units.sh 会根据 systemd/*.template 生成等效的 systemd 用户单元和 logrotate 文件，方式与 scripts/generate_launchd_plists.sh 生成 launchd 文件相同——但不包括 MLX，因为 MLX 仅适用于 Apple Silicon：

scripts/generate_systemd_units.sh \
  --repo-root "$HOME/fagan" \
  --out-dir "$HOME/fagan/systemd"

安装为当前用户的 systemd 单元（无需 root）：

mkdir -p ~/.config/systemd/user
cp systemd/com.fagan.pipeline.advance-scheduler.service ~/.config/systemd/user/
cp systemd/com.fagan.pipeline.usage-poller.service ~/.config/systemd/user/
cp systemd/com.fagan.pipeline.usage-poller.timer ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now com.fagan.pipeline.advance-scheduler.service
systemctl --user enable --now com.fagan.pipeline.usage-poller.timer
  # Optional: let these run even when you are not logged in
loginctl enable-linger "$USER"

日志轮转（需要 root，仅需执行一次）：

sudo cp systemd/pipeline-logs.logrotate.conf /etc/logrotate.d/com.fagan.pipeline

可靠性与局限

此流水线会运行真实的自主编码循环，并且会以特定且有记录的方式失败——在将它用于任何重要任务之前，请先阅读本节。

• 本地（非 Claude）模型调度是薄弱环节。 对于范围小、任务明确的故事（一个关注点、≤2 个生产文件），它表现良好；但对于更大的任务，表现会急剧下降：修改大型文件、涉及多个函数的故事，以及在现有长函数中插入锚定内容，都会稳定地导致步骤上限超时、停滞，或因使用过时行号修改而破坏文件。本仓库中的 docs/plans/*.md 和 retros/*.md 是得出这一发现的真实事故记录，不是营销说辞——在让本地调度处理任何不简单的任务之前，请先读几份记录。设置 PIPELINE_BACKEND_DISPATCH=auto，就是为了在本地尝试遇到困难时升级到 Claude，而不是任由它陷入循环。
• “每月 20 美元”的说法是各项门控措施围绕的设计目标，尚未经过基准测试验证。 目前有记录的唯一一次完整模型对比测试（tests/benchmark/FINDINGS.md）在运行过程中受到速率限制和额度耗尽的影响，因此尚未发布跨后端、干净且可直接比较的成功率／成本对比结果。其中最可靠的数据范围很窄——设备端运行的 gpt-oss:20b，2 个 T1 任务，2/2 成功，合并代码通过独立预言机验证，每项任务各试一次——这只能反映趋势，并非质量对比。在引用其中的数据之前，请阅读该文件，确认哪些结论已知、哪些尚不清楚。
• 测试套件全绿，并不能证明改动正确或完整。 执行器（本地或 Claude）会收敛到能让自己的测试通过的最小差异，并且可能编写与实现自洽但错误的测试，使其与实现包含同一错误。请参阅 .claude/rules/code-review.md 中的 "合并门控与 AI 审查经验教训" 部分——其中的每一条经验都来自真实合并后引发的回归，而非假设情境。
• 标记为 done 的故事，并不能证明其标题所述范围已全部交付。 “迁移所有内容”或“移除所有 X”这样的故事，即使只完成了部分工作，也可能通过审查并合并，因为审查评估的是故事自己的测试，而不是标题中的承诺。请参阅 .claude/rules/agent-dispatch-story-sizing.md。
• overlord 的 park-and-ping 级别是真正的安全底线，不是建议——在高风险决策（不可逆操作、身份验证／安全、资金、生产配置、破坏性变更）中，dry-run 和 gated 模式会暂停并等待人工处理；在 full 模式下，overlord 会裁定高风险合并拦截，并记录裁定结果以供事后审计。任何新的部署都应从 PIPELINE_AUTONOMY=dry-run 开始，并在信任 gated 或 full 之前阅读决策日志。
• 这是一个由单人维护的研究项目，并非提供 SLA 的受维护产品。测试套件和 CI 确实会执行门控，但仍可能存在不完善之处；随着新问题不断被发现，故障模式目录也会持续扩充。

如果遇到新的故障模式，建议记录下来（现有格式请参阅 retros/），而不是悄悄绕过问题——这个项目设计的全部价值，就在于为故障模式命名，并将经验反馈到故事范围的划分与审查中。

许可证

本项目采用 Apache License, Version 2.0 许可——请参阅 LICENSE 和 NOTICE。