From e0ac0e45cc6791695fc51e1cc76ee169836ec7d1 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 1 Jul 2026 04:12:24 +0000 Subject: [PATCH] docs: capture JD01 GC post-task lessons --- .agents/skills/unidesk-gc/SKILL.md | 11 ++++++++++- docs/reference/gc.md | 18 ++++++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/.agents/skills/unidesk-gc/SKILL.md b/.agents/skills/unidesk-gc/SKILL.md index 845920ea..54d936de 100644 --- a/.agents/skills/unidesk-gc/SKILL.md +++ b/.agents/skills/unidesk-gc/SKILL.md @@ -118,6 +118,15 @@ Read `docs/reference/gc.md` before these remote cases: For JD01, Chrome memory growth should first be treated as an observer lifecycle problem: sentinel/quick-verify terminal paths must stop their observer, and runner TTL/maxSamples/artifact caps must come from YAML. Do not solve it by raw killing Chrome or deleting web-observe directories; use controlled observe stop and GC plan candidates. +JD01 and other remote hosts may use rebuildable tool caches only through explicit opt-in: + +```bash +bun scripts/cli.ts gc remote JD01 plan --target-use-percent 49 --include-tool-caches --limit 100 +bun scripts/cli.ts gc remote JD01 run --confirm --target-use-percent 49 --include-tool-caches --limit 100 +``` + +Review the plan first. The remote tool-cache candidate is limited to fixed allowlisted npm/npx/Bun cache directories; do not replace it with ad hoc `rm -rf ~/.npm ~/.bun`, and do not touch `node_modules`, auth/config, k3s/containerd, PVCs, or Docker volumes. + ## Protected Boundaries Never use these as generic disk relief: @@ -143,4 +152,4 @@ docker system df du -sh /root/unidesk/.worktree /root/unidesk/.state /tmp /var/log 2>/dev/null || true ``` -Summarize the starting and final `df` percentage, major successful cleanup classes, protected failures, and remaining high-risk pressure sources. +For remote memory/Chrome pressure, also include `free -h`, Chrome/observer process summary, and web-observe state size. Summarize the starting and final `df` percentage, major successful cleanup classes, protected failures, and remaining high-risk pressure sources. diff --git a/docs/reference/gc.md b/docs/reference/gc.md index b1beac1c..b5e0c03d 100644 --- a/docs/reference/gc.md +++ b/docs/reference/gc.md @@ -11,6 +11,7 @@ UniDesk 的磁盘治理入口是 `bun scripts/cli.ts gc ...`。该入口用于 - `gc policy plan|install`：从 `config/unidesk-cli.yaml#gc.policyTimer` 渲染或安装低风险长期策略，例如 journald cap、每日 allowlisted 文件/tmp 清理 timer、VPN 诊断 pcap retention、`.state` artifact retention 和 VS Code CachedExtensionVSIXs 下载缓存 retention。 - `gc db-trace plan|run --confirm --before-date YYYY-MM-DD --vacuum-full`：显式 trace 遥测留存入口；涉及数据库重写时按维护窗口处理。 - `gc remote plan|run --confirm|status --job-id `：通过 UniDesk SSH 透传在 provider host 上执行受控 GC。远端长任务必须使用异步 job 和 `status` 短查询，不应让单次 SSH 等待完整 registry GC 或其他长清理。 +- `--include-tool-caches`：本机和远端都必须是显式 opt-in，只清理固定 allowlist 的可重建 npm/npx/Bun 缓存；不得扩大成清理 `~/.npm`、`~/.bun`、`node_modules`、auth/config 或运行面依赖。 所有成功和失败输出都必须是 JSON。`plan` 必须标记 `dryRun=true`、`mutation=false`；`run` 必须要求 `--confirm` 并报告 `diskBefore`、`diskAfter`、`summary`、`results` 和 `protected`。远端 GC 可用 `--target-use-percent N` 显式表达目标根盘水位；`summary.target` 必须给出目标所需释放量、候选估算、预计水位、缺口和 `safeStop` 决策，避免靠人工心算判断是否应该继续扩大清理范围。 @@ -98,6 +99,10 @@ JD01 Chrome 内存治理应优先管理 observer runner 生命周期，而不是 JD01 plan 和 status 应同时披露内存压力摘要：active observer 数、Chrome process 数、Chrome RSS、stale observer 数、state root artifact bytes、last cleanup、last stop failure 和 drill-down 命令。GC run 只能执行 plan 中明确标记 safe 的低风险动作，例如 apt/journal/tmp allowlist、dead web-observe raw artifact retention，以及通过受控 observe stop 处理 stale observer；对 PVC、k3s runtime、containerd、Docker volume、Secret 和 auth/config 状态一律保持 protected 或转交专用 retention 入口。 +JD01 的 npm/npx/Bun 缓存可作为中低风险边界候选，但必须通过 `gc remote JD01 plan|run --include-tool-caches` 显式启用。该入口只允许固定 allowlist 的可重建缓存目录，并在执行前重新校验路径、非 symlink 和 allowlist；它不清理 `node_modules`、用户配置、认证状态、k3s/containerd、PVC、Docker image/container/volume 或 GitOps 运行面对象。 + +Web probe sentinel 的 `quick-verify`、Playwright 或浏览器验证不得作为 CI/CD 发布 gate 自动周期触发。若某个 sentinel 需要周期 quick-verify，必须在 YAML 中显式 opt-in cadence scheduler；默认发布验证只看配置的 health endpoint，quick-verify 只作为人工或独立 post-deploy evidence 入口。这样避免 CI/CD 周期性重启 observer/Chrome 并重新制造内存和 artifact 增长。 + ## HWLAB Registry Retention G14 HWLAB registry 清理必须显式使用 `--include-hwlab-registry`，默认 `gc remote G14 plan` 不进入 registry。策略必须保守，不能只留 latest，也不能只删除 tag link 后误判已经释放空间。 @@ -188,6 +193,8 @@ G14 进入 50% 这类维护窗口目标时，标准顺序是： 4. 再次运行 `gc remote G14 plan --target-use-percent --include-hwlab-registry ...`。 5. 若只剩 KiB 级低风险候选且 `safeStop=true`，停止自动清理，不得为了命中百分比目标手工删除受保护目录。 +维护窗口目标接近整数边界时，验收必须同时报告 `df -h /` 和 `df -B1 /`。`summary.target` 使用字节计算，`df` 使用整数展示，二者在 49/50 这类边界可能看起来不一致；收口时以最终 `diskAfter.usePercent`、`df -h` 展示和字节视图共同说明，不得因为四舍五入差异绕过 protected boundary。 + ## G14 Space Attribution Baseline G14 当前只有一个本机 k3s cluster；空间归因时不要把 `hwlab-dev`、`hwlab-prod`、`hwlab-v02` 理解成独立 cluster，它们是同一 k3s 上的 namespace/runtime slice。长期诊断应按三层归因： @@ -280,6 +287,16 @@ bun scripts/cli.ts hwlab g14 control-plane cleanup-released-pvs --lane all --lim 验收结论至少包含：根盘水位、`DiskPressure=False`、registry readiness/API、AgentRun `aligned=true`、HWLAB v0.2 `state=aligned`、active PipelineRun 数，以及 remaining low-risk candidates / safe-stop 决策。若目标百分比未达到但 `safeStop=true`，必须写清剩余缺口和下一类策略选择，不得把未执行的高风险清理伪装成已完成。 +JD01 GC 或 Chrome/observer 压力收口还必须补充： + +```bash +trans JD01 sh -- 'df -h /; df -B1 /; free -h' +trans JD01 sh -- 'ps -eo pid,rss,comm,args | awk '\''BEGIN{IGNORECASE=1} /chrome|chromium|web-probe observe/ && !/awk/ {print}'\'' || true' +bun scripts/cli.ts web-probe sentinel control-plane status --node JD01 --lane v03 --sentinel +``` + +若本次变更涉及关闭 cadence scheduler，还应确认 GitOps objects 不再包含 quick-verify CronJob，并确认 runtime/Argo/health endpoint 仍为 ready。 + ## Long-Term Anti-Bloat Plan | 措施 | 默认策略 | 预期收益 | @@ -288,6 +305,7 @@ bun scripts/cli.ts hwlab g14 control-plane cleanup-released-pvs --lane all --lim | CI tag growth cap | 每个 service 对 commit tag 增长设置上限并进入 GC plan | 防止 registry 每周持续膨胀 | | Tekton/Pipeline retention | 完成态 PipelineRun/TaskRun/Job 按留存期清理 | 释放少量空间，降低 API 噪声 | | Log/journal cap | journald 上限、文件日志轮转、Docker json log truncate | 稳定防止日志膨胀，收益通常为数百 MiB 到数 GiB | +| Remote tool cache opt-in | `gc remote ... --include-tool-caches` 只清理固定 allowlist 的 npm/npx/Bun 可重建缓存 | 在不触碰运行面状态的前提下释放数百 MiB 级边界空间 | | VS Code CachedExtensionVSIXs retention | 只清理可重建 extension VSIX 下载缓存，不触碰已安装扩展/server/user data | 防止远程 VS Code 扩展升级缓存长期堆积，收益通常为数百 MiB | | Core dump limits | 限制 dump 大小或按 allowlist 删除实际分配块 | 防止 crash dump 污染观测；sparse dump 不应被高估 | | Containerd image audit | 定期只读报告 runtime image cache 构成 | 为维护窗口 prune 提供证据，不默认删除 |