跳转到正文

AI 集成

Blockstudio 为编码助手提供两个上下文文件。主要文件是精简的文档索引。另一个文件包含每份文档和架构的完整文本,供希望在一次请求中获取整个内容库的工具使用。

代理会读取索引,找到所需的一份文档并打开它。另一种做法是把半兆字节、未经整理的文本交给代理,其中内容无法单独寻址,而且无论是否相关都会全部加载。

索引

blockstudio-llm.txt 按照导航顺序,依据所属的章节和小节分组,逐一列出每份已发布的文档。每个条目包含:

  • route:文档URL。
  • file:Blockstudio仓库中的Markdown源路径。
  • purpose:用一行文字说明文档的用途。
  • settings:该文档负责的 blockstudio.json 路径。
  • hooks:该文档负责的 PHP 和 JavaScript 筛选器与操作名称。
  • php:该文档负责的函数、类和方法。
  • cli:该文档负责的命令。
Text
## Docs / Dev / Inspection Tools

### Canvas
route: /docs/dev/canvas
file: docs/docs/dev/canvas.md
purpose: A visual workspace and public inventory API for Blockstudio content.
settings: dev/canvas/enabled, ui
hooks: blockstudio/settings/dev/canvas/admin_bar, blockstudio/settings/dev/canvas/enabled
php: Blockstudio\Canvas, Canvas::documents(), Canvas::inventory()

只有文档确实负责某类内容时,才会写入对应的标识符行,因此上面的条目没有 cli 行,而静态预渲染页面负责整个预渲染命令系列。

标识符行让索引能够回答查询。代理若要查找区块渲染前触发的钩子,就会扫描钩子行并找到 PHP 钩子,该文档涵盖完整的筛选器和操作词汇。代理若要查找静态预渲染,就会搜索同一个词并找到 静态预渲染 和 设置,它们分别负责计数器和配置。五个公共 JSON 架构也以相同方式列出各自的路由和文件。

标识符从正文、行内代码和代码示例中读取。标记为 text 的区块包含字面输出和目录清单,因此会跳过:打印某个命令的输出,并不意味着该文档就负责这个命令。

完整文本

blockstudio-llm-full.txt 在一个文件中包含完整文档和所有架构。它仍然是生成的、已发布的且可寻址的,但不再是首先交给代理的内容,并且文件自己的标头也说明了这一点。

构建方式

这两个文件都在构建时由 npm run build:llm 组装,该工具会运行 scripts/build-llm.ts。脚本会:

  1. 读取 docs、guides 和 registry 集合中每份已发布文档的 frontmatter,获取标题、路由和用途。
  2. 从每份文档正文中提取其负责的标识符:从筛选器和操作调用中提取钩子名称,根据设置架构验证设置路径,并提取 PHP 函数和类,以及 CLI 命令。
  3. 将索引写入 includes/llm/blockstudio-llm.txt。
  4. 按照导航顺序遍历文档树,移除仅用于导航的 Markdown,同时保留标题和代码示例;附加 JSON 架构,并将完整文本写入 includes/llm/blockstudio-llm-full.txt。

如果已发布的文档缺少索引项,或者索引指向的文件已不存在,npm run docs:check 就会失败。

使用方法

  1. 在你的 blockstudio.json 中启用 ai/enableContextGeneration 设置:
JSON
{
  "ai": {
    "enableContextGeneration": true
  }
}
  1. 文件现在可在 your-site.com/blockstudio-llm.txt 和 your-site.com/blockstudio-llm-full.txt 中访问。

  2. 将你的 AI 工具指向该索引:

    • Cursor:在项目设置中将 URL 添加为文档。
    • Claude Code:引用 URL,或下载该文件并将其添加到项目上下文中。
    • GitHub Copilot:将文件包含在仓库中,或在说明中引用它。

任何接受 URL 或文本文件作为上下文的工具都可以使用。这两个文件都是静态的,不包含特定于站点的数据,例如已注册区块或当前设置。

你项目自己的契约

索引描述的是 Blockstudio,而不是你的项目;但代理还需要另一半信息:区块和页面存放在哪里、启用了哪些功能,以及哪些内容会被分析拒绝。vendor/bin/blockstudio-agents 会根据你的 blockstudio.json 和你自己的文件生成这些信息。请参阅项目契约。