---
name: numa-oss-access
metadata:
  version: "1.6.1"
description: 使用 Numa CLI 通过 Keycloak 用户或 client_credentials 机器身份发现 OSS Grant、申请短期 STS，并按目录、元数据和日期搜索、排序，以及生成短效下载链接、安全列举、检查、下载、上传或删除授权范围内的 Aliyun OSS 对象。用户提到 Numa OSS、OSS Grant、STS、Bucket/Prefix 文件读写、CLI 对接 OSS、机器 client 访问 OSS，或排查相关 401/403/503 时使用。
---

# Numa OSS Access

## 加载基础 Skill（必读）

本 Skill 依赖同来源的 `numa-cli@1.4.1`。加载基础 Skill 的任务入口规则；缺失时按 [依赖恢复指引](references/cli-bootstrap.md) 处理；用户尚未授权安装时询问，已获授权不重复确认。命令示例使用 npx，无需全局安装；执行时将示例中的 `latest` 换为基础 Skill 已确认的具体版本，同一任务沿用同一入口。

把 Numa 平台当作身份、Grant 和 STS 的受控入口，把 `npx -y @numa-tech/numa@latest oss` 当作对象操作入口。CLI 获得短期 STS 后通过 `ali-oss` 直连 OSS；不要改用长期 AccessKey、原始平台接口、`ossutil` 或自写 SDK 脚本绕过现有边界。

## 查询：一次任务调用

查询目录、文件、日期或元数据时，直接调用已连接 MCP 的 `numa_oss_query`。没有 Numa MCP 且已有固定 CLI 入口时使用：

```sh
npx -y @numa-tech/numa@latest task run oss.query --input-file /ABS/query.json --json
```

JSON 文件或 MCP 参数使用同一结构，例如：

```json
{
  "bucket": "example-bucket",
  "prefix": "reports/",
  "suffix": ".pdf",
  "sort": "modified",
  "order": "desc",
  "limit": 20,
  "scan_limit": 1000,
  "fields": ["key", "sizeBytes", "lastModified"]
}
```

替换用户指定的真实 bucket/prefix。也可传已确认的 `grant_id`，省略 `bucket`；执行器按平台配置的 `accessPriority` 选择 Grant、申请 STS、核对精确范围并执行有界搜索。五级从高到低为：最高 `HIGHEST`、高 `HIGH`、普通 `NORMAL`（默认）、低 `LOW`、最低 `LOWEST`；同级按 Grant ID 升序。多个匹配自动依次尝试；列表中没有目标 bucket 时，按顺序申请候选的新会话，只有会话覆盖目标 bucket/prefix 才访问 OSS。已知 bucket 的 prefix 不匹配时不扩大候选范围。显式传入 `grant_id` 时不切换 Grant。查询字段沿用 `numa_oss_search` 的 snake_case schema，详见 [搜索语义与 MCP](references/search-and-mcp.md)。

不要在正常 task 前调用版本、命令目录、help、auth/config、grants 或 session。工具能力在安装/初始化时确定；`npx -y @numa-tech/numa@latest task inspect oss.query --json` 只用于 schema 查询或诊断。新 Skill 不代表现有 npm CLI 已支持新任务入口；已连接 MCP 缺工具时报告模块/版本缺口，不自动改用终端或复制 MCP 秘密。

`succeeded` 表示查询完成，仍须报告 `complete`、`truncated`、`resultsLimited` 和扫描范围；`needs_input` 按缺项或候选请求补充；`blocked` 报告脱敏配置、授权或范围错误；`pending` 不认定完成。不要把 `LastModified` 称为创建时间。MCP 直接使用 `npx -y @numa-tech/numa@latest serve` 的用户/机器身份与环境，不切换身份。

## 临时下载链接

用户要求为选中文件或文件夹生成短效下载链接时，读取 [临时下载链接](references/download-links.md)，使用 `numa_oss_download_links` 或当前已选定 CLI 的 `oss download-link`。文件夹返回逐文件清单；硬上限 100 个文件，超量直接拒绝，不自动拆批。默认 5 分钟且受 STS 剩余有效期限制；交付时注明实际到期时间。

## 多个匹配授权：完成查询后询问优先级

成功结果包含 `data.priority_advice` 时，先交付本次查询结果，再列出 `matching_grants` 的 Grant ID、当前五级优先级及本次使用的 `selected_grant_id`，询问：“是否需要调整这些 Grant 的访问优先级，确定后续优先使用哪一个？”本次任务保持成功，不改成 `needs_input`，不等待回答才展示结果。同一目标在连续分页或同一任务中只提示一次；用户选择保持现状后不重复询问。

`basis:grant_metadata` 表示平台授权配置匹配；只有 `access_status:succeeded` 的 Grant 在本次实际访问成功，`not_tested` 不能称为“已验证可访问”。失败候选见 `attempts`，不能列为可访问选项。无需为了提示额外查询 Grant、申请 STS、测速或重复读取文件；没有 advice 不推断存在其他可用授权。调整顺序可帮助优先选用常用授权、减少失败回退，不能承诺吞吐或延迟提升。

用户希望调整时，明确其选择的 Grant ID 和目标级别，再引导到 DevOps Platform 的“OSS 平台访问授权”编辑“访问优先级”。该优先级影响该 Grant 覆盖的其他资源，不能当作当前路径的独立偏好。仅询问意愿或用户未回复不代表授权修改；当前查询工具不提供优先级写入，不能声称已保存。

## 其他对象操作

需要 stat、下载、上传、删除、管理员初始化，或用户明确选择旧版兼容流程时，读取 [对象操作与管理员边界](references/object-operations.md)。已连接 MCP 时保持服务身份，使用相应工具，不为复用 CLI 示例自动改走终端。

查询任务不读取对象操作的整套前置流程。候选级 403/404/409/503、会话范围不匹配和操作权限不足由执行器按优先级尝试下一候选；401、无效响应或非预期错误立即停止。成功查询即结束，空列表也不切换授权。自动候选超过 100 项返回 `needs_input`，请求指定 Grant；旧运行时返回歧义也按其候选询问，不自行模拟新流程。任务最终返回错误时报告脱敏原因和 `attempts`，不能切换身份、扩大 Grant、修改 RAM Policy 或自动 bootstrap。Task 查询不下载对象；对象写入仍须用户明确授权精确目标。

最终报告任务返回的 Grant、`access_priority`（若有）、bucket/prefix、查询范围、完整性和实际结果，不为补齐报告追加版本或身份探测。