diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dc807bf16f..503314aae1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -456,6 +456,20 @@ jobs: node-version: 22 - run: node scripts/config-surface-guard.mjs + # #3249 lifecycle ledger guard: every BILI_* env var read in src/ must be + # registered in LIFECYCLE.md (§1 transition ledger with release condition, or + # §2 permanent registry) — a new switch without a lifecycle entry goes red here. + # Stale entries (dynamic/unmerged/retired names) notice only. Zero-dep: plain + # node, no install step. Not gated to pull_request, same as the guards above. + lifecycle-ledger-guard: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - run: node scripts/lifecycle-ledger-guard.mjs + # #2170 lane guard: the side-lane decision (#388 passthrough — src/server/ # side-request.ts + the lane region of src/server/handle.ts, extracted from # src/server.ts by #1440) is regression-critical diff --git a/LIFECYCLE.md b/LIFECYCLE.md new file mode 100644 index 0000000000..5ef4e18448 --- /dev/null +++ b/LIFECYCLE.md @@ -0,0 +1,184 @@ +# LIFECYCLE.md — 过渡开关台账 · 退役模块盘点 · 卫生记录 + +> 与 CONFIGURATION.md 的分工:CONFIGURATION 记录每个旋钮**今天做什么**;本台账记录哪些旋钮是**临时的**(盖子 / kill-switch / 实验性 opt-in,带解除条件),以及哪些模块在退役路径上。 +> 建立于 #3249(陈年件清理)。纪律:**只立账不删**——删除逐项由 owner 拍板。 +> +> **CI 强制**:`scripts/lifecycle-ledger-guard.mjs`(workflow job `lifecycle-ledger-guard`)会检查 `src/` 里读到的每一个 `BILI_*` 环境变量是否都出现在本文件——**台账外的新变量直接 fail**;台账里有但代码已不读的条目只给 notice(动态生成名、未落 master 的分支变量属正常滞后)。 + +## 规则 + +1. `src/` 中读取的每个 `BILI_*` 环境变量必须在本文件出现(§1 或 §2)——CI 强制。 +2. §1 = 过渡开关:有明确解除条件的盖子 / kill-switch / 实验。字段:引入 / 引入原因 / 解除条件 / 状态。 +3. §2 = 常设面:按类列出,一行一个(名称 / 类别 / 一句话用途),无解除条件预期。 +4. 新增过渡开关:先在 §1 立账(含解除条件),再落码;CI 保证不漏。 +5. 共享 `BILI_` 前缀但**不是环境变量**的标识符列在 §3,避免混淆。 + +--- + +## 1. 过渡开关台账(盖子 / kill-switch / 实验) + +| 开关 | 引入 | 引入原因 | 解除条件 | 状态(2026-10-15) | +|------|------|----------|----------|--------------------| +| `BILI_ANTHROPIC_THREADS_INJECT` | #2888(未合入 master 的开放 PR,分支 `2026-10-12_claude-global-scope-narrow-gate`) | #2884 CC 全局作用域直通 bug 的临时盖子:threads lane 默认逐字节直通;`=1` 才启用完整注入 | #2926 S5:真实 CC 主会话抓包证明注入后上游 200 + SQLite 统一 rebuild-fold 落地 | 未落 master(PR #2888 open);生命周期跟踪于 #2926 | +| `BILI_STREAM_STALL_MS` | #1706 时代的流停滞检测 | #1706 事故(陈年 400ms 误报)后由 #1714 退役;现在只读它来发一条警告(src/server.ts:594) | 已无生产意义——连警告读一起删 | 已退役(只读告警);整体移除候选 | +| `BILI_SESSION_WARM_MAX` | #2803 bounded startup | 限制 boot 时预热会话数(master 当前默认 8,src/knobs.ts:230) | 在途 PR #3194 把默认翻成 0 → 本变量退化为纯 opt-back;合入后观察 dogfood 数据再决定去留 | 在用(master 默认 8);决策等 #3194 合入后的数据 | +| `BILI_STORAGE_UNIFIED` | #2671 存储统一重建 | dry-run 转正开关 legacy/shadow/full(当前默认 shadow,JSON 仍是唯一事实源) | shadow 跑稳后转正拍板(full 成为默认);届时一并决定「legacy 显式值还要不要支持」 | 在用(默认 shadow);未转正 | +| `BILI_STORAGE_JSON_WRITER` | #2960 Phase 3 | full 模式下的 JSON writer 关闭开关(回滚通路;仅 full 模式生效,默认 on) | 与 storage.unified 转正绑定:unified 定案后退役 | 在用(仅 full 生效) | +| `BILI_ROLLOUT_`(前缀家族;现成员 `BILI_ROLLOUT_SIMHASH_V2`、`BILI_ROLLOUT_FOLD_GUARD`) | src/rollout.ts 灰度机制 | 每功能灰度 kill-switch:env > config `rollout.features.`(true/false/percent 简写,#3062)> 确定性分桶(sha256(salt\nid)%10000)> off | 单个功能灰度完成并稳定后,从 rollout 表移除该功能,其 env 随之失去意义 | 机制常设;单个成员轮换 | +| `BILI_FOLD_RECONCILE` | #1921 | fold 对账模式 off/warn/repair(默认 repair;非法值只告警不致命,src/fold-reconcile.ts:384) | 增量车道 #3248 落地后评估 legacy 对账路径去留 | 在用(默认 repair);与 #3248 联动 | +| `BILI_RECLAIM_FETCH_PATCH` | #1158 | escape hatch:`=0` 保留经典直装 fetch patch 路径 | fetch-chain patch 成为既定行为后退役 | 默认开(`=0` 回退经典路径) | +| `BILI_CODEX_COMPACT` | #3008 | codex compaction 拦截 kill-switch(intercept/pass);intercept 覆盖显式与内联 auto-compact(SUMMARIZATION_PROMPT 识别) | intercept-by-default 站稳后评估 pass 模式是否还有人需要 | 默认 intercept | +| `BILI_SQLITE_AUTO_DOWNLOAD` | #2833 | sqlite 引擎自下载开关(严格 1/0 > 文件 > 默认 true;被拒时仍用缓存副本) | —(转正为常设安全阀则移 §2) | 在用(默认 true) | +| `BILI_NATIVE_ATTACH_EXTERNAL` | #1322/#1335 | 外部 attach opt-in:默认拒绝 attach 到会长命于会话的实例(拒绝文案见 launcher.ts:3561) | —(长期安全姿态则移 §2) | opt-in(默认 false) | +| `BILI_LAUNCHER_DIRECT` | launcher direct-URL 模式 | `=1` 进入直通 URL 模式:LLM 流量不过代理 ⇒ 无压缩(只有 bili MCP 调用可用);默认 MITM | —(两种模式都是正式入口则移 §2) | opt-in(`=1`) | +| `BILI_LAUNCHER_PLUGIN` | launcher plugin 车道 | `=0` kill switch 回 wire 注入工具;`=1` 强制 plugin 车道;缺省自动 | plugin 车道成为唯一车道后退役 kill switch | 默认 auto | +| `BILI_RESIGN` / `BILI_RESIGN_PASSTHROUGH` / `BILI_RESIGN_BENEFIT` / `BILI_CODEARTS_REF` | #1884 / #2090 | 签名上游重签特性族:`=0` 整族下线(回到 #1884 前重写行为);passthrough 是「此链路不带压缩」的显式确认通道 | 特性族定型后各成员转 §2 | 特性族在用(`=0` 可整族下线) | +| `BILI_FAKE_COMPLETION_RETRIES` | fake-completion fallback | 假完成重试(opt-in,默认 0 = 禁用) | fallback 机制定型后转 §2 | opt-in | +| `BILI_NO_CACHE_CONTROL` | compat | 历史 no-cache-control 怪癖保留(knobs.ts:458 明言 "Historical quirk preserved in the env") | 兼容窗口结束后退役 | 默认 off | +| `BILI_STREAM_ERROR_SHAPE` | compat | 给无法带内上报错误的 SDK 的流错误形状兼容 | 兼容保留(长期) | 常设兼容旋钮 | +| `BILI_SUBAGENT_SPLIT` | #970 | subagent 拆分(默认 on) | 成为既定行为后移 §2 | 默认 ON(`=0` 退出) | +| `BILI_RESUME_INHERITANCE` | resume inheritance | resume 继承行为(默认 on) | 同上 | 默认 ON(`=0` 退出) | +| `BILI_AFFINITY_SIMHASH` | #2265 | simhash adoption kill-switch(`=0` 禁用) | adoption 成为既定行为后移 §2 | 默认 ON | +| `BILI_CHAIN_CONTENT` | chain 识别 | chain 内容检测(#1683 背景;默认 off,文件可开) | 实验结论出来转正或删 | 默认 off | +| `BILI_CHAIN_STAMP` | egress stamp | stripped-middlebox 场景的出口戳(默认 off) | 同上 | 默认 off | +| `BILI_STABLE_SYSTEM_ANCHOR` | stable-system-anchor 实验 | 每会话 system 锚点实验(默认 OFF) | 稳定性评估后转正或删 | opt-in(默认 OFF) | +| `BILI_FORK_ADOPTION` | fork-adoption 特性 | fork 继承实验(opt-in;禁用时提示从零开始,fork-adoption.ts:300) | 稳定后转正或退役 | opt-in(默认 off) | +| `BILI_ALLOW_DSH_COMPACTION` | dsh compaction | dsh compaction opt-in(env 语义同 BILI_PERSIST 家族) | 转正后移 §2 | opt-in(`=1`) | +| 测试钩子:`BILI_DSH_RECOVERY_INTERVAL_MS` / `BILI_DSH_RETRY_INTERVAL_MS` / `BILI_MODEL_INFO_RETRY_MS` | #2082 等 | 缩短测试/运维节奏(dsh-native.ts;NODE_TEST_CONTEXT 感知,避免生产误缩) | 永久测试设施,随宿主代码走 | 测试钩子 | + +## 2. 常设面全量登记表(src/ 实际读取的其余 BILI_* 环境变量) + +### 2.1 宿主 opt-out(per-host kill switch;另有全局 `BILLION_CONTEXT_PLUGIN=0`) + +| 变量 | 一句话用途 | +|------|-----------| +| `BILI_NATIVE_CLAUDE` / `BILI_NATIVE_DSH` / `BILI_NATIVE_KIMI` / `BILI_NATIVE_OMP` / `BILI_NATIVE_OPENCODE` / `BILI_NATIVE_PI` / `BILI_NATIVE_ZCODE` | 对应宿主 native 车道 `=0` 整体退出(bootstrap 各文件入口判断) | +| `BILI_NATIVE_ATTACH_POLICY` | native attach 策略(env > 文件 native.attachPolicy) | + +### 2.2 内部 spawn 通道(launcher→子进程,非用户面) + +| 变量 | 一句话用途 | +|------|-----------| +| `BILI_LAUNCH_TOKEN` | launch 令牌(spawn 时注入;日志中脱敏) | +| `BILI_PARENT_PID` | owner-pid 看门狗(会话生命周期归属) | +| `BILI_STRICT_PORT` | `=1` claude SessionStart hook 退出端口重试(#964) | +| `BILI_OPENCODE_ACP_SPEC` | 剥离版 ACP spec 临时配置**文件路径**提示 | +| `BILI_LAUNCHER_LANE` | lane 身份戳(attach 时比对归属) | +| `BILI_LAUNCHER_MODEL_WINDOWS` / `BILI_LAUNCHER_MODEL_MAX_OUTPUTS` | 模型窗口/输出上限 JSON,传给子进程对齐 nudge 分母与输出预留 | +| `BILI_INHERITED_HTTP_PROXY` / `BILI_INHERITED_HTTPS_PROXY` / `BILI_INHERITED_ALL_PROXY` / `BILI_INHERITED_NO_PROXY` | 继承调用方代理设置转发给 proxy 子进程 | +| `BILI_MITM_HOSTS` / `BILI_MITM_DOMAINS` | MITM 主机/域名单传给子进程 | +| `BILI_NON_HTTP_PROVIDERS` | #1392 非 http(s) baseUrl provider 白名单传递 | +| `BILI_PROVIDER_REWRITES` | #535 provider 改写 manifest JSON(存在即关 zcode native) | +| `BILI_UPGRADE_REPLACEMENT` | #3044 self-restart 替换进程交接标记(UPGRADE_REPLACEMENT_ENV) | + +### 2.3 网络调优(#2030 迁移家族:env > 文件 network.* > 默认) + +| 变量 | 默认 | +|------|------| +| `BILI_UPSTREAM_TIMEOUT_MS` | 720000(12 min) | +| `BILI_REQUEST_WATCHDOG_MS` | 2× upstream timeout | +| `BILI_KEEP_ALIVE_TIMEOUT_MS` | 5000 | +| `BILI_CLIENT_ERROR_BACKSTOP_MS` | 30000 | +| `BILI_EXPOSURE_LOG_INTERVAL_MS` | 3600000(0 禁用,垃圾值回落 3600000) | +| `BILI_MAX_SHRINK_PER_COMPRESS` | unset(不做收缩引导) | +| `BILI_REPLAY_RETRY_MAX` / `BILI_REPLAY_RETRY_BASE_MS` | 3 / 1500 | +| `BILI_STREAM_KEEPALIVE_MS` | 15000(0 禁用 hold) | +| `BILI_PREFLIGHT_HOLD_MS` | 30000 | +| `BILI_PREFLIGHT_DEAD_END_COOLDOWN_MS` | 300000 | +| `BILI_POST_RESPONSE_LINGER_MS` | 5000(#1982,曾为纯 env) | +| `BILI_PROXY_KEEPALIVE_MAX_MS` | 55000(0 = 一次性连接) | +| `BILI_CCR_RETRIEVAL_TTL_MS` | 600000 | +| `BILI_DECOMPRESS_TMP_CAP` | 50 | +| `BILI_PUBLIC_SNAPSHOT_CAP_BYTES` | 100 MiB(#2017;0 完全禁用留存) | +| `BILI_MITM_HANDSHAKE_TIMEOUT_MS` | 10000 | +| `BILI_CHAIN_MAX_FUTURE_SKEW_MS` / `BILI_CHAIN_RECENT_WINDOW_MS` | chain-checkpoint 内部默认值 | + +### 2.4 会话池 / GC / 持久化 + +| 变量 | 一句话用途 / 默认 | +|------|------------------| +| `BILI_MAX_SESSIONS` | sessions.max,默认 256 | +| `BILI_SESSION_GC` | 会话 GC 总开关(`=1/true/on` 启用,默认 off;启用后下面三个参数生效) | +| `BILI_SESSION_GC_INTERVAL_MS` / `BILI_SESSION_GC_MAX_AGE_DAYS` / `BILI_SESSION_GC_MAX_TOKENS` | 会话 GC 参数(默认 1h / 7d / 1M tokens) | +| `BILI_SESSION_RESIDENT_MAX_BYTES` | sessions.residentMaxBytes,512 MiB 软上限(#2803) | +| `BILI_SESSION_WARM_MAX_BYTES` | warm 解码字节上限,64 MiB(#2803) | +| `BILI_PERSIST` | `=0` 关闭持久化(ephemeral/test) | +| `BILI_PERSIST_DEBOUNCE_MS` | persist.debounceMs,500 | +| `BILI_PERSIST_EPERM_ALERT_THRESHOLD` / `BILI_PERSIST_EPERM_ALERT_REPEAT_MS` | EPERM 告警阈值 5 / 重复间隔 0(不限次) | +| `BILI_PERSIST_TAIL_TOKENS` | persist.tailTokens,16384(0 禁用消息持久化,#401) | +| `BILI_PERSIST_ZSTD` | `=1/true` 启用 zstd 压缩持久化(owner 决定 #1080,默认 off) | +| `BILI_SESSIONS_DIR` | 状态目录重定位 | + +### 2.5 诊断 + +| 变量 | 一句话用途 | +|------|-----------| +| `BILI_DUMP_4XX` | `=1` 或 diagnostics.dump4xx:4xx 时落盘精确重放 body(#762/#276,默认 off) | +| `BILI_DUMP_4XX_MAX_BYTES` | dump 单文件上限,2 MiB(floor 1 KiB) | +| `BILI_DUMP_MAX_TOTAL_BYTES` | dump 总量上限,默认 off(null) | +| `BILI_DUMP_MAX_AGE_DAYS` | dump 年龄上限,默认 off(null) | +| `BILI_FAKE_BUF_CAP` | fake-completion 缓冲上限,16 MiB | +| `BILI_CONFLICT_SCAN` | thirdparty-scan 冲突扫描开关 | + +### 2.6 安全 / 运维通道 + +| 变量 | 一句话用途 | +|------|-----------| +| `BILI_ENCRYPTION_KEY` | sidecar 加密密钥(hex/base64 恰好 32 字节,#708;设置期间 sidecar 拒绝打开明文) | +| `BILI_CONFIG_FILE` | `--config` 等价物 | +| `BILI_CLIENT_BIN` | native 可执行文件覆盖(probe 契约同 launcher) | +| `BILI_CONVERSATION_ID` | codex spawn 期会话注册(CLAUDE_CODE_SESSION_ID 优先) | +| `BILI_MCP_PROXY` | codex MCP shell 用的 proxy origin(含发现回退) | +| `BILI_MCP_DEFAULT_ORIGIN` | zcode MCP entry 默认 origin(http://127.0.0.1:8787) | +| `BILI_MCP_NO_ORPHAN_ADOPT` | `=1` 多宿主共享一个 proxy 时禁用孤儿 adopt | +| `BILI_UPSTREAM_PROXY` / `BILI_UPSTREAM_PROXY_MODE` | 上游出口代理及 manual/auto 模式(默认直连是有意设计,#346/#357) | +| `BILI_TUNNEL_ALLOWED_HOSTS` | 远端隧道允许清单(host / host:port) | +| `BILI_ZONE_PORT` | USER zone 基址覆盖(#1660) | +| `BILI_CLAUDE_NATIVE_PORT` / `BILI_ZCODE_PORT` | 显式 zone 端口覆盖(strict-port 语义,#1660) | +| `BILI_ATTACH_EVIDENCE_GRACE_MS` / `BILI_ATTACH_HEALTH_DEADLINE_MS` | native attach 证据宽限窗 / 健康截止窗 | +| `BILI_DSH_BIN` / `BILI_PI_BIN` | dsh / pi 可执行文件覆盖 | +| `BILI_PLUGIN_AGENT` | `--plugin` 目标 agent 选择(默认 claude) | +| `BILI_LOG_MASK_HOSTS` | 日志主机名掩码(默认开;`=0` 本地调试退出) | +| `BILI_ALLOW_PRIVATE_HTTP_PROVIDERS` | 私有 http provider 放行(CGNAT 100.64/10 恒拒) | +| `BILI_MITM` | MITM 功能总开关(env > 文件 mitm.enabled > 默认开;`=0` 整体关闭;与内部通道 `BILI_MITM_HOSTS`/`BILI_MITM_DOMAINS` 不同) | +| `BILI_CLAUDE_UPSTREAM` | direct-URL 模式下绕过预置 relay 的上游 URL(OAuth 订阅流量需 MITM 模式) | + +### 2.7 更新器 / 公告 + +| 变量 | 一句话用途 | +|------|-----------| +| `BILI_UPDATE_REGISTRY` | registry base URL 覆盖(完整 URL) | +| `BILI_UPDATE_CHECK_INTERVAL_MS` | update.checkIntervalMs 覆盖(#2030) | +| `BILI_ADVISORY_CHECK` | 公告检查开关(默认 ON;文件 advisoryCheck:false 退出) | +| `BILI_ADVISORY_URL` | 公告文档 URL 覆盖 | +| `BILI_RELEASE_NOTES_CHECK` | 发布说明检查(#1870,默认 ON) | +| `BILI_RELEASE_NOTES_URL` | 发布说明 URL 覆盖 | + +### 2.8 图像计费 / zcode 兼容 + +| 变量 | 一句话用途 | +|------|-----------| +| `BILI_IMAGE_BILLING` | `=bytes` 走字节替代路线 | +| `BILI_IMAGE_TOKEN_CAP` | 单图成本上限 live-read(#1843 L3) | +| `BILI_ZCODE_ROUTE` | zcode 路由兼容逃生舱(`=none` / kill-switch → 降级路由) | +| `BILI_ZCODE_SIGNING_FIXED` | zcode 固定签名 | + +## 3. 非环境变量的 BILI_* 标识符(勿与上表混淆) + +以下共享 `BILI_` 前缀但是代码常量/工具表/错误码,不是环境变量,不在 CI 检查范围: + +`BILI_ACP_HANDLED__`(哨兵 Error 字符串)、`BILI_ACP_TOOLS_{ANTHROPIC,GOOGLE,OPENAI,RESPONSES}[_NO_RANGE]`、`BILI_ACP_READONLY_TOOLS_RESPONSES[_NO_RANGE]`、`BILI_DECOMPRESS_TOOL{,_OPENAI,_RESPONSES,_GOOGLE}`、`BILI_DECOMPRESS_IMG_{ANTHROPIC,GOOGLE,OPENAI,RESPONSES}`、`BILI_SEARCH_CONTEXT_TOOL{,_OPENAI,_RESPONSES,_GOOGLE}`(compress-tool.ts 工具表常量)、`BILI_DSH_PACKAGE`(="billion-context")、`BILI_HOP_HEADER`(="x-bili-hop")、`BILI_INJECTABLE_TOOL_NAMES`(Set)、`BILI_OVERLAY_BUSY`(错误码)、`BILI_PASSTHROUGH_HEADER`、`BILI_PLUGIN_BYPASS_HEADER`(="x-bili-plugin-bypass")、`V2_BILI_TOOLS` / `BILI_TOOLS`(opencode-v2.ts)、`BILI_TOOL_NAMES`(Set,side-request.ts)、`MCP_BILI_TOOL_PREFIX`(="mcp__bili__")、`BILI_TUNNEL_HEADER`(="x-bili-tunnel")。 + +## 4. 退役模块盘点 + +| 模块 / 标记 | 现状 | 退役条件 | 跟踪 | +|-------------|------|----------|------| +| `src/persona-anchor.ts`(179 行) | 生产路径已迁 v2.2(session-resolve),但 **src/session-resolve.ts 自身仍 import 它**,另有 src/plugin.ts、src/server/side-request.ts 及 4 个测试套件(dsh-persona-continuity、issue2601-model-drift-absorption、issue2601-persona-fork-lineage、issue2944-neutral-skeleton)引用做断言 | #2989 孪生化完成后整文件删除(注意 session-resolve.ts 的依赖也要切掉) | #2989 | +| `src/fold-reconcile.ts` legacy 对账路径 | 在用(`BILI_FOLD_RECONCILE` 默认 repair,见 §1) | 增量车道 #3248 落地后评估去留 | #3248 | +| `TODO(#NNNN)` 标记 | 全仓(src/、kernel/src/、pi-subagents/src/)**零命中**——不存在 issue 编号型 TODO | — | 无需跟踪 | +| deprecated 标记 | 均为小项:① acp.json delegate 配置弃用(运行时警告"future release 移除",prompt←delegatePrompt 改名,pi-subagents.ts:153/163、config.ts:1502)② config.ts:1713 某章节的 deprecated fallback(仅在章节缺失时读)③ `minCompressRangeChars` 是 `minCompressRange` 的弃用别名(compress-settings.ts:50/223)④ claude-native-bootstrap.ts:263 关于 ps/wmic 的系统 API 注释(非 bili 代码) | 各自随所属特性演进;无批量行动 | — | + +## 5. 卫生记录 + +- **2026-10-15 远端分支卫生(#3249 执行)**:删除 origin 已合并远端分支 **1394 条**(1386 条 = 已合并 PR 的同仓 head 分支 + 8 条 = 完全并入 master 但无对应 PR 记录:`2026-08-08_release-v0.1.14`、`2026-09-26_opencode-zen-mitm`、`2026-09-30_responses-side-compaction`、`2026-10-04_plugin-fork-context-provenance`、`2026-10-13_lastmessages-tabling`、`chore/pages-enablement`、`fix/codex-custom-tool-call-text-protocol`、`revert-3189-pages-enablement`)。删除前核对:与 open PR head 交集为空。删除后 origin 剩 361 个 head(其中 128 条为 open PR 分支、201 条 closed-unmerged 且未并入 master、30 条无 PR 未并入 = 废弃工作,均不动)。另执行一次 `git worktree prune` 清掉失效 worktree 登记。 +- **机器侧纪律(owner 手工做过,记录备查,不做自动化)**:2026-10-15 手工清理 11 个陈年 bili 进程(全部零活跃连接才杀)/ /tmp 清 2.2GB / master-wt worktree 421MB / 20 个已合并本地分支 / index.db 旧归档。**杀进程保持人工**(需要人眼判断连接归属,自动化风险大于收益),每次大版本装机后人工过一遍。 diff --git a/reference/env-vars.md b/reference/env-vars.md index 177d4e09b0..6f94e243fb 100644 --- a/reference/env-vars.md +++ b/reference/env-vars.md @@ -13,6 +13,12 @@ precisely so knobs don't bloat the environment. Precedence everywhere: **env var > config file > built-in default**, resolved in exactly one place (`src/knobs.ts`). +> **Lifecycle vs. existence.** This file governs whether a knob MAY be an env var. +> Whether an existing one is TEMPORARY (a cap / kill-switch / experiment with a +> release condition) is tracked in [`LIFECYCLE.md`](../LIFECYCLE.md) (#3249) — +> every `BILI_*` read in `src/` must be registered there; CI enforces it via +> `scripts/lifecycle-ledger-guard.mjs`. + ## Where a knob lives | Category | Home | Examples | diff --git a/scripts/lifecycle-ledger-guard.mjs b/scripts/lifecycle-ledger-guard.mjs new file mode 100644 index 0000000000..613e1ca30f --- /dev/null +++ b/scripts/lifecycle-ledger-guard.mjs @@ -0,0 +1,134 @@ +#!/usr/bin/env node +// lifecycle-ledger-guard.mjs — #3249: every BILI_* env var read from src/ must be +// registered in LIFECYCLE.md (§1 transition ledger or §2 permanent registry). +// +// node scripts/lifecycle-ledger-guard.mjs # CI mode: exit 1 on unregistered vars +// node scripts/lifecycle-ledger-guard.mjs report # always exit 0, print findings +// +// POSTURE (same as config-surface-guard.mjs): an env var read in src/ but ABSENT from +// LIFECYCLE.md is a FAILURE — a new switch without a lifecycle entry is exactly the +// rot this ledger exists to stop. A ledger entry with no live reader is a NOTICE +// only: dynamic names (BILI_ROLLOUT_), branches not yet on master +// (BILI_ANTHROPIC_THREADS_INJECT lives in open PR #2888) and retired-but-still-warned +// reads legitimately lag the code. +// +// Extraction covers every way src/ names an env var: direct property reads, bracket +// reads, `env.X` param reads, and quoted name literals — including helper-call sites +// like tInt("BILI_X", fileValue) in src/knobs.ts that never touch process.env on the +// same line. Names in §3 (non-env identifiers sharing the BILI_ prefix) are exempt +// from the missing/stale checks by section, not by name list. + +import { readFileSync, readdirSync, statSync } from "node:fs"; +import { join, dirname, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const repoRoot = resolve(__dirname, ".."); +const SRC_DIR = join(repoRoot, "src"); +const LEDGER = join(repoRoot, "LIFECYCLE.md"); + +const DIRECT = /process\.env\.([A-Z][A-Z0-9_]*)/g; +const BRACKET = /process\.env\[\s*["']([A-Z][A-Z0-9_]*)["']\s*\]/g; +const PARAM = /\benv\.([A-Z][A-Z0-9_]*)/g; +const QUOTED = /["'](BILI_[A-Z0-9_]+)["']/g; + +function stripComments(src) { + return src + .split("\n") + .map((line) => { + const hash = line.indexOf("//"); + if (hash >= 0 && !line.slice(0, hash).match(/["'`]/)) return line.slice(0, hash); + return line; + }) + .join("\n"); +} + +function walk(dir, out = []) { + for (const name of readdirSync(dir)) { + const p = join(dir, name); + const st = statSync(p); + if (st.isDirectory()) walk(p, out); + else if (name.endsWith(".ts")) out.push(p); + } + return out; +} + +function extractEnvNames() { + const names = new Set(); + for (const file of walk(SRC_DIR)) { + const text = stripComments(readFileSync(file, "utf8")); + for (const re of [DIRECT, BRACKET, PARAM]) { + re.lastIndex = 0; + let m; + while ((m = re.exec(text))) { + if (m[1].startsWith("BILI_")) names.add(m[1]); + } + } + QUOTED.lastIndex = 0; + let qm; + while ((qm = QUOTED.exec(text))) names.add(qm[1]); + } + return [...names].sort(); +} + +// Tokens in §3 are non-env identifiers: exempt from the stale notice by section. +function splitLedgerTokens(text) { + const s3Start = text.indexOf("## 3."); + const s3End = s3Start >= 0 ? text.indexOf("## 4.", s3Start) : -1; + const s3Slice = s3Start >= 0 ? text.slice(s3Start, s3End > s3Start ? s3End : undefined) : ""; + const rest = s3Start >= 0 ? text.slice(0, s3Start) + (s3End > s3Start ? text.slice(s3End) : "") : text; + const tok = (s) => [...new Set([...s.matchAll(/BILI_[A-Z0-9_]+/g)].map((m) => m[0]))]; + return { active: tok(rest), exempt: tok(s3Slice) }; +} + +const isPrefixToken = (t) => t.endsWith("_"); +const isPlaceholder = (t) => t.includes("<"); + +function runChecks() { + const ledgerText = readFileSync(LEDGER, "utf8"); + const { active, exempt } = splitLedgerTokens(ledgerText); + const readers = extractEnvNames(); + + const exemptSet = new Set(exempt); + const missing = readers.filter((name) => { + if (exemptSet.has(name)) return false; // §3 identifier quoted somewhere in src/ + if (active.includes(name)) return false; + // A registered prefix token (e.g. BILI_ROLLOUT_) covers its dynamic family. + return !active.some((t) => isPrefixToken(t) && name.startsWith(t)); + }); + + const readerSet = new Set(readers); + const stale = active.filter( + (t) => !isPrefixToken(t) && !isPlaceholder(t) && !readerSet.has(t), + ); + + return { readers, missing, stale, exempt }; +} + +function main() { + const mode = process.argv[2] ?? "check"; + const { readers, missing, stale, exempt } = runChecks(); + console.log(`lifecycle-ledger: ${readers.length} BILI_* env names read from src/, ${activeCount(readers)} ledger entries active, ${exempt.length} §3 identifiers exempt`); + if (stale.length) { + console.log(`notice: ${stale.length} ledger entr${stale.length === 1 ? "y has" : "ies have"} no live reader in src/ (expected for dynamic/unmerged/retired names): ${stale.join(", ")}`); + } + if (missing.length === 0) { + console.log("OK: every BILI_* env var read from src/ is registered in LIFECYCLE.md"); + return; + } + console.error(`FAIL: ${missing.length} BILI_* env var(s) read from src/ but NOT in LIFECYCLE.md:`); + for (const n of missing) console.error(` - ${n}`); + console.error("Add them to §1 (transition, with release condition) or §2 (permanent) of LIFECYCLE.md."); + if (mode !== "report") process.exitCode = 1; +} + +function activeCount(readers) { + try { + const { active } = splitLedgerTokens(readFileSync(LEDGER, "utf8")); + return active.filter((t) => !isPlaceholder(t)).length; + } catch { + return 0; + } +} + +if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main();