artifact-cafe

artifact.cafe

技能版本：0.12.6

artifact.cafe 托管供评审使用的静态产物。一个循环：

publish a folder → review URL → guest comments (no login) → publish v2

它不是通用托管平台。它托管自包含的静态产物（一个 index.html 加上资源），让人可以打开链接，通过点击元素或选择文本发表评论，作者则可以据此迭代。

安装或更新：npx skills add artifact-cafe/skill --skill artifact-cafe -g （在仓库本地安装时去掉 -g）。

此文件是始终加载的手册。更深入的操作指南与它一同放在 ./references/ 中（整理资源库、实时编辑循环、访问与分享，以及 data.md 中的共享数据）——下方各节会说明何时阅读哪份指南；请在需要时阅读，而不是一开始就全部读完。

何时使用

• 用户构建了可视化或交互式内容，并希望获得反馈。
• 用户想要一个可分享的链接，让非技术评审者可以打开并标注。
• 用户正在迭代：发布、收集评论、发布下一个版本。

如果他们只想托管原始文件，不需要评审流程，那么这就不是合适的工具。

要求

• 首选： Node / npx（所有主流 Agent 宿主都提供）。无需提前安装任何内容——npx artifact-cafe@latest 会按需获取 CLI。
• 备用方案（无 Node）： bash、curl、jq 和 shasum/sha256sum。使用随附的 ./scripts/publish.sh。

保持更新

• 始终使用 npx artifact-cafe@latest … 调用 CLI（此处的每个示例都如此）。@latest 标签会让 npx 每次运行时获取最新发布的 CLI，而不是复用过期缓存——这就是 CLI 的自动更新方式。
• CLI 会检查更新（每天最多一次），并在标准错误中打印 [artifact-cafe] … 通知；它们不会污染 --json 的标准输出。看到 Skill update available 时，运行它打印的命令——npx skills add artifact-cafe/skill --skill artifact-cafe -g（在仓库本地安装时去掉 -g）——然后继续操作前重新阅读更新后的 SKILL.md。无需征求许可即可进行此更新；它只会改写此技能自身的文件。

发布（首选方式）

在调用此技能的会话中运行，并将其指向要发布的文件夹：

npx artifact-cafe@latest publish ./my-artifact --title "Onboarding redesign"

文件夹根目录下必须包含入口文件 index.html（或传入 --entry）。 资源（CSS、JS、图像、字体）与其放在一起，并一并上传。

始终传入 --title——自行生成，不要等用户要求。 根据产物本身的内容（其 <title>、主标题或明显用途）推断一个简洁、易读的标题（3–6 个词）。标题会显示在审核页面上，并成为易读的审核 URL slug（例如 artifact.cafe/a/onboarding-redesign-a1b2c3）。省略后会显示“Untitled artifact”，并生成随机 slug，因此只有在确实无法推断标题时才省略。

每次发布都要用 --notes 编写版本说明。 这些说明是此版本的变更日志，会显示在审核页面的版本面板中。规则：

• 只能使用项目符号——每项变更占一行，不要写成段落。
• 每项变更单独列一条。不要把重大变更压缩成一条——如果发布了三项有意义的内容，就写三条，而不是一条。
• 每条都要简短具体（“添加深色模式切换”，而不是“杂项 UI”）。
• 将它们作为以换行符分隔的字符串传入；$'…\n…' 是可靠的 shell 写法：

npx artifact-cafe@latest publish ./my-artifact --title "Onboarding redesign" \
  --notes $'- Added dark-mode toggle\n- Fixed nav overlap on mobile\n- Rewrote pricing copy'

在 v1 中，说明应描述初始版本；在 v2+ 中，说明应描述自上一版本以来的变更。

选项：

--title "Onboarding redesign"   # RECOMMENDED — review-page title + URL slug; generate one by default
--notes $'- Added X\n- Fixed Y' # RECOMMENDED — bullet-point changelog for this version (see below)
--description "One line"        # share-card summary; overrides the entry HTML (see below)
--entry index.html              # entry file (default: auto-detect)
--artifact art_xxx              # publish a new version to an existing artifact
--workspace acme                # explicit team workspace
--folder specs                  # folder in that workspace — SETS VISIBILITY, see below
--review off                    # plain artifact: no review tools (see below)
--json                          # machine-readable output (use this for agents)
--no-open                       # don't try to open a browser

除非用户另有要求，否则保持审核开启。 发布的目的就是收到评论。只有当用户明确表示需要的是交付物、演示或作品集内容，而不是反馈时，才使用 --review off；它会生成完全没有审核功能的普通产物。 --review readonly 会保留现有评论供查看，并拒绝新评论。 之后可以使用发布令牌（无需账户）更改这两种设置：

npx artifact-cafe@latest review readonly   # close it to new comments
npx artifact-cafe@latest review open       # reopen it

此操作不会删除评论；重新开启审核后，评论会再次显示。

--folder 决定谁可以打开审核链接。 文件夹具有可见性（public 或 workspace），产物发布时会继承该设置。 放入 workspace 文件夹后，审核 URL 就不再是任何人都能打开的链接——打开时会要求登录，只有该工作区的成员才能访问。 如果不传入 --folder，新产物的可见性为 unlisted：任何拥有链接的人都可以访问，无需账户。因此，请先使用 npx artifact-cafe@latest folders --workspace <handle> --json 查询文件夹的可见性，并在发布到 unlisted 以外的位置前告知用户。默认仍会将产物归档到文件夹中——请参阅“保持资料库井然有序”。

publish --json 会在 visibility 字段中报告结果 （public | unlisted | workspace | private）——请查看此字段，并告诉用户他们即将发送的链接实际会如何访问。请参阅“告知用户的内容”。

首次以匿名方式发布到新文件夹时，命令会输出一个审核 URL 和一个认领 URL（仅显示一次）。它会在 .artifactcafe/config.json 中写入产物 ID 和机密发布令牌，并将该文件加入 gitignore。

首次发布前，请确定目标位置——请参阅下文的“选择发布位置”。始终使用 --json，并报告其中的 destination 和 destinationSource 字段。

让分享链接正确展开预览

将审核 URL 粘贴到 X、Threads、Slack、Telegram 或 Discord 时，预览卡片会根据作品生成。默认情况下，这是一个由系统生成的 artifact.cafe 卡片，文案围绕审核展开。这适用于希望他人提供反馈的仪表盘，但不适合供人阅读的内容。

如果你要制作的是供人阅读而非审核的内容（文章、报告、指南、对比），请在入口文件的 <head> 中添加以下内容：

<meta name="description" content="One line on what this is.">
<meta property="og:image" content="cover.png">
<meta name="author" content="Ada Lovelace">

API 会在发布时读取这些内容，因此无论通过哪种方式发布，都能生效：npm CLI、bash 回退方案，以及直接调用 API。也支持 og:description 和 article:author。如果这三项都不设置，链接的行为就和以往完全一样。

图片有一些规则，全部由服务器端强制执行：

• 必须是待发布文件夹内的文件。 cover.png、./cover.png 和 /assets/cover.png 都可以。远程 URL、协议相对 URL 和 data: URI 会被直接拒绝。
• 格式必须为 PNG、JPEG、WebP 或 GIF，且小于 5 MB。推荐尺寸为 1200x630。不支持 SVG。
• 被拒绝的内容会静默回退到系统生成的卡片。不会造成任何问题，描述和署名栏仍会正常发布。

--description "…" 会覆盖入口文件中声明的内容。如果文档自身的 meta 描述并不适合出现在动态消息中的句子，可以使用此选项。

受限作品不会声明任何内容。 受密码保护、工作区内以及私有作品无论标签是什么，展开预览时始终显示锁定卡片，因此无需为这些作品设置任何内容。

选择发布位置（在发布新制品前执行）

**运行时 Agent 令牌：**如果 ARTIFACT_CAFE_API_KEY 以 aat_ 开头，请直接使用该凭据，不要打印或保存。跳过 whoami、登录、工作区发现和文件夹选择。发布时不要使用 --workspace 或 --folder；该令牌会准确选择其自身的工作区，项目默认设置不适用。comments、reply 和 resolve 会使用已保存的绑定，并标注 Agent 身份。新制品默认为 unlisted：任何人都可以通过链接查看，无需账户。该制品没有匿名过期时间、认领 URL 或永久发布令牌。不要尝试账户、授权、成员或工作区管理命令。运行结束时，运行时会撤销该令牌；过期或已撤销的令牌会返回 401。

对于使用普通凭据首次发布新文件夹，此规则适用。新版本会复用 .artifactcafe/config.json 中已记录的目标位置——跳过以下所有步骤，直接再次执行 publish。按以下优先级确定目标位置：

**1. 先检查登录状态。**运行 npx artifact-cafe@latest whoami --json。

• 已登录（退出码为 0）：在该账户下发布。已登录用户绝不应意外创建匿名、有效期为 24 小时的制品——这正是需要按此顺序操作的原因。请注意，密钥按源站解析，且 ARTIFACT_CAFE_URL 会选择源站：如果 whoami 在你即将发布到的源站上失败，账户密钥也无法用于发布——应明确告知用户（他们在此源站未登录），而不是默默匿名发布。
• 未登录（退出码非 0）：直接发布。这是一个匿名制品，会在 24 小时后过期，并返回一次性认领 URL。告知用户这是匿名制品，并说明先运行 artifact-cafe login 即可创建永久归账户所有的制品。

**2. 然后选择工作区（仅限已登录）。**如果用户指定了 --workspace，或项目的 artifact-cafe.json 默认设置适用，则使用该设置，不要询问。否则，使用 npx artifact-cafe@latest workspaces --json 列出账户的工作区并作出选择：

• 仅有 Personal（没有团队工作区）：直接发布到 Personal，无需询问。
• Personal 和团队工作区并存：不要默认选择 Personal。查看制品的主题；如果其明显主题与用户的某个工作区相符（例如，内容是为名为「hellyeah」的产品做规划，而存在 hellyeah 工作区），请询问用户是发布到该工作区还是 Personal，然后相应地传入 --workspace <handle>。

内容只能作为询问什么的提示——绝不要根据你从内容推测出的结果，擅自将制品发布到某个工作区；应由用户的选择决定。--json 会禁用 CLI 自带的交互式工作区选择器，因此跳过此步骤的已登录 Agent 会直接默认使用 Personal——这正是你要自行执行这两项检查的原因。

让资料库井然有序（文件夹）

每个工作区（包括 Personal）都有一个扁平的文件夹列表（不支持嵌套）。归档也是做好发布的一部分：发布时就将每个作品归入文件夹，不要把所有内容都堆在一个未归档的地方。

3. 选择文件夹（确定工作区后、首次发布前）。 确定工作区后，列出其中的文件夹：

npx artifact-cafe@latest folders --workspace <handle> --json

• 如果现有文件夹明显符合该作品的主题，请使用 --folder "<name>" 发布（名称必须完全匹配且区分大小写，也可以使用文件夹 ID）。按含义匹配，而不是按字符串是否相同匹配——即使没有相同的词，新规范也应归入名为 "Specs" 的文件夹。
• 如果没有合适的文件夹，就让作品保持未归档，不要强行归入不合适的文件夹。只有确实存在一组作品时才创建文件夹（folders create "<name>" --workspace <handle>）——绝不要为单个作品创建文件夹——并且创建前先复用现有文件夹：CLI 会拒绝重复名称；遇到这种情况时，请视为“使用现有文件夹”。
• ⚠ 文件夹的可见性会成为作品的可见性。 发布到或移入 public 文件夹会使作品公开，且不会出现任何确认提示——将作品放到任何公开位置之前，务必先向用户确认，并报告每次可见性变更（参见上文“--folder 决定谁能打开评审链接”）。
• 无需重新发布即可重新归档：npx artifact-cafe@latest move --folder "<name>"（使用 --artifact <id> 指定作品，使用 --unfiled 移至根目录）。不会创建新版本；评论保持不变。

当用户要求你整理他们的资料库时（“整理我的作品”“清理我的工作区”），请先阅读 ./references/organize.md，并遵循先制定计划的流程——未经展示计划，绝不要批量移动或批量创建文件夹。该文件还包含文件夹创建规则、命名指南，以及 move/list --workspace 的详细说明。文件夹命令需要 Node CLI 和已登录的账号；bash 后备方案无法管理归档位置。

不使用 Node 发布（后备方案）

使用纯 bash 实现相同的静态发布流程，适用于无法使用 npx 的环境：

./scripts/publish.sh ./my-artifact --title "Onboarding redesign"

它支持 --title、--entry、--artifact、--json 和 --no-open，使用相同的 API，并写入相同的 .artifactcafe/config.json。发现工作区、项目默认设置和人工选择器需要 npm CLI。如果新作品带有 artifact-cafe.json 策略文件，后备方案会拒绝发布，而不会悄悄将作品发布到其他位置。

发布新版本

版本是不可变的——新发布不会修改现有版本，评论也会继续附属于其发布时所在的版本。要发布 v2，只需在同一目录中再次发布同一文件夹：

npx artifact-cafe@latest publish ./my-artifact \
  --notes $'- Moved the CTA above the fold\n- Tightened hero spacing'   # → v2, v3, …

使用 --notes 说明自上一版本以来的变更——如果新版本没有变更日志，评审者就只能猜测需要重新评审哪些内容。

运行时的 aat_ Agent 令牌或 .artifactcafe/config.json 中存储的发布令牌，会自动授权发布新版本。从缺少令牌的全新检出目录发布时，请设置 ARTIFACT_CAFE_TOKEN（发布令牌），或使用 --artifact <id> 指定目标。如果已登录，artifact-cafe link --artifact <id>（或 --slug <slug>）可将文件夹关联到你有权发布到的任意作品——无论是你自己的作品，还是你所属工作区中队友的作品——这样后续命令就可以直接运行，无需令牌；账号操作会使用你的登录信息。link --json 会先列出候选项。这就是你在他人已发布作品的基础上继续创作的方式。

拉取评论

循环的读取端——查看审阅者的反馈，以便 Agent 进行处理：

npx artifact-cafe@latest comments            # open threads on the current version
npx artifact-cafe@latest comments --json     # structured, for programmatic handling
./scripts/comments.sh                 # no-Node fallback

筛选条件：--status open|resolved|all、--version current|all。每个讨论串都包含作者、评论所针对的版本、锚点（引用的文本片段或元素路径）、消息正文和回复。处理反馈，发布下一个版本，然后使用 reply/resolve（见下文）完成闭环。

CLI 和备用方式都支持 --artifact <id>（或 ARTIFACT_CAFE_ARTIFACT_ID），无需指定文件夹即可读取 artifact——与 publish 的分离式定位方式相同；若 artifact 受密码保护，请添加 ARTIFACT_CAFE_TOKEN。

回复评论

循环的写入端——Agent 发布处理反馈的版本后，如何回复反馈。使用 comments --json 中每个讨论串的 id：

# Post what changed back into the thread, then close it — one step
npx artifact-cafe@latest reply <threadId> --body "Fixed in v2 — CTA moved above the fold." --resolve

npx artifact-cafe@latest reply <threadId> --body "…"     # reply, leave it open
echo "$msg" | npx artifact-cafe@latest reply <threadId>  # long body from stdin
npx artifact-cafe@latest resolve <threadId>              # close a thread you addressed
npx artifact-cafe@latest reopen <threadId>               # undo — reopen a resolved one

使用发布令牌或 Agent 令牌回复时，回复会归于Agent：审阅者会看到“Yulong's Claude”，并显示你的工具标识——你的自称名称（自动检测，或使用 --as "Claude Code"），后接 artifact 的所有者名称。若在已登录的账户下回复，显示的则是所有者名称，工具会作为“via”标签显示。建议使用 reply --resolve，而不是单独使用 resolve——这样可以告知审阅者你做了什么修改，而不是悄无声息地关闭讨论串。 分离式定位方式与其他命令相同（--artifact <id> + ARTIFACT_CAFE_TOKEN，或你的账户密钥）；所有命令都支持 --json。

修改或撤回你写的消息——使用 comments --json 中的 ID（每个讨论串的 messageId 对应开篇评论，每条回复的 id 对应该回复）：

npx artifact-cafe@latest edit <messageId> --body "Revised — moved the CTA, not removed it."
npx artifact-cafe@latest delete <messageId>

你只能编辑或删除自己撰写的消息——由令牌撰写的 Agent 回复，或你自己的账户评论；修改操作必须使用撰写该消息时的相同凭据。edit 会添加“已编辑”标记（不保留历史记录）。delete 是软删除：评论会变成“评论已删除”的墓碑，下面的回复仍会保留。

开启审阅讨论串

reply 用于回复现有讨论串；comment 用于开启新讨论串——在 artifact 上留下你自己的审阅备注：

npx artifact-cafe@latest comment --quote "Where AI work lives" --body "This headline is vague."
npx artifact-cafe@latest comment --body "Overall this reads well."   # page-level, no --quote

与循环中的其他操作不同，comment 使用你的账户作为作者，因此需要运行 artifact-cafe login——发布令牌不能开启讨论串（Agent 负责回复；账户负责发起），如果你只有发布令牌，命令会返回登录提示。--quote 会将讨论串锚定到匹配的文本（若引用内容重复，可用 --prefix/--suffix 消除歧义）；不使用 --quote 时，评论会显示在页面级别。--as "Claude Code" 会在账户名称后设置显示标签——它只会附加显示，绝不会替代账户名称；如果不指定，则会从你的环境中自动检测。

comment、edit 和 delete（与 listen 一样）需要 Node CLI——没有 bash 备用方式。

提供实时编辑模式（可选）

发布和实时编辑是两个独立操作。发布并分享审阅 URL 后，询问用户是否要进入实时编辑模式：你将继续连接到本地 artifact，接收新评论（npx artifact-cafe@latest listen --json --timeout 540），进行修改，并在审阅者查看期间发布新的不可变版本。

不要自动启动实时编辑模式。 用户可能希望分享链接并异步收集反馈，而不让 Agent 会话持续运行。用户明确同意后，阅读 ./references/live-editing.md，并运行其中说明的循环（listen → edit → publish → reply --resolve → listen）。当 listen 以 2 退出（超时）时，告知用户监听时间已结束，并询问是否继续，然后再重新运行——绝不要让无人值守的会话无限期运行。

持久化共享数据

对于投票、留言簿、RSVP，或跨访客收集提交内容的场景，请使用 Artifact Data。artifact 必须已认领；访客无需账户即可提交。编写清单前，请阅读 ./references/data.md。

打开审阅页面

npx artifact-cafe@latest open     # prints (and, in a terminal, opens) the review URL

本地配置和发布令牌

首次发布后，文件夹中会包含以下内容（aat_ 发布不会包含 publishToken）：

.artifactcafe/config.json

{
  "artifactId": "art_…",
  "slug": "…",
  "url": "https://artifact.cafe/a/…",
  "apiUrl": "https://artifact.cafe",
  "publishToken": "apt_…"
}

• publishToken 是一个秘密令牌，仅返回一次，用于授权向此 artifact 发布新版本。**绝不要打印、提交或记录它。**CLI 会将其存储为 chmod 600，并将 .artifactcafe/ 添加到 .gitignore。
• 将 config.json 视为内部关联状态，而不是 URL。绝不要把本地文件路径当作审核链接展示给用户。

谁可以打开审核链接

每个 artifact 都有一个可见性设置：public 和 unlisted 允许任何拥有链接的人打开，无需账号（unlisted 使用随机、不可猜测的 slug，是新 artifact 的默认设置）；workspace 会要求非成员登录；private 仅允许发布者、工作区所有者/管理员以及通过电子邮件获邀的人访问。新 artifact 如果放在某个文件夹中，会采用该文件夹的可见性。CLI 无法更改可见性——没有 --visibility 标志；可见性需要在仪表板中设置，或由 artifact 所在文件夹决定。

关于这句概述之外的所有内容——完整的可见性表、通过电子邮件邀请他人（share <email>——邀请 URL 只会显示一次，请原样提供）、审查和撤销访问权限（share --list、unshare），以及通过 HTTP 读取已发布 artifact 的内容（在其内容 URL 后追加 .md；受限 artifact 需要 Bearer 账号密钥）——请阅读 ./references/access.md。

匿名 artifact 与已认领 artifact

• 首次发布时，如果没有账号或 Agent 令牌，会创建一个匿名 artifact，并在24 小时后过期，同时返回一个一次性认领 URL。
• 认领 artifact（打开认领 URL）后，artifact 会永久保留并关联到用户的账号。认领令牌只会显示一次，且无法找回——请立即向用户提供认领 URL。

限制

• 每个文件最大 20 MB，每个 artifact 总计最大 50 MB。
• 匿名用户每天每个 IP 最多发布 20 次。
• Agent 令牌发布每个工作区每小时最多 120 次，不按 IP 限制。
• 绝不上传秘密文件和垃圾内容：.git*、node_modules、.env*、*.pem、*.key、.DS_Store 和符号链接会自动忽略。

安全

artifact HTML 不可信，只会在自身独立源上的沙盒 iframe 中渲染——绝不会在主站上渲染。无需清理 artifact，但不要发布包含真实秘密或凭据的内容。

内容政策——拒绝违规内容

**你是执行政策的第一道防线。**发布前，请检查即将发布的内容。如果 artifact 包含以下任一内容，请拒绝发布，并告诉用户原因：

• 钓鱼 / 凭据窃取——虚假的登录页面，或捕获密码、支付信息或 2FA 验证码并发送到其他地方的页面。
• 恶意软件 / 恶意代码——漏洞利用、未经用户操作的下载、经过混淆或蓄意造成危害的 JavaScript、欺骗性重定向。
• 仇恨或骚扰——基于身份攻击或贬低他人的内容，或针对个人进行辱骂的内容。
• 色情内容——色情材料；任何性化未成年人的内容都必须绝对拒绝，绝不发布。
• 暴力——血腥内容、威胁或煽动暴力。
• 垃圾信息 / 骗局 / 欺诈——欺骗性骗局、虚假赠品、误导性的金融或医疗声明。
• 其他非法内容。

不要试图“清理”违规内容后再发布——请拒绝发布。拒绝时，请明确说明该内容违反了 artifact.cafe 的内容政策。安全概念的正当演示（例如附有注释的说明）可以发布；可运行的钓鱼页面或实时恶意软件则不可以。计划在发布时进行自动审核——请现在就执行此政策，不要试图绕过过滤。

要告知用户的内容

• 始终分享当前运行生成的评审 URL——评审者会打开该链接并发表评论。
• **说明谁可以打开它。**从 publish --json 读取 visibility。如果是 public/unlisted，请明确说明：评审者无需账号。若是 workspace/private，不要说任何人都能打开该链接——请告知用户，非成员需要登录，并为外部人员提供 artifact-cafe share <email>。用户将仅限成员访问的链接发给外部评审者，却迟迟没有收到回复，正是这条说明要避免的情况。
• 如果运行输出了领取 URL，请告知用户该 URL 只会显示一次，且除非领取，否则 artifact 将在 24 小时后过期。请原样分享该 URL。
• 发布新版本时，请分享评审 URL，并注明当前版本为v{N}；之前的评论仍保留在各自原来的版本上。
• 绝不要让用户通过 .artifactcafe/config.json 查找 URL 或令牌。