docs: align iCloud resilience PR documentation

background.js

@@ -4678,12 +4678,12 @@ async function fetchIcloudHideMyEmail(options = {}) {
     try {
       let generated = null;
       try {
-      generated = await icloudRequest('POST', `${activeServiceUrl}/v1/hme/generate`, {
-        timeoutMs: ICLOUD_REQUEST_TIMEOUT_MS,
-        maxAttempts: ICLOUD_WRITE_MAX_ATTEMPTS,
-        retryLabel: '生成 Hide My Email 地址',
-        logRetries: true,
-      });
+        generated = await icloudRequest('POST', `${activeServiceUrl}/v1/hme/generate`, {
+          timeoutMs: ICLOUD_REQUEST_TIMEOUT_MS,
+          maxAttempts: ICLOUD_WRITE_MAX_ATTEMPTS,
+          retryLabel: '生成 Hide My Email 地址',
+          logRetries: true,
+        });
       } catch (err) {
         if (!isIcloudRetryableError(err)) {
           throw err;

项目完整链路说明.md

@@ -170,6 +170,7 @@
 - Cloudflare / Temp Email 设置
 - 接码开关，以及 HeroSMS 的 API Key 与默认国家设置
 - iCloud 相关偏好：Host、获取策略、成功后自动删除、目标邮箱类型与转发收码邮箱 provider
+- iCloud Hide My Email 别名缓存：`icloudAliasCache` / `icloudAliasCacheAt`，用于在 iCloud 会话或网络上下文短暂波动时回退展示最近可用列表
 - LuckMail API 配置
 - 自动运行默认配置
 - 账号运行历史 `accountRunHistory`（以邮箱为主键，保存该邮箱最近一次状态：成功/失败/停止）
@@ -745,11 +746,22 @@ Plus 模式可见步骤：
 - `icloudTargetMailboxType = icloud-inbox` 时，Step 4 / Step 8 直接打开 iCloud Mail 收件箱轮询验证码。
 - `icloudTargetMailboxType = forward-mailbox` 时，注册邮箱仍由 iCloud Hide My Email 生成，但 Step 4 / Step 8 改为打开 `icloudForwardMailProvider` 指定的转发目标邮箱收码；当前支持 `qq / 163 / 163-vip / 126 / gmail`。
 
+Hide My Email 获取与管理链路：
+
+1. 后台优先通过 `setup.icloud.com*/setup/ws/1/validate` 解析 `premiummailsettings.url`，并记录最近可用服务节点。
+2. 如果后台请求受 401 / 403 / 409 / 421 / 429 / 5xx、CORS、超时或地址空间限制影响，会优先尝试在已打开或自动创建的 `www.icloud.com*/mail/` 页面主上下文中重放请求。
+3. `maildomainws` 请求会补充 `clientBuildNumber / clientMasteringNumber / clientId / dsid` 查询参数，写请求使用 `text/plain;charset=UTF-8`，以兼容 iCloud 网页端接口。
+4. 别名列表加载成功后会缓存到 `icloudAliasCache`；遇到短暂上下文波动时，列表展示会按“最近缓存 -> 历史缓存 -> 本地已用/保留记录”回退。
+5. 生成新别名后若 `reserve` 返回鉴权或网络异常，会先回查列表确认候选别名是否已经创建；必要时刷新服务节点重试一次，最后才进入可复用别名回退或暂停等待用户处理。
+6. 自动运行获取 iCloud 别名时，检测到会话或网络上下文异常后会停止重复消耗获取重试次数，转入等待邮箱状态，避免连续请求放大 iCloud 风控或上下文抖动。
+
 维护约定：
 
 - iCloud 转发目标邮箱 provider 的 label、URL、source、inject 配置统一由 `mail-provider-utils.js` 输出。
 - `background.js` 只根据 `icloudTargetMailboxType` 选择 iCloud Mail 收件箱或共享转发邮箱配置，不再在主文件内硬编码各 provider 地址。
 - `sidepanel/sidepanel.js` 只负责展示、保存和回显目标邮箱类型 / 转发邮箱 provider，不重复定义 provider 业务清单。
+- iCloud 登录态提示必须区分“真实未登录”和“已登录但请求上下文波动”；不能把所有 401 / 403 / 421 都直接提示为未登录。
+- iCloud 别名缓存只用于短暂失败回退，不应改变最终的已用 / 保留状态来源；状态仍以 `manualAliasUsage`、`preservedAliases` 与最新线上列表合并后的结果为准。
 
 ## 8. 自动运行完整链路
 

项目开发规范（AI协作）.md

@@ -142,6 +142,13 @@
 - 贡献模式的侧栏按钮、状态展示和轮询调度应优先收敛到独立 manager，例如 `sidepanel/contribution-mode.js`
 - 如果服务端当前返回“无需手动提交 callback”，扩展端必须把它当兼容成功态处理，不能简单按 HTTP 非 200 直接视为失败
 
+### 3.4.1 iCloud Hide My Email 维护补充
+
+- iCloud Hide My Email 的会话校验、页面上下文回退、别名缓存回退和 `maildomainws` 兼容参数属于同一条链路；修改其中任一环时，必须同步检查列表加载、别名生成、保留、删除、自动运行等待邮箱和 sidepanel 登录提示。
+- iCloud 登录态判断不能只看单个 HTTP 状态码。`401 / 403 / 421 / 429 / 5xx` 可能来自后台请求上下文、CORS 或服务节点波动，必须结合错误文案、页面上下文回退结果和用户提示文案判断。
+- iCloud 别名缓存只能作为短暂失败回退，不允许替代线上列表成为最终状态来源；已用和保留状态仍然以 `manualAliasUsage`、`preservedAliases` 与最新线上列表合并后的结果为准。
+- 如果新增 iCloud 相关回退路径，必须补覆盖登录提示、缓存回退、自动运行停止重试和 reserve 异常恢复的测试，并同步更新 [项目完整链路说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目完整链路说明.md)。
+
 ## 4. 测试规范
 
 ### 4.1 原则

项目文件结构说明.md

@@ -174,6 +174,7 @@
 - `tests/background-custom-email-pool.test.js`：测试后台对自定义邮箱池生成方式，以及自定义邮箱服务号池的归一化、标签文案和按轮次取邮箱逻辑。
 - `tests/background-generated-email-module.test.js`：测试生成邮箱辅助模块已接入且导出工厂，并覆盖 2925 receive 模式回退普通邮箱生成、自定义邮箱池按轮次取值、2925 provide 模式账号池预热，以及 iCloud `always_new` 传参。
 - `tests/background-icloud.test.js`：测试 iCloud 相关后台纯函数与别名收尾逻辑。
+- `tests/background-icloud-login-help.test.js`：测试 iCloud 登录判定、页面上下文回退、别名缓存回退和保留异常恢复的关键源码约束。
 - `tests/background-icloud-mail-provider.test.js`：测试 iCloud 邮箱 provider 配置解析，并覆盖转发收码模式复用共享 provider 配置。
 - `tests/background-logging-status-module.test.js`：测试日志 / 状态模块已接入且导出工厂。
 - `tests/background-luckmail.test.js`：测试 LuckMail 相关后台逻辑，如购买、复用、标记已用与重置。