docs: 重整 GitHub 首页、使用文档与正式签名说明

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.

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` 的格式，不混用。

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)。
 
 产品流程：首次教学 → 一键检测 → 问题与权限分类 → 合并修复方案 → 确认写入 →

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 场景已经通过。后续提交应引用自己的测试记录。