@numa-tech/numa 1.20.4 → 1.20.5

package/skills/numa-oss-access/references/download-links.md

@@ -0,0 +1,42 @@
+# 短效下载链接
+
+用户明确要求为选中的文件或文件夹生成临时下载链接时使用。本操作把限时下载能力交给链接持有者；不把普通查询或本地下载请求解释为生成分享链接的授权。
+
+沿用用户选择的身份和明确 Grant，不自动切换授权。单文件需要 `oss:GetObject`；文件夹还需要 `oss:ListObjects`，递归展开为逐文件链接清单，不打 ZIP、不写临时对象。
+
+## 已连接 MCP
+
+使用实际已安装的 `numa_oss_download_links`，例如：
+
+```json
+{
+  "grant_id": 123,
+  "entries": [
+    { "key": "reports/weekly.pdf", "directory": false },
+    { "key": "reports/attachments/", "directory": true }
+  ],
+  "expires": 300,
+  "confirmed": true
+}
+```
+
+替换真实 Grant 和用户选定路径。`confirmed:true` 表示用户已请求生成这些目标的链接，无需重复询问许可。缺少此工具时报告版本/模块缺口；已连接 MCP 不自动改走另一个身份的终端。
+
+## 已选定 CLI 入口
+
+```sh
+npx -y @numa-tech/numa@latest oss download-link GRANT_ID EXACT_FILE_KEY --expires 300 --json
+npx -y @numa-tech/numa@latest oss download-link GRANT_ID FOLDER_PREFIX/ --recursive --expires 300 --json
+```
+
+沿用当前任务固定版本；上例 latest 不是发布状态承诺。文件夹必须末尾 `/` 并显式 `--recursive`。CLI 一次接受一个目标，网页和 MCP 可以多选。
+
+## 数量、时效与结果
+
+- **硬上限 100 个文件**，包含递归子文件，重叠选择去重。发现超过上限即拒绝，说明未交付链接清单，提示缩小范围或使用批量下载；不得自动拆成多批绕过上限。极多空目录或异常分页也会触发有界扫描限制。
+- 全部对象 HEAD 权限检查通过后才签名。任一失败就报告错误，不宣称其余目标已有完整可用清单。
+- 默认 300 秒，允许 60–3600 秒，实际不得超过 STS 剩余有效期并留安全余量；以每条 `expiresAt` 为准。续期不会延长旧链接，不能保证所有文件在有效期内下载完。
+- 成功返回 `data.fileCount`、`data.links`、整体最早 `expiresAt`。向用户交付所需链接、文件名和实际到期时间，说明持有者可下载。只在用户要求的输出中交付，不自动发消息或持久化到知识库、日志、Skill 或培训材料。
+- 显式生成链接的结果有意保留完整 URL；其他工具的错误、凭据和普通元数据仍脱敏。不要索取或打印 AccessKeySecret、完整 STS 响应，也不要改写签名参数。
+
+网页：选中文件/文件夹 →「临时下载链接」，或右键同名菜单；选择时效并生成后可复制单条或全部链接。关闭弹窗清除页面中的链接内容。

package/skills/numa-oss-access/references/search-and-mcp.md

@@ -1,6 +1,6 @@
 # OSS 列举、搜索与 MCP
 
-正常查询优先调用主 Skill 的 `numa_oss_query` / `task run oss.query`，直接携带下述筛选条件，由执行器解析唯一 Grant。低层 CLI 示例需要 CLI >=1.15.0；仅在初始化、诊断或用户选择兼容路径时核对帮助与工具清单。所有例子的 Grant 和 prefix 必须来自当前身份的真实授权，不能原样执行占位值。
+正常查询优先调用主 Skill 的 `numa_oss_query` / `task run oss.query`，直接携带下述筛选条件，由执行器按主 Skill 定义的五级优先级选择 Grant。低层 CLI 示例需要 CLI >=1.15.0；仅在初始化、诊断或用户选择兼容路径时核对帮助与工具清单。所有例子的 Grant 和 prefix 必须来自当前身份的真实授权，不能原样执行占位值。
 
 ## 目录和分页
 
@@ -50,15 +50,20 @@ prefix/delimiter 由 OSS 服务端执行，其余条件属于 CLI 有界扫描
 
 | 工具 | 用途 |
 | --- | --- |
-| `numa_oss_query` | 新任务入口：精确 bucket/prefix 或 grant_id，内部唯一 Grant 解析与有界搜索 |
+| `numa_oss_query` | 新任务入口：精确 bucket/prefix 或 grant_id，内部按优先级选择 Grant 与有界搜索 |
 | `numa_oss_grants` | 解析当前身份可用的精确 Grant |
 | `numa_oss_list` | 单页 prefix/目录列表，marker 延续 |
 | `numa_oss_search` | 与 CLI 相同的筛选、扫描和排序语义 |
 | `numa_oss_stat` | 标准头与自定义元数据 |
+| `numa_oss_download_links` | 用户要求时生成短效链接，文件夹展开清单；硬上限 100 个文件 |
 | `numa_oss_download` | 写入服务机器的新文件，`output_path` |
 | `numa_oss_upload` | 读取服务机器的 `file_path` 并上传 |
 | `numa_oss_delete` | 删除精确对象 |
 
-低层 MCP 使用 `grant_id`；新任务 query 还允许精确 `bucket` + `prefix`，歧义返回 `needs_input`。搜索参数为 `scan_limit`、`directories_only`、`modified_after` 等 snake_case；`fields` 是数组，`meta` 是 KEY=VALUE 数组。禁止把 CLI 参数带连字符原样当成 MCP 字段。
+低层 MCP 使用 `grant_id`；新任务 query 还允许精确 `bucket` + `prefix`，多个匹配按 `accessPriority` 从高到低尝试，同级按 Grant ID 升序；候选超过 100 项返回 `needs_input`。搜索参数为 `scan_limit`、`directories_only`、`modified_after` 等 snake_case；`fields` 是数组，`meta` 是 KEY=VALUE 数组。禁止把 CLI 参数带连字符原样当成 MCP 字段。
+
+成功结果的 `priority_advice` 用于完成查询后询问用户是否调整优先级；按主 Skill 的“多个匹配授权”规则展示，不额外探测授权或阻塞本次结果。
+
+优先级由 DevOps Platform 的授权编辑页面设置，API 字段为 `accessPriority`；查询输入不接受临时覆盖优先级。旧平台未返回此字段时视为 `NORMAL`。这项自动选择只作用于 query，低层工具仍使用明确的 `grant_id`。
 
 下载、上传和删除要求 `confirmed:true`；上传覆盖另需 `overwrite:true`。授权、范围和未知结果处理与主 Skill 相同。不得通过工具调用测试消息发送或对象写入来验证连接；没有用户授权就只核对工具清单和必要只读查询。