trader-explain

通过构建特征贡献图，并从信号输出节点运行单入口 forward-push PageRank，来解释交易信号。排名靠前的 K 个特征将以 Markdown 表格形式返回，并持久化到 trading-analysis，作为 SignedAttributionArtifact（ADR-126 第 6 阶段）。

这项技能的重要性：

• 欧盟《人工智能法案》及 SEC 的 Reg-AI 指引要求，对任何涉及散户资金的算法交易系统，其模型输出都必须可解释。这是监管级归因路径，也是底层架构其他部分一直在等待的能力。
• 一旦该工具在运行时注册，同一调用点就会使用 mcp__ruflo-sublinear__page-rank-entry 提供的完整原生 WASM PageRank；在此之前，signed-attribution.mjs 中的本地幂迭代内核会提供相同的排序（使用种子化 mulberry32）。

步骤：

1. 从规范的 trading-signals 命名空间检索信号（ADR-126 第 1 阶段和第 2 阶段生命周期）：

   mcp__plugin_ruflo-core_ruflo__memory_retrieve({
     key: "SIGNAL_ID",
     namespace: "trading-signals"
   })
   

   信号条目包含 modelId、prediction 以及推理时的特征向量。

2. 从模型中提取各特征的贡献分数：

   npx neural-trader --predict --signal "$SIGNAL_ID" --explain --json
   

   预期的输出形状：

   {
     features: Array<{ name: string; contribution: number }>;
     // for Transformers, also includes per-head attention co-occurrence:
     attention?: Array<{ head: string; cooccur: Array<[number, number, number]> }>;
   }
   

   回退路径——如果已安装的 neural-trader 构建版本尚未提供 --explain（较旧版本；该标志原本计划在后续上游 PR 中加入），此技能会降级为针对信号输入向量的确定性特征重要性启发式算法：contribution_i = |input_i - μ_i| / σ_i（z 分数的绝对值）。这是已知的代理指标——其忠实度不如 attention/SHAP——生成的产物会标记为 attribution_method: "input-zscore-fallback"，以便下游使用方在监管申报中将其筛除。请在生成的 Markdown 摘要中说明回退路径，以便 Agent 向用户展示。

3. 构建特征贡献图：

   • 节点：每个特征对应一个节点，另为预测创建一个源节点 __signal_output__。
   • 边：从 __signal_output__ 指向每个特征节点的出边，权重为 contribution_i。如果有 attention 共现数据，还要添加特征节点之间的边，权重为 cooccur——这使 PageRank 采用单入口方式，而不是退化为简单的 top-K。
   • 源节点：__signal_output__（按照约定，索引为 0，以便 smoke 测试断言结果可复现）。

4. 运行单入口 PageRank——首选路径是在已注册 mcp__ruflo-sublinear__page-rank-entry 时使用：

   mcp__ruflo-sublinear__page-rank-entry({
     nodes: GRAPH_NODES,
     edges: GRAPH_EDGES,
     sourceIndex: 0,
     damping: 0.85,
     maxIterations: 100,
     tolerance: 1e-8,
     seed: 42
   })
   

   如果 MCP 工具不可用，本地回退方案（plugins/ruflo-neural-trader/src/signed-attribution.mjs 中的 localSingleEntryPageRank）会运行约 30 行的种子化幂迭代——数学原理相同，在浮点容差范围内结果相同；对于相同的种子，排序也相同（第 6 阶段的 smoke 测试会对此进行断言）。

5. 通过 topKFeatures(graph, scores, k=10, excludeIndex=0) 构建 top-K AttributionFeature[]——从排名结果中排除源节点。并列时按节点索引排序（索引较小者优先），以确保排序具有确定性。

6. 为制品签名（复用 Phase 4 的签名原语——使用相同的 Ed25519 和规范化方法）：

   • 构建 SignedAttributionArtifact 主体：

     {
       signalId: SIGNAL_ID,
       modelId: SIGNAL.modelId,
       features: TOP_K_FEATURES,             // 来自步骤 5
       graphMetadata: {
         nodeCount: GRAPH.nodes.length,
         edgeCount: COUNT_EDGES,
         pageRankIterations: PR_RESULT.iterations,
         seed: SEED                          // 对可复现性至关重要
       },
       generatedAt: NEW_DATE_ISO
     }
     

   • 解析见证签名密钥——查找顺序与 Phase 4 相同：
     1. RUFLO_WITNESS_KEY_PATH 环境变量——包含 { "privateKey": "<hex>" } 的 JSON 文件。
     2. verification/witness-key.json（ADR-103 默认路径）。
   • 如果找到密钥：调用 plugins/ruflo-neural-trader/src/signed-attribution.mjs 中的 signAttributionArtifact(body, privateKeyHex)。
   • 如果两个路径都未找到密钥：记录 "[WARN] ruflo-neural-trader: no witness signing key found — storing attribution artifact in UNSIGNED degraded mode. Regulator filings will reject UNSIGNED artifacts."，并以未签名状态存储主体。绝不能静默回退。

7. 将（可能已签名的）制品存储到规范的 trading-analysis 命名空间（ADR-126 Phase 1）：

   mcp__plugin_ruflo-core_ruflo__memory_store({
     key: "attribution-SIGNAL_ID-TIMESTAMP",
     namespace: "trading-analysis",
     value: JSON.stringify(signedArtifact)
   })
   

   trading-analysis 命名空间是模型分析输出（状态分类、技术指标摘要、模型训练结果，以及现在的归因排名）的规范存放位置。长期保留——不设 TTL——因为审计记录就是交付物。

8. 将 Markdown 摘要返回给 Agent。建议格式：

   ## Feature attribution for signal `SIGNAL_ID` (model: MODEL_ID)
   
   | Rank | Feature | Score |
   |------|---------|-------|
   | 1    | NAME    | 0.42  |
   | 2    | NAME    | 0.18  |
   | …    | …       | …     |
   
   - PageRank iterations: N
   - Graph: nodeCount nodes, edgeCount edges
   - Seed: 42 (reproducible — same seed → same ordering)
   - Path: mcp | local
   - Signature: ed25519:abcd… (or UNSIGNED — degraded warning above)
   

验证

下游使用者会在生成任何面向监管机构的报告或进行 paper→live 晋级之前，先验证制品：

import { verifyAttributionArtifact } from 'plugins/ruflo-neural-trader/src/signed-attribution.mjs';

const ok = await verifyAttributionArtifact(artifact, trustedPublicKey);
if (!ok) {
  // [ERROR] attribution verification failed — refuse to publish.
  // Pin to trustedPublicKey from project config; do NOT trust the
  // artifact.witnessPublicKey field (CWE-347 / #1922 — attacker-controllable).
  return;
}

验收标准（ADR-126 Phase 6）：

• trader-explain <signalId> 返回按排名排列的特征列表，其排名前三的特征与模型的注意力 argmax 重叠（--explain 可用时；容差已记录）。
• 可复现性：使用相同的 signalId 和 --seed 运行两次，会产生字节级一致的排名顺序（由 scripts/smoke-neural-trader-feature-attribution.mjs 断言）。
• 已签名制品可通过受信任的公钥验证；篡改任何特征分数或 graphMetadata.seed 都会导致签名失效。
• 回退路径可正常启用：MCP 不可用时运行本地内核；缺少 --explain 标志时运行 z-score 启发式方法，并为制品添加标记。

参考：

• ADR-126 Phase 6（此技能的编写 ADR）
• ADR-126 Phase 4（此处复用的签名方案）
• ADR-123（单入口 PageRank 基础设施；与 Phase 3 用于投资组合 CG 的基础设施属于同一系列）
• plugins/ruflo-neural-trader/src/signed-attribution.ts（类型化契约）
• plugins/ruflo-neural-trader/src/signed-attribution.mjs（运行时镜像）
• scripts/smoke-neural-trader-feature-attribution.mjs（回归冒烟测试）