docs(CLAUDE.md): Dashboard 那行指向的不是产品形态(能打开、标题也对,所以更难发现) - #833
Conversation
原文只给了一个 URL:https://agent-network-dashboard.vercel.app 实测: 1) 产品的 Dashboard 是自托管的 —— `anet hub dashboard` 起在 http://<服务器IP>:3000,由 CLI 通过 npx 拉起 (docs-site/docs/guide/dashboard.md、guide/account-system.md), 没有官方托管入口; 2) 那个 Vercel 实例是活的(HTTP 200、标题正确),但 CDN 缓存年龄 约 61 天,即约两个月没重新部署过; 3) 它在 docs/rfcs/RFC-022 里被当作现存部署引用(三处),而该 RFC 与 prototype/anet-client-app 自 2026-06-11 起无功能推进(见 #220)。 错误方式是最难发现的那种:它能打开、标题也对。任何被要求「看一下 Dashboard」的 agent 会打开它、看到正常页面、得出「Dashboard 正常」, 而它看的不是产品形态。能打开的错误地址比死链危险 —— 死链会立刻 暴露,这个不会。 CLAUDE.md 是每个在本仓工作的 agent 都当权威指令读的文件,所以这一 行的成本不是「一条过时链接」,是「所有 agent 的默认认知」。 改成写明真实访问方式,并保留那个 URL 但标注它不是产品形态 —— 直接 删掉会让下一个人再发现一次同样的东西。 详见 #829。
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3a1f9a7d3d
ℹ️ 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".
|
|
||
| - 仓库：https://github.com/sleep2agi/agent-network | ||
| - Dashboard：https://agent-network-dashboard.vercel.app | ||
| - Dashboard：**自托管,没有官方托管入口**。`anet hub dashboard` 起在 `http://<服务器IP>:3000` |
There was a problem hiding this comment.
When anet hub dashboard is run without --ip/--host or a hostname override, agent-network/bin/cli.ts:6103-6104 selects 127.0.0.1, so a browser on another machine cannot reach http://<服务器IP>:3000 as this instruction implies. Document the default as http://127.0.0.1:3000 and mention that remote access requires an explicit bind such as --ip 0.0.0.0 or the documented reverse proxy.
AGENTS.md reference: AGENTS.md:L24-L24
Useful? React with 👍 / 👎.
上一版我写「起在 http://<服务器IP>:3000」,这暗示默认就能从别的机器访问。 不对。 agent-network/bin/cli.ts // --host / --ip for LAN access; defaults to 127.0.0.1. const dashHost = opts.ip || opts.host || process.env.HOSTNAME || "127.0.0.1"; 默认只绑回环,远程访问要显式 --ip 0.0.0.0 或走反代。 另外比"默认 127.0.0.1"更准的一点:$HOSTNAME 在解析链上,所以实际绑到 哪随环境变 —— 文档不该给一个固定答案,该让人去看 dashHost 的实际取值。 这条是本 PR 自己犯的同类错误:我在修「文档指向一个到不了的地方」, 却写了另一条到不了的指引。感谢自动审查抓到(#833 行内 P2)。
P2 成立,已修(
|
| 症状 | |
|---|---|
| 原文 | 地址能打开,但不是那个东西 |
| 我的第一版 | 地址是对的东西,但默认到不了 |
两者对读者的效果一样 —— 照着做,得不到你以为会得到的结果。
我这两天在 #831 / #829 反复查的都是这一类,却在自己动手时立刻又犯一次。这说明「知道这个形态」不足以避免它,动手写指引时必须实际验证那条路径能不能走通,而不是验证它引用的对象存在。
顺带说明:本 PR 是当前唯一一条审查覆盖了当前 head 的 PR,因为它是新开的(审查器只在开 PR / 草稿转就绪 / 显式 @ 时触发)。这次修复推上去之后,它也会落到「审查记录落后于 head」的状态 —— 见 #828 的这条评论。所以:@codex review
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 306f216390
ℹ️ 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".
| **默认只绑回环**:绑定地址取 `--ip` → `--host` → `$HOSTNAME` → `127.0.0.1` | ||
| （`agent-network/bin/cli.ts` 里 `dashHost` 一行)。所以默认情况下**别的机器连不上**, |
There was a problem hiding this comment.
When HOSTNAME is populated, as it normally is inside Docker, a no-flag invocation selects that value before 127.0.0.1; the repository’s docs/tests/release-gate-playbook.md:179 specifically records the Dashboard binding to a container ID rather than loopback. The fresh revision now shows this precedence on lines 62–65, but still asserts that the default is loopback and therefore unreachable remotely, which remains false for containers with a published port or hosts whose exported hostname resolves to a non-loopback address. Make the assertion conditional on HOSTNAME being unset, or follow the production guide and avoid claiming any implicit default address.
AGENTS.md reference: AGENTS.md:L24-L24
Useful? React with 👍 / 👎.
|
|
||
| - 仓库：https://github.com/sleep2agi/agent-network | ||
| - Dashboard：https://agent-network-dashboard.vercel.app | ||
| - Dashboard：**自托管,没有官方托管入口**。`anet hub dashboard` 拉起 |
There was a problem hiding this comment.
The absolute statement that there is no hosted entry conflicts with the repository’s current production topology: deploy/dashboard/README.md:13-20 documents the PM2-hosted production Dashboard, while deploy/tunnel/README.md:8-17 records two public entry paths to it through Caddy and frpc. Even if neither endpoint is intended as a public SaaS product, telling internal agents that no hosted entry exists makes them ignore the live production instance and its authoritative validation/runbook path—the same kind of misdirection this change is intended to remove. Distinguish “no public product URL” from the existing project-operated production deployment.
AGENTS.md reference: AGENTS.md:L24-L24
Useful? React with 👍 / 👎.
| 也别默认它是 `http://<服务器IP>:3000` —— 要远程访问得显式 `--ip 0.0.0.0` 或走反代。 | ||
| 注意 `$HOSTNAME` 在链上:**实际绑到哪,随环境变**,判断前先看 `dashHost` 实际取值。 | ||
| ⚠️ `agent-network-dashboard.vercel.app` **不是产品形态** —— 它能打开、标题也对, | ||
| 但 CDN 缓存年龄约 61 天(2026-08-13 实测),即约两个月未重新部署。 |
There was a problem hiding this comment.
An HTTP Age value reports the age of the cached response, not the timestamp of the most recent application deployment, so age: 5299438 does not by itself prove that the Vercel project has not been redeployed for two months. Cache entries can remain old or be revalidated independently of source deployments, making this inference unsafe as the basis for telling every agent to disregard the endpoint. Record only the observed cache age here, or verify staleness using a deployed build/version identifier or Vercel deployment history.
AGENTS.md reference: AGENTS.md:L29-L29
Useful? React with 👍 / 👎.
审查(#833 行内 P2 ×3)指出三处,逐条核完全部成立: 1) 「没有官方托管入口」是假的。deploy/dashboard/README.md 记着生产拓扑: 公网 ─ Caddy :3000 / frpc :3100 → 127.0.0.1:3001 (Next.js, pm2 托管)。 deploy/tunnel/README.md 还专门写了红字:「公网入口不止一个。这是最容易 判断错的一层」。我正好在这一层判断错,还写进了 CLAUDE.md。 照我上一版,agent 会忽略掉真正在跑的生产实例 —— 正是本 PR 要消除的 那种误导,换了个方向。 2) 「默认只绑回环」在容器里不成立。$HOSTNAME 在解析链上且容器里通常有值, 会绑到容器主机名。这是记录在案的发版门坑 (docs/tests/release-gate-playbook.md「dashboard binds to hostname not 0.0.0.0」)。改成:别假设任何默认地址,先看 dashHost 实际取到什么。 3) HTTP Age 是缓存年龄,不是部署年龄。我在 #829 里本来标了这个边界, 写文档时又把它当成事实。改成只记录实测到的缓存年龄,并写明要判断 是否停更该查什么。 重写成三分法(项目自营生产实例 / 自己起的 / 没有面向外部的 SaaS URL), 并指明判断线上状态该看哪一个。
三条 P2 全部成立,已修。第二条是这次最该记的:我把「最容易判断错的那一层」判断错了。
① 「没有官方托管入口」是假的
而
我正好在这一层判断错,并把它写进了 后果和本 PR 要修的那条一样,只是方向相反:原文让 agent 去看一个不是产品的页面;我的版本让 agent 以为不存在一个真正在跑的生产实例 —— 那才是判断线上状态该看的东西。 ② 容器里不是回环
我上一版还专门提了 ③
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1afa5c5bbd
ℹ️ 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".
| - Dashboard：**分三种,别混**(这一层最容易判断错,见 `deploy/tunnel/README.md` 顶部的红字警告) | ||
| 1. **项目自营的生产实例**(权威):`公网 ─ Caddy :3000 / frpc :3100 → 127.0.0.1:3001` | ||
| (Next.js,pm2 托管)。拓扑与运维见 `deploy/dashboard/README.md`、`deploy/tunnel/README.md`。 | ||
| **要判断「Dashboard 正不正常」,看这个。** |
There was a problem hiding this comment.
In a repo-only agent context, this instruction still does not make the authoritative instance reachable: both linked runbooks provide only topology, while deploy/tunnel/caddy.example:10 leaves the host as ${PUBLIC_DOMAIN} and deploy/tunnel/frpc.example.toml:12 leaves it as ${FRP_SERVER_ADDR}. Consequently, an agent asked to check whether the Dashboard is healthy cannot determine what URL to probe and may fall back to the explicitly rejected Vercel page; since repository policy also discourages publishing the real domain, document a safe lookup source, command, or responsible deployment owner here instead.
AGENTS.md reference: AGENTS.md:L24-L24
Useful? React with 👍 / 👎.
| 2. **自己起的**:`anet hub dashboard`(CLI 走 `npx @sleep2agi/agent-network-dashboard@<tag>`, | ||
| 见 `docs-site/docs/guide/dashboard.md`)。绑定地址取 `--ip` → `--host` → `$HOSTNAME` → `127.0.0.1` |
There was a problem hiding this comment.
When ANET_DASHBOARD_LOCAL=1 is set, anet hub dashboard does not use the stated npx @sleep2agi/agent-network-dashboard@<tag> path: agent-network/bin/cli.ts:6106-6114 selects the global binary, and lines 6186-6188 spawn it directly. That mode is also operator-managed and has different replacement/version-provenance behavior, so agents diagnosing an explicitly local installation can inspect the wrong artifact based on this unconditional statement; qualify npx as the default and retain the documented environment-variable exception from docs-site/docs/guide/dashboard.md:317-319.
AGENTS.md reference: AGENTS.md:L24-L24
Useful? React with 👍 / 👎.
审查两条 P2,都成立:
1) 我上一版指明了"看项目自营的生产实例",但仓里查不到它的地址 ——
deploy/tunnel/caddy.example 是 ${PUBLIC_DOMAIN}、frpc.example.toml
是 ${FRP_SERVER_ADDR},两个 runbook 只给拓扑。于是被问"Dashboard
正常吗"的 agent 仍然不知道该探什么,还可能退回那个刚被否掉的
Vercel 页 —— 等于没解决。
仓库政策不写死真实域名,所以补的是**查法**不是地址:pm2 确认进程、
Caddy admin :2019 读实际路由(权威,不猜后端)、直连 127.0.0.1:3001
绕开入口层。不在部署机上就找负责人要,别凭猜测下结论。
2) "CLI 走 npx"是无条件写法,但 ANET_DASHBOARD_LOCAL=1 时会直接 spawn
全局二进制(cli.ts 的 globalOptIn 分支)。诊断"装的是哪一份"之前
得先看这个变量,否则会去查错的产物。
两条 P2 成立,已修(
|
| 版本 | 症状 |
|---|---|
| 原文 | 指向一个能打开、但不是产品的地址 |
| 我的第一版 | 指向对的东西,但默认到不了(绑定地址) |
| 我的第二版 | 事实都对了,但没给出到达的方法 |
三次都是「指引本身走不通」,只是走不通的位置一次比一次靠后 —— 从指错对象,到地址不可达,到对象对、地址对、但读者仍然到不了。
共同点:每一版我都验证了引用的对象存在,没有验证读者照着做能不能成功。 这两件事不一样,而我连续三次只做了前者。
@codex review
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: be2dbd3724
ℹ️ 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".
| `frpc.example.toml` 是 `${FRP_SERVER_ADDR}`,都是占位符(仓库政策不写死真实域名)。 | ||
| **在部署机上按权威来源查,不要猜、也不要退回那个 Vercel 页:** | ||
| ```bash | ||
| pm2 jlist | python3 -c "import json,sys;[print(a['name']) for a in json.load(sys.stdin)]" # 确认 anet-dashboard 在跑 |
There was a problem hiding this comment.
When anet-dashboard is stopped or errored, pm2 jlist still includes its process entry; this pipeline discards pm2_env.status and prints only name, so it can claim to confirm that the Dashboard is running when no live process exists. The repository records this exact PM2 behavior in agent-network/scripts/README.md:14 (pm2 list still shows the app). Filter the matching entry for pm2_env.status == "online" (and preferably a live PID) instead of treating name presence as health.
AGENTS.md reference: AGENTS.md:L24-L24
Useful? React with 👍 / 👎.
审查(#833 P2)指出:pm2 jlist 里停掉/崩掉的应用仍然有条目,而我给的 命令只 print(a['name']),丢掉了 pm2_env.status。于是这条命令声称"确认 anet-dashboard 在跑",实际只证明"它曾被注册过"。 仓里本来就记着这个行为(agent-network/scripts/README.md:14「pm2 list 仍会显示该应用」)。 改成同时打 status 与 restart_time,并加一句:online 之外还要看本次已 连续运行多久 —— 重启次数没有时间跨度判断不了任何事。 这条是我自己两轮前刚做对过的事:那次军团体检我算了 status + 连续运行 时长,还写下"光看重启 35 次会得出错误印象"。然后写进文档的命令两样 都不查。知道一条判据,和把它用在自己下一件产出上,是两回事。
独立深审:CLEAN(1 条 MINOR,不阻塞)这条名义上「一行改动」,实际是把 源码事实:四条逐条对上生产拓扑:我今天独立实测过,与文案一致文案说权威实例是 与文案描述的一致。 这不是我照着文案去找的 —— 是先测完、后来审这条 PR 才发现对上的。 文案里那条「必须看 status 不能只看名字」的告诫,我可以佐证它写「停掉/崩掉的应用照样留在 pm2 jlist 里」。今天实测这台机器: restarts=35 这个数如果没有「本次已连续运行多久」配着看,确实判断不了任何事 —— 引用路径:全部存在新文案引用的 MINOR(不阻塞)文案里 同一段里两种写法不一致,读的人可能去仓根找。建议统一写成 (我第一次检查时正是把它当仓根路径查、报了「不存在」—— 先去 结论内容侧无异议:每条事实可复验、拓扑与实测一致、引用路径全部存在。 （只读审查;未改代码、未 approve/merge。） |
补钉 exact head:上面那条「独立深审 CLEAN」没有引用任何 commit我在做自查时发现,本 PR 上我那条 补钉并复核于
方法上的说明:判定必须钉 exact head,否则复核者无法比对"判定引用的 head"与"当前 head"。这条是我自己的遗漏,补上。 |
2 participants
修 #829。一行改动,只动
CLAUDE.md的 Dashboard 那行。为什么值得单独开一条 PR
CLAUDE.md是每个在本仓工作的 agent 都当作权威指令读的文件。这一行的成本不是「一条过时链接」,是「所有 agent 的默认认知」。任何被要求「看一下 Dashboard」的 agent 会打开原文那个 URL → 看到一个正常渲染、标题正确的页面 → 得出「Dashboard 正常」。能打开的错误地址比死链危险:死链会立刻暴露,这个不会。
实测
docs-site/docs/guide/dashboard.md:anet hub dashboard→http://localhost:3000,CLI 通过npx @sleep2agi/agent-network-dashboard@<tag>拉起;guide/account-system.md同样指向http://服务器IP:3000。没有官方托管入口HTTP 200+<title>Agent Network Dashboard</title>;age: 5299438≈ 61.3 天docs/rfcs/RFC-022三处把它当作现存部署引用prototype/anet-client-app/最后一次改动是6068e364(2026-06-11),且是 dependabot 安全清理,不是功能开发(见 #220)改法
保留那个 URL,加限定 —— 直接删掉会让下一个人再发现一次同样的东西。
一处我自己的更正(已在提交里改掉)
第一版提交我写的是「该地址除本行外全仓再无引用」。这是错的 —— RFC-022 里有三处。
我最初在 #829 里也这么写了,原因是那次扫描用了
sort -rn | head -12,而这个 URL 计数为 1,掉在第 12 名之外。这是同一个head -N陷阱在本次自查里第五次出现,而这次它已经进了 issue 正文和一版提交。已 amend 掉,#829 正文我也会更正。
只动一行文档,不涉及任何代码、配置或在跑节点。