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。
设置归属: 非用户设置项

本页目录