ruflo market-ingest 实战：市场数据归一化、OHLCV 向量化与 HNSW 索引的完整接入流程-二趣网

ruflo market-ingest 实战：市场数据归一化、OHLCV 向量化与 HNSW 索引的完整接入流程

【免费下载链接】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 仓库中plugins/ruflo-market-data插件的market-ingest技能展开，讲解如何将原始行情数据（价格与成交量）抓取、归一化为 OHLCV 向量、编码为 64 维定长向量并写入 HNSW 索引，从而为后续的 K 线形态检测与相似度检索做好准备。读完本文，你将掌握该技能的完整六步接入流程、每维向量背后的归一化公式、memory_*与agentdb_hierarchical-*两套工具的路由差异这一关键陷阱，以及插件如何以 smoke 脚本作为契约进行自验证。

技能定位：形态检测前的第一步数据管线

market-ingest是 ruflo 市场数据插件的两项核心技能之一，其定义文件为 skills/market-ingest/SKILL.md。该技能的前置元数据声明了它的参数提示与允许调用的工具集：

name: market-ingest description: Ingest and normalize market data into OHLCV vectors with HNSW indexing argument-hint: "<symbol> [--source api]" allowed-tools: Bash mcp__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__memory_search mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_create mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_add mcp__plugin_ruflo-core_ruflo__embeddings_generate

从这份 frontmatter 可以看出两点设计意图：

调用形态为/market-ingest <symbol> [--source api]，即以一个交易符号（symbol）为核心参数，--source可选地指定数据来源（REST API、CSV 文件或手工输入）；
允许的工具被严格收敛为"存储 + 索引 + 嵌入"三类 MCP 工具加Bash，符合插件最小权限的思路——Bash的存在正是为了支撑文末给出的 CLI 备用路径。

该技能处于数据管线的最上游：README 将其描述为 "Ingest and normalize market data into OHLCV vectors with HNSW indexing"，是运行market-pattern形态检测或跨标的比较之前的必经步骤。插件整体由 1 个 agent（data-engineer）+ 2 个 skills + 1 个 command（含 5 个子命令）组成，其中market ingest子命令在 commands/market.md 中给出了与技能一致的六步描述。

六步接入流程：从抓取到报告

技能主体定义了六个步骤，下面逐步拆解并结合仓库文档补充细节。

第 1 步：Fetch data（抓取）

从配置好的数据源获取该 symbol 的 OHLCV 数据，支持 REST API、CSV 文件或手工输入三种来源。这一步的产出是后续所有计算的原料：每个 K 线周期（candle）包含 open/high/low/close 四个价格与 volume 一个量值。

第 2 步：Normalize（归一化）

这是整个技能中最关键的一步。原始价格具有绝对量纲，不同标的之间、同一标的不同时期之间不可直接比较，因此必须先转换为无量纲的相对值。SKILL.md 与 agents/data-engineer.md 给出的归一化公式完全一致：

字段	归一化方式	公式
Open	相对前一收盘价	`(open - prev_close) / prev_close`
High	相对开盘价	`(high - open) / open`
Low	相对开盘价	`(low - open) / open`
Close	相对开盘价	`(close - open) / open`
Volume	滚动 Z-score	`(vol - mean_vol) / std_vol`

这套设计值得注意：价格类字段全部转换为"日内/日际变化率"，因此一个 K 线的向量刻画的是形态本身（跳空幅度、上影线、下影线、收盘强弱、量能异动），而不是价格水平。这使同一形态在不同价位、不同标的上都能得到相近的向量表示，正是后面 HNSW 相似度检索能够跨标的工作的基础。成交量则用滚动均值/标准差做 Z-score，突出"量能异常"这一信息。

第 3 步：Vectorize（向量化）

每个 K 线被编码为64 维定长向量：5 个归一化后的 OHLCV 值加上填充（padding）至 64 维。data-engineer.md 进一步给出了多 K 线形态的编码策略：

单 K 线形态：5 维（归一化 OHLCV）；
多 K 线形态：5 × N 维（N 根 K 线 OHLCV 拼接）；
元数据向量：3 维（pattern_type_id、reliability_score、trend_direction）；
最终统一 padding 到 64 维供 HNSW 索引。

定长 padding 是 HNSW 这类固定维度索引引擎的硬性要求——所有向量必须同维才能构建距离图。技能文档在此还明确了一个工具名陷阱：对形态描述做语义嵌入时，必须调用mcp__plugin_ruflo-core_ruflo__embeddings_generate，embeddings_embed这个工具名并不存在。这一点并非笔误式警告，而是插件契约 ADR 修复过的真实缺陷，下文会展开。

第 4 步：Store（按命名空间存储）

调用mcp__plugin_ruflo-core_ruflo__memory_store --namespace market-data，以 "symbol+date" 为 key 持久化归一化后的 OHLCV 数据。技能文档在这里特别强调了路由规则：

memory_*工具族按namespace路由；agentdb_hierarchical-*工具族按tier（working | episodic | semantic）路由，会忽略 namespace 字符串。因此本步骤必须用memory_*。

这是 ruflo 插件体系中一个反复出现的坑：如果在agentdb_hierarchical-store上传namespace: 'market-data'，参数会被静默丢弃，数据落入错误的层级分区。ADR-0001 记录的三个真实 bug 中，第 2 个正是本技能此前用agentdb_hierarchical-store配 namespace 参数导致的，修复方式就是切换到 namespace 路由的memory_*。

命名空间归属也有明确约定（见 README "Namespace coordination"）：本插件独占两个 kebab-case 命名空间——

market-data：每 symbol+date 的归一化 OHLCV 向量；
market-patterns：带可靠度评分的已检测形态（由market-pattern技能写入）。

同时约定保留命名空间（pattern、claude-memories、default）不得被占用。

第 5 步：Index（HNSW 建索引）

调用mcp__plugin_ruflo_core_ruflo__ruvllm_hnsw_add（实际前缀为mcp__plugin_ruflo-core_ruflo__）将向量加入 HNSW 索引，使后续最近邻检索可用。索引创建走ruvllm_hnsw_create，检索走ruvllm_hnsw_route——这三个 HNSW 工具由 CLI 的 MCP 工具层实现，可在 v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts 中找到对应注册与测试（v3/@claude-flow/cli/tests/ruvllm-tools.test.ts）。语义嵌入侧的工具则定义在 v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts，那里提供的是embeddings_generate——与技能文档中"不要用embeddings_embed"的告诫互相印证。

第 6 步：Report（报告）

运行结束输出摘要：摄入 K 线数量、日期范围、价格区间、平均成交量。commands/market.md 中的market ingest描述还补充了 min/max/avg 价格与成交量画像（volume profile），方便人工核对数据覆盖是否完整。

CLI 备用路径与插件加载方式

技能文档提供了不依赖 MCP 会话的 CLI 等价命令：

npx @claude-flow/cli@latest memory store --namespace market-data --key "symbol-SYMBOL-DATE" --value "OHLCV_JSON"

其中--key遵循symbol-SYMBOL-DATE的命名约定（symbol 大写、日期按天粒度），--value为归一化后的 OHLCV JSON。检索侧的等价命令可在姊妹技能 market-pattern/SKILL.md 中看到：

npx @claude-flow/cli@latest memory search --query "bullish reversal patterns" --namespace market-patterns npx @claude-flow/cli@latest memory store --key "pattern-AAPL-2026-05-04-doji" --value '{...}' --namespace market-patterns

整个插件通过指定插件目录加载：

claude --plugin-dir plugins/ruflo-market-data

兼容性上，README 将 CLI 固定在@claude-flow/cliv3.6（major+minor），插件版本 0.2.1 并在.claude-plugin/plugin.json中声明了mcp、candlestick-patterns、namespace-routing三个关键词——这几项恰好都被 scripts/smoke.sh 的第一项检查所校验。

上游教训：两个真实 bug 与契约化验证

理解market-ingest的两个"反直觉"细节，需要看它的契约 ADR。ADR-0001 记录了该插件（v0.1.0）在技能文件中发现的三个真实缺陷：

embeddings_embed工具名不存在，真实工具是embeddings_generate；
用agentdb_hierarchical-store配namespace: 'market-data'，namespace 参数被静默忽略（该工具族按 tier 路由）；
market-pattern中的同类 hierarchical-recall / pattern-store namespace 问题。

修复方案统一为：namespaced 读写一律改走memory_*工具族；语义嵌入统一使用embeddings_generate；插件版本从 0.1.0 升到 0.2.x。ADR 的"负面后果"一节很坦率：任何之前按错误工具名写脚本的人本来就在静默失败，所以修复的净影响为零——这正是"契约必须可机器验证"的动机。

为此插件将scripts/smoke.sh定义为契约（"smoke as contract"），共 11 项结构检查，其中与本技能直接相关的回归项包括：

第 3 项：全插件范围内embeddings_embed不得再出现在任何工具调用位点（ADR 与 README 中的说明性引用除外）；
第 4 项：market-ingest/SKILL.md必须含memory_store，且不允许再出现agentdb_hierarchical-store与market-data同句的违规组合；
第 7 项：market-ingest必须引用真实存在的embeddings_generate。

运行方式与预期输出：

bash plugins/ruflo-market-data/scripts/smoke.sh # Expected: "11 passed, 0 failed"

这 11 项检查覆盖版本与关键词、两个技能 + agent + command 的 frontmatter 完整性、v3.6 固定、命名空间声明、ADR 状态等，使"文档漂移"（文档写错工具名而无人发现）成为可被 CI 拦截的失败。

与下游的衔接：形态检测与模式检索

market-ingest的产出直接服务两条下游链路：

形态检测：market-pattern技能先memory_search/memory_list从market-data命名空间召回归一化数据，再扫描单 K 线（doji、hammer）、双 K 线（engulfing）、三 K 线（morning star、three white soldiers）到多 K 线（head & shoulders、double top/bottom）形态，检测出的形态按双路径写入——agentdb_pattern-store（typed、ReasoningBank 路由，不传namespace）与memory_store --namespace market-patterns（namespace 路由），该双路径写法沿用 ruflo-cost-tracker ADR-0001 的先例；
历史检索：market search子命令经ruvllm_hnsw_route在 HNSW 索引中做最近邻查询，再从market-patterns命名空间召回匹配条目，按相似度与时间新鲜度排序。

插件的 README 也列出了模式库概览：Doji（1 K 线，中等可靠度）、Hammer（1 根，中高）、Engulfing（2 根，高）、Morning/Evening Star（3 根，高）、Three White Soldiers（3 根，高）、Head & Shoulders（5–7 根，很高）、Double Top/Bottom（可变，高），每种形态同样编码为 64 维 padding 向量。生态上，README 指明消费方为ruflo-neural-trader（将市场形态作为策略信号）、ruflo-ruvector（HNSW 索引引擎）、ruflo-agentdb（命名空间约定的拥有者）。

小结

market-ingest技能虽然只有几十行 Markdown，却浓缩了 ruflo 插件体系的三条工程纪律：归一化公式保证跨标的可比性（变化率 + Z-score，而非原始价格）；64 维定长 padding 保证 HNSW 可索引；namespace 路由纪律保证数据落在正确的分区（memory_*按 namespace 路由，agentdb_hierarchical-*按 tier 路由，二者不可混用）。配合 smoke.sh 的 11 项契约检查与 ADR-0001 的缺陷记录，这套"技能文档 + 契约脚本 + 决策记录"的三层结构使数据接入流程既可复制运行，又能防止文档与工具名漂移——这也是研究 ruflo 插件机制时值得注意的实践样本。

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

企业官网建设流程全解析