ContextForge工具命名空间：生命周期校验不等于并发唯一性

wiki/ai/sources/contextforge-tool-namespace-lifecycle-and-reachability.md

分类：ai / sources · 更新：2026-10-26 09:10

ContextForge工具命名空间：生命周期校验不等于并发唯一性

结论与用户价值

知识轴：MCP Gateway / harness-runtime / sandbox-security / benchmark-evaluation。 联邦工具名的安全合同不是“注册时查一次重名”，而是规范化后的实际调用名、可见域、目录生命周期、并发写入和健康状态分别验收。工具前缀能减少撞名，但拼接/slug并非主体身份；目录刷新失败也不应自动被解释为上游断网。

ContextForge v1.1.0 release API发布时间为2026-10-20，正文版本日期为10-19；不是今日新发布。PR #6534于09-30合并。固定发布tag解析到aee91ff6db63b6aafa77522684a9483c418bb2a3；已读最终service关键函数、slug实现及部分单测，而非用PR patch替代最终tag。未运行pytest、数据库/容器或真实网关。

一阶机制：校验实际名字与投影后状态

build_gateway_tool_invocation_name()以slugify(gateway_name) + separator + slugify(tool_name)构造实际调用名；slug包含小写、标点归并、特殊字符替换及ASCII规范化。因此显示字符串不同不保证最终键不同。校验器复用同一构造语义，而不是拿原始名称做另一套比较。

_validate_tool_name_collisions()先生成更新后的投影：旧tool保留custom alias；rename重算前缀；visibility变化按原继承关系投影，避免粗暴改掉独立配置。随后检查本批重复，再查数据库中同名候选：

public对public冲突，不以owner不同为豁免；
team对相同team的team冲突；
private对相同owner的private冲突。

这是该实现的同类scope规则，不是“所有用户可同时看到的任意scope之间绝不冲突”的证明。 最终调用解析/授权如何处理跨scope同名，仍须独立验收。

生命周期比创建入口更重要

release列出register、refresh、OAuth discovery、reactivation、rename和visibility update的冲突处理；最终service在catalog sync之前验证并由调用方处理rollback。_sync_gateway_catalog()还把按清理策略保留的local aliases纳入比较，不能用“本gateway跳过自身”吞掉应保留的冲突项。

一个重要边界：普通刷新并不回溯清理所有历史外部重复。最终函数只有名称或scope变化的旧tool才进入external-conflict候选；单测存在test_ordinary_refresh_ignores_historical_external_collision，新刷新tool则仍校验。release要求管理员审阅existing duplicate rows，不能声称升级已自动修复旧数据。

reachability与catalog acceptance分账

_mark_gateway_reachable()遇到catalog冲突会调用_recover_gateway_reachability_after_catalog_conflict()：恢复gateway/既有tool的reachable标记、更新last_seen并失效registry/tool lookup缓存，同时告警catalog refresh被拒绝。

这表达了两个不同事实：上游连接恢复与新目录未获准提交。健康绿不等于目录最新，目录冲突不等于网络持续故障。监控应分别输出gateway ID、最近成功目录版本、冲突调用名/可见域及最后连接时间；不要把残留目录请求归为服务宕机。

并发与发布边界

源码注释明确：validation guard不是database uniqueness constraint，concurrent writers不在本操作事务保证内。两个writer都先查不到同名再写入仍是需要另验的竞态，不能用顺序单测推出并发唯一性。是否使用部分唯一索引、锁或其他串行化方案，需要结合真实schema/迁移/事务设计，本文不宣称产品没有其他保护。

PR历史patch与最终tag已有差异，例如保留alias的参数；“PR merged”“release包含改动”“部署运行该版本”“有效配置及数据已清理”是四种不同证据。

对Hermes与内部工具目录的可执行启发

回归矩阵按最终调用名 × public/team/private × 新建/refresh/rename/授权后发现/重激活 × 顺序/并发设计；包含规范化等价名称、custom alias与可见域扩张。
拒绝后读回旧目录、实际调用对象和两上游接收计数器；检查rollback及缓存失效，不仅断言报错。
先做离线导出/小型fixture分析历史重复，数据库审查须先看索引/EXPLAIN；不要照抄release的全表GROUP BY到用户生产大表。
指标至少分连接健康、catalog acceptance、冲突数与最后成功sync；审计再关联实际credential recipient和tool effect。

这些是可复用验收题型，本轮没有更改用户网关、权限、数据库或生产监控。

与已有概念的关系及未解问题

MCP-Gateway-Runtime的注册/调用/撤销合同因此补上namespace生命周期；a2a-name-collision-origin-bound-dispatch说明显示名不能成为主体，二者不能互相当作已修复证据。contextforge-egress-path-parity-dns-rebinding关注实际出站终点，而本页关注选择了哪个工具，两条边界都要过。Agent-Benchmarks与Harness-Engineering可把历史数据、并发竞态及reachable/catalog分离加入可信验收。

未解项是跨scope最终resolver、真实DB约束/多worker竞态、旧重复迁移和实际调用路径；本轮固定源码不覆盖这些E2E，也不是用户实例故障通报。

写入记录

2026-10-26 09:08 CST：新增最终tag的调用名/可见域投影、历史重复与并发边界、连接恢复和目录拒绝分账；上游测试仅阅读未执行。