核心用法
subagent-spawn-command-builder 是一个命令行工具，用于从预定义的 JSON 配置文件生成 sessions_spawn 的完整请求负载。它解决了在复杂多代理工作流中重复配置模型参数、超时设置和清理策略的问题。
典型工作流程：
1. 复制模板配置文件到活跃配置位置
2. 编辑 spawn-profiles.json 定义常用子代理画像（如轻量监控、深度分析、快速验证等）
3. 通过 CLI 指定画像名称和任务内容，生成可直接使用的 JSON 负载
关键特性：
- 三层参数优先级：CLI 选项 > 画像配置 > 默认配置，确保灵活性与一致性兼顾
task必须显式传入，避免意外执行未经验证的指令- 支持完整的
sessions_spawn参数集：model、thinking、runTimeoutSeconds、cleanup、agentId、label
显著优点
- 配置可复用：将常用参数组合固化为命名画像，避免重复输入
- 版本可控：配置文件采用 JSON 格式，便于版本管理和团队共享
- 非侵入式设计：仅生成负载不执行，允许在提交前审查或修改
- 审计友好：生成日志记录到
build-log.jsonl，支持追溯
潜在局限
- 无内置验证：不检查生成的参数组合是否被目标系统支持（如特定 model 可用性）
- 手动步骤较多：需要预先维护配置文件，对一次性任务而言配置成本可能高于收益
- Python 版本敏感：文档明确要求使用
python3而非python，在混用环境需注意 - 单画像限制：每次调用仅支持单一画像，复杂任务需多次调用或外部编排
适合人群
- 需要频繁启动同类子代理的开发者和自动化工程师
- 构建多步骤 AI 工作流、需要标准化子代理行为的团队
- 偏好"配置即代码"、希望将子代理参数纳入版本控制的 DevOps 实践者
常规风险
- 配置漂移：若活跃配置未纳入版本管理，本地修改可能导致行为不一致
- 凭据泄露：JSON 配置文件中若包含敏感信息（如 agentId 关联的密钥），需注意文件权限
- 误用风险：生成的 JSON 可直接用于 API 调用，若未经审查批量执行，可能因参数错误导致资源浪费或意外清理（cleanup: delete）
- 依赖项风险：
build_spawn_payload.py的执行环境需维护，脚本本身的完整性影响生成结果可靠性