核心用法
Soulforge 是一个基于守护进程的工作流引擎，通过 YAML 定义将编码任务分派给 Claude Code CLI 或 Codex CLI 执行，并在关键节点暂停等待人工审查。用户通过 soulforge run <workflow> "<task>" --workdir /path/to/project 启动工作流，内置 feature-dev（功能开发）和 bugfix（缺陷修复）两种预设流程，覆盖从规划、实现、验证到 PR 提交的完整软件开发生命周期。
显著优点
1. 后台自动化：守护进程模式允许任务在后台持续运行，用户可并行处理其他工作
2. 人机协作审查：通过 executor: self 步骤在关键环节（如代码审查门控）暂停，由人工决策后继续或回退
3. Git 工作树隔离：自动创建工作树（worktree）避免污染主分支，支持裸仓库和标准 .git 布局
4. 灵活的执行器切换：支持在 Codex CLI 和 Claude Code 之间动态切换，并可指定模型（如 gpt-5.3-codex、opus）
5. 结构化输出支持：通过 output_schema 定义步骤输出格式，配合 soulforge complete 命令实现可靠的数据传递
潜在缺点与局限性
1. 单守护进程限制：建议每台机器仅运行一个守护进程实例，多实例可能导致数据库冲突
2. 任务描述敏感性：缺乏约束的任务描述易导致计划膨胀（10-12 个 stories），需显式指定文件路径、最大 story 数量及排除项
3. 取消残留风险：取消运行可能遗留孤儿步骤，需显式执行 soulforge cancel 或重启守护进程清理
4. 依赖外部 CLI：要求预先安装并配置 codex/claude、gh CLI，且目标仓库需包含 AGENTS.md 文件以支持构建/测试发现
5. 审查门控复杂度：代码审查 → 门控 → 修复的循环逻辑由调用代理（agent）而非人工执行，需理解门控路由逻辑
适合人群
- 需要自动化端到端功能开发或缺陷修复流程的软件开发团队
- 希望在后台运行编码任务同时保持人工审查控制点的技术负责人
- 已采用 Claude Code 或 Codex CLI 作为主力开发工具，寻求工作流编排能力的开发者
- 需要标准化 PR 提交流程、代码审查门控和分支管理的开源维护者
常规风险
- 凭证泄露风险：虽然 Soulforge 本身不管理 API 密钥，但执行器 CLI 的凭证配置不当可能导致令牌泄露；
--callback-exec参数注入恶意命令可导致任意代码执行 - 工作树污染：
--keep-worktree选项保留工作树文件，可能在磁盘上遗留敏感代码副本 - 无限循环风险：审查门控的修复循环最多执行 5 次，但配置错误可能导致资源浪费
- 守护进程挂起：超过 5 分钟无轮询即判定为"可能挂起"，需监控
soulforge daemon status输出 - 模型行为不确定性：底层 LLM 可能生成不符合预期的代码，结构化输出验证虽能降低但仍需人工最终确认