forked from longtao.wu/droboticflow
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>
856 lines
37 KiB
Python
856 lines
37 KiB
Python
#!/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())
|