跳转到正文

面向 AI 的区块开发

文件加上无需构建的流程,正是智能体擅长处理的方式。

一段无声的屏幕录制:编码代理根据单条提示构建完整的 WordPress 站点,包含 10 个自定义区块和 6 个页面。

描述区块,即可生成区块

AI 编码代理可以根据一条提示搭建区块、页面和模式。无需图形界面,也无需数据库,只需文件。

~/starter-theme

❯ 创建一个包含三个档位、月付/年付切换开关,并为每个档位设置行动号召的定价区块。

✓ 已创建 pricing/block.json

✓ 已创建 pricing/index.php

✓ 已创建 pricing/style.css

❯ 现在创建一个包含主视觉和常见问题版块的定价页面。

✓ 已创建 pages/pricing/page.json

✓ 已创建 pages/pricing/index.php

文件

blockstudio/

├── pricing/ 新建

├── block.json

├── index.php

└── style.css

pages/

├── pricing/ 新建

├── page.json

└── index.php

一切皆以文件为基础

区块、页面、图案和扩展都是包含 JSON 配置和模板的目录。智能体可以直接读取和写入这些文件。

无需数据库配置

无需在管理面板中逐项点击。每项设置都是一个 JSON 键,智能体无需打开浏览器即可搭建好库。

结构清晰可预测

每个区块都遵循相同的约定:block.json、一个模板和可选样式。只需学习一次这种模式。

提供上下文,而非猜测

文档的精简索引,以及供需要完整内容的工具使用的全文。

智能体首先读取的索引

blockstudio-llm.txt 会为每份文档列出一次其路由、源文件、用途,以及它所拥有的设置、钩子、PHP 函数和 CLI 命令。索引约为 11k 个 token,智能体可以一次读完,然后只打开所需的页面。

blockstudio-llm-full.txt 在一个文件中包含所有文档和 JSON 架构,约为 169k 个 token,适合需要完整语料的工具。启用 ai.enableContextGeneration 后,网站会同时提供这两者。

blockstudio-llm.txt
# Blockstudio documentation index

This is the primary context file for coding assistants. It is an index, not
the documentation itself. Each entry names one document, what it is for, and
the identifiers that document owns. Read this index, then open only the
document you need.

Every document is addressable two ways: as a URL on https://blockstudio.dev,
and as a Markdown file in the Blockstudio repository. The full text of every
document and schema is also available in one file at /blockstudio-llm-full.txt
for tools that want everything at once.

为项目设定约定

文档描述的是 Blockstudio。AGENTS.md 描述的是智能体即将修改的项目。

一条命令即可写入 AGENTS.md

vendor/bin/blockstudio-agents 描述其所运行的项目:项目包含什么、哪些功能由 blockstudio.json 启用、分析会拒绝什么,以及适用的命令。

每一行都来自你的文件、设置或选定的分析预设。重新生成时会保留你手写的备注;如果约定已过时,--check 会报错。

AGENTS.md
# Blockstudio contract for Acme

## Project

- Kind: WordPress theme `Acme`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.

## What this project contains

- Blocks: 1 in `blockstudio`.
- Pages: 1 in `pages`.
- Block namespaces: `acme`.
- Block templates are written in PHP.

在提交前发现错误

四种分析预设,每种都包含前一种的全部内容,并提供一个在每次提交时运行它们的钩子。

了解 block.json 的分析

blockstudio/phpstan 预设会读取你的区块、页面和设置。如果模板读取了其 block.json 未声明的字段,或输出时未进行转义,分析就会失败。

模板会读取一个 $a 类型值,该值由同目录的 block.json 推断;每种字段类型都有具体的 PHP 类型,而 Db::get() 返回符合 db.php 结构的记录。设置路径或钩子名称拼写错误时,系统会提示最接近的正确名称。

设置 githooks.commit 并运行 vendor/bin/blockstudio-githooks sync:受管理的提交前钩子会运行相同的分析,因此有问题的区块无法进入提交。

blockstudio.json
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": { "preset": "extreme-theme" },
  "githooks": { "commit": true }
}

通过 PHP 查看清单并进行渲染

只需几次调用,代理就能查看项目注册了哪些内容、渲染其中任意部分,并检查存储的数据。

向项目提问,渲染答案

Canvas::inventory() 会列出项目注册的所有页面、区块、图案、站点编辑器模板、模板部件和 UI 示例,无需渲染任何内容。

Render::document() 会将其中任意项渲染为完整的 HTML 文档,并且只包含实际使用的资源,让智能体能在编辑器之外检查结果。

Canvas::documents() 会精确渲染你选中的记录。Render::composition() 和 Render::content() 会将嵌套声明或序列化区块内容作为 HTML 返回;Ui::inventory() 和 Ui::examples() 则会列出捆绑的组件系列,每个系列各含一个可渲染声明。

对于单个区块,bs_block_fields()、bs_block_extension_fields()、bs_block_values() 和 bs_block_assets() 无需渲染即可返回其字段、值和资源;bs_validate_block() 则会在保存前检查存储的属性。

inspect.php
use Blockstudio\Canvas;
use Blockstudio\Render;

$project = Canvas::inventory(['blocks' => true]);

foreach ($project['inventory']['blocks'] as $block) {
  echo $block['name'] . "\n";
}

$doc = Render::document(
  ['name' => 'acme/hero', 'data' => ['heading' => 'Hello']],
  ['title' => 'Hero preview']
);

file_put_contents('hero.html', $doc['html']);

每个页面所需的 token 不到一半

智能体编写普通的 HTML。同步时,Blockstudio 会将其转换为序列化的 WordPress 区块标记:生成内容更少,出错机会也更少。

Blockstudio

代理写入的内容

约 135 个令牌
index.php
<h1>Build Websites That Convert</h1>
<p>The all-in-one platform for creating
beautiful, high-performance landing pages.</p>

<block name="core/columns">
  <block name="core/column">
    <h3>Lightning Fast</h3>
    <p>Pages load in under one second.</p>
  </block>
  <block name="core/column">
    <h3>Easy to Use</h3>
    <p>No technical skills required.</p>
  </block>
  <block name="core/column">
    <h3>SEO Optimized</h3>
    <p>Built-in best practices from day one.</p>
  </block>
</block>

<img src="/dashboard.jpg" alt="Dashboard" />

WordPress

解析器为其生成的内容

约 310 个令牌
post_content
<!-- wp:heading {"level":1} -->
<h1 class="wp-block-heading">Build Websites That Convert</h1>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>The all-in-one platform for creating
beautiful, high-performance landing pages.</p>
<!-- /wp:paragraph -->
<!-- wp:columns -->
<div class="wp-block-columns">
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">Lightning Fast</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>Pages load in under one second.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">Easy to Use</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>No technical skills required.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">SEO Optimized</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>Built-in best practices from day one.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
</div>
<!-- /wp:columns -->
<!-- wp:image {"alt":"Dashboard","url":"/dashboard.jpg"} -->
<figure class="wp-block-image"><img src="/dashboard.jpg" alt="Dashboard"/></figure>
<!-- /wp:image -->

根据上方两个面板测得:HTML 有 540 个字符,区块标记有 1,233 个字符(由标准解析器生成),再除以 4,即通常估算的每个令牌字符数。标记中添加了换行,以便阅读。

需要生成的内容更少

智能体编写 HTML,无需添加区块分隔符、生成的类或包装标记。

出错机会更少

解析器能从更简单的输入中保证生成有效的区块输出。

更快、更省钱

输出 token 更少,响应更快,模型成本更低。

适用于所有 AI 编码工具

任何能够读写文件的智能体都能开箱即用地使用 Blockstudio。

Claude Code
Codex CLI
Gemini CLI
Cursor
Windsurf
Amp

为 AI 工作流程而打造

区块、页面、图案和设置。一切都是智能体可以读取、写入和修改的文件。

每个区块只需两个文件

一个 JSON 配置和一个模板就是整个区块。精简的结构让首次生成更加可靠。

27 种字段类型

文本、文件、重复项、颜色、日期等,都在 JSON 中定义。选择项可以从文章、分类项和用户中填充。

JSON 架构验证

每个配置都有架构,为智能体提供明确规则,并能立即发现错误。

自动注册

将文件放入目录,区块便会自动注册,无需再维护配置清单。

画布总览

在一个可缩放视图中查看所有托管页面,或查看所有区块及其默认值。

实时画布

实时模式会在保存约一秒后,通过服务器发送事件刷新受影响的画板。点击标签即可聚焦对应画板。

内置 Tailwind

TailwindPHP 会编译每个页面使用的类,无需配置 Node。

Element Grabber

复制元素的模板路径和标记,即可立即为智能体提供上下文。

HTML 转为区块

页面和图案都是普通文件,可转换为原生 WordPress 区块。

渲染冒烟测试

wp bs blocks render 会像渲染页面一样渲染每个区块;如果模板产生通知、警告或错误,则以 1 退出。

存储内容检查

wp bs blocks validate 会检查文章已保存的字段;pages sync 则会警告哪些区块属性虽已存储却从未渲染。

在终端中检查

使用 wp bs 列出设置、自定义字段和资源;使用 wp bs tailwind compile 或 wp bs scss compile 编译代码片段或文件。

Plus

官方扩展套件

高级站点模板、AI 系统指令和私人 Discord 社区。一次购买,终身更新。

  • 500+ 个网站模板
  • AI 系统指令
  • 终身更新
  • 私有 Discord 社区