trader-portfolio-cg

通过共轭梯度法求解均值-方差优化问题 Σ · x = μ，替代旧版 Neumann 级数。

为何使用 CG 而非 Neumann（ADR-123 Wedge 8）：

• Neumann 级数：n=256 时约 50 µs（旧版 npx neural-trader --portfolio optimize）
• 共轭梯度法：n=256 时约 816 ns（本技能）
• 实测提速：40-60×；在固定种子下，结果差异在 1e-4 以内。

协方差矩阵 Σ 按构造为对称正定矩阵（它是实数收益的 Gram 矩阵），因此 CG 在理论上是最优的——无需预条件，最多迭代 n 次即可收敛；当特征值聚集时，通常所需迭代次数会少得多。

禁用标志：设置 RUFLO_NEURAL_TRADER_DISABLE_CG=1 可完全跳过 CG 路径，并转到步骤 4 的旧版 Neumann 路径。适用于 A/B 验证，或上游协方差回归导致矩阵不再是 SPD 的情况。

原生分派标志：设置 RUFLO_SUBLINEAR_NATIVE=1 可强制适配器尝试原生 mcp__ruflo-sublinear__solve 路径，即使 globalThis 未公开该工具（例如，测试框架通过不同传输方式挂载该工具）。原生分派若失败，适配器会平稳回退到本地 JS CG，并在产物元数据中记录 method: 'cg-local'，以便审计回归问题。

步骤：

1. 确保 neural-trader 可用：

   npm ls neural-trader 2>/dev/null || npm install --ignore-scripts neural-trader
   

2. 从 neural-trader 的投资组合 API 读取当前协方差矩阵 Σ 和预期收益向量 μ：

   # Primary path (preferred — clean JSON):
   npx neural-trader --portfolio current --json
   # Fallback paths if the --json flag is unavailable on the installed version:
   npx neural-trader --portfolio current  # parse the text output
   # OR pull from AgentDB if a prior run stored the matrix there:
   

   mcp__plugin_ruflo-core_ruflo__memory_search({ query: "covariance matrix current", namespace: "trading-risk", limit: 1 })
   

   该技能要求响应包含 covariance: number[][]（n × n）和 expectedReturns: number[]（长度为 n）。

3. 通过 SublinearAdapter 求解 Σ · x = μ（首选路径），前提是未设置 RUFLO_NEURAL_TRADER_DISABLE_CG：

   import { sublinearAdapter } from '../../src/sublinear-adapter.mjs';
   const result = await sublinearAdapter.solveCG(COVARIANCE, EXPECTED_RETURNS, {
     tolerance: 1e-6,
     maxIterations: 200,
   });
   // result.solution    — optimal weights (number[])
   // result.iterations  — CG iterations executed
   // result.residual    — final ||A·x − b||₂
   // result.latencyMs   — wall-clock latency
   // result.method      — 'cg-sublinear-native' | 'cg-local'   <-- READ THIS
   // result.solver      — '[email protected]' | 'local-js-cg'
   // result.degraded    — true if input failed SPD checks (fall back to step 4)
   

   适配器会自行完成分派：它会探测 globalThis 上的 mcp__ruflo-sublinear__solve（并支持将 RUFLO_SUBLINEAR_NATIVE=1 作为手动覆盖），在原生内核可用时通过该内核运行；否则会透明地回退到内置的约 50 行 JS CG。无论哪种方式，数学过程都相同——使用 CG、稠密形式和 n × n SPD 协方差矩阵。算子会读取 result.method，以确定哪个后端生成了产物。

   原生 MCP 工具的传输格式（适用于希望绕过适配器的直接调用者）：

   mcp__ruflo-sublinear__solve({
     matrix: COVARIANCE,
     rhs: EXPECTED_RETURNS,
     algorithm: "cg",
     tolerance: 1e-6,
     maxIterations: 200
   })
   

   输出：

   { solution: number[], iterations: number, residual: number }
   

4. 回退（旧版 Neumann）——如果步骤 3 报告 degraded: true（输入非 SPD、矩阵非方阵或 MCP 错误），或设置了 RUFLO_NEURAL_TRADER_DISABLE_CG=1：

   npx neural-trader --portfolio optimize
   

   捕获权重输出，并在产物元数据中标记 method: 'neumann-fallback' 和 reason 字段。

5. 将最优权重存储到 trading-risk 命名空间，并附上完整的溯源元数据。直接从适配器结果中获取 method 和 solver，以便操作者确认运行的是哪个后端：

   mcp__plugin_ruflo-core_ruflo__memory_store({
     key: "portfolio-weights-PORTFOLIO_ID-TIMESTAMP",
     namespace: "trading-risk",
     value: JSON.stringify({
       weights: result.solution,           // number[] from step 3 (or weights from step 4 fallback)
       method: result.method,              // 'cg-sublinear-native' | 'cg-local' | 'neumann-fallback'
       solver: result.solver,              // '[email protected]' | 'local-js-cg' | 'neural-trader-cli'
       iterations: result.iterations,
       residual: result.residual,
       latencyMs: result.latencyMs,
       capturedAt: NEW_DATE_ISO,
       reason: FALLBACK_REASON || null
     })
   })
   

   trading-risk 命名空间是规范来源（ADR-126 Phase 1；五命名空间对齐）。数据长期保留，不设 TTL，因为投资组合权重是 Phase 4 将使用 Ed25519 签名的审计记录。

6. 与历史模式交叉核对（可选，但建议执行）：

   mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search({
     query: "portfolio weights Sharpe regime:CURRENT_REGIME",
     namespace: "trading-risk"
   })
   

   如果任一资产的新权重与历史中位数相差超过 30%，则在应用前标记并交由人工审核。这是防护措施，不是硬性阻止。

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

• n = 256 的协方差矩阵延迟 < 1 ms（本地 JS CG）；原生路径目标为提速 40-60×（根据 [email protected]，每次求解原生路径为 816 ns，Neumann 为 50 µs）。
• 在固定种子下，与旧版 Neumann 的差异满足 ||cg − neumann||_∞ < 1e-4。
• 原生 MCP 不可用或协方差非 SPD 时，回退路径能平稳启用。
• 产物元数据能区分 cg-sublinear-native、cg-local 和 neumann-fallback。

参考资料：

• ADR-126 Phase 3（本技能的编写 ADR）
• ADR-123 §162 Row 8（Wedge 8 提速声明）
• ADR-123 §262-289（SublinearAdapter 合约）
• plugins/ruflo-neural-trader/src/sublinear-adapter.ts（适配器）
• plugins/ruflo-neural-trader/benchmarks/portfolio-cg.bench.ts（实测数据）