publish-on-qutke（发布到趣客）

on.qutke.cn

Skill 版本: 1.0.1

将任何文件或文件夹创建为一个在线 URL。仅支持静态托管。

环境要求

• 必需的命令行工具：curl、file、jq
• 可选环境变量：$ONQUTKE_API_KEY
• 可选凭据文件：~/.onqutke/credentials

创建站点

./scripts/publish.sh {文件或目录}

输出在线 URL（例如 https://a-big-apple-xj7d.on.qutke.cn/）。

底层是三步流程：创建/更新 -> 上传文件 -> 完成发布。站点在完成发布（finalize）成功之前不会上线。

不使用 API Key 时会创建一个 匿名站点，24 小时后过期。 使用已保存的 API Key 时，站点永久有效。

文件结构： 对于 HTML 站点，请将 index.html 放在发布目录的根目录下，而不是子目录中。目录的内容会成为站点的根路径。例如，发布 my-site/ 目录（其中包含 my-site/index.html）——不要发布包含 my-site/ 的上层目录。

也可以发布非 HTML 的原始文件。单个文件会获得一个富媒体预览器（支持图片、PDF、视频、音频）。多个文件则会生成一个自动目录列表，包含文件夹导航和图片画廊。

更新已有站点

./scripts/publish.sh {文件或目录} --slug {slug}

更新匿名站点时，脚本会自动从 .onqutke/state.json 加载 claimToken。如需覆盖，请传入 --claim-token {token}。

已认证站点的更新需要已保存的 API Key。

客户端标识

使用 --client 参数让 on.qutke.cn 能按 agent 追踪发布可靠性：

./scripts/publish.sh {文件或目录} --client cursor

这会在发布 API 调用中发送 X-OnQutke-Client: cursor/publish-sh 头。 如果省略，脚本会发送一个默认值。

API Key 存储

发布脚本按以下优先级读取 API Key（匹配第一个）：

1. --api-key {key} 参数（仅用于 CI/脚本场景——避免在交互使用中传入）
2. $ONQUTKE_API_KEY 环境变量
3. ~/.onqutke/credentials 文件（推荐 agent 使用）

保存 Key，将其写入凭据文件：

mkdir -p ~/.onqutke && echo "{API_KEY}" > ~/.onqutke/credentials && chmod 600 ~/.onqutke/credentials

重要：收到 API Key 后请立即保存——自行执行上述命令。不要让用户手动运行。避免在交互会话中通过 CLI 参数（如 --api-key）传递 Key；凭据文件是推荐的存储方式。

切勿将凭据或本地状态文件（~/.onqutke/credentials、.onqutke/state.json）提交到版本控制系统。

状态文件

每次站点创建/更新后，脚本会在工作目录写入 .onqutke/state.json：

{
  "publishes": {
    "a-big-apple-xj7d": {
      "siteUrl": "https://a-big-apple-xj7d.on.qutke.cn/",
      "claimToken": "abc123",
      "claimUrl": "https://on.qutke.cn/claim?slug=a-big-apple-xj7d&token=abc123",
      "expiresAt": "2026-02-18T01:00:00.000Z"
    }
  }
}

在创建或更新站点之前，可以检查此文件以查找之前的 slug。 将 .onqutke/state.json 视为内部缓存。 切勿将此本地文件路径当作 URL 展示，也切勿将其作为认证模式、过期时间或认领 URL 的唯一来源。

告知用户的内容

• 始终分享当前脚本运行输出的 siteUrl。
• 读取脚本 stderr 中的 publish_result.* 行来确定认证模式。
• 当 publish_result.auth_mode=authenticated 时：告诉用户站点永久有效，已保存到他们的账户。无需认领 URL。
• 当 publish_result.auth_mode=anonymous 时：告诉用户站点 24 小时后过期。分享认领 URL（如果 publish_result.claim_url 非空且以 https:// 开头），以便用户永久保留站点。提醒认领令牌仅返回一次且无法恢复。
• 切勿让用户去查看 .onqutke/state.json 来获取认领 URL 或认证状态。

使用限制

获取 API Key

从匿名（24 小时）升级为永久站点：

1. 向用户索取邮箱地址。
2. 请求一次性登录验证码：

curl -sS https://on.qutke.cn/api/auth/agent/request-code \
  -H "content-type: application/json" \
  -d '{"email": "user@example.com"}'

1. 告诉用户："请查看您的收件箱，找到来自 on.qutke.cn 的验证码并粘贴到这里。"
2. 验证代码并获取 API Key：

curl -sS https://on.qutke.cn/api/auth/agent/verify-code \
  -H "content-type: application/json" \
  -d '{"email":"user@example.com","code":"ABCD-2345"}'

1. 自行保存返回的 apiKey（不要让用户操作）：

mkdir -p ~/.onqutke && echo "{API_KEY}" > ~/.onqutke/credentials && chmod 600 ~/.onqutke/credentials

脚本参数

复制站点

curl -sS -X POST https://on.qutke.cn/api/v1/publish/{slug}/duplicate \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

在新 slug 下创建站点的完整副本。所有文件在服务器端复制——无需上传。新站点立即上线。需要认证且必须拥有源站点的所有权。

可选择覆盖预览器元数据（与源站点的元数据浅合并）：

curl -sS -X POST https://on.qutke.cn/api/v1/publish/{slug}/duplicate \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"viewer": {"title": "我的副本"}}'

更多操作

删除、元数据修改（包括密码保护）、复制、认领、列表等操作，请参阅 references/REFERENCE.zh.md。

Handle（标识）

Handle 是用户拥有的子域名命名空间（例如 yourname.on.qutke.cn），可将路径路由到您的站点。申请 Handle 需要付费计划（Hobby 或以上）。

• Handle 接口：/api/v1/handle
• Handle 格式：小写字母/数字/连字符，2-30 个字符，不能以连字符开头或结尾

自定义域名

使用您自己的域名（例如 example.com）来提供站点服务。自定义域名：免费版 1 个，Hobby 版最多 5 个。

• 域名接口：/api/v1/domains 和 /api/v1/domains/:domain

添加自定义域名

curl -sS https://on.qutke.cn/api/v1/domains \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

响应包含 is_apex、DNS 指引，以及（对于顶级域名）一个带有 TXT 记录详情的 ownership_verification 对象。

按域名类型配置 DNS：

• 子域名（例如 docs.example.com）：添加一条 CNAME 记录指向 fallback.on.qutke.cn。
• 顶级域名（例如 example.com）：

1. 添加一条 ALIAS 记录指向 fallback.on.qutke.cn。（您的 DNS 提供商可能将其称为 ANAME 或 CNAME 扁平化。） 2. 使用响应中 ownership_verification 字段的 name 和 value 添加一条 TXT 记录。

DNS 验证通过后，SSL 会自动配置。

检查域名状态

curl -sS https://on.qutke.cn/api/v1/domains/example.com \
  -H "Authorization: Bearer {API_KEY}"

状态在 DNS 验证和 SSL 激活前为 pending，之后变为 active。对于顶级域名，响应包含 ownership_verification 的 TXT 记录详情，如有问题还会包含 verification_errors。

列出自定义域名

curl -sS https://on.qutke.cn/api/v1/domains \
  -H "Authorization: Bearer {API_KEY}"

删除自定义域名

curl -sS -X DELETE https://on.qutke.cn/api/v1/domains/example.com \
  -H "Authorization: Bearer {API_KEY}"

删除域名及其下的所有链接。

链接（Links）

链接将站点连接到您的 Handle 或自定义域名上的某个位置。相同的接口同时适用于两者——省略 domain 参数则指向 Handle，包含它则指向自定义域名。

• 链接接口：/api/v1/links 和 /api/v1/links/:location
• 路径参数中根位置的标识符：__root__
• 变更在全球范围内最多 60 秒内生效（Cloudflare KV）

链接到您的 Handle：

curl -sS https://on.qutke.cn/api/v1/links \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"location": "docs", "slug": "a-big-apple-xj7d"}'

链接到自定义域名：

curl -sS https://on.qutke.cn/api/v1/links \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"location": "", "slug": "a-big-apple-xj7d", "domain": "example.com"}'

空的 location 使其成为首页（例如 https://example.com/）。使用 "location": "docs" 对应 https://example.com/docs/。