AI 集成
Blockstudio 为编码助手提供两个上下文文件。主要文件是精简的文档索引。另一个文件包含每份文档和架构的完整文本,供希望在一次请求中获取整个内容库的工具使用。
代理会读取索引,找到所需的一份文档并打开它。另一种做法是把半兆字节、未经整理的文本交给代理,其中内容无法单独寻址,而且无论是否相关都会全部加载。
索引
blockstudio-llm.txt 按照导航顺序,依据所属的章节和小节分组,逐一列出每份已发布的文档。每个条目包含:
route:文档URL。file:Blockstudio仓库中的Markdown源路径。purpose:用一行文字说明文档的用途。settings:该文档负责的blockstudio.json路径。hooks:该文档负责的 PHP 和 JavaScript 筛选器与操作名称。php:该文档负责的函数、类和方法。cli:该文档负责的命令。
## 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。脚本会:
- 读取
docs、guides和registry集合中每份已发布文档的 frontmatter,获取标题、路由和用途。 - 从每份文档正文中提取其负责的标识符:从筛选器和操作调用中提取钩子名称,根据设置架构验证设置路径,并提取 PHP 函数和类,以及 CLI 命令。
- 将索引写入
includes/llm/blockstudio-llm.txt。 - 按照导航顺序遍历文档树,移除仅用于导航的 Markdown,同时保留标题和代码示例;附加 JSON 架构,并将完整文本写入
includes/llm/blockstudio-llm-full.txt。
如果已发布的文档缺少索引项,或者索引指向的文件已不存在,npm run docs:check 就会失败。
使用方法
- 在你的
blockstudio.json中启用ai/enableContextGeneration设置:
{
"ai": {
"enableContextGeneration": true
}
}
-
文件现在可在
your-site.com/blockstudio-llm.txt和your-site.com/blockstudio-llm-full.txt中访问。 -
将你的 AI 工具指向该索引:
- Cursor:在项目设置中将 URL 添加为文档。
- Claude Code:引用 URL,或下载该文件并将其添加到项目上下文中。
- GitHub Copilot:将文件包含在仓库中,或在说明中引用它。
任何接受 URL 或文本文件作为上下文的工具都可以使用。这两个文件都是静态的,不包含特定于站点的数据,例如已注册区块或当前设置。
你项目自己的契约
索引描述的是 Blockstudio,而不是你的项目;但代理还需要另一半信息:区块和页面存放在哪里、启用了哪些功能,以及哪些内容会被分析拒绝。vendor/bin/blockstudio-agents 会根据你的 blockstudio.json 和你自己的文件生成这些信息。请参阅项目契约。