安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install alibabacloud-oss-multipart-upload-diagnosis
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 alibabacloud-oss-multipart-upload-diagnosis。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

本 Openclaw Skills 诊断工具有助于排查停滞、失败或在完成前中断的大文件上传，以及占用存储空间的未完成分片。它会检查调用者身份、定位 bucket、列出未完成的上传、验证分片大小和并发设置，并使用返回的证据指导排查。
该工作流严格为只读模式：不会中止上传、修改对象或更改 bucket 配置。Openclaw Skills 会报告排查结果和手动下一步操作，区分可能的服务端、客户端和网络原因，同时清晰记录不可用的证据。
Alibaba Cloud OSS Multipart Upload Diagnosis 应用场景
大文件分片上传卡在 0% 或没有任何进度。
上传中断，你需要检查分片或规划断点续传。
大文件上传重复失败，你需要验证分片大小、分片数量或并发数。
bucket 显示为空，但未完成的分片可能正在占用存储空间。
你需要基于证据进行排查，同时确保诊断操作不会修改 OSS 数据。
配置或使用问题需要根据官方 OSS 文档进行核实。
Alibaba Cloud OSS Multipart Upload Diagnosis 工作原理
收集 bucket 名称，以及可用的文件大小、症状、分片大小、并发数、前缀和地域（region）。脚本会报告缺失的必要输入，而不是盲目猜测。
运行身份辅助工具以衍生调用者 UID 用于追溯。凭证来自 Alibaba Cloud 的默认凭证链；该 skill 绝不会请求或打印 AccessKey 凭证。
运行分片诊断入口脚本。它会检查分片参数，通过 GetBucketInfo（带有 ListBuckets 回退机制）定位 bucket，并使用只读的 ListMultipartUploads API 列出未完成的上传。
审查结构化报告，包括状态、分片详情与保留时间、参数检查、建议、错误和下一步操作。失败的证据获取调用会被报告为降级（degraded），而不是被视为不存在问题的证明。
使用诊断决策树进行归因。存在的分片表明上传未完成；未列出分片则引导排查转向客户端或网络证据，例如 Request ID 和客户端日志。
展示基于证据的排查结果并披露自动填充的值。如果适合进行清理，仅提供手动指引；该 skill 绝不执行任何写入操作。
Alibaba Cloud OSS Multipart Upload Diagnosis 配置指南
安装声明的 Python 依赖项，并确保 Alibaba Cloud CLI 已安装并通过身份验证。CLI 版本必须为 3.3.3 或更高。凭证通过默认凭证链解析；切勿向该 skill 提供 AK/SK。

From the skill directory

pip install -r scripts/requirements.txt

Check the CLI version; upgrade if needed

aliyun version
aliyun upgrade --yes

Configure the CLI default credential chain if it is not already configured

aliyun configure

Optional identity pre-check (informational traceability only)

python3 scripts/sts_token.py

Diagnose a multipart upload

python3 scripts/multipart_upload_diagnosis.py
--bucket
--file-size 40GB
--symptom interrupted
--region bucket 名称是必需的；文件大小和症状是可选的但很有用。其他支持的选项包括 --part-size、--concurrency、--prefix、--endpoint 和 --region。对于配置或使用问题，可将客户的原话通过 --question "" 传入，以启用官方文档核实。脚本会输出结构化报告以及 STATUS/NEXT_ACTION 契约行。清理和其他写入操作均在 skill 的执行边界之外。
Alibaba Cloud OSS Multipart Upload Diagnosis 数据架构与分类体系
该 skill 的脚本和参考资料按以下方式组织诊断：
Location or report field Purpose
scripts/multipart_upload_diagnosis.py 必需的诊断入口点；收集参数、bucket 位置、分片列表和建议证据。
scripts/sts_token.py 通过 Alibaba Cloud CLI 默认凭证链检查调用者身份；UID 是可追溯性标签。
scripts/_oss_client.py 共享的 OSS 客户端行为，包括请求追踪、重试和降级错误处理。
scripts/_doc_lookup.py 用于 --question 验证环节的可选官方文档查询。
scripts/requirements.txt Python 依赖，包括 oss2 和 Alibaba Cloud 凭证链库。
references/multipart-playbook.md 分片限制、归因指引和客户端证据清单。
references/fragment-cleanup-guide.md 分片计费上下文和手动清理选项；该 skill 不会执行任何清理。
references/ram-policies.md 诊断所需的最小只读 RAM 权限。
status, verdict/findings 整体结果和诊断摘要。Status 可能是 OK、DEGRADED 或 FAIL。
fragments 列表返回的未完成上传证据，例如 object key、upload ID、初始化时间和保留时间。
parameter_check, recommendations 基于所提供输入的验证结果以及建议的分片大小或并发设置。
auto_filled 由脚本衍生或设为默认的值，必须在最终响应中披露。
errors[], next_action 当证据不完整或缺失必要输入时提供的结构化错误详情和下一步操作。
doc_verification 请求时提供的官方文档查询结果；仅引用 docs 中返回的 URL。
OSS 请求为纯只读：GetBucketInfo、ListBuckets 和 ListMultipartUploads，加上调用者身份检查。每次运行的 session ID 都会附加到请求中以实现可观测性。分片检查考虑了文档记载的限制：最多 10,000 个分片，分片大小从 100 KB 到 5 GB（最后一个分片允许更小），以及最高 48.8 TB 的分片对象。
Alibaba Cloud OSS Multipart Upload Diagnosis 高级特性
强制执行只读边界：Agent 不得生成或执行 AbortMultipartUpload、PutObject、UploadPart、CompleteMultipartUpload、删除、ACL、策略或生命周期变更。
要求将打包的脚本作为诊断入口点，而不是使用临时（ad hoc）SDK、ossutil 或 curl 调用。
使用结构化证据报告以及明确的
OK
、
DEGRADED
FAIL
结果，并在查询失败时提供警告和下一步操作。
在共享客户端层重试选定的瞬态服务错误，并尽可能保留部分证据。
使用每次运行的 session ID 和特定于 skill 的 User-Agent 来关联请求，以实现可观测性。
支持过滤器和排查输入，例如症状、前缀、endpoint、地域（region）、文件大小、分片大小和并发数。 --question 时，可以针对 OSS 官方文档验证配置或使用解答；引用必须来自脚本返回的文档结果。
仅提供手动分片清理指引，并将超出生效边界的问题（如计费详情或单次请求上传错误）路由至相应的专家工作流。

name: alibabacloud-oss-multipart-upload-diagnosis description: | Read-only diagnostics for OSS multipart upload. Use when a multipart
upload is stuck or interrupted, a large file upload fails, or
multipart fragments occupy storage. Finds fragments via read-only
ListMultipartUploads, checks part size/concurrency limits,
attributes server/client/network causes; cleanup guidance is
manual-only. Triggers: "multipart upload stuck", "upload stuck at 0%", "resume interrupted upload", "multipart fragments occupy storage", "large file upload fails", "fragment cleanup", "resumable upload", "breakpoint resume". Do NOT use for single-request upload errors (use
alibabacloud-oss-transfer-error-code-diagnosis), billing (use
alibabacloud-oss-billing-diagnosis), endpoints (use
alibabacloud-oss-endpoint-internal-diagnosis), signed URL V4 (use
alibabacloud-oss-presigned-url-v4-diagnosis), browser/mini-program
direct upload with CORS (use
alibabacloud-oss-browser-upload-cors-diagnosis).

OSS Multipart Upload Diagnosis

Diagnose Alibaba Cloud OSS large-file upload problems: "my 40GB backup multipart upload is stuck at 0%", "the upload was interrupted halfway, how do I resume it", "uploading a large file keeps failing", "the bucket seems empty but storage capacity is occupied by multipart fragments".

Core approach: verify the caller identity, locate the bucket's real region with the read-only GetBucketInfo control-plane query (ListBuckets fallback), enumerate unfinished multipart upload events with the read-only ListMultipartUploads to identify fragments, check the user's part size / concurrency against the official OSS multipart limits, and attribute stuck / interrupted / failed uploads to a server-side, client-side, or network cause via a decision tree. Conclude with evidence-based findings only; this skill never changes anything.

Absolute Rules

ABSOLUTE PROHIBITION (read-only enforcement): Under NO circumstances may you generate, write, or execute any command/script calling a mutating OSS API — including AbortMultipartUpload (fragment cleanup), PutObject, UploadPart, CompleteMultipartUpload, DeleteObject, DeleteBucket, or any ACL/policy/lifecycle configuration change. Fragment cleanup is a WRITE operation: this skill only outputs manual cleanup guidance and command templates for the user to execute themselves (see references/fragment-cleanup-guide.md).
MANDATORY entry-point enforcement: All OSS diagnostics MUST be performed by running the scripts under scripts/ (multipart_upload_diagnosis.py as the entry, sts_token.py for identity). The Agent is forbidden from assembling its own ossutil / SDK / curl commands against the OSS control plane or bypassing the scripts — the scripts embed timeout, error degradation, and observability guarantees that ad-hoc commands lack. Read the script output, interpret it, and compose the report; do not re-implement the queries.
ABSOLUTE PROHIBITION (credential handling): Never read, print, or pass AK/SK/STS tokens explicitly. The OSS SDK resolves credentials exclusively through the Alibaba Cloud default credential chain library; the identity check uses the aliyun CLI default credential chain. Never accept AK/SK from the user or from another script.
NO FABRICATION: Every conclusion must be grounded in data actually returned by GetBucketInfo / ListBuckets / ListMultipartUploads / GetCallerIdentity or the user-provided parameters. If a query fails or returns empty, record it and state the limitation — never invent upload IDs, fragment counts, or speed figures.
EXECUTION RULE FOR ERRORS: On any API error, log [WARN] : to stderr, continue with the remaining steps (including the ListBuckets fallback), and still produce the final report with STATUS: DEGRADED and a NEXT_ACTION line — never silently skip or abort without a report.
SCOPE BOUNDARY: This skill only answers multipart / resumable upload questions (stuck / interrupted / failed attribution, part parameter sanity, fragment identification and cost impact, resume guidance). It does NOT handle single-request upload error-code semantics (EntityTooLarge / SignatureDoesNotMatch / FileAlreadyExists — defer to alibabacloud-oss-transfer-error-code-diagnosis), download problems, billing deduction details, or executing any cleanup — for such requests, state the boundary and give manual guidance only.

Official Doc Verification

MANDATORY: For configuration or usage questions, the entry script MUST be invoked with --question "". The script first matches embedded knowledge, then verifies against official OSS docs (doc_verification, llms-index). The final answer MUST cite the URLs from doc_verification.docs. If doc_verification.note starts with DEGRADED, state explicitly: "Unable to verify against online official docs (offline)." Never fabricate doc URLs; only URLs returned by the script may be cited.

Trigger Conditions

Use this skill when the customer's own wording matches one of these phrases (the same list the description advertises):

"multipart upload stuck"
"upload stuck at 0%"
"resume interrupted upload"
"multipart fragments occupy storage"
"large file upload fails"
"fragment cleanup"
"resumable upload"
"breakpoint resume"

Do NOT use it for the following -- those belong to a sibling skill:

Customer topic Route to

single-request upload errors alibabacloud-oss-transfer-error-code-diagnosis
billing alibabacloud-oss-billing-diagnosis
endpoints alibabacloud-oss-endpoint-internal-diagnosis
signed URL V4 alibabacloud-oss-presigned-url-v4-diagnosis
browser/mini-program direct upload with CORS alibabacloud-oss-browser-upload-cors-diagnosis
bucket deletion blocked by fragments / versioning recovery alibabacloud-oss-deletion-recovery-diagnosis

A customer rarely states the technical cause; match on the symptom sentence, the error code or the EC number, not on product vocabulary. When the customer gives no way to locate the resource, still run the entry script: it exits STATUS: FAIL with a NEXT_ACTION naming the missing input and lists the buckets visible to the current credential, which is what should be put back to the customer.

Execution Principle

All diagnostics MUST be performed by running the scripts under scripts/. Read the structured JSON report, interpret status / fragments / parameter_check / recommendations, and compose the user-facing answer; do not re-implement the queries or call OSS APIs directly.

Observability

All API calls issued by the scripts include:

User-Agent template: AlibabaCloud-Agent-Skills/{skill-name}/{session-id} skill-version/{skill-version}, where {skill-name} is alibabacloud-oss-multipart-upload-diagnosis
session-id: 32-character hex string (uuid.uuid4().hex) generated once per script run and attached to every OSS SDK request (User-Agent header) and every --user-agent argument of the aliyun CLI identity call of that run, so all calls of one diagnosis can be correlated.

The shared client layer (scripts/_oss_client.py) implements this automatically: the session-id is generated lazily on the first call of each run and cached for the rest of the run.

Exit codes (contract) 0 -- the run produced a conclusion: STATUS: OK, or STATUS: DEGRADED when part of the evidence was unavailable (the missing steps are recorded in errors[] and as [WARN] lines on stderr; the conclusion is still usable). 1 -- no usable conclusion: STATUS: FAIL, because required input is missing or every evidence call failed. NEXT_ACTION states what to ask the user for or what to fix; do not treat this as a success. 2 -- argparse usage error only (unknown option). A diagnosed condition never exits with 2.

Credentials

Credentials are resolved exclusively by the Alibaba Cloud default credential chain — the skill never reads, prints or passes an AccessKey pair:

OSS control-plane calls (Python oss2 SDK): resolved by the chain library alibabacloud-credentials, which picks the source itself (standard environment credentials, a CLI/credentials profile, or an instance RAM role).
Identity check (aliyun sts get-caller-identity): the aliyun CLI default credential chain.

The OSS SDK leg needs the Python dependencies declared in scripts/requirements.txt (oss2 plus the alibabacloud-credentials chain library) — install them once with pip install -r scripts/requirements.txt before the first run.

If either fails, guide the user to configure the chain (aliyun configure) — never ask for AK/SK.

aliyun CLI version requirement

The scripts shell out to the aliyun CLI (at minimum the aliyun sts get-caller-identity identity pre-check), which MUST be version 3.3.3 or newer: older builds resolve the default credential chain differently and can drop the STS session token. Verify the installed version and upgrade it before the first run:

aliyun version # must print 3.3.3 or newer (measured with 3.4.5)
aliyun upgrade --yes # upgrade the installed CLI in place to the latest version

If the CLI is not installed at all, install the Alibaba Cloud CLI package for the host OS from the official release channel and then run aliyun configure (the profile stays in ~/.aliyun/config.json; this skill never asks for AK/SK). When the CLI is missing, too old to upgrade, or unauthenticated, the identity pre-check degrades instead of aborting: scripts/_oss_client.py logs [WARN] identity pre-check failed: ... on stderr, records the empty UID, and the diagnosis still runs to a conclusion, because the identity label is traceability only and never evidence.

cd $SKILL_DIR

# Verify caller identity (informational only; credentials always come from the default chain)
python3 scripts/sts_token.py

User Confirmation

Because every action of this skill is strictly read-only, no user confirmation is required before running the diagnostic scripts. Confirmation discipline applies at the write boundary instead: any fragment cleanup (AbortMultipartUpload) or lifecycle change MUST be executed by the user themselves after reviewing references/fragment-cleanup-guide.md — this skill never executes it, even when explicitly asked.

Orchestration

One read-only script gathers evidence; the reference modules interpret it. Consult a module by responsibility, in this order:

Collect the inputs the report needs. Never guess a bucket or region: let the script's STATUS: FAIL output tell you what to ask, and offer only resources the credential can actually see.
Run scripts/multipart_upload_diagnosis.py and read status, verdict/findings, auto_filled and errors[].
Interpret through the modules below; the diagnosis tree routes the symptom, the field-semantics module explains the failing check, and the RAM module names the permission to grant when category is permission.
Answer per the Final Answer Contract: verdict first, then the fix steps, then a declaration of every auto-filled parameter.
Module Responsibility (from Module Index)
M1: Multipart playbook Official limits, stuck/interrupted/failed attribution tree, client-side evidence collection (Request ID self-check, client logs, ossutil output), fragment completeness
M2: Fragment cleanup guide Fragment billing impact and MANUAL cleanup options (console / ossutil / lifecycle) — executed by the user, never by this skill
M3: RAM policies Minimal read-only RAM policy required by this skill

Documented run order: Step 1: Confirm Identity and Collect Inputs; Step 2: Run the Multipart Upload Diagnosis; Step 3: Interpret the Evidence and Attribute; Step 4: Conclusion and Suggestions.

Input Parameters

Bucket name (--bucket): required; the OSS bucket receiving the upload.
File size (--file-size): optional but recommended, e.g. 40GB / 512MB / 1048576; drives the part size / concurrency recommendation.
Part size (--part-size): optional, e.g. 10MB; validated against the OSS limits (100 KB .. 5 GB, resulting part count