rtfx.pro

artifacts-server

基于 Cloudflare Workers 运行，为落地页和 HTML/Claude artifacts 提供私密、需授权访问的托管服务。/（以及 /docs、/signup 和 /login）是公开产品网站，介绍产品并让用户开始使用 Free 计划。登录由应用自身处理，无需密码：rtfx.pro 会发送一次性验证码或魔法链接，然后通过仅限主机的 rtfx_session 让浏览器保持登录状态。/admin 下的单一仪表板用于处理发布、分享，以及查看与你共享的所有内容的图库。Artifacts（单个 HTML 文件或多文件静态包）可通过 Web 仪表板、CLI 或 Agent 会话（Claude Code、Hermes）发布。支持单个 artifact 的权限设置和版本管理。

• 🤖 原生支持 Agent 发布 — Claude Code、原生 MCP 服务、Hermes、CLI 和 HTTP API 都与人工用户使用相同的流程；没有独立且功能较弱的 Agent 发布途径。参见 plugins/rtfx 和 docs/MCP.md。
• 👥 优先基于身份控制访问 — 每个 artifact 都可以设为私密、与指定人员共享，或向所有已登录用户开放。未获授权和不存在的内容都会返回 404。
• 🔗 可撤销的分享链接 — 如需分享给没有账户的人，可为单个 artifact 创建能力 URL，并可选择设置 1–365 天的有效期。只存储哈希值。
• 🕓 版本管理 — 每次重新发布都会创建一个不可变的新版本；可在计划规定的保留期限内回滚（免费计划保留最近 5 个版本；付费计划保留全部版本）。
• 📈 浏览记录与已读回执 — 查看谁在何时、从何处查看了每个 artifact，以及查看的版本；每位指定收件人首次打开时会收到一封邮件。
• 🏢 工作区与角色 — Artifacts 归属于账户，角色包括 owner/admin/member/viewer；实例权限会根据配置重新计算，从不读取数据表。
• 🔗 规范的工作区地址 — 每个工作区都有一个地址（自动生成为 w-xxxxxxxx；付费工作区可以自定义地址），每个 artifact 链接都采用 rtfx.pro/<workspace>/<artifact> 格式，例如 rtfx.pro/yogev/q3-board-report。这是产品展示或返回的唯一 URL：查看器在应用主机上渲染，并以内嵌框架加载沙盒内容源；内容源永远不会成为地址。旧的 a.rtfx.pro/<slug>/ 链接会将浏览器重定向到新地址。这是应用主机上的路径，不是自定义域名。
• 🌐 公开产品网站 — 任何人都可以访问 /、/docs、/signup、/login、/privacy 和 /terms，这些页面提供 SEO 元数据、sitemap.xml、robots.txt 和 llms.txt；其他所有内容都需要身份验证。
• 🔒 需授权访问的仪表板 — 应用自身通过电子邮件 OTP/魔法链接登录 /admin 和 API；应用不存储密码。
• 🖼️ 单一仪表板 — 在 Artifacts 下发布和管理内容；在 Gallery 下查看与你共享的所有内容。界面框架、导航和品牌统一一致。
• 🔑 API 令牌 — 用于服务器间发布（Hermes Cloud、CI）的哈希 Bearer 令牌，设有作用范围、绑定所有者且可撤销。
• ☁️ 完全基于 Cloudflare — Worker + R2（文件）+ D1（元数据）。无需运行服务器或数据库。

技术栈： TypeScript · Hono · Cloudflare Workers / R2 / D1 / Email Sending · Lemon Squeezy

尚未构建，且文案中有意不暗示已提供的功能：单个链接密码、artifact 自定义域名（品牌化工作区地址是应用主机上的路径，不是你自己的主机名）、评论/审批、公开 artifact 图库、按用量计费，以及超出各计划固定包含席位数的按席位计费。访问优先基于身份；分享链接是独立的能力 URL，可选择设置有效期，并可立即撤销。竞争分析以及完整的市场基准功能与差异化功能对比，参见 docs/POSITIONING.md。公开网站只有一个页面：rtfx.pro — 连接 MCP 服务，然后发布、分享和删除。

工作原理

                    /, /docs, /signup, /login and legal pages (public)
                                        │
Browser / CLI ─────────────────────────┼──────────────────────────▶  Worker (Hono)
                    ┌──────── app-owned email OTP / magic link ───────┐    │
                    │  rtfx_session cookie + users/accounts tables    │────┘
                    └─────────────────────────────────────────────────┘
                            files · /admin · /api                          │
                        ┌───────────────────────┬────────────────────┐      │
                        ▼                       ▼                    ▼      │
                  R2  (files at            D1 (metadata:        Email +     │
                  <slug>/v<N>/…)           artifacts, grants,   billing     │
                                           versions, sessions)  webhooks    │

• /、/signup、/login、/docs、/privacy、/terms、robots.txt、sitemap.xml 和 llms.txt 是公开的产品页面／爬虫页面。
• rtfx.pro 会话使用在通过电子邮件验证码或魔法链接验证后创建的签名 rtfx_session Cookie，对仪表板／API／制品请求进行身份验证。
• Worker 按制品授权（决定谁能看到什么），提供每个制品的当前版本，渲染公开网站和仪表板，并开放 JSON API。
• R2 将文件存储在 <slug>/v<N>/… 下；D1 存储元数据。

详情请参阅 docs/ARCHITECTURE.md。

前置条件

• Node.js 18+
• 一个 Cloudflare 账户，且账户中有一个 域名（区域）（你将通过自己控制的主机名提供服务；如果想实现与 rtfx.pro 相同的隔离，还需使用单独的内容主机名）。
• 已启用 Cloudflare Workers、R2、D1 和 Email Sending。
• npx wrangler login（授权 Workers/R2/D1/部署）

快速部署

git clone https://github.com/yogevgab/artifacts-server.git
cd artifacts-server
npm install
npx wrangler login

npm run setup

npm run setup 是适用于单主机名的简易部署方式：它会创建 R2 存储桶和 D1 数据库、应用架构、填写基本的 Worker 配置并部署，然后由你添加仅用于生产环境的选项，例如单独的内容主机名、Email Sending、账单密钥和法律声明内容。对于类似 rtfx.pro 的多主机名部署，请使用 docs/SELF_HOSTING.md 以及下面的手动步骤，而不要依赖设置脚本。

完成后，配置 Email Sending 和 SESSION_SECRET，然后打开 https://<your-domain>/signup 或 /login 创建第一个账户。wrangler.jsonc 中的 ADMIN_EMAILS 决定哪些用户拥有平台管理员权限。

手动部署

npm install
npx wrangler login

# 1. Storage
npx wrangler r2 bucket create artifacts-files
npx wrangler d1 create artifacts-meta        # copy the database_id into wrangler.jsonc
npx wrangler d1 execute artifacts-meta --remote --file schema.sql

# 2. Edit wrangler.jsonc: set route patterns to your app/content hostnames,
#    ADMIN_EMAILS, PUBLIC_BASE_URL, CONTENT_HOSTNAMES and the database_id.

# 3. Required secrets / mail
npx wrangler secret put SESSION_SECRET
# Optional, only if selling paid plans:
# npx wrangler secret put LEMONSQUEEZY_WEBHOOK_SECRET

# 4. Deploy (creates the custom domains)
npx wrangler deploy

配置

所有配置都位于 wrangler.jsonc（vars）中，另有一个密钥。请参阅其中的注释。

使用

公开产品网站

https://<your-domain>/ — 公开访问，无需登录。介绍产品定位、涵盖使用场景和差异化优势，并收集 /waitlist 访问申请。两个 CTA 有意区分：申请访问权限（适用于没有账户的用户）和 登录（/login，适用于已有账户的用户）。 /docs 是公开文档页面（发布、Claude Code/Hermes、访问模型、#why-rtfx、常见问题解答）。有关 SEO/爬虫可见内容和文案规则，请参阅 docs/PUBLIC_SITE.md；有关文案可做出的声明，请参阅 docs/POSITIONING.md。

登录

https://<your-domain>/login — 公开访问，由应用提供登录功能。系统会通过电子邮件发送一次性验证码或 magic link，验证后设置仅限当前主机的 rtfx_session cookie。页面会呈现已登出、已登录和账户已暂停等状态。在全新部署中，无需密码身份验证，也不依赖 Cloudflare Access。

控制面板

https://<your-domain>/admin — 发布制品、管理每个制品的访问权限、上传新版本／回滚，以及（仅限管理员）管理用户。每位用户（包括管理员）只能查看自己拥有或所属的制品；平台管理员无法访问其他用户的制品内容、版本、查看日志、访问列表或分享链接。「平台」部分（超级管理员）会列出所有制品的元数据（所有者、大小、数量、日期），并提供经过审计的滥用内容删除功能。图库部分位于 /admin/gallery，仅显示当前查看者可以打开的内容——即自己拥有的内容以及已分享给自己的内容。/gallery 会保留为跳转入口；未登录时访问会跳转到 /login。

用户（用户管理）

仅限管理员，可在控制面板中使用，也可通过 /api/users 访问。应用使用签名会话管理身份，并在 D1 中存储账户／用户状态：

Worker 会根据配置重新判定平台权限，绝不从用户可修改的表中读取权限。生命周期操作可以暂停／重新启用／移除账户并撤销 API 令牌，但用户管理路由会完全拒绝 API 令牌。

命令行

export ARTIFACTS_URL=https://<your-domain>
# One credential: the artifact commands go to /api/machine/…, which authenticates
# this bearer token and nothing else.
export RTFX_API_TOKEN=<rtfx_… token>

node cli/artifacts.mjs publish ./page.html --slug my-page --title "My Page"
node cli/artifacts.mjs publish ./site/ --slug demo --title "Demo"   # a folder is zipped
node cli/artifacts.mjs list
node cli/artifacts.mjs publish ./page-v2.html --slug my-page --note "new hero"  # new version
node cli/artifacts.mjs versions my-page
node cli/artifacts.mjs rollback my-page 1
node cli/artifacts.mjs grant my-page [email protected]
node cli/artifacts.mjs views my-page   # total/unique + recent views log
node cli/artifacts.mjs users                     # directory with role + status
node cli/artifacts.mjs user-add [email protected]  # invite
node cli/artifacts.mjs user-disable [email protected]  # pause + revoke their tokens
node cli/artifacts.mjs user-enable [email protected]

node cli/artifacts.mjs token-create "hermes-cloud" --owner [email protected] --scopes read,publish
node cli/artifacts.mjs tokens
node cli/artifacts.mjs token-revoke <token-id>

token-* 和 user-* 需要具备相应平台／工作区角色的应用会话 — API 令牌无法创建或撤销令牌，也无法更改谁可以登录。

远程 MCP 服务（托管）

rtfx.pro 是远程 MCP 服务。将其添加到 Claude（claude.ai、Claude Desktop 和移动端使用相同的流程：Customize → Connectors → + Add → Add custom connector），然后让 Claude 发布、分享和删除内容。分步说明（含截图）：rtfx.pro/guide。

• 端点：https://mcp.rtfx.pro/mcp（Streamable HTTP）
• 身份验证：OAuth 2.1，支持发现、动态客户端注册和客户端 ID 元数据文档 （CIMD）；无需粘贴任何内容。作用域：rtfx:read、rtfx:publish、rtfx:manage。
• Claude Code：claude mcp add --transport http rtfx https://mcp.rtfx.pro/mcp

托管服务会发布工具调用中传入的内容；它无法读取你磁盘上的路径（请改用下方的本地插件）。工具（src/mcp.ts 中的 REMOTE_TOOLS）：

Claude Code 插件（本地，stdio 替代方案）

此仓库也是一个 Claude Code 市场。安装插件后，发布就成为对话的一部分，无需单独操作：

/plugin marketplace add yogevgab/artifacts-server
/plugin install rtfx@rtfx

然后在会话中登录——无需复制、粘贴或保存令牌：

/rtfx:login

这会针对该实例运行一个使用 PKCE 的 OAuth 授权码流程，通过环回重定向，并将 0600 凭据写入 ~/.config/rtfx/credentials.json（刷新令牌会轮换；/rtfx:logout 会撤销两个令牌并删除该文件）。对于 CI 和脚本化使用，可使用环境令牌作为后备方案，且其优先级高于任何已保存的登录凭据：

export RTFX_API_TOKEN=rtfx_…            # dashboard → Integrations (scopes: read, publish)
export ARTIFACTS_URL=https://rtfx.pro   # only when self-hosting

发布器（plugins/rtfx/scripts/rtfx.mjs）无需依赖 Node 18+，因此也可以作为普通 CLI 在从未检出此仓库的机器上运行。它会拒绝上传 .env、*.pem、*.key 等类似文件，并跳过 .git/node_modules，同时打印所有排除项。

此功能现已可用，无需任何人批准——任何包含有效 .claude-plugin/marketplace.json 的仓库都是 Claude Code 市场。该插件未列入 Anthropic 的社区市场或官方市场；向前者提交所需的内容已记录在 docs/ANTHROPIC_PLUGIN_SUBMISSION.md 中。

详细信息、测试和设计说明：docs/CLAUDE_CODE.md。发行说明： plugins/rtfx/CHANGELOG.md。

Claude Desktop 扩展

从当前版本下载，或在本地构建：

https://github.com/yogevgab/artifacts-server/releases/download/v1.2.0/rtfx.dxt

npm run dxt:pack
open dist/rtfx.dxt

这会安装同一个本地 MCP 服务，无需手动编辑 claude_desktop_config.json。由于它在用户的机器上运行，因此可以发布本地路径/文件夹。使用浏览器 OAuth 凭据存储时，可将可选 API 令牌留空；只有在明确需要时才启用访问管理。 完整详情请参阅：docs/CLAUDE_DESKTOP.md。

本地 MCP 服务（stdio 替代方案）

上面的托管服务是默认选项。该插件还附带一个原生本地 MCP 服务（plugins/rtfx/scripts/rtfx-mcp.mjs），因此无法运行命令的客户端——Claude Desktop 或任何其他支持 MCP 的客户端——可以改用工具调用进行发布。安装插件后会自动注册该服务；如需手动配置 Claude Desktop，请将 claude_desktop_config.json 指向该脚本：

{
  "mcpServers": {
    "rtfx": {
      "command": "node",
      "args": ["/absolute/path/to/plugins/rtfx/scripts/rtfx-mcp.mjs"],
      "env": { "RTFX_API_TOKEN": "rtfx_…" }
    }
  }
}

工具：publish（提供不上传任何内容的 dry_run）、list_artifacts、get_versions、rollback、doctor，以及通过选择启用的环境变量控制的 update_access。令牌、权限范围和捆绑包筛选规则均相同——它只是对 CLI 所用相同库的封装，并非另一套实现。零依赖，无需 MCP SDK，Node 18+。

工具架构、客户端配置以及何时改用插件： docs/MCP.md。

API 令牌（服务到服务）

自动化发布方 — Hermes Cloud、CI、脚本 — 使用哈希 API 令牌进行身份验证，并通过 Authorization: Bearer <token> 发送，而不是通过浏览器登录：

curl -X POST "$ARTIFACTS_URL/api/machine/artifacts" \
  -H "Authorization: Bearer $RTFX_API_TOKEN" \
  -F "slug=my-page" -F "title=My Page" -F "file=@./page.html;type=text/html"

• 每个令牌仅存储其 SHA-256 哈希值；明文仅在创建时显示一次。
• 每个令牌都有一个所有者，因此遵循该所有者的权限规则 — 管理员令牌可管理所有内容，用户令牌只能管理该用户自己的制品。
• 作用域（read、publish、manage）会将令牌权限限制在所有者权限之下；绝不会扩大任何人的权限。默认值为 read,publish，因此发布集成无法删除内容。
• 令牌可撤销（token-revoke），可设置过期时间；当所有者被移出 rtfx.pro 时，令牌会自动撤销。

特意设置了两个入口。 /api/… 是仪表板的浏览器／会话 API：由应用管理的 rtfx_session 用于识别你的身份，并通过常规角色检查决定你可以执行哪些操作。/api/machine/… 是面向机器的同一制品接口 — 发布、列出、版本、回滚、查看、共享、删除 — 但需要通过更严格的门禁：必须提供 Bearer 令牌，并且会直接拒绝浏览器会话 （src/auth.ts 中的 requireApiToken）。用户管理、令牌签发和工作区成员管理 不会挂载在此处：这些操作要求使用具有相应角色的已登录应用会话，并且无论路径为何，都会拒绝 API 令牌。

完整的请求／响应约定、错误代码和回滚流程： docs/HERMES_CLOUD.md。

权限

应用通过验证通过电子邮件发送的代码或魔法链接，并设置 rtfx_session Cookie，来决定谁已登录。Worker 决定谁能查看每个制品：restricted（仅获授权的电子邮件地址）或 everyone（制品所在工作区的所有人）。平台管理员只能查看元数据，不能查看内容。新制品默认设为私有。查看者无权访问的直接 URL 会返回 404。

所有权。 每个制品都属于发布它的个人/工作区 （artifacts.owner_email / artifacts.account_id）。实例管理员（ADMIN_EMAILS / SUPER_ADMIN_EMAILS）可以管理所有内容；普通的已登录成员只能管理其工作区角色允许他们管理的制品——他们的控制面板、/api/artifacts 列表、版本预览和分析数据，都仅包含他们拥有/可管理的制品。尝试读取或更改他人的制品会返回 404，因此，他们不拥有的 slug 与不存在的 slug 无法区分。获得查看权限不会授予管理权限；如果发布到他人拥有的 slug，系统会拒绝操作（409 slug_taken），而不是向其制品添加版本。账户/用户管理仅限管理员，且 API 令牌会被这些路由明确拒绝。

没有所有者的制品（在此模型推出前发布的，或由没有电子邮件地址的旧版服务令牌发布的）只能由管理员管理。在现有数据库上运行 migrations/0005_owner_email.sql；该迁移会根据 created_by 回填真实电子邮件地址对应的所有者。API 令牌位于 migrations/0006_api_tokens.sql，本地用户/账户表则从 0007 起以增量方式添加。

账户/工作区。 制品还属于某个账户——也就是拥有该制品的工作区，也是之后计费方案对应的主体（artifacts.account_id）。每个人都会自动获得一个个人工作区；团队工作区可以有多名成员，每名成员在账户中的角色为 owner、admin、member 或 viewer。member 及以上角色可以管理工作区的制品；viewer 可以打开制品，但不能更改。

我们刻意将四个概念分开，建议仔细阅读与你相关的行：

成为工作区的 owner 并不意味着成为实例管理员，而且无法通过写入数据库来获得实例管理员身份：每次请求都会根据配置重新推导实例权限，且永远不会从表中读取。这正是测试套件重点保障的属性。

这些改动完全是增量式的。account_id 在所有位置都允许为空，仍会优先检查 owner_email；回填时未归属到账户的制品，其行为与之前完全相同。在现有数据库上运行 migrations/0008_accounts.sql、0009_account_links.sql 和 0010_backfill_accounts.sql——0008 和 0010 可以安全地重复运行，0009 会添加两列，不能重复运行（请先检查 PRAGMA table_info(artifacts)）。这些迁移都不是严格必需的：Worker 会在首次使用时创建相同的记录。完整模型请参阅 docs/ARCHITECTURE.md。

版本管理

每次向现有 slug 发布内容，都会创建一个新的不可变版本并使其上线。在免费方案中，会保留最近的五个版本，较早的版本会过期——其字节数据会被删除，但历史记录仍会保留，因此版本列表不会出现空缺。付费方案会保留所有版本。之前的 版本会保留。管理员可以在 /v/<slug>/<n>/ 预览任意版本；可以从控制面板回滚，或运行 rollback <slug> <n>。

查看日志

当已登录用户加载 HTML 页面时，每个制品都会记录一次查看（资源、机器／服务令牌获取以及管理员版本预览不计入）。管理面板和 views <slug> 会显示总数／独立查看人数以及近期日志（时间 · 查看者 · 版本 · 国家）。查看记录会无限期保留；如果 artifact_views 表变得过大，请清理该表。

开发

npm install
npm run dev        # wrangler dev on http://localhost:8787 (DEV_LOGIN: no sign-in, you are admin)
npm test           # vitest (unit + integration via @cloudflare/vitest-pool-workers)
npm run typecheck
npm run validate:plugin  # structural check of the Claude Code plugin files
npm run check      # typecheck + tests + plugin validation

本地环境不会进行真实的电子邮件验证。要模拟特定查看者，请发送 X-Dev-Email 标头；要模拟已退出登录的访客（例如，查看 /gallery 是否会重定向到 /login），请发送 X-Dev-Anonymous: true。只有在 DEV_LOGIN=true 时才会启用这两项设置；npm run dev 会设置该变量——生产环境中绝不会启用。

# once, seed the local DB:
npx wrangler d1 execute artifacts-meta --local --file schema.sql

贡献

欢迎提交问题和 PR——请参阅 CONTRIBUTING.md。提交 PR 前，请运行 npm run check。安全问题报告：请参阅 SECURITY.md——通过 GitHub Security Advisories 提交，切勿公开提交问题。

自托管

运行自己的实例所需的一切都在此仓库中；你需要自行提供 Cloudflare 账户、R2/D1、邮件发送渠道、会话密钥、可选的 Lemon Squeezy 计费配置，以及自己的法律信息——/privacy 和 /terms 页面以运营方模板形式提供，并在页面上注明这一点。请参阅 docs/SELF_HOSTING.md。

开源，以及界限所在

源代码采用 MIT 许可，并且有意公开：访问控制产品应允许你查看负责执行访问控制的代码。Worker、插件、本地和远程 MCP 服务、CLI、测试和文档都在此处；在你自己的机器上运行的部分不会有所保留。

托管的 rtfx.pro 服务独立于此源代码运行。其客户数据、实时账户配置、支持和计费流程以及商业材料均不在此仓库中；名称、标志和域名也不属于 MIT 授权范围，因为 MIT 是版权许可，并不授权使用商标。你可以分叉并运行它；请使用自己的名称。

完整的界限说明——哪些内容有意公开、哪些内容不会公开，以及原因——请参阅 OPEN_SOURCE.md。威胁模型、插件的凭据处理方式，以及本地 MCP 与远程 MCP 的界限，请参阅 SECURITY.md。

许可证

MIT