shareone（shareone 文档）

AI Agent 技能：发布到 ShareOne (shareone)

这个 Skill 允许 AI Agent（如Openclaw等）将当前生成的历史会话以及HTML/PDF/PPT等文件，自动发布到 ShareOne 线上托管服务，并为用户生成一个持久化的公网分享链接。

使用说明与触发条件

如何触发 (Triggering): 当用户表达出以下意图时，应主动调用此技能：

• "帮我把 index.html 发布到 ShareOne"
• "把我刚才生成的网页发布，给我个链接"
• "生成一个可分享的链接给我的团队看"
• "Upload this presentation to ShareOne and protect it with password 'secret'"
• "发布这个 PDF 到 ShareOne，并加上密码 1234"
• "把这个网页发布到 ShareOne，加上水印 '内部绝密'"
• "用 shareone 分享上一轮对话"
• "把我刚才写的代码/大段文字分享出去"
• "Share your last response as a note"

前置条件 (Prerequisites): 用户需要拥有 ShareOne 的 API 凭证 (API Key)。请确保已在环境变量中设置 SHAREONE_API_KEY。

核心执行指令 / Execution Instructions

当你被要求发布文件到 ShareOne 时，请严格按照以下步骤执行：

1. 识别目标与环境预检 (Identify & Pre-flight)

找出用户明确指定要发布的文件，或者提取对话内容：

• 如果用户要求分享对话/大段文本/代码：请首先从你的对话历史中提取上一轮生成的完整文本或代码块。将其保存到当前目录下的一个临时文件中，例如 share_note.md 或 share_note.html。

- 建议：如果是 Markdown 格式内容，建议在保存为 .html 前，使用简单的 HTML 模板包裹它，或者在 ShareOne 后端支持 Markdown 渲染的情况下直接发送 Markdown。如果无法确定，优先生成美观的 .html 文件。

• 如果用户指定了文件：使用用户指定的文件。如果用户没有指定，请根据上下文寻找你最近一次生成或编辑的文件（如 .html, .pdf, .pptx）。

• 校验文件是否存在：如果你通过上述步骤生成或锁定了文件，但文件仍不存在，停止并告知用户。
• 获取或创建 API Key：执行本技能目录下的 check_api_key.js 脚本，它会依次检查环境变量、本地配置文件。如果都没有找到，脚本会输出 KEY_NOT_FOUND。

node scripts/check_api_key.js

• 如果脚本输出 KEY_FOUND:<api_key>：将该 API Key 用于后续的发布请求，直接进入第 2 步。
• 如果脚本输出 KEY_NOT_FOUND：你必须暂停发布流程，并向用户询问是否已有 API Key：

> 💡 提示：我没有找到您的 ShareOne API Key。 > 请问您是否已经拥有 API Key？ > > - 如果有，请直接回复您的 API Key（例如 sk-xxx），我将为您保存并继续发布。 > - 如果没有，请回复“没有”或“创建”，我将自动为您创建一个临时 API Key。

• 根据用户的回复进行处理：

- 如果用户回复了 API Key (例如 sk-xxx)： 执行本技能目录下的 save_api_key.js 脚本将用户提供的 Key 保存到本地，然后使用该 Key 继续发布（进入第 2 步）：

    node scripts/save_api_key.js <用户提供的KEY>

- 如果用户回复“没有”或“创建”： 执行本技能目录下的 create_guest_key.js 脚本调用接口创建临时 API Key 并保存到本地：

    node scripts/create_guest_key.js

- 如果输出 GUEST_KEY_CREATED:<api_key>：将该 API Key 用于后续的发布请求，并在回复用户时加入以下提示： > 💡 提示：已为您自动分配了临时 API Key：<api_key>。 > 为了方便您后续管理分享的链接，请前往 ShareOne 官网 绑定您的永久账号。 - 如果输出 ERROR:RATE_LIMIT_EXCEEDED：请暂停发布，并提示用户： > ❌ 获取临时凭证失败 > 您今天自动创建临时 API Key 的次数已达上限（每天最多5次）。请前往 ShareOne 官网 手动注册并获取 API Key。

2. 免责声明机制 (Smart Consent) - 必须执行 (MANDATORY)

检查当前目录下是否存在 .shareone_agreed 文件。

• 如果存在：静默跳过此步骤，直接进入第 3 步。
• 如果不存在：你必须向用户展示安全提示，并等待用户明确回复“同意”或“agree”后才能继续：

> ⚠️ 发布前安全提示 > 在将页面发布到公网前，请您确认该页面内容符合相关法律法规要求。禁止发布反动、涉政、暴力、色情、侵权或恶意代码。上传的内容将免费托管保留 90 天。 > 如果您的内容符合要求，请回复 “同意”，我将为您发布。

• 用户同意后：立即执行 touch .shareone_agreed，记录状态，然后再继续。

3. 判断发布类型：创建 (POST) 还是 更新 (PUT)

检查对话上下文。如果你在这个会话中，已经为同一个文件生成过 ShareOne 链接，你应该提取之前的 share_id（16位字符串）。

• 如果有 share_id，接下来执行更新 (PUT)。
• 如果没有，执行首次创建 (POST)。

4. 构造请求并执行发布 (Execute Request)

根据文件类型和操作类型构造请求。提取用户可能要求的密码 (password) 和水印 (watermark)。为了最大兼容性，推荐使用 Node.js 脚本发起 HTTP 请求。

场景 A：文本、代码或纯 HTML 文件 (.html, .md, .txt)

⚠️ 警告 (CRITICAL): 绝对不要通过这个接口上传任何二进制文件（如 .ppt, .pptx, .pdf, .zip, .png 等），否则服务器会返回 400 Bad Request 错误（提示检测到二进制内容）。如果你看到此类错误，请立即更换为 场景 B 的 /api/v1/files 接口重新上传。

接口：https://shareone.app/api/v1/pages 格式：application/json

对于提取的对话、大段文字或独立的代码块，请将其包装为一段美观的 HTML（含基础样式）以保证展示效果：

如果是首次创建 (POST):

执行本技能目录下的 upload_page.js 脚本：

node scripts/upload_page.js <YOUR_FILE_PATH> --api-key $SHAREONE_API_KEY --filename "YOUR_FILE_NAME" [--password "OPTIONAL_PASSWORD"] [--watermark "OPTIONAL_WATERMARK"]

如果是更新已有链接 (PUT):

执行本技能目录下的 upload_page.js 脚本，并传入 --share-id 参数：

node scripts/upload_page.js <YOUR_FILE_PATH> --api-key $SHAREONE_API_KEY --filename "YOUR_FILE_NAME" --share-id <YOUR_SHARE_ID>

场景 B：二进制文件 (PDF, PPTX 等)

由于二进制文件可能较大，ShareOne 采用直传云存储（支持 S3 或 Azure）的方式。请直接调用本技能目录下的 shareone_upload.js 脚本进行上传（脚本会自动根据服务端返回的 upload_type 字段判断是走 S3 表单上传还是 Azure 的 PUT 直传）：

如果是首次创建 (POST):

node scripts/shareone_upload.js <FILE_PATH> --api-key $SHAREONE_API_KEY [--password "OPTIONAL_PASSWORD"] [--watermark "OPTIONAL_WATERMARK"]

如果是更新已有链接的密码或水印 (PUT):

对于已经上传的二进制文件，如果用户要求修改密码或水印，请调用 update_file_meta.js 脚本（假设存在，或通过 curl 直接调用 /api/v1/files/{share_id} 接口）：

curl -X PUT "https://shareone.app/api/v1/files/<YOUR_SHARE_ID>" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: $SHAREONE_API_KEY" \
     -d '{"password": "NEW_PASSWORD", "watermark": "NEW_WATERMARK"}'

_(注意：传空字符串 "" 表示取消密码或水印)_

5. 异常处理与结果反馈 (Feedback)

解析接口返回的 JSON。

• 发布成功 (HTTP 200/201):

- 获取分享链接: - 接口和脚本的返回结果中已经包含了完整的 share_url 字段（例如 https://shareone.app/s/<share_id>）。 - 你必须直接使用接口或脚本返回的 share_url 展示给用户，不要自己尝试拼接链接。 - 如果设置了密码，务必在回复中加粗显示密码： > 🎉 发布成功！ > 🔗 链接: <返回的 share_url> > 🔑 提取码: <密码> - 功能提示 (Feature Discovery): 在本次会话首次向用户展示生成的短链接时，请主动（但简短且友好地）提示他们支持未使用的功能，以便用户了解更多高级特性。后续发布不再提示。 - 如果用户未使用密码和水印，提示： > “💡 提示：您也可以让我为分享链接‘加上访问密码’或‘添加自定义水印’，以更好地保护您的内容。” - 如果用户使用了密码但未使用水印，提示： > “💡 提示：除了密码，您也可以让我为内容‘添加自定义水印’。” - 如果用户使用了水印但未使用密码，提示： > “💡 提示：除了水印，您也可以让我为分享链接‘加上访问密码’。” - 如果用户同时使用了密码和水印，则不进行任何提示。

• 内容违规拦截 (HTTP 400): 提取 JSON 中的 detail 字段展示给用户，如："❌ 发布失败，内容未通过安全审核。原因：<detail>"
• API Key 无效 (HTTP 401): 提示用户 "API Key 无效或权限不足"。
• 找不到页面 (HTTP 404): 若 PUT 更新遇 404，说明原页面已被后台删除，请询问用户是否作为新页面重新 POST。