{"id":49561317,"url":"https://github.com/zrainbow1275/windows-codex-stability-guardian","last_synced_at":"2026-05-15T03:12:16.516Z","repository":{"id":353128297,"uuid":"1214543671","full_name":"ZRainbow1275/windows-codex-stability-guardian","owner":"ZRainbow1275","description":"Windows-native local stability tooling for Codex CLI, Docker Desktop/WSL2, and User Profile diagnostics.","archived":false,"fork":false,"pushed_at":"2026-05-14T16:35:58.000Z","size":439,"stargazers_count":17,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T18:39:46.418Z","etag":null,"topics":["codex-cli","diagnostics","docker-desktop","rust","windows","wsl"],"latest_commit_sha":null,"homepage":"https://github.com/ZRainbow1275/windows-codex-stability-guardian","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZRainbow1275.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T18:09:03.000Z","updated_at":"2026-05-14T16:36:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ZRainbow1275/windows-codex-stability-guardian","commit_stats":null,"previous_names":["zrainbow1275/windows-codex-stability-guardian"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ZRainbow1275/windows-codex-stability-guardian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZRainbow1275%2Fwindows-codex-stability-guardian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZRainbow1275%2Fwindows-codex-stability-guardian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZRainbow1275%2Fwindows-codex-stability-guardian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZRainbow1275%2Fwindows-codex-stability-guardian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZRainbow1275","download_url":"https://codeload.github.com/ZRainbow1275/windows-codex-stability-guardian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZRainbow1275%2Fwindows-codex-stability-guardian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33051913,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codex-cli","diagnostics","docker-desktop","rust","windows","wsl"],"created_at":"2026-05-03T09:03:13.989Z","updated_at":"2026-05-15T03:12:16.508Z","avatar_url":"https://github.com/ZRainbow1275.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Windows Codex 稳定性守护工具（Windows Codex Stability Guardian）\n\n[![CI](https://github.com/ZRainbow1275/windows-codex-stability-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/ZRainbow1275/windows-codex-stability-guardian/actions/workflows/ci.yml)\n[![Release](https://github.com/ZRainbow1275/windows-codex-stability-guardian/actions/workflows/release.yml/badge.svg)](https://github.com/ZRainbow1275/windows-codex-stability-guardian/actions/workflows/release.yml)\n\n面向 Windows 工作站的本地稳定性工具，覆盖 Codex CLI、Docker Desktop / WSL2、以及 Windows 用户配置文件三个常见故障域。\n\nGuardian 的目标只有一个：把 Codex / Docker / Profile 这一类**反复出现、根因在本地状态漂移**的小故障，变成可观察、可证据化、可在 `--confirm` 守护下安全修复的事项；其它无法分类的情况一律只报告、绝不动手。\n\n---\n\n## 当前状态\n\n| 项目 | 状态 |\n| --- | --- |\n| 发布线 | `v0.1.3` |\n| 打包产物 | 已修复：Release zip 内的 `guardian.exe` 可直接双击启动桌面 GUI |\n| 默认入口 | `guardian.exe` 无参数运行时进入桌面 GUI；CLI 子命令仍通过 `check` / `repair` / `diagnose` / `export` 显式调用 |\n| 已验证产物 | `dist/v0.1.3/guardian.exe` 无参 GUI smoke 通过，`cargo test --workspace` 与 `cargo clippy --workspace --all-targets -- -D warnings` 通过 |\n| 安全边界 | 只读诊断默认不写入；修复动作必须显式 `--confirm` |\n\n从 `v0.1.3` 起，过去“打包后双击 `guardian.exe` 一闪而过、不显示 GUI”的问题已经通过正式 release 产物修复。原因是旧版本把无参启动当作 CLI 用法错误处理；现在无参入口会默认打开桌面 GUI，适合普通 Windows 用户从文件管理器直接启动。\n\n## 桌面 GUI 运行截图\n\n以下截图均来自真实打包产物通过无参数启动后的桌面 GUI。\n\n### 只读健康概览\n\n![Guardian GUI 健康概览](docs/assets/readme/guardian-gui-overview.png)\n\n### 诊断步骤\n\n![Guardian GUI 诊断步骤](docs/assets/readme/guardian-gui-diagnose.png)\n\n### 受保护的操作顺序\n\n![Guardian GUI 受保护操作提示](docs/assets/readme/guardian-gui-guarded-step.png)\n\n---\n\n## 社区支持\n\n学 AI，上 L 站：[LinuxDO](https://linux.do/)\n\n---\n\n## 为什么做这个项目\n\nOpenAI Codex CLI 在 Windows 上有一组反复被报告、长期未修复或修复不彻底的本地故障。受影响最严重的是 `/resume`、侧边栏历史、`codex resume` 三个入口。这些症状共同特征是：**会话文件其实还在磁盘上，但 Codex 因本地数据库 / 配置 / 启动器漂移而读不出来**。\n\nGuardian 直接对位以下上游 issues：\n\n| 上游 Issue | 现象（Windows） | Guardian 分类 | 修复策略 |\n| --- | --- | --- | --- |\n| [openai/codex#14469](https://github.com/openai/codex/issues/14469) | Severe chat-switch lag；线程切换 / `/resume` 卡顿（issue 已 closed，但 slow-path 症状仍可在 0.x 版本上复现） | **C4** | TUI 日志检测到 `Loading sessions...`，在 `--confirm` 下做启动器（launcher）补丁 + `vendor-hotfix\\codex.exe` 旁路二进制 |\n| [openai/codex#17540](https://github.com/openai/codex/issues/17540) | Windows 桌面应用重启后侧边栏历史会话丢失，但磁盘上 sessions 还在（open） | **C2** | 备份 `state_*.sqlite` → 清除最新 state DB 中的 stale rows（`threads.has_user_event` 漂移），让 Codex 重新认得磁盘上的会话 |\n| [openai/codex#15007](https://github.com/openai/codex/issues/15007) | `/resume` 或 `codex resume` 不加载 project config（open） | **C6 + C2** | 备份 `%USERPROFILE%\\.codex\\config.toml` → 补回缺失的 trusted project 条目；同时清理 stale rows 让会话重新可见 |\n| [openai/codex#14756](https://github.com/openai/codex/issues/14756) | Codex CLI 即使是简单请求也响应极慢（open） | **C4（+C2）** | 与 #14469 同一条 slow-path 路径：状态库 stale rows + TUI `Loading sessions` 联合判定，按需走启动器 hotfix |\n| [openai/codex#14949](https://github.com/openai/codex/issues/14949) | Windows shell 任务被中断后留下孤儿子进程；重启 Codex 时可能进入 process storm（open） | **诊断 + 证据导出**（不自动 kill） | `guardian diagnose profile` + `guardian export bundle` 收集证据；不自动终止进程，避免误杀安全软件或 vmmem |\n\n\u003e 注：Guardian 不\"代替\"上游修复，也不长驻后台修改你的环境。它只在你显式给出 `--confirm` 时执行已分类的修复路径，其余情况下只做只读观察、写出结构化健康报告与审计文件。\n\n---\n\n## 工作原则\n\n- **先观察再修复** — 每一次修复都从 live 机器证据出发，绝不基于假设\n- **先备份再写入** — SQLite、`config.toml`、Codex 启动器在变更前一律备份\n- **先确认再变更** — 必须显式 `--confirm`，没有后台自动修复\n- **修复面有界** — Guardian 只修它能从证据分类的故障类型；其余只报告、不触碰\n- **Windows 原生、低开销** — 工作站本地运行，使用 Windows 事件日志、注册表读取、必要时调 PowerShell\n- **零远端依赖** — 不上报遥测、不调用云、不需要账号\n\n---\n\n## 故障分类表（C / D / P）\n\nGuardian 用证据驱动的失败分类系统，将本地故障落到具体的\"故障类（FailureClass）\"上。\n\n### Codex 域\n\n| 分类 | 含义 | 触发证据 |\n| --- | --- | --- |\n| `C2` | Codex 状态数据库漂移（**stale rows**） | 最新 `state_*.sqlite` 中 `threads.has_user_event` 出现陈旧记录 |\n| `C3` | Codex 版本处于已知风险窗口 | `codex --version` 落在已知会触发 picker bug 的版本范围 |\n| `C4` | `/resume` slow-path 漂移 | `~/.codex/log/codex-tui.log` 近期含 `Loading sessions...` |\n| `C5` | 配置访问错误 | TUI 日志含 config / access error；或 `config.toml` 解析失败 |\n| `C6` | trusted-project 漂移 | `%USERPROFILE%\\.codex\\config.toml` 缺少当前项目的 trust 条目 |\n\n### Docker / WSL 域 与 Profile 域\n\n`D1`–`D4` 覆盖 `.wslconfig` 基线漂移、Docker / WSL 运行时状态；`P1`–`P4` 覆盖 Windows 用户配置文件相关事件（Temp Profile、ProfileList 注册表锁、安全软件介入等）。Profile 域**全程只读**，不会修改 ProfileList。\n\n---\n\n## Guardian 能做什么\n\n### Codex 健康检查与修复\n\n- 读取 `~/.codex` 下的 `history.jsonl`、rollout / session 文件、最新 `state_*.sqlite`\n- 分类 `C2`（stale rows）/ `C4`（slow-path）/ `C6`（trust 漂移）等\n- 在 `--confirm` 下：\n  - 备份 SQLite → 清理 stale rows → post-write 校验\n  - 备份 `config.toml` → 追加 trusted project 条目\n  - 在已存在已验证 hotfix 二进制时，备份原启动器 → 替换为 `vendor-hotfix\\codex.exe`\n- 即使 slow-path（`C4`）那一步因为没有可用 hotfix 而失败，也**不会回滚**前面已经成功的 stale-row / trust 修复；失败原因写入审计\n\n### Docker / WSL 基线恢复\n\n- 校验 `.wslconfig` 基线键\n- 区分\"配置漂移\"和\"运行时恢复\"\n- 若有运行中的容器，会主动**阻止**高风险的 runtime 重启\n- `--confirm` 模式下写出审计\n\n### Profile 诊断（只读）\n\n- 读 User Profile Service 事件\n- 分类 Temp Profile / ProfileList 注册表锁信号\n- 检测安全软件介入迹象\n- 输出结构化诊断 JSON\n- **永远不会**自动改 ProfileList，也不会终止安全软件进程\n\n### Bundle 导出\n\n- 把当前健康报告、profile 诊断、审计摘要打包成支持 bundle，便于事后排查或团队协助\n\n---\n\n## 命令一览\n\n| 命令 | 用途 | 写入边界 |\n| --- | --- | --- |\n| `guardian.exe check` | 跑只读健康检查 | 只读 |\n| `guardian.exe repair codex` | 检查 + 可选修复 Codex 漂移 | 写入需 `--confirm` |\n| `guardian.exe repair docker` | 检查 + 可选修复 Docker / WSL 漂移 | 写入需 `--confirm` |\n| `guardian.exe diagnose profile` | 输出 profile 诊断 + 引导式恢复建议 | 只读 |\n| `guardian.exe export bundle` | 导出当前健康 + 审计支持 bundle | 只读（对被监控系统） |\n| `guardian.exe` | 默认启动桌面 GUI，适合文件管理器双击 | 无显式动作不修复 |\n| `guardian.exe gui` | 启动桌面 GUI | 无显式动作不修复 |\n| `guardian.exe tray` | 启动系统托盘入口 | 无显式动作不修复 |\n\n\u003e **注意**：从 `v0.1.3` 之后，文件管理器里直接双击 `guardian.exe` 会打开桌面 GUI；命令行用户仍可显式运行 `guardian.exe check`、`guardian.exe repair ...` 等子命令。想要常驻后台 UI，请用 `guardian.exe tray`。\n\n---\n\n## 快速开始\n\n### 1. 下载 Release\n\n从 [Releases](https://github.com/ZRainbow1275/windows-codex-stability-guardian/releases) 获取：\n\n- `guardian-v\u003cversion\u003e-windows-x64.zip` ← **唯一推荐下载**：含 `guardian.exe` + README/CHANGELOG/LICENSE + `tools/repair-codex-resume.ps1`\n- `SHA256SUMS.txt` ← 校验推荐 zip 的 SHA-256\n\n\u003e GitHub Release 页面会固定显示 `Source code (zip)` 和 `Source code (tar.gz)`。这两个是 GitHub 按 tag 自动生成的源码归档，不是 Windows 可执行程序包；普通用户请不要下载它们。\n\n### 2. 校验下载\n\n推荐流程：\n\n1. 在 GitHub 上确认 tag 是 signed / verified\n2. 下载 zip 与 `SHA256SUMS.txt`\n3. 本地校验 hash：\n\n```powershell\nGet-FileHash .\\guardian-v0.1.3-windows-x64.zip -Algorithm SHA256\n```\n\n把输出和 `SHA256SUMS.txt` 对照。\n\n### 3. 先跑只读体检\n\n```powershell\nguardian.exe --json check\n```\n\n这一步**纯只读**，不会动你机器上任何东西。看它在 `domains.codex.evidence` 里报告的 `failure_classes` 是 `C2 / C4 / C6` 中的哪些。\n\n### 4. 按需升级到修复\n\n```powershell\n# Codex：先 dry-run 看会做什么\nguardian.exe --json repair codex --dry-run\n\n# 真正执行（备份后修复 stale rows / trust / slow-path）\nguardian.exe --json repair codex --confirm\n\n# Docker / WSL 基线\nguardian.exe --json repair docker --dry-run\n\n# Profile 只读诊断\nguardian.exe --json diagnose profile --output profile-diagnosis.json\n\n# 打 support bundle\nguardian.exe --json export bundle\n\n# 常驻托盘 UI\nguardian.exe tray\n```\n\n---\n\n## 上游 Issue 与操作 cheat sheet\n\n\u003e 想直接对症操作，按下面的步骤走。\n\n### 症状对应 #14469 / #14756（slow-path、`/resume` 卡顿）\n\n```powershell\n# 1. 体检：看 codex 域的 failure_classes 是否包含 C4\nguardian.exe --json check\n\n# 2. 在 dry-run 下确认 Guardian 打算做什么\nguardian.exe --json repair codex --dry-run\n\n# 3. 如果机器上已有可用的 hotfix codex.exe（位于 %TEMP%\\codex-src\\codex-rs\\target\\release\\codex.exe\n#    或 release zip 内 vendor-hotfix 路径），执行：\nguardian.exe --json repair codex --confirm\n```\n\n`C4` 修复链：备份 Codex 启动器（launcher） → 把启动器指向 `vendor-hotfix\\codex.exe` → post-write 校验。**没有 hotfix 时不会瞎动**：失败原因写入审计 + CLI / GUI / tray notes，前面已成功的 `C2 / C6` 修复**不回滚**。\n\n### 症状对应 #17540（重启后侧边栏历史丢失）\n\n```powershell\nguardian.exe --json check                       # 应看到 C2，evidence.stale_rows \u003e 0\nguardian.exe --json repair codex --dry-run\nguardian.exe --json repair codex --confirm      # 备份 sqlite → 清 stale rows → 校验\n```\n\n修完之后重启 Codex 桌面应用，侧边栏历史应该重新出现。\n\n### 症状对应 #15007（`/resume` 不加载 project config）\n\n```powershell\n# 在出问题的项目根目录里跑（让 Guardian 知道目标 project path）\ncd D:\\path\\to\\your\\project\nguardian.exe --json check                                       # 应看到 C6\nguardian.exe --json repair codex --dry-run\nguardian.exe --json repair codex --confirm\n```\n\n修复链：备份 `%USERPROFILE%\\.codex\\config.toml` → 追加当前 project 的 trusted project 条目 → 重新解析校验。\n\n### 症状对应 #14949（孤儿子进程 / process storm）\n\nGuardian **不会自动 kill 进程**，因为误杀 `vmmem` 或安全软件代价过大。它的角色是**证据收集**：\n\n```powershell\n# 1. 立即抓 profile + Codex 域证据（只读）\nguardian.exe --json diagnose profile --output profile-diagnosis.json\nguardian.exe --json export bundle\n\n# 2. 把 bundle（默认在 %LOCALAPPDATA%\\guardian\\bundles 下）和 profile-diagnosis.json\n#    一并附在 issue / 求助贴里\n```\n\n之后再决定是手动 `taskkill /T` 进程树、重启 Codex，还是按 issue #14949 里讨论的 workaround 处理。\n\n---\n\n## 安全模型\n\nGuardian 故意做得很保守：\n\n- `guardian.exe check` 永远只读\n- 写入操作必须经过 `--confirm`\n- Codex 修复**先备份**当前 state SQLite\n- Codex slow-path（`C4`）启动器替换**只在** `guardian repair codex --confirm` 内、且 Guardian 已经分类为 `C4`、且找到已验证的 hotfix 二进制时才执行\n- Profile 诊断**永不**自动编辑 `ProfileList`，**永不**终止安全软件\n- Docker / WSL 的运行时重启会先看 live 机器状态再决定是否拒绝\n\n---\n\n## 数据路径\n\n默认位置：\n\n- 审计：`%LOCALAPPDATA%\\guardian\\audits`\n- 支持 bundle：`%LOCALAPPDATA%\\guardian\\bundles`\n- 备份（SQLite / config.toml / launcher）：`%LOCALAPPDATA%\\guardian\\backups`\n\n---\n\n## 仓库结构\n\n| 路径 | 用途 |\n| --- | --- |\n| `apps/guardian/` | 主程序入口、CLI、托盘、GUI、打包脚本 |\n| `crates/guardian-core/` | 共享类型、策略、审计结构 |\n| `crates/guardian-observers/` | 只读机器证据采集与分类器 |\n| `crates/guardian-repair/` | 修复编排、bundle 导出、守护写入路径 |\n| `crates/guardian-windows/` | Windows 专用辅助：路径、事件日志、进程执行、注册表 |\n| `.github/workflows/` | CI 与 tag 驱动的发布流水线 |\n\n---\n\n## 开发\n\n### 环境\n\n- Windows\n- Rust stable\n- PowerShell\n\n### 本地构建\n\n```powershell\ncargo build -p guardian\ncargo test --workspace\n```\n\n### 本地打 release 包\n\n```powershell\n.\\apps\\guardian\\scripts\\package-release.ps1 -Version v0.1.1\n```\n\n产物落到 `dist\\\u003cversion\u003e\\`。如果打包机的 `%TEMP%\\codex-src\\codex-rs\\target\\release\\codex.exe` 已存在已验证的 Codex slow-path hotfix 二进制，会自动复制到 `vendor-hotfix\\\u003ctriple\u003e\\codex\\`，使 release 构建无需依赖原始 temp 路径就能完成 `C4` 修复。\n\n---\n\n## 项目状态\n\n当前发布线：**v0.1.1**\n\n已实现并接通：\n\n- Codex 健康检查（history、sessions、state SQLite、TUI 日志、trusted-project 配置）\n- Codex 托管修复编排：`C2`（stale rows）/ `C6`（trust 漂移）/ `C4`（slow-path）三链联合执行\n- 修复链 fail-soft：`C4` 步骤失败不会丢弃前面已成功的 `C2 / C6` 修复，失败原因落到审计\n- Docker / WSL 检查与守护下的 `.wslconfig` / runtime 修复\n- Profile 诊断与引导式恢复\n- Bundle 导出（含保留策略）\n- Tray 与 GUI 入口，复用 CLI 同一条修复管线\n\n---\n\n## 安全与隐私\n\n本仓库刻意不包含机器特定的密钥、私有 session 文件或仅本地的笔记。\n\n参见 [SECURITY.md](./SECURITY.md)。\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzrainbow1275%2Fwindows-codex-stability-guardian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzrainbow1275%2Fwindows-codex-stability-guardian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzrainbow1275%2Fwindows-codex-stability-guardian/lists"}