docs(rag-api): 对外 API README（鉴权/7端点/示例，字段与代码核对）

- 鉴权：cookie 会话 或 dapi Bearer key（load_dapi 注册，RBAC logined 统一把关）
- 返回格式、参数、示例；标注 VDB/embedding 网络可达为运行前置

wwwroot/api/README.md

@@ -0,0 +1,97 @@
+# RAG 对外 API
+
+供其他系统（非 Bricks 前端）以 HTTP JSON 调用的知识库接口。与 UI 通道共用同一套
+RBAC 鉴权、机构隔离与底层入库/检索实现（`rag/api_core.py` + `rag/ingest.py`）。
+
+## 鉴权
+
+二选一，均由 RBAC 中间件统一把关（端点注册为 `logined` 权限）：
+
+1. **Cookie 会话**：先 `POST /rbac/user/up_login.dspy` 登录，携带 `AIOHTTP_SESSION` cookie。
+2. **Bearer API Key**：`Authorization: Bearer <key>`。
+   Key 由平台 **dapi 模块**统一管理（`downapp` + `downapikey` 表），不在本模块自建。
+   发放方式：
+   - UI：API Key 管理页（dapi 的 `apikey_manage.ui`）为目标用户按 downapp 创建；
+   - 代码：`from dapi import create_user_apikey` → 传入 `(sor, dappid, user_id, user_orgid)`，
+     返回 `{'status','apikey',...}`。`create_user_apikey` 内部按 `(dappid,userid)` 幂等，
+     已存在则返回现有 key。
+   - 校验链：`register_auth_method('Bearer ', bearer_auth)` 在 `load_dapi()` 时挂载；
+     key 命中后解析出绑定的 RBAC 用户与机构，**org 身份与 UI 通道完全一致**
+     （`session_env(request)` 统一注入），因此知识库/标签/文档天然按机构隔离。
+
+匿名请求返回 401；跨机构访问他人 kb_id 返回业务 error（查不到即拒绝，不泄露存在性）。
+
+## 通用返回格式
+
+```json
+{"status": "ok",    "data": { ... }}
+{"status": "error", "message": "原因", "data": null}
+```
+
+HTTP 状态码恒为 200（除鉴权失败 401），业务成败看 `status` 字段。
+
+## 端点一览（POST，参数走 JSON body，也兼容 query）
+
+| 端点 | 参数 | 返回 data |
+|---|---|---|
+| `/rag/api/kb_create.dspy` | `name`*, `description?`, `embedding_engine?`(默认 bge-m3) | `{kb_id, name, embedding_engine}` |
+| `/rag/api/kb_delete.dspy` | `kb_id`* | `{kb_id, documents, files_removed, ...}`（级联删 chunks/向量/文件） |
+| `/rag/api/doc_upload.dspy` | query: `kb_id`*, `file_name`*, `folder_id?`；body=文件**原始字节**（Content-Type: application/octet-stream） | `{doc_id, kb_id, file_name, file_size, status:"pending", ingest:"running_in_background"}` |
+| `/rag/api/doc_delete.dspy` | `doc_id`* | `{doc_id, kb_id, chunks_deleted, file_removed}` |
+| `/rag/api/tag_create.dspy` | `kb_id`*, `name`*, `color?` | `{tag_id, name, color}`（同名幂等返回已有并带 `duplicate:true`） |
+| `/rag/api/doc_set_tags.dspy` | `kb_id`*, `doc_id`*, `tags`(名称列表) \| `tag_ids`(ID列表) | `{doc_id, added, removed, tags:[{id,name,color}]}`（全量语义，空数组=清空） |
+| `/rag/api/search.dspy` | `query`*, `kb_id?`(缺省=本机构全部KB), `top_k?`(默认10), `recall_k?`(默认top_k*3) | `{results:[{chunk_id, text, score, kb_id, doc:{id,file_name,file_type,kb_id}}], total, recall, kbs_searched}` |
+
+`*` 为必填。缺失/非法一律返回 `{"status":"error","message":...}`，不会产生 500。
+
+## 调用示例
+
+```bash
+BASE=https://<host>/rag/api
+KEY=*** 1. 建知识库
+curl -s -X POST $BASE/kb_create.dspy -H "Authorization: Bearer $KEY" \
+     -H 'Content-Type: application/json' \
+     -d '{"name":"标书资料库","embedding_engine":"bge-m3"}'
+
+# 2. 上传文件（原始字节；kb_id/file_name 走 query）
+curl -s -X POST "$BASE/doc_upload.dspy?kb_id=$KB&file_name=tender.pdf" \
+     -H "Authorization: Bearer $KEY" \
+     -H 'Content-Type: application/octet-stream' \
+     --data-binary @tender.pdf
+
+# 3. 检索（上传后等待后台入库完成，status 变 done 才可被召回）
+curl -s -X POST $BASE/search.dspy -H "Authorization: Bearer $KEY" \
+     -H 'Content-Type: application/json' \
+     -d '{"query":"投标人资质要求","kb_id":"'$KB'","top_k":5}'
+
+# 4. 标签：创建 + 全量设置（tags 里的新名字自动建标签；空数组=清空）
+curl -s -X POST $BASE/tag_create.dspy -H "Authorization: Bearer $KEY" \
+     -H 'Content-Type: application/json' -d '{"kb_id":"'$KB'","name":"技术标"}'
+curl -s -X POST $BASE/doc_set_tags.dspy -H "Authorization: Bearer $KEY" \
+     -H 'Content-Type: application/json' \
+     -d '{"kb_id":"'$KB'","doc_id":"'$DOC'","tags":["技术标","2026"]}'
+
+# 5. 删除
+curl -s -X POST $BASE/doc_delete.dspy -H "Authorization: Bearer $KEY" \
+     -H 'Content-Type: application/json' -d '{"doc_id":"'$DOC'"}'
+curl -s -X POST $BASE/kb_delete.dspy -H "Authorization: Bearer $KEY" \
+     -H 'Content-Type: application/json' -d '{"kb_id":"'$KB'"}'
+```
+
+## 入库与检索说明
+
+- `doc_upload` 立即返回（`status:"pending"`），后台 asyncio 任务完成
+  解析→分块→向量化→VDB upsert→chunks 落库；成功置 `done`，
+  任何失败置 `failed` 并把真实原因写 `rag_documents.error_msg`（不静默）。
+  文本类（txt/md/pdf/docx/pptx/xlsx/csv…）可被检索召回；图片/音视频走多模态/embedding 引擎配置。
+- 检索向量引擎按知识库 `embedding_engine` 选择（`bge-m3` 在线文本 / `qwen3-vl-embedding` 在线多模态），
+  配置在 `rag_engine_configs`（endpoint + RC4 加密 key）。召回后自动重排（若 rerank 引擎可用）。
+- 依赖基础设施：embedding/rerank 在线 API 与 VDB 服务
+  （`upapp.rag-vdb` 的 baseurl）必须从部署机网络可达；不可达时 ingest/search 会明确报错而非假成功。
+
+## 内部助手（非 HTTP）
+
+同一套能力封装为 OpenAI function-calling schema 供宿主 Agent 直调，不绕 HTTP：
+见 `rag/tools.py`（`rag_kb_create` 等 7 个）。宿主 env 需具备
+`db` / `get_user` / `get_userorgid` / `password_encode` / `get_module_dbname`；
+org 由宿主注入，与 API 通道的机构隔离语义一致。