Opencode 循环工作流约束设计：为 CLI 优先的 AI Agent 配置绑定护栏（loop-constraints 实战指南）

Opencode 循环工作流约束设计为 CLI 优先的 AI Agent 配置绑定护栏loop-constraints 实战指南【免费下载链接】loop-engineeringPractical patterns, starters CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.项目地址: https://gitcode.com/gh_mirrors/lo/loop-engineering在 loop-engineering 仓库的 Opencode 示例中examples/opencode/constraints-example.md展示了如何为基于 CLI 的自动化循环工作流定义简单而有效的安全护栏guardrails。本文将以此文档为骨架结合仓库中的loop-constraints技能、默认约束模板与安全基线完整讲解如何在 Opencode 中落地一套每次运行前必读、运行中绝不违反的绑定约束体系帮助你掌控自动循环的边界、降低误操作风险并让新贡献者与共享仓库的协作变得可预测、可审计。一、约束的本质让循环可预测自动化循环loop放大的不仅是产出也包括错误。约束constraints是一组绑定规则binding rules——循环在任何场景下都不得违反的边界。examples/opencode/constraints-example.md开篇即点明其定位为 CLI 优先工作流定义简单护栏并与loop-init --tool opencode初始化命令配对使用初始化完成后可以针对项目定制生成的技能附加项目专属约束。它之所以有效是因为约束在循环运行之前就被注入到 Agent 上下文中而不是在运行中途才被想起。约束使自动化工作流可预测并显著降低意外或危险操作的发生概率——这一点对新贡献者和共享仓库尤其重要。二、最小示例一个带护栏的 loop-triage 技能原文档给出的最小示例只有三行目录结构却代表了 Opencode 中约束的典型载体——技能skillskills/ └── loop-triage/ └── SKILL.mdOpencode 会自动发现仓库根目录skills/下的技能文件因此约束规则被直接写进技能文件的## Constraints小节# Loop Triage ## Constraints - Read-only during the first week of onboarding. - Never force-push to any branch. - Only modify files directly related to the assigned issue. - Request confirmation before deleting or renaming files. - Do not expose secrets, tokens, or internal URLs.这五条规则覆盖了 L1报告模式阶段最常见的风险面读写边界只读、Git 操作边界禁止强推、修改范围边界只动与任务相关文件、破坏性操作边界删除/重命名需确认以及信息泄露边界不暴露密钥与内部 URL。它们全部使用平实的自然语言书写因为约束的消费方是 LLM Agent而不是编译器。与之配套的loop-triage技能本体见 starters/minimal-loop-opencode/skills/loop-triage/SKILL.md定义了技能的执行纪律输出 High-Priority Items、Watch Items、Noise/Ignore、State Updates 四个区块并要求Be brutally concise尽量简洁、triage 阶段绝不提出架构级改造——这些自身就是一种内置约束约束与技能互相强化。三、约束技能如何运作每次运行前的强制注入仅把规则写在技能里还不够还需要一个机制保证规则每次运行都被读到。仓库通过loop-constraints技能skills/loop-constraints/SKILL.md模板见 templates/SKILL.md.loop-constraints完成这一职责。该技能的核心身份是 Loop Constraints Enforcer约束执行者其强制流程如下从项目根目录读取loop-constraints.md将每一条规则加载进工作记忆检查loop-pause-all是否激活——若激活则立即退出对后续每一个动作应用这些规则。技能会在每次运行开始时输出一行确认信息给出生效规则数量Constraints loaded from loop-constraints.md: N rules active.如果loop-constraints.md不存在技能不会静默放行而是回退到 docs/safety.md 中的默认安全规则例如永不编辑.env、.env.*、auth/、payments/、secrets/、credentials/永不自动合并到 main永不禁用测试连续 3 次修复失败后升级上报。与其他技能的协作契约约束技能并非孤立运行它与循环中的其他技能存在明确的交互契约loop-triage约束可能覆盖 triage 的优先级例如不要 push意味着不要对 CI 修复采取行动minimal-fix约束限定可被修改的文件范围loop-verifier约束定义验证器必须检查的黑名单路径loop-budget约束可能施加比loop-budget.md更严格的预算策略。四、约束文件loop-constraints.md的结构与默认集约束规则的持久化载体是项目根目录的loop-constraints.md。examples/opencode/constraints.md明确技能在每次运行开始时读取该文件把 header 之下的每一行都视为绑定规则允许注释。仓库提供的默认模板 templates/loop-constraints.md 按主题分节是开箱即用的起始约束集分节默认规则Push Merge不 push 前先告知未经人工批准不自动合并到 main先建 draft PR 供审阅后再标记 readyPaths永不编辑.env、.env.*、auth/、payments/、secrets/、credentials/未经批准不编辑基础设施配置Code提出修复前必须运行测试永不为让 CI 变绿而禁用测试不做无关重构一次运行只修一个问题单项目最多 3 次修复尝试之后升级Communication行动前先告知未经批准不关闭 issue 或 PRBudgettoken 消耗达到日上限 80% 时切换为只报告模式loop-pause-all激活时立即退出模板末尾特别注明使用平实英语添加你自己的规则。循环逐字读取。——这意味着约束的语义完全由书写者负责Agent 不会主动猜你隐含的意图。新增规则的方式在 Opencode 中追加规则有两种途径方式一通过opencode run追加让循环自己写入# 追加一条规则循环先运行一次完成读取与持久化之后每次运行都会强制执行 opencode run \ Append this rule to loop-constraints.md verbatim: Dont push before telling me. Always run tests first.方式二直接编辑文件。任何规则修改都会在下一次循环运行时生效。五、把约束放在每次循环运行之前有了约束文件和技能之后关键操作是把约束注入到每次调度运行的最前面让它先于 triage 执行。examples/opencode/constraints.md给出了可复制的运行命令opencode run Run skills/loop-constraints/SKILL.md. Then run skills/loop-triage/SKILL.md. Update STATE.md. No auto-fix in week one.这条命令的含义是先运行约束技能读取loop-constraints.md并把规则烘焙进上下文再运行 triage最后更新状态文件且第一周不启用自动修复。由于 triage 与约束运行在同一个上下文中规则已经内嵌到 Agent 的上下文窗口triage 的任何决策都会被约束实时约束。六、自动脚手架与手动拷贝examples/opencode/constraints.md提供了两种落地方式。方式一使用 loop-init 自动生成npx cobusgreyling/loop-init . --pattern daily-triage --tool opencodeloop-init会将loop-constraints.md和skills/loop-constraints/SKILL.md复制到 opencode 期望的仓库根目录布局中。方式二手动拷贝无需初始化工具mkdir -p skills/loop-constraints cp templates/SKILL.md.loop-constraints skills/loop-constraints/SKILL.md cp templates/loop-constraints.md loop-constraints.md同时examples/opencode/README.md提示当前尚未提供loop-init --tool opencode的正式支持推荐直接复制 starters/minimal-loop-opencode/ 启动包或按上述片段在 30 秒内手动完成搭建。启动包中的权限控制参考starters/minimal-loop-opencode/opencode.json.example展示了如何在 opencode 层面对 agent 施加第二道约束——权限permission{ agent: { loop-triage: { mode: primary, prompt: Read AGENTS.md, LOOP.md, STATE.md, and skills/loop-triage/SKILL.md. Run report-only triage. Update STATE.md. Do not edit source code unless the human has explicitly enabled L2., permission: { bash: ask, edit: ask } }, verifier: { mode: subagent, prompt: Review the supplied diff or worktree summary against project rules, tests, and docs/safety.md. Do not edit files. Respond with APPROVE or REJECT and concise evidence., permission: { bash: ask, edit: deny } } } }注意 verifier 的edit权限被设置为deny——验证者只能审查、只能 APPROVE 或 REJECT不能改代码。这是约束在工具权限层的物化即使上下文注入失效权限系统仍会兜底拦截。starters/minimal-loop-opencode/AGENTS.md则把关键约束固化为 opencode 每次加载的项目级规则L1 只读模式起步triage 前先读STATE.md每次运行后更新STATE.md未经人工明确开启 L2 前不修改源码永不未经批准 push 或 merge禁止编辑.env、auth/、payments/等路径每次改代码必须使用独立 git worktree单项目最多 3 次修复尝试。 这构成了技能约束 项目规则 权限配置三层防护。七、安全基线约束背后的仓库级护栏约束不是孤立的灵感仓库在 docs/safety.md 中给出了系统化的安全基线可作为书写约束时的权威参考路径黑名单**/.env、**/.env.*、**/secrets/**、**/credentials/**、**/*_key*、**/*_secret*、**/.terraform/**、**/k8s/production/**、**/migrations/**、**/auth/**、**/payments/**、**/billing/**——循环未经人工批准永不自动编辑这些路径应编码进minimal-fix与实施类技能中自动合并策略默认不自动合并。即使对琐碎循环开放自动合并也只允许注释/文档错字、测试文件内的 lint 自动修复、import 排序、白名单docs/路径下的配置依赖版本升级、lockfile 变更、任何黑名单路径一律禁止人工门禁Human Gates安全、认证授权、支付账单、基础设施/Terraform/K8s 生产环境、依赖升级供应链风险、超过 N 个文件建议 N10的改动、同一事项第三次失败、token 预算超限申请——这些场景必须有人工介入Secrets 防护调度器 prompt 中绝不粘贴 API keytriage 技能应在写入状态前对 CI 日志脱敏状态文件经常被提交STATE.md中不得出现凭证。docs/safety.md还强调loop-sync每次运行都会将上述规则与gate.yaml交叉校验报告漂移但绝不自行改写任何一侧——哪边是正确的属于人工判断范畴。八、与其他工具链的约束写法对比约束的载体随工具而变化但核心契约一致每次循环运行开始前读取并强制执行loop-constraints.md。仓库提供了多套对照实现examples/claude-code/constraints.md通过/constraints rule命令追加规则技能安装在.claude/skills/loop-constraints/SKILL.mdexamples/cursor/constraints.mdCursor 无原生/constraints命令采用技能 always-on rules Automation prompt组合并可选在.cursor/rules/loop-constraints.mdc中镜像关键规则examples/codex/constraints.md直接在 Automation prompt 中声明运行约束技能后再 triageexamples/grok/constraints.md与 Claude Code 类似的/constraints追加方式。examples/opencode/constraints-example.md建议将本文方案与 Cursor 的编辑器优先工作流示例对照阅读——两者的差别本质上是CLI 优先与编辑器优先两种循环形态下约束载体的差异。九、约束的书写纪律examples/opencode/constraints.md在 Safety 一节给出了最关键的提醒也是整个约束体系的设计哲学Constraints arebinding. If a rule can be misinterpreted, rewrite it — the loop will not second-guess, the human will.约束是绑定的。如果某条规则可能被误解就重写它——循环不会二次揣测最终承担后果的是人类。这意味着约束作者必须假设 Agent 会逐字照办因此规则要尽量单义、具体、可判定例如永不强推分支优于推送时小心并覆盖读写范围、Git 操作、破坏性操作、信息泄露等风险维度。结合docs/safety.md的路径黑名单与人工门禁清单来编写约束可以让自动化循环既高效又有清晰的问责边界。十、参考资料索引examples/opencode/constraints-example.md — 本文骨架来源的最小护栏示例examples/opencode/constraints.md — Opencode 约束完整指南templates/loop-constraints.md — 默认约束集模板templates/SKILL.md.loop-constraints — 约束技能模板skills/loop-constraints/SKILL.md — 已安装的约束技能实现docs/safety.md — 路径黑名单、自动合并策略、人工门禁与 Secrets 防护starters/minimal-loop-opencode/ — 可克隆即用的最小 L1 triage 启动包含opencode.json.example、AGENTS.md、LOOP.mdexamples/cursor/constraints.md — 编辑器优先工作流的约束对照实现【免费下载链接】loop-engineeringPractical patterns, starters CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.项目地址: https://gitcode.com/gh_mirrors/lo/loop-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考