回測反饋循環

定期任務，為已執行 N 小時的交易計算 P&L 結果，並把它們反饋進 EvaluationLoop + MethodologyStore，使 Wilson-LB 畢業機制累積真實的盈虧信號。默認完全黑（BACKTEST_ENABLED=false）。不重放歷史交易或重跑過往決策——只評估實際在會話內執行過的行。 Rollout 協議： 1. BACKTEST_ENABLED=true + BACKTEST_DRY_RUN=true 持續 1 周 2. 檢查 shadow_runs WHERE facet='backtest_outcome' 3. 結果看起來乾淨時把 BACKTEST_DRY_RUN=false 4. 最後把 LEARNING_RECORD_USAGE=true——啟用 Wilson 計數器更新

`BACKTEST_ENABLED`

運行器 + 調度器的總開關。 false（默認）= 永不構造運行器，cron 定時器也不註冊。零運行時開銷。 true = 構造運行器，調度器每隔 BACKTEST_CRON_HOURS 小時觸發一次。仍遵守下方的 DRY_RUN。

格式: true / false.
設置歸屬: 設置 → 偏好（schema 鍵）

`BACKTEST_DRY_RUN`

為 true 時，運行器計算結果並寫入 shadow_runs(facet='backtest_outcome')，但不會調用 updateTradeOutcome 或 recordUsage。僅在至少完整跑完一個 cron 週期、抽查 shadow 行確認無誤後，才翻為 false。

格式: true / false.
設置歸屬: 非用戶設置項

`BACKTEST_MIN_TRADE_AGE_MS`

一筆交易進入回測評估資格前的最小時長（毫秒）。結果需要時間才能顯現；5 分鐘的時間窗只是噪聲。透傳給 ReviewEngine 的 minTradeAgeForEvalMs。默認 86400000（24h）。

格式: 正整數（毫秒）。
設置歸屬: 非用戶設置項

`BACKTEST_OUTCOME_HORIZON_HOURS`

在交易 created_at 之後多少小時對結果價格進行採樣。+5% in 24h = 24。該值會鏡像寫入發出的結果字符串，讓評估器看到窗口長度。Sprint 6 使用單一全局值（TODOS #9 跟蹤按交易類型的調優）。默認 24。

格式: 正整數（小時）。
設置歸屬: 非用戶設置項

`BACKTEST_BATCH_LIMIT`

運行器每次觸發拉取的最大待處理行數。透傳給 ReviewEngine 的 maxEvalsPerBatch。調低以限制單次運行的 LLM 花費；當待處理隊列持續繁忙時調高。默認 20。

格式: 正整數。
設置歸屬: 非用戶設置項

`BACKTEST_CRON_HOURS`

調度器間隔。運行器通過 setInterval(… * 3600_000) 調用；該定時器使用 unref()，因此絕不會單獨讓進程保持存活。允許浮點數；低於 0.017（1 分鐘）的值會被上調鉗制。默認 24。

格式: 正數（小時）。
設置歸屬: 非用戶設置項

`BACKTEST_PRICE_PROVIDER`

為調試強制指定單一歷史價格來源。auto 按資產類別路由（crypto → Hyperliquid → Yahoo -USD 兜底；stock/unknown → Yahoo；stablecoin → 1.0）。懷疑 Yahoo 符號歸一化有問題時釘到 hyperliquid；Hyperliquid 被限流時釘到 yahoo。

格式: auto / hyperliquid / yahoo.
設置歸屬: 非用戶設置項

`BACKTEST_MAX_COST_USD_PER_RUN`

單次調用的硬性成本上限。運行器在 evaluatePacked 前後各快照一次 BudgetTracker.getDailySpend("learning")；若差值超過該上限，本次運行返回 status=stopped_budget。0 禁用上限。默認 2.00。

Stackable: BudgetTracker 中已有的日/月度上限仍然生效。
格式: 非負浮點數（美元）。
設置歸屬: 非用戶設置項

`LEARNING_RECORD_USAGE`

為 true 時，EvaluationLoop 在每筆已評估交易後檢查 trade_history.methodology_ids。Phase 1.2a 的去重（codex R1 P1）有意抑制對任何已歸因方法論交易的 recordUsage 調用——這些交易改由 case-attribution.ts 進行 Wilson 訓練。如今未歸因的交易同樣不會從這條路徑產生 Wilson 信號；Wilson 更新完全經由 case-attribution 流轉。

因此該環境變量如今是一個可觀測性開關，而非學習
開關：將其翻為 true 會觸發一行 wilson_dedup_skip 日誌
（每筆已歸因交易一行），供運維驗證去重是否在
生產環境中生效。舊的“對每筆已評估交易一律 recordUsage”
行為已移除。
格式: true / false.
設置歸屬: 設置 → 偏好（schema 鍵）

`LEARNING_TUNING_ENABLED`

離線貝葉斯優化調優框架的總開關，用於搜索 src/learning/methodology-store.ts 中 LEARNING_CONFIG 的更優取值。該框架是離線工具（經 minara learning replay + tools/tuning/ 中的 Python BO 運行），絕不屬於請求路徑。設立該門是為防止在生產環境誤觸發 replay CLI。

消費方: src/gateway/learning-cli.ts 中的 replay 子命令
在此值不為 true 時以 { skipped: "tuning_disabled" }
短路返回。
Exception: minara learning stats 是純只讀（對
trade_history + methodologies 執行 SQL SELECT 以做數據就緒度報告），並
無論該門狀態如何都會運行。運維需要持續掌握
是否已積累足夠的 Sprint 6 數據，值得發起一次調優
運行（目標：≥100 筆已評估交易，覆蓋 ≥20 個唯一方法論
id）。
Rollout: 在滿足以下條件前該值保持 false：(a) Sprint 6 已完成推廣
（LEARNING_RECORD_USAGE=true），(b) minara learning stats 報告
READY_FOR_BO=true，且 (c) 由人工運維顯式發起一次
調優會話。在生產環境保持 false 是默認安全的
姿態。
格式: true / false.
設置歸屬: 非用戶設置項

Phase 1 — 決策捕獲（建議 BUY/SELL/HOLD）

decision-capture hook 在 agent 循環的輪末運行。當該輪涉及投資建議（9 個建議場景之一活躍，或 agent 回覆中出現 BUY/SELL/HOLD 關鍵詞 + ticker 匹配）時，一次獨立的 summarizer LLM 調用會提取一個結構化的 {asset, decision, confidence, quoted_price} 元組並持久化到 decision_history。該數據餵給 Phase 2 多時間跨度回測和 Phase 6 methodology-instance BO 調優。 summarizer 始終是 fire-and-forget（異步）；用戶可見的輪延遲不變。失敗會記錄日誌並靜默丟棄該行。

`DECISION_CAPTURE_ENABLED`

Phase 1 採集的總開關。為 false（默認）時，turn-end 鉤子立即返回，不運行任何預過濾或 LLM 調用。翻為 true 即開始填充 decision_history。可隨時翻轉——無需數據遷移。

消費方: src/learning/decision-capture/capture-hook.ts.
未設置時: 默認 false。
格式: true / false.
設置歸屬: 設置 → 偏好（schema 鍵）

`DECISION_SUMMARIZER_MODEL`

決策摘要器 LLM 調用所用的模型。默認指向 Claude Haiku 4.5 以兼顧成本（在 800 輸入 + 200 輸出 token 下約 $0.002/輪）。若統計中摘要器覆蓋率 < 70%，可上調至 Sonnet。

消費方: src/learning/decision-capture/summarizer.ts.
未設置時: 默認 claude-haiku-4-5-20251001。
格式: Anthropic 模型 id。
設置歸屬: 非用戶設置項

`DECISION_SUMMARIZER_TIMEOUT_MS`

單次摘要器調用的硬性超時。摘要器以 fire-and-forget 方式運行；超時會丟棄該決策並記一條 warn 日誌，不重試。

消費方: src/learning/decision-capture/summarizer.ts.
未設置時: 默認 15000。
格式: 正整數（毫秒）。
設置歸屬: 非用戶設置項

`DECISION_CAPTURE_SYNC_MODE`

為 true 時，在鉤子返回前等待摘要器完成（會增加每輪延遲）。僅用於確定性測試 / CI；生產環境應保持 false。

消費方: src/learning/decision-capture/capture-hook.ts.
未設置時: 默認 false。
格式: true / false.
設置歸屬: 非用戶設置項

`DECISION_CAPTURE_HEURISTIC_ENABLED`

Tier 2 正則預過濾。為 true（默認）時，即使沒有建議場景處於激活狀態，只要 agent 的最終回覆包含 BUY/SELL/HOLD 關鍵詞 + 資產 ticker，鉤子也會採集該輪。設為 false 可將採集嚴格限制在建議場景的輪次。

消費方: src/learning/decision-capture/classify-capture-source.ts.
未設置時: 默認 true（啟用）。
格式: true / false.
設置歸屬: 非用戶設置項

`DECISION_CAPTURE_UNIVERSAL_SCAN`

Tier 3 可選的全量掃描。為 true 時，每一輪都會調用摘要器（繞過 Tier 1/2）。僅用於診斷性 A/B 運行——長期使用會使摘要器預算約翻 4 倍。強烈建議保持 false。

消費方: src/learning/decision-capture/classify-capture-source.ts.
未設置時: 默認 false。
格式: true / false.
設置歸屬: 非用戶設置項

Phase 2 — 多時間跨度決策回測

DecisionBacktestRunner 掃描年齡 ≥ max_horizon 的 decision_history 行（1m 時間跨度默認 30 天）並填充： (a) 來自 HistoricalPriceProvider 的 real_price_at_decision，與 agent_quoted_price 比對以標記幻覺 (b) decision_outcomes 行——每個時間跨度 {1d, 3d, 1w, 1m} 一條若 |agent_quoted - real|/real > HALLUCINATION_MAX_PRICE_DELTA_PCT，該決策被標記為 state='skipped_halluc' 並排除在下游學習之外。

`DECISION_BACKTEST_ENABLED`

decision-history 多時間窗回測 cron 的總開關。本次發佈中為 EXPERIMENTAL（實驗性）：運行器現在接入了 ReasoningQualityJudge（見 src/learning/backtest/reasoning-quality.ts），使得“agent 說 HOLD 但市場上漲”這類失誤不會被直接用於更新 Wilson—— 因為該模式會訓練 agent 去追逐上一段市場行情（即產品團隊明確想要避免的散戶行為）。Phase 1 上線的是無操作的默認裁判，將每個決策都歸類為 no_judgment，也就是說，如今把該開關翻為 true 只會填充 decision_outcomes 行 + 發出裁決計數； 不會從這條路徑遞增任何方法論 Wilson 計數器。在依賴該 cron 進行學習前，請等待 Phase 2 的 EvaluationProvider 落地真正的 LLM-as-judge。在此之前： - false（默認）：運行器無操作。 - true（建議僅 dry-run）：填充 decision_outcomes，在運行摘要中統計裁決數，絕不更新 Wilson。

消費方: src/learning/backtest/decision-runner.ts.
未設置時: 默認 false。
格式: true / false.
設置歸屬: 設置 → 偏好（schema 鍵）

`METHODOLOGY_LEARNING_CRON_ENABLED`

進程內方法論 cron 編排器的選擇性啟用（sweep → 7 天 case-attribution → synthesis）。未設置（默認）時，agent 不會自動調度；運維通過系統 cron / launchctl / systemd 調用 minara learning cron 推進該循環。設為 true 時，編排器每隔 METHODOLOGY_LEARNING_CRON_INTERVAL_MS（默認 6h）運行一次。已執行交易的 Wilson 訓練在該門下經由 case-attribution 流轉——只有當該安裝為每個活躍 asset_class 積累 ≥ 100 個真實案例後再開啟，信號才不會太嘈雜。

消費方: src/app.ts + src/learning/methodology-cron.ts.
未設置時: 默認 false。
格式: true / false.
設置歸屬: 設置 → 偏好（schema 鍵）

`METHODOLOGY_LEARNING_CRON_INTERVAL_MS`

當 METHODOLOGY_LEARNING_CRON_ENABLED=true 時，兩次 cron 掃描之間的間隔（毫秒）。默認 21600000（6 小時）。更小的間隔會更快消耗 LLM 裁判預算，卻不會產生更多信號。

消費方: src/learning/methodology-cron.ts.
未設置時: 默認 21600000。
格式: 正整數。
設置歸屬: 非用戶設置項

`METHODOLOGY_TUNING_ENABLED`

選擇性啟用 apps/agent/src/learning/experimental/tuning/ 下的實驗性方法論調優（BO 規劃器）子樹。Phase 1.7 將這段代碼移出了默認的 agent 啟動路徑，因為 cycle-planner.ts 只是一個僅發出 dry-run 計劃的樁——它從不執行 BO，因此也從不變更任何方法論。只有當你想通過 minara learning tune-methodology --dry-run 查看規劃器的 tunability-score 輸出時才翻為 true；實盤執行器將在未來階段落地。

消費方: src/gateway/learning-cli.ts.
未設置時: 默認 false。
格式: true / false.
設置歸屬: 設置 → 偏好（schema 鍵）

`DECISION_REPLAY_ENABLED`

選擇性啟用 apps/agent/src/learning/experimental/replay/ 下的實驗性 decision-replay 子樹。當前 decision-replay.ts 的實現明確是一個 PLACEHOLDER（佔位實現，見文件頭）——它只返回簡單的加權平均獎勵，並不做閾值感知的回放。**不要依賴其輸出來支撐方法論調整。**Phase 6+ 的工作會用真正的引擎替換該佔位實現。

消費方: src/gateway/learning-cli.ts.
未設置時: 默認 false。
格式: true / false.
設置歸屬: 設置 → 偏好（schema 鍵）

`DECISION_BACKTEST_DRY_RUN`

為 true 時，運行器不寫入 decision_outcomes / decision_history；而是將結果 + 標誌記錄到 shadow_runs(facet='decision_outcome')。這是第一週的上線協議。確認 shadow 行合理後再翻為 false。

消費方: src/learning/backtest/decision-runner.ts.
未設置時: 默認 false。
格式: true / false.
設置歸屬: 非用戶設置項

`DECISION_BACKTEST_HORIZONS`

時間窗規格的 CSV，形如 <number><unit>，其中 unit 為 h/d/w/m（小時/天/周/月）。例如 1d,3d,1w,1m。每個時間窗為每個決策在 decision_outcomes 中生成一行。最大時間窗決定一個待處理決策何時進入回測資格。

消費方: src/learning/backtest/decision-runner.ts.
未設置時: 默認 1d,3d,1w,1m。
格式: 逗號分隔的列表。
設置歸屬: 非用戶設置項

`DECISION_BACKTEST_CRON_HOURS`

兩次運行器調用之間的間隔。

消費方: src/app/backtest.ts（wireBacktest 的 interval）。
未設置時: 默認 24。
格式: 正數（小時）。
設置歸屬: 非用戶設置項

`DECISION_BACKTEST_MAX_AGE_DAYS`

決策年齡的硬性上限。超過該年齡的行無論時間窗填充狀態如何都會被跳過，以防積壓無限增長。

消費方: src/learning/backtest/decision-runner.ts.
未設置時: 默認 60。
格式: 正整數（天）。
設置歸屬: 非用戶設置項

`HALLUCINATION_MAX_PRICE_DELTA_PCT`

當設置了 agent_quoted_price 且它與 real_price_at_decision 的偏離超過該比例時，該決策會被標記並排除在下游學習之外。0.05（5%）能擋掉大多數因工具輸出陳舊導致的誤報，同時仍能捕捉大幅編造。若陳舊緩存常見可收緊到 0.03；僅當 HistoricalPriceProvider 本身噪聲較大時才放寬到 0.10。

消費方: src/learning/backtest/decision-outcome-filler.ts.
未設置時: 默認 0.05。
格式: 正小數（0.01 = 1%）。
設置歸屬: 非用戶設置項

Phase 3 — 獎勵計算

獎勵函數把 4 時間跨度的收益向量（Phase 2）轉換為每個決策的單個標量。三條規則： BUY: pct_return 的加權均值（價格上漲則獎勵上升） SELL: -pct_return 的加權均值（價格下跌則獎勵上升） HOLD: 線性中性獎勵——|return| < 閾值給正獎勵（0 處為 1，衰減到閾值處為 0）；超過閾值，線性負（機會成本 / 錯過的行情）。

`DECISION_HORIZON_WEIGHTS_JSON`

獎勵求和中各時間窗的權重。字符串化的 JSON 對象 {label: weight}。缺失的 label 權重為 0。默認體現“中期信號”偏好——1w 最高，1d 最低（因為日線噪聲）。

消費方: src/learning/decision-reward/reward.ts rewardOptionsFromEnv().
未設置時: 默認 {"1d":0.15,"3d":0.25,"1w":0.35,"1m":0.25}。
格式: JSON 字符串。
示例（更側重短期）： DECISION_HORIZON_WEIGHTS_JSON='{"1d":0.35,"3d":0.30,"1w":0.25,"1m":0.10}'
設置歸屬: 非用戶設置項

`DECISION_HOLD_NEUTRALITY_THRESHOLD`

|pct_return| 低於該值即計為一次 HOLD 勝出。0.02 = 2%。調高以放寬 HOLD 獎勵（更能容忍“波動也沒關係”）；調低以收緊（HOLD 必須接近零波動）。

消費方: src/learning/decision-reward/reward.ts rewardOptionsFromEnv().
未設置時: 默認 0.02。
格式: 正小數（0.01 = 1%）。
設置歸屬: 非用戶設置項

Phase 6 — BO 調優循環

對每個（template, asset_class）的 methodology 閾值做離線貝葉斯優化。定期運行（cron），讀取 Phase 1-3 的決策獎勵，把調優後的閾值寫入 methodology_instances。完全黑落地——啟用前運行時零成本。需要 tools/tuning/ 中的 Python harness。

`METHODOLOGY_INSTANCE_TUNING_ENABLED`

BO 週期編排器的總開關。為 false（默認）時，即便已調度，該週期也是無操作。只有在 Phase 1/2/3 數據已積累且 minara learning stats 顯示 READY_FOR_BO=true 之後才翻為 true。

消費方: src/learning/experimental/tuning/cycle.ts（將於
Phase 7 接線）。
未設置時: 默認 false。
格式: true / false.
設置歸屬: 非用戶設置項

`METHODOLOGY_TUNING_CRON_DAYS`

兩次 BO 週期調用之間的天數。默認 7（每週）。更小的值有過擬合短期市場噪聲的風險；更大的值會減慢學習。

消費方: src/app.ts（cron 接線，Phase 7）。
未設置時: 默認 7。
格式: 正整數（天）。
設置歸屬: 非用戶設置項

`METHODOLOGY_TUNING_MAX_BUCKETS_PER_CYCLE`

每週期上限。符合條件的 bucket 按 tunability_score 排序；每週期只把前 N 個傳給 Python BO 框架。

消費方: src/learning/experimental/tuning/cycle.ts.
未設置時: 默認 10。
格式: 正整數。
設置歸屬: 非用戶設置項

`METHODOLOGY_TUNING_PROFILES_PATH`

資產類別 profiles JSON 的覆蓋路徑。按類別對 BUILTIN_PROFILES 做淺合併。將某個類別的值設為 null 可將其完全排除在調優之外。

消費方: src/learning/experimental/tuning/asset-profiles.ts.
未設置時: 默認 $MINARA_DATA_DIR/methodology-tuning-profiles.json。
格式: 文件系統路徑（可以不存在——此時為無操作）。
設置歸屬: 非用戶設置項

`METHODOLOGY_TUNING_MIN_DECISIONS_GLOBAL`

所有 profile 的 min_decisions 全局下限（與各 profile 的值取最大）。用於緊急收緊，例如一次糟糕的上線之後。

消費方: src/learning/experimental/tuning/asset-profiles.ts.
未設置時: 不施加下限。
格式: 正整數。
設置歸屬: 非用戶設置項

`METHODOLOGY_TUNING_MIN_IMPROVEMENT_REL`

BO 後檢查 #1，相對改進門（測試劃分的平均獎勵必須比基線高出該比例）。0.05 = 5%。

消費方: src/learning/experimental/tuning/cycle.ts Phase 7.
未設置時: 默認 0.05。
格式: 正小數。
設置歸屬: 非用戶設置項

`METHODOLOGY_TUNING_MAX_SENSITIVITY_DROP_10PCT`

BO 後檢查 #2，窄峰拒絕。最優候選在 ±10% 鄰域內的評分下降不得超過該比例。0.5 = 50%。

消費方: src/learning/experimental/tuning/cycle.ts Phase 7.
未設置時: 默認 0.5。
格式: (0, 1] 之間的小數。
設置歸屬: 非用戶設置項

`METHODOLOGY_TUNING_PARAM_BOUND_REL`

BO pbounds 的半寬，以模板默認值的倍數表示。0.5 表示每個參數的邊界 = [默認值 × 0.5, 默認值 × 1.5]。

消費方: src/learning/experimental/tuning/cycle.ts Phase 7.
未設置時: 默認 0.5。
格式: 正小數。
設置歸屬: 非用戶設置項

`METHODOLOGY_TUNING_MIN_CAPTURE_CONFIDENCE`

BO 回放框架只考慮 capture_confidence ≥ 該閾值的決策。0.3 涵蓋全部三個層級（advice_scenario、heuristic_match、summarizer_promoted）；調高到 0.6+ 可僅限於高信號決策。

消費方: src/learning/experimental/replay/decision-replay.ts（Phase 7）。
未設置時: 默認 0.3。
格式: [0, 1] 之間的小數。
設置歸屬: 非用戶設置項

偏好演化 (M2: Financial Auto-Memory)

定期的 LLM 驅動 proposer，掃描近期用戶消息，請模型把它們聚類成持久的偏好（kind ∈ {personal_style, behavioral_preference}），並每個冷卻窗口一次性浮現卡片式的畢業請求。仿照 AutoClaw 的每週演化循環，帶每週 1-3 次畢業的軟上限。 M2 邊界：hard_constraint 候選被降級為 behavioral_preference，且從不在工具層自動應用—— 工具層強制隨 M3 與關鍵詞掃描器一同落地。手動 /preferences approve|reject|deprecate 無論總開關如何都可用，供運營方覆蓋。

`PREFERENCE_LEARNING`

M2 週期性提議器 + 畢業卡片流程的總開關。為 0 時，agent 循環不會排隊用戶消息、不會觸發提議器、不會注入畢業卡片。即便該開關關閉，M1 提供的 PreferenceStore + REPL/CLI/REST 端點仍可用於手動管理。

格式: 0 / 1.
設置歸屬: 設置 → 偏好（schema 鍵）

`PREFERENCE_PROPOSER_INTERVAL`

連續兩次提議器觸發之間的輪數。提議器在該輪的用戶可見回覆發出後以 fire-and-forget 異步方式運行，因此這是攤銷成本，而非用戶延遲。更低 = 學習更靈敏 + LLM 花費更高；默認 30 ≈ 每約半小時活躍對話觸發一次。

格式: 正整數。
設置歸屬: 非用戶設置項

`PREFERENCE_WEEKLY_QUOTA`

任意滾動 7 天窗口內允許的最大畢業數。一旦觸頂，提議器跳過其週期——新候選在隊列中積壓，但不向用戶呈現。手動 /preferences approve 可覆蓋該配額（由運維決定）。對應 AutoClaw 的“每週 1-3 次深度演進”原則。

格式: 正整數。
設置歸屬: 非用戶設置項

`PREFERENCE_DEDUP_THRESHOLD`

TF-IDF 餘弦相似度高於該值時，候選被視為現有生效偏好（state ∈ {active, proposed, deprecated}）的重複，並在持久化前丟棄。範圍 [0, 1]；0.85 能捕捉改寫，又不會對共享關鍵詞的短語句產生誤報。

格式: [0, 1] 之間的浮點數。
設置歸屬: 非用戶設置項

`PREFERENCE_PROPOSER_BATCH_SIZE`

單次提議器 LLM 調用拉入的最大近期候選數。更大的批量給 LLM 更多聚類信號，但消耗更多 token；默認 200 足以支撐一個有意義的提議器週期，又不會佔滿其餘上下文。

格式: 正整數。
設置歸屬: 非用戶設置項

`PREFERENCE_MIN_CLUSTER_SIZE`

在持久化該提議前，提議器 LLM 必須報告支持單個聚類的最小候選消息數。下限 3 可防止單例觀察抬高偏好噪聲。

格式: 正整數（強制 ≥ 2）。
設置歸屬: 非用戶設置項

`PREFERENCE_ASK_COOLDOWN_HOURS`

對同一偏好連續兩次畢業詢問之間的最小小時數。當用戶回覆“稍後”（或根本不回覆）後，該行保持 proposed，但在此窗口過去前從詢問隊列中隱藏。默認 24h 與場景流程一致。

格式: 正整數。
設置歸屬: 非用戶設置項

`PREFERENCE_ASK_MIN_GAP_TURNS`

同一 REPL 會話內，連續兩次畢業詢問（跨不同偏好）之間的最小輪數。即使提議器隊列充足，也能防止卡片詢問接連出現。

格式: 正整數。
設置歸屬: 非用戶設置項

`PREFERENCE_SKIP_IN_CHAT_ASK`

完全禁用聊天內畢業卡片。為 1 時，提議器仍運行並寫入提議，但卡片永不注入系統提示；運維通過 REPL /preferences pending + approve，或通過 CLI / REST 審閱並批准。適用於非交互式部署。

格式: 0 / 1.
設置歸屬: 非用戶設置項

M3: 關鍵詞掃描器 + 工具層約束強制

`PREFERENCE_STYLE_MIN_OBSERVATIONS`

掃描器在自動激活前，對同一風格偏好（按 dedup_key）所需的獨立觀察次數。下限 1；提高到 3+ 會給用戶更多機會在該行固化前推翻自己。

格式: 正整數。默認 2。
設置歸屬: 非用戶設置項

`PREFERENCE_HARD_UNDO_WINDOW_HOURS`

強信號自動激活後，用戶還能在多長時間內運行 /preferences undo <id> 撤回。超出該窗口的行必須改用 /preferences deprecate <id> 退役。

格式: 正整數。默認 24。
設置歸屬: 非用戶設置項

`MINARA_SKIP_FUND_CONFIRM`

資金轉移確認的旁路開關。

作用: 統一確認門（ToolEntry 上的 controlPolicy.confirm，由 tools/_security/tier-gate.ts 解釋）。資金轉移工具（swap / buy / sell / transfer / perps 開-平-撤 / perp-wallet 歸集+轉賬 / autopilot 啟用 / workflow 激活 / strategy-studio 啟動+部署）先預覽，用戶接受確認卡片（或其他確認證據）後才執行。handler 只負責執行。
消費方: src/tools/_security/tier-gate.ts（confirmFlowHook），經 src/tools/_shared/confirm.ts（isFundConfirmBypassEnvSet）。
何時設置: 僅在沒有人類參與循環、且調用方為非人類的非交互式場景中： - 回測運行 - workflow 引擎執行（服務端 autopilot、DCA） - 故意觸及資金轉移路徑的 CI 冒煙測試設置此項會在整個進程範圍內旁路確認門；沒有其他逃生艙。LLM 無法翻轉它；REPL 也無法翻轉它。
未設置時: 每次資金轉移調用都經過確認門。
格式: 1 / true / yes / on 表示啟用。其他任何值 = 關閉。
⚠ 切勿在交互式 REPL 會話或生產部署中設置，除非你確定每個調用方都是非人類。
設置歸屬: 設置 → 偏好（schema 鍵）

`WORKBENCH_REMOTE_WEB_PTY_ENABLED`

通過遠程 Gateway 開放交互式工作臺 Shell。

作用: 允許已認證的 Web 客戶端在 Gateway 綁定到非迴環地址時創建交互式 PTY 會話。
消費方: apps/agent/src/gateway/api.ts，以及設置中的安全偏好 safety.remoteWebPty。
何時設置: 僅在受信任、啟用鑑權且主機具備受支持 OS 沙箱的部署中設置。Web UI 也可在明確確認關鍵風險後啟用。
未設置時: 遠程 Web PTY 保持關閉；迴環 Gateway 繼續沿用本地終端行為。
格式: 設為 1 / true / yes / on 啟用。工作區邊界、環境變量白名單、所有權檢查、併發上限和進程生命週期限制仍會生效。
設置歸屬: 設置 → 偏好（schema 鍵）

`WORKBENCH_REMOTE_SHELL_PROFILE_POLICY`

控制遠程工作臺終端如何加載用戶 Shell 配置。

作用: 決定遠程終端在加載用戶 Shell rc 文件前詢問、自動加載，還是始終使用 Minara 內置 Shell 配置。
消費方: apps/agent/src/gateway/api.ts，以及內部工作臺終端能力和創建路由。
何時設置: 僅在受信任且預期執行用戶 rc 文件的遠程主機上設為 user。設為 builtin 可禁止加載。使用 prompt 時，每個瀏覽器可記住各標籤頁的明確選擇。
未設置時: 遠程 Gateway 默認為 prompt。迴環 Gateway 始終加載用戶 Shell 配置且不彈窗。
格式: 可選值為 prompt、user 或 builtin。非法值回退到 prompt，並記錄一次警告。
設置歸屬: 非用戶設置項

`MINARA_DANGEROUSLY_SKIP_PERMISSIONS`

⚠ 危險按鈕 —— 跳過非資金類授權的總開關（相當於 Claude Code 的 --dangerously-skip-permissions）。

作用: 一次性關閉非資金類的交互式授權門，使 agent 運行永不為它們停下詢問： 1. Tier 門（tools/_security/tier-gate.ts）—— 針對 terminal、 write_file、execute_code 等的首次使用 / 高風險 / 自主授予提示。 2. Command-guard（tools/_security/command-guard.ts）—— shell 命令絆線。 3. 沙箱寫逃逸門（tools/_security/sandbox-gate.ts）。 4. 腳本風險 YELLOW 確認（tools/_security/script-risk-gate.ts）。
What it does NOT control: 資金轉移確認（tools/_shared/confirm.ts）—— 當此項已設置時，swap / buy / sell / transfer / perps 仍需要 confirm: true。資金轉移由 MINARA_SKIP_FUND_CONFIRM 獨立把關。用 web-ui 的術語說，單獨打開此開關是“Auto”模式（操作自動執行，資金轉移仍需確認）；兩者都設則是“Full auto”。
消費方: src/tools/_security/permission-skip.ts （isPermissionSkipSet），由 tier 門、command-guard、沙箱門和腳本風險門讀取。
即便設置，也有兩條安全底線保持不變： - 腳本風險 RED 仍是硬拒絕（RED 從不提示，因此不屬於“授權”界面）。 - workflow 測試運行（ctx.test_run）仍絕不轉移資金。
何時設置: 沒有人類參與循環、且每個調用方都可信的自動化測試 / 無頭驅動。有三種設置方式： - 本環境變量，或 - --dangerously-skip-permissions CLI 標誌，或 - 持久化在 ~/.minara/runtime-preferences.json 中的 safety.skipPermissions 覆蓋項（也可在 web UI 設置的危險區編輯，需先 minara settings unlock-critical）。
未設置時: 每個門都處於激活狀態，照常提示 / 確認。
格式: 1 / true / yes / on 表示啟用。其他任何值 = 關閉。
⚠ 切勿在你無法完全掌控的交互式 REPL 或生產部署中設置。LLM 無法翻轉它。
設置歸屬: 設置 → 偏好（schema 鍵）

`MINARA_AUTO_REVIEW`

Smart 模式：由審核助手決定本會向用戶彈出的非資金類批准（對應 Codex AutoReview）。

作用: 把非資金類“本來會詢問”的入口改走一輪短的 Guardian LLM 會話，而不是 InteractionQueue： 1. Tier 門的首次使用 / 高風險提示（非資金）。 2. 沙箱寫逃逸與命令逃逸提示。 3. 腳本風險 YELLOW 確認。拒絕以工具錯誤返回主 agent，不會彈出確認卡片。超時 / 解析失敗一律失敗關閉（拒絕）。
What it does NOT control: 資金轉移確認仍走人工路徑。Auto / Full （safety.skipPermissions）會直接跳過詢問並優先於 Smart。 Coding 會話與自動化不使用 Smart。
消費方: src/tools/_security/permission-skip.ts （isGuardianReviewEnabled）以及 src/guardian/。
何時設置: 當你希望把聊天菜單的 Smart /「幫我批准」作為進程默認時設置。 web UI 也會把 safety.autoReview 持久化到 runtime-preferences.json。
未設置時: Ask 模式：用戶確認非資金操作。
格式: 1 / true / yes / on 表示啟用。其他任何值 = 關閉。
設置歸屬: 設置 → 偏好（schema 鍵）

`DISABLE_SCRIPT_RISK_GATE`

⚠ 危險按鈕 —— 腳本風險的終止開關。

作用: 在 execute_code（python/node 主體）、terminal（shell 命令）、write_file（最終文件內容）和 patch（應用後內容）之前運行的靜態分析腳本風險門。默認行為將主體分類為 RED（自動拒絕）、YELLOW（AskUserQuestion 確認）或 GREEN（放行）。RED 捕捉批量 rm * / rm -r *、刪除工作區之外的路徑、IMDS / SSRF、容器逃逸、憑證 / 錢包庫讀取、間接混淆 + sink 組合、遠程 pickle/yaml 反序列化等。YELLOW 捕捉資金轉移 CLI 外殼調用（minara swap / cast send / forge --broadcast）、鏈上危險調用（approve / Permit2 / Safe owner 變更）、環境投毒（NODE_OPTIONS / LD_PRELOAD / BASH_ENV）、特定路徑 rm、從 git / tarball / 非官方索引安裝包、heredoc 內嵌腳本，以及進程替換。
消費方: src/tools/_shared/script-risk-gate.ts.
何時設置: 僅用於事件響應，或沒有人類回答 AskUserQuestion 且每個調用方都可信的完全離線 CI 運行。這是單個布爾值——它同時旁路 RED 和 YELLOW 檢查。日常 workflow 豁免請使用按 workflow 的 script_risk_policy 字段（在 workflow_activate 時預批 body_sha256 + 類別）；切勿設置此環境變量來放寬單個 workflow 的界面。
未設置時: 門處於激活狀態。RED 硬拒絕，YELLOW 通過 AskUserQuestion 提示。沒有交互式會話的 Cron / workflow 場景返回 script_risk_no_session，除非它們有匹配的 script_risk_policy。
格式: 1 / true / yes / on 表示啟用。其他任何值 = 關閉。
Audit: 每次門決策都會落入 script_risk_decisions SQLite 表——設置此環境變量後，該行的 bypassed_by 列會顯示 env_global，便於運維日後發現該旁路。
⚠ 切勿在交互式 REPL 會話或生產部署中設置此項，除非你已核實每個調用方都是非人類，並接受批量刪除 / 憑證外洩模式將無提示地執行。
設置歸屬: 設置 → 偏好（schema 鍵）

`DISABLE_OUTPUT_REDACTION`

⚠ 危險按鈕 —— 輸出脫敏的終止開關。

作用: 對子進程輸出的密鑰脫敏處理。execute_code / terminal 的 stdout+stderr（本地與 docker）在進入模型上下文和持久化聊天曆史之前，會被清洗掉憑證形態的字符串：任意位置的廠商 token 形態（sk-…、ghp_…、xoxb-…、AKIA…、完整 JWT），以及綁定到疑似密鑰名的值（KEY=…、"api_key": "…"、Authorization: 頭、://user:password@host URL）。匹配項被替換為 [REDACTED]。
消費方: src/tools/_security/redact.ts（在 src/tools/_shared/subprocess-result.ts 和 docker 環境中應用）。
何時設置: 僅在不處理任何真實憑證的會話中調試誤報（脫敏器損壞了合法輸出）時使用。該開關在進程啟動時只讀取一次——terminal 工具調用內的 export 無法在會話中途翻轉它；更改需要重啟宿主。
未設置時: 脫敏在每條子進程輸出路徑上都處於激活狀態。
格式: 1 / true / yes / on 表示禁用。其他任何值 = 開啟。
設置歸屬: 非用戶設置項

`MINARA_TOOL_RESULT_RETAIN_HOURS`

spill 文件的保留窗口。

作用: 一個超大工具結果持久化在 <dataDir>/sandbox/files/.tool-results/ 下後，在被週期性清掃（每 6h）刪除前可存活多少小時。同一取值同時驅動啟動時清掃和長時運行清掃，因此持續運行數天的進程絕不會積累超過所配置的窗口。
消費方: src/core/tool-result-retain.ts，接入 src/app.ts 中的 sweepStaleSpillFiles 啟動 + 定時調用。
何時設置: - 24（默認）適用於典型的交互式 REPL 和開發工作——給 LLM 充足時間去 read_file 早先某輪的 spill。 - 168（7 天）是面向審計的取值，適用於受合規約束的部署，spill 出的工具輸出必須存活足夠久，以支撐季度審查或監管回溯。 - 1 是面向臨時 CI 運行的激進清理取值。
未設置時: 24h。
格式: [1, 720] 內的正整數（1h 到 30 天）。任何格式錯誤 / 越界的值都會靜默回退到 24h 並記一條 warn。
設置歸屬: 非用戶設置項

──────────────────────────────────────────────────────────────────── 個性化重建 — M3.2 事件驅動閾值 ────────────────────────────────────────────────────────────────────

`CHAT_TURN_RECORDING`

啟用逐輪記錄 (user_message、final_response、tool_calls) 到 chat_turns SQLite 表。

作用: agent 循環中的 chatTurnRecorder 鉤子（[src/core/agent-loop.ts]，在 turn_complete 時 fire-and-forget）。該記錄是個性化記憶抽取重建器的輸入——沒有它，rebuildMemories 無內容可掃描，返回 no_turns。
消費方: src/app.ts isChatTurnRecordingEnabled()——切換是否在 agent 循環上註冊該鉤子。
何時設置: 生產環境保持默認開啟。僅在對隱私敏感的部署中，或需將 turn 循環與個性化層隔離調試時，才設為 0。
未設置時: 默認開啟——每一輪都會被持久化。
格式: 0 / false / no / off 表示禁用。其他任何值（包括空或未設置）都保持開啟。
設置歸屬: 設置 → 偏好（schema 鍵）

`FIN_PROFILE_TRADING_SUMMARY_MIN_NEW_TRADES`

交易摘要重建器考慮運行前所需的最小新增交易數。兩道門之一（另一道是下方的最小檢查間隔）；兩者必須同時滿足。

作用: rebuildTradingSummary（[src/memory/personalization-rebuilder.ts]）中的 tradingSummaryMinNewTrades 閾值。也影響調度器的 60 分鐘兜底 tick——當 tick 觸發但 maxTradeId - last_seen < threshold 時，重建靜默無操作，不觸及 LLM。
消費方: 重建器中的 rebuildTradingSummary。
何時設置: 對頻繁進行小額 swap、覺得摘要更新過於頻繁的用戶調高到 5+；對希望任何一筆交易都立即刷新摘要的低頻用戶降到 1。
未設置時: 默認 3——僅在積累 3 筆新交易後才重建。
格式: 正整數。
設置歸屬: 非用戶設置項

`FIN_PROFILE_TRADING_SUMMARY_MIN_INTERVAL_MIN`

兩次成功交易摘要重建之間的最小分鐘數。與上方的新增交易閾值配對使用。

作用: tradingSummaryMinCheckIntervalMs。取代舊的 tradingSummaryCooldownMs 語義。
消費方: rebuildTradingSummary 的第 1 道門。
何時設置: 對希望摘要快速收斂的高級用戶調低（10-15）；調高（60-120）以降低 LLM 成本。
未設置時: 默認 30 分鐘。
格式: 正整數（分鐘）。
設置歸屬: 非用戶設置項

`FIN_PROFILE_TRADING_SUMMARY_MAX_TRADES`

全量重生成模式（冷啟動或 force=true）下每次重建考慮的最大交易數。

作用: 當不存在既有摘要時，傳給 LLM 的交易數上限。增量合併使用下方單獨的 INCREMENTAL_MAX_TRADES 窗口。
消費方: rebuildTradingSummary 的全量重生成路徑。
未設置時: 默認 100。
格式: 正整數。
設置歸屬: 非用戶設置項

`FIN_PROFILE_TRADING_SUMMARY_INCREMENTAL_MAX_TRADES`

增量合併模式（存在既有摘要時）餵給 LLM 的最大新增交易數。保持較小以讓每次重建都低成本。

作用: tradingSummaryIncrementalMaxTrades。LLM 看到 (existingSummary, newTrades) 並將其合併。
未設置時: 默認 50。
格式: 正整數。
設置歸屬: 非用戶設置項

`FIN_PROFILE_TRADING_SUMMARY_MAX_INCREMENTAL_RUNS`

在重建器強制進行一次全量重生成之前，可連續運行多少次增量合併。增量模式僅憑新交易增量重寫自己既有的摘要，因此小錯誤和虛假的“長期模式”會在多次合併中累積；週期性的全量重生成會重新讀取真實交易歷史並重新錨定摘要。

作用: tradingSummaryMaxIncrementalRuns。一個按用戶的計數器（financial_profile.trading_summary_incremental_runs）在每次增量合併時遞增，在全量重生成時重置為 0；當它達到該上限時，下一次重建即為全量重生成。
未設置時: 默認 10。
格式: 正整數。
設置歸屬: 非用戶設置項

`FIN_PROFILE_MEMORIES_MIN_NEW_TURNS`

rebuildMemories 掃描前所需的最小新增聊天輪數。與交易摘要的新增交易閾值相對應。

作用: memoriesMinNewTurns。記憶抽取重建器的第二道門（與最小檢查間隔並列）。
消費方: rebuildMemories 的第 2 道門。
何時設置: 對快速產生事實的健談用戶調低（2-3）；對節奏緩慢的單問對話調高（10+）。
未設置時: 默認 5。
格式: 正整數。
設置歸屬: 非用戶設置項

`FIN_PROFILE_MEMORIES_MIN_INTERVAL_MIN`

兩次成功記憶抽取重建之間的最小分鐘數。

作用: memoriesMinCheckIntervalMs.
未設置時: 默認 10 分鐘。
格式: 正整數（分鐘）。
設置歸屬: 非用戶設置項

`FIN_PROFILE_EVENT_DEBOUNCE_SEC`

事件驅動的 scheduleCheck(dim) 調用的防抖窗口。將快速爆發的數據寫入事件（例如 500ms 內 5 筆交易）合併為窗口結束後的單次經門校驗的重建嘗試。

作用: eventDebounceMs。重建器為每個維度複用同一個 setTimeout；窗口內的新事件會重置計時器。
消費方: PersonalizationRebuilder.scheduleCheck.
何時設置: 對大量模擬交易快速接連落地的回測 / CI 場景調高到 60+；對希望調試時獲得近乎即時重建反饋的開發者降到 5-10。
未設置時: 默認 30 秒。
格式: 正整數（秒）。
設置歸屬: 非用戶設置項

會話外歷史鏡像

personalization rebuilder 現在消費三個來源：本地 trade_history（agent 會話內）、perps_fills（Minara 的 /v1/perp-wallets/fills 的跨 sub 鏡像）、以及 external_spot_activities （Minara 的 /v1/tx/cross-chain/activities）。下面的旋鈕調優鏡像如何保持自身最新，以及 LLM rebuilder 讀取其中多少。

`FIN_PROFILE_HISTORY_SYNC_WINDOW_DAYS`

滾動同步窗口（天）。

作用: perps fills 和 spot activities 的截止時間。早於 now - WINDOW_DAYS 的一律不拉取。
消費方: MinaraHistorySync，以及經由 tradingSummaryAggregateWindowDays 的交易摘要聚合查詢。
何時設置: 對希望捕捉更長期風格的交易者調大；對高頻用戶調小，否則其鏡像會增長到數萬行。
未設置時: 默認 90 天。
格式: 正整數（天）。
設置歸屬: 非用戶設置項

`FIN_PROFILE_HISTORY_SYNC_MIN_INTERVAL_MIN`

相繼同步觸發之間的節流下限。窗口內的多次 scheduleSync() 調用會合併為最終一次運行。防止每個交易事件都變成一次上游 API 請求。

消費方: MinaraHistorySync.scheduleSync + runIfStale.
未設置時: 默認 5 分鐘。
格式: 正整數（分鐘）。
設置歸屬: 非用戶設置項

`FIN_PROFILE_HISTORY_SYNC_TIMEOUT_SEC`

單次 syncAll() 調用的硬性超時。經由 AbortController 路由，因此底層 HTTP 調用會被取消，而非僅僅被遺棄。

未設置時: 默認 8 秒。
格式: 正整數（秒）。
設置歸屬: 非用戶設置項

`FIN_PROFILE_HISTORY_SYNC_PAGE_HINT`

針對缺少任何分頁參數的 perps-fills 端點的“本頁大概已滿”上游啟發式。當 getPerpSubAccountFills 返回 >= 該行數時，我們假定同一窗口內可能還有更多，並將 startTime 前移以再次請求。

未設置時: 默認 500。
格式: 正整數（行）。
設置歸屬: 非用戶設置項

`FIN_PROFILE_HISTORY_SYNC_OVERLAP_SEC`

在可能被截斷的頁面上前移 startTime 時的重疊（秒）。重疊越大 = 越多無謂抓取；越小 = 越可能漏掉邊界處的一筆 fill。fill_uid 去重使重複計數無害。

未設置時: 默認 60 秒。
格式: 正整數（秒）。
設置歸屬: 非用戶設置項

`FIN_PROFILE_HISTORY_SYNC_MAX_ROUNDS_PER_SUB`

每個子賬戶截斷滾動循環的硬性上限。超過該輪數後我們放棄，讓下一次同步從水位線繼續。

未設置時: 默認 10。
格式: 正整數。
設置歸屬: 非用戶設置項

`FIN_PROFILE_HISTORY_SYNC_MAX_FAILURES`

按 (source, sub_account_id) 的連續失敗閾值。達到或超過該計數時，同步在正常調度期間跳過該鍵；水位線保持不動，使下一次嘗試從同一位置恢復。該跳過並非永久——見 _FAILURE_COOLDOWN_MIN。

未設置時: 默認 5。
格式: 正整數。
設置歸屬: 非用戶設置項

`FIN_PROFILE_HISTORY_SYNC_FAILURE_COOLDOWN_MIN`

當某個鍵觸及 MAX_FAILURES 後，下一次探測嘗試以自 last_synced_at 起經過該冷卻時間為前提。探測成功 → 計數器重置為 0；探測失敗 → 計數器繼續遞增。防止一次瞬時故障永久禁用鏡像。

未設置時: 默認 30 分鐘。
格式: 正整數（分鐘）。
設置歸屬: 非用戶設置項

`FIN_PROFILE_HISTORY_SYNC_SPOT_MAX_PAGES`

spot 分頁循環的硬性上限。當上遊持續返回“頁已滿”響應時，阻止分頁失控。

未設置時: 默認 20。
格式: 正整數。
設置歸屬: 非用戶設置項

`FIN_PROFILE_HISTORY_SYNC_SPOT_PAGE_SIZE`

spot 分頁批量大小。作為 limit 轉發給 Minara。必須為上游 API 所支持；100 是文檔記載的默認值。

未設置時: 默認 100。
格式: 正整數。
設置歸屬: 非用戶設置項

`FIN_PROFILE_TRADING_SUMMARY_PERPS_RECENT_FILLS`

有多少條最近的 perps fills 會發送給 LLM 重建。按 symbol 的聚合始終完整發送；該旋鈕只限制原始 fill 日誌。

未設置時: 默認 30。
格式: 正整數。
設置歸屬: 非用戶設置項

`FIN_PROFILE_TRADING_SUMMARY_SPOT_RECENT_ACTIVITIES`

對 spot 同理。

未設置時: 默認 20。
格式: 正整數。
設置歸屬: 非用戶設置項

`FIN_PROFILE_TRADING_SUMMARY_AGGREGATE_WINDOW_DAYS`

餵給 LLM 重建的按 symbol / 按 pair 聚合的窗口。通常等於 HISTORY_SYNC_WINDOW_DAYS；可調小以聚焦近期行為。

未設置時: 默認 90。
格式: 正整數（天）。
設置歸屬: 非用戶設置項

`FIN_PROFILE_MEMORY_SOFT_DELETE_RETENTION_DAYS`

軟刪除的記憶在 30 分鐘清除 cron 物理移除前可恢復多久。web UI 的“撤銷刪除”提示可在 5 秒內恢復；該旋鈕通過保留該行來防範更長期的誤刪，使 CLI 級別的恢復仍能將其找回。

未設置時: 默認 30 天。
格式: 正整數（天）。
設置歸屬: 非用戶設置項

`MINARA_HL_DEX_DISCOVERY`

在同步 perps 持倉、訂單和歷史時，選擇性啟用實時 Hyperliquid perpDexs 發現。

作用: perps 快照與歷史同步的每次掃描 dex 扇出。默認只查詢已知當前用戶群持有持倉的兩個 dex（"" 默認 + "xyz" 股票/大宗商品）——每次掃描 16 個 HL 請求，遠在 HL 的每 IP 限流之內。當此開關打開時，快照還會調用 HL perpDexs（緩存 10 分鐘）並對其返回的每個具名 dex（xyz、flx、vntl、hyna、km、abcd、cash、para、……）扇出。對於典型的 4 子賬戶用戶，這會把每次掃描的預算推高到約 72 個請求，穩定觸發公共 /info 端點的 429。
何時設置: 僅當你確實在 "" / "xyz" 之外的具名 dex（例如 flx、vntl）上持有持倉時。多數用戶應保持關閉。
未設置時: 只查詢已知可靠的 ["", "xyz"] 組合，且按子賬戶的 clearinghouseState + frontendOpenOrders 扇出保持在 HL 的限流預算之內。
格式: 1 / true / yes / on 表示啟用；其他任何值（或未設置）保持發現禁用。
設置歸屬: 設置 → 偏好（schema 鍵）

`WORKFLOW_HEARTBEAT_CHECK_MS`

workflow 心跳監視器的掃描節奏。控制內容：HeartbeatMonitor.checkIntervalMs（[src/workflow/heartbeat.ts]）。若某個運行中實例上一步 updateInstance 早於 MAX_SILENCE_MS，就會被標記為 status="canceled" cancel_reason="timeout"。

何時設置: 在 dev/staging 中調短（例如 5000）以快速暴露掛起，在生產中調長以降低 SQLite 掃描負載。
未設置時: 默認 30 000 ms（30 秒）。
格式: 正整數（毫秒）。非數值 / 非正值回退到默認。
設置歸屬: 非用戶設置項

`WORKFLOW_HEARTBEAT_MAX_SILENCE_MS`

判定運行中 workflow 超時前的靜默閾值。

作用: HeartbeatMonitor.maxSilenceMs。也限制單步可容忍的最大時長，因為 last_heartbeat_ms 在每次 commitStepAdvance 時都會被推進。
何時設置: 對含有較長 agent_turn 步驟或外部 API 抓取的 workflow，調高到 300 000 ms 默認值以上。
未設置時: 默認 300 000 ms（5 分鐘）。
格式: 正整數（毫秒）。
設置歸屬: 非用戶設置項

`WORKFLOW_MAX_QUEUE_DEPTH`

按定義的 cron/事件觸發隊列上限（[src/workflow/triggers.ts]）。每個 workflow 定義有自己的 FIFO；隊列滿時丟棄最舊的待處理觸發。

何時設置: 對觸發頻率會合理超過單次運行時長、且你在意補跑的 workflow 調高；當只有最新信號重要時降到 1。
未設置時: 默認 10。
格式: 正整數。
設置歸屬: 非用戶設置項

`MINARA_SS_CODEGEN_MAX_ITER`

離線 strategy-codegen 子代理在每次 benchmark 運行中允許多少次“生成代碼 → 臨時回測 → 精煉”迭代。

作用: runStrategyCodeSubagent（[src/core/strategy-code-subagent.ts]）中 codegen 循環的步數預算。子代理運行到這麼多步。模型在該預算內自行決定何時回測、何時停止；返回時，成功與否根據最終回測重新計算（status COMPLETED + 非零交易數 + drawdown < 0.95）。
消費方: src/core/strategy-code-subagent.ts 中的 runStrategyCodeSubagent，由 strategy-rl benchmark 運行器驅動（僅離線調優；非面向聊天的工具）。
未設置時默認: 3
鉗制範圍: [1, 10]
格式: 正整數
當運維的 llmClient 快速且便宜（例如 Haiku）並想要更好的收斂時調高；當使用慢速 / 昂貴的模型並願意接受更差的代碼時調低（1–2）。
設置歸屬: 非用戶設置項

`MINARA_STRATEGY_SKILL_RL_ENABLED`

Strategy Studio Skill RL / 自演化 Skill 文本的選擇性試點。

作用: 由存儲支撐的 Strategy Studio skill 版本、按用戶的策略偏好疊加層、rollout 追蹤，以及離線 codegen benchmark 循環的獎勵日誌。
未設置時默認: 禁用。禁用時，bootstrap 不創建 strategy_skill_* 表，也不改動生產 Strategy Studio skill 提示或 codegen 策略。
可接受的真值: 1 | true | yes | on
Scope: 本試點僅限 Strategy Studio；這不是面向每個 skill 的全局 RL 框架。
設置歸屬: 設置 → 偏好（schema 鍵）

`MINARA_STRATEGY_CONTEXT_RL_ENABLED`

Strategy Studio Context Policy RL 的選擇性試點。

作用: 帶版本的外部上下文選擇策略、策略感知的上下文收集、三臂回放 benchmark，以及顯式的晉升 / 回滾審計記錄。
未設置時默認: 禁用。需要 MINARA_STRATEGY_SKILL_RL_ENABLED=1。禁用時，bootstrap 不創建 strategy_context_policy_* 表，外部上下文 provider 保持不變。
可接受的真值: 1 | true | yes | on
Scope: 僅限 Strategy Studio 的外部上下文選擇。
設置歸屬: 設置 → 偏好（schema 鍵）

`MINARA_SKILL_ROUTER_RL_ENABLED`

面向 Skill Router 策略演化的通用 Agent Harness RL 選擇性試點。

作用: 帶版本的 skill 排序策略、離線路由 benchmark 用例、有界的策略探索、顯式的晉升 / 回滾，以及用已晉升策略對每輪 Skill catalog 排序。
未設置時默認: 禁用。Bootstrap 不創建 skill_router_* 表，Skill catalog 保持其既有優先級順序，內置的 did-you-mean 路由行為不變。
可接受的真值: 1 | true | yes | on
Scope: 僅限通用 Skill 發現/路由。它絕不改變 Skill 文本、工具權限層級、安全門或模型權重。
設置歸屬: 設置 → 偏好（schema 鍵）

───────────────────────────────────────────────────────────────── 機構模式（多智能體公司模擬） ───────────────────────────────────────────────────────────────── minara_institution_analyze 工具召集一條 6 階段 pipeline （4 個分析師並行 → 多頭/空頭研究辯論 → 研究經理 → 交易員 → 三方風險辯論 → 組合經理），用於高風險的單資產分析。仿照 TradingAgents （https://github.com/TauricResearch/TradingAgents）。輪數的默認值錨定於 TradingAgents 的 default_config.py。超時 / token 上限遵循 Minara 實踐（deep-research 階段預算、agent-loop max_tokens）。下面所有變量都是 agent-loop 基礎設施——按項目的 env-var 命名約定，無 MINARA_ 前綴。

`INSTITUTION_MAX_DEBATE_ROUNDS`

多頭 vs 空頭交替回合數。

作用: 機構分析管線 Phase 2 的完整回合數。1 回合 = 共 2 輪（一次多頭、一次空頭）。更高 → 辯論更充分，LLM 成本更高。
消費方: src/tools/institution/orchestrator.ts 中的 runInstitution
Surfaced via tool: minara_institution_analyze（max_debate_rounds 參數可為單次調用覆蓋此值）
未設置時默認: 1（與 TradingAgents 的 max_debate_rounds: 1 一致）
鉗制範圍: [1, 5]
格式: 正整數
何時設置: 對希望多頭和空頭交鋒兩次的高確信度交易調到 2；常規分析保持 1 以控制成本。
設置歸屬: 非用戶設置項

`INSTITUTION_MAX_RISK_ROUNDS`

激進/保守/中性輪換回合數。

作用: Phase 5 的完整回合數。1 回合 = 共 3 輪（激進 → 保守 → 中性）。更高 → 風險審視更徹底，LLM 成本更高。
消費方: src/tools/institution/orchestrator.ts 中的 runInstitution
Surfaced via tool: minara_institution_analyze（max_risk_rounds 參數可為單次調用覆蓋此值）
未設置時默認: 1（與 TradingAgents 的 max_risk_discuss_rounds: 1 一致）
鉗制範圍: [1, 5]
格式: 正整數
設置歸屬: 非用戶設置項

`INSTITUTION_WALL_CLOCK_TIMEOUT_MS`

單次機構運行的全局牆鍾預算。

作用: 單次 minara_institution_analyze 調用總耗時的硬性上限。超出時，編排器短路所有進行中的階段，返回已完成的部分並附帶 meta.truncated: true。單個 sub-LLM 調用的按調用超時由 INSTITUTION_PER_CALL_TIMEOUT_MS（見下）控制，並被鉗制為絕不超過此牆鍾。
消費方: src/tools/institution/orchestrator.ts 中的 runInstitution
未設置時默認: 1200000（20 分鐘——為兩次順序的 5 分鐘調用加上管線其餘部分留足餘量）
鉗制範圍: [60000, 1800000]
格式: 整數毫秒
何時設置: 對接受部分結果的更便宜 / 更快運行調低（例如 600000 = 10 分鐘）；用深度模型跑大型辯論時調高（例如 1800000 = 30 分鐘）。
設置歸屬: 非用戶設置項

`INSTITUTION_PER_CALL_TIMEOUT_MS`

機構管線內每次 LLM 調用的超時。

作用: 施加到每次 sub-LLM 調用（分析師、辯手、經理、結構化輸出重試）的按調用中止信號。需要在單個 sub-agent 循環內調用 2-3 個數據工具並寫出結構化 AnalystReport 的分析師，通常耗時超過一個過緊的上限——先前 60s 的默認值（wallClock/10）會在其寫到一半時中止它們。新的 300s 默認值為這類工作留足預算，同時仍能防範卡住的 provider。
消費方: src/tools/institution/orchestrator.ts 中的 perCallTimeoutMs（也會穿入 runInstitutionSubagent）
未設置時默認: 300000（5 分鐘）
鉗制範圍: [5000, INSTITUTION_WALL_CLOCK_TIMEOUT_MS]
格式: 整數毫秒
何時設置: 在快速的 quick-model 上運行、且希望分析師快速失敗而非燒牆鍾時調低（例如 60000 = 1 分鐘）；僅當 provider 響應緩慢時，配合相應的牆鐘上調再調高（例如 600000）。
設置歸屬: 非用戶設置項

`INSTITUTION_MAX_OUTPUT_TOKENS_PER_TURN`

每次 LLM 調用的輸出上限。

作用: 統一施加到機構管線內每次 LLM 調用（分析師、辯手、經理、結構化輸出重試）的 max_tokens 上限。作為成本上限——而非行為旋鈕。每個角色的提示本就要求簡潔輸出；這只是防範生成失控。
消費方: src/tools/institution/ 中的 runInstitution 和 runInstitutionSubagent
未設置時默認: 4096（與 agent 循環的默認 max_tokens 一致）
鉗制範圍: [1024, 16384]
格式: 正整數
何時設置: 實驗期間為控制成本調低；當 PM 不斷截斷 executive_summary 時調高。
設置歸屬: 非用戶設置項

───────────────────────────────────────────────────────────────── 機構模式 v2 — 自學習 (PR 1 + PR 2) ───────────────────────────────────────────────────────────────── 持久化 + Phase B 反思階梯 + Phase 0 回顧式刷新。運行時數據與 Minara 其餘部分保存在同一個 SQLite db。反思 alpha 數值餵給 PR 4 的 methodology 畢業反饋循環（在後續中落地）。

`INSTITUTION_LEARNING_ENABLED`

v2 自學習路徑（institution_runs / institution_role_outputs / institution_reflections 持久化）的總開關。

作用: 開啟時，每次 minara_institution_analyze 運行都以 fire-and-forget 方式持久化其完整結構化產物（PM 評級 + 論點 + 各角色輸出 + 方法論引用）。關閉時，採集鉤子無操作，institution_* 表保持為空。
消費方: src/learning/institution/capture-hook.ts 中的 captureInstitutionRun
未設置時默認: on
格式: on | off | 1/true/yes——其他任何值（包括未設置）→ on
何時設置: 僅在你不希望任何 institution 行寫入磁盤的臨時 / CI / dev 運行中設為 off。生產環境保持開啟；持久化的行會向下遊供給 Phase B 反思 + 方法論畢業。
設置歸屬: 設置 → 偏好（schema 鍵）

`INSTITUTION_RETROSPECT_ENABLED`

Phase 0 惰性刷新總開關。

作用: 開啟時，每次新的 minara_institution_analyze 調用都會遍歷同一 (ticker, asset_class) 上的近期運行，並對任何最新反思已陳舊的運行寫入一條 lazy_refresh 反思。運維可通過 /institution-history 查看它們。
消費方: src/tools/institution/index.ts 中的 runSingleTicker（Phase 0 塊），src/learning/institution/reflect.ts 中的 runLazyRefresh
未設置時默認: on
格式: on | off
何時設置: 在 YahooFinance 網絡調用會無謂拖慢運行的 CI / 批量測試中關閉。標準 cron 反思（若已調度）會獨立繼續運行。
設置歸屬: 設置 → 偏好（schema 鍵）

`INSTITUTION_RETROSPECT_LIMIT`

Phase 0 歷史深度。

作用: Phase 0 在決定刷新哪些之前，每個 (ticker, asset_class) 拉取的先前運行的最大數量。
消費方: src/tools/institution/index.ts 中的 runSingleTicker
未設置時默認: 10
鉗制範圍: [1, 50]
格式: 正整數
何時設置: 對多 ticker 的健談用戶調低（3-5）以限制單次調用延遲；當反思性上下文在小 ticker 集上比新鮮度更有價值時調高（20+）。
設置歸屬: 非用戶設置項

`INSTITUTION_RETROSPECT_TIMEOUT_MS`

Phase 0 牆鍾。

作用: Phase 0 每次機構調用花在惰性刷新寫入上的總時間的硬性上限。有效超時為 min(this var, INSTITUTION_WALL_CLOCK_TIMEOUT_MS / 2)，並有 5s 下限——保證 Phase 1 啟動時編排器（Phase 1-6）仍至少擁有其聲明牆鍾預算的 50%。沒有該上限，一個 60s 的工具調用預算可能最終總共耗時 180s 以上（codex 評審第 2 輪）。
消費方: src/tools/institution/index.ts 中的 runSingleTicker
未設置時默認: 120000（2 分鐘）
鉗制範圍: [5000, INSTITUTION_WALL_CLOCK_TIMEOUT_MS / 2]
格式: 正整數毫秒
設置歸屬: 非用戶設置項

`INSTITUTION_LAZY_REFRESH_STALE_HOURS`

Phase 0 陳舊閾值。

作用: 當先前運行的最新反思的 evaluated_at 早於這麼多小時時，該反思被視為“陳舊”（並符合惰性刷新資格）。更小的值使每次調用寫入更多刷新（= 更高成本 + 更新的 PM 上下文）；更大的值則依賴每日 cron 保持新鮮。
消費方: src/learning/institution/reflect.ts 中的 shouldWriteLazyRefresh
未設置時默認: 24
鉗制範圍: [1, 168]
格式: 正整數小時
設置歸屬: 非用戶設置項

`INSTITUTION_LAZY_REFRESH_DEDUPE_HOURS`

Phase 0 寫入去重。

作用: 同一運行上連續兩次 lazy_refresh 寫入之間的最小小時數。防止 10 分鐘內三次調用 /institution BTC 生成三條几乎相同的反思——第二次和第三次調用複用第一行。
消費方: src/learning/institution/reflect.ts 中的 shouldWriteLazyRefresh
未設置時默認: 6
鉗制範圍: [1, 48]
格式: 正整數小時
設置歸屬: 非用戶設置項

`INSTITUTION_AUTO_STALE_DAYS`

自動陳舊晉升閾值。

作用: 當一個 open 機構運行的年齡超過這麼多天仍未最終定案時，會被晉升為 auto_stale。自動陳舊的運行繼續接收 Phase B 反思，但在 PM past_context 注入中被降權（PR 2 下游接線）。
消費方: src/learning/institution/reflect.ts 中的 runScheduledReflections
未設置時默認: 90
鉗制範圍: [30, 365]
格式: 正整數天
設置歸屬: 非用戶設置項

`INSTITUTION_BENCHMARK_CRYPTO` / `INSTITUTION_BENCHMARK_STOCK` / `INSTITUTION_BENCHMARK_FOREX`

各資產類別的 alpha 基準。Phase B 反思 alpha 計算為同一窗口內的 raw_return - benchmark_return。設為所配置價格來源能解析的 ticker（默認 Yahoo）。

Defaults when unset: crypto → BTC stock → SPY forex → DXY
（commodity / stablecoin / unknown 有意沒有基準
——這些類別的 alpha 記為 null。）
格式: ticker 字符串
設置歸屬: 非用戶設置項

分析師恢復

每個 Phase-1 分析師槽在一個自由 tool-calling 循環中運行模型，然後運行單次綜合輪，要求以 HEADLINE / KEY FINDINGS / CONFIDENCE 格式給出結構化的散文摘要。orchestrator 直接把該散文解析成 AnalystReport—— 無強制提交的 toolChoice 步驟，無重試 harness。當綜合為空或不可解析時，orchestrator 回落到 buildSubagentSummaryReport，它總能發出一份可用報告（工具成功時從原始工具輸出，否則用角色默認推理）。下游階段總能收到一份可用摘要；舊的 data_gap 標誌已退役。無運營方可調的 env 變量——契約是 "總能產出可用之物"，且沒有可調的預算。

`INSTITUTION_FORCE_RESOLVER_PREFLIGHT`

始終開啟的規範預檢。

作用: 默認情況下，服務端規範身份預檢僅在 classifyAsset(ticker) === "unknown" 時運行。將其設為 true 會強制對每個 ticker 預檢，這對運維驗證有用（解析器在知名 ticker 上是否也表現正確？）。有少量延遲成本（緩存命中約 50ms，緩存未命中約 200-500ms）。
消費方: 編排器預檢階段。
未設置時默認: false
可接受的值: true / false / 1 / 0
設置歸屬: 非用戶設置項

規範資產緩存

canonical-asset 解析器寫穿一個 SQLite 緩存，因此 agent 第二次看到某個 ticker 時不再重新命中 CoinGecko / CMC / DexScreener。TTL 按結果而定——唯一解析可比有歧義的緩存更久，而空結果快速過期，以便在 provider 發佈更多數據後重試。

`CANONICAL_ASSET_CACHE_TTL_RESOLVED_DAYS`

outcome: "resolved" 的 TTL（單一規範 chain+contract 或 native+chain）。

消費方: src/learning/canonical-asset-cache.ts
未設置時默認: 30
格式: 正整數天
設置歸屬: 非用戶設置項

`CANONICAL_ASSET_CACHE_TTL_MULTI_DAYS`

outcome: "multi" 的 TTL（多鏈部署，例如 USDC 在 20 條鏈上）。比 resolved 短，因為運維/用戶消歧可能會釘到某條特定鏈。

消費方: src/learning/canonical-asset-cache.ts
未設置時默認: 14
格式: 正整數天
設置歸屬: 非用戶設置項

`CANONICAL_ASSET_CACHE_TTL_AMBIGUOUS_DAYS`

outcome: "ambiguous" 的 TTL（provider 結果不一致，存在多個 token 候選）。較短，以便在 provider 數據收斂或用戶覆蓋釘定後重新解析。

消費方: src/learning/canonical-asset-cache.ts
未設置時默認: 7
格式: 正整數天
設置歸屬: 非用戶設置項

`CANONICAL_ASSET_CACHE_TTL_NONE_DAYS`

outcome: "none" 的 TTL（沒有來源返回數據）。非常短——provider 每日更新，因此我們希望儘快重新嘗試，而不是緩存一個否定結果。

消費方: src/learning/canonical-asset-cache.ts
未設置時默認: 1
格式: 正整數天
設置歸屬: 非用戶設置項

`CANONICAL_ASSET_CACHE_TTL_USER_DAYS`

用戶提供條目的 TTL（經 minara assets pin 或橫幅 CTA 的運維覆蓋）。較長，因為用戶已明確告訴我們想要哪個規範；pin 條目優先於 provider 解析。

消費方: src/learning/canonical-asset-cache.ts
未設置時默認: 365
格式: 正整數天
設置歸屬: 非用戶設置項

`CANONICAL_ASSET_CACHE_FALLBACK_TO_EXPIRED`

陳舊兜底策略。

作用: 當實時聚合器失敗（所有 provider 宕機或被限流）時，解析器可以 (a) 返回標記為 from_expired_fallback: true 的過期緩存條目（true，默認），或 (b) 將該失敗視為 outcome: "none"（false）。對於幾天前的 token 解析，陳舊數據通常好過沒有數據；若你的部署無法容忍任何漂移，則設為 false。
消費方: src/learning/canonical-asset-resolver.ts
未設置時默認: true
可接受的值: true / false / 1 / 0
設置歸屬: 非用戶設置項

混合記憶檢索

這四個變量啟用 embedding 增強的記憶搜索。當 EMBEDDING_PROVIDER 為 disabled（默認）時，store 讓每行的 embedding_state='pending'、embedding 列為 NULL，而 searchMemoriesHybrid 穿透到 Phase-A 之前的 BM25 路徑，結果逐字節相同。運營方僅在想要語義召回提升時才啟用它——屆時每次 writeMemory / writeRoleMemory 都經 queueMicrotask 調度一次異步 embedding（無寫入路徑延遲成本）。失敗絕不會拋給調用方：embedding_state 列轉為 'failed' / 'skipped'，因此 minara doctor 能檢測到堆積， minara doctor --fix --apply 之後能回填它們。

`EMBEDDING_PROVIDER`

調用哪個 provider。

消費方: src/memory/embedding-provider.ts 中的 createEmbeddingProviderFromEnv
Surfaced to: MemoryStore.searchMemoriesHybrid、MemoryStore.scheduleEmbedding、MemoryStore.backfillEmbeddings
可接受的值: disabled | openai | voyage
未設置時默認: disabled
為 disabled 時，工廠返回 null——混合代碼路徑
完全惰性，行為與 Phase-A 之前的代碼一致。僅當 EMBEDDING_API_KEY 也已配置時
才設為真實 provider；否則
工廠仍返回 null（並記一條 warn）。
設置歸屬: 非用戶設置項

`EMBEDDING_API_KEY`

所配置 provider 的 bearer token。

OpenAI: 從 https://platform.openai.com/api-keys 獲取（sk-...）。
Voyage: 從 https://dash.voyageai.com/api-keys 獲取（pa-...）。
未設置時默認: （provider 返回 null，混合路徑惰性）
格式: 不透明字符串，無需引號。
設置歸屬: 設置 → API 密鑰

`EMBEDDING_MODEL`

模型標識符。

默認跟隨每個 provider 最便宜的 1536 維模型，使 vec0 表
尺寸與 EMBEDDING_DIM 的默認值保持對齊： - openai → text-embedding-3-small - voyage → voyage-3
僅當你已驗證維度匹配
EMBEDDING_DIM 時才覆蓋；不匹配會在嵌入時被拒絕（記 warn，
行保持 'failed'）。
設置歸屬: 非用戶設置項

`EMBEDDING_DIM`

向量維數。

必須與模型匹配。默認：1536。用於在啟動時聲明 vec0
虛擬表（memories_vec、role_memory_vec）——
在已有 DB 上更改此值需要手動遷移
vec0 表（刪除 + 重建；嵌入是非權威的，因此
丟失可通過 doctor --fix --apply 恢復）。
格式: 正整數。
設置歸屬: 非用戶設置項

`EMBEDDING_BASE_URL`

provider HTTP 端點的可選覆蓋。

未設置時默認: provider 原生 URL。 - openai → https://api.openai.com/v1/embeddings - voyage → https://api.voyageai.com/v1/embeddings
用於自託管網關或代理。格式：以
/embeddings 結尾的完整 URL。
設置歸屬: 非用戶設置項

`SQLITE_VEC_EXTENSION_PATH`

sqlite-vec 可加載擴展二進制的顯式路徑。

消費方: src/memory/memory-store.ts 中的 MemoryStore.tryEnableVec
未設置時默認: sqlite-vec npm 包自帶的平臺
二進制（通過 getLoadablePath() 解析）。運維僅在自行管理該二進制時才設置此項
（例如共享系統路徑、自定義
構建，或從 node_modules 中剝離同級
sqlite-vec-<platform>-<arch> 包的 Docker 層）。
格式: 指向 .so/.dylib/.dll 的絕對文件系統路徑。加載
失敗是非致命的——混合路徑靜默降級為純 BM25。
設置歸屬: 非用戶設置項

本頁目錄