用途与实际影响
这项功能怎样使用
为什么需要它
直接覆盖旧安装可能留下半套文件；卸载时一句“完成”也可能让人误以为所有模型、账号授权和个人配置都没了。安装先验候选，卸载明确保留范围。
举个实际例子
我可以说：“把 main 的最后修复装上；若遇到未知旧文件就先停。以后普通卸载保留我的 Profile 和密文，只有我明确彻底清理时才删本工具数据。”我会得到安装、保留内容和可回退位置的明确结果。
最后我会得到什么
拿到当前用户可用的 aicli 命令和已核对的安装版本；失败有旧版可回退。普通卸载保留配置和本机密钥，明确彻底清理才删本工具数据，远端账号授权还要到服务侧另办。
正常时
候选安装、切换和新命令窗口回读都通过后，说明本工具安装完成。
发现问题时
旧模块还在使用或上游变更时提示关闭旧窗口、更新对应部件或暂用旧版。
入口不可用或证据不足时
未知旧文件、候选不完整或安装目录被占时不做半套替换，保留原安装。
从哪里开始
在本机用项目安装器处理已核对的源码或 Release 包；卸载时明确普通保留还是彻底清理本工具数据。
需要准备什么
- 可信安装包或源码
- 现有 Profile 和密文是否要保留
- 已知旧版及回滚位置
从开始到拿到结果
- 1
先预检旧状态
检查已有安装与退役对象，未知用户文件先停下核对。
- 2
安装可回退候选
构建独立候选并切换，失败时恢复旧版。
- 3
新开终端验入口
重新打开命令窗口，检查版本、保存的配置档、静态体检和启动预览；普通卸载保留本工具数据，彻底清理与远端账号授权撤销分开办理。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
0.3.18 正式安装有 Owner 回读；新版桌面桥已见真实 GUI 进程路径，模型任务仍另验关键规则与设计选择
源码版本、发布包、当前用户模块和桌面内容寻址发行是不同对象；模块升级不会自动重建或切换正在工作的桌面发行。
旧 Qwen3.7 可验证对象移入 quarantine（可恢复隔离区），SecretRef 和 Key 不参与迁移。
普通卸载保留 Profile、DPAPI 密文和代理数据；--purge-user-data 才删除本工具数据，仍不代表远程 OAuth（账号授权协议） 撤销。
本模块用到的名词
- CurrentUser（当前用户范围）
- 模块只安装给当前 Windows 用户，不要求系统级管理员安装。
- quarantine（可恢复隔离区）
- 把身份已闭合的退役文件移出活动位置并保留前像，而不是直接删除。
- atomic switch（原子切换）
- 候选完整验证后用同父目录重命名替换，避免复制中途留下半套文件。
专业定义
模块、用户数据、上游 CLI（命令行工具） 与远程授权各有自己的生命周期。
解决什么
防止升级造成半套模块、退役误删用户配置，以及卸载把多个独立生命周期说成一个动作。
当前怎样实现
- Install.ps1 从当前 PSModulePath 选择 CurrentUser 模块根，在临时候选中导入验证，再对同一父目录执行原子重命名。
- Invoke-AiCliRetirementMigration.ps1 只移动 marker、路径、内容 hash（内容指纹） 与 state 都闭合的退役 Qwen3.7 对象，未知项在写前阻断。
- UpdateService 识别实际启动入口和安装渠道；只读检查与指引不静默升级上游。
- Uninstall.ps1 停止己方已验证代理并移除模块、shim（受保护入口垫片）、PATH 与受管 Profile 块；用户数据和上游产品默认保留。
- 《AI CLI（命令行工具） Profile Manager 使用手册》拥有产品安装、Profile、Doctor/Live、代理、更新、卸载与排障；《Codex、Claude Code 与 Open Interpreter CLI（命令行工具） 中文手册》拥有上游会话内模型、effort（思考等级）、权限、上下文、恢复和命令差异。
- 两本 PDF 是同版本 Markdown 的打印制品；只有源 hash（内容指纹）、文本抽取和逐页视觉复核闭合时才 current（当前状态），但它们仍不证明安装或 Live。
- 0.3.18 已由原安装器交付；DryRun/WhatIf（只读预演）在任何写入前返回，未知参数拒绝。Toolkit按已声明的诊断/控制能力使用入口，不因一般模块更新强迫升级桌面。桌面启用、停用和设置同步使用各自显式入口。
执行流程
- 1
从可信源码或已核对 Release 包启动安装。
- 2
只读预检退役对象和安装目录。
- 3
构建并导入临时候选。
- 4
原子移动旧版与候选，失败则恢复。
- 5
新开 PowerShell 并回读 aicli version/list/show/doctor/native/eject。
- 6
退出时选择普通卸载或显式 purge，并另外处理远程授权。
边界
- 本轮不创建新的 GitHub Release。
- 不静默升级 Codex、Claude、Ollama、Open Interpreter 或代理。
- 文档与 PDF 是用户入口，不是当前安装、运行或 Live 的替代证据。
失败与恢复
- 同版本已经安装但未给 -Force
- 默认拒绝覆盖，避免意外替换正在使用的版本。
- 退役对象无法证明归属
- 安装在任何迁移前阻断，保留原件供人工审阅。
- 安装后当前 shell 仍加载旧模块
- 关闭重开 PowerShell，或 Remove-Module 后强制 Import-Module，再核对路径和版本。
真实入口
E:\Projects\Tools\ai-cli-profile-manager\scripts\Install.ps1候选验证与原子安装
E:\Projects\Tools\ai-cli-profile-manager\scripts\Invoke-AiCliRetirementMigration.ps1旧入口预检、可恢复移动与回滚
E:\Projects\Tools\ai-cli-profile-manager\scripts\Uninstall.ps1模块、shim（受保护入口垫片）、PATH 与数据边界
E:\Projects\Tools\ai-cli-profile-manager\docs\user\AI CLI Profile Manager 使用手册.md安装、Profile、验证、代理、更新、卸载与排障事实源
E:\Projects\Tools\ai-cli-profile-manager\docs\user\Codex、Claude Code 与 Open Interpreter CLI 中文手册.md原生 CLI（命令行工具） 会话内命令与差异
E:\Projects\Tools\ai-cli-profile-manager\docs\compatibility\VERIFIED-COMPATIBILITY.md每条 Profile 的当前证据边界
如何验证
- 0.3.18 正式发行时完整 Pester 555/555、发行 smoke 与隔离安装/同版替换通过；旧32项退役、385项全量和 Junction（目录联接） 修复保留原日期。
- 2026-09-24T04:59Z 零写入 diagnose 回读本机 0.3.18 与桌面 562b29bf4a6ac0af 启用；真实主 GUI 的 Bridge 路径同版，本网页未执行安装或切换。
- 安装、进程加载、Profile 配置与真实模型结果分别证明；9月14日73/73和9月3日损坏Profile拒绝不冒充新版 E2E（端到端验证）。
与其他模块的关系
这是产品进入和退出本机的生命周期；配置档与秘密模块拥有用户数据，验证模块负责安装后的真实功能回读。