# BT AI 开发入口

## 功能

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

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

```text
https://btlang.org/ai
```

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

## 语法

```text
GET https://btlang.org/ai
GET https://btlang.org/llms.txt  # 自动发现兼容别名，正文与 /ai 相同
GET https://btlang.org/ai/manifest
GET https://btlang.org/ai/search?q={query}&limit={limit}
GET https://btlang.org/ai/index
GET https://btlang.org/ai/block/{module_id}/{block_name}
GET https://btlang.org/ai/knowledge/{module_id}
GET https://btlang.org/md/docs/{path}
GET https://btlang.org/ai/bundle/{knowledge_version}
```

推荐读取顺序：

1. 首次只读 `/ai`；
2. 用 `/ai/search` 查询 API 名、模块名或运行时名；
3. 搜索结果是 `symbol` 时直接使用响应中的完整函数契约，是 `doc` 时读取 `markdown_url`，是 `block` 时读取 `content_url`；
4. 只有系统设计或语义不确定时才读取整个模块；
5. 完整索引和离线包只供客户端缓存、离线开发或知识工具集成。

## 参数

### 路径参数

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

### 查询参数

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

### 条件请求头

| 字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `If-None-Match` | String | 否 | 无 | 上次响应的 `ETag`，支持弱标签和逗号分隔列表 | 清单、索引、知识块、模块或离线包未变化时返回 `304 Not Modified`。 |
| `If-Modified-Since` | String | 否 | 无 | 上次响应的 `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_version` | Int | 是 | 无 | 当前为 `1` | 清单结构版本。 |
| `bt_version` | String | 是 | 无 | 三段式版本 | 知识对应的 BT 版本。 |
| `knowledge_version` | String | 是 | 无 | `YYYY.MM.DD.revision` | 本次官方知识发布的唯一版本。 |
| `updated_at` | String | 是 | 无 | ISO 8601 | 知识发布时间。 |
| `last_modified` | String | 是 | 无 | RFC 7231 HTTP 日期 | 条件请求使用的最后修改时间。 |
| `min_client_version` | String | 是 | 无 | 三段式版本 | 能读取当前 schema 的最低工具版本。 |
| `guide_url` | String | 是 | `/ai` | 站内绝对路径 | 通用 AI 唯一规范入口。 |
| `text_content_type` | String | 是 | `text/plain; charset=utf-8` | 固定值 | AI 入口、精确文档、知识块和模块使用的兼容响应类型；正文仍采用 Markdown 结构。 |
| `search_url_template` | String | 是 | 无 | 带 `{query}` 和 `{limit}` 占位符 | 小结果搜索接口模板。 |
| `search_index_url` | String | 是 | `/ai/index` | 站内绝对路径 | 完整搜索索引地址。 |
| `search_index_sha256` | String | 是 | 无 | 64 位小写十六进制 | 完整搜索索引原始 UTF-8 字节摘要。 |
| `block_url_template` | String | 是 | 无 | 带 `{module_id}` 和 `{block_name}` 占位符 | 单个知识块接口模板。 |
| `docs_url_template` | String | 是 | 无 | 带 `{path}` 占位符 | 精确函数或主题 Markdown 接口模板。 |
| `source_sha256` | String | 是 | 无 | 64 位小写十六进制 | 单一知识源规范化后的摘要。 |
| `bundle_format` | String | 是 | `bt-ai-bundle-json-v1` | 固定值 | 完整离线包格式。 |
| `bundle_url` | String | 是 | 无 | `/ai/bundle/{knowledge_version}` | 当前完整离线包地址。 |
| `bundle_sha256` | String | 是 | 无 | 64 位小写十六进制 | 完整离线包原始 UTF-8 字节摘要。 |
| `modules` | Array[Object] | 是 | 无 | 固定模块清单 | 可按需读取的知识模块元数据。 |

`modules[]` 字段：

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

### 按关键词搜索

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

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

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

| 字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `kind` | String | 是 | 无 | `symbol/doc/block` | `symbol` 表示可直接使用的完整函数契约，`doc` 表示精确文档，`block` 表示稳定知识块。 |
| `id` | String | 是 | 无 | 稳定 ID | 结果标识。 |
| `title` | String | 是 | 无 | 非空文本 | 结果标题。 |
| `approx_tokens` | Int | 是 | 无 | 大于 `0` | 读取该结果的近似 Token 数。 |
| `signature` | String | `symbol` 是 | 无 | Markdown 行内代码 | 函数调用方式。 |
| `parameters` | String | `symbol` 是 | 无 | 文本 | 参数名、类型与必填规则。 |
| `defaults` | String | `symbol` 是 | 无 | 文本 | 参数默认值。 |
| `returns` | String | `symbol` 是 | 无 | 文本 | 返回类型与语义。 |
| `example` | String | `symbol` 是 | 无 | Markdown 行内代码 | 最小调用示例。 |
| `notes` | String | `symbol` 是 | 无 | 文本 | 行为边界与注意事项。 |
| `limits` | String | `symbol` 是 | 无 | 文本 | 上下文、权限或资源限制。 |
| `category` | String | `doc` 是 | 无 | 文档分类 | 精确文档所属分类。 |
| `markdown_url` | String | `doc` 是 | 无 | `/md/docs/...` | AI 应读取的精确 Markdown 地址。 |
| `html_url` | String | `doc` 是 | 无 | `/docs/...` | 人类阅读页面。 |
| `module_id` | String | `block` 是 | 无 | 稳定模块 ID | 知识块所属模块。 |
| `runtimes` | Array[String] | `block` 是 | 无 | 运行时列表 | 知识块适用运行时。 |
| `tags` | Array[String] | `block` 是 | 无 | 标签列表 | 知识块主题标签。 |
| `content_url` | String | `block` 是 | 无 | `/ai/block/...` | AI 应读取的单块 Markdown 地址。 |
| `sha256` | String | `block` 是 | 无 | 64 位小写十六进制 | 单块正文摘要。 |

### 完整搜索索引

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

| 字段 | 类型 | 必填 | 默认值 | 有效范围或可选值 | 含义 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| `schema_version` | Int | 是 | 无 | 当前为 `1` | 索引结构版本。 |
| `knowledge_version` | String | 是 | 无 | 当前知识版本 | 索引所属发布版本。 |
| `source_sha256` | String | 是 | 无 | 64 位小写十六进制 | 索引对应的知识源摘要。 |
| `entries` | Array[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_version` | Int | 是 | 无 | 当前为 `1` | 完整包结构版本。 |
| `bundle_format` | String | 是 | 无 | `bt-ai-bundle-json-v1` | 完整包格式。 |
| `knowledge_version` | String | 是 | 无 | 与请求版本一致 | 包内知识版本。 |
| `manifest` | Object | 是 | 无 | 清单快照 | 为避免自引用哈希，包内 `bundle_sha256` 固定为 `null`。 |
| `block_index` | Object | 是 | 无 | schema 1 | 全部稳定知识块的行号、标签、Token 估算和摘要。 |
| `modules` | Object[String,String] | 是 | 无 | 键为模块 ID | 全部模块 Markdown 正文。 |

### 响应头

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

## 代码示例

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

```bt
search_response = reqwest('https://btlang.org/ai/search')
    .query({q: 'string replace', limit: 5})
    .send()
search_result = search_response.body.parse_json()
symbol = search_result.results.find(fn(item) {
    item.kind == 'symbol'
})

// 输出：`string.replace(pattern, replacement)`
print symbol.signature
```

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

```bt
block_response = reqwest('https://btlang.org/ai/block/stdlib-core/section-5-2').send()
verified = crypto(block_response.body).sha256() === block_response.headers['x-content-sha256']

// 输出：true
print verified
```

## 注意事项

- 普通编码任务不要读取完整搜索索引、完整模块集合或离线包；先搜索并按最小结果读取。
- `/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`。