comate-cli 0.6.2__tar.gz → 0.7.0__tar.gz

{comate_cli-0.6.2 → comate_cli-0.7.0}/.gitignore

@@ -5,6 +5,8 @@ __pycache__/
 .agent
 .agents
 set_env.sh
+.vscode/
+codex/
 .worktrees/
 # C extensions
 *.so
@@ -227,3 +229,7 @@ __marimo__/
 .DS_Store
 .DS_Store.worktrees/
 .superpowers/
+.codex/
+
+# pnpm
+.pnpm-store/

comate_cli-0.7.0/AGENTS.md

@@ -0,0 +1,115 @@
+## global rule
+1. 涉及到 Prompt_toolkit 这个TUI框架, 你必须使用 context7 mcp里面的  query-docs和resolve-library-id 功能来查询相关文档, 以确保你对这个框架的理解是正确的. this is MUST
+2. 总是使用中文编写详细的git commit message
+
+## 12条黄金规则
+
+这些规则适用于本项目中的每一个任务，除非被明确覆盖。核心原则：非简单任务宁可谨慎，不要图快。简单任务可以灵活处理。
+
+1. 动手之前先动脑
+把你的假设说出来。不确定就问，别猜。遇到模糊需求时，列出多种可能的理解。如果有更简单的方案，要敢于提出来。搞不清楚的时候就停下来，把不清楚的点明确说出来。
+
+2. 简单至上
+写能解决问题的最少代码，不写投机性代码。不加需求以外的功能。一次性代码不搞抽象封装。自测标准：一个资深工程师看了会不会觉得过度设计？如果会，就简化。
+
+3. 精准修改，不多动
+只改必须改的地方。只清理自己弄乱的部分。不要顺手"优化"旁边的代码、注释或格式。没坏的东西不要重构。风格跟已有代码保持一致。
+
+4. 以目标驱动执行
+先定义成功标准，然后循环迭代直到验证通过。不要机械地按步骤走，而是盯着目标不断调整。有了清晰的成功标准，你才能自主地持续迭代。
+
+5. 模型只用于需要判断力的场景
+适合用 AI 做的事：分类、起草、总结、信息提取。不该用 AI 做的事：路由分发、重试逻辑、确定性转换。如果写代码就能搞定，就用代码搞定。
+
+6. 核实优先于推断（冰山法则）
+你在上下文中看到的信息只是冰山一角，不能代替真实验证。
+判断标准不是"我有没有说出猜测的话"，而是"我这个结论背后有没有本轮刚验证过的事实支撑"——只要要陈述文件/函数/配置内容或修改代码，却没有刚读过、刚确认过，就是在猜，必须先验证再继续。
+
+7. 遇到冲突要选边，不要和稀泥
+两种模式互相矛盾时，选一个（优先选更新的或经过更多验证的），说明理由，把另一个标记为待清理。不要把两种冲突的模式混在一起用。
+
+8. 先读再写
+写新代码之前，先读清楚现有的导出接口、直接调用方、公共工具函数。"看起来互不相关"这种判断很危险。如果不理解代码为什么这样写，先问。
+
+9.  测试要验证意图，不只是行为
+测试必须体现某个行为**为什么**重要，而不仅仅是**做了什么**。如果业务逻辑变了，测试却不会挂，那这个测试就是有问题的。
+
+10.  每完成一个重要步骤就做检查点
+总结一下：做了什么、验证了什么、还剩什么。不要在一个自己都说不清楚的状态上继续推进。如果失去了方向感，停下来，重新陈述当前状态。
+
+11.  跟着项目的既有约定走，哪怕你不认同
+在项目内部，一致性 > 个人偏好。如果你真觉得某个约定有害，把问题提出来讨论，但不要悄悄另搞一套。
+
+12. 有问题就大声说
+如果有东西被悄悄跳过了，不能说"已完成"。如果有测试被跳过了，不能说"测试全过"。默认立场是把不确定性暴露出来，而不是藏起来。
+
+
+## python coding rule
+1. 代码必须使用 logging 模块进行日志记录，禁止使用 print 语句
+2. 运行 python必须使用 uv run python 脚本名.py 的方式运行
+3. 安装pip包必须使用 uv add 包名 的方式安装
+
+## Context 重建铁律
+comate_agent_sdk 的上下文重建规则是高优先级架构约束。涉及 static header / session_state / conversation 三层分离、header_snapshot 的 first-snapshot-wins 语义、resume / fork / compact / clear_history 各自的不变量，以及最低测试护栏清单。
+任何改动涉及 chat_session.py、context/ir.py、context/compaction.py、agent/history.py、agent/init.py、agent/setup.py 时 MUST 先阅读完整规则。
+→ ./rules/context-rebuild.md
+
+## Token 账本语义铁律
+
+comate_agent_sdk 的 token 相关概念分属不同账本，后续改动 MUST 先阅读完整规则，禁止为了修某个阈值或展示问题把不同账本混算。
+→ ./rules/token-accounting.md
+
+## TUI 编程铁律
+不做 History TUI，历史只写 scrollback。layout 只允许底部交互带。颜色策略以 shell 背景为准。包含 Team 事件显示铁律和 Pre-flight TUI 铁律。
+涉及 prompt_toolkit layout、team 事件渲染、独立 Application 弹窗时 MUST 先阅读完整规则。
+→ ./rules/tui.md
+
+## 代码放置规则
+
+当需要为某个模块添加新功能时，先判断：这个功能是该模块的 **核心职责** 还是 **业务扩展**？
+
+- **核心职责**：直接操作该模块自身管理的数据结构 → 可以加方法
+- **业务扩展**：借用该模块的 API 完成上层业务目标 → 在调用方实现，禁止侵入
+
+判断标准：如果删掉这个方法，该模块的核心抽象（数据结构 + 主流程）是否仍然完整？
+如果仍然完整，说明这个方法不属于这里。
+
+实践要求：
+1. 新增方法前，说明它属于核心职责还是业务扩展
+2. 如果是业务扩展，必须放在调用方或独立 service 中，通过公共 API 操作
+3. 单个模块超过 500 行时，主动审视是否有职责泄漏
+
+## Prompt 工程规则
+
+涉及 SDK 内置 prompt / 提示词时，后续 agent MUST 默认遵循以下约定，禁止重新回到“局部硬编码 + 局部替换”的分散实现。
+
+- SDK 自带 prompt 资源 MUST 放在 `comate_agent_sdk/prompts/` 下，按领域分目录，例如 `agent/`、`subagent/`。
+- 新增 prompt 时，优先判断它是 **SDK 静态资源** 还是 **调用方临时拼接文本**：
+  - SDK 静态资源：放入 `comate_agent_sdk/prompts/`，通过统一 loader 读取。
+  - 调用方临时拼接文本：保留在调用方，禁止为了“统一”硬塞进不相关模块。
+- MUST 使用两阶段接口：
+  - `load_prompt()` 只负责读取包内 markdown 资源。
+  - `render_prompt()` 只负责变量渲染。
+- 新 prompt 的变量语法 MUST 统一使用 `{{VAR_NAME}}`，不要新增 `{var}`、`%s`、手写 `replace()` 等新风格。
+
+## System Tool 描述工程规则
+
+涉及 SDK 内置 system tool 的 schema description / system prompt usage_rules / 默认上限值时，
+后续 agent MUST 默认遵循以下约定。
+
+→ ./rules/system-tool-prompt-conventions.md
+
+## Tool Envelope 与 Typed Schema 铁律
+
+comate_agent_sdk 内置 system tool 的"信封 (`ok/err` 6-key envelope) + typed OutputSchema + `ToolMessage.raw_envelope` 三轨分离"是 typed `ToolResultEvent.output`、SDK 投影、resume 持久化、reminder 引擎共同依赖的事实契约。envelope 一旦被静默改形 / 截断 / 污染框架字段，会让 typed 事件、投影、reminder、jsonl resume **同时静默失效**。
+
+涉及以下任一项 MUST 先阅读完整规则，禁止仅"局部 patch"：
+
+- `comate_agent_sdk/system_tools/tool_result.py`、`tool_schemas/`（含 `_registry.py` / `_projection.py` / `_base.py` / 各 `<tool>.py`）、`system_tools/tools|task|team/` 下 system tool 的返回结构。
+- `agent/tool_exec.py` 中 `_build_tool_result_message()` / `_extract_tool_envelope()`、`llm/messages.py` 中 `ToolMessage` 的 `content` / `raw_envelope` / `execution_meta` 字段、`mcp/manager.py` 中 `McpToolResult`。
+- `agent/runner_engine/execution/tool_execution.py` 的 `_resolve_tool_output()`、`runner_engine/projection/tool_result_projection.py`、`agent/events.py` 中 `ToolResultEvent.output`、`context/reminder_engine.py`、`subagent/team_session.py`、`chat_session.py` resume 路径。
+- size guard / truncation / artifact spill 与 envelope 关系的任何 plan。
+
+核心铁律一句话：**system tool 必须 `ok()/err()` envelope；envelope 形状不可破坏性变更；envelope 是 typed schema 唯一原料；envelope 只装业务字段，框架元数据走 `execution_meta`；envelope 严禁 slim / 入 prompt / 被 monkey-patch 注册；MCP 用 `McpToolResult.raw_result`、不混 `raw_envelope`；用户 `@tool` 永远是 `CustomToolOutput`。**
+
+→ ./rules/tool-envelope.md

comate_cli-0.7.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## Unreleased
+
+### Fixed
+
+- Windows 上 Ctrl+C 退出时 `ERROR:mcp.client.stdio:Failed to parse JSONRPC message from server`
+  和 traceback 漏到终端的问题。修复包含两部分：`app.py` finally 顺序调整，
+  以及 SDK stdio MCP 关闭路径切换到主动信号升级链。
+- Windows 上 Ctrl+C 退出时 `Exception ignored in: <BaseSubprocessTransport.__del__>`
+  和 `ValueError: I/O operation on closed pipe` 漏到终端的问题。现在由
+  `_ShutdownNoiseGuard` catch-all 接管 `sys.unraisablehook` 并写入 agent log。
+
+### Added
+
+- 新增 `/clear` slash command：清空当前 leader session 的 conversation，
+  保留 session_id、team membership、inbox 与 TaskStore。成功后会清屏、
+  重打 logo、重置 TUI transcript view，并刷新 status bar；busy 或
+  compacting 状态会拒绝执行。
+- `_ShutdownNoiseGuard` 扩展为四合一接管器：SIGINT、`sys.unraisablehook`、
+  `sys.excepthook`、`warnings.showwarning`。捕获到的噪音统一路由到独立的
+  `comate.noise` logger（`propagate=False`），写入 `~/.comate/logs/agent.log`。
+- 新增 `COMATE_DEBUG_NOISE=1` 环境变量逃生口，开发排障时可关闭噪音接管器，
+  查看旧版本的原始 stderr 输出。
+
+### Changed
+
+- TUI 分支退出时先执行 `_graceful_shutdown(...)`，再关闭 `logging_session`，
+  让现有 logging 屏蔽机制覆盖 MCP teardown 全程。
+
+## 0.7.0a1 - 2026-05-19 (alpha)
+
+> 这是一个 **alpha 预发布版本**，用于内部 / 早期测试。
+> `pip install comate-cli` 默认不会安装到本版本，需要显式 `pip install comate-cli==0.7.0a1` 或 `pip install --pre comate-cli`。
+
+### Breaking Changes
+
+- 依赖 `comate-agent-sdk>=0.8.0a1`，与旧 SDK 不兼容。
+- 旧版本生成的 resume jsonl / context 快照不保证可以正常回放，**建议从空 session 重新开始**。
+
+### 累积变更
+
+自 0.6.x 起累积大量 TUI 与会话能力改进，涵盖：
+
+- Resume picker 重做：搜索、跨 cwd 切换、预览模式、视觉抛光
+- Auto compact 期间显式提示 `Compacting context`
+- Team / subagent 事件透出与渲染统一
+- 与 SDK 0.8.0a2 配套的 tool envelope / token 账本展示
+
+详细变更请参考 git log。

{comate_cli-0.6.2 → comate_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comate-cli
-Version: 0.6.2
+Version: 0.7.0
 Summary: Comate terminal CLI built on comate-agent-sdk
 Project-URL: Homepage, https://github.com/AndyLee1024/agent-sdk
 Project-URL: Repository, https://github.com/AndyLee1024/agent-sdk
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
 Requires-Dist: charset-normalizer==3.4.7
-Requires-Dist: comate-agent-sdk<1.0.0,>=0.0.2
+Requires-Dist: comate-agent-sdk<0.9.0,>=0.8.0a1
 Requires-Dist: concurrent-log-handler>=0.9.25
 Requires-Dist: curl-cffi==0.13.0
 Requires-Dist: packaging>=21.0
@@ -41,3 +41,28 @@ Or install globally:
 uv tool install comate-cli
 comate
 ```
+
+## 排错 / Troubleshooting
+
+### 看不到错误信息但行为异常
+
+comate 在生产模式下会把若干无害但吵闹的 shutdown 噪音写入
+`~/.comate/logs/agent.log`，而不是显示在终端里。这包括 Windows asyncio
+shutdown 的 `ResourceWarning`、MCP 服务器违规向 stdout 写日志导致的 JSONRPC
+解析失败，以及解释器退出阶段的 unraisable 异常。
+
+如果你怀疑隐藏了真实错误，可以按下面顺序排查：
+
+```bash
+# 1. 看 noise 通道的最近 50 条
+grep -E "\[unraisable\]|\[excepthook\]|\[warning\]" ~/.comate/logs/agent.log | tail -50
+
+# 2. 看完整 agent.log 末尾
+tail -200 ~/.comate/logs/agent.log
+
+# 3. 临时关掉噪音接管器,看原始输出(开发场景)
+COMATE_DEBUG_NOISE=1 comate
+```
+
+`COMATE_DEBUG_NOISE=1` 设置后，`_ShutdownNoiseGuard` 会跳过 install，
+错误会像旧版本一样直接打印到 stderr。

comate_cli-0.7.0/README.md

@@ -0,0 +1,41 @@
+# comate-cli
+
+Comate terminal CLI package.
+
+## Usage
+
+```bash
+uvx comate-cli
+```
+
+Or install globally:
+
+```bash
+uv tool install comate-cli
+comate
+```
+
+## 排错 / Troubleshooting
+
+### 看不到错误信息但行为异常
+
+comate 在生产模式下会把若干无害但吵闹的 shutdown 噪音写入
+`~/.comate/logs/agent.log`，而不是显示在终端里。这包括 Windows asyncio
+shutdown 的 `ResourceWarning`、MCP 服务器违规向 stdout 写日志导致的 JSONRPC
+解析失败，以及解释器退出阶段的 unraisable 异常。
+
+如果你怀疑隐藏了真实错误，可以按下面顺序排查：
+
+```bash
+# 1. 看 noise 通道的最近 50 条
+grep -E "\[unraisable\]|\[excepthook\]|\[warning\]" ~/.comate/logs/agent.log | tail -50
+
+# 2. 看完整 agent.log 末尾
+tail -200 ~/.comate/logs/agent.log
+
+# 3. 临时关掉噪音接管器,看原始输出(开发场景)
+COMATE_DEBUG_NOISE=1 comate
+```
+
+`COMATE_DEBUG_NOISE=1` 设置后，`_ShutdownNoiseGuard` 会跳过 install，
+错误会像旧版本一样直接打印到 stderr。

{comate_cli-0.6.2 → comate_cli-0.7.0}/comate_cli/main.py

@@ -3,9 +3,11 @@ from __future__ import annotations
 import atexit
 import asyncio
 import logging
+import os
 import signal
 import subprocess
 import sys
+import warnings
 try:
     import termios
 except ImportError:
@@ -68,10 +70,21 @@ class _ShutdownNoiseGuard:
 
     def __init__(self) -> None:
         self._shutdown_armed = False
+        self._installed = False
         self._orig_unraisablehook = sys.unraisablehook
+        self._orig_excepthook = sys.excepthook
+        self._orig_showwarning = warnings.showwarning
+        self._noise_logger = self._build_noise_logger()
 
     def install(self) -> None:
+        if self._installed:
+            return
+        if os.environ.get("COMATE_DEBUG_NOISE", "").strip().lower() in ("1", "true", "yes"):
+            return
         sys.unraisablehook = self._unraisablehook
+        sys.excepthook = self._excepthook
+        warnings.showwarning = self._showwarning
+        self._installed = True
 
     def begin_shutdown(self) -> None:
         if self._shutdown_armed:
@@ -88,13 +101,94 @@ class _ShutdownNoiseGuard:
         except Exception as exc:
             logger.debug(f"Failed to switch SIGINT to SIG_IGN during shutdown: {exc}")
 
+    def _route(
+        self,
+        channel: str,
+        *,
+        exc: BaseException | None = None,
+        msg: str = "",
+        **extra: object,
+    ) -> None:
+        try:
+            if exc is not None:
+                self._noise_logger.warning(
+                    "[%s] %s: %s",
+                    channel,
+                    type(exc).__name__,
+                    exc,
+                    exc_info=(type(exc), exc, exc.__traceback__),
+                    extra={"noise_channel": channel, **extra},
+                )
+            else:
+                self._noise_logger.warning(
+                    "[%s] %s",
+                    channel,
+                    msg,
+                    extra={"noise_channel": channel, **extra},
+                )
+        except Exception:
+            pass
+
     def _unraisablehook(self, unraisable: object) -> None:
         exc_value = getattr(unraisable, "exc_value", None)
         if self._shutdown_armed and isinstance(exc_value, KeyboardInterrupt):
-            logger.debug("Suppressed unraisable KeyboardInterrupt during shutdown")
             return
+        obj = getattr(unraisable, "object", None)
+        self._route("unraisable", exc=exc_value, object_repr=repr(obj))
+
+    def _excepthook(
+        self,
+        exc_type: type[BaseException],
+        exc_value: BaseException,
+        exc_tb: object,
+    ) -> None:
+        self._route("excepthook", exc=exc_value)
+
+    def _showwarning(
+        self,
+        message: Warning | str,
+        category: type[Warning],
+        filename: str,
+        lineno: int,
+        file: object | None = None,
+        line: str | None = None,
+    ) -> None:
+        self._route(
+            "warning",
+            msg=str(message),
+            category=category.__name__,
+            warning_filename=str(filename),
+            warning_lineno=lineno,
+        )
 
-        self._orig_unraisablehook(unraisable)
+    def _build_noise_logger(self) -> logging.Logger:
+        log = logging.getLogger("comate.noise")
+        log.setLevel(logging.WARNING)
+        log.propagate = False
+        if log.handlers:
+            return log
+
+        try:
+            from concurrent_log_handler import ConcurrentRotatingFileHandler
+
+            log_dir = os.path.join(os.path.expanduser("~"), ".comate", "logs")
+            os.makedirs(log_dir, exist_ok=True)
+            handler = ConcurrentRotatingFileHandler(
+                os.path.join(log_dir, "agent.log"),
+                maxBytes=10 * 1024 * 1024,
+                backupCount=3,
+                encoding="utf-8",
+            )
+            handler.setFormatter(
+                logging.Formatter(
+                    "%(asctime)s %(levelname)s %(name)s [%(noise_channel)s]: %(message)s"
+                )
+            )
+            log.addHandler(handler)
+        except Exception:
+            log.addHandler(logging.NullHandler())
+
+        return log
 
 
 def _usage_text() -> str:
@@ -153,6 +247,10 @@ def _parse_args(argv: list[str]) -> tuple[bool, str | None, bool, str | None]:
 def main(argv: list[str] | None = None) -> None:
     run_argv = list(argv) if argv is not None else sys.argv[1:]
 
+    if run_argv in (["--help"], ["-h"]):
+        sys.stdout.write(f"{_usage_text()}\n")
+        return
+
     if run_argv and run_argv[0] == "mcp":
         from comate_cli.mcp_cli import McpCliError, run_mcp_command
 

{comate_cli-0.6.2 → comate_cli-0.7.0}/comate_cli/terminal_agent/animations.py

@@ -9,7 +9,7 @@ from enum import Enum
 from rich.console import RenderableType
 from rich.text import Text
 
-from comate_agent_sdk.agent.events import StopEvent, TextEvent, ToolCallEvent, ToolResultEvent, UserQuestionEvent
+from comate_agent_sdk.agent.events import StopEvent, ToolCallEvent, ToolResultEvent, UserQuestionEvent
 
 from comate_cli.terminal_agent.figures import (
     BREATH_DOT_GLYPHS as _FIGURES_BREATH_DOT_GLYPHS,
@@ -238,6 +238,25 @@ BREATH_DOT_COLORS: tuple[str, ...] = (
 )
 BREATH_DOT_GLYPHS: tuple[str, ...] = _FIGURES_BREATH_DOT_GLYPHS
 
+LOADING_SPINNER_FRAMES: tuple[str, ...] = (
+    "⠋",
+    "⠙",
+    "⠹",
+    "⠸",
+    "⠼",
+    "⠴",
+    "⠦",
+    "⠧",
+    "⠇",
+    "⠏",
+)
+
+HIDDEN_THINKING_BADGES: tuple[str, ...] = (
+    "ultra thinking",
+    "deep thinking",
+    "extended thinking"
+)
+
 
 def breathing_dot_color(frame: int) -> str:
     """Return the breathing dot color for a given animation frame."""
@@ -252,6 +271,11 @@ def breathing_dot_glyph(now_monotonic: float | None = None) -> str:
     return BREATH_DOT_GLYPHS[phase]
 
 
+def loading_spinner_glyph(frame: int) -> str:
+    """Return the compact spinner glyph for the main loading line."""
+    return LOADING_SPINNER_FRAMES[frame % len(LOADING_SPINNER_FRAMES)]
+
+
 def _lerp_rgb(
     start_rgb: tuple[int, int, int],
     end_rgb: tuple[int, int, int],
@@ -385,11 +409,9 @@ class SubmissionAnimator:
             return Text("")
 
         phrase = self._status_hint if self._status_hint else (self._shuffled[self._phrase_idx] + ELLIPSIS)
-        dot_color = breathing_dot_color(self._frame)
-        now_monotonic = time.monotonic()
         dot = Text(
-            f"{breathing_dot_glyph(now_monotonic)} ",
-            style=f"bold {dot_color}",
+            f"{loading_spinner_glyph(self._frame)} ",
+            style="bold #9CA3AF",
         )
         sweep = _cyan_sweep_text(phrase, frame=self._frame)
         return Text.assemble(dot, sweep)

{comate_cli-0.6.2 → comate_cli-0.7.0}/comate_cli/terminal_agent/app.py

@@ -186,14 +186,23 @@ async def add(a: int, b: int) -> int:
 
 
 def _build_agent(*, project_root: Path | None = None) -> Agent:
+    from comate_agent_sdk.agent.compaction import CompactionConfig
+    from comate_cli.terminal_agent.config import store
+
     resolved_project_root = project_root or _resolve_cli_project_root()
+    snapshot = store.load()
 
     return Agent(
         config=AgentConfig(
             role="software_engineering",
             cwd=resolved_project_root,
             env_options=EnvOptions(system_env=True, git_env=True),
-            use_streaming_task=True,  # 启用流式 Task（实时显示嵌套工具调用）
+            use_streaming_task=True,
+            memory_background_enabled=snapshot.memory_background_enabled,
+            memory_dreaming_enabled=snapshot.memory_dreaming_enabled,
+            compaction=CompactionConfig(
+                threshold_ratio=snapshot.compaction_threshold_ratio,
+            ),
         )
     )
 
@@ -415,11 +424,13 @@ async def run(
                 exc_info=True,
             )
     finally:
-        logging_session.close()
-        if active_session is session:
-            await _graceful_shutdown(active_session)
-        else:
-            await _graceful_shutdown(session, active_session)
+        try:
+            if active_session is session:
+                await _graceful_shutdown(active_session)
+            else:
+                await _graceful_shutdown(session, active_session)
+        finally:
+            logging_session.close()
 
     if usage_line:
         console.print(f"[dim]{usage_line}[/]")

comate_cli-0.7.0/comate_cli/terminal_agent/config/model.py

@@ -0,0 +1,52 @@
+"""ConfigSnapshot：/config UI、store、startup 三处共享的偏好快照。
+
+Revision 2: 5 项偏好（display_thinking, model_level, compaction, memory_background, memory_dreaming）。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Literal
+
+ModelLevelPreset = Literal["LOW", "MID", "HIGH"]
+ThresholdPreset = Literal["conservative", "balanced", "aggressive"]
+
+COMPACT_PRESETS: dict[str, float] = {
+    "conservative": 0.65,
+    "balanced": 0.80,
+    "aggressive": 0.92,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigSnapshot:
+    """5 项 CLI 偏好的不可变快照。"""
+
+    display_thinking: bool = False
+    model_level: ModelLevelPreset = "MID"
+    compaction_threshold_ratio: float = 0.80
+    compaction_threshold_preset: ThresholdPreset = "balanced"
+    memory_background_enabled: bool = True
+    memory_dreaming_enabled: bool = True
+
+    @classmethod
+    def default(cls) -> "ConfigSnapshot":
+        return cls()
+
+    def with_display_thinking(self, enabled: bool) -> "ConfigSnapshot":
+        return replace(self, display_thinking=enabled)
+
+    def with_model_level(self, level: ModelLevelPreset) -> "ConfigSnapshot":
+        return replace(self, model_level=level)
+
+    def with_threshold_preset(self, preset: ThresholdPreset) -> "ConfigSnapshot":
+        return replace(
+            self,
+            compaction_threshold_preset=preset,
+            compaction_threshold_ratio=COMPACT_PRESETS[preset],
+        )
+
+    def with_memory_background(self, enabled: bool) -> "ConfigSnapshot":
+        return replace(self, memory_background_enabled=enabled)
+
+    def with_memory_dreaming(self, enabled: bool) -> "ConfigSnapshot":
+        return replace(self, memory_dreaming_enabled=enabled)