deveco_hmigbot 0.21.5

package/skills/migrate-core/references/topics/system-capabilities/document-picker.md

@@ -0,0 +1,246 @@
+# 文件管理器 DocumentViewPicker
+
+> 使用 `@kit.CoreFileKit` 的 `picker` 模块拉起系统文件管理器，替代 Android 的 `Intent.ACTION_OPEN_DOCUMENT` 和 `Intent.ACTION_CREATE_DOCUMENT`。
+
+---
+
+## 基本导入
+
+```typescript
+import { picker } from '@kit.CoreFileKit';
+import { common } from '@kit.AbilityKit';
+```
+
+---
+
+## 唤起文件管理器（选择文件）
+
+> 对应 Android：`Intent.ACTION_OPEN_DOCUMENT`
+
+### 基础用法
+
+```typescript
+function openFileManager(context: common.UIAbilityContext): void {
+  const docPicker = new picker.DocumentViewPicker(context);
+  const selectOptions = new picker.DocumentSelectOptions();
+
+  docPicker.select(selectOptions)
+    .then((uris: Array<string>) => {
+      hilog.info(DOMAIN, TAG, `Selected files: ${uris.length}`);
+      // uris 是用户选择的文件 URI 数组
+      uris.forEach(uri => {
+        hilog.info(DOMAIN, TAG, `Selected URI: ${uri}`);
+      });
+    })
+    .catch((err: Error) => {
+      hilog.error(DOMAIN, TAG, `Failed to open file manager: ${err.message}`);
+    });
+}
+```
+
+### 限定文件后缀
+
+```typescript
+function openFileManagerWithFilter(context: common.UIAbilityContext): void {
+  const docPicker = new picker.DocumentViewPicker(context);
+  const selectOptions = new picker.DocumentSelectOptions();
+
+  // 仅允许选择特定后缀的文件
+  selectOptions.fileSuffixFilters = ['.txt', '.pdf', '.epub', '.mht'];
+
+  docPicker.select(selectOptions)
+    .then((uris: Array<string>) => {
+      if (uris.length > 0) {
+        hilog.info(DOMAIN, TAG, `Selected: ${uris[0]}`);
+      }
+    })
+    .catch((err: Error) => {
+      hilog.error(DOMAIN, TAG, `Select error: ${err.message}`);
+    });
+}
+```
+
+---
+
+## 唤起文件管理器（保存文件）
+
+> 对应 Android：`Intent.ACTION_CREATE_DOCUMENT`
+
+### 基础用法
+
+```typescript
+function saveFileToDownloads(context: common.UIAbilityContext, fileName: string, content: string): void {
+  const docPicker = new picker.DocumentViewPicker(context);
+  const saveOptions = new picker.DocumentSaveOptions();
+
+  // 设置默认文件名
+  saveOptions.newFileNames = [fileName];
+  // 限定可保存的文件后缀
+  saveOptions.fileSuffixChoices = ['.txt', '.mht', '.html'];
+
+  docPicker.save(saveOptions)
+    .then((uris: Array<string>) => {
+      if (uris.length > 0) {
+        hilog.info(DOMAIN, TAG, `File saved to: ${uris[0]}`);
+        // 通过 URI 写入文件内容（需配合 fileIo）
+      }
+    })
+    .catch((err: Error) => {
+      hilog.error(DOMAIN, TAG, `Save cancelled or failed: ${err.message}`);
+    });
+}
+```
+
+### 完整示例：保存网页为 MHT
+
+```typescript
+import { picker } from '@kit.CoreFileKit';
+import { fileIo } from '@kit.CoreFileKit';
+import { common } from '@kit.AbilityKit';
+
+function saveWebPage(context: common.UIAbilityContext, title: string, content: string): void {
+  const docPicker = new picker.DocumentViewPicker(context);
+  const saveOptions = new picker.DocumentSaveOptions();
+
+  // 清理文件名中的非法字符
+  let fileName = title || 'page';
+  if (fileName.length > 50) {
+    fileName = fileName.substring(0, 50);
+  }
+  fileName = fileName.replace(/[\\/:*?"<>|]/g, '_');
+
+  saveOptions.newFileNames = [fileName + '.mht'];
+  saveOptions.fileSuffixChoices = ['MHT|.mht'];
+
+  docPicker.save(saveOptions)
+    .then((uris: Array<string>) => {
+      if (uris.length > 0) {
+        hilog.info(DOMAIN, TAG, `Saved to: ${uris[0]}`);
+        // 写入文件内容
+        try {
+          const file = fileIo.openSync(uris[0], fileIo.OpenMode.WRITE_ONLY | fileIo.OpenMode.CREATE);
+          fileIo.writeSync(file.fd, content);
+          fileIo.closeSync(file.fd);
+          hilog.info(DOMAIN, TAG, 'File content written successfully');
+        } catch (writeErr) {
+          hilog.error(DOMAIN, TAG, `Write file error: ${writeErr.message}`);
+        }
+      }
+    })
+    .catch((err: Error) => {
+      hilog.info(DOMAIN, TAG, `Save cancelled: ${err.message}`);
+    });
+}
+```
+
+---
+
+## DocumentSelectOptions 配置项
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `fileSuffixFilters` | `string[]` | 限定可选择的文件后缀，如 `['.txt', '.pdf']` |
+| `subFuzzingNumber` | `number` | 子目录搜索深度，默认 0（仅当前目录） |
+
+---
+
+## DocumentSaveOptions 配置项
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `newFileNames` | `string[]` | 默认文件名数组（第一个为默认名） |
+| `fileSuffixChoices` | `string[]` | 允许保存的文件后缀列表，格式如 `'MHT|.mht'` 或 `'.mht'` |
+
+---
+
+## DocumentViewPicker 其他方法
+
+| 方法 | 用途 | 对应 Android |
+|------|------|-------------|
+| `.select(options)` | 选择文件（可多选） | `ACTION_OPEN_DOCUMENT` |
+| `.save(options)` | 保存文件 | `ACTION_CREATE_DOCUMENT` |
+
+---
+
+## module.json5 配置
+
+> ⚠️ **重要**：`DocumentViewPicker` 是系统内置 picker，通常**不需要**额外配置 module.json5。
+
+以下情况可能需要配置：
+- 应用需要作为文件提供者响应其他应用的文件请求
+- 需要声明特定的 file 类型支持
+
+```json5
+{
+  "skills": [{
+    "entities": ["entity.system.home"],
+    "actions": [
+      "ohos.want.action.home"
+    ]
+  }]
+}
+```
+
+---
+
+## 常见错误
+
+### 错误 1：选择文件后未正确处理 URI
+
+```typescript
+// 错误 — 直接使用 URI 访问文件
+const data = fileIo.readFileSync(uri);  // ❌ 不支持直接路径
+
+// 正确 — 使用 fileIo.openSync 获取 fd
+const file = fileIo.openSync(uri, fileIo.OpenMode.READ_ONLY);
+const data = fileIo.readSync(file.fd);
+fileIo.closeSync(file.fd);
+```
+
+### 错误 2：保存文件时文件名包含非法字符
+
+```typescript
+// 错误 — Windows 文件名不允许以下字符
+saveOptions.newFileNames = ['file:name?.mht'];
+
+// 正确 — 替换非法字符
+let safeName = fileName.replace(/[\\/:*?"<>|]/g, '_');
+saveOptions.newFileNames = [safeName + '.mht'];
+```
+
+### 错误 3：save() 的 Promise 被静默取消
+
+```typescript
+// 错误 — 用户取消时可能静默失败
+docPicker.save(saveOptions)
+  .then((uris) => {
+    if (uris.length > 0) { /* 保存成功 */ }
+    // ⚠️ 用户取消时 uris 为空数组，但没有提示
+  });
+
+// 正确 — 用 finally 或区分处理
+docPicker.save(saveOptions)
+  .then((uris) => {
+    if (uris.length > 0) {
+      hilog.info(DOMAIN, TAG, 'Save success');
+    }
+  })
+  .catch((err) => {
+    hilog.error(DOMAIN, TAG, 'Save failed');
+  })
+  .finally(() => {
+    // 用户取消也会走到这里
+    hilog.info(DOMAIN, TAG, 'Save dialog closed');
+  });
+```
+
+---
+
+## 与 cameraPicker 的对比
+
+| 维度 | DocumentViewPicker（本节） | cameraPicker |
+|------|--------------------------|--------------|
+| 所属 Kit | `@kit.CoreFileKit` | `@kit.CameraKit` |
+| 功能 | 选择/保存文件 | 拍照/录像 |
+| 返回 | `Promise<Array<string>>`（URI 数组） | `Promise<PickerResult>` |
+| module.json5 配置 | 通常不需要 | 需要 `entity.system.camera` |

package/skills/migrate-core/references/topics/system-capabilities/file-utils.md

@@ -0,0 +1,131 @@
+# 文件操作指南
+
+> @kit.CoreFileKit 文件读写的完整使用模式，替代 Android 的 java.io.File。
+
+---
+
+## 基本导入
+
+```typescript
+import { fileIo } from '@kit.CoreFileKit'
+import { util } from '@kit.ArkTS'
+```
+
+---
+
+## 沙箱路径
+
+HarmonyOS 应用只能访问自己的沙箱目录：
+
+```typescript
+// 获取沙箱路径
+const filesDir = context.filesDir       // 持久化存储目录
+const cacheDir = context.cacheDir       // 缓存目录（系统可能自动清理）
+const tempDir = context.tempDir         // 临时目录
+```
+
+**关键规则**：
+- ✅ 只能使用 `context.filesDir`、`context.cacheDir`、`context.tempDir`
+- ❌ 不能写入 `/storage/...` 等绝对路径（Permission denied）
+
+---
+
+## 文件读写
+
+### 写入文件
+
+```typescript
+function writeFile(context: Context, fileName: string, content: string): void {
+  const filePath = `${context.filesDir}/${fileName}`
+  const file = fileIo.openSync(filePath, fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY)
+  fileIo.writeSync(file.fd, content)
+  fileIo.closeSync(file.fd)
+}
+```
+
+### 读取文件
+
+```typescript
+function readFile(context: Context, fileName: string): string {
+  const filePath = `${context.filesDir}/${fileName}`
+  const file = fileIo.openSync(filePath, fileIo.OpenMode.READ_ONLY)
+  const stat = fileIo.statSync(filePath)
+  const buffer = new ArrayBuffer(stat.size)
+  fileIo.readSync(file.fd, buffer)
+  fileIo.closeSync(file.fd)
+
+  const decoder = new util.TextDecoder('utf-8')
+  return decoder.decodeWithStream(new Uint8Array(buffer))
+}
+```
+
+### 检查文件是否存在
+
+```typescript
+function fileExists(path: string): boolean {
+  try {
+    fileIo.accessSync(path)
+    return true
+  } catch {
+    return false
+  }
+}
+```
+
+### 创建目录
+
+```typescript
+function ensureDir(dirPath: string): void {
+  try {
+    fileIo.mkdirSync(dirPath, true)  // true = 递归创建
+  } catch {
+    // 目录已存在
+  }
+}
+```
+
+### 删除文件
+
+```typescript
+function deleteFile(path: string): void {
+  try {
+    fileIo.unlinkSync(path)
+  } catch {
+    // 文件不存在
+  }
+}
+```
+
+---
+
+## 下载文件到沙箱
+
+```typescript
+import { http } from '@kit.NetworkKit'
+
+async function downloadToSandbox(
+  context: Context,
+  url: string,
+  fileName: string
+): Promise<string> {
+  const savePath = `${context.filesDir}/downloads`
+  ensureDir(savePath)
+
+  const filePath = `${savePath}/${fileName}`
+  const httpRequest = http.createHttp()
+  try {
+    const response = await httpRequest.request(url, {
+      method: http.RequestMethod.GET,
+      expectDataType: http.HttpDataType.ARRAY_BUFFER
+    })
+    if (response.responseCode === 200) {
+      const file = fileIo.openSync(filePath, fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY)
+      fileIo.writeSync(file.fd, response.result as ArrayBuffer)
+      fileIo.closeSync(file.fd)
+    }
+  } finally {
+    httpRequest.destroy()
+  }
+  return filePath
+}
+```

package/skills/migrate-core/references/topics/system-capabilities/permission-helper.md

@@ -0,0 +1,112 @@
+# 权限请求与检查
+
+> ⚠ 本文样例中 `getContext(this)` 为已废弃写法：组件内一律改 `this.getUIContext().getHostContext()`；Ability 内用 `this.context`。
+
+
+> abilityAccessCtrl 权限管理的完整使用模式，替代 Android 的 ActivityCompat.requestPermissions。
+
+---
+
+## 基本导入
+
+```typescript
+import { abilityAccessCtrl, Permissions, bundleManager, common } from '@kit.AbilityKit'
+```
+
+---
+
+## 完整权限请求封装
+
+```typescript
+// helpers/PermissionHelper.ets
+export class PermissionHelper {
+  /**
+   * 检查并请求权限
+   * @returns true 表示已获得所有权限
+   */
+  static async requestPermissions(
+    context: common.UIAbilityContext,
+    permissions: Permissions[]
+  ): Promise<boolean> {
+    const atManager = abilityAccessCtrl.createAtManager()
+
+    // 先检查是否已有权限
+    const allGranted = await PermissionHelper.checkPermissions(context, permissions)
+    if (allGranted) return true
+
+    // 请求权限
+    const result = await atManager.requestPermissionsFromUser(context, permissions)
+
+    // 检查结果
+    for (let i = 0; i < result.authResults.length; i++) {
+      if (result.authResults[i] !== 0) {
+        return false  // 有权限被拒绝
+      }
+    }
+    return true
+  }
+
+  /**
+   * 检查权限状态
+   */
+  static async checkPermissions(
+    context: common.UIAbilityContext,
+    permissions: Permissions[]
+  ): Promise<boolean> {
+    const atManager = abilityAccessCtrl.createAtManager()
+    const bundleInfo = await bundleManager.getBundleInfoForSelf(
+      bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
+    )
+    const tokenId = bundleInfo.appInfo.accessTokenId
+
+    for (const permission of permissions) {
+      const grantStatus = await atManager.checkAccessToken(tokenId, permission)
+      if (grantStatus !== abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
+        return false
+      }
+    }
+    return true
+  }
+}
+```
+
+---
+
+## 使用示例
+
+```typescript
+// 在页面中请求权限
+async aboutToAppear(): Promise<void> {
+  const context = getContext(this) as common.UIAbilityContext
+  const granted = await PermissionHelper.requestPermissions(context, [
+    'ohos.permission.CAMERA' as Permissions,
+    'ohos.permission.MICROPHONE' as Permissions,
+  ])
+
+  if (granted) {
+    await this.loadData()
+  } else {
+    // 提示用户去设置页面开启权限
+    this.showPermissionDeniedTip()
+  }
+}
+```
+
+---
+
+## 常用权限列表
+
+| 权限 | 用途 | 类型 |
+|------|------|------|
+| `ohos.permission.INTERNET` | 网络访问 | system_grant（自动授权）|
+| `ohos.permission.CAMERA` | 相机 | user_grant（需用户同意）|
+| `ohos.permission.MICROPHONE` | 麦克风 | user_grant |
+| `ohos.permission.APPROXIMATELY_LOCATION` | 模糊定位 | user_grant |
+| `ohos.permission.LOCATION` | 精确定位 | user_grant，**须与 APPROXIMATELY_LOCATION 一起申请**，不能单独申请 |
+| `ohos.permission.KEEP_BACKGROUND_RUNNING` | 后台运行 | system_grant |
+| `ohos.permission.READ_IMAGEVIDEO` / `WRITE_IMAGEVIDEO` | 全量读/直写媒体库 | **受限开放**（system_basic，须 ACL）——三方应用改用 PhotoViewPicker / SaveButton（免权限） |
+| `ohos.permission.READ_CONTACTS` / `WRITE_CONTACTS` | 读/写通讯录 | **受限开放**——改用 `contact.selectContacts`（系统选人，免权限） |
+
+**system_grant**：在 module.json5 中声明即可，系统自动授权。
+**user_grant**：需要在 module.json5 声明 + 代码运行时请求用户同意。
+**受限开放权限**（READ/WRITE_IMAGEVIDEO、READ/WRITE_CONTACTS、READ/WRITE_AUDIO、SYSTEM_FLOAT_WINDOW、READ_PASTEBOARD 等）：normal 应用须 ACL 才能申请，默认拿不到——改走系统 Picker / 安全控件。权限名以 SDK `ets/api/permissions.d.ts` 为准，是否受限以官方"受限开放权限"清单为准。

package/skills/migrate-core/references/topics/system-capabilities/photo-access-helper.md

@@ -0,0 +1,208 @@
+# photoAccessHelper 媒体查询指南
+
+> HarmonyOS 媒体库访问的完整使用模式，替代 Android 的 MediaStore + ContentProvider。
+
+## 权限口径（先定路线再写码）
+
+| 路线 | API | 权限 | 适用 |
+|---|---|---|---|
+| 选图 | `new photoAccessHelper.PhotoViewPicker().select(options)` | 无需权限；返回 uri 只读，不在 picker 回调里直接开文件，存下来由按钮等事件再读 | 三方应用默认 |
+| 存图 | `SaveButton` 安全控件 `onClick` 内 `MediaAssetChangeRequest.createImageAssetRequest / createAssetRequest` + `applyChanges` | 无需权限（点击态临时授权） | 三方应用默认 |
+| 存图 | `phAccessHelper.showAssetsCreationDialog(srcUris, configs)` 拿目标 uri 后 `fileIo` 写入 | 无需权限（弹窗授权） | 三方应用默认 |
+| 全量读 | `getAssets` / `getAlbums` | `ohos.permission.READ_IMAGEVIDEO`——**受限开放权限**（system_basic，须 ACL） | 仅拿到 ACL 的应用 |
+| 直写 | `createAsset`、`SaveButton` 之外调用的 `applyChanges` | `ohos.permission.WRITE_IMAGEVIDEO`——受限开放权限 | 仅拿到 ACL 的应用 |
+
+Android `MediaStore` 查询默认映射到"选图"路线（用户从系统图库选），不是 `getAssets`；相册写入映射到 `SaveButton` 路线。
+
+---
+
+## 选图（PhotoViewPicker，无需权限）
+
+```typescript
+import { photoAccessHelper } from '@kit.MediaLibraryKit'
+import { BusinessError } from '@kit.BasicServicesKit'
+
+@State pickedUris: string[] = []
+
+async pickImages(): Promise<void> {
+  const options = new photoAccessHelper.PhotoSelectOptions()
+  options.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE
+  options.maxSelectNumber = 9
+  try {
+    const result: photoAccessHelper.PhotoSelectResult = await new photoAccessHelper.PhotoViewPicker().select(options)
+    this.pickedUris = result.photoUris   // 只读 uri；读文件放到按钮等事件里做，不在此回调里直接 open
+  } catch (e) {
+    const err = e as BusinessError      // 用户取消也走这里：保持原状或给可见提示
+  }
+}
+```
+
+---
+
+## 基本导入与初始化
+
+```typescript
+import { photoAccessHelper } from '@kit.MediaLibraryKit'
+import { dataSharePredicates } from '@kit.ArkData'
+
+const phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context)
+```
+
+---
+
+## 全量查询媒体资源（getAssets：需 `READ_IMAGEVIDEO`，受限开放——只在拿到 ACL 时用）
+
+```typescript
+async function getMediaAssets(context: Context): Promise<photoAccessHelper.PhotoAsset[]> {
+  const phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context)
+
+  const fetchOptions: photoAccessHelper.FetchOptions = {
+    fetchColumns: [
+      photoAccessHelper.PhotoKeys.URI,
+      photoAccessHelper.PhotoKeys.DISPLAY_NAME,
+      photoAccessHelper.PhotoKeys.SIZE,
+      photoAccessHelper.PhotoKeys.DATE_ADDED,
+      photoAccessHelper.PhotoKeys.DURATION,
+      photoAccessHelper.PhotoKeys.WIDTH,
+      photoAccessHelper.PhotoKeys.HEIGHT,
+      photoAccessHelper.PhotoKeys.PHOTO_TYPE,
+    ],
+    predicates: new dataSharePredicates.DataSharePredicates()
+  }
+
+  const fetchResult = await phAccessHelper.getAssets(fetchOptions)
+  const count = fetchResult.getCount()
+  const assets: photoAccessHelper.PhotoAsset[] = []
+
+  if (count > 0) {
+    let asset = await fetchResult.getFirstObject()
+    let index = 0
+    while (index < count) {
+      assets.push(asset)
+      index++
+      if (index < count) {
+        asset = await fetchResult.getNextObject()
+      }
+    }
+  }
+
+  fetchResult.close()  // 必须关闭！
+  return assets
+}
+```
+
+---
+
+## FetchResult 遍历模式（关键）
+
+**FetchResult 不是数组**，是游标式迭代器。必须按以下模式遍历：
+
+```typescript
+// ✅ 正确模式
+let asset = await fetchResult.getFirstObject()
+let index = 0
+while (index < count) {
+  // 处理 asset
+  processAsset(asset)
+  index++
+  if (index < count) {
+    asset = await fetchResult.getNextObject()
+  }
+}
+fetchResult.close()  // 必须关闭
+
+// ❌ 错误 — 不能用 for...of
+for (const asset of fetchResult) { ... }  // 不支持
+
+// ❌ 错误 — 不能一次性获取全部
+const allAssets = await fetchResult.getAllObjects()  // 大量数据会内存溢出
+```
+
+---
+
+## 获取文件 URI
+
+```typescript
+// 获取资源 URI（可用于 Image 组件显示）
+const uri = asset.uri  // 格式: file://media/Photo/xxx
+
+// ⚠️ 视频 URI 不能传给 Image 组件（会显示灰色空白）
+// 图片 URI 可以直接传给 Image 组件
+Image(asset.uri)
+  .sourceSize({ width: 256, height: 256 })  // 缩略图优化
+```
+
+---
+
+## 按类型筛选
+
+```typescript
+// 只查图片
+const predicates = new dataSharePredicates.DataSharePredicates()
+predicates.equalTo(photoAccessHelper.PhotoKeys.PHOTO_TYPE, photoAccessHelper.PhotoType.IMAGE)
+
+// 只查视频
+predicates.equalTo(photoAccessHelper.PhotoKeys.PHOTO_TYPE, photoAccessHelper.PhotoType.VIDEO)
+```
+
+---
+
+## 保存图片到系统相册（MediaAssetChangeRequest 三步）
+
+把 app 生成/下载的图片写入系统相册，**走资产变更请求范式**，不要臆造一步式 `saveImage`，也**不要用 `phAccessHelper.createAsset(...)` + `fileIo.open(uri)` + `copyFile` 直写文件**（`createAsset` 需受限权限 `WRITE_IMAGEVIDEO`）。
+`applyChanges` 免权限的前提是**在 `SaveButton` 安全控件的 `onClick` 里调用**（点击态临时授权）；在别处调用同样需要 `WRITE_IMAGEVIDEO`。
+
+三步（编译校验过）：
+
+```typescript
+import { photoAccessHelper } from '@kit.MediaLibraryKit'
+import { common } from '@kit.AbilityKit'
+
+// srcFileUri：沙箱内源图片的 file:// URI（沙箱路径可用 fileUri.getUriFromPath 转换）
+async function saveImageToAlbum(context: common.UIAbilityContext, srcFileUri: string): Promise<void> {
+  const phAccessHelper: photoAccessHelper.PhotoAccessHelper =
+    photoAccessHelper.getPhotoAccessHelper(context)
+
+  // 1) 创建图片资产变更请求（photoType + 扩展名；options 可选）
+  const req: photoAccessHelper.MediaAssetChangeRequest =
+    photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(
+      context, photoAccessHelper.PhotoType.IMAGE, 'jpg'
+    )
+
+  // 2) 注入图片数据：源文件 URI（string）或 ArrayBuffer 二选一
+  req.addResource(photoAccessHelper.ResourceType.IMAGE_RESOURCE, srcFileUri)
+
+  // 3) 提交生效（异步，必须 await / then）
+  await phAccessHelper.applyChanges(req)
+}
+```
+
+触发点必须是 `SaveButton`（安全控件）的 `onClick`——点击态临时授权，免 `WRITE_IMAGEVIDEO`：
+
+```typescript
+SaveButton({ icon: SaveIconStyle.FULL_FILLED, text: SaveDescription.SAVE_IMAGE, buttonType: ButtonType.Capsule })
+  .onClick(async (event: ClickEvent, result: SaveButtonOnClickResult) => {
+    if (result === SaveButtonOnClickResult.SUCCESS) {
+      await saveImageToAlbum(this.getUIContext().getHostContext() as common.UIAbilityContext, srcFileUri)
+    }
+  })
+```
+
+关键签名与要点：
+
+| 项 | 内容 |
+|----|------|
+| 创建请求 | `MediaAssetChangeRequest.createAssetRequest(context: Context, photoType: PhotoType, extension: string, options?: CreateOptions): MediaAssetChangeRequest` |
+| 注入数据 | `req.addResource(type: ResourceType, fileUri: string \| ArrayBuffer): void`，类型用 `photoAccessHelper.ResourceType.IMAGE_RESOURCE` |
+| 提交 | `await phAccessHelper.applyChanges(req)`（返回 Promise） |
+| 权限 | `SaveButton.onClick` 内调用免权限；其它位置需 `ohos.permission.WRITE_IMAGEVIDEO`（受限开放，须 ACL） |
+
+> `addResource` 传源文件 URI 时，须确保该 URI 对应的资源实际存在。已有现成图片文件时也可用 `MediaAssetChangeRequest.createImageAssetRequest(context, fileUri)` 一步建请求再 `applyChanges`。
+
+---
+
+## 权限要求
+
+三方应用默认路线（PhotoViewPicker / SaveButton / showAssetsCreationDialog）**不声明任何媒体权限**。
+只有拿到 ACL 的应用才声明 `ohos.permission.READ_IMAGEVIDEO` / `WRITE_IMAGEVIDEO`（受限开放权限，system_basic；普通应用声明后签名即失败）。
+写相册不能靠只读权限：`READ_IMAGEVIDEO` 不覆盖写入。