eust-w d5da39f5c6 🔖 Prepare POC rendering build with API-only rollout
Bump the workspace build version to 1.1.10 per the release policy.
Add poc.api-image to pin only the API container by digest, with server
 dry-run, POC/repository guards and a resource-version precondition.
Preserve all other deployments, operator pins, ConfigMaps and Secrets.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-05 05:09:20 +08:00
..

ops — 统一运维入口的能力目录

这个目录是 droboticflow 全部运维/平台动作的唯一事实源。scripts/generate_ops_catalog.py 从这里生成三个入口(仓库 CLI droctl、Claude Code 技能、产品内对话助手)和人读的 docs/ops-catalog.md,所以动作定义只改这里,不要手改任何生成产物。

ops/catalog/<domain>.yaml  ──generate_ops_catalog.py──▶  internal/opscatalog/catalog_generated.go
                                                         .claude/skills/droflow-ops/
                                                         .claude/commands/droflow-*.md
                                                         src/lib/ops-catalog.generated.ts
                                                         docs/ops-catalog.md

校验与一致性:npm run generate:ops-catalog:check(已接入 npm run verify:local)。 生成器自带 schema 校验(字段、类型、引用的脚本 / npm script / 文档锚点 / 复合步骤),不依赖 jsonschema。

文件结构

每个 ops/catalog/<domain>.yaml 是一个域:

domain: poc
title: POC 环境
summary: POC 环境的构建、部署与数据收敛
surface_note: 可选;本域里不在产品内的动作默认用这句说明原因
actions:
  - id: poc.deploy
    ...

domain 必须和文件名一致;action.id 必须以 <domain>. 开头,全局唯一。

动作字段

字段 必填 说明
id 是 <domain>.<name>,小写字母、数字和 -
title 是 中文短标题(≤40 字),进斜杠菜单
summary 是 一句话说明它做什么
tier 是 read / operate / release / admin
roles 否 显式角色列表,覆盖 tier 的默认映射(如审核类动作给 qa_reviewer)
mutates 是 是否改变环境状态
confirm 否 默认 = mutates。为真时执行前必须显式确认
surfaces 是 cli / claude / product 的非空子集
surface_note 不含 product 时必填 为什么产品内不能跑
args 否 类型化参数,见下
preflight 否 执行前的机器检查,见下
execution 是 怎么执行,见下
evidence 否 产物路径,供入口提示去哪看证据
runbook 否 docs/...#anchor,生成器会校验标题锚点真实存在
failure_modes 否 docs/...#anchor 列表,失败时该读哪段

tier → 角色

映射到 internal/domain/types.go 已有的 UserRole,不新建权限模型:

tier 允许角色
read 全部角色
operate admin pipeline_engineer data_operator
release admin pipeline_engineer
admin admin

产品内助手在此之上还有两条:脚本类动作(在集群内的 ops-runner Job 里执行)只允许 admin; http 动作在进程内以当前用户身份分发,原有路由级角色校验与组织隔离照常生效。

surfaces

哪些入口可以执行这个动作。依赖本机工作树、钥匙串、Docker 或本地凭据的动作不要给 product, 并用 surface_note 写明原因——目录显式标明不可达,而不是让产品助手跑到一半才失败。 npm 类动作需要 node_modules,不能进 product(测试会拦)。

args

args:
  - name: env                    # [a-z][a-z0-9_]*,入口里用 --arg env=poc 传
    type: enum                   # string | bool | int | enum | list
    values: [poc, wjzh]          # 仅 enum,必填
    default: poc                 # 可选;bool/int 的默认值写成字符串
    required: false              # 有 default 时不得为 true
    summary: 部署环境
    maps_to: {kind: env, name: DEPLOY_ENV}

maps_to 按执行方式取值:

执行 kind 渲染
script positional + index 第 N 个位置参数(不得以 - 开头)
script flag + flag --flag=值;bool 为裸 flag;list 为重复的 --flag=项
script env + name 环境变量;list 用逗号连接
http path + name 替换路径里的 {name};值只能是 [A-Za-z0-9._:-]
http query + name 查询参数
http body + name JSON 请求体字段(按类型转成数字/布尔/数组)

参数永远渲染成 argv 元素、环境变量或结构化请求,永不拼进 shell 字符串。 产品侧能执行运维动作 靠的就是这条:没有自由 shell,只有目录里声明过的类型化参数。

preflight

执行前的机器检查,把 AGENTS.md 里只存在于约定中的规则变成会报错的检查。复合动作在第一步执行前 跑完所有步骤的检查。

kind 参数 检查内容
git-branch expect 当前分支等于 expect;镜像里没有 .git 时读 DROBOTICFLOW_SOURCE_BRANCH
env name 环境变量非空
file path 文件存在(相对仓库根)
command command 可执行文件在 PATH 上
kube-reachable env_arg(可选) 按脚本同样的方式 source scripts/load-deploy-env.sh 后 kubectl get --raw /version 能通;顺带执行其中的分支/环境守卫

execution

# script —— 跑仓库里的脚本(解释器按扩展名推断:.sh→bash,.py→python3,.mjs→node)
execution:
  kind: script
  script: scripts/cleanup-operator-jobs.sh
  interpreter: [python3, -I]     # 可选,覆盖推断
  fixed_args: [publish]          # 可选,固定的前置参数(如子命令)
  dry_run_env: DRY_RUN           # 可选:dry-run 时设为 true,否则显式设为 false
  apply_flag: --apply            # 可选:仅真正执行时追加(与 dry_run_env 二选一)
  timeout_seconds: 600

# npm —— package.json 里的 script(生成器校验存在)
execution: {kind: npm, npm_script: "k8s:validate", timeout_seconds: 300}

# http —— 调平台 API(测试校验路由在 internal/api 真实注册)
execution: {kind: http, method: GET, path: "/api/runs/{id}"}

# composite —— 按序跑别的动作,前一步失败即停(步骤不能有必填参数)
execution: {kind: composite, steps: [poc.images, poc.deploy, accept.readiness]}

dry_run_env / apply_flag 是变更动作能否 dry-run 的唯一依据:没有它们,变更动作的 dry-run 会被拒绝,而不是假装跑了一遍。只读动作的 dry-run 就是正常执行。

复合动作的 tier、角色、入口、mutates、confirm 必须覆盖所有步骤(生成器校验)。

加一个动作

  1. 在对应 ops/catalog/<domain>.yaml 的 actions 里加一条
  2. npm run generate:ops-catalog
  3. go test ./internal/opscatalog/ ./internal/api/ -run 'Ops|Catalog|Assistant' —— 校验脚本路径、角色矩阵与 HTTP 路由真实注册
  4. 三个入口同时就有了这个动作,按 tier 授权