内容
# 板块状态
> **您的仪表盘就是数据。任何人工智能都可以构建它；任何人都可以编辑它。**
**[▶ 现场演示](https://100yenadmin.github.io/boardstate/)** — 按下“模拟代理”并观看人工智能组成板块，然后自己拖动事物。
板块状态（Boardstate）是一种用于**代理可组合仪表盘**的协议和运行时。整个仪表盘 — 选项卡、小部件、布局、数据绑定，甚至代理作者的自定义小部件注册表 — 都是一个已验证的 JSON 文档：_板块状态_。人工智能代理通过工具组成它，人类通过拖放重新排列它，脚本通过 RPC 编辑它 — **所有操作都通过同一个受保护的控制平面**，没有特权路径。代理作者的小部件在沙盒中渲染，确保外部代码_从构建开始就是安全的_，并在明确的操作员批准门槛后。
- 📄 **文档即 API** — 可差异化、可撤销、可导出、可导入、可模板化、可时间旅行。
- 🤖 **任何 AI，零集成** — `@boardstate/mcp` 向任何 MCP 客户端（Claude 或其他任何支持 MCP 的客户端）公开完整的工具集。
- 🧑🎨 **人类平等是一项协议要求** — 拖放、折叠、批准、撤销：与代理使用的相同方法。
- 🔒 **安全梯度，而非警告标签** — 受信任的内置功能与沙盒自定义功能（不透明来源，CSP `connect-src 'none'`，功能清单，批准门控安装，服务器端 404 表示未批准）。
## 它如何组合在一起
```mermaid
flowchart TB
subgraph Authors["谁组成仪表盘 — 一个已验证的控制平面"]
A1["🤖 AI 代理 · 工具<br/>(dashboard_tab_create, _widget_scaffold, …)"]
A2["👤 人类 · 用户界面<br/>(拖放 / 批准)"]
A3["⌨️ 脚本 · 命令行界面 / RPC"]
end
A1 --> CP
A2 --> CP
A3 --> CP
CP["控制平面 · dashboard.* 方法<br/>(允许键白名单，完整验证)"]
CP --> STORE["🔒 存储<br/>序列化写入 · 原子持久性<br/>撤销环 · 大小上限"]
STORE --> DOC[["工作区文档<br/>板块状态"]]
STORE -- "boardstate.changed" --> UI["主机用户界面 · <boardstate-view>"]
UI --> B["✅ 内置小部件 — 受信任层"]
UI --> C["🧩 自定义小部件 — 沙盒层<br/>不透明来源 · 无网络 · 批准门控"]
C -. "postMessage 桥 — 父级解析所有数据" .-> UI
```
为什么代理编写的代码可以安全运行：
```mermaid
sequenceDiagram
participant Agent as 🤖 代理
participant Store as 存储
participant Op as 👤 操作员
participant Frame as 沙盒 iframe
Agent->>Store: widget_scaffold (清单 + index.html)
Store-->>Op: 状态 "待处理" — 一张卡片，不是 iframe
Op->>Store: 批准
Store-->>Frame: 提供资产（未批准 → 404）+ CSP connect-src 'none'
Frame->>Store: 仅限其清单声明的绑定 — 通过父级
Note over Frame: 无来源 · 无网络 · 无凭证
```
## 软件包
| 软件包 | 说明 |
| ---------------------------------------- | ----------------------------------------------------------------------------------- |
| [`@boardstate/schema`](packages/schema) | 文档模式、验证器和 **[规范](packages/schema/SPEC.md)** |
| [`@boardstate/core`](packages/core) | 无头运行时：存储、绑定、网格数学、导出/导入、发布/订阅、历史 |
| [`@boardstate/server`](packages/server) | `dashboard.*` 控制平面、代理工具、小部件服务、命令行界面 |
| [`@boardstate/host`](packages/host) | 无框架 DOM 主机：沙盒安装、postMessage 桥、客户端存储 |
| [`@boardstate/lit`](packages/lit) | 参考视图 — `<boardstate-view>` 和 15 个内置小部件，作为自定义元素 |
| [`@boardstate/react`](packages/react) | 自定义元素的类型化 React 包装 |
| [`@boardstate/mcp`](packages/mcp) | MCP 服务器：为任何 AI 提供完整的仪表盘工具集 |
| [`@boardstate/conformance`](conformance) | 传输一致性套件 — 在您的主机上运行 |
## 快速开始
零安装：打开 **[现场演示](https://100yenadmin.github.io/boardstate/)**。本地：
```sh
git clone https://github.com/100yenadmin/boardstate && cd boardstate
pnpm install && pnpm build
pnpm --filter boardstate-example-standalone dev # 60 秒演示
```
无论哪种方式，请按 **“模拟代理”**，然后观看：出现一个选项卡，图表绑定，一个自定义小部件作为待处理卡片出现，您批准后，沙盒 iframe 安装并实时渲染。然后拖动事物 — 您和代理正在编辑同一个文档。
直接为 AI 提供工具：
```sh
npx @boardstate/mcp --serve 4400 # MCP 标准输入/输出服务器 + 现场主机页面
```
## 主题
`@boardstate/lit` 提供一个完整、世界级的默认主题 — **Graphite** （一种 Linear / Vercel / Codex 家族调色板）— 默认情况下在**浅色和深色**下看起来很棒。只需导入一次；无需其他配置。
```ts
import "@boardstate/lit";
import "@boardstate/lit/styles.css"; // Graphite 默认主题 - 浅色 + 深色
```
- **免费的深色模式** — 自动遵循 `prefers-color-scheme`；在需要切换时，在 `<html>` 上固定为 `data-theme="dark"` / `"light"`。
- **直接替换主题** — 在 `styles.css` 之后层叠，以完全重新设置皮肤（每个主题都提供自己的浅色 + 深色）：
```ts
import "@boardstate/lit/themes/aurora.css"; // 未来主义 - 青色强调 + 极光洗白
import "@boardstate/lit/themes/vibrancy.css"; // macOS 原生磨砂玻璃
```
- **完全控制** — 每个值都是 `--bs-*` 自定义属性；覆盖一个令牌或编写整个主题。参见 **[THEME.md](packages/lit/THEME.md)** 获取令牌表和构建您自己的指南。
| Graphite（默认，浅色） | Aurora | Vibrancy |
| :-------------------------------------------------------------: | :--------------------------------------------------: | :------------------------------------------------------: |
|  |  |  |
**[现场演示](https://100yenadmin.github.io/boardstate/)** 在其标题中具有主题切换器 + 浅色/深色切换 — 快速查看这三个主题的最简单方式。
## 了解更多
- **[SPEC.md](packages/schema/SPEC.md)** — 协议：文档格式、`dashboard.*` 方法、桥协议 v1、功能和批准模型、安全不变量。
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — 实现：软件包图、三个接缝（存储/传输/服务器主机）、请求生命周期以及如何构建您自己的主机。
- **[docs/authoring.md](docs/authoring.md)** — 编写小部件（内置渲染器或沙盒自定义）。
- **[docs/living-answers.md](docs/living-answers.md)** — 代理约定：用实时小部件而非散文回答视觉问题。
- **[docs/design-review.md](docs/design-review.md)** — 代理工作流，用于审查和改进其构建的布局。
- **[templates/](templates)** — 启动器小部件和工作区模板。
## 状态
**v0.1（提取中）。** 板块状态是从为 [OpenClaw](https://github.com/openclaw/openclaw) 构建的模块化仪表盘系统中提取的（[路线图和 PR](https://github.com/openclaw/openclaw/issues/101136)）— 该插件是第一个一致的主机。协议稳定到足以阅读；软件包按依赖顺序出现（模式 → 核心 → 服务器 → 主机 → lit）。
## 许可证
MIT
