diff --git a/README.md b/README.md
index bcf3c4d..a61abff 100644
--- a/README.md
+++ b/README.md
@@ -397,6 +397,37 @@ uapi
 
 ---
 
+## 在 Sage 系统中的角色
+
+uapi 是 Sage 平台的**配置化 API 网关层**，llmage（大模型管理模块）是其主要消费者。两者的协同关系：
+
+```
+llmage (模型管理)          uapi (API 网关)
+     │                         │
+     │  llm 表                 │
+     │  upappid ──────────────→│ upapp 表 (baseurl, myappid, ownerid)
+     │  apiname ──────────────→│ uapi 表 (httpmethod, path, headers, ...)
+     │                         │ uapiset 表 (auth_apiname)
+     │                         │ upappkey 表 (apikey, secretkey)
+     │                         │
+     │  UpAppApi(request)      │
+     │  .stream_linify() ─────→│ StreamHttpClient → 外部 LLM API
+     │  .call() ──────────────→│ 同步/流式 HTTP 调用
+     │                         │
+```
+
+**新增一个 LLM 的完整流程**：
+1. 在 uapi 模块的 `uapiset` 中创建 API 集合（配置认证方式）
+2. 在 `upapp` 中注册上位系统（baseurl、appkey 等）
+3. 在 `uapi` 中定义具体的 API 端点（path、method、headers 模板、response 模板）
+4. 在 `upappkey` 中分配 API 密钥给调用方
+5. 在 llmage 模块的 `llm` 表中注册模型，关联 `upappid` + `apiname`
+6. 用户在 llmage 前端页面点击模型卡片 → 推理 → 通过 uapi 网关调用外部 API
+
+**优势**：新增模型无需修改 Python 代码，只需在数据库/CRUD 页面中配置 API 定义。
+
+---
+
 ## 开发注意事项
 
 1. **dbname 获取**：必须通过 `get_serverenv('get_module_dbname')('uapi')` 动态获取，禁止硬编码
diff --git a/json/uapi.json b/json/uapi.json
index e28048f..f0db3dd 100644
--- a/json/uapi.json
+++ b/json/uapi.json
@@ -27,11 +27,11 @@
 
 		"title":"API",
 		"description":"API定义",
-		"sortby":["apisetid", "name"],
+		"sortby":"name",
 		"browserfields":{
-			"exclouded":["id", "apisetid"],
+			"exclouded":["id"],
 			"alters":{}
 		},
-		"editexclouded":["id", "apisetid"]
+		"editexclouded":["id"]
 	}
 }
diff --git a/scripts/migrate_uapi_upappid.py b/scripts/migrate_uapi_upappid.py
index caad97c..089d902 100644
--- a/scripts/migrate_uapi_upappid.py
+++ b/scripts/migrate_uapi_upappid.py
@@ -24,10 +24,17 @@ async def generate_migration_sql():
     lines = [
         "-- Migration: uapi table apisetid -> upappid",
         "-- Removes uapiset intermediate layer.",
-        "-- Each upapp owns its own uapi records after migration.",
         "",
-        "-- Step 1: Add upappid column to uapi",
+        "-- Step 1: Schema changes",
+        "-- 1.1 Add upappid to uapi",
         "ALTER TABLE uapi ADD COLUMN upappid VARCHAR(21) DEFAULT NULL COMMENT '上位系统ID' AFTER id;",
+        "",
+        "-- 1.2 Add auth_apiname to upapp",
+        "ALTER TABLE upapp ADD COLUMN auth_apiname VARCHAR(200) DEFAULT NULL COMMENT '授权API名' AFTER apisetid;",
+        "",
+        "-- 1.3 Migrate auth_apiname from uapiset to upapp",
+        "UPDATE upapp u JOIN uapiset s ON u.apisetid = s.id",
+        "SET u.auth_apiname = s.auth_apiname WHERE s.auth_apiname IS NOT NULL;",
         ""
     ]