Subagent Spawn Command Builder

核心用法

subagent-spawn-command-builder 是一个 Node.js 构建工具，用于将 JSON 配置模板转换为可直接使用的 sessions_spawn 命令载荷。它不执行实际的子代理启动，仅生成标准化的 JSON 输出，便于在自动化流水线、测试脚本或编排系统中复用。

关键流程

1. 配置准备：复制模板文件 spawn-profiles.template.json 到 spawn-profiles.json 并编辑自定义配置集（profile）
2. 载荷生成：通过 CLI 指定 profile 和 task，输出完整的 sessions_spawn JSON
3. 参数继承：遵循三层优先级——CLI 选项 > Profile 值 > Defaults 值，task 必须始终通过 CLI 提供

显著优点

• 配置可复用：通过 profile 机制避免重复定义 model、thinking、timeout 等参数
• 声明式管理：JSON 配置便于版本控制和团队协作
• 非侵入式：仅生成载荷不执行，降低误操作风险，适合 CI/CD 集成
• 灵活覆盖：CLI 参数可动态覆盖 profile 配置，适应临时调整需求

潜在局限

• 执行依赖：需外部调用 sessions_spawn 实际生效，增加了编排复杂度
• Node.js 环境：.mjs 脚本要求 Node.js 运行时，Python 任务需显式使用 python3
• 无内置验证：不校验生成的 JSON 是否满足目标系统的 schema 要求
• 模板维护：profile 模板需手动同步更新，可能产生配置漂移

适合人群

• 需要批量生成子代理配置的自动化工程师
• 构建复杂多步骤工作流的系统架构师
• 追求配置即代码（Configuration as Code）的DevOps 团队
• 需要隔离"配置生成"与"执行"阶段的安全敏感场景

常规风险

• 配置泄露：spawn-profiles.json 可能包含敏感参数（如 agentId），需妥善管理文件权限
• 版本不匹配：builder 脚本与目标系统的 sessions_spawn API 变更可能不同步
• 超时误配：runTimeoutSeconds 继承不当可能导致任务被意外终止
• CLI 注入：--task 内容若来自不可信输入，需防范命令注入（尽管仅生成 JSON）

典型场景

适合需要动态组合多个子代理、进行 A/B 测试不同模型配置、或在预生产环境验证配置 before production deployment 的场景。