| name | bscp-file-config |
| slug | bscp-file-config |
| version | 2.0.0 |
| description | bscp（蓝鲸基础配置平台）文件型配置只读查看指引。为挂载了 bk-bscp-prod-file-manage 的模型补充
MCP 工具 schema 表达不了的领域知识：文件型（config_type=file）配置的领域模型、只读查看编排、
参数获取、字段级业务约束与报错处置，帮助模型正确完成"定位服务 → 查询配置项元数据 →
取下载 URL 查看文件内容"闭环。
Use this skill whenever the user asks to 查看 bscp 文件配置, 看某文件型服务的配置,
查询文件配置项, 看文件配置内容, 取文件下载 URL 查看文件内容,
or invokes bk-bscp-prod-file-manage 的文件型配置项查询 / 文件下载 URL 工具。
|
| metadata | {"requires":{"mcps":["bk-bscp-prod-file-manage"]}} |
bscp 文件型配置只读查看指引
定位
本 skill 只补充 MCP schema 表达不了的知识（跨工具编排、字段间业务约束、错误语义、领域模型），
不重复 MCP 工具已有的单字段描述——填参时字段含义以 MCP 工具 schema 为准。文中的业务
约束来自 bscp 服务端的实际校验规则，会随 bscp 版本演进；若与调用返回的报错不一致，以服务端返回为准。
适用范围：只读查看 config_type=file 服务的文件型配置——定位服务 → 查询配置项元数据 →
用下载 URL 查看文件内容。本 skill 只支持查看，不支持任何写操作：不做配置项增删改、
不做批量导入、不生成版本、不发布/灰度发布。文件内容上传与配置项变更、发版仍走 UI / SDK。
前置条件
本 skill 依赖 bk-bscp-prod-file-manage（蓝鲸 API 网关提供的 bscp 文件型专用 MCP Server）暴露的工具。
只读查看所需的工具（服务定位、文件配置项查询、下载 URL）都由这一个 MCP 提供，与 KV 型的
bk-bscp-prod-server-mcp 相互独立。开始操作前必须先确认这些工具已可用：
- 检查当前会话是否已挂载
bk-bscp-prod-file-manage，能看到 Config_ListAppsBySpaceRest /
Config_GetAppByName 等服务定位工具。
- 只读查看还需要「文件配置项查询」工具与「文件下载 URL」工具，同样由
bk-bscp-prod-file-manage
提供。这些工具须在蓝鲸 API 网关注册后才会出现在 MCP 工具集里。
- 若某个工具不存在：不要臆造工具名或伪造调用结果，直接告知用户"未检测到
bk-bscp-prod-file-manage
或对应工具，可能尚未挂载 / 在网关注册"，并说明缺失的能力，然后停下等待用户确认接入，或退化为对可用工具的编排。
- 工具可用后再按后续章节执行。
说明：文件下载 URL 接口只返回临时预签名 URL 与有效期，不透传文件字节；网关注册后自动纳入
bk-bscp-prod-file-manage 工具集，用于查看文件内容。
交互引导（面向不熟悉闭环的用户）
用户往往只抛一个模糊意图（如"看看某文件服务的配置 / 看下文件内容"）而不知道要给哪些参数。
不要一次性罗列一堆参数把用户劝退，也不要臆造参数；按下面的方式分步反问，一次只问当前缺的一个关键信息。
通用引导步骤（任何意图先做）
- 确认业务 ID（bizId）：用户没给就先问"请提供业务 ID（bizId）"。
- 确认服务名 → 解析 appId：拿到服务名后调
Config_GetAppByName（或先 Config_ListAppsBySpaceRest
让用户从列表里挑）得到 appId，并校验 config_type=file；若不是 file 型（如 kv 型），
直接告知"该服务不是文件型服务"并停止（R-002）。
- 参数齐了再进入对应意图的动作；能从上下文推断的（如上一步已拿到的 appId）不要重复问。
两类查看意图的最小引导
| 用户说 | 最少还需要问 | 拿齐后动作 |
|---|
| 查询文件配置 / 看某文件服务配置 | bizId、服务名 | 列草稿态配置项或已发布配置项，展示 sign / path / name / byte_size |
| 查看某个文件的内容 | bizId、服务名、目标内容 sign（或先列配置项找到 sign） | 用下载 URL 工具取临时 URL，交给用户直连存储下载查看 |
遇到写操作诉求如何处置
若用户要求新增/更新/删除配置项、批量导入、生成版本、发布/灰度发布等写操作：
本 skill 不执行这些操作。直接说明"当前文件型 skill 仅支持查看，写操作请走 UI / SDK 或对应的写工具"，
不要臆造或调用写工具，也不要伪造执行结果。
⚠️ 核心规则
- 本 skill 仅只读查看：不做配置项增删改、批量导入、生成版本、发布/灰度发布等任何写操作。
- 文件型操作只适用于
config_type=file 的 app；对 KV 型 app 操作文件接口会报错，务必先校验（R-002）。
- 下载 URL 只返回临时预签名 URL 与有效期，不透传文件字节；由用户用该 URL 直连存储下载查看，
避免大文件穿透管理面/网关。
- 查看内容依赖已上传的内容 sign：sign 指向的内容须已由 UI/SDK 上传；未上传会报"内容未上传"，
此时说明内容尚未上传，不产生指向空对象的引用（R-004）。
领域模型速览（F-001）
biz（业务） → app（服务，config_type=file） → config_item（配置项：sign + 元数据） → release（不可变版本快照）
│
content（内容对象，按 sign 标识，已上传，只读引用）
- 文件型配置项由「内容 sign（SHA256）+ 元数据（path / name / byte_size / 权限等）」组织，
区别于 KV 型的 key / kvType / value。
- 草稿态配置项与已发布配置项都可查询；本 skill 只读，不改变任何状态。
- content 是对象存储里以 sign 标识的已上传文件内容，本 skill 只读引用，不上传、不透传字节。
只读查看调用编排（F-001 / F-006）
标准查看链路：
- 定位服务 → 拿
appId
- 已知业务：
Config_ListAppsBySpaceRest（按 bizId 列 app）
- 已知服务名：
Config_GetAppByName
- 从返回结果的
config_type 字段辨别 file 型 app，非 file 型直接停止（R-002）
- 查询配置项（F-001）
- 草稿态配置项列表 / 详情、已发布配置项列表（读 sign / path / name / byte_size）
- 需要查看某文件内容时，先从配置项列表拿到目标内容 sign
- 查看文件内容（F-006）
- 用文件下载 URL 工具对目标内容 sign 取临时预签名下载 URL（响应只含
download_url +
expire_seconds，不含文件字节），再由用户用该 URL 直连存储下载查看。
参数获取
bizId：来自蓝鲸平台上下文（CMDB 业务 / 空间）或请求头 X-Bkapi-Biz-Id；MCP 不提供列 biz 的工具，需由用户/上下文给出。appId：通过 Config_ListAppsBySpaceRest（按 bizId 列 app）或 Config_GetAppByName（已知服务名）获取。- 辨别 file 型 app：从上述工具返回结果里读
config_type 字段，取 config_type=file 的 app。
- 内容
sign（SHA256，64 位十六进制）：从配置项列表 / 详情中读取，用于取下载 URL 查看内容。
报错 → 原因 → 处置
| 报错关键字 | 原因 | 处置 |
|---|
内容未上传 / file content not uploaded / file content not found | 引用的 sign 尚未上传到对象存储 | 说明该内容尚未上传，无法取下载 URL 查看；上传走 UI/SDK |
not a file type service / 服务类型不符 | 对非 file 型 app 操作文件接口 | 确认目标 app 的 config_type=file（R-002） |
| 鉴权失败 / 无权限 | 未通过业务/服务（内容）鉴权 | 确认对该 biz/app 有权限；鉴权失败不会返回下载 URL（不泄露） |
场景化示例
以下为调用序列示意（bizId / appId / sign 用占位符，实际以获取到的值为准）。
工具名以当前 MCP 工具集实际暴露的为准；文件配置项查询与下载 URL 工具须已在网关注册。
1) 查看某文件型服务的配置项列表
Config_ListAppsBySpaceRest {bizId} → 从结果中找 config_type=file 的目标 app，取其 appId
列出文件配置项 {bizId, appId} → 展示每项的 sign / path / name / byte_size
2) 查看某个文件的内容
Config_GetAppByName {bizId, 服务名} → 校验 config_type=file，取 appId
列出文件配置项 {bizId, appId} → 找到目标文件的内容 sign
下载URL工具 {bizId, appId, sign} → {download_url, expire_seconds:3600} // 只拿 URL, 不透传字节
// 由用户用 download_url 直连存储下载查看文件内容
3) 引用的内容未上传的处置
下载URL工具 {..., sign:"<未上传的 sha256>"} → 报"内容未上传"
→ 告知用户：该内容尚未上传，无法查看；上传走 UI/SDK
文件型 vs KV 型差异（速查）
| 维度 | 文件型（本 skill，只读查看） | KV 型（见 bscp-kv-config） |
|---|
| 配置对象 | config_item：sign（SHA256）+ 元数据（path/name/byte_size/权限） | kv：key / kvType / value |
| 类型校验 | 操作前校验 config_type=file | 操作前校验 config_type=kv |
| 支持能力 | 仅查看：查询配置项元数据 + 下载 URL 查看内容 | 查询 + 增删改 + 发布 |
| 查看内容 | 用下载 URL 接口取临时 URL 直连存储查看（不透传字节） | Config_ListReleasedKvs 直读已发布值 |
说明
本文的领域约束与操作规范可能随 bscp 版本演进而变化。实际以工具调用的返回结果和报错信息为准；
遇到与本文不一致的情况，按报错对照表处置或咨询 bscp 平台。
