# Changelog

## Unreleased

### Performance

- 启动重排：交互模式在参数解析后立即打印 logo，preflight、Agent 构造与 TUI 准备阶段
  之后执行；重活段用 transient spinner 桥接，避免首屏长时间空白。
- 新增 CLI 首屏 import 体重护栏，锁住 `app` / `update_check` / `preflight` 导入链，
  防止 `pydantic`、`mcp`、`openai`、`anthropic`、`tiktoken`、`prompt_toolkit`
  等重依赖回到 logo 前同步路径。
- 新增 `tools/startup_bench.py` 启动基准脚本，基于真实 TUI 与
  `COMATE_STARTUP_PROFILE=1` 输出启动阶段表，POSIX 下通过 pty 自动采样。
- 新增 `docs/startup-performance.md`，记录字节码预编译、Windows Defender 排除建议、
  startup_profile 排障方法，以及当前基准样本。

### Changed

- CLI 退出尾声改为结果优先的硬有界生命周期：TUI Token/resume 与 print mode
  文本/JSON 先 flush，再启动固定 10 秒 daemon watchdog；Windows/POSIX 均忽略
  尾声 SIGINT，session 使用共享剩余预算内的 8 秒软等待，硬期限触发以 code 1
  暴露异常清理。
- Session Report 最终 `ended=true` snapshot 继续先持久化到 spool；最终上传 task
  在同一退出 deadline 内获得有界机会，不再被通用 backend task 首轮取消误杀，
  ACK 删除未变化 spool，离线/超时/取消仍交给后续 drain。
- `BackendServices.identity_resolver` 改为一次接收 Agent 构造后的 LOW/MID/HIGH
  provider snapshot，并返回 token tuple；runtime 统一去空、去重和排序。旧的请求期
  零参数 resolver / 单个 `identity_token` 契约不再支持。
- SDK `ChatSession` 新增 `flush_usage_ledger()`，`total_usage.json` 写入统一收敛到
  history 游标 flush；标题 side query 与普通 turn 并发落账时不会重复累计。
- **Nico Dark 设计语言**: 全部 UI 表面收敛到统一设计 token（品牌青 #67D5FF + 5 级冷灰阶 + 三语义色），
  新增 `terminal_agent/theme.py` 唯一颜色事实源与防回潮扫描测试。
  工具行改为"状态色只上字形"三段式；markdown 去强制纯白、代码块主题 nord。
  loading 流光峰值精调为品牌青；呼吸点改为青色呼吸。
  六处交互组件统一解剖，菜单光标统一 ❯。
  preflight 删除自画深色背景回归 shell 背景；resume picker 换 token。
  状态栏粉彩分段色与 logo 保持原样。
- **文本档提亮对齐 Claude Code 亮度**: 四级文本 token 整体提亮，解决部分终端下正文发暗、
  对比不足的问题——`text.bright #E9EEF3→#FFFFFF`、`text #C8D0D9→#F1F4F8`、
  `text.muted #97A1AE→#A2A9B2`、`text.faint #6C7683→#7C8590`。
  青色品牌 accent 与语义色不变，最弱档不采用 CC 更暗的 `#505050`。
- **user 回显正文回归终端默认色**: 不再把用户消息重新染成灰（`text.muted`），
  与输入框观感一致、消除"打字时亮、回显后变灰"的突兀落差；`>` 前缀仍留 faint 弱标记、
  slash 命令仍单独高亮。
- **进行中任务实心方块对齐 Claude Code claude 橙**: tasklist 里进行中 `◼` 由品牌青改为
  `in_progress_marker #D77757`（CC claude 橙），TUI 底部带与 scrollback 两处方块统一；
  任务文字维持原样（TUI 亮白 / scrollback 青）。

### Fixed

- 启动重排回归：`Preparing interface…` spinner（rich Live 会临时把 `sys.stdout`
  换成非 tty 的 FileProxy）窗口内构造了 prompt_toolkit Application，AppSession
  把降级 `PlainTextOutput` 永久缓存，导致 input 区域无法加载、底部带被反复追加进
  scrollback、样式全部丢失。修复为 logo 后立即预热 session output（固化真实 tty
  的 `Vt100_Output`）+ TUI 构造移出 spinner 窗口；新增真实 pty 机制护栏与 e2e
  启动冒烟护栏（断言 bracketed-paste 就绪序列）。
- 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

- 后台 Bash（Phase 2）：`Bash(run_in_background=true)` 立即返回 job_id；
  jobs 面板/落痕/`/ps` 详情渲染 Bash 变体（字节数指标、exit code、命令与输出尾部）。
- `/ps` 强杀 bash 任务后按看护结算的权威终态展示（killed/completed/failed），
  未结算时保持 stopping 并可再次按 x，不再按任务类型猜测终态。
- 退出守卫：`/exit`、Ctrl+C 二连、Ctrl+D 退出时若存在 running background job，
  弹出底部带确认视图（默认焦点“杀掉并退出”，Esc/取消回会话；守卫期间再按
  Ctrl+C/Ctrl+D 直接确认杀退）。idle 保活 agent 不拦截、仅计数展示；
  print mode / RPC 模式不受影响。
- 发行版配置 services 后启用 CLI 会话 digest：每个用户轮原子写 checkpoint/spool，
  按 10 轮或 10 分钟幂等 upsert，并在后续启动串行 drain。首个有效助手轮会用 LOW
  model 生成 report 内部标题；标题不写 session metadata，也不改变 resume 列表的
  `first_prompt` 展示。`services=None` 或 `session_report_enabled=false` 时整条链路休眠。
- DistributionProfile 扩展面：新增 `startup_hooks` / `session_hooks` / `agent_hooks` / `services` 四个字段；overlay 发行版可注入 SDK runtime hooks 与后端服务配置（feedback/公告/评分）及运行时身份解析器 `identity_resolver`（上报主身份，`device_id` 降附属），`services=None` 时三功能整体不存在，官方入口行为零变化。
- 新增 `/feedback`（services 注入时）：确认后异步上传当前会话 transcript（gzip，50MB 上限）与 agent.log 尾部 5MB，支持一行可选描述。
- 新增公告机制（services 注入时）：启动展示上次拉取缓存中的未读公告（`theme.ANNOUNCEMENT_ACCENT` 主题 + OSC 8 链接），后台拉取只写缓存下次启动展示。
- 新增会话评分（services 注入时）：user prompt 提交达 50 轮后底部选择组件提示 Bad/Fine/Good/Dismiss，每 session 一次 + 每日冷静期，Bad 衔接 feedback 流程。
- 新增 `/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.9.0 - 2026-07-02

### Added

- 新增 `DistributionProfile` 白标扩展面，调用方可注入产品名、命令名、包名、
  system role、provider presets、logo renderer、更新源与安装参数。
- CLI 入口、preflight、logo、更新检查、resume hint、MCP 子命令帮助文案等运行时路径
  支持通过发行版 profile 接管用户可见身份。

### Changed

- `UpdateTarget` 改为由 `fetch_latest` 回调和 `install_args` 描述更新源。
  直接构造 `UpdateTarget` 的下游需要从旧字段迁移到新契约；这是对该内部扩展面的
  破坏性变更。
- 更新命令现在会透传 profile 提供的安装参数，支持发行版自定义安装源。

### Removed

- 公开仓库中的发行版专用示例、测试夹具和历史文档已中性化或移出仓库；构建产物目录
  `packages/comate_cli/dist-*/` 已加入忽略规则。

## 0.8.6 - 2026-06-24

### `/loop` 定时循环能力升级

本周期对 `/loop` 做了一次提示词驱动的重构，修复了一个影响中文用户的核心 bug，
并收紧了调度规则。

#### Fixed

- **中文「每隔N分钟」不再静默回退为 10 分钟**：之前 `/loop 每隔1分钟 检查构建状态`
  这类中文自然语言措辞，会因为未命中代码里的英文正则而静默回退为默认 10 分钟，
  调度完全不符合预期。现在间隔解析从"代码硬正则"改为提示词驱动，把规则和原始输入
  交给模型按用户意图（任意语言）自行解析。中文「每隔1分钟」「每两小时」、英文
  "every couple of hours" 都能被正确识别。
- **`/loop` 运行数次后神秘停止**：根因是 TUI 状态栏刷新抛异常时会"杀死" event pump，
  进而关闭 scheduled prompt scheduler。现在状态栏刷新失败被隔离为局部防护（带日志），
  不再波及 event pump 与 `/loop` 调度消费。

#### Changed

- **间隔→cron 转换规则收紧**：为避免 cron 在边界重置导致节奏不均匀，规则现在只允许
  能整除单位的间隔，其他值会自动向上取整并明确告知取整结果：
  - 分钟（能整除 60）：1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30（如 `7m → 10m`）
  - 小时（能整除 24）：1, 2, 3, 4, 6, 8, 12（如 `5h → 6h`；13~24h → `1d`）
  - 天：仅 `1d`（禁止多天，`Nd, N>1` 会在月末重置，无法表达"每 N 天"）
  - 显式禁止 `7m`、`5h`、`2d` 等会让节奏"漂移"的写法。
- **CronCreate 使用规则精简**：删除四条容易让模型误判触发窗口/续跑语义的规则段落，
  追加 recurring 与 one-shot 的可复用 cron 示例模板，减少模型凭空构造错误 cron。

### Added

- **空闲 Recap（会话摘要回顾）**：回到终端时自动生成"离开期间发生了什么"摘要并渲染到
  scrollback，带 label 标签与禁用提示，方便恢复上下文。
- **`/learn` slash 命令**：引导把刚解决的问题沉淀为可复用知识。
- **`/implement-plan` slash 命令**：一键进入计划执行模式。
- **内置 default custom commands 加载链**：开箱即用一组默认 custom slash 命令。
- **工具调用流式进度**：Loading 行实时展示工具参数解析进度（token 估算），告别"干等"。
- **LLM 重试动态面板**：主 agent LLM 重试状态可视化，底部面板动态展示重试进度，SDK
  原始重试噪声收敛到统一面板。
- **`Ctrl+J` 手动换行**：多行输入时显式插入换行。
- **`@path` 提示行统一**：抽出为单一事实源并在 staging 界面同步显示。
- **Logo 支持 2x 放大**；统一圆点 marker 为呼吸点动画；tool signature 路径自动相对化。

### Changed（体验优化）

- 退出汇总输出精简、token 字段标签重命名。
- 时长显示数字与单位间加空格（如 `12 s`）。
- scrollback diff 展示优化。
- 错误 tool result 截断/展开提示保持 dim 样式。

### Fixed（稳定性）

- **Windows 状态栏 git 命令卡住 TUI 事件泵**。
- **provider 异常击穿 prompt_toolkit 防护**：LLM provider 抛出未处理异常时不再击穿到 TUI 层。
- **LLM stream 清理的无界等待**。
- **启动更新检查改为真正异步 HTTP**：不再占用默认线程池导致退出卡死；移除 24h 限频机制。
- **memory prefetch 退出噪声**兜底屏蔽。

### Fixed（渲染与配置）

- scrollback diff 背景未铺满内容行、diff 背景在 tab 行上的宽度计算错误。
- 代码块末行背景填充保留，避免渲染断裂。
- Bash scrollback 命令摘要单行化，避免多行折叠错乱。
- marketplace 详情页更新反馈不正确。
- 移除 CLI 的上下文压缩阈值配置（改由 SDK 安全窗口自动管理）。

## 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。
