| name | bscp-kv-config |
| slug | bscp-kv-config |
| version | 1.0.0 |
| description | bscp（蓝鲸基础配置平台）KV 配置操作指引。为挂载了 bk-bscp-prod-server-mcp 的模型补充
MCP 工具 schema 表达不了的领域知识：领域模型、端到端调用编排、参数获取、字段级业务
约束、报错处置与场景化示例，帮助模型正确完成"改 KV → 生成版本 → 发布 → 验证"闭环。
Use this skill whenever the user asks to 操作 bscp 配置, 改 bscp KV, 新增/更新/删除 KV,
发布 bscp 版本, 灰度发布, kv 配置查询/更新/发布, 看看某个服务的配置, 帮我发版,
or invokes any bk-bscp-prod-server-mcp Config_* tool
(CreateKv/UpdateKv/DeleteKv/BatchUpsertKvs/CreateRelease/Publish 等).
|
| metadata | {"requires":{"mcps":["bk-bscp-prod-server-mcp"]}} |
bscp KV 配置操作指引
定位
本 skill 只补充 MCP schema 表达不了的知识（跨工具编排、字段间业务约束、错误语义、领域模型），
不重复 MCP 工具已有的单字段描述——填参时字段含义以 MCP 工具 schema 为准。文中的业务
约束来自 bscp 服务端的实际校验规则，会随 bscp 版本演进；若与调用返回的报错不一致，以服务端返回为准。
适用范围：bk-bscp-prod-server-mcp 当前的 13 个工具，聚焦 config_type=kv 服务的 KV 配置闭环。
不覆盖模板、分组管理、客户端等 KV 闭环以外的接口。
前置条件
本 skill 依赖 bk-bscp-prod-server-mcp（蓝鲸 API 网关提供的 bscp MCP Server）暴露的 Config_* 工具。
开始操作前必须先确认这些工具已可用：
- 检查当前会话是否已挂载
bk-bscp-prod-server-mcp，能看到 Config_ListAppsBySpaceRest/Config_CreateKv 等工具。
- 若工具不存在：不要臆造工具名或伪造调用结果，直接告知用户"未检测到 bscp MCP，需要先接入"，并给出下述接入指引，然后停下等待用户完成配置。
- 工具可用后再按后续章节执行。
接入指引（当工具缺失时告知用户）
请在你的 AI IDE（Cursor / Claude 等）的 MCP 配置中添加 bk-bscp-prod-server-mcp，通常需要准备：
- MCP Server 地址：蓝鲸 API 网关上 bscp MCP Server 的接入地址；
- 鉴权信息：调用网关所需的鉴权（如网关应用凭证 /
X-Bkapi-Authorization）；
- 业务上下文：目标业务的
bizId（来自 CMDB 业务 / 空间）。
具体的接入地址与凭证请向 bscp 平台或蓝鲸 API 网关管理员获取；配置完成后重新加载 MCP，确认 Config_* 工具出现即可。
交互引导（面向不熟悉闭环的用户）
用户往往只会抛一个模糊意图（如"kv 配置查询 / 更新 / 发布"）而不知道要给哪些参数、要走什么闭环。
不要一次性罗列一堆参数把用户劝退，也不要臆造参数；按下面的方式分步反问，一次只问当前缺的一个关键信息，
把用户缺的参数逐步补齐后再执行。
通用引导步骤（任何意图先做）
- 确认业务 ID（bizId）：用户没给就先问"请提供业务 ID（bizId）"。
- 确认服务名 → 解析 appId：拿到服务名后调
Config_GetAppByName（或先 Config_ListAppsBySpaceRest 让用户从列表里挑）
得到 appId，并校验 config_type=kv；若不是 kv 型，直接告知"该服务不是 KV 型服务"并停止。
- 参数齐了再进入对应意图的动作；能从上下文推断的（如上一步已拿到的 appId）不要重复问。
三类意图的最小引导
| 用户说 | 最少还需要问 | 拿齐后动作 |
|---|
| kv 配置查询 / 看某服务配置 | bizId、服务名（可选 key） | Config_ListKvs（草稿）或 Config_ListReleasedKvs（已发布），展示结果 |
| kv 配置更新 / 新增 / 删除 | bizId、服务名、key（更新/新增再要 value，必要时 kvType） | Config_CreateKv/UpdateKv/DeleteKv（草稿态）；完成后主动追问"是否现在生成版本并发布？"，用户同意再走发布流程 |
| kv 配置发布 / 发版 | bizId、服务名 | 有草稿改动 → 生成版本前先捕获历史命名规则给出建议版本名并询问用户（见「版本命名」），确认后 Config_CreateRelease 拿 releaseId；或让用户从 Config_ListReleases 选已有版本，再 Config_Publish |
写操作执行前必须二次确认
对 发布（Config_Publish）、覆盖式批量导入（Config_BatchUpsertKvs 且 replaceAll=true）、
删除（Config_DeleteKv/Config_BatchDeleteKv） 这类会影响客户端生效内容或清空数据的操作，
执行前先展示将影响的内容（如将发布的版本、将被覆盖/删除的 key 列表）并等用户确认后再调用；用户未确认不执行。
⚠️ 核心规则
- KV 增删改都是草稿态，客户端不可见；必须"生成版本 + 发布"后才生效。
- KV 只适用于
config_type=kv 的 app；对 file 型 app 操作会报 not a KV type service。
- 删除按 id/ids，不是按 key：
DeleteKv/BatchDeleteKv 需先 ListKvs 拿到 id。
Config_Publish 只发布已存在的 releaseId，不会从草稿自动生成版本。- 灰度字段在
Config_Publish 上（grayPublishMode/groups/labels），需要先有 releaseId。
- 列表接口必须显式给分页：
Config_ListKvs/ListReleasedKvs/ListReleases/ListAppsBySpaceRest 要么传 all:true 全量取，要么显式传 limit（1–1000，配合 start 翻页）。不传 limit 会被服务端当成 0，报 page.limit value should >= 1 而查询失败——这是这些接口"要重试才成功"的常见原因。查询本意是"拿全部"时优先直接 all:true。
领域模型速览（F-001）
biz（业务） → app（服务，带 config_type / data_type） → kv（草稿态配置项） → release（不可变版本快照）
- app 有
config_type（kv / file）和 data_type（app 级 KV 类型，可为 any）。
- KV 的每次增删改只改草稿区，不影响已发布内容；release 是一次生成后不可变的快照。
端到端调用编排（F-002）
标准闭环链路：
- 定位服务 → 拿
appId
- 已知业务：
Config_ListAppsBySpaceRest（按 bizId 列 app）
- 已知服务名：
Config_GetAppByName
- 从返回结果的
config_type 字段辨别 kv 型 app（该工具当前不支持 config_type 过滤）
- 改配置（草稿态）
- 单条：
Config_CreateKv / Config_UpdateKv / Config_DeleteKv
- 批量：
Config_BatchUpsertKvs（replaceAll=true 会先清空草稿区再写入）/ Config_BatchDeleteKv（按 ids）
- 删除前先
Config_ListKvs 拿 id
- 生成版本
- 用户未指定版本名时，先捕获历史命名规则并询问用户（见下节「版本命名」），拿到确认后的名字再调用
Config_CreateRelease → 产出 releaseId
- 发布
Config_Publish：发布已有 releaseId；all=true 全量，或灰度（见下）
- 验证
Config_ListReleases / Config_GetReleasedKv / Config_ListReleasedKvs
全量 vs 灰度发布
| 场景 | 推荐工具 | 关键参数 |
|---|
| 生成版本并全量发布 | 先 Config_CreateRelease 拿 releaseId，再 Config_Publish | all=true |
| 发布某个已有版本（全量） | Config_Publish | releaseId + all=true |
| 灰度发布 | 先 Config_CreateRelease 拿 releaseId，再 Config_Publish | all=false + grayPublishMode（publish_by_groups/publish_by_labels）+ groups 或 labels |
注意：灰度相关字段（grayPublishMode/groups/labels/groupName）在 Config_Publish 的 body 上，
需要发布时统一走 CreateRelease 拿 releaseId 再 Publish 两步。
groups（分组 ID 列表）有值时 all 必须为 false。
版本命名：捕获历史规则后询问用户
Config_CreateRelease 的 name（版本名）必填，且同一 app 内唯一。用户往往不想每次都自己想名字，
但又希望沿用团队既有的命名习惯。因此用户未显式给版本名时，不要直接臆造，也不要直接用一个固定默认值，
按下面的流程做：
- 拉历史版本名：
Config_ListReleases {bizId, appId, all:true}，取各 release 的 name（列表接口记得带 all:true，见核心规则 6）。
- 识别命名规律：从历史 name 里归纳规则，常见几类——
- 递增序号：
v1/v2/v3、release-1/release-2
- 语义前缀 + 序号：
v-import-1、gray-2
- 日期类：
20260702、2026-07-02、2026-07-02-1（同日多次带尾号）
- 生成建议名：按识别到的规律推下一个值（递增类要在最大序号上 +1，日期类用当天日期；都要避免与已有 name 重名）。
- 询问用户是否采用：把建议名给用户，例如「按历史命名规律，建议版本名
v4，是否使用？也可以自定义」，
用户确认或给出自定义名后再 Config_CreateRelease。
- 无历史或无明显规律：给一个合理默认（如
v1 或当天日期），同样先问用户，不要静默替用户决定。
命名约束（服务端 ValidateReleaseName 强校验，与 key 类似）：长度 1–128；仅中文 / 英文 / 数字 / _ / - / .；
首尾必须是中文、英文或数字；同 app 内不可重名（重名报 release name ... already exists）。
参数获取（F-003）
bizId：来自蓝鲸平台上下文（CMDB 业务 / 空间）或请求头 X-Bkapi-Biz-Id；MCP 不提供列 biz 的工具，需由用户/上下文给出。appId：通过 Config_ListAppsBySpaceRest（按 bizId 列 app）或 Config_GetAppByName（已知服务名）获取。- 辨别 kv 型 app：从上述工具返回结果里读
config_type 字段，取 config_type=kv 的 app。
id（KV 主键）：删除 KV 前用 Config_ListKvs 查询获取。releaseId：由 Config_CreateRelease 返回，或从 Config_ListReleases 中选取未废弃的版本。
字段级业务约束（F-004）
以下为 MCP schema 无法表达的关联约束（schema 只描述单字段），由 bscp 服务端强校验：
- key
- 长度 1–128
- 仅中文 / 英文 / 数字 /
_ / -；首尾必须是中文、英文或数字
- 禁止
_bk 前缀（不区分大小写）
- 不含
. 和 /（保留字符）
- value
- 非空；上限 1MB
- 按 kvType 做格式校验：
json 须合法 JSON；yaml 须合法 YAML；xml 须合法 XML；number 须为数字；string 不含换行符；text/secret 不做内容格式校验
- kvType
- 单条 KV 的 kvType 不可填
any（any 只用于 app 的 data_type）
- 单条 KV 的 kvType 必须与 app 的
data_type 一致；例外：app 的 data_type 为 any 时允许任意 kvType
UpdateKv 不能改 kvType：更新时沿用已存储的类型，请求里的 kvType 不生效；要改类型需删掉重建
- secret
- kvType=
secret 时 secretType 必填，枚举：password / certificate / secret_key / token / custom
certificate 类型的 value 应为 X.509 PEM，可配合 certificateExpirationDatesecretHidden 控制明文是否隐藏
- 数量上限
- 单 app 未删除的配置项默认上限 2000（含模板+非模板），部分业务可能有不同上限
报错 → 原因 → 处置（F-005）
| 报错关键字 | 原因 | 处置 |
|---|
already exists ... cannot be created again | key 已存在 | 改用 Config_UpdateKv，或换一个 key |
kv type does not match the data type defined in the application | kvType 与 app 的 data_type 不一致 | 按 app.data_type 修正 kvType（app 为 any 时不受此限） |
the type of config item ... is incorrect | 批量导入时同 key 类型与已有不一致 | 保持已有类型 |
not a KV type service | 对非 kv 型 app 操作 KV | 确认目标 app 的 config_type=kv |
there are duplicate keys ... | 同一批量请求内 key 重复 | 去重后重试 |
there is a release in publishing currently | 已有版本正在上线 | 等待当前上线完成后再发布 |
release ... is deprecated | 目标版本已废弃 | 换未废弃版本，或重新 CreateRelease |
exceeded the limit | 配置项数超过上限（默认 2000） | 清理无用 KV 后重试 |
page.limit value should >= 1 | 列表接口未传 limit 且 all≠true（limit 默认为 0） | 传 all:true 全量，或显式 limit(1–1000) |
invalid page.limit max value: 1000 | limit 超过单页上限 | limit ≤ 1000，需要更多时用 start 翻页或改 all:true |
release ... already exists | 版本名与同 app 已有版本重名 | 换一个不重名的 name（递增类在最大序号上 +1） |
场景化示例（F-006）
以下为调用序列示意（bizId/appId 用占位符，实际以获取到的值为准）。
1) 新增一个 json 配置并全量发布
Config_ListAppsBySpaceRest {bizId, all:true} → 从结果中找 config_type=kv 的目标 app，取其 appId // 列表接口带 all:true
Config_CreateKv {bizId, appId} body: {key:"feature_flags", kvType:"json", value:"{\"beta\":true}"}
Config_ListReleases {bizId, appId, all:true} // 捕获历史命名规则，据此建议版本名并询问用户
Config_CreateRelease {bizId, appId} body: {name:"<用户确认的版本名>"} → releaseId // 生成版本
Config_Publish {bizId, appId, releaseId} body: {all:true} // 全量发布
Config_ListReleasedKvs {bizId, appId, all:true} // 验证已发布内容（列表接口带 all:true）
2) 批量导入 KV（覆盖式，replaceAll）
Config_BatchUpsertKvs {bizId, appId} body: {replaceAll:true, kvs:[{key,kvType,value}, ...]}
Config_CreateRelease {bizId, appId} body: {name:"v-import-1"} // 拿 releaseId
Config_Publish {bizId, appId, releaseId} body: {all:true}
3) 删除一个只知道 key 的 KV
Config_ListKvs {bizId, appId, key:["obsolete_key"], all:true} // key 为数组；列表接口带 all:true；拿到该 KV 的 id
Config_DeleteKv {bizId, appId, id} // 按 id 删（草稿态）
Config_ListReleases {bizId, appId, all:true} // 捕获历史命名规则，建议版本名并询问用户
Config_CreateRelease {bizId, appId} body: {name:"<用户确认的版本名>"} → releaseId // 生成版本
Config_Publish {bizId, appId, releaseId} body: {all:true} // 发布后才对客户端生效
4) 更新一个 secret 配置
Config_UpdateKv {bizId, appId} body: {key:"db_password", value:"<new>", secretType:"password", secretHidden:true}
// 注意：UpdateKv 不能改 kvType；secret 必填 secretType
Config_CreateRelease {bizId, appId} → releaseId
Config_Publish {bizId, appId, releaseId} body: {all:true}
5) 灰度发布到指定分组
Config_CreateRelease {bizId, appId} body: {name:"v-gray-1"} → releaseId
Config_Publish {bizId, appId, releaseId} body: {all:false, grayPublishMode:"publish_by_groups", groups:[<groupId>, ...]}
// 或按 labels：grayPublishMode:"publish_by_labels", labels:[{...}], 可选 groupName
说明
本文的领域约束与操作规范可能随 bscp 版本演进而变化。实际以工具调用的返回结果和报错信息为准；
遇到与本文不一致的情况，按报错对照表处置或咨询 bscp 平台。
