# BT 编程语言与 bt_app：AI 开发入口

> 唯一规范入口：https://btlang.org/ai 。`/llms.txt` 只用于兼容 AI 工具自动发现，并返回同一份 Markdown。
> BT 是类 JavaScript 语法的解释型语言，`bt_app` 是内嵌 WebView 的桌面开发与打包运行时。
> 当前 BT 版本：`1.1.3`；知识版本：`2026.08.27.2`。

## 必须遵循的节省 Token 读取策略

1. 不要一次读取完整知识包，也不要假定开发机存在 BT 源码仓库或固定本地路径。
2. 先读取 [知识清单](https://btlang.org/ai/manifest) 判断模块、运行时、依赖和 Token 预算。
3. 用 [按关键词搜索](https://btlang.org/ai/search?q=bt_app&limit=8) 找到最小相关结果；查询词优先写 API 名、模块名或运行时名，例如 `string replace`、`mysql transaction`、`bt_app window.bt.call`。
4. 搜索结果为 `symbol` 时，响应已包含调用方式、参数、返回值、示例、注意事项和限制，通常无需继续加载；结果为 `doc` 时只读取其 `markdown_url`；结果为 `block` 时只读取其 `content_url`。
5. 只有新建项目、语义不确定或需要系统设计时才读取整个知识模块。完整离线包只用于离线缓存或工具集成，不应直接塞入模型上下文。
6. 项目自己的 AGENTS.md、README 和测试命令优先于本站通用建议；运行、测试和打包应使用项目实际提供的 `bt.exe` / `bt_app.exe`，不要臆造安装路径。

## 最小查询协议

- 搜索：`GET https://btlang.org/ai/search?q={空格分隔关键词}&limit={1..20}`
- 精确函数文档：`GET https://btlang.org/md/docs/{category}/{api}`
- 单个知识块：`GET https://btlang.org/ai/block/{module_id}/{block_name}`
- 整个知识模块：`GET https://btlang.org/ai/knowledge/{module_id}`
- 机器清单：`GET https://btlang.org/ai/manifest`
- 完整搜索索引：`GET https://btlang.org/ai/index`（仅供工具构建缓存，不建议直接放入上下文）
- 完整离线包：先从清单读取 `bundle_url` 和 SHA-256；仅在确实需要离线全量知识时下载。

示例：查询字符串替换函数时，请求 `/ai/search?q=string%20replace&limit=5`，优先直接使用 `symbol` 结果；需要完整主题说明时再读取 `/md/docs/string/replace`。开发桌面应用时，请求 `/ai/search?q=bt_app%20window.bt.call&limit=8`，先使用约百 Token 的函数契约，需要架构上下文时再读取相关文档或知识块。

## 知识模块路由

- `core-contract`（约 4835 tokens）：bt、semantics、empty、null、runtime、permission；依赖 无。
- `syntax`（约 2885 tokens）：syntax、function、class、include、control-flow；依赖 `core-contract`。
- `stdlib-core`（约 19849 tokens）：string、number、array、object、regex、math、date；依赖 `core-contract`、`syntax`。
- `stdlib-system`（约 24352 tokens）：system、fs、path、process、reqwest、bytes、crypto；依赖 `core-contract`、`syntax`。
- `web-development`（约 4594 tokens）：web、http、route、tpl、request、response；依赖 `core-contract`、`syntax`、`stdlib-system`。
- `desktop-development`（约 11771 tokens）：desktop、bt_app、app.json、window.bt、bundle；依赖 `core-contract`、`syntax`、`stdlib-system`。
- `net-device-data`（约 16129 tokens）：net、mysql、device、modbus、tcp、udp、websocket；依赖 `core-contract`、`syntax`、`stdlib-system`。
- `extensions-ffi`（约 8537 tokens）：extension、ffi、manifest、bindings、wasm、abi；依赖 `core-contract`、`syntax`、`stdlib-system`。
- `generation-checklist`（约 1487 tokens）：generation、checklist、review、coverage、maintenance；依赖 `core-contract`。

## 运行与验收速记

- 普通脚本：在项目目录用项目提供的 BT 运行时执行 `bt.exe -c <script.bt>`；项目根目录存在 `main.bt` 时也可按项目约定直接启动。
- 桌面开发：`bt_app.exe run`；独立 EXE 构建：`bt_app.exe build`；产物默认位于 `dist/`。
- 桌面前端通过 `window.bt.call()` 调用长期驻留的 BT 后端；`app.json` 是桌面配置唯一来源，前端资源必须纳入 `resources`。
- 生成代码前先查语义和目标 API，生成后必须用项目自己的运行时、测试和构建命令验证，不要用 JavaScript/PHP 等语言行为替代 BT 行为。

## 接口说明

通用 AI 接口、返回字段、缓存、哈希校验和错误规则见 [BT AI 开发入口文档](https://btlang.org/md/docs/ai-knowledge)。所有公开知识接口只返回文档，不接收项目源码、用户问题、模型配置、账号或 API Key。