ruflo-observability 插件契约ADR-0001解读namespace 路由修复与 smoke-as-contract 验证体系【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/rufloruflo-observability 是 ruflo 插件体系中负责可观测性的模块提供结构化日志、分布式追踪与带异常检测的指标采集。本文以 ADR-0001插件契约 为主体结合插件源码与 CLI 层 MCP 工具实现完整讲解namespace 路由 Bug 的根因与修复路径以及以 smoke.sh 作为可执行契约的工程实践读完后你将掌握 ruflo 插件如何在 AgentDB 双路由体系namespace 路由 vs tier 路由下正确读写命名空间数据并能独立读懂与复用 smoke-as-contract 的十项结构校验。背景一个会被静默忽略的 namespace 参数ruflo-observabilityv0.1.0由 1 个 Agentobservability-engineer、2 个 Skillobserve-trace、observe-metrics和 1 个命令observe含 5 个子命令构成。它负责将 swarm 多 Agent 协作产生的遥测数据span、指标快照、日志条目写入 AgentDB 并按需召回。在 ADR-0001 之前该插件的两个 Skill 都存在同一类 bug调用agentdb_hierarchical-recall时传入namespace: observability参数期望按命名空间读取数据。但根据 ruflo-agentdb ADR-0001命名空间约定 的定义工具族存在双路由体系agentdb_hierarchical-*家族按tier路由working | episodic | semantic完全忽略 namespace 字符串agentdb_pattern-*家族按 ReasoningBank 路由同样忽略 namespace只有memory_*memory_store/memory_search/memory_list与embeddings_search路径才真正接受并应用 namespace 参数。也就是说observability这个 namespace 参数传给了agentdb_hierarchical-recall后会被静默丢弃——调用不报错但读取结果完全错误。这是成本追踪ruflo-cost-tracker、行情数据ruflo-market-data、数据迁移ruflo-migrations插件共有的同一类 bugADR-0001 的 Related 部分明确列出这三个同病类插件属于跨插件的系统性文档/调用偏差。决策三项功能修复与两项工程加固ADR-0001状态 Accepted日期 2026-05-04更新于 2026-05-09作出如下决策功能修复核心将两个 Skill 中的命名空间读取从agentdb_hierarchical-recall切换为memory_search/memory_list真正的 namespace 路由并在 observe-metrics 中记录双 pattern-store 路径。文档加固README 增补 Compatibility锁定 CLI v3.6、Namespace coordination声明observability命名空间归属、Verification 与 Architecture Decisions 小节。版本与元数据0.1.0 → 0.2.0仓库中 plugin.json 实际为0.2.1keywords 新增mcp、distributed-tracing、anomaly-detection。契约化新增 scripts/smoke.sh以 10 项结构检查作为插件契约。根因深入memory_* 与 hierarchical-* 的路由差异源码级佐证要真正理解这次修复需要对比 CLI 层 MCP 工具的真实语义。v3/claude-flow/cli/src/mcp-tools/memory-tools.ts中memory_store/memory_search/memory_list均接受namespace参数memory_store的输入 schema 明确声明namespace字段Namespace for organization (default: default)并在实现中执行const namespace (input.namespace as string) || defaultmemory-tools.tsmemory_list同样解析 namespace 并回传{ key, namespace }输入校验函数validateMemoryInput(key, value, query, namespace)还会拒绝含危险字符路径穿越 / shell 元字符的 namespacememory-tools.ts。而agentdb_hierarchical-*家族的路由键是 tiernamespace 参数既不被校验也不被应用。这正是静默失败的来源错误调用不报错数据却读不到。因此 ADR-0001 将其归类为silent ignored-namespace reads并指出负面影响为零——任何依赖旧错误调用的脚本本来就在静默失败。修复落地observe-metrics 与 observe-trace 的命名空间读写修复后两个 Skill 的读写路径如下。observe-metricsskills/observe-metrics/SKILL.md读取指标调用mcp__plugin_ruflo-core_ruflo__memory_search --namespace observability或memory_list获取指定周期默认 1 小时的指标记录聚合Counter 求和tasks_completed、errors、token_usage、Gauge 取当前值active_agents、memory_usage_bytes、Histogram 计算 p50/p95/p99task_duration_ms、span_duration_ms建立基线调用mcp__plugin_ruflo-core_ruflo__agentdb_pattern-searchReasoningBank 路由注意不要传 namespace 参数——pattern-* 工具会忽略它异常标记与基线偏离 2 个标准差时标记异常并标注方向高于/低于与严重度双路径存储对应 ADR-0001 决策第 1 条的document the dual pattern-store path模式库路径类型化推荐mcp__plugin_ruflo-core_ruflo__agentdb_pattern-storetype: metric-snapshot不传 namespace普通存储路径可 namespace 路由mcp__plugin_ruflo-core_ruflo__memory_store --namespace observability将快照与时间戳绑定报告输出指标名、当前值、基线、偏差、趋势up/down/stable、异常标记以及整体健康分green/yellow/red。observe-traceskills/observe-trace/SKILL.md收集 spanmemory_search --namespace observability或memory_list按task-id召回全部 span构建 trace 树依据parentSpanId组织父子层级根 span 置顶计算时序每个 span 计算 durationendTime - startTime识别关键路径最长串行 span 链定位瓶颈标记超过该操作类型 p95 时长的 span以及 span 间空隙空闲时间异常的 span上下文合成调用mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize将 span 元数据整合为执行流程的叙事性摘要报告输出 span 名、agent、duration、状态OK/ERROR、瓶颈标记以及总 trace 时长与关键路径时长。两个 Skill 的allowed-tools前端元数据均只授予memory_search、memory_list外加agentdb_pattern-*、agentdb_semantic-route、agentdb_context-synthesize等不再授予agentdb_hierarchical-recall——这与 smoke.sh 第 10 项无通配符工具授权共同构成权限面的最小化约束。Namespace coordinationobservability 命名空间的归属与约束README 的 Namespace coordination 小节明确了契约边界本插件拥有observability这个 AgentDB 命名空间基名例外先例同federation、migrations依据 ruflo-agentdb ADR-0001 的 Namespace convention保留命名空间不可遮蔽patternReasoningBank 回退写入处、claude-memoriesClaude Code 自动记忆桥接目标、defaultmemory_store默认值三者 MUST NOT 被 shadowobservability命名空间必须通过memory_*工具访问namespace 路由存放 span、指标快照与日志条目。ruflo-agentdb ADR-0001 还补充了通用命名规范plugin-stem-intent的 kebab-case 命名、namespace 不得含:与桥接层键内分隔符冲突、长度 ≤200 字符、必须通过validateIdentifier校验。这些约束使跨插件的数据读写具备可预测性。以 smoke.sh 为契约十项结构检查逐条解析ADR-0001 的工程亮点是smoke as contract不再依赖人肉核对文档而是把契约写成可执行脚本 scripts/smoke.sh。运行方式bash plugins/ruflo-observability/scripts/smoke.sh # Expected: 10 passed, 0 failed脚本逐项输出→ 检查名 ... PASS/FAIL最终汇总N passed, N failed任一失败即exit 1。十项检查对应 ADR-0001 决策第 5 条具体为#检查项校验内容1plugin.json 声明 0.2.1 与新 keywords版本号精确匹配0.2.1且mcp、distributed-tracing、anomaly-detection三个 keyword 全部存在2两个 Skill Agent Command 齐备observe-trace、observe-metrics的 SKILL.md 均含name:、description:、allowed-tools:前置元数据agents/observability-engineer.md与commands/observe.md存在3observe-trace 使用memory_*做命名空间读取含memory_search/memory_list且不含agentdb_hierarchical-recall.observability或反向组合回归防复发4observe-metrics 使用memory_*做命名空间读取同上判定逻辑5observe-metrics 记录了双 pattern-store 路径同时包含ReasoningBank与memory_store --namespace observability6/observe命令覆盖 5 个子命令trace、metrics、logs、dashboard、correlate全部出现7README 锁定claude-flow/cliv3.6匹配claude-flow/cli.*v3.6或反向组合8README 引用 ruflo-agentdb 命名空间约定同时含ruflo-agentdb与Namespace convention9ADR-0001 存在且状态为 Accepted文件存在且status: Accepted10无通配符工具授权所有skills/*/SKILL.md的allowed-tools:不以*结尾其中第 3、4 项正是 ADR-0001 修复的直接回归测试一旦有人把agentdb_hierarchical-recall加回 Skill 并与observability命名空间绑定契约立刻失败。第 1 项的版本锁定与第 7 项的 CLI 兼容性锁定共同构成插件元数据 运行时依赖双层 pinning。smoke.sh 的工程要点单一真实来源脚本以ROOT$(cd $(dirname $0)/.. pwd)定位插件根目录全部检查相对$ROOT进行可在任意工作目录执行结构即契约不依赖真实运行时与 MCP daemon全部为grep文件检查因此冷启动环境、无模型环境也能稳定通过——这是与 ruflo-agentdb ADR-0001 中依赖 daemon 健康的运行时 smoke 不同的定位版本演进感知第 1 项把版本号硬编码为0.2.1与 plugin.json 一致发布新版本时需同步更新此检查错误信息可定位每项失败都会输出具体缺项如missing keywords: distributed-tracing、still-uses-hierarchical-recall便于直接修复。验证与关联在仓库根目录执行bash plugins/ruflo-observability/scripts/smoke.sh # Expected: 10 passed, 0 failed该命令同时是 README 的 Verification 小节声明、ADR-0001 的 Verification 小节声明与 smoke.sh 自身的契约输出三者指向同一结果构成文档-决策-脚本三方一致。关联文档与同病类插件均可作为同类契约的参照实现ruflo-cost-tracker ADR-0001 —— 同 bug 类也是 observe-metrics 双路径模式pattern-store / memory_store的出处ruflo-market-data ADR-0001 —— 同 bug 类ruflo-migrations ADR-0001 —— 同 bug 类ruflo-agentdb ADR-0001 —— namespace 约定的定义者与路由规则来源。实施状态与总结ADR-0001 的 Implementation status 确认插件以 v0.2.0 发布并进入 marketplace.json源码位于plugins/ruflo-observability/。契约要素全部落地——两个 Skill 的 namespace 路由 Bug 已修复agentdb_hierarchical-recall→memory_search/memory_list、observe-metrics 记录了双 pattern-store 路径、smoke-as-contract 门禁定义于 scripts/smoke.sh。回顾这一 ADR 的工程价值可以提炼为三点可复用的方法论认识工具族的路由边界在 ruflo 的 AgentDB 体系中hierarchical-*按 tier、pattern-*按 ReasoningBank、memory_*按 namespace是三条互不相通的路由路径传参前必须先确认目标工具是否真的消费该参数否则就是静默错误文档契约化把必须使用 memory_* 读取命名空间数据这类规则写进可执行 smoke 脚本比任何 README 声明都可靠——回归测试就是防复发的最后防线跨插件归因同一 bug 类在 cost-tracker、market-data、migrations 中反复出现说明此类问题应通过共享约定ruflo-agentdb 的 namespace convention从源头治理而非各插件各自修补。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考