[policy] 三个公开仓的 slug 门口径不一致:同一个 slug 在 app 仓放行、在主仓拦截,需要一次统一决定

[vansin]

三个仓都有 slug 门了(今天补齐的),但口径互不相同

今天把三个 PUBLIC 仓的 slug 防护补齐了(#756 / #771 / dashboard#25),
过程中横向比出一件事:三道门对「哪些文件算公开」的判断不一致,而这不是笔误,
每一处都有各自写明的理由。

仓	实现	覆盖	对 docs/
agent-network	.github/scripts/check-no-memory-slugs.py	os.walk 全树,EXTENSIONS 白名单(今天加了 .sh/.py)	扫,但 ALLOWLIST_PATH_PREFIXES 放行 docs/sop/、docs/rfcs/、docs/research/、docs/troubleshooting/、docs/tests/
agent-network-app	.github/workflows/scrub-guard.yml	仅 src/ + App.tsx	完全不扫(注释:internal notes may reference slugs)
agent-network-dashboard	同上,今天移植	仅 app/	完全不扫(沿用移植来源的口径)

具体后果:同一个 slug,在两个仓待遇不同

agent-network-app  docs/RFC-026-mobile-picker-design.md:150
  … per `[[feedback_doc_capability_claim_verify_code_path]]`      ← 门有意放行,留在 PUBLIC main 上

agent-network      docs/ 下同类文件
  → 若不在那五个 ALLOWLIST 前缀内,会被拦

两个仓都是 PUBLIC,同一类内容,一个放行一个拦截。

这不是「谁写错了」

每一处都写了理由:

• app / dashboard:内部笔记引用 slug 有其用处,全面禁止会让笔记失去索引价值;
• agent-network:用前缀白名单而不是整个 docs/ 豁免,是更细的折中。

问题在于三个仓没有共同答案,而它们面向的是同一批读者、同一个公开面。

需要一次决定(我不替 owner 定)

三选一,或另有第四种:

1. 统一为「代码禁、docs 允许」 —— 与 app/dashboard 现状一致,agent-network 放宽;
2. 统一为「全仓禁,少数明确目录豁免」 —— 与 agent-network 现状一致,app/dashboard 收紧
   (代价:app 的 docs/RFC-026 需要清理);
3. 按仓自行决定 —— 现状,但至少要写下来,否则下一个人会以为某个仓漏配了。

附:我在这条线上做过的事

• #756 给 agent-network 的门补分母(此前扫 0 个文件与扫 898 个输出逐字相同);
• #771 补 .sh/.py 覆盖 —— 三处真 slug 一直藏在那 898 之外;
• dashboard#25 从零补门 + 清 2 处泄漏(此前完全没有门),并已核实它在 main 上
  真跑过(completed/success);
• app 仓的门是三者里写得最好的(自报分母、范围与理由写在注释里),我只验证未改动。

横向比才发现的规律:三道门各有各的盲区 —— 一个没有门、一个漏文件类型、一个有意不扫 docs。
单看任何一个仓都发现不了。

[vansin]

路径更正(我自己写错的,自查发现)

本 issue 正文里引用的两条路径,在 origin/main 上都不存在:

正文写的	实际
scripts/check-no-memory-slugs.py	.github/scripts/check-no-memory-slugs.py
docs/RFC-026-mobile-picker-design.md	无此文件;仓里的 RFC-026 是 docs/rfcs/RFC-026-create-node-host-daemon.md(另一个主题),所以这条引用要么是笔误、要么指向一份从未产出的文档

第一条会把读者带到不存在的路径,第二条更糟 —— 它让人以为有一份同名 RFC 在。
本 issue 的结论不受影响(三个公开仓的 slug 门口径确实不一致),只是引用坐标要按上面这份读。

发现方式:扫全部 70 条 open issue 正文里引用的仓内路径,与 origin/main 的文件清单比对。
扫描器先用三条输入校准过(纯路径存在 / GitHub URL 形式 / 编造的不存在路径),
第一版没把 URL 形状放进校准,报了 5 条假阳性,归一化后才得到真名单。

[vansin]

把这条从「口径之争」变成数字(2026-08-14 实测,全只读)

三个 PUBLIC 仓当前实际公开的 memory slug 数量,用主仓那道门自己的判据
(\[\[(feedback|project|reference|user)_[a-z0-9_-]+(?:\.md)?\]\])统一度量:

仓	公开的 slug	说明
agent-network	60 处 / 16 个文件	全在 ALLOWLIST_PATH_PREFIXES 里,门有意放行
agent-network-app	1 处 / 1 个文件	docs/RFC-026-mobile-picker-design.md:150,门不扫 docs/
agent-network-dashboard	0 处	门不扫 docs/,但 docs/ 里本来就没有

主仓那 60 处的分布(前几名):

docs/sop/methodology.md                              28
docs/rfcs/RFC-010-node-lifecycle.md                   5
docs/rfcs/RFC-022-agent-network-client-app.md         5
docs/rfcs/RFC-023-destructive-command-guardrail.md    4

ALLOWLIST 外只有 1 处,在 .github/scripts/check-no-memory-slugs.py 自己里
(那是模式定义,门自排除)。门是准的,没有漏网。

这个数字改变了问题

这条 issue 原来的说法是「同一个 slug,在 app 仓放行、在主仓拦截」,读起来像是
app 仓的门太松。但实测下来:

• 主仓自己有意公开了 60 处;
• app 仓那个「漏网的」只有 1 处。

所以真正要决定的不是「app 仓该不该扫 docs/」,而是:

公开 60 处内部记忆 slug,是可以接受的吗?

• 如果可以(理由多半是:slug 只是个名字,内容不在公开仓里)——
  那 app 仓那 1 处也没问题,三道门应当统一到宽的那一侧,把主仓的
  ALLOWLIST_PATH_PREFIXES 明确成policy而不是例外。
• 如果不可以 —— 那要清理的是主仓的 60 处,不是 app 仓的 1 处。
  app 仓那条只是个零头。

两种走法的工作量差了一个数量级,而且方向相反。所以这确实需要一次决定,
但决定的对象和这条 issue 原来写的不一样。

顺带记两条方法上的东西

1. gh api search/code 对这个 slug 返回 total_count=0,但它其实在文件里。
   我改用 contents API 直接取文件才拿到第 150 行那条。
   搜索索引的「找不到」不能当「不存在」用。

2. 我第一次量出「ALLOWLIST 外有 5 处」,是我自己的正则太宽。
   我用的是 \[\[[a-z0-9_]{4,}\]\],把 [[marker]]、[[visitors]] 也算进去了 ——
   那不是记忆 slug。改用门自己的正则(要求 feedback|project|reference|user 前缀)
   重量才得到上面的数。拿仓库不用的口径去量,得到的是零信息的结论。

3. docs/qa/weekly/2026-W19.md 不是 UTF-8,这已经是它第二次打断我的全目录扫描
   (第一次在 docs: docs/ 里 13 条 cli.ts 行号引用改钉符号锚(22 → 9,改前 11/11 全错) #857)。任何按 UTF-8 读全树的脚本都会在它上面炸。

[vansin]

把「口径不一致」量成了当下的数字(2026-08-16 实测)

判据用的是真实 slug 清单(记忆目录里的 417 个文件名),不是形状正则 —— 理由见文末。

sleep2agi/agent-network-app         真实 slug   1 处
sleep2agi/agent-network-dashboard   真实 slug  10 处

正文点名的那一处三天后仍在 PUBLIC main 上:

agent-network-app  docs/RFC-026-mobile-picker-design.md:150
  … per `[[feedback_doc_capability_claim_verify_code_path]]`

🔴 dashboard 那 10 处里,有 4 处落在它自己的门声称覆盖的目录下

tests/   6 处
app/     4 处   ← scrub-guard 声称扫的就是 app/
    app/api/hub/nodes/[ref]/attrs/route.ts   ← feedback_error_msg_points_at_wrong_layer
    app/components/NodeList.tsx              ← feedback_tolerant_assertion_accepts_noncompliance
    app/components/TaskChatPanel.tsx         ← feedback_assert_the_fact_not_the_declaration
    app/tasks/TasksView.tsx                  ← feedback_verify_both_directions_with_real_data

这不一定是门坏了 —— 也可能是它们早于门落地、被既成事实带过,或者门只在 PR 触到那些路径时才跑。
但无论哪种,「dashboard 的门覆盖 app/」这句话和 app/ 下当前有 4 处 slug 这件事同时为真,
所以那张覆盖表读起来比实际更安全。这一格值得在做统一决定之前先确认。

(另 6 处在 tests/,不在任何一道门的覆盖里,与正文表格一致。)

🔴 两个测量方法上的坑,都是我这次踩过的

一、GitHub 代码搜索对这件事会给假阴性。

gh api search/code  q="feedback_ repo:sleep2agi/agent-network-app"   → total_count = 0
直接取文件                                                            → 第 150 行就在那儿

0 是索引/分词的结果,不是仓库的状态。这件事上别用代码搜索定论。

二、形状正则会把普通标识符算进来。

我第一版用 (feedback|reference|project)_[a-z0-9_]{6,},得到 app=4 / dashboard=16;
换成"必须命中真实 slug 名"之后是 1 / 10。差额全是 project_settings 这类普通代码名。
数"提及"找到的是候选,不是缺陷。

判据可复跑:取两个仓的 git/trees/main?recursive=1,逐 blob 解 base64,
再与本地记忆目录的文件名集合求交 —— 交集才算命中。

[vansin]

更正我上一条的数字,并把「门有没有坏」这件事查清

一、门没有坏 —— 是判据只覆盖一种写法

dashboard 的 scrub-guard.yml 判据是:

grep -nE '\[\[[A-Za-z0-9_-]+\]\]'      # 只认 [[slug]] 这种维基链接写法

而 app/ 下那几处是注释里裸写的名字,不是 [[…]]:

app/components/NodeList.tsx:88   // empty. See feedback_tolerant_assertion_accepts_noncompliance.
app/tasks/TasksView.tsx:80       // See feedback_verify_both_directions_with_real_data — this is a

⇒ 这不是那次"从固定串 [[ 收窄到 slug 形状"造成的回归 —— 裸名从一开始就不在覆盖里
(原来的 [[ 固定串同样抓不到它)。门按写下来的样子在正确工作;缺的是判据的一格。

二、我上一条报的「10 处」是低估

我拿的"真实 slug 清单"只有本项目那 417 条。而本机 ~/.claude/projects/ 下有 19 个命名空间,
合计 964 条 —— dashboard 仓里引的有些是它自己那个命名空间的 slug,我当成了误报:

project_dashboard_concurrent_editors     ← 本以为是普通标识符
feedback_dash_zombie_port_3000           ← 正文里就写着 “feedback_dash_zombie_port_3000.md memory rule:”

按 964 条重数:

agent-network-app         1 处   (app/ 下 0)
agent-network-dashboard  12 处   (app/ 下 6)     ← 上一条说 10 / 4

🔴 教训:用"我的清单"当真值,会把别人的真命中读成误报。 判"这是不是内部标识"时,
清单的边界就是判据的边界。

三、那么补一条"裸名"规则可行吗 —— 量了误报率

在 dashboard 的 app/ 下 125 个源文件上跑
(feedback|reference|project)_[a-z][a-z0-9_]{9,}:

命中 6 处；逐条看过,6 处**全是**内部 memory slug,0 处普通标识符

也就是说在这棵树上,这条形状规则的精确率是 6/6。
(我先前担心它会误伤 project_settings 那类名字 —— 在这个仓里没有发生;
其它仓要各自量过再说,别把这一个仓的结果当普适结论。)

⇒ 做统一决定时,"能不能自动判"这一格现在有数据了:能,而且不需要把真值清单塞进公开 CI ——
形状规则在这棵树上就够。

[vansin]

三个仓共享同一个盲点:判据只认 [[…]],裸写的名字一个都抓不到

上面比的是三道门的覆盖范围不一致。这条是另一件事:范围之外,判据本身也一致地漏。

主仓那道门,变异实测

在 origin/main 的干净检出上跑 .github/scripts/check-no-memory-slugs.py
(先见绿:scanned 1186 file(s) / OK),然后逐条注入:

见 [[feedback_tolerant_assertion_accepts_noncompliance]]。   → 🔴 抓住   exit=1
// See feedback_tolerant_assertion_accepts_noncompliance.    → ✅ 放行   exit=0
按 feedback_verify_both_directions_with_real_data.md 的判据   → ✅ 放行   exit=0

判据是:

SLUG_RE = re.compile(r"\[\[(feedback|project|reference|user)_[a-z0-9_-]+(?:\.md)?\]\]")

[[ ]] 是必需的。 dashboard 那份(\[\[[A-Za-z0-9_-]+\]\])同理,app 那份也同理 ——
三个仓一致。

于是数一下:主仓当前有多少裸引用

判据:命中本机 19 个记忆命名空间合计 964 条真实 slug 名之一(不是形状猜测),
扫 EXTENSIONS = {.ts .tsx .js .jsx .mjs .cjs .md .yml .yaml .sh .py},跳过门自己那个文件。

白名单内(docs/sop、docs/rfcs、docs/research、docs/troubleshooting、docs/tests)   85 处 —— 政策允许
🔴 白名单外                                                                        47 处

白名单外那 47 处落在门确实会扫的路径和扩展名上,只是判据抓不到:

 24  docs/team-collab-playbook.md
  6  docs/plans/RFC-011-implementation-plan.md
  4  docs/sdk-upgrade-2026-05-12-baseline.md
  4  docs/analysis/hub-per-node-endpoints-2026-07-31.md
  2  docs/architecture.md
  2  server/src/file-download-date-bucket.test.ts
  1  agent-network/bin/cli.ts

sleep2agi/agent-network 是 public。

这对「统一决定」意味着什么

正文在讨论三个仓的覆盖范围该怎么统一。这条说明:光统一范围不够 ——
三份判据统一之后,如果仍然只认 [[…]],那 47 处照样在公开 main 上。

补裸名规则可不可行,我量过误报:

• dashboard app/ 125 个源文件:形状规则命中 6 处,6/6 全是真 slug
• 主仓全树:命中 146 处,其中 132 处是真 slug、14 处不是
  (不是的那些像 user_token_required、project_explicit_rc —— 测试脚本里的普通变量名)

⇒ 主仓需要一个比纯形状更严的判据(例如要求下划线段数 ≥ 4,或维护一份前缀例外),
不能照抄 dashboard 那条。一个仓量出来的精确率不能直接搬到另一个仓。

[vansin]

今晚在两个仓上都跑过这道门,量到的东西比「口径不一致」更具体。先说一句:agent-network 这道门本身是诚实的 —— 它在代码里写明了自己的豁免范围和理由。问题不在它撒谎,在它够不着。

一、两个仓的门,失效方式完全不同

agent-network(check-no-memory-slugs.py)—— 豁免是声明过的

# Path-prefix allowlist for the initial rollout. The pre-existing 57
# legacy references in these trees are historical design context …
ALLOWLIST_PATH_PREFIXES = ("docs/sop/", "docs/rfcs/", "docs/research/",
                           "docs/troubleshooting/", "docs/tests/")

跑它:scanned 1220 file(s) … OK: no internal memory-slug references found,exit 0。

这是一个有边界、有理由、写在代码里的豁免 —— 不是假绿。能一眼看出它豁免了什么,这本身是好设计。

agent-network-app(scrub-guard.yml)—— 豁免是没人知道的

它的范围是 src/** + App.tsx,job 名写着 "in code";而 docs/RFC-026:150 里有一个真的 slug,一直没人看它。同时它用 grep -F '['+'[' 匹配「任意两个左方括号」,把一条合法的 IPv6 正则判成泄漏,昨晚把 main 合红了。

已在 app #36 修掉:范围加 docs/**/*.md、匹配收紧到 slug 形状、那条真 slug 换成散文。三条证据(当前树绿 / 放回 slug 变红 / 旧 IPv6 写法不再误报)都在 PR 里。

二、🔴 主仓那个 57,今天是 60 —— 而这不是最要紧的

带方括号的 [[feedback_xxx]] 引用(排除门自己):  60 处 / 17 个文件

注释写的是 57。一个写在注释里的计数,会随每一次新增悄悄失准 —— 今晚我在别处已经记过这个形状三次(行号 pin、计数 pin、TODO 里的版本号)。建议把它改成「截至 2026-08-18 为 60」,加上日期它就从一个会过期的事实变成一条永远为真的记录。

三、🔴 真正要紧的:同一份信息还有一种门完全看不见的写法

裸 slug 名(feedback_xxx,不带方括号):  约 116 处 / 29 个文件

举两个实例:

docs/tests/release-gate-playbook.md:174
  … per 通信龙 self-correction in [feedback_pane_vs_commhub_truth](../../memory))

docs/team-collab-playbook.md   24 行
docs/sop/methodology.md        22 行

第一条尤其说明问题:它把 slug 名写成了链接文字,链接目标是 ../../memory —— 一个仓外的私有目录。

泄漏的信息和 [[feedback_pane_vs_commhub_truth]] 一模一样,但:

• 主仓的门按方括号形状匹配 → 看不见
• app 仓修好之后按 slug 形状匹配 → 同样看不见

⇒ 两个仓的门都在防「那个括号」,而要防的是「那个名字」。

建议:统一口径时,把判据定在「名字」上而不是「包装」上

1. 判据:匹配 (feedback|project|reference|user)_[a-z0-9_-]{6,},不要求方括号。方括号只是它今天最常见的一种写法。
2. 范围:两个仓都覆盖 docs/ 与源码;主仓保留 allowlist,但把豁免的数字带上日期,并按树逐个退役(注释里已经写了「REMOVE entries as their backing tree is audited」,这个设计是对的)。
3. 迁移:去掉方括号不算修好。判据一旦落在名字上,今天那 116 处会立刻变红 —— 所以要么先清、要么把它们也放进有日期的 allowlist。不能靠「换个写法」绕过。

我没做的

没有动主仓的门。 它的豁免是有意的、写明了理由的,收紧它会让 60+116 处立刻变红 —— 那是一个需要人决定节奏的动作,不是我顺手能做的。本条只提供数字和口径建议。