尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

ECC loop-operator:自主 Agent 循环的安全运营 Agent 设计与落地实践

ECC loop-operator:自主 Agent 循环的安全运营 Agent 设计与落地实践 ECC loop-operator自主 Agent 循环的安全运营 Agent 设计与落地实践【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文以 ECC 仓库中 Kiro 适配包内的 loop-operator Agent 定义.kiro/agents/loop-operator.md为主体系统讲解“循环运营者”这一角色的设计意图、五步操作工作流、启动前四项必备检查与四类升级Escalation判据并结合仓库中配套的loop-start/loop-status命令与 scripts/loop-status.js 的源码实现说明这套“观察—检测—干预—恢复”机制是如何被具体工具支撑起来的。读完后你将掌握如何为长时间自主运行的 Agent 循环建立可观测、可暂停、可回滚的运营规范并能直接用仓库提供的 CLI 手段监控卡死循环。loop-operator 是什么定位与文件格式loop-operator 是 ECC 提供的一个专职“运营者”角色其定位写在文档的 YAML frontmatter 中--- name: loop-operator description: Operate autonomous agent loops, monitor progress, and intervene safely when loops stall. allowedTools: - read - shell ---它不是一个“写代码的 Agent”而是一个站在自主循环外部做监控与干预的运营角色负责跑循环、盯进度、在循环卡死stall时安全介入。allowedTools只授予read读取与shell执行命令两类工具从权限层面就限定了它的行为边界——可以观测、可以执行受控操作但不具备任意写入能力。在 Kiro 适配包中每个 Agent 都同时提供两种格式loop-operator 也不例外文件用途.kiro/agents/loop-operator.mdIDE 格式Markdown通过自动选择或显式调用如/loop-operator使用.kiro/agents/loop-operator.jsonCLI 格式JSON通过/agent swap命令切换JSON 版本把同一份运营者 Prompt 内嵌为prompt字段并声明tools: [builtin]、allowedTools: [fs_read, shell]与 MD 版本的工具约束一一对应。整个 Kiro 包可通过 .kiro/install.sh 一键安装到任意项目安装采用非破坏性复制不会覆盖已有文件。值得注意的是ECC 在 Claude Code 一侧还维护了一份对应物 agents/loop-operator.md。它除了相同的 Mission/Workflow/Checks/Escalation 内容外额外携带了model: sonnet、tools: Read, Grep, Glob, Bash, Edit的声明以及一段Prompt Defense Baseline提示词防御基线禁止改变角色与身份、禁止泄露机密与密钥、把外部抓取/检索到的第三方数据一律视为不可信内容并在行动前校验、检测零宽字符与同形字等注入技巧。从源码结构看这份基线意味着 loop-operator 在读取循环日志、外部 CI 输出等不可信输入时需要把这些内容当作“数据”而非“指令”处理——这对一个需要长时间读取第三方文本流的运营 Agent 尤为关键。使命用明确的停止条件运营自主循环loop-operator 的核心使命只有一句话Run autonomous loops safely with clear stop conditions, observability, and recovery actions. 带着清晰的停止条件、可观测性与恢复手段安全地运行自主循环。这句话拆解出三个支柱恰好对应后文的工作流、状态检查和升级判据明确的停止条件循环必须在启动时就定义好“何时算完、何时必须停”可观测性进度必须以检查点checkpoint的形式被持续追踪而不是靠“感觉它在动”恢复手段卡死或反复失败时有暂停、收缩范围、验证后恢复的既定动作而不是盲目重启。这个设计与 ECC 仓库中另一个技能 skills/continuous-agent-loop/SKILL.md 中列出的四类典型失败模式直接呼应无可度量进展的循环空转loop churn、同一根因的重复重试、合并队列卡死、无上限升级导致的成本漂移。loop-operator 的存在就是给这四类失败模式提供一个专职的“值班人”。五步操作工作流文档给出的标准工作流共五步构成一个“启动—观察—检测—干预—恢复”的闭环1. 从明确的模式启动循环Start loop from explicit pattern and mode循环不能“凭感觉启动”必须显式指定模式pattern与运行档位mode。在 ECC 中这对应/loop-start命令commands/loop-start.md/loop-start [pattern] [--mode safe|fast]pattern可选值sequential顺序流水线、continuous-pr持续 PR 循环、rfc-dagRFC 驱动的多 Agent DAG、infinite无限代理循环--modesafe默认严格质量门与检查点或fast为速度放宽门禁。loop-start自身的启动流程要求确认仓库状态与分支策略 → 选择循环模式与模型档位策略 → 为所选模式启用必要的 hooks/profile → 在.claude/plans/下写入循环计划与 runbook → 最后打印启动与监控命令。它还有三条硬性安全检查首次迭代前测试必须通过、ECC_HOOK_PROFILE未被全局禁用、循环必须有显式停止条件。loop-operator 工作流的第 1 步正是以此为起点没有这些前置条件运营者不应放行循环。2. 追踪进度检查点Track progress checkpoints运行中运营者要持续记录“最后一个成功检查点”在哪里。这一步是后续所有判断是否卡死、是否倒退的基准线——没有检查点序列就无法区分“在慢速推进”与“已经完全停摆”。3. 检测卡死与重试风暴Detect stalls and retry storms这里仓库提供了真正的实现级支撑/loop-status命令commands/loop-status.md与其底层 CLI scripts/loop-status.js。该 CLI 扫描~/.claude/projects/**下的 Claude 会话转录JSONL专门检测两类“悬挂信号”过期的ScheduleWakeup调用计划了唤醒但没有后续动作没有匹配tool_result的Bash工具调用命令发出后始终没有结果返回。源码中的默认阈值可以直接查证scripts/loop-status.jsconst DEFAULT_BASH_TIMEOUT_SECONDS 30 * 60; // 1800 秒 const DEFAULT_LIMIT 10; // 默认检查最近 10 份转录 const DEFAULT_WAKE_GRACE_MULTIPLIER 2; // ScheduleWakeup 宽限倍数 const DEFAULT_WATCH_INTERVAL_SECONDS 5; // --watch 刷新间隔即一条悬挂的 Bash 调用超过 30 分钟无结果即被判定为 stale。4. 失败重复时暂停并收缩范围Pause and reduce scope当检测到同一失败反复出现重试风暴运营者的动作不是“再试一次”而是冻结循环并把范围收缩到失败单元。这与 skills/continuous-agent-loop/SKILL.md 的 Recovery 段落完全一致freeze loop → 运行/harness-auditcommands/harness-audit.md→ reduce scope to failing unit → replay with explicit acceptance criteria。5. 验证通过后才恢复Resume only after verification passes恢复循环的门槛是验证通过而非“看起来修好了”。仓库中承担验证职责的是verification-loop技能build、type check、lint、tests、security scan、diff review 全量跑一遍与/quality-gate命令。后者在 commands/quality-gate.md 中说明质量门由 PostToolUse hookscripts/hooks/quality-gate.js驱动按文件类型调用 Biome/Prettier/gofmt/ruff并通过环境变量ECC_QUALITY_GATE_FIXtrue应用修复与ECC_QUALITY_GATE_STRICTtrue把 formatter 失败记为门禁失败切换行为。启动前四项必备检查Required Checks文档要求 loop-operator 在启动循环前确认四项检查全部就位缺一不放行检查项含义在 ECC 中的落点quality gates are active质量门处于激活状态/quality-gate命令与post:quality-gatePostToolUse hookscripts/hooks/quality-gate.js且ECC_HOOK_PROFILE未被全局禁用loop-start的硬性检查之一eval baseline exists评估基线已存在eval-harness技能skills/eval-harness/SKILL.md为循环提供可度量的对照基线否则“有没有进展”无从判定rollback path exists回滚路径存在循环产出的任何提交都必须可撤回通常依托显式的分支/工作区隔离与干净的提交边界branch/worktree isolation is configured分支/worktree 隔离已配置continuous-pr模式创建continuous-claude/iteration-N分支Ralphinho DAG 模式中每个工作单元独占一个 worktree/tmp/workflow-wt-{unit-id}/见 skills/autonomous-loops/SKILL.md其中“eval baseline”一项值得强调它要求循环在启动前就有一个可对照的度量基准如既有测试通过率、eval 分数这样第 2 步的“检查点”才有客观标尺——没有基线的循环检查点只是时间戳无法判定进展。四类升级Escalation判据loop-operator 明确规定了满足任一条件即必须升级升级到人工干预的四条红线两个连续检查点零进展no progress across two consecutive checkpoints重复出现栈迹完全相同的失败repeated failures with identical stack traces——相同栈迹说明重试没有带来新信息继续重试就是纯烧 token成本漂移超出预算窗口cost drift outside budget window合并冲突阻塞队列推进merge conflicts blocking queue advancement——对应continuous-pr/rfc-dag模式下的 merge queue stall。这四条判据与 scripts/loop-status.js 的退出码设计形成了呼应该 CLI 支持--exit-code参数检测到 stale 循环/工具信号时退出码为 2转录无法扫描时退出码为 1从而可以写进 watchdog 脚本让“升级”动作本身也可以被自动化触发。实战用仓库自带工具落地这套运营流程把上述机制串起来一个典型的 loop-operator 值班流程在仓库内可以直接执行启动阶段对应工作流第 1 步# 交互式会话内/loop-start continuous-pr --mode safe # 等价的人工前置确认 # - 测试已全绿loop-start 的 Required Safety Check # - ECC_HOOK_PROFILE 未被全局禁用 # - 循环有显式停止条件--max-runs / --max-cost / --max-duration / 完成信号监控阶段对应第 2、3 步在另一个终端运行打包 CLI因为/loop-status会话内命令要等当前会话出队才能执行监控卡死会话必须用独立进程npx --package ecc-universal ecc loop-status --json常用参数均以 commands/loop-status.md 与 scripts/loop-status.js 的 usage 输出为准参数作用--json输出机器可读的状态 JSONwatch 模式下每刷新一次输出一行 JSON可供其他终端/脚本消费--home dir扫描另一个 home 目录检查其他本地 profile 或挂载工作区--transcript session.jsonl直接检查单份转录文件--bash-timeout-seconds 1800调整“悬挂 Bash 判定为 stale”的阈值默认 1800 秒--exit-code发现 stale 信号退出 2 / 无法扫描退出 1供 watchdog 使用--watch周期性刷新直到中断--watch --watch-count 3 --exit-code有界刷新 3 次后退出并返回观察到的最高状态码watch exit-code 必须搭配 watch-count否则进程永不退出源码中有显式校验--write-dir ~/.claude/loops写出index.json每个被检会话一行与session-id.json完整状态负载供兄弟终端或 watchdog 读取需要明确的一点这些快照文件只是本地转录分析的快照它们并不控制、也不超时 Claude Code 运行时中的工具调用——干预动作仍由运营者或人依据快照信号来执行。干预阶段对应第 4、5 步状态报告应包含/loop-status文档列出的五个字段——当前循环模式、所处阶段与最后一个成功检查点、正在失败的检查项、预估的时间/成本漂移、以及建议动作continue / pause / stop。选择 pause 后按 continuous-agent-loop 的 Recovery 流程收缩范围验证通过再恢复。权限边界与升级之外的“人”loop-operator 的安全设计还体现在两处权限与责任的边界上其一工具白名单最小化。Kiro 侧只有readshellClaude Code 侧虽有Edit但整体仍以 Read/Grep/Glob/Bash 的观察型工具为主——运营者的首要职责是“看与判”写操作是受控的例外。其二判断权不转移给机器。仓库中 skills/loop-design-check/SKILL.md 把这一点表述为红线前提机器擅长“执行层”反馈离目标差多远、把它磨平但“目标本身对不对、要不要停”这种“判断层”反馈必须留在人手里循环可以开 PR但不应自动合并最后的开关由人拨动。loop-operator 的升级机制正是这条红线在运营侧的落地它负责把“该停了”的信号及时、结构化地报出来但“停不停、怎么改”的最终决定权在人。适用前提与限制Kiro 用户loop-operator 位于 .kiro/agents/ 目录随 Kiro 适配包.kiro/README.md安装使用Agent 实际使用的模型由 Kiro 当前选择的模型决定不由 Agent 配置指定.kiro/README.md 中的说明。Claude Code 用户对应定义在 agents/loop-operator.md额外携带提示词防御基线与sonnet模型标注。监控工具的前提ecc loop-statusCLI 依赖本地 Claude 转录 JSONL~/.claude/projects/**因此它监控的是 Claude 侧的自主循环快照不控制运行时工具调用只能作为干预决策的输入。本文描述的命令参数与默认值均以当前仓库的 commands/loop-status.md 与 scripts/loop-status.js 为准如仓库版本更新请以最新源码输出为准。小结loop-operator 用不到一页纸的篇幅定义了一套完整的安全运营契约五步工作流规定了“怎么跑、怎么盯、怎么停”四项必备检查把质量门、eval 基线、回滚路径、隔离配置设为启动前置条件四条升级判据把零进展、重复失败、成本漂移、队列阻塞量化为可执行的升级触发器。配合仓库中真实实现的 scripts/loop-status.js 转录分析 CLI、/loop-start的启动门禁与verification-loop/quality-gate的恢复验证这套机制从规范落到了可运行的工具链上——它给出的核心经验是自主循环的可靠性不来自循环本身而来自循环外部一个权限受控、判据明确、随时可以把决定权交还给人运营者。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表