Codex Vibe Monitor

Codex Vibe Monitor 是面向自部署的 OpenAI 兼容代理观测工作台：它接入 /v1/* HTTP / WebSocket 流量，将调用留证、实时 SSE、历史统计、请求排障、上游账号池、forward proxy、价格目录和 SQLite 持久化收在同一套运营界面中。CRS runtime polling 已退役；历史 xy 记录和 quota snapshot 仅保留只读查询，服务不再从 XYAI 上游抓取新数据，这是重要的兼容边界。

• Tags: Progressive web app, Monitoring dashboard, Storybook accessibility, UI version display, GitHub Actions scheduling, Worktree bootstrap

• Cargo.toml 是 Axum/SQLx/Tokio 服务 manifest，包含 SQLite、SSE、proxy、OpenAI-compatible forwarding 和 CLI 依赖。
• web/ 是 React/Vite 管理台；web/.storybook/main.ts 启用 @storybook/addon-a11y 与 docs，属于 Storybook accessibility。
• web/public/site.webmanifest 与 web/index.html 定义了 standalone install metadata、theme color 和 icon/manifest linkage。
• Dockerfile 先构建 web assets，再构建 Rust binary，并固定 Bun/Rust/Debian 版本以控制 glibc 漂移。
• ops/observability/ 保存 Prometheus、Grafana、可选 Tempo、Compose network/volume、dashboard provisioning、recording rules 与 alert provisioning；src/observability/ 保存应用侧 bounded metrics、HTTP/body/browser 采集、资源采样、报告适配和可选 tracing 边界。
• .github/quality-gates.json、ci-pr.yml、ci-main.yml、release.yml 和 review-policy.yml 定义 PR/main/release gate。

Web build 会写入版本信息：web/package.json 的 build 链接 scripts/write-version.mjs，Dockerfile 通过 APP_EFFECTIVE_VERSION 注入 VITE_APP_VERSION。后端运行时是单 Rust service，SQLite 为低运维持久层；Docker artifact 是主要部署形态。与此同时，web/index.html 与 web/public/site.webmanifest 已经把这个控制台声明成 display: standalone 的 install surface，说明 install metadata 不是附属美术资源，而是产品 runtime identity 的一部分。

性能观测是独立于业务持久化的运行时交付面：应用从真实事件更新有界 metrics，Prometheus 负责历史，Grafana 通过仓库 provisioning 管理六个 dashboard、查询和告警；hotpath-rs 负责函数、规范化 SQL、路由和选定锁的归因。请求 tracing 当前是默认关闭的可选能力，Tempo 只保存受限的请求链路；受限 samply CPU attach 是按需诊断工具，不是常驻 profiler。相关 Compose、网络隔离、凭据边界和验证顺序见 ops/observability/README.md 与 docs/solutions/performance/prometheus-grafana-compose-integration.md。

这个仓库也是 Lefthook 型 Worktree bootstrap 的 canonical 实现。维护者先确保 repo 外的全局 lefthook 可执行，再以 bun run hooks:install 生成 shared Git hooks；lefthook.yml 的 post-checkout command 调用当前 checkout 的 scripts/run-lefthook-hook.sh。linked worktree 会自动以 copy-missing-only 语义同步本地资源，并通过 scripts/worktree-setup.sh 依次恢复 repo root、web/、docs-site/ 的 Bun 依赖和 Rust crate 缓存；主 worktree 普通 checkout 跳过依赖恢复。自动路径汇总告警但不阻断 checkout，手动 bun run worktree:bootstrap 则保留聚合失败码（README.md、docs/specs/v7se4-worktree-bootstrap/SPEC.md、lefthook.yml、scripts/worktree-bootstrap.sh、scripts/worktree-setup.sh）。

系统边界是代理层、统计采集层、SQLite persistence 和 dashboard SSE。代理不能只当 reverse proxy；它还承担审计记录和 quota snapshot 暴露。历史 XYAI 数据是 compatibility/read-only surface，后续改动不能重新引入上游抓取假设。

观测链路另有清晰的职责边界：应用 exporter 和 hotpath exporter 向 Prometheus 提供聚合指标，Grafana 只查询已 provision 的 Prometheus/Tempo 数据，业务数据库继续保存调用、费用、token、终态、任务与审计事实。metrics、trace 和 CPU profile 不能互相冒充；观测组件、exporter、sampler 或报告 API 的故障只能使观测降级，不能改变代理请求、ACK、任务执行或业务写入的成功语义。固定 label 白名单、凭据分离、私网抓取、报告限额和 tracing 的异步有界队列是当前实现的安全边界，而不是所有项目的固定数值。

证据锚点：README.md。

这个 repo 是 PR label release 的强参考：PR gate、main gate、release snapshot、review policy 拆得很细。.github/quality-gates.json 记录 required checks，release.yml 与 label gate 决定版本发布，.github/workflows/notify-release-failure.yml 把失败通知作为独立的可复用 release surface。Storybook a11y 和 web tests 属于 UI gate，Rust tests 属于服务 gate。

观测集成的质量证明覆盖配置、运行时和查询语义：六个 dashboard JSON、Prometheus recording rules、Grafana datasources/alerts、Compose 服务边界、metrics freshness/样本量检查、hotpath 报告白名单，以及监控停机不影响业务的验收。scripts/cvm-observe 提供固定查询和 HTTPS 机器访问面，scripts/test-observability-tools.py、scripts/test-observability-acceptance.py 与 scripts/test-observability-diagnostics.py 证明工具输入、隔离验收和诊断边界；这些证据不等于生产部署或性能预算已在所有环境通过。

.github/workflows/ci-pr.yml 的 edited metadata 重验与普通 candidate 共用可取消的 per-PR concurrency group；是否隔离重验运行属于 GitHub Actions scheduling，而不是修改 gate 名称或 release contract。

Worktree 侧的质量证明不是 shell 静态检查，而是 scripts/test-worktree-bootstrap.sh 建立真实 linked worktree 并通过真实 Lefthook hook 触发 bootstrap；fake Bun/Cargo 锁定依赖执行顺序和 locked 参数，Vitest sentinel 证明恢复后的 web tool 可执行。测试还覆盖缺少全局 Lefthook、repo-local binary shadow、unmanaged hook 保留、自定义 core.hooksPath、历史 revision no-op、现有 .env.local 不覆盖，以及自动/手动失败语义（scripts/test-worktree-bootstrap.sh、scripts/install-lefthook-hooks.sh）。

• 在 Dockerfile 中固定 builder/runtime 发行版，避免 glibc 版本漂移导致容器运行失败。
• 把版本显示作为 UI contract；release 和 web build 都要传递 effective version。
• 将代理审计数据放入 SQLite，适合个人/小团队单节点服务。
• 把 manifest、theme-color、apple-touch-icon 和 app icons 都内置在仓库里，有助于保持 install surface 与本地图标资产一致，不再依赖运行时第三方拉取。
• 已采用 Lefthook 的仓库可把 standard shared hook generation、当前 revision runner、copy-missing local resources、best-effort dependency recovery 和真实 linked-worktree smoke 收敛成一条 canonical bootstrap chain；不要再并列维护 custom wrapper 或 dual entrypoint（lefthook.yml、scripts/install-lefthook-hooks.sh、scripts/run-lefthook-hook.sh）。
• 自动 post-checkout 与手动 worktree:bootstrap 应复用同一 setup implementation，但保留不同失败语义：自动路径告警后成功返回，手动路径暴露聚合非零状态（scripts/worktree-bootstrap.sh、scripts/worktree-setup.sh）。
• 用有界、低基数的 runtime metrics 记录真实 source event，把 Prometheus/Grafana 当作历史与查询面，把业务 SQLite 当作业务事实面；不要用业务表回填 metrics，也不要让 dashboard 成为业务成功条件（docs/design/performance-observability.md、docs/specs/performance-telemetry/METRICS.md）。
• 将应用 classic Histogram 与 hotpath native Histogram 分开抓取、查询和容量审查；dashboard provisioning、recording rules 和 alert rules 进入仓库，Grafana UI 不作为配置真相（ops/observability/prometheus.yml、ops/observability/grafana/provisioning/）。
• 将 metrics scrape、Grafana Viewer、hotpath report 和 tracing 摄入/查询凭据分开，并把 Prometheus/Tempo 保持在受限网络；项目具体的端口、留存、采样率、容量与性能预算只由当前项目合同决定，不能复制成通用默认值（ops/observability/compose.yml、docs/design/request-lifecycle-observability.md）。
• 让 tracing 默认可关闭、异步且有界；让 CPU profiler 通过受限命令按需 attach，禁止把任意 PID、shell 或 profiler daemon 暴露成通用运维入口（src/observability/traces.rs、scripts/cvm-hotpath-cpu）。

• 代理处理敏感请求，日志和 SQLite retention 需要清晰策略。
• CRS/XYAI 历史兼容边界容易被误解。
• Release snapshot 机制复杂，不能用简单 tag push 替换。
• 当前 install metadata 已经明确，但没有 service worker/offline/update lifecycle 的同等级证据；后续若要把它提升为“真正的可离线 PWA”，必须先补齐这条链路。
• linked worktree 在本地依赖出现前就需要启动 shared hook，因此全局 Lefthook 是明确前置条件；repo-local node_modules/.bin/lefthook 不能替代它。自定义 core.hooksPath 或 unmanaged hook 必须被保留，不能由安装入口暗中覆盖（docs/specs/v7se4-worktree-bootstrap/SPEC.md、scripts/install-lefthook-hooks.sh）。
• 观测的六个 dashboard、Tempo 兼容边界和旧性能 SQLite/自研性能图表退役是当前实现事实；新增项目不能据此推导固定 dashboard 数量、tracing 必选、留存期限或性能预算。任何容量/开销结论都需要项目自己的验证卡和环境证据（docs/specs/performance-telemetry/SPEC.md、docs/specs/performance-telemetry/empirical-candidate-card.md）。
• Grafana、Tempo、hotpath 或 profiler 的可达性不能通过复制生产入口、凭据或内部部署路径来证明；公共 playbook 只保留相对配置路径和抽象网络/身份边界。

• README.md
• Cargo.toml
• Dockerfile
• web/package.json
• web/index.html
• web/public/site.webmanifest
• web/.storybook/main.ts
• ops/observability/README.md
• ops/observability/compose.yml
• ops/observability/prometheus.yml
• ops/observability/recording-rules.yml
• ops/observability/grafana/dashboards/
• ops/observability/grafana/provisioning/
• src/observability/
• scripts/cvm-observe
• scripts/cvm-hotpath-cpu
• scripts/test-observability-acceptance.py
• scripts/test-observability-diagnostics.py
• scripts/test-observability-tools.py
• docs/design/performance-observability.md
• docs/design/request-lifecycle-observability.md
• docs/specs/performance-telemetry/SPEC.md
• docs/specs/performance-telemetry/METRICS.md
• docs/solutions/performance/prometheus-grafana-compose-integration.md
• docs/specs/k7kpk-bundle-icons-locally/SPEC.md
• docs/specs/v7se4-worktree-bootstrap/SPEC.md
• docs/specs/v7se4-worktree-bootstrap/IMPLEMENTATION.md
• lefthook.yml
• scripts/install-lefthook-hooks.sh
• scripts/run-lefthook-hook.sh
• scripts/worktree-bootstrap.sh
• scripts/worktree-setup.sh
• scripts/sync-worktree-resources.sh
• scripts/test-worktree-bootstrap.sh
• .github/quality-gates.json
• .github/workflows/ci-pr.yml
• .github/workflows/ci-main.yml
• .github/workflows/label-gate.yml
• .github/workflows/notify-release-failure.yml
• .github/workflows/release.yml