00Widget

00Widget

为所有 Agent 提供 Widget。

一款可复用的 Apple 平台配套应用和 Cloudflare Worker 后端，通过 Widget、实时活动、灵动岛和 Apple TV 仪表板，为 Claude、ChatGPT、自动化流程及你构建的软件提供原生输出渠道。

服务端不会发送 UI，而只会发送符合一小组模板规范的结构化状态。Apple 应用通过预定义的 SwiftUI 视图渲染这些状态。

选择连接方式

Claude、ChatGPT 和其他 MCP 宿主

支持模型上下文协议的宿主可以直接向 00Widget 发布内容，无需编写集成代码：将 <BASE_URL>/mcp 添加为自定义连接器，登录并选择租户即可。这些工具封装了与 REST 路由相同的处理程序，因此两种接口不会出现偏差。

MCP 默认关闭（wrangler.toml 中的 MCP_ENABLED），因为它会公开一个可在公共互联网中签发 API 令牌的浏览器流程。批准连接器需要先登录，签发的凭据是普通的租户令牌，仅限批准者自己的帐户使用，可从 /admin 撤销。

详情：server/README.md → “MCP”。

无需改动该连接器，即可测试增量式 MCP Apps UI：使用 MCP_PREVIEW_ENABLED = "true" 部署相同的 Worker，然后将 <BASE_URL>/mcp-preview 添加为单独的开发者模式连接。它会添加由版本化 HTML 资源支持的只读 render_card、render_activity 和 render_dashboard 工具；/mcp 保持现有的发现和工具契约不变。

应用、脚本、自动化流程和编码 Agent

如果你正在另一个仓库中（例如 CI 流水线或家庭自动化脚本），并希望让 Claude Code / Codex 向你的 00Widget 实例发布状态，请将以下内容粘贴给 Agent——其中包含所有必要信息：

Integrate this project with 00Widget so its state shows up on iOS widgets and Live Activities.

Read the integration contract: https://github.com/morais/00widget/blob/main/docs/llms.md
That single document is everything you need — don't pull in the rest of the 00Widget repo.

Operator-supplied env vars:
  00WIDGET_BASE_URL=https://api.example.com
  00WIDGET_API_KEY=<bearer token>

Verify both work with `curl $00WIDGET_BASE_URL/health` and an authenticated `GET /v1/cards` before writing any code.

Then:
1. Identify the surfaces in this project that an iOS widget should reflect (status, build state, queue depth, in-progress jobs, etc.).
2. For each, pick a template (`summary`, `progress`, `list`, `action`, `chart`, `history`, `breakdown`, `briefing`, or `timeline`) per llms.md's decision matrix.
3. Add the smallest possible publish path — POST one card to `/v1/cards/upsert`, or one related snapshot to `/v1/cards/upsert-batch`, using stable ids. No SDK, no class hierarchy.
4. If something is time-bounded with a clear end (a build, a charge cycle, a delivery), use a Live Activity instead of a card.

Constraints:
- Use a stable `id` per logical thing — never embed timestamps or run ids.
- Never put secrets or PII in card fields. They render on the Lock Screen.
- Always end Live Activities. Never make destructive actions auto-run from widgets.
- Don't publish more than ~once a minute per card unless the value actually changed.

If this project is itself a Cloudflare Worker, see the "Notes for Cloudflare Workers callers" section in llms.md — same-account integrations should use a Service Binding instead of a public HTTPS fetch.

架构

00widget/
  ios/          # SwiftUI app + WidgetKit extension + Live Activity (iOS 26+)
  server/       # Cloudflare Worker (TypeScript) — REST API + APNs fan-out
  examples/     # curl scripts showing how any agent can publish state
  marketing/    # Screenshot and App Preview sources, docs, and entry points
  artifacts/    # Generated marketing output (ignored by Git)

快速开始

1. 后端

cd server
npm install
install -m 600 .dev.vars.example .dev.vars   # fill in SESSION_SECRET; enable the local fallback only when needed
npx wrangler dev

然后：

curl -s http://localhost:8787/health

2. 示例

cd examples
install -m 600 env.example.sh env.sh   # edit BASE_URL and API_KEY
./upsert-solar.sh

3. iOS

需要 macOS、Xcode 26+、iOS 26 模拟器或设备，以及 XcodeGen。

brew install xcodegen
cd ios
xcodegen
open ZeroZeroWidget.xcodeproj

在 Xcode 中，将 Bundle ID 和 App Group 改为你的 Apple Developer 团队拥有的值（参见 ios/README.md），然后运行。

数据模型

参见 ios/Sources/Shared/Models/（Swift）和 server/src/types.ts（zod）——两者保持同步。

• DashboardCard — 单个 Widget 磁贴。模板：summary、progress、list、action、chart、history、breakdown、briefing、timeline。
• LiveActivitySession — 锁定屏幕 / 灵动岛活动。
• ActionDefinition — 一个按钮，可通过 POST /v1/actions/:id/run 执行后端定义的操作。

Web 登录与管理

/login 使用用户在 iOS 应用中使用的同一 Apple ID 登录。 登录可确认身份，但不会授予权限：ADMIN_EMAILS 指定会话额外具备管理员权限的邮箱地址，并且 /admin 下的每个路由都会验证该权限，而不是想当然地认为用户拥有该权限。

登录不会为你创建账户。 回调会将 Apple 身份与应用创建的账户进行匹配，并拒绝无法识别的身份，因此找到此端点并不能让你成为租户。WEB_SIGNUP_ENABLED（默认关闭）可让部署启用 Web 账户创建。

/admin 中的管理仪表板会列出所有租户的卡片、设备、推送令牌、实时活动、待处理活动和启动推送令牌。它还可以创建和撤销租户凭据，以及删除租户数据，因此访问权限意味着完整的管理控制权，而非只读查看权限。对于尚无账户的部署，可使用 API_KEYS 引导登录（ADMIN_API_TOKEN_LOGIN=true，默认关闭）。

管理功能默认启用。在 server/wrangler.toml 的 [vars] 下设置 ADMIN_ENABLED = "false" 并重新部署，即可让 /admin 及其所有变更端点在访问会话或数据库前返回 404。Web 登录、账户仪表板、MCP 授权和公共 API 仍然可用。

在 /admin 中使用租户所有者邮箱和权限预设，创建遵循最小权限原则的租户 API 令牌；这些生成的凭据供应用和 Agent 用于 /v1/*。

设置指南：server/README.md → “Web sign-in”。

文档

• ios/README.md — Xcode 设置、权限配置、签名。
• server/README.md — Worker 部署、D1 绑定、APNs 密钥、Web 登录与管理。
• examples/README.md — 如何从任意 shell 或 Agent 发布状态。
• docs/llms.md — 供 Agent（Claude Code / Codex）将另一个项目与 00Widget 集成时参考。
• docs/brand/README.md — 徽标、颜色、标语规范。
• marketing/screenshots/README.md — 原始截图、宣传素材制作和 App Store 截图工作流。
• marketing/app-preview/README.md — App Store Preview 截取、渲染和验证工作流。

状态

端到端流程已可正常运行。卡片可以发布，实时活动可以启动、更新和结束，启动推送已接通，APNs 负载也已根据 Apple 当前文档完成验证（文档日期已标注在 server/src/apns.ts 中）。

启动推送（ActivityKit，iOS 17.2+） — 已完整实现。iOS 从 didFinishLaunchingWithOptions 开始监听 Activity<ZeroZeroWidgetActivityAttributes>.pushToStartTokenUpdates，并通过 POST /v1/live-activities/register-start-token 注册。后端的 POST /v1/live-activities/start 会向所有已注册设备发送启动事件；如果没有令牌已注册（或 APNs 投递失败），则回退到待处理队列路径。端到端验证需要在 Worker 上配置 .p8 凭据。

tvOS 活动仪表板 — Apple TV 应用会在小组件上方列出正在进行的实时活动。后端提供一个经过去重、限定于租户的视图，整合待处理的启动事件和已注册设备上的活动；tvOS 则在本地显示倒计时和进度。

WidgetKit pushHandler（iOS 26+） — 已完整实现。每个小组件配置都会调用 .pushHandler(ZeroZeroWidgetPushHandler.self)。处理程序会将 WidgetKit 的规范令牌／配置快照持久保存到 App Group 中，宿主应用则会在启动时、进入前台时、应用构建版本发生变化后，以及在 WidgetKit 生成令牌期间通过短暂且有界的重试来完成同步。后端推送会携带 aps.content-changed: true，采用考虑预算的租户级发送频率，并将被抑制的变更可靠地合并为一条延迟队列投递，在发送频率窗口开启时发送。应用成功获取前台数据后，也会立即请求针对性时间线重新加载。端到端验证仍需要 .p8 凭据和实体设备。

许可证

源代码采用 MIT 许可证。00Widget 名称和品牌素材不在许可范围内； 请参阅 LICENSE 和 docs/brand/LICENSE。