From 9c3ab0e726646937813a85543a8cf72b4ff33d5f Mon Sep 17 00:00:00 2001 From: "xiaobing.wang" Date: Tue, 31 Mar 2026 17:28:37 +0800 Subject: [PATCH] docs: prefer interactive config collection --- gitops-app-onboarding/SKILL.md | 34 +++++++++++++++------------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/gitops-app-onboarding/SKILL.md b/gitops-app-onboarding/SKILL.md index f7d1e1d..5e7a0e9 100644 --- a/gitops-app-onboarding/SKILL.md +++ b/gitops-app-onboarding/SKILL.md @@ -242,7 +242,7 @@ deploy/helm// ## 对外暴露模型 -对外暴露模型使用固定方式，不再按项目自由选择。 +对外暴露模型使用固定方式。 - 固定使用 nginx 作为统一入口，代理前端与后端路径 - 对外只暴露 nginx 入口，并通过 `NodePort` 提供入口访问 @@ -258,7 +258,7 @@ deploy/helm// - 如果用户或项目文档已经提供了分配好的 `NodePort`，直接使用 - 如果没有提供，先完成所有非阻塞工作，最后只问用户一个最小必要问题来索取该端口 - 不要擅自写入示例端口或看起来顺手的默认值，例如 `30080`、`30081` -- 如果用户暂时没有提供，最终输出中必须明确说明 nginx 对外 `NodePort` 尚未分配，因此外部访问配置未完成 +- 如果用户暂时没有提供，就停在这一项等待补值，不要擅自填入 ## Release Bundle 规则 @@ -299,12 +299,12 @@ deploy/helm// - 不要为了“看起来完整”而伪造假的生产值 - 先区分“外部集成凭据”和“应用自带私有依赖的内部口令” -- 如果是外部集成凭据，应在完成所有非阻塞工作后主动向用户索取，而不是只在最后留警告 +- 如果是外部集成凭据，应在完成所有非阻塞工作后主动向用户索取 - 如果是应用自带私有依赖的内部口令，优先由生成流程一次性生成并写入 release secret，而不是要求用户手填 - 如果用户暂时没有提供，不要造占位内容冒充可部署配置 - 对部署阻塞项，按最小必要粒度逐项提问，优先直接问“这一项应填什么” -- 只有当用户明确暂不提供、或本轮对话结束时仍未补齐，才在最终输出中保留缺失项警告 -- 可以只保留结构，或暂不生成具体 secret 内容，但必须在最终输出中明确警告缺失项与影响 +- 在交互会话中，完成非阻塞工作后，如果仍有必填项缺失，应先向用户索取当前顺序中的下一项 +- 可以只保留结构，或暂不生成具体 secret 内容，但不要用伪造值把未完成配置包装成已完成 release bundle 只负责导出当前应用自己的发布结果，不负责维护 GitOps 仓库中的其他对象。 @@ -337,8 +337,9 @@ shared 边界： - shared 只负责共享基础设施和通用运行时地址 - 平台共享基础设施包括 `PostgreSQL`、`Redis`、`Qdrant`、`MinIO` - 应用 Chart / release bundle 默认应引用这些 shared 组件的既有服务地址与 shared Secret，不要重复生成这些工作负载 +- 这些 shared 组件的 host 应使用平台提供的实际地址或 FQDN，不要默认写成当前应用 namespace 下的裸服务名，例如 `postgres`、`redis`、`qdrant`、`minio` - 只有当用户明确要求该应用自带独立实例时，才为 `PostgreSQL`、`Redis`、`Qdrant`、`MinIO` 生成应用私有资源 -- `Neo4j` 不再作为平台共享基础设施提供；如应用需要图数据库，应由应用自己部署和维护 +- 平台共享基础设施不包含 `Neo4j`；如应用需要图数据库，应由应用自己部署和维护 - 只要应用运行时配置仍引用某个应用私有依赖，就应在应用 Chart / release bundle 中把它一并表达出来，而不是只在 values 里保留连接参数 - 不要把某个厂商的客户端证书、私钥、应用专属 `app_id`、tenant id、client id、namespace id、应用独有 webhook 签名密钥放进 `shared/` - 镜像拉取默认使用 `registry-pull-secret`，不要随便为每个应用再造一个 pull secret，除非平台模型发生变化 @@ -354,7 +355,7 @@ shared 边界： - 先完成所有非阻塞工作 - `env` 与鉴权材料均为必填项 - 鉴权材料按固定顺序向用户索取：`app_id` -> `app.crt` -> `app.key` -> `ca.crt` -> `public.key` -- 如果用户还没提供完整值，不要写伪造占位内容；在最终输出中明确警告缺失了哪些字段以及可能影响 +- 如果用户还没提供完整值，不要写伪造占位内容 opensdk 读取与挂载规则： @@ -372,7 +373,8 @@ opensdk 读取与挂载规则： - 先做完不依赖这些值的工作 - 按必填项收集百智云配置 - 先索取 `env`，再按固定顺序逐项索取 `app_id`、`app.crt`、`app.key`、`ca.crt`、`public.key` -- 对外部集成字段，应在非阻塞工作完成后逐项索取，而不是直接跳到最终缺失项警告 +- 对外部集成字段，应在非阻塞工作完成后逐项索取 +- 如果当前正在等待用户补值，就把回复重点放在“当前要补的这一项” - 对应用自带私有依赖内部口令，优先自动生成；只有用户明确要求自定义时才向用户索取 - 不要用“把需要的都给我”这种模糊问法 - 缺少任一必填项时，要明确指出当前卡在哪一项 @@ -399,14 +401,14 @@ opensdk 读取与挂载规则： 至少确认： -- 应用仓库不再缺少接入文件 +- 应用仓库接入文件齐全 - `.gitlab-ci.yml` 包含 test、镜像构建、chart 发布、release 结果同步逻辑 - release values 指向 `registry.baizhi.cloud` - GitOps 仓库更新 job 指向 `https://deploy.baizhi.cloud/gitops-admin/argodeploy.git` - CI 中没有直接调用 Argo -- 没有继续使用旧域名 -- 没有继续使用不安全的 HTTP registry 访问方式 -- 如果存在用户未提供的必填私有配置，最终输出中已明确列出缺失项和潜在影响 +- 仅使用 `deploy.baizhi.cloud` 与 `registry.baizhi.cloud` +- 没有使用不安全的 HTTP registry 访问方式 +- 如果存在用户未提供的必填私有配置，交互会话会继续停在当前必填项上索取补值 ## 最终输出要求 @@ -416,12 +418,6 @@ opensdk 读取与挂载规则： 2. 关键设计决策 3. 最值得人工复核的 3 个点 -如果存在用户未提供的必填私有配置，额外增加“缺失项警告”，明确列出： - -- 缺少哪些字段 -- 因此哪些配置尚未完成 -- 不补齐会影响什么，例如无法直接部署、某功能未启用、secret 仍为空 - ## 常见错误 以下都属于接入错误： @@ -429,7 +425,7 @@ opensdk 读取与挂载规则： - 把应用私有鉴权材料放进 `shared/` - 在 CI 里直接刷新 Argo - 重新引入已废弃的旧域名 -- 在 HTTPS 已恢复后仍使用 insecure registry 参数 +- 使用 insecure registry 参数 - 生成的 Chart 与应用真实组件不匹配 - 在生产 release values 中写 `registry.example.com` 这类示例地址 - 应用没有这个设计却擅自发明新的公网 host