anet hub dashboard 不分通道一律拉 @preview:稳定版 CLI 起出来的是 preview UI,而紧邻的注释写着 channel-matched

[vansin]

结论

anet hub dashboard 不分通道,一律拉 @preview 的 Dashboard。
所以一个装了稳定版 CLI(当前 latest = 2.2.21)的用户,起出来的是
@sleep2agi/agent-network-dashboard@preview(当前 0.6.3-preview.56)。

而紧挨着这段代码的注释写的是相反的意思。

证据(origin/main,只读)

agent-network/bin/cli.ts:1484:

function dashboardReleaseTag(): string {
  const envOverride = process.env.ANET_DASHBOARD_VERSION;
  if (envOverride) return envOverride;
  return "preview";        // ← 无条件
}

它是 tag 的唯一来源,全文件只有一处赋值、没有别处覆盖:

6107:    const tag = dashboardReleaseTag();
6188:    : spawn("npx", ["-y", `@sleep2agi/agent-network-dashboard@${tag}`], …)

而 6176-6177 的注释是:

// Default stays channel-matched (see #61 + dashboardReleaseTag). A global
// binary is used only after the explicit ANET_DASHBOARD_LOCAL=1 opt-in.

「channel-matched」与代码不符 —— 代码里没有任何读取 CLI 自身版本/通道的逻辑。

当前各通道的实际版本(实测)

@sleep2agi/agent-network            latest 2.2.21          preview 2.3.0-preview.39
@sleep2agi/commhub-server           latest 0.8.8           preview 0.9.0-preview.29
@sleep2agi/agent-network-dashboard  latest 0.6.0（06-10）   preview 0.6.3-preview.56（08-12）

所以默认组合是:稳定 CLI + 稳定 hub + preview Dashboard。
latest 的 Dashboard 0.6.0 在这条路径上几乎永远不会被用到。

为什么这值得修(或至少值得写明)

1. 注释在说谎,下一个人读它会以为通道是匹配的,不会去查;
2. 用户拿到的是 preview UI,但他并不知道 —— guide/dashboard.md:283 有一节
   「Preview 通道(下一个 stable WIP)」把 preview 描述成需要显式选择的东西,
   而实际上默认就是它;
3. ANET_DASHBOARD_VERSION 这个唯一的逃生口在文档里每个文件只出现 1 次
   (deploy/npm.md / guide/dashboard.md 各 1 处,中英各一),不容易被发现。

建议(三选一,都不大)

• 要么改代码:让 tag 真的跟随 CLI 自身通道(注释描述的行为);
• 要么改注释:直接写「默认固定 preview,ANET_DASHBOARD_VERSION 可覆盖」,
  并在 guide/dashboard.md 那节说明"默认就是 preview,不需要你切";
• 要么钉住:如果希望稳定 CLI 配稳定 UI,那就让 latest 通道返回 latest。

我倾向第二个 —— 现状(默认 preview)可能是有意为之(Dashboard 的 stable 落后两个月),
那么问题就只是注释和文档没说实话,改字比改行为安全。

我没做的事

没有真起 Dashboard 去验(那会占端口、起服务)。
上述结论全部来自 origin/main 的源码;已发布的 2.2.21 里这段逻辑是否相同,
我没有验 —— 它的 dist 是字符串表混淆的,grep 不能证明不存在
(这一点我在 #777 里踩过,见那条更正)。要确认 2.2.21 的实际行为,
需要在隔离环境里真跑一次 anet hub dashboard 并看它打印的
[anet] spawning dashboard @<tag> 那一行。

(只读:git show origin/main:... + npm view;未起服务、未改代码、未碰生产。)

[vansin]

验收判据:怎么算"这条已修"

本条有三条互斥的修法(改代码 / 改注释+文档 / 改成钉住),
所以验收判据要按选的那条走。共同的一点是:必须能看见 anet hub dashboard 实际拉的是哪个 tag,
而不是读源码推断。

共同前提:那行输出是唯一的现场证据

agent-network/bin/cli.ts:6181 在 spawn 前会打印:

[anet] spawning dashboard @<tag> (anet <version>)

这行就是判据。 任何验收都要贴它的真实输出,而不是贴 dashboardReleaseTag() 的源码。

注意:跑这条会真起一个 Dashboard 进程并占端口。
请在隔离环境里做(容器 / 独立 HOME / 用 PORT= 指一个空闲端口),
别在有生产 Dashboard 在跑的机器上直接试 —— 本机 :3001 就有一个在跑。
(我因此没有实测,只给了源码结论,见本 issue 正文最后一节。)

按修法分列

修法 A —— 让 tag 真的跟随 CLI 通道

装 latest CLI（当前 2.2.21） → 跑 anet hub dashboard
  期望：[anet] spawning dashboard @latest …
装 preview CLI（2.3.0-preview.39）→
  期望：[anet] spawning dashboard @preview …

两条都要贴,只贴一条不算 —— 通道匹配是双向的断言。
另外要有一个单元测试直接断言 dashboardReleaseTag() 在两种版本下的返回值,
否则下次有人改回去,CI 不会拦。

修法 B —— 保持默认 preview,改注释和文档(我倾向这条)

1. cli.ts:6176 那句 "Default stays channel-matched" 必须删掉或改写；
   验收：grep 该文件不再出现 channel-matched 这类与行为相反的措辞。
2. guide/dashboard.md（ZH+EN）的「Preview 通道」一节要写明
   **默认就是 preview,不需要你切**；
   验收：那一节里能读到"默认"二字，而不是把 preview 描述成需要显式选择。
3. ANET_DASHBOARD_VERSION 这个唯一逃生口要在同一节出现（现在中英各只有 1 处、且不在这节）。

修法 C —— 让 latest 通道拉 latest Dashboard

除 A 的两条输出外,还要说明 stable Dashboard(当前 0.6.0,2026-06-10)
是否还能配当前 stable hub(0.8.8) —— 这条是行为变更,
必须有一次真跑的界面验证,不能只看进程起来了。

不接受的"已修"证据

• ❌ 只贴 dashboardReleaseTag() 的新源码 —— 那正是本条要纠正的"读代码推断";
• ❌ 只在 preview CLI 上试 —— 问题恰恰出在 latest CLI 上;
• ❌ 「dist 里 grep 到 latest 了」—— 两个通道的 dist 都是字符串表混淆的,
  grep 命中=存在,grep 不到什么都不能证明(这个坑我在 [release] latest 落后 preview 一个 minor:量化「默认安装的用户拿不到什么」,供决定要不要推 latest #777 里踩过并公开更正过)。

顺带:本条不需要动生产

本机 ~/.commhub/dashboard-runtime-v56 跑的是 dash-start.sh 显式钉住的
0.6.3-preview.56(脚本变量与运行时包 package.json 一致,我核过),
不走 anet hub dashboard 这条路。所以修这条不影响在跑的生产 Dashboard。

[vansin]

同一类的第二处:deploy/dashboard/dash-start.sh 的注释也已与现状不符

本 issue 讲的是「紧邻的注释写着相反的意思」。查 dashboard 部署侧时发现同类的第二处。

deploy/dashboard/dash-start.sh:58-60:

# 2026-08-04: Dashboard Chat HA (#82), source/build commit 54150269.
# The npm version remains preview.54; this pinned runtime is built from the
# reviewed main commit, so the directory name is the deployment identity.
RUNTIME_BIN="$HOME/.commhub/dashboard-runtime-v56/node_modules/.bin/agent-network-dashboard"

而 :15 是 VERSION="0.6.3-preview.56"。实测 npm(只读查 registry):

@sleep2agi/agent-network-dashboard
  dist-tags   latest=0.6.0   preview=**0.6.3-preview.56**
  0.6.3-preview.* 共 57 个，最高 0.6.3-preview.56
  脚本钉的 .56  ✅ 存在
  注释说的 .54  ✅ 存在（但已不是 preview 标签所指）

注释写于 08-04,当时 npm 确实停在 .54,所以 VERSION(.56)与 npm 不一致,
注释解释了为什么可以不一致。但 .56 之后已经发布,preview 标签现在正指向它 ——
两者已经一致了,那段解释因此失效。

后果不大(注释而已),但方向是误导性的:读到它的人会以为
「VERSION 领先于 npm,预检会告警走 RUNTIME_BIN 兜底」,而实际上预检现在会通过。

顺带:这个脚本本身的设计值得肯定,不是缺陷

同一份文件里几处做得很好,一并记下来免得被误改:

:4-6    解释了为什么不直接 exec npx —— 2026-07-29 钉到未发布版号，
        npx 每次 ETARGET 立即退出，pm2 无退避重启 **34494 次**，整夜锤 registry
:46-56  预检不再是启动硬前提 —— 因为开机时网络可能还没起来，
        而真正执行的是固化的 RUNTIME_BIN，不需要联网
:64-67  预检不过但 RUNTIME_BIN 在 → **告警但不阻塞**，并明写
        「这说明 VERSION 与 registry 不一致，请择机核对」
:70-73  RUNTIME_BIN 缺失时才慢速失败（sleep 30）—— 给 pm2 退避留时间

「VERSION 只用于预检、RUNTIME_BIN 才是真正执行的东西」这个区分是对的,
而且每一处都写明了是哪次事故催生的。要改的只是那句已经过期的版本陈述。

[vansin]

复核成立,并补上「为什么会硬编码」这一段 + 实际版本差

2026-08-15 在 origin/main@034f0064 复核,本 issue 的两半都成立:

// agent-network/bin/cli.ts:1484
function dashboardReleaseTag(): string {
  const envOverride = process.env.ANET_DASHBOARD_VERSION;
  if (envOverride) return envOverride;
  return "preview";                       // ← 恒为 preview，不看安装通道
}
// agent-network/bin/cli.ts:6176
//   Default stays channel-matched (see #61 + dashboardReleaseTag).

补充一:实际的版本差有多大

@sleep2agi/agent-network-dashboard
  latest   0.6.0             发布 2026-06-10（65 天前）
  preview  0.6.3-preview.56  发布 2026-08-12（2 天前）

装稳定版 CLI 的用户,anet hub dashboard 起出来的是比 latest 新 63 天、且在 preview 线上的 UI。

补充二:为什么没有通道匹配 —— 那个 pin 常量已经从 cli.ts 里消失了

scripts/sync-pinned-versions.sh:86 还注册着它:

register "@sleep2agi/agent-network-dashboard" "agent-network/bin/cli.ts:PINNED_DASHBOARD_VERSION"

但 PINNED_DASHBOARD_VERSION 在 origin/main 上共出现于 6 个文件
(release.yml、两份 changelog、evolution-log、一份旧基线文档、以及这个脚本自己),
唯独不在 agent-network/bin/cli.ts 里。

实跑那个脚本可以看见它:

$ bash scripts/sync-pinned-versions.sh @sleep2agi/agent-network-dashboard 0.6.0
🔴 1 个注册目标在文件里已不存在 —— 这份注册表不再覆盖它们。
退出码=6

🔴 一处我自己的更正

我一开始只在 agent-network/src/** agent-network/bin/** 范围里搜,0 命中,
差点写成「注册表指着一个不存在的符号,而且没人发现」。后半句是错的 ——
全仓搜之后发现 sync-pinned-versions.sh:161 的注释里就写着这个实例,
脚本还专门为此加了 MISSING TARGET 守卫和计数器,退出码 6。

这不是一个没人注意到的幽灵,是一个已知且已被守卫标记的状态。
(教训:窄范围 grep 的 0 命中不能推出"不存在",更不能推出"没人知道"。)

与 #862 的关系

那个守卫会以退出码 6 报出来 —— 但 sync-pinned-versions.sh 没有接在任何自动执行面上
(正是 #862 的内容)。所以这条信号只在有人手动跑的时候才可见。
本 issue 要真正修好,涉及的是"把常量放回去并让通道匹配"还是"接受硬编码并改掉那句注释",
这是个取舍,不该由复核者代拍。

我没有断言的事

• 没有验证 preview 线的 dashboard UI 与 latest 线的 server 是否存在实际不兼容 ——
  上面只量了版本与日期差,没有跑过任何兼容性测试。

[vansin]

独立复核:确认成立,而且是让稳定版二进制自己说的

不看源码、不看文档,直接跑已发布的 stable 包:

npm pack @sleep2agi/agent-network@latest --prefer-online     # → 2.2.21
env -i HOME=<tmp> PATH=/usr/bin:/bin:<node> node package/dist/bin/cli.js hub dashboard

输出第一行:

[anet] spawning dashboard @preview (anet 2.2.21)

⇒ stable CLI 2.2.21 拉的是 @preview 的 dashboard,本 issue 成立。

判据在两个包里的形态

preview 包(2.3.0-preview.39)里这段没被字符串表吃掉,可以直接读:

function Al(){
  let v = process.env.ANET_DASHBOARD_VERSION;
  if (v) return v;
  return 'preview';                 // ← 无条件兜底，没有任何 channel 匹配
}
// 使用处:spawn(['-y', '@sleep2agi/agent-network-dashboard@' + tag])

latest 包(2.2.21)里同一个函数返回的是字符串表索引(_0x11f2a2(0x40c)),读不出字面量 ——
所以我没有靠 grep 下结论,而是跑它。跑出来的那行日志就是判据。

🔴 这一点值得单说:两个包的混淆程度不一样,同一份 grep 在一个包上能读、在另一个包上读不出。
遇到读不出的,别推测,让它自己说。

⚠️ 一个我做得不够干净的地方,记在这里

我把「跑一个子命令看它打印什么」当成了只读探针。它不是 ——
anet hub dashboard 会尝试监听 127.0.0.1:3000:

Error: listen EADDRINUSE: address already in use 127.0.0.1:3000

这次没造成影响(端口已被占用,它直接退了;复核后 :3000 仍是 1 个 LISTEN,占用方未受影响),
但那是运气,不是设计。如果 :3000 空着,我就会在这台机上起一个 dashboard。

⇒ 给后来者:要验这类"CLI 会去拉哪个 tag",优先找不启动服务的路径
(--help、--dry-run、或直接把 npx/bunx 从 PATH 拿掉并只看第一行日志)。
我这次是拿掉了 npx,但没料到它在 spawn 之前就先绑端口了。

[vansin]

修了(45043588)。但先更正一个定性:这不是 bug,是一个写明了退出条件的临时措施

dashboardReleaseTag() 上方的注释把话说得很清楚:

// 🅗2 temp fallback per #61 — anet@latest 用户从 dashboard 0.4.5-preview.1
//   → 0.4.2 (current @latest) 是 *功能 regress* …短期双 channel 都拉 @preview
// TODO(#61 phase-2): swap anet@latest fallback "preview" → "latest" once
//   @sleep2agi/agent-network-dashboard promotes 0.4.5 stable.

退出条件写在那儿。今天去量:

npm view @sleep2agi/agent-network-dashboard dist-tags
  latest  = 0.6.0
  preview = 0.6.3-preview.56

latest 已远超 0.4.5 —— 条件满足,措施到期。

⇒ 所以本 issue 不该读成"有人写错了",而是"一个临时措施的到期条件已经满足,但没有人回来收"。
这两种定性会导向完全不同的处理:前者去找责任,后者去建到期提醒。

过期之后的代价,比"没升级"更隐蔽

紧邻的日志文案是 channel-matched npx startup,而函数恒返 preview。
⇒ 稳定版 CLI 起出 preview UI,而文案让用户以为自己在稳定通道上。
文案与行为矛盾比单纯拉错通道更糟:它让人没有理由去怀疑。

改法与验证

return getAnetVersion().includes("-preview.") ? "preview" : "latest";

getAnetVersion() 本来就存在(读 CLI 自己 package.json)。ANET_DASHBOARD_VERSION 覆盖不变。

2.2.21            → latest    ✅
2.3.0-preview.39  → preview   ✅
2.3.0             → latest    ✅
""（读不到版本）   → latest    ✅   🔴 读不到时**保守走 latest**，不猜 preview
2.3.0-rc.1        → latest    ✅   rc 不是 preview 通道

bun build bin/cli.ts 通过。

留给这条 issue 的一个更一般的问题

这次是人肉发现一个到期的 TODO。仓里还有多少这种"写了退出条件、条件已满足、没人回来收"的临时措施?
那是可以机械扫的(找 TODO(#...) + 判断其条件),但判据要一条条写,不是一句 grep 能解决 ——
这一条我没有做,只把问题提出来。

[vansin]

那条临时措施自己写明的退出条件已经满足,今天复核过

本 issue 的核心是:紧邻的日志文案写 channel-matched,而 dashboardReleaseTag() 恒返 preview。
origin/main 现在仍是这样:

// origin/main:agent-network/bin/cli.ts:1484
function dashboardReleaseTag(): string {
  const envOverride = process.env.ANET_DASHBOARD_VERSION;
  if (envOverride) return envOverride;
  return "preview";          // ← 恒定
}

那段临时措施的注释里写了退出条件:「once @sleep2agi/agent-network-dashboard promotes 0.4.5 stable」。

2026-08-16 复核(不是引用当时的记录,是今天重新跑的):

$ npm view @sleep2agi/agent-network-dashboard dist-tags
{ "latest": "0.6.0", "preview": "0.6.3-preview.56" }

⇒ latest = 0.6.0,已远超 0.4.5,退出条件满足,这条临时措施到期了。

代价不是"没升级",是文案与行为矛盾

稳定通道的 CLI 起出来的是 preview UI,而紧邻的日志文案写着 channel-matched npx startup。
⇒ 用户按文案理解,会以为自己在稳定通道上。这比单纯"版本旧"更难查 ——
出了问题他会去排查稳定版的代码,而他跑的根本不是那份。

已有的改法(在本地分支上,未落地)

return getAnetVersion().includes("-preview.") ? "preview" : "latest";

ANET_DASHBOARD_VERSION 覆盖保留 —— 需要跨通道拉某个特定版本时仍然可以显式指定,
默认则回到文案承诺的 channel-matched。

🔴 我没有开 PR(本轮指令),分支在本地 integration/tip-2026-08-16 上。
另外注释里把「退出条件 + 今天的实测 dist-tags」一起写在了函数上方 ——
下一个读它的人不必再去猜这条临时措施还该不该在。

[vansin]

在 origin/main 上核了,本条成立,而且底下还有一件比它更值得处理的事。

现状

// agent-network/bin/cli.ts
function dashboardReleaseTag(): string {
  const envOverride = process.env.ANET_DASHBOARD_VERSION;
  if (envOverride) return envOverride;
  return "preview";          // ← 对每一个调用者
}

而紧邻的调用点(:6302)写着:

// Default stays channel-matched (see #61 + dashboardReleaseTag).

这句注释和代码相反。 而且它是大多数读到这个调用点的人唯一会看到的说明 —— 函数自己那段把 #61 理由讲清楚的注释在 4700 行之外。

一个补充观察:运行时输出是诚实的 —— :6307 那行 spawn 日志打印的是真实的 @${tag},用户会看到 spawning dashboard @preview。所以这不是「程序骗用户」,是**「注释骗读代码的人」**,而后者的受害者是下一个改这段代码的同事。

注释已在 #918 修好(纯注释,零行为变化)。

🔴 更值得处理的:那个 TODO 的到期条件早就满足了

同一段还有:

// TODO(#61 phase-2): swap anet@latest fallback "preview" → "latest" once
//   @sleep2agi/agent-network-dashboard promotes 0.4.5 stable.

今天对着 live registry 量:

$ npm view @sleep2agi/agent-network-dashboard dist-tags
{ "latest": "0.6.0", "preview": "0.6.3-preview.56" }

它等的那个条件(0.4.5 进 latest)早就过了 —— latest 现在是 0.6.0,比它等的版本高好几个 minor。

原始理由写得很具体:「anet@latest 用户从 dashboard 0.4.5-preview.1 → 0.4.2(current @latest)是功能 regress,因为 preview channel 远超 latest」。那个具体的落差今天已经不成立:latest 0.6.0 vs preview 0.6.3-preview.56,差的是一个 patch 上的 preview 序列,不是当年那种 0.4.2 vs 0.4.5 的代际差。

需要一个决定(我不单方面翻)

翻转 dashboardReleaseTag() 会改变每个 stable channel 用户 anet hub dashboard 实际拉到的东西:

	现在	翻转后
stable 用户拿到	0.6.3-preview.56	0.6.0

0.6.0 功能够不够,是产品决定不是清理。 判据应该是:有没有 stable 用户会用到、而只存在于 0.6.1 ~ 0.6.3-preview.56 之间的能力。这个我没量 —— 要量得逐版比 changelog,而且结论会随下一次发版变。

建议:要么翻转(如果 0.6.0 够用),要么把 TODO 的条件改写成一个仍然成立的条件(比如「等 0.6.3 promote 到 latest」)。现在这个 TODO 的条件已经满足,它既不会触发任何动作,也不再描述任何真实的等待。

🔴 一句一般化(已写进 #918 的注释里)

一个把到期条件写下来的临时方案,比不写的好 —— 但只在有人回头读它的前提下。没有任何东西会去重新评估一个存在注释里的条件。

TODO 里的那个版本号是在写下的那一刻正确的,之后它只会离现实越来越远,而没有任何门、任何测试、任何 CI 会告诉你它过期了。这和 #834 / #850 那批「行号 pin 失效」是同一个族:一个把外部状态硬编码进文本的引用,会静默腐烂。

[vansin]

补一组决策需要的数字(全部命令输出)

@sleep2agi/agent-network-dashboard
  latest  = 0.6.0                发布于 2026-06-10     ← 冻结 69 天
  preview = 0.6.3-preview.56     发布于 2026-08-12

两者之间发布过的版本:59 个 —— **59 个全在 preview 线,稳定线 0 个**

⇒ 稳定通道在这 69 天里一个版本都没发过。 所以「翻不翻这个 fallback」不是
「preview 比 latest 新一点」的取舍,而是:

翻过去 = 稳定通道用户从 0.6.3-preview.56 退回到 69 天前的 0.6.0,中间 59 个版本的改动全部消失。

代码里那句判断因此是准确的:

whether 0.6.0 is feature-complete enough is a product call, not a cleanup.

🔴 我本来想给它加一道「过期条件检查」的门,想清楚之后没有加

dashboardReleaseTag() 上方那段注释里有一句我很认同的话:

a temporary workaround that WRITES DOWN its expiry condition is better than one that
doesn't — but only if someone re-reads it. Nothing re-evaluates a condition stored in a comment.

而这个仓里已经有正确的位置可以放这种检查 —— published-artifact-drift.yml 是定时跑的,
它的头部还专门解释了为什么不做成 per-PR:「它检查的是已发布产物,PR 不改变它,
而且它需要 npm registry」。技术上完全可以再加一个 job 去重新求值这个过期条件。

但我判断不该加,理由是:

这个条件已经过期了,而且注释里就写着它过期了。 一道门加上去第一天就是红的,
而红了之后没有任何动作可做 —— 翻转它需要的是一个产品决定(#866 本身),不是一次检测。

一道说真话、但指向不了任何动作的门,会变成墙纸。 而墙纸的代价不是零:
它会训练所有人忽略这一类红色,包括下一个真正需要动作的。

⇒ 这里缺的不是检测,是决定。 检测已经由那段注释和这条 issue 完成了。

真正值得做成门的是它的反面:等有人决定了(比如「稳定通道必须发一个 0.6.x」),
那时加一道「稳定通道最长冻结天数」的门才有动作可指 —— 判据是决定的产物,不是决定的替代品。