droboticflow/scripts/generate_ops_catalog.py
eust-w 7fa8ca0547 ✨ Add ops capability catalog with droctl CLI and Claude Code skill
One declarative catalog (ops/catalog/*.yaml) now describes every deploy,
acceptance, release, diagnose and platform action with typed args, tier-based
role mapping, preflight checks and honest per-surface availability.
scripts/generate_ops_catalog.py validates it and generates the Go catalog,
the Claude Code skill and slash commands, the product's TypeScript catalog
and docs/ops-catalog.md (--check is part of verify:local).

droctl runs any action with argument validation, preflights (branch, cluster
reachability via load-deploy-env.sh), confirm/admin gates and real dry-run
only where a script supports it. The Claude skill drives droctl so both share
one execution path.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-11-04 11:28:17 +08:00

856 lines
37 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

#!/usr/bin/env python3
"""Generate the three ops entry points (droctl, Claude Code, product assistant) from ops/catalog/*.yaml."""
from __future__ import annotations
import argparse
import json
import pathlib
import re
import sys
import yaml
ROOT = pathlib.Path(__file__).resolve().parents[1]
CATALOG_DIR = ROOT / "ops" / "catalog"
PACKAGE_JSON = ROOT / "package.json"
GO_OUTPUT = ROOT / "internal" / "opscatalog" / "catalog_generated.go"
TS_OUTPUT = ROOT / "src" / "lib" / "ops-catalog.generated.ts"
DOC_OUTPUT = ROOT / "docs" / "ops-catalog.md"
SKILL_DIR = ROOT / ".claude" / "skills" / "droflow-ops"
COMMANDS_DIR = ROOT / ".claude" / "commands"
GENERATED_NOTICE = "Code generated by scripts/generate_ops_catalog.py; DO NOT EDIT."
TIERS = ["read", "operate", "release", "admin"]
TIER_ROLES = {
"read": ["admin", "pipeline_engineer", "data_operator", "qa_reviewer", "compliance_auditor"],
"operate": ["admin", "pipeline_engineer", "data_operator"],
"release": ["admin", "pipeline_engineer"],
"admin": ["admin"],
}
TIER_LABELS = {"read": "只读", "operate": "操作", "release": "发布", "admin": "管理"}
ROLES = TIER_ROLES["read"]
SURFACES = ["cli", "claude", "product"]
ARG_TYPES = ["string", "bool", "int", "enum", "list"]
MAPPING_KINDS = {"positional", "flag", "env", "path", "query", "body"}
SCRIPT_MAPPINGS = {"positional", "flag", "env"}
HTTP_MAPPINGS = {"path", "query", "body"}
PREFLIGHT_KINDS = {"git-branch": "expect", "env": "name", "file": "path", "command": "command", "kube-reachable": None}
EXECUTION_KINDS = {"script", "npm", "http", "composite"}
HTTP_METHODS = {"GET", "POST", "PUT", "DELETE"}
INTERPRETERS = {".sh": ["bash"], ".py": ["python3"], ".mjs": ["node"], ".js": ["node"]}
ACTION_KEYS = {
"id", "title", "summary", "tier", "roles", "mutates", "confirm", "surfaces", "surface_note",
"args", "preflight", "execution", "evidence", "runbook", "failure_modes",
}
ARG_KEYS = {"name", "type", "values", "default", "required", "summary", "maps_to"}
EXECUTION_KEYS = {
"kind", "script", "interpreter", "fixed_args", "npm_script", "method", "path", "steps",
"dry_run_env", "apply_flag", "timeout_seconds",
}
ID_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*\.[a-z0-9]+(?:-[a-z0-9]+)*$")
NAME_PATTERN = re.compile(r"^[a-z][a-z0-9_]*$")
ENV_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
FLAG_PATTERN = re.compile(r"^--[a-z0-9][a-z0-9-]*$")
# Slash commands are thin wrappers over catalog domains for the Claude Code entry point.
CLAUDE_COMMANDS = {
"droflow-status": ("查看 droboticflow 平台、集群与验收门的当前状态", "status"),
"droflow-diagnose": ("按常见故障模式做只读诊断", "diagnose"),
"droflow-deploy": ("构建、部署、滚动重启或清理 POC 环境", "poc"),
"droflow-accept": ("跑 POC / drosync 验收链路", "accept"),
"droflow-release": ("drosync 与内置算子的发版", "drosync,operators"),
"droflow-platform": ("项目、工作流、运行与审核的日常操作", "platform"),
"droflow-verify": ("提交前的 lint、测试与构建校验", "verify"),
}
class CatalogError(Exception):
pass
def fail(where: str, message: str) -> None:
raise CatalogError(f"{where}: {message}")
def require_keys(where: str, value: dict, allowed: set[str], required: set[str]) -> None:
if not isinstance(value, dict):
fail(where, "must be a mapping")
unknown = set(value) - allowed
if unknown:
fail(where, f"unknown keys {sorted(unknown)}")
missing = required - set(value)
if missing:
fail(where, f"missing keys {sorted(missing)}")
def require_text(where: str, value, limit: int = 240) -> str:
if not isinstance(value, str) or not value.strip():
fail(where, "must be a non-empty string")
if len(value) > limit:
fail(where, f"must be at most {limit} characters")
return value.strip()
def github_anchor(heading: str) -> str:
slug = heading.strip().lower()
slug = re.sub(r"[^\w\- ]", "", slug)
return slug.replace(" ", "-")
def doc_anchors(path: pathlib.Path) -> set[str]:
anchors: set[str] = set()
in_fence = False
for line in path.read_text(encoding="utf-8").splitlines():
if line.startswith("```"):
in_fence = not in_fence
continue
match = re.match(r"^#{1,6}\s+(.*)$", line)
if match and not in_fence:
anchors.add(github_anchor(match.group(1)))
return anchors
def check_doc_reference(where: str, reference: str) -> None:
path_part, _, anchor = reference.partition("#")
path = ROOT / path_part
if not path_part.startswith("docs/") or not path.is_file():
fail(where, f"{reference!r} must point to an existing file under docs/")
if anchor and anchor not in doc_anchors(path):
fail(where, f"{reference!r}: heading anchor #{anchor} does not exist")
def normalize_arg(where: str, raw: dict, execution_kind: str) -> dict:
require_keys(where, raw, ARG_KEYS, {"name", "type", "summary", "maps_to"})
name = raw["name"]
if not isinstance(name, str) or not NAME_PATTERN.match(name):
fail(where, f"name {name!r} must match {NAME_PATTERN.pattern}")
arg_type = raw["type"]
if arg_type not in ARG_TYPES:
fail(where, f"type must be one of {ARG_TYPES}")
values = raw.get("values") or []
if arg_type == "enum":
if not values or not all(isinstance(item, str) and item for item in values):
fail(where, "enum args need a non-empty list of string values")
elif values:
fail(where, "values is only valid for enum args")
has_default = "default" in raw
default = "" if not has_default else str(raw["default"])
if has_default:
if arg_type == "enum" and default not in values:
fail(where, f"default {default!r} is not one of {values}")
if arg_type == "bool" and default not in {"true", "false"}:
fail(where, "bool defaults must be the strings 'true' or 'false'")
if arg_type == "int" and not re.fullmatch(r"-?\d+", default):
fail(where, "int defaults must be integers")
required = bool(raw.get("required", False))
if required and has_default:
fail(where, "an arg with a default cannot be required")
mapping = raw["maps_to"]
if not isinstance(mapping, dict) or mapping.get("kind") not in MAPPING_KINDS:
fail(where, f"maps_to.kind must be one of {sorted(MAPPING_KINDS)}")
kind = mapping["kind"]
allowed = HTTP_MAPPINGS if execution_kind == "http" else SCRIPT_MAPPINGS
if kind not in allowed:
fail(where, f"maps_to.kind {kind!r} is not valid for {execution_kind} actions (use {sorted(allowed)})")
normalized_mapping = {"kind": kind, "index": 0, "flag": "", "name": ""}
if kind == "positional":
index = mapping.get("index")
if not isinstance(index, int) or index < 0:
fail(where, "positional mappings need a non-negative integer index")
normalized_mapping["index"] = index
elif kind == "flag":
flag = mapping.get("flag", "")
if not FLAG_PATTERN.match(str(flag)):
fail(where, f"flag {flag!r} must match {FLAG_PATTERN.pattern}")
normalized_mapping["flag"] = flag
elif kind == "env":
env_name = mapping.get("name", "")
if not ENV_PATTERN.match(str(env_name)):
fail(where, f"env name {env_name!r} must match {ENV_PATTERN.pattern}")
normalized_mapping["name"] = env_name
else:
target = mapping.get("name", "")
if not isinstance(target, str) or not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", target):
fail(where, f"{kind} mapping needs a parameter name")
normalized_mapping["name"] = target
if arg_type == "list" and kind not in {"flag", "env"}:
fail(where, "list args can only map to a repeated flag or a comma-joined env var")
return {
"name": name,
"type": arg_type,
"summary": require_text(f"{where}.summary", raw["summary"]),
"values": list(values),
"default": default,
"has_default": has_default,
"required": required,
"maps_to": normalized_mapping,
}
def normalize_execution(where: str, raw: dict, npm_scripts: dict) -> dict:
require_keys(where, raw, EXECUTION_KEYS, {"kind"})
kind = raw["kind"]
if kind not in EXECUTION_KINDS:
fail(where, f"kind must be one of {sorted(EXECUTION_KINDS)}")
execution = {
"kind": kind, "script": "", "interpreter": [], "fixed_args": [], "npm_script": "",
"method": "", "path": "", "steps": [], "dry_run_env": "", "apply_flag": "",
"timeout_seconds": int(raw.get("timeout_seconds", 0) or 0),
}
allowed_by_kind = {
"script": {"kind", "script", "interpreter", "fixed_args", "dry_run_env", "apply_flag", "timeout_seconds"},
"npm": {"kind", "npm_script", "timeout_seconds"},
"http": {"kind", "method", "path"},
"composite": {"kind", "steps"},
}
extra = set(raw) - allowed_by_kind[kind]
if extra:
fail(where, f"keys {sorted(extra)} are not valid for {kind} executions")
if kind in {"script", "npm"} and execution["timeout_seconds"] <= 0:
fail(where, "timeout_seconds must be a positive integer")
if kind == "script":
script = require_text(f"{where}.script", raw.get("script"))
path = ROOT / script
if not path.is_file():
fail(where, f"script {script} does not exist")
interpreter = raw.get("interpreter") or INTERPRETERS.get(path.suffix)
if not interpreter:
fail(where, f"no interpreter known for {script}; set interpreter explicitly")
execution["script"] = script
execution["interpreter"] = [str(item) for item in interpreter]
execution["fixed_args"] = [str(item) for item in raw.get("fixed_args", [])]
dry_run_env = raw.get("dry_run_env", "")
if dry_run_env and not ENV_PATTERN.match(dry_run_env):
fail(where, f"dry_run_env {dry_run_env!r} must match {ENV_PATTERN.pattern}")
apply_flag = raw.get("apply_flag", "")
if apply_flag and not FLAG_PATTERN.match(apply_flag):
fail(where, f"apply_flag {apply_flag!r} must match {FLAG_PATTERN.pattern}")
if dry_run_env and apply_flag:
fail(where, "use either dry_run_env or apply_flag, not both")
execution["dry_run_env"] = dry_run_env
execution["apply_flag"] = apply_flag
elif kind == "npm":
npm_script = require_text(f"{where}.npm_script", raw.get("npm_script"))
if npm_script not in npm_scripts:
fail(where, f"npm script {npm_script!r} is not defined in package.json")
execution["npm_script"] = npm_script
elif kind == "http":
method = raw.get("method")
if method not in HTTP_METHODS:
fail(where, f"method must be one of {sorted(HTTP_METHODS)}")
path = require_text(f"{where}.path", raw.get("path"))
if not re.fullmatch(r"/(?:api|worker-api)/[A-Za-z0-9/_{}.-]*", path):
fail(where, f"path {path!r} must be an /api or /worker-api route")
execution["method"] = method
execution["path"] = path
else:
steps = raw.get("steps")
if not isinstance(steps, list) or len(steps) < 2:
fail(where, "composite executions need at least two steps")
execution["steps"] = [str(step) for step in steps]
return execution
def normalize_action(where: str, raw: dict, domain: str, npm_scripts: dict) -> dict:
require_keys(where, raw, ACTION_KEYS, {"id", "title", "summary", "tier", "mutates", "surfaces", "execution"})
action_id = raw["id"]
if not isinstance(action_id, str) or not ID_PATTERN.match(action_id):
fail(where, f"id {action_id!r} must match {ID_PATTERN.pattern}")
if not action_id.startswith(domain + "."):
fail(where, f"id {action_id!r} must start with '{domain}.'")
where = f"{where}({action_id})"
tier = raw["tier"]
if tier not in TIERS:
fail(where, f"tier must be one of {TIERS}")
roles = raw.get("roles") or []
for role in roles:
if role not in ROLES:
fail(where, f"unknown role {role!r}")
if not isinstance(raw["mutates"], bool):
fail(where, "mutates must be a boolean")
confirm = raw.get("confirm", raw["mutates"])
if not isinstance(confirm, bool):
fail(where, "confirm must be a boolean")
surfaces = raw["surfaces"]
if not isinstance(surfaces, list) or not surfaces or any(item not in SURFACES for item in surfaces):
fail(where, f"surfaces must be a non-empty subset of {SURFACES}")
if len(set(surfaces)) != len(surfaces):
fail(where, "surfaces must not repeat")
surface_note = raw.get("surface_note", "")
if "product" not in surfaces and not surface_note:
fail(where, "actions unavailable in the product need a surface_note explaining why")
execution = normalize_execution(f"{where}.execution", raw["execution"], npm_scripts)
args = [normalize_arg(f"{where}.args[{index}]", item, execution["kind"]) for index, item in enumerate(raw.get("args") or [])]
names = [arg["name"] for arg in args]
if len(set(names)) != len(names):
fail(where, "arg names must be unique")
if execution["kind"] in {"npm", "composite"} and args:
fail(where, f"{execution['kind']} actions take no args")
positions = sorted(arg["maps_to"]["index"] for arg in args if arg["maps_to"]["kind"] == "positional")
if positions != list(range(len(positions))):
fail(where, "positional indexes must be contiguous from 0")
if execution["kind"] == "http":
placeholders = set(re.findall(r"\{([A-Za-z][A-Za-z0-9_]*)\}", execution["path"]))
path_args = {arg["maps_to"]["name"] for arg in args if arg["maps_to"]["kind"] == "path"}
if placeholders != path_args:
fail(where, f"path placeholders {sorted(placeholders)} must match path args {sorted(path_args)}")
for arg in args:
if arg["maps_to"]["kind"] == "path" and not arg["required"]:
fail(where, f"path arg {arg['name']} must be required")
if execution["method"] == "GET" and any(arg["maps_to"]["kind"] == "body" for arg in args):
fail(where, "GET actions cannot take body args")
if execution["method"] == "GET" and raw["mutates"]:
fail(where, "GET actions cannot be mutating")
preflight = []
for index, item in enumerate(raw.get("preflight") or []):
check_where = f"{where}.preflight[{index}]"
if not isinstance(item, dict) or item.get("kind") not in PREFLIGHT_KINDS:
fail(check_where, f"kind must be one of {sorted(PREFLIGHT_KINDS)}")
kind = item["kind"]
parameter = PREFLIGHT_KINDS[kind]
allowed = {"id", "kind"} | ({parameter} if parameter else {"env_arg"})
require_keys(check_where, item, allowed, {"id", "kind"} | ({parameter} if parameter else set()))
check = {"id": require_text(f"{check_where}.id", item["id"], 60), "kind": kind, "expect": "", "name": "", "path": "", "command": "", "env_arg": ""}
if parameter:
check[parameter] = require_text(f"{check_where}.{parameter}", item[parameter])
else:
env_arg = item.get("env_arg", "")
if env_arg and env_arg not in names:
fail(check_where, f"env_arg {env_arg!r} is not an arg of this action")
check["env_arg"] = env_arg
preflight.append(check)
evidence = [require_text(f"{where}.evidence", item) for item in raw.get("evidence") or []]
runbook = raw.get("runbook", "")
if runbook:
check_doc_reference(f"{where}.runbook", runbook)
failure_modes = []
for item in raw.get("failure_modes") or []:
check_doc_reference(f"{where}.failure_modes", item)
failure_modes.append(item)
return {
"id": action_id,
"domain": domain,
"title": require_text(f"{where}.title", raw["title"], 40),
"summary": require_text(f"{where}.summary", raw["summary"]),
"tier": tier,
"roles": list(roles),
"mutates": raw["mutates"],
"confirm": confirm,
"surfaces": list(surfaces),
"surface_note": surface_note,
"args": args,
"preflight": preflight,
"execution": execution,
"evidence": evidence,
"runbook": runbook,
"failure_modes": failure_modes,
}
def effective_roles(action: dict) -> list[str]:
return action["roles"] or TIER_ROLES[action["tier"]]
def validate_composites(actions: dict[str, dict]) -> None:
def visit(action_id: str, trail: list[str]) -> None:
if action_id in trail:
fail(trail[0], f"composite cycle {' -> '.join(trail + [action_id])}")
action = actions[action_id]
for step in action["execution"]["steps"]:
if step not in actions:
fail(action_id, f"composite step {step!r} does not exist")
visit(step, trail + [action_id])
for action_id, action in actions.items():
if action["execution"]["kind"] != "composite":
continue
visit(action_id, [])
for step_id in action["execution"]["steps"]:
step = actions[step_id]
if TIERS.index(step["tier"]) > TIERS.index(action["tier"]):
fail(action_id, f"tier {action['tier']} is lower than step {step_id} ({step['tier']})")
if not set(effective_roles(action)) <= set(effective_roles(step)):
fail(action_id, f"roles must be a subset of step {step_id}'s roles")
if not set(action["surfaces"]) <= set(step["surfaces"]):
fail(action_id, f"surfaces must be a subset of step {step_id}'s surfaces")
if step["mutates"] and not action["mutates"]:
fail(action_id, f"step {step_id} mutates, so the composite must too")
if step["confirm"] and not action["confirm"]:
fail(action_id, f"step {step_id} requires confirmation, so the composite must too")
def load_catalog() -> tuple[list[dict], list[dict]]:
npm_scripts = json.loads(PACKAGE_JSON.read_text(encoding="utf-8")).get("scripts", {})
domains: list[dict] = []
actions: dict[str, dict] = {}
files = sorted(CATALOG_DIR.glob("*.yaml"))
if not files:
raise CatalogError(f"no catalog files under {CATALOG_DIR.relative_to(ROOT)}")
for path in files:
where = str(path.relative_to(ROOT))
raw = yaml.safe_load(path.read_text(encoding="utf-8"))
require_keys(where, raw, {"domain", "title", "summary", "surface_note", "actions"}, {"domain", "title", "summary", "actions"})
domain = raw["domain"]
if domain != path.stem:
fail(where, f"domain {domain!r} must match the file name")
domains.append({"id": domain, "title": require_text(f"{where}.title", raw["title"], 40), "summary": require_text(f"{where}.summary", raw["summary"])})
if not isinstance(raw["actions"], list) or not raw["actions"]:
fail(where, "actions must be a non-empty list")
for index, item in enumerate(raw["actions"]):
if isinstance(item, dict) and "product" not in (item.get("surfaces") or []) and raw.get("surface_note"):
item.setdefault("surface_note", raw["surface_note"])
action = normalize_action(f"{where}.actions[{index}]", item, domain, npm_scripts)
if action["id"] in actions:
fail(where, f"duplicate action id {action['id']}")
actions[action["id"]] = action
validate_composites(actions)
return domains, list(actions.values())
# --- Go -------------------------------------------------------------------------------------------
def go_string(value: str) -> str:
return json.dumps(value, ensure_ascii=False)
def go_strings(values: list[str]) -> str:
return "[]string{" + ", ".join(go_string(item) for item in values) + "}"
def go_struct(type_name: str, fields: list[tuple[str, str]], indent: str) -> str:
inner = indent + "\t"
body = "".join(f"{inner}{name}: {value},\n" for name, value in fields)
return f"{type_name}{{\n{body}{indent}}}"
GO_SURFACES = {"cli": "SurfaceCLI", "claude": "SurfaceClaude", "product": "SurfaceProduct"}
GO_TIERS = {"read": "TierRead", "operate": "TierOperate", "release": "TierRelease", "admin": "TierAdmin"}
GO_ROLES = {
"admin": "domain.UserRoleAdmin",
"pipeline_engineer": "domain.UserRolePipelineEngineer",
"data_operator": "domain.UserRoleDataOperator",
"qa_reviewer": "domain.UserRoleQAReviewer",
"compliance_auditor": "domain.UserRoleComplianceAuditor",
}
def go_arg(arg: dict, indent: str) -> str:
mapping = arg["maps_to"]
mapping_fields = [("Kind", go_string(mapping["kind"]))]
if mapping["kind"] == "positional":
mapping_fields.append(("Index", str(mapping["index"])))
if mapping["flag"]:
mapping_fields.append(("Flag", go_string(mapping["flag"])))
if mapping["name"]:
mapping_fields.append(("Name", go_string(mapping["name"])))
fields = [("Name", go_string(arg["name"])), ("Type", go_string(arg["type"])), ("Summary", go_string(arg["summary"]))]
if arg["values"]:
fields.append(("Values", go_strings(arg["values"])))
if arg["has_default"]:
fields += [("Default", go_string(arg["default"])), ("HasDefault", "true")]
if arg["required"]:
fields.append(("Required", "true"))
fields.append(("MapsTo", "ArgMapping{" + ", ".join(f"{name}: {value}" for name, value in mapping_fields) + "}"))
return go_struct("", fields, indent)
def go_preflight(check: dict) -> str:
fields = [("ID", go_string(check["id"])), ("Kind", go_string(check["kind"]))]
for key, name in (("expect", "Expect"), ("name", "Name"), ("path", "Path"), ("command", "Command"), ("env_arg", "EnvArg")):
if check[key]:
fields.append((name, go_string(check[key])))
return "{" + ", ".join(f"{name}: {value}" for name, value in fields) + "}"
def go_execution(execution: dict, indent: str) -> str:
fields = [("Kind", go_string(execution["kind"]))]
for key, name in (("script", "Script"), ("npm_script", "NPMScript"), ("method", "Method"), ("path", "Path"), ("dry_run_env", "DryRunEnv"), ("apply_flag", "ApplyFlag")):
if execution[key]:
fields.append((name, go_string(execution[key])))
for key, name in (("interpreter", "Interpreter"), ("fixed_args", "FixedArgs"), ("steps", "Steps")):
if execution[key]:
fields.append((name, go_strings(execution[key])))
if execution["timeout_seconds"]:
fields.append(("TimeoutSeconds", str(execution["timeout_seconds"])))
return go_struct("Execution", fields, indent)
def go_action(action: dict) -> str:
indent = "\t"
inner = "\t\t"
fields = [
("ID", go_string(action["id"])),
("Domain", go_string(action["domain"])),
("Title", go_string(action["title"])),
("Summary", go_string(action["summary"])),
("Tier", GO_TIERS[action["tier"]]),
]
if action["roles"]:
fields.append(("Roles", "[]domain.UserRole{" + ", ".join(GO_ROLES[role] for role in action["roles"]) + "}"))
fields += [
("Mutates", "true" if action["mutates"] else "false"),
("Confirm", "true" if action["confirm"] else "false"),
("Surfaces", "[]Surface{" + ", ".join(GO_SURFACES[item] for item in action["surfaces"]) + "}"),
]
if action["surface_note"]:
fields.append(("SurfaceNote", go_string(action["surface_note"])))
if action["args"]:
rendered = "".join(f"{inner}\t{go_arg(arg, inner + chr(9))},\n" for arg in action["args"])
fields.append(("Args", f"[]Arg{{\n{rendered}{inner}}}"))
if action["preflight"]:
rendered = "".join(f"{inner}\t{go_preflight(check)},\n" for check in action["preflight"])
fields.append(("Preflight", f"[]Preflight{{\n{rendered}{inner}}}"))
fields.append(("Execution", go_execution(action["execution"], inner)))
if action["evidence"]:
fields.append(("Evidence", go_strings(action["evidence"])))
if action["runbook"]:
fields.append(("Runbook", go_string(action["runbook"])))
if action["failure_modes"]:
fields.append(("FailureModes", go_strings(action["failure_modes"])))
return go_struct("", fields, indent)
def generate_go(domains: list[dict], actions: list[dict]) -> str:
uses_roles = any(action["roles"] for action in actions)
imports = '\nimport "droboticflow/internal/domain"\n' if uses_roles else ""
domain_lines = "".join(
f"\t{{ID: {go_string(item['id'])}, Title: {go_string(item['title'])}, Summary: {go_string(item['summary'])}}},\n"
for item in domains
)
action_lines = "".join(f"\t{go_action(action)},\n" for action in actions)
return (
f"// {GENERATED_NOTICE}\n\npackage opscatalog\n{imports}\n"
f"var generatedDomains = []Domain{{\n{domain_lines}}}\n\n"
f"var generatedActions = []Action{{\n{action_lines}}}\n"
)
# --- TypeScript -----------------------------------------------------------------------------------
def ts_action(action: dict) -> dict:
return {
"id": action["id"],
"domain": action["domain"],
"title": action["title"],
"summary": action["summary"],
"tier": action["tier"],
"roles": effective_roles(action),
"mutates": action["mutates"],
"confirm": action["confirm"],
"surfaces": action["surfaces"],
**({"surfaceNote": action["surface_note"]} if action["surface_note"] else {}),
"args": [
{
"name": arg["name"],
"type": arg["type"],
"summary": arg["summary"],
**({"values": arg["values"]} if arg["values"] else {}),
**({"default": arg["default"]} if arg["has_default"] else {}),
"required": arg["required"],
}
for arg in action["args"]
],
"supportsDryRun": supports_dry_run(action),
**({"runbook": action["runbook"]} if action["runbook"] else {}),
}
def supports_dry_run(action: dict) -> bool:
execution = action["execution"]
if not action["mutates"]:
return True
if execution["kind"] == "script":
return bool(execution["dry_run_env"] or execution["apply_flag"])
return False
def generate_ts(domains: list[dict], actions: list[dict]) -> str:
domains_json = json.dumps(domains, ensure_ascii=False, indent=2)
actions_json = json.dumps([ts_action(action) for action in actions], ensure_ascii=False, indent=2)
return f"""// {GENERATED_NOTICE}
export type OpsTier = "read" | "operate" | "release" | "admin";
export type OpsSurface = "cli" | "claude" | "product";
export type OpsArgType = "string" | "bool" | "int" | "enum" | "list";
export interface OpsArg {{
name: string;
type: OpsArgType;
summary: string;
values?: string[];
default?: string;
required: boolean;
}}
export interface OpsAction {{
id: string;
domain: string;
title: string;
summary: string;
tier: OpsTier;
roles: string[];
mutates: boolean;
confirm: boolean;
surfaces: OpsSurface[];
surfaceNote?: string;
args: OpsArg[];
supportsDryRun: boolean;
runbook?: string;
}}
export interface OpsDomain {{
id: string;
title: string;
summary: string;
}}
export const OPS_TIER_LABELS: Record<OpsTier, string> = {json.dumps(TIER_LABELS, ensure_ascii=False)};
export const OPS_DOMAINS: OpsDomain[] = {domains_json};
export const OPS_ACTIONS: OpsAction[] = {actions_json};
"""
# --- Markdown (docs, Claude skill, slash commands) -------------------------------------------------
def droctl_usage(action: dict) -> str:
parts = ["droctl", "run", action["id"]]
for arg in action["args"]:
if arg["required"]:
parts.append(f"--arg {arg['name']}=<{arg['name']}>")
return " ".join(parts)
def arg_cell(action: dict) -> str:
if not action["args"]:
return "—"
rendered = []
for arg in action["args"]:
detail = arg["type"] if arg["type"] != "enum" else "/".join(arg["values"])
suffix = ",必填" if arg["required"] else (f",默认 {arg['default']}" if arg["has_default"] else "")
rendered.append(f"`{arg['name']}`({detail}{suffix})")
return "<br>".join(rendered)
def flags(action: dict) -> str:
marks = []
if action["mutates"]:
marks.append("变更")
if action["confirm"]:
marks.append("需确认")
if action["mutates"] and supports_dry_run(action):
marks.append("可 dry-run")
return "、".join(marks) or "只读"
def action_table(actions: list[dict], link_runbooks: str) -> str:
rows = ["| 动作 | 说明 | 权限 | 性质 | 参数 | 入口 |", "|---|---|---|---|---|---|"]
for action in actions:
surfaces = " ".join(action["surfaces"])
summary = action["summary"]
if action["runbook"]:
summary += f"([runbook]({link_runbooks}{action['runbook']}))"
if action["surface_note"]:
summary += f"<br>不在产品内:{action['surface_note']}"
roles = "、".join(effective_roles(action)) if action["roles"] else TIER_LABELS[action["tier"]]
rows.append(f"| `{action['id']}`<br>{action['title']} | {summary} | {roles} | {flags(action)} | {arg_cell(action)} | {surfaces} |")
return "\n".join(rows)
def tier_table() -> str:
rows = ["| tier | 含义 | 允许角色 |", "|---|---|---|"]
for tier in TIERS:
rows.append(f"| `{tier}` | {TIER_LABELS[tier]} | {'、'.join(TIER_ROLES[tier])} |")
return "\n".join(rows)
def generate_doc(domains: list[dict], actions: list[dict]) -> str:
sections = []
for item in domains:
domain_actions = [action for action in actions if action["domain"] == item["id"]]
sections.append(f"## {item['title']}(`{item['id']}`)\n\n{item['summary']}\n\n{action_table(domain_actions, '../')}\n")
return f"""<!-- {GENERATED_NOTICE} -->
# droboticflow 能力目录
droboticflow 的全部运维与平台动作。同一张目录同时驱动三个入口,定义在 `ops/catalog/*.yaml`,
字段说明见 [ops/README.md](../ops/README.md)。
| 入口 | 用法 |
|---|---|
| 仓库 CLI | `go run ./cmd/droctl list`、`droctl describe <动作>`、`droctl run <动作> --arg k=v [--dry-run] [--yes]` |
| Claude Code | `/droflow-status`、`/droflow-deploy` 等斜杠命令,或直接描述需求(技能 `droflow-ops` 会调用 droctl) |
| 产品内助手 | 左侧导航「运维助手」,输入 `/` 选动作,或用自然语言描述 |
## 权限分层
{tier_table()}
产品内助手按登录用户的角色过滤动作;集群内执行脚本类动作(经 ops-runner Job)另外只允许 `admin`。
变更类动作在产品内默认 dry-run,带「需确认」的动作必须再确认一次才会执行。
{chr(10).join(sections)}"""
def generate_skill(domains: list[dict], actions: list[dict]) -> str:
domain_lines = "\n".join(
f"- **{item['title']}**(`{item['id']}`):{item['summary']} → [references/{item['id']}.md](references/{item['id']}.md)"
for item in domains
if any("claude" in action["surfaces"] for action in actions if action["domain"] == item["id"])
)
return f"""---
name: droflow-ops
description: droboticflow 统一运维入口。部署/构建/滚动重启 POC、跑验收、故障诊断、drosync 与算子发版、项目/工作流/运行/审核操作、提交前校验时使用。所有动作都通过仓库里的 droctl 执行,不要自己拼脚本命令。
---
<!-- {GENERATED_NOTICE} -->
# droboticflow 运维入口
这个仓库的全部运维与平台动作都登记在能力目录 `ops/catalog/*.yaml` 里,并由 `droctl` 统一执行。
**始终通过 droctl 执行,不要直接调用 `scripts/` 下的脚本或 `npm run`**——droctl 会做前置检查
(分支、集群可达性、所需命令)、参数校验、dry-run 与确认闸门,和 CLI、产品内助手走同一条执行路径。
## 怎么用
```bash
go run ./cmd/droctl list # 全部动作(可加 --domain poc / --tier read)
go run ./cmd/droctl describe poc.rollout-restart
go run ./cmd/droctl run status.poc-readiness --surface claude --json
go run ./cmd/droctl run poc.cleanup-jobs --surface claude --dry-run
go run ./cmd/droctl run poc.cleanup-jobs --surface claude --yes
```
规则:
1. 先 `describe` 看清参数、tier、是否变更、runbook,再执行。
2. 变更类动作:能 dry-run 的先 `--dry-run` 跑一遍,把结果给用户看。
3. 标了「需确认」的动作(`confirm: true`)**必须先得到用户明确同意**,再加 `--yes` 执行;不要替用户确认。
4. `tier: admin` 的动作还需要 `DROCTL_ALLOW_ADMIN=1`,只在用户明确要求时设置。
5. 失败时读 `describe` 里的 runbook 与 failure_modes 对应文档段落,再按 `diagnose.symptom` 做只读诊断。
6. 先用只读动作确认现状,再动环境;结论要基于命令真实输出,不要推断成功。
7. 遵守 `AGENTS.md`:`poc` 分支只部署 POC 环境;发版前 drosync 版本号要 +1(`drosync.release` 已包含)。
平台类(`platform.*`、`status.*` 等 http 动作)需要 `DROBOTICFLOW_API_BASE_URL` 与
`DROBOTICFLOW_API_TOKEN`(或 `DROBOTICFLOW_ACCEPTANCE_EMAIL` / `DROBOTICFLOW_ACCEPTANCE_PASSWORD`)。
## 能力域
{domain_lines}
## 权限分层
{tier_table()}
"""
def generate_skill_reference(item: dict, actions: list[dict]) -> str:
domain_actions = [action for action in actions if action["domain"] == item["id"] and "claude" in action["surfaces"]]
details = []
for action in domain_actions:
lines = [f"### `{action['id']}` — {action['title']}", "", action["summary"], "", "```bash", f"go run ./cmd/{droctl_usage(action)} --surface claude", "```", ""]
if action["preflight"]:
lines.append("前置检查:" + "、".join(f"`{check['id']}`" for check in action["preflight"]))
lines.append("")
if action["execution"]["kind"] == "composite":
lines.append("步骤:" + " → ".join(f"`{step}`" for step in action["execution"]["steps"]))
lines.append("")
if action["runbook"]:
lines.append(f"Runbook:`{action['runbook']}`")
lines.append("")
details.append("\n".join(lines))
return f"""<!-- {GENERATED_NOTICE} -->
# {item['title']}(`{item['id']}`)
{item['summary']}
{action_table(domain_actions, '../../../../')}
{chr(10).join(details)}"""
def generate_command(name: str, description: str, domain_ids: str, domains: list[dict], actions: list[dict]) -> str:
wanted = domain_ids.split(",")
domain_actions = [action for action in actions if action["domain"] in wanted and "claude" in action["surfaces"]]
lines = "\n".join(f"- `{action['id']}`:{action['title']}——{action['summary']}({flags(action)})" for action in domain_actions)
return f"""---
description: {description}
argument-hint: "[要做什么,例如 {domain_actions[0]['title']}]"
---
<!-- {GENERATED_NOTICE} -->
使用 `droflow-ops` 技能处理这个请求:$ARGUMENTS
本命令覆盖的动作:
{lines}
先用 `go run ./cmd/droctl describe <动作>` 确认参数与 tier;变更类先 dry-run,需确认的动作先征得用户同意再加 `--yes`。
没有给出具体要求时,先跑本组的只读动作汇报现状。
"""
def render_outputs() -> dict[pathlib.Path, str]:
domains, actions = load_catalog()
outputs = {
GO_OUTPUT: generate_go(domains, actions),
TS_OUTPUT: generate_ts(domains, actions),
DOC_OUTPUT: generate_doc(domains, actions),
SKILL_DIR / "SKILL.md": generate_skill(domains, actions),
}
for item in domains:
if any("claude" in action["surfaces"] for action in actions if action["domain"] == item["id"]):
outputs[SKILL_DIR / "references" / f"{item['id']}.md"] = generate_skill_reference(item, actions)
for name, (description, domain_ids) in CLAUDE_COMMANDS.items():
outputs[COMMANDS_DIR / f"{name}.md"] = generate_command(name, description, domain_ids, domains, actions)
return outputs
def gofmt(content: str) -> str:
import subprocess
return subprocess.run(["gofmt"], input=content, text=True, capture_output=True, check=True).stdout
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
mode = parser.add_mutually_exclusive_group(required=True)
mode.add_argument("--write", action="store_true")
mode.add_argument("--check", action="store_true")
args = parser.parse_args()
try:
outputs = render_outputs()
except CatalogError as error:
print(f"ops catalog error: {error}", file=sys.stderr)
return 1
outputs[GO_OUTPUT] = gofmt(outputs[GO_OUTPUT])
stale_references = set()
if (SKILL_DIR / "references").is_dir():
stale_references = set((SKILL_DIR / "references").glob("*.md")) - set(outputs)
stale = sorted(str(path.relative_to(ROOT)) for path, content in outputs.items() if not path.is_file() or path.read_text(encoding="utf-8") != content)
stale += sorted(f"{path.relative_to(ROOT)} (no longer generated)" for path in stale_references)
if args.check:
if stale:
print("ops catalog outputs are stale; run npm run generate:ops-catalog:", file=sys.stderr)
for item in stale:
print(f" {item}", file=sys.stderr)
return 1
return 0
for path, content in outputs.items():
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(content, encoding="utf-8")
for path in stale_references:
path.unlink()
print(f"wrote {len(outputs)} ops catalog outputs")
return 0
if __name__ == "__main__":
raise SystemExit(main())