ruflo-neural-trader 插件契约解析五命名空间协调、版本锚定与 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-neural-trader是 ruflo 生态中基于npx neural-traderRust/NAPI 绑定构建的神经交易插件。本文以其插件级架构决策记录 ADR-0001 为主体系统讲解该插件如何通过规范五命名空间集合 README 契约段落 smoke 脚本即契约三层机制把命名空间协调、版本锚定、内容完整性与安全约束固化为可机器验证的契约。读完本文你将掌握插件的 5 个 AgentDB 命名空间如何划分与协调、trading-前缀设计取舍背后的依据、以及如何用一条命令11 项检查验证整个插件契约的符合性。背景一份已符合规范的插件契约ADR-0001状态Accepted2026-05-04 提出、2026-05-09 更新记录的是一份以文档形式把既有事实固化为契约的决策。其背景对象是ruflo-neural-traderv0.2.0——一个通过npx neural-trader调用神经交易能力的 Ruflo 插件底层为 Rust/NAPI 绑定实现的神经交易引擎对外暴露112 个 MCP 工具README 中记载其回测性能为 Python 方案的 8–19 倍见 README.md 的 Performance 一节插件侧资产为4 个专用 Agent 9 个 Skills 1 个命令全部内存访问均通过memory_*命名空间路由完成审计未发现路由错误。这份 ADR 的特殊之处在于它不是规划未来改动而是把已经符合规范的现状写成契约并补上三个此前缺失的工程缺口——插件级 ADR、冒烟测试、Compatibility兼容性段落。用 ADR 自己的话说这是already-compliant已合规类型的契约记录。命名空间审计规范五命名空间集合契约的核心是命名空间namespace协调。ADR-0001 明确插件当前使用5 个命名空间全部遵循 kebab-case 的plugin-stem-intent插件词干-意图命名约定该约定的权威定义来自 ruflo-agentdb ADR-0001「Namespace convention」一节。这 5 个命名空间的规范集合由 ADR-126 Phase 1 定义命名空间用途生命周期特征trading-strategies策略定义、参数、regime市场状态条件映射由trader-backtest、trader-signal加载trading-backtests历史回测结果按策略 时间戳索引长生命周期ADR-126 Phase 4 起做 Ed25519 签名trading-risk风险模型状态、VaR/CVaR 快照、熔断器触发记录持续累积trading-analysis市场分析师输出——regime 分类、技术指标摘要、模型训练结果分析师落盘trading-signals短期信号事件日内级别短生命周期ADR-126 Phase 2 施加 24h TTL为什么前缀是trading-而不是neural-trader-ADR 特别强调了一个刻意为之的设计决策命名空间前缀取trading-交易这一真实意图而非neural-trader-插件词干。这与plugin-stem-intent约定的广义解释一致——插件的首要关切本身就是交易trading下游消费者真正推理、依赖的是trading这一语义。这个选择在 ADR 中被称为ergonomic tightness人体工学意义上的紧凑性如今已被契约化文档化成为后续插件命名空间设计的参照先例。同时契约重申了三个保留命名空间reserved namespaces不得被遮蔽pattern、claude-memories、default——它们由 AgentDB 插件本身持有ReasoningBank 回退写入、Claude Code 自动记忆桥、memory_store默认值任何下游插件都不应抢占。曾存在的三向不一致ADR-126 Phase 1 修复值得注意的是ADR-0001 标题中的4-namespace claim四命名空间主张指向一个真实存在的缺陷。ADR-126 的调查发现了一个活动 bugREADME 声称 4 个命名空间trading-{strategies,backtests,risk,analysis}、ADR-0001 声称trading-signalstrading-models、而trader-signalskill 实际写入trading-signals——三方对不上且冒烟测试只校验 README 的 4 个名字导致smoke 通过、但信号数据从文档化表面丢失任何按 4 个命名空间发起的 memory 搜索都会静默漏掉全部信号数据。ADR-126 Phase 1 将三处对齐为上述规范五命名空间并在 smoke.sh 第 8 项中加入第五命名空间断言。这正是文档契约能暴露真实数据风险的典型例证。审计发现的另外三个缺口除命名空间外审计还列出三个结构性缺口成为本 ADR 决策的直接动因无插件级 ADR——此前插件的架构决策散落各处没有统一记录入口无冒烟测试——插件是否符合自身声明技能齐全、版本正确、命名空间对齐没有任何自动验证手段无 Compatibility兼容性段落——插件的 CLI 版本锚定、运行时依赖、验证方式没有在 README 中显式声明。决策四项契约条款针对上述背景ADR-0001 提出四项决策全部为插件本地改动不需要修改任何上游引擎代码新增本 ADR状态从 Proposed 走向 AcceptedREADME 增补新增 Compatibility锚定claude-flow/cliv3.6 neural-trader 运行时、Namespace coordination命名空间协调块声明五个命名空间、Verification、Architecture Decisions 四个段落插件元数据保持节奏版本停留在0.2.0后续落地为0.2.1keywords 增加neural-trader-runtime、walk-forward、monte-carlo以冒烟测试为契约新增 scripts/smoke.sh内含11 项结构性检查详见下节。第 3 项已经在 .claude-plugin/plugin.json 中落地当前version为0.2.1keywords 数组已包含neural-trader-runtime、walk-forward、monte-carlo与冒烟脚本第 1 项检查逐一对应。smoke-as-contract11 项结构性检查详解ADR 把契约具象化为一个可执行脚本这是整个决策中最具操作性的部分。scripts/smoke.sh 逐项验证插件的内容完整性与声明一致性任一失败都以非零退出码终止。11 项检查如下#检查内容验证方式源码依据1plugin.json声明版本0.2.1且包含新关键词grep 版本号 逐个检查neural-trader-runtime、walk-forward、monte-carlo三个关键词2全部 9 个 skill 存在且 frontmatter 合法name:/description:/allowed-tools:遍历skills/trader-{backtest,portfolio,regime,risk,signal,train,cloud-backtest,portfolio-cg,explain}/SKILL.md并断言trader-cloud-backtest引用managed_agent_create工具且提供本地trader-backtest回退3全部 4 个 Agent 存在检查agents/backtest-engineer.md、market-analyst.md、risk-analyst.md、trading-strategist.md4命令存在检查 commands/trader.md5README 锚定claude-flow/cliv3.6grepclaude-flow/cli.*v3.6或v3.6.*claude-flow/cli6README 锚定 neural-trader 运行时grepnpx neural-trader或Rust/NAPI7README 委托 ruflo-agentdb 命名空间约定同时 grepruflo-agentdb与Namespace convention8声明全部 5 个规范命名空间逐个 greptrading-strategies/-backtests/-risk/-analysis/-signalsADR-126 Phase 1 新增的第五命名空间断言9回测特性已文档化grep walk-forward、Monte Carlo、parameter optimization 三类关键词10ADR-0001 存在且状态为Accepted检查docs/adrs/0001-neural-trader-contract.md及status: Accepted11skill 中无通配工具授权遍历所有skills/*/SKILL.md禁止出现allowed-tools: *第 11 项是安全约束——技能文件只能枚举明确授权的最小工具集杜绝通配符导致的越权调用。这与 ruflo 生态一贯的最小权限原则一致。双重验证结构契约之外还有运行时契约值得注意的是smoke.sh属于结构契约——它只检查文件存在性、README 锚定与命名空间声明不实际调用neural-trader。与之互补的是 scripts/runtime-smoke.sh后者针对真实安装逐条执行npx neural-trader的 20 个文档化入口基础命令 Kelly 分数 walk-forward Monte Carlo optimize 多标的 pairs adaptive multi-indicator并断言每条返回可解析 JSON 且含预期的command字段。该脚本通过NT_PIN默认2.8.11锁定版本且强制--ignore-scripts安装以规避上游 install 钩子的历史风险README 前言之中的四项 2.5.0–2.7.x 编译/打包缺陷修复记录。两者合起来构成静态结构 动态行为的双重防线。验证与执行契约的验证入口在 ADR 的 Verification 一节与 README 的 Verification 段落保持一致bash plugins/ruflo-neural-trader/scripts/smoke.sh # Expected: 11 passed, 0 failed若需进一步验证真实运行时行为需要本地安装neural-tradernpm 包bash plugins/ruflo-neural-trader/scripts/runtime-smoke.sh # 20 个入口逐条执行期望 20 passed, 0 failed契约的后果评估ADR 对决策后果的评估分两面正向收益插件正式进入节奏化发布队列joins the cadencetrading-而非neural-trader-的前缀取舍被契约化记录作为有意的 ergonomic 决策供后续作者参照命名空间协调、兼容性锚定与验证方式首次有了权威、可执行的单一事实源。负面后果无实质负面影响none material。从后续落地看这份契约的实际收益远超文档本身ADR-126 在此契约基础上叠加了六阶段演进——24h TTL 的信号过期trader-signal/SKILL.md 第 8 步即写入expiresAt、回测去重、HNSW 温启动、共轭梯度组合优化trader-portfolio-cg、Ed25519 见证签名回测工件与归因工件schema 见 src/signed-attribution.ts、以及带风险闸门的 SendMessage 流水线消息 schema 见 src/pipeline-messages.ts风险门禁在 agents/trading-strategist.md 中有强制约束。这些能力都建立在五个命名空间稳定可依赖这一契约前提之上。实现状态与相关文档索引截至当前仓库契约各元素均已落地插件版本0.2.1已发布见 .claude-plugin/plugin.json5 个命名空间全部合规README、ADR-0001、skill 源码三方一致4 个 Agent 9 个 Skills已交付冒烟脚本第 2/3/4 项逐一守护smoke-as-contract 门禁定义于 scripts/smoke.sh11 项检查含第五命名空间断言。进一步阅读的关联文档ruflo-agentdb ADR-0001「Namespace convention」——命名空间命名约定与保留命名空间的权威定义ADR-126neural-trader 基座集成——规范五命名空间的来源、三向不一致 bug 的修复过程及六个演进阶段ruflo-market-data ADR-0001——向上游为交易器提供 OHLCV 数据ruflo-cost-tracker ADR-0001——下游承接 PnL 与成本归因插件 README——Compatibility、Namespace coordination、Verification、Architecture Decisions 四个契约段落的实际落地形态。【免费下载链接】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），仅供参考 ruflo-neural-trader 插件契约解析：五命名空间协调、版本锚定与 smoke-as-contract 验证体系
ruflo-neural-trader 插件契约解析五命名空间协调、版本锚定与 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-neural-trader是 ruflo 生态中基于npx neural-traderRust/NAPI 绑定构建的神经交易插件。本文以其插件级架构决策记录 ADR-0001 为主体系统讲解该插件如何通过规范五命名空间集合 README 契约段落 smoke 脚本即契约三层机制把命名空间协调、版本锚定、内容完整性与安全约束固化为可机器验证的契约。读完本文你将掌握插件的 5 个 AgentDB 命名空间如何划分与协调、trading-前缀设计取舍背后的依据、以及如何用一条命令11 项检查验证整个插件契约的符合性。背景一份已符合规范的插件契约ADR-0001状态Accepted2026-05-04 提出、2026-05-09 更新记录的是一份以文档形式把既有事实固化为契约的决策。其背景对象是ruflo-neural-traderv0.2.0——一个通过npx neural-trader调用神经交易能力的 Ruflo 插件底层为 Rust/NAPI 绑定实现的神经交易引擎对外暴露112 个 MCP 工具README 中记载其回测性能为 Python 方案的 8–19 倍见 README.md 的 Performance 一节插件侧资产为4 个专用 Agent 9 个 Skills 1 个命令全部内存访问均通过memory_*命名空间路由完成审计未发现路由错误。这份 ADR 的特殊之处在于它不是规划未来改动而是把已经符合规范的现状写成契约并补上三个此前缺失的工程缺口——插件级 ADR、冒烟测试、Compatibility兼容性段落。用 ADR 自己的话说这是already-compliant已合规类型的契约记录。命名空间审计规范五命名空间集合契约的核心是命名空间namespace协调。ADR-0001 明确插件当前使用5 个命名空间全部遵循 kebab-case 的plugin-stem-intent插件词干-意图命名约定该约定的权威定义来自 ruflo-agentdb ADR-0001「Namespace convention」一节。这 5 个命名空间的规范集合由 ADR-126 Phase 1 定义命名空间用途生命周期特征trading-strategies策略定义、参数、regime市场状态条件映射由trader-backtest、trader-signal加载trading-backtests历史回测结果按策略 时间戳索引长生命周期ADR-126 Phase 4 起做 Ed25519 签名trading-risk风险模型状态、VaR/CVaR 快照、熔断器触发记录持续累积trading-analysis市场分析师输出——regime 分类、技术指标摘要、模型训练结果分析师落盘trading-signals短期信号事件日内级别短生命周期ADR-126 Phase 2 施加 24h TTL为什么前缀是trading-而不是neural-trader-ADR 特别强调了一个刻意为之的设计决策命名空间前缀取trading-交易这一真实意图而非neural-trader-插件词干。这与plugin-stem-intent约定的广义解释一致——插件的首要关切本身就是交易trading下游消费者真正推理、依赖的是trading这一语义。这个选择在 ADR 中被称为ergonomic tightness人体工学意义上的紧凑性如今已被契约化文档化成为后续插件命名空间设计的参照先例。同时契约重申了三个保留命名空间reserved namespaces不得被遮蔽pattern、claude-memories、default——它们由 AgentDB 插件本身持有ReasoningBank 回退写入、Claude Code 自动记忆桥、memory_store默认值任何下游插件都不应抢占。曾存在的三向不一致ADR-126 Phase 1 修复值得注意的是ADR-0001 标题中的4-namespace claim四命名空间主张指向一个真实存在的缺陷。ADR-126 的调查发现了一个活动 bugREADME 声称 4 个命名空间trading-{strategies,backtests,risk,analysis}、ADR-0001 声称trading-signalstrading-models、而trader-signalskill 实际写入trading-signals——三方对不上且冒烟测试只校验 README 的 4 个名字导致smoke 通过、但信号数据从文档化表面丢失任何按 4 个命名空间发起的 memory 搜索都会静默漏掉全部信号数据。ADR-126 Phase 1 将三处对齐为上述规范五命名空间并在 smoke.sh 第 8 项中加入第五命名空间断言。这正是文档契约能暴露真实数据风险的典型例证。审计发现的另外三个缺口除命名空间外审计还列出三个结构性缺口成为本 ADR 决策的直接动因无插件级 ADR——此前插件的架构决策散落各处没有统一记录入口无冒烟测试——插件是否符合自身声明技能齐全、版本正确、命名空间对齐没有任何自动验证手段无 Compatibility兼容性段落——插件的 CLI 版本锚定、运行时依赖、验证方式没有在 README 中显式声明。决策四项契约条款针对上述背景ADR-0001 提出四项决策全部为插件本地改动不需要修改任何上游引擎代码新增本 ADR状态从 Proposed 走向 AcceptedREADME 增补新增 Compatibility锚定claude-flow/cliv3.6 neural-trader 运行时、Namespace coordination命名空间协调块声明五个命名空间、Verification、Architecture Decisions 四个段落插件元数据保持节奏版本停留在0.2.0后续落地为0.2.1keywords 增加neural-trader-runtime、walk-forward、monte-carlo以冒烟测试为契约新增 scripts/smoke.sh内含11 项结构性检查详见下节。第 3 项已经在 .claude-plugin/plugin.json 中落地当前version为0.2.1keywords 数组已包含neural-trader-runtime、walk-forward、monte-carlo与冒烟脚本第 1 项检查逐一对应。smoke-as-contract11 项结构性检查详解ADR 把契约具象化为一个可执行脚本这是整个决策中最具操作性的部分。scripts/smoke.sh 逐项验证插件的内容完整性与声明一致性任一失败都以非零退出码终止。11 项检查如下#检查内容验证方式源码依据1plugin.json声明版本0.2.1且包含新关键词grep 版本号 逐个检查neural-trader-runtime、walk-forward、monte-carlo三个关键词2全部 9 个 skill 存在且 frontmatter 合法name:/description:/allowed-tools:遍历skills/trader-{backtest,portfolio,regime,risk,signal,train,cloud-backtest,portfolio-cg,explain}/SKILL.md并断言trader-cloud-backtest引用managed_agent_create工具且提供本地trader-backtest回退3全部 4 个 Agent 存在检查agents/backtest-engineer.md、market-analyst.md、risk-analyst.md、trading-strategist.md4命令存在检查 commands/trader.md5README 锚定claude-flow/cliv3.6grepclaude-flow/cli.*v3.6或v3.6.*claude-flow/cli6README 锚定 neural-trader 运行时grepnpx neural-trader或Rust/NAPI7README 委托 ruflo-agentdb 命名空间约定同时 grepruflo-agentdb与Namespace convention8声明全部 5 个规范命名空间逐个 greptrading-strategies/-backtests/-risk/-analysis/-signalsADR-126 Phase 1 新增的第五命名空间断言9回测特性已文档化grep walk-forward、Monte Carlo、parameter optimization 三类关键词10ADR-0001 存在且状态为Accepted检查docs/adrs/0001-neural-trader-contract.md及status: Accepted11skill 中无通配工具授权遍历所有skills/*/SKILL.md禁止出现allowed-tools: *第 11 项是安全约束——技能文件只能枚举明确授权的最小工具集杜绝通配符导致的越权调用。这与 ruflo 生态一贯的最小权限原则一致。双重验证结构契约之外还有运行时契约值得注意的是smoke.sh属于结构契约——它只检查文件存在性、README 锚定与命名空间声明不实际调用neural-trader。与之互补的是 scripts/runtime-smoke.sh后者针对真实安装逐条执行npx neural-trader的 20 个文档化入口基础命令 Kelly 分数 walk-forward Monte Carlo optimize 多标的 pairs adaptive multi-indicator并断言每条返回可解析 JSON 且含预期的command字段。该脚本通过NT_PIN默认2.8.11锁定版本且强制--ignore-scripts安装以规避上游 install 钩子的历史风险README 前言之中的四项 2.5.0–2.7.x 编译/打包缺陷修复记录。两者合起来构成静态结构 动态行为的双重防线。验证与执行契约的验证入口在 ADR 的 Verification 一节与 README 的 Verification 段落保持一致bash plugins/ruflo-neural-trader/scripts/smoke.sh # Expected: 11 passed, 0 failed若需进一步验证真实运行时行为需要本地安装neural-tradernpm 包bash plugins/ruflo-neural-trader/scripts/runtime-smoke.sh # 20 个入口逐条执行期望 20 passed, 0 failed契约的后果评估ADR 对决策后果的评估分两面正向收益插件正式进入节奏化发布队列joins the cadencetrading-而非neural-trader-的前缀取舍被契约化记录作为有意的 ergonomic 决策供后续作者参照命名空间协调、兼容性锚定与验证方式首次有了权威、可执行的单一事实源。负面后果无实质负面影响none material。从后续落地看这份契约的实际收益远超文档本身ADR-126 在此契约基础上叠加了六阶段演进——24h TTL 的信号过期trader-signal/SKILL.md 第 8 步即写入expiresAt、回测去重、HNSW 温启动、共轭梯度组合优化trader-portfolio-cg、Ed25519 见证签名回测工件与归因工件schema 见 src/signed-attribution.ts、以及带风险闸门的 SendMessage 流水线消息 schema 见 src/pipeline-messages.ts风险门禁在 agents/trading-strategist.md 中有强制约束。这些能力都建立在五个命名空间稳定可依赖这一契约前提之上。实现状态与相关文档索引截至当前仓库契约各元素均已落地插件版本0.2.1已发布见 .claude-plugin/plugin.json5 个命名空间全部合规README、ADR-0001、skill 源码三方一致4 个 Agent 9 个 Skills已交付冒烟脚本第 2/3/4 项逐一守护smoke-as-contract 门禁定义于 scripts/smoke.sh11 项检查含第五命名空间断言。进一步阅读的关联文档ruflo-agentdb ADR-0001「Namespace convention」——命名空间命名约定与保留命名空间的权威定义ADR-126neural-trader 基座集成——规范五命名空间的来源、三向不一致 bug 的修复过程及六个演进阶段ruflo-market-data ADR-0001——向上游为交易器提供 OHLCV 数据ruflo-cost-tracker ADR-0001——下游承接 PnL 与成本归因插件 README——Compatibility、Namespace coordination、Verification、Architecture Decisions 四个契约段落的实际落地形态。【免费下载链接】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），仅供参考