lightning-artifacts

Lightning AI Artifacts（持久、可分享的文件链接）

将文件发布到团队空间，并获取一个 https://lightning.ai/artifacts/<id> URL，任何人都可以打开，无需登录 Lightning。控制平面会在每次请求时从存储中流式传输 字节，因此与预签名 S3 URL 不同，该链接永不过期（没有约 1 小时的时限）。

整个流程仅使用 CLI。 lightning cp / ls / rm 用于处理文件， lightning api 用于调用发布和取消发布接口。无需 Python 或 curl。

设置与身份验证

export DEBUG=0 LIGHTNING_DEBUG=0   # an inherited DEBUG=1 logs the Authorization header; set this in every new shell
# Use the Lightning AI CLI from the current env; install or upgrade it there if it's missing or older than 2026.9.18
v=$(lightning --version 2>/dev/null | sed -n 's/^Lightning CLI version //p')
[ -n "$v" ] && [ "$(printf '%s\n' 2026.9.18 "$v" | sort -V | head -1)" = 2026.9.18 ] \
  || uv pip install -U lightning-sdk || python3 -m pip install -U lightning-sdk
lightning --version   # must print "Lightning CLI version …"; if not, see the table below
lightning login                       # interactive browser sign-in — enough for everything here
# or: export LIGHTNING_API_KEY=...    # non-interactive alternative (CI, agents)

这两种凭据都适用于此技能中的每次调用——无需创建令牌或 执行额外的身份验证步骤。从 lightning.ai → 用户/组织设置中获取密钥，或运行 lightning api-key create --org <org> --name artifacts。切勿将密钥硬编码—— 请从环境中读取。要使用非生产环境的控制平面，请设置 LIGHTNING_CLOUD_URL（默认值为 https://lightning.ai）。

这会使用智能体当前的环境（项目 venv、conda 环境等），并在需要时将其安装到该环境中； 之后，所有地方都调用普通的 lightning …。如果设置过程不顺利：

症状	解决方法
没有激活的环境、出现 externally-managed-environment，或与项目自身的固定版本冲突	单独安装：uv tool install lightning-sdk（或 pipx install lightning-sdk），如果它不在 PATH 中，则调用 "$(uv tool dir --bin)/lightning"
安装后仍没有 Lightning CLI version 行	另一个 lightning（PyTorch Lightning 的）或未激活的环境排在前面：检查 command -v lightning，然后激活环境或调用其中的 bin/lightning
出现 No such command、No such option 或 unexpected extra argument	CLI 版本太旧：在 command -v lightning 指向的位置升级它（uv pip install -U lightning-sdk，或 uv tool upgrade lightning-sdk）
安装受阻（环境或主目录为只读，或智能体沙盒限制）	将每条命令写成 UV_CACHE_DIR="${TMPDIR:-/tmp}/uv" UV_TOOL_DIR="${TMPDIR:-/tmp}/uv-tools" uvx lightning-sdk … 来运行
每次调用都出现 SSL/CA 错误，甚至 lightning --version 也如此，且仅在智能体沙盒中出现	**/*.pem 读取拒绝规则隐藏了 certifi 的 cacert.pem：允许访问该路径；不要禁用沙盒
出现 NameResolutionError，且仅在智能体沙盒中出现	如果 lightning api 也失败，请让用户允许访问 lightning.ai 和 *.lightning.ai（/sandbox）。如果只有 studio/job 命令或 SDK 失败，则它们绕过了沙盒代理：只在沙盒外运行这些命令。后台轮询器也会以相同方式静默失败

lightning api 标志：-X 方法，-f key=val 字符串字段，-F key=val 类型化字段，-H 标头，--input <file> 请求正文（使用 --input - 可通过管道传入 正文），-q jq 筛选器（使用 -q 需要 jq 二进制文件），-i 包含响应 标头，--silent 不输出内容。不带 -X 的字段会使请求成为 POST。对于 POST/带正文的 PUT，字段是 JSON 正文；如果请求同时带有 --input 或为 GET，则字段是查询参数。

查找团队空间（先执行此步骤）

Artifacts 存放在团队空间中（在 REST API 中称为“项目”）。你需要知道 所有者名称和团队空间名称（用于 lit:// 路径），以及项目 ID（用于 REST 调用）。切勿猜测。 如果有多个匹配的成员身份，且 没有配置默认项，请询问用户要使用哪一个：

lightning api /v1/memberships -q '.memberships[] | [.name, .projectId, .ownerType, .ownerId] | @tsv'

成员身份中仅包含所有者 ID。根据 ownerType 查找名称：

PID=<projectId-from-above>
TSNAME=<name-from-above>
OWNER_ID=<ownerId-from-above>
if [ "<ownerType-from-above>" = organization ]; then
  OWNER=$(lightning api "/v1/orgs/$OWNER_ID" | jq -r .name)
else   # a personal teamspace: yours, or another user's you were added to
  OWNER=$(lightning api /v1/users/search -X GET -f "query=$OWNER_ID" \
    | jq -r --arg id "$OWNER_ID" '.users[] | select(.id==$id) | .username')
fi
[ -n "$OWNER" ] && [ "$OWNER" != null ] || echo "could not resolve the owner of $TSNAME — ask the user" >&2

用户搜索采用模糊匹配，因此请精确匹配 .id（SDK 也是如此）。切勿 退回使用自己的用户名：在 lit:// 路径中使用错误的所有者会将文件上传到 另一个团队空间。

通过组织级权限访问的团队空间不会出现在 /v1/memberships 中。如果用户指定了一个你找不到的团队空间，请向他们索取 <owner>/<teamspace> 对以及项目 ID。不要尝试按名称查找： /v1/projects?name=… 并不存在。

发布持久链接（CLI 流程）

公开链接（private=false，也是下方示例的默认值）需要用户在本次请求中明确同意。 “发布这个”或“给我一个公开链接”即表示授权——不要再问一次。“发给团队”则不算：说明链接会公开哪些内容并获得肯定答复，或使用 -F private=true。

分三步调用：将文件上传到 artifacts/ 驱动器，读取其存储集群，然后将对象注册为共享工件。下文的 share 和 shares 需要 jq 二进制文件；如果没有，请自行解析 JSON。

# share <local-file> [remote-name] [content-type]
# Pretty status goes to stderr; the bare URL is the only thing on stdout, so
# URL=$(share file.html) captures cleanly while interactive use looks like:
#   ✅ Published report.html (text/html; charset=utf-8)
#   🔗 https://lightning.ai/artifacts/art_...
share() {
  local FILE="$1" NAME="${2:-$(basename "$1")}" CT="${3:-$(file -b --mime-type "$1")}"
  local KEY="artifacts/${NAME#artifacts/}"     # publish only finds objects under artifacts/
  # 1. upload; the server picks where to store it (see Gotchas)
  lightning cp "$FILE" "lit://$OWNER/$TSNAME/$KEY" >&2 || return 1
  # 2. publish needs the blob's storage cluster, read from the listing (see Gotchas)
  local CLUSTER; CLUSTER=$(lightning ls --json "lit://$OWNER/$TSNAME/$KEY" | jq -r '.[0].clusterId')
  # 3. register it -> durable, no-expiry lightning.ai/artifacts/<id>
  local LINK; LINK=$(lightning api "/v1/projects/$PID/shared-artifacts" -X POST \
    -f clusterId="$CLUSTER" -f filename="$KEY" -f contentType="$CT" -F private=false -q .url | tr -d '"')
  echo "✅ Published $NAME ($CT)" >&2
  printf '🔗 ' >&2
  echo "$LINK"
}

share report.html                                  # -> https://lightning.ai/artifacts/art_...
share dashboard.html reports/dash.html text/html   # custom remote name + explicit type

始终将完整 URL 单独一行展示给用户，不要只说“完成”。 终端会让它可以点击。

共享链接仅限 artifacts/ 文件夹。 发布功能只会查找 lit://<owner>/<teamspace>/artifacts/... 下的对象。uploads/ 或 lightning_storage/ 下的文件可以用 lightning cp 复制，但发布功能找不到它们。KEY 变量可确保上传路径与发布时的 filename 一致。服务器会为不带路径的 filename 自动添加 artifacts/ 前缀，但明确保持两者一致最清楚。

默认的 private=false 链接任何持有者都能打开，无需身份验证。 设置 -F private=true，这样只有获得授权的项目读者才能打开。

可内嵌呈现的内容类型

发布调用中的 contentType 决定 HTML/PDF 是内嵌呈现还是下载。 它在发布时设置，而非上传时设置，并且每次请求都会覆盖存储对象的类型。file -b --mime-type 可以猜出大多数情况；扩展名不明确时，请传入显式类型。

文件	Content-Type
.html	text/html; charset=utf-8
.pdf	application/pdf
.svg	image/svg+xml
.png / .jpg	image/png / image/jpeg
.json / .txt / .csv	application/json / text/plain / text/csv
强制下载任何文件	application/octet-stream

列出内容、查看已发布内容、取消发布、删除

lightning ls 会完整列出驱动器内容，即使文件夹中有数千个文件也一样。 它会逐页获取服务器返回的内容。默认显示一层内容；使用 -r 可显示所有下级文件，使用 --json 可获取包含 size 和 clusterId 的条目：

lightning ls "lit://$OWNER/$TSNAME/artifacts/"              # one level; folders end in /
lightning ls -r "lit://$OWNER/$TSNAME/artifacts/reports"    # full relative file paths
lightning ls --json "lit://$OWNER/$TSNAME/artifacts/reports"

shares 会按时间倒序列出项目中所有已发布的链接。 它调用 GET /v1/projects/{pid}/shared-artifacts，该接口会返回 id、filename、content type、公开/私有状态、下载次数和 URL：

# shares  ->  one block per published artifact
shares() {
  lightning api "/v1/projects/$PID/shared-artifacts" | jq -r '.artifacts // [] | .[] |
    "\(if .private then "🔒" else "🌐" end) \(.filename)  ·  ⬇ \(.downloads // 0)  ·  \(.createdAt // "")
   id: \(.id)
   🔗 \(.url)"'
}

unshare 会撤销链接，但保留驱动器中的文件：

# unshare <artifact-id>
unshare() {
  lightning api "/v1/projects/$PID/shared-artifacts/$1" -X DELETE --silent \
    && echo "🗑️  Unpublished $1 — link is dead, file kept in the drive" >&2
}

unshare art_01kxgaep54zzs84arfns1j21wd   # illustrative id; take yours from shares

lightning rm 会删除文件本身，无需集群 id。 服务器会从文件的存储位置将其删除。在取消发布后使用它，或用于清理未完成的上传：

lightning rm "lit://$OWNER/$TSNAME/artifacts/report.html"
lightning rm -r "lit://$OWNER/$TSNAME/artifacts/reports"     # a folder and everything under it

rm 对不存在的路径会报错（传入 -f 可忽略），且没有 -r 时会拒绝处理文件夹。

再次运行 lightning cp，将文件复制到相同的 artifacts/<name>，即可更新现有链接指向的内容。 链接的 id 会保持不变，并继续提供新内容。使用相同的 filename 重复调用发布功能会生成新的 id 和 URL；如需更改所提供内容的 Content-Type，请这样操作。

示例工作流

此技能处理的提示词示例：“将这份 HTML 报告分享为永久链接”、 “给我 output.pdf 的公开 URL”、“发布这份单页文档，这样我就能发给别人”、“把这个文件放到 CI 能用 curl 获取的地方”。

Agent 生成的 HTML 单页文档只需使用 share；任何人都能打开输出的 URL：

share summary.html                                 # hand the printed URL to anyone

循环调用 share 可发布文件夹中的一组报告，每份报告对应一个链接：

for f in out/*.html; do share "$f" "reports/$(basename "$f")" "text/html; charset=utf-8"; done

share 只会将 URL 输出到 stdout，因此 CI 作业可以捕获该 URL 并用 curl 获取内容：

URL=$(share model-metrics.json)
# elsewhere:  curl -sL "$URL" -o metrics.json

注意事项

• 使用计算集群的 ID 发布会失败并返回 HTTP 500；发布时需要的是 Blob 的存储集群。 Teamspace 可以绑定到计算集群，而这些集群会将文件存储在父集群的存储桶中，因此上传集群不一定是存储集群。像 share 一样，从列表中读取实际的 clusterId。
• lightning cp 无需指定集群标志，因为服务器会选择存储位置。 只有服务器因缺少集群而拒绝上传时，cp 才会自行选择一个（优先使用 LIGHTNING_CLUSTER_ID，该变量在 Studio 中设置；其次使用 teamspace 唯一的或默认的云账户），并发出警告 No cloud account specified. Using cloud account: <id>. 仅在有意指定存储位置时才传入 --cloud-account <id>，并选择 status.phase 为 CLUSTER_STATE_RUNNING 的集群（/v1/projects/$PID/clusters）。已绑定但不可用的集群会导致上传失败并显示云盘错误，但错误信息不会说明集群的健康状态。
• 取消发布会对不存在的链接报告成功。 对已撤销或输入错误的 ID，DELETE /v1/projects/{pid}/shared-artifacts/{id} 会返回 HTTP 200 和 {}。退出代码为 0 并不能证明链接已取消发布；请检查公共 URL 是否返回 404。（相比之下，如果路径不存在，lightning rm 会失败，除非传入 -f。）
• 提供的 HTML 与上传内容并非逐字节一致，因此不要将其与源文件进行校验和比对。 Cloudflare 会在 HTML 响应中注入 Browser-Insights RUM 信标（static.cloudflareinsights.com/beacon.min.js）。这不会影响查看，但不要承诺文档逐字节完全一致。
• 在 2026 年 7 月中旬之前构建的控制平面上，shares 会失败并返回 HTTP 501「Method Not Allowed」。 列表端点 GET /v1/projects/{pid}/shared-artifacts 比其他端点更新。发布和取消发布仍可正常使用。
• 任何拥有公共链接的人都可以访问；撤销链接也无法收回已被获取的副本。 对于不应公开访问的内容，请使用 -F private=true。