ops-assistant/docs/module-adapter-template.md

Module Adapter Template

目标：新功能模块以最小改动接入 ops-assistant。

必备文件

• internal/module/<name>/module.go
• runbooks/<name>_*.yaml

推荐实现

1. 在 module.go 内解析命令前缀（如 /cf）
2. 构建 core/module.Request
3. 统一调用 core/module.Runner.Run(...)
4. 所有 gate（flag/confirm/dry-run）通过 Request.Gate 声明

最小示例（伪代码）

req := coremodule.Request{
  RunbookName: "cf_dns_upsert",
  Inputs: map[string]string{"zone": zone, "name": name},
  Meta: runbook.RunMeta{Target:"cf", RiskLevel:"medium"},
  Gate: coremodule.Gate{NeedFlag:"allow_cf_write", RequireConfirm:true, ExpectedToken:"YES_CF", AllowDryRun:true},
  DryRun: dryRun,
  ConfirmToken: confirm,
}
jobID, out, err := runner.Run(cmd.Raw, userID, req)

接入检查

• 命令不直接执行 shell/ssh
• 使用统一 Runner
• 风险操作有 Gate
• 返回 job_id 可追踪
• runbook step 可审计