Codex TRACE Write Guard

中文 · English

中文

一个可导入 Codex 的防护 skill，用于检测 logs_2.sqlite 是否因为 TRACE 日志持续高频写盘，并在确认异常后通过 SQLite trigger 阻断 logs 表写入。

这个项目源自一次真实排查：约 10 天产生了 3.2 TB 磁盘写入。它不会删除数据库、WAL、SHM 或历史日志，也不会默认创建定时任务。

功能

• 采样 MAX(id)、日志行数、TRACE 行数、数据库大小和 WAL 大小
• 仅在新增日志以 TRACE 为主，且写入速率或 WAL 增长超过阈值时自动处理
• 修改前使用 SQLite Online Backup API 创建一致性备份
• 安装幂等的 BEFORE INSERT ... RAISE(IGNORE) trigger
• 验证日志、MAX(id)、TRACE 和 WAL 不再增长
• 识别已有兼容 trigger，避免重复安装
• 支持 Windows、macOS 和 Linux，仅依赖 Python 标准库

Warning

保护 trigger 会阻断 logs 表的全部 INSERT，而不只是 TRACE。启用后 Codex 的本地诊断日志将不再写入。请先使用 check，并保留脚本生成的备份。

安装

Windows PowerShell

git clone https://github.com/bingxijun/codex-trace-write-guard.git
Set-Location codex-trace-write-guard
.\install.ps1

macOS / Linux

git clone https://github.com/bingxijun/codex-trace-write-guard.git
cd codex-trace-write-guard
./install.sh

安装器会把 skill/codex-trace-write-guard 复制到：

• $CODEX_HOME/skills/codex-trace-write-guard，如果设置了 CODEX_HOME
• 否则复制到 ~/.codex/skills/codex-trace-write-guard

如果目标已存在，安装器默认停止；显式使用 -Force 或 --force 时，会先创建带时间戳的备份。

也可以直接把 skill/codex-trace-write-guard 文件夹复制到 Codex skills 目录。

使用

在 Codex 中：

使用 $codex-trace-write-guard 检查 logs_2.sqlite 是否存在异常 TRACE 高频写盘。

直接运行只读检测：

python skill/codex-trace-write-guard/scripts/guard_codex_trace_writes.py --mode check --sample-seconds 10

自动检测并在达到阈值时修复：

python skill/codex-trace-write-guard/scripts/guard_codex_trace_writes.py --mode auto --sample-seconds 10 --verify-seconds 5

立即安装保护 trigger：

python skill/codex-trace-write-guard/scripts/guard_codex_trace_writes.py --mode protect --verify-seconds 5

只验证现有保护：

python skill/codex-trace-write-guard/scripts/guard_codex_trace_writes.py --mode verify --verify-seconds 5

移除本项目创建的 trigger：

python skill/codex-trace-write-guard/scripts/guard_codex_trace_writes.py --mode unprotect

脚本只会移除 codex_trace_write_guard_block_logs，不会移除其他或旧版 trigger。

默认异常阈值

• 新增日志速率：至少 2 条/秒
• 新增日志中 TRACE 占比：至少 80%
• 或采样期 WAL 增长：至少 1 MiB

所有阈值都可以通过命令行参数调整。脚本输出单个 JSON 对象，便于审计和外部监控。

测试

python -m unittest discover -s tests -v

项目不会默认启用周期巡检。需要定时执行时，请由使用者根据自己的环境显式配置。

English

An importable Codex skill that detects sustained high-frequency TRACE writes to logs_2.sqlite. After confirming abnormal activity, it can install a SQLite trigger that blocks inserts into the logs table.

The project was created after investigating an environment that generated roughly 3.2 TB of disk writes in 10 days. It never deletes the database, WAL, SHM, or historical rows, and it does not create scheduled jobs by default.

Install

Windows:

git clone https://github.com/bingxijun/codex-trace-write-guard.git
Set-Location codex-trace-write-guard
.\install.ps1

macOS / Linux:

git clone https://github.com/bingxijun/codex-trace-write-guard.git
cd codex-trace-write-guard
./install.sh

Important safety note

The protection trigger blocks every INSERT into logs, not only TRACE rows. This disables local diagnostic log collection. Run in check mode first and keep the generated backup.

The skill supports check, auto, protect, verify, and unprotect modes. It uses only the Python standard library and emits machine-readable JSON.

License

MIT