> ## Documentation Index
> Fetch the complete documentation index at: https://gugu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 维护、更新与撤回

> 发一个新版本，处理权限增长、撤回、停维和下架。

修改已发布 App 时，先增加 manifest 的 `version`，写本版 CHANGELOG，提交源码，再用 `add-version.mjs` 把新版本追加到同一份索引记录，并提 PR。每一版都走[提交校验与官方审阅](/apps/publishing)。

## 兼容与数据

开始使用新接口时同时核对 apiVersion 和 engines.gugu。市场选择这台机器能安装的最新兼容版本；不要仅为了消除提示修改版本声明而不改实现。

更新数据结构时，读取旧结构并执行必要迁移。清单或页面能加载不代表旧用户的数据已经适配。App 私有数据在升级时保留，卸载时清理；共享文件按文件自身的生命周期处理。

## 用户怎样收到更新

已安装的市场 App 默认自动更新到兼容新版。新增权限或网络去处的版本等待用户点更新，只确认新增项目；已撤销的授权不会自动恢复。用户关闭自动更新或自行停在旧版时，保持其选择。

测试新版要覆盖首次安装和从上一版升级，包括旧数据、已撤权限和程序配置。程序设置保存后，会等正在执行的调用完成，再让后续调用采用新值。

## 有问题的一版

在该版本行加 `yanked`：

```json theme={null}
"yanked": { "reason": "此版本保存数据有误，请更新到修复版。" }
```

撤回后这版不再可安装，版本号不能复用；已经装上的仍能运行，用户会看到原因和更新入口。撤回不是远程停止 App。

## 停止维护或下架

| 操作 | 索引修改 | 用户看到什么 |
| - | - | - |
| 停止维护 | deprecated 写 note 和 replacedBy（无替代时 null） | 停维提示和可选替代建议，不自动卸载或迁移 |
| 从市场下架 | unlisted 设为 true | 目录中消失；已装版本继续可用，不再提供市场更新 |

已经发布的版本行，除了添加撤回信息，不允许改字段或删除。撤回不能取消。下架也保留原索引文件和已发布版本资料。测试用 App 完成测试后应 unlisted，市场里正常列出的应是准备交给用户使用的 App。

当前没有自动将用户数据迁到替代 App 的机制，也没有公开承诺维护者停维后的接管流程。需要迁移时先在源码和说明中提供明确方法，并在 PR 中交代影响。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.