核心用法
Soulforge 是一款守护进程驱动的工作流引擎，专为自动化端到端软件开发而设计。用户通过 YAML 定义多步骤编码流程，由后台守护进程调度至 Claude Code CLI 或 Codex CLI 执行，并在关键节点暂停等待人工审核。
典型使用场景：
1. 端到端功能开发：从需求规划→实现→验证→自动提PR
2. 后台委托编码：启动任务后解放终端做其他工作
3. 需人工审核的开发流程：代码审查、质量门禁等检查点
4. 自动化分支管理：功能分支创建、实现、PR提交一体化
关键命令：
soulforge run <workflow> "<task>" --workdir <path>：启动工作流（--workdir 为必需参数）soulforge status/complete/cancel/resume：运行状态管理与检查点完成soulforge daemon start/stop：守护进程管理
内置工作流：
feature-dev：完整功能开发（含故事拆解、循环实现、多轮审核）bugfix：精准Bug修复（先写失败测试、诊断、修复、验证）
执行器覆盖：支持 --executor claude-code/codex-cli 和 --model opus/gpt-5.3-codex 等参数切换底层AI编码工具。
显著优点
1. 真正的后台自动化：守护进程架构允许任务在后台持续运行，用户可断开终端或切换上下文
2. 结构化检查点机制：type: pause 步骤配合 soulforge complete 实现精确的人工介入控制
3. Git工作树自动管理：自动创建隔离的工作目录，避免污染主分支，支持裸库和标准布局
4. 灵活的回调通知：支持 OpenClaw 集成，可将步骤状态路由至 Slack 等渠道
5. 执行器无关设计：可切换 Claude Code 与 Codex CLI，模型选择灵活
6. 结构化输出验证：支持 JSON Schema 定义的步骤输出，自动验证
潜在局限与风险
1. 单守护进程限制：同一机器多实例会导致数据库冲突，需手动清理孤儿进程
2. 任务描述敏感性：缺乏约束时计划易膨胀至10-12个故事，需极其具体的提示词工程
3. 取消操作副作用：cancel 可能导致步骤孤儿化，需重启守护进程清理
4. 依赖外部CLI生态：必须预装并认证 claude/codex + gh CLI， credential 链条较长
5. AGENTS.md 隐式依赖：feature-dev 工作流依赖目标仓库包含 AGENTS.md 文件进行构建/测试发现
6. 检查点责任归属：gate 检查点的分流决策由调用方（AI agent）而非真实人类执行，存在误判风险
适合人群
- 需要批量处理功能开发的技术负责人或高级开发者
- 希望异步化编码工作流的多任务处理者
- 已深度使用 Claude Code 或 Codex CLI 的AI辅助开发早期采用者
- 拥有标准化代码审查流程的工程团队
- 熟悉 Git 工作树、YAML 配置和命令行工具的运维向开发者
常规风险
- 工作目录误操作：
--workdir指向非Git仓库时直接在原目录工作，可能产生意外文件变更 - 模型成本失控：长循环工作流（如 gate-fix 最多5轮）可能累积大量token消耗
- PR自动化风险：自动创建的PR缺乏人工预审，可能提交未完成或不符合团队规范的代码
- 守护进程挂起：
daemon status显示 ">5min since last poll" 时需主动重启，否则运行状态不可靠