回测反馈循环

定期任务，为已执行 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。
设置归属: 非用户设置项

本页目录