Skill: suda6632/agent-concurrency-controller (version 1.0.0)

# Agent Concurrency Controller > > OpenClaw Agent并发安全调度器 > 基于Claude Code三层架构模式（Tool→ToolUse→Task）实现 > > **核心原则**：默认Fail-Closed，串行队列，显式权限日志 ## 背景问题 原生OpenClaw spawn子Agent时： - 6个cron任务因**isolated session网络冲突**频繁失败 - 敏感操作（公众号发布、文件覆盖）无**权限审计** - 大结果直接回显导致**token爆炸** **根因**：Claude Code原生的Agent调度缺乏并发安全控制 ## 解决方案 ### 1. 三层调度模型 ``` ┌─────────────────────────────────────────┐ │ Layer 3: Task Queue (队列层) │ │ - 优先级排序 (priority: 1-10) │ │ - 依赖图拓扑排序 │ │ - 串行消费（默认） │ └─────────────────────────────────────────┘ ↓ 出队 ┌─────────────────────────────────────────┐ │ Layer 2: ToolUse Context (执行层) │ │ - 权限检查 (checkPermissions) │ │ - 并发安全检查 (isConcurrencySafe) │ │ - 超时熔断机制 │ └─────────────────────────────────────────┘ ↓ spawn ┌─────────────────────────────────────────┐ │ Layer 1: Agent Instance (实例层) │ │ - isolated session (默认) │ │ - main session (上下文连续任务) │ │ - subagent 生命周期管理 │ └─────────────────────────────────────────┘ ``` ### 2. Fail-Closed默认值 参考Claude Code原始设计： ```python TOOL_DEFAULTS = { isConcurrencySafe: () => False, # 默认串行 isReadOnly: () => False, # 默认会修改 isDestructive: () => False, # 默认不破坏 checkPermissions: () => ({ behavior: 'allow' }), } ``` **应用到OpenClaw**： - 所有spawn操作默认 `is_concurrency_safe=False` - 必须显式声明才能并行 - 资源冲突自动降级为串行 ### 3. 敏感操作分级 | Level | 说明 | 行为 | 示例 | |-------|------|------|------| | **normal** | 普通操作 | ALLOW + LOG | 查询、搜索 | | **sensitive** | 敏感操作 | ALLOW + LOG | 文件覆盖、配置修改 | | **critical** | 关键操作 | ASK + LOG | 公众号发布、付款、外发 | ### 4. Coordinator协调原则 参考Claude Code Coordinator原始设计，应用于cron调度： **原则1：永远先Synthesize** ``` 错误：子Agent直接回给用户 正确：子Agent结果 → 父Agent合成 → 统一输出 ``` **原则2：并行是默认策略（需显式安全标记）** ``` is_concurrency_safe=True 才能并发 否则串行队列 ``` **原则3：Worker结果 = 内部信号** ``` 不是对话伙伴，是状态机触发器 MAINTENANCE_REPORT 格式输出 ``` ## 使用方式 ### Python API ```python from agent_concurrency_controller import spawn_agent_safe, on_agent_complete # 安全spawn Agent（默认Fail-Closed） result = spawn_agent_safe( task="调研Claude Code架构", agent_type="researcher", runtime="subagent", priority=3, # 优先级（越小越高） is_concurrency_safe=False, # Fail-Closed（默认） sensitive_level="normal", # normal/sensitive/critical timeout_seconds=300 ) # result: QUEUED:researcher-20260403-151500 # or STARTED:researcher-20260403-151500 # 任务完成回调 on_agent_complete( task_id="researcher-20260403-151500", success=True, result={"output": "调研完成"} ) ``` ### Skill集成 在SKILL.md中声明： ```yaml whenToUse: | 需要spawn子Agent时先检查队列深度 避免并行isolated session导致网络冲突 permissions: - agent:spawn (带队列控制) - file:write (日志目录) - log:append ``` ## 日志审计 ### 并发日志 (`logs/agent-concurrency.log`) ```json {"timestamp": "2026-04-03T15:15:00", "task_id": "researcher-001", "status": "QUEUED", "queue_depth": 2} {"timestamp": "2026-04-03T15:16:30", "task_id": "researcher-001", "status": "START_FROM_QUEUE", "queue_depth": 1} {"timestamp": "2026-04-03T15:18:00", "task_id": "researcher-001", "status": "COMPLETED"} ``` ### 敏感操作日志 (`logs/sensitive-operations.log`) ```json {"timestamp": "2026-04-03T15:20:00", "task_id": "publisher-001", "sensitive_level": "critical", "decision": "ASK_USER_CONFIRMATION"} ``` ## 部署验证 验证队列功能： ```powershell python skills/agent-concurrency-controller/agent_concurrency_controller.py ``` 输出：`{'running': [], 'pending': [], 'queue_depth': 0}` ## 迁移检查清单 将旧cron任务迁移到安全调度器： - [ ] 识别所有 `sessions_spawn` 调用 - [ ] 添加 `is_concurrency_safe` 标记（默认False） - [ ] 设置 `sensitive_level`（外发=critical） - [ ] 添加 `on_agent_complete` 回调 - [ ] 验证日志输出 ## 关联文件 | 文件 | 作用 | |------|------| | `agent_concurrency_controller.py` | 核心控制器实现 | | `logs/agent-concurrency.log` | 队列执行日志 | | `logs/sensitive-operations.log` | 权限审计日志 | | `memory/agent-queue-state.json` | 队列状态持久化 | ## 参考 - Claude Code 架构：`memory/learnings/claude-code-architecture-2026-04-03.md` - Claude Code 源码：https://github.com/ultraworkers/claw-code-parity - 安全设计：https://clawhub.ai/1491007406/cc-insider ## 版本 - **v1.0.0** (2026-04-03): 初始实现，Fail-Closed并发控制+敏感权限日志


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)