ruflo-observability 插件契约（ADR-0001）解读：namespace 路由修复与 smoke-as-contract 验证体系-平芜编程栈

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/ruflo

ruflo-observability 是 ruflo 插件体系中负责可观测性的模块，提供结构化日志、分布式追踪与带异常检测的指标采集。本文以 ADR-0001（插件契约）为主体，结合插件源码与 CLI 层 MCP 工具实现，完整讲解"namespace 路由 Bug 的根因与修复路径"以及"以 smoke.sh 作为可执行契约"的工程实践，读完后你将掌握 ruflo 插件如何在 AgentDB 双路由体系（namespace 路由 vs tier 路由）下正确读写命名空间数据，并能独立读懂与复用 smoke-as-contract 的十项结构校验。

背景：一个会被静默忽略的 namespace 参数

ruflo-observability（v0.1.0）由 1 个 Agent（observability-engineer）、2 个 Skill（observe-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）插件共有的同一类 bug（ADR-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.1），keywords 新增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) || 'default'（memory-tools.ts）；
memory_list同样解析 namespace 并回传{ key, namespace }；
输入校验函数validateMemoryInput(key, value, query, namespace)还会拒绝含危险字符（路径穿越 / shell 元字符）的 namespace（memory-tools.ts）。

而agentdb_hierarchical-*家族的路由键是 tier，namespace 参数既不被校验也不被应用。这正是"静默失败"的来源：错误调用不报错，数据却读不到。因此 ADR-0001 将其归类为"silent ignored-namespace reads"，并指出负面影响为零——任何依赖旧错误调用的脚本本来就在静默失败。

修复落地：observe-metrics 与 observe-trace 的命名空间读写

修复后两个 Skill 的读写路径如下。

observe-metrics（skills/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/p99（task_duration_ms、span_duration_ms）；
建立基线：调用mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search（ReasoningBank 路由，注意不要传 namespace 参数——pattern-* 工具会忽略它）；
异常标记：与基线偏离 >2 个标准差时标记异常，并标注方向（高于/低于）与严重度；
双路径存储（对应 ADR-0001 决策第 1 条的"document the dual pattern-store path"）：
- 模式库路径（类型化，推荐）：mcp__plugin_ruflo-core_ruflo__agentdb_pattern-store，type: 'metric-snapshot'，不传 namespace；
- 普通存储路径（可 namespace 路由）：mcp__plugin_ruflo-core_ruflo__memory_store --namespace observability，将快照与时间戳绑定；
报告：输出指标名、当前值、基线、偏差、趋势（up/down/stable）、异常标记，以及整体健康分（green/yellow/red）。

observe-trace（skills/observe-trace/SKILL.md）

收集 span：memory_search --namespace observability（或memory_list）按<task-id>召回全部 span；
构建 trace 树：依据parentSpanId组织父子层级，根 span 置顶；
计算时序：每个 span 计算 duration（endTime - 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 coordination：observability 命名空间的归属与约束

README 的 Namespace coordination 小节明确了契约边界：

本插件拥有observability这个 AgentDB 命名空间（基名例外，先例同federation、migrations，依据 ruflo-agentdb ADR-0001 的 "Namespace convention"）；
保留命名空间不可遮蔽：pattern（ReasoningBank 回退写入处）、claude-memories（Claude Code 自动记忆桥接目标）、default（memory_store默认值）三者 MUST NOT 被 shadow；
observability命名空间必须通过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 条，具体为：

#	检查项	校验内容
1	plugin.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`存在
3	observe-trace 使用`memory_*`做命名空间读取	含`memory_search`/`memory_list`；且不含`agentdb_hierarchical-recall.+observability`或反向组合（回归防复发）
4	observe-metrics 使用`memory_*`做命名空间读取	同上判定逻辑
5	observe-metrics 记录了双 pattern-store 路径	同时包含`ReasoningBank`与`memory_store --namespace observability`
6	`/observe`命令覆盖 5 个子命令	`trace`、`metrics`、`logs`、`dashboard`、`correlate`全部出现
7	README 锁定`@claude-flow/cli`v3.6	匹配`@claude-flow/cli.*v3.6`或反向组合
8	README 引用 ruflo-agentdb 命名空间约定	同时含`ruflo-agentdb`与`Namespace convention`
9	ADR-0001 存在且状态为 Accepted	文件存在且`status: Accepted`
10	无通配符工具授权	所有`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）从源头治理，而非各插件各自修补。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考