docs(pm-dispatch): 增补 2026-08-03 全天运行沉淀的八条 PM 操作经验 (#4882)

[os-zhuang]

Fixes #4882

把 2026-08-03 主 backlog PM 会话跑完 12 单合并 + 8 单新立后沉淀的八条操作经验写进 .claude/skills/pm-dispatch/SKILL.md,让下一个 PM 会话不用重新踩。纯插入,不重写既有章节:git diff --stat 为 134 insertions(+),既有行删除数为 0。

落点与内容

step 2 分诊 — 新增「无生产者」形状的识别规则:声明了、消费端有读取、gate 全绿,却没有任何生产者写值;类型系统与 lint 只验消费方,所以这类洞在全绿下长期存活。当日五次命中(#4704 / #4837 / #4839 / #4862 / #4867)。遇到 declared ≠ enforced 类 issue,分诊时先问「生产者在哪」,答案通常就是根因,并会在派发前改掉 issue 的作用域与 domain:* 标签。

step 3 选批 — 同文件 issue 严格跨轮串行,并明确推迟 ≠ 搁置:#4820 的 dev 查出 #4821 正文建议的 JSON.stringify 键法会改掉类型强制语义、引入静默新缺陷,这条警告与 Blocked-by: 在 #4820 复核完成的同一轮就钉到了 #4821 上 —— 被推迟的 issue 在每次 sweep(包括别的 PM 的)里看起来都是可派发的,你知道的坑不写上去就等于不存在。

step 5 派发 — 两条:

1. 「main 当天已动过同一文件」要写进派发词(现有 Stale-premise check 防的是 issue 过期,同日变体是另一回事):phoneOtp.cooldownSeconds 配成大于 1 小时会被静默截断 —— OtpSendGuard 的历史 TTL 硬编码 1 小时 #4808 派发前 fix(plugin-auth): 每号码 OTP 发送预算改用惰性解析的共享计数存储 —— 多节点下不再按节点数倍增 (#4790) #4806 刚改过同一 guard,compareTo drops every measure-scoped filter, so <measure>__compare silently reports a different measure than the column beside it #4820 派发前 fix(service-analytics): 按聚合种类填充「查询从未报告过的分组」,并补上 compareTo 这一道接缝 (#4708) #4822 刚改过同一文件,两单都因派发词点名而避开返工。
2. 新增 #### Handing off an interrupted dev(worktree 接手协议):/compact 与宿主中断会把运行中的子 agent 连同挂起的工具调用一并杀死(@objectstack/verify 的 bootStack 与 qa dogfood 同样用裸 import 解析 cloud 私有包 —— 与 cloud#1013 同一缺陷类 #4700 / hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 停在同一秒),agent 不可恢复但 worktree/分支/提交完好。接手 = 派新 agent + 明确「worktree 已存在,⛔ 不要新建」+ 先通读既有改动再逐块决定取舍 + 补跑从未跑过的验证 + 认领与分支不变。两单按此接手后均一次通过复核。

step 7 复核 — 两条:

1. dev 证伪 issue 或派发词是好报告的标志,照单全收的报告反而要多看两眼(phoneOtp.cooldownSeconds 配成大于 1 小时会被静默截断 —— OtpSendGuard 的历史 TTL 硬编码 1 小时 #4808 / 内核的插件 init/start 超时守卫定时器从不清除也不 unref —— 每个进程在工作结束后还要空转 startupTimeout(CLI 挂 ~120s 才退出) #4813 / [metadata] nextEventSeq() 把驱动读失败也当成「表还没建」,静默从 1 重新发号 —— #4632 同形,机械检查覆盖不到 #4825 / 每号码 OTP 发送预算(#2780)也只在进程内计数 —— 与 #4772 的限流洞同类,多节点下可按节点数倍增 #4790);PM 被纠正时公开认账,错误归因另立 issue(os migrate 成功时退出码是随机非零值(208/171/176/163/62…),--version / --help 却干净退出 0 #4873)而不是静默丢弃。
2. PR diff 里的 +0/-0 未必是空文件 —— 文件含 NUL 字节时 git 判为二进制。fix(service-analytics): compareTo 带上 measure 自己的 filter,__compare 列不再是另一个 measure (#4820) #4870 的 347 行测试文件即如此,PM 一度误判为占位空文件。判据落在 blob 不落在 diff;修法写转义 \\u0000(反斜杠 + u0000),不写裸字节。

新增 ## Operational notes(实测坑位)(接在 State model 之后,中文,与 Domain lanes 节先例一致) — 四条队列/平台层结论,共同点是「判据取命令输出,不取 API 字段字面值,也不取本地工作树现状」:

• 判断 PR 是否在合并队列看 gh-readonly-queue/* 分支,不看 auto_merge(入队后该字段回落为 off,零信息量);
• 队列踢出先认签名再决定重投(flaky: spec/src/cloud/tenant.test.ts 的 #4739 导出面用例贴着 5s 超时 —— 今晚已两次把不相干的 PR 踢出合并队列 #4796 连踢五个无关 PR,原样重投全过);但止血 PR fix(spec): 给 packages/spec 的 vitest 设 testTimeout 60s —— 止血,不再把无关 PR 踢出合并队列 (#4850) #4856 合入后同签名再现即新问题,禁止条件反射式重投;
• GraphQL 配额 5000/时 极易打满(当日三次归零,峰值 10402/5000),读与评论走 REST,写操作排队并轮询 rate_limit 的 resources.graphql.remaining,复核意见先用 REST 发出不等配额;
• 核验 main 的事实一律 git grep ... origin/main / git show origin/main: —— 共享检出可能落后数十提交(当日 PM 与一名 dev 都在落后 63 提交的树上 grep 出假阴性),这条同时写进派发词。

验收自检

验收项	结果
六个关键词可检索	生产者 ×2、worktree 接手 ×1、gh-readonly-queue ×2、rate_limit ×2、origin/main ×9、nul ×5(不区分大小写)
八条(A1 A2 B1 B2 C1 C2 D1 D2 D3 D4)全部落地	全部当日证据编号均在文中命中
不破坏既有结构与内容	134 insertions(+), 0 deletions,既有行删除数 grep 得 0
changeset 与 #4824 同形	空 frontmatter(--- / ---),不发布任何包 —— 与 .changeset/pm-dispatch-domain-lanes.md 首 12 字节逐字节一致

门禁

node scripts/check-nul-bytes.mjs → check-nul-bytes: OK (2986 tracked source file(s), no raw NUL bytes).

值得记一笔:写 C2 那条时编辑工具真的把转义写成了裸 NUL 字节(SKILL.md 第 626 行),先被控制字符扫描(grep -naP '[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f]')抓住、按字节改写为转义文本后才提交 —— 该条经验在自己身上原样复现了一次;本 PR 正文首版的同一处也被 GitHub 吃掉过一次,现已修正。eslint 不覆盖 md(配置仅 **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} 等 JS/TS glob),check:doc-authoring 的 ROOTS 是 skills / content,不含 .claude/,故无其他适用门禁。

改动面严格限于 .claude/skills/pm-dispatch/SKILL.md + 一个 changeset,未碰 .claude/agents/os-dev.md、packages/**、顶层 skills/**、content/docs/**。

🤖 Generated with Claude Code

https://claude.ai/code/session_015Br2xsJsczFsTR9bvbh2Ny

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 3, 2026 1:11pm