ShareOut 技能

ShareOut 能将文件转化为可共享的 Web 工件，支持持久化数据、实时协作、文件存储、集成和自动化。它支持 HTML 应用以及 CSV、Markdown、JSON 和 TXT 查看器。

这是规范技能。执行每个 ShareOut 任务时，应首先加载此技能。

版本检查 — 强制第一步

在执行其他任何操作之前，请确认您拥有最新技能。此文件的 YAML 前置元数据中的 version 字段是您当前持有的版本（当前为 2.21.0）。

GET https://shareout.site/v1/skill/version → { "version": "...", "updated_at": "..." }。
如果返回的 version 比此文件的 version 新，说明版本已过时：下载 GET https://shareout.site/v1/skill（完整技能文件夹的 zip 包），解压缩，丢弃旧副本，然后使用解压后的文件继续。
如果版本匹配，则继续。

不要跳过此检查。使用过时的技能会导致错误的端点和行为。

计划模型

ShareOut 有两个计划：

计划	使用此技能的行为
个人版	仅使用此基础技能。构建、发布、更新、自动化和管理用户自己的工件。
团队版	首先使用此基础技能，然后加载团队覆盖层以进行工作区管理或团队专属功能。

团队版是附加功能。切勿使用团队覆盖层来代替此基础技能。

代理加载协议

从此文件开始。
如果用户提到团队、工作区、成员、内部工作区共享、子域、工作区自定义风格、工作区计划或管理员控制，若尚不明确，请询问用户是否使用 团队版 计划。
如果用户不使用团队版，则保持个人模式，不加载或不应用团队专属指令。
如果用户使用团队版，则加载 team/SKILL.md。如果提供了工作区 slug/id 和令牌，则执行 GET /v1/skill?workspace={slugOrId} — zip 包中包含一个额外的 workspace-context.md 文件，其中包含团队规则。
使用 INDEX.md 按需加载详细文件。

初始提问

在推荐实施方案之前，需明确：

他们正在构建什么？仪表板、表单、报告、工具、文档、数据表格、演示文稿还是自动化应用。
使用者是谁？仅所有者、受邀人员、团队工作区还是公众。
需要什么数据？无、简单状态、结构化记录、文件、实时外部数据或实时协作。
发布后应该做什么？分享链接、收集数据、发送通知、计划交付、指标告警、接收并处理入站电子邮件，或让查看者与 AI 聊天。

模式路由器

用户意图	首先加载	然后根据需要
发布 HTML/CSV/Markdown/JSON/TXT	`api/artifact-types.md`	`api/artifacts.md`, `core/source-editor.md`, `auth.md`
构建 HTML 应用/页面/仪表板/表单	`core/html-spec/overview.md`	`modules/ui/overview.md`, `patterns/overview.md`
使其美观/有好的设计品味/避免通用的 AI 外观	`modules/ui/taste.md`	`modules/ui/overview.md`
保存简单状态	`sdk/json.md`	`core/html-spec/manifest.md`
存储记录/提交	`sdk/table.md`	`patterns/forms.md`, `patterns/tables.md`
可编辑的电子表格网格	`sdk/grid.md`	`sdk/table.md`, `integrations/google-sheets.md`
上传文件/图片	`sdk/blobs.md`	`patterns/uploads.md`
使用实时外部数据	`sdk/live-data.md`	`sdk/connections.md`, `integrations/overview.md`
构建实时协作	`sdk/realtime.md`	`modules/_shared/permissions.md`
添加评论	`sdk/comments.md`	`modules/_shared/permissions.md`
添加工件内 AI 聊天	`agents/overview.md`	`agents/context.md`
通过 Telegram 与页面聊天	`agents/telegram.md`	`api/jobs.md`
通过 Slack 与页面聊天（DM 机器人）	`agents/slack.md`	`integrations/slack.md`, `agents/telegram.md`
在浏览器中运行 Python	`sdk/python.md`	`sdk/overview.md`
发送电子邮件或模板	`sdk/email.md`	`api/templates.md`
接收邮件 / 将邮件转发到工件 / 通过入站邮件触发	`integrations/inbound-email.md`	`api/jobs.md`
定时仓库/json 快照刷新（确定性的）	`api/jobs.md`	`agents/crew.md`, `sdk/connections.md`
工件团队（查询 → 总结 → 交付）	`agents/crew.md`	`api/jobs.md`, `integrations/slack.md`
请求访问私人页面	`modules/_shared/permissions.md`	`core/access-policy.md`
计划交付或 Webhooks	`api/jobs.md`	`api/destinations.md`
当指标超过阈值时发出告警	`api/metric-alerts.md`	`patterns/dashboards.md`
团队工作区/管理员/子域/上下文	`team/SKILL.md`	`team/INDEX.md`
团队发布治理（公开需成员批准）	`team/publish-governance.md`	`team/SKILL.md`, `modules/_shared/publishing.md`
团队技能市场（可复用的剧本）	`team/skill-marketplace.md`	`team/workspace-context.md`, `agents/overview.md`

数据选择

选择最小的合适存储：

简单状态：主题、过滤器、上次打开 -> sdk.json
结构化记录：任务、提交、订单 -> sdk.table()
实时编辑：文档、白板、多人 UI -> sdk.realtime()
文件：图片、PDF、附件 -> sdk.blobs
实时外部系统：REST、BigQuery、Mixpanel、仓库 -> sdk.connection / live-data

不要将数据选择与账户计划混淆。sdk.json、sdk.table() 和 sdk.realtime() 是数据存储方式，而非计费计划。

SDK 加载

<head>
  <link rel="stylesheet" href="https://shareout.site/sdk/shareout.css">
  <script src="https://shareout.site/sdk/shareout-ui.js" defer></script>
  <script src="https://shareout.site/sdk/shareout.js"></script>
</head>
<script>
(async () => {
  const sdk = await ShareOut.create();
})();
</script>

规则：

在调用 ShareOut.create() 之前加载 https://shareout.site/sdk/shareout.js。
优先使用 await ShareOut.create() 而不是 new ShareOut()，以确保嵌入的 Bearer 令牌已就绪。
发布的 HTML 在 {hex}.shareoutcdn.site 的沙箱 iframe 中运行；请使用 SDK 方法，而不是直接使用 fetch 调用 /v1/data/...。详见 sdk/live-data.md。
引用 https://shareout.site/sdk/shareout.css 并在编写自定义 CSS 之前使用 .so- 类。详见 modules/ui/overview.md。
不要使用 cdn.jsdelivr.net 上的 ShareOut SDK URL。

HTML 工件规则

HTML 工件无论是否包含 ShareOut 的结构标记都可以正常工作——发布永远不会被阻止。但是，工件声明的信息越多，可视化编辑器 能够对其进行操作的就越多（大纲导航、内联编辑、添加/删除行）。默认目标是编辑器就绪；仅在故意创建一个一次性的静态页面时跳过。

编辑器就绪清单（编辑器所查找的内容）：

文档 head 中包含一个 script type="shareout/manifest" 标签，其内容为有效的 JSON。
所有用到的 sdk.json 键和 sdk.table() 名称都已在清单的 sources 中声明。
动态内容带有 data-shareout-binding 属性，并且每个绑定都引用了一个已声明的源。
页面使用 data-shareout-page（驱动编辑器大纲）；重复内容使用 data-shareout-template。
交互目标已解析：data-shareout-link / data-shareout-action 指向实际的页面/部分/模态框/标签页；模态框有触发打开的触发器；表单有提交操作。
在 sources 上声明 default 样本数据 — json、tables 以及 connections（例如 BigQuery/Snowflake/Sheets 等实时连接器：sources.connections.<name>.default 是一个样本行数组）。可视化编辑器预览数据时不进行实时获取或查询（它会从此默认值或空值解析所有 SDK 读取操作，包括 sdk.connection(...).query()），因此，即使工件将其 UI 隐藏在 await sdk.table(...).exec() / 连接器查询之后，它仍能渲染并保持可编辑。没有 default 的源将显示为空白预览。

每次发布 HTML 工件都会返回一个建议性的 editor_readiness 配置文件（参见 api/artifacts.md），该文件对这些项进行评分并说明每个差距导致哪些功能被禁用。与用户分享一行摘要，但将其视为指导而非限制——他们可以精确发布他们想要的任何内容。

完整规范：core/html-spec/overview.md。

设计品味

编辑器就绪是关于结构的，而不是外观。外观是一个单独的、有意的决定——而 AI 构建的页面的默认值是“模板化和通用的”。在构建任何视觉内容之前，请阅读 modules/ui/taste.md：它总结了如何交付看起来专业设计而非自动生成的工件。简而言之：

使用设计系统（.so- 类 + 令牌）——它自带品牌字体、暖色明亮调色板以及协调的间距/阴影，因此您可以免费继承良好的品味。参见 modules/ui/overview.md。
品味是克制： 一种强调色、一个字体系统、每屏一个主要操作、充足的留白、仅在必要时使用动效。
避免 AI 生成的痕迹： 紫色/霓虹发光、三张等宽卡片排版、眉毛式文本、虚假完美的数字、营销套话、缺失的空/错误状态。完整的禁用列表和发布前检查清单位于 modules/ui/taste.md 中。

工件类型

ShareOut 会根据 MIME 类型或文件扩展名自动检测类型：

类型	扩展名	用途
`html`	`.html`, `.htm`	完整的 SDK 应用、仪表板、工具、演示文稿
`csv`	`.csv`	可排序/可过滤的数据网格
`markdown`	`.md`, `.markdown`	带渲染 HTML 和目录的文档
`json`	`.json`	可折叠的树形查看器
`txt`	`.txt`	纯文本/日志查看器

详情：api/artifact-types.md。

首次运行 — 获取令牌

每个经过身份验证的操作都需要一个令牌。如果 ~/.shareout/credentials 尚不存在，则用户没有账户——在发布或进行其他任何经过身份验证的调用之前引导创建账户：

POST https://shareout.site/v1/auth/create-account（唯一一个未经身份验证的端点，无请求体）→ { "token": "so_…", "user_id": "usr_…" }。
将 token 保存到 ~/.shareout/credentials，格式为 { "token": "so_…" }（chmod 600）。
后续所有请求使用 Authorization: Bearer so_…。

账户创建有 IP 频率限制（错误码：RATE_LIMIT_EXCEEDED，HTTP 429）。该账户是匿名且无头的——无需电子邮件即可发布。

然后询问用户是否要连接 Gmail/Google。 新创建的账户没有电子邮件，因此只能通过存储的令牌使用。关联电子邮件可让他们登录 Web UI 以访问 https://shareout.site（主页仪表板、可视化编辑器、自助 API 令牌）。提供两种路径：

Google： 在浏览器中打开 GET https://shareout.site/v1/auth/link-google（使用 Bearer 令牌）来关联他们的 Google 账户。
邮箱验证码： POST /v1/auth/link-email/start { "email" } → POST /v1/auth/link-email/verify { "email", "code" }（6 位验证码，10 分钟有效期）。

如果他们拒绝，仅使用令牌的流程将继续正常工作。完整的设置和关联参考文档见 auth.md。

发布

ShareOut 受 Cloudflare 保护。Python 的 requests 库可能会触发 1010 拦截。请按照您的意愿构建负载，然后通过管道传给 curl：

TOKEN=$(python3 -c "import json,os; print(json.load(open(os.path.expanduser('~/.shareout/credentials')))['token'])")
python3 build_payload.py | curl -sS -X POST 'https://shareout.site/v1/publish' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @-

完整 API：api/overview.md。

团队边界

个人工件仍然可以设为私有、与协作者共享、公开或不公开。仅在团队计划的工作区功能时才加载团队文档：

工作区成员和角色。
内部工作区可见性（visibility: "workspace"）。
基于电子邮件/域名的工作区成员策略。
工作区子域名。
用于团队风格的工作区上下文文件。
工作区级别的计划、自动化、功能标志和管理员视图。

重要的术语区分：

术语	含义
`access_policy`	行级别的工件数据过滤：每个查看者只能看到允许的行。参见 `core/access-policy.md`。
工作区成员策略	Teams 电子邮件/域名成员规则：谁可以加入工作区。参见 `team/SKILL.md`。
协作者角色	工件级别的 `owner`、`editor`、`viewer`。
工作区角色	Teams 工作区的 `owner`、`admin`、`member`。

版本检查

在每个任务之前执行强制版本检查。以下是三种等效方式来比较您持有的版本与最新版本：

GET  https

…

[内容已被截断以进行翻译]

getshareout/shareout-skill

shareout-skill 是什么？

在你喜欢的 AI 中提问

文档

ShareOut 技能

版本检查 — 强制第一步

计划模型

代理加载协议

初始提问

模式路由器

数据选择

SDK 加载

HTML 工件规则

设计品味

工件类型

首次运行 — 获取令牌

发布

团队边界

版本检查

相关技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me