ruflo agent-ops-cicd-github 技能详解：用一份声明式规格定义 GitHub Actions CI/CD 工程师 Agent

ruflo（The original agent meta-harness）通过 .agents/skills/ 目录下的 SKILL.md 文件把"专家角色"沉淀为可被 Codex CLI 等 harness 加载的声明式技能。本文以 .agents/skills/agent-ops-cicd-github/SKILL.md 为主体，逐段拆解这份"cicd-engineer"技能的完整规格——从触发条件、工具白名单、文件沙箱到生命周期钩子与 CI/CD 工作流模板——并结合 config.toml、CLAUDE.md 与 pod-schema.ts 等仓库源码，说明该技能在 ruflo 体系中的注册与协作位置。读完本文，你可以掌握 ruflo 技能的双层 frontmatter 编写规范、Agent 能力预算与安全约束的声明方式，并得到一个可直接复用的 GitHub Actions 工作流基线模板。

一、技能在 ruflo 中的位置：.agents 目录与双层 frontmatter

按 .agents/README.md 的说明，.agents/ 目录是 "agent configuration and skills for OpenAI Codex CLI"，其标准结构为：config.toml 主控配置，skills/<skill-name>/SKILL.md 存放技能指令（可选附带 scripts/ 与 docs/），技能通过 $skill-name 语法调用。仓库中该目录下已有上百个同类技能（如 agent-swarm、github-automation、github-workflow-automation、security-audit 等），agent-ops-cicd-github 是其中专攻 CI/CD 的一个。

该 SKILL.md 采用双层 YAML frontmatter 结构，这也是理解其成文骨架的关键：

• 外层 frontmatter（L1–L4）：技能注册层，name: agent-ops-cicd-github，description 明确"invoke with $agent-ops-cicd-github"，即声明了 harness 的调用入口；
• 内层 frontmatter（L6–L121）：完整的 Agent 规格层，包含角色名、触发器、能力、约束、行为、集成关系、性能参数、生命周期钩子和调用示例。

这种分层让"harness 如何找到它"与"它是什么、能做什么、边界在哪"两件事解耦。

二、角色身份与元数据

内层 frontmatter 定义了 Agent 的身份字段（见 SKILL.md L7–L17）：

字段	取值	含义
name	cicd-engineer	角色名，后续在 ruflo 业务 Pod 等机制中以此名引用
description	Specialized agent for GitHub Actions CI/CD pipeline creation and optimization	一句话职责定位：创建与优化流水线
type	devops	角色类别
color	cyan	UI 展示色
version / created	1.0.0 / 2025-07-25	静态版本快照
autonomous	true	允许自主执行
specialization	GitHub Actions, workflow automation, deployment pipelines	专业领域
complexity	moderate	复杂度分级

三、触发系统：关键词、文件模式与任务模式

triggers 段（L18–L37）声明了四种激活信号。需要说明：原文文件用 $ 占位路径分隔符（如 .github$workflows、ci$cd），还原为标准写法如下：

• keywords：github actions、ci/cd、pipeline、workflow、deployment、continuous integration —— 用户语句命中这些词即可唤起；
• file_patterns：.github/workflows/*.yml、.github/workflows/*.yaml、**/action.yml、**/action.yaml —— 当操作对象是工作流文件或复合 Action 定义文件时，该技能与当前任务天然相关，这是"上下文感知"式的触发依据；
• task_patterns：create * pipeline、setup github actions、add * workflow —— 匹配典型任务句式；
• domains：devops、ci/cd —— 领域标签，供调度器归类。

从这份清单可以看出设计意图：让 harness 在用户"提到 CI"或"正在改 workflow 文件"两种情况下都能把任务路由给 cicd-engineer。

四、工具白名单与执行预算（capabilities）

capabilities 段（L38–L52）为该 Agent 划定了能力边界与资源预算：

配置项	取值	说明
allowed_tools	Read, Write, Edit, MultiEdit, Bash, Grep, Glob	文件读写、编辑、执行与检索全套本地工具
restricted_tools	WebSearch, Task	注释写明"Focused on pipeline creation"——禁止联网检索，也禁止再派生子任务，强制聚焦
max_file_operations	40	单次执行的文件操作上限
max_execution_time	300	执行时长预算（秒），与 .agents/config.toml 中 [performance] 段的 task_timeout = 300 相互呼应
memory_access	both	可读可写记忆

restricted_tools 把 Task（子任务委派）列入限制、can_spawn: [] 为空（见第七节），两处共同表达同一个约束：cicd-engineer 是一个"终端执行者"而非"协调者"，它的价值在于把流水线文件做对，而不是继续分裂任务。

五、文件系统沙箱（constraints）

constraints 段（L53–L70）是这份规格的安全核心，用"允许 + 禁止 + 体积 + 类型"四道闸门限定操作面：

constraints:
  allowed_paths:
    - ".github/**"
    - "scripts/**"
    - "*.yml"
    - "*.yaml"
    - "Dockerfile"
    - "docker-compose*.yml"
  forbidden_paths:
    - ".git/objects/**"
    - "node_modules/**"
    - "secrets/**"
  max_file_size: 1048576  # 1MB
  allowed_file_types:
    - ".yml"
    - ".yaml"
    - ".sh"
    - ".json"

允许面完全贴合 CI/CD 工程师的合理工作半径：.github/**（工作流与 Action 定义）、构建脚本、YAML 配置与容器编排文件；禁止面则封死 Git 内部对象、依赖目录和任何名为 secrets 的目录。这套思路与 .agents/config.toml 全局 [security] 段的策略一脉相承——后者同样声明了 secret_scanning = true、path_traversal_prevention = true，并用正则 blocked_patterns（\.env$、credentials\.json$、\.pem$、\.key$）全局拦截敏感文件。技能级沙箱相当于在全局安全策略之上再收了一圈。

六、行为策略与人工确认闸门（behavior / communication）

behavior 段（L71–L78）规定了失败与高危操作时的行为准则：

配置项	取值	解读
error_handling	strict	错误不容忍，直接暴露而非静默兜底
confirmation_required	production deployment workflows；secret management changes；permission modifications	三类高危变更必须先向人确认：生产部署工作流、密钥管理变更、权限修改
auto_rollback	true	失败时自动回滚
logging_level	debug	调试级日志，便于审计每次流水线改动

communication 段（L79–L83）则约束交互风格：style: technical（技术化表达）、update_frequency: batch（批量汇报而非逐条刷屏）、include_code_snippets: true（回复必须附带代码片段）、emoji_usage: minimal。

与第六节的"高危操作确认"叠加，requires_approval_from: security（见下节）构成了双闸门：既需要人确认，也需要 security 域角色审批——这正是该技能"生产流水线"安全立场的声明式表达。

七、多 Agent 协作拓扑（integration）

integration 段（L84–L93）描述了它在 ruflo 多 Agent 体系中的位置：

配置项	取值	含义
can_spawn	[]	不派生任何子 Agent
can_delegate_to	analyze-security、test-integration	遇到安全分析、集成测试问题时，可委派给对应专家
requires_approval_from	security	注释标注"For production pipelines"——生产流水线变更需 security 角色审批
shares_context_with	ops-deployment、ops-infrastructure	与部署、基础设施两个运维角色共享上下文，保证 CI 改动与部署环境信息对齐

仓库其他位置印证了 cicd-engineer 这个角色的真实使用场景：CLAUDE.md 将其列入角色名录（与 backend-dev、system-architect、api-docs 等并列）；v3/@claude-flow/cli/src/business-pods/pod-schema.ts 的合法角色列表中包含 'cicd-engineer'；plugins/ruflo-business-pods/templates/ops.json 运维业务 Pod 模板与 v3/mcp/tools/agent-tools.ts 的 Agent 工具实现中也引用了该角色名。可以推断：在 ruflo 的 business pod 模型里，cicd-engineer 是运维域 Pod 的默认成员之一，而非孤立技能。

八、性能优化参数（optimization）

optimization 段（L94–L98）给出执行期调优参数：

optimization:
  parallel_operations: true   # 允许并行操作
  batch_size: 5               # 批量大小
  cache_results: true         # 缓存结果
  memory_limit: "256MB"       # 技能级内存预算

对照 .agents/config.toml 的全局 [performance] 段（max_agents = 8、parallel_execution = true、cache_enabled = true、cache_ttl = 3600、memory_limit = "512MB"），从源码结构看，技能级的 256MB 预算比全局默认值更保守，属于"该角色自我加压"的声明；并行与缓存策略则与全局配置保持一致，说明技能参数是全局策略的细粒度覆盖而非另起炉灶。

九、生命周期钩子：项目自探测与产出校验

hooks 段（L99–L115）以 shell 脚本声明了执行前、执行后与出错时的行为（还原原文 $ 占位符后的逻辑）：

pre_execution —— 环境盘点与技术栈识别：

echo "🔧 GitHub CI/CD Pipeline Engineer starting..."
echo "📂 Checking existing workflows..."
find .github/workflows -name "*.yml" -o -name "*.yaml" 2>/dev/null | head -10 || echo "No workflows found"
echo "🔍 Analyzing project type..."
test -f package.json && echo "Node.js project detected"
test -f requirements.txt && echo "Python project detected"
test -f go.mod && echo "Go project detected"

设计意图很清晰：动手写工作流之前，先盘点仓库已有 workflow（避免重复或覆盖），再通过三个"指纹文件"（package.json / requirements.txt / go.mod）推断项目类型，为后续选择 setup-node、setup-python 或 Go 工具链 Action 提供依据。

post_execution —— 产出校验：遍历 .github/workflows 下所有 yml/yaml 文件并打印首行，作为"简易 YAML 校验"（注释中自述为 Simple YAML validation）；

on_error —— 标准化错误回执：

echo "❌ Pipeline configuration error: {{error_message}}"
echo "📝 Check GitHub Actions documentation for syntax"

{{error_message}} 是留给 harness 填充的模板占位符，体现了钩子脚本"声明式模板 + 运行时注入"的编写方式。

十、调用示例（examples）

frontmatter 末尾给出两组触发/响应样例（L116–L121），可视为该技能的"验收用例"：

1. 触发 create GitHub Actions CI/CD pipeline for Node.js app → 响应：创建覆盖 build、test、deployment 三阶段的综合工作流；
2. 触发 add automated testing workflow → 响应：创建在 pull request 上运行、含测试覆盖率报告的自动化测试工作流。

两条示例恰好覆盖"从零建流水线"与"增强测试"两种典型任务，且与 task_patterns 中的句式一致。

十一、正文：职责、最佳实践与工作流模板

frontmatter 之后的正文（L123–L169）是给 LLM 的提示词主体，共四块：

Key responsibilities（L127–L133）——五项核心职责：创建高效 GitHub Actions 工作流；实现 build/test/deploy 流水线；配置多环境测试的 job matrix；搭建缓存与 artifact 管理；落实安全最佳实践。

Best practices（L134–L141）——六条实践原则，逐条对应文档中的声明：

1. 用 composite action 实现工作流复用（workflow reusability）；
2. 实施正确的密钥管理（proper secret management）；
3. 最小化工作流执行时间；
4. 选用合适的 runner（如 ubuntu-latest）；
5. 实施分支保护规则（branch protection rules）；
6. 有效缓存依赖。

Workflow pattern（L143–L163）——文档给出的 Node.js CI 基线模板。原文以 $ 代替 Action 引用中的 /，还原为标准 GitHub Actions 语法如下，可复制到 github/workflows/ci.yml 作为起点：

name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
      - run: npm ci
      - run: npm test

该模板本身就示范了前文多项声明：cache: 'npm' 落实"有效缓存依赖"；npm ci 而非 npm install 保证可复现安装（对应"最小化执行时间"）；触发器区分 push（main/develop）与 pull_request（main），配合最佳实践第 5 条的分支保护形成常规防线；runs-on: ubuntu-latest 对应第 4 条。矩阵测试、composite action 复用等进阶项，正文以"实践原则"形式给出而非完整 YAML，属于刻意留白——留给 Agent 在具体项目中按职责第 3 条现场生成。

Security considerations（L165–L169）——安全基线四条：绝不硬编码密钥；GITHUB_TOKEN 使用最小权限；用 CODEOWNERS 管控工作流文件变更；使用 environment 保护规则。其中"CODEOWNERS 管控 workflow 变更"与第六节 confirmation_required 中的"permission modifications"互相咬合：机器侧强制人审，仓库侧强制指定 owner 批准，双保险。

十二、如何验证与延伸阅读

• 技能目录全貌：.agents/skills/ 下可对比上百个兄弟技能的双层 frontmatter 写法；与本技能直接相关的还有 github-workflow-automation、security-audit、hooks-automation；
• harness 配置：.agents/config.toml 中 [[skills.config]] 段（L83–L97）显式启用了 swarm-orchestration、memory-management、sparc-methodology、security-audit 四个技能；从源码结构看，agent-ops-cicd-github 未出现在该显式名单中，其调用更可能依赖 harness 对 skills/ 目录的扫描与 $agent-ops-cicd-github 语法，适用前提是所用 harness 支持目录扫描式技能发现；
• 角色注册链路：CLAUDE.md → pod-schema.ts → ops.json，展示了 cicd-engineer 从文档角色到 Pod Schema 合法取值再到运维 Pod 模板的完整落地链。

十三、适用性与限制

最后明确几点边界：这份 SKILL.md 是声明式提示词规格，本身不是可执行引擎——max_execution_time: 300、memory_limit: "256MB"、max_file_operations: 40 等是技能向 harness 申报的预算与约束，其实际强制力取决于加载方（Codex CLI / Claude Code 等）对这些字段的解析程度；钩子脚本假定 Linux/macOS 的 find/test 可用，on_error 的 {{error_message}} 需 harness 完成模板注入；version: 1.0.0（2025-07-25）是静态快照，角色在 business pod 中的行为还会受 pod-schema.ts 侧 Schema 约束共同限定。在 ruflo 仓库语境下，阅读该文件的最佳路径是：先按本文十一节的模板落地一条最小 CI 流水线，再对照第四、五、六节理解"一个受限、可审计、需人审的 CI/CD 专家 Agent"应当声明哪些边界——这正是 agent-ops-cicd-github 技能给开发者留下的最大参考价值。