01
探索
Explorer 在 plan 模式里读仓库、查历史、提结构化问题。它不写文件、不改 Git，在你确认之前始终只读。
mode plan / read-only
tools read · search · ask
writes 0AI Software Pipeline Factory
需求进来，
流水线出去。
Pipeline Factory 把一条需求变成可执行、可验证、可追溯的软件流水线。探索阶段只读澄清，派发前锁成契约，执行在独立 Worktree 里跑，门禁不过不合并。全过程写进事件流，随时回放。
- 本地优先
- 单进程托管
- 事件溯源
- Node ≥ 22.5
RUN run-8f2c
执行中
- 探索
- 契约
- 入队
- 执行
- 验证
- 合并
12:04:07explorer读取 14 个文件，提出 3 个澄清问题
12:05:32planpipeline-factory-plan 契约完整，等待确认
12:06:10enqueue方案已确认，落盘到 docs/pipeline/plans
12:06:12runworktree factory/20261019-health-check
12:11:48verifypnpm verify · 141 passed
12:12:03mergeMERGE READY · 等待人工确认
base 3f8a1c7
128 条事件 · 可回放
一条需求，六个工位
每个工位都有明确的输入、产物和边界。模型做模型擅长的事，人做只有人能做的决定。
02
契约
方案被固化成可审阅的 Plan。缺关键项会自动续探索；只有完整契约才形成 CandidatePlan，确认与入队都是人的操作。
docs/pipeline/plans/
plan-7c1e-v1.md
plan-7c1e-v2.md03
入队
依赖、验证子集与优先级由人来挑。Plan 是 Factory-owned 的契约，模型不能替你把前置条件填上。
{
"planId": "plan-7c1e",
"revision": 2,
"verification": ["typecheck", "test"]
}04
执行
每个方案一棵独立 Git Worktree，基线恒为 baseCommit。工作区不干净就硬阻断——你本地看到的代码和 Agent 改的代码必须是同一棵。
branch factory/20261019-health-check
base 3f8a1c7
worktree .pipeline-worktrees/run-8f2c05
验证
验证命令按 tag 选择，结果写进 Run 详情与事件流。不通过就停在那里，不会给你一个“看起来成功”的结果。
$ pnpm verify
✓ domain build
✓ typecheck · 3 packages
✓ test · 141 passed
✓ no cycles
MERGE READY06
合并
最后一步留给人。查看 Merge Request、冲突预测和验证结果，确认后再合并；整条链路都有据可查。
run-8f2c MERGE_READY
target main
action confirm-merged它替你守住的边界
不是“让 Agent 更自由”，而是让每一步都有明确的权限、产物和停点。
只读探索
Explorer 恒为 plan 模式。读代码、查历史、提问都可以；改文件、动 Git 不行。你确认之前，它碰不到工作区。
契约先于代码
Plan 缺失关键项会自动发起内部续探索。只有完整契约才生成 CandidatePlan，确认与入队是人的决定。
隔离执行
每个 Run 有自己的 Worktree 和分支，基线固定为派发时的 baseCommit。未提交改动不会被偷偷带进工作树。
门禁验证
验证命令按 tag 挑选，结果进入 Run 详情和事件流。失败就是失败，暂停、补要求、重新验证都在同一个 Run 上完成。
事件溯源
需求、Plan、Run、门禁、合并都写事件。SSE 推送实时时间线，历史事件可回放，排障不靠猜。
多后端，按角色分工
Codex App Server 与 Claude Agent SDK 同构。你可以让探索走一个后端、执行走另一个，每个 Project 还能单独覆盖。
控制台
需求清单、时间线、Plan 抽屉与 Run 详情在同一个工作区里。下面是界面示意，数据为示例。
Pipeline Factory v4
API 正常
PF
demo-api
需求清单
01
把健康检查改成并发安全
Plan v2 已确认 · factory/20261019-health-check
执行中
02
给上传接口补限流
结构化 Plan 完整 · 等待确认
待确认
03
回放一次失败的 Run
Run 已取消 · 保留完整事件流
已取消
开始使用
发布物自带安装脚本和 pipeline 命令。安装完成后，配置与数据都留在本机。
前置条件
- Node.js ≥ 22.5（使用
node:sqlite） - Git ≥ 2.38（冲突预测需要
git merge-tree） - Codex CLI 或 Claude Code 之一，并已登录
-
下载发布物
从 GitHub Releases 取对应平台的
pipeline-factory-<version>.tar.gz。 -
安装
安装到
~/.pipeline-factory，并把pipeline链接到~/.local/bin。 -
改配置
至少确认
project.root、storage和model；重复安装不会覆盖已有配置。 -
启动
打开
http://127.0.0.1:4310/。首次启动会初始化 SQLite 与运行时目录。
安装包不包含 Claude Agent SDK。使用 Claude 后端时，按安装文档把 SDK 装进安装目录，或配置
model.claudeAgent.sdkPath；Codex 后端不受影响。
zsh — pipeline-factory
# 1. 解压发布物
tar -xzf pipeline-factory-0.2.0.tar.gz
cd pipeline-factory-0.2.0
# 2. 安装（保留已有 config/ 与 var/）
./install.sh
# 3. 确认受管项目与模型后端
$EDITOR ~/.pipeline-factory/config/pipeline-factory.config.json
# 4. 启动
pipeline start
# → http://127.0.0.1:4310/日常命令
一个 pipeline 命令管理启动、日志与升级；数据与日志都在安装目录的 var/ 下。
| 命令 | 作用 |
|---|---|
pipeline start | 后台启动；PID 与日志在 ~/.pipeline-factory/var/ |
pipeline status | 查看版本、PID 与健康检查结果 |
pipeline logs -f | 跟随 var/pipeline.log |
pipeline stop | 停止服务 |
pipeline restart | 重启服务 |
pipeline update | 从 GitHub Releases 升级到最新发布物 |
pipeline update --file <tar.gz> | 从本地发布物升级 |
排障
先看 pipeline status，再看 pipeline logs -f。大部分问题在这两步里就能定位。
启动后页面打不开，或提示端口被占用？
先运行 pipeline status 确认实例是否已在运行。出现 EADDRINUSE 127.0.0.1:4310
通常表示 API 已经启动，不要重复启动同一实例。页面是旧界面时，确认发布物已升级，然后硬刷新浏览器。
出现 CLAUDE_AGENT_SDK_UNAVAILABLE？
只有使用 Claude 后端时才会出现。把 SDK 装进安装目录的 app/，或在配置里用
model.claudeAgent.sdkPath 指向 SDK 入口文件。使用 Codex 后端不受影响。
出现 SCHEMA_TOO_NEW？
旧程序打开了新版本创建的数据库。运行 pipeline update 升级发布物，不要降级程序版本。
结构版本由 SQLite 的 PRAGMA user_version 自动对齐。
能把服务暴露到局域网或公网吗？
默认只监听回环地址。把 server.host 改成非回环地址时，必须同时配置
server.authToken，否则服务拒绝启动。API 的能力等同于本机 shell、文件系统与 Git，
请先读安装文档里的安全边界，再决定是否对外暴露。
数据在哪里？怎么备份？
运行时数据都在安装目录的 var/ 下：SQLite 数据库、对话图片附件和 Run 的 Git Worktree。
先 pipeline stop，再复制整个 config/ 与 var/。
模型 API Key 存在 Pipeline Factory 里吗？
不存。Factory 不读取也不保存 API Key；Codex 与 Claude 的登录态、端点和凭据由各自的 CLI 管理。