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>
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 必须覆盖所有步骤(生成器校验)。
加一个动作
- 在对应
ops/catalog/<domain>.yaml的actions里加一条 npm run generate:ops-cataloggo test ./internal/opscatalog/ ./internal/api/ -run 'Ops|Catalog|Assistant'—— 校验脚本路径、角色矩阵与 HTTP 路由真实注册- 三个入口同时就有了这个动作,按 tier 授权