Agent-loop 控制

Kill switch（退出次世代默認）

次世代行為默認啟用。下面每個 DISABLE_* env 在設為 1 / true / yes / on 時回退單個特性。把它們用於迴歸二分定位，而非日常運營。

1 把 buildPlaybookBlock 恢復為軟性建議式的頭部（"Follow the playbooks below…"），而非默認的祈使式清單（"The playbook below is the AUTHORITATIVE specification for this turn — not guidance. …"）。當更嚴格的語氣在某個場景上過度約束了 LLM，或運維想對二者做 A/B 時有用。

消費方: src/skills/scenarios/session.ts（buildPlaybookBlock）。
格式: 1 / true / yes / on 禁用（默認未設置）。
設置歸屬: 設置 → 偏好（schema 鍵）

`DISABLE_METHODOLOGY_INJECTION`

1 抑制所有按需 methodology 路徑：場景佔位符解析（{{methodology:key|default:val}} 回退到 default:）、工具輸出的 <methodology_reminder> 融合，以及 methodology_lookup 工具命中。默認行為（未設置）：三條路徑都以畢業檔（Wilson ≥ 0.55）查詢存儲。

消費方: src/skills/scenarios/methodology-placeholder.ts、
src/core/tool-output-hints.ts、src/tools/methodology-lookup.ts。
格式: 1 / true / yes / on 禁用（默認未設置）。
Compat: legacy METHODOLOGY_INJECTION_MODE=off 仍作為別名被接受
（啟動時輸出一次性棄用警告）。legacy 的
readonly / full 值映射到新默認（enabled），
因為在舊的三態下二者都是 "on" 狀態。
設置歸屬: 設置 → 偏好（schema 鍵）

`DISABLE_METHODOLOGY_CASE_RECORDING`

1 短路 case 記錄器的寫入路徑（recordHint / finalizeTurn 變為 no-op）。比 DISABLE_METHODOLOGY_INJECTION 更窄 —— 讀取路徑繼續工作。當你懷疑 case schema、想在不丟失 LLM 可見 methodology 提示的情況下停止學習時使用。

消費方: src/learning/case-recorder.ts，經由
src/learning/methodology-kill-switches.ts。
格式: 1 / true / yes / on 禁用（默認未設置）。
也可從 web-UI Settings → Preferences →
safety.methodologyCaseRecording（正向形式）觸及。
設置歸屬: 設置 → 偏好（schema 鍵）

`DISABLE_METHODOLOGY_MUTATIONS`

1 短路所有 methodology 變更：recordUsage / recordOutcome / requantize / 合成 cron / case 歸因全部變為 no-op。讀取（retrieve / findByKey / 融合 / lookup）繼續工作。最廣的 kill switch —— 用於當學習寫入路徑本身可疑時的事件響應。

消費方: src/learning/methodology-store.ts、
src/learning/case-attribution.ts、src/learning/methodology-synthesis.ts，
經由 src/learning/methodology-kill-switches.ts。
格式: 1 / true / yes / on 禁用（默認未設置）。
也可從 web-UI Settings → Preferences →
safety.methodologyMutations（正向形式）觸及。
設置歸屬: 設置 → 偏好（schema 鍵）

`MINARA_RETRIEVAL_ENGINE`

為記憶召回選擇檢索引擎。bm25（默認）是一直隨附的關鍵詞全文引擎；hybrid 把 BM25 與向量緩存結合，以延遲 + 內存為代價，對改寫過的查詢有更好的召回。未知值回退到 bm25。

消費方: src/learning/contracts/learning-services.ts（Phase 5C
腳手架；接線在後續 PR 中落地）。
格式: bm25 / hybrid（默認 bm25）。
設置歸屬: 非用戶設置項

`PROMPT_COMPOSER_ENABLED`

為 true 時，使用新的基於 provider-registry 的 PromptComposer 來組裝系統提示。Phase 5B 以 shadow 模式隨附該 composer（輸出與 legacy 組裝器逐字節一致），因此這個 flag 是給想在它成為默認之前壓測 composer 的運維的 opt-in。默認禁用可保持 golden 快照穩定。

消費方: src/core/prompt-composer.ts。
格式: 1 / true / yes / on 啟用（默認未設置）。
設置歸屬: 非用戶設置項

Methodology 審計子系統

對 methodology 學習循環的被動、只讀觀察者。以每日節奏對既有的學習表運行 SQL 聚合，並把一份綜合健康報告寫入 methodology_audit_reports。絕不改動學習狀態。與 agent 循環協作：在用戶輪進行中時跳過 tick，在一次遍歷內的 SQL 階段之間讓出。見 src/learning/methodology-audit.ts 和文檔站的 env-vars 文檔。

`METHODOLOGY_AUDIT_CRON_ENABLED`

進程內審計調度器的 opt-in 開關。默認 0（關）—— 一旦學習循環積累了足夠的可評分數據（通常在啟用 METHODOLOGY_LEARNING_CRON_ENABLED 後一兩週），須由運維顯式啟用調度器。在多 worker 部署中，只有 IS_PRIMARY_WORKER=1 的 worker 運行調度器 —— 副本靜默 no-op。

消費方: src/learning/methodology-audit-cron.ts。
格式: 1 / true / yes / on 啟用。
設置歸屬: 設置 → 偏好（schema 鍵）

`METHODOLOGY_AUDIT_CRON_INTERVAL_MS`

審計調度器的 tick 間隔。默認 86400000（24h）。運行時鉗制到 [5min, 30d]，這樣打錯字既不會刷爆 agent 進程，也不會靜默禁用審計。

消費方: src/learning/methodology-audit-cron.ts。
設置歸屬: 設置 → 偏好（schema 鍵）

`METHODOLOGY_AUDIT_WINDOW_DAYS`

窗口受限評分維度（synthesis_quality、attribution_integrity、quarantine_churn）的回溯窗口。默認 30。運行時範圍鉗制到 [1, 365]。更大的窗口平滑趨勢，但減慢系統對突發退化的反應。

消費方: src/learning/methodology-audit-cron.ts。
設置歸屬: 設置 → 偏好（schema 鍵）

`METHODOLOGY_AUDIT_RETENTION_DAYS`

審計報告保留多久。默認 90。範圍鉗制到 [7, 3650]。審計 cron 在每日 tick 之後，每個本地日最多修剪一次。

消費方: src/learning/methodology-audit-cron.ts。
設置歸屬: 非用戶設置項

`METHODOLOGY_AUDIT_SKIP_BUSY_THRESHOLD_MS`

busy 預檢的空閒閾值。默認 180000（3min）。當 BusyTracker 報告 inFlight > 0 或 idleSinceMs < threshold 時，審計 tick 被推遲，deferred_count 遞增。範圍鉗制到 [0, 1h]。設為 0 可禁用預檢門（無論 agent 狀態如何，審計在每個 tick 立即運行）—— 對測試有用，生產中不推薦。

消費方: src/learning/methodology-audit-cron.ts。
設置歸屬: 非用戶設置項

`METHODOLOGY_AUDIT_MAX_DEFERRED_TICKS`

餓死守衛。在連續這麼多次推遲的 tick 之後，即便 agent 仍然繁忙，審計過程也會運行，這樣一個永久繁忙的安裝不會丟失審計覆蓋。默認 4（在 24h 默認間隔下 ≈ 4 天）。鉗制到 [0, 100]。設為 0 可強制每個 tick 無論 busy 狀態都運行。

消費方: src/learning/methodology-audit-cron.ts。
設置歸屬: 非用戶設置項

`METHODOLOGY_AUDIT_YIELD_TIMEOUT_MS`

在每個 SQL 階段之間，審計編排器讓出給事件循環，並等待 BusyTracker 報告空閒。這會給該等待設上限，這樣一個永不結束的輪次不會無限期餓死審計。默認 60000（60s）。鉗制到 [0, 10min]。超時後，審計無論 busy 狀態都恢復。

消費方: src/learning/methodology-audit-cron.ts、
src/learning/methodology-audit.ts。
設置歸屬: 非用戶設置項

`DISABLE_METHODOLOGY_AUDIT`

審計子系統的頂層 kill switch。1 同時短路 cron 過程和 audit run CLI：返回一個 band=disabled 的佔位報告，且不持久化。CLI 讀取路徑（audit show、audit trend、audit findings）不受影響。與現有的 DISABLE_METHODOLOGY_MUTATIONS kill switch 相仿。

消費方: src/learning/methodology-audit.ts。
格式: 1 / true / yes / on 禁用。
設置歸屬: 非用戶設置項

`DISABLE_METHODOLOGY_INSTANCE_DISPATCH`

1 強制 MethodologyInstanceStore.resolveThresholds 始終返回模板默認值，忽略 BO 調優的按資產類別實例覆蓋。默認行為（未設置）：存在實例覆蓋時，將其合併到模板默認值之上。

消費方: src/learning/methodology-instance-store.ts。
格式: 1 / true / yes / on 禁用（默認未設置）。
設置歸屬: 非用戶設置項

主動財富 Agent

運行每個已激活委託的後臺監督循環：把持倉按市值計價、止盈 / 止損 / 再平衡、為曲線快照 PnL，並寫入工作日誌。兩個旋鈕也可在 Settings → Proactive 以及 Proactive 模塊自身的設置頁實時編輯（它們映射到 proactive.* preferences）。

`PROACTIVE_SUPERVISOR_ENABLED`

後臺 supervisor 的總開關。默認 1（開）：已激活的 mandate 在你設定的限度內自行持續工作。設為 0 可暫停每個 mandate 的自主活動 —— mandate 保持激活，只是停止行動，直到你把它重新打開。在多 worker 部署中只有 IS_PRIMARY_WORKER=1 運行該循環；副本 no-op。

消費方: src/proactive/supervisor-cron.ts。
格式: 1 / true / yes / on 啟用（默認開）。
設置歸屬: 設置 → 偏好（schema 鍵）

`PROACTIVE_SUPERVISOR_INTERVAL_SEC`

每個 mandate 多久檢查一次其持倉，單位秒。默認 900（15min）。運行時鉗制到 [10s, 1h]，這樣打錯字既不會刷爆進程，也不會拖住循環。更短的間隔反應更快，但做更多工作。

消費方: src/proactive/supervisor-cron.ts。
設置歸屬: 設置 → 偏好（schema 鍵）

`PROACTIVE_REDISCOVER_INTERVAL_SEC`

一個 mandate 多久搜尋一次新機會（付費的 re-plan 步驟），單位秒。默認 1800（30min）。運行時鉗制到 [1min, 24h]。這個值每個週期實時讀取，因此更改無需重啟即可生效。re-discovery 在更快的 supervisor 過程之上運行；越不頻繁，LLM 調用花費越少。未配置模型時優雅跳過。

消費方: src/app.ts（runProactiveMandateCycle）。
設置歸屬: 設置 → 偏好（schema 鍵）

`DISABLE_KNOWLEDGE_BUDGET`

1 完全繞過 Knowledge Budget 協商器；場景 playbook + 記憶快照 + 角色提示以完整長度輸出，僅受 Anthropic 上下文限制約束。默認行為（未設置）：若合併大小超過 KNOWLEDGE_BUDGET_TOKENS（默認 15000 ≈ 60k 字符）則裁剪。

消費方: src/core/knowledge-budget.ts，經由 src/core/agent-loop.ts。
格式: 1 / true / yes / on 禁用（默認未設置）。
設置歸屬: 設置 → 偏好（schema 鍵）

`ROLE_MEMORY_MODE`

啟動時的角色 case 學習與注入模式。

作用: off 讓現有角色 case 對審計 API 仍然可用，但不創建、不評估、不召回、不注入任何新的；shadow（默認）僅在匹配的手動交易執行後才存儲並評估 case，不註冊召回、不改變模型提示；active 額外把已反思的手動 case 召回進匹配的分析 skill 以及 institution 的 Trader / PM 提示。Autopilot、Strategy Studio、workflow 以及來源未知的 perps 永遠不進入這條路徑。執行工具永遠不接收角色記憶文本。
何時設置: 在驗證 case 質量期間保持 shadow；僅在審閱反思後才用 active，或用 off 停止新的角色學習。
When unset or invalid: shadow（無效值在啟動時輸出警告）。
更改在啟動時讀取一次，需要重啟 agent。
格式: 嚴格為 off、shadow 或 active。
設置歸屬: 設置 → 偏好（schema 鍵）

`DISABLE_PARALLEL_TOOL_CALLS`

DISABLE_PARALLEL_TOOL_CALLS 控制逐輪工具調度器。設為 1 時，所有工具調用強制串行。未設置時，READ_ONLY 工具默認進入有上限的 FIFO 併發窗口；主動退出併發的工具、寫操作、資金操作、未知工具、動態工具、tool_invoke 和 META_UNSAFE 工具仍獨佔執行。

消費方: 由逐輪工具執行調度器讀取。
格式: 1 / true / yes / on 禁用（默認未設置）。
修改從下一輪開始生效。
設置歸屬: 設置 → 偏好（schema 鍵）

`MAX_PARALLEL_TOOL_CALLS`

MAX_PARALLEL_TOOL_CALLS 設置一輪內最多可同時運行多少個安全的只讀工具。

默認值: 默認值為 16。
格式: 格式為 1 到 32 的十進制整數。
非法值回退為 16，並只輸出一次結構化啟動告警。用戶 Preference override 優先於此值。
修改從下一輪開始生效。關閉工具併發時忽略此上限。
設置歸屬: 設置 → 偏好（schema 鍵）

`MINARA_SUBAGENT_FOREGROUND_MAX_CONCURRENT`

MINARA_SUBAGENT_FOREGROUND_MAX_CONCURRENT 控制前臺子智能體併發，不佔用普通工具併發池。

默認值: 默認 8。
格式: 格式為 1 到 16 的整數。
超出的任務進入獨立 FIFO 隊列；用戶設置優先，下一輪生效。
設置歸屬: 設置 → 偏好（schema 鍵）

`MINARA_SUBAGENT_BACKGROUND_MAX_CONCURRENT`

MINARA_SUBAGENT_BACKGROUND_MAX_CONCURRENT 控制後臺子智能體併發，並使用與前臺獨立的隊列。

默認值: 默認 8。
格式: 格式為 1 到 16 的整數。
超出的任務進入獨立 FIFO 隊列；用戶設置優先，下一輪生效。
設置歸屬: 設置 → 偏好（schema 鍵）

`MINARA_SUBAGENT_TIMEOUT_SECONDS`

MINARA_SUBAGENT_TIMEOUT_SECONDS 設置每個子智能體實際開始後的默認運行時限。

默認值: 默認 600 秒。
格式: 格式為 30 到 3600 的整數，排隊時間不計入。
單次調用可用 subagent.timeout_s 覆蓋；用戶設置優先。
設置歸屬: 設置 → 偏好（schema 鍵）

影子模式（A/B 觀察記錄器）

輕量記錄器，在被插樁的決策點把（當前行為、擬議行為）變體對寫入 shadow_runs SQLite 表以供離線分析。無 LLM 雙跑。旨在用真實流量驗證 Sprint 2+ 優化（memory snapshot 分桶、緩存命中率、角色提示注入）。

`SHADOW_MODE`

記錄器模式。 off — 不記錄。零開銷。 sampled — 按 SHADOW_SAMPLE_RATE 隨機採樣。默認。 on — 記錄每一次調用。僅用於短暫的審計窗口。

格式: off / sampled / on。
設置歸屬: 非用戶設置項

`SHADOW_SAMPLE_RATE`

當 SHADOW_MODE=sampled 時記錄的合格調用比例。默認 0.1（10%）。範圍 [0, 1]。

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

`SHADOW_RETENTION_DAYS`

保留多少天的 shadow_runs 行。每次啟動運行一次性修剪，丟棄早於此閾值的行，防止長期運行的部署上表無限增長。默認 30。高流量 / 磁盤受限環境調低。

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

Memory Snapshot 分桶

MemoryStore.loadSnapshot() 在會話開始時運行一次，並注入一個 FIFO 50 行的記憶列表到系統 prompt。在 Sprint 2 之前，一批近期的 observation 行可能擠掉長期存活的 preference / strategy 行。Sprint 2 用按類別配額替代 FIFO；高優先級桶中未用的槽溢出到 observation，因此在稀疏 profile 上總數仍保持 50。發出順序：preference → strategy → trade_note → observation。由 src/memory/memory-store.ts 經 app.ts 接線消費。調優指引：為 profile 繁重的用戶提高 preference / strategy；為嘈雜的短期分析 workflow 提高 observation。

`MEMORY_SNAPSHOT_PREF_LIMIT`

用戶偏好槽位。核心 profile 數據。

設置歸屬: 非用戶設置項

`MEMORY_SNAPSHOT_STRAT_LIMIT`

用戶的長期策略筆記。

設置歸屬: 非用戶設置項

`MEMORY_SNAPSHOT_TRADE_LIMIT`

交易投訴 / 復盤筆記。

設置歸屬: 非用戶設置項

`MEMORY_SNAPSHOT_OBS_LIMIT`

滾動觀察配額，外加未用的偏好 / 策略 / 交易槽位的滾存池。

設置歸屬: 非用戶設置項

Memory Snapshot 軟刷新 (P1-2)

會話開始時加載的 snapshot 通常在整個會話保持凍結（保留 prompt 前綴緩存）。長會話會丟失信息新鮮度——用戶在第 10 輪聲明的偏好在下一次會話之前永遠到不了 prompt。軟刷新在自上次重建以來兩個閾值都滿足（寫入次數 AND 輪數）時於會話中重建 snapshot。設 MEMORY_REFRESH_TURNS=0 恢復到舊的會話凍結行為。

`MEMORY_REFRESH_WRITES`

自上次快照重建以來的 memory_write 調用數。默認 3。

設置歸屬: 非用戶設置項

`MEMORY_REFRESH_TURNS`

自上次快照重建以來的輪次數。默認 10。設為 0 可完全禁用軟刷新（快照保持會話凍結）。此項與 MEMORY_REFRESH_WRITES 都必須達到才會重建 —— 防止單次大寫入造成緩存抖動。

設置歸屬: 非用戶設置項

`MEMORY_WRITE_MAX_LEN`

agent 經 memory_write 工具保存記憶（observation / preference / trade_note / strategy 類別）時保留的最大字符數。更長的內容在存儲前會被裁剪到此長度，這樣單條超大或被投毒的條目無法灌滿系統提示或 FTS 索引。更嚴格的個性化事實路徑保留自己更短的限制，不受影響。由 src/tools/memory-tool.ts 消費；也作為 Settings 偏好 memory.writeMaxLen 呈現。未設置時默認 2000。可接受範圍 200–8000（正整數，字符）。

設置歸屬: 設置 → 偏好（schema 鍵）

記憶整合 (FactLayer, Phase 1)

`MEMORY_CONSOLIDATION_ENABLED`

對後臺重建器學到的、從聊天中提取的個性化事實做矛盾消解。

ON by default: 重建器每次記憶重建多運行一次
後臺 LLM 調用，逐個事實判斷它是重複 / 精煉 /
取代了某個現有事實，這樣記憶快照就不再累積
陳舊或矛盾的行。設為 0 / false / no / off 可
退出 —— 那樣每個提取出的事實都會作為新行追加（
長期以來的行為）。被取代的事實做軟刪除（可恢復），
每個決定都記入 memory_consolidation_events 審計
表。由 memory/consolidation-config.ts +
memory/fact-consolidation.ts 消費。也驅動近重複仲裁
針對 agent 記錄的事實（memory/general-fact-service.ts）。
格式: 未設置 / 1 / true / yes / on 啟用；只有顯式的
0 / false / no / off 禁用。作為 Settings →
Experimental "Tidy duplicate and outdated memories" 開關呈現。
設置歸屬: 設置 → 偏好（schema 鍵）

`MEMORY_CONSOLIDATION_GUIDANCE`

可選的自由文本引導，用於說明 consolidation 如何合併或退役事實（例如 "prefer my most recent statement"、"keep separate notes per asset"）。作為非權威偏好注入到 resolver 提示中：它絕不覆蓋硬性安全規則（用戶設置的硬約束絕不被丟棄，除非有更新的用戶顯式陳述；用戶陳述的事實始終高於 assistant 推斷的事實）。上限 500 字符。當 MEMORY_CONSOLIDATION_ENABLED 關閉時無效。

格式: 純文本，默認空（使用內置策略）。
設置歸屬: 設置 → 偏好（schema 鍵）

`FACT_LIFECYCLE_ENABLED`

選擇加入事實陳舊化生命週期。關閉時（默認）每個已存儲事實永遠保持滿權重（長期以來的行為）。開啟時，後臺記憶重建運行一次確定性的、無 LLM 的掃描，按類型給事實計齡：市場觀點（observation.market_view）約 14 天后降為 warm，約 45 天后掉出注入的 profile（cold），交易筆記約 90 / 約 270 天，而用戶設置的硬約束（constraint.hard）和目標永不計齡。降級可逆 —— 什麼都不刪除，cold 事實仍可搜索，一次新的提及（一次 consolidation 更新）會把事實提升回 hot。由 memory/consolidation-config.ts + memory/fact-lifecycle.ts 經個性化重建器消費。格式：1 / true / yes / on 啟用；未設置 / 其他任何值都保持關閉。作為 Settings → Experimental "Let old memories fade" 開關呈現。

設置歸屬: 設置 → 偏好（schema 鍵）

`FACT_LIFECYCLE_AGE_MULTIPLIER`

對每個事實生命週期年齡閾值的全局縮放。1（默認）使用內置的按類型年齡；2 讓每個事實在降級前持續兩倍時長；0.5 減半。讓運維能移動整條衰減曲線，而無需為每種事實類型暴露一個旋鈕。鉗制到 [0.25, 10]；非正 / 無法解析的值回退到 1。當 FACT_LIFECYCLE_ENABLED 關閉時無效。由 memory/consolidation-config.ts 消費。格式：一個正數。

設置歸屬: 設置 → 偏好（schema 鍵）

側邊任務併發

側邊任務 session 數量不受限制，但模型 turn 共享一個有界的進程內調度器。主 session 的 turn 不經過此限制。

`MINARA_SIDE_TASK_MAX_CONCURRENT_TURNS`

Gateway 中可同時運行的側邊任務 agent turn 上限。超過上限的 turn 會進入公平隊列；僅打開或空閒的標籤不佔用名額。主 session 不受此限制。

消費方: 由 src/gateway/side-task-concurrency.ts 消費。
何時設置: 模型提供商反覆限制併發側邊任務時可降低此值。
未設置時: 未設置時默認允許 8 個併發側邊任務 turn。
格式: 格式：1 到 32 的整數；無效值回退到 8。修改後需重啟 Gateway。
設置歸屬: 非用戶設置項

知識預算（動態塊上限）

`KNOWLEDGE_BUDGET_TOKENS`

系統提示中三個動態知識塊（場景 playbook + 記憶上下文 + 角色提示）合併大小的數值上限（以 token 計）。當合並大小超過此值時，協商器從最低優先級開始裁剪：roleHints → memoryContext → scenarioPlaybook。

默認 15000 token（~60k 字符 ≈ 200k 上下文的 7.5%）—— 足夠
對大多數輪次的餘量。經此 env 顯式覆蓋。要禁用
整個協商器（讓塊以完整長度輸出），設置
DISABLE_KNOWLEDGE_BUDGET=1 —— 見上面的 kill-switch 塊。
格式: 非負整數。0 禁用。
設置歸屬: 非用戶設置項

`KNOWLEDGE_SOURCE_TAGS`

給每個動態知識塊前置一個 HTML 註釋來源標籤（、）。純粹用於人工 / 基於日誌的提示審計 —— LLM 把 HTML 註釋當作噪聲。默認關閉。

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

本頁目錄