google-cloud-storage-okf

用途

google-cloud-storage-okf 是 Google Cloud Storage 插件中的一个实验性技能，用于高效导航、检查和按字节范围提取非结构化或半结构化的 GCS（gs://）对象内容。它通过渐进披露（progressive disclosure）方式工作，避免把整个文件读入或倾倒进上下文窗口。

其核心思路基于 Open Knowledge Format（OKF）：将自描述、面向 AI 的语义知识直接附加到数据资产上，而不改动原始内容。在对象存储场景中，OKF 清单写入 blob 的 GCS Object Context（custom_contexts），不产生分离的旁挂文件。

主要能力

三层访问模式：Tier 0 的 peek 返回高层摘要卡片，用于快速判断相关性；Tier 1/2 的 list_regions 返回语义目录，列出连续区域的包含式字节范围、标题和关键词；Tier 2/3 的 expand 按区域边界精确读取指定字节切片。
生成层：write_okf 将新生成的 OKF 索引持久化到 GCS Object Context，键包括 okf.sum、okf.r.000、okf.created_at、okf.src_generation 等。
陈旧检测：若底层对象 generation 变化，peek、list_regions、expand 会返回陈旧索引警告。
诊断信息：缺少 OKF 时返回 OKF_NOT_FOUND，附带 Object Context 剩余容量、已有上下文、自定义元数据和对象属性，便于生成索引时参考。
SDK 双版本兼容：新版本 SDK 若暴露 ObjectContexts、ObjectCustomContextPayload 等类型类，则直接使用并读写 blob.contexts；旧版本则退回到直接注入 REST JSON 载荷（blob._properties["contexts"] / blob._patch_property）并标记 blob._changes，由 blob.patch() 发出标准 PATCH 请求。读取时同时检查 blob.contexts 与 blob._properties["contexts"]，保证兼容性。

需要区分 GCS Object Context 与传统 Custom Metadata（metadata / x-goog-meta-*）：前者是面向 AI 知识的专用结构化上下文层，OKF 键写入此处；后者是通用用户标签与旧属性，两者相互独立。

使用方式

所有 OKF 操作都由 google-cloud-storage-okf MCP 服务器提供。开始任务前必须确认 peek、list_regions、expand、write_okf 四个工具均已在工具列表中（可带 harness 特定前缀）；任一缺失则不应启动流程，需告知用户服务器未注册并停止。禁止直接导入或执行 scripts/core.py、scripts/mcp_server.py 来绕过 MCP。

一次性配置步骤：

将完整技能目录（含 scripts/）安装到 harness 发现技能的位置，仅有 SKILL.md 的副本无法运行服务器。
用将运行服务器的 python3 安装依赖：

python3 -m pip install mcp google-cloud-storage

认证并选择项目：

gcloud auth application-default login
gcloud config set project <project-id>

也可仅在服务器 env 块中传入项目。

用绝对路径 <abs skill_dir> 和同一 python3 在 MCP 客户端注册服务器命令，然后重启客户端：

{
  "mcpServers": {
    "google-cloud-storage-okf": {
      "command": "python3",
      "args": ["<abs skill_dir>/scripts/mcp_server.py"],
      "env": {"GOOGLE_CLOUD_PROJECT": "<project-id>"}
    }
  }
}

若连接失败，可手动运行该命令查看 traceback。遇到凭据过期、缺少项目或 401/403 权限错误时，应原样转述错误并给出对应修复（重新登录、设置项目、授予对象读取权限及 write_okf 所需的 storage.objects.update），不要自行修改用户 gcloud 配置或凭据，也不要改用 gcloud storage、gsutil 等绕过。

索引生成与确认门

对小于 20 KB 的对象，若用户只是读取、搜索或诊断，应直接用 expand(gs_uri, 0, size - 1) 读取，不生成 OKF。对 ≥ 20 KB 且缺少索引（或索引陈旧）的对象，除非用户已明确要求或批准生成，否则应先说明对象大小与剩余 Object Context 容量，提出一次是否生成索引的是/否问题并结束本轮；用户同意后才扫描对象、划分语义区域并调用 write_okf。若用户提示已明确要求生成或授权，或此前已确认，或作为批量索引的子代理在获授权后被调用，则可直接执行。

生成时，应利用诊断返回的已有上下文、自定义元数据和对象属性（如 environment、category、log-type、content_type、size）丰富摘要、区域标题与关键词。对大中型对象，按章节、日志阶段、数据表或关键帧区间等语义边界切分，不要生硬按段落切分；同构日志可按时间戳或处理里程碑切分。摘要建议控制在约 200–250 字节以内。区域 JSON 需满足：偏移为 0 起始整数，0 <= start_byte <= end_byte < 对象大小，按 start_byte 升序且不重叠（下一 start_byte 至少为上一 end_byte + 1）；write_okf 会严格校验并拒绝倒置、负数、乱序、越界或重叠范围。

批量处理多个未索引对象时，可先列出候选 URI，一次性确认后分批（如每个子代理 5–10 个对象）通过 invoke_subagent 并行分发，各子代理执行 peek、检查属性、生成并写入索引的流程。

适用场景

在数 GB 的文档、日志、数据导出等对象中先定位章节再按需读取片段。
为多个对象建立可复用的语义目录，供后续代理低成本导航。
日志或结构化转储按时间或处理阶段切分检索。
需要在不复制、不修改原始对象的前提下附加 AI 可读知识。

限制

技能标注为实验性；Object Context 容量有限（示例中总容量 25600 字节），超出容量会写入失败。
必须通过已注册的 MCP 服务器运行，依赖 mcp 与 google-cloud-storage 库，并需要有效的 Application Default Credentials 和项目。
索引陈旧时需重新生成；生成过程会消耗时间和 token。
写入需要 storage.objects.update 权限；读取需要对象读权限。
关于定价、性能量化、支持平台等信息，资料暂未提供。

技能介绍

用途

主要能力

使用方式

索引生成与确认门

适用场景

限制