docs(api): trial 配额两个数字与真实 0.8.8 不符;一处行号 pin 已漂到无关代码

[vansin]

docs(api): 修正 trial 档的两个配额数字,并把漂掉的行号 pin 改成函数名

1. trial limits 有两个数字是错的

文档 GET /api/license 的 trial 样例写:

"limits": { "max_agents": 5, "max_networks": 1, "max_tasks_day": 100 }

真实 0.8.8(干净容器 bunx --bun @sleep2agi/commhub-server@0.8.8,全新库,type=trial):

"limits": { "max_agents": 5, "max_networks": 3, "max_tasks_day": 500 }

max_networks 1→3、max_tasks_day 100→500。源码侧确认不是环境差异 ——
server/src/db.ts 的 licenses 表 schema 默认就是:

max_agents INTEGER DEFAULT 5
max_networks INTEGER DEFAULT 3
max_tasks_day INTEGER DEFAULT 500

而 /api/license 直接读这张表(server.ts:888)。

这条会影响用户决策:照文档看会以为试用期只能建 1 个网络、每天 100 个任务。

2. 同页一处行号 pin 已经漂了

第 396 行(en 398)说 plan quota "在 auth.ts:184-189 enforced"。
实测 auth.ts:184-189 现在是发 user token 的代码,与配额无关;
真正的关卡在 createNetwork() 里(QUOTAS 表 + max_networks_owned 判定)。

根因是钉行号 —— 行号必然漂。改成钉函数名。
(RELEASE-SOP 里 R367 对 sdk-deep-dive.md 做过同样的动作:取消行号 pin。)

原文里「free plan 默认 max_networks_owned=2」核过,是对的,保留。

范围

只改 docs-site 的 zh + en 两个文件,不动产品源码。
探测全部在容器里做,生产只做了只读 curl。

[vansin]

接受这条 MINOR —— 是我措辞过宽

审查意见指出中文的「当前 quota 仍在 createNetwork() 里 enforced」过宽,会把两层混成一层。这条成立,我认。

我的本意只覆盖建网门,但句子里 quota 是单数、无限定,读者完全可能理解成「trial 的 max_agents / max_networks / max_tasks_day 三个字段都在这个函数里 enforce」—— 而我没有验过后两者。en 那侧因为保留了 free max_networks_owned=2 反而不易误读,所以这是 zh/en 不对称,不是两边都错。

拟采纳的替换(来自审查意见,我未改动):

建网配额在 auth.ts 的 createNetwork() 按 plan 的 max_networks_owned 校验(free=2,admin 豁免);trial limits 默认见 licenses 的 5/3/500,与行号 184–189 发 token 无关。

现在不改分支 —— 本 PR 在冻结中(我此前反复改动导致复审无法收口,已停手)。这条记在这里,等复审收口后随其它意见一并落。

另外确认一条 NOT COVERED 的定性:作者(我)那句 0.8.8 干净容器动态探测,审查方判定「仅作者声明、无独立日志、不得当独立复验证据」是对的。这里数字的正确性应当只由 base 的 db.ts:695-700 默认值支撑,不该由我那次探测背书 —— 两者结论一致纯属应该如此,不构成互证。

[vansin]

自审(本 PR 至今零行内审查):把 5/3/500 这条链路从头验到尾,成立;顺带关掉一条 NOT COVERED

本 PR 是三条从没被自动审查器碰过的最后一条(#823 已自审出一条 fail-open 并修,#800 自审为无发现)。

文档 PR 的生死线就是数字对不对,所以直接走源码。

完整链路(三跳,全部命中)

① 建表默认值 — server/src/db.ts:698-700

max_agents    INTEGER DEFAULT 5,
max_networks  INTEGER DEFAULT 3,
max_tasks_day INTEGER DEFAULT 500,

② trial 插入不指定这三列 — server/src/db.ts:713

INSERT INTO licenses (id, license_key, type, expires_at)
VALUES (?1, ?2, 'trial', datetime('now', '+14 days'))

只有四列,三个配额列缺席 → 取①的默认值。

(对照:server/src/server.ts:916 的 pro 插入是显式给值 50, 10, 10000 —— 两条路径分开,不会互相污染。)

③ REST 原样回传 — server/src/server.ts:888 → :899

"SELECT type, expires_at, max_agents, max_networks, max_tasks_day FROM licenses ORDER BY created_at LIMIT 1"
…
limits: { max_agents: license.max_agents, max_networks: license.max_networks, max_tasks_day: license.max_tasks_day },

逐字段透传,没有任何变换、覆盖或兜底。

结论

文档里的 "limits": { "max_agents": 5, "max_networks": 3, "max_tasks_day": 500 } 对,且是端到端可追的,不依赖任何运行时观察。

这关掉了一条 NOT COVERED

此前的窄审留了这条:

NOT COVERED:trial JSON 与 REST 响应路径、作者 0.8.8 动态探测(未复验)

现在 REST 响应路径这一支已验。

值得说清楚的是用什么验的:不是重跑我自己那次 0.8.8 动态探测 —— 审查方判定「仅作者声明、无原始日志,不得当独立复验证据」是对的,而我再跑一次仍然是同一作者侧,不会变得更独立。走源码链路才是能独立复现的那条路:任何人拿这三个行号就能自己走一遍。

仍未覆盖(不夸大)

• ORDER BY created_at LIMIT 1 取的是最早那行 license。文中数字描述的是全新安装的状态;若一台机器上后来激活过 pro,首行仍是 trial,但这属于超出本文档范围的情形;
• createNetwork() 是否 enforce max_agents / max_tasks_day —— 仍未验。这也正是此前那条 MINOR(中文措辞过宽)指向的同一处,我已接受并记录,待收口后一并落。

[vansin]

最后一条 NOT COVERED 验完了,而结论比原来那条 MINOR 更重

此前留的是:

NOT COVERED:createNetwork 是否 enforce max_agents / max_tasks_day

验完:不但没 enforce,这三个数在整个仓里没有任何人 enforce。

① createNetwork() 只认一个字段

// server/src/auth.ts:313-317
const QUOTAS: Record<string, { max_networks_owned: number; max_networks_joined: number }> = {
  free:  { max_networks_owned: 2,  max_networks_joined: 3 },
  pro:   { max_networks_owned: 10, max_networks_joined: 20 },
  admin: { max_networks_owned: Infinity, max_networks_joined: Infinity },

QUOTAS 只有两个字段,max_agents / max_tasks_day 根本不在这个结构里。createNetwork()(:320)只比 max_networks_owned(:325-327)。

② 三个 license 字段全仓只被「读出来给人看」

引用点	做什么
server/src/server.ts:899	塞进 /api/license 响应
agent-network/bin/cli.ts:12819	打印:Soft limits: agents=…, networks=…, tasks/day=…

除此之外没有比较、没有拒绝、没有门。产品自己的 CLI 就把它们叫 Soft limits。

(扫描范围:origin/main 全仓 *.ts / *.tsx,排除 *.test.*。auth.ts 里那几处 max_networks 是另一个东西 —— plan QUOTAS 的 max_networks_owned,不是 licenses 表的列。)

所以原来那条 MINOR 说轻了

原判是「中文措辞过宽,易把 license trial 的 5/3/500 与 free plan 建网门 max_networks_owned=2 混成一层」。方向对,但实际情况更尖:

这两组数不只是"层不同",而是一组生效、一组根本不生效,而且:

• license 说 max_networks: 3,plan 门实际按 max_networks_owned: 2 拒绝 —— 两个数不一样,读者按 3 去建第 3 个网络会被拒;
• 文档把 "limits": {5, 3, 500} 摆在讲已生效配额门的段落旁边,读者几乎必然把它读成"这就是被 enforce 的限额"。

这跟文档自己已经点名的 max_members(dormant)是同一类,只是这三个还没被点名。

建议改法(比之前那版更准)

/api/license 的 limits(trial 默认 max_agents=5 / max_networks=3 / max_tasks_day=500)是软限额:服务端只存储和返回,不做任何拦截(CLI 里也直接标作 Soft limits)。真正会拒绝请求的是 plan 配额 —— auth.ts 的 createNetwork() 按 max_networks_owned 校验(free=2,admin 豁免)。注意两者的 networks 数字不同(3 vs 2),以实际生效的 plan 配额为准。

冻结中未改分支,与此前接受的那条 MINOR 一并待收口后落。

---

至此本 PR 的 NOT COVERED 只剩一条:ORDER BY created_at LIMIT 1 取最早那行 license,文中数字描述的是全新安装状态。这条我认为是文档范围的自然边界,不打算再收窄。

[vansin]

同一页上还有 4 个行号 pin 也漂了 —— 本 PR 修了一个,没扫同类

本 PR 的立意之一就是「原文钉的 auth.ts:184-189 已漂到发 token 的代码上,所以改钉函数名」。这个判断对。但同一个文件里还有 5 处 tools.ts:NNN 形式的 pin,逐个核完:全部漂了,一个都没命中。

文档位置	pin	声称那里有	origin/main 上实际是
rest.md:52	tools.ts:521	license_expired 仍 emit	// discovery (#337 extracts this field). "host_supervisor" = (daemon role 的 zod 注释)
rest.md:1542	tools.ts:286	chained_reply	network_id: z.string().max(200).optional(),
rest.md:1542	tools.ts:646	chained_reply	cpu_pct: processCpuPct,
rest.md:1545	tools.ts:571	new_message/broadcast 实际 payload	}],
rest.md:1545	tools.ts:911	同上	message_id: z.string().min(1).max(200),

真正的 license_expired 在 tools.ts:1265(if (license.expires_at < now) { … error: "license_expired" })。

其中一处特别值得指出来

rest.md:1545 的原句是:

旧 doc 在 new_message 上写过 message 字段、broadcast 上写过 {content, from} —— 都不对。verify [tools.ts:571 + 911] 实际 payload 以上表为准。

这句话的全部作用就是「别信旧文档,去这两个坐标自己核」—— 而这两个坐标核不了任何东西。 一条指向失效的验证指引,比没有指引更糟:它让人以为已经可以核实。

建议

按本 PR 已经确立的做法处理,不是更新数字,是改钉符号:

• tools.ts:521 → 钉 license_expired 这个错误码本身(它是唯一的,grep -n 'license_expired' server/src/tools.ts 一步到位);
• tools.ts:286/646 → 钉 chained_reply;
• tools.ts:571 + 911 → 钉 new_message / broadcast 的构造点符号。

理由和本 PR 对 auth.ts 的处理完全一样:行号每次重构都会漂,符号不会。

一条对我自己的批评

本 PR 发现了「行号 pin 会漂」这个问题,却只修了触发它的那一处。修了一个实例、没扫同一类,而同页另外四处一直是坏的。

这跟我这两天反复在别人和自己代码里查的是同一件事:发现一个形态之后,必须查它是不是模式。我在 #815 的清单里写过这条,自己在这条 PR 上没做。

冻结中未改分支,与前两条(MINOR 措辞、软限额)一并待收口后落。

[vansin]

@codex review

本 PR 至今零审查记录(自动审查器只在开 PR / 草稿转就绪 / 显式 @ 时触发,push 不触发)。这是第二次请求。

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Delightful!

Reviewed commit: 147a9f0ff9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[vansin]

三条一直停在「已接受」的意见,现在落地了(147a9f0f → a89372f2)

先说为什么拖到现在 —— 这是我自己造成的。

三条我在窄审后都写过「我认」,然后统一挂在「冻结中,待收口后落」。而**「收口」这个条件实际上从没到来**:本 PR 至今零审查记录,根本不存在会被打断的在途复审。

我设的延后规则,变成了阻塞我自己修复的东西。 而且它无声 —— 每次汇报里写「待收口后落」都像是在管理节奏,实际是九条同类意见(本 PR 3 条 + #803 3 条 + #801 3 条)在原地不动。

①② 措辞过宽 + 软限额定性(合并成一处改)

原文:「当前 quota 仍在 createNetwork() 里 enforced」。窄审说它把两层混成一层 —— 方向对,但实际更尖:

/api/license 的 limits(trial 5/3/500)  →  全仓无人 enforce
  server.ts   塞进响应
  cli.ts      打印成 "Soft limits"
  除此之外没有比较、没有拒绝、没有门

真正会拒绝建网的  →  plan 配额 max_networks_owned(free=2)

两者的 networks 数字还不同(3 vs 2) —— 读者按 3 去建第 3 个网络会被拒。中英两侧都补上了这个区分。

③ 行号 pin 全部已漂

该页的 tools.ts#L521 / #L286 / #L571 全部指不到声称的东西(#L521 指到 daemon role 的 zod 注释,真正的 license_expired 在别处)。

按 #831 对参考页的结论(钉符号不钉行号),去掉误导的行号锚点 —— 链接指向文件是准的,而符号名(license_expired / chained_reply / payload)本来就写在句子里。中英各 3 处,共 6 处,改后残留 0。

---

一句

我这两天反复在写「接受一条意见和实施它是两件事」。这条 PR 是那句话的完整代价:三条正确的意见,在「已接受」状态里躺了整整一天。

剩下六条同类(#803 的 Bun 未钉死 / 安全套件顺序 / --rm 丢报告,#801 的 ②⑥⑤)我会按同样方式逐条落,不再等一个不会到来的「收口」。

[vansin]

提醒:这个 PR 与 #843(文档行号 pin 的下限门)有一处硬耦合

我在 #843 里加了 docs/doc-source-pins-baseline.txt,记录已知失效的行号 pin,语义是只许缩小:某条对应的引用从文档里消失了,门会要求把它从基线里删掉,不删就红。

这个 PR 恰好会让基线里的条目消失:

• 删掉了引用 tools.ts#L521 / tools.ts#L571 / auth.ts#L184 的那几行

所以合并顺序上有一个动作项:

• 如果 ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 先合,这个 PR 里需要顺带删掉基线中对应的条目;
• 如果这个 PR 先合,ci(test831): 文档站行号 pin 的下限门(守住不再变多,不解决 #831) #843 的基线重新生成一次即可(那几条本来就不会进去)。

我在 #845 的树上模拟跑过,完整输出贴在 #843 的这条评论。

不做的话,表现是「一个只改文档的 PR 把 CI 弄红了」,而红的原因看起来跟它毫无关系 —— 这条提醒的价值就在这里。

[vansin]

补充上一条提醒:现在不用手工数该删哪几条了 —— 合并后跑 python3 scripts/check-doc-source-pins.py . --write-baseline 即可,它只许缩小(出现新失效会拒绝写)。实现与断言见 #843 的这条评论。

[vansin]

合了。四条说法我逐个从源码验了,全部成立,而且其中一条比 PR 说得还准。

① 三个数字

$ git show origin/main:server/src/db.ts   (licenses 表)
    max_agents    INTEGER DEFAULT 5
    max_networks  INTEGER DEFAULT 3
    max_tasks_day INTEGER DEFAULT 500

文档原样例写的是 {max_agents:5, max_networks:1, max_tasks_day:100} —— 后两个都错。改成 5/3/500 与建表默认值逐字一致。

② auth.ts:184-189 确实漂了,而且漂到了很误导的位置

$ git show origin/main:server/src/auth.ts | sed -n '182,190p'
  // Issue a NEW user token — do NOT rotate/invalidate existing ones. Each
  // login (cli, dashboard, second machine) gets its own row so they don't
  // kick each other out of session.
  const userToken = generateUserToken();

那是发 token 的代码,和网络配额毫无关系。 而真正的配额在:

auth.ts:314  const QUOTAS = { free: { max_networks_owned: 2, ... }, ... }
auth.ts:326  if ((ownedCount?.cnt || 0) >= quota.max_networks_owned) {

🔴 这类漂移比「指向空行」更坏:它指向一段看起来很正经、也确实在讲鉴权的代码 —— 读的人容易以为自己找到了,然后基于错的地方推理。改钉函数名是对的。

③ 「软限额 vs 真配额」这一段是本 PR 最有价值的部分

它指出 /api/license 的 limits(max_networks=3)和真正拦截建网的 plan 配额(max_networks_owned=2)是两回事,而且数字不同。

我验了两边:db.ts:699 默认 3,auth.ts:315 free 是 2。确实是 3 vs 2。

也验了「软」这个说法:CLI 自己就把它印成 Soft limits:

cli.ts:13117  console.log(`    Soft limits: agents=${lim.max_agents}, networks=${lim.max_networks}, …`)

⇒ 一个用户看到 max_networks: 3、建到第 3 个被拒,会以为是 bug。 两个数字都真实存在、都在 API 里露出、只有一个会拦人 —— 而在这个 PR 之前,文档只说了会拦的那个的错误行号。

④ 其余几处行号 pin 去掉 #L 锚点

tools.ts:521 / 286 / 571 / 911 保留在行内文本里(说明当时的位置),但链接不再带 #L —— 与今晚 #857 / #851 / #834 定下的做法一致:指向当前代码的引用不钉行号,历史陈述钉提交。

[vansin]

合并时红了三轮,三次都是这道门在正确工作

① 基线残留 3 条 —— 本 PR 把它们的 #L 去掉了,于是不再是「文档里的失效行号 pin」。只删这 3 行,断言 removed=3 added=0;没有用 --write-baseline(整份重生成会把新出现的坏 pin 一起洗白)。

② 分母预期 15→11 / 35→28 —— 逐条数得出来:tools.ts#L521/#L571/#L286 各 ×2、auth.ts#L184 ×1 = 唯一 4 个 / 出现 7 处。15−4=11,35−7=28,files 仍 106。
🔴 关键佐证:diff 的 + 侧一个 #L 都没有 ⇒ 净减少,不是「挪了个位置」。如果 + 侧也有,数字一样但含义相反。

③ 🔴 L7 静默死 —— 日志最后一行是造场景的输出,之后直接 exit 1,stderr 一个字都没有。

本地 set -x 追到确切位置:

+++ grep -cv '^\s*#\|^\s*$' docs/doc-source-pins-baseline.txt
++ BL_AFTER=0
(到此为止)

下一行是 [[ 0 -lt 1 ]] || fail …,本该通过。真正原因在赋值本身:

grep -c 在计数为 0 时退出码是 1,而那一段 set -e 是开着的 ⇒ VAR=$(grep -c …) 静默终止整个脚本。

而计数为 0 恰恰是这道门「清干净了」才会出现的状态 —— 本 PR 把基线从 4 条清到 1 条,L7③ 再清掉最后 1 条,BL_AFTER 就是 0。

🔴 今晚第三次同一形状:门因为自己起了作用而坏掉。 前两次是 L5①(写死 == 1 只在「一条钉 SHA 的引用都没有」时成立)和 L7 造场景借用真实提交 22ed1886(而 #834 让它变成了真实数据)。

修法:两处 grep -c 加 || true。本地重放整段 L7:③ 引用消失时删对了(1 → 0)…复原后回绿 ✓ RESULT: PASS rc=0,跑完 git status --porcelain 干净。

CI 17 个 check 全绿,合。