diff --git a/README.md b/README.md index 4fa7f6c..e68e722 100644 --- a/README.md +++ b/README.md @@ -1,258 +1,83 @@ # EnvScope -面向 Windows 和 macOS 的极简桌面环境工具。以 [claude-switcher](https://github.com/YOURSJEYO/claude-switcher) 为功能底座,保留原版维护能力,增加独立检测、事务式账号管理、代理诊断和历史对比。 +**Claude 环境检测、修复与持续守护。** -当前源码 **0.25.0 Alpha** 按“地区与时区 → 一键检测 → 问题和修复 → 持久化守护”运行。侧栏直接进入检测、守护和账号,其余检查、工具和历史集中在“更多功能”;切换页面保留位置,筛选保留展开说明。地区预设覆盖 **247 个国家和地区、417 个城市/时区**。参见 [操作流程](docs/SIMPLE_WORKFLOW.md) 和 [完整功能对照](docs/FULL_PARITY_AUDIT.md)。公开安装包以 Releases 为准。 +面向 Windows 和 macOS 的开源桌面工具。确认地区与时区后,一键检查连接和配置,直接查看问题、修复办法与复检结果;需要长期保持时,再启用后台守护。 -**0.25.0 新增**按失败项目引导系统授权,返回后复检原选择;明确区分权限拒绝、组织策略、超时和本版未支持。Windows 增加受保护的系统时区守护,与 macOS 一样先审核授权、每 60 秒检查、失败留痕并可恢复。异常通知去重,重开软件后仍可查看未解决事项。应用、托盘和导航采用统一原创图标。项目按纯开源方式发布,商业签名和 Apple 公证可选;包身份与完整性校验不等于发布者签名。参见 [权限验收](docs/PERMISSION_ACCEPTANCE.md) 和 [开源构建说明](docs/OPEN_SOURCE_BUILDS.md)。 +[下载](https://github.com/qudadd/envscope/releases/tag/v0.25.0-alpha.1) · [使用说明](docs/USER_GUIDE.md) · [文档目录](docs/README.md) · [反馈问题](https://github.com/qudadd/envscope/issues) -**0.23.0 已加入**可恢复的旧软件清理、临时浏览器独立清理进程与重启恢复,以及 48 小时不同出口集合统计。清理支持单项 / 全选,先预览、再确认,保留账号与凭据。参见 [旧软件清理](docs/LEGACY_SOFTWARE.md) 和 [临时浏览器](docs/BROWSER_SESSIONS.md)。 +## 下载与启动 -**0.20.0 已加入**旧后台任务的可逆迁移:单项选择或全选、预览访问与配置影响、保存原定义后停用、自动复检,以及恢复原任务。新守护会监测旧任务重新出现,发现冲突时暂停自身操作并留痕。一键流程按新检测结果分阶段生成方案。参见 [旧后台任务迁移](docs/legacy-components.md)。公开安装包以 Releases 为准。 +当前版本:**0.25.0 Alpha**。独立软件包自带运行环境,日常使用无需安装 Python 或输入命令。 -**0.19.0 已加入** Windows WireGuard 专项模式:选择具体隧道,分别核对服务、所属进程、程序摘要、对应网卡与实际目标选路;原生守护固定同一服务基线。服务停止、读取权限拒绝及其他 VPN 选路分别显示原因和处理步骤。参见 [WireGuard 检测与守护](docs/WIREGUARD.md)。 - -**0.18.0 已加入**原生客户端启动 / 重开、Clash Verge TUN 持久化修复,以及 macOS Claude 专用语言设置与恢复。先正常退出 Claude,审核所选程序与改动;备份、读回、失败恢复和中断恢复都有入口。一键流程先修复客户端并自动复检,再使用实际测到的网卡预览后续守护,减少手动选择。参见 [客户端与应用语言修复](docs/CLIENT_REPAIR.md)。 - -**0.17.0 已加入** Windows / macOS 原生网络修复:按已确认目标勾选或全选 IPv6 接口、预览影响、申请本次系统授权、独立读回、失败回滚和中断恢复;DNS 缓存刷新单独说明不可撤销。接入一键流程与“全部检查”的所选修复,完成后自动复检并刷新接口。参见 [网络设置与恢复](docs/SYSTEM_NETWORK.md)。 - -**0.16.0 已加入** macOS 原生系统时区守护:审核一次后申请系统授权,每 60 秒检查批准时区;接入“保持本次设置”、地区修改、失败回滚和跨重启撤销。辅助程序和基线由 root 持有,后台不会弹出授权框。参见 [系统时区守护](docs/TIMEZONE_SERVICE.md)。 - -**0.15.0 已加入** macOS 原生加密 DMG 兼容:账号页直接选择原版 A–D 备份、只读挂载、文件回读校验与未完成暂存清理;无需安装旧维护核心。Windows / macOS 仍使用 .envsnap 进行跨平台认证加密备份。参见 [加密备份的格式与恢复范围](docs/DMG_ARCHIVES.md)。 - -**0.14.0 已加入** Clash Verge 原生路由修复:预览 16 条规则、保留用户脚本、备份与重载、实际运行验证、失败回滚和重启后恢复;接入逐项修复与持续维护。参见 [原生路由配置](docs/ROUTING.md)。 - -**0.13.0 已加入**原生 10 秒进程守护;先审核再启用,监测失败时停止已识别的当前用户 Claude 桌面并留痕。完整功能升级仍在进行,参见 [完整核对表](docs/FULL_PARITY_AUDIT.md) 和 [进程守护](docs/PROCESS_GUARD.md)。 - -账号按独立本地数据卷完整封存和载入,保留目录内已有身份与会话;新增正常退出、APFS 写时复制、内容读回及中断恢复入口。恢复前审核,所有现场副本保留。真实客户端认证、钥匙串及服务端设备判断的边界见 [账号数据卷](docs/ACCOUNT_VOLUMES.md)。 - -**0.12.0 已加入**:读取出口 IP 后只显示相应国家的城市,并匹配目标时区、语言与地区格式。Watchdog 可周期检查批准基线、恢复漂移、重开所选离线代理客户端并读回复检;权限不足或不能自动处理时标红。完整事件按日保存,账号切换保留独立资料、限制跨账号文件混合。仍支持全选、单项检测与批量修复。实际所在地与出口分开核对,CN / RU 官方地区条件不合格不能通过配置修改消除。[IP 联动、守护与账号隔离](docs/WATCHDOG_AND_IDENTITIES.md) · [功能与验收范围](docs/ENVIRONMENT_COVERAGE.md)。 - -首页贯通检测、配置与修复、复检、打开 Claude 和长期保持。桌面打开与正常重开都先重新检测,核对安装、配置、账号恢复及目标连接;未通过时保留资料并说明原因。Code 可主动完善本机连接与证书校验设置。[交付范围与验收依据](docs/PRODUCT_ACCEPTANCE.md)。 - -连接诊断与完整隐私验证分别报告:API 未认证探测返回 401 不会被当成密钥失效;本版未实现权威 DNS 出口、目标进程全流量关联和防火墙断网保护,不会因为网页有响应就声称零泄漏。 - -Scrapling 仅用于开发前期抓取和核对方案、项目与文档,不属于产品、运行依赖或检测引擎。 - -![EnvScope 桌面界面,离线演示](docs/images/desktop.png) - -界面采用黑白配色和单页主流程;问题、处理入口与复检结果直接展示。截图来自离线模拟环境,未运行真实网络检测。设计约定见 [桌面界面](docs/UI_DESIGN.md)。 - -## 一键检测 - -Windows 桌面包解压后双击 `EnvScope.exe`。macOS 桌面包的入口为 `EnvScope.app`。程序打开独立窗口,不需要另外启动浏览器或 Python: - -[下载 Windows / macOS 桌面包](https://github.com/qudadd/envscope/releases)。macOS 分 Apple Silicon 与 Intel,按处理器选择。Alpha 包未获商业代码签名 / Apple 公证。 - -1. 确认实际使用地区、节点地区和城市。出口 IP 可建议节点地区与时区;不会代填实际所在地。需要时展开用途与连接选项。 -2. 点“确认并一键检测”。首页列出不合格项目、缺少的必需证据和下一步;展开对应问题查看原因与手动步骤。 -3. 核对修复方案,点“确认修复并复检”。写入前保存恢复记录;代理连接未验证时不会写入。需要先启动客户端时,完成并复检后再审核后续改动。 -4. 在“持续守护”勾选需保持的配置,预览并确认启用;同页可停用。系统守护与高级修复按需展开;选择检查 / 全选和备份从“更多功能”进入,账号资料可从侧栏直接进入。 - -复检区分已消除、仍存在和仍缺少证据的问题。“详细记录与使用帮助”保留打开 / 正常重开 Claude、实际试用指引和技术证据。Code 配置修改后需要重开会话;实际账号使用仍须在自己的 Claude 中确认。 - -配置完善优先测试 Code 已有的本机 HTTP 代理,再测试已发现的候选;明确指定地址时不试用其他连接。自定义接口、Bedrock / Vertex / Foundry 和未明确更换的远程代理保留其原路径。只改用户配置文件;项目与组织设置可能覆盖它,实际会话仍需重开确认。完全相同的设置不会仅为排版而重写。复检单列配置文件凭据,不把写入成功或账号手动确认当作隐私通过。 - -“看懂 14 项检查”和完整技术记录按需展开,不要求先理解术语。工具页明确区分随附的 claude-switcher、Mihomo 本机接口,以及可选外部客户端 Clash Verge Rev 的作用;读取与审核后的修改分开,不会自动安装代理或提供节点。见 [新用户使用说明](docs/USER_GUIDE.md)。 - -检测不需要终端或手动导入。桌面包自带 Python 运行时;Windows 使用系统 WebView2,macOS 使用 WKWebView。关闭窗口后默认驻留托盘/菜单栏,从相应菜单可以重新打开或退出。在“设置 → 软件与后台”关闭驻留后,关闭窗口即退出。首次安装维护核心与系统修复可能请求管理员授权;普通读取被拒绝时,只为对应项目提供权限处理入口。 - -软件默认每日向 GitHub 查询版本,不下载或执行更新。用户确认后,从 `qudadd/envscope` 下载对应架构软件包,同时核对发布校验表与 GitHub SHA256,安装到用户目录中的新版本文件夹,保留旧文件。重启由用户确认;已保存的前一版本可回退。参考开源项目的更新只提示差异,经兼容测试后随 EnvScope 发布,不直接替换正在运行的核心。系统定时巡检独立于窗口驻留;其现有任务继续使用已批准的程序路径,可在维护页重新预览启用来迁移。 - -Windows 独立程序已在本机构建并通过隔离的真实窗口、托盘和退出测试。Windows、macOS 两种架构由发布 CI 构建并测试,结果以本标签的 Actions 为准;真实账号登录、平台授权弹窗与 Safari 外部浏览器仍需实际设备验收。手机端暂不适配。 - -## 功能范围 - -| 功能 | Windows | macOS | +| 系统 | 下载 | 启动方式 | |---|---|---| -| 原版 14 类检查与独立测量证据 | 原生实现 | 原生实现 | -| 19 项扩展检查、问题归因、处理步骤与复检比较 | 原生实现 | 原生实现 | -| JSON 多余逗号修复、Code 代理 / 绕过项与恢复 TLS 校验 | 预览后确认执行,备份及撤销 | 预览后确认执行,备份及撤销 | -| 所选接口 IPv6、DNS 缓存刷新、事务记录与恢复 | 原生 UAC 事务;不执行可改写脚本 | 原生 SystemConfiguration 辅助程序;保留手动地址 | -| 所选客户端启动 / 正常重开、TUN 偏好备份 / 验证 / 恢复 | Clash Verge、Mihomo Party、Clash Nyanpasu;持久化 TUN 支持 Clash Verge | 另外识别 Shadowrocket、ClashX、Surge;持久化 TUN 支持 Clash Verge,其他客户端在其界面设置 | -| Claude 专用语言、缺省 / ByHost 原值和中断恢复 | 标红并提供手动确认步骤 | 原生当前用户应用偏好;不改全局语言,实际界面另行确认 | -| 配置编辑器、系统设置和官方服务入口 | 固定目标 | 固定目标 | -| 14 项逐项检测 / 解决 / 保持清单及固定版本来源 | 原生实现 | 原生实现 | -| 用户可启停的 5 / 15 / 60 分钟原生巡检、事件与 48 小时出口变化 | 用户计划任务 | 用户 LaunchAgent | -| 批准的 Code 配置漂移恢复、私有备份、次数上限、跨重启撤销 | 原生实现 | 原生实现 | -| 已批准的系统时区守护、基线联动、更新 / 撤销 / 中断恢复 | 用户权限任务,权限不足转手动 | 原生 root 服务,前台单次申请系统授权 | -| 系统 HTTP / IPv4 / IPv6、UDP STUN、浏览器 HTTP / ICE 自动合并 | 支持 | 支持 | -| 动态账号槽位、命名、首次归档、切换前重检、复制校验与失败回滚 | 原生实现 | 原生实现 | -| 首页复检后打开桌面版、确认正常退出再复检重开 | 原生实现,同账号操作锁 | 原生实现,同账号操作锁 | -| 安装、修复、守护任务、路由迁移及维护核心更新 | 适配原版核心 | 适配原版核心 | -| 城市目标、系统时区与地区格式配置、读回与撤销 | 原生实现 | 原生实现,联动已授权时区守护 | -| 切换原版代理客户端 | 原版未提供相应命令 | 适配原版核心 | -| .envsnap 加密存档、临时浏览器 | 原生实现 | 原生实现 | -| 原版加密 DMG 导入 / 导出 | 原版未提供 | 原生格式兼容 | -| 非活动槽位的未加密目录备份 / 空槽位导入 | 原生实现 | 原生实现 | -| 代理自动发现、指定代理连接诊断、耗时与响应分类 | 原生实现 | 原生实现 | -| 最近 50 次脱敏历史、状态差异与出口集合变化提示 | 原生实现 | 原生实现 | -| CLI 安装信息、设备信息、浏览器 Canvas / WebGL 信息 | Windows 只读安装位置和硬件 / 字体信息 | 原版详细 CLI / 设备信息;原生浏览器信息 | -| 脱敏诊断包、允许网段、目标偏好与偏好恢复 | 原生实现 | 原生实现 | - -14 类包括代理客户端、TUN、出口国家、出口变化、时区、地区格式、IPv6、DNS 配置、UDP / WebRTC、守护任务、代理规则、客户端语言、ASN 和服务连接。取得配置信息与验证实际流量是不同范围,详细证据单独展示。 - -19 项扩展检查包括: - -| 分组 | 具体检查 | -|---|---| -| 域名与路径 | 两个目标的系统域名解析、按地址族查询系统选路、hosts 覆盖 | -| 代理 | 当前用户系统代理与环境变量差异、绕过名单、本机已配置端口的 TCP 监听、内核 TUN 配置、控制接口监听范围 | -| 连接质量 | TLS 证书校验、DNS / TCP / TLS / 首字节 / 总耗时、多个 HTTPS 日期与系统时间的偏差、10 个固定外围端点的 HTTPS 回应 | -| 客户端 | 常见位置 / 已注册桌面安装、资料目录、客户端 / CLI JSON 与 MCP 数量 | -| CLI 与资料 | PATH 候选入口冲突、认证和接口环境配置、资料磁盘空间、账号标记和未完成事务 | - -不执行 PAC/WPAD 脚本,不扫描端口,不执行 PATH 中发现的 CLI,不读取 Cookie 或登录数据库。配置检查仅提取白名单元数据,不执行 MCP 命令,不导出密钥和 MCP 参数;经确认的配置修复会在本机读取及备份完整原文。TCP 端口接受连接不等于代理协议正常;系统选路不等于进程数据包证明;HTTP 日期比较不替代可信 NTP。 - -## 一站式处理 +| Windows · x64 | [Windows ZIP](https://github.com/qudadd/envscope/releases/download/v0.25.0-alpha.1/EnvScope-Windows-x64.zip) | 完整解压,打开 `EnvScope.exe` | +| macOS · Apple 芯片 | [Apple Silicon ZIP](https://github.com/qudadd/envscope/releases/download/v0.25.0-alpha.1/EnvScope-macOS-arm64.zip) | 解压,打开 `EnvScope.app` | +| macOS · Intel | [Intel ZIP](https://github.com/qudadd/envscope/releases/download/v0.25.0-alpha.1/EnvScope-macOS-x64.zip) | 解压,打开 `EnvScope.app` | -区分代理解析、目标解析、TCP、TLS / CA、代理认证 407、服务拒绝 403、限流 429、服务端错误、分段耗时、配置语法、Code SOCKS 不兼容、认证 / 云提供方冲突、账号事务和磁盘空间。TUN 未启用、语言地区差异和缺少可选文件不会被一概当成故障。具体来源和验收规则见 [从检测到处理](docs/DIAGNOSIS.md)。 +[本版更新与校验文件](https://github.com/qudadd/envscope/releases/tag/v0.25.0-alpha.1) · [所有版本](https://github.com/qudadd/envscope/releases) · [从源码运行](docs/DEVELOPMENT.md) -自动处理覆盖确定的 JSON 多余逗号、先测试成功的本机 HTTP(S) 代理写入 Code、匹配目标的绕过项、Code TLS 校验,以及已确认的地区 / 路由 / IPv6 接口与 DNS 缓存操作。修改前列出范围并保留恢复记录;缓存内容不能撤销。未知语法、认证方式和企业 CA 提供具体入口和步骤。部分代理客户端修复仍使用明确安装的兼容核心;安装器打开后仍需继续复检。 +当前 Windows 包未进行发布者签名;macOS 包使用 ad-hoc 签名,尚未进行 Developer ID 签名或 Apple 公证。首次打开可能被系统拦截。下载校验与签名是不同的验证,详见 [开源构建与更新](docs/OPEN_SOURCE_BUILDS.md)、[正式签名准备](docs/SIGNING.md)。 -只修改固定的桌面配置和 `~/.claude/settings.json`,保留其他键、MCP 和凭据。原文备份及恢复记录保存在 `~/.envscope/config-backups`,**未加密、可能含密钥,不可分享**。权限保护也取决于用户目录 ACL。逐文件原子替换;多文件或维护步骤可能部分完成,会明确报告并保留备份。撤销支持跨重启哈希校验;文件后来又被修改时拒绝覆盖,需要按备份手动合并。 +## 四步使用 -方案绑定当前本机报告且有有效期;历史 / 导入报告不能授权修复。复检没有取得证据时显示“无法核实”,不计为已解决。服务端权限、额度、组织认证和服务故障提供对应官方入口,不能通过本机改配置保证解决。 +1. **确认目标**:填写实际使用地区,读取出口 IP 建议节点国家与城市,匹配时区和地区格式。实际所在地与代理出口分别记录。 +2. **一键检测**:查看哪些条件合格、哪里有问题、哪些检查还缺少证据。也可进入“更多功能 → 全部检查”,选择项目或全选。 +3. **修复并复检**:审核具体改动后执行,完成后自动复检。需要授权的项目说明用途;不能自动处理的项目提供手动步骤,支持的配置修改保留撤销入口。 +4. **按需持续守护**:选择需要保持的配置,预览并确认启用。后台按批准的基线巡检、尝试恢复并记录结果,反复失败会暂停并提醒。 -原版完整源码锁定在 `870c4ca`,57 个文件逐一校验并随产品分发。工具页使用固定操作适配原版的独立安装;未安装、平台不支持或版本缺少命令时会明确禁用。安装器打开只代表安装流程已开始,不能作为安装完成的证据。原版输出不会变成 EnvScope 的独立检测通过结果。详见 [逐项功能对照](docs/FEATURE_PARITY.md)。 +首次打开有使用教学,之后可随时重看。关闭窗口默认驻留托盘或菜单栏;驻留不会自动开启守护。[完整操作说明 →](docs/USER_GUIDE.md) -## 持续维护 +
+查看桌面界面(离线模拟数据) -“持续维护”页先预览再启用用户计划任务 / LaunchAgent,默认只读巡检。可选保持已批准的 Code 五个字段、时区和地区格式,以及已验证本机代理的节点与客户端。至少间隔 5 分钟、每项 24 小时最多尝试 3 次,反复漂移会暂停。后台不提权、不安装程序、不停止 Claude、不切换账号、不回退直连;macOS 时区权限不足转手动,特权守护仍需另行安装原版。完整事件按日追加,停用后保留。 +![EnvScope 检测与修复界面,展示问题、权限提示和处理方案](docs/images/desktop.png) -可立即复检、查看最近报告、事件、48 小时出口变化和停用。退出页面不停止已启用的任务;停止按钮先关闭恢复标记,再移除自己的任务。注册、等待执行、完成、超期、失败与恢复受阻分别显示。Windows 与两种架构的 macOS 包增加真实 OS 调度验收:注册、两次自动执行冻结 worker、移除;结果见对应标签的 Actions。该验收不联网、不修改用户配置,不能代替权限、重新登录、休眠恢复或真实账号验收。详见 [逐项检测与长期保持](docs/CLAUDE_CHECKS.md)。 +截图展示界面流程,不代表真实 Claude 登录或网络检测结果。 -## 账号与维护 +
-“账号”页支持 A-D 及自定义槽位。切换前重新运行原生检测,拒绝过期、缺失或失败的必需证据;确认应用退出后,先创建并校验暂存副本,再提交交换。异常时尝试回滚;发现未完成事务会保留副本、阻止继续写入。断电后的自动恢复尚未实现。首次切换会将原有资料归入 A。 +## 可以做什么 -账号沿用 `~/.claude-switcher` 存档,实时资料位于 Windows `%APPDATA%/Claude` 或 macOS `~/Library/Application Support/Claude`。不要同时用原版和 EnvScope 交换账号。`keep-in-workspace.txt` 默认关闭,0.12 起仅允许显式选择的 `skills/` 文件;身份、Cookie、会话与设置禁止跨账号混合,旧清单有此类路径时停止切换并提示调整。切换事件记录在 `~/.claude-switcher/account-events`,不记录凭据内容。 - -账号页优先使用 **.envsnap 加密备份**:Scrypt 派生密钥、AES-256-GCM 认证加密、逐文件 SHA-256 清单;错误密码、损坏、路径异常或非空槽位均拒绝导入。密码至少 12 字符,不保存、不进入进程参数;临时明文放在受限目录,完成后清理,不声称安全擦除。存档上限 8 GiB。高级目录备份仍未加密,不可分享。macOS 原版 DMG 入口保留。复制资料不保证服务端会话、系统凭据库或跨系统登录迁移。 - -“工具”页列出维护操作的实际影响。安装 / 修复可能改写代理规则、IPv6、时区、地区格式和后台任务。完整卸载并不等于恢复历史网络设置。原版更新只更新已安装的维护核心;EnvScope 本体使用“设置 → 软件与后台”的校验更新。当前 Alpha 使用发布摘要校验,尚无商业代码签名 / Apple 公证。 - -## 从源码启动 - -源码运行需要 Python 3.10+,先在源码目录执行 `python -m pip install '.[desktop]'`,再在 Windows 双击 `start-windows.cmd`,或在 macOS 运行 `start-macos.command`。日常用户直接下载自带运行时的桌面包即可。Windows 10/11 和 macOS 自带的 curl 用于原生 HTTP 检测。 - -以下命令用于开发或进阶诊断,日常桌面使用无需执行。 - -## CLI +| 你要解决的问题 | EnvScope 提供的能力 | 详细说明 | +|---|---|---| +| 不知道 Claude 为什么连不上 | 代理与 TUN、域名解析、系统选路、TLS、响应状态和耗时,以及桌面版 / Code 配置检查 | [检测与处理](docs/DIAGNOSIS.md) | +| 不知道哪些结果可信 | 分开展示 HTTP、IPv4 / IPv6、原生 UDP 与浏览器观测;每项保留来源、范围和失败原因 | [检查范围](docs/ENVIRONMENT_COVERAGE.md) | +| 配置有问题却不知道怎么改 | 预览 Code 配置、地区时区、Clash Verge 路由、所选 IPv6 接口及客户端修复;确认后执行、读回与复检 | [修复流程](docs/SIMPLE_WORKFLOW.md) | +| 信息读不到,反复出现未知 | 区分权限拒绝、组织策略、超时、缺少工具和本版未支持;适用时引导授权,返回后复检原选择 | [权限与验证边界](docs/PERMISSION_ACCEPTANCE.md) | +| 配好后又漂移,代理掉线 | 周期巡检、批准配置恢复、所选代理客户端重开、Windows / macOS 时区守护及事件记录 | [Watchdog](docs/WATCHDOG_AND_IDENTITIES.md) · [时区守护](docs/TIMEZONE_SERVICE.md) | +| 多个账号的本地资料混在一起 | 独立资料槽位、切换前复检、封存与载入校验、中断恢复入口、加密备份 | [账号资料](docs/ACCOUNT_VOLUMES.md) | +| 想知道变化发生在什么时候 | 脱敏检测历史、修复与守护事件、48 小时出口集合变化、诊断包导出 | [日志与证据](docs/CLI.md) | +| 需要迁移旧工具或更新软件 | 旧后台任务与软件的可恢复迁移、更新包校验、保留前一版本用于回退 | [旧组件迁移](docs/legacy-components.md) · [软件更新](docs/OPEN_SOURCE_BUILDS.md) | -需要 Python 3.10+;在线 CLI 检测还需要系统 `curl`。浏览器页面无第三方 JavaScript/CSS 依赖。 +另提供临时浏览器、Windows WireGuard 专项检查、macOS 加密 DMG 兼容和单独启用的进程守护。平台差异、原生实现与兼容入口见 [完整功能对照](docs/FULL_PARITY_AUDIT.md)。 -下载本仓库源码后,在源码目录中运行: +## 怎样理解“环境合格” -```powershell -cd envscope -python -m envscope --help +合格表示**本次所选范围内,所需证据已取得且符合已确认目标**。未测、超时、不支持和证据过期都会单独显示,不计为通过。 -# 默认仅采集本机只读信息,不向公共服务发探测请求 -python -m envscope audit --html reports/audit.html +- 本机配置正确、服务有响应,不等于账号能登录或有可用额度;实际回复仍需在自己的 Claude 中确认。 +- 系统授权只能解决相应的权限问题。本版尚无权威 DNS 出口、完整进程流量关联和防火墙断网保护;进程守护不等于零泄漏保证。 +- 地区预设不等于 Claude 支持地区。修改时区、语言或节点不改变实际所在地,也不保证账号安全或服务端设备判断。 +- 诊断只读;修复、账号切换和守护分别审核。配置原文备份可能含凭据,请勿上传;分享诊断包前也应复核。 -# HTTP + 原生 UDP STUN + IPv6;公共端点会看到探测来源地址 -python -m envscope audit --online --stun --ipv6 --html reports/audit.html +权限、平台与真实设备的验证范围见 [验收记录](docs/DESKTOP_ACCEPTANCE.md);数据处理边界见 [SECURITY.md](SECURITY.md)。 -# 当前浏览器的真实观测;在浏览器打开输出的 loopback 地址 -python -m envscope serve -``` +## 与 claude-switcher 的关系 -命令行可 `python -m pip install .` 后使用 `envscope`。源码运行独立窗口请安装 `python -m pip install '.[desktop]'`;浏览器兼容入口是 `python -m envscope desktop --browser`。Windows 和 macOS 的系统适配器读取各自的网卡、路由和 DNS 配置;配置存在不能证明流量已接管。 +EnvScope 以 [claude-switcher](https://github.com/YOURSJEYO/claude-switcher) 为功能参考并随附固定版本源码,在此基础上提供独立桌面交互、检测证据、事务式修复与账号管理。上游原生功能、EnvScope 重实现和需手动处理的项目分别列在 [功能对照表](docs/FULL_PARITY_AUDIT.md),不将随附源码等同于全部功能已自动可用。 -退出码仍按选定验证范围:`0` 范围内通过,`1` 明确策略或目标不符,`2` 证据不完整或需要复核,`3` 输入/本地资源错误。连接诊断显示“服务有响应”时,完整隐私范围仍可能返回 `2`;这是覆盖不足,不等于服务不可用。默认离线运行返回 `2`,不是程序崩溃。 +可配合已有 Mihomo / Clash Verge Rev 等客户端使用,不提供账号、代理节点或订阅。Scrapling 只用于开发研究资料采集,不是运行依赖或检测引擎。 -## 检测规则的升级 +## 文档与参与 -| 观测 | EnvScope 的解释 | +| 使用软件 | 了解实现 | |---|---| -| STUN 超时、IPv6 无响应 | 未知,不能推导“零暴露”或“已关闭 IPv6” | -| 原生 UDP 有响应 | 只说明原生 UDP 路径;与浏览器 ICE 分开 | -| HTTP 200 但 IP 响应结构无效 | 未知;验证码页面不会成为有效 IP 证据 | -| HTTP 401 / 403 / 429 / 5xx | 分别标注认证、访问拒绝、限流、服务异常 | -| UDP/ICE 与 HTTP 出口不同 | 无明确允许地址时提示复核,不直接宣称“真实 IP 泄漏” | -| 观测地址超出用户明确配置的允许 CIDR | 策略违反;不推断地址所有者或物理位置 | -| 只有 mDNS、私网或 TURN relay 候选 | 没有可比较公网候选,保留未知 | -| TUN 网卡存在、代理进程存活、Fake-IP、DoH 可达 | 配置或行为线索,不能替代实际路径验证 | -| 中文语言、时区、ASN 机构名 | 不用于推断账号安全、住宅属性或封禁概率 | -| 上游 `checkdetail` 报告中的 `ok` | 导入为“未独立重测”,不继承通过结论 | - -默认 `privacy` 范围要求 IPv4、IPv6、UDP、浏览器和权威 DNS 证据。若只检查 HTTP 传输,可明确选择 `--profile transport`;此时 `0` 也只表示所选范围内通过,其他未知项仍展示。 - -## 配置允许地址 - -创建不会提交到 Git 的 `policy.private.json`。下面地址是文档示例,请替换成自己**明确知道应当使用的**出口网段;不要直接把待测结果自动学习成可信范围。 - -```json -{ - "allowed_ipv4": ["203.0.113.10/32"], - "allowed_ipv6": ["2001:db8:1234::/48"] -} -``` - -```powershell -python -m envscope audit --online --stun --ipv6 --policy policy.private.json -``` - -允许列表区分 IPv4/IPv6,可配置多个合法出口。没有列表时,仅报告同一场景内的一致性或差异。CIDR 命中证明符合这份策略,不证明运营商、国家或“住宅 IP”属性。 - -## 指定代理和目标 - -```powershell -python -m envscope audit --online --proxy http://127.0.0.1:7890 -# 含凭据时,从自己设置的环境变量读取,避免写进命令历史 -python -m envscope audit --online --proxy-env ENVSCOPE_PROXY_URL -python -m envscope audit --online --target https://example.com/ -# 可选:密钥从 ENVSCOPE_CONTROLLER_SECRET 读取,只访问 loopback GET /configs -python -m envscope audit --online --controller http://127.0.0.1:9090 -``` - -显式代理失败不会回退为另一条路径重试。HTTP 代理设置不会自动控制原生 STUN;跨路径差异必须结合实际 TUN/UDP 策略解释。没有 `--proxy` 时,curl 使用环境代理和系统路由,**不等于 Windows 浏览器的 WinINET 代理设置**。 - -curl 不载入用户 `.curlrc`,不执行远端脚本,不跟随 HTTP 重定向。控制接口不经过环境代理、不跟随重定向,不导出返回配置中的密钥。 - -## 系统与浏览器观测 - -一键检测在当前浏览器收集 HTTP 与 ICE 观测,然后自动传给本机 loopback 进程,合并系统检测结果。不会传给 EnvScope 外部服务器,不需要用户交换文件。浏览器与系统各自使用对应路径的 HTTP 对照。 - -高级 CLI 仍接受 `--browser <原始观测文件>`,重新评估地址和 ICE 类型。过期、未来、脱敏或未完成的观测不能通过。用户提供的观测未签名,不用于可信远程审计。 - -浏览器不申请麦克风/摄像头权限,不保证覆盖浏览器可使用的全部接口。网页不能强制双栈域名走某一地址族;IPv6 使用专用端点,结果保持独立。 - -## 报告、导入与变化比较 - -```powershell -python -m envscope import-switcher <已保存的last-check.txt> -python -m envscope report reports/audit.json --html reports/audit.html -python -m envscope diff reports/before.json reports/after.json -``` - -默认导出对地址使用本报告内别名,保留证据关系,隐藏常见用户目录名,删除 URL 凭据、查询参数和已识别的密钥字段。时区、语言、软件信息等仍可能识别环境,分享前需要自行复核。`diff` 只比较检查状态,不用不同报告的地址别名推断 IP 变化。 - -桌面偏好、对比密钥与最近 50 次脱敏历史保存在 `~/.envscope`。原始检测地址只在本次进程内存中评估;历史用本机随机密钥的 HMAC 比较实际观测的出口集合,密钥丢失后不跨密钥声称出口变化。历史页面不能用旧报告授权启动,切换仍会重新检测。出口变化本身不等于泄漏或账号风险。 - -`--include-sensitive` 可在本地保留原始地址。`reports/`、`artifacts/`、`.env`、`*.private.json` 均被 Git 忽略。静态 HTML 报告不加载外部资源、不包含可执行脚本。浏览器分享版与 CLI 诊断报告是两种有明确 `kind`/`tool` 的格式,不混用。 - -## 开发与验证 - -```powershell -python -m unittest discover -s tests -v -node --test tests/browser.test.mjs -node --check envscope/web/app.mjs -node --check envscope/web/controls.mjs -node --check envscope/web/diagnosis.mjs -# 可选开发依赖,运行离线页面交互与截图检查 -python -m pip install playwright -python -m playwright install chromium -python -m scripts.browser_smoke -python -m pip wheel . --no-deps --wheel-dir dist -python -m scripts.verify_package dist -``` - -回归测试只使用合成数据及 loopback 假服务,不断开真实网络、不使用真实账号、不发送实际 UDP 到外部 STUN 端点。规则 CI 在 Windows/Linux/macOS 运行;产品适配范围为 Windows/macOS。自动化通过不等于真实账号、维护权限和浏览器场景均已验收。运行记录见 [Actions](https://github.com/qudadd/envscope/actions)。 - -桌面包构建:安装开发依赖 `pyinstaller>=6.10,<7`,在目标 Windows/macOS 系统运行 `python -m scripts.build_desktop`。也可在 GitHub Actions 手动运行 `desktop packages`。桌面产物目前未签名,首次启动体验需要纳入平台验收。 +| [新用户指南](docs/USER_GUIDE.md) · [选择检查与批量处理](docs/SELECTIVE_CHECKS.md) | [架构](docs/ARCHITECTURE.md) · [开发与验证](docs/DEVELOPMENT.md) | +| [账号资料与恢复](docs/ACCOUNT_VOLUMES.md) · [系统时区守护](docs/TIMEZONE_SERVICE.md) | [命令行](docs/CLI.md) · [开源构建](docs/OPEN_SOURCE_BUILDS.md) | +| [本版更新](docs/releases/0.25.0-alpha.1.md) · [全部文档](docs/README.md) | [正式签名准备](docs/SIGNING.md) · [第三方来源](THIRD_PARTY_NOTICES.md) | -macOS 打包要求 cryptography 静态链接 OpenSSL,构建脚本会检查。Intel 从源码构建加密库时,先安装 Rust、OpenSSL 开发库,按[官方说明](https://cryptography.io/en/latest/installation/#building-cryptography-on-macos)使用 `OPENSSL_STATIC=1` 并禁用旧 wheel 缓存;CI 已配置此步骤,避免与 Python 自带的 OpenSSL 冲突。最终用户不需要这些构建工具。 +欢迎通过 [Issue](https://github.com/qudadd/envscope/issues) 提交可复现问题,通过 Pull Request 改进代码或文档。请附系统、版本、复现步骤和脱敏结果,不要上传账号资料、密钥或真实代理凭据。 -阅读 [逐项功能对照](docs/FEATURE_PARITY.md)、[验证记录](docs/VALIDATION.md)、[源码审查与方案取舍](docs/RESEARCH.md)、[检测架构](docs/ARCHITECTURE.md)、[实施路线](docs/ROADMAP.md)、[安全边界](SECURITY.md) 和 [第三方来源](THIRD_PARTY_NOTICES.md)。 +[MIT License](LICENSE)。EnvScope 是独立开源项目,与 Anthropic / Claude 无官方隶属关系。第三方组件保留各自许可,见 [来源与许可](THIRD_PARTY_NOTICES.md)。 diff --git a/SECURITY.md b/SECURITY.md index ec5a4a7..81941ee 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -3,7 +3,7 @@ ## Reviewed configuration remedies Diagnostics do not change system or client settings. A separate reviewed plan -requires explicit boolean confirmation. Native edits target only the fixed +requires explicit boolean confirmation. JSON remedies target the fixed desktop JSON and Code user-settings JSON. Deterministic trailing commas are removed outside strings; ambiguous syntax, duplicate keys and nonstandard numbers are not guessed. Code proxy edits require a successful anonymous API @@ -41,18 +41,33 @@ stale, failed and completed heartbeats are distinct states. The worker may perform disclosed public probes and optionally restore five approved Code env keys. It preserves unrelated current settings and never runs -upstream installers/repairs, switches accounts, stops Claude or changes OS -networking/locale. Restoration verifies the credential-free loopback proxy, +upstream installers/repairs, switches accounts or stops Claude. Code restoration +verifies the credential-free loopback proxy, makes private backups, refuses malformed/deleted configs and concurrent edits, and pauses after three recoveries in 24 hours or changed/unverifiable settings. Browser ICE and login are not measured in this context. Shell, project and organization settings are outside the user-file restoration scope. +Separately selected Watchdog baselines can restore approved timezone / locale +settings, the chosen local controller selection and an approved proxy client's +availability. They use bounded retries, readback and event records. The user +worker never opens elevation dialogs. A separately reviewed, protected Windows +SYSTEM task or macOS root service can maintain the approved timezone every 60 +seconds after foreground OS authorization. Unknown, stale or conflicting service +state is not protection. See [timezone service](docs/TIMEZONE_SERVICE.md). + +The optional process guard is a separate approval: it may stop identified Claude +processes and interrupt unsaved work. It is polling, not firewall enforcement. + Closing the UI does not stop an approved task. Disable saves the worker's off flag before attempting to remove its owned schedule. Failure to remove the OS entry does not re-enable repairs. Records remain under `~/.envscope/maintenance`; raw config backups remain private. Do not move the executable while scheduled. -Tests use fake schedulers; real OS lifecycle acceptance is still pending. +Tests include fake schedulers and isolated real OS lifecycle acceptance. The +published version's evidence and pending human authorization / sleep / restart +cases are listed in [permission acceptance](docs/PERMISSION_ACCEPTANCE.md). +Disabling user maintenance does not remove a separately approved timezone service; +that service has its own reviewed removal and recovery flow. ## Measurement limits @@ -118,15 +133,22 @@ and is not signed attestation. Native account copying uses verified staging, per-state OS locks and rollback. Symlinks/reparse points, traversal, overlaps and pending transactions are refused. -Failures preserve copies; power-loss recovery is manual. A separate legacy +Failures preserve copies; incomplete transactions block further exchanges and +offer a reviewed recovery flow. This is not silent recovery or proof of all +physical power-loss scenarios. A separate legacy account manager does not honor this lock: do not run both concurrently. Local snapshot copies do not include every OS credential-store item or guarantee server-session continuity. Native directory export is **unencrypted**. Optional -retention deliberately copies listed paths across identities; do not list cookies -or credentials unless that sharing is intended. - -macOS encrypted DMGs use the original password-stdin path; passwords never enter -argv or returned plans. Original installers/repair scripts retain their own +retention is restricted to explicitly selected skills files; identity, cookies, +credentials and settings cannot be shared through that list. Older out-of-scope +lists block switching rather than silently copying sensitive files. + +Native encrypted `.envsnap` archives use Scrypt and AES-256-GCM; CSNAP001 and macOS +DMG compatibility have separate format and platform limits. Export targets an +inactive slot and import requires an empty slot. Passwords are not stored or put +in process arguments; temporary plaintext is access-restricted and removed, not +claimed to be securely erased. Local copies cannot guarantee cross-device login. +Original installers/repair scripts retain their own privilege, backup and rollback behavior. Their bundled hashes verify provenance, not native-device acceptance. Installers can register background services and the macOS original updater. Original output is marked unverified by EnvScope. @@ -142,7 +164,13 @@ Use GitHub's private vulnerability reporting when enabled. Do not publish proxy credentials, browser profiles, account snapshots, access tokens or real network addresses in an issue. Include a minimal synthetic reproduction and version. -Supported development line: current `main`. EnvScope has no whole-product updater. +Supported development line: current `main`. EnvScope checks GitHub for updates by +default; downloading, installing and restarting require confirmation. Updates +validate the repository, architecture, hashes, archive paths and application +identity, install alongside the current version and preserve a prior version for +rollback. These checks do not establish a trusted publisher signature: current +Windows builds are unsigned and macOS builds use ad-hoc signing without +notarization. See [build identity](docs/OPEN_SOURCE_BUILDS.md). Explicit original-core installation/update is separate and can install the -upstream macOS scheduled updater. Windows/macOS native action acceptance, -administrator cancellation and real-session round trips remain release gates. +upstream macOS scheduled updater. Human administrator prompts and real-session +round trips remain outside automated fixture evidence. diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 0000000..307fd45 --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,98 @@ +# 命令行与检测证据 + +[文档目录](README.md) · [桌面入门](USER_GUIDE.md) + +## CLI + +需要 Python 3.10+;在线 CLI 检测还需要系统 `curl`。浏览器页面无第三方 JavaScript/CSS 依赖。 + +下载本仓库源码后,在源码目录中运行: + +```powershell +cd envscope +python -m envscope --help + +# 默认仅采集本机只读信息,不向公共服务发探测请求 +python -m envscope audit --html reports/audit.html + +# HTTP + 原生 UDP STUN + IPv6;公共端点会看到探测来源地址 +python -m envscope audit --online --stun --ipv6 --html reports/audit.html + +# 当前浏览器的真实观测;在浏览器打开输出的 loopback 地址 +python -m envscope serve +``` + +命令行可 `python -m pip install .` 后使用 `envscope`。源码运行独立窗口请安装 `python -m pip install '.[desktop]'`;浏览器兼容入口是 `python -m envscope desktop --browser`。Windows 和 macOS 的系统适配器读取各自的网卡、路由和 DNS 配置;配置存在不能证明流量已接管。 + +退出码仍按选定验证范围:`0` 范围内通过,`1` 明确策略或目标不符,`2` 证据不完整或需要复核,`3` 输入/本地资源错误。连接诊断显示“服务有响应”时,完整隐私范围仍可能返回 `2`;这是覆盖不足,不等于服务不可用。默认离线运行返回 `2`,不是程序崩溃。 + +## 检测规则的升级 + +| 观测 | EnvScope 的解释 | +|---|---| +| STUN 超时、IPv6 无响应 | 未知,不能推导“零暴露”或“已关闭 IPv6” | +| 原生 UDP 有响应 | 只说明原生 UDP 路径;与浏览器 ICE 分开 | +| HTTP 200 但 IP 响应结构无效 | 未知;验证码页面不会成为有效 IP 证据 | +| HTTP 401 / 403 / 429 / 5xx | 分别标注认证、访问拒绝、限流、服务异常 | +| UDP/ICE 与 HTTP 出口不同 | 无明确允许地址时提示复核,不直接宣称“真实 IP 泄漏” | +| 观测地址超出用户明确配置的允许 CIDR | 策略违反;不推断地址所有者或物理位置 | +| 只有 mDNS、私网或 TURN relay 候选 | 没有可比较公网候选,保留未知 | +| TUN 网卡存在、代理进程存活、Fake-IP、DoH 可达 | 配置或行为线索,不能替代实际路径验证 | +| 中文语言、时区、ASN 机构名 | 不用于推断账号安全、住宅属性或封禁概率 | +| 上游 `checkdetail` 报告中的 `ok` | 导入为“未独立重测”,不继承通过结论 | + +默认 `privacy` 范围要求 IPv4、IPv6、UDP、浏览器和权威 DNS 证据。若只检查 HTTP 传输,可明确选择 `--profile transport`;此时 `0` 也只表示所选范围内通过,其他未知项仍展示。 + +## 配置允许地址 + +创建不会提交到 Git 的 `policy.private.json`。下面地址是文档示例,请替换成自己**明确知道应当使用的**出口网段;不要直接把待测结果自动学习成可信范围。 + +```json +{ + "allowed_ipv4": ["203.0.113.10/32"], + "allowed_ipv6": ["2001:db8:1234::/48"] +} +``` + +```powershell +python -m envscope audit --online --stun --ipv6 --policy policy.private.json +``` + +允许列表区分 IPv4/IPv6,可配置多个合法出口。没有列表时,仅报告同一场景内的一致性或差异。CIDR 命中证明符合这份策略,不证明运营商、国家或“住宅 IP”属性。 + +## 指定代理和目标 + +```powershell +python -m envscope audit --online --proxy http://127.0.0.1:7890 +# 含凭据时,从自己设置的环境变量读取,避免写进命令历史 +python -m envscope audit --online --proxy-env ENVSCOPE_PROXY_URL +python -m envscope audit --online --target https://example.com/ +# 可选:密钥从 ENVSCOPE_CONTROLLER_SECRET 读取,只访问 loopback GET /configs +python -m envscope audit --online --controller http://127.0.0.1:9090 +``` + +显式代理失败不会回退为另一条路径重试。HTTP 代理设置不会自动控制原生 STUN;跨路径差异必须结合实际 TUN/UDP 策略解释。没有 `--proxy` 时,curl 使用环境代理和系统路由,**不等于 Windows 浏览器的 WinINET 代理设置**。 + +curl 不载入用户 `.curlrc`,不执行远端脚本,不跟随 HTTP 重定向。控制接口不经过环境代理、不跟随重定向,不导出返回配置中的密钥。 + +## 系统与浏览器观测 + +一键检测在当前浏览器收集 HTTP 与 ICE 观测,然后自动传给本机 loopback 进程,合并系统检测结果。不会传给 EnvScope 外部服务器,不需要用户交换文件。浏览器与系统各自使用对应路径的 HTTP 对照。 + +高级 CLI 仍接受 `--browser <原始观测文件>`,重新评估地址和 ICE 类型。过期、未来、脱敏或未完成的观测不能通过。用户提供的观测未签名,不用于可信远程审计。 + +浏览器不申请麦克风/摄像头权限,不保证覆盖浏览器可使用的全部接口。网页不能强制双栈域名走某一地址族;IPv6 使用专用端点,结果保持独立。 + +## 报告、导入与变化比较 + +```powershell +python -m envscope import-switcher <已保存的last-check.txt> +python -m envscope report reports/audit.json --html reports/audit.html +python -m envscope diff reports/before.json reports/after.json +``` + +默认导出对地址使用本报告内别名,保留证据关系,隐藏常见用户目录名,删除 URL 凭据、查询参数和已识别的密钥字段。时区、语言、软件信息等仍可能识别环境,分享前需要自行复核。`diff` 只比较检查状态,不用不同报告的地址别名推断 IP 变化。 + +桌面偏好、对比密钥与最近 50 次脱敏历史保存在 `~/.envscope`。原始检测地址只在本次进程内存中评估;历史用本机随机密钥的 HMAC 比较实际观测的出口集合,密钥丢失后不跨密钥声称出口变化。历史页面不能用旧报告授权启动,切换仍会重新检测。出口变化本身不等于泄漏或账号风险。 + +`--include-sensitive` 可在本地保留原始地址。`reports/`、`artifacts/`、`.env`、`*.private.json` 均被 Git 忽略。静态 HTML 报告不加载外部资源、不包含可执行脚本。浏览器分享版与 CLI 诊断报告是两种有明确 `kind`/`tool` 的格式,不混用。 diff --git a/docs/DESKTOP_ACCEPTANCE.md b/docs/DESKTOP_ACCEPTANCE.md index 5107d1c..37309d1 100644 --- a/docs/DESKTOP_ACCEPTANCE.md +++ b/docs/DESKTOP_ACCEPTANCE.md @@ -2,11 +2,11 @@ ## 0.25 权限与桌面刷新 -- Python 回归 720 项,5 项按平台跳过;JavaScript 19 项及全部模块语法检查通过。 +- 发布源提交的本地 Python 回归运行 726 项(5 项按平台跳过),其余通过;JavaScript 19 项及全部模块语法检查通过。 - Windows/macOS 离线场景各覆盖 1024、1280、1440 宽度的 8 个页面,检查键盘菜单、滚动位置、筛选展开状态、单次检测提交和无横向溢出。 - 首次教学与 IP 读取、原生设置刷新与保存、修复中的复检按钮均加入竞争时序回归;仅只读 IP 查询可在服务短暂忙碌时有限重试。 - 浏览器回归覆盖权限返回、原选择复检、取消、仍拒绝、目标变更,以及修复预览、过期、部分失败、恢复与守护。Windows 冻结包核对应用图标、版本资源和更新后的原生启动。 -- 专用 CI 使用隔离时钟完成 Windows SYSTEM / macOS root 时区服务生命周期与两轮自动巡检,不改测试机器真实时区。最终标签的构建结果为分发依据。 +- 专用 CI 使用隔离时钟完成 Windows SYSTEM / macOS root 时区服务生命周期与两轮自动巡检,不改测试机器真实时区。0.25.0 Alpha 源提交 `e7cd61d0e8f1884441a1845c5a72f429102ae300` 的 [检查 CI](https://github.com/qudadd/envscope/actions/runs/41045089026) 与 [三架构桌面 CI](https://github.com/qudadd/envscope/actions/runs/41045082167) 已通过。 - 实际人工 UAC/TCC 允许、拒绝、撤权、重启及休眠仍需专用设备验收,未用上述夹具代替。参见 [权限证据表](PERMISSION_ACCEPTANCE.md)。 产品流程:首次教学 → 一键检测 → 问题与权限分类 → 合并修复方案 → 确认写入 → diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..0a499b7 --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,79 @@ +# 开发与验证 + +[项目首页](../README.md) · [文档目录](README.md) · [命令行与检测证据](CLI.md) + +产品面向 Windows 和 macOS。Linux CI 用于规则与页面回归,不代表提供 Linux 桌面版。开发前阅读仓库根目录的 [AGENTS.md](../AGENTS.md) 与 [安全边界](../SECURITY.md)。 + +## 从源码运行 + +需要 Python 3.10+。系统 `curl` 用于在线 HTTP 检测;Windows 桌面窗口使用 WebView2,macOS 使用 WKWebView。下载仓库源码后,在仓库目录运行: + +```sh +python -m pip install '.[desktop]' +python -m envscope desktop +``` + +也可双击 Windows 的 `start-windows.cmd`,或在 macOS 运行 `start-macos.command`。浏览器兼容入口为 `python -m envscope desktop --browser`;只需命令行时安装 `python -m pip install .` 即可。更多参数见 [CLI](CLI.md)。 + +日常用户应直接使用自带运行环境的 [桌面包](https://github.com/qudadd/envscope/releases/tag/v0.25.0-alpha.1),无需安装开发工具。 + +## 本地检查 + +在仓库根目录执行: + +```sh +python -m unittest discover -s tests -v +node --test tests/browser.test.mjs tests/permission_flow.test.mjs +node --check envscope/web/app.mjs +node --check envscope/web/permission_flow.mjs +node --check envscope/web/workspace_ui.mjs +python -m scripts.check_release +python -m pip wheel . --no-deps --wheel-dir dist +python -m scripts.verify_package dist +``` + +修改其他 JavaScript 模块时也要检查相应文件语法。完整 CI 检查列表见 [checks.yml](../.github/workflows/checks.yml),不要只以这里列出的几个模块替代全部发布检查。 + +页面交互和视觉验收使用 Playwright: + +```sh +python -m pip install playwright +python -m playwright install chromium +python -m scripts.browser_smoke +python -m scripts.simple_workflow_smoke +python -m scripts.permission_flow_smoke +python -m scripts.desktop_refresh_smoke +``` + +按改动范围补跑对应脚本;完整发布矩阵以工作流为准。测试只使用合成资料、临时目录和 loopback 服务,不修改开发者真实时区、代理、账号或后台任务,不使用真实 Claude 凭据。 + +## 桌面构建 + +在对应 Windows / macOS 主机安装构建依赖后运行: + +```sh +python -m pip install '.[desktop]' 'pyinstaller>=6.10,<7' +python -m scripts.build_desktop +``` + +也可运行 GitHub Actions 的 [desktop packages](../.github/workflows/desktop.yml)。构建包括 Windows x64、macOS ARM64 与 Intel;以各自架构的实际构建和验收结果为准。 + +macOS 加密依赖需静态链接 OpenSSL,构建脚本会检查;Intel 的 Rust、OpenSSL 与源码构建设置见工作流。最终用户不需要这些构建工具。当前 Windows 包未签名,macOS 使用 ad-hoc 签名。身份与摘要的意义见 [开源构建](OPEN_SOURCE_BUILDS.md),正式发布者签名的准备工作见 [SIGNING.md](SIGNING.md)。 + +## 改动与发布要求 + +- 修复必须保持“预览影响 → 用户确认 → 写入 → 读回 / 复检”的流程;缺少证据、取消授权和部分失败不能转成通过。 +- 上游随附文件是固定摘要的来源资料,保留原字节和许可证;不要执行其测试、安装器或脚本来替代本项目回归。 +- 不提交真实报告、账号卷、凭据、浏览器资料或研究抓取原文。配置原文备份可能含密钥,也不得作为测试夹具。 +- 提交 Pull Request 时写清问题、结果、适用平台与已运行的验证;区分模拟测试、真实 OS 夹具和人工设备验收。 +- 发布检查包括 Python / JavaScript、页面与视觉、包构建与内容、三架构桌面和更新流程。正式签名启用后还需加入实际签名与公证验证。 + +## 当前版本证据 + +0.25.0 Alpha 的测试源提交为 `e7cd61d0e8f1884441a1845c5a72f429102ae300`: + +- [规则、页面与包内容 CI](https://github.com/qudadd/envscope/actions/runs/41045089026) +- [三架构桌面与原生隔离验收 CI](https://github.com/qudadd/envscope/actions/runs/41045082167) +- [桌面验收范围](DESKTOP_ACCEPTANCE.md) · [权限验收范围](PERMISSION_ACCEPTANCE.md) + +这些结果不证明真实 Claude 登录、服务端设备识别、所有第三方 VPN 驱动或人工 UAC / TCC 场景已经通过。后续提交应引用自己的测试记录。 diff --git a/docs/ENVIRONMENT_COVERAGE.md b/docs/ENVIRONMENT_COVERAGE.md index 7a5f6a6..124e602 100644 --- a/docs/ENVIRONMENT_COVERAGE.md +++ b/docs/ENVIRONMENT_COVERAGE.md @@ -1,14 +1,14 @@ # 环境全览与功能范围 -0.13 开发分支新增 [原生进程守护](PROCESS_GUARD.md),完整升级状态以 -[全功能核对表](FULL_PARITY_AUDIT.md) 为准。下面保留原有检测、存档和浏览器的范围。 +[新用户指南](USER_GUIDE.md) · [完整功能对照](FULL_PARITY_AUDIT.md) · [文档目录](README.md) -0.11 新增 [可选检查与地区配置](SELECTIVE_CHECKS.md);0.19 增加 Windows WireGuard -专项后,当前 56 个目录入口支持全选、单项与批量操作;其中包含派生目标检查, -不代表 56 次独立测量。原生时区、当前用户地区格式 -修改和现有兼容节点切换,均需预览、确认、读回与复检。系统授权可能取消或被组织策略拒绝; -遇到不可自动处理项标红并给出步骤。真实系统写入在本轮测试中使用模拟适配器验证, -没有据此宣称已在真实用户系统执行成功。 +0.25.0 的检查目录共 **57 项**,包含 14 类基础、19 项扩展,以及目标条件、设备资料和 +补充测量。目录数量不是独立实验数量,也不代表每种用途都需要完成全部项目。 +[可选检查](SELECTIVE_CHECKS.md) 支持单项、全选与批量处理;每项区分本次结果、来源和限制。 + +原生时区、地区格式、兼容节点及网络设置的修改,均需预览、确认、读回与复检。 +系统授权可能取消或被组织策略拒绝;无法自动处理时给出步骤。模拟适配器、真实 OS +隔离夹具与用户设备观察分别记录,详见 [权限验收](PERMISSION_ACCEPTANCE.md)。 目标是逐项说明测了什么、发现什么问题、如何处理,以及所选使用条件是否合格。 “环境画像”指可追溯的本机资料和观测,不是 Claude 服务端评分。不提供指纹伪造、 @@ -28,36 +28,37 @@ | 后台保护 | 代理、TUN、控制接口、守护任务及安装文件的客户端模式一致性 | | 账号与变化 | 本地事务、磁盘、存档验证与持续变化;文件存在不证明登录有效 | -35 个固定检查入口包括 14 项基础、18 项扩展、地区资格和两个环境资料项;另按用途 -派生验收条件。数量不代表等量独立实验,不计算“账号安全分”。后台没有当前浏览器 +目录由 [check_catalog.py](../envscope/check_catalog.py) 生成,不计算“账号安全分”。后台没有当前浏览器 资料时会说明缺失,不复用旧观测;不适用条件单列,缺失和参考项不改成通过。 ## 上游功能对应 -界面中 23 项对照覆盖检查、状态、切换、跨账号保留、修复、地区 / 客户端设置、 +功能对照覆盖检查、状态、切换、跨账号保留、修复、地区 / 客户端设置、 设备 / CLI 信息、临时浏览器、快照、代理诊断、守护 / 看门狗、路由、维护、托盘、 更新、安装 / 卸载和历史。状态由原生能力与已安装维护核心动态决定。 - 原生实现:独立检测、事务账号管理、Code 修复与撤销、目标、历史、用户定时任务、 托盘、整包更新、两平台临时浏览器、.envsnap 存档、CLI 被动来源和设备资料。 另有城市地区配置与撤销、10 秒进程守护、Clash Verge 路由维护、macOS 原生 DMG - 兼容,以及可明确授权的 Mac 60 秒系统时区服务、更新 / 移除 / 基线恢复。 -- 原版核心或手动处理:系统深度网络修复、其余客户端适配与旧组件迁移。 + 兼容,以及 Windows / macOS 60 秒系统时区服务、更新 / 移除 / 基线恢复。所选 + IPv6 接口与 DNS 缓存、客户端 TUN、旧任务迁移和旧软件清理也有原生审核与恢复流程。 +- 原版核心或手动处理:尚未原生适配的客户端命令、原版详细信息及兼容维护入口。 安装和执行需在产品中确认。保留 Mac 原版详细 CLI / 字体入口;原生 CLI 不运行 PATH 中任意程序,无法从元数据获得的版本会说明需要用户核对。 -- 平台边界:新上游 Windows 已增加 set-region;固定随附核心仍无该命令、时区看门狗或 DMG;没有 - 卸载脚本,仍按原版手动说明操作。界面明确显示,不将源码留存当成功能可用。 +- 平台边界:Windows Claude 专用语言设置提供手动步骤;DMG 兼容只在 macOS; + WireGuard 专项面向 Windows。固定随附核心的命令范围与 EnvScope 原生实现分开标注。 -上游主分支核对至 `223a5cc44edf36dfa568903ab02e73f0f015ec9e`。随附 57 文件仍固定 -在 `870c4ca0754234965878ef58144d7a755d965037`,原字节和许可不变。原生检测保留 -多来源地区证据,并补充守护模式检查;不声称随附安装器已包含新上游所有修复。 +上游参考版本与逐项证据以 [完整功能对照](FULL_PARITY_AUDIT.md) 为准。随附 57 文件固定在 +`870c4ca0754234965878ef58144d7a755d965037`,原字节和许可不变。原生检测保留多来源证据, +不声称随附安装器已包含新上游所有修复。 ## 使用与数据边界 临时浏览器使用已安装 Chrome / Edge / Brave / Chromium 的独立目录,禁用同步和 扩展,限制非代理 UDP;保留真实语言 / 时区。打开前复查网页使用条件,不要求网页 用户安装 Claude 桌面版。未确认进程退出时保留资料;正常退出尝试清理,工具页可 -清理本次已关闭会话。异常退出后的残留可能需手动处理;浏览器开关不是防火墙。 +清理已关闭会话。独立清理进程与重启恢复会核对进程归属,无法确认时保留现场并说明原因; +浏览器开关不是防火墙。详见 [临时浏览器](BROWSER_SESSIONS.md)。 加密存档只导出非活动槽位,导入空槽位。Scrypt 固定 N=32768、r=8、p=1; AES-256-GCM 随机盐 / nonce 并认证头部。先验证标签,再解析 ZIP 和核对文件清单。 @@ -74,8 +75,9 @@ AES-256-GCM 随机盐 / nonce 并认证头部。先验证标签,再解析 ZIP 只用临时资料、网络夹具和假启动器。三架构冻结包另实际运行加密库、窗口、托盘、 更新和用户调度生命周期。 -真实 Claude 登录、组织权限、商业签名 / Apple 公证、第三方浏览器 WebRTC 策略 -效果、系统凭据库和长期休眠恢复仍需具体设备验收。 +真实 Claude 登录、组织权限、第三方浏览器 WebRTC 策略效果、系统凭据库和长期休眠恢复 +仍需具体设备验收。当前 Windows 未进行发布者签名,macOS 为 ad-hoc 签名且未公证; +正式签名是独立的发布接入工作,见 [签名准备](SIGNING.md)。 依据:[原项目](https://github.com/YOURSJEYO/claude-switcher)、 [原项目安全边界](https://github.com/YOURSJEYO/claude-switcher/blob/main/SECURITY.md)、 diff --git a/docs/FULL_PARITY_AUDIT.md b/docs/FULL_PARITY_AUDIT.md index 39f02d2..882bb23 100644 --- a/docs/FULL_PARITY_AUDIT.md +++ b/docs/FULL_PARITY_AUDIT.md @@ -4,9 +4,11 @@ [`92cd62f95f98599215995406deaa7edd89c97c40`](https://github.com/YOURSJEYO/claude-switcher/tree/92cd62f95f98599215995406deaa7edd89c97c40),核对日期 2026-10-30。 Linux 和手机端按产品范围延后。随包 57 个上游文件仍固定在 `870c4ca`,未改写其字节。 -当前 0.23 源码已将所列功能映射到原生实现或明确的兼容 / 手动入口。发布前仍须通过 -对应提交的三平台 Python、20 组浏览器流程、三架构桌面包及实际 OS 夹具验收。 -本文列的是实现与证据范围,不把候选版本、模拟账号或静态表格当作已发布或真实登录成功。 +当前公开版本为 [0.25.0 Alpha](https://github.com/qudadd/envscope/releases/tag/v0.25.0-alpha.1), +所列功能分别映射到原生实现或明确的兼容 / 手动入口。该版源提交的 +[规则与页面 CI](https://github.com/qudadd/envscope/actions/runs/41045089026) 和 +[三架构桌面 / 原生隔离验收](https://github.com/qudadd/envscope/actions/runs/41045082167) 已通过。 +本文列的是实现与证据范围,不把模拟账号或静态表格当作真实登录成功。 ## 功能映射 @@ -31,7 +33,7 @@ Linux 和手机端按产品范围延后。随包 57 个上游文件仍固定在 | open-safe | 两平台独立临时资料、允许网址与代理参数检查、UDP 选项、独立隐藏清理进程、重启恢复 | BROWSER_SESSIONS;真实无害父子进程退出与冻结包夹具;不等于浏览器内部状态或防火墙验证 | | snapshot-export / import | 原生跨平台 ENVSNAP1、原版 Windows CSNAP001、Mac 原版加密 DMG | CSNAP_ARCHIVES / DMG_ARCHIVES;密码经内存 / stdin、先认证、边界限制、空槽、独立 .NET 交叉验证与逐文件回读 | | 10 秒进程守护 | 独立用户任务、固定 PID / 用户 / 路径和批准基线、心跳、冷却与日志 | PROCESS_GUARD;只停止已识别 Claude;是轮询,不是零数据包泄漏保证 | -| 时区 Watchdog / 漂移恢复 | Mac root 60 秒服务与用户巡检;Windows 批准基线恢复;安装 / 更新 / 撤销 / 中断恢复 | TIMEZONE_SERVICE / WATCHDOG_AND_IDENTITIES;权限不足转手动,旧守护冲突时暂停自动写入 | +| 时区 Watchdog / 漂移恢复 | Mac root 服务;Windows 按用户能力使用原用户任务或经前台授权的 SYSTEM 服务;系统服务每 60 秒检查,支持安装 / 更新 / 撤销 / 中断恢复 | TIMEZONE_SERVICE / WATCHDOG_AND_IDENTITIES;拒绝授权、组织策略和旧守护冲突明确显示,未取得新心跳不算正常 | | 后台维护 / 代理离线 | 审核过的配置保持、所选客户端重开、节点恢复、冷却、复检、按日日志 | maintenance / watchdog;新目标需要新批准,不在后台随意切换账号或国家 | | 48 小时出口历史 | 观测次数、不同出口集合数、变化次数分别展示;HMAC、过期清理、缺样本说明 | maintenance / watchdog;集合不等于单个 IP,密钥轮换后不延续不可比计数 | | 安装、更新、卸载维护组件 | 原生组件各自安装 / 更新 / 可逆移除;固定旧安装器兼容入口保留 | 系统权限由本次 OS 授权,第三方驱动仍用原客户端;不把 CI 提升权限等同实际授权弹窗验收 | diff --git a/docs/OPEN_SOURCE_BUILDS.md b/docs/OPEN_SOURCE_BUILDS.md index 295502c..f0795eb 100644 --- a/docs/OPEN_SOURCE_BUILDS.md +++ b/docs/OPEN_SOURCE_BUILDS.md @@ -15,9 +15,10 @@ macOS 的 `CFBundleIdentifier`、`CFBundleShortVersionString`、`CFBundleVersion 记录在安装后改变时停止启动该更新。现有旧版回退记录仍可用,不会因新增身份文件要求丢失回退。 目前不接受包内自行声称“发布者已验证”或“已公证”的构建。若今后启用正式签名,需要单独 -提交并审查发布流程:证书通过仓库秘密配置、固定签发者/Team ID、公证结果读回,并在更新端 -校验真实操作系统签名。只添加环境变量或 JSON 标志不能启用此模式。不要将密码、证书私钥 -或 Apple 账号凭据提交到仓库。 +提交并审查发布流程:接入受控签名服务或密钥库、固定发布者 / Team ID、读回公证结果,并在 +更新端校验真实操作系统签名。只添加环境变量或 JSON 标志不能启用此模式。不要将密码、 +证书私钥或 Apple 账号凭据提交到仓库。身份、费用、可申请的开源方案与接入步骤见 +[正式签名准备](SIGNING.md)。 可重复构建入口:`python -m scripts.build_desktop`。最终包运行 `python -m scripts.packaged_smoke <主程序路径>`,更新路径运行 diff --git a/docs/PERMISSION_ACCEPTANCE.md b/docs/PERMISSION_ACCEPTANCE.md index 015fad4..ed582b3 100644 --- a/docs/PERMISSION_ACCEPTANCE.md +++ b/docs/PERMISSION_ACCEPTANCE.md @@ -18,10 +18,12 @@ Windows 原生验收 `scripts.windows_timezone_acceptance` 只在明确启用的 `scripts.timezone_acceptance`,使用唯一 fixture 路径及真实 LaunchDaemon,并核对 `/etc/localtime` 未改变。fixture 辅助程序不进入发布包。 -当前本地完整回归:720 项 Python 测试通过(5 项平台跳过),19 项 JavaScript 测试通过; +0.25.0 Alpha 发布源提交的本地完整回归:运行 726 项 Python 测试(5 项平台跳过,其余通过),19 项 JavaScript 测试通过; 真实 Windows 冻结包和离线更新包的窗口、托盘、隐藏、恢复、退出与版本身份检查通过。 -跨平台原生验收以本分支和最终发布标签的 [desktop packages 工作流](https://github.com/qudadd/envscope/actions/workflows/desktop.yml) -结果与对应产物为准;未成功的运行不计为通过。 +该版源提交 `e7cd61d0e8f1884441a1845c5a72f429102ae300` 的 +[检查 CI](https://github.com/qudadd/envscope/actions/runs/41045089026) 与 +[三架构 desktop packages](https://github.com/qudadd/envscope/actions/runs/41045082167) 已通过。 +后续版本以自己的提交、运行结果与对应产物为准;未成功的运行不计为通过。 后续专用设备矩阵仍待执行:普通用户首次允许/取消、组织策略拒绝、运行中撤权、升级后 再次打开、系统重启、睡眠唤醒。当前开源 Alpha 可继续交付,但不得将这些待验证场景写成 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e71f9ee --- /dev/null +++ b/docs/README.md @@ -0,0 +1,51 @@ +# 文档目录 + +[返回项目首页](../README.md) · [下载桌面软件](https://github.com/qudadd/envscope/releases/tag/v0.25.0-alpha.1) + +日常使用从 [新用户指南](USER_GUIDE.md) 开始。只想知道“检查什么、怎么修、如何保持”,按下面对应入口阅读即可。 + +## 使用与排障 + +| 要做的事 | 文档 | +|---|---| +| 第一次使用、理解结果、授权与复检 | [新用户指南](USER_GUIDE.md) | +| 按地区与时区完成检测、修复和守护 | [一键流程](SIMPLE_WORKFLOW.md) · [目标环境](TARGET_ENVIRONMENT.md) | +| 选择项目、全选、批量修复 | [可选检查](SELECTIVE_CHECKS.md) · [检查偏好](CHECK_PREFERENCES.md) | +| 查明问题、了解检测证据 | [检测与处理](DIAGNOSIS.md) · [环境覆盖](ENVIRONMENT_COVERAGE.md) · [逐项检查](CLAUDE_CHECKS.md) | +| 确认权限问题和软件能力边界 | [权限验收与限制](PERMISSION_ACCEPTANCE.md) | +| 比较原项目、平台和实现范围 | [完整功能对照](FULL_PARITY_AUDIT.md) | + +## 修复与长期保持 + +| 功能 | 文档 | +|---|---| +| 批准基线、周期检查、漂移恢复与日志 | [Watchdog](WATCHDOG_AND_IDENTITIES.md) | +| Windows / macOS 系统时区服务 | [时区守护](TIMEZONE_SERVICE.md) | +| 启动或重开代理客户端、TUN 与应用语言 | [客户端修复](CLIENT_REPAIR.md) | +| Clash Verge 路由、IPv6 与 DNS 缓存 | [路由](ROUTING.md) · [网络设置与恢复](SYSTEM_NETWORK.md) | +| Windows WireGuard 与可选进程保护 | [WireGuard](WIREGUARD.md) · [进程守护](PROCESS_GUARD.md) | +| 迁移旧任务、清理旧软件与恢复 | [旧任务迁移](legacy-components.md) · [旧软件清理](LEGACY_SOFTWARE.md) | + +## 账号、备份与软件更新 + +| 功能 | 文档 | +|---|---| +| 独立资料槽位、切换与中断恢复 | [账号资料](ACCOUNT_VOLUMES.md) | +| 加密存档与兼容格式 | [.envsnap 与 CSNAP001](CSNAP_ARCHIVES.md) · [macOS DMG](DMG_ARCHIVES.md) | +| 独立临时浏览器会话与清理 | [临时浏览器](BROWSER_SESSIONS.md) | +| 下载校验、更新身份、版本回退 | [开源构建与更新](OPEN_SOURCE_BUILDS.md) | +| 本版变更 | [0.25.0 Alpha](releases/0.25.0-alpha.1.md) · [所有公开版本](https://github.com/qudadd/envscope/releases) | + +## 开发与证据 + +| 内容 | 文档 | +|---|---| +| 从源码运行、测试、打包和提交改动 | [开发指南](DEVELOPMENT.md) | +| 命令行、策略、报告与证据解释 | [CLI](CLI.md) | +| 模块与安全边界 | [架构](ARCHITECTURE.md) · [安全与隐私](../SECURITY.md) | +| 桌面与权限测试的已验证 / 待验证范围 | [桌面验收](DESKTOP_ACCEPTANCE.md) · [权限验收](PERMISSION_ACCEPTANCE.md) | +| Windows 签名、Apple 签名与公证所需条件 | [正式签名准备](SIGNING.md) | +| 界面与交互原则 | [桌面设计](UI_DESIGN.md) | +| 参考项目、固定版本与许可 | [源码研究](RESEARCH.md) · [来源与许可](../THIRD_PARTY_NOTICES.md) | + +[早期功能映射](FEATURE_PARITY.md)、[历史验证记录](VALIDATION.md)、[早期产品验收](PRODUCT_ACCEPTANCE.md)、[可用性测试记录](USABILITY_TESTING.md) 和 [路线记录](ROADMAP.md) 保留阶段背景。判断当前分发状态时,以对应 Release、源码提交和该提交的 CI 结果为准;历史计划不代表新版本已实现。 diff --git a/docs/SELECTIVE_CHECKS.md b/docs/SELECTIVE_CHECKS.md index 4a3ffa7..a9463f1 100644 --- a/docs/SELECTIVE_CHECKS.md +++ b/docs/SELECTIVE_CHECKS.md @@ -1,4 +1,6 @@ -# 可选检查与地区配置(0.11.0 Alpha) +# 可选检查与地区配置 + +[新用户指南](USER_GUIDE.md) · [文档目录](README.md) 先填写实际所在地、用途和连接方式,再选期望配置的国家与城市。美国、加拿大、澳大利亚 提供多个城市,避免用一个国家代替具体时区。预设填入目标出口国家、系统时区和当前用户 @@ -26,7 +28,9 @@ loopback HTTP origin。`ENVSCOPE_CONTROLLER_SECRET` 可用于本机认证;不 原值先写入本机 `~/.envscope/region-recovery.private.json`。权限取消、超时或读回 不一致时停止后续步骤并保留记录。撤销前检查当前值,拒绝覆盖后来手动修改的配置。 部分完成的记录未恢复前不接受新的地区改写。恢复节点可能需要原节点仍在订阅中。 -自动时区服务可能覆盖手动时区;在系统设置中按实际需要核对,后台不会强制改回。 +其他自动时区服务可能覆盖手动时区,需要核对其来源。未启用 EnvScope 守护时不会在后台 +恢复;已批准时区守护时,后台会按其基线处理漂移。修改目标时也需同步已安装的守护基线, +详见 [系统时区守护](TIMEZONE_SERVICE.md)。 无法自动修复的项目标红,展开显示原因、手动步骤、检测本项入口。权威 DNS 出口和 Claude 进程流量关联仍未实现;系统授予更多权限不能代替缺失的测量能力。参考资料与 diff --git a/docs/SIGNING.md b/docs/SIGNING.md new file mode 100644 index 0000000..8ab1691 --- /dev/null +++ b/docs/SIGNING.md @@ -0,0 +1,71 @@ +# 正式签名准备 + +[项目首页](../README.md) · [开源构建与更新](OPEN_SOURCE_BUILDS.md) · [文档目录](README.md) + +核对日期:**2026-10-30**。适用于通过 GitHub Releases 分发的 Windows / macOS 桌面包。申请资格、价格与服务政策可能变化,提交申请前应再核对下方官方页面。 + +## 目前处于什么状态 + +EnvScope 是 MIT 开源项目,可以继续免费分发源码和软件。正式签名用于让操作系统验证发布者与文件完整性,不要求项目转为商业软件。 + +| 项目 | 当前公开的 0.25.0 Alpha | 正式发布者签名所需路径 | +|---|---|---| +| Windows | EXE 未作 Authenticode 发布者签名 | 受 Windows 信任的代码签名服务或证书、签名时间戳与验证 | +| macOS | ad-hoc 签名,无 Developer ID,无公证 | Developer ID Application 签名、Hardened Runtime、Apple 公证及票据附加 | +| 更新器 | 校验仓库、架构、版本、SHA-256 与应用标识 | 还需接入真实操作系统签名和发布者身份验证 | + +校验和、Git 提交上的 Verified 标记和软件的发布者签名各有不同用途。目前没有申请结果、证书或公证通过记录,不应在下载页展示“已签名”。 + +## Windows:先选择签名来源 + +| 路径 | 需要准备 | 对 EnvScope 的适用情况 | +|---|---|---| +| SignPath Foundation 开源支持 | 公开源码和发布包、开源许可、可追溯构建、维护与审核角色;提交项目审核 | 可先评估申请,是否接受由基金会审核决定 | +| 公共受信任 CA 的代码签名证书 / 云签名 | 真实个人或组织身份;选择接受申请人所在地与主体类型的服务商;硬件令牌或 HSM / 云签名环境 | 不依赖开源资助审核,费用与资格由供应商确定 | +| Microsoft Artifact Signing(原 Trusted Signing) | Azure 订阅、Entra 租户、身份验证、证书配置文件;申请主体须满足支持地区条件 | 需先核对身份所在地,不能只看 Azure 部署区域 | + +**SignPath 有额外约束。** 其免费证书的发布者是 SignPath Foundation;项目需满足开源组成、项目声誉、构建来源、成员多因素认证、签名审批和公开签名政策等要求。诊断类功能是否符合其限制,需要如实提交审核。本项目尚未获批,不预先声明受其签名支持。[官方条件](https://signpath.org/terms) · [申请入口](https://signpath.org/apply) + +**购买证书不再等同于取得一个可随意复制的私钥文件。** 新签发的公共代码签名证书通常要求私钥处于合规硬件令牌或 HSM 中;云签名可由服务商管理硬件。购买前需确认能否用于 GitHub Actions、身份显示名称、时间戳服务和续期流程。[DigiCert 私钥存储要求](https://knowledge.digicert.com/alerts/code-signing-changes-in-2023) + +**Microsoft 的地区资格需要单独核对。** 当前公共信任服务面向指定地区的组织,个人申请仅支持美国与加拿大;中国大陆不在当前组织支持名单中。如果以中国大陆个人或组织申请,不能将这条路线视为已可用,也不能用改变云区域代替身份资格。[Microsoft 官方前提条件](https://learn.microsoft.com/en-us/azure/artifact-signing/quickstart) + +Windows 签名应覆盖本项目的主程序和特权辅助程序;若以后增加安装器,也需纳入。先签最终程序字节、加时间戳并验证,再生成发布包和摘要。第三方组件保留自己的来源与签名,不冒充由 EnvScope 开发。[SignTool](https://learn.microsoft.com/en-us/windows/win32/seccrypto/signtool) + +有效签名也不保证新软件立即消除所有 SmartScreen 提示;系统还会参考文件和发布者信誉。[Microsoft SmartScreen 说明](https://learn.microsoft.com/en-us/windows/security/operating-system-security/virus-and-threat-protection/microsoft-defender-smartscreen/) + +## macOS:个人开发者也可以申请 + +| 项目 | 要准备的内容 | +|---|---| +| Apple Developer Program | Apple 账号、双重认证、真实身份与联系方式;个人通常无需成立公司 | +| 组织身份(可选) | 合法组织、签约授权、D-U-N-S 编号、组织域名邮箱与网站;特殊机构按官方例外处理 | +| 费用 | 标准会员费为 **99 美元 / 年**,当地币种与实际结算以 Apple 为准;开源本身不自动免除年费 | +| 签名证书 | Developer ID Application,用于 GitHub 下载的 `.app`;如果另做 `.pkg` 安装器,再准备 Developer ID Installer | +| 构建与公证 | macOS / Xcode 工具链、签名私钥受控保存、公证认证方式及 Team ID | + +个人与组织的注册条件和费用见 [Apple 官方注册说明](https://developer.apple.com/programs/enroll/)。申请主体决定签名身份,不能将仓库昵称直接当作已验证的法人名称。 + +Developer ID 证书通常由 Account Holder 创建;Apple 另外提供有特定授权的云管理证书路径。证书的用途必须区分 Application 与 Installer,普通开发证书或 ad-hoc 签名不能替代 Developer ID 分发签名。[Developer ID 官方说明](https://developer.apple.com/help/account/certificates/create-developer-id-certificates) + +正式构建需要正确签署嵌套程序与辅助程序,启用 Hardened Runtime,设置所需的最小 entitlements 并带安全时间戳。随后使用 `notarytool` 提交公证,读回成功结果与日志,再附加并验证公证票据。公证后重新打包,最终下载文件的 SHA-256 才能用于发布校验。[Apple 公证说明](https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution) · [自定义公证流程](https://developer.apple.com/documentation/security/customizing-the-notarization-workflow) + +## 本仓库还需要完成的接入 + +拿到证书后仍需修改构建与更新逻辑。当前 `build-identity.json` 明确表示未验证发布者;更新器拒绝仅在文件内自行改成“已签名 / 已公证”的构建。 + +1. **固定发布身份**:明确 Windows 发布者与 Apple Team ID,记录允许的证书更换策略。 +2. **接入受控签名**:为 Windows 主程序、时区辅助程序和 macOS 嵌套代码建立签名步骤;私钥留在硬件 / 密钥库 / 受控签名服务中。CI 使用最小权限及受保护的发布凭据,不在日志里输出秘密。 +3. **调整打包顺序**:先签特权辅助程序,再固定其载荷摘要与包内身份,随后完成主程序 / `.app` 签名并读回验证。macOS 公证成功并附加票据后,才生成最终分发包和校验表;不在最终签名后改写包内身份文件。 +4. **更新端真实验证**:调用平台验证能力核对签名、发布者或 Team ID、证书链与公证状态;验证从旧未签名版升级、回退、证书轮换及损坏包拒绝。 +5. **验证再发布**:Windows x64、macOS ARM64 / Intel 分别验收下载后的首次打开、UAC / 系统授权、后台守护、更新与卸载。仅凭 CI 上传成功不能宣称已完成公证或用户授权。 + +实现入口:[构建身份](../envscope/app_identity.py)、[桌面打包](../scripts/build_desktop.py)、[更新器](../envscope/updates.py)、[桌面发布工作流](../.github/workflows/desktop.yml)。 + +签名不会自动授予管理员、文件访问或后台服务权限;这些仍由系统与用户按实际操作批准。签名也不证明 Claude 账号、订阅或地区使用条件符合要求。 + +## 适合当前开源阶段的顺序 + +先确定以个人还是组织名义发布。Windows 可以先评估 SignPath 开源申请,同时了解支持真实申请主体的 CA / 云签名报价;macOS 可走个人 Apple Developer Program。选定方案并取得身份与证书后,再实施上述发布流水线改造。 + +账号注册、付费和申请应由维护者在官方站点完成。不要在 Issue、聊天、源码或普通构建产物中提交身份证件、密码、私钥、`.p12` / `.pfx` 或公证凭据。 diff --git a/docs/SIMPLE_WORKFLOW.md b/docs/SIMPLE_WORKFLOW.md index afbe6d8..56fa1fa 100644 --- a/docs/SIMPLE_WORKFLOW.md +++ b/docs/SIMPLE_WORKFLOW.md @@ -1,4 +1,6 @@ -# 简化的一键流程(0.24) +# 一键检测、修复与守护 + +[新用户指南](USER_GUIDE.md) · [文档目录](README.md) 首页只按实际操作顺序展示四个部分,保留黑白、系统字体和桌面宽度。 diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 450e9be..982686c 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -1,124 +1,100 @@ -# 让 Claude 稳定可用 +# 新用户使用指南 -0.18 增加“持续维护 → 客户端与 TUN 修复 / Claude 应用语言”。检测后可选择已安装 -程序,预览启动、正常重开或 Clash Verge TUN 持久化修复;语言按自己填写的目标处理。 -一键流程修复客户端后自动复检,再按实际读到的网卡生成下一步守护方案。 -无法自动处理的客户端或 Windows 应用语言显示手动步骤。原值与未完成恢复入口保留, -详见 [客户端修复与恢复](CLIENT_REPAIR.md)。 - -0.8 起默认是独立软件。关闭窗口后,可从 Windows 托盘或 macOS 菜单栏再次打开; -再次双击程序会唤回已有窗口。退出请用托盘菜单或窗口内退出按钮。 -“设置 → 软件与后台”控制驻留与每日更新检查,下载、安装和重启前会说明并确认。 -后台驻留不会自动安装维护任务,也不会自动修复网络。下面旧端口说明仅适用于浏览器兼容模式。 +[项目首页](../README.md) · [文档目录](README.md) · [下载 0.25.0 Alpha](https://github.com/qudadd/envscope/releases/tag/v0.25.0-alpha.1) -首页的环境结论只评价列出的基本使用条件:有确定问题时先修复,关键结果缺失时补全, -所列条件通过后才显示范围内合格。“不适用”是已经检查过当前用途;“本版未支持” -是软件能力缺口,申请更多权限也无效。两者都不是隐私检测通过。 -“需要读取权限”只在系统明确拒绝时出现;点击查看用途,打开对应系统入口, -由用户授予读取权限后重新检测。程序不会把打开设置当成已经授权。 +EnvScope 帮你看清 Claude 的本机环境问题,执行已确认的修复,并按需持续检查。它不提供账号、代理节点或订阅;账号实际能否使用,最后仍要在自己的 Claude 中确认。 -0.7.1:左侧“全部检查”可随时查看 32 项目录,检测后按分类或状态筛选;工具页环境 -信息直接显示在按钮下方,不会弹出额外窗口。部分信息读不到会保留已取得的部分并解释原因。 +## 1. 打开软件,确认目标 -本地页面地址会随程序启动改变。顶部显示正在连接的版本与状态;页面可见时保持服务连接。 -如果显示“本地服务已断开”,重新双击 EnvScope 或本地试用启动器,使用新打开的页面。 -不要继续刷新已退出进程的旧端口。结束服务或页面长期不可见后,旧页可能仍留在浏览器里。 +完整解压与你的系统和处理器对应的软件包,打开 `EnvScope.exe` 或 `EnvScope.app`。独立包自带运行环境,无需终端。当前包的签名状态见 [下载说明](../README.md#下载与启动)。 -EnvScope 的使用顺序是:检查连接和配置,处理影响使用的问题,回到自己的 Claude -确认实际回复,再按需要开启日常保持。它不提供账号、节点或登录凭据。 +首次打开有使用教学,可以跳过,也可从左下角“使用教学”重看。完成教学不会修改系统配置或启用守护。 -0.7 把这些操作合在首页。一键检测后自动出方案,审核后点“确认配置并修复”, -随后自动复检;可继续打开或正常重开桌面版,长期保持也在当前页预览、启用和停用。 -[查看一条龙方案界面(离线示例)](images/one-stop.png)。 +首页“地区与时区”中: -“环境设置”默认按需完善 Code 连接:先核对已有本机代理,再测试候选,预览固定 -HTTP(S) 连接、绕过名单整理和开启证书校验的具体影响。也可明确指定本机地址, -或取消配置完善,只修复已定位问题。明确指定后不会试用别的地址。 -自定义接口、云平台和未明确更换的远程代理不自动改路;缺少可信企业证书仍须自行取得。 -原有 MCP、权限及其他字段保留;相同值不会为了排版而重写。 +- 填写**实际使用地区**,再确认用途与连接方式;不确定用途时可选择自动识别。 +- 读取出口 IP,获得**节点国家与城市建议**。列表按对应国家提供代表城市,并填入目标时区、地区格式与语言。 +- 其他城市可选择同一时区的代表城市,或使用自定义目标。查询失败时可手动填写,不会把本机当前值自动当成正确目标。 -![首次打开的使用教学,离线演示](images/teaching.png) +实际所在地与出口分开记录。地区预设只是配置选项,不代表 Claude 官方支持全部地区。时区与语言差异本身不用于推断账号封禁概率。 -首次打开会出现三步教学。选择桌面版、Claude Code、两者或自动识别,了解结果和 -修复流程,再开始第一次检测。可以跳过,左下角“使用教学”随时重看。 -教学进度存在本机 `~/.envscope/learning.private.json`,不依赖浏览器端口或 Cookie; -完成教学不会放宽账号启动条件,不会启用系统任务。 +## 2. 一键检测,看清问题 -## 怎样看结果 +点击“确认并一键检测”。首页显示本次目标、已完成的必需检查、问题与下一步。需要深入查看时,打开具体问题或“全部检查与证据”。 -“全部检查”在检测前显示未检测;检测开始会清除上轮状态,失败时不拿旧结果填充。 -14 项基础与 18 项扩展有各自的用途、结果、下一步和保持说明;HTTP / UDP / 浏览器等 -独立测量另外列出,不重复算入 32 项。查看历史或后台报告时明确标注来源和时间。 +| 结果 | 含义 | 接下来怎么做 | +|---|---|---| +| 所列范围通过 | 当前证据满足这一项的检查条件 | 继续处理其他必需项 | +| 不合格 / 发现问题 | 测到了与目标不符或影响使用的情况 | 查看修复方案,或按手动步骤处理 | +| 需要授权 | 系统明确拒绝了这一项需要的访问 | 查看读取用途,按入口授权后返回复检 | +| 超时 / 缺少证据 | 本次未取得足够信息,不能确认好坏 | 查看原因、检查连接后重测 | +| 本版未支持 | 软件尚无对应测量能力 | 阅读边界,更多权限不能补齐这一项 | +| 不适用 / 未选择 | 当前用途不需要,或本次没有测 | 不计入通过;缺少必需项时整体仍待完成 | -首页把当前最优先的一件事展开,说明发生了什么、为什么需要处理、接下来怎样做。 -其他问题可以展开。软件与设置、连接 Claude、日常保持各自报告状态。 +环境结论仅覆盖所列条件。系统配置存在不证明实际进程流量;HTTP 有响应不证明账号可用;原生 UDP 观测不等于浏览器 WebRTC。展开证据可看到测量来源、时间与范围。 -“还不能确认”表示本次证据不足,或当前工具不能测量这一部分;不是发现故障。 -地区、语言和网络归属资料不要求你为了通过而修改。 -14 项检查配有白话名称,展开后可看当前证据、具体处理方法和长期保持办法。 -完整技术记录与导出仍然保留,不需要先读懂它们才能操作。 +想只检查部分项目时,进入“更多功能 → 全部检查”。可以单选、全选、只选需处理项或选择筛选结果。未选项不会沿用旧结果;启动或切换账号的必要复检不会因此跳过。详见 [选择检查](SELECTIVE_CHECKS.md)。 -自动生成方案仍是只读。具体改动列出后,点击确认才执行;配置修改先备份,写入前 -再次验证代理。配置文件或继承的连接来源变化、连接失效、方案过期时停止写入。 -复检没有当前证据的项目不计为已解决。撤销入口在本次结果及工具页;后续改动会阻止覆盖。 +## 3. 按项授权,修复并复检 -复检中的“配置文件核对”是重新读取固定文件后与方案核对,表示文件中的设置符合方案。 -项目或组织设置可能覆盖用户设置,它不证明实际进程已使用该连接,也不证明账号权限。 +软件先生成只读方案,列出要改什么、影响什么、能否撤销。核对后点击确认才执行。需要先启动代理客户端时,会先完成该步骤并复检,再按新结果生成后续方案。 -收到服务器回应只证明该次探测有回应。API 匿名 401 不代表密钥失效,也不证明账号可用。 -你需要回到自己的 Claude 登录并发消息。“我已收到 Claude 的回复”只记录本页中的 -手动确认,不改技术报告;下一次检测重新要求实际确认。 +授权与修复的区别: -桌面用户可点“复检后打开桌面版”。操作前会重新采集本机信息,核对安装、桌面配置、 -账号资料与连接条件。网页端点与 API 分开核对;403 只表明要求访问校验,不算登录成功。 -"查看启动条件与处理办法"列出还需确认的内容。启动必需项未知、检测过期或有待恢复副本时不提交启动。 +- **读取权限**:只为对应失败项提供入口。打开系统设置不等于已授权,返回后实际复检;拒绝或取消会保留原因。 +- **系统修改权限**:更改时区、IPv6 或安装系统守护时,可能由系统请求管理员授权。EnvScope 不接收或保存管理员密码。 +- **组织策略限制**:不能通过反复点击授权解决,需由管理这台电脑的人处理。 -修改桌面配置后,先保存工作,再点“保存后复检并重开”。先复检,再请求正常退出, -退出后再次复检才重开。若 Claude 仍在运行,不会强制终止;请手动退出后再使用打开入口。 -此操作与账号切换共用锁,不交换或首次归档账号资料。Code 用户需重开常用终端或会话。 -[查看桌面打开与日常保持界面(离线示例)](images/handoff.png)。 +支持自动处理的配置先保存原值与恢复记录,再执行和读回。遇到不支持的修复会标明原因与手动步骤。DNS 缓存刷新不可恢复原缓存,会单独说明;不要把所有操作都理解为可撤销。 -仍不能用时,选择“一直转圈 / 登录失败 / 经常中断 / 证书错误 / Code / MCP”中的 -实际现象。步骤链接到官方说明;命令提供复制,工具不会擅自运行 `/doctor`、`/mcp` -或执行 PATH 中发现的程序。 +修复结束后自动复检,分别列出已消除、仍存在及证据不足的问题。方案过期、目标变化或文件后来被修改时,不会继续使用旧方案覆盖新设置。部分完成或中断的操作,先处理恢复入口,再发起新修改。 -## 账号怎样使用 +Code 配置只改用户文件中已审核的字段,保留其他设置。项目或组织配置仍可能覆盖它,修改后应重开终端或会话。配置备份保存在本机,**未加密、可能含密钥,不可上传分享**。更多说明见 [检测与处理](DIAGNOSIS.md)。 -只有一个账号时,在 Claude 正常登录即可,无需创建槽位。账号页管理的是 Claude -桌面版资料文件夹,不是账户注册或密码管理;浏览器与 Claude Code 登录不会跟着切换。 +## 4. 确认实际使用,再开启守护 -1. 需要多个账号时,先给 A 命名,点击“检测启动条件”。 -2. 检测通过后点“保存当前资料到 A”,先保存桌面应用中的工作,再确认退出与归档。 -3. 给 B 命名,点“首次登录”。现有资料保留为 A,在新打开的 Claude 中手动登录另一个账号。 -4. 以后通过“切换并打开”返回已有存档;“当前资料”不等于登录仍然有效。 +检测与修复后,回到自己的 Claude 登录并发一条消息。首页“详细记录与使用帮助”保留打开 / 正常重开桌面版的入口,操作前重新核对必要条件;Code 用户需重开自己的会话。 -添加显示名称只保存本机备注,不创建账号、不登录、不自动启动。切换前重新检测; -未通过时显示原因,不交换资料。发现未完成事务时保留所有副本并停止切换。 -目录导出包含未加密的登录资料,空槽位导入仅用于本人受保护的本机备份。 +“我已收到 Claude 的回复”仅记录你的本次手动确认,不改变技术报告,也不成为下一轮的自动通过证据。匿名 API 的 401 只表明到达认证边界,不等于密钥错误或登录成功。 -## 怎样保持 +需要长期保持时,在首页“持久化守护”或侧栏“持续守护”中选择范围,预览并确认: -定时复检、Code 配置保持、系统基线和进程守护可分别审核。定时复检默认关闭; -可选每 5 / 15 / 60 分钟检查,后台结果显示实际完成时间。 -Code 配置保持需要先验证当前代理、预览批准字段再启用,每次恢复先备份。 -时区与地区格式需先配置到已确认城市目标。Mac 选择时区守护时,可在同一方案中 -申请原生系统服务授权,每 60 秒检查;地区修改和撤销同步服务基线。遇到旧任务冲突 -先按界面说明处理,不让两个基线互相覆盖。[系统时区守护说明](TIMEZONE_SERVICE.md)。 -需要进程保护时,另行审核原生 10 秒守护的进程与连接范围;该功能可能停止应用和 -中断未保存工作,不等于防火墙断网。Clash Verge 路由可在维护页预览、确认、读回与撤销。 -更换代理或改变检测目标后重新检测,并重新生成维护方案。 +| 功能 | 运行方式与限制 | +|---|---| +| 定时巡检 | 默认关闭,可选 5 / 15 / 60 分钟;显示实际完成时间和失败原因 | +| 配置与代理保持 | 仅恢复批准的字段、节点与所选客户端;保留日志,反复失败暂停 | +| 系统时区服务 | Windows / macOS 可在前台申请相应系统授权,按批准时区每 60 秒检查;单独提供停用与恢复入口 | +| 进程守护 | 另行审核的 10 秒监测;触发条件时可能停止已识别 Claude,需先保存工作,不等于防火墙断网 | -## 开源方案怎样配合 +后台不会反复弹出授权框。权限不足、心跳过期、旧任务冲突或恢复受阻时,会保留异常与处理入口。更改目标或代理后重新检测并审核新的守护方案。[Watchdog](WATCHDOG_AND_IDENTITIES.md) · [系统时区守护](TIMEZONE_SERVICE.md) -| 项目 | EnvScope 中的实际用途 | 边界 | -|---|---|---| -| [claude-switcher](https://github.com/YOURSJEYO/claude-switcher) | 完整固定源码随附,维护操作适配,逐项检测对照 | 安装与修复单独确认;上游输出不直接算本工具通过 | -| [Mihomo 文档接口](https://wiki.metacubex.one/api/) | 本机读取运行配置、规则和节点;经确认可选择已有节点并验证,路由修复后读回 | 不捆绑内核、不创建节点;未确认时不修改,不兼容或未授权则说明原因 | -| [Clash Verge Rev](https://github.com/clash-verge-rev/clash-verge-rev) | 可选 Windows/macOS 外部客户端,代理发现、端口测试与原生路由维护 | 需单独安装;修改先预览并确认,保留备份、失败回滚,不内置连接服务 | +关闭窗口默认驻留托盘 / 菜单栏,可从菜单重新打开或退出;“设置 → 软件与后台”可关闭驻留。**退出应用不会自动删除已批准的系统任务**。停用普通巡检和移除独立系统时区服务是各自的操作,按对应入口处理。 + +## 多账号与备份怎样使用 + +只有一个账号时,直接在 Claude 登录,无需建槽位。账号页管理 Claude **桌面版的本地资料**,不负责注册、订阅或密码管理;浏览器和 Code 的登录不会跟随切换。 + +1. 给 A 命名并检测启动条件,保存桌面应用中的工作后,将当前资料归档到 A。 +2. 给另一个槽位命名,使用“首次登录”,在 Claude 中自行登录另一个账号。 +3. 以后使用“切换并打开”。软件重新检测、正常退出应用、校验封存与载入;不会通过调用登出来切换。 +4. 发现未完成事务时,先审核恢复方案。所有现场副本保留,不要再用另一套工具同时交换资料。 + +本地资料独立不保证系统钥匙串、DPAPI、跨设备会话或服务端设备判断完全一致。优先使用 `.envsnap` 加密备份;高级目录导出未加密,包含敏感资料。密码不由软件保存,遗失后无法代为恢复。[账号资料与恢复](ACCOUNT_VOLUMES.md) · [加密格式](CSNAP_ARCHIVES.md) + +## 更新、日志与反馈 + +“设置 → 软件与后台”默认每日向 GitHub 查询版本;下载、安装和重启需要确认。更新核对仓库、架构、摘要和应用身份,保留前一版本用于回退。已启用的任务仍引用原来批准的程序路径,移动应用后需重新核对。[更新说明](OPEN_SOURCE_BUILDS.md) + +“更多功能”中可以查看历史、工具和环境信息。分享问题时附上系统、软件版本、操作步骤和复核过的脱敏诊断包,不要上传账号卷、配置原文、真实 IP 或代理凭据。 + +只有通过源码的浏览器兼容模式运行时,才需要留意本地页面端口:服务退出后旧页面失效,重新启动并使用新打开的页面即可。独立软件日常使用无需记住端口。 + +## 与其他开源工具怎样配合 -优先使用已安装的工具;增加项目名称本身不会增加检测证据。Scrapling 只在开发研究时 -采集与核对公开方案。第三方界限见 [来源说明](../THIRD_PARTY_NOTICES.md)。 +| 工具 | 实际作用 | +|---|---| +| [claude-switcher](https://github.com/YOURSJEYO/claude-switcher) | 功能参考、固定源码与明确的维护兼容入口;上游输出不直接变成本项目通过结论 | +| [Mihomo](https://wiki.metacubex.one/api/) | 通过已有本机控制接口读取状态;经确认可选择已有节点并验证,不创建节点 | +| [Clash Verge Rev](https://github.com/clash-verge-rev/clash-verge-rev) | 可选外部客户端,提供相应的启动、TUN 与路由维护;需单独安装 | -官方依据:[网络与证书配置](https://code.claude.com/docs/en/network-config)、 -[/doctor 与稳定性排障](https://code.claude.com/docs/en/troubleshooting)、 -[MCP](https://code.claude.com/docs/en/mcp)。 +更多平台差异见 [完整功能对照](FULL_PARITY_AUDIT.md)。Scrapling 只用于开发研究,第三方许可见 [来源说明](../THIRD_PARTY_NOTICES.md)。