@numa-tech/numa 1.14.16 → 1.14.17

package/skills/numa-jenkins-deployment/references/diagnostics.md

@@ -0,0 +1,121 @@
+# Jenkins 部署诊断树
+
+## 快速判定
+
+| 观察结果 | 分类 | 含义 | 下一步 |
+|---|---|---|---|
+| `numa app list` 没有 application | `APPLICATION_NOT_REGISTERED` | 应用尚未进入 DevOps 应用目录 | 使用 `numa-create-application` 做 onboarding plan；不要直接创建 Jenkins Job |
+| 应用存在，但 pipeline list/inspect 无 binding | `JENKINS_NOT_INITIALIZED` | delivery/Jenkins 绑定尚未创建或确认 | 平台管理员完成 Jenkins inventory、Job 候选和 binding |
+| binding 非 `CONFIRMED` | `JENKINS_NOT_INITIALIZED` | 平台尚未确认应用与 Job 的治理关系 | 确认 binding，不要绕过平台直触发 |
+| instance unhealthy 或 stale | `JENKINS_NOT_INITIALIZED` | Jenkins 凭据、网络或 inventory sync 不可用 | 测试 instance 并同步 inventory |
+| Multibranch 父 Job `buildable=false` | 继续检查 branch | 父容器常常不可直接构建 | 用目标 branch 解析直接子 Job；不要仅凭父字段阻断 |
+| branch 子 Job 不存在/不可构建 | `JENKINS_NOT_INITIALIZED` 或 SCM 分支问题 | Jenkins 尚未索引该分支，或分支不符合 Job 规则 | 确认远端 branch、multibranch scan 和子 Job |
+| 只有父 Job 或 `scanMode=NONE` | `JENKINS_NOT_INITIALIZED` | 完整的 branch 初始化尚未发生 | 新部署命令会在 SCM/Jenkinsfile 已验证后自动尝试一次 INDEX_ONLY/NoTrigger scan；仍失败时用受治理的初始化/replan 修复 |
+| 目标分支经过自动索引后仍无 child | `JENKINS_BRANCH_FILTERED` | Jenkins 分支策略过滤、索引未收敛或 branch child 不可构建 | 检查 Multibranch branch source/filter 与 Jenkinsfile；不要改用默认分支或影子 Job |
+| Jenkins 索引读取结果不可确认 | `JENKINS_BRANCH_DISCOVERY_FAILED` | Jenkins 上游读取、超时或中断 | 保留同一部署参数和幂等键，先查状态与 Jenkins 索引结果，再按服务端错误恢复 |
+| v2 writer bootstrap/provenance/rollout 非 exact verified readiness | `PLATFORM_V2_NOT_READY` | 新平台构建入口尚未达到安全门禁 | 回到 onboarding/rollout 恢复；不得用 legacy readiness 或 `pipeline build` 降级 |
+| 401 | `AUTHORIZATION_OR_APPROVAL` | 登录缺失、过期或 issuer/profile 不匹配 | `auth status`、`profile`，必要时重新登录 |
+| 403 | `AUTHORIZATION_OR_APPROVAL` | 团队权限、平台角色或生产角色不足 | 核对成员关系和 ops-admin；不要索要 token 绕过 |
+| 生产审批缺失/无效 | `AUTHORIZATION_OR_APPROVAL` | 服务端治理拒绝写操作 | 使用真实 approval ID 或合规具体原因 |
+| Jenkinsfile/buildEntry/APP_NAME/入口不合规 | `PROJECT_STANDARD` | 项目不符合 MCI 构建/运行契约 | 使用 `mci-build-standards` 检查并按用户授权修复 |
+| 编译、测试、镜像阶段失败 | `BUILD_OR_RUNTIME_FAILURE` | 源码或依赖问题 | 定位首个失败命令，修复后重跑 preflight |
+| Pod 启动、探针或 ApplicationContext 失败 | `BUILD_OR_RUNTIME_FAILURE` | 镜像已构建但运行态失败 | 从首个 root cause 修复；增加启动/Bean wiring 契约测试 |
+| Jenkins image update 失败/intent `UNKNOWN`，远端 marker/HEAD 已匹配 | `GITOPS_LEDGER_UNRESOLVED` | CAS 可能已落地，但 writer response/readback/本地账本未确认 | 不重放；核验 exact intent 与 Flux observed revision，等待同一 durable request 的服务端 reconcile/recover |
+| build/status/log 同时 404/500/503 | `CONTROL_PLANE_OUTAGE` | DevOps API 或其网关路由不可用 | 停止 CLI 重试；若是自部署，进入受控 break-glass |
+
+## 应用未登记与 Jenkins 未初始化的区别
+
+先查应用目录，再查流水线：
+
+```text
+app 不存在
+└─ 需要应用 onboarding：团队、SCM、环境、技术栈、delivery
+
+app 存在
+└─ pipeline/binding 不存在
+   └─ 需要 Jenkins 初始化：instance、inventory、Job/branch、confirmed binding
+```
+
+不要因为两者最终都表现为“不能部署”就混为一谈。应用 onboarding 可能创建/绑定流水线，但需要独立确认和服务端 plan；部署 Skill 不直接替代该流程。
+
+## 项目规范诊断
+
+使用 `mci-build-standards` 核对：
+
+- Jenkinsfile 使用统一 `buildEntry()`；
+- `APP_NAME` 与应用/镜像名一致；
+- monorepo 的 `APP_HOME` 正确；
+- `TRIGGER_BUILD`、目标 branch 和手动/webhook 策略一致；
+- Java/Go 使用合适节点，Node/Python 使用可访问依赖源的节点；
+- Java 产物是 Spring Boot layered jar；
+- Next.js standalone 有可运行的 `server.js` 和正确 COPY_PATH；
+- Python 有明确 entrypoint；
+- 应用监听 `PORT=8080`，启动命令、readiness/liveness 可用；
+- 不用普通构建参数传 credential、token、password、secret。
+
+构建成功不代表部署成功。日志出现 Pod startup、ApplicationContext、probe timeout 或容器入口错误时，应继续按运行时规范排查。
+
+## 日志分析顺序
+
+1. 保存 request ID、build number、branch 和 commit。
+2. 从日志末尾确认 Jenkins `Finished:`。
+3. 向前寻找第一个 `Caused by`、失败命令、测试失败或 probe/startup 错误。
+4. 区分流水线包装错误与应用 root cause。
+5. 报告最小修复面；未经用户授权不要顺手修改项目。
+
+常见状态陷阱：
+
+- `UNKNOWN` 不等于失败，也不等于成功。
+- `UNKNOWN` 同时带 `completedAt`，而 Jenkins 日志结尾是 `Finished: FAILURE`，通常是状态归一或旧服务版本问题；按失败处理并报告映射缺口。
+- `--wait` 没有输出可能只是只在终态输出 JSON；用只读 `builds` 交叉检查，不要重复触发。
+- HTTP 500/503 发生在被部署后端滚动时，远端 Jenkins 可能继续运行；服务恢复后用原请求续查。
+- Jenkins `Finished: FAILURE` 若根因是 `GitOpsUnknownResult`，不能直接归类为源码构建失败。远端 target HEAD 含本次稳定 request marker、image repository/tag/digest 与原 intent 精确匹配且 Flux 已应用时，分别报告 Jenkins/build、platform ledger、Flux/runtime；runtime healthy 仍不等于账本成功。
+- Git ref 的 CAS/fast-forward 更新可以是原子的，但 API 响应、后续 readback 或平台持久化仍可能失败；这就是“远端成功、平台未知”的窗口，不是 Git push 半成功。
+
+## GitOps ledger 对账清单
+
+按同一原请求核验，不从日志文本或邮箱/显示名推断 identity：
+
+1. application、binding/target、request ID、client request key 和 build number；
+2. source revision 与 image repository/tag/digest；
+3. expected old head、稳定 request marker、remote target HEAD/revision 和目标 image 字段；
+4. Flux GitRepository/Kustomization/HelmRelease observed revision；
+5. Deployment/Pod exact image 与 readiness。
+
+全部匹配可报告 `RUNTIME_DEPLOYED / PLATFORM_LEDGER_UNRESOLVED`，但不能伪造平台成功。任何冲突都是 fail closed。当前 command catalog 没有同一 durable request 的服务端 reconcile/recover 时，停止写操作并把修复责任交给控制面。
+
+## 自部署故障与 break-glass
+
+典型证据：
+
+- 目标应用就是 `mci-devops-platform` 或提供 Numa pipeline API 的服务；
+- Jenkins 页面可见日志，但 `numa pipeline log` 返回 404/503；
+- `pipeline list`、`builds` 和其他新 API 同时不可用；
+- 网页是直连 Jenkins，而 CLI 通过 DevOps 后端代理。
+
+处理：
+
+1. 明确当前 CLI 控制面已经丢失，不再尝试 `build/retry`。
+2. 通过已有、审计化的 Jenkins SSO 或独立恢复服务查看日志。
+3. 修复并推送代码，完成本地/CI preflight。
+4. 经用户明确授权，手工触发白名单后端 Job，固定 branch/commit 和 approval ID。
+5. 后端恢复后用 Numa CLI验证新能力、刷新旧请求终态，再部署前端或其他依赖应用。
+6. 记录手工构建可能未进入平台 request 表；不要伪造 request ID。
+
+break-glass 不是匿名接口、共享管理员密码或绕过审批。理想实现独立于被管理平台，权限最小、目标白名单、MFA、强制审批、全量审计，并在恢复后回填记录。
+
+## 排除报告模板
+
+```markdown
+结论：<分类与是否可继续部署>
+
+证据：
+- 应用登记：<存在/缺失>
+- Jenkins 初始化：<instance/job/branch/binding>
+- 项目规范：<preflight/关键缺口>
+- 身份治理：<profile/role/approval>
+- 构建运行态：<request/build/Finished/root cause>
+
+已排除：<其他类别及证据>
+下一步：<责任方、最小动作、恢复后验证>
+```

package/skills/numa-jenkins-deployment/references/release-policy.md

@@ -0,0 +1,94 @@
+# 仓库驱动的发布策略
+
+## 策略优先级
+
+按以下顺序解析发布策略：
+
+1. 仓库根目录 `.numa/pipeline-release.json`；
+2. `AGENTS.md` 和仓库部署文档；
+3. 用户为本次发布明确提供的值。
+
+不要擅自覆盖版本化的应用顺序、tier、preflight、approval ID 或生产原因。用户如果要改变发布策略，应把策略修改和实际部署分开 review。
+
+## Manifest v1
+
+```json
+{
+  "schemaVersion": 1,
+  "tier": "production",
+  "approval": {
+    "id": "APPROVAL-ID",
+    "reason": "具体生产发布原因"
+  },
+  "preflight": [
+    {
+      "command": "./scripts/verify-cli-deploy.sh",
+      "description": "仓库发布门禁"
+    }
+  ],
+  "applications": [
+    {
+      "code": "backend-application",
+      "description": "先部署迁移和 API"
+    },
+    {
+      "code": "frontend-application",
+      "description": "仅在后端成功后部署"
+    }
+  ]
+}
+```
+
+校验规则：
+
+- `schemaVersion` 为 1；
+- tier 只接受 develop、staging、production；
+- applications 至少一个，code 非空且唯一；
+- production 至少提供真实 approval ID 或不少于 10 字符的具体原因；
+- approval ID 匹配 `[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}`；
+- reason 不超过 800 字符；
+- manifest、preflight 和 build parameters 不含 Secret。
+
+## Git 与 preflight
+
+生产发布前：
+
+```bash
+git status --short --branch
+git check-ref-format --branch BRANCH
+git fetch origin BRANCH
+git rev-parse HEAD
+git rev-parse origin/BRANCH
+```
+
+要求工作树干净、branch 合法、本地 HEAD 与远端完全一致。不要 stash、reset、checkout 或提交用户的无关修改来强行通过。
+
+逐条检查 preflight 命令内容后按顺序执行；第一条非零即停止。preflight 应覆盖编译、测试、打包和运行时产物契约，而不仅是静态 lint。
+
+## 计划与授权
+
+为每个应用派生稳定幂等键：
+
+```text
+APPLICATION-COMMIT_SHA
+```
+
+展示解析后的应用顺序、tier、branch/SHA、Jenkins binding、preflight、审批和幂等键。用户明确要求按仓库既有 manifest 发布该 branch，且解析没有改变目标或政策时，视为已授权该发布；任何新增目标或生产影响都要重新确认。
+
+每个应用还要记录 delivery mode。`PLATFORM_V2` 使用 `pipeline platform-build trigger`，不接受任意参数；只有明确 `LEGACY_V1` 才使用 `pipeline build`。manifest 不能把 v2 应用静默降级成 legacy，也不能把同一 idempotency key 用于不同 source revision 或 image intent。
+
+## 串行发布
+
+依次执行 manifest applications。v2 前置应用只有 Jenkins/build、platform image-intent ledger 与 Flux/runtime 三方一致并通过健康检查后，才算 `SUCCESS`；后端、数据库迁移或公共 API 等前置应用未满足该条件时，禁止触发前端和下游应用。
+
+如果本地等待中断：
+
+- 远端任务可能仍运行；
+- 复用原幂等键；
+- 先通过 builds/status/log 恢复；
+- 不自动 retry，不推进下一个应用。
+- 若远端 Flux CAS/运行态已经成功但平台 ledger 未决，报告 `RUNTIME_DEPLOYED / PLATFORM_LEDGER_UNRESOLVED`，不重复发布，也不推进依赖完整平台成功证明的后续应用。
+
+## 完成验证
+
+除 Jenkins 终态外，还要执行仓库定义的健康、迁移或能力探针。v2 分别报告 Jenkins/build、platform ledger、Flux/runtime，及每个应用的 request/build ID、branch/SHA 和幂等键；失败或 ledger 未决时明确哪些后续应用被跳过。

package/skills/numa-local-flux-deploy/SKILL.md

@@ -16,9 +16,10 @@ Read [local-flux-release.md](references/local-flux-release.md) completely before
 - Never read registry auth files, kubeconfig contents, application secrets, token caches, or `secrets/**`. Check only whether the required authenticated tools can operate.
 - Do not modify Keycloak, database data, unrelated Flux resources, or a live Deployment unless the user separately placed that target in scope.
 - A local interruption or registry/network error creates an unknown result. Inspect the existing image tag, Git ref, Flux revision, and workload before any retry. Reuse the exact operation identity; never create a second release to escape uncertainty.
+- A Numa v2 platform-build whose writer result is `UNKNOWN` is not evidence that the Flux write failed. Before selecting this fallback, inspect the original platform request plus the remote target HEAD/request marker and exact image field. If the intended CAS already landed, do not write Flux again; observe the existing revision and leave platform-ledger reconciliation to the supported server-side recovery path.
 
 ## Finish with evidence
 
-Do not call the release successful until GitOps has applied the exact Flux commit, the controller and workload are healthy on the exact image tag, the application readiness check passes, and any optional npm release has passed candidate smoke testing before promotion to `latest`.
+Do not call the release successful until GitOps has applied the exact Flux commit, the controller and workload are healthy on the exact image tag, the application readiness check passes, and any optional npm release has passed candidate smoke testing before promotion to `latest`. When this fallback only verifies a revision already written by a v2 platform request, report `runtime deployed / platform ledger unresolved` until the control plane reconciles the original request.
 
 Report the source commit, image tag and digest, Flux commit/revision, cluster context, controller/workload status, health results, npm version/tags when applicable, and whether Jenkins or Keycloak were touched.

package/skills/numa-local-flux-deploy/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Numa Local Flux Deploy"
   short_description: "Fallback local image builds and Flux releases"
-  default_prompt: "Use $numa-local-flux-deploy to perform a controlled local image and Flux deployment when the normal pipeline is unavailable."
+  default_prompt: "Use $numa-local-flux-deploy only as an explicitly authorized fallback when the normal pipeline is unavailable. First rule out a v2 writer result whose Flux CAS already landed; never rewrite Flux to hide an unresolved platform ledger."

package/skills/numa-local-flux-deploy/references/local-flux-release.md

@@ -2,6 +2,8 @@
 
 Use this runbook only after the user authorizes the exact deployment and the normal Jenkins/Numa pipeline is unavailable or explicitly excluded. Keep the pipeline failure evidence in the handoff, but do not repeatedly probe or trigger it once the fallback is selected.
 
+Do not select the fallback merely because a v2 platform-build ended with `GitOpsUnknownResult`, a gateway timeout, or an image-intent ledger in `UNKNOWN`. First inspect the original request and the remote Flux branch. If the target HEAD contains the same stable request marker and the resolved image repository/tag/digest matches the original intent, the governed CAS already landed: skip image/Flux writes, observe that exact revision, and report the platform ledger separately. Local fallback cannot reconcile or overwrite the control-plane record.
+
 ## 1. Resolve and freeze the release identity
 
 Collect these values from repository and live read-only evidence:
@@ -129,6 +131,7 @@ Use the original identity at every stage:
 | Flux reconciliation | GitRepository/Kustomization revision and conditions | continue observing or request reconciliation for the same commit |
 | workload rollout | controller revision, Deployment generation, Pod image ID | continue observing the same rollout; do not create a new release |
 | health check | workload readiness plus bounded endpoint checks | diagnose the deployed revision; do not infer rollback or success from one timeout |
+| Numa v2 writer ledger | original request plus remote target HEAD/request marker and exact image intent | if the CAS already landed, perform no local write; verify runtime and leave the same durable request `PLATFORM_LEDGER_UNRESOLVED` until server-side reconciliation |
 
 Never hide an unknown result by choosing a new image tag, commit, or audit branch.
 
@@ -169,4 +172,5 @@ Report, without credentials or secret values:
 - controller, Deployment, Pod restart, readiness/liveness, and migration results;
 - npm release commit/tag, package version, and all dist-tags when applicable;
 - any unknown stage still unresolved;
+- when applicable, separate `Jenkins/build`, `platform image-intent ledger`, and `Flux/runtime` status instead of collapsing a healthy runtime into platform success;
 - confirmation that Keycloak and unrelated resources were not modified.