用途：验证 Agent 发布链路是否正确，覆盖 token 写入口闸门、publish.sh 单文件/目录发布、链接渲染和默认过期/永久发布。全部使用真实 curl、publish.sh 与 ipfs-cluster-ctl 断言。集群基础设施的 e2e 属于 kubo-deploy-e2e。
前置与约定：ENDPOINT=http://localhost:9097（token 写入口，仅 POST /add），BASE=http://localhost:8088（读网关，路径 /artifact/<CID>），发布脚本为 skills/publish-artifact/publish.sh，token 取自 .env 的 IPFS_PUBLISH_TOKEN。镜像锁定 kubo v0.42.0、ipfs-cluster v1.1.6、caddy:2-alpine。发布技能契约需 3 个环境变量：IPFS_PUBLISH_ENDPOINT、IPFS_PUBLISH_TOKEN、IPFS_BASE_URL。
使用方式：一键 e2e 运行 make publish-e2e（自起栈，跑完自动 down），或 make publish-e2e-keep 保留集群手测。手动步骤先导出三个环境变量；写入口闸门断言：无 token POST /add 应 401，token + GET /add 应 403，token + DELETE /pins/x 应 403；单文件发布后用 curl 链接应见正文；目录站点需断言 index.html 与 css/app.css 均返回 200；默认发布的 pin 应有 expire_at；--permanent 发布无 expire_at。失败时不要清栈，按排查章节处理。
排查：查看容器状态、校验 Caddyfile、查看 caddy 日志；修改 Caddyfile 后需 docker exec cl-caddy caddy reload 手动重载，docker compose up -d 不会因 bind-mount 变化重建容器。
限制与注意事项：写入口只放行 POST /add，Agent 无法 unpin 或访问 peers 等管理能力，必须走 :9097 + token，不能直连 :9095/:9094；publish.sh 默认 expire-in=168h（1 周），到期集群自动 unpin，--permanent 应少量使用；无 owner 概念，不提供取消发布，清理靠过期与管理员 ipfs-cluster-ctl；单 CID pin ls 为美化 JSON（expire_at 冒号后有空格），全量 pin ls 为 compact，断言 grep 需容忍空格；目录链接带尾斜杠，根的 CID 是响应中 name 为空的那行。机密文件 .env 与 runtime/private/swarm.key 均 gitignored。更多细节见 docs/SINGLE_HOST_DEPLOYMENT.md §5、docs/AGENT_INTEGRATION_GUIDE.md、docs/CLUSTER_CTL_REFERENCE.md。