BT AI 开发入口

BT AI 开发入口

AI 原文

BT AI 开发入口

功能

BT 官网为通用编码 AI、智能 IDE 和文档工具提供一套按需读取的官方知识接口。它完整覆盖 BT 语言语义、语法、标准库、Web 开发、bt_app 桌面开发、网络与设备、扩展和 FFI，同时避免每次把完整知识库放入模型上下文。

给 AI 单独提供一个网址时，统一使用：

该入口会要求 AI 先搜索，再读取单个函数文档、单个稳定知识块或确实需要的模块。接口只返回公开文档，不接收用户问题、项目源码、模型配置、账号、API Key 或其他私有数据。

语法

推荐读取顺序：

1. 首次只读 /ai；

2. 用 /ai/search 查询 API 名、模块名或运行时名；

3. 搜索结果是 symbol 时直接使用响应中的完整函数契约，是 doc 时读取 markdown_url，是 block 时读取 content_url；

4. 只有系统设计或语义不确定时才读取整个模块；

5. 完整索引和离线包只供客户端缓存、离线开发或知识工具集成。

参数

路径参数

字段类型必填默认值有效范围或可选值含义
module_idString知识模块和知识块接口是无清单 modules[].id 中的稳定 ID要读取的知识模块。
block_nameString知识块接口是无搜索结果 content_url 中的稳定块名称要读取的单个知识块。
pathString精确文档接口是无搜索结果 markdown_url 中的文档路径要读取的函数或主题 Markdown。
knowledge_versionString完整包接口是无清单的 knowledge_version要下载的不可变离线包版本。

查询参数

字段类型必填默认值有效范围或可选值含义
qString搜索接口是无1 至 100 个字符；建议使用空格分隔的 API、模块或运行时关键词全部非空关键词都必须命中同一条索引记录。
limitInt否81..20；非法值回退为 8，大于 20 按 20最多返回的搜索结果数量。

条件请求头

字段类型必填默认值有效范围或可选值含义
If-None-MatchString否无上次响应的 ETag，支持弱标签和逗号分隔列表清单、索引、知识块、模块或离线包未变化时返回 304 Not Modified。
If-Modified-SinceString否无上次响应的 Last-Modified未同时发送 If-None-Match 且发布时间一致时返回 304 Not Modified。

返回值

AI 首读入口

GET /ai 以 text/plain; charset=utf-8 返回一份带 Markdown 结构的精简纯文本，避免只接受常见网页文本类型的 AI 抓取组件拒绝响应。正文包含：

  • 最省 Token 的强制读取策略；
  • 搜索、精确文档、知识块、模块和离线包地址；
  • 模块路由、依赖与 Token 估算；
  • BT 与 bt_app 的运行、构建和验收速记。

它不是全量文档，AI 不应只凭入口摘要猜测具体函数签名。

知识清单

GET /ai/manifest 返回 UTF-8 JSON：

字段类型必填默认值有效范围或可选值含义
schema_versionInt是无当前为 1清单结构版本。
bt_versionString是无三段式版本知识对应的 BT 版本。
knowledge_versionString是无YYYY.MM.DD.revision本次官方知识发布的唯一版本。
updated_atString是无ISO 8601知识发布时间。
last_modifiedString是无RFC 7231 HTTP 日期条件请求使用的最后修改时间。
min_client_versionString是无三段式版本能读取当前 schema 的最低工具版本。
guide_urlString是/ai站内绝对路径通用 AI 唯一规范入口。
text_content_typeString是text/plain; charset=utf-8固定值AI 入口、精确文档、知识块和模块使用的兼容响应类型；正文仍采用 Markdown 结构。
search_url_templateString是无带 {query} 和 {limit} 占位符小结果搜索接口模板。
search_index_urlString是/ai/index站内绝对路径完整搜索索引地址。
search_index_sha256String是无64 位小写十六进制完整搜索索引原始 UTF-8 字节摘要。
block_url_templateString是无带 {module_id} 和 {block_name} 占位符单个知识块接口模板。
docs_url_templateString是无带 {path} 占位符精确函数或主题 Markdown 接口模板。
source_sha256String是无64 位小写十六进制单一知识源规范化后的摘要。
bundle_formatString是bt-ai-bundle-json-v1固定值完整离线包格式。
bundle_urlString是无/ai/bundle/{knowledge_version}当前完整离线包地址。
bundle_sha256String是无64 位小写十六进制完整离线包原始 UTF-8 字节摘要。
modulesArray[Object]是无固定模块清单可按需读取的知识模块元数据。

modules[] 字段：

字段类型必填默认值有效范围或可选值含义
idString是无稳定模块 ID模块唯一标识。
revisionInt是无大于等于 1模块正文修订号。
content_urlString是无/ai/knowledge/{id}整个模块 Markdown 地址。
sha256String是无64 位小写十六进制模块原始 UTF-8 字节摘要。
approx_tokensInt是无大于 0模块的近似 Token 数。
runtimesArray[String]是无cli/web/desktop/extension/ffi模块适用运行时。
tagsArray[String]是无稳定检索标签模块主题标签。
depends_onArray[String]是[]其他模块 ID读取整个模块前应同时考虑的依赖。
block_countInt是无大于 0模块包含的稳定知识块数量。

按关键词搜索

GET /ai/search 返回小型 UTF-8 JSON：

字段类型必填默认值有效范围或可选值含义
queryString是无规范化为小写的查询文本本次实际查询。
limitInt是81..20本次结果上限。
countInt是无0..limit实际返回数量。
resultsArray[Object]是[]函数契约、文档或知识块结果精确符号和精确路径优先，其后返回相关候选。

results[] 共有字段与分支字段：

字段类型必填默认值有效范围或可选值含义
kindString是无symbol/doc/blocksymbol 表示可直接使用的完整函数契约，doc 表示精确文档，block 表示稳定知识块。
idString是无稳定 ID结果标识。
titleString是无非空文本结果标题。
approx_tokensInt是无大于 0读取该结果的近似 Token 数。
signatureStringsymbol 是无Markdown 行内代码函数调用方式。
parametersStringsymbol 是无文本参数名、类型与必填规则。
defaultsStringsymbol 是无文本参数默认值。
returnsStringsymbol 是无文本返回类型与语义。
exampleStringsymbol 是无Markdown 行内代码最小调用示例。
notesStringsymbol 是无文本行为边界与注意事项。
limitsStringsymbol 是无文本上下文、权限或资源限制。
categoryStringdoc 是无文档分类精确文档所属分类。
markdown_urlStringdoc 是无/md/docs/...AI 应读取的精确 Markdown 地址。
html_urlStringdoc 是无/docs/...人类阅读页面。
module_idStringblock 是无稳定模块 ID知识块所属模块。
runtimesArray[String]block 是无运行时列表知识块适用运行时。
tagsArray[String]block 是无标签列表知识块主题标签。
content_urlStringblock 是无/ai/block/...AI 应读取的单块 Markdown 地址。
sha256Stringblock 是无64 位小写十六进制单块正文摘要。

完整搜索索引

GET /ai/index 返回全部精确文档和稳定知识块的 JSON 索引。它适合 IDE 或本地工具建立缓存，不适合直接作为普通编码任务的模型上下文。

字段类型必填默认值有效范围或可选值含义
schema_versionInt是无当前为 1索引结构版本。
knowledge_versionString是无当前知识版本索引所属发布版本。
source_sha256String是无64 位小写十六进制索引对应的知识源摘要。
entriesArray[Object]是无symbol/doc/block 混合列表全部可搜索条目；内部 search_text 和 exact_queries 仅供搜索匹配。

单个知识块与整个模块

GET /ai/block/{module_id}/{block_name} 只返回一个稳定 Markdown 知识块；GET /ai/knowledge/{module_id} 返回整个模块。两者都以 text/plain; charset=utf-8 传输 Markdown 正文，并提供 SHA-256 和条件缓存响应头。

知识块通常比整个模块小得多。比如只需要 String 方法总表时，应读取相应知识块；只需要 string.replace 的精确签名时，应直接使用搜索结果中的 symbol 函数契约。

完整离线包

GET /ai/bundle/{knowledge_version} 返回 bt-ai-bundle-json-v1 JSON：

字段类型必填默认值有效范围或可选值含义
schema_versionInt是无当前为 1完整包结构版本。
bundle_formatString是无bt-ai-bundle-json-v1完整包格式。
knowledge_versionString是无与请求版本一致包内知识版本。
manifestObject是无清单快照为避免自引用哈希，包内 bundle_sha256 固定为 null。
block_indexObject是无schema 1全部稳定知识块的行号、标签、Token 估算和摘要。
modulesObject[String,String]是无键为模块 ID全部模块 Markdown 正文。

响应头

字段类型必填默认值有效范围或可选值含义
Content-TypeString是无JSON 使用 application/json；AI 文本使用 text/plain; charset=utf-8响应正文格式；纯文本正文仍保留 Markdown 标题、表格和代码块。
Cache-ControlString是无首读入口 60 秒；搜索/知识 5 分钟；版本包一年且 immutable客户端缓存策略；首读入口缩短缓存，便于内容类型等兼容调整快速生效。
ETagString搜索接口外的版本化接口是无HTTP 实体标签条件请求值。
Last-ModifiedString搜索接口外的版本化接口是无RFC 7231 HTTP 日期条件请求值。
X-BT-Knowledge-VersionStringAI JSON/文本接口是无当前知识版本响应所属知识版本。
X-Content-SHA256String索引、知识块、模块和完整包是无64 位小写十六进制当前响应正文摘要。
Access-Control-Allow-OriginStringAI 接口是*固定为 *允许公开知识客户端跨域读取。

代码示例

下面的 BT 脚本搜索 string.replace，直接读取最小函数契约：

下面的 BT 脚本按清单校验单个知识块：

注意事项

  • 普通编码任务不要读取完整搜索索引、完整模块集合或离线包；先搜索并按最小结果读取。
  • /llms.txt 是 AI 工具约定的自动发现别名，正文格式仍是 Markdown；开发者主动提供链接时只使用 https://btlang.org/ai。
  • AI 入口、精确文档、知识块和模块故意使用兼容性更高的 text/plain，不要改回可能被部分网页读取组件拒绝的 text/markdown。
  • API 名已知时优先搜索 category api_name 或完整符号，例如 string replace、mysql begin、window.bt.call。
  • 同一个开发任务应固定使用一个 knowledge_version，不要在任务中途混用两个版本。
  • 模块、知识块、索引或离线包下载后应先校验原始 UTF-8 字节的 SHA-256，再写入正式缓存。
  • 304 响应没有正文，客户端应继续使用本地已校验内容。
  • 官网不可访问时，工具可以回退到自己内置且已校验的完整包；普通项目不得因此假定存在 E:\bt-lang 等固定本地目录。
  • 项目自身的 AGENTS.md、README、运行时文件位置和测试命令优先于本站通用建议。
  • 未知路径、模块或知识块返回 404，缺少搜索词返回 400，非 GET 请求返回 405。