核心用法
Agent Swarm Orchestrator 是一套本地运行的多项目编码自动化工作流系统。用户通过 Obsidian 笔记创建任务（标记 status: ready），系统通过 cron 定时扫描自动派生编码代理。每个代理在独立 git worktree 中运行，使用 Claude Code CLI 执行开发任务，完成后触发 Codex 进行代码审查，根据严重程度分级处理（CRITICAL/HIGH 自动修复最多2次），最终推送至 GitLab 创建 MR 并等待合并。系统通过 check-agents.sh 后台监控任务状态，自动处理超时、合并检测和状态同步。
关键使用路径：
- 手动触发：
spawn-agent.sh <project> "<task>"直接创建任务 - Obsidian 驱动：在
~/Documents/Obsidian Vault/agent-swarm/创建带 frontmatter 的笔记，scan-obsidian.sh每15分钟自动处理 - 监控调试：
tmux attach -t agent-<id>实时查看，或 tail 日志文件 - 项目初始化：
new-project.sh一键配置 GitLab 仓库、registry 条目和 Obsidian 模板
显著优点
1. 端到端自动化：从需求输入（Obsidian）到代码合并（GitLab）全程无人值守，适合个人开发者批量管理多个 side project
2. 隔离与并发：每个任务独立 worktree + tmux 会话，互不干扰，支持并行开发
3. 分层审查机制：Claude 编码 + Codex 审查 + 分级响应策略，比单一 LLM 自我审查更可靠
4. Obsidian 原生集成：利用现有笔记工作流，无需切换工具，任务描述支持 Markdown 富格式
5. 状态机驱动：明确的任务生命周期（starting → running → reviewing → ready_to_merge → done），便于追踪和故障排查
潜在缺点与局限性
- 本地单点依赖：控制平面和 cron 均运行在本机，无分布式容错，机器重启或 tmux 异常可能导致状态不一致
- 审查质量不可控：Codex 审查标准依赖 OpenAI 模型能力，可能出现误报或漏报，需人工兜底
needs-manual-fix状态 - GitLab 锁定：MR 流程深度绑定 GitLab（
glabCLI），不支持 GitHub 或其他代码托管平台 - 环境泄露风险：脚本涉及 OAuth token（
~/.claude.json）、GitLab token 和 Telegram bot key，文件权限管理不当可导致凭证泄露 - 上下文窗口限制：
context.md需手动维护，大型项目可能超出 Claude/Codex 上下文限制 - 无回滚机制：自动修复失败转人工后，历史中间状态未保留，可能丢失调试信息
适合人群
- 同时维护 3-10 个中小型开源项目的独立开发者
- 已深度使用 Obsidian 作为知识管理中枢的技术用户
- 追求"异步编码"体验、愿用机器时间换取自己时间的效率优先者
- 熟悉 shell 脚本和 cron，具备基础 DevOps 调试能力的用户
不适合：团队协作场景（无权限管理）、对代码审查有合规审计要求的企业环境、以及期望零配置开箱即用的非技术用户。
常规风险
| 风险类型 | 具体表现 | 缓解建议 |
|---------|---------|---------|
| 凭证泄露 | `~/.claude.json`、`send-notifications.sh` 中的 token 明文存储 | 使用 `chmod 600` 限制权限，考虑迁移至 macOS keychain 或 secret 管理工具 |
| 代理失控 | Claude 在 `-p` 模式下执行危险操作（如 `rm -rf`） | 已配置 `skipDangerousModePermissionPrompt: true`，需确认项目目录已设置信任，建议增加 `--dangerous-skip-permissions` 的显式审计日志 |
| 审查绕过 | Codex 误判 CRITICAL 为 MEDIUM，合并带缺陷代码 | 强制 CRITICAL/HIGH 修复后二次审查，或增加人工 MR 审批环节 |
| 状态不一致 | cron 异常导致任务状态与实际 MR 状态脱节 | 定期运行 `check-agents.sh` 手动校验，或增加健康检查端点 |
| 成本失控 | 大量并发任务导致 Anthropic/OpenAI API 费用激增 | 监控 `tasks.json` 积压量，设置并发上限和月度预算告警 |