@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/35-/346/226/207/344/273/266/347/263/273/347/273/237.md

@@ -0,0 +1,431 @@
+# 豆包应用插件的端能力 API: 文件系统
+
+文件读写、目录管理和文件信息操作。
+
+[返回目录](./groups.md) | [返回速查](./quick-reference.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [getFileSystemManager](#getfilesystemmanager) | 获取文件系统管理器。 |
+
+## API 详情
+
+<a id="getfilesystemmanager"></a>
+### getFileSystemManager()
+
+# getFileSystemManager
+
+获取文件系统管理器。
+
+## 扫码预览
+![扫码预览 getFileSystemManager](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Ffile-system%252Fget-file-system-manager%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.31`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- 无额外前置条件，直接调用 getFileSystemManager 获取管理器实例后再调用其方法
+
+## 使用说明
+
+- readFile、readFileSync 省略 encoding 时默认返回 Base64 字符串，writeFile、appendFile 省略 encoding 时默认按 UTF-8 写入；需要明确编码时请显式传入 encoding。
+
+## 调用方式
+
+### 同步 API
+
+```typescript
+getFileSystemManager(): FileSystemManager
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { getFileSystemManager } from '@doubao-dev/framework/api';
+
+const fs = getFileSystemManager();
+const { data } = await fs.readFile({
+  filePath: '/tmp/profile.json',
+  encoding: 'utf-8'
+});
+
+console.log(data);
+```
+
+## 返回值
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>access</code></td><td><code>(params: AccessParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>判断文件或目录是否存在（异步）。存在时 Promise 兑现，不存在时 Promise 拒绝。</td></tr>
+<tr><td><code>accessSync</code></td><td><code>(params: AccessParams) =&gt; void</code></td><td>是</td><td>判断文件或目录是否存在（同步）。不存在时抛出异常。</td></tr>
+<tr><td><code>appendFile</code></td><td><code>(params: AppendFileParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>在文件末尾追加内容（异步）。文件不存在则创建，不会覆盖已有内容。</td></tr>
+<tr><td><code>appendFileSync</code></td><td><code>(params: AppendFileParams) =&gt; void</code></td><td>是</td><td>在文件末尾追加内容（同步）。文件不存在则创建，不会覆盖已有内容。</td></tr>
+<tr><td><code>copyFile</code></td><td><code>(params: CopyFileParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>复制文件（异步）。仅支持文件，目标已存在同名文件时覆盖。</td></tr>
+<tr><td><code>copyFileSync</code></td><td><code>(params: CopyFileParams) =&gt; void</code></td><td>是</td><td>复制文件（同步）。仅支持文件，目标已存在同名文件时覆盖。</td></tr>
+<tr><td><code>getFileInfo</code></td><td><code>(params: GetFileInfoParams) =&gt; Promise&lt;GetFileInfoResult&gt;</code></td><td>是</td><td>获取文件信息（异步）；返回 GetFileInfoResult，含字节大小和可选的摘要。</td></tr>
+<tr><td><code>getSavedFileList</code></td><td><code>() =&gt; Promise&lt;GetSavedFileListResult&gt;</code></td><td>是</td><td>获取已保存的本地文件列表（异步）；返回 GetSavedFileListResult，每项含路径、字节大小和毫秒级保存时间。</td></tr>
+<tr><td><code>mkdir</code></td><td><code>(params: MkdirParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>创建目录（异步）。recursive 为 true 时一并创建缺失的上级目录。</td></tr>
+<tr><td><code>mkdirSync</code></td><td><code>(params: MkdirParams) =&gt; void</code></td><td>是</td><td>创建目录（同步）。recursive 为 true 时一并创建缺失的上级目录。</td></tr>
+<tr><td><code>readdir</code></td><td><code>(params: ReaddirParams) =&gt; Promise&lt;ReaddirResult&gt;</code></td><td>是</td><td>读取目录内容（异步）；返回 ReaddirResult，files 为目录下的文件与子目录名称（非完整路径，非递归）。</td></tr>
+<tr><td><code>readdirSync</code></td><td><code>(params: ReaddirParams) =&gt; ReaddirResult</code></td><td>是</td><td>读取目录内容（同步）；返回 ReaddirResult，files 为目录下的文件与子目录名称（非完整路径，非递归）。</td></tr>
+<tr><td><code>readFile</code></td><td><code>(params: ReadFileParams) =&gt; Promise&lt;ReadFileResult&gt;</code></td><td>是</td><td>读取文件内容（异步）；返回 ReadFileResult，其中 data 按 encoding 为 UTF-8 或 Base64 字符串。</td></tr>
+<tr><td><code>readFileSync</code></td><td><code>(params: ReadFileParams) =&gt; ReadFileResult</code></td><td>是</td><td>读取文件内容（同步）；返回 ReadFileResult，其中 data 按 encoding 为 UTF-8 或 Base64 字符串。</td></tr>
+<tr><td><code>removeSavedFile</code></td><td><code>(params: RemoveSavedFileParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>删除通过 saveFile 保存的本地文件（异步）。</td></tr>
+<tr><td><code>rename</code></td><td><code>(params: RenameParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>重命名或移动文件（异步）。目标已存在同名文件时覆盖。</td></tr>
+<tr><td><code>renameSync</code></td><td><code>(params: RenameParams) =&gt; void</code></td><td>是</td><td>重命名或移动文件（同步）。目标已存在同名文件时覆盖。</td></tr>
+<tr><td><code>rmdir</code></td><td><code>(params: RmdirParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>删除目录（异步）。recursive 为 false 时仅能删除空目录，为 true 时递归删除全部内容。</td></tr>
+<tr><td><code>rmdirSync</code></td><td><code>(params: RmdirParams) =&gt; void</code></td><td>是</td><td>删除目录（同步）。recursive 为 false 时仅能删除空目录，为 true 时递归删除全部内容。</td></tr>
+<tr><td><code>saveFile</code></td><td><code>(params: SaveFileParams) =&gt; Promise&lt;SaveFileResult&gt;</code></td><td>是</td><td>将临时文件保存到本地持久化存储（异步）；返回 SaveFileResult，含实际保存路径。</td></tr>
+<tr><td><code>saveFileSync</code></td><td><code>(params: SaveFileParams) =&gt; SaveFileResult</code></td><td>是</td><td>将临时文件保存到本地持久化存储（同步）；返回 SaveFileResult，含实际保存路径。</td></tr>
+<tr><td><code>stat</code></td><td><code>(params: StatParams) =&gt; Promise&lt;StatResult&gt;</code></td><td>是</td><td>获取文件或目录状态（异步）；返回 StatResult，含字节大小、毫秒级修改时间和是否为目录。</td></tr>
+<tr><td><code>statSync</code></td><td><code>(params: StatParams) =&gt; StatResult</code></td><td>是</td><td>获取文件或目录状态（同步）；返回 StatResult，含字节大小、毫秒级修改时间和是否为目录。</td></tr>
+<tr><td><code>truncate</code></td><td><code>(params: TruncateParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>截断文件到指定长度（异步）。短于原长度时截断，长于原长度时以 \0 填充。</td></tr>
+<tr><td><code>truncateSync</code></td><td><code>(params: TruncateParams) =&gt; void</code></td><td>是</td><td>截断文件到指定长度（同步）。短于原长度时截断，长于原长度时以 \0 填充。</td></tr>
+<tr><td><code>unlink</code></td><td><code>(params: UnlinkParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>删除文件（异步）。只能删除文件，删除目录请使用 rmdir。</td></tr>
+<tr><td><code>unlinkSync</code></td><td><code>(params: UnlinkParams) =&gt; void</code></td><td>是</td><td>删除文件（同步）。只能删除文件，删除目录请使用 rmdir。</td></tr>
+<tr><td><code>unzip</code></td><td><code>(params: UnzipParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>解压 zip 文件到指定目录（异步）。目标目录须已存在。</td></tr>
+<tr><td><code>writeFile</code></td><td><code>(params: WriteFileParams) =&gt; Promise&lt;void&gt;</code></td><td>是</td><td>写入文件内容（异步）。文件和父目录不存在则创建，文件已存在则覆盖。</td></tr>
+<tr><td><code>writeFileSync</code></td><td><code>(params: WriteFileParams) =&gt; void</code></td><td>是</td><td>写入文件内容（同步）。文件和父目录不存在则创建，文件已存在则覆盖。</td></tr>
+</tbody>
+</table>
+
+## 错误处理
+
+同步调用失败时抛出错误。错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 203,
+  "errMsg": "file does not exist"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>203</code></td><td><code>file does not exist</code></td><td>Android、iOS</td><td>readFile、stat、getFileInfo、copyFile、rename、truncate、unlink、rmdir、removeSavedFile、unzip 等操作的目标文件或目录不存在</td><td>确认路径存在或先创建后重试。</td></tr>
+<tr><td><code>213</code></td><td><code>invalid file path</code></td><td>Android、iOS</td><td>传入的路径不是合法的沙箱内 appletfile 路径，或试图越过沙箱根目录访问</td><td>使用应用沙箱内的合法本地路径后重试。</td></tr>
+<tr><td><code>208</code></td><td><code>total size limit exceeded</code></td><td>Android、iOS</td><td>readFile、writeFile、appendFile、copyFile 时单次读写超过单文件大小上限，或写入后超出沙箱存储配额</td><td>减小单次读写数据量或清理已保存文件后重试。</td></tr>
+<tr><td><code>1901001</code></td><td><code>target is a directory</code></td><td>Android、iOS</td><td>对目录执行了仅适用于文件的操作（如 readFile、writeFile、appendFile、copyFile、truncate、getFileInfo、unzip 的源文件），或 rmdir 删除非空目录时未开启 recursive</td><td>改为对文件操作，或删除目录时开启 recursive。</td></tr>
+<tr><td><code>1901002</code></td><td><code>target is not a directory</code></td><td>Android、iOS</td><td>对文件执行了仅适用于目录的操作（如 readdir），或 mkdir 目标已存在同名文件、unzip 的 targetPath 不是目录</td><td>确认目标为目录后重试。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>当前环境不支持该能力</td><td>Android</td></tr>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>参数不合法</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 相关类型
+
+<a id="readfileparams"></a>
+### ReadFileParams
+
+FileSystemManager.readFile 的参数。
+
+#### Properties
+
+• **filePath**: `string` - 要读取的文件路径（本地路径）
+• **encoding?**: `'utf-8' | 'base64'` - 指定读取文件的字符编码。 - 'utf-8'：以 UTF-8 字符串形式返回文件内容。 - 'base64'：以 Base64 编码字符串形式返回文件内容，适用于二进制文件。 省略时以 Base64 编码字符串返回文件内容
+
+<a id="readfileresult"></a>
+### ReadFileResult
+
+FileSystemManager.readFile 的返回结果。
+
+#### Properties
+
+• **data**: `string` - 文件内容。 具体格式由 ReadFileParams.encoding 决定： - 编码为 'utf-8' 时返回 UTF-8 字符串； - 编码为 'base64' 时返回 Base64 编码后的字符串
+
+<a id="writefileparams"></a>
+### WriteFileParams
+
+FileSystemManager.writeFile 的参数。
+
+#### Properties
+
+• **filePath**: `string` - 要写入的文件路径（本地路径）
+• **data**: `string` - 要写入的内容。 - 当 encoding 为 'utf-8' 时，直接写入该字符串； - 当 encoding 为 'base64' 时，将该字符串先进行 Base64 解码再写入文件
+• **encoding?**: `'utf-8' | 'base64'` - 指定写入文件的字符编码
+
+<a id="appendfileparams"></a>
+### AppendFileParams
+
+FileSystemManager.appendFile 的参数。
+
+#### Properties
+
+• **filePath**: `string` - 要追加内容的文件路径（本地路径）
+• **data**: `string` - 要追加的内容。 - 当 encoding 为 'utf-8' 时，直接追加该字符串； - 当 encoding 为 'base64' 时，将该字符串先进行 Base64 解码再追加到文件末尾
+• **encoding?**: `'utf-8' | 'base64'` - 指定写入文件的字符编码
+
+<a id="accessparams"></a>
+### AccessParams
+
+FileSystemManager.access 的参数。
+
+#### Properties
+
+• **path**: `string` - 要判断是否存在的文件或目录路径
+
+<a id="mkdirparams"></a>
+### MkdirParams
+
+FileSystemManager.mkdir 的参数。
+
+#### Properties
+
+• **dirPath**: `string` - 要创建的目录路径
+• **recursive?**: `boolean` - 是否递归创建该目录的上级目录。 设为 true 时，即使中间路径不存在也会一并创建（类似 mkdir -p）
+
+<a id="rmdirparams"></a>
+### RmdirParams
+
+FileSystemManager.rmdir 的参数。
+
+#### Properties
+
+• **dirPath**: `string` - 要删除的目录路径
+• **recursive?**: `boolean` - 是否递归删除目录下的所有子文件和子目录。 设为 false 时，仅当目录为空才能删除成功；设为 true 时会递归删除所有内容
+
+<a id="readdirparams"></a>
+### ReaddirParams
+
+FileSystemManager.readdir 的参数。
+
+#### Properties
+
+• **dirPath**: `string` - 要读取的目录路径
+
+<a id="readdirresult"></a>
+### ReaddirResult
+
+FileSystemManager.readdir 的返回结果。
+
+#### Properties
+
+• **files**: `string[]` - 目录下的文件和子目录名称列表（不含 . 和 ..）
+
+<a id="unlinkparams"></a>
+### UnlinkParams
+
+FileSystemManager.unlink 的参数。
+
+#### Properties
+
+• **filePath**: `string` - 要删除的文件路径。 该接口只能删除文件，不能删除目录；删除目录应使用 FileSystemManager.rmdir
+
+<a id="statparams"></a>
+### StatParams
+
+FileSystemManager.stat 的参数。
+
+#### Properties
+
+• **path**: `string` - 要获取状态信息的文件或目录路径
+
+<a id="statresult"></a>
+### StatResult
+
+FileSystemManager.stat 的返回结果。
+
+#### Properties
+
+• **size**: `number` - 文件大小，单位为字节（Byte）
+• **lastModifiedTime**: `number` - 文件最近一次被修改的时间戳，单位为毫秒
+• **isDirectory**: `boolean` - 判断当前路径是否是一个目录
+
+<a id="copyfileparams"></a>
+### CopyFileParams
+
+FileSystemManager.copyFile 的参数。
+
+#### Properties
+
+• **srcPath**: `string` - 源文件路径（被复制的文件）
+• **destPath**: `string` - 目标文件路径（复制后生成的文件）
+
+<a id="renameparams"></a>
+### RenameParams
+
+FileSystemManager.rename 的参数。
+
+#### Properties
+
+• **oldPath**: `string` - 源文件路径（即当前文件路径）
+• **newPath**: `string` - 新文件路径（即重命名或移动后的目标路径）
+
+<a id="truncateparams"></a>
+### TruncateParams
+
+FileSystemManager.truncate 的参数。
+
+#### Properties
+
+• **filePath**: `string` - 要截断的文件路径
+• **length?**: `number` - 截断后的文件字节长度。 - 若 length 小于文件原始长度，文件将被截取到指定长度，多余部分丢弃。 - 若 length 大于文件原始长度，文件将被扩展到指定长度，扩展部分用 \0 填充
+
+<a id="getfileinfoparams"></a>
+### GetFileInfoParams
+
+FileSystemManager.getFileInfo 的参数。
+
+#### Properties
+
+• **filePath**: `string` - 要获取信息的文件路径
+• **digestAlgorithm?**: `'md5' | 'sha1'` - 用于计算文件摘要的哈希算法。 - 'md5'：使用 MD5 算法计算文件摘要。 - 'sha1'：使用 SHA-1 算法计算文件摘要。 不传时不计算摘要，返回结果中 GetFileInfoResult.digest 为 undefined
+
+<a id="getfileinforesult"></a>
+### GetFileInfoResult
+
+FileSystemManager.getFileInfo 的返回结果。
+
+#### Properties
+
+• **size**: `number` - 文件大小，单位为字节（Byte）
+• **digest?**: `string` - 按照 GetFileInfoParams.digestAlgorithm 计算得到的文件摘要（十六进制字符串）。 仅当请求时指定了 digestAlgorithm 才会返回
+
+<a id="savefileparams"></a>
+### SaveFileParams
+
+FileSystemManager.saveFile 的参数。
+
+#### Properties
+
+• **tempFilePath**: `string` - 临时文件路径（需先通过下载或其他方式获得的临时文件路径）
+• **filePath?**: `string` - 保存到的目标文件路径。 不指定时会在用户目录（appletfile://user/）下自动生成一个带时间戳前缀的路径， 实际保存路径通过 SaveFileResult.savedFilePath 返回
+
+<a id="savefileresult"></a>
+### SaveFileResult
+
+FileSystemManager.saveFile 的返回结果。
+
+#### Properties
+
+• **savedFilePath**: `string` - 文件保存后的实际存储路径
+
+<a id="getsavedfilelistresult"></a>
+### GetSavedFileListResult
+
+FileSystemManager.getSavedFileList 的返回结果。
+
+#### Properties
+
+• **fileList**: `Array<{
+    /** 文件的本地路径。 */
+    filePath: string;
+    /** 文件大小，单位为字节（Byte）。 */
+    size: number;
+    /** 文件保存时的时间戳，单位为毫秒。 */
+    createTime: number;
+  }>` - 已保存的本地文件列表，每项包含文件路径、大小和创建时间
+
+<a id="removesavedfileparams"></a>
+### RemoveSavedFileParams
+
+FileSystemManager.removeSavedFile 的参数。
+
+#### Properties
+
+• **filePath**: `string` - 需要删除的已保存文件路径（应为 SaveFileResult.savedFilePath 返回的路径）
+
+<a id="unzipparams"></a>
+### UnzipParams
+
+FileSystemManager.unzip 的参数。
+
+#### Properties
+
+• **zipFilePath**: `string` - 要解压的 zip 文件路径
+• **targetPath**: `string` - 解压后的目标目录路径。 目标目录须已存在，否则解压会失败
+
+<a id="filesystemmanager"></a>
+### FileSystemManager
+
+文件系统管理器，提供对本地文件系统的完整读写能力。 通过 getFileSystemManager 获取实例后，可使用该接口上的方法执行文件和目录操作。 大多数方法同时提供异步（返回 Promise）和同步（Sync 后缀）两种调用方式。
+
+#### Properties
+
+• **readFile**: `(params: ReadFileParams) => Promise<ReadFileResult>` - 读取文件内容（异步）；返回 ReadFileResult，其中 data 按 encoding 为 UTF-8 或 Base64 字符串
+• **readFileSync**: `(params: ReadFileParams) => ReadFileResult` - 读取文件内容（同步）；返回 ReadFileResult，其中 data 按 encoding 为 UTF-8 或 Base64 字符串
+• **writeFile**: `(params: WriteFileParams) => Promise<void>` - 写入文件内容（异步）。文件和父目录不存在则创建，文件已存在则覆盖
+• **writeFileSync**: `(params: WriteFileParams) => void` - 写入文件内容（同步）。文件和父目录不存在则创建，文件已存在则覆盖
+• **appendFile**: `(params: AppendFileParams) => Promise<void>` - 在文件末尾追加内容（异步）。文件不存在则创建，不会覆盖已有内容
+• **appendFileSync**: `(params: AppendFileParams) => void` - 在文件末尾追加内容（同步）。文件不存在则创建，不会覆盖已有内容
+• **access**: `(params: AccessParams) => Promise<void>` - 判断文件或目录是否存在（异步）。存在时 Promise 兑现，不存在时 Promise 拒绝
+• **accessSync**: `(params: AccessParams) => void` - 判断文件或目录是否存在（同步）。不存在时抛出异常
+• **mkdir**: `(params: MkdirParams) => Promise<void>` - 创建目录（异步）。recursive 为 true 时一并创建缺失的上级目录
+• **mkdirSync**: `(params: MkdirParams) => void` - 创建目录（同步）。recursive 为 true 时一并创建缺失的上级目录
+• **rmdir**: `(params: RmdirParams) => Promise<void>` - 删除目录（异步）。recursive 为 false 时仅能删除空目录，为 true 时递归删除全部内容
+• **rmdirSync**: `(params: RmdirParams) => void` - 删除目录（同步）。recursive 为 false 时仅能删除空目录，为 true 时递归删除全部内容
+• **readdir**: `(params: ReaddirParams) => Promise<ReaddirResult>` - 读取目录内容（异步）；返回 ReaddirResult，files 为目录下的文件与子目录名称（非完整路径，非递归）
+• **readdirSync**: `(params: ReaddirParams) => ReaddirResult` - 读取目录内容（同步）；返回 ReaddirResult，files 为目录下的文件与子目录名称（非完整路径，非递归）
+• **unlink**: `(params: UnlinkParams) => Promise<void>` - 删除文件（异步）。只能删除文件，删除目录请使用 rmdir
+• **unlinkSync**: `(params: UnlinkParams) => void` - 删除文件（同步）。只能删除文件，删除目录请使用 rmdir
+• **stat**: `(params: StatParams) => Promise<StatResult>` - 获取文件或目录状态（异步）；返回 StatResult，含字节大小、毫秒级修改时间和是否为目录
+• **statSync**: `(params: StatParams) => StatResult` - 获取文件或目录状态（同步）；返回 StatResult，含字节大小、毫秒级修改时间和是否为目录
+• **copyFile**: `(params: CopyFileParams) => Promise<void>` - 复制文件（异步）。仅支持文件，目标已存在同名文件时覆盖
+• **copyFileSync**: `(params: CopyFileParams) => void` - 复制文件（同步）。仅支持文件，目标已存在同名文件时覆盖
+• **rename**: `(params: RenameParams) => Promise<void>` - 重命名或移动文件（异步）。目标已存在同名文件时覆盖
+• **renameSync**: `(params: RenameParams) => void` - 重命名或移动文件（同步）。目标已存在同名文件时覆盖
+• **truncate**: `(params: TruncateParams) => Promise<void>` - 截断文件到指定长度（异步）。短于原长度时截断，长于原长度时以 \0 填充
+• **truncateSync**: `(params: TruncateParams) => void` - 截断文件到指定长度（同步）。短于原长度时截断，长于原长度时以 \0 填充
+• **getFileInfo**: `(params: GetFileInfoParams) => Promise<GetFileInfoResult>` - 获取文件信息（异步）；返回 GetFileInfoResult，含字节大小和可选的摘要
+• **saveFile**: `(params: SaveFileParams) => Promise<SaveFileResult>` - 将临时文件保存到本地持久化存储（异步）；返回 SaveFileResult，含实际保存路径
+• **saveFileSync**: `(params: SaveFileParams) => SaveFileResult` - 将临时文件保存到本地持久化存储（同步）；返回 SaveFileResult，含实际保存路径
+• **getSavedFileList**: `() => Promise<GetSavedFileListResult>` - 获取已保存的本地文件列表（异步）；返回 GetSavedFileListResult，每项含路径、字节大小和毫秒级保存时间
+• **removeSavedFile**: `(params: RemoveSavedFileParams) => Promise<void>` - 删除通过 saveFile 保存的本地文件（异步）
+• **unzip**: `(params: UnzipParams) => Promise<void>` - 解压 zip 文件到指定目录（异步）。目标目录须已存在

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/common-errors.md

@@ -0,0 +1,69 @@
+# 通用错误处理
+
+## 错误返回
+
+JS API 调用失败时，异步 API 会 reject、同步 API 会 throw 一个错误对象，其结构如下：
+
+```json
+{
+  "errNo": 1600004,
+  "errMsg": "key is empty"
+}
+```
+
+<table>
+<thead>
+<tr><th>字段</th><th>类型</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>errNo</code></td><td><code>number</code></td><td>错误码。建议优先使用该字段判断失败原因。</td></tr>
+<tr><td><code>errMsg</code></td><td><code>string</code></td><td>错误信息，用于辅助排查问题，不建议依赖文案进行逻辑判断。</td></tr>
+</tbody>
+</table>
+
+## 通用错误码
+
+以下错误码由多个 JS API 共用。每个 API 实际可能返回的错误码以对应 API 页面的错误码表为准。
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>100</code></td><td><code>unknown error</code></td><td>未知错误</td></tr>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td></tr>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>当前环境不支持该能力</td></tr>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>参数不合法</td></tr>
+<tr><td><code>105</code></td><td><code>authentication fail</code></td><td>身份认证失败</td></tr>
+<tr><td><code>106</code></td><td><code>system permission denied</code></td><td>系统权限未授予</td></tr>
+<tr><td><code>107</code></td><td><code>user permission denied</code></td><td>用户未授权</td></tr>
+<tr><td><code>110</code></td><td><code>API call prohibited</code></td><td>API 调用被禁止</td></tr>
+<tr><td><code>112</code></td><td><code>invalid result</code></td><td>返回结果无效</td></tr>
+<tr><td><code>113</code></td><td><code>bridge unavailable</code></td><td>JS API 暂不可用</td></tr>
+<tr><td><code>114</code></td><td><code>operation cancelled</code></td><td>操作已取消</td></tr>
+<tr><td><code>115</code></td><td><code>operation timeout</code></td><td>操作超时</td></tr>
+<tr><td><code>116</code></td><td><code>resource not found</code></td><td>资源不存在</td></tr>
+<tr><td><code>117</code></td><td><code>not implemented</code></td><td>能力尚未实现</td></tr>
+<tr><td><code>118</code></td><td><code>already exists</code></td><td>资源已存在</td></tr>
+<tr><td><code>120</code></td><td><code>too many requests</code></td><td>请求过于频繁</td></tr>
+</tbody>
+</table>
+
+## 处理示例
+
+```typescript
+try {
+  await someJsApi();
+} catch (error) {
+  const { errNo, errMsg } = error as { errNo?: number; errMsg?: string };
+
+  if (errNo === 115) {
+    console.warn('操作超时，请稍后重试');
+    return;
+  }
+
+  console.error(`调用失败：${errNo ?? 'unknown'} ${errMsg ?? ''}`);
+}
+```
+
+请使用 `errNo` 进行程序判断，并为未识别的错误码提供兜底处理。`errMsg` 适合展示或排查问题，不应作为稳定的判断条件。

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/groups.md

@@ -0,0 +1,43 @@
+# 豆包应用插件的端能力 API 分组目录（Open API）
+
+> 这里是豆包应用插件运行时 API 的分组目录，也称 Open API。先用 [速查索引](quick-reference.md) 找 API，再进入对应分组查看完整参数、返回值、示例和相关类型。
+
+## 分组
+
+| 分组 | 说明 | API 数量 | 详细文档 |
+| --- | --- | ---: | --- |
+| 基础 | 账号、授权、豆包客户端信息、窗口信息和能力可用性。 | 10 | [查看](./01-基础.md) |
+| 系统 | 豆包客户端信息、窗口信息和系统设置。 | 9 | [查看](./02-系统.md) |
+| 自定义通信 | 在应用插件的页面或卡片实例之间发送和接收自定义事件。 | 1 | [查看](./03-自定义通信.md) |
+| 定位 | 获取设备当前的地理位置信息。 | 5 | [查看](./04-定位.md) |
+| 存储 | 本地缓存；带 Sync 后缀的是同步 API。 | 10 | [查看](./05-存储.md) |
+| 路由 | 应用内页面跳转、返回、退出和关闭。 | 8 | [查看](./06-路由.md) |
+| 界面 | 对话框状态、Toast、Loading、Modal、ActionSheet、BottomSheet、返回前提醒、键盘和输入框能力。 | 3 | [查看](./07-界面.md) |
+| 交互 | Toast、Loading、Modal、ActionSheet、BottomSheet 和返回前提醒。 | 10 | [查看](./08-交互.md) |
+| 输入 | 键盘和输入框选区能力。 | 2 | [查看](./09-输入.md) |
+| 网络 | 网络请求与 WebSocket。 | 4 | [查看](./10-网络.md) |
+| 媒体 | 图片选择、预览、保存、压缩和信息读取；录音管理；背景音频和内部音频播放。 | 8 | [查看](./11-媒体.md) |
+| 业务能力 | 开放业务能力、卡片更新、模型上下文、任务和隐私设置。 | 7 | [查看](./12-业务能力.md) |
+| 登录 | 豆包一次性登录凭证、Widget 登录交互和 MCP 授权结果回传能力。 | 3 | [查看](./13-登录.md) |
+| 支付 | 订单创建、普通支付、平台免密支付、纯签约和支付并签约能力。 | 6 | [查看](./14-支付.md) |
+| 数据分析 | 监控上报、事件和数据分析上报。 | 1 | [查看](./15-数据分析.md) |
+| 蓝牙 | 蓝牙和 BLE 能力；通常先打开适配器，再扫描、连接和读写。 | 23 | [查看](./16-蓝牙.md) |
+| Wi-Fi | Wi-Fi 模块能力；通常先 startWifi，再获取列表或连接。 | 7 | [查看](./17-wi-fi.md) |
+| 加速度计 | 加速度计监听能力。 | 3 | [查看](./18-加速度计.md) |
+| iBeacon | iBeacon 搜索和结果读取能力。 | 3 | [查看](./19-ibeacon.md) |
+| 罗盘 | 罗盘监听能力。 | 3 | [查看](./20-罗盘.md) |
+| 设备方向 | 设备方向监听能力。 | 3 | [查看](./21-设备方向.md) |
+| 陀螺仪 | 陀螺仪监听能力。 | 3 | [查看](./22-陀螺仪.md) |
+| 媒体 / 设备 / 网络 | 网络类型和本机局域网 IP。 | 2 | [查看](./23-媒体-设备-网络.md) |
+| 短信 | 拉起系统短信发送面板。 | 1 | [查看](./24-短信.md) |
+| 无障碍 | 检测无障碍能力开关状态。 | 1 | [查看](./25-无障碍.md) |
+| 基础信息 | 设备品牌、型号、系统、内存和性能等级。 | 2 | [查看](./26-基础信息.md) |
+| 电池 | 电池信息读取与变化监听。 | 2 | [查看](./27-电池.md) |
+| 剪贴板 | 读取和设置系统剪贴板内容。 | 2 | [查看](./28-剪贴板.md) |
+| 加密 | 安全随机数能力。 | 1 | [查看](./29-加密.md) |
+| 日历 | 向系统日历添加事件和重复事件。 | 3 | [查看](./30-日历.md) |
+| 电话 | 拨打电话。 | 1 | [查看](./31-电话.md) |
+| 扫码 | 调起扫码并读取扫码结果。 | 1 | [查看](./32-扫码.md) |
+| 屏幕 | 屏幕亮度、常亮和截屏/录屏相关能力。 | 7 | [查看](./33-屏幕.md) |
+| 震动 | 触发短震动和长震动。 | 2 | [查看](./34-震动.md) |
+| 文件系统 | 文件读写、目录管理和文件信息操作。 | 1 | [查看](./35-文件系统.md) |